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

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])

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).

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

The SWIG interface files Vector.i, Matrix.i Tensor.i and SuperTensor.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
and SuperTensor.i are required.  The other things done in Vector.i,
Matrix.i Tensor.i and SuperTensor.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 and _SuperTensor extension modules and Vector
, Matrix, Tensor and SuperTensor 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