Creating source for a basic extension module#

Consider the following subroutine, contained in a file namedadd.f

CSUBROUTINEZADD(A,B,C,N)CDOUBLE COMPLEXA(*)DOUBLE COMPLEXB(*)DOUBLE COMPLEXC(*)INTEGERNDO20J=1,NC(J)=A(J)+B(J)20CONTINUE      END

This routine simply adds the elements in two contiguous arrays and places theresult in a third. The memory for all three arrays must be provided by thecalling routine. A very basic interface to this routine can be automaticallygenerated by f2py:

python-mnumpy.f2py-maddadd.f

This command will produce an extension module namedaddmodule.c in thecurrent directory. This extension module can now be compiled and used fromPython just like any other extension module.

Creating a compiled extension module#

You can also get f2py to both compileadd.f along with the producedextension module leaving only a shared-library extension file that canbe imported from Python:

python-mnumpy.f2py-c-maddadd.f

This command produces a Python extension module compatible with your platform.This module may then be imported from Python. It will contain a method for eachsubroutine inadd. The docstring of each method contains information abouthow the module method may be called:

>>>importadd>>>print(add.zadd.__doc__)zadd(a,b,c,n)Wrapper for ``zadd``.Parameters----------a : input rank-1 array('D') with bounds (*)b : input rank-1 array('D') with bounds (*)c : input rank-1 array('D') with bounds (*)n : input int

Improving the basic interface#

The default interface is a very literal translation of the Fortran code intoPython. The Fortran array arguments are converted to NumPy arrays and theinteger argument should be mapped to aC integer. The interface will attemptto convert all arguments to their required types (and shapes) and issue an errorif unsuccessful. However, becausef2py knows nothing about the semantics ofthe arguments (such thatC is an output andn should really match thearray sizes), it is possible to abuse this function in ways that can causePython to crash. For example:

>>>add.zadd([1,2,3],[1,2],[3,4],1000)

will cause a program crash on most systems. Under the hood, the lists are beingconverted to arrays but then the underlyingadd function is told to cycleway beyond the borders of the allocated memory.

In order to improve the interface,f2py supports directives. This isaccomplished by constructing a signature file. It is usually best to start fromthe interfaces thatf2py produces in that file, which correspond to thedefault behavior. To getf2py to generate the interface file use the-hoption:

python-mnumpy.f2py-hadd.pyf-maddadd.f

This command creates theadd.pyf file in the current directory. The sectionof this file corresponding tozadd is:

subroutinezadd(a,b,c,n)! in :add:add.fdouble complexdimension(*)::adouble complexdimension(*)::bdouble complexdimension(*)::cinteger::nend subroutinezadd

By placing intent directives and checking code, the interface can be cleaned upquite a bit so the Python module method is both easier to use and more robust tomalformed inputs.

subroutinezadd(a,b,c,n)! in :add:add.fdouble complexdimension(n)::adouble complexdimension(n)::bdouble complexintent(out),dimension(n)::cintegerintent(hide),depend(a)::n=len(a)end subroutinezadd

The intent directive, intent(out) is used to tell f2py thatc isan output variable and should be created by the interface before beingpassed to the underlying code. The intent(hide) directive tells f2pyto not allow the user to specify the variable,n, but instead toget it from the size ofa. The depend(a ) directive isnecessary to tell f2py that the value of n depends on the input a (sothat it won’t try to create the variable n until the variable a iscreated).

After modifyingadd.pyf, the new Python module file can be generatedby compiling bothadd.f andadd.pyf:

python-mnumpy.f2py-cadd.pyfadd.f

The new interface’s docstring is:

>>>importadd>>>print(add.zadd.__doc__)c = zadd(a,b)Wrapper for ``zadd``.Parameters----------a : input rank-1 array('D') with bounds (n)b : input rank-1 array('D') with bounds (n)Returns-------c : rank-1 array('D') with bounds (n)

Now, the function can be called in a much more robust way:

>>>add.zadd([1,2,3],[4,5,6])array([5.+0.j, 7.+0.j, 9.+0.j])

Notice the automatic conversion to the correct format that occurred.

Inserting directives in Fortran source#

The robust interface of the previous section can also be generated automaticallyby placing the variable directives as special comments in the original Fortrancode.

Thus, if the source code is modified to contain:

CSUBROUTINEZADD(A,B,C,N)CCF2PYINTENT(OUT)::CCF2PYINTENT(HIDE)::NCF2PYDOUBLE COMPLEX::A(N)CF2PYDOUBLE COMPLEX::B(N)CF2PYDOUBLE COMPLEX::C(N)DOUBLE COMPLEXA(*)DOUBLE COMPLEXB(*)DOUBLE COMPLEXC(*)INTEGERNDO20J=1,NC(J)=A(J)+B(J)20CONTINUE      END

Then, one can compile the extension module using:

python-mnumpy.f2py-c-maddadd.f

The resulting signature for the function add.zadd is exactly the sameone that was created previously. If the original source code hadcontainedA(N) instead ofA(*) and so forth withB andC,then nearly the same interface can be obtained by placing theINTENT(OUT)::C comment line in the source code. The only differenceis thatN would be an optional input that would default to the lengthofA.