diff options
| author | Pauli Virtanen <pav@iki.fi> | 2014-01-02 22:41:27 +0200 |
|---|---|---|
| committer | Pauli Virtanen <pav@iki.fi> | 2014-01-02 22:41:27 +0200 |
| commit | 337366c6d512b47e6a702d18a3f3f6240c3fda4a (patch) | |
| tree | cf9affed706e98fe8731032c37895ab6c3e39737 | |
| parent | 5bcfbe92fd7fa5db67ba0fc06a1e63a806c33127 (diff) | |
| download | numpy-337366c6d512b47e6a702d18a3f3f6240c3fda4a.tar.gz | |
DOC: split up f2py user guide + markup fixes
| -rw-r--r-- | doc/source/contents.rst | 1 | ||||
| -rw-r--r-- | doc/source/f2py/advanced.rst | 45 | ||||
| -rw-r--r-- | doc/source/f2py/distutils.rst | 108 | ||||
| -rw-r--r-- | doc/source/f2py/getting-started.rst | 261 | ||||
| -rw-r--r-- | doc/source/f2py/index.rst | 1732 | ||||
| -rw-r--r-- | doc/source/f2py/python-usage.rst | 419 | ||||
| -rw-r--r-- | doc/source/f2py/signature-file.rst | 651 | ||||
| -rw-r--r-- | doc/source/f2py/usage.rst | 233 |
8 files changed, 1726 insertions, 1724 deletions
diff --git a/doc/source/contents.rst b/doc/source/contents.rst index 04ee229b2..023ebb8a0 100644 --- a/doc/source/contents.rst +++ b/doc/source/contents.rst @@ -6,6 +6,7 @@ Numpy manual contents user/index reference/index + f2py/index dev/index release about diff --git a/doc/source/f2py/advanced.rst b/doc/source/f2py/advanced.rst new file mode 100644 index 000000000..7990a9ce4 --- /dev/null +++ b/doc/source/f2py/advanced.rst @@ -0,0 +1,45 @@ +====================== +Advanced F2PY usages +====================== + +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`` + +.. include:: spam.pyf + :literal: + +wraps the C library function ``system()``:: + + f2py -c spam.pyf + +In Python: + +.. include:: spam_session.dat + :literal: + +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 + +.. include:: var.pyf + :literal: + +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: + +.. include:: var_session.dat + :literal: diff --git a/doc/source/f2py/distutils.rst b/doc/source/f2py/distutils.rst new file mode 100644 index 000000000..30debf824 --- /dev/null +++ b/doc/source/f2py/distutils.rst @@ -0,0 +1,108 @@ +============================ +Using via``numpy_distutils`` +============================ + +``numpy_distutils`` is part of the SciPy_ project and aims to extend +standard Python ``distutils`` to deal with Fortran sources and F2PY +signature files, e.g. compile Fortran sources, call F2PY to construct +extension modules, etc. + +.. topic:: Example + + Consider the following `setup file`__: + + .. include:: setup_example.py + :literal: + + Running + + :: + + python setup_example.py build + + will build two extension modules ``scalar`` and ``fib2`` to the + build directory. + + __ setup_example.py + +``numpy_distutils`` extends ``distutils`` with the following features: + +* ``Extension`` class argument ``sources`` may contain Fortran source + files. In addition, the list ``sources`` may contain at most one + F2PY signature file, and then the name of an Extension module must + match with the ``<modulename>`` used in signature file. It is + assumed that an F2PY signature file contains exactly one ``python + module`` block. + + If ``sources`` does not contain a signature files, then F2PY is used + to scan Fortran source files for routine signatures to construct the + wrappers to Fortran codes. + + Additional options to F2PY process can be given using ``Extension`` + class argument ``f2py_options``. + +``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 + +``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. + +.. _SciPy: http://www.numpy.org/ diff --git a/doc/source/f2py/getting-started.rst b/doc/source/f2py/getting-started.rst new file mode 100644 index 000000000..20c10b378 --- /dev/null +++ b/doc/source/f2py/getting-started.rst @@ -0,0 +1,261 @@ +====================================== + 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 +ommited 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: + +.. include:: fib1.f + :literal: + +__ fib1.f + +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.] + +.. note:: + + * Note that F2PY found that the second argument ``n`` is the + dimension of the first array argument ``a``. Since by default all + arguments are input-only arguments, F2PY concludes that ``n`` can + be optional with the default value ``len(a)``. + + * One can use different values for optional ``n``:: + + >>> a1=Numeric.zeros(8,'d') + >>> fib1.fib(a1,6) + >>> print a1 + [ 0. 1. 1. 2. 3. 5. 0. 0.] + + but an exception is raised when it is incompatible with the input + array ``a``:: + + >>> fib1.fib(a,10) + fib:n=10 + Traceback (most recent call last): + File "<stdin>", line 1, in ? + fib.error: (len(a)>=n) failed for 1st keyword n + >>> + + This demonstrates one of the useful features in F2PY, that it, + F2PY implements basic compatibility checks between related + arguments in order to avoid any unexpected crashes. + + * When a Numeric array, that is Fortran contiguous and has a typecode + corresponding to presumed Fortran type, is used as an input array + argument, then its C pointer is directly passed to Fortran. + + Otherwise F2PY makes a contiguous copy (with a proper typecode) of + the input array and passes C pointer of the copy to Fortran + subroutine. As a result, any possible changes to the (copy of) + input array have no effect to the original argument, as + demonstrated below:: + + >>> a=Numeric.ones(8,'i') + >>> fib1.fib(a) + >>> print a + [1 1 1 1 1 1 1 1] + + Clearly, this is not an expected behaviour. The fact that the + above example worked with ``typecode='d'`` is considered + accidental. + + F2PY provides ``intent(inplace)`` attribute that would modify + the attributes of an input array so that any changes made by + Fortran routine will be effective also in input argument. For example, + if one specifies ``intent(inplace) a`` (see below, how), then + the example above would read: + + >>> a=Numeric.ones(8,'i') + >>> fib1.fib(a) + >>> print a + [ 0. 1. 1. 2. 3. 5. 8. 13.] + + However, the recommended way to get changes made by Fortran + subroutine back to python is to use ``intent(out)`` attribute. It + is more efficient and a cleaner solution. + + * The usage of ``fib1.fib`` in Python is very similar to using + ``FIB`` in Fortran. However, using *in situ* output arguments in + Python indicates a poor style as there is no safety mechanism + in Python with respect to wrong argument types. When using Fortran + or C, compilers naturally discover any type mismatches during + compile time but in Python the types must be checked in + runtime. So, using *in situ* output arguments in Python may cause + difficult to find bugs, not to mention that the codes will be less + readable when all required type checks are implemented. + + Though the demonstrated way of wrapping Fortran routines to Python + is very straightforward, it has several drawbacks (see the comments + above). These drawbacks are due to the fact that there is no way + that F2PY can determine what is the acctual intention of one or the + other argument, is it input or output argument, or both, or + something else. So, F2PY conservatively assumes that all arguments + are input arguments by default. + + However, there are ways (see below) how to "teach" F2PY about the + true intentions (among other things) of function arguments; and then + F2PY is able to generate more Pythonic (more explicit, easier to + use, and less error prone) wrappers to Fortran functions. + +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. + + .. include:: fib1.pyf + :literal: + +* 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: + + .. include:: fib2.pyf + :literal: + +* 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.] + +.. note:: + + * Clearly, the signature of ``fib2.fib`` now corresponds to the + intention of Fortran subroutine ``FIB`` more closely: given the + number ``n``, ``fib2.fib`` returns the first ``n`` Fibonacci numbers + as a Numeric array. Also, the new Python signature ``fib2.fib`` + rules out any surprises that we experienced with ``fib1.fib``. + + * Note that by default using single ``intent(out)`` also implies + ``intent(hide)``. Argument that has ``intent(hide)`` attribute + specified, will not be listed in the argument list of a wrapper + function. + +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``: + +.. include:: fib3.f + :literal: + +__ 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.] diff --git a/doc/source/f2py/index.rst b/doc/source/f2py/index.rst index 65c0d00d8..b4dd73d32 100644 --- a/doc/source/f2py/index.rst +++ b/doc/source/f2py/index.rst @@ -28,1732 +28,16 @@ Python C/API extension modules that make it possible from Python. See F2PY_ web site for more information and installation instructions. -====================================== - Three ways to wrap - getting started -====================================== +.. toctree:: + :maxdepth: 2 -Wrapping Fortran or C functions to Python using F2PY consists of the -following steps: + getting-started + signature-file + python-usage + usage + distutils + advanced -* 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 -ommited 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: - -.. include:: fib1.f - :literal: - -__ fib1.f - -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.] - -.. topic:: Comments - - * Note that F2PY found that the second argument ``n`` is the - dimension of the first array argument ``a``. Since by default all - arguments are input-only arguments, F2PY concludes that ``n`` can - be optional with the default value ``len(a)``. - - * One can use different values for optional ``n``:: - - >>> a1=Numeric.zeros(8,'d') - >>> fib1.fib(a1,6) - >>> print a1 - [ 0. 1. 1. 2. 3. 5. 0. 0.] - - but an exception is raised when it is incompatible with the input - array ``a``:: - - >>> fib1.fib(a,10) - fib:n=10 - Traceback (most recent call last): - File "<stdin>", line 1, in ? - fib.error: (len(a)>=n) failed for 1st keyword n - >>> - - This demonstrates one of the useful features in F2PY, that it, - F2PY implements basic compatibility checks between related - arguments in order to avoid any unexpected crashes. - - * When a Numeric array, that is Fortran contiguous and has a typecode - corresponding to presumed Fortran type, is used as an input array - argument, then its C pointer is directly passed to Fortran. - - Otherwise F2PY makes a contiguous copy (with a proper typecode) of - the input array and passes C pointer of the copy to Fortran - subroutine. As a result, any possible changes to the (copy of) - input array have no effect to the original argument, as - demonstrated below:: - - >>> a=Numeric.ones(8,'i') - >>> fib1.fib(a) - >>> print a - [1 1 1 1 1 1 1 1] - - Clearly, this is not an expected behaviour. The fact that the - above example worked with ``typecode='d'`` is considered - accidental. - - F2PY provides ``intent(inplace)`` attribute that would modify - the attributes of an input array so that any changes made by - Fortran routine will be effective also in input argument. For example, - if one specifies ``intent(inplace) a`` (see below, how), then - the example above would read: - - >>> a=Numeric.ones(8,'i') - >>> fib1.fib(a) - >>> print a - [ 0. 1. 1. 2. 3. 5. 8. 13.] - - However, the recommended way to get changes made by Fortran - subroutine back to python is to use ``intent(out)`` attribute. It - is more efficient and a cleaner solution. - - * The usage of ``fib1.fib`` in Python is very similar to using - ``FIB`` in Fortran. However, using *in situ* output arguments in - Python indicates a poor style as there is no safety mechanism - in Python with respect to wrong argument types. When using Fortran - or C, compilers naturally discover any type mismatches during - compile time but in Python the types must be checked in - runtime. So, using *in situ* output arguments in Python may cause - difficult to find bugs, not to mention that the codes will be less - readable when all required type checks are implemented. - - Though the demonstrated way of wrapping Fortran routines to Python - is very straightforward, it has several drawbacks (see the comments - above). These drawbacks are due to the fact that there is no way - that F2PY can determine what is the acctual intention of one or the - other argument, is it input or output argument, or both, or - something else. So, F2PY conservatively assumes that all arguments - are input arguments by default. - - However, there are ways (see below) how to "teach" F2PY about the - true intentions (among other things) of function arguments; and then - F2PY is able to generate more Pythonic (more explicit, easier to - use, and less error prone) wrappers to Fortran functions. - -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. - - .. include:: fib1.pyf - :literal: - -* 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: - - .. include:: fib2.pyf - :literal: - -* 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.] - -.. topic:: Comments - - * Clearly, the signature of ``fib2.fib`` now corresponds to the - intention of Fortran subroutine ``FIB`` more closely: given the - number ``n``, ``fib2.fib`` returns the first ``n`` Fibonacci numbers - as a Numeric array. Also, the new Python signature ``fib2.fib`` - rules out any surprises that we experienced with ``fib1.fib``. - - * Note that by default using single ``intent(out)`` also implies - ``intent(hide)``. Argument that has ``intent(hide)`` attribute - specified, will not be listed in the argument list of a wrapper - function. - -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``: - -.. include:: fib3.f - :literal: - -__ 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.] - - -================== - Signature file -================== - -The syntax specification for 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 that help designing Fortran to Python interface, make it -more "Pythonic". - -Signature files may contain arbitrary Fortran code (so that Fortran -codes can be considered as signature files). F2PY silently ignores -Fortran constructs that are irrelevant for creating the interface. -However, this includes also syntax errors. So, be careful not making -ones;-). - -In general, the contents of signature files is case-sensitive. When -scanning Fortran codes and writing a signature file, F2PY lowers all -cases automatically except in multi-line blocks or when ``--no-lower`` -option is used. - -The syntax of signature files is overvied below. - -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. - - -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>] ] - -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`__. - -+ ``<intlen>`` may be negative integer for ``integer`` type - specifications. In such cases ``integer*<negintlen>`` represents - unsigned C integers. - -__ `C expressions`_ - -If an argument has no ``<argument type declaration>``, its type is -determined by applying ``implicit`` rules to its name. - - -Statements ----------- - -Attribute statements: - The ``<argument/variable attribute statement>`` is - ``<argument/variable type declaration>`` without ``<typespec>``. - In addition, in an attribute statement one cannot use other - attributes, also ``<entitydecl>`` can be only a list of names. - -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 and ``external`` arguments (call-back functions), see - `Call-back arguments`_. - -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 latter 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 to 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 - (`more details`__?); - - __ external_ - - + ``include`` statements - - :: - - include '<filename>' - include "<filename>" - - If a file ``<filename>`` does not exist, the ``include`` - statement is ignored. Otherwise, the file ``<filename>`` is - included to a signature file. ``include`` statements can be used - in any part of a signature file, also outside the Fortran/C - routine signature blocks. - - + ``implicit`` statements - - :: - - implicit none - implicit <list of implicit maps> - - where - - :: - - <implicit map> := <typespec> ( <list of letters or range of letters> ) - - Implicit rules are used to deterimine the type specification of - a variable (from the first-letter of its name) if the variable - is not defined using ``<variable type declaration>``. Default - implicit rule is given by - - :: - - implicit real (a-h,o-z,$_), integer (i-m) - - + ``entry`` statements - - :: - - entry <entry name> [([<arguments>])] - - F2PY generates wrappers to all entry names using the signature - of the routine block. - - Tip: ``entry`` statement can be used to describe the signature - of an arbitrary routine allowing F2PY to generate a number of - wrappers from only one routine block signature. There are few - restrictions while doing this: ``fortranname`` cannot be used, - ``callstatement`` and ``callprotoargument`` can be used only if - they are valid for all entry routines, etc. - - 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|multi-line block>`` - Replace F2PY generated call statement to Fortran/C function with - ``<C-expr|multi-line block>``. The wrapped Fortran/C function - is available as ``(*f2py_func)``. To raise an exception, set - ``f2py_success = 0`` in ``<C-expr|multi-line block>``. - - + ``callprotoargument <C-typespecs>`` - When ``callstatement`` statement is used then F2PY may 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. - - If ``fortranname`` statement is used without - ``<acctual Fortran/C routine name>`` then a dummy wrapper is - generated. - - + ``usercode <multi-line block>`` - When used inside ``python module`` block, then given C code - will be inserted to generated C/API source just before - wrapper function definitions. Here you can define arbitrary - C functions to be used in initialization of optional arguments, - for example. If ``usercode`` is used twise inside ``python - module`` block then the second multi-line block is inserted - after the definition of external routines. - - When used inside ``<routine singature>``, then given C code will - be inserted to the corresponding wrapper function just after - declaring variables but before any C statements. So, ``usercode`` - follow-up can contain both declarations and C statements. - - When used inside the first ``interface`` block, then given C - code will be inserted at the end of the initialization - function of the extension module. Here you can modify extension - modules dictionary. For example, for defining additional - variables etc. - - + ``pymethoddef <multi-line block>`` - Multiline block will be inserted to the definition of - module methods ``PyMethodDef``-array. It must be a - comma-separated list of C arrays (see `Extending and Embedding`__ - Python documentation for details). - ``pymethoddef`` statement can be used only inside - ``python module`` block. - - __ http://www.python.org/doc/current/ext/ext.html - -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. - - For an optional array argument, all its dimensions must be bounded. - -``required`` - The corresponding argument is considered as a required one. This is - default. You need to specify ``required`` only if there is a need to - disable automatic ``optional`` setting when ``<init_expr>`` is used. - - If Python ``None`` object is used as an required argument, the - argument is treated as optional. That is, in the case of array - argument, the memory is allocated. And if ``<init_expr>`` is given, - the corresponding initialization is carried out. - -``dimension(<arrayspec>)`` - The corresponding variable is considered as an array with given - dimensions in ``<arrayspec>``. - -``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. See also ``intent(inplace)`` attribute. - - + ``inplace`` - The argument is considered as an input/output or *in situ* - output argument. ``intent(inplace)`` arguments must be - Numeric arrays with proper size. If the type of an array is - not "proper" or the array is non-contiguous then the array - will be changed in-place to fix the type and make it contiguous. - - Using ``intent(inplace)`` is generally not recommended either. - For example, when slices have been taken from an - ``intent(inplace)`` argument then after in-place changes, - slices data pointers may point to unallocated memory area. - - + ``out`` - The argument is considered as an return variable. It is appended - to the ``<returned variables>`` list. Using ``intent(out)`` - sets ``intent(hide)`` automatically, unless also - ``intent(in)`` or ``intent(inout)`` were used. - - By default, returned multidimensional arrays are - Fortran-contiguous. If ``intent(c)`` is used, then returned - multi-dimensional arrays are C-contiguous. - - + ``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 scalar or C array argument. In - the case of a scalar argument, 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 - argument, the wrapper function is assumed to treat - multi-dimensional arrays as C-contiguous arrays. - - There is no need to use ``intent(c)`` for one-dimensional - arrays, no matter if the wrapped function is either a Fortran or - a C function. This is because the concepts of Fortran- and - C-contiguousness overlap in one-dimensional cases. - - If ``intent(c)`` is used as an statement but without entity - declaration list, then F2PY adds ``intent(c)`` attibute to all - arguments. - - Also, when wrapping C functions, one must use ``intent(c)`` - attribute for ``<routine name>`` in order to disable Fortran - specific ``F_FUNC(..,..)`` macros. - - + ``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 in connection with - ``intent(hide)`` or ``optional`` attributes. - - + ``copy`` - Ensure that the original contents of ``intent(in)`` argument is - preserved. Typically used in connection with ``intent(in,out)`` - attribute. F2PY creates an optional argument - ``overwrite_<argument name>`` with the default value ``0``. - - + ``overwrite`` - The original contents of the ``intent(in)`` argument may be - altered by the Fortran/C function. F2PY creates an optional - argument ``overwrite_<argument name>`` with the default value - ``1``. - - + ``out=<new name>`` - Replace the return name with ``<new name>`` in the ``__doc__`` - string of a wrapper function. - - + ``callback`` - Construct an external function suitable for calling Python function - from Fortran. ``intent(callback)`` must be specified before the - corresponding ``external`` statement. If 'argument' is not in - argument list then it will be added to Python wrapper but only - initializing external function. - - Use ``intent(callback)`` in situations where a Fortran/C code - assumes that a user implements a function with given prototype - and links it to an executable. Don't use ``intent(callback)`` - if function appears in the argument list of a Fortran routine. - - With ``intent(hide)`` or ``optional`` attributes specified and - using a wrapper function without specifying the callback argument - in argument list then call-back function is looked in the - namespace of F2PY generated extension module where it can be - set as a module attribute by a user. - - + ``aux`` - Define auxiliary C variable in F2PY generated wrapper function. - Useful to save parameter values so that they can be accessed - in initialization expression of other variables. Note that - ``intent(aux)`` silently implies ``intent(c)``. - - 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. - + ``intent(inout,inplace)`` is ``intent(inplace)``. - + ``intent(in,inplace)`` is ``intent(inplace)``. - + ``intent(hide)`` disables ``optional`` and ``required``. - -``check([<C-booleanexpr>])`` - Perform consistency check of arguments by evaluating - ``<C-booleanexpr>``; if ``<C-booleanexpr>`` 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(..)`` attribute is not - used then F2PY determines dependence relations automatically. Use - ``depend()`` to disable dependence relations generated by F2PY. - - When you edit dependence relations that were initially generated by - F2PY, be careful not to break the dependence relations of other - relevant variables. Another thing to watch out is cyclic - dependencies. F2PY is able to detect cyclic dependencies - when constructing wrappers and it complains if any are found. - -``allocatable`` - The corresponding variable is Fortran 90 allocatable array defined - as Fortran 90 module data. - -.. _external: - -``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 - - See also ``intent(callback)`` attribute. - -``parameter`` - The corresponding variable is a parameter and it must have a fixed - value. F2PY replaces all parameter occurrences by their - corresponding values. - -Extensions -============ - -F2PY directives ------------------ - -The so-called F2PY directives allow using F2PY signature file -constructs also in Fortran 77/90 source codes. With this feature you -can skip (almost) completely intermediate signature file generations -and apply F2PY directly to Fortran source codes. - -F2PY directive has the following form:: - - <comment char>f2py ... - -where allowed comment characters for fixed and free format Fortran -codes are ``cC*!#`` and ``!``, respectively. Everything that follows -``<comment char>f2py`` is ignored by a compiler but read by F2PY as a -normal Fortran (non-comment) line: - - When F2PY finds a line with F2PY directive, the directive is first - replaced by 5 spaces and then the line is reread. - -For fixed format Fortran codes, ``<comment char>`` must be at the -first column of a file, of course. For free format Fortran codes, -F2PY directives can appear anywhere in a file. - -C expressions --------------- - -C expressions are used in the following parts of signature files: - -* ``<init_expr>`` of variable initialization; -* ``<C-booleanexpr>`` of the ``check`` attribute; -* ``<arrayspec> of the ``dimension`` attribute; -* ``callstatement`` statement, here also a C multi-line block can be used. - -A C expression may contain: - -* standard C constructs; -* functions from ``math.h`` and ``Python.h``; -* variables from the argument list, presumably initialized before - according to given dependence relations; -* the following CPP macros: - - ``rank(<name>)`` - Returns the rank of an array ``<name>``. - ``shape(<name>,<n>)`` - Returns the ``<n>``-th dimension of an array ``<name>``. - ``len(<name>)`` - Returns the lenght of an array ``<name>``. - ``size(<name>)`` - Returns the size of an array ``<name>``. - ``slen(<name>)`` - Returns the length of a string ``<name>``. - -For initializing an array ``<array name>``, F2PY generates a loop over -all indices and dimensions that executes the following -pseudo-statement:: - - <array name>(_i[0],_i[1],...) = <init_expr>; - -where ``_i[<i>]`` refers to the ``<i>``-th index value and that runs -from ``0`` to ``shape(<array name>,<i>)-1``. - -For example, a function ``myrange(n)`` generated from the following -signature - -:: - - 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 - -is equivalent to ``Numeric.arange(n,typecode='d')``. - -.. topic:: Warning! - - F2PY may lower cases also in C expressions when scanning Fortran codes - (see ``--[no]-lower`` option). - -Multi-line blocks ------------------- - -A multi-line block starts with ``'''`` (triple single-quotes) and ends -with ``'''`` in some *strictly* subsequent line. Multi-line blocks can -be used only within .pyf files. The contents of a multi-line block can -be arbitrary (except that it cannot contain ``'''``) and no -transformations (e.g. lowering cases) are applied to it. - -Currently, multi-line blocks can be used in the following constructs: - -+ as a C expression of the ``callstatement`` statement; - -+ as a C type specification of the ``callprotoargument`` statement; - -+ as a C code block of the ``usercode`` statement; - -+ as a list of C arrays of the ``pymethoddef`` statement; - -+ as documentation string. - -================================== -Using F2PY bindings in Python -================================== - -All wrappers (to Fortran/C routines or to common blocks or to Fortran -90 module data) generated by F2PY are exposed to Python as ``fortran`` -type objects. Routine wrappers are callable ``fortran`` type objects -while wrappers to Fortran data have attributes referring to data -objects. - -All ``fortran`` type object have attribute ``_cpointer`` that contains -CObject referring to the C pointer of the corresponding Fortran/C -function or variable in C level. Such CObjects can be used as an -callback argument of F2PY generated functions to bypass Python C/API -layer of calling Python functions from Fortran or C when the -computational part of such functions is implemented in C or Fortran -and wrapped with F2PY (or any other tool capable of providing CObject -of a function). - -.. topic:: Example - - Consider a `Fortran 77 file`__ ``ftype.f``: - - .. include:: ftype.f - :literal: - - and build a wrapper using:: - - f2py -c ftype.f -m ftype - - __ ftype.f - - In Python: - - .. include:: ftype_session.dat - :literal: - - -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. - -.. topic:: Example - - Consider the following `Fortran 77 code`__: - - .. include:: scalar.f - :literal: - - and wrap it using ``f2py -c -m scalar scalar.f``. - - __ scalar.f - - In Python: - - .. include:: scalar_session.dat - :literal: - - -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. - -.. topic:: Example - - Consider the following `Fortran 77 code`__: - - .. include:: string.f - :literal: - - and wrap it using ``f2py -c -m mystring string.f``. - - __ string.f - - Python session: - - .. include:: string_session.dat - :literal: - - -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. - -.. topic:: Example - - Consider `Fortran 77 code`__: - - .. include:: array.f - :literal: - - and wrap it using ``f2py -c -m arr array.f -DF2PY_REPORT_ON_ARRAY_COPY=1``. - - __ array.f - - In Python: - - .. include:: array_session.dat - :literal: - -Call-back arguments -==================== - -F2PY supports calling Python functions from Fortran or C codes. - - -.. topic:: Example - - Consider the following `Fortran 77 code`__ - - .. include:: callback.f - :literal: - - and wrap it using ``f2py -c -m callback callback.f``. - - __ callback.f - - In Python: - - .. include:: callback_session.dat - :literal: - -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. - -.. topic:: Example - - We use the same `Fortran 77 code`__ as in previous example but now - we'll pretend that F2PY was not able to guess the signatures of - call-back arguments correctly. First, we create an initial signature - file ``callback2.pyf`` using F2PY:: - - f2py -m callback2 -h callback2.pyf callback.f - - Then modify it as follows - - .. include:: callback2.pyf - :literal: - - Finally, build the extension module using:: - - f2py -c callback2.pyf callback.f - - An example Python session would be identical to the previous example - except that argument names would differ. - - __ 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. - -.. topic:: Example - - Consider the following `Fortran 77 subroutine`__ that takes an array - and applies a function ``func`` to its elements. - - .. include:: calculate.f - :literal: - - __ calculate.f - - It is expected that function ``func`` has been defined - externally. In order to use a Python function as ``func``, it must - have an attribute ``intent(callback)`` (it must be specified before - the ``external`` statement). - - Finally, build an extension module using:: - - f2py -c -m foo calculate.f - - In Python: - - .. include:: calculate_session.dat - :literal: - -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. - -.. topic:: Example - - Consider the following `Fortran 77 subroutine`__. - - .. include:: extcallback.f - :literal: - - __ extcallback.f - - and wrap it using ``f2py -c -m pfromf extcallback.f``. - - In Python: - - .. include:: extcallback_session.dat - :literal: - -Resolving arguments to call-back functions ------------------------------------------- - -F2PY generated interface is very flexible with respect to call-back -arguments. For each call-back argument an additional optional -argument ``<name>_extra_args`` is introduced by F2PY. This argument -can be used to pass extra arguments to user provided call-back -arguments. - -If a F2PY generated wrapper function expects the following call-back -argument:: - - def fun(a_1,...,a_n): - ... - return x_1,...,x_k - -but the following Python function - -:: - - def gun(b_1,...,b_m): - ... - return y_1,...,y_l - -is provided by an user, and in addition, - -:: - - fun_extra_args = (e_1,...,e_p) - -is used, then the following rules are applied when a Fortran or C -function calls the call-back argument ``gun``: - -* If ``p==0`` then ``gun(a_1,...,a_q)`` is called, here - ``q=min(m,n)``. -* If ``n+p<=m`` then ``gun(a_1,...,a_n,e_1,...,e_p)`` is called. -* If ``p<=m<n+p`` then ``gun(a_1,...,a_q,e_1,...,e_p)`` is called, here - ``q=m-p``. -* If ``p>m`` then ``gun(e_1,...,e_m)`` is called. -* If ``n+p`` is less than the number of required arguments to ``gun`` - then an exception is raised. - -The function ``gun`` may return any number of objects as a tuple. Then -following rules are applied: - -* If ``k<l``, then ``y_{k+1},...,y_l`` are ignored. -* If ``k>l``, then only ``x_1,...,x_l`` are set. - - - -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. - -.. topic:: Example - - Consider the following `Fortran 77 code`__ - - .. include:: common.f - :literal: - - and wrap it using ``f2py -c -m common common.f``. - - __ common.f - - In Python: - - .. include:: common_session.dat - :literal: - -Fortran 90 module data -======================= - -The F2PY interface to Fortran 90 module data is similar to Fortran 77 -common blocks. - -.. topic:: Example - - Consider the following `Fortran 90 code`__ - - .. include:: moddata.f90 - :literal: - - and wrap it using ``f2py -c -m moddata moddata.f90``. - - __ moddata.f90 - - In Python: - - .. include:: moddata_session.dat - :literal: - -Allocatable arrays -------------------- - -F2PY has basic support for Fortran 90 module allocatable arrays. - -.. topic:: Example - - Consider the following `Fortran 90 code`__ - - .. include:: allocarr.f90 - :literal: - - and wrap it using ``f2py -c -m allocarr allocarr.f90``. - - __ allocarr.f90 - - In Python: - - .. include:: allocarr_session.dat - :literal: - - -=========== -Using F2PY -=========== - -F2PY can be used either as a command line tool ``f2py`` or as a Python -module ``f2py2e``. - -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. -``--[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.mktemp()``. -``--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. - -Python module ``f2py2e`` -========================= - -.. topic:: Warning - - The current Python interface to ``f2py2e`` module is not mature and - may change in future depending on users needs. - -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 - - .. include:: run_main_session.dat - :literal: - - 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, - - .. include:: compile_session.dat - :literal: - -========================== -Using ``numpy_distutils`` -========================== - -``numpy_distutils`` is part of the SciPy_ project and aims to extend -standard Python ``distutils`` to deal with Fortran sources and F2PY -signature files, e.g. compile Fortran sources, call F2PY to construct -extension modules, etc. - -.. topic:: Example - - Consider the following `setup file`__: - - .. include:: setup_example.py - :literal: - - Running - - :: - - python setup_example.py build - - will build two extension modules ``scalar`` and ``fib2`` to the - build directory. - - __ setup_example.py - -``numpy_distutils`` extends ``distutils`` with the following features: - -* ``Extension`` class argument ``sources`` may contain Fortran source - files. In addition, the list ``sources`` may contain at most one - F2PY signature file, and then the name of an Extension module must - match with the ``<modulename>`` used in signature file. It is - assumed that an F2PY signature file contains exactly one ``python - module`` block. - - If ``sources`` does not contain a signature files, then F2PY is used - to scan Fortran source files for routine signatures to construct the - wrappers to Fortran codes. - - Additional options to F2PY process can be given using ``Extension`` - class argument ``f2py_options``. - -``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 - -``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. - -====================== - Extended F2PY usages -====================== - -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`` - -.. include:: spam.pyf - :literal: - -wraps the C library function ``system()``:: - - f2py -c spam.pyf - -In Python: - -.. include:: spam_session.dat - :literal: - -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 - -.. include:: var.pyf - :literal: - -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: - -.. include:: var_session.dat - :literal: - -.. References - ========== .. _F2PY: http://cens.ioc.ee/projects/f2py2e/ .. _Python: http://www.python.org/ .. _NumPy: http://www.numpy.org/ diff --git a/doc/source/f2py/python-usage.rst b/doc/source/f2py/python-usage.rst new file mode 100644 index 000000000..24ec3f15d --- /dev/null +++ b/doc/source/f2py/python-usage.rst @@ -0,0 +1,419 @@ +================================== +Using F2PY bindings in Python +================================== + +All wrappers (to Fortran/C routines or to common blocks or to Fortran +90 module data) generated by F2PY are exposed to Python as ``fortran`` +type objects. Routine wrappers are callable ``fortran`` type objects +while wrappers to Fortran data have attributes referring to data +objects. + +All ``fortran`` type object have attribute ``_cpointer`` that contains +CObject referring to the C pointer of the corresponding Fortran/C +function or variable in C level. Such CObjects can be used as an +callback argument of F2PY generated functions to bypass Python C/API +layer of calling Python functions from Fortran or C when the +computational part of such functions is implemented in C or Fortran +and wrapped with F2PY (or any other tool capable of providing CObject +of a function). + +.. example:: + + Consider a `Fortran 77 file`__ ``ftype.f``: + + .. include:: ftype.f + :literal: + + and build a wrapper using:: + + f2py -c ftype.f -m ftype + + __ ftype.f + + In Python: + + .. include:: ftype_session.dat + :literal: + + +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. + +.. example:: + + Consider the following `Fortran 77 code`__: + + .. include:: scalar.f + :literal: + + and wrap it using ``f2py -c -m scalar scalar.f``. + + __ scalar.f + + In Python: + + .. include:: scalar_session.dat + :literal: + + +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. + +.. example:: + + Consider the following `Fortran 77 code`__: + + .. include:: string.f + :literal: + + and wrap it using ``f2py -c -m mystring string.f``. + + __ string.f + + Python session: + + .. include:: string_session.dat + :literal: + + +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. + +.. example:: + + Consider `Fortran 77 code`__: + + .. include:: array.f + :literal: + + and wrap it using ``f2py -c -m arr array.f -DF2PY_REPORT_ON_ARRAY_COPY=1``. + + __ array.f + + In Python: + + .. include:: array_session.dat + :literal: + +.. _Call-back arguments: + +Call-back arguments +==================== + +F2PY supports calling Python functions from Fortran or C codes. + + +.. example:: + + Consider the following `Fortran 77 code`__ + + .. include:: callback.f + :literal: + + and wrap it using ``f2py -c -m callback callback.f``. + + __ callback.f + + In Python: + + .. include:: callback_session.dat + :literal: + +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. + +.. example:: + + We use the same `Fortran 77 code`__ as in previous example but now + we'll pretend that F2PY was not able to guess the signatures of + call-back arguments correctly. First, we create an initial signature + file ``callback2.pyf`` using F2PY:: + + f2py -m callback2 -h callback2.pyf callback.f + + Then modify it as follows + + .. include:: callback2.pyf + :literal: + + Finally, build the extension module using:: + + f2py -c callback2.pyf callback.f + + An example Python session would be identical to the previous example + except that argument names would differ. + + __ 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. + +.. example:: + + Consider the following `Fortran 77 subroutine`__ that takes an array + and applies a function ``func`` to its elements. + + .. include:: calculate.f + :literal: + + __ calculate.f + + It is expected that function ``func`` has been defined + externally. In order to use a Python function as ``func``, it must + have an attribute ``intent(callback)`` (it must be specified before + the ``external`` statement). + + Finally, build an extension module using:: + + f2py -c -m foo calculate.f + + In Python: + + .. include:: calculate_session.dat + :literal: + +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. + +.. example:: + + Consider the following `Fortran 77 subroutine`__. + + .. include:: extcallback.f + :literal: + + __ extcallback.f + + and wrap it using ``f2py -c -m pfromf extcallback.f``. + + In Python: + + .. include:: extcallback_session.dat + :literal: + +Resolving arguments to call-back functions +------------------------------------------ + +F2PY generated interface is very flexible with respect to call-back +arguments. For each call-back argument an additional optional +argument ``<name>_extra_args`` is introduced by F2PY. This argument +can be used to pass extra arguments to user provided call-back +arguments. + +If a F2PY generated wrapper function expects the following call-back +argument:: + + def fun(a_1,...,a_n): + ... + return x_1,...,x_k + +but the following Python function + +:: + + def gun(b_1,...,b_m): + ... + return y_1,...,y_l + +is provided by an user, and in addition, + +:: + + fun_extra_args = (e_1,...,e_p) + +is used, then the following rules are applied when a Fortran or C +function calls the call-back argument ``gun``: + +* If ``p==0`` then ``gun(a_1,...,a_q)`` is called, here + ``q=min(m,n)``. +* If ``n+p<=m`` then ``gun(a_1,...,a_n,e_1,...,e_p)`` is called. +* If ``p<=m<n+p`` then ``gun(a_1,...,a_q,e_1,...,e_p)`` is called, here + ``q=m-p``. +* If ``p>m`` then ``gun(e_1,...,e_m)`` is called. +* If ``n+p`` is less than the number of required arguments to ``gun`` + then an exception is raised. + +The function ``gun`` may return any number of objects as a tuple. Then +following rules are applied: + +* If ``k<l``, then ``y_{k+1},...,y_l`` are ignored. +* If ``k>l``, then only ``x_1,...,x_l`` are set. + + + +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. + +.. example:: + + Consider the following `Fortran 77 code`__ + + .. include:: common.f + :literal: + + and wrap it using ``f2py -c -m common common.f``. + + __ common.f + + In Python: + + .. include:: common_session.dat + :literal: + +Fortran 90 module data +======================= + +The F2PY interface to Fortran 90 module data is similar to Fortran 77 +common blocks. + +.. example:: + + Consider the following `Fortran 90 code`__ + + .. include:: moddata.f90 + :literal: + + and wrap it using ``f2py -c -m moddata moddata.f90``. + + __ moddata.f90 + + In Python: + + .. include:: moddata_session.dat + :literal: + +Allocatable arrays +------------------- + +F2PY has basic support for Fortran 90 module allocatable arrays. + +.. example:: + + Consider the following `Fortran 90 code`__ + + .. include:: allocarr.f90 + :literal: + + and wrap it using ``f2py -c -m allocarr allocarr.f90``. + + __ allocarr.f90 + + In Python: + + .. include:: allocarr_session.dat + :literal: diff --git a/doc/source/f2py/signature-file.rst b/doc/source/f2py/signature-file.rst new file mode 100644 index 000000000..f81ee9311 --- /dev/null +++ b/doc/source/f2py/signature-file.rst @@ -0,0 +1,651 @@ +================== + Signature file +================== + +The syntax specification for 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 that help designing Fortran to Python interface, make it +more "Pythonic". + +Signature files may contain arbitrary Fortran code (so that Fortran +codes can be considered as signature files). F2PY silently ignores +Fortran constructs that are irrelevant for creating the interface. +However, this includes also syntax errors. So, be careful not making +ones;-). + +In general, the contents of signature files is case-sensitive. When +scanning Fortran codes and writing a signature file, F2PY lowers all +cases automatically except in multi-line blocks or when ``--no-lower`` +option is used. + +The syntax of signature files is overvied below. + +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 :ref:`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. + + +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>] ] + +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`__. + ++ ``<intlen>`` may be negative integer for ``integer`` type + specifications. In such cases ``integer*<negintlen>`` represents + unsigned C integers. + +__ `C expressions`_ + +If an argument has no ``<argument type declaration>``, its type is +determined by applying ``implicit`` rules to its name. + + +Statements +---------- + +Attribute statements: + The ``<argument/variable attribute statement>`` is + ``<argument/variable type declaration>`` without ``<typespec>``. + In addition, in an attribute statement one cannot use other + attributes, also ``<entitydecl>`` can be only a list of names. + +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 and ``external`` arguments (call-back functions), see + :ref:`Call-back arguments`. + +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 latter 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 to 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 + (`more details`__?); + + __ external_ + + + ``include`` statements + :: + + include '<filename>' + include "<filename>" + + If a file ``<filename>`` does not exist, the ``include`` + statement is ignored. Otherwise, the file ``<filename>`` is + included to a signature file. ``include`` statements can be used + in any part of a signature file, also outside the Fortran/C + routine signature blocks. + + + ``implicit`` statements + :: + + implicit none + implicit <list of implicit maps> + + where + + :: + + <implicit map> := <typespec> ( <list of letters or range of letters> ) + + Implicit rules are used to deterimine the type specification of + a variable (from the first-letter of its name) if the variable + is not defined using ``<variable type declaration>``. Default + implicit rule is given by + + :: + + implicit real (a-h,o-z,$_), integer (i-m) + + + ``entry`` statements + :: + + entry <entry name> [([<arguments>])] + + F2PY generates wrappers to all entry names using the signature + of the routine block. + + Tip: ``entry`` statement can be used to describe the signature + of an arbitrary routine allowing F2PY to generate a number of + wrappers from only one routine block signature. There are few + restrictions while doing this: ``fortranname`` cannot be used, + ``callstatement`` and ``callprotoargument`` can be used only if + they are valid for all entry routines, etc. + + 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|multi-line block>`` + Replace F2PY generated call statement to Fortran/C function with + ``<C-expr|multi-line block>``. The wrapped Fortran/C function + is available as ``(*f2py_func)``. To raise an exception, set + ``f2py_success = 0`` in ``<C-expr|multi-line block>``. + + + ``callprotoargument <C-typespecs>`` + When ``callstatement`` statement is used then F2PY may 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. + + If ``fortranname`` statement is used without + ``<acctual Fortran/C routine name>`` then a dummy wrapper is + generated. + + + ``usercode <multi-line block>`` + When used inside ``python module`` block, then given C code + will be inserted to generated C/API source just before + wrapper function definitions. Here you can define arbitrary + C functions to be used in initialization of optional arguments, + for example. If ``usercode`` is used twise inside ``python + module`` block then the second multi-line block is inserted + after the definition of external routines. + + When used inside ``<routine singature>``, then given C code will + be inserted to the corresponding wrapper function just after + declaring variables but before any C statements. So, ``usercode`` + follow-up can contain both declarations and C statements. + + When used inside the first ``interface`` block, then given C + code will be inserted at the end of the initialization + function of the extension module. Here you can modify extension + modules dictionary. For example, for defining additional + variables etc. + + + ``pymethoddef <multi-line block>`` + Multiline block will be inserted to the definition of + module methods ``PyMethodDef``-array. It must be a + comma-separated list of C arrays (see `Extending and Embedding`__ + Python documentation for details). + ``pymethoddef`` statement can be used only inside + ``python module`` block. + + __ http://www.python.org/doc/current/ext/ext.html + +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. + + For an optional array argument, all its dimensions must be bounded. + +``required`` + The corresponding argument is considered as a required one. This is + default. You need to specify ``required`` only if there is a need to + disable automatic ``optional`` setting when ``<init_expr>`` is used. + + If Python ``None`` object is used as an required argument, the + argument is treated as optional. That is, in the case of array + argument, the memory is allocated. And if ``<init_expr>`` is given, + the corresponding initialization is carried out. + +``dimension(<arrayspec>)`` + The corresponding variable is considered as an array with given + dimensions in ``<arrayspec>``. + +``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. See also ``intent(inplace)`` attribute. + + + ``inplace`` + The argument is considered as an input/output or *in situ* + output argument. ``intent(inplace)`` arguments must be + Numeric arrays with proper size. If the type of an array is + not "proper" or the array is non-contiguous then the array + will be changed in-place to fix the type and make it contiguous. + + Using ``intent(inplace)`` is generally not recommended either. + For example, when slices have been taken from an + ``intent(inplace)`` argument then after in-place changes, + slices data pointers may point to unallocated memory area. + + + ``out`` + The argument is considered as an return variable. It is appended + to the ``<returned variables>`` list. Using ``intent(out)`` + sets ``intent(hide)`` automatically, unless also + ``intent(in)`` or ``intent(inout)`` were used. + + By default, returned multidimensional arrays are + Fortran-contiguous. If ``intent(c)`` is used, then returned + multi-dimensional arrays are C-contiguous. + + + ``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 scalar or C array argument. In + the case of a scalar argument, 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 + argument, the wrapper function is assumed to treat + multi-dimensional arrays as C-contiguous arrays. + + There is no need to use ``intent(c)`` for one-dimensional + arrays, no matter if the wrapped function is either a Fortran or + a C function. This is because the concepts of Fortran- and + C-contiguousness overlap in one-dimensional cases. + + If ``intent(c)`` is used as an statement but without entity + declaration list, then F2PY adds ``intent(c)`` attibute to all + arguments. + + Also, when wrapping C functions, one must use ``intent(c)`` + attribute for ``<routine name>`` in order to disable Fortran + specific ``F_FUNC(..,..)`` macros. + + + ``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 in connection with + ``intent(hide)`` or ``optional`` attributes. + + + ``copy`` + Ensure that the original contents of ``intent(in)`` argument is + preserved. Typically used in connection with ``intent(in,out)`` + attribute. F2PY creates an optional argument + ``overwrite_<argument name>`` with the default value ``0``. + + + ``overwrite`` + The original contents of the ``intent(in)`` argument may be + altered by the Fortran/C function. F2PY creates an optional + argument ``overwrite_<argument name>`` with the default value + ``1``. + + + ``out=<new name>`` + Replace the return name with ``<new name>`` in the ``__doc__`` + string of a wrapper function. + + + ``callback`` + Construct an external function suitable for calling Python function + from Fortran. ``intent(callback)`` must be specified before the + corresponding ``external`` statement. If 'argument' is not in + argument list then it will be added to Python wrapper but only + initializing external function. + + Use ``intent(callback)`` in situations where a Fortran/C code + assumes that a user implements a function with given prototype + and links it to an executable. Don't use ``intent(callback)`` + if function appears in the argument list of a Fortran routine. + + With ``intent(hide)`` or ``optional`` attributes specified and + using a wrapper function without specifying the callback argument + in argument list then call-back function is looked in the + namespace of F2PY generated extension module where it can be + set as a module attribute by a user. + + + ``aux`` + Define auxiliary C variable in F2PY generated wrapper function. + Useful to save parameter values so that they can be accessed + in initialization expression of other variables. Note that + ``intent(aux)`` silently implies ``intent(c)``. + + 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. + + ``intent(inout,inplace)`` is ``intent(inplace)``. + + ``intent(in,inplace)`` is ``intent(inplace)``. + + ``intent(hide)`` disables ``optional`` and ``required``. + +``check([<C-booleanexpr>])`` + Perform consistency check of arguments by evaluating + ``<C-booleanexpr>``; if ``<C-booleanexpr>`` 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(..)`` attribute is not + used then F2PY determines dependence relations automatically. Use + ``depend()`` to disable dependence relations generated by F2PY. + + When you edit dependence relations that were initially generated by + F2PY, be careful not to break the dependence relations of other + relevant variables. Another thing to watch out is cyclic + dependencies. F2PY is able to detect cyclic dependencies + when constructing wrappers and it complains if any are found. + +``allocatable`` + The corresponding variable is Fortran 90 allocatable array defined + as Fortran 90 module data. + +.. _external: + +``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 + + See also ``intent(callback)`` attribute. + +``parameter`` + The corresponding variable is a parameter and it must have a fixed + value. F2PY replaces all parameter occurrences by their + corresponding values. + +Extensions +============ + +F2PY directives +----------------- + +The so-called F2PY directives allow using F2PY signature file +constructs also in Fortran 77/90 source codes. With this feature you +can skip (almost) completely intermediate signature file generations +and apply F2PY directly to Fortran source codes. + +F2PY directive has the following form:: + + <comment char>f2py ... + +where allowed comment characters for fixed and free format Fortran +codes are ``cC*!#`` and ``!``, respectively. Everything that follows +``<comment char>f2py`` is ignored by a compiler but read by F2PY as a +normal Fortran (non-comment) line: + + When F2PY finds a line with F2PY directive, the directive is first + replaced by 5 spaces and then the line is reread. + +For fixed format Fortran codes, ``<comment char>`` must be at the +first column of a file, of course. For free format Fortran codes, +F2PY directives can appear anywhere in a file. + +C expressions +-------------- + +C expressions are used in the following parts of signature files: + +* ``<init_expr>`` of variable initialization; +* ``<C-booleanexpr>`` of the ``check`` attribute; +* ``<arrayspec> of the ``dimension`` attribute; +* ``callstatement`` statement, here also a C multi-line block can be used. + +A C expression may contain: + +* standard C constructs; +* functions from ``math.h`` and ``Python.h``; +* variables from the argument list, presumably initialized before + according to given dependence relations; +* the following CPP macros: + + ``rank(<name>)`` + Returns the rank of an array ``<name>``. + ``shape(<name>,<n>)`` + Returns the ``<n>``-th dimension of an array ``<name>``. + ``len(<name>)`` + Returns the lenght of an array ``<name>``. + ``size(<name>)`` + Returns the size of an array ``<name>``. + ``slen(<name>)`` + Returns the length of a string ``<name>``. + +For initializing an array ``<array name>``, F2PY generates a loop over +all indices and dimensions that executes the following +pseudo-statement:: + + <array name>(_i[0],_i[1],...) = <init_expr>; + +where ``_i[<i>]`` refers to the ``<i>``-th index value and that runs +from ``0`` to ``shape(<array name>,<i>)-1``. + +For example, a function ``myrange(n)`` generated from the following +signature + +:: + + 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 + +is equivalent to ``Numeric.arange(n,typecode='d')``. + +.. warning:: + + F2PY may lower cases also in C expressions when scanning Fortran codes + (see ``--[no]-lower`` option). + +Multi-line blocks +------------------ + +A multi-line block starts with ``'''`` (triple single-quotes) and ends +with ``'''`` in some *strictly* subsequent line. Multi-line blocks can +be used only within .pyf files. The contents of a multi-line block can +be arbitrary (except that it cannot contain ``'''``) and no +transformations (e.g. lowering cases) are applied to it. + +Currently, multi-line blocks can be used in the following constructs: + ++ as a C expression of the ``callstatement`` statement; + ++ as a C type specification of the ``callprotoargument`` statement; + ++ as a C code block of the ``usercode`` statement; + ++ as a list of C arrays of the ``pymethoddef`` statement; + ++ as documentation string. diff --git a/doc/source/f2py/usage.rst b/doc/source/f2py/usage.rst new file mode 100644 index 000000000..2011c662a --- /dev/null +++ b/doc/source/f2py/usage.rst @@ -0,0 +1,233 @@ +=========== +Using F2PY +=========== + +F2PY can be used either as a command line tool ``f2py`` or as a Python +module ``f2py2e``. + +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. +``--[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.mktemp()``. +``--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. + +Python module ``f2py2e`` +========================= + +.. warning:: + + The current Python interface to ``f2py2e`` module is not mature and + may change in future depending on users needs. + +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 + + .. include:: run_main_session.dat + :literal: + + 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, + + .. include:: compile_session.dat + :literal: |