2.1   The quick way

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

f2py -c fib1.f -m fib1

This command builds (see -c flag, execute 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 Numeric
>>> import fib1
>>> print fib1.fib.__doc__
fib - Function signature:
  fib(a,[n])
Required arguments:
  a : input rank-1 array('d') with bounds (n)
Optional arguments:
  n := len(a) input int

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

2.2   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

  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 a 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

  f2py -c fib2.pyf fib1.f
  

In Python:

>>> import fib2
>>> print fib2.fib.__doc__
fib - Function signature:
  a = fib(n)
Required arguments:
  n : input int
Return objects:
  a : rank-1 array('d') with bounds (n)

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

2.3   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 example Fortran code, saved 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:

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__
fib - Function signature:
  a = fib(n)
Required arguments:
  n : input int
Return objects:
  a : rank-1 array('d') with bounds (n)

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

3.1   Python module block

A signature file may contain one (recommended) or more python module blocks. python module block describes the contents of a Python/C extension module <modulename>module.c that F2PY generates.

Exception: if <modulename> contains a substring __user__, then the corresponding python module block describes the signatures of so-called call-back functions (see Call-back arguments).

A python module block has the following structure:

python module <modulename>
  [<usercode statement>]...
  [
  interface
    <usercode statement>
    <Fortran block data signatures>
    <Fortran/C routine signatures>
  end [interface]
  ]...
  [
  interface
    module <F90 modulename>
      [<F90 module data type declarations>]
      [<F90 module routine signatures>]
    end [module [<F90 modulename>]]
  end [interface]
  ]...
end [python module [<modulename>]]

Here brackets [] indicate a optional part, dots ... indicate one or more of a previous part. So, []... reads zero or more of a previous part.

3.2   Fortran/C routine signatures

The signature of a Fortran routine has the following structure:

[<typespec>] function | subroutine <routine name> \
              [ ( [<arguments>] ) ] [ result ( <entityname> ) ]
  [<argument/variable type declarations>]
  [<argument/variable attribute statements>]
  [<use statements>]
  [<common block statements>]
  [<other statements>]
end [ function | subroutine [<routine name>] ]

From a Fortran routine signature F2PY generates a Python/C extension function that has the following signature:

def <routine name>(<required arguments>[,<optional arguments>]):
     ...
     return <return variables>

The signature of a Fortran block data has the following structure:

block data [ <block data name> ]
  [<variable type declarations>]
  [<variable attribute statements>]
  [<use statements>]
  [<common block statements>]
  [<include statements>]
end [ block data [<block data name>] ]

3.3   Extensions

<comment char>f2py ...

<array name>(_i[0],_i[1],...) = <init_expr>;

subroutine myrange(a,n)
  fortranname        ! myrange is a dummy wrapper
  integer intent(in) :: n
  real*8 intent(c,out),dimension(n),depend(n) :: a = _i[0]
end subroutine myrange

4.1   Scalar arguments

In general, a scalar argument of a F2PY generated wrapper function can be ordinary Python scalar (integer, float, complex number) as well as an arbitrary sequence object (list, tuple, array, string) of scalars. In the latter case, the first element of the sequence object is passed to Fortran routine as a scalar argument.

Note that when type-casting is required and there is possible loss of information (e.g. when type-casting float to integer or complex to float), F2PY does not raise any exception. In complex to real type-casting only the real part of a complex number is used.

intent(inout) scalar arguments are assumed to be array objects in order to in situ changes to be effective. It is recommended to use arrays with proper type but also other types work.

4.2   String arguments

F2PY generated wrapper functions accept (almost) any Python object as a string argument, str is applied for non-string objects. Exceptions are Numeric arrays that must have type code 'c' or '1' when used as string arguments.

A string can have arbitrary length when using it as a string argument to F2PY generated wrapper function. If the length is greater than expected, the string is truncated. If the length is smaller that expected, additional memory is allocated and filled with \0.

Because Python strings are immutable, an intent(inout) argument expects an array version of a string in order to in situ changes to be effective.

C FILE: STRING.F
      SUBROUTINE FOO(A,B,C,D)
      CHARACTER*5 A, B
      CHARACTER*(*) C,D
Cf2py intent(in) a,c
Cf2py intent(inout) b,d
      PRINT*, "A=",A
      PRINT*, "B=",B
      PRINT*, "C=",C
      PRINT*, "D=",D
      PRINT*, "CHANGE A,B,C,D"
      A(1:1) = 'A'
      B(1:1) = 'B'
      C(1:1) = 'C'
      D(1:1) = 'D'
      PRINT*, "A=",A
      PRINT*, "B=",B
      PRINT*, "C=",C
      PRINT*, "D=",D
      END
C END OF FILE STRING.F

>>> import mystring
>>> print mystring.foo.__doc__
foo - Function signature:
  foo(a,b,c,d)
Required arguments:
  a : input string(len=5)
  b : in/output rank-0 array(string(len=5),'c')
  c : input string(len=-1)
  d : in/output rank-0 array(string(len=-1),'c')

>>> import Numeric
>>> a=Numeric.array('123')
>>> b=Numeric.array('123')
>>> c=Numeric.array('123')
>>> d=Numeric.array('123')
>>> mystring.foo(a,b,c,d)
 A=123
 B=123
 C=123
 D=123
 CHANGE A,B,C,D
 A=A23
 B=B23
 C=C23
 D=D23
>>> a.tostring(),b.tostring(),c.tostring(),d.tostring()
('123', 'B23', '123', 'D23')

4.3   Array arguments

In general, array arguments of F2PY generated wrapper functions accept arbitrary sequences that can be transformed to Numeric array objects. An exception is intent(inout) array arguments that always must be proper-contiguous and have proper type, otherwise an exception is raised. Another exception is intent(inplace) array arguments that attributes will be changed in-situ if the argument has different type than expected (see intent(inplace) attribute for more information).

In general, if a Numeric array is proper-contiguous and has a proper type then it is directly passed to wrapped Fortran/C function. Otherwise, an element-wise copy of an input array is made and the copy, being proper-contiguous and with proper type, is used as an array argument.

There are two types of proper-contiguous Numeric arrays:

• Fortran-contiguous arrays when data is stored column-wise, i.e. indexing of data as stored in memory starts from the lowest dimension;
• C-contiguous or simply contiguous arrays when data is stored row-wise, i.e. indexing of data as stored in memory starts from the highest dimension.

For one-dimensional arrays these notions coincide.

For example, an 2x2 array A is Fortran-contiguous if its elements are stored in memory in the following order:

A[0,0] A[1,0] A[0,1] A[1,1]

and C-contiguous if the order is as follows:

A[0,0] A[0,1] A[1,0] A[1,1]

To test whether an array is C-contiguous, use .iscontiguous() method of Numeric arrays. To test for Fortran-contiguousness, all F2PY generated extension modules provide a function has_column_major_storage(<array>). This function is equivalent to Numeric.transpose(<array>).iscontiguous() but more efficient.

Usually there is no need to worry about how the arrays are stored in memory and whether the wrapped functions, being either Fortran or C functions, assume one or another storage order. F2PY automatically ensures that wrapped functions get arguments with proper storage order; the corresponding algorithm is designed to make copies of arrays only when absolutely necessary. However, when dealing with very large multi-dimensional input arrays with sizes close to the size of the physical memory in your computer, then a care must be taken to use always proper-contiguous and proper type arguments.

To transform input arrays to column major storage order before passing them to Fortran routines, use a function as_column_major_storage(<array>) that is provided by all F2PY generated extension modules.

C FILE: ARRAY.F
      SUBROUTINE FOO(A,N,M)
C
C     INCREMENT THE FIRST ROW AND DECREMENT THE FIRST COLUMN OF A
C
      INTEGER N,M,I,J
      REAL*8 A(N,M)
Cf2py intent(in,out,copy) a
Cf2py integer intent(hide),depend(a) :: n=shape(a,0), m=shape(a,1)
      DO J=1,M
         A(1,J) = A(1,J) + 1D0
      ENDDO
      DO I=1,N
         A(I,1) = A(I,1) - 1D0
      ENDDO
      END
C END OF FILE ARRAY.F

>>> import arr
>>> from Numeric import array
>>> print arr.foo.__doc__
foo - Function signature:
  a = foo(a,[overwrite_a])
Required arguments:
  a : input rank-2 array('d') with bounds (n,m)
Optional arguments:
  overwrite_a := 0 input int
Return objects:
  a : rank-2 array('d') with bounds (n,m)

>>> a=arr.foo([[1,2,3],
...            [4,5,6]])
copied an array using PyArray_CopyFromObject: size=6, elsize=8
>>> print a
[[ 1.  3.  4.]
 [ 3.  5.  6.]]
>>> a.iscontiguous(), arr.has_column_major_storage(a)
(0, 1)
>>> b=arr.foo(a)              # even if a is proper-contiguous
...                           # and has proper type, a copy is made
...                           # forced by intent(copy) attribute
...                           # to preserve its original contents
... 
copied an array using copy_ND_array: size=6, elsize=8
>>> print a
[[ 1.  3.  4.]
 [ 3.  5.  6.]]
>>> print b
[[ 1.  4.  5.]
 [ 2.  5.  6.]]
>>> b=arr.foo(a,overwrite_a=1) # a is passed directly to Fortran
...                            # routine and its contents is discarded
... 
>>> print a
[[ 1.  4.  5.]
 [ 2.  5.  6.]]
>>> print b
[[ 1.  4.  5.]
 [ 2.  5.  6.]]
>>> a is b                       # a and b are acctually the same objects
1
>>> print arr.foo([1,2,3])       # different rank arrays are allowed
copied an array using PyArray_CopyFromObject: size=3, elsize=8
[ 1.  1.  2.]
>>> print arr.foo([[[1],[2],[3]]])
copied an array using PyArray_CopyFromObject: size=3, elsize=8
[ [[ 1.]
  [ 3.]
  [ 4.]]]
>>>
>>> # Creating arrays with column major data storage order:
...
>>> s = arr.as_column_major_storage(array([[1,2,3],[4,5,6]]))
copied an array using copy_ND_array: size=6, elsize=4
>>> arr.has_column_major_storage(s)
1
>>> print s
[[1 2 3]
 [4 5 6]]
>>> s2 = arr.as_column_major_storage(s)
>>> s2 is s    # an array with column major storage order 
               # is returned immediately
1

4.4   Call-back arguments

F2PY supports calling Python functions from Fortran or C codes.

C FILE: CALLBACK.F
      SUBROUTINE FOO(FUN,R)
      EXTERNAL FUN
      INTEGER I
      REAL*8 R
Cf2py intent(out) r
      R = 0D0
      DO I=-5,5
         R = R + FUN(I)
      ENDDO
      END
C END OF FILE CALLBACK.F

>>> import callback
>>> print callback.foo.__doc__
foo - Function signature:
  r = foo(fun,[fun_extra_args])
Required arguments:
  fun : call-back function
Optional arguments:
  fun_extra_args := () input tuple
Return objects:
  r : float
Call-back functions:
  def fun(i): return r
  Required arguments:
    i : input int
  Return objects:
    r : float

>>> def f(i): return i*i
... 
>>> print callback.foo(f)     
110.0
>>> print callback.foo(lambda i:1)
11.0

In the above example F2PY was able to guess accurately the signature of a call-back function. However, sometimes F2PY cannot establish the signature as one would wish and then the signature of a call-back function must be modified in the signature file manually. Namely, signature files may contain special modules (the names of such modules contain a substring __user__) that collect various signatures of call-back functions. Callback arguments in routine signatures have attribute external (see also intent(callback) attribute). To relate a callback argument and its signature in __user__ module block, use use statement as illustrated below. The same signature of a callback argument can be referred in different routine signatures.

f2py -m callback2 -h callback2.pyf callback.f

!    -*- f90 -*-
python module __user__routines 
    interface
        function fun(i) result (r)
            integer :: i
            real*8 :: r
        end function fun
    end interface
end python module __user__routines

python module callback2
    interface
        subroutine foo(f,r)
            use __user__routines, f=>fun
            external f
            real*8 intent(out) :: r
        end subroutine foo
    end interface 
end python module callback2

f2py -c callback2.pyf callback.f

Sometimes a Fortran package may require that users provide routines that the package will use. F2PY can construct an interface to such routines so that Python functions could be called from Fortran.

      subroutine calculate(x,n)
cf2py intent(callback) func
      external func
c     The following lines define the signature of func for F2PY:
cf2py real*8 y
cf2py y = func(y)
c
cf2py intent(in,out,copy) x
      integer n,i
      real*8 x(n)
      do i=1,n
         x(i) = func(x(i))
      end do
      end

f2py -c -m foo calculate.f

>>> import foo
>>> foo.calculate(range(5), lambda x: x*x)
array([  0.,   1.,   4.,   9.,  16.])
>>> import math
>>> foo.calculate(range(5), math.exp)
array([  1.        ,   2.71828175,   7.38905621,  20.08553696,  54.59814835])

The function is included as an argument to the python function call to the FORTRAN subroutine eventhough it was NOT in the FORTRAN subroutine argument list. The "external" refers to the C function generated by f2py, not the python function itself. The python function must be supplied to the C function.

The callback function may also be explicitly set in the module. Then it is not necessary to pass the function in the argument list to the FORTRAN function. This may be desired if the FORTRAN function calling the python callback function is itself called by another FORTRAN function.

      subroutine f1()
         print *, "in f1, calling f2 twice.."
         call f2()
         call f2()
         return
      end
      
      subroutine f2()
cf2py    intent(callback, hide) fpy
         external fpy
         print *, "in f2, calling f2py.."
         call fpy()
         return
      end

>>> import pfromf
>>> pfromf.f2()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
pfromf.error: Callback fpy not defined (as an argument or module pfromf attribute).

>>> def f(): print "python f"
... 
>>> pfromf.fpy = f
>>> pfromf.f2()
 in f2, calling f2py..
python f
>>> pfromf.f1()
 in f1, calling f2 twice..
 in f2, calling f2py..
python f
 in f2, calling f2py..
python f
>>> 

def fun(a_1,...,a_n):
   ...
   return x_1,...,x_k

def gun(b_1,...,b_m):
   ...
   return y_1,...,y_l

fun_extra_args = (e_1,...,e_p)

4.5   Common blocks

F2PY generates wrappers to common blocks defined in a routine signature block. Common blocks are visible by all Fortran codes linked with the current extension module, but not to other extension modules (this restriction is due to how Python imports shared libraries). In Python, the F2PY wrappers to common blocks are fortran type objects that have (dynamic) attributes related to data members of common blocks. When accessed, these attributes return as Numeric array objects (multi-dimensional arrays are Fortran-contiguous) that directly link to data members in common blocks. Data members can be changed by direct assignment or by in-place changes to the corresponding array objects.

C FILE: COMMON.F
      SUBROUTINE FOO
      INTEGER I,X
      REAL A
      COMMON /DATA/ I,X(4),A(2,3)
      PRINT*, "I=",I
      PRINT*, "X=[",X,"]"
      PRINT*, "A=["
      PRINT*, "[",A(1,1),",",A(1,2),",",A(1,3),"]"
      PRINT*, "[",A(2,1),",",A(2,2),",",A(2,3),"]"
      PRINT*, "]"
      END
C END OF COMMON.F

>>> import common
>>> print common.data.__doc__
i - 'i'-scalar
x - 'i'-array(4)
a - 'f'-array(2,3)

>>> common.data.i = 5
>>> common.data.x[1] = 2 
>>> common.data.a = [[1,2,3],[4,5,6]]
>>> common.foo()
 I= 5
 X=[ 0 2 0 0]
 A=[
 [  1.,  2.,  3.]
 [  4.,  5.,  6.]
 ]
>>> common.data.a[1] = 45
>>> common.foo()
 I= 5
 X=[ 0 2 0 0]
 A=[
 [  1.,  2.,  3.]
 [  45.,  45.,  45.]
 ]
>>> common.data.a                 # a is Fortran-contiguous
array([[  1.,   2.,   3.],
       [ 45.,  45.,  45.]],'f')

4.6   Fortran 90 module data

The F2PY interface to Fortran 90 module data is similar to Fortran 77 common blocks.

module mod
  integer i
  integer :: x(4)
  real, dimension(2,3) :: a
  real, allocatable, dimension(:,:) :: b 
contains
  subroutine foo
    integer k
    print*, "i=",i
    print*, "x=[",x,"]"
    print*, "a=["
    print*, "[",a(1,1),",",a(1,2),",",a(1,3),"]"
    print*, "[",a(2,1),",",a(2,2),",",a(2,3),"]"
    print*, "]"
    print*, "Setting a(1,2)=a(1,2)+3"
    a(1,2) = a(1,2)+3
  end subroutine foo
end module mod

>>> import moddata
>>> print moddata.mod.__doc__
i - 'i'-scalar
x - 'i'-array(4)
a - 'f'-array(2,3)
foo - Function signature:
  foo()


>>> moddata.mod.i = 5  
>>> moddata.mod.x[:2] = [1,2]
>>> moddata.mod.a = [[1,2,3],[4,5,6]]
>>> moddata.mod.foo()                
 i=           5
 x=[           1           2           0           0 ]
 a=[
 [   1.000000     ,   2.000000     ,   3.000000     ]
 [   4.000000     ,   5.000000     ,   6.000000     ]
 ]
 Setting a(1,2)=a(1,2)+3
>>> moddata.mod.a               # a is Fortran-contiguous
array([[ 1.,  5.,  3.],
       [ 4.,  5.,  6.]],'f')

module mod
  real, allocatable, dimension(:,:) :: b 
contains
  subroutine foo
    integer k
    if (allocated(b)) then
       print*, "b=["
       do k = 1,size(b,1)
          print*, b(k,1:size(b,2))
       enddo
       print*, "]"
    else
       print*, "b is not allocated"
    endif
  end subroutine foo
end module mod

>>> import allocarr 
>>> print allocarr.mod.__doc__
b - 'f'-array(-1,-1), not allocated
foo - Function signature:
  foo()

>>> allocarr.mod.foo()  
 b is not allocated
>>> allocarr.mod.b = [[1,2,3],[4,5,6]]         # allocate/initialize b
>>> allocarr.mod.foo()
 b=[
   1.000000       2.000000       3.000000    
   4.000000       5.000000       6.000000    
 ]
>>> allocarr.mod.b                             # b is Fortran-contiguous
array([[ 1.,  2.,  3.],
       [ 4.,  5.,  6.]],'f')
>>> allocarr.mod.b = [[1,2,3],[4,5,6],[7,8,9]] # reallocate/initialize b
>>> allocarr.mod.foo()
 b=[
   1.000000       2.000000       3.000000    
   4.000000       5.000000       6.000000    
   7.000000       8.000000       9.000000    
 ]
>>> allocarr.mod.b = None                      # deallocate array
>>> allocarr.mod.foo()
 b is not allocated

5.1   Command f2py

When used as a command line tool, f2py has three major modes, distinguished by the usage of -c and -h switches:

1. To scan Fortran sources and generate a signature file, use

f2py -h <filename.pyf> <options> <fortran files>   \
  [[ only: <fortran functions>  : ]                \
   [ skip: <fortran functions>  : ]]...            \
  [<fortran files> ...]

Note that a Fortran source file can contain many routines, and not necessarily all routines are needed to be used from Python. So, you can either specify which routines should be wrapped (in only: .. : part) or which routines F2PY should ignored (in skip: .. : part).

If <filename.pyf> is specified as stdout then signatures are send to standard output instead of a file.

Among other options (see below), the following options can be used in this mode:

--overwrite-signature

Overwrite existing signature file.

2. To construct an extension module, use

f2py <options> <fortran files>          \
  [[ only: <fortran functions>  : ]     \
   [ skip: <fortran functions>  : ]]... \
  [<fortran files> ...]

The constructed extension module is saved as <modulename>module.c to the current directory.

Here <fortran files> may also contain signature files. Among other options (see below), the following options can be used in this mode:

--debug-capi

Add debugging hooks to the extension module. When using this extension module, various information about the wrapper is printed to standard output, for example, the values of variables, the steps taken, etc.

-include'<includefile>'

Add a CPP #include statement to the extension module source. <includefile> should be given in one of the following forms:

"filename.ext"
<filename.ext>

The include statement is inserted just before the wrapper functions. This feature enables using arbitrary C functions (defined in <includefile>) in F2PY generated wrappers.

This option is deprecated. Use usercode statement to specify C codelets directly in signature filess

--[no-]wrap-functions

Create Fortran subroutine wrappers to Fortran functions. --wrap-functions is default because it ensures maximum portability and compiler independence.

--include-paths <path1>:<path2>:..

Search include files from given directories.

--help-link [<list of resources names>]

List system resources found by numpy_distutils/system_info.py. For example, try f2py --help-link lapack_opt.

3. To build an extension module, use

f2py -c <options> <fortran files>       \
  [[ only: <fortran functions>  : ]     \
   [ skip: <fortran functions>  : ]]... \
  [ <fortran/c source files> ] [ <.o, .a, .so files> ]

If <fortran files> contains a signature file, then a source for an extension module is constructed, all Fortran and C sources are compiled, and finally all object and library files are linked to the extension module <modulename>.so which is saved into the current directory.

If <fortran files> does not contain a signature file, then an extension module is constructed by scanning all Fortran source codes for routine signatures.

Among other options (see below) and options described in previous mode, the following options can be used in this mode:

--help-fcompiler

List available Fortran compilers.

--help-compiler [depreciated]

List available Fortran compilers.

--fcompiler=<Vendor>

Specify Fortran compiler type by vendor.

--f77exec=<path>

Specify the path to F77 compiler

--fcompiler-exec=<path> [depreciated]

Specify the path to F77 compiler

--f90exec=<path>

Specify the path to F90 compiler

--f90compiler-exec=<path> [depreciated]

Specify the path to F90 compiler

--f77flags=<string>

Specify F77 compiler flags

--f90flags=<string>

Specify F90 compiler flags

--opt=<string>

Specify optimization flags

--arch=<string>

Specify architecture specific optimization flags

--noopt

Compile without optimization

--noarch

Compile without arch-dependent optimization

--debug

Compile with debugging information

-l<libname>

Use the library <libname> when linking.

-D<macro>[=<defn=1>]

Define macro <macro> as <defn>.

-U<macro>

Define macro <macro>

-I<dir>

Append directory <dir> to the list of directories searched for include files.

-L<dir>

Add directory <dir> to the list of directories to be searched for -l.

link-<resource>

Link extension module with <resource> as defined by numpy_distutils/system_info.py. E.g. to link with optimized LAPACK libraries (vecLib on MacOSX, ATLAS elsewhere), use --link-lapack_opt. See also --help-link switch.

When building an extension module, a combination of the following macros may be required for non-gcc Fortran compilers:

-DPREPEND_FORTRAN
-DNO_APPEND_FORTRAN
-DUPPERCASE_FORTRAN

To test the performance of F2PY generated interfaces, use -DF2PY_REPORT_ATEXIT. Then a report of various timings is printed out at the exit of Python. This feature may not work on all platforms, currently only Linux platform is supported.

To see whether F2PY generated interface performs copies of array arguments, use -DF2PY_REPORT_ON_ARRAY_COPY=<int>. When the size of an array argument is larger than <int>, a message about the coping is sent to stderr.

Other options:

-m <modulename>

Name of an extension module. Default is untitled. Don't use this option if a signature file (*.pyf) is used.

System Message: WARNING/2 (numpy/f2py/docs/usersguide/index.txt, line 1556); backlink

Inline emphasis start-string without end-string.

--[no-]lower

Do [not] lower the cases in <fortran files>. By default, --lower is assumed with -h switch, and --no-lower without the -h switch.

--build-dir <dirname>

All F2PY generated files are created in <dirname>. Default is tempfile.mkdtemp().

--quiet

Run quietly.

--verbose

Run with extra verbosity.

-v

Print f2py version ID and exit.

Execute f2py without any options to get an up-to-date list of available options.

5.2   Python module f2py2e

The following functions are provided by the f2py2e module:

run_main(<list>)

Equivalent to running:

f2py <args>

where <args>=string.join(<list>,' '), but in Python. Unless -h is used, this function returns a dictionary containing information on generated modules and their dependencies on source files. For example, the command f2py -m scalar scalar.f can be executed from Python as follows

>>> import f2py2e
>>> r=f2py2e.run_main(['-m','scalar','docs/usersguide/scalar.f'])
Reading fortran codes...
        Reading file 'docs/usersguide/scalar.f'
Post-processing...
        Block: scalar
                        Block: FOO
Building modules...
        Building module "scalar"...
        Wrote C/API module "scalar" to file "./scalarmodule.c"
>>> print r
{'scalar': {'h': ['/home/users/pearu/src_cvs/f2py2e/src/fortranobject.h'],
         'csrc': ['./scalarmodule.c', 
                  '/home/users/pearu/src_cvs/f2py2e/src/fortranobject.c']}}

You cannot build extension modules with this function, that is, using -c is not allowed. Use compile command instead, see below.

compile(source, modulename='untitled', extra_args='', verbose=1, source_fn=None)

Build extension module from Fortran 77 source string source. Return 0 if successful. Note that this function actually calls f2py -c .. from shell to ensure safety of the current Python process. For example,

>>> import f2py2e
>>> fsource = '''
...       subroutine foo
...       print*, "Hello world!"
...       end 
... '''
>>> f2py2e.compile(fsource,modulename='hello',verbose=0)
0
>>> import hello
>>> hello.foo()
 Hello world!

6.1   numpy_distutils 0.2.2 and up

• The following new distutils commands are defined:

  build_src

  to construct Fortran wrapper extension modules, among many other things.

  config_fc

  to change Fortran compiler options

  as well as build_ext and build_clib commands are enhanced to support Fortran sources.

  Run

  python <setup.py file> config_fc build_src build_ext --help
  

  to see available options for these commands.

• When building Python packages containing Fortran sources, then one can choose different Fortran compilers by using build_ext command option --fcompiler=<Vendor>. Here <Vendor> can be one of the following names:

  absoft sun mips intel intelv intele intelev nag compaq compaqv gnu vast pg hpux
  

  See numpy_distutils/fcompiler.py for up-to-date list of supported compilers or run

  f2py -c --help-fcompiler
  

6.2   numpy_distutils pre 0.2.2

• The following new distutils commands are defined:

  build_flib

  to build f77/f90 libraries used by Python extensions;

  run_f2py

  to construct Fortran wrapper extension modules.

  Run

  python <setup.py file> build_flib run_f2py --help
  

  to see available options for these commands.

• When building Python packages containing Fortran sources, then one can choose different Fortran compilers either by using build_flib command option --fcompiler=<Vendor> or by defining environment variable FC_VENDOR=<Vendor>. Here <Vendor> can be one of the following names:

  Absoft Sun SGI Intel Itanium NAG Compaq Digital Gnu VAST PG
  

  See numpy_distutils/command/build_flib.py for up-to-date list of supported compilers.

7.1   Adding self-written functions to F2PY generated modules

Self-written Python C/API functions can be defined inside signature files using usercode and pymethoddef statements (they must be used inside the python module block). For example, the following signature file spam.pyf

!    -*- f90 -*-
python module spam
    usercode '''
  static char doc_spam_system[] = "Execute a shell command.";
  static PyObject *spam_system(PyObject *self, PyObject *args)
  {
    char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = system(command);
    return Py_BuildValue("i", sts);
  }
    '''
    pymethoddef '''
    {"system",  spam_system, METH_VARARGS, doc_spam_system},
    '''
end python module spam

wraps the C library function system():

f2py -c spam.pyf

In Python:

>>> import spam
>>> status = spam.system('whoami')
pearu
>> status = spam.system('blah')
sh: line 1: blah: command not found

7.2   Modifying the dictionary of a F2PY generated module

The following example illustrates how to add an user-defined variables to a F2PY generated extension module. Given the following signature file

!    -*- f90 -*-
python module var
  usercode '''
    int BAR = 5;
  '''
  interface
    usercode '''
      PyDict_SetItemString(d,"BAR",PyInt_FromLong(BAR));
    '''
  end interface
end python module

compile it as f2py -c var.pyf.

Notice that the second usercode statement must be defined inside an interface block and where the module dictionary is available through the variable d (see f2py var.pyf-generated varmodule.c for additional details).

In Python:

>>> import var
>>> var.BAR
5