.. -*- rest -*- ======================= G3 F2PY library package ======================= :Author: Pearu Peterson :Created: July 2007 .. contents:: Table of Contents Overview ======== The G3 F2PY library package contains tools to parse Fortran codes and construct Python C/API extension modules for wrapping Fortran programs. These tools are also suitable for implementing Fortran program translators or wrappers to any other programming language. In fact, wrapping Fortran programs to Python would be just one example of using these tools. Wrapping Fortran with Python - UI ================================= There are two user interfaces to wrap Fortran programs with Python: - the command line program `f2py` that scans Fortran files given as command line arguments and builds extension modules that can be used to call Fortran programs from Python. The `f2py` program has four different ways of building extension modules as specified with the following command line flags: - `--g3-numpy` --- create extension modules with NumPy array support using the new tools from `the 3rd generation of F2PY`__. This is a work-in-progress feature. - `--2d-numpy` --- create extension modules with NumPy array support using `the stable version of F2PY`__. This is default. - `--2d-numeric` --- create extension modules with Numeric array support using the old version of f2py2e. The f2py2e package must be downloaded and installed separately from the `f2py2e homepage`__. - `--2d-numarray` --- create extension modules with Numarray array support using the old version of f2py2e. Example:: $ cat hello.f90 subroutine hello print*, "Hello!" end subroutine hello $ f2py --g3-numpy -m foo -c hello.f90 --fcompiler=gnu95 $ python >>> import foo >>> foo.hello() Hello! >>> See the output of `f2py` for more information. __ http://projects.scipy.org/scipy/numpy/wiki/G3F2PY/ __ http://www.scipy.org/F2py/ __ http://cens.ioc.ee/projects/f2py2e/ - the function `compile()` that scans its string input containing Fortran code and returns a list of imported extension modules that can be used to call Fortran programs from Python. Example:: $ python >>> from numpy.f2py.lib.api import compile >>> code = 'subroutine hello\n print*, "Hello!"\nend' >>> print code subroutine hello print*, "Hello!" end >>> foo, = compile(code, extra_args = ['--fcompiler=gnu95']) >>> foo.hello() Hello! >>> Wrapping Fortran with Python - how it works? ============================================ The two users interfaces discussed above are implemented by functions `main(sys_argv=None)` and `compile(source, jobname='untitled', extra_args=[], source_ext=None, modulenames=None)` in file `numpy/f2py/lib/main.py`. Both these functions call `build_extension(sys_argv, sources_only=False)` function that reads `sys_argv` list for files and options, constructs wrapper functions, creates a `numpy.distutils` style `setup.py` file, and finally runs it. `build_extension` options ------------------------- The following options are defined that can be used as command line arguments to `f2py` or in `extra_args` list argument of the `compiler` function: - `-m []` --- specify the name of a wrapper extension module. Default is `untitled` or `unspecified` (if `` part is not specified). - `--target-dir=` --- specify the directory path where extension modules are saved. Default is the current working directory. - `--build-dir=` --- specify the directory path where temporary files are created during the build process. Default is `_g2f2py` or temporary directory (when `` part is not specified)). - `-I` --- specifies include directory path that is used for finding Fortran 90 modules and when compiling sources. - `-D[=]`, `-U` --- defines or undefines CPP macro used in compiling sources. See below for F2PY specific macros. - `-L` --- specifies library directory path that is used in linking extension modules. - `-l` --- specifies library that is used in linking extension modules. - `.(o|a|so|dll|dylib|sl)` --- specifies extra object files used in linking extension modules. - ``.pyf --- specifies signature file used for scanning Fortran program signatures. - `.(f|f90|F90|F)` --- specifies Fortran source files used for scanning Fortran program signatures (in case no signature files are specified). These sources will be compiled and linked with extension modules. - `.(c|cpp|C|CPP|c++)` --- specifies C/C++ source files that will be compiled and linked with extension modules. Note that if no signature file is specified then also C/C++ files are scanned for Fortran program signatures. The Fortran program signatures are assumed to be inside the C comment `/* f2py ... */` block. - `--fcompiler=` --- specifies Fortran compiler to be used in compiling/linking the sources. See also `--help-fcompiler` option. - `--help-fcompiler` --- list Fortran compilers that are found in the system, that are available or unavailable for the current system. Then return without processing any other options. - `--compiler=` --- specifies C/C++ compiler to be used in compiling/linking the sources. See also `--help-compiler` option. - `--help-compiler` --- list C/C++ compilers that are available for the current system. Then return without processing any other options. Additional `f2py` command line options -------------------------------------- Command line tool `f2py` uses the following additional command line options: - `-c` --- specifies that F2PY should build extension modules. Without this option F2PY just scans source files for signatures and constructs extension module sources --- useful when one needs to build extension modules manually (in Makefile, for instance). See also `-h` option below. - `-h ` --- specifies the signature file name where the results of scanning sources will be saved. With this option F2PY just scans the sources but does not construct extension modules sources --- useful when one needs to edit the signatures of Fortran programs. If `` is `stdout` or `stderr` is specified then the scanned signatures will be dumped to `stdout` or `stderr` streams, respectively. - `--help-link [ ]...` --- list system resources as defined in `numpy/distutils/system_info.py` and return. - `--parse` --- specifies that F2PY should just parce the source files and dump the results to `stdout` stream. Useful for debugging F2PY parser. F2PY specific CPP macros ------------------------ F2PY may use the following CPP macros: - `-DF2PY_DEBUG_PYOBJ_TOFROM` --- show debug messages from `pyobj_(to|from)_` functions. - `-DPREPEND_FORTRAN`, `-DNO_APPEND_FORTRAN`, `-DUPPERCASE_FORTRAN`, `-DUNDERSCORE_G77` --- specify how Fortran compiler mangles Fortran symbol names that need to be accessed from C extension modules. Usually one never needs to specify these macros as supported Fortran compilers should always mangle the names to be lower-cased and with exactly one underscore after the name. Options for `compile` --------------------- The `compile` function has the following options: - `source` --- a string containing Fortran code. To specify the Fortran format of the `source` use the following header lines in the `source` string: - `C -*- f77 -*-` --- the string contains Fortran 77 code - `! -*- f90 -*-` --- the string contains Fortran 90 code in free format. - `! -*- fix -*-` --- the string contains Fortran 90 code in fixed format. - `! -*- pyf -*-` --- the string contains Fortran signatures. - `jobname='untitled'` --- a string specifing the name of an extension module - `extra_args=[]` --- a list of `build_extension(..)` arguments, see above. - `source_ext=None` --- a string specifying the extension (`.f` or `.f90`) of the file where `source` will be saved for further processing. Default extension will be determined from the `source` string. - `modulenames=None` --- a list of module names that the build process should create. `compile` function will try to import these modules and return the corresponding module objects as a list.