======================================================================
               F2PY Frequently Asked Questions
======================================================================

.. contents::

General information
===================

Q: How to get started?
----------------------

First, install__ F2PY. Then check that F2PY installation works
properly (see below__). Try out a `simple example`__.

Read `F2PY Users Guide and Reference Manual`__. It contains lots
of complete examples.

If you have any questions/problems when using F2PY, don't hesitate to
turn to `F2PY users mailing list`__ or directly to me.

__ index.html#installation
__ #testing
__ index.html#usage
__ usersguide/index.html
__ index.html#mailing-list

Q: When to report bugs?
-----------------------

* If F2PY scanning fails on Fortran sources that otherwise compile
  fine.

* After checking that you have the latest version of F2PY from its
  CVS.  It is possible that a bug has been fixed already. See also the
  log entries in the file `HISTORY.txt`_ (`HISTORY.txt in CVS`_).

* After checking that your Python and Numerical Python installations
  work correctly.

* After checking that your C and Fortran compilers work correctly.


Q: How to report bugs?
----------------------

You can send bug reports directly to me. Please, include information
about your platform (operating system, version) and
compilers/linkers, e.g. the output (both stdout/stderr) of
::

  python -c 'import f2py2e.diagnose;f2py2e.diagnose.run()'

Feel free to add any other relevant information.  However, avoid
sending the output of F2PY generated ``.pyf`` files (unless they are
manually modified) or any binary files like shared libraries or object
codes.

While reporting bugs, you may find the following notes useful:

* `How To Ask Questions The Smart Way`__ by E. S. Raymond and R. Moen.

* `How to Report Bugs Effectively`__ by S. Tatham.

__ http://www.catb.org/~esr/faqs/smart-questions.html
__ http://www.chiark.greenend.org.uk/~sgtatham/bugs.html

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

Q: How to use F2PY with different Python versions?
--------------------------------------------------

Run the installation command using the corresponding Python
executable. For example,
::

    python2.1 setup.py install

installs the ``f2py`` script as ``f2py2.1``.

See `Distutils User Documentation`__ for more information how to
install Python modules to non-standard locations.

__ http://www.python.org/sigs/distutils-sig/doc/inst/inst.html


Q: Why F2PY is not working after upgrading?
-------------------------------------------

If upgrading from F2PY version 2.3.321 or earlier then remove all f2py
specific files from ``/path/to/python/bin`` directory before
running installation command.

Q: How to get/upgrade numpy_distutils when using F2PY from CVS?
---------------------------------------------------------------

To get numpy_distutils from SciPy CVS repository, run
::

  cd cvs/f2py2e/
  make numpy_distutils

This will checkout numpy_distutils to the current directory.

You can upgrade numpy_distutils by executing
::

  cd cvs/f2py2e/numpy_distutils
  cvs update -Pd

and install it by executing
::

  cd cvs/f2py2e/numpy_distutils
  python setup_numpy_distutils.py install

In most of the time, f2py2e and numpy_distutils can be upgraded
independently.

Testing
=======

Q: How to test if F2PY is installed correctly?
----------------------------------------------

Run
::

  f2py

without arguments. If F2PY is installed correctly then it should print
the usage information for f2py.

Q: How to test if F2PY is working correctly?
--------------------------------------------

For a quick test, try out an example problem from Usage__
section in `README.txt`_.

__ index.html#usage

For running F2PY unit tests, see `TESTING.txt`_.


Q: How to run tests and examples in f2py2e/test-suite/ directory?
---------------------------------------------------------------------

You shouldn't. These tests are obsolete and I have no intention to
make them work. They will be removed in future.


Compiler/Platform-specific issues
=================================

Q: What are supported platforms and compilers?
----------------------------------------------

F2PY is developed on Linux system with a GCC compiler (versions
2.95.x, 3.x). Fortran 90 related hooks are tested against Intel
Fortran Compiler. F2PY should work under any platform where Python and
Numeric are installed and has supported Fortran compiler installed.

To see a list of supported compilers, execute::

  f2py -c --help-fcompiler

