Annotation of python/f2py2e/docs/README.txt, revision 1.47

1.23      pearu       1: .. -*- rest -*-
1.1       pearu       2: 
1.2       pearu       3: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                      4:  F2PY: Fortran to Python interface generator
                      5: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.1       pearu       6: 
                      7: :Author: Pearu Peterson <pearu@cens.ioc.ee>
                      8: :License: LGPL_.
1.2       pearu       9: :Web-site: http://cens.ioc.ee/projects/f2py2e/
1.6       pearu      10: :Discussions to: `f2py-users mailing list`_
1.18      pearu      11: :Documentation: `User's Guide`__, FAQ__
1.8       pearu      12: :Platforms: All
1.47    ! pearu      13: :Date: $Date: 2005/01/30 18:54:53 $
1.1       pearu      14: 
                     15: .. _f2py-users mailing list: http://cens.ioc.ee/mailman/listinfo/f2py-users/
1.18      pearu      16: __ usersguide/index.html
                     17: __ FAQ.html
1.1       pearu      18: 
1.8       pearu      19: -------------------------------
1.6       pearu      20: 
1.8       pearu      21: .. topic:: NEWS!!!
1.43      pearu      22: 
1.47    ! pearu      23:   July 19, 2007
        !            24: 
        !            25:     F2PY is now part of `NumPy`__. All the development and maintenance
        !            26:     of F2PY is carried out under NumPy SVN tree. See `F2PY`__ for more
        !            27:     information. If you need F2PY with Numeric or Numarray array support
        !            28:     then you must use the F2PY version found below.
        !            29: 
        !            30:   __ http://numpy.scipy.org/
        !            31:   __ http://www.scipy.org/F2py
        !            32: 
1.46      pearu      33:   January 30, 2005
1.45      pearu      34: 
1.46      pearu      35:     Latest F2PY release (version 2.45.241_1926).
1.45      pearu      36:     New features: wrapping unsigned integers, support for ``.pyf.src`` template files,
                     37:     callback arguments can now be CObjects, fortran objects, built-in functions.
                     38:     Introduced ``intent(aux)`` attribute. Wrapped objects have ``_cpointer``
                     39:     attribute holding C pointer to wrapped functions or variables.
                     40:     Many bug fixes and improvements, updated documentation.
                     41:     `Differences with the previous release (version 2.43.239_1831)`__.
                     42: 
1.46      pearu      43:   __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.163&r2=1.137&f=h
1.45      pearu      44: 
1.43      pearu      45:   October 4, 2004
                     46:     F2PY bug fix release (version 2.43.239_1831).
                     47:     Better support for 64-bit platforms.
                     48:     Introduced ``--help-link`` and ``--link-<resource>`` options.
                     49:     Bug fixes.
                     50:     `Differences with the previous release (version 2.43.239_1806)`__.
                     51: 
                     52:   __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.137&r2=1.131&f=h
1.25      pearu      53: 
1.38      pearu      54:   September 25, 2004
1.41      pearu      55:     Latest F2PY release (version 2.43.239_1806). 
1.38      pearu      56:     Support for ``ENTRY`` statement. New attributes:
                     57:     ``intent(inplace)``, ``intent(callback)``. Supports Numarray 1.1.
                     58:     Introduced ``-*- fix -*-`` header content. Improved ``PARAMETER`` support.
                     59:     Documentation updates. `Differences with the previous release
                     60:     (version 2.39.235-1693)`__.
                     61: 
1.41      pearu      62:   __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.131&r2=1.98&f=h
1.35      pearu      63: 
1.45      pearu      64:   `History of NEWS`__
1.18      pearu      65: 
1.45      pearu      66:   __ OLDNEWS.html
1.8       pearu      67: 
                     68: -------------------------------
1.7       pearu      69: 
                     70: .. Contents::
1.2       pearu      71: 
                     72: ==============
                     73:  Introduction
                     74: ==============
1.1       pearu      75: 
                     76: The purpose of the F2PY --*Fortran to Python interface generator*--
                     77: project is to provide connection between Python_ and Fortran
1.3       pearu      78: languages. F2PY is a Python extension tool for creating Python C/API
1.1       pearu      79: modules from (handwritten or F2PY generated) signature files (or
                     80: directly from Fortran sources). The generated extension modules
                     81: facilitate:
                     82: 
                     83: * Calling Fortran 77/90/95, Fortran 90/95 module, and C functions from
                     84:   Python.
                     85: 
                     86: * Accessing Fortran 77 ``COMMON`` blocks and Fortran 90/95 module
                     87:   data (including allocatable arrays) from Python.
                     88: 
                     89: * Calling Python functions from Fortran or C (call-backs).
                     90: 
                     91: * Automatically handling the difference in the data storage order of
                     92:   multi-dimensional Fortran and Numerical Python (i.e. C) arrays.
                     93: 
                     94: In addition, F2PY can build the generated extension modules to shared
                     95: libraries with one command. F2PY uses the ``scipy_distutils`` module
