====================================================================== F2PY Frequently Asked Questions ====================================================================== .. contents:: General information =================== Q: How to get started? ---------------------- First, install__ F2PY. Then check that F2PY installation works properly (see below__). Try out a `simple example`__. Read `F2PY Users Guide and Reference Manual`__. It contains lots of complete examples. If you have any questions/problems when using F2PY, don't hesitate to turn to `F2PY users mailing list`__ or directly to me. __ index.html#installation __ #testing __ index.html#usage __ usersguide/index.html __ index.html#mailing-list Q: When to report bugs? ----------------------- * If F2PY scanning fails on Fortran sources that otherwise compile fine. * After checking that you have the latest version of F2PY from its CVS. It is possible that a bug has been fixed already. See also the log entries in the file `HISTORY.txt`_ (`HISTORY.txt in CVS`_). * After checking that your Python and Numerical Python installations work correctly. * After checking that your C and Fortran compilers work correctly. Q: How to report bugs? ---------------------- F2PY is part of NumPy. Report bugs on the NumPy issue tracker at __ https://github.com/numpy/numpy/issues Please, include information about your platform (operating system, version) and compilers/linkers, e.g. the output (both stdout/stderr) of :: python -c 'import numpy.f2py.diagnose;numpy.f2py.diagnose.run()' Feel free to add any other relevant information. However, avoid sending the output of F2PY generated ``.pyf`` files (unless they are manually modified) or any binary files like shared libraries or object codes. N.B. You may notice that other F2PY issues are tagged 'f2py'. Only the admins can add tags to issues, don't waste time trying to work out how to tag it yourself. While reporting bugs, you may find the following notes useful: * `How To Ask Questions The Smart Way`__ by E. S. Raymond and R. Moen. * `How to Report Bugs Effectively`__ by S. Tatham. __ http://www.catb.org/~esr/faqs/smart-questions.html __ http://www.chiark.greenend.org.uk/~sgtatham/bugs.html Installation ============ Q: How to use F2PY with different Python versions? -------------------------------------------------- Run the installation command using the corresponding Python executable. For example, :: python2.1 setup.py install installs the ``f2py`` script as ``f2py2.1``. See `Distutils User Documentation`__ for more information how to install Python modules to non-standard locations. __ http://www.python.org/sigs/distutils-sig/doc/inst/inst.html Q: Why F2PY is not working after upgrading? ------------------------------------------- If upgrading from F2PY version 2.3.321 or earlier then remove all f2py specific files from ``/path/to/python/bin`` directory before running installation command. Q: How to get/upgrade numpy and F2PY from git? --------------------------------------------------------------- The numpy code repository is hosted on GitHub at __ http://github.com/numpy/numpy You can check it out with :: git clone git://github.com/numpy/numpy.git numpy Installation information is at __ http://www.scipy.org/scipylib/download.html Information for developers is at __ http://www.scipy.org/scipylib/dev-zone.html Testing ======= Q: How to test if F2PY is installed correctly? ---------------------------------------------- Run :: f2py without arguments. If F2PY is installed correctly then it should print the usage information for f2py. Q: How to test if F2PY is working correctly? -------------------------------------------- For a quick test, try out an example problem from Usage__ section in `README.txt`_. __ index.html#usage For running F2PY unit tests, see `TESTING.txt`_. Compiler/Platform-specific issues ================================= Q: What are supported platforms and compilers? ---------------------------------------------- F2PY is developed on Linux system with a GCC compiler (versions 2.95.x, 3.x). Fortran 90 related hooks are tested against Intel Fortran Compiler. F2PY should work under any platform where Python and Numeric are installed and has supported Fortran compiler installed. To see a list of supported compilers, execute:: f2py -c --help-fcompiler Example output:: List of available Fortran compilers: --fcompiler=gnu GNU Fortran Compiler (3.3.4) --fcompiler=intel Intel Fortran Compiler for 32-bit apps (8.0) List of unavailable Fortran compilers: --fcompiler=absoft Absoft Corp Fortran Compiler --fcompiler=compaq Compaq Fortran Compiler --fcompiler=compaqv DIGITAL|Compaq Visual Fortran Compiler --fcompiler=hpux HP Fortran 90 Compiler --fcompiler=ibm IBM XL Fortran Compiler --fcompiler=intele Intel Fortran Compiler for Itanium apps --fcompiler=intelev Intel Visual Fortran Compiler for Itanium apps --fcompiler=intelv Intel Visual Fortran Compiler for 32-bit apps --fcompiler=lahey Lahey/Fujitsu Fortran 95 Compiler --fcompiler=mips MIPSpro Fortran Compiler --fcompiler=nag NAGWare Fortran 95 Compiler --fcompiler=pg Portland Group Fortran Compiler --fcompiler=sun Sun|Forte Fortran 95 Compiler --fcompiler=vast Pacific-Sierra Research Fortran 90 Compiler List of unimplemented Fortran compilers: --fcompiler=f Fortran Company/NAG F Compiler For compiler details, run 'config_fc --verbose' setup command. Q: How to use the F compiler in F2PY? ------------------------------------- Read `f2py2e/doc/using_F_compiler.txt`__. It describes why the F compiler cannot be used in a normal way (i.e. using ``-c`` switch) to build F2PY generated modules. It also gives a workaround to this problem. __ http://cens.ioc.ee/cgi-bin/viewcvs.cgi/python/f2py2e/doc/using_F_compiler.txt?rev=HEAD&content-type=text/vnd.viewcvs-markup Q: How to use F2PY under Windows? --------------------------------- F2PY can be used both within Cygwin__ and MinGW__ environments under Windows, F2PY can be used also in Windows native terminal. See the section `Setting up environment`__ for Cygwin and MinGW. __ http://cygwin.com/ __ http://www.mingw.org/ __ http://cens.ioc.ee/~pearu/numpy/BUILD_WIN32.html#setting-up-environment Install numpy_distutils and F2PY. Win32 installers of these packages are provided in `F2PY Download`__ section. __ http://cens.ioc.ee/projects/f2py2e/#download Use ``--compiler=`` and ``--fcompiler`` F2PY command line switches to to specify which C and Fortran compilers F2PY should use, respectively. Under MinGW environment, ``mingw32`` is default for a C compiler. Supported and Unsupported Features ================================== Q: Does F2PY support ``ENTRY`` statements? ------------------------------------------ Yes, starting at F2PY version higher than 2.39.235_1706. Q: Does F2PY support derived types in F90 code? ----------------------------------------------- Not yet. However I do have plans to implement support for F90 TYPE constructs in future. But note that the task in non-trivial and may require the next edition of F2PY for which I don't have resources to work with at the moment. Jeffrey Hagelberg from LLNL has made progress on adding support for derived types to f2py. He writes: At this point, I have a version of f2py that supports derived types for most simple cases. I have multidimensional arrays of derived types and allocatable arrays of derived types working. I'm just now starting to work on getting nested derived types to work. I also haven't tried putting complex number in derived types yet. Hopefully he can contribute his changes to f2py soon. Q: Does F2PY support pointer data in F90 code? ----------------------------------------------- No. I have never needed it and I haven't studied if there are any obstacles to add pointer data support to F2PY. Q: What if Fortran 90 code uses ``(kind=KIND(..))``? --------------------------------------------------------------- Currently, F2PY can handle only ``(kind=)`` declarations where ```` is a numeric integer (e.g. 1, 2, 4,...) but not a function call ``KIND(..)`` or any other expression. F2PY needs to know what would be the corresponding C type and a general solution for that would be too complicated to implement. However, F2PY provides a hook to overcome this difficulty, namely, users can define their own to maps. For example, if Fortran 90 code contains:: REAL(kind=KIND(0.0D0)) ... then create a file ``.f2py_f2cmap`` (into the working directory) containing a Python dictionary:: {'real':{'KIND(0.0D0)':'double'}} for instance. Or more generally, the file ``.f2py_f2cmap`` must contain a dictionary with items:: : {:} that defines mapping between Fortran type:: ([kind=]) and the corresponding ````. ```` can be one of the following:: char signed_char short int long_long float double long_double complex_float complex_double complex_long_double string For more information, see ``f2py2e/capi_maps.py``. Related software ================ Q: How F2PY distinguishes from Pyfort? -------------------------------------- F2PY and Pyfort have very similar aims and ideology of how they are targeted. Both projects started to evolve in the same year 1999 independently. When we discovered each other's projects, a discussion started to join the projects but that unfortunately failed for various reasons, e.g. both projects had evolved too far that merging the tools would have been impractical and giving up the efforts that the developers of both projects have made was unacceptable to both parties. And so, nowadays we have two tools for connecting Fortran with Python and this fact will hardly change in near future. To decide which one to choose is a matter of taste, I can only recommend to try out both to make up your choice. At the moment F2PY can handle more wrapping tasks than Pyfort, e.g. with F2PY one can wrap Fortran 77 common blocks, Fortran 90 module routines, Fortran 90 module data (including allocatable arrays), one can call Python from Fortran, etc etc. F2PY scans Fortran codes to create signature (.pyf) files. F2PY is free from most of the limitations listed in in `the corresponding section of Pyfort Reference Manual`__. __ http://pyfortran.sourceforge.net/pyfort/pyfort_reference.htm#pgfId-296925 There is a conceptual difference on how F2PY and Pyfort handle the issue of different data ordering in Fortran and C multi-dimensional arrays. Pyfort generated wrapper functions have optional arguments TRANSPOSE and MIRROR that can be used to control explicitly how the array arguments and their dimensions are passed to Fortran routine in order to deal with the C/Fortran data ordering issue. F2PY generated wrapper functions hide the whole issue from an end-user so that translation between Fortran and C/Python loops and array element access codes is one-to-one. How the F2PY generated wrappers deal with the issue is determined by a person who creates a signature file via using attributes like ``intent(c)``, ``intent(copy|overwrite)``, ``intent(inout|in,out|inplace)`` etc. For example, let's consider a typical usage of both F2PY and Pyfort when wrapping the following simple Fortran code: .. include:: simple.f :literal: The comment lines starting with ``cf2py`` are read by F2PY (so that we don't need to generate/handwrite an intermediate signature file in this simple case) while for a Fortran compiler they are just comment lines. And here is a Python version of the Fortran code: .. include:: pytest.py :literal: To generate a wrapper for subroutine ``foo`` using F2PY, execute:: $ f2py -m f2pytest simple.f -c that will generate an extension module ``f2pytest`` into the current directory. To generate a wrapper using Pyfort, create the following file .. include:: pyforttest.pyf :literal: and execute:: $ pyfort pyforttest In Pyfort GUI add ``simple.f`` to the list of Fortran sources and check that the signature file is in free format. And then copy ``pyforttest.so`` from the build directory to the current directory. Now, in Python .. include:: simple_session.dat :literal: Q: Can Pyfort .pyf files used with F2PY and vice versa? ------------------------------------------------------- After some simple modifications, yes. You should take into account the following differences in Pyfort and F2PY .pyf files. + F2PY signature file contains ``python module`` and ``interface`` blocks that are equivalent to Pyfort ``module`` block usage. + F2PY attribute ``intent(inplace)`` is equivalent to Pyfort ``intent(inout)``. F2PY ``intent(inout)`` is a strict (but safe) version of ``intent(inplace)``, any mismatch in arguments with expected type, size, or contiguouness will trigger an exception while ``intent(inplace)`` (dangerously) modifies arguments attributes in-place. Misc ==== Q: How to establish which Fortran compiler F2PY will use? --------------------------------------------------------- This question may be releavant when using F2PY in Makefiles. Here follows a script demonstrating how to determine which Fortran compiler and flags F2PY will use:: # Using post-0.2.2 numpy_distutils from numpy_distutils.fcompiler import new_fcompiler compiler = new_fcompiler() # or new_fcompiler(compiler='intel') compiler.dump_properties() # Using pre-0.2.2 numpy_distutils import os from numpy_distutils.command.build_flib import find_fortran_compiler def main(): fcompiler = os.environ.get('FC_VENDOR') fcompiler_exec = os.environ.get('F77') f90compiler_exec = os.environ.get('F90') fc = find_fortran_compiler(fcompiler, fcompiler_exec, f90compiler_exec, verbose = 0) print 'FC=',fc.f77_compiler print 'FFLAGS=',fc.f77_switches print 'FOPT=',fc.f77_opt if __name__ == "__main__": main() Users feedback ============== Q: Where to find additional information on using F2PY? ------------------------------------------------------ There are several F2PY related tutorials, slides, papers, etc available: + `Fortran to Python Interface Generator with an Application to Aerospace Engineering`__ by P. Peterson, J. R. R. A. Martins, and J. J. Alonso in `In Proceedings of the 9th International Python Conference`__, Long Beach, California, 2001. __ http://www.python9.org/p9-cdrom/07/index.htm __ http://www.python9.org/ + Section `Adding Fortran90 code`__ in the UG of `The Bolometer Data Analysis Project`__. __ http://www.astro.rub.de/laboca/download/boa_master_doc/7_4Adding_Fortran90_code.html __ http://www.openboa.de/ + Powerpoint presentation `Python for Scientific Computing`__ by Eric Jones in `The Ninth International Python Conference`__. __ http://www.python9.org/p9-jones.ppt __ http://www.python9.org/ + Paper `Scripting a Large Fortran Code with Python`__ by Alvaro Caceres Calleja in `International Workshop on Software Engineering for High Performance Computing System Applications`__. __ http://csdl.ics.hawaii.edu/se-hpcs/pdf/calleja.pdf __ http://csdl.ics.hawaii.edu/se-hpcs/ + Section `Automatic building of C/Fortran extension for Python`__ by Simon Lacoste-Julien in `Summer 2002 Report about Hybrid Systems Modelling`__. __ http://moncs.cs.mcgill.ca/people/slacoste/research/report/SummerReport.html#tth_sEc3.4 __ http://moncs.cs.mcgill.ca/people/slacoste/research/report/SummerReport.html + `Scripting for Computational Science`__ by Hans Petter Langtangen (see the `Mixed language programming`__ and `NumPy array programming`__ sections for examples on using F2PY). __ http://www.ifi.uio.no/~inf3330/lecsplit/ __ http://www.ifi.uio.no/~inf3330/lecsplit/slide662.html __ http://www.ifi.uio.no/~inf3330/lecsplit/slide718.html + Chapters 5 and 9 of `Python Scripting for Computational Science`__ by H. P. Langtangen for case studies on using F2PY. __ http://www.springeronline.com/3-540-43508-5 + Section `Fortran Wrapping`__ in `Continuity`__, a computational tool for continuum problems in bioengineering and physiology. __ http://www.continuity.ucsd.edu/cont6_html/docs_fram.html __ http://www.continuity.ucsd.edu/ + Presentation `PYFORT and F2PY: 2 ways to bind C and Fortran with Python`__ by Reiner Vogelsang. __ http://www.prism.enes.org/WPs/WP4a/Slides/pyfort/pyfort.html + Lecture slides of `Extending Python: speed it up`__. __ http://www.astro.uni-bonn.de/~heith/lecture_pdf/friedrich5.pdf + Wiki topics on `Wrapping Tools`__ and `Wrapping Benchmarks`__ for Climate System Center at the University of Chicago. __ https://geodoc.uchicago.edu/climatewiki/DiscussWrappingTools __ https://geodoc.uchicago.edu/climatewiki/WrappingBenchmarks + `Performance Python with Weave`__ by Prabhu Ramachandran. __ http://www.numpy.org/documentation/weave/weaveperformance.html + `How To Install py-f2py on Mac OSX`__ __ http://py-f2py.darwinports.com/ Please, let me know if there are any other sites that document F2PY usage in one or another way. Q: What projects use F2PY? -------------------------- + `SciPy: Scientific tools for Python`__ __ http://www.numpy.org/ + `The Bolometer Data Analysis Project`__ __ http://www.openboa.de/ + `pywavelet`__ __ http://www.met.wau.nl/index.html?http://www.met.wau.nl/medewerkers/moenea/python/pywavelet.html + `PyARTS: an ARTS related Python package`__. __ http://www.met.ed.ac.uk/~cory/PyARTS/ + `Python interface to PSPLINE`__, a collection of Spline and Hermite interpolation tools for 1D, 2D, and 3D datasets on rectilinear grids. __ http://pypspline.sourceforge.net + `Markovian Analysis Package for Python`__. __ http://pymc.sourceforge.net + `Modular toolkit for Data Processing (MDP)`__ __ http://mdp-toolkit.sourceforge.net/ Please, send me a note if you are using F2PY in your project. Q: What people think about F2PY? -------------------------------- *F2PY is GOOD*: Here are some comments people have posted to f2py mailing list and c.l.py: + Ryan Krauss: I really appreciate f2py. It seems weird to say, but I am excited about relearning FORTRAN to compliment my python stuff. + Fabien Wahl: f2py is great, and is used extensively over here... + Fernando Perez: Anyway, many many thanks for this amazing tool. I haven't used pyfort, but I can definitely vouch for the amazing quality of f2py. And since f2py is actively used by numpy, it won't go unmaintained. It's quite impressive, and very easy to use. + Kevin Mueller: First off, thanks to those responsible for F2PY; its been an integral tool of my research for years now. + David Linke: Best regards and thanks for the great tool! + Perrin Meyer: F2Py is really useful! + Hans Petter Langtangen: First of all, thank you for developing F2py. This is a very important contribution to the scientific computing community. We are using F2py a lot and are very happy with it. + Berthold Höllmann: Thank's alot. It seems it is also working in my 'real' application :-) + John Hunter: At first I wrapped them with f2py (unbelievably easy!)... + Cameron Laird: Among many other features, Python boasts a mature f2py, which makes it particularly rewarding to yoke Fortran- and Python-coded modules into finished applications. + Ryan Gutenkunst: f2py is sweet magic. *F2PY is BAD*: + `Is it worth using on a large scale python drivers for Fortran subroutines, interfaced with f2py?`__ __ http://sepwww.stanford.edu/internal/computing/python.html Additional comments on F2PY, good or bad, are welcome! .. References: .. _README.txt: index.html .. _HISTORY.txt: HISTORY.html .. _HISTORY.txt in CVS: http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt?rev=HEAD&content-type=text/x-cvsweb-markup .. _TESTING.txt: TESTING.html