Example output::

  List of available Fortran compilers:
    --fcompiler=gnu    GNU Fortran Compiler (3.3.4)
    --fcompiler=intel  Intel Fortran Compiler for 32-bit apps (8.0)
  List of unavailable Fortran compilers:
    --fcompiler=absoft   Absoft Corp Fortran Compiler
    --fcompiler=compaq   Compaq Fortran Compiler
    --fcompiler=compaqv  DIGITAL|Compaq Visual Fortran Compiler
    --fcompiler=hpux     HP Fortran 90 Compiler
    --fcompiler=ibm      IBM XL Fortran Compiler
    --fcompiler=intele   Intel Fortran Compiler for Itanium apps
    --fcompiler=intelev  Intel Visual Fortran Compiler for Itanium apps
    --fcompiler=intelv   Intel Visual Fortran Compiler for 32-bit apps
    --fcompiler=lahey    Lahey/Fujitsu Fortran 95 Compiler
    --fcompiler=mips     MIPSpro Fortran Compiler
    --fcompiler=nag      NAGWare Fortran 95 Compiler
    --fcompiler=pg       Portland Group Fortran Compiler
    --fcompiler=sun      Sun|Forte Fortran 95 Compiler
    --fcompiler=vast     Pacific-Sierra Research Fortran 90 Compiler
  List of unimplemented Fortran compilers:
    --fcompiler=f  Fortran Company/NAG F Compiler
  For compiler details, run 'config_fc --verbose' setup command.


Q: How to use the F compiler in F2PY?
-------------------------------------

Read `f2py2e/doc/using_F_compiler.txt`__. It describes why the F
compiler cannot be used in a normal way (i.e. using ``-c`` switch) to
build F2PY generated modules. It also gives a workaround to this
problem.

__ http://cens.ioc.ee/cgi-bin/viewcvs.cgi/python/f2py2e/doc/using_F_compiler.txt?rev=HEAD&content-type=text/vnd.viewcvs-markup

Q: How to use F2PY under Windows?
---------------------------------

F2PY can be used both within Cygwin__ and MinGW__ environments under
Windows, F2PY can be used also in Windows native terminal.
See the section `Setting up environment`__ for Cygwin and MinGW.

__ http://cygwin.com/
__ http://www.mingw.org/
__ http://cens.ioc.ee/~pearu/numpy/BUILD_WIN32.html#setting-up-environment

Install numpy_distutils and F2PY. Win32 installers of these packages
are provided in `F2PY Download`__ section.

__ http://cens.ioc.ee/projects/f2py2e/#download

Use ``--compiler=`` and ``--fcompiler`` F2PY command line switches to
to specify which C and Fortran compilers F2PY should use, respectively.

Under MinGW environment, ``mingw32`` is default for a C compiler.

Supported and Unsupported Features
==================================

Q: Does F2PY support ``ENTRY`` statements?
------------------------------------------

Yes, starting at F2PY version higher than 2.39.235_1706.

Q: Does F2PY support derived types in F90 code?
-----------------------------------------------

Not yet. However I do have plans to implement support for F90 TYPE
constructs in future. But note that the task in non-trivial and may
require the next edition of F2PY for which I don't have resources to
work with at the moment.

Jeffrey Hagelberg from LLNL has made progress on adding 
support for derived types to f2py. He writes:

  At this point, I have a version of f2py that supports derived types
  for most simple cases.  I have multidimensional arrays of derived
  types and allocatable arrays of derived types working.  I'm just now
  starting to work on getting nested derived types to work.  I also
  haven't tried putting complex number in derived types yet.

Hopefully he can contribute his changes to f2py soon.

Q: Does F2PY support pointer data in F90 code?
-----------------------------------------------

No. I have never needed it and I haven't studied if there are any
obstacles to add pointer data support to F2PY.

Q: What if Fortran 90 code uses ``<type spec>(kind=KIND(..))``?
---------------------------------------------------------------

Currently, F2PY can handle only ``<type spec>(kind=<kindselector>)``
declarations where ``<kindselector>`` is a numeric integer (e.g. 1, 2,
4,...) but not a function call ``KIND(..)`` or any other
expression. F2PY needs to know what would be the corresponding C type
and a general solution for that would be too complicated to implement.

