Notes for the numpy/tools/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.

Documentation
-------------
Documentation for how to use numpy.i, as well as for the testing
system used here, can be found in the NumPy reference guide.

Testing
-------
The tests are a good example of what we are trying to do with numpy.i.
The files related to testing are are in the test subdirectory::

    Vector.h
    Vector.cxx
    Vector.i
    testVector.py

    Matrix.h
    Matrix.cxx
    Matrix.i
    testMatrix.py

    Tensor.h
    Tensor.cxx
    Tensor.i
    testTensor.py

    SuperTensor.h
    SuperTensor.cxx
    SuperTensor.i
    testSuperTensor.py

    Flat.h
    Flat.cxx
    Flat.i
    testFlat.py

The header files contain prototypes for functions that illustrate the
wrapping issues we wish to address.  Right now, this consists of
functions with argument signatures of the following forms.  Vector.h::

    (type IN_ARRAY1[ANY])
    (type* IN_ARRAY1, int DIM1)
    (int DIM1, type* IN_ARRAY1)

    (type INPLACE_ARRAY1[ANY])
    (type* INPLACE_ARRAY1, int DIM1)
    (int DIM1, type* INPLACE_ARRAY1)

    (type ARGOUT_ARRAY1[ANY])
    (type* ARGOUT_ARRAY1, int DIM1)
    (int DIM1, type* ARGOUT_ARRAY1)

Matrix.h::

    (type IN_ARRAY2[ANY][ANY])
    (type* IN_ARRAY2, int DIM1, int DIM2)
    (int DIM1, int DIM2, type* IN_ARRAY2)

    (type INPLACE_ARRAY2[ANY][ANY])
    (type* INPLACE_ARRAY2, int DIM1, int DIM2)
    (int DIM1, int DIM2, type* INPLACE_ARRAY2)

    (type ARGOUT_ARRAY2[ANY][ANY])

Tensor.h::

    (type IN_ARRAY3[ANY][ANY][ANY])
    (type* IN_ARRAY3, int DIM1, int DIM2, int DIM3)
    (int DIM1, int DIM2, int DIM3, type* IN_ARRAY3)

    (type INPLACE_ARRAY3[ANY][ANY][ANY])
    (type* INPLACE_ARRAY3, int DIM1, int DIM2, int DIM3)
    (int DIM1, int DIM2, int DIM3, type* INPLACE_ARRAY3)

    (type ARGOUT_ARRAY3[ANY][ANY][ANY])

SuperTensor.h::

    (type IN_ARRAY4[ANY][ANY][ANY][ANY])
    (type* IN_ARRAY4, int DIM1, int DIM2, int DIM3, int DIM4)
    (int DIM1, int DIM2, int DIM3, int DIM4, type* IN_ARRAY4)

    (type INPLACE_ARRAY4[ANY][ANY][ANY][ANY])
    (type* INPLACE_ARRAY4, int DIM1, int DIM2, int DIM3, int DIM4)
    (int DIM1, int DIM2, int DIM3, int DIM4, type* INPLACE_ARRAY4)

    (type ARGOUT_ARRAY4[ANY][ANY][ANY][ANY])

Flat.h::
    (type* INPLACE_ARRAY_FLAT, int DIM_FLAT)

These function signatures take a pointer to an array of type "type",
whose length is specified by the integer(s) DIM1 (and DIM2, and DIM3,
and DIM4, or DIM_FLAT).

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", and
"double" 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 files Vector.cxx, Matrix.cxx, Tensor.cxx, SuperTensor.cxx
and Flat.cxx contain the actual implementations of the functions
described in Vector.h, Matrix.h Tensor.h, SuperTensor.h and Flat.h.
The python scripts testVector.py, testMatrix.py testTensor.py,
testSuperTensor.py and testFlat.py test the resulting python wrappers
using the unittest module.

The SWIG interface files Vector.i, Matrix.i, Tensor.i, SuperTensor.i
and Flat.i are 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
Vector.i, Matrix.i Tensor.i, SuperTensor.i and Flat.i are required.
The other things done in Vector.i, Matrix.i, Tensor.i, SuperTensor.i
and Flat.i are the inclusion of the appropriate header file and
numpy.i file, and the "%apply" directives to force the functions to
use the typemaps.

The setup.py script is a standard python distutils script.  It defines
_Vector, _Matrix, _Tensor, _SuperTensor, _Flat extension modules and Vector,
Matrix, Tensor, SuperTensor and Flat python modules.  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 objects.  Targets "all" (default), "test",
"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 run the test code, simply execute from the shell::

    $ make test