===========
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 code snippets directly in signature files

   ``--[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.mkdtemp()``.
``--quiet``
  Run quietly.
``--verbose``
  Run with extra verbosity.
``-v``
  Print f2py version ID and exit.

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

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: