diff options
Diffstat (limited to 'numpy/f2py/docs/FAQ.txt')
| -rw-r--r-- | numpy/f2py/docs/FAQ.txt | 615 |
1 files changed, 615 insertions, 0 deletions
diff --git a/numpy/f2py/docs/FAQ.txt b/numpy/f2py/docs/FAQ.txt new file mode 100644 index 000000000..e2ed79445 --- /dev/null +++ b/numpy/f2py/docs/FAQ.txt @@ -0,0 +1,615 @@ + +====================================================================== + 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 scipy_distutils when using F2PY from CVS? +--------------------------------------------------------------- + +To get scipy_distutils from SciPy CVS repository, run +:: + + cd cvs/f2py2e/ + make scipy_distutils + +This will checkout scipy_distutils to the current directory. + +You can upgrade scipy_distutils by executing +:: + + cd cvs/f2py2e/scipy_distutils + cvs update -Pd + +and install it by executing +:: + + cd cvs/f2py2e/scipy_distutils + python setup_scipy_distutils.py install + +In most of the time, f2py2e and scipy_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/scipy/BUILD_WIN32.html#setting-up-environment + +Install scipy_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 scipy_distutils + from scipy_distutils.fcompiler import new_fcompiler + compiler = new_fcompiler() # or new_fcompiler(compiler='intel') + compiler.dump_properties() + + # Using pre-0.2.2 scipy_distutils + import os + from scipy_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.scipy.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.scipy.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 scipy, 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 Höllmann: 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 |