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>
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to README.txt CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CENS] / python / f2py2e / docs