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.

Documentation
-------------
Documentation for how to use numpy.i is in the doc directory.  The
primary source file here is numpy_swig.txt, a restructured text file
that documents how to use numpy.i.  The Makefile in doc allows for the
conversion of numpy_swig.txt to HTML (if you have docutils installed)
and to PDF (if you have docutils and latex/pdftex installed).  This
should not be necessary, however, as numpy_swig.html and
numpy_swig.pdf are stored in the repository.

The same is true for a file called doc/testing.txt, which describes
the testing system used here.

If you have the prerequisites installed and wish to build the HTML and
PDF documentation, this can be achieved by calling::

    $ make doc

from the shell.

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

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

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

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

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