.. -*- rest -*-

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 F2PY: Fortran to Python interface generator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:Author: Pearu Peterson <[email protected]>
:License: NumPy License
:Web-site: http://cens.ioc.ee/projects/f2py2e/
:Discussions to: `f2py-users mailing list`_
:Documentation: `User's Guide`__, FAQ__
:Platforms: All
:Date: $Date: 2005/01/30 18:54:53 $

.. _f2py-users mailing list: http://cens.ioc.ee/mailman/listinfo/f2py-users/
__ usersguide/index.html
__ FAQ.html

.. Contents::

==============
 Introduction
==============

The purpose of the F2PY --*Fortran to Python interface generator*--
project is to provide connection between Python_ and Fortran
languages. F2PY is a Python extension tool for creating Python C/API
modules from (handwritten or F2PY generated) signature files (or
directly from Fortran sources). The generated extension modules
facilitate:

* Calling Fortran 77/90/95, Fortran 90/95 module, and C functions from
  Python.

* Accessing Fortran 77 ``COMMON`` blocks and Fortran 90/95 module
  data (including allocatable arrays) from Python.

* Calling Python functions from Fortran or C (call-backs).

* Automatically handling the difference in the data storage order of
  multi-dimensional Fortran and Numerical Python (i.e. C) arrays.

In addition, F2PY can build the generated extension modules to shared
libraries with one command. F2PY uses the ``numpy_distutils`` module
from SciPy_ that supports number of major Fortran compilers.

..
  (see `COMPILERS.txt`_ for more information).

F2PY generated extension modules depend on NumPy_ package that
provides fast multi-dimensional array language facility to Python.


---------------
 Main features
---------------

Here follows a more detailed list of F2PY features:

* F2PY scans real Fortran codes to produce the so-called signature
  files (.pyf files). The signature files contain all the information
  (function names, arguments and their types, etc.)  that is needed to
  construct Python bindings to Fortran (or C) functions.

  The syntax of signature files is borrowed from the
  Fortran 90/95 language specification and has some F2PY specific
  extensions. The signature files can be modified to dictate how
  Fortran (or C) programs are called from Python:

    + F2PY solves dependencies between arguments (this is relevant for
      the order of initializing variables in extension modules).

    + Arguments can be specified to be optional or hidden that
      simplifies calling Fortran programs from Python considerably.

    + In principle, one can design any Python signature for a given
      Fortran function, e.g. change the order arguments, introduce
      auxiliary arguments, hide the arguments, process the arguments
      before passing to Fortran, return arguments as output of F2PY
      generated functions, etc.

* F2PY automatically generates __doc__ strings (and optionally LaTeX
  documentation) for extension modules.

* F2PY generated functions accept arbitrary (but sensible) Python
  objects as arguments. The F2PY interface automatically takes care of
  type-casting and handling of non-contiguous arrays.

* The following Fortran constructs are recognized by F2PY:

  + All basic Fortran types::

      integer[ | *1 | *2 | *4 | *8 ], logical[ | *1 | *2 | *4 | *8 ]
      integer*([ -1 | -2 | -4 | -8 ])
      character[ | *(*) | *1 | *2 | *3 | ... ]
      real[ | *4 | *8 | *16 ], double precision
      complex[ | *8 | *16 | *32 ]

    Negative ``integer`` kinds are used to wrap unsigned integers.

  + Multi-dimensional arrays of all basic types with the following
    dimension specifications::

      <dim> | <start>:<end> | * | :

  + Attributes and statements::

      intent([ in | inout | out | hide | in,out | inout,out | c |
               copy | cache | callback | inplace | aux ])
      dimension(<dimspec>)
      common, parameter
      allocatable
      optional, required, external
      depend([<names>])
      check([<C-booleanexpr>])
      note(<LaTeX text>)
      usercode, callstatement, callprotoargument, threadsafe, fortranname
      pymethoddef
      entry

* Because there are only little (and easily handleable) differences
  between calling C and Fortran functions from F2PY generated
  extension modules, then F2PY is also well suited for wrapping C
  libraries to Python.

* Practice has shown that F2PY generated interfaces (to C or Fortran
  functions) are less error prone and even more efficient than
  handwritten extension modules. The F2PY generated interfaces are
  easy to maintain and any future optimization of F2PY generated
  interfaces transparently apply to extension modules by just
  regenerating them with the latest version of F2PY.

