F2PY: Fortran to Python interface generator

Author: Pearu Peterson <pearu@cens.ioc.ee>
License:LGPL.
Web-site:http://cens.ioc.ee/projects/f2py2e/
Discussions to:f2py-users mailing list
Documentation:User's Guide, FAQ
Platforms:All
Date: 2007-07-19

NEWS!!!

July 19, 2007

F2PY is now part of NumPy. All the development and maintenance of F2PY is carried out under NumPy SVN tree. See F2PY for more information. If you need F2PY with Numeric or Numarray array support then you must use the F2PY version found below.

January 30, 2005

Latest F2PY release (version 2.45.241_1926). New features: wrapping unsigned integers, support for .pyf.src template files, callback arguments can now be CObjects, fortran objects, built-in functions. Introduced intent(aux) attribute. Wrapped objects have _cpointer attribute holding C pointer to wrapped functions or variables. Many bug fixes and improvements, updated documentation. Differences with the previous release (version 2.43.239_1831).
October 4, 2004
F2PY bug fix release (version 2.43.239_1831). Better support for 64-bit platforms. Introduced --help-link and --link-<resource> options. Bug fixes. Differences with the previous release (version 2.43.239_1806).
September 25, 2004
Latest F2PY release (version 2.43.239_1806). Support for ENTRY statement. New attributes: intent(inplace), intent(callback). Supports Numarray 1.1. Introduced -*- fix -*- header content. Improved PARAMETER support. Documentation updates. Differences with the previous release (version 2.39.235-1693).

History of NEWS


Contents

Introduction

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:

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.

Main features

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 ]
      integer*([ -1 | -2 | -4 | -8 ])
      character[ | *(*) | *1 | *2 | *3 | ... ]
      real[ | *4 | *8 | *16 ], double precision
      complex[ | *8 | *16 | *32 ]
      

      Negative integer kinds are used to wrap unsigned integers.

    • 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 | callback | inplace | aux ])
      dimension(<dimspec>)
      common, parameter
      allocatable
      optional, required, external
      depend([<names>])
      check([<C-booleanexpr>])
      note(<LaTeX text>)
      usercode, callstatement, callprotoargument, threadsafe, fortranname
      pymethoddef
      entry
      
  • 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

Prerequisites

F2PY requires the following software installed:

Python 1.x users also need distutils.

Of course, to build extension modules, you'll need also working C and/or Fortran compilers installed.

Download

You can download the sources for the latest F2PY and scipy_distutils releases as:

Windows users might be interested in Win32 installer for F2PY and Scipy_distutils (these installers are built using Python 2.3):

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.

Development version of F2PY from CVS is available as f2py2e.tar.gz.

Debian Sid users can simply install python-f2py package.

Installation

Unpack the source file, change to directrory F2PY-?-???/ and run (you may need to become a root):

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.

See also Installation section in F2PY FAQ.

Similarly, to install scipy_distutils, unpack its tar-ball and run:

python setup.py install

Usage

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:

  1. 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
    
  1. 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.

  1. 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.

Documentation

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.

Mailing list

A mailing list f2py-users@cens.ioc.ee is open for F2PY releated discussion/questions/etc.

CVS

F2PY is being developed under CVS. The CVS version of F2PY can be obtained as follows:

  1. First you need to login (the password is guest):

    cvs -d :pserver:anonymous@cens.ioc.ee:/home/cvs login
    
  2. and then do the checkout:

    cvs -z6 -d :pserver:anonymous@cens.ioc.ee:/home/cvs checkout f2py2e
    
  3. You can update your local F2PY tree f2py2e/ by executing:

    cvs -z6 update -P -d
    

You can browse the F2PY CVS repository.

Contributions

Related sites