diff options
Diffstat (limited to 'doc/swig/README')
| -rw-r--r-- | doc/swig/README | 135 |
1 files changed, 0 insertions, 135 deletions
diff --git a/doc/swig/README b/doc/swig/README deleted file mode 100644 index df5dbfc47..000000000 --- a/doc/swig/README +++ /dev/null @@ -1,135 +0,0 @@ -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, 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 |