F2PY Users Guide and Reference Manual

Author: Pearu Peterson <pearu@cens.ioc.ee>
Web-site:http://cens.ioc.ee/projects/f2py2e/

Contents

1   Introduction

The purpose of the F2PY --Fortran to Python interface generator-- project is to provide a connection between Python and Fortran languages. F2PY is a Python package (with a command line tool f2py and a module f2py2e) that facilitates creating/building Python C/API extension modules that make it possible

from Python. See F2PY web site for more information and installation instructions.

2   Signature file

The syntax of signature files (.pyf files) is borrowed from the Fortran 90/95 language specification. Almost all Fortran 90/95 standard constructs are understood, both in free and fixed format (recall that Fortran 77 is a subset of Fortran 90/95). F2PY introduces also some extensions to Fortran 90/95 language specification (e.g. attributes intent(out), intent(hide), intent(cache), etc) that help designing Fortran to Python interface, make it more "Pythonic".

Signature files can contain arbitrary Fortran code (so that Fortran codes itself can be considered as signature files). F2PY ignores Fortran constructs that are irrelevant for creating the interface. However, this includes also syntax errors. So, be careful to not make ones;-).

In the following, a short overview of the syntax of signature files, or more specifically, the Fortran constructs used by F2PY, will be given,

2.1   Python module block

A signature file may contain one (recommended) or more python module blocks. python module block describes the contents of Python/C extension module <modulename>module.c that F2PY generates. Exception: if <modulename> contains a substring __user__, then the corresponding python module block describes so-called call-back functions (see ...).

A python module block has the following structure:

