User guide

NumPy User Guide, Release 1.9.0
5.2.2 Hand-generated wrappers
Extension modules were discussed in Chapter 1 . The most basic way to interface with compiled code is to write an
extension module and construct a module method that calls the compiled code. For improved readability, your method
should take advantage of the PyArg_ParseTuple call to convert between Python objects and C data-types. For standard
C data-types there is probably already a built-in converter. For others you may need to write your own converter and
use the “O&” format string which allows you to specify a function that will be used to perform the conversion from
the Python object to whatever C-structures are needed.
Once the conversions to the appropriate C-structures and C data-types have been performed, the next step in the
wrapper is to call the underlying function. This is straightforward if the underlying function is in C or C++. However,
in order to call Fortran code you must be familiar with how Fortran subroutines are called from C/C++ using your
compiler and platform. This can vary somewhat platforms and compilers (which is another reason f2py makes life
much simpler for interfacing Fortran code) but generally involves underscore mangling of the name and the fact that
all variables are passed by reference (i.e. all arguments are pointers).
The advantage of the hand-generated wrapper is that you have complete control over how the C-library gets used and
called which can lead to a lean and tight interface with minimal over-head. The disadvantage is that you have to
write, debug, and maintain C-code, although most of it can be adapted using the time-honored technique of “cutting-
pasting-and-modifying” from other extension modules. Because, the procedure of calling out to additional C-code is
fairly regimented, code-generation procedures have been developed to make this process easier. One of these code-
generation techniques is distributed with NumPy and allows easy integration with Fortran and (simple) C code. This
package, f2py, will be covered briefly in the next session.
5.2.3 f2py
F2py allows you to automatically construct an extension module that interfaces to routines in Fortran 77/90/95 code.
It has the ability to parse Fortran 77/90/95 code and automatically generate Python signatures for the subroutines it
encounters, or you can guide how the subroutine interfaces with Python by constructing an interface-definition-file (or
modifying the f2py-produced one).
Creating source for a basic extension module
Probably the easiest way to introduce f2py is to offer a simple example. Here is one of the subroutines contained in a
file named add.f:
C
SUBROUTINE ZADD(A,B,C,N)
C
DOUBLE COMPLEX A(
*
)
DOUBLE COMPLEX B(
*
)
DOUBLE COMPLEX C(
*
)
INTEGER N
DO 20 J = 1, N
C(J) = A(J)+B(J)
20 CONTINUE
END
This routine simply adds the elements in two contiguous arrays and places the result in a third. The memory for
all three arrays must be provided by the calling routine. A very basic interface to this routine can be automatically
generated by f2py:
f2py -m add add.f
62 Chapter 5. Using Numpy C-API