However, F2PY provides a hook to overcome this difficulty, namely,
users can define their own <Fortran type> to <C type> maps. For
example, if Fortran 90 code contains::

  REAL(kind=KIND(0.0D0)) ...

then create a file ``.f2py_f2cmap`` (into the working directory)
containing a Python dictionary::

  {'real':{'KIND(0.0D0)':'double'}}

for instance.

Or more generally, the file ``.f2py_f2cmap`` must contain a dictionary
with items::

  <Fortran typespec> : {<selector_expr>:<C type>}

that defines mapping between Fortran type::

  <Fortran typespec>([kind=]<selector_expr>)

and the corresponding ``<C type>``. ``<C type>`` can be one of the
following::

  char
  signed_char
  short
  int
  long_long
  float
  double
  long_double
  complex_float
  complex_double
  complex_long_double
  string

For more information, see ``f2py2e/capi_maps.py``.

Related software
================

Q: How F2PY distinguishes from Pyfort?
--------------------------------------

F2PY and Pyfort have very similar aims and ideology of how they are
targeted. Both projects started to evolve in the same year 1999
independently. When we discovered each others projects, a discussion
started to join the projects but that unfortunately failed for
various reasons, e.g. both projects had evolved too far that merging
the tools would have been impractical and giving up the efforts that
the developers of both projects have made was unacceptable to both
parties. And so, nowadays we have two tools for connecting Fortran
with Python and this fact will hardly change in near future. To decide
which one to choose is a matter of taste, I can only recommend to try
out both to make up your choice.

At the moment F2PY can handle more wrapping tasks than Pyfort,
e.g. with F2PY one can wrap Fortran 77 common blocks, Fortran 90
module routines, Fortran 90 module data (including allocatable
arrays), one can call Python from Fortran, etc etc. F2PY scans Fortran
codes to create signature (.pyf) files. F2PY is free from most of the
limitations listed in in `the corresponding section of Pyfort
Reference Manual`__.

__ http://pyfortran.sourceforge.net/pyfort/pyfort_reference.htm#pgfId-296925

There is a conceptual difference on how F2PY and Pyfort handle the
issue of different data ordering in Fortran and C multi-dimensional
arrays. Pyfort generated wrapper functions have optional arguments
TRANSPOSE and MIRROR that can be used to control explicitly how the array
arguments and their dimensions are passed to Fortran routine in order
to deal with the C/Fortran data ordering issue. F2PY generated wrapper
functions hide the whole issue from an end-user so that translation
between Fortran and C/Python loops and array element access codes is
one-to-one. How the F2PY generated wrappers deal with the issue is
determined by a person who creates a signature file via using
attributes like ``intent(c)``, ``intent(copy|overwrite)``,
``intent(inout|in,out|inplace)`` etc.

For example, let's consider a typical usage of both F2PY and Pyfort
when wrapping the following simple Fortran code:

.. include:: simple.f
   :literal:

The comment lines starting with ``cf2py`` are read by F2PY (so that we
don't need to generate/handwrite an intermediate signature file in
this simple case) while for a Fortran compiler they are just comment
lines.

And here is a Python version of the Fortran code:

.. include:: pytest.py
   :literal:

To generate a wrapper for subroutine ``foo`` using F2PY, execute::

  $ f2py -m f2pytest simple.f -c

that will generate an extension module ``f2pytest`` into the current
directory.

To generate a wrapper using Pyfort, create the following file

.. include:: pyforttest.pyf
   :literal:

and execute::

  $ pyfort pyforttest

In Pyfort GUI add ``simple.f`` to the list of Fortran sources and
check that the signature file is in free format. And then copy
``pyforttest.so`` from the build directory to the current directory.

Now, in Python

.. include:: simple_session.dat
   :literal:

Q: Can Pyfort .pyf files used with F2PY and vice versa?
-------------------------------------------------------

After some simple modifications, yes. You should take into account the
following differences in Pyfort and F2PY .pyf files.

