1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
===========
Using F2PY
===========
F2PY can be used either as a command line tool ``f2py`` or as a Python
module ``numpy.f2py``. While we try to install the command line tool as part
of the numpy setup, some platforms like Windows make it difficult to
reliably put the executable on the ``PATH``. We will refer to ``f2py``
in this document but you may have to run it as a module::
python -m numpy.f2py
If you run ``f2py`` with no arguments, and the line ``numpy Version`` at the
end matches the NumPy version printed from ``python -m numpy.f2py``, then you
can use the shorter version. If not, or if you cannot run ``f2py``, you should
replace all calls to ``f2py`` here with the longer version.
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 -m <modulename> <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.
.. note:: This option is deprecated. Use ``usercode`` statement to specify C code snippets directly in signature files.
``--[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 ``numpy_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
``numpy_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.
.. note:: The ``f2py -c`` option must be applied either to an existing ``.pyf`` file (plus the source/object/library files) or one must specify the ``-m <modulename>`` option (plus the sources/object/library files). Use one of the following options:
::
f2py -c -m fib1 fib1.f
or
::
f2py -m fib1 fib1.f -h fib1.pyf
f2py -c fib1.pyf fib1.f
For more information, see `Building C and C++ Extensions`__ Python documentation for details.
__ https://docs.python.org/3/extending/building.html
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.mkdtemp()``.
``--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 ``numpy.f2py``
============================
.. warning::
The current Python interface to the ``f2py`` module is not mature and
may change in the future.
.. automodule:: numpy.f2py
:members:
|
