[Plplot-devel] SWIG wrapping of Python output arrays

[Alan W. I. <ir...@be...>]

I have been discussing this topic off-list with Andrew, but I thought
my conclusions should be on-list in case this topic ever comes up
again.

What started this topic is I implemented a Python interface to ephcom
(part of the Time Ephemerides project) following what is done for the
array typemaps in PLplot.  The ephcom API has several different kinds
of output arrays, and when I looked at how the one output real array
in PLplot (i.e., the PLFLT **OutMatrixCk argument of plgriddata in
bindings/swig-support/plplotcapi.i) was treated, I quickly became
dissatisfied with the PLplot approach.  Currently that is a pretty
gross hack where the contents of pre-existing NumPy arrays of the
correct size and type are overwritten by our c_plgriddata code.  This
paradigm is contrary to what Python users normally expect which is
that argument lists remain unmodified and results are returned as
newly created Python objects contained in a return tuple.

Fast forward to today where I finished implementing the ephcom Python
interface using the returned tuple approach (where the output arrays
are newly created elements of that tuple).  However, I have run into a
SWIG idiosyncrasy that makes this approach impossible for the PLplot
case so I will be leaving our PLplot Python bindings for the
plgriddata PLFLT **OutMatrixCk argument in its current "hacked" state.

The SWIG idiosyncrasy is numinputs=0 arguments (i.e, the case of
output arrays where nothing appears in the Python arguments
corresponding to that output array) have their associated code
deployed in the wrapper routine before the code associated with normal
arguments.  So there is no Xlen, Ylen information available from
previous Python arguments on what size values are needed for the
Matrix dimensions.

In the ephcom case I could make an excellent initial guess since the
output arrays being treated have known maximum dimensions that are
#defined as macros in the ephcom header. Then afterwards, once the
actual desired dimensions were known, my implementation changed the
size of that NumPy array to accommodate the range of matrix index
values defined by the call to the ephcom library.

For plgriddata there is no known limit on the size of matrix.  So the
PLplot Python interface could guess at 10000 by 10000 and still have
some user exceed that. So I think in the PLplot case the current
"in-place" approach is better where the user defines a NumPy array to
use as an argument of the plgriddata call with appropriate dimensions
and our interface only checks that the dimensions of the various
vectors and arrays in the argument list are consistent with each other
before our c_plgridata code overwrites the contents of that array.

However, I will change my mind if that swig idiosyncrasy ever
disappears so swig just deploys code fragments in the wrapper code in
the exact order of the argument list.  In that case, Xlen and Ylen
will be available from prior NumPy 1-D arrays in the argument list,
and there will be no guessing required about the size of the NumPy 2D
array that should be created.

Alan
__________________________
Alan W. Irwin

Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).

Programming affiliations with the FreeEOS equation-of-state
implementation for stellar interiors (freeeos.sf.net); the Time
Ephemerides project (timeephem.sf.net); PLplot scientific plotting
software package (plplot.sf.net); the libLASi project
(unifont.org/lasi); the Loads of Linux Links project (loll.sf.net);
and the Linux Brochure Project (lbproject.sf.net).
__________________________

Linux-powered Science
__________________________