+ F2PY signature file contains ``python module`` and ``interface``
  blocks that are equivalent to Pyfort ``module`` block usage.

+ F2PY attribute ``intent(inplace)`` is equivalent to Pyfort
  ``intent(inout)``. F2PY ``intent(inout)`` is a strict (but safe)
  version of ``intent(inplace)``, any mismatch in arguments with
  expected type, size, or contiguouness will trigger an exception
  while ``intent(inplace)`` (dangerously) modifies arguments
  attributes in-place.

Misc
====

Q: How to establish which Fortran compiler F2PY will use?
---------------------------------------------------------

This question may be releavant when using F2PY in Makefiles.  Here
follows a script demonstrating how to determine which Fortran compiler
and flags F2PY will use::

  # Using post-0.2.2 numpy_distutils
  from numpy_distutils.fcompiler import new_fcompiler
  compiler = new_fcompiler() # or new_fcompiler(compiler='intel')
  compiler.dump_properties()

  # Using pre-0.2.2 numpy_distutils
  import os
  from numpy_distutils.command.build_flib import find_fortran_compiler
  def main():
      fcompiler = os.environ.get('FC_VENDOR')
      fcompiler_exec = os.environ.get('F77')
      f90compiler_exec = os.environ.get('F90')
      fc = find_fortran_compiler(fcompiler,
                                 fcompiler_exec,
                                 f90compiler_exec,
                                 verbose = 0)
      print 'FC=',fc.f77_compiler
      print 'FFLAGS=',fc.f77_switches
      print 'FOPT=',fc.f77_opt
  if __name__ == "__main__":
      main()

Users feedback
==============

Q: Where to find additional information on using F2PY?
------------------------------------------------------

There are several F2PY related tutorials, slides, papers, etc
available:

+ `Fortran to Python Interface Generator with an Application to
  Aerospace Engineering`__ by P. Peterson, J. R. R. A. Martins, and
  J. J. Alonso in `In Proceedings of the 9th International Python
  Conference`__, Long Beach, California, 2001.

__ http://www.python9.org/p9-cdrom/07/index.htm
__ http://www.python9.org/

+ Section `Adding Fortran90 code`__ in the UG of `The Bolometer Data
  Analysis Project`__.

__ http://www.astro.rub.de/laboca/download/boa_master_doc/7_4Adding_Fortran90_code.html
__ http://www.openboa.de/

+ Powerpoint presentation `Python for Scientific Computing`__ by Eric
  Jones in `The Ninth International Python Conference`__.

__ http://www.python9.org/p9-jones.ppt
__ http://www.python9.org/

+ Paper `Scripting a Large Fortran Code with Python`__ by Alvaro Caceres
  Calleja in `International Workshop on Software Engineering for High
  Performance Computing System Applications`__.

__ http://csdl.ics.hawaii.edu/se-hpcs/pdf/calleja.pdf
__ http://csdl.ics.hawaii.edu/se-hpcs/

+ Section `Automatic building of C/Fortran extension for Python`__ by
  Simon Lacoste-Julien in `Summer 2002 Report about Hybrid Systems
  Modelling`__.

__ http://moncs.cs.mcgill.ca/people/slacoste/research/report/SummerReport.html#tth_sEc3.4
__ http://moncs.cs.mcgill.ca/people/slacoste/research/report/SummerReport.html

+ `Scripting for Computational Science`__ by Hans Petter Langtangen
   (see the `Mixed language programming`__ and `NumPy array programming`__
   sections for examples on using F2PY).

__ http://www.ifi.uio.no/~inf3330/lecsplit/
__ http://www.ifi.uio.no/~inf3330/lecsplit/slide662.html
__ http://www.ifi.uio.no/~inf3330/lecsplit/slide718.html

+  Chapters 5 and 9 of `Python Scripting for Computational Science`__
   by H. P. Langtangen for case studies on using F2PY.

__ http://www.springeronline.com/3-540-43508-5

+ Section `Fortran Wrapping`__ in `Continuity`__, a computational tool
  for continuum problems in bioengineering and physiology.