1.7       pearu      96: from SciPy_ that supports number of major Fortran compilers.
                     97: 
                     98: ..
                     99:   (see `COMPILERS.txt`_ for more information).
1.1       pearu     100: 
                    101: F2PY generated extension modules depend on NumPy_ package that
                    102: provides fast multi-dimensional array language facility to Python.
                    103: 
                    104: 
1.2       pearu     105: ---------------
                    106:  Main features
                    107: ---------------
1.1       pearu     108: 
                    109: Here follows a more detailed list of F2PY features:
                    110: 
1.2       pearu     111: * F2PY scans real Fortran codes to produce the so-called signature
                    112:   files (.pyf files). The signature files contain all the information
                    113:   (function names, arguments and their types, etc.)  that is needed to
                    114:   construct Python bindings to Fortran (or C) functions.
                    115: 
                    116:   The syntax of signature files is borrowed from the
1.1       pearu     117:   Fortran 90/95 language specification and has some F2PY specific
                    118:   extensions. The signature files can be modified to dictate how
1.2       pearu     119:   Fortran (or C) programs are called from Python:
1.1       pearu     120: 
                    121:     + F2PY solves dependencies between arguments (this is relevant for
                    122:       the order of initializing variables in extension modules).
                    123: 
                    124:     + Arguments can be specified to be optional or hidden that
                    125:       simplifies calling Fortran programs from Python considerably.
                    126: 
                    127:     + In principle, one can design any Python signature for a given
                    128:       Fortran function, e.g. change the order arguments, introduce
                    129:       auxiliary arguments, hide the arguments, process the arguments
                    130:       before passing to Fortran, return arguments as output of F2PY
                    131:       generated functions, etc.
                    132: 
                    133: * F2PY automatically generates __doc__ strings (and optionally LaTeX
                    134:   documentation) for extension modules.
                    135: 
                    136: * F2PY generated functions accept arbitrary (but sensible) Python
                    137:   objects as arguments. The F2PY interface automatically takes care of
                    138:   type-casting and handling of non-contiguous arrays.
                    139: 
                    140: * The following Fortran constructs are recognized by F2PY:
                    141: 
                    142:   + All basic Fortran types::
                    143: 
                    144:       integer[ | *1 | *2 | *4 | *8 ], logical[ | *1 | *2 | *4 | *8 ]
1.45      pearu     145:       integer*([ -1 | -2 | -4 | -8 ])
1.1       pearu     146:       character[ | *(*) | *1 | *2 | *3 | ... ]
                    147:       real[ | *4 | *8 | *16 ], double precision
                    148:       complex[ | *8 | *16 | *32 ]
                    149: 
1.45      pearu     150:     Negative ``integer`` kinds are used to wrap unsigned integers.
                    151: 
1.1       pearu     152:   + Multi-dimensional arrays of all basic types with the following
                    153:     dimension specifications::
                    154: 
                    155:       <dim> | <start>:<end> | * | :
                    156: 
                    157:   + Attributes and statements::
                    158:      
                    159:       intent([ in | inout | out | hide | in,out | inout,out | c |
1.45      pearu     160:                copy | cache | callback | inplace | aux ])
1.1       pearu     161:       dimension(<dimspec>)
1.18      pearu     162:       common, parameter
                    163:       allocatable
                    164:       optional, required, external
1.1       pearu     165:       depend([<names>])
                    166:       check([<C-booleanexpr>])
                    167:       note(<LaTeX text>)
1.18      pearu     168:       usercode, callstatement, callprotoargument, threadsafe, fortranname
1.37      pearu     169:       pymethoddef
1.35      pearu     170:       entry
1.1       pearu     171: 
                    172: * Because there are only little (and easily handleable) differences
                    173:   between calling C and Fortran functions from F2PY generated
                    174:   extension modules, then F2PY is also well suited for wrapping C
                    175:   libraries to Python.
                    176: 
                    177: * Practice has shown that F2PY generated interfaces (to C or Fortran
                    178:   functions) are less error prone and even more efficient than
                    179:   handwritten extension modules. The F2PY generated interfaces are
                    180:   easy to maintain and any future optimization of F2PY generated
                    181:   interfaces transparently apply to extension modules by just
                    182:   regenerating them with the latest version of F2PY.
                    183: 
