| ====================================================================== | |
| 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 ``<type spec>(kind=KIND(..))``? | |
| --------------------------------------------------------------- | |
| Currently, F2PY can handle only ``<type spec>(kind=<kindselector>)`` | |
| declarations where ``<kindselector>`` 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 <Fortran type> to <C type> 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:: | |
| <Fortran typespec> : {<selector_expr>:<C type>} | |
| that defines mapping between Fortran type:: | |
| <Fortran typespec>([kind=]<selector_expr>) | |
| and the corresponding ``<C type>``. ``<C type>`` 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 others 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 Bemchmarks`__ 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 | |