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
234
235
236
237
238
239
|
.. -*- rest -*-
=======================
G3 F2PY library package
=======================
:Author:
Pearu Peterson <pearu.peterson@gmail.com>
:Created: July 2007
.. contents:: Table of Contents
Overview
========
The G3 F2PY library package contains tools to parse Fortran codes and
construct Python C/API extension modules for wrapping Fortran
programs. These tools are also suitable for implementing Fortran
program translators or wrappers to any other programming language. In
fact, wrapping Fortran programs to Python would be just one example of
using these tools.
Wrapping Fortran with Python - UI
=================================
There are two user interfaces to wrap Fortran programs with Python:
- the command line program `f2py` that scans Fortran files
given as command line arguments and builds extension modules
that can be used to call Fortran programs from Python.
The `f2py` program has four different ways of building
extension modules as specified with the following command
line flags:
- `--g3-numpy` --- create extension modules with NumPy array
support using the new tools from `the 3rd generation of F2PY`__.
This is a work-in-progress feature.
- `--2d-numpy` --- create extension modules with NumPy array
support using `the stable version of F2PY`__. This is default.
- `--2d-numeric` --- create extension modules with Numeric
array support using the old version of f2py2e. The f2py2e
package must be downloaded and installed separately from
the `f2py2e homepage`__.
- `--2d-numarray` --- create extension modules with Numarray
array support using the old version of f2py2e.
Example::
$ cat hello.f90
subroutine hello
print*, "Hello!"
end subroutine hello
$ f2py --g3-numpy -m foo -c hello.f90 --fcompiler=gnu95
$ python
>>> import foo
>>> foo.hello()
Hello!
>>>
See the output of `f2py` for more information.
__ http://projects.scipy.org/scipy/numpy/wiki/G3F2PY/
__ http://www.scipy.org/F2py/
__ http://cens.ioc.ee/projects/f2py2e/
- the function `compile()` that scans its string input containing
Fortran code and returns a list of imported extension modules
that can be used to call Fortran programs from Python.
Example::
$ python
>>> from numpy.f2py.lib.api import compile
>>> code = 'subroutine hello\n print*, "Hello!"\nend'
>>> print code
subroutine hello
print*, "Hello!"
end
>>> foo, = compile(code, extra_args = ['--fcompiler=gnu95'])
>>> foo.hello()
Hello!
>>>
Wrapping Fortran with Python - how it works?
============================================
The two users interfaces discussed above are implemented by functions
`main(sys_argv=None)` and `compile(source, jobname='untitled',
extra_args=[], source_ext=None, modulenames=None)` in file
`numpy/f2py/lib/main.py`. Both these functions call
`build_extension(sys_argv, sources_only=False)` function that reads
`sys_argv` list for files and options, constructs wrapper functions,
creates a `numpy.distutils` style `setup.py` file, and finally runs
it.
`build_extension` options
-------------------------
The following options are defined that can be used as command line
arguments to `f2py` or in `extra_args` list argument of the `compiler`
function:
- `-m [<name>]` --- specify the name of a wrapper extension
module. Default is `untitled` or `unspecified` (if `<name>` part
is not specified).
- `--target-dir=<path>` --- specify the directory path where
extension modules are saved. Default is the current working
directory.
- `--build-dir=<path>` --- specify the directory path where
temporary files are created during the build process. Default is
`_g2f2py` or temporary directory (when `<path>` part is not
specified)).
- `-I<path>` --- specifies include directory path that is used for
finding Fortran 90 modules and when compiling sources.
- `-D<name>[=<value>]`, `-U<name>` --- defines or undefines CPP
macro used in compiling sources. See below for F2PY specific
macros.
- `-L<path>` --- specifies library directory path that is used in
linking extension modules.
- `-l<name>` --- specifies library that is used in linking extension
modules.
- `<filename>.(o|a|so|dll|dylib|sl)` --- specifies extra object
files used in linking extension modules.
- `<filename>`.pyf --- specifies signature file used for scanning
Fortran program signatures.
- `<filename>.(f|f90|F90|F)` --- specifies Fortran source files used
for scanning Fortran program signatures (in case no signature
files are specified). These sources will be compiled and linked
with extension modules.
- `<filename>.(c|cpp|C|CPP|c++)` --- specifies C/C++ source files
that will be compiled and linked with extension modules. Note that
if no signature file is specified then also C/C++ files are
scanned for Fortran program signatures. The Fortran program
signatures are assumed to be inside the C comment `/* f2py ... */`
block.
- `--fcompiler=<compiler name>` --- specifies Fortran compiler to be
used in compiling/linking the sources. See also `--help-fcompiler`
option.
- `--help-fcompiler` --- list Fortran compilers that are found in
the system, that are available or unavailable for the current
system. Then return without processing any other options.
- `--compiler=<compiler name>` --- specifies C/C++ compiler to be
used in compiling/linking the sources. See also `--help-compiler`
option.
- `--help-compiler` --- list C/C++ compilers that are available
for the current system. Then return without processing any other
options.
Additional `f2py` command line options
--------------------------------------
Command line tool `f2py` uses the following additional command line
options:
- `-c` --- specifies that F2PY should build extension
modules. Without this option F2PY just scans source files for
signatures and constructs extension module sources --- useful when
one needs to build extension modules manually (in Makefile, for
instance). See also `-h` option below.
- `-h <filename>` --- specifies the signature file name
where the results of scanning sources will be saved. With this
option F2PY just scans the sources but does not construct extension
modules sources --- useful when one needs to edit the signatures
of Fortran programs. If `<filename>` is `stdout` or `stderr` is
specified then the scanned signatures will be dumped to `stdout`
or `stderr` streams, respectively.
- `--help-link [<resouce name> ]...` --- list system resources as
defined in `numpy/distutils/system_info.py` and return.
- `--parse` --- specifies that F2PY should just parce the
source files and dump the results to `stdout` stream.
Useful for debugging F2PY parser.
F2PY specific CPP macros
------------------------
F2PY may use the following CPP macros:
- `-DF2PY_DEBUG_PYOBJ_TOFROM` --- show debug messages from
`pyobj_(to|from)_<ctype>` functions.
- `-DPREPEND_FORTRAN`, `-DNO_APPEND_FORTRAN`, `-DUPPERCASE_FORTRAN`,
`-DUNDERSCORE_G77` --- specify how Fortran compiler mangles Fortran
symbol names that need to be accessed from C extension modules.
Usually one never needs to specify these macros as supported
Fortran compilers should always mangle the names to be lower-cased
and with exactly one underscore after the name.
Options for `compile`
---------------------
The `compile` function has the following options:
- `source` --- a string containing Fortran code. To specify the
Fortran format of the `source` use the following header lines
in the `source` string:
- `C -*- f77 -*-` --- the string contains Fortran 77 code
- `! -*- f90 -*-` --- the string contains Fortran 90 code in
free format.
- `! -*- fix -*-` --- the string contains Fortran 90 code in
fixed format.
- `! -*- pyf -*-` --- the string contains Fortran signatures.
- `jobname='untitled'` --- a string specifing the name of an
extension module
- `extra_args=[]` --- a list of `build_extension(..)` arguments,
see above.
- `source_ext=None` --- a string specifying the extension (`.f` or
`.f90`) of the file where `source` will be saved for further
processing. Default extension will be determined from the `source`
string.
- `modulenames=None` --- a list of module names that the build
process should create. `compile` function will try to import
these modules and return the corresponding module objects
as a list.
|
