[PYTHON MATRIX-SIG] IMSL bindings
Jim Fulton
jim.fulton@digicool.com
Fri, 18 Oct 1996 16:11:00 -0400
David Ascher wrote:
>
> It would make some people here very happy if there were Python
> bindings to the IMSL Fortran libraries (and C, but they're less
> complete).
>
> Have people come up with tools which make binding to Fortran
> libraries relatively automatic? IMSL is fairly big.
You want fidl:
NAME
fidl - Fortran interface description language for building
Python modules
SYNOPSIS
fidl [ -c ] [ -l library ] foomodule.fidl ...
DESCRIPTION
The Fortran interface description language (fidl) provides
a mechanism for calling Fortran routines from the Python
object-oriented interpreter. In addition, the interfaces
to routines may be significantly simplified, because the
interface created by a fidl compiler is able to generate
many arguments automatically.
When a Fortran program requires an input array argument,
any Python sequence object may be passed. For example, if
a two-dimensional array is expected, any Python object
that behaves as a sequence of sequences may be passed,
such as a list of lists, a tuple of tuples, a database
table, and so on.
Routines are described by writing fidl specification for
each routine. A fidl compiler converts a fidl specifica-
tion into a C python module that interfaces between the
python interpreter and the Fortran routines.
The fidl spec is provided in a file. The name of the file
is given as the last argument to the fidl command and must
consist of a module name concatinated with the suffix
"module.py". For example, to create a Python module named
"spam", create a fidl spec named spammodule.fidl. The
generated C file will have the same name as the fidl spec
except that the ".fidl" suffix is changed to ".c". If
requested, the generated C file will be compiled and
linked with any specified Fortran libraries to produce a
shared object library that may be imported into python.
The shared object library will have the same name as the
fidl spec except that the ".fidl" suffix is changed to
".so".
A fidl specification consists of a routine return type, a
routine name, and a list of argument specifications sepa-
rated by commas. For example:
c Fit an Akima spline function
subroutine dcsakm(in integer ndata,
in double xdata(ndata),
in double fdata(ndata),
out double csbreak(ndata),
out double cscoef(ndata,4));
specifies a routine of type subroutine, named dcsakm, and
taking 5 arguments. Valid return types are: subroutine,
real, double, integer (or int), integer*1, integer*2,
integer*4, and character. A return type of subroutine
means that the routine does not return a value from For-
tran. The return type may be ommitted, in which case a
subroutine is assumed.
Note that Fortran-style comments can be included in fidl
specs. They will be retained as documentation strings
(which can be accessed from Python) of the generated
python-callable functions. Comments may also be provided
for empty fidl specifications, in which case the comments
are used to build the module documentation string for the
generated module.
Each argument definition consists of an argument direc-
tion, type, name, and optional dimension. Valid argument
types are: real, double, integer (or int), integer*1,
integer*2, integer*4, and character. The argument type may
be ommitted, in which case the argument type will be
inferred from the argument name using usual Fortran con-
ventions. Valid argument directions are in, expr, out,
modify, work, ok, and error. If the argument direction is
ommitted, then a direction of "in" will be assumed. Each
of these directions are described below.
Arguments that have direction of "in" are input arguments.
Only input and modify arguments need to be passed from
python scripts, and only if they can not be infered from
other information. In particular, input dimensions are
inferred from the dimensions of the arrays passed, because
the generated C code can determine the sizes of sequence
objects passed. For example, in the specification above,
the input argument, ndata, is not passed because it can be
inferred from the dimension of xdata. The dimensions of
xdata and fdata are checked to make sure they are the
same.
Arguments that are direction "expr" are used for scalar
arguments that can be computed from other arguments or
from argument dimensions. For these arguments, a C
expression is provided in parentheses where a dimension
would otherwise be expected.
Arguments that have direction "out" are output arguments.
Even though they are passed to the fortran routine, they
are not passed from Python, but are generated by the C
interface generated by fidl. Python functions can return
multiple arguments (by returning tuples). Output argu-
ments are returned along with the Fortran return value, if
any. For example, the function dcsakm specified above
will return two values to python, the arrays csbreak and
cscoef.
Arguments that have direction "modify" are treated as both
input and output arguments. The argument is passed in
from python and is returned to python as one of the func-
tion return values. Note that the object passed from
Python will not be modified unless it is a Matrix object
with the same data type that is required by the Fortran
routine.
Arguments that have direction "work" are used for Fortran
routines that need extra memory to perform computations.
They are neither passed in from Python or returned to
python, but are allocated prior to calling the Fortran
routine and freed after calling the Fortran routine.
Arguments that have direction "ok" or "error" are used for
output arguments that indicate the success of the Fortran
routine call. They are not returned to python directly.
If the value of an "ok" argument is zero after the Fortran
routine is called, then a Python exception is raised to
indicate the error. If the value of an "error" argument
is non-zero after the Fortran routine is called, then a
Python exception is raised to indicate the error. The
type of the exception will be the string "module.error",
where "module" is the name of the Fortran module.
OPTIONS
-c If the -c option is given, then the generated C
code will be compiled. This is useful, because
special compiler options needed by Python modules
(for example, to specify the location of Python C
include files) are provided. The command used to
compile the module is echod to standard output.
-l library
Specify a library to be linked with the module.
This option may be given multiple times, once for
each library specified. The libraries specified
should be Fortran libraries.
If any libraries are specified, then the compiled
C code will be linked with the libraries to create
a shared object library. The command used to link
the files and create the shared object library is
echod to standard output.
EXAMPLES
Given the following fidl specification (in the file
interpmodule.fidl):
c Spline interpolation using Akima algorithm
c
c Demonstration fidl module
;
c Fit an Akima spline function
subroutine dcsakm(in integer ndata,
in double xdata(ndata),
in double fdata(ndata),
out double csbreak(ndata),
out double cscoef(ndata,4));
c Use a fitted spline function to interpolate a point
double dcsval(in double x,
expr int nintv(ndata-1),
in double csbreak(ndata),
in double cscoef(ndata,4));
The following Python code shows how the module might be used:
import interp
b,c = dcsakm([0, .1, .2, .5], [100, 200, 10, 50])
for i in range(50):
print dcsval(i/100.0,b,c)
SEE ALSO
python(1), f77(1)
BUGS
This tool is still in a very preliminary form.
Note that the above example is for an IMSL routine.
FIDL has been in a beta testing state for some time because
I haven't been able to get any beta testers to actually
test it, or at least to let me know how it works.
If you are interested in *really* being a beta tester,
let me know and I'll point you at the current version.
Note that fidl uses a precursor to NumPy arrays. It should
work with NumPy with a little extra copying. I'm planning
to integrate NumPy with FIDL, but it hasn't been a high
priority since I changed jobs and no longer need fidl myself.
Jim
--
Jim Fulton Digital Creations
jim@digicool.com 540.371.6909
## Python is my favorite language ##
## http://www.python.org/ ##
=================
MATRIX-SIG - SIG on Matrix Math for Python
send messages to: matrix-sig@python.org
administrivia to: matrix-sig-request@python.org
=================