146 lines
5.0 KiB
Plaintext
146 lines
5.0 KiB
Plaintext
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
|