1.7       pearu     184: * `F2PY Users Guide and Reference Manual`_
                    185: 
                    186: 
1.2       pearu     187: ===============
                    188:  Prerequisites
                    189: ===============
1.1       pearu     190: 
                    191: F2PY requires the following software installed:
                    192: 
1.45      pearu     193: * Python_ (versions 1.5.2 or later; 2.1 and up are recommended).
                    194:   You must have python-dev package installed.
1.11      pearu     195: * NumPy_ (versions 13 or later; 20.x, 21.x, 22.x, 23.x are recommended)
1.38      pearu     196: * Numarray_ (version 0.9 and up), optional, partial support.
                    197: * Scipy_distutils (version 0.2.2 and up are recommended) from SciPy_
                    198:   project. Get it from Scipy CVS or download it below.
1.1       pearu     199: 
1.2       pearu     200: Python 1.x users also need distutils_.
1.1       pearu     201: 
                    202: Of course, to build extension modules, you'll need also working C
1.10      pearu     203: and/or Fortran compilers installed.
                    204: 
1.2       pearu     205: ==========
                    206:  Download
                    207: ==========
                    208: 
1.38      pearu     209: You can download the sources for the latest F2PY and scipy_distutils
                    210: releases as:
1.1       pearu     211: 
1.2       pearu     212: * `2.x`__/`F2PY-2-latest.tar.gz`__
1.38      pearu     213: * `2.x`__/`scipy_distutils-latest.tar.gz`__
1.1       pearu     214: 
1.38      pearu     215: Windows users might be interested in Win32 installer for F2PY and
                    216: Scipy_distutils (these installers are built using Python 2.3):
1.27      pearu     217: 
1.42      pearu     218: * `2.x`__/`F2PY-2-latest.win32.exe`__
1.38      pearu     219: * `2.x`__/`scipy_distutils-latest.win32.exe`__
1.27      pearu     220: 
1.1       pearu     221: Older releases are also available in the directories
1.2       pearu     222: `rel-0.x`__, `rel-1.x`__, `rel-2.x`__, `rel-3.x`__, `rel-4.x`__, `rel-5.x`__,
1.1       pearu     223: if you need them.
                    224: 
1.2       pearu     225: .. __: 2.x/
                    226: .. __: 2.x/F2PY-2-latest.tar.gz
1.29      pearu     227: .. __: 2.x/
1.38      pearu     228: .. __: 2.x/scipy_distutils-latest.tar.gz
1.29      pearu     229: .. __: 2.x/
1.42      pearu     230: .. __: 2.x/F2PY-2-latest.win32.exe
1.29      pearu     231: .. __: 2.x/
1.38      pearu     232: .. __: 2.x/scipy_distutils-latest.win32.exe
1.2       pearu     233: .. __: rel-0.x
                    234: .. __: rel-1.x
                    235: .. __: rel-2.x
                    236: .. __: rel-3.x
                    237: .. __: rel-4.x
                    238: .. __: rel-5.x
                    239: 
1.36      pearu     240: Development version of F2PY from CVS is available as `f2py2e.tar.gz`__.
                    241: 
                    242: __ http://cens.ioc.ee/cgi-bin/viewcvs.cgi/python/f2py2e/f2py2e.tar.gz?tarball=1
                    243: 
1.45      pearu     244: Debian Sid users can simply install ``python-f2py`` package.
1.36      pearu     245: 
1.2       pearu     246: ==============
                    247:  Installation
                    248: ==============
1.1       pearu     249: 
1.38      pearu     250: Unpack the source file, change to directrory ``F2PY-?-???/`` and run
                    251: (you may need to become a root)::
1.1       pearu     252: 
                    253:   python setup.py install
                    254: 
1.6       pearu     255: The F2PY installation installs a Python package ``f2py2e`` to your
                    256: Python ``site-packages`` directory and a script ``f2py`` to your
                    257: Python executable path. 
1.1       pearu     258: 
1.2       pearu     259: See also Installation__ section in `F2PY FAQ`_.
1.1       pearu     260: 
1.2       pearu     261: .. __: FAQ.html#installation
1.44      pearu     262: 
                    263: Similarly, to install ``scipy_distutils``, unpack its tar-ball and run::
                    264: 
                    265:   python setup.py install
1.1       pearu     266: 
1.2       pearu     267: =======
                    268:  Usage
                    269: =======
1.1       pearu     270: 
                    271: To check if F2PY is installed correctly, run
                    272: ::
                    273: 
                    274:   f2py
                    275: 
                    276: without any arguments. This should print out the usage information of
                    277: the ``f2py`` program.
                    278: 
                    279: Next, try out the following three steps:
                    280: 
