Three ways to wrap - getting started

Wrapping Fortran or C functions to Python using F2PY consists of the following steps:

• Creating the so-called signature file that contains descriptions of wrappers to Fortran or C functions, also called as signatures of the functions. In the case of Fortran routines, F2PY can create initial signature file by scanning Fortran source codes and catching all relevant information needed to create wrapper functions.
• Optionally, F2PY created signature files can be edited to optimize wrappers functions, make them “smarter” and more “Pythonic”.
• F2PY reads a signature file and writes a Python C/API module containing Fortran/C/Python bindings.
• F2PY compiles all sources and builds an extension module containing the wrappers. In building extension modules, F2PY uses numpy_distutils that supports a number of Fortran 77/90/95 compilers, including Gnu, Intel, Sun Fortre, SGI MIPSpro, Absoft, NAG, Compaq etc. compilers.

Depending on a particular situation, these steps can be carried out either by just in one command or step-by-step, some steps can be omitted or combined with others.

Below I’ll describe three typical approaches of using F2PY. The following example Fortran 77 code will be used for illustration, save it as fib1.f:

C FILE: FIB1.F
      SUBROUTINE FIB(A,N)
C
C     CALCULATE FIRST N FIBONACCI NUMBERS
C
      INTEGER N
      REAL*8 A(N)
      DO I=1,N
         IF (I.EQ.1) THEN
            A(I) = 0.0D0
         ELSEIF (I.EQ.2) THEN
            A(I) = 1.0D0
         ELSE 
            A(I) = A(I-1) + A(I-2)
         ENDIF
      ENDDO
      END
C END FILE FIB1.F

The quick way

The quickest way to wrap the Fortran subroutine FIB to Python is to run

python -m numpy.f2py -c fib1.f -m fib1

This command builds (see -c flag, execute python -m numpy.f2py without arguments to see the explanation of command line options) an extension module fib1.so (see -m flag) to the current directory. Now, in Python the Fortran subroutine FIB is accessible via fib1.fib:

>>> import numpy
>>> import fib1
>>> print(fib1.fib.__doc__)
fib(a,[n])

Wrapper for ``fib``.

Parameters
----------
a : input rank-1 array('d') with bounds (n)

Other Parameters
----------------
n : input int, optional
    Default: len(a)

>>> a = numpy.zeros(8, 'd')
>>> fib1.fib(a)
>>> print(a)
[  0.   1.   1.   2.   3.   5.   8.  13.]

The smart way

Let’s apply the steps of wrapping Fortran functions to Python one by one.

• First, we create a signature file from fib1.f by running

  python -m numpy.f2py fib1.f -m fib2 -h fib1.pyf
  

  The signature file is saved to fib1.pyf (see -h flag) and its contents is shown below.

  !    -*- f90 -*-
  python module fib2 ! in 
      interface  ! in :fib2
          subroutine fib(a,n) ! in :fib2:fib1.f
              real*8 dimension(n) :: a
              integer optional,check(len(a)>=n),depend(a) :: n=len(a)
          end subroutine fib
      end interface 
  end python module fib2
  
  ! This file was auto-generated with f2py (version:2.28.198-1366).
  ! See http://cens.ioc.ee/projects/f2py2e/
  

• Next, we’ll teach F2PY that the argument n is an input argument (use intent(in) attribute) and that the result, i.e. the contents of a after calling Fortran function FIB, should be returned to Python (use intent(out) attribute). In addition, an array a should be created dynamically using the size given by the input argument n (use depend(n) attribute to indicate dependence relation).

  The content of a modified version of fib1.pyf (saved as fib2.pyf) is as follows:

  !    -*- f90 -*-
  python module fib2 
      interface
          subroutine fib(a,n)
              real*8 dimension(n),intent(out),depend(n) :: a
              integer intent(in) :: n
          end subroutine fib
      end interface 
  end python module fib2
  

• And finally, we build the extension module by running

  python -m numpy.f2py -c fib2.pyf fib1.f
  

In Python:

>>> import fib2
>>> print(fib2.fib.__doc__)
a = fib(n)

Wrapper for ``fib``.

Parameters
----------
n : input int

Returns
-------
a : rank-1 array('d') with bounds (n)

>>> print(fib2.fib(8))
[  0.   1.   1.   2.   3.   5.   8.  13.]

The quick and smart way

The “smart way” of wrapping Fortran functions, as explained above, is suitable for wrapping (e.g. third party) Fortran codes for which modifications to their source codes are not desirable nor even possible.

However, if editing Fortran codes is acceptable, then the generation of an intermediate signature file can be skipped in most cases. Namely, F2PY specific attributes can be inserted directly to Fortran source codes using the so-called F2PY directive. A F2PY directive defines special comment lines (starting with Cf2py, for example) which are ignored by Fortran compilers but F2PY interprets them as normal lines.

Here is shown a modified version of the previous Fortran code, save it as fib3.f:

C FILE: FIB3.F
      SUBROUTINE FIB(A,N)
C
C     CALCULATE FIRST N FIBONACCI NUMBERS
C
      INTEGER N
      REAL*8 A(N)
Cf2py intent(in) n
Cf2py intent(out) a
Cf2py depend(n) a
      DO I=1,N
         IF (I.EQ.1) THEN
            A(I) = 0.0D0
         ELSEIF (I.EQ.2) THEN
            A(I) = 1.0D0
         ELSE 
            A(I) = A(I-1) + A(I-2)
         ENDIF
      ENDDO
      END
C END FILE FIB3.F

Building the extension module can be now carried out in one command:

python -m numpy.f2py -c -m fib3 fib3.f

Notice that the resulting wrapper to FIB is as “smart” as in previous case:

>>> import fib3
>>> print(fib3.fib.__doc__)
a = fib(n)

Wrapper for ``fib``.

Parameters
----------
n : input int

Returns
-------
a : rank-1 array('d') with bounds (n)

>>> print(fib3.fib(8))
[  0.   1.   1.   2.   3.   5.   8.  13.]