1 files changed, 130 insertions, 0 deletions
diff --git a/doc/swig/README b/doc/swig/README
new file mode 100644
index 000000000..d557b305f
--- /dev/null
+++ b/doc/swig/README
@@ -0,0 +1,130 @@
+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