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.

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?

You can send bug reports directly to me. Please, include information about your platform (operating system, version) and compilers/linkers, e.g. the output (both stdout/stderr) of

python -c 'import f2py2e.diagnose;f2py2e.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.

While reporting bugs, you may find the following notes useful:

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.

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 scipy_distutils when using F2PY from CVS?

To get scipy_distutils from SciPy CVS repository, run

cd cvs/f2py2e/
make scipy_distutils

This will checkout scipy_distutils to the current directory.

You can upgrade scipy_distutils by executing

cd cvs/f2py2e/scipy_distutils
cvs update -Pd

and install it by executing

cd cvs/f2py2e/scipy_distutils
python setup_scipy_distutils.py install

In most of the time, f2py2e and scipy_distutils can be upgraded independently.

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.

For running F2PY unit tests, see TESTING.txt.

Q: How to run tests and examples in f2py2e/test-suite/ directory?

You shouldn't. These tests are obsolete and I have no intention to make them work. They will be removed in future.

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.

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.

Install scipy_distutils and F2PY. Win32 installers of these packages are provided in F2PY Download section.

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.

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:

cFile: simple.f
      subroutine foo(a,m,n)
      integer m,n,i,j
      real a(m,n)
cf2py intent(in,out) a
cf2py intent(hide) m,n
      do i=1,m
         do j=1,n
            a(i,j) = a(i,j) + 10*i+j
         enddo
      enddo
      end
cEOF

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:

#File: pytest.py
import Numeric
def foo(a):
    a = Numeric.array(a)
    m,n = a.shape
    for i in range(m):
        for j in range(n):
            a[i,j] = a[i,j] + 10*(i+1) + (j+1)
    return a
#eof

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

subroutine foo(a,m,n)
integer m = size(a,1)
integer n = size(a,2)
real, intent(inout) :: a(m,n)
end subroutine foo

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

>>> import pytest
>>> import f2pytest
>>> import pyforttest
>>> print f2pytest.foo.__doc__
foo - Function signature:
  a = foo(a)
Required arguments:
  a : input rank-2 array('f') with bounds (m,n)
Return objects:
  a : rank-2 array('f') with bounds (m,n)

>>> print pyforttest.foo.__doc__
foo(a)

>>> pytest.foo([[1,2],[3,4]])
array([[12, 14],
       [24, 26]])
>>> f2pytest.foo([[1,2],[3,4]])  # F2PY can handle arbitrary input sequences
array([[ 12.,  14.],
       [ 24.,  26.]],'f')
>>> pyforttest.foo([[1,2],[3,4]])
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
pyforttest.error: foo, argument A: Argument intent(inout) must be an array.

>>> import Numeric
>>> a=Numeric.array([[1,2],[3,4]],'f')
>>> f2pytest.foo(a)
array([[ 12.,  14.],
       [ 24.,  26.]],'f')
>>> a   # F2PY makes a copy when input array is not Fortran contiguous
array([[ 1.,  2.],
       [ 3.,  4.]],'f')
>>> a=Numeric.transpose(Numeric.array([[1,3],[2,4]],'f'))
>>> a
array([[ 1.,  2.],
       [ 3.,  4.]],'f')
>>> f2pytest.foo(a)
array([[ 12.,  14.],
       [ 24.,  26.]],'f')
>>> a   # F2PY passes Fortran contiguous input array directly to Fortran
array([[ 12.,  14.],
       [ 24.,  26.]],'f')
# See intent(copy), intent(overwrite), intent(inplace), intent(inout)
# attributes documentation to enhance the above behavior.

>>> a=Numeric.array([[1,2],[3,4]],'f')
>>> pyforttest.foo(a)
>>> a   # Huh? Pyfort 8.5 gives wrong results..
array([[ 12.,  23.],
       [ 15.,  26.]],'f')

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 scipy_distutils
from scipy_distutils.fcompiler import new_fcompiler
compiler = new_fcompiler() # or new_fcompiler(compiler='intel')
compiler.dump_properties()

# Using pre-0.2.2 scipy_distutils
import os
from scipy_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:

Please, let me know if there are any other sites that document F2PY usage in one or another way.

Q: What projects use F2PY?

  • Python interface to PSPLINE, a collection of Spline and Hermite interpolation tools for 1D, 2D, and 3D datasets on rectilinear grids.

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:

  • 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 scipy, 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:

Additional comments on F2PY, good or bad, are welcome!