python module <modulename>
  [
  interface
    <Fortran 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.

2.2   Fortran 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 Fortran routine signatures F2PY generates Python/C extension functions that have the following general signature:

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

2.2.1   Type declarations

The definition of the <argument/variable type declaration> part is

<typespec> [ [<attrspec>] :: ] <entitydecl>

where

<typespec> := byte | character [<charselector>] 
           | complex [<kindselector>] | real [<kindselector>]
           | double complex | double precision 
           | integer [<kindselector>] | logical [<kindselector>]

<charselector> := * <charlen> 
               | ( [len=] <len> [ , [kind=] <kind>] )
               | ( kind= <kind> [ , len= <len> ] )
<kindselector> := * <intlen> | ( [kind=] <kind> )

<entitydecl> := <name> [ [ * <charlen> ] [ ( <arrayspec> ) ] 
                      | [ ( <arrayspec> ) ] * <charlen> ]
                     | [ / <init_expr> / | = <init_expr> ] \
                       [ , <entitydecl> ]

and

  • <attrspec> is a comma separated list of attributes;
  • <arrayspec> is a comma separated list of dimension bounds;
  • <init_expr> is a C-expression (see Sec. 2.4).

If an argument has no <argument type declaration>, its type is determined by applying implicit rules.

2.2.2   Statements

Attribute statements:

The <argument/variable attribute statement> is <argument/variable type declaration> without <typespec>.

Use statements:

The definition of the <use statement> part is

use <modulename> [ , <rename_list> | , ONLY : <only_list> ]

where

<rename_list> := <local_name> => <use_name> [ , <rename_list> ]

Currently F2PY uses use statement only for linking call-back modules (Sec. 2.7) and external arguments (call-back functions).

Common block statements:

The definition of the <common block statement> part is

common / <common name> / <shortentitydecl>

where

<shortentitydecl> := <name> [ ( <arrayspec> ) ] [ , <shortentitydecl> ]

One python module block should not contain two or more common blocks with the same name. Otherwise, the later ones are ignored. The types of variables in <shortentitydecl> are defined using <argument type declarations>. Note that the corresponding <argument type declarations> may contain array specifications; then you don't need specify these in <shortentitydecl>.

Other statements:

The <other statement> part refers to any other Fortran language constructs that are not described above. F2PY ignores most of them except

  • call statements and function calls of external arguments;
  • include statements;
  • implicit statements.

In addition, F2PY introduces the following statements:

  • threadsafe

    Use Py_BEGIN_ALLOW_THREADS .. Py_END_ALLOW_THREADS block around the call to Fortran/C function.

  • callstatement <C-expr>

    Replace F2PY generated call statement to Fortran/C function with <C-expr>. Use (*f2py_func) to refer to a Fortran/C function.

  • callprotoargument <C-typespecs>

    When callstatement statement is used then F2PY does not generate proper prototypes for Fortran/C functions (because <C-expr> may contain any function calls and F2PY has no way to determine what should be the proper prototype). With this statement you can explicitely specify the arguments of the corresponding prototype:

    extern <return type> FUNC_F(<routine name>,<ROUTINE NAME>)(<callprotoargument>);
    
  • fortranname <acctual Fortran/C routine name>

    You can use arbitrary <routine name> for a given Fortran/C function. Then you have to specify <acctual Fortran/C routine name> with this statement.

2.2.3   Attributes

The following attributes are used by F2PY:

optional

The corresponding argument is moved to the end of <optional arguments> list. A default value for an optional argument can be specified <init_expr>, see entitydecl definition. Note that the default value must be given as a valid C expression.

Note that whenever <init_expr> is used, optional attribute is set automatically by F2PY.

required
The corresponding argument is considered as a required one. This is default. You need to specify required only to disable automatic optional setting when <init_expr> is used.
dimension(<arrayspec>)
The corresponding variable is considered as an array.
intent(<intentspec>)

This specifies the "intention" of the corresponding argument. <intentspec> is a comma separated list of the following keys:

  • in

    The argument is considered as an input only argument. It means that the value of the argument is passed to Fortran/C function and that function is expected not to change the value of an argument.

  • inout

    The argument is considered as an input/output or in situ output argument. intent(inout) arguments can be only "contiguous" Numeric arrays with proper type and size. Here "contiguous" can be either in Fortran or C sense. The latter one coincides with the contiguous concept used in Numeric and is effective only if intent(c) is used. Fortran-contiguousness is assumed by default.

    Using intent(inout) is generally not recommended, use intent(in,out) instead.

  • out

    The argument is considered as an return variable. It is appended to the <returned variables> list. Using intent(out) automatically also sets intent(hide) unless also intent(in) or intent(inout) were used.

  • hide

    The argument is removed from the list of required or optional arguments. Typically intent(hide) is used with intent(out) or when <init_expr> completely determines the value of the argument like in the following example:

    integer intent(hide),depend(a) :: n = len(a)
    real intent(in),dimension(n) :: a      
    
  • c

    The argument is treated as a C argument. In the case of a scalar, its value is passed to C function as a C scalar argument (recall that Fortran scalar arguments are actually C pointer arguments). In the case of an array, the F2PY hooks for checking Fortran-contiguousness are disabled.

  • cache

    The argument is treated as a junk of memory. No Fortran nor C contiguousness checks are carried out. Using intent(cache) makes sense only for array arguments, also with connection to intent(hide) or optional.

  • copy

    Ensure that the original contents of intent(in) argument is preserved. Typically used in connection with intent(in,out).

  • overwrite

    The original contents of the intent(in) argument may be altered by the Fortran/C function.

  • out=<new name>

    Replace the return name with <new name> in the __doc__ string of a wrapper function.

The following rules apply:

  • If no intent(in | inout | out | hide) is specified, intent(in) is assumed.
  • intent(in,inout) is intent(in).
  • intent(in,hide) or intent(inout,hide) is intent(hide).
  • intent(out) is intent(out,hide) unless intent(in) or intent(inout) is specified.
  • If intent(copy) or intent(overwrite) is used, then an additional optional argument is introduced with a name overwrite_<argument name> and a default value 0 or 1, respectively.
check([<C-booleanexpr>])
Perform consistency check of arguments by evaluating <C-booleanexpr>, if it returns 0 an exception is raised. If check(..) is not used then F2PY generates few standard checks (e.g. in a case of an array argument, check for the proper shape and size) automatically. Use check() to disable checks generated by F2PY.
depend([<names>])

This declares that the corresponding argument depends on the values of variables in the list <names>. For example, <init_expr> may use the values of other arguments. Using information given by depend(..) attributes, F2PY ensures that arguments are initialized in a proper order. If depend(..) is not used then F2PY determines dependence relations automatically. Use depend() to disable dependence relations generated by F2PY.

When you edit dependence relations that wer initially generated by F2PY, be careful not to break the dependence relations of other relevant variables. Another thing to watch out is cyclic dependencies. Luckily F2PY is able to detect cyclic dependencies when constructing wrappers and complains if any is found.

allocatable
The corresponding variable is Fortran 90 allocatable array defined as Fortran 90 module data.
external

The corresponding argument is a function provided by user. The signature of this so-called call-back function can be defined

  • in __user__ module block,
  • or by demonstrative (or real, if the signature file is a real Fortran code) call in the <other statements> block.

For example, F2PY generates from

external cb_sub, cb_fun
integer n
real a(n),r
call cb_sub(a,n)
r = cb_fun(4)

the following call-back signatures:

subroutine cb_sub(a,n)
    real dimension(n) :: a
    integer optional,check(len(a)>=n),depend(a) :: n=len(a)
end subroutine cb_sub
function cb_fun(e_4_e) result (r)
    integer :: e_4_e
    real :: r
end function cb_fun

The corresponding user-provided Python function are then:

def cb_sub(a,[n]):
    ...
    return
def cb_fun(e_4_e):
    ...
    return r
parameter
The corresponding variable (but not argument!) is a parameter and it must have a fixed value. F2PY replaces all parameter occurrence by their corresponding values.