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