__ http://www.continuity.ucsd.edu/cont6_html/docs_fram.html
__ http://www.continuity.ucsd.edu/

+ Presentation `PYFORT and F2PY: 2 ways to bind C and Fortran with Python`__
  by Reiner Vogelsang.

__ http://www.prism.enes.org/WPs/WP4a/Slides/pyfort/pyfort.html

+ Lecture slides of `Extending Python: speed it up`__.

__ http://www.astro.uni-bonn.de/~heith/lecture_pdf/friedrich5.pdf

+ Wiki topics on `Wrapping Tools`__ and `Wrapping Bemchmarks`__ for Climate
  System Center at the University of Chicago.

__ https://geodoc.uchicago.edu/climatewiki/DiscussWrappingTools
__ https://geodoc.uchicago.edu/climatewiki/WrappingBenchmarks

+ `Performance Python with Weave`__ by Prabhu Ramachandran.

__ http://www.numpy.org/documentation/weave/weaveperformance.html

+ `How To Install py-f2py on Mac OSX`__

__ http://py-f2py.darwinports.com/

Please, let me know if there are any other sites that document F2PY
usage in one or another way.

Q: What projects use F2PY?
--------------------------

+ `SciPy: Scientific tools for Python`__

__ http://www.numpy.org/

+ `The Bolometer Data Analysis Project`__

__ http://www.openboa.de/

+ `pywavelet`__

__ http://www.met.wau.nl/index.html?http://www.met.wau.nl/medewerkers/moenea/python/pywavelet.html

+ `PyARTS: an ARTS related Python package`__.

__ http://www.met.ed.ac.uk/~cory/PyARTS/

+ `Python interface to PSPLINE`__, a collection of Spline and
  Hermite interpolation tools for 1D, 2D, and 3D datasets on
  rectilinear grids. 

__ http://pypspline.sourceforge.net

+ `Markovian Analysis Package for Python`__.

__ http://pymc.sourceforge.net

+ `Modular toolkit for Data Processing (MDP)`__

__ http://mdp-toolkit.sourceforge.net/


Please, send me a note if you are using F2PY in your project.

Q: What people think about F2PY?
--------------------------------

*F2PY is GOOD*:

Here are some comments people have posted to f2py mailing list and c.l.py:

+ Ryan Krauss: I really appreciate f2py.  It seems weird to say, but I
  am excited about relearning FORTRAN to compliment my python stuff.

+ Fabien Wahl: f2py is great, and is used extensively over here...

+ Fernando Perez: Anyway, many many thanks for this amazing tool.

  I haven't used pyfort, but I can definitely vouch for the amazing quality of 
  f2py.  And since f2py is actively used by numpy, it won't go unmaintained.  
  It's quite impressive, and very easy to use.

+ Kevin Mueller: First off, thanks to those responsible for F2PY; 
  its been an integral tool of my research for years now.

+ David Linke: Best regards and thanks for the great tool!

+ Perrin Meyer: F2Py is really useful!

+ Hans Petter Langtangen: First of all, thank you for developing
  F2py. This is a very important contribution to the scientific
  computing community. We are using F2py a lot and are very happy with
  it.

+ Berthold Hllmann: Thank's alot. It seems it is also working in my
  'real' application :-)

+ John Hunter: At first I wrapped them with f2py (unbelievably easy!)...

+ Cameron Laird: Among many other features, Python boasts a mature
  f2py, which makes it particularly rewarding to yoke Fortran- and
  Python-coded modules into finished applications.

+ Ryan Gutenkunst: f2py is sweet magic.

*F2PY is BAD*:

+ `Is it worth using on a large scale python drivers for Fortran
  subroutines, interfaced with f2py?`__

__ http://sepwww.stanford.edu/internal/computing/python.html

Additional comments on F2PY, good or bad, are welcome!

.. References:
.. _README.txt: index.html
.. _HISTORY.txt: HISTORY.html
.. _HISTORY.txt in CVS: http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt?rev=HEAD&content-type=text/x-cvsweb-markup
.. _TESTING.txt: TESTING.html