Notes for the numpy/doc/swig directory
======================================

This set of files is for developing and testing file numpy.i, which is
intended to be a set of typemaps for helping SWIG interface between C
and C++ code that uses C arrays and the python module NumPy.  It is
ultimately hoped that numpy.i will be included as part of the SWIG
distribution.

In the spirit of "writing your tests first", I will begin by
describing the tests, as they are a good example of what we are trying
to do with numpy.i.  The files related to testing are::

    series.h
    series.cxx
    Series.i
    testSeries.py

The series.h header file contains prototypes for functions that
illustrate the wrapping issues we wish to address.  Right now, this
consists of functions with argument signatures of the form::

    (type* IN_ARRAY1, int DIM1)
    (type* IN_ARRAY2, int DIM1, int DIM2)
    (int DIM1, type* IN_ARRAY1)``
    (int DIM1, int DIM2, type* IN_ARRAY2)``
    (type* INPLACE_ARRAY1, int DIM1)
    (type* INPLACE_ARRAY2, int DIM1, int DIM2)
    (int DIM1, type* INPLACE_ARRAY1)
    (int DIM1, int DIM2, type* INPLACE_ARRAY2)

which take a pointer to an array of type "type", whose length is
specified by the integer(s) DIM1 (and DIM2).

The objective for the IN_ARRAY signatures is for SWIG to generate
python wrappers that take a container that constitutes a valid
argument to the numpy array constructor, and can be used to build an
array of type "type".  Currently, types "signed char", "unsigned
char", "short", "unsigned short", "int", "unsigned int", "long",
"unsigned long", "long long", "unsigned long long", "float", "double",
"PyObject" and "char" are supported and tested.

The objective for the INPLACE_ARRAY signatures is for SWIG to generate
python wrappers that accept a numpy array of any of the above-listed
types.

The source file series.cxx contains the actual implementations of the
functions described in series.h.  The python script testSeries.py
tests the resulting python wrappers using the unittest module.

The SWIG interface file Series.i is used to generate the wrapper code.
The SWIG_FILE_WITH_INIT macro allows numpy.i to be used with multiple
python modules.  If it is specified, then the %init block found in
Series.i is required.  The other things done in Series.i are the
inclusion of the series.h and numpy.i files, and the "%apply"
directives to force the functions to use the typemaps.

The setup.py script is a standard python distutils script.  It defines
a _Series extension module and a Series python module.  The Makefile
automates everything, setting up the dependencies, calling swig to
generate the wrappers, and calling setup.py to compile the wrapper
code and generate the shared object.  Targets "all" (default), "doc"
and "clean" are supported.  The "doc" target creates HTML
documentation (with make target "html"), and PDF documentation (with
make targets "tex" and "pdf").

To build and test the code, simply execute from the shell::

    $ make
    $ testSeries.py

================================================================================

ToDo
----

  * Support for complex data types should be added.  Currently swig
    dies with a syntax error when the %numpy_typemaps macro is used
    with complex types.

  * Better ARGOUT typemaps need to be implemented and tested.  I
    stalled on this because SWIG implements a new method for
    aggregating output arguments; it has changed from a tuple to a
    list and requires importing a different SWIG library file.  I
    didn't particularly want to spend time trying to support both
    approaches, and I ended up not finishing a typemap for either.
