|Author:||Pearu Peterson <email@example.com>|
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.
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,
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.
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>
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> ]
- <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.
The <argument/variable attribute statement> is <argument/variable type declaration> without <typespec>.
The definition of the <use statement> part isuse <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 iscommon / <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>.
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:
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.
The following attributes are used by F2PY:
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.
This specifies the "intention" of the corresponding argument. <intentspec> is a comma separated list of the following keys:
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.
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.
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.
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
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.
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.
Ensure that the original contents of intent(in) argument is preserved. Typically used in connection with intent(in,out).
The original contents of the intent(in) argument may be altered by the Fortran/C function.
Replace the return name with <new name> in the __doc__ string of a wrapper function.
The following rules apply:
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.
The corresponding argument is a function provided by user. The signature of this so-called call-back function can be defined
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