F2PY: Fortran to Python interface generator
NEWS!!!
- March 30, 2004
- F2PY bug fix release (version 2.39.235-1693). Two new command line switches:
--compiler and --include_paths. Support for allocatable string arrays.
Callback arguments may now be arbitrary callable objects. Win32 installers
for F2PY and Scipy_core are provided.
Differences with the previous release (version 2.37.235-1660).
- March 9, 2004
- F2PY bug fix release (version 2.39.235-1660).
Differences with the previous release (version 2.37.235-1644).
- February 24, 2004
- Latest F2PY release (version 2.39.235-1644).
Support for scipy_distutils 0.2.2 and up (e.g. compiler flags can be
changed via f2py command line options). Implemented support for
character arrays and arrays of strings (e.g. character*(*) a(m,..)).
Important bug fixes regarding complex arguments, upgrading is
highly recommended. Documentation updates.
Differences with the previous release (version 2.37.233-1545).
- September 11, 2003
- Latest F2PY release (version 2.37.233-1545).
New statements: pymethoddef and usercode in interface blocks.
New function: as_column_major_storage.
New CPP macro: F2PY_REPORT_ON_ARRAY_COPY.
Bug fixes.
Differences with the previous release (version 2.35.229-1505).
- August 2, 2003
- Latest F2PY release (version 2.35.229-1505).
Differences with the previous release (version 2.32.225-1419).
- April 2, 2003
- Initial support for Numarray (thanks to Todd Miller).
- December 8, 2002
- Sixth public release of F2PY (version 2.32.225-1419). Comes with
revised F2PY Users Guide, new testing site, lots of fixes
and other improvements, see HISTORY.txt for details.
The purpose of the F2PY --Fortran to Python interface generator--
project is to provide connection between Python and Fortran
languages. F2PY is a Python extension tool for creating Python C/API
modules from (handwritten or F2PY generated) signature files (or
directly from Fortran sources). The generated extension modules
facilitate:
- Calling Fortran 77/90/95, Fortran 90/95 module, and C functions from
Python.
- Accessing Fortran 77 COMMON blocks and Fortran 90/95 module
data (including allocatable arrays) from Python.
- Calling Python functions from Fortran or C (call-backs).
- Automatically handling the difference in the data storage order of
multi-dimensional Fortran and Numerical Python (i.e. C) arrays.
In addition, F2PY can build the generated extension modules to shared
libraries with one command. F2PY uses the scipy_distutils module
from SciPy that supports number of major Fortran compilers.
F2PY generated extension modules depend on NumPy package that
provides fast multi-dimensional array language facility to Python.
Here follows a more detailed list of F2PY features:
F2PY scans real Fortran codes to produce the so-called signature
files (.pyf files). The signature files contain all the information
(function names, arguments and their types, etc.) that is needed to
construct Python bindings to Fortran (or C) functions.
The syntax of signature files is borrowed from the
Fortran 90/95 language specification and has some F2PY specific
extensions. The signature files can be modified to dictate how
Fortran (or C) programs are called from Python:
- F2PY solves dependencies between arguments (this is relevant for
the order of initializing variables in extension modules).
- Arguments can be specified to be optional or hidden that
simplifies calling Fortran programs from Python considerably.
- In principle, one can design any Python signature for a given
Fortran function, e.g. change the order arguments, introduce
auxiliary arguments, hide the arguments, process the arguments
before passing to Fortran, return arguments as output of F2PY
generated functions, etc.
F2PY automatically generates __doc__ strings (and optionally LaTeX
documentation) for extension modules.
F2PY generated functions accept arbitrary (but sensible) Python
objects as arguments. The F2PY interface automatically takes care of
type-casting and handling of non-contiguous arrays.
The following Fortran constructs are recognized by F2PY:
All basic Fortran types:
integer[ | *1 | *2 | *4 | *8 ], logical[ | *1 | *2 | *4 | *8 ]
character[ | *(*) | *1 | *2 | *3 | ... ]
real[ | *4 | *8 | *16 ], double precision
complex[ | *8 | *16 | *32 ]
Multi-dimensional arrays of all basic types with the following
dimension specifications:
<dim> | <start>:<end> | * | :
Attributes and statements:
intent([ in | inout | out | hide | in,out | inout,out | c |
copy | cache ])
dimension(<dimspec>)
common, parameter
allocatable
optional, required, external
depend([<names>])
check([<C-booleanexpr>])
note(<LaTeX text>)
usercode, callstatement, callprotoargument, threadsafe, fortranname
Because there are only little (and easily handleable) differences
between calling C and Fortran functions from F2PY generated
extension modules, then F2PY is also well suited for wrapping C
libraries to Python.
Practice has shown that F2PY generated interfaces (to C or Fortran
functions) are less error prone and even more efficient than
handwritten extension modules. The F2PY generated interfaces are
easy to maintain and any future optimization of F2PY generated
interfaces transparently apply to extension modules by just
regenerating them with the latest version of F2PY.
F2PY Users Guide and Reference Manual
F2PY requires the following software installed:
- Python (versions 1.5.2 or later; 2.1 and up are recommended)
- NumPy (versions 13 or later; 20.x, 21.x, 22.x, 23.x are recommended)
- Numarray (version 0.4.4 and up), optional, partial support.
- Scipy_core (version 0.2.2 and up are recommended), contains SciPy
package scipy_distutils that f2py uses.
Python 1.x users also need distutils.
Of course, to build extension modules, you'll need also working C
and/or Fortran compilers installed.
You can download the sources for the latest F2PY release as:
Windows users might be interested in Win32 installer for F2PY and Scipy_core:
Older releases are also available in the directories
rel-0.x, rel-1.x, rel-2.x, rel-3.x, rel-4.x, rel-5.x,
if you need them.
Snapshots of Scipy_core are also available in 2.x.
Unpack the source file, change to directrory f2py-?-???/ and run:
python setup.py install
The F2PY installation installs a Python package f2py2e to your
Python site-packages directory and a script f2py to your
Python executable path.
In addition, if scipy_distutils is not already installed, then the
above setup.py script installs it from the f2py-?-???/other/
directory. If scipy_distutils is installed, then its version is
checked. If f2py needs a newer version, then a permission is asked to
upgrade scipy_distutils:
-> Let f2py to upgrade scipy_distutils? [y]/n:
See also Installation section in F2PY FAQ.
To check if F2PY is installed correctly, run
f2py
without any arguments. This should print out the usage information of
the f2py program.
Next, try out the following three steps:
Create a Fortran file hello.f that contains:
C File hello.f
subroutine foo (a)
integer a
print*, "Hello from Fortran!"
print*, "a=",a
end
- Run
f2py -c -m hello hello.f
This will build an extension module hello.so (or hello.sl,
or hello.pyd, etc. depending on your platform) into the current
directory.
Now in Python try:
>>> import hello
>>> print hello.__doc__
>>> print hello.foo.__doc__
>>> hello.foo(4)
Hello from Fortran!
a= 4
>>>
If the above works, then you can try out more thorough
F2PY unit tests and read the F2PY Users Guide and Reference Manual.
The documentation of the F2PY project is collected in f2py2e/docs/
directory. It contains the following documents:
- README.txt (in CVS)
- The first thing to read about F2PY -- this document.
- usersguide/index.txt, usersguide/f2py_usersguide.pdf
- F2PY Users Guide and Reference Manual. Contains lots of examples.
- FAQ.txt (in CVS)
- F2PY Frequently Asked Questions.
- TESTING.txt (in CVS)
- About F2PY testing site. What tests are available and how to run them.
- HISTORY.txt (in CVS)
- A list of latest changes in F2PY. This is the most up-to-date
document on F2PY.
- THANKS.txt
- Acknowledgments.
F2PY is being developed under CVS. The CVS version of F2PY can be
obtained as follows:
First you need to login (the password is guest):
cvs -d :pserver:anonymous@cens.ioc.ee:/home/cvs login
and then do the checkout:
cvs -z6 -d :pserver:anonymous@cens.ioc.ee:/home/cvs checkout f2py2e
You can update your local F2PY tree f2py2e/ by executing:
cvs -z6 update -P -d
You can browse the F2PY CVS repository.