* `F2PY Users Guide and Reference Manual`_


===============
 Prerequisites
===============

F2PY requires the following software installed:

* Python_ (versions 1.5.2 or later; 2.1 and up are recommended).
  You must have python-dev package installed.
* NumPy_ (versions 13 or later; 20.x, 21.x, 22.x, 23.x are recommended)
* Numarray_ (version 0.9 and up), optional, partial support.
* Scipy_distutils (version 0.2.2 and up are recommended) from SciPy_
  project. Get it from Scipy CVS or download it below.

Python 1.x users also need distutils_.

Of course, to build extension modules, you'll need also working C
and/or Fortran compilers installed.

==========
 Download
==========

You can download the sources for the latest F2PY and numpy_distutils
releases as:

* `2.x`__/`F2PY-2-latest.tar.gz`__
* `2.x`__/`numpy_distutils-latest.tar.gz`__

Windows users might be interested in Win32 installer for F2PY and
Scipy_distutils (these installers are built using Python 2.3):

* `2.x`__/`F2PY-2-latest.win32.exe`__
* `2.x`__/`numpy_distutils-latest.win32.exe`__

Older releases are also available in the directories
`rel-0.x`__, `rel-1.x`__, `rel-2.x`__, `rel-3.x`__, `rel-4.x`__, `rel-5.x`__,
if you need them.

.. __: 2.x/
.. __: 2.x/F2PY-2-latest.tar.gz
.. __: 2.x/
.. __: 2.x/numpy_distutils-latest.tar.gz
.. __: 2.x/
.. __: 2.x/F2PY-2-latest.win32.exe
.. __: 2.x/
.. __: 2.x/numpy_distutils-latest.win32.exe
.. __: rel-0.x
.. __: rel-1.x
.. __: rel-2.x
.. __: rel-3.x
.. __: rel-4.x
.. __: rel-5.x

Development version of F2PY from CVS is available as `f2py2e.tar.gz`__.

__ http://cens.ioc.ee/cgi-bin/viewcvs.cgi/python/f2py2e/f2py2e.tar.gz?tarball=1

Debian Sid users can simply install ``python-f2py`` package.

==============
 Installation
==============

Unpack the source file, change to directrory ``F2PY-?-???/`` and run
(you may need to become a root)::

  python setup.py install

The F2PY installation installs a Python package ``f2py2e`` to your
Python ``site-packages`` directory and a script ``f2py`` to your
Python executable path.

See also Installation__ section in `F2PY FAQ`_.

.. __: FAQ.html#installation

Similarly, to install ``numpy_distutils``, unpack its tar-ball and run::

  python setup.py install

=======
 Usage
=======

To check if F2PY is installed correctly, run
::

  f2py

without any arguments. This should print out the usage information of
the ``f2py`` program.

Next, try out the following three steps:

1) Create a Fortran file `hello.f`__ that contains::

    C File hello.f
          subroutine foo (a)
          integer a
          print*, "Hello from Fortran!"
          print*, "a=",a
          end

__ hello.f

2) Run

  ::

    f2py -c -m hello hello.f

  This will build an extension module ``hello.so`` (or ``hello.sl``,
  or ``hello.pyd``, etc. depending on your platform) into the current
  directory.

3) Now in Python try::

    >>> import hello
    >>> print hello.__doc__
    >>> print hello.foo.__doc__
    >>> hello.foo(4)
     Hello from Fortran!
     a= 4
    >>>

If the above works, then you can try out more thorough
`F2PY unit tests`__ and read the `F2PY Users Guide and Reference Manual`_.

__ FAQ.html#q-how-to-test-if-f2py-is-working-correctly

===============
 Documentation
===============

The documentation of the F2PY project is collected in ``f2py2e/docs/``
directory. It contains the following documents:

`README.txt`_ (on GitHub__)
  The first thing to read about F2PY -- this document.

__ https://github.com/numpy/numpy/blob/master/numpy/f2py/docs/README.txt

`usersguide/index.txt`_, `usersguide/f2py_usersguide.pdf`_
  F2PY Users Guide and Reference Manual. Contains lots of examples.

`FAQ.txt`_ (on GitHub__)
  F2PY Frequently Asked Questions.

__ https://github.com/numpy/numpy/blob/master/numpy/f2py/docs/FAQ.txt

`TESTING.txt`_ (on GitHub__)
  About F2PY testing site. What tests are available and how to run them.

__ https://github.com/numpy/numpy/blob/master/numpy/f2py/docs/TESTING.txt

`HISTORY.txt`_ (on GitHub__)
  A list of latest changes in F2PY. This is the most up-to-date
  document on F2PY.

__ https://github.com/numpy/numpy/blob/master/numpy/f2py/docs/HISTORY.txt

`THANKS.txt`_
  Acknowledgments.

..
  `COMPILERS.txt`_
  Compiler and platform specific notes.

===============
 Mailing list
===============

A mailing list [email protected] is open for F2PY releated
discussion/questions/etc.

* `Subscribe..`__
* `Archives..`__

__ http://cens.ioc.ee/mailman/listinfo/f2py-users
__ http://cens.ioc.ee/pipermail/f2py-users


=====
 CVS
=====

F2PY is being developed under CVS_. The CVS version of F2PY can be
obtained as follows:

1) First you need to login (the password is ``guest``)::

    cvs -d :pserver:[email protected]:/home/cvs login

2) and then do the checkout::

    cvs -z6 -d :pserver:[email protected]:/home/cvs checkout f2py2e

3) You can update your local F2PY tree ``f2py2e/`` by executing::

    cvs -z6 update -P -d

You can browse the `F2PY CVS`_ repository.

===============
 Contributions
===============

* `A short introduction to F2PY`__ by Pierre Schnizer.

* `F2PY notes`__ by Fernando Perez.

* `Debian packages of F2PY`__ by José Fonseca. [OBSOLETE, Debian Sid
  ships python-f2py package]

__ http://fubphpc.tu-graz.ac.at/~pierre/f2py_tutorial.tar.gz
__ http://cens.ioc.ee/pipermail/f2py-users/2003-April/000472.html
__ http://jrfonseca.dyndns.org/debian/


===============
 Related sites
===============

* `Numerical Python`_ -- adds a fast array facility to the Python language.
* Pyfort_ -- A Python-Fortran connection tool.
* SciPy_ -- An open source library of scientific tools for Python.
* `Scientific Python`_ -- A collection of Python modules that are
  useful for scientific computing.
* `The Fortran Company`_ -- A place to find products, services, and general
  information related to the Fortran programming language.
* `American National Standard Programming Language FORTRAN ANSI(R) X3.9-1978`__
* `J3`_ -- The US Fortran standards committee.
* SWIG_ -- A software development tool that connects programs written
  in C and C++ with a variety of high-level programming languages.
* `Mathtools.net`_ -- A technical computing portal for all scientific
  and engineering needs.

.. __: http://www.fortran.com/fortran/F77_std/rjcnf.html

.. References
   ==========


.. _F2PY Users Guide and Reference Manual: usersguide/index.html
.. _usersguide/index.txt: usersguide/index.html
.. _usersguide/f2py_usersguide.pdf: usersguide/f2py_usersguide.pdf
.. _README.txt: README.html
.. _COMPILERS.txt: COMPILERS.html
.. _F2PY FAQ:
.. _FAQ.txt: FAQ.html
.. _HISTORY.txt: HISTORY.html
.. _HISTORY.txt from CVS: http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt?rev=HEAD&content-type=text/x-cvsweb-markup
.. _THANKS.txt: THANKS.html
.. _TESTING.txt: TESTING.html
.. _F2PY CVS2: http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/
.. _F2PY CVS: http://cens.ioc.ee/cgi-bin/viewcvs.cgi/python/f2py2e/

.. _CVS: http://www.cvshome.org/
.. _Python: http://www.python.org/
.. _SciPy: http://www.numpy.org/
.. _NumPy: http://www.numpy.org/
.. _Numarray: http://www.stsci.edu/resources/software_hardware/numarray
.. _docutils: http://docutils.sourceforge.net/
.. _distutils: http://www.python.org/sigs/distutils-sig/
.. _Numerical Python: http://www.numpy.org/
.. _Pyfort: http://pyfortran.sourceforge.net/
.. _Scientific Python:
   http://starship.python.net/crew/hinsen/scientific.html
.. _The Fortran Company: http://www.fortran.com/fortran/
.. _J3: http://www.j3-fortran.org/
.. _Mathtools.net: http://www.mathtools.net/
.. _SWIG: http://www.swig.org/

..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End: