2
======================================================================
3
F2PY Frequently Asked Questions
4
======================================================================
11
Q: How to get started?
12
----------------------
14
First, install__ F2PY. Then check that F2PY installation works
15
properly (see below__). Try out a `simple example`__.
17
Read `F2PY Users Guide and Reference Manual`__. It contains lots
20
If you have any questions/problems when using F2PY, don't hesitate to
21
turn to `F2PY users mailing list`__ or directly to me.
23
__ index.html#installation
26
__ usersguide/index.html
27
__ index.html#mailing-list
29
Q: When to report bugs?
30
-----------------------
32
* If F2PY scanning fails on Fortran sources that otherwise compile
35
* After checking that you have the latest version of F2PY from its
36
CVS. It is possible that a bug has been fixed already. See also the
37
log entries in the file `HISTORY.txt`_ (`HISTORY.txt in CVS`_).
39
* After checking that your Python and Numerical Python installations
42
* After checking that your C and Fortran compilers work correctly.
45
Q: How to report bugs?
46
----------------------
48
You can send bug reports directly to me. Please, include information
49
about your platform (operating system, version) and
50
compilers/linkers, e.g. the output (both stdout/stderr) of
53
python -c 'import f2py2e.diagnose;f2py2e.diagnose.run()'
55
Feel free to add any other relevant information. However, avoid
56
sending the output of F2PY generated ``.pyf`` files (unless they are
57
manually modified) or any binary files like shared libraries or object
60
While reporting bugs, you may find the following notes useful:
62
* `How To Ask Questions The Smart Way`__ by E. S. Raymond and R. Moen.
64
* `How to Report Bugs Effectively`__ by S. Tatham.
66
__ http://www.catb.org/~esr/faqs/smart-questions.html
67
__ http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
72
Q: How to use F2PY with different Python versions?
73
--------------------------------------------------
75
Run the installation command using the corresponding Python
76
executable. For example,
79
python2.1 setup.py install
81
installs the ``f2py`` script as ``f2py2.1``.
83
See `Distutils User Documentation`__ for more information how to
84
install Python modules to non-standard locations.
86
__ http://www.python.org/sigs/distutils-sig/doc/inst/inst.html
89
Q: Why F2PY is not working after upgrading?
90
-------------------------------------------
92
If upgrading from F2PY version 2.3.321 or earlier then remove all f2py
93
specific files from ``/path/to/python/bin`` directory before
94
running installation command.
96
Q: How to get/upgrade numpy_distutils when using F2PY from CVS?
97
---------------------------------------------------------------
99
To get numpy_distutils from SciPy CVS repository, run
105
This will checkout numpy_distutils to the current directory.
107
You can upgrade numpy_distutils by executing
110
cd cvs/f2py2e/numpy_distutils
113
and install it by executing
116
cd cvs/f2py2e/numpy_distutils
117
python setup_numpy_distutils.py install
119
In most of the time, f2py2e and numpy_distutils can be upgraded
125
Q: How to test if F2PY is installed correctly?
126
----------------------------------------------
133
without arguments. If F2PY is installed correctly then it should print
134
the usage information for f2py.
136
Q: How to test if F2PY is working correctly?
137
--------------------------------------------
139
For a quick test, try out an example problem from Usage__
140
section in `README.txt`_.
144
For running F2PY unit tests, see `TESTING.txt`_.
147
Q: How to run tests and examples in f2py2e/test-suite/ directory?
148
---------------------------------------------------------------------
150
You shouldn't. These tests are obsolete and I have no intention to
151
make them work. They will be removed in future.
154
Compiler/Platform-specific issues
155
=================================
157
Q: What are supported platforms and compilers?
158
----------------------------------------------
160
F2PY is developed on Linux system with a GCC compiler (versions
161
2.95.x, 3.x). Fortran 90 related hooks are tested against Intel
162
Fortran Compiler. F2PY should work under any platform where Python and
163
Numeric are installed and has supported Fortran compiler installed.
165
To see a list of supported compilers, execute::
167
f2py -c --help-fcompiler
171
List of available Fortran compilers:
172
--fcompiler=gnu GNU Fortran Compiler (3.3.4)
173
--fcompiler=intel Intel Fortran Compiler for 32-bit apps (8.0)
174
List of unavailable Fortran compilers:
175
--fcompiler=absoft Absoft Corp Fortran Compiler
176
--fcompiler=compaq Compaq Fortran Compiler
177
--fcompiler=compaqv DIGITAL|Compaq Visual Fortran Compiler
178
--fcompiler=hpux HP Fortran 90 Compiler
179
--fcompiler=ibm IBM XL Fortran Compiler
180
--fcompiler=intele Intel Fortran Compiler for Itanium apps
181
--fcompiler=intelev Intel Visual Fortran Compiler for Itanium apps
182
--fcompiler=intelv Intel Visual Fortran Compiler for 32-bit apps
183
--fcompiler=lahey Lahey/Fujitsu Fortran 95 Compiler
184
--fcompiler=mips MIPSpro Fortran Compiler
185
--fcompiler=nag NAGWare Fortran 95 Compiler
186
--fcompiler=pg Portland Group Fortran Compiler
187
--fcompiler=sun Sun|Forte Fortran 95 Compiler
188
--fcompiler=vast Pacific-Sierra Research Fortran 90 Compiler
189
List of unimplemented Fortran compilers:
190
--fcompiler=f Fortran Company/NAG F Compiler
191
For compiler details, run 'config_fc --verbose' setup command.
194
Q: How to use the F compiler in F2PY?
195
-------------------------------------
197
Read `f2py2e/doc/using_F_compiler.txt`__. It describes why the F
198
compiler cannot be used in a normal way (i.e. using ``-c`` switch) to
199
build F2PY generated modules. It also gives a workaround to this
202
__ http://cens.ioc.ee/cgi-bin/viewcvs.cgi/python/f2py2e/doc/using_F_compiler.txt?rev=HEAD&content-type=text/vnd.viewcvs-markup
204
Q: How to use F2PY under Windows?
205
---------------------------------
207
F2PY can be used both within Cygwin__ and MinGW__ environments under
208
Windows, F2PY can be used also in Windows native terminal.
209
See the section `Setting up environment`__ for Cygwin and MinGW.
211
__ http://cygwin.com/
212
__ http://www.mingw.org/
213
__ http://cens.ioc.ee/~pearu/numpy/BUILD_WIN32.html#setting-up-environment
215
Install numpy_distutils and F2PY. Win32 installers of these packages
216
are provided in `F2PY Download`__ section.
218
__ http://cens.ioc.ee/projects/f2py2e/#download
220
Use ``--compiler=`` and ``--fcompiler`` F2PY command line switches to
221
to specify which C and Fortran compilers F2PY should use, respectively.
223
Under MinGW environment, ``mingw32`` is default for a C compiler.
225
Supported and Unsupported Features
226
==================================
228
Q: Does F2PY support ``ENTRY`` statements?
229
------------------------------------------
231
Yes, starting at F2PY version higher than 2.39.235_1706.
233
Q: Does F2PY support derived types in F90 code?
234
-----------------------------------------------
236
Not yet. However I do have plans to implement support for F90 TYPE
237
constructs in future. But note that the task in non-trivial and may
238
require the next edition of F2PY for which I don't have resources to
239
work with at the moment.
241
Jeffrey Hagelberg from LLNL has made progress on adding
242
support for derived types to f2py. He writes:
244
At this point, I have a version of f2py that supports derived types
245
for most simple cases. I have multidimensional arrays of derived
246
types and allocatable arrays of derived types working. I'm just now
247
starting to work on getting nested derived types to work. I also
248
haven't tried putting complex number in derived types yet.
250
Hopefully he can contribute his changes to f2py soon.
252
Q: Does F2PY support pointer data in F90 code?
253
-----------------------------------------------
255
No. I have never needed it and I haven't studied if there are any
256
obstacles to add pointer data support to F2PY.
258
Q: What if Fortran 90 code uses ``<type spec>(kind=KIND(..))``?
259
---------------------------------------------------------------
261
Currently, F2PY can handle only ``<type spec>(kind=<kindselector>)``
262
declarations where ``<kindselector>`` is a numeric integer (e.g. 1, 2,
263
4,...) but not a function call ``KIND(..)`` or any other
264
expression. F2PY needs to know what would be the corresponding C type
265
and a general solution for that would be too complicated to implement.
267
However, F2PY provides a hook to overcome this difficulty, namely,
268
users can define their own <Fortran type> to <C type> maps. For
269
example, if Fortran 90 code contains::
271
REAL(kind=KIND(0.0D0)) ...
273
then create a file ``.f2py_f2cmap`` (into the working directory)
274
containing a Python dictionary::
276
{'real':{'KIND(0.0D0)':'double'}}
280
Or more generally, the file ``.f2py_f2cmap`` must contain a dictionary
283
<Fortran typespec> : {<selector_expr>:<C type>}
285
that defines mapping between Fortran type::
287
<Fortran typespec>([kind=]<selector_expr>)
289
and the corresponding ``<C type>``. ``<C type>`` can be one of the
305
For more information, see ``f2py2e/capi_maps.py``.
310
Q: How F2PY distinguishes from Pyfort?
311
--------------------------------------
313
F2PY and Pyfort have very similar aims and ideology of how they are
314
targeted. Both projects started to evolve in the same year 1999
315
independently. When we discovered each others projects, a discussion
316
started to join the projects but that unfortunately failed for
317
various reasons, e.g. both projects had evolved too far that merging
318
the tools would have been impractical and giving up the efforts that
319
the developers of both projects have made was unacceptable to both
320
parties. And so, nowadays we have two tools for connecting Fortran
321
with Python and this fact will hardly change in near future. To decide
322
which one to choose is a matter of taste, I can only recommend to try
323
out both to make up your choice.
325
At the moment F2PY can handle more wrapping tasks than Pyfort,
326
e.g. with F2PY one can wrap Fortran 77 common blocks, Fortran 90
327
module routines, Fortran 90 module data (including allocatable
328
arrays), one can call Python from Fortran, etc etc. F2PY scans Fortran
329
codes to create signature (.pyf) files. F2PY is free from most of the
330
limitations listed in in `the corresponding section of Pyfort
333
__ http://pyfortran.sourceforge.net/pyfort/pyfort_reference.htm#pgfId-296925
335
There is a conceptual difference on how F2PY and Pyfort handle the
336
issue of different data ordering in Fortran and C multi-dimensional
337
arrays. Pyfort generated wrapper functions have optional arguments
338
TRANSPOSE and MIRROR that can be used to control explicitly how the array
339
arguments and their dimensions are passed to Fortran routine in order
340
to deal with the C/Fortran data ordering issue. F2PY generated wrapper
341
functions hide the whole issue from an end-user so that translation
342
between Fortran and C/Python loops and array element access codes is
343
one-to-one. How the F2PY generated wrappers deal with the issue is
344
determined by a person who creates a signature file via using
345
attributes like ``intent(c)``, ``intent(copy|overwrite)``,
346
``intent(inout|in,out|inplace)`` etc.
348
For example, let's consider a typical usage of both F2PY and Pyfort
349
when wrapping the following simple Fortran code:
351
.. include:: simple.f
354
The comment lines starting with ``cf2py`` are read by F2PY (so that we
355
don't need to generate/handwrite an intermediate signature file in
356
this simple case) while for a Fortran compiler they are just comment
359
And here is a Python version of the Fortran code:
361
.. include:: pytest.py
364
To generate a wrapper for subroutine ``foo`` using F2PY, execute::
366
$ f2py -m f2pytest simple.f -c
368
that will generate an extension module ``f2pytest`` into the current
371
To generate a wrapper using Pyfort, create the following file
373
.. include:: pyforttest.pyf
380
In Pyfort GUI add ``simple.f`` to the list of Fortran sources and
381
check that the signature file is in free format. And then copy
382
``pyforttest.so`` from the build directory to the current directory.
386
.. include:: simple_session.dat
389
Q: Can Pyfort .pyf files used with F2PY and vice versa?
390
-------------------------------------------------------
392
After some simple modifications, yes. You should take into account the
393
following differences in Pyfort and F2PY .pyf files.
395
+ F2PY signature file contains ``python module`` and ``interface``
396
blocks that are equivalent to Pyfort ``module`` block usage.
398
+ F2PY attribute ``intent(inplace)`` is equivalent to Pyfort
399
``intent(inout)``. F2PY ``intent(inout)`` is a strict (but safe)
400
version of ``intent(inplace)``, any mismatch in arguments with
401
expected type, size, or contiguouness will trigger an exception
402
while ``intent(inplace)`` (dangerously) modifies arguments
408
Q: How to establish which Fortran compiler F2PY will use?
409
---------------------------------------------------------
411
This question may be releavant when using F2PY in Makefiles. Here
412
follows a script demonstrating how to determine which Fortran compiler
413
and flags F2PY will use::
415
# Using post-0.2.2 numpy_distutils
416
from numpy_distutils.fcompiler import new_fcompiler
417
compiler = new_fcompiler() # or new_fcompiler(compiler='intel')
418
compiler.dump_properties()
420
# Using pre-0.2.2 numpy_distutils
422
from numpy_distutils.command.build_flib import find_fortran_compiler
424
fcompiler = os.environ.get('FC_VENDOR')
425
fcompiler_exec = os.environ.get('F77')
426
f90compiler_exec = os.environ.get('F90')
427
fc = find_fortran_compiler(fcompiler,
431
print 'FC=',fc.f77_compiler
432
print 'FFLAGS=',fc.f77_switches
433
print 'FOPT=',fc.f77_opt
434
if __name__ == "__main__":
440
Q: Where to find additional information on using F2PY?
441
------------------------------------------------------
443
There are several F2PY related tutorials, slides, papers, etc
446
+ `Fortran to Python Interface Generator with an Application to
447
Aerospace Engineering`__ by P. Peterson, J. R. R. A. Martins, and
448
J. J. Alonso in `In Proceedings of the 9th International Python
449
Conference`__, Long Beach, California, 2001.
451
__ http://www.python9.org/p9-cdrom/07/index.htm
452
__ http://www.python9.org/
454
+ Section `Adding Fortran90 code`__ in the UG of `The Bolometer Data
457
__ http://www.astro.rub.de/laboca/download/boa_master_doc/7_4Adding_Fortran90_code.html
458
__ http://www.openboa.de/
460
+ Powerpoint presentation `Python for Scientific Computing`__ by Eric
461
Jones in `The Ninth International Python Conference`__.
463
__ http://www.python9.org/p9-jones.ppt
464
__ http://www.python9.org/
466
+ Paper `Scripting a Large Fortran Code with Python`__ by Alvaro Caceres
467
Calleja in `International Workshop on Software Engineering for High
468
Performance Computing System Applications`__.
470
__ http://csdl.ics.hawaii.edu/se-hpcs/pdf/calleja.pdf
471
__ http://csdl.ics.hawaii.edu/se-hpcs/
473
+ Section `Automatic building of C/Fortran extension for Python`__ by
474
Simon Lacoste-Julien in `Summer 2002 Report about Hybrid Systems
477
__ http://moncs.cs.mcgill.ca/people/slacoste/research/report/SummerReport.html#tth_sEc3.4
478
__ http://moncs.cs.mcgill.ca/people/slacoste/research/report/SummerReport.html
480
+ `Scripting for Computational Science`__ by Hans Petter Langtangen
481
(see the `Mixed language programming`__ and `NumPy array programming`__
482
sections for examples on using F2PY).
484
__ http://www.ifi.uio.no/~inf3330/lecsplit/
485
__ http://www.ifi.uio.no/~inf3330/lecsplit/slide662.html
486
__ http://www.ifi.uio.no/~inf3330/lecsplit/slide718.html
488
+ Chapters 5 and 9 of `Python Scripting for Computational Science`__
489
by H. P. Langtangen for case studies on using F2PY.
491
__ http://www.springeronline.com/3-540-43508-5
493
+ Section `Fortran Wrapping`__ in `Continuity`__, a computational tool
494
for continuum problems in bioengineering and physiology.
496
__ http://www.continuity.ucsd.edu/cont6_html/docs_fram.html
497
__ http://www.continuity.ucsd.edu/
499
+ Presentation `PYFORT and F2PY: 2 ways to bind C and Fortran with Python`__
502
__ http://www.prism.enes.org/WPs/WP4a/Slides/pyfort/pyfort.html
504
+ Lecture slides of `Extending Python: speed it up`__.
506
__ http://www.astro.uni-bonn.de/~heith/lecture_pdf/friedrich5.pdf
508
+ Wiki topics on `Wrapping Tools`__ and `Wrapping Bemchmarks`__ for Climate
509
System Center at the University of Chicago.
511
__ https://geodoc.uchicago.edu/climatewiki/DiscussWrappingTools
512
__ https://geodoc.uchicago.edu/climatewiki/WrappingBenchmarks
514
+ `Performance Python with Weave`__ by Prabhu Ramachandran.
516
__ http://www.numpy.org/documentation/weave/weaveperformance.html
518
+ `How To Install py-f2py on Mac OSX`__
520
__ http://py-f2py.darwinports.com/
522
Please, let me know if there are any other sites that document F2PY
523
usage in one or another way.
525
Q: What projects use F2PY?
526
--------------------------
528
+ `SciPy: Scientific tools for Python`__
530
__ http://www.numpy.org/
532
+ `The Bolometer Data Analysis Project`__
534
__ http://www.openboa.de/
538
__ http://www.met.wau.nl/index.html?http://www.met.wau.nl/medewerkers/moenea/python/pywavelet.html
540
+ `PyARTS: an ARTS related Python package`__.
542
__ http://www.met.ed.ac.uk/~cory/PyARTS/
544
+ `Python interface to PSPLINE`__, a collection of Spline and
545
Hermite interpolation tools for 1D, 2D, and 3D datasets on
548
__ http://pypspline.sourceforge.net
550
+ `Markovian Analysis Package for Python`__.
552
__ http://pymc.sourceforge.net
554
+ `Modular toolkit for Data Processing (MDP)`__
556
__ http://mdp-toolkit.sourceforge.net/
559
Please, send me a note if you are using F2PY in your project.
561
Q: What people think about F2PY?
562
--------------------------------
566
Here are some comments people have posted to f2py mailing list and c.l.py:
568
+ Ryan Krauss: I really appreciate f2py. It seems weird to say, but I
569
am excited about relearning FORTRAN to compliment my python stuff.
571
+ Fabien Wahl: f2py is great, and is used extensively over here...
573
+ Fernando Perez: Anyway, many many thanks for this amazing tool.
575
I haven't used pyfort, but I can definitely vouch for the amazing quality of
576
f2py. And since f2py is actively used by numpy, it won't go unmaintained.
577
It's quite impressive, and very easy to use.
579
+ Kevin Mueller: First off, thanks to those responsible for F2PY;
580
its been an integral tool of my research for years now.
582
+ David Linke: Best regards and thanks for the great tool!
584
+ Perrin Meyer: F2Py is really useful!
586
+ Hans Petter Langtangen: First of all, thank you for developing
587
F2py. This is a very important contribution to the scientific
588
computing community. We are using F2py a lot and are very happy with
591
+ Berthold H�llmann: Thank's alot. It seems it is also working in my
592
'real' application :-)
594
+ John Hunter: At first I wrapped them with f2py (unbelievably easy!)...
596
+ Cameron Laird: Among many other features, Python boasts a mature
597
f2py, which makes it particularly rewarding to yoke Fortran- and
598
Python-coded modules into finished applications.
600
+ Ryan Gutenkunst: f2py is sweet magic.
604
+ `Is it worth using on a large scale python drivers for Fortran
605
subroutines, interfaced with f2py?`__
607
__ http://sepwww.stanford.edu/internal/computing/python.html
609
Additional comments on F2PY, good or bad, are welcome!
612
.. _README.txt: index.html
613
.. _HISTORY.txt: HISTORY.html
614
.. _HISTORY.txt in CVS: http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt?rev=HEAD&content-type=text/x-cvsweb-markup
615
.. _TESTING.txt: TESTING.html
added
removed
numpy/f2py/docs/FAQ.txt
