diff options
Diffstat (limited to 'numpy/f2py/docs')
48 files changed, 5166 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 diff --git a/numpy/f2py/docs/HISTORY.txt b/numpy/f2py/docs/HISTORY.txt new file mode 100644 index 000000000..876ab2362 --- /dev/null +++ b/numpy/f2py/docs/HISTORY.txt @@ -0,0 +1,1044 @@ +.. -*- rest -*- + +========================= + F2PY History +========================= + +:Author: Pearu Peterson <pearu@cens.ioc.ee> +:Web-site: http://cens.ioc.ee/projects/f2py2e/ +:Date: $Date: 2005/09/16 08:36:45 $ +:Revision: $Revision: 1.191 $ + +.. Contents:: + +Release 2.46.243 +===================== + +* common_rules.py + + - Fixed compiler warnings. + +* fortranobject.c + + - Fixed another dims calculation bug. + - Fixed dims calculation bug and added the corresponding check. + - Accept higher dimensional arrays if their effective rank matches. + Effective rank is multiplication of non-unit dimensions. + +* f2py2e.py + + - Added support for scipy.distutils version 0.4.0. + +* Documentation + + - Added example about ``intent(callback,hide)`` usage. Updates. + - Updated FAQ. + +* cb_rules.py + + - Fixed missing need kw error. + - Fixed getting callback non-existing extra arguments. + - External callback functions and extra_args can be set via + ext.module namespace. + - Avoid crash when external callback function is not set. + +* rules.py + + - Enabled ``intent(out)`` for ``intent(aux)`` non-complex scalars. + - Fixed splitting lines in F90 fixed form mode. + - Fixed FORTRANAME typo, relevant when wrapping scalar functions with + ``--no-wrap-functions``. + - Improved failure handling for callback functions. + - Fixed bug in writting F90 wrapper functions when a line length + is exactly 66. + +* cfuncs.py + + - Fixed dependency issue with typedefs. + - Introduced ``-DUNDERSCORE_G77`` that cause extra underscore to be + used for external names that contain an underscore. + +* capi_maps.py + + - Fixed typos. + - Fixed using complex cb functions. + +* crackfortran.py + + - Introduced parent_block key. Get ``use`` statements recursively + from parent blocks. + - Apply parameter values to kindselectors. + - Fixed bug evaluating ``selected_int_kind`` function. + - Ignore Name and Syntax errors when evaluating scalars. + - Treat ``<int>_intType`` as ``<int>`` in get_parameters. + - Added support for F90 line continuation in fix format mode. + - Include optional attribute of external to signature file. + - Add ``entry`` arguments to variable lists. + - Treat \xa0 character as space. + - Fixed bug where __user__ callback subroutine was added to its + argument list. + - In strict 77 mode read only the first 72 columns. + - Fixed parsing ``v(i) = func(r)``. + - Fixed parsing ``integer*4::``. + - Fixed parsing ``1.d-8`` when used as a parameter value. + +Release 2.45.241_1926 +===================== + +* diagnose.py + + - Clean up output. + +* cb_rules.py + + - Fixed ``_cpointer`` usage for subroutines. + - Fortran function ``_cpointer`` can be used for callbacks. + +* func2subr.py + + - Use result name when wrapping functions with subroutines. + +* f2py2e.py + + - Fixed ``--help-link`` switch. + - Fixed ``--[no-]lower`` usage with ``-c`` option. + - Added support for ``.pyf.src`` template files. + +* __init__.py + + - Using ``exec_command`` in ``compile()``. + +* setup.py + + - Clean up. + - Disabled ``need_scipy_distutils`` function. From now on it is assumed + that proper version of ``scipy_distutils`` is already installed. + +* capi_maps.py + + - Added support for wrapping unsigned integers. In a .pyf file + ``integer(-1)``, ``integer(-2)``, ``integer(-4)`` correspond to + ``unsigned char``, ``unsigned short``, ``unsigned`` C types, + respectively. + +* tests/c/return_real.py + + - Added tests to wrap C functions returning float/double. + +* fortranobject.c + + - Added ``_cpointer`` attribute to wrapped objects. + +* rules.py + + - ``_cpointer`` feature for wrapped module functions is not + functional at the moment. + - Introduced ``intent(aux)`` attribute. Useful to save a value + of a parameter to auxiliary C variable. Note that ``intent(aux)`` + implies ``intent(c)``. + - Added ``usercode`` section. When ``usercode`` is used in ``python + module`` block twise then the contents of the second multi-line + block is inserted after the definition of external routines. + - Call-back function arguments can be CObjects. + +* cfuncs.py + + - Allow call-back function arguments to be fortran objects. + - Allow call-back function arguments to be built-in functions. + +* crackfortran.py + + - Fixed detection of a function signature from usage example. + - Cleaned up -h output for intent(callback) variables. + - Repair malformed argument list (missing argument name). + - Warn on the usage of multiple attributes without type specification. + - Evaluate only scalars ``<initexpr>`` (e.g. not of strings). + - Evaluate ``<initexpr>`` using parameters name space. + - Fixed resolving `<name>(<args>)[result(<result>)]` pattern. + - ``usercode`` can be used more than once in the same context. + +Release 2.43.239_1831 +===================== + +* auxfuncs.py + + - Made ``intent(in,inplace)`` to mean ``intent(inplace)``. + +* f2py2e.py + + - Intoduced ``--help-link`` and ``--link-<resource>`` + switches to link generated extension module with system + ``<resource>`` as defined by scipy_distutils/system_info.py. + +* fortranobject.c + + - Patch to make PyArray_CanCastSafely safe on 64-bit machines. + Fixes incorrect results when passing ``array('l')`` to + ``real*8 intent(in,out,overwrite)`` arguments. + +* rules.py + + - Avoid empty continuation lines in Fortran wrappers. + +* cfuncs.py + + - Adding ``\0`` at the end of a space-padded string, fixes tests + on 64-bit Gentoo. + +* crackfortran.py + + - Fixed splitting lines with string parameters. + +Release 2.43.239_1806 +===================== + +* Tests + + - Fixed test site that failed after padding strings with spaces + instead of zeros. + +* Documentation + + - Documented ``intent(inplace)`` attribute. + - Documented ``intent(callback)`` attribute. + - Updated FAQ, added Users Feedback section. + +* cfuncs.py + + - Padding longer (than provided from Python side) strings with spaces + (that is Fortran behavior) instead of nulls (that is C strncpy behavior). + +* f90mod_rules.py + + - Undoing rmbadnames in Python and Fortran layers. + +* common_rules.py + + - Renaming common block items that have names identical to C keywords. + - Fixed wrapping blank common blocks. + +* fortranobject.h + + - Updated numarray (0.9, 1.0, 1.1) support (patch by Todd Miller). + +* fortranobject.c + + - Introduced ``intent(inplace)`` feature. + - Fix numarray reference counts (patch by Todd). + - Updated numarray (0.9, 1.0, 1.1) support (patch by Todd Miller). + - Enabled F2PY_REPORT_ON_ARRAY_COPY for Numarray. + +* capi_maps.py + + - Always normalize .f2py_f2cmap keys to lower case. + +* rules.py + + - Disabled ``index`` macro as it conflicts with the one defined + in string.h. + - Moved ``externroutines`` up to make it visible to ``usercode``. + - Fixed bug in f90 code generation: no empty line continuation is + allowed. + - Fixed undefined symbols failure when ``fortranname`` is used + to rename a wrapped function. + - Support for ``entry`` statement. + +* auxfuncs.py + + - Made is* functions more robust with respect to parameters that + have no typespec specified. + - Using ``size_t`` instead of ``int`` as the type of string + length. Fixes issues on 64-bit platforms. + +* setup.py + + - Fixed bug of installing ``f2py`` script as ``.exe`` file. + +* f2py2e.py + + - ``--compiler=`` and ``--fcompiler=`` can be specified at the same time. + +* crackfortran.py + + - Fixed dependency detection for non-intent(in|inout|inplace) arguments. + They must depend on their dimensions, not vice-versa. + - Don't match ``!!f2py`` as a start of f2py directive. + - Only effective intent attributes will be output to ``-h`` target. + - Introduced ``intent(callback)`` to build interface between Python + functions and Fortran external routines. + - Avoid including external arguments to __user__ modules. + - Initial hooks to evaluate ``kind`` and ``selected_int_kind``. + - Evaluating parameters in {char,kind}selectors and applying rmbadname. + - Evaluating parameters using also module parameters. Fixed the order + of parameter evaluation. + - Fixed silly bug: when block name was not lower cased, it was not + recognized correctly. + - Applying mapping '.false.'->'False', '.true.'->'True' to logical + parameters. TODO: Support for logical expressions is needed. + - Added support for multiple statements in one line (separated with semicolon). + - Impl. get_useparameters function for using parameter values from + other f90 modules. + - Applied Bertholds patch to fix bug in evaluating expressions + like ``1.d0/dvar``. + - Fixed bug in reading string parameters. + - Evaluating parameters in charselector. Code cleanup. + - Using F90 module parameters to resolve kindselectors. + - Made the evaluation of module data init-expression more robust. + - Support for ``entry`` statement. + - Fixed ``determineexprtype`` that in the case of parameters + returned non-dictionary objects. + - Use ``-*- fix -*-`` to specify that a file is in fixed format. + +Release 2.39.235_1693 +===================== + +* fortranobject.{h,c} + + - Support for allocatable string arrays. + +* cfuncs.py + + - Call-back arguments can now be also instances that have ``__call__`` method + as well as instance methods. + +* f2py2e.py + + - Introduced ``--include_paths <path1>:<path2>:..`` command line + option. + - Added ``--compiler=`` support to change the C/C++ compiler from + f2py command line. + +* capi_maps.py + + - Handle ``XDY`` parameter constants. + +* crackfortran.py + + - Handle ``XDY`` parameter constants. + + - Introduced formatpattern to workaround a corner case where reserved + keywords are used in format statement. Other than that, format pattern + has no use. + + - Parameters are now fully evaluated. + +* More splitting of documentation strings. + +* func2subr.py - fixed bug for function names that f77 compiler + would set ``integer`` type. + +Release 2.39.235_1660 +===================== + +* f2py2e.py + + - Fixed bug in using --f90flags=.. + +* f90mod_rules.py + + - Splitted generated documentation strings (to avoid MSVC issue when + string length>2k) + + - Ignore ``private`` module data. + +Release 2.39.235_1644 +===================== + +:Date:24 February 2004 + +* Character arrays: + + - Finished complete support for character arrays and arrays of strings. + - ``character*n a(m)`` is treated like ``character a(m,n)`` with ``intent(c)``. + - Character arrays are now considered as ordinary arrays (not as arrays + of strings which actually didn't work). + +* docs + + - Initial f2py manpage file f2py.1. + - Updated usersguide and other docs when using scipy_distutils 0.2.2 + and up. + +* capi_maps.py + + - Try harder to use .f2py_f2cmap mappings when kind is used. + +* crackfortran.py + + - Included files are first search in the current directory and + then from the source file directory. + - Ignoring dimension and character selector changes. + - Fixed bug in Fortran 90 comments of fixed format. + - Warn when .pyf signatures contain undefined symbols. + - Better detection of source code formats. Using ``-*- fortran -*-`` + or ``-*- f90 -*-`` in the first line of a Fortran source file is + recommended to help f2py detect the format, fixed or free, + respectively, correctly. + +* cfuncs.py + + - Fixed intent(inout) scalars when typecode=='l'. + - Fixed intent(inout) scalars when not using numarray. + - Fixed intent(inout) scalars when using numarray. + +* diagnose.py + + - Updated for scipy_distutils 0.2.2 and up. + - Added numarray support to diagnose. + +* fortranobject.c + + - Fixed nasty bug with intent(in,copy) complex slice arrays. + - Applied Todd's patch to support numarray's byteswapped or + misaligned arrays, requires numarray-0.8 or higher. + +* f2py2e.py + + - Applying new hooks for scipy_distutils 0.2.2 and up, keeping + backward compatibility with depreciation messages. + - Using always os.system on non-posix platforms in f2py2e.compile + function. + +* rules.py + + - Changed the order of buildcallback and usercode junks. + +* setup.cfg + + - Added so that docs/ and tests/ directories are included to RPMs. + +* setup.py + + - Installing f2py.py instead of f2py.bat under NT. + - Introduced ``--with-scipy_distutils`` that is useful when making + f2py tar-ball with scipy_distutils included. + +Release 2.37.233-1545 +===================== + +:Date: 11 September 2003 + +* rules.py + + - Introduced ``interface_usercode`` replacement. When ``usercode`` + statement is used inside the first interface block, its contents + will be inserted at the end of initialization function of a F2PY + generated extension module (feature request: Berthold Höllmann). + - Introduced auxiliary function ``as_column_major_storage`` that + converts input array to an array with column major storage order + (feature request: Hans Petter Langtangen). + +* crackfortran.py + + - Introduced ``pymethoddef`` statement. + +* cfuncs.py + + - Fixed "#ifdef in #define TRYPYARRAYTEMPLATE" bug (patch thanks + to Bernhard Gschaider) + +* auxfuncs.py + + - Introduced ``getpymethod`` function. + - Enabled multi-line blocks in ``callprotoargument`` statement. + +* f90mod_rules.py + + - Undone "Fixed Warning 43 emitted by Intel Fortran compiler" that + causes (curios) segfaults. + +* fortranobject.c + + - Fixed segfaults (that were introduced with recent memory leak + fixes) when using allocatable arrays. + - Introduced F2PY_REPORT_ON_ARRAY_COPY CPP macro int-variable. If defined + then a message is printed to stderr whenever a copy of an array is + made and arrays size is larger than F2PY_REPORT_ON_ARRAY_COPY. + +Release 2.35.229-1505 +===================== + +:Date: 5 August 2003 + +* General + + - Introduced ``usercode`` statement (dropped ``c_code`` hooks). + +* setup.py + + - Updated the CVS location of scipy_distutils. + +* auxfuncs.py + + - Introduced ``isint1array(var)`` for fixing ``integer*1 intent(out)`` + support. + +* tests/f77/callback.py + + Introduced some basic tests. + +* src/fortranobject.{c,h} + + - Fixed memory leaks when getting/setting allocatable arrays. + (Bug report by Bernhard Gschaider) + + - Initial support for numarray (Todd Miller's patch). Use -DNUMARRAY + on the f2py command line to enable numarray support. Note that + there is no character arrays support and these hooks are not + tested with F90 compilers yet. + +* cfuncs.py + + - Fixed reference counting bug that appeared when constructing extra + argument list to callback functions. + - Added ``PyArray_LONG != PyArray_INT`` test. + +* f2py2e.py + + Undocumented ``--f90compiler``. + +* crackfortran.py + + - Introduced ``usercode`` statement. + - Fixed newlines when outputting multi-line blocks. + - Optimized ``getlincoef`` loop and ``analyzevars`` for cases where + len(vars) is large. + - Fixed callback string argument detection. + - Fixed evaluating expressions: only int|float expressions are + evaluated succesfully. + +* docs + + Documented -DF2PY_REPORT_ATEXIT feature. + +* diagnose.py + + Added CPU information and sys.prefix printout. + +* tests/run_all.py + + Added cwd to PYTHONPATH. + +* tests/f??/return_{real,complex}.py + + Pass "infinity" check in SunOS. + +* rules.py + + - Fixed ``integer*1 intent(out)`` support + - Fixed free format continuation of f2py generated F90 files. + +* tests/mixed/ + + Introduced tests for mixing Fortran 77, Fortran 90 fixed and free + format codes in one module. + +* f90mod_rules.py + + - Fixed non-prototype warnings. + - Fixed Warning 43 emitted by Intel Fortran compiler. + - Avoid long lines in Fortran codes to reduce possible problems with + continuations of lines. + +Public Release 2.32.225-1419 +============================ + +:Date: 8 December 2002 + +* docs/usersguide/ + + Complete revision of F2PY Users Guide + +* tests/run_all.py + + - New file. A Python script to run all f2py unit tests. + +* Removed files: buildmakefile.py, buildsetup.py. + +* tests/f77/ + + - Added intent(out) scalar tests. + +* f2py_testing.py + + - Introduced. It contains jiffies, memusage, run, cmdline functions + useful for f2py unit tests site. + +* setup.py + + - Install scipy_distutils only if it is missing or is too old + for f2py. + +* f90modrules.py + + - Fixed wrapping f90 module data. + - Fixed wrapping f90 module subroutines. + - Fixed f90 compiler warnings for wrapped functions by using interface + instead of external stmt for functions. + +* tests/f90/ + + - Introduced return_*.py tests. + +* func2subr.py + + - Added optional signature argument to createfuncwrapper. + - In f2pywrappers routines, declare external, scalar, remaining + arguments in that order. Fixes compiler error 'Invalid declaration' + for:: + + real function foo(a,b) + integer b + real a(b) + end + +* crackfortran.py + + - Removed first-line comment information support. + - Introduced multiline block. Currently usable only for + ``callstatement`` statement. + - Improved array length calculation in getarrlen(..). + - "From sky" program group is created only if ``groupcounter<1``. + See TODO.txt. + - Added support for ``dimension(n:*)``, ``dimension(*:n)``. They are + treated as ``dimesnion(*)`` by f2py. + - Fixed parameter substitution (this fixes TODO item by Patrick + LeGresley, 22 Aug 2001). + +* f2py2e.py + + - Disabled all makefile, setup, manifest file generation hooks. + - Disabled --[no]-external-modroutines option. All F90 module + subroutines will have Fortran/C interface hooks. + - --build-dir can be used with -c option. + - only/skip modes can be used with -c option. + - Fixed and documented `-h stdout` feature. + - Documented extra options. + - Introduced --quiet and --verbose flags. + +* cb_rules.py + + - Fixed debugcapi hooks for intent(c) scalar call-back arguments + (bug report: Pierre Schnizer). + - Fixed intent(c) for scalar call-back arguments. + - Improved failure reports. + +* capi_maps.py + + - Fixed complex(kind=..) to C type mapping bug. The following hold + complex==complex(kind=4)==complex*8, complex(kind=8)==complex*16 + - Using signed_char for integer*1 (bug report: Steve M. Robbins). + - Fixed logical*8 function bug: changed its C correspondence to + long_long. + - Fixed memory leak when returning complex scalar. + +* __init__.py + + - Introduced a new function (for f2py test site, but could be useful + in general) ``compile(source[,modulename,extra_args])`` for + compiling fortran source codes directly from Python. + +* src/fortranobject.c + + - Multi-dimensional common block members and allocatable arrays + are returned as Fortran-contiguous arrays. + - Fixed NULL return to Python without exception. + - Fixed memory leak in getattr(<fortranobj>,'__doc__'). + - <fortranobj>.__doc__ is saved to <fortranobj>.__dict__ (previously + it was generated each time when requested). + - Fixed a nasty typo from the previous item that caused data + corruption and occasional SEGFAULTs. + - array_from_pyobj accepts arbitrary rank arrays if the last dimension + is undefined. E.g. dimension(3,*) accepts a(3,4,5) and the result is + array with dimension(3,20). + - Fixed (void*) casts to make g++ happy (bug report: eric). + - Changed the interface of ARR_IS_NULL macro to avoid "``NULL used in + arithmetics``" warnings from g++. + +* src/fortranobject.h + + - Undone previous item. Defining NO_IMPORT_ARRAY for + src/fortranobject.c (bug report: travis) + - Ensured that PY_ARRAY_UNIQUE_SYMBOL is defined only for + src/fortranobject.c (bug report: eric). + +* rules.py + + - Introduced dummy routine feature. + - F77 and F90 wrapper subroutines (if any) as saved to different + files, <modulename>-f2pywrappers.f and <modulename>-f2pywrappers2.f90, + respectively. Therefore, wrapping F90 requires scipy_distutils >= + 0.2.0_alpha_2.229. + - Fixed compiler warnings about meaningless ``const void (*f2py_func)(..)``. + - Improved error messages for ``*_from_pyobj``. + - Changed __CPLUSPLUS__ macros to __cplusplus (bug report: eric). + - Changed (void*) casts to (f2py_init_func) (bug report: eric). + - Removed unnecessary (void*) cast for f2py_has_column_major_storage + in f2py_module_methods definition (bug report: eric). + - Changed the interface of f2py_has_column_major_storage function: + removed const from the 1st argument. + +* cfuncs.py + + - Introduced -DPREPEND_FORTRAN. + - Fixed bus error on SGI by using PyFloat_AsDouble when ``__sgi`` is defined. + This seems to be `know bug`__ with Python 2.1 and SGI. + - string_from_pyobj accepts only arrays whos elements size==sizeof(char). + - logical scalars (intent(in),function) are normalized to 0 or 1. + - Removed NUMFROMARROBJ macro. + - (char|short)_from_pyobj now use int_from_pyobj. + - (float|long_double)_from_pyobj now use double_from_pyobj. + - complex_(float|long_double)_from_pyobj now use complex_double_from_pyobj. + - Rewrote ``*_from_pyobj`` to be more robust. This fixes segfaults if + getting * from a string. Note that int_from_pyobj differs + from PyNumber_Int in that it accepts also complex arguments + (takes the real part) and sequences (takes the 1st element). + - Removed unnecessary void* casts in NUMFROMARROBJ. + - Fixed casts in ``*_from_pyobj`` functions. + - Replaced CNUMFROMARROBJ with NUMFROMARROBJ. + +.. __: http://sourceforge.net/tracker/index.php?func=detail&aid=435026&group_id=5470&atid=105470 + +* auxfuncs.py + + - Introduced isdummyroutine(). + - Fixed islong_* functions. + - Fixed isintent_in for intent(c) arguments (bug report: Pierre Schnizer). + - Introduced F2PYError and throw_error. Using throw_error, f2py + rejects illegal .pyf file constructs that otherwise would cause + compilation failures or python crashes. + - Fixed islong_long(logical*8)->True. + - Introduced islogical() and islogicalfunction(). + - Fixed prototype string argument (bug report: eric). + +* Updated README.txt and doc strings. Starting to use docutils. + +* Speed up for ``*_from_pyobj`` functions if obj is a sequence. + +* Fixed SegFault (reported by M.Braun) due to invalid ``Py_DECREF`` + in ``GETSCALARFROMPYTUPLE``. + +Older Releases +============== + +:: + + *** Fixed missing includes when wrapping F90 module data. + *** Fixed typos in docs of build_flib options. + *** Implemented prototype calculator if no callstatement or + callprotoargument statements are used. A warning is issued if + callstatement is used without callprotoargument. + *** Fixed transposing issue with array arguments in callback functions. + *** Removed -pyinc command line option. + *** Complete tests for Fortran 77 functions returning scalars. + *** Fixed returning character bug if --no-wrap-functions. + *** Described how to wrap F compiled Fortran F90 module procedures + with F2PY. See doc/using_F_compiler.txt. + *** Fixed the order of build_flib options when using --fcompiler=... + *** Recognize .f95 and .F95 files as Fortran sources with free format. + *** Cleaned up the output of 'f2py -h': removed obsolete items, + added build_flib options section. + *** Added --help-compiler option: it lists available Fortran compilers + as detected by scipy_distutils/command/build_flib.py. This option + is available only with -c option. + + +:Release: 2.13.175-1250 +:Date: 4 April 2002 + +:: + + *** Fixed copying of non-contigious 1-dimensional arrays bug. + (Thanks to Travis O.). + + +:Release: 2.13.175-1242 +:Date: 26 March 2002 + +:: + + *** Fixed ignoring type declarations. + *** Turned F2PY_REPORT_ATEXIT off by default. + *** Made MAX,MIN macros available by default so that they can be + always used in signature files. + *** Disabled F2PY_REPORT_ATEXIT for FreeBSD. + + +:Release: 2.13.175-1233 +:Date: 13 March 2002 + +:: + + *** Fixed Win32 port when using f2py.bat. (Thanks to Erik Wilsher). + *** F2PY_REPORT_ATEXIT is disabled for MACs. + *** Fixed incomplete dependency calculator. + + +:Release: 2.13.175-1222 +:Date: 3 March 2002 + +:: + + *** Plugged a memory leak for intent(out) arrays with overwrite=0. + *** Introduced CDOUBLE_to_CDOUBLE,.. functions for copy_ND_array. + These cast functions probably work incorrectly in Numeric. + + +:Release: 2.13.175-1212 +:Date: 23 February 2002 + +:: + + *** Updated f2py for the latest scipy_distutils. + *** A nasty bug with multi-dimensional Fortran arrays is fixed + (intent(out) arrays had wrong shapes). (Thanks to Eric for + pointing out this bug). + *** F2PY_REPORT_ATEXIT is disabled by default for __WIN32__. + + +:Release: 2.11.174-1161 +:Date: 14 February 2002 + +:: + + *** Updated f2py for the latest scipy_distutils. + *** Fixed raise error when f2py missed -m flag. + *** Script name `f2py' now depends on the name of python executable. + For example, `python2.2 setup.py install' will create a f2py + script with a name `f2py2.2'. + *** Introduced 'callprotoargument' statement so that proper prototypes + can be declared. This is crucial when wrapping C functions as it + will fix segmentation faults when these wrappers use non-pointer + arguments (thanks to R. Clint Whaley for explaining this to me). + Note that in f2py generated wrapper, the prototypes have + the following forms: + extern #rtype# #fortranname#(#callprotoargument#); + or + extern #rtype# F_FUNC(#fortranname#,#FORTRANNAME#)(#callprotoargument#); + *** Cosmetic fixes to F2PY_REPORT_ATEXIT feature. + + +:Release: 2.11.174-1146 +:Date: 3 February 2002 + +:: + + *** Reviewed reference counting in call-back mechanism. Fixed few bugs. + *** Enabled callstatement for complex functions. + *** Fixed bug with initializing capi_overwrite_<varname> + *** Introduced intent(overwrite) that is similar to intent(copy) but + has opposite effect. Renamed copy_<name>=1 to overwrite_<name>=0. + intent(overwrite) will make default overwrite_<name>=1. + *** Introduced intent(in|inout,out,out=<name>) attribute that renames + arguments name when returned. This renaming has effect only in + documentation strings. + *** Introduced 'callstatement' statement to pyf file syntax. With this + one can specify explicitly how wrapped function should be called + from the f2py generated module. WARNING: this is a dangerous feature + and should be used with care. It is introduced to provide a hack + to construct wrappers that may have very different signature + pattern from the wrapped function. Currently 'callstatement' can + be used only inside a subroutine or function block (it should be enough + though) and must be only in one continuous line. The syntax of the + statement is: callstatement <C-expression>; + + +:Release: 2.11.174 +:Date: 18 January 2002 + +:: + + *** Fixed memory-leak for PyFortranObject. + *** Introduced extra keyword argument copy_<varname> for intent(copy) + variables. It defaults to 1 and forces to make a copy for + intent(in) variables when passing on to wrapped functions (in case + they undesirably change the variable in-situ). + *** Introduced has_column_major_storage member function for all f2py + generated extension modules. It is equivalent to Python call + 'transpose(obj).iscontiguous()' but very efficient. + *** Introduced -DF2PY_REPORT_ATEXIT. If this is used when compiling, + a report is printed to stderr as python exits. The report includes + the following timings: + 1) time spent in all wrapped function calls; + 2) time spent in f2py generated interface around the wrapped + functions. This gives a hint whether one should worry + about storing data in proper order (C or Fortran). + 3) time spent in Python functions called by wrapped functions + through call-back interface. + 4) time spent in f2py generated call-back interface. + For now, -DF2PY_REPORT_ATEXIT is enabled by default. Use + -DF2PY_REPORT_ATEXIT_DISABLE to disable it (I am not sure if + Windows has needed tools, let me know). + Also, I appreciate if you could send me the output of 'F2PY + performance report' (with CPU and platform information) so that I + could optimize f2py generated interfaces for future releases. + *** Extension modules can be linked with dmalloc library. Use + -DDMALLOC when compiling. + *** Moved array_from_pyobj to fortranobject.c. + *** Usage of intent(inout) arguments is made more strict -- only + with proper type contiguous arrays are accepted. In general, + you should avoid using intent(inout) attribute as it makes + wrappers of C and Fortran functions asymmetric. I recommend using + intent(in,out) instead. + *** intent(..) has new keywords: copy,cache. + intent(copy,in) - forces a copy of an input argument; this + may be useful for cases where the wrapped function changes + the argument in situ and this may not be desired side effect. + Otherwise, it is safe to not use intent(copy) for the sake + of a better performance. + intent(cache,hide|optional) - just creates a junk of memory. + It does not care about proper storage order. Can be also + intent(in) but then the corresponding argument must be a + contiguous array with a proper elsize. + *** intent(c) can be used also for subroutine names so that + -DNO_APPEND_FORTRAN can be avoided for C functions. + + *** IMPORTANT BREAKING GOOD ... NEWS!!!: + + From now on you don't have to worry about the proper storage order + in multi-dimensional arrays that was earlier a real headache when + wrapping Fortran functions. Now f2py generated modules take care + of the proper conversations when needed. I have carefully designed + and optimized this interface to avoid any unnecessary memory usage + or copying of data. However, it is wise to use input arrays that + has proper storage order: for C arguments it is row-major and for + Fortran arguments it is column-major. But you don't need to worry + about that when developing your programs. The optimization of + initializing the program with proper data for possibly better + memory usage can be safely postponed until the program is working. + + This change also affects the signatures in .pyf files. If you have + created wrappers that take multi-dimensional arrays in arguments, + it is better to let f2py re-generate these files. Or you have to + manually do the following changes: reverse the axes indices in all + 'shape' macros. For example, if you have defined an array A(n,m) + and n=shape(A,1), m=shape(A,0) then you must change the last + statements to n=shape(A,0), m=shape(A,1). + + +:Release: 2.8.172 +:Date: 13 January 2002 + +:: + + *** Fixed -c process. Removed pyf_extensions function and pyf_file class. + *** Reorganized setup.py. It generates f2py or f2py.bat scripts + depending on the OS and the location of the python executable. + *** Started to use update_version from scipy_distutils that makes + f2py startup faster. As a side effect, the version number system + changed. + *** Introduced test-site/test_f2py2e.py script that runs all + tests. + *** Fixed global variables initialization problem in crackfortran + when run_main is called several times. + *** Added 'import Numeric' to C/API init<module> function. + *** Fixed f2py.bat in setup.py. + *** Switched over to scipy_distutils and dropped fortran_support. + *** On Windows create f2py.bat file. + *** Introduced -c option: read fortran or pyf files, construct extension + modules, build, and save them to current directory. + In one word: do-it-all-in-one-call. + *** Introduced pyf_extensions(sources,f2py_opts) function. It simplifies + the extension building process considerably. Only for internal use. + *** Converted tests to use scipy_distutils in order to improve portability: + a,b,c + *** f2py2e.run_main() returns a pyf_file class instance containing + information about f2py generated files. + *** Introduced `--build-dir <dirname>' command line option. + *** Fixed setup.py for bdist_rpm command. + *** Added --scipy-setup command line option. + *** Fixed crackfortran that did not recognized capitalized type + specification with --no-lower flag. + *** `-h stdout' writes signature to stdout. + *** Fixed incorrect message for check() with empty name list. + + +:Release: 2.4.366 +:Date: 17 December 2001 + +:: + + *** Added command line option --[no-]manifest. + *** `make test' should run on Windows, but the results are not truthful. + *** Reorganized f2py2e.py a bit. Introduced run_main(comline_list) function + that can be useful when running f2py from another Python module. + *** Removed command line options -f77,-fix,-f90 as the file format + is determined from the extension of the fortran file + or from its header (first line starting with `!%' and containing keywords + free, fix, or f77). The later overrides the former one. + *** Introduced command line options --[no-]makefile,--[no-]latex-doc. + Users must explicitly use --makefile,--latex-doc if Makefile-<modulename>, + <modulename>module.tex is desired. --setup is default. Use --no-setup + to disable setup_<modulename>.py generation. --overwrite-makefile + will set --makefile. + *** Added `f2py_rout_' to #capiname# in rules.py. + *** intent(...) statement with empty namelist forces intent(...) attribute for + all arguments. + *** Dropped DL_IMPORT and DL_EXPORT in fortranobject.h. + *** Added missing PyFortran_Type.ob_type initialization. + *** Added gcc-3.0 support. + *** Raising non-existing/broken Numeric as a FatalError exception. + *** Fixed Python 2.x specific += construct in fortran_support.py. + *** Fixed copy_ND_array for 1-rank arrays that used to call calloc(0,..) + and caused core dump with a non-gcc compiler (Thanks to Pierre Schnizer + for reporting this bug). + *** Fixed "warning: variable `..' might be clobbered by `longjmp' or `vfork'": + - Reorganized the structure of wrapper functions to get rid of + `goto capi_fail' statements that caused the above warning. + + +:Release: 2.3.343 +:Date: 12 December 2001 + +:: + + *** Issues with the Win32 support (thanks to Eric Jones and Tiffany Kamm): + - Using DL_EXPORT macro for init#modulename#. + - Changed PyObject_HEAD_INIT(&PyType_Type) to PyObject_HEAD_INIT(0). + - Initializing #name#_capi=NULL instead of Py_None in cb hooks. + *** Fixed some 'warning: function declaration isn't a prototype', mainly + in fortranobject.{c,h}. + *** Fixed 'warning: missing braces around initializer'. + *** Fixed reading a line containing only a label. + *** Fixed nonportable 'cp -fv' to shutil.copy in f2py2e.py. + *** Replaced PyEval_CallObject with PyObject_CallObject in cb_rules. + *** Replaced Py_DECREF with Py_XDECREF when freeing hidden arguments. + (Reason: Py_DECREF caused segfault when an error was raised) + *** Impl. support for `include "file"' (in addition to `include 'file'') + *** Fixed bugs (buildsetup.py missing in Makefile, in generated MANIFEST.in) + + +:Release: 2.3.327 +:Date: 4 December 2001 + +:: + + *** Sending out the third public release of f2py. + *** Support for Intel(R) Fortran Compiler (thanks to Patrick LeGresley). + *** Introduced `threadsafe' statement to pyf-files (or to be used with + the 'f2py' directive in fortran codes) to force + Py_BEGIN|END_ALLOW_THREADS block around the Fortran subroutine + calling statement in Python C/API. `threadsafe' statement has + an effect only inside a subroutine block. + *** Introduced `fortranname <name>' statement to be used only within + pyf-files. This is useful when the wrapper (Python C/API) function + has different name from the wrapped (Fortran) function. + *** Introduced `intent(c)' directive and statement. It is useful when + wrapping C functions. Use intent(c) for arguments that are + scalars (not pointers) or arrays (with row-ordering of elements). + + +:Release: 2.3.321 +:Date: 3 December 2001 + +:: + + *** f2py2e can be installed using distutils (run `python setup.py install'). + *** f2py builds setup_<modulename>.py. Use --[no-]setup to control this + feature. setup_<modulename>.py uses fortran_support module (from SciPy), + but for your convenience it is included also with f2py as an additional + package. Note that it has not as many compilers supported as with + using Makefile-<modulename>, but new compilers should be added to + fortran_support module, not to f2py2e package. + *** Fixed some compiler warnings about else statements. + diff --git a/numpy/f2py/docs/OLDNEWS.txt b/numpy/f2py/docs/OLDNEWS.txt new file mode 100644 index 000000000..b21215464 --- /dev/null +++ b/numpy/f2py/docs/OLDNEWS.txt @@ -0,0 +1,63 @@ + +.. topic:: Old F2PY NEWS + + March 30, 2004 + F2PY bug fix release (version 2.39.235-1693). Two new command line switches: + ``--compiler`` and ``--include_paths``. Support for allocatable string arrays. + Callback arguments may now be arbitrary callable objects. Win32 installers + for F2PY and Scipy_core are provided. + `Differences with the previous release (version 2.37.235-1660)`__. + + __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.98&r2=1.87&f=h + + + March 9, 2004 + F2PY bug fix release (version 2.39.235-1660). + `Differences with the previous release (version 2.37.235-1644)`__. + + __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.87&r2=1.83&f=h + + February 24, 2004 + Latest F2PY release (version 2.39.235-1644). + Support for scipy_distutils 0.2.2 and up (e.g. compiler flags can be + changed via f2py command line options). Implemented support for + character arrays and arrays of strings (e.g. ``character*(*) a(m,..)``). + *Important bug fixes regarding complex arguments, upgrading is + highly recommended*. Documentation updates. + `Differences with the previous release (version 2.37.233-1545)`__. + + __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.83&r2=1.58&f=h + + September 11, 2003 + Latest F2PY release (version 2.37.233-1545). + New statements: ``pymethoddef`` and ``usercode`` in interface blocks. + New function: ``as_column_major_storage``. + New CPP macro: ``F2PY_REPORT_ON_ARRAY_COPY``. + Bug fixes. + `Differences with the previous release (version 2.35.229-1505)`__. + + __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.58&r2=1.49&f=h + + August 2, 2003 + Latest F2PY release (version 2.35.229-1505). + `Differences with the previous release (version 2.32.225-1419)`__. + + __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.49&r2=1.28&f=h + + April 2, 2003 + Initial support for Numarray_ (thanks to Todd Miller). + + December 8, 2002 + Sixth public release of F2PY (version 2.32.225-1419). Comes with + revised `F2PY Users Guide`__, `new testing site`__, lots of fixes + and other improvements, see `HISTORY.txt`_ for details. + + __ usersguide/index.html + __ TESTING.txt_ + +.. References + ========== + +.. _HISTORY.txt: HISTORY.html +.. _Numarray: http://www.stsci.edu/resources/software_hardware/numarray +.. _TESTING.txt: TESTING.html
\ No newline at end of file diff --git a/numpy/f2py/docs/README.txt b/numpy/f2py/docs/README.txt new file mode 100644 index 000000000..fc7149645 --- /dev/null +++ b/numpy/f2py/docs/README.txt @@ -0,0 +1,457 @@ +.. -*- rest -*- + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + F2PY: Fortran to Python interface generator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:Author: Pearu Peterson <pearu@cens.ioc.ee> +:License: LGPL_. +: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 + +------------------------------- + +.. topic:: NEWS!!! + + January 30, 2005 + + Latest F2PY release (version 2.45.241_1926). + New features: wrapping unsigned integers, support for ``.pyf.src`` template files, + callback arguments can now be CObjects, fortran objects, built-in functions. + Introduced ``intent(aux)`` attribute. Wrapped objects have ``_cpointer`` + attribute holding C pointer to wrapped functions or variables. + Many bug fixes and improvements, updated documentation. + `Differences with the previous release (version 2.43.239_1831)`__. + + __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.163&r2=1.137&f=h + + October 4, 2004 + F2PY bug fix release (version 2.43.239_1831). + Better support for 64-bit platforms. + Introduced ``--help-link`` and ``--link-<resource>`` options. + Bug fixes. + `Differences with the previous release (version 2.43.239_1806)`__. + + __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.137&r2=1.131&f=h + + September 25, 2004 + Latest F2PY release (version 2.43.239_1806). + Support for ``ENTRY`` statement. New attributes: + ``intent(inplace)``, ``intent(callback)``. Supports Numarray 1.1. + Introduced ``-*- fix -*-`` header content. Improved ``PARAMETER`` support. + Documentation updates. `Differences with the previous release + (version 2.39.235-1693)`__. + + __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.131&r2=1.98&f=h + + `History of NEWS`__ + + __ OLDNEWS.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 ``scipy_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 scipy_distutils +releases as: + +* `2.x`__/`F2PY-2-latest.tar.gz`__ +* `2.x`__/`scipy_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`__/`scipy_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/scipy_distutils-latest.tar.gz +.. __: 2.x/ +.. __: 2.x/F2PY-2-latest.win32.exe +.. __: 2.x/ +.. __: 2.x/scipy_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 ``scipy_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`_ (in CVS__) + The first thing to read about F2PY -- this document. + +__ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/README.txt?rev=HEAD&content-type=text/x-cvsweb-markup + +`usersguide/index.txt`_, `usersguide/f2py_usersguide.pdf`_ + F2PY Users Guide and Reference Manual. Contains lots of examples. + +`FAQ.txt`_ (in CVS__) + F2PY Frequently Asked Questions. + +__ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/FAQ.txt?rev=HEAD&content-type=text/x-cvsweb-markup + +`TESTING.txt`_ (in CVS__) + About F2PY testing site. What tests are available and how to run them. + +__ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/TESTING.txt?rev=HEAD&content-type=text/x-cvsweb-markup + +`HISTORY.txt`_ (in CVS__) + A list of latest changes in F2PY. This is the most up-to-date + document on F2PY. + +__ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt?rev=HEAD&content-type=text/x-cvsweb-markup + +`THANKS.txt`_ + Acknowledgments. + +.. + `COMPILERS.txt`_ + Compiler and platform specific notes. + +=============== + Mailing list +=============== + +A mailing list f2py-users@cens.ioc.ee 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:anonymous@cens.ioc.ee:/home/cvs login + +2) and then do the checkout:: + + cvs -z6 -d :pserver:anonymous@cens.ioc.ee:/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.scipy.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/ +.. _LGPL: http://www.fsf.org/copyleft/lesser.html +.. _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: diff --git a/numpy/f2py/docs/TESTING.txt b/numpy/f2py/docs/TESTING.txt new file mode 100644 index 000000000..feae18dc6 --- /dev/null +++ b/numpy/f2py/docs/TESTING.txt @@ -0,0 +1,108 @@ + +======================================================= + F2PY unit testing site +======================================================= + +.. Contents:: + +Tests +----- + +* To run all F2PY unit tests in one command:: + + cd tests + python run_all.py [<options>] + + For example:: + + localhost:~/src_cvs/f2py2e/tests$ python2.2 run_all.py 100 --quiet + ********************************************** + Running '/usr/bin/python2.2 f77/return_integer.py 100 --quiet' + run 1000 tests in 1.87 seconds + initial virtual memory size: 3952640 bytes + current virtual memory size: 3952640 bytes + ok + ********************************************** + Running '/usr/bin/python2.2 f77/return_logical.py 100 --quiet' + run 1000 tests in 1.47 seconds + initial virtual memory size: 3952640 bytes + current virtual memory size: 3952640 bytes + ok + ... + + If some tests fail, try to run the failing tests separately (without + the ``--quiet`` option) as described below to get more information + about the failure. + +* Test intent(in), intent(out) scalar arguments, + scalars returned by F77 functions + and F90 module functions:: + + tests/f77/return_integer.py + tests/f77/return_real.py + tests/f77/return_logical.py + tests/f77/return_complex.py + tests/f77/return_character.py + tests/f90/return_integer.py + tests/f90/return_real.py + tests/f90/return_logical.py + tests/f90/return_complex.py + tests/f90/return_character.py + + Change to tests/ directory and run:: + + python f77/return_<type>.py [<options>] + python f90/return_<type>.py [<options>] + + where ``<type>`` is integer, real, logical, complex, or character. + Test scripts options are described below. + + A test is considered succesful if the last printed line is "ok". + + If you get import errors like:: + + ImportError: No module named f77_ext_return_integer + + but ``f77_ext_return_integer.so`` exists in the current directory then + it means that the current directory is not included in to `sys.path` + in your Python installation. As a fix, prepend ``.`` to ``PYTHONPATH`` + environment variable and rerun the tests. For example:: + + PYTHONPATH=. python f77/return_integer.py + +* Test mixing Fortran 77, Fortran 90 fixed and free format codes:: + + tests/mixed/run.py + +* Test basic callback hooks:: + + tests/f77/callback.py + +Options +------- + +You may want to use the following options when running the test +scripts: + +``<integer>`` + Run tests ``<integer>`` times. Useful for detecting memory leaks. Under + Linux tests scripts output virtual memory size state of the process + before and after calling the wrapped functions. + +``--quiet`` + Suppress all messages. On success only "ok" should be displayed. + +``--fcompiler=<Gnu|Intel|...>`` + Use:: + + f2py -c --help-fcompiler + + to find out what compilers are available (or more precisely, which + ones are recognized by ``scipy_distutils``). + +Reporting failures +------------------ + +XXX: (1) make sure that failures are due to f2py and (2) send full +stdout/stderr messages to me. Also add compiler,python,platform +information. diff --git a/numpy/f2py/docs/THANKS.txt b/numpy/f2py/docs/THANKS.txt new file mode 100644 index 000000000..cbaa083fc --- /dev/null +++ b/numpy/f2py/docs/THANKS.txt @@ -0,0 +1,63 @@ + +================= + Acknowledgments +================= + +F2PY__ is a LGPL'd Python package and command line tool developed and +maintained by Pearu Peterson (me__). + +.. __: http://cens.ioc.ee/projects/f2py2e/ +.. __: http://cens.ioc.ee/~pearu/ + +Many people have contributed to the F2PY project in terms of interest, +encouragement, suggestions, criticism, bug reports, code +contributions, and keeping me busy with developing F2PY. For all that +I thank + + James Amundson, John Barnard, David Beazley, Frank Bertoldi, Roman + Bertle, James Boyle, Moritz Braun, Rolv Erlend Bredesen, John + Chaffer, Fred Clare, Adam Collard, Ben Cornett, Jose L Gomez Dans, + Jaime D. Perea Duarte, Paul F Dubois, Thilo Ernst, Bonilla Fabian, + Martin Gelfand, Eduardo A. Gonzalez, Siegfried Gonzi, Bernhard + Gschaider, Charles Doutriaux, Jeff Hagelberg, Janko Hauser, Thomas + Hauser, Heiko Henkelmann, William Henney, Yueqiang Huang, Asim + Hussain, Berthold Höllmann, Vladimir Janku, Henk Jansen, Curtis + Jensen, Eric Jones, Tiffany Kamm, Andrey Khavryuchenko, Greg + Kochanski, Jochen Küpper, Simon Lacoste-Julien, Tim Lahey, Hans + Petter Langtangen, Jeff Layton, Matthew Lewis, Patrick LeGresley, + Joaquim R R A Martins, Paul Magwene Lionel Maziere, Craig McNeile, + Todd Miller, David C. Morrill, Dirk Muders, Kevin Mueller, Andrew + Mullhaupt, Vijayendra Munikoti, Travis Oliphant, Kevin O'Mara, Arno + Paehler, Fernando Perez, Didrik Pinte, Todd Alan Pitts, Prabhu + Ramachandran, Brad Reisfeld, Steve M. Robbins, Theresa Robinson, + Pedro Rodrigues, Les Schaffer, Christoph Scheurer, Herb Schilling, + Pierre Schnizer, Kevin Smith, Paulo Teotonio Sobrinho, José Rui + Faustino de Sousa, Andrew Swan, Dustin Tang, Charlie Taylor, Paul le + Texier, Michael Tiller, Semen Trygubenko, Ravi C Venkatesan, Peter + Verveer, Nils Wagner, R. Clint Whaley, Erik Wilsher, Martin + Wiechert, Gilles Zerah, SungPil Yoon. + +(This list may not be complete. Please forgive me if I have left you +out and let me know, I'll add your name.) + +Special thanks are due to ... + +Eric Jones - he and Travis O. are responsible for starting the +scipy_distutils project that allowed to move most of the platform and +compiler specific codes out from F2PY. This simplified maintaining the +F2PY project considerably. + +Joaquim R R A Martins - he made possible for me to test F2PY on IRIX64 +platform. He also presented our paper about F2PY in the 9th Python +Conference that I planned to attend but had to cancel in very last +minutes. + +Travis Oliphant - his knowledge and experience on Numerical Python +C/API has been invaluable in early development of the F2PY program. +His major contributions are call-back mechanism and copying N-D arrays +of arbitrary types. + +Todd Miller - he is responsible for Numarray support in F2PY. + +Thanks! + Pearu diff --git a/numpy/f2py/docs/default.css b/numpy/f2py/docs/default.css new file mode 100644 index 000000000..9289e2826 --- /dev/null +++ b/numpy/f2py/docs/default.css @@ -0,0 +1,180 @@ +/* +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:date: $Date: 2002/08/01 20:52:44 $ +:version: $Revision: 1.1 $ +:copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. +*/ + +body { + background: #FFFFFF ; + color: #000000 +} + +a.footnote-reference { + font-size: smaller ; + vertical-align: super } + +a.target { + color: blue } + +a.toc-backref { + text-decoration: none ; + color: black } + +dd { + margin-bottom: 0.5em } + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.attention, div.caution, div.danger, div.error, div.hint, +div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +div.hint p.admonition-title, div.important p.admonition-title, +div.note p.admonition-title, div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em } + +div.footer, div.header { + font-size: smaller } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr { + width: 75% } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.first { + margin-top: 0 } + +p.label { + white-space: nowrap } + +p.topic-title { + font-weight: bold } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em ; + background-color: #eeeeee } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.field-argument { + font-style: italic } + +span.interpreted { + font-family: sans-serif } + +span.option-argument { + font-style: italic } + +span.problematic { + color: red } + +table { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.citation { + border-left: solid thin gray ; + padding-left: 0.5ex } + +table.docinfo { + margin: 2em 4em } + +table.footnote { + border-left: solid thin black ; + padding-left: 0.5ex } + +td, th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: baseline } + +td.docinfo-name { + font-weight: bold ; + text-align: right } + +td.field-name { + font-weight: bold } diff --git a/numpy/f2py/docs/docutils.conf b/numpy/f2py/docs/docutils.conf new file mode 100644 index 000000000..4e5a8425b --- /dev/null +++ b/numpy/f2py/docs/docutils.conf @@ -0,0 +1,16 @@ +[general] + +# These entries affect all processing: +#source-link: 1 +datestamp: %Y-%m-%d %H:%M UTC +generator: 1 + +# These entries affect HTML output: +#stylesheet-path: pearu_style.css +output-encoding: latin-1 + +# These entries affect reStructuredText-style PEPs: +#pep-template: pep-html-template +#pep-stylesheet-path: stylesheets/pep.css +#python-home: http://www.python.org +#no-random: 1 diff --git a/numpy/f2py/docs/hello.f b/numpy/f2py/docs/hello.f new file mode 100644 index 000000000..3e0dc6d21 --- /dev/null +++ b/numpy/f2py/docs/hello.f @@ -0,0 +1,7 @@ +C File hello.f + subroutine foo (a) + integer a + print*, "Hello from Fortran!" + print*, "a=",a + end + diff --git a/numpy/f2py/docs/pyforttest.pyf b/numpy/f2py/docs/pyforttest.pyf new file mode 100644 index 000000000..79a9ae205 --- /dev/null +++ b/numpy/f2py/docs/pyforttest.pyf @@ -0,0 +1,5 @@ +subroutine foo(a,m,n) +integer m = size(a,1) +integer n = size(a,2) +real, intent(inout) :: a(m,n) +end subroutine foo diff --git a/numpy/f2py/docs/pytest.py b/numpy/f2py/docs/pytest.py new file mode 100644 index 000000000..abd3487df --- /dev/null +++ b/numpy/f2py/docs/pytest.py @@ -0,0 +1,10 @@ +#File: pytest.py +import Numeric +def foo(a): + a = Numeric.array(a) + m,n = a.shape + for i in range(m): + for j in range(n): + a[i,j] = a[i,j] + 10*(i+1) + (j+1) + return a +#eof diff --git a/numpy/f2py/docs/simple.f b/numpy/f2py/docs/simple.f new file mode 100644 index 000000000..ba468a509 --- /dev/null +++ b/numpy/f2py/docs/simple.f @@ -0,0 +1,13 @@ +cFile: simple.f + subroutine foo(a,m,n) + integer m,n,i,j + real a(m,n) +cf2py intent(in,out) a +cf2py intent(hide) m,n + do i=1,m + do j=1,n + a(i,j) = a(i,j) + 10*i+j + enddo + enddo + end +cEOF diff --git a/numpy/f2py/docs/simple_session.dat b/numpy/f2py/docs/simple_session.dat new file mode 100644 index 000000000..10d9dc962 --- /dev/null +++ b/numpy/f2py/docs/simple_session.dat @@ -0,0 +1,51 @@ +>>> import pytest +>>> import f2pytest +>>> import pyforttest +>>> print f2pytest.foo.__doc__ +foo - Function signature: + a = foo(a) +Required arguments: + a : input rank-2 array('f') with bounds (m,n) +Return objects: + a : rank-2 array('f') with bounds (m,n) + +>>> print pyforttest.foo.__doc__ +foo(a) + +>>> pytest.foo([[1,2],[3,4]]) +array([[12, 14], + [24, 26]]) +>>> f2pytest.foo([[1,2],[3,4]]) # F2PY can handle arbitrary input sequences +array([[ 12., 14.], + [ 24., 26.]],'f') +>>> pyforttest.foo([[1,2],[3,4]]) +Traceback (most recent call last): + File "<stdin>", line 1, in ? +pyforttest.error: foo, argument A: Argument intent(inout) must be an array. + +>>> import Numeric +>>> a=Numeric.array([[1,2],[3,4]],'f') +>>> f2pytest.foo(a) +array([[ 12., 14.], + [ 24., 26.]],'f') +>>> a # F2PY makes a copy when input array is not Fortran contiguous +array([[ 1., 2.], + [ 3., 4.]],'f') +>>> a=Numeric.transpose(Numeric.array([[1,3],[2,4]],'f')) +>>> a +array([[ 1., 2.], + [ 3., 4.]],'f') +>>> f2pytest.foo(a) +array([[ 12., 14.], + [ 24., 26.]],'f') +>>> a # F2PY passes Fortran contiguous input array directly to Fortran +array([[ 12., 14.], + [ 24., 26.]],'f') +# See intent(copy), intent(overwrite), intent(inplace), intent(inout) +# attributes documentation to enhance the above behavior. + +>>> a=Numeric.array([[1,2],[3,4]],'f') +>>> pyforttest.foo(a) +>>> a # Huh? Pyfort 8.5 gives wrong results.. +array([[ 12., 23.], + [ 15., 26.]],'f') diff --git a/numpy/f2py/docs/usersguide/allocarr.f90 b/numpy/f2py/docs/usersguide/allocarr.f90 new file mode 100644 index 000000000..e0d6c2ec8 --- /dev/null +++ b/numpy/f2py/docs/usersguide/allocarr.f90 @@ -0,0 +1,16 @@ +module mod + real, allocatable, dimension(:,:) :: b +contains + subroutine foo + integer k + if (allocated(b)) then + print*, "b=[" + do k = 1,size(b,1) + print*, b(k,1:size(b,2)) + enddo + print*, "]" + else + print*, "b is not allocated" + endif + end subroutine foo +end module mod diff --git a/numpy/f2py/docs/usersguide/allocarr_session.dat b/numpy/f2py/docs/usersguide/allocarr_session.dat new file mode 100644 index 000000000..fc91959b7 --- /dev/null +++ b/numpy/f2py/docs/usersguide/allocarr_session.dat @@ -0,0 +1,27 @@ +>>> import allocarr +>>> print allocarr.mod.__doc__ +b - 'f'-array(-1,-1), not allocated +foo - Function signature: + foo() + +>>> allocarr.mod.foo() + b is not allocated +>>> allocarr.mod.b = [[1,2,3],[4,5,6]] # allocate/initialize b +>>> allocarr.mod.foo() + b=[ + 1.000000 2.000000 3.000000 + 4.000000 5.000000 6.000000 + ] +>>> allocarr.mod.b # b is Fortran-contiguous +array([[ 1., 2., 3.], + [ 4., 5., 6.]],'f') +>>> allocarr.mod.b = [[1,2,3],[4,5,6],[7,8,9]] # reallocate/initialize b +>>> allocarr.mod.foo() + b=[ + 1.000000 2.000000 3.000000 + 4.000000 5.000000 6.000000 + 7.000000 8.000000 9.000000 + ] +>>> allocarr.mod.b = None # deallocate array +>>> allocarr.mod.foo() + b is not allocated diff --git a/numpy/f2py/docs/usersguide/array.f b/numpy/f2py/docs/usersguide/array.f new file mode 100644 index 000000000..ef20c9c20 --- /dev/null +++ b/numpy/f2py/docs/usersguide/array.f @@ -0,0 +1,17 @@ +C FILE: ARRAY.F + SUBROUTINE FOO(A,N,M) +C +C INCREMENT THE FIRST ROW AND DECREMENT THE FIRST COLUMN OF A +C + INTEGER N,M,I,J + REAL*8 A(N,M) +Cf2py intent(in,out,copy) a +Cf2py integer intent(hide),depend(a) :: n=shape(a,0), m=shape(a,1) + DO J=1,M + A(1,J) = A(1,J) + 1D0 + ENDDO + DO I=1,N + A(I,1) = A(I,1) - 1D0 + ENDDO + END +C END OF FILE ARRAY.F diff --git a/numpy/f2py/docs/usersguide/array_session.dat b/numpy/f2py/docs/usersguide/array_session.dat new file mode 100644 index 000000000..f64933482 --- /dev/null +++ b/numpy/f2py/docs/usersguide/array_session.dat @@ -0,0 +1,65 @@ +>>> import arr +>>> from Numeric import array +>>> print arr.foo.__doc__ +foo - Function signature: + a = foo(a,[overwrite_a]) +Required arguments: + a : input rank-2 array('d') with bounds (n,m) +Optional arguments: + overwrite_a := 0 input int +Return objects: + a : rank-2 array('d') with bounds (n,m) + +>>> a=arr.foo([[1,2,3], +... [4,5,6]]) +copied an array using PyArray_CopyFromObject: size=6, elsize=8 +>>> print a +[[ 1. 3. 4.] + [ 3. 5. 6.]] +>>> a.iscontiguous(), arr.has_column_major_storage(a) +(0, 1) +>>> b=arr.foo(a) # even if a is proper-contiguous +... # and has proper type, a copy is made +... # forced by intent(copy) attribute +... # to preserve its original contents +... +copied an array using copy_ND_array: size=6, elsize=8 +>>> print a +[[ 1. 3. 4.] + [ 3. 5. 6.]] +>>> print b +[[ 1. 4. 5.] + [ 2. 5. 6.]] +>>> b=arr.foo(a,overwrite_a=1) # a is passed directly to Fortran +... # routine and its contents is discarded +... +>>> print a +[[ 1. 4. 5.] + [ 2. 5. 6.]] +>>> print b +[[ 1. 4. 5.] + [ 2. 5. 6.]] +>>> a is b # a and b are acctually the same objects +1 +>>> print arr.foo([1,2,3]) # different rank arrays are allowed +copied an array using PyArray_CopyFromObject: size=3, elsize=8 +[ 1. 1. 2.] +>>> print arr.foo([[[1],[2],[3]]]) +copied an array using PyArray_CopyFromObject: size=3, elsize=8 +[ [[ 1.] + [ 3.] + [ 4.]]] +>>> +>>> # Creating arrays with column major data storage order: +... +>>> s = arr.as_column_major_storage(array([[1,2,3],[4,5,6]])) +copied an array using copy_ND_array: size=6, elsize=4 +>>> arr.has_column_major_storage(s) +1 +>>> print s +[[1 2 3] + [4 5 6]] +>>> s2 = arr.as_column_major_storage(s) +>>> s2 is s # an array with column major storage order + # is returned immediately +1
\ No newline at end of file diff --git a/numpy/f2py/docs/usersguide/calculate.f b/numpy/f2py/docs/usersguide/calculate.f new file mode 100644 index 000000000..1cda1c8dd --- /dev/null +++ b/numpy/f2py/docs/usersguide/calculate.f @@ -0,0 +1,14 @@ + subroutine calculate(x,n) +cf2py intent(callback) func + external func +c The following lines define the signature of func for F2PY: +cf2py real*8 y +cf2py y = func(y) +c +cf2py intent(in,out,copy) x + integer n,i + real*8 x(n) + do i=1,n + x(i) = func(x(i)) + end do + end diff --git a/numpy/f2py/docs/usersguide/calculate_session.dat b/numpy/f2py/docs/usersguide/calculate_session.dat new file mode 100644 index 000000000..2fe64f522 --- /dev/null +++ b/numpy/f2py/docs/usersguide/calculate_session.dat @@ -0,0 +1,6 @@ +>>> import foo +>>> foo.calculate(range(5), lambda x: x*x) +array([ 0., 1., 4., 9., 16.]) +>>> import math +>>> foo.calculate(range(5), math.exp) +array([ 1. , 2.71828175, 7.38905621, 20.08553696, 54.59814835]) diff --git a/numpy/f2py/docs/usersguide/callback.f b/numpy/f2py/docs/usersguide/callback.f new file mode 100644 index 000000000..6e9bfb920 --- /dev/null +++ b/numpy/f2py/docs/usersguide/callback.f @@ -0,0 +1,12 @@ +C FILE: CALLBACK.F + SUBROUTINE FOO(FUN,R) + EXTERNAL FUN + INTEGER I + REAL*8 R +Cf2py intent(out) r + R = 0D0 + DO I=-5,5 + R = R + FUN(I) + ENDDO + END +C END OF FILE CALLBACK.F diff --git a/numpy/f2py/docs/usersguide/callback2.pyf b/numpy/f2py/docs/usersguide/callback2.pyf new file mode 100644 index 000000000..3d77eed24 --- /dev/null +++ b/numpy/f2py/docs/usersguide/callback2.pyf @@ -0,0 +1,19 @@ +! -*- f90 -*- +python module __user__routines + interface + function fun(i) result (r) + integer :: i + real*8 :: r + end function fun + end interface +end python module __user__routines + +python module callback2 + interface + subroutine foo(f,r) + use __user__routines, f=>fun + external f + real*8 intent(out) :: r + end subroutine foo + end interface +end python module callback2 diff --git a/numpy/f2py/docs/usersguide/callback_session.dat b/numpy/f2py/docs/usersguide/callback_session.dat new file mode 100644 index 000000000..cd2f26084 --- /dev/null +++ b/numpy/f2py/docs/usersguide/callback_session.dat @@ -0,0 +1,23 @@ +>>> import callback +>>> print callback.foo.__doc__ +foo - Function signature: + r = foo(fun,[fun_extra_args]) +Required arguments: + fun : call-back function +Optional arguments: + fun_extra_args := () input tuple +Return objects: + r : float +Call-back functions: + def fun(i): return r + Required arguments: + i : input int + Return objects: + r : float + +>>> def f(i): return i*i +... +>>> print callback.foo(f) +110.0 +>>> print callback.foo(lambda i:1) +11.0 diff --git a/numpy/f2py/docs/usersguide/common.f b/numpy/f2py/docs/usersguide/common.f new file mode 100644 index 000000000..b098ab20c --- /dev/null +++ b/numpy/f2py/docs/usersguide/common.f @@ -0,0 +1,13 @@ +C FILE: COMMON.F + SUBROUTINE FOO + INTEGER I,X + REAL A + COMMON /DATA/ I,X(4),A(2,3) + PRINT*, "I=",I + PRINT*, "X=[",X,"]" + PRINT*, "A=[" + PRINT*, "[",A(1,1),",",A(1,2),",",A(1,3),"]" + PRINT*, "[",A(2,1),",",A(2,2),",",A(2,3),"]" + PRINT*, "]" + END +C END OF COMMON.F diff --git a/numpy/f2py/docs/usersguide/common_session.dat b/numpy/f2py/docs/usersguide/common_session.dat new file mode 100644 index 000000000..846fdaa07 --- /dev/null +++ b/numpy/f2py/docs/usersguide/common_session.dat @@ -0,0 +1,27 @@ +>>> import common +>>> print common.data.__doc__ +i - 'i'-scalar +x - 'i'-array(4) +a - 'f'-array(2,3) + +>>> common.data.i = 5 +>>> common.data.x[1] = 2 +>>> common.data.a = [[1,2,3],[4,5,6]] +>>> common.foo() + I= 5 + X=[ 0 2 0 0] + A=[ + [ 1., 2., 3.] + [ 4., 5., 6.] + ] +>>> common.data.a[1] = 45 +>>> common.foo() + I= 5 + X=[ 0 2 0 0] + A=[ + [ 1., 2., 3.] + [ 45., 45., 45.] + ] +>>> common.data.a # a is Fortran-contiguous +array([[ 1., 2., 3.], + [ 45., 45., 45.]],'f') diff --git a/numpy/f2py/docs/usersguide/compile_session.dat b/numpy/f2py/docs/usersguide/compile_session.dat new file mode 100644 index 000000000..0d8408198 --- /dev/null +++ b/numpy/f2py/docs/usersguide/compile_session.dat @@ -0,0 +1,11 @@ +>>> import f2py2e +>>> fsource = ''' +... subroutine foo +... print*, "Hello world!" +... end +... ''' +>>> f2py2e.compile(fsource,modulename='hello',verbose=0) +0 +>>> import hello +>>> hello.foo() + Hello world! diff --git a/numpy/f2py/docs/usersguide/default.css b/numpy/f2py/docs/usersguide/default.css new file mode 100644 index 000000000..bb7226161 --- /dev/null +++ b/numpy/f2py/docs/usersguide/default.css @@ -0,0 +1,180 @@ +/* +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:date: $Date: 2002/12/07 23:59:33 $ +:version: $Revision: 1.2 $ +:copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. +*/ + +body { + background: #FFFFFF ; + color: #000000 +} + +a.footnote-reference { + font-size: smaller ; + vertical-align: super } + +a.target { + color: blue } + +a.toc-backref { + text-decoration: none ; + color: black } + +dd { + margin-bottom: 0.5em } + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.attention, div.caution, div.danger, div.error, div.hint, +div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +div.hint p.admonition-title, div.important p.admonition-title, +div.note p.admonition-title, div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em } + +div.footer, div.header { + font-size: smaller } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr { + width: 75% } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.first { + margin-top: 0 } + +p.label { + white-space: nowrap } + +p.topic-title { + font-weight: bold } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em ; + background-color: #ee9e9e } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.field-argument { + font-style: italic } + +span.interpreted { + font-family: sans-serif } + +span.option-argument { + font-style: italic } + +span.problematic { + color: red } + +table { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.citation { + border-left: solid thin gray ; + padding-left: 0.5ex } + +table.docinfo { + margin: 2em 4em } + +table.footnote { + border-left: solid thin black ; + padding-left: 0.5ex } + +td, th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: baseline } + +td.docinfo-name { + font-weight: bold ; + text-align: right } + +td.field-name { + font-weight: bold } diff --git a/numpy/f2py/docs/usersguide/docutils.conf b/numpy/f2py/docs/usersguide/docutils.conf new file mode 100644 index 000000000..b772fd137 --- /dev/null +++ b/numpy/f2py/docs/usersguide/docutils.conf @@ -0,0 +1,16 @@ +[general] + +# These entries affect all processing: +#source-link: 1 +datestamp: %Y-%m-%d %H:%M UTC +generator: 1 + +# These entries affect HTML output: +#stylesheet-path: f2py_style.css +output-encoding: latin-1 + +# These entries affect reStructuredText-style PEPs: +#pep-template: pep-html-template +#pep-stylesheet-path: stylesheets/pep.css +#python-home: http://www.python.org +#no-random: 1 diff --git a/numpy/f2py/docs/usersguide/extcallback.f b/numpy/f2py/docs/usersguide/extcallback.f new file mode 100644 index 000000000..9a800628e --- /dev/null +++ b/numpy/f2py/docs/usersguide/extcallback.f @@ -0,0 +1,14 @@ + subroutine f1() + print *, "in f1, calling f2 twice.." + call f2() + call f2() + return + end + + subroutine f2() +cf2py intent(callback, hide) fpy + external fpy + print *, "in f2, calling f2py.." + call fpy() + return + end diff --git a/numpy/f2py/docs/usersguide/extcallback_session.dat b/numpy/f2py/docs/usersguide/extcallback_session.dat new file mode 100644 index 000000000..c22935ea0 --- /dev/null +++ b/numpy/f2py/docs/usersguide/extcallback_session.dat @@ -0,0 +1,19 @@ +>>> import pfromf +>>> pfromf.f2() +Traceback (most recent call last): + File "<stdin>", line 1, in ? +pfromf.error: Callback fpy not defined (as an argument or module pfromf attribute). + +>>> def f(): print "python f" +... +>>> pfromf.fpy = f +>>> pfromf.f2() + in f2, calling f2py.. +python f +>>> pfromf.f1() + in f1, calling f2 twice.. + in f2, calling f2py.. +python f + in f2, calling f2py.. +python f +>>>
\ No newline at end of file diff --git a/numpy/f2py/docs/usersguide/fib1.f b/numpy/f2py/docs/usersguide/fib1.f new file mode 100644 index 000000000..cfbb1eea0 --- /dev/null +++ b/numpy/f2py/docs/usersguide/fib1.f @@ -0,0 +1,18 @@ +C FILE: FIB1.F + SUBROUTINE FIB(A,N) +C +C CALCULATE FIRST N FIBONACCI NUMBERS +C + INTEGER N + REAL*8 A(N) + DO I=1,N + IF (I.EQ.1) THEN + A(I) = 0.0D0 + ELSEIF (I.EQ.2) THEN + A(I) = 1.0D0 + ELSE + A(I) = A(I-1) + A(I-2) + ENDIF + ENDDO + END +C END FILE FIB1.F diff --git a/numpy/f2py/docs/usersguide/fib1.pyf b/numpy/f2py/docs/usersguide/fib1.pyf new file mode 100644 index 000000000..3d6cc0a54 --- /dev/null +++ b/numpy/f2py/docs/usersguide/fib1.pyf @@ -0,0 +1,12 @@ +! -*- f90 -*- +python module fib2 ! in + interface ! in :fib2 + subroutine fib(a,n) ! in :fib2:fib1.f + real*8 dimension(n) :: a + integer optional,check(len(a)>=n),depend(a) :: n=len(a) + end subroutine fib + end interface +end python module fib2 + +! This file was auto-generated with f2py (version:2.28.198-1366). +! See http://cens.ioc.ee/projects/f2py2e/ diff --git a/numpy/f2py/docs/usersguide/fib2.pyf b/numpy/f2py/docs/usersguide/fib2.pyf new file mode 100644 index 000000000..4a5ae29f1 --- /dev/null +++ b/numpy/f2py/docs/usersguide/fib2.pyf @@ -0,0 +1,9 @@ +! -*- f90 -*- +python module fib2 + interface + subroutine fib(a,n) + real*8 dimension(n),intent(out),depend(n) :: a + integer intent(in) :: n + end subroutine fib + end interface +end python module fib2 diff --git a/numpy/f2py/docs/usersguide/fib3.f b/numpy/f2py/docs/usersguide/fib3.f new file mode 100644 index 000000000..08b050cd2 --- /dev/null +++ b/numpy/f2py/docs/usersguide/fib3.f @@ -0,0 +1,21 @@ +C FILE: FIB3.F + SUBROUTINE FIB(A,N) +C +C CALCULATE FIRST N FIBONACCI NUMBERS +C + INTEGER N + REAL*8 A(N) +Cf2py intent(in) n +Cf2py intent(out) a +Cf2py depend(n) a + DO I=1,N + IF (I.EQ.1) THEN + A(I) = 0.0D0 + ELSEIF (I.EQ.2) THEN + A(I) = 1.0D0 + ELSE + A(I) = A(I-1) + A(I-2) + ENDIF + ENDDO + END +C END FILE FIB3.F diff --git a/numpy/f2py/docs/usersguide/ftype.f b/numpy/f2py/docs/usersguide/ftype.f new file mode 100644 index 000000000..cabbb9e2d --- /dev/null +++ b/numpy/f2py/docs/usersguide/ftype.f @@ -0,0 +1,9 @@ +C FILE: FTYPE.F + SUBROUTINE FOO(N) + INTEGER N +Cf2py integer optional,intent(in) :: n = 13 + REAL A,X + COMMON /DATA/ A,X(3) + PRINT*, "IN FOO: N=",N," A=",A," X=[",X(1),X(2),X(3),"]" + END +C END OF FTYPE.F diff --git a/numpy/f2py/docs/usersguide/ftype_session.dat b/numpy/f2py/docs/usersguide/ftype_session.dat new file mode 100644 index 000000000..01f9febaf --- /dev/null +++ b/numpy/f2py/docs/usersguide/ftype_session.dat @@ -0,0 +1,21 @@ +>>> import ftype +>>> print ftype.__doc__ +This module 'ftype' is auto-generated with f2py (version:2.28.198-1366). +Functions: + foo(n=13) +COMMON blocks: + /data/ a,x(3) +. +>>> type(ftype.foo),type(ftype.data) +(<type 'fortran'>, <type 'fortran'>) +>>> ftype.foo() + IN FOO: N= 13 A= 0. X=[ 0. 0. 0.] +>>> ftype.data.a = 3 +>>> ftype.data.x = [1,2,3] +>>> ftype.foo() + IN FOO: N= 13 A= 3. X=[ 1. 2. 3.] +>>> ftype.data.x[1] = 45 +>>> ftype.foo(24) + IN FOO: N= 24 A= 3. X=[ 1. 45. 3.] +>>> ftype.data.x +array([ 1., 45., 3.],'f') diff --git a/numpy/f2py/docs/usersguide/index.txt b/numpy/f2py/docs/usersguide/index.txt new file mode 100644 index 000000000..9fafb99fb --- /dev/null +++ b/numpy/f2py/docs/usersguide/index.txt @@ -0,0 +1,1772 @@ +.. -*- rest -*- + +////////////////////////////////////////////////////////////////////// + F2PY Users Guide and Reference Manual +////////////////////////////////////////////////////////////////////// + +:Author: Pearu Peterson +:Contact: pearu@cens.ioc.ee +:Web site: http://cens.ioc.ee/projects/f2py2e/ +:Date: $Date: 2005/04/02 10:03:26 $ +:Revision: $Revision: 1.27 $ + + +.. section-numbering:: + +.. Contents:: + + +================ + Introduction +================ + +The purpose of the F2PY_ --*Fortran to Python interface generator*-- +project is to provide a connection between Python and Fortran +languages. F2PY is a Python_ package (with a command line tool +``f2py`` and a module ``f2py2e``) that facilitates creating/building +Python C/API extension modules that make it possible + +* to call Fortran 77/90/95 external subroutines and Fortran 90/95 + module subroutines as well as C functions; +* to access Fortran 77 ``COMMON`` blocks and Fortran 90/95 module data, + including allocatable arrays + +from Python. See F2PY_ web site for more information and installation +instructions. + +====================================== + Three ways to wrap - getting started +====================================== + +Wrapping Fortran or C functions to Python using F2PY consists of the +following steps: + +* Creating the so-called signature file that contains descriptions of + wrappers to Fortran or C functions, also called as signatures of the + functions. In the case of Fortran routines, F2PY can create initial + signature file by scanning Fortran source codes and + catching all relevant information needed to create wrapper + functions. + +* Optionally, F2PY created signature files can be edited to optimize + wrappers functions, make them "smarter" and more "Pythonic". + +* F2PY reads a signature file and writes a Python C/API module containing + Fortran/C/Python bindings. + +* F2PY compiles all sources and builds an extension module containing + the wrappers. In building extension modules, F2PY uses + ``scipy_distutils`` that supports a number of Fortran 77/90/95 + compilers, including Gnu, Intel, + Sun Fortre, SGI MIPSpro, Absoft, NAG, Compaq etc. compilers. + +Depending on a particular situation, these steps can be carried out +either by just in one command or step-by-step, some steps can be +ommited or combined with others. + +Below I'll describe three typical approaches of using F2PY. +The following `example Fortran 77 code`__ will be used for +illustration: + +.. include:: fib1.f + :literal: + +__ fib1.f + +The quick way +============== + +The quickest way to wrap the Fortran subroutine ``FIB`` to Python is +to run + +:: + + f2py -c fib1.f -m fib1 + +This command builds (see ``-c`` flag, execute ``f2py`` without +arguments to see the explanation of command line options) an extension +module ``fib1.so`` (see ``-m`` flag) to the current directory. Now, in +Python the Fortran subroutine ``FIB`` is accessible via ``fib1.fib``:: + + >>> import Numeric + >>> import fib1 + >>> print fib1.fib.__doc__ + fib - Function signature: + fib(a,[n]) + Required arguments: + a : input rank-1 array('d') with bounds (n) + Optional arguments: + n := len(a) input int + + >>> a=Numeric.zeros(8,'d') + >>> fib1.fib(a) + >>> print a + [ 0. 1. 1. 2. 3. 5. 8. 13.] + +.. topic:: Comments + + * Note that F2PY found that the second argument ``n`` is the + dimension of the first array argument ``a``. Since by default all + arguments are input-only arguments, F2PY concludes that ``n`` can + be optional with the default value ``len(a)``. + + * One can use different values for optional ``n``:: + + >>> a1=Numeric.zeros(8,'d') + >>> fib1.fib(a1,6) + >>> print a1 + [ 0. 1. 1. 2. 3. 5. 0. 0.] + + but an exception is raised when it is incompatible with the input + array ``a``:: + + >>> fib1.fib(a,10) + fib:n=10 + Traceback (most recent call last): + File "<stdin>", line 1, in ? + fib.error: (len(a)>=n) failed for 1st keyword n + >>> + + This demonstrates one of the useful features in F2PY, that it, + F2PY implements basic compatibility checks between related + arguments in order to avoid any unexpected crashes. + + * When a Numeric array, that is Fortran contiguous and has a typecode + corresponding to presumed Fortran type, is used as an input array + argument, then its C pointer is directly passed to Fortran. + + Otherwise F2PY makes a contiguous copy (with a proper typecode) of + the input array and passes C pointer of the copy to Fortran + subroutine. As a result, any possible changes to the (copy of) + input array have no effect to the original argument, as + demonstrated below:: + + >>> a=Numeric.ones(8,'i') + >>> fib1.fib(a) + >>> print a + [1 1 1 1 1 1 1 1] + + Clearly, this is not an expected behaviour. The fact that the + above example worked with ``typecode='d'`` is considered + accidental. + + F2PY provides ``intent(inplace)`` attribute that would modify + the attributes of an input array so that any changes made by + Fortran routine will be effective also in input argument. For example, + if one specifies ``intent(inplace) a`` (see below, how), then + the example above would read: + + >>> a=Numeric.ones(8,'i') + >>> fib1.fib(a) + >>> print a + [ 0. 1. 1. 2. 3. 5. 8. 13.] + + However, the recommended way to get changes made by Fortran + subroutine back to python is to use ``intent(out)`` attribute. It + is more efficient and a cleaner solution. + + * The usage of ``fib1.fib`` in Python is very similar to using + ``FIB`` in Fortran. However, using *in situ* output arguments in + Python indicates a poor style as there is no safety mechanism + in Python with respect to wrong argument types. When using Fortran + or C, compilers naturally discover any type mismatches during + compile time but in Python the types must be checked in + runtime. So, using *in situ* output arguments in Python may cause + difficult to find bugs, not to mention that the codes will be less + readable when all required type checks are implemented. + + Though the demonstrated way of wrapping Fortran routines to Python + is very straightforward, it has several drawbacks (see the comments + above). These drawbacks are due to the fact that there is no way + that F2PY can determine what is the acctual intention of one or the + other argument, is it input or output argument, or both, or + something else. So, F2PY conservatively assumes that all arguments + are input arguments by default. + + However, there are ways (see below) how to "teach" F2PY about the + true intentions (among other things) of function arguments; and then + F2PY is able to generate more Pythonic (more explicit, easier to + use, and less error prone) wrappers to Fortran functions. + +The smart way +============== + +Let's apply the steps of wrapping Fortran functions to Python one by +one. + +* First, we create a signature file from ``fib1.f`` by running + + :: + + f2py fib1.f -m fib2 -h fib1.pyf + + The signature file is saved to ``fib1.pyf`` (see ``-h`` flag) and + its contents is shown below. + + .. include:: fib1.pyf + :literal: + +* Next, we'll teach F2PY that the argument ``n`` is a input argument + (use ``intent(in)`` attribute) and that the result, i.e. the + contents of ``a`` after calling Fortran function ``FIB``, should be + returned to Python (use ``intent(out)`` attribute). In addition, an + array ``a`` should be created dynamically using the size given by + the input argument ``n`` (use ``depend(n)`` attribute to indicate + dependence relation). + + The content of a modified version of ``fib1.pyf`` (saved as + ``fib2.pyf``) is as follows: + + .. include:: fib2.pyf + :literal: + +* And finally, we build the extension module by running + + :: + + f2py -c fib2.pyf fib1.f + +In Python:: + + >>> import fib2 + >>> print fib2.fib.__doc__ + fib - Function signature: + a = fib(n) + Required arguments: + n : input int + Return objects: + a : rank-1 array('d') with bounds (n) + + >>> print fib2.fib(8) + [ 0. 1. 1. 2. 3. 5. 8. 13.] + +.. topic:: Comments + + * Clearly, the signature of ``fib2.fib`` now corresponds to the + intention of Fortran subroutine ``FIB`` more closely: given the + number ``n``, ``fib2.fib`` returns the first ``n`` Fibonacci numbers + as a Numeric array. Also, the new Python signature ``fib2.fib`` + rules out any surprises that we experienced with ``fib1.fib``. + + * Note that by default using single ``intent(out)`` also implies + ``intent(hide)``. Argument that has ``intent(hide)`` attribute + specified, will not be listed in the argument list of a wrapper + function. + +The quick and smart way +======================== + +The "smart way" of wrapping Fortran functions, as explained above, is +suitable for wrapping (e.g. third party) Fortran codes for which +modifications to their source codes are not desirable nor even +possible. + +However, if editing Fortran codes is acceptable, then the generation +of an intermediate signature file can be skipped in most +cases. Namely, F2PY specific attributes can be inserted directly to +Fortran source codes using the so-called F2PY directive. A F2PY +directive defines special comment lines (starting with ``Cf2py``, for +example) which are ignored by Fortran compilers but F2PY interprets +them as normal lines. + +Here is shown a `modified version of the example Fortran code`__, saved +as ``fib3.f``: + +.. include:: fib3.f + :literal: + +__ fib3.f + +Building the extension module can be now carried out in one command:: + + f2py -c -m fib3 fib3.f + +Notice that the resulting wrapper to ``FIB`` is as "smart" as in +previous case:: + + >>> import fib3 + >>> print fib3.fib.__doc__ + fib - Function signature: + a = fib(n) + Required arguments: + n : input int + Return objects: + a : rank-1 array('d') with bounds (n) + + >>> print fib3.fib(8) + [ 0. 1. 1. 2. 3. 5. 8. 13.] + + +================== + Signature file +================== + +The syntax specification for signature files (.pyf files) is borrowed +from the Fortran 90/95 language specification. Almost all Fortran +90/95 standard constructs are understood, both in free and fixed +format (recall that Fortran 77 is a subset of Fortran 90/95). F2PY +introduces also some extensions to Fortran 90/95 language +specification that help designing Fortran to Python interface, make it +more "Pythonic". + +Signature files may contain arbitrary Fortran code (so that Fortran +codes can be considered as signature files). F2PY silently ignores +Fortran constructs that are irrelevant for creating the interface. +However, this includes also syntax errors. So, be careful not making +ones;-). + +In general, the contents of signature files is case-sensitive. When +scanning Fortran codes and writing a signature file, F2PY lowers all +cases automatically except in multi-line blocks or when ``--no-lower`` +option is used. + +The syntax of signature files is overvied below. + +Python module block +===================== + +A signature file may contain one (recommended) or more ``python +module`` blocks. ``python module`` block describes the contents of +a Python/C extension module ``<modulename>module.c`` that F2PY +generates. + +Exception: if ``<modulename>`` contains a substring ``__user__``, then +the corresponding ``python module`` block describes the signatures of +so-called call-back functions (see `Call-back arguments`_). + +A ``python module`` block has the following structure:: + + python module <modulename> + [<usercode statement>]... + [ + interface + <usercode statement> + <Fortran block data signatures> + <Fortran/C routine signatures> + end [interface] + ]... + [ + interface + module <F90 modulename> + [<F90 module data type declarations>] + [<F90 module routine signatures>] + end [module [<F90 modulename>]] + end [interface] + ]... + end [python module [<modulename>]] + +Here brackets ``[]`` indicate a optional part, dots ``...`` indicate +one or more of a previous part. So, ``[]...`` reads zero or more of a +previous part. + + +Fortran/C routine signatures +============================= + +The signature of a Fortran routine has the following structure:: + + [<typespec>] function | subroutine <routine name> \ + [ ( [<arguments>] ) ] [ result ( <entityname> ) ] + [<argument/variable type declarations>] + [<argument/variable attribute statements>] + [<use statements>] + [<common block statements>] + [<other statements>] + end [ function | subroutine [<routine name>] ] + +From a Fortran routine signature F2PY generates a Python/C extension +function that has the following signature:: + + def <routine name>(<required arguments>[,<optional arguments>]): + ... + return <return variables> + +The signature of a Fortran block data has the following structure:: + + block data [ <block data name> ] + [<variable type declarations>] + [<variable attribute statements>] + [<use statements>] + [<common block statements>] + [<include statements>] + end [ block data [<block data name>] ] + +Type declarations +------------------- + + The definition of the ``<argument/variable type declaration>`` part + is + + :: + + <typespec> [ [<attrspec>] :: ] <entitydecl> + + where + + :: + + <typespec> := byte | character [<charselector>] + | complex [<kindselector>] | real [<kindselector>] + | double complex | double precision + | integer [<kindselector>] | logical [<kindselector>] + + <charselector> := * <charlen> + | ( [len=] <len> [ , [kind=] <kind>] ) + | ( kind= <kind> [ , len= <len> ] ) + <kindselector> := * <intlen> | ( [kind=] <kind> ) + + <entitydecl> := <name> [ [ * <charlen> ] [ ( <arrayspec> ) ] + | [ ( <arrayspec> ) ] * <charlen> ] + | [ / <init_expr> / | = <init_expr> ] \ + [ , <entitydecl> ] + + and + + + ``<attrspec>`` is a comma separated list of attributes_; + + + ``<arrayspec>`` is a comma separated list of dimension bounds; + + + ``<init_expr>`` is a `C expression`__. + + + ``<intlen>`` may be negative integer for ``integer`` type + specifications. In such cases ``integer*<negintlen>`` represents + unsigned C integers. + +__ `C expressions`_ + + If an argument has no ``<argument type declaration>``, its type is + determined by applying ``implicit`` rules to its name. + + +Statements +------------ + +Attribute statements: + + The ``<argument/variable attribute statement>`` is + ``<argument/variable type declaration>`` without ``<typespec>``. + In addition, in an attribute statement one cannot use other + attributes, also ``<entitydecl>`` can be only a list of names. + +Use statements: + + The definition of the ``<use statement>`` part is + + :: + + use <modulename> [ , <rename_list> | , ONLY : <only_list> ] + + where + + :: + + <rename_list> := <local_name> => <use_name> [ , <rename_list> ] + + Currently F2PY uses ``use`` statement only for linking call-back + modules and ``external`` arguments (call-back functions), see + `Call-back arguments`_. + +Common block statements: + + The definition of the ``<common block statement>`` part is + + :: + + common / <common name> / <shortentitydecl> + + where + + :: + + <shortentitydecl> := <name> [ ( <arrayspec> ) ] [ , <shortentitydecl> ] + + One ``python module`` block should not contain two or more + ``common`` blocks with the same name. Otherwise, the latter ones are + ignored. The types of variables in ``<shortentitydecl>`` are defined + using ``<argument type declarations>``. Note that the corresponding + ``<argument type declarations>`` may contain array specifications; + then you don't need to specify these in ``<shortentitydecl>``. + +Other statements: + + The ``<other statement>`` part refers to any other Fortran language + constructs that are not described above. F2PY ignores most of them + except + + + ``call`` statements and function calls of ``external`` arguments + (`more details`__?); + +__ external_ + + + ``include`` statements + + :: + + include '<filename>' + include "<filename>" + + If a file ``<filename>`` does not exist, the ``include`` + statement is ignored. Otherwise, the file ``<filename>`` is + included to a signature file. ``include`` statements can be used + in any part of a signature file, also outside the Fortran/C + routine signature blocks. + + + ``implicit`` statements + + :: + + implicit none + implicit <list of implicit maps> + + where + + :: + + <implicit map> := <typespec> ( <list of letters or range of letters> ) + + Implicit rules are used to deterimine the type specification of + a variable (from the first-letter of its name) if the variable + is not defined using ``<variable type declaration>``. Default + implicit rule is given by + + :: + + implicit real (a-h,o-z,$_), integer (i-m) + + + ``entry`` statements + + :: + + entry <entry name> [([<arguments>])] + + F2PY generates wrappers to all entry names using the signature + of the routine block. + + Tip: ``entry`` statement can be used to describe the signature + of an arbitrary routine allowing F2PY to generate a number of + wrappers from only one routine block signature. There are few + restrictions while doing this: ``fortranname`` cannot be used, + ``callstatement`` and ``callprotoargument`` can be used only if + they are valid for all entry routines, etc. + + In addition, F2PY introduces the following statements: + + + ``threadsafe`` + Use ``Py_BEGIN_ALLOW_THREADS .. Py_END_ALLOW_THREADS`` block + around the call to Fortran/C function. + + + ``callstatement <C-expr|multi-line block>`` + Replace F2PY generated call statement to Fortran/C function with + ``<C-expr|multi-line block>``. The wrapped Fortran/C function + is available as ``(*f2py_func)``. To raise an exception, set + ``f2py_success = 0`` in ``<C-expr|multi-line block>``. + + + ``callprotoargument <C-typespecs>`` + When ``callstatement`` statement is used then F2PY may not + generate proper prototypes for Fortran/C functions (because + ``<C-expr>`` may contain any function calls and F2PY has no way + to determine what should be the proper prototype). With this + statement you can explicitely specify the arguments of the + corresponding prototype:: + + extern <return type> FUNC_F(<routine name>,<ROUTINE NAME>)(<callprotoargument>); + + + ``fortranname [<acctual Fortran/C routine name>]`` + You can use arbitrary ``<routine name>`` for a given Fortran/C + function. Then you have to specify + ``<acctual Fortran/C routine name>`` with this statement. + + If ``fortranname`` statement is used without + ``<acctual Fortran/C routine name>`` then a dummy wrapper is + generated. + + + ``usercode <multi-line block>`` + When used inside ``python module`` block, then given C code + will be inserted to generated C/API source just before + wrapper function definitions. Here you can define arbitrary + C functions to be used in initialization of optional arguments, + for example. If ``usercode`` is used twise inside ``python + module`` block then the second multi-line block is inserted + after the definition of external routines. + + When used inside ``<routine singature>``, then given C code will + be inserted to the corresponding wrapper function just after + declaring variables but before any C statements. So, ``usercode`` + follow-up can contain both declarations and C statements. + + When used inside the first ``interface`` block, then given C + code will be inserted at the end of the initialization + function of the extension module. Here you can modify extension + modules dictionary. For example, for defining additional + variables etc. + + + ``pymethoddef <multi-line block>`` + Multiline block will be inserted to the definition of + module methods ``PyMethodDef``-array. It must be a + comma-separated list of C arrays (see `Extending and Embedding`__ + Python documentation for details). + ``pymethoddef`` statement can be used only inside + ``python module`` block. + + __ http://www.python.org/doc/current/ext/ext.html + +Attributes +------------ + +The following attributes are used by F2PY: + +``optional`` + The corresponding argument is moved to the end of ``<optional + arguments>`` list. A default value for an optional argument can be + specified ``<init_expr>``, see ``entitydecl`` definition. Note that + the default value must be given as a valid C expression. + + Note that whenever ``<init_expr>`` is used, ``optional`` attribute + is set automatically by F2PY. + + For an optional array argument, all its dimensions must be bounded. + +``required`` + The corresponding argument is considered as a required one. This is + default. You need to specify ``required`` only if there is a need to + disable automatic ``optional`` setting when ``<init_expr>`` is used. + + If Python ``None`` object is used as an required argument, the + argument is treated as optional. That is, in the case of array + argument, the memory is allocated. And if ``<init_expr>`` is given, + the corresponding initialization is carried out. + +``dimension(<arrayspec>)`` + The corresponding variable is considered as an array with given + dimensions in ``<arrayspec>``. + +``intent(<intentspec>)`` + This specifies the "intention" of the corresponding + argument. ``<intentspec>`` is a comma separated list of the + following keys: + + + ``in`` + The argument is considered as an input-only argument. It means + that the value of the argument is passed to Fortran/C function and + that function is expected not to change the value of an argument. + + + ``inout`` + The argument is considered as an input/output or *in situ* + output argument. ``intent(inout)`` arguments can be only + "contiguous" Numeric arrays with proper type and size. Here + "contiguous" can be either in Fortran or C sense. The latter one + coincides with the contiguous concept used in Numeric and is + effective only if ``intent(c)`` is used. Fortran-contiguousness + is assumed by default. + + Using ``intent(inout)`` is generally not recommended, use + ``intent(in,out)`` instead. See also ``intent(inplace)`` attribute. + + + ``inplace`` + The argument is considered as an input/output or *in situ* + output argument. ``intent(inplace)`` arguments must be + Numeric arrays with proper size. If the type of an array is + not "proper" or the array is non-contiguous then the array + will be changed in-place to fix the type and make it contiguous. + + Using ``intent(inplace)`` is generally not recommended either. + For example, when slices have been taken from an + ``intent(inplace)`` argument then after in-place changes, + slices data pointers may point to unallocated memory area. + + + ``out`` + The argument is considered as an return variable. It is appended + to the ``<returned variables>`` list. Using ``intent(out)`` + sets ``intent(hide)`` automatically, unless also + ``intent(in)`` or ``intent(inout)`` were used. + + By default, returned multidimensional arrays are + Fortran-contiguous. If ``intent(c)`` is used, then returned + multi-dimensional arrays are C-contiguous. + + + ``hide`` + The argument is removed from the list of required or optional + arguments. Typically ``intent(hide)`` is used with ``intent(out)`` + or when ``<init_expr>`` completely determines the value of the + argument like in the following example:: + + integer intent(hide),depend(a) :: n = len(a) + real intent(in),dimension(n) :: a + + + ``c`` + The argument is treated as a C scalar or C array argument. In + the case of a scalar argument, its value is passed to C function + as a C scalar argument (recall that Fortran scalar arguments are + actually C pointer arguments). In the case of an array + argument, the wrapper function is assumed to treat + multi-dimensional arrays as C-contiguous arrays. + + There is no need to use ``intent(c)`` for one-dimensional + arrays, no matter if the wrapped function is either a Fortran or + a C function. This is because the concepts of Fortran- and + C-contiguousness overlap in one-dimensional cases. + + If ``intent(c)`` is used as an statement but without entity + declaration list, then F2PY adds ``intent(c)`` attibute to all + arguments. + + Also, when wrapping C functions, one must use ``intent(c)`` + attribute for ``<routine name>`` in order to disable Fortran + specific ``F_FUNC(..,..)`` macros. + + + ``cache`` + The argument is treated as a junk of memory. No Fortran nor C + contiguousness checks are carried out. Using ``intent(cache)`` + makes sense only for array arguments, also in connection with + ``intent(hide)`` or ``optional`` attributes. + + + ``copy`` + Ensure that the original contents of ``intent(in)`` argument is + preserved. Typically used in connection with ``intent(in,out)`` + attribute. F2PY creates an optional argument + ``overwrite_<argument name>`` with the default value ``0``. + + + ``overwrite`` + The original contents of the ``intent(in)`` argument may be + altered by the Fortran/C function. F2PY creates an optional + argument ``overwrite_<argument name>`` with the default value + ``1``. + + + ``out=<new name>`` + Replace the return name with ``<new name>`` in the ``__doc__`` + string of a wrapper function. + + + ``callback`` + Construct an external function suitable for calling Python function + from Fortran. ``intent(callback)`` must be specified before the + corresponding ``external`` statement. If 'argument' is not in + argument list then it will be added to Python wrapper but only + initializing external function. + + Use ``intent(callback)`` in situations where a Fortran/C code + assumes that a user implements a function with given prototype + and links it to an executable. Don't use ``intent(callback)`` + if function appears in the argument list of a Fortran routine. + + With ``intent(hide)`` or ``optional`` attributes specified and + using a wrapper function without specifying the callback argument + in argument list then call-back function is looked in the + namespace of F2PY generated extension module where it can be + set as a module attribute by a user. + + + ``aux`` + Define auxiliary C variable in F2PY generated wrapper function. + Useful to save parameter values so that they can be accessed + in initialization expression of other variables. Note that + ``intent(aux)`` silently implies ``intent(c)``. + + The following rules apply: + + + If no ``intent(in | inout | out | hide)`` is specified, + ``intent(in)`` is assumed. + + ``intent(in,inout)`` is ``intent(in)``. + + ``intent(in,hide)`` or ``intent(inout,hide)`` is + ``intent(hide)``. + + ``intent(out)`` is ``intent(out,hide)`` unless ``intent(in)`` or + ``intent(inout)`` is specified. + + If ``intent(copy)`` or ``intent(overwrite)`` is used, then an + additional optional argument is introduced with a name + ``overwrite_<argument name>`` and a default value 0 or 1, respectively. + + ``intent(inout,inplace)`` is ``intent(inplace)``. + + ``intent(in,inplace)`` is ``intent(inplace)``. + + ``intent(hide)`` disables ``optional`` and ``required``. + +``check([<C-booleanexpr>])`` + Perform consistency check of arguments by evaluating + ``<C-booleanexpr>``; if ``<C-booleanexpr>`` returns 0, an exception + is raised. + + If ``check(..)`` is not used then F2PY generates few standard checks + (e.g. in a case of an array argument, check for the proper shape + and size) automatically. Use ``check()`` to disable checks generated + by F2PY. + +``depend([<names>])`` + This declares that the corresponding argument depends on the values + of variables in the list ``<names>``. For example, ``<init_expr>`` + may use the values of other arguments. Using information given by + ``depend(..)`` attributes, F2PY ensures that arguments are + initialized in a proper order. If ``depend(..)`` attribute is not + used then F2PY determines dependence relations automatically. Use + ``depend()`` to disable dependence relations generated by F2PY. + + When you edit dependence relations that were initially generated by + F2PY, be careful not to break the dependence relations of other + relevant variables. Another thing to watch out is cyclic + dependencies. F2PY is able to detect cyclic dependencies + when constructing wrappers and it complains if any are found. + +``allocatable`` + The corresponding variable is Fortran 90 allocatable array defined + as Fortran 90 module data. + +.. _external: + +``external`` + The corresponding argument is a function provided by user. The + signature of this so-called call-back function can be defined + + - in ``__user__`` module block, + - or by demonstrative (or real, if the signature file is a real Fortran + code) call in the ``<other statements>`` block. + + For example, F2PY generates from + + :: + + external cb_sub, cb_fun + integer n + real a(n),r + call cb_sub(a,n) + r = cb_fun(4) + + the following call-back signatures:: + + subroutine cb_sub(a,n) + real dimension(n) :: a + integer optional,check(len(a)>=n),depend(a) :: n=len(a) + end subroutine cb_sub + function cb_fun(e_4_e) result (r) + integer :: e_4_e + real :: r + end function cb_fun + + The corresponding user-provided Python function are then:: + + def cb_sub(a,[n]): + ... + return + def cb_fun(e_4_e): + ... + return r + + See also ``intent(callback)`` attribute. + +``parameter`` + The corresponding variable is a parameter and it must have a fixed + value. F2PY replaces all parameter occurrences by their + corresponding values. + +Extensions +============ + +F2PY directives +----------------- + +The so-called F2PY directives allow using F2PY signature file +constructs also in Fortran 77/90 source codes. With this feature you +can skip (almost) completely intermediate signature file generations +and apply F2PY directly to Fortran source codes. + +F2PY directive has the following form:: + + <comment char>f2py ... + +where allowed comment characters for fixed and free format Fortran +codes are ``cC*!#`` and ``!``, respectively. Everything that follows +``<comment char>f2py`` is ignored by a compiler but read by F2PY as a +normal Fortran (non-comment) line: + + When F2PY finds a line with F2PY directive, the directive is first + replaced by 5 spaces and then the line is reread. + +For fixed format Fortran codes, ``<comment char>`` must be at the +first column of a file, of course. For free format Fortran codes, +F2PY directives can appear anywhere in a file. + +C expressions +-------------- + +C expressions are used in the following parts of signature files: + +* ``<init_expr>`` of variable initialization; +* ``<C-booleanexpr>`` of the ``check`` attribute; +* ``<arrayspec> of the ``dimension`` attribute; +* ``callstatement`` statement, here also a C multi-line block can be used. + +A C expression may contain: + +* standard C constructs; +* functions from ``math.h`` and ``Python.h``; +* variables from the argument list, presumably initialized before + according to given dependence relations; +* the following CPP macros: + + ``rank(<name>)`` + Returns the rank of an array ``<name>``. + ``shape(<name>,<n>)`` + Returns the ``<n>``-th dimension of an array ``<name>``. + ``len(<name>)`` + Returns the lenght of an array ``<name>``. + ``size(<name>)`` + Returns the size of an array ``<name>``. + ``slen(<name>)`` + Returns the length of a string ``<name>``. + +For initializing an array ``<array name>``, F2PY generates a loop over +all indices and dimensions that executes the following +pseudo-statement:: + + <array name>(_i[0],_i[1],...) = <init_expr>; + +where ``_i[<i>]`` refers to the ``<i>``-th index value and that runs +from ``0`` to ``shape(<array name>,<i>)-1``. + +For example, a function ``myrange(n)`` generated from the following +signature + +:: + + subroutine myrange(a,n) + fortranname ! myrange is a dummy wrapper + integer intent(in) :: n + real*8 intent(c,out),dimension(n),depend(n) :: a = _i[0] + end subroutine myrange + +is equivalent to ``Numeric.arange(n,typecode='d')``. + +.. topic:: Warning! + + F2PY may lower cases also in C expressions when scanning Fortran codes + (see ``--[no]-lower`` option). + +Multi-line blocks +------------------ + +A multi-line block starts with ``'''`` (triple single-quotes) and ends +with ``'''`` in some *strictly* subsequent line. Multi-line blocks can +be used only within .pyf files. The contents of a multi-line block can +be arbitrary (except that it cannot contain ``'''``) and no +transformations (e.g. lowering cases) are applied to it. + +Currently, multi-line blocks can be used in the following constructs: + ++ as a C expression of the ``callstatement`` statement; + ++ as a C type specification of the ``callprotoargument`` statement; + ++ as a C code block of the ``usercode`` statement; + ++ as a list of C arrays of the ``pymethoddef`` statement; + ++ as documentation string. + +================================== +Using F2PY bindings in Python +================================== + +All wrappers (to Fortran/C routines or to common blocks or to Fortran +90 module data) generated by F2PY are exposed to Python as ``fortran`` +type objects. Routine wrappers are callable ``fortran`` type objects +while wrappers to Fortran data have attributes referring to data +objects. + +All ``fortran`` type object have attribute ``_cpointer`` that contains +CObject referring to the C pointer of the corresponding Fortran/C +function or variable in C level. Such CObjects can be used as an +callback argument of F2PY generated functions to bypass Python C/API +layer of calling Python functions from Fortran or C when the +computational part of such functions is implemented in C or Fortran +and wrapped with F2PY (or any other tool capable of providing CObject +of a function). + +.. topic:: Example + + Consider a `Fortran 77 file`__ ``ftype.f``: + + .. include:: ftype.f + :literal: + + and build a wrapper using:: + + f2py -c ftype.f -m ftype + + __ ftype.f + + In Python: + + .. include:: ftype_session.dat + :literal: + + +Scalar arguments +================= + +In general, a scalar argument of a F2PY generated wrapper function can +be ordinary Python scalar (integer, float, complex number) as well as +an arbitrary sequence object (list, tuple, array, string) of +scalars. In the latter case, the first element of the sequence object +is passed to Fortran routine as a scalar argument. + +Note that when type-casting is required and there is possible loss of +information (e.g. when type-casting float to integer or complex to +float), F2PY does not raise any exception. In complex to real +type-casting only the real part of a complex number is used. + +``intent(inout)`` scalar arguments are assumed to be array objects in +order to *in situ* changes to be effective. It is recommended to use +arrays with proper type but also other types work. + +.. topic:: Example + + Consider the following `Fortran 77 code`__: + + .. include:: scalar.f + :literal: + + and wrap it using ``f2py -c -m scalar scalar.f``. + + __ scalar.f + + In Python: + + .. include:: scalar_session.dat + :literal: + + +String arguments +================= + +F2PY generated wrapper functions accept (almost) any Python object as +a string argument, ``str`` is applied for non-string objects. +Exceptions are Numeric arrays that must have type code ``'c'`` or +``'1'`` when used as string arguments. + +A string can have arbitrary length when using it as a string argument +to F2PY generated wrapper function. If the length is greater than +expected, the string is truncated. If the length is smaller that +expected, additional memory is allocated and filled with ``\0``. + +Because Python strings are immutable, an ``intent(inout)`` argument +expects an array version of a string in order to *in situ* changes to +be effective. + +.. topic:: Example + + Consider the following `Fortran 77 code`__: + + .. include:: string.f + :literal: + + and wrap it using ``f2py -c -m mystring string.f``. + + __ string.f + + Python session: + + .. include:: string_session.dat + :literal: + + +Array arguments +================ + +In general, array arguments of F2PY generated wrapper functions accept +arbitrary sequences that can be transformed to Numeric array objects. +An exception is ``intent(inout)`` array arguments that always must be +proper-contiguous and have proper type, otherwise an exception is +raised. Another exception is ``intent(inplace)`` array arguments that +attributes will be changed in-situ if the argument has different type +than expected (see ``intent(inplace)`` attribute for more +information). + +In general, if a Numeric array is proper-contiguous and has a proper +type then it is directly passed to wrapped Fortran/C function. +Otherwise, an element-wise copy of an input array is made and the +copy, being proper-contiguous and with proper type, is used as an +array argument. + +There are two types of proper-contiguous Numeric arrays: + +* Fortran-contiguous arrays when data is stored column-wise, + i.e. indexing of data as stored in memory starts from the lowest + dimension; +* C-contiguous or simply contiguous arrays when data is stored + row-wise, i.e. indexing of data as stored in memory starts from the + highest dimension. + +For one-dimensional arrays these notions coincide. + +For example, an 2x2 array ``A`` is Fortran-contiguous if its elements +are stored in memory in the following order:: + + A[0,0] A[1,0] A[0,1] A[1,1] + +and C-contiguous if the order is as follows:: + + A[0,0] A[0,1] A[1,0] A[1,1] + +To test whether an array is C-contiguous, use ``.iscontiguous()`` +method of Numeric arrays. To test for Fortran-contiguousness, all +F2PY generated extension modules provide a function +``has_column_major_storage(<array>)``. This function is equivalent to +``Numeric.transpose(<array>).iscontiguous()`` but more efficient. + +Usually there is no need to worry about how the arrays are stored in +memory and whether the wrapped functions, being either Fortran or C +functions, assume one or another storage order. F2PY automatically +ensures that wrapped functions get arguments with proper storage +order; the corresponding algorithm is designed to make copies of +arrays only when absolutely necessary. However, when dealing with very +large multi-dimensional input arrays with sizes close to the size of +the physical memory in your computer, then a care must be taken to use +always proper-contiguous and proper type arguments. + +To transform input arrays to column major storage order before passing +them to Fortran routines, use a function +``as_column_major_storage(<array>)`` that is provided by all F2PY +generated extension modules. + +.. topic:: Example + + Consider `Fortran 77 code`__: + + .. include:: array.f + :literal: + + and wrap it using ``f2py -c -m arr array.f -DF2PY_REPORT_ON_ARRAY_COPY=1``. + + __ array.f + + In Python: + + .. include:: array_session.dat + :literal: + +Call-back arguments +==================== + +F2PY supports calling Python functions from Fortran or C codes. + + +.. topic:: Example + + Consider the following `Fortran 77 code`__ + + .. include:: callback.f + :literal: + + and wrap it using ``f2py -c -m callback callback.f``. + + __ callback.f + + In Python: + + .. include:: callback_session.dat + :literal: + +In the above example F2PY was able to guess accurately the signature +of a call-back function. However, sometimes F2PY cannot establish the +signature as one would wish and then the signature of a call-back +function must be modified in the signature file manually. Namely, +signature files may contain special modules (the names of such modules +contain a substring ``__user__``) that collect various signatures of +call-back functions. Callback arguments in routine signatures have +attribute ``external`` (see also ``intent(callback)`` attribute). To +relate a callback argument and its signature in ``__user__`` module +block, use ``use`` statement as illustrated below. The same signature +of a callback argument can be referred in different routine +signatures. + +.. topic:: Example + + We use the same `Fortran 77 code`__ as in previous example but now + we'll pretend that F2PY was not able to guess the signatures of + call-back arguments correctly. First, we create an initial signature + file ``callback2.pyf`` using F2PY:: + + f2py -m callback2 -h callback2.pyf callback.f + + Then modify it as follows + + .. include:: callback2.pyf + :literal: + + Finally, build the extension module using:: + + f2py -c callback2.pyf callback.f + + An example Python session would be identical to the previous example + except that argument names would differ. + + __ callback.f + +Sometimes a Fortran package may require that users provide routines +that the package will use. F2PY can construct an interface to such +routines so that Python functions could be called from Fortran. + +.. topic:: Example + + Consider the following `Fortran 77 subroutine`__ that takes an array + and applies a function ``func`` to its elements. + + .. include:: calculate.f + :literal: + + __ calculate.f + + It is expected that function ``func`` has been defined + externally. In order to use a Python function as ``func``, it must + have an attribute ``intent(callback)`` (it must be specified before + the ``external`` statement). + + Finally, build an extension module using:: + + f2py -c -m foo calculate.f + + In Python: + + .. include:: calculate_session.dat + :literal: + +The function is included as an argument to the python function call to +the FORTRAN subroutine eventhough it was NOT in the FORTRAN subroutine argument +list. The "external" refers to the C function generated by f2py, not the python +function itself. The python function must be supplied to the C function. + +The callback function may also be explicitly set in the module. +Then it is not necessary to pass the function in the argument list to +the FORTRAN function. This may be desired if the FORTRAN function calling +the python callback function is itself called by another FORTRAN function. + +.. topic:: Example + + Consider the following `Fortran 77 subroutine`__. + + .. include:: extcallback.f + :literal: + + __ extcallback.f + + and wrap it using ``f2py -c -m pfromf extcallback.f``. + + In Python: + + .. include:: extcallback_session.dat + :literal: + +Resolving arguments to call-back functions +------------------------------------------ + +F2PY generated interface is very flexible with respect to call-back +arguments. For each call-back argument an additional optional +argument ``<name>_extra_args`` is introduced by F2PY. This argument +can be used to pass extra arguments to user provided call-back +arguments. + +If a F2PY generated wrapper function expects the following call-back +argument:: + + def fun(a_1,...,a_n): + ... + return x_1,...,x_k + +but the following Python function + +:: + + def gun(b_1,...,b_m): + ... + return y_1,...,y_l + +is provided by an user, and in addition, + +:: + + fun_extra_args = (e_1,...,e_p) + +is used, then the following rules are applied when a Fortran or C +function calls the call-back argument ``gun``: + +* If ``p==0`` then ``gun(a_1,...,a_q)`` is called, here + ``q=min(m,n)``. +* If ``n+p<=m`` then ``gun(a_1,...,a_n,e_1,...,e_p)`` is called. +* If ``p<=m<n+p`` then ``gun(a_1,...,a_q,e_1,...,e_p)`` is called, here + ``q=m-p``. +* If ``p>m`` then ``gun(e_1,...,e_m)`` is called. +* If ``n+p`` is less than the number of required arguments to ``gun`` + then an exception is raised. + +The function ``gun`` may return any number of objects as a tuple. Then +following rules are applied: + +* If ``k<l``, then ``y_{k+1},...,y_l`` are ignored. +* If ``k>l``, then only ``x_1,...,x_l`` are set. + + + +Common blocks +============== + +F2PY generates wrappers to ``common`` blocks defined in a routine +signature block. Common blocks are visible by all Fortran codes linked +with the current extension module, but not to other extension modules +(this restriction is due to how Python imports shared libraries). In +Python, the F2PY wrappers to ``common`` blocks are ``fortran`` type +objects that have (dynamic) attributes related to data members of +common blocks. When accessed, these attributes return as Numeric array +objects (multi-dimensional arrays are Fortran-contiguous) that +directly link to data members in common blocks. Data members can be +changed by direct assignment or by in-place changes to the +corresponding array objects. + +.. topic:: Example + + Consider the following `Fortran 77 code`__ + + .. include:: common.f + :literal: + + and wrap it using ``f2py -c -m common common.f``. + + __ common.f + + In Python: + + .. include:: common_session.dat + :literal: + +Fortran 90 module data +======================= + +The F2PY interface to Fortran 90 module data is similar to Fortran 77 +common blocks. + +.. topic:: Example + + Consider the following `Fortran 90 code`__ + + .. include:: moddata.f90 + :literal: + + and wrap it using ``f2py -c -m moddata moddata.f90``. + + __ moddata.f90 + + In Python: + + .. include:: moddata_session.dat + :literal: + +Allocatable arrays +------------------- + +F2PY has basic support for Fortran 90 module allocatable arrays. + +.. topic:: Example + + Consider the following `Fortran 90 code`__ + + .. include:: allocarr.f90 + :literal: + + and wrap it using ``f2py -c -m allocarr allocarr.f90``. + + __ allocarr.f90 + + In Python: + + .. include:: allocarr_session.dat + :literal: + + +=========== +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 codelets directly in signature filess + + + ``--[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 ``scipy_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 + ``scipy_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.mktemp()``. +``--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`` +========================= + +.. topic:: 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: + +========================== +Using ``scipy_distutils`` +========================== + +``scipy_distutils`` is part of the SciPy_ project and aims to extend +standard Python ``distutils`` to deal with Fortran sources and F2PY +signature files, e.g. compile Fortran sources, call F2PY to construct +extension modules, etc. + +.. topic:: Example + + Consider the following `setup file`__: + + .. include:: setup_example.py + :literal: + + Running + + :: + + python setup_example.py build + + will build two extension modules ``scalar`` and ``fib2`` to the + build directory. + + __ setup_example.py + +``scipy_distutils`` extends ``distutils`` with the following features: + +* ``Extension`` class argument ``sources`` may contain Fortran source + files. In addition, the list ``sources`` may contain at most one + F2PY signature file, and then the name of an Extension module must + match with the ``<modulename>`` used in signature file. It is + assumed that an F2PY signature file contains exactly one ``python + module`` block. + + If ``sources`` does not contain a signature files, then F2PY is used + to scan Fortran source files for routine signatures to construct the + wrappers to Fortran codes. + + Additional options to F2PY process can be given using ``Extension`` + class argument ``f2py_options``. + +``scipy_distutils`` 0.2.2 and up +================================ + +* The following new ``distutils`` commands are defined: + + ``build_src`` + to construct Fortran wrapper extension modules, among many other things. + ``config_fc`` + to change Fortran compiler options + + as well as ``build_ext`` and ``build_clib`` commands are enhanced + to support Fortran sources. + + Run + + :: + + python <setup.py file> config_fc build_src build_ext --help + + to see available options for these commands. + +* When building Python packages containing Fortran sources, then one + can choose different Fortran compilers by using ``build_ext`` + command option ``--fcompiler=<Vendor>``. Here ``<Vendor>`` can be one of the + following names:: + + absoft sun mips intel intelv intele intelev nag compaq compaqv gnu vast pg hpux + + See ``scipy_distutils/fcompiler.py`` for up-to-date list of + supported compilers or run + + :: + + f2py -c --help-fcompiler + +``scipy_distutils`` pre 0.2.2 +============================= + +* The following new ``distutils`` commands are defined: + + ``build_flib`` + to build f77/f90 libraries used by Python extensions; + ``run_f2py`` + to construct Fortran wrapper extension modules. + + Run + + :: + + python <setup.py file> build_flib run_f2py --help + + to see available options for these commands. + +* When building Python packages containing Fortran sources, then one + can choose different Fortran compilers either by using ``build_flib`` + command option ``--fcompiler=<Vendor>`` or by defining environment + variable ``FC_VENDOR=<Vendor>``. Here ``<Vendor>`` can be one of the + following names:: + + Absoft Sun SGI Intel Itanium NAG Compaq Digital Gnu VAST PG + + See ``scipy_distutils/command/build_flib.py`` for up-to-date list of + supported compilers. + +====================== + Extended F2PY usages +====================== + +Adding self-written functions to F2PY generated modules +======================================================= + +Self-written Python C/API functions can be defined inside +signature files using ``usercode`` and ``pymethoddef`` statements +(they must be used inside the ``python module`` block). For +example, the following signature file ``spam.pyf`` + +.. include:: spam.pyf + :literal: + +wraps the C library function ``system()``:: + + f2py -c spam.pyf + +In Python: + +.. include:: spam_session.dat + :literal: + +Modifying the dictionary of a F2PY generated module +=================================================== + +The following example illustrates how to add an user-defined +variables to a F2PY generated extension module. Given the following +signature file + +.. include:: var.pyf + :literal: + +compile it as ``f2py -c var.pyf``. + +Notice that the second ``usercode`` statement must be defined inside +an ``interface`` block and where the module dictionary is available through +the variable ``d`` (see ``f2py var.pyf``-generated ``varmodule.c`` for +additional details). + +In Python: + +.. include:: var_session.dat + :literal: + +.. References + ========== +.. _F2PY: http://cens.ioc.ee/projects/f2py2e/ +.. _Python: http://www.python.org/ +.. _NumPy: http://www.numpy.org/ +.. _SciPy: http://www.scipy.org/ diff --git a/numpy/f2py/docs/usersguide/moddata.f90 b/numpy/f2py/docs/usersguide/moddata.f90 new file mode 100644 index 000000000..0e98f0467 --- /dev/null +++ b/numpy/f2py/docs/usersguide/moddata.f90 @@ -0,0 +1,18 @@ +module mod + integer i + integer :: x(4) + real, dimension(2,3) :: a + real, allocatable, dimension(:,:) :: b +contains + subroutine foo + integer k + print*, "i=",i + print*, "x=[",x,"]" + print*, "a=[" + print*, "[",a(1,1),",",a(1,2),",",a(1,3),"]" + print*, "[",a(2,1),",",a(2,2),",",a(2,3),"]" + print*, "]" + print*, "Setting a(1,2)=a(1,2)+3" + a(1,2) = a(1,2)+3 + end subroutine foo +end module mod diff --git a/numpy/f2py/docs/usersguide/moddata_session.dat b/numpy/f2py/docs/usersguide/moddata_session.dat new file mode 100644 index 000000000..1ec212f8b --- /dev/null +++ b/numpy/f2py/docs/usersguide/moddata_session.dat @@ -0,0 +1,23 @@ +>>> import moddata +>>> print moddata.mod.__doc__ +i - 'i'-scalar +x - 'i'-array(4) +a - 'f'-array(2,3) +foo - Function signature: + foo() + + +>>> moddata.mod.i = 5 +>>> moddata.mod.x[:2] = [1,2] +>>> moddata.mod.a = [[1,2,3],[4,5,6]] +>>> moddata.mod.foo() + i= 5 + x=[ 1 2 0 0 ] + a=[ + [ 1.000000 , 2.000000 , 3.000000 ] + [ 4.000000 , 5.000000 , 6.000000 ] + ] + Setting a(1,2)=a(1,2)+3 +>>> moddata.mod.a # a is Fortran-contiguous +array([[ 1., 5., 3.], + [ 4., 5., 6.]],'f') diff --git a/numpy/f2py/docs/usersguide/run_main_session.dat b/numpy/f2py/docs/usersguide/run_main_session.dat new file mode 100644 index 000000000..29ecc3dfe --- /dev/null +++ b/numpy/f2py/docs/usersguide/run_main_session.dat @@ -0,0 +1,14 @@ +>>> import f2py2e +>>> r=f2py2e.run_main(['-m','scalar','docs/usersguide/scalar.f']) +Reading fortran codes... + Reading file 'docs/usersguide/scalar.f' +Post-processing... + Block: scalar + Block: FOO +Building modules... + Building module "scalar"... + Wrote C/API module "scalar" to file "./scalarmodule.c" +>>> print r +{'scalar': {'h': ['/home/users/pearu/src_cvs/f2py2e/src/fortranobject.h'], + 'csrc': ['./scalarmodule.c', + '/home/users/pearu/src_cvs/f2py2e/src/fortranobject.c']}} diff --git a/numpy/f2py/docs/usersguide/scalar.f b/numpy/f2py/docs/usersguide/scalar.f new file mode 100644 index 000000000..c22f639ed --- /dev/null +++ b/numpy/f2py/docs/usersguide/scalar.f @@ -0,0 +1,12 @@ +C FILE: SCALAR.F + SUBROUTINE FOO(A,B) + REAL*8 A, B +Cf2py intent(in) a +Cf2py intent(inout) b + PRINT*, " A=",A," B=",B + PRINT*, "INCREMENT A AND B" + A = A + 1D0 + B = B + 1D0 + PRINT*, "NEW A=",A," B=",B + END +C END OF FILE SCALAR.F diff --git a/numpy/f2py/docs/usersguide/scalar_session.dat b/numpy/f2py/docs/usersguide/scalar_session.dat new file mode 100644 index 000000000..4fe8c03b1 --- /dev/null +++ b/numpy/f2py/docs/usersguide/scalar_session.dat @@ -0,0 +1,21 @@ +>>> import scalar +>>> print scalar.foo.__doc__ +foo - Function signature: + foo(a,b) +Required arguments: + a : input float + b : in/output rank-0 array(float,'d') + +>>> scalar.foo(2,3) + A= 2. B= 3. + INCREMENT A AND B + NEW A= 3. B= 4. +>>> import Numeric +>>> a=Numeric.array(2) # these are integer rank-0 arrays +>>> b=Numeric.array(3) +>>> scalar.foo(a,b) + A= 2. B= 3. + INCREMENT A AND B + NEW A= 3. B= 4. +>>> print a,b # note that only b is changed in situ +2 4
\ No newline at end of file diff --git a/numpy/f2py/docs/usersguide/setup_example.py b/numpy/f2py/docs/usersguide/setup_example.py new file mode 100644 index 000000000..a7d27403a --- /dev/null +++ b/numpy/f2py/docs/usersguide/setup_example.py @@ -0,0 +1,19 @@ +#!/usr/bin/env python +# File: setup_example.py + +from scipy_distutils.core import Extension + +ext1 = Extension(name = 'scalar', + sources = ['scalar.f']) +ext2 = Extension(name = 'fib2', + sources = ['fib2.pyf','fib1.f']) + +if __name__ == "__main__": + from scipy_distutils.core import setup + setup(name = 'f2py_example', + description = "F2PY Users Guide examples", + author = "Pearu Peterson", + author_email = "pearu@cens.ioc.ee", + ext_modules = [ext1,ext2] + ) +# End of setup_example.py diff --git a/numpy/f2py/docs/usersguide/spam.pyf b/numpy/f2py/docs/usersguide/spam.pyf new file mode 100644 index 000000000..21ea18b77 --- /dev/null +++ b/numpy/f2py/docs/usersguide/spam.pyf @@ -0,0 +1,19 @@ +! -*- f90 -*- +python module spam + usercode ''' + static char doc_spam_system[] = "Execute a shell command."; + static PyObject *spam_system(PyObject *self, PyObject *args) + { + char *command; + int sts; + + if (!PyArg_ParseTuple(args, "s", &command)) + return NULL; + sts = system(command); + return Py_BuildValue("i", sts); + } + ''' + pymethoddef ''' + {"system", spam_system, METH_VARARGS, doc_spam_system}, + ''' +end python module spam diff --git a/numpy/f2py/docs/usersguide/spam_session.dat b/numpy/f2py/docs/usersguide/spam_session.dat new file mode 100644 index 000000000..7f99d13f9 --- /dev/null +++ b/numpy/f2py/docs/usersguide/spam_session.dat @@ -0,0 +1,5 @@ +>>> import spam +>>> status = spam.system('whoami') +pearu +>> status = spam.system('blah') +sh: line 1: blah: command not found
\ No newline at end of file diff --git a/numpy/f2py/docs/usersguide/string.f b/numpy/f2py/docs/usersguide/string.f new file mode 100644 index 000000000..9246f02e7 --- /dev/null +++ b/numpy/f2py/docs/usersguide/string.f @@ -0,0 +1,21 @@ +C FILE: STRING.F + SUBROUTINE FOO(A,B,C,D) + CHARACTER*5 A, B + CHARACTER*(*) C,D +Cf2py intent(in) a,c +Cf2py intent(inout) b,d + PRINT*, "A=",A + PRINT*, "B=",B + PRINT*, "C=",C + PRINT*, "D=",D + PRINT*, "CHANGE A,B,C,D" + A(1:1) = 'A' + B(1:1) = 'B' + C(1:1) = 'C' + D(1:1) = 'D' + PRINT*, "A=",A + PRINT*, "B=",B + PRINT*, "C=",C + PRINT*, "D=",D + END +C END OF FILE STRING.F diff --git a/numpy/f2py/docs/usersguide/string_session.dat b/numpy/f2py/docs/usersguide/string_session.dat new file mode 100644 index 000000000..64ebcb3f4 --- /dev/null +++ b/numpy/f2py/docs/usersguide/string_session.dat @@ -0,0 +1,27 @@ +>>> import mystring +>>> print mystring.foo.__doc__ +foo - Function signature: + foo(a,b,c,d) +Required arguments: + a : input string(len=5) + b : in/output rank-0 array(string(len=5),'c') + c : input string(len=-1) + d : in/output rank-0 array(string(len=-1),'c') + +>>> import Numeric +>>> a=Numeric.array('123') +>>> b=Numeric.array('123') +>>> c=Numeric.array('123') +>>> d=Numeric.array('123') +>>> mystring.foo(a,b,c,d) + A=123 + B=123 + C=123 + D=123 + CHANGE A,B,C,D + A=A23 + B=B23 + C=C23 + D=D23 +>>> a.tostring(),b.tostring(),c.tostring(),d.tostring() +('123', 'B23', '123', 'D23')
\ No newline at end of file diff --git a/numpy/f2py/docs/usersguide/var.pyf b/numpy/f2py/docs/usersguide/var.pyf new file mode 100644 index 000000000..8275ff3af --- /dev/null +++ b/numpy/f2py/docs/usersguide/var.pyf @@ -0,0 +1,11 @@ +! -*- f90 -*- +python module var + usercode ''' + int BAR = 5; + ''' + interface + usercode ''' + PyDict_SetItemString(d,"BAR",PyInt_FromLong(BAR)); + ''' + end interface +end python module diff --git a/numpy/f2py/docs/usersguide/var_session.dat b/numpy/f2py/docs/usersguide/var_session.dat new file mode 100644 index 000000000..fb0f798bf --- /dev/null +++ b/numpy/f2py/docs/usersguide/var_session.dat @@ -0,0 +1,3 @@ +>>> import var +>>> var.BAR +5
\ No newline at end of file |