1.4       pearu     281: 1) Create a Fortran file `hello.f`__ that contains::
1.1       pearu     282: 
                    283:     C File hello.f
1.4       pearu     284:           subroutine foo (a)
                    285:           integer a
                    286:           print*, "Hello from Fortran!"
                    287:           print*, "a=",a
                    288:           end
                    289: 
1.7       pearu     290: __ hello.f
                    291: 
                    292: 2) Run
1.1       pearu     293: 
1.7       pearu     294:   ::
1.1       pearu     295:   
                    296:     f2py -c -m hello hello.f
                    297: 
1.20      pearu     298:   This will build an extension module ``hello.so`` (or ``hello.sl``,
                    299:   or ``hello.pyd``, etc. depending on your platform) into the current
                    300:   directory.
1.1       pearu     301: 
                    302: 3) Now in Python try::
                    303: 
                    304:     >>> import hello
                    305:     >>> print hello.__doc__
1.20      pearu     306:     >>> print hello.foo.__doc__
1.1       pearu     307:     >>> hello.foo(4)     
                    308:      Hello from Fortran!
                    309:      a= 4
                    310:     >>> 
                    311: 
1.2       pearu     312: If the above works, then you can try out more thorough 
1.7       pearu     313: `F2PY unit tests`__ and read the `F2PY Users Guide and Reference Manual`_.
1.2       pearu     314: 
1.7       pearu     315: __ FAQ.html#q-how-to-test-if-f2py-is-working-correctly
1.2       pearu     316: 
                    317: ===============
                    318:  Documentation
                    319: ===============
1.1       pearu     320: 
                    321: The documentation of the F2PY project is collected in ``f2py2e/docs/``
                    322: directory. It contains the following documents:
                    323: 
1.14      pearu     324: `README.txt`_ (in CVS__)
1.1       pearu     325:   The first thing to read about F2PY -- this document.
                    326: 
1.14      pearu     327: __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/README.txt?rev=HEAD&content-type=text/x-cvsweb-markup
                    328: 
1.13      pearu     329: `usersguide/index.txt`_, `usersguide/f2py_usersguide.pdf`_
1.7       pearu     330:   F2PY Users Guide and Reference Manual. Contains lots of examples.
1.1       pearu     331: 
1.14      pearu     332: `FAQ.txt`_ (in CVS__)
1.1       pearu     333:   F2PY Frequently Asked Questions.
                    334: 
1.14      pearu     335: __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/FAQ.txt?rev=HEAD&content-type=text/x-cvsweb-markup
                    336: 
                    337: `TESTING.txt`_ (in CVS__)
1.5       pearu     338:   About F2PY testing site. What tests are available and how to run them.
                    339: 
1.14      pearu     340: __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/TESTING.txt?rev=HEAD&content-type=text/x-cvsweb-markup
                    341: 
1.15      pearu     342: `HISTORY.txt`_ (in CVS__)
1.2       pearu     343:   A list of latest changes in F2PY. This is the most up-to-date
1.15      pearu     344:   document on F2PY.
                    345: 
                    346: __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt?rev=HEAD&content-type=text/x-cvsweb-markup
1.1       pearu     347: 
                    348: `THANKS.txt`_
                    349:   Acknowledgments.
                    350: 
1.7       pearu     351: ..
                    352:   `COMPILERS.txt`_
                    353:   Compiler and platform specific notes.
                    354: 
1.6       pearu     355: ===============
                    356:  Mailing list
                    357: ===============
                    358: 
                    359: A mailing list f2py-users@cens.ioc.ee is open for F2PY releated
                    360: discussion/questions/etc.
                    361: 
                    362: * `Subscribe..`__ 
                    363: * `Archives..`__
                    364: 
1.7       pearu     365: __ http://cens.ioc.ee/mailman/listinfo/f2py-users
                    366: __ http://cens.ioc.ee/pipermail/f2py-users
1.6       pearu     367: 
1.1       pearu     368: 
1.2       pearu     369: =====
                    370:  CVS
                    371: =====
1.1       pearu     372: 
                    373: F2PY is being developed under CVS_. The CVS version of F2PY can be
                    374: obtained as follows:
                    375: 
                    376: 1) First you need to login (the password is ``guest``)::
                    377: 
                    378:     cvs -d :pserver:anonymous@cens.ioc.ee:/home/cvs login
                    379: 
                    380: 2) and then do the checkout::
                    381: 
                    382:     cvs -z6 -d :pserver:anonymous@cens.ioc.ee:/home/cvs checkout f2py2e
                    383: 
1.2       pearu     384: 3) You can update your local F2PY tree ``f2py2e/`` by executing::
1.1       pearu     385: 
                    386:     cvs -z6 update -P -d
                    387: 
1.36      pearu     388: You can browse the `F2PY CVS`_ repository.
1.14      pearu     389: 
                    390: ===============
                    391:  Contributions
                    392: ===============
                    393: 
                    394: * `A short introduction to F2PY`__ by Pierre Schnizer.
                    395: 
                    396: * `F2PY notes`__ by Fernando Perez.
                    397: 
1.45      pearu     398: * `Debian packages of F2PY`__ by Josť Fonseca. [OBSOLETE, Debian Sid
                    399:   ships python-f2py package]
1.14      pearu     400: 
                    401: __ http://fubphpc.tu-graz.ac.at/~pierre/f2py_tutorial.tar.gz
                    402: __ http://cens.ioc.ee/pipermail/f2py-users/2003-April/000472.html
                    403: __ http://jrfonseca.dyndns.org/debian/
1.1       pearu     404: 
                    405: 
1.2       pearu     406: ===============
                    407:  Related sites
                    408: ===============
1.1       pearu     409: 
                    410: * `Numerical Python`_ -- adds a fast array facility to the Python language.
                    411: * Pyfort_ -- A Python-Fortran connection tool.
                    412: * SciPy_ -- An open source library of scientific tools for Python.
                    413: * `Scientific Python`_ -- A collection of Python modules that are
                    414:   useful for scientific computing.
                    415: * `The Fortran Company`_ -- A place to find products, services, and general
                    416:   information related to the Fortran programming language.
                    417: * `American National Standard Programming Language FORTRAN ANSI(R) X3.9-1978`__
                    418: * `J3`_ -- The US Fortran standards committee.
                    419: * SWIG_ -- A software development tool that connects programs written
                    420:   in C and C++ with a variety of high-level programming languages. 
                    421: * `Mathtools.net`_ -- A technical computing portal for all scientific
                    422:   and engineering needs. 
                    423: 
                    424: .. __: http://www.fortran.com/fortran/F77_std/rjcnf.html
                    425: 
                    426: .. References
                    427:    ==========
1.2       pearu     428: 
1.7       pearu     429: 
                    430: .. _F2PY Users Guide and Reference Manual: usersguide/index.html
                    431: .. _usersguide/index.txt: usersguide/index.html
1.13      pearu     432: .. _usersguide/f2py_usersguide.pdf: usersguide/f2py_usersguide.pdf
1.2       pearu     433: .. _README.txt: README.html
                    434: .. _COMPILERS.txt: COMPILERS.html
                    435: .. _F2PY FAQ:
                    436: .. _FAQ.txt: FAQ.html
                    437: .. _HISTORY.txt: HISTORY.html
1.12      pearu     438: .. _HISTORY.txt from CVS: http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt?rev=HEAD&content-type=text/x-cvsweb-markup
1.2       pearu     439: .. _THANKS.txt: THANKS.html
1.5       pearu     440: .. _TESTING.txt: TESTING.html
1.36      pearu     441: .. _F2PY CVS2: http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/
                    442: .. _F2PY CVS: http://cens.ioc.ee/cgi-bin/viewcvs.cgi/python/f2py2e/
1.2       pearu     443: 
                    444: .. _CVS: http://www.cvshome.org/
1.1       pearu     445: .. _Python: http://www.python.org/
                    446: .. _SciPy: http://www.scipy.org/
                    447: .. _NumPy: http://www.numpy.org/
1.36      pearu     448: .. _Numarray: http://www.stsci.edu/resources/software_hardware/numarray
1.1       pearu     449: .. _docutils: http://docutils.sourceforge.net/
                    450: .. _distutils: http://www.python.org/sigs/distutils-sig/
                    451: .. _LGPL: http://www.fsf.org/copyleft/lesser.html
                    452: .. _Numerical Python: http://www.numpy.org/
                    453: .. _Pyfort: http://pyfortran.sourceforge.net/
                    454: .. _Scientific Python: 
                    455:    http://starship.python.net/crew/hinsen/scientific.html
                    456: .. _The Fortran Company: http://www.fortran.com/fortran/
                    457: .. _J3: http://www.j3-fortran.org/
                    458: .. _Mathtools.net: http://www.mathtools.net/
                    459: .. _SWIG: http://www.swig.org/
                    460: 
                    461: ..
                    462:    Local Variables:
                    463:    mode: indented-text
                    464:    indent-tabs-mode: nil
                    465:    sentence-end-double-space: t
                    466:    fill-column: 70
                    467:    End:

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>