diff options
Diffstat (limited to 'doc/swig/doc')
| -rw-r--r-- | doc/swig/doc/Makefile | 51 | ||||
| -rw-r--r-- | doc/swig/doc/numpy_swig.html | 1244 | ||||
| -rw-r--r-- | doc/swig/doc/numpy_swig.pdf | bin | 0 -> 168839 bytes | |||
| -rw-r--r-- | doc/swig/doc/numpy_swig.txt | 950 | ||||
| -rw-r--r-- | doc/swig/doc/testing.html | 482 | ||||
| -rw-r--r-- | doc/swig/doc/testing.pdf | bin | 0 -> 72439 bytes | |||
| -rw-r--r-- | doc/swig/doc/testing.txt | 173 |
7 files changed, 2900 insertions, 0 deletions
diff --git a/doc/swig/doc/Makefile b/doc/swig/doc/Makefile new file mode 100644 index 000000000..9223f0481 --- /dev/null +++ b/doc/swig/doc/Makefile @@ -0,0 +1,51 @@ +# ReStructured Text +RST2HTML = rst2html.py +RST2LATEX = rst2latex.py +RFLAGS = --generator --time +HTML_FLAGS = --no-xml-declaration +LATEX_FLAGS = +LATEX = pdflatex + +# Web pages that need to be made +WEB_PAGES = numpy_swig.html testing.html + +# LaTeX files that need to be made +LATEX_FILES = numpy_swig.tex testing.tex + +# PDF files that need to be made +PDF_FILES = numpy_swig.pdf testing.pdf + +# Default target: documentation +.PHONY : doc +doc: html pdf + +# HTML target +.PHONY : html +html: $(WEB_PAGES) + +# Rule: %.txt -> %.html +%.html: %.txt + $(RST2HTML) $(RFLAGS) $(HTML_FLAGS) $< $@ + +# LaTeX target +.PHONY : tex +tex: $(LATEX_FILES) + +# Rule: %.txt -> %.tex +%.tex: %.txt + $(RST2LATEX) $(RFLAGS) $(LATEX_FLAGS) $< $@ + +# PDF target +.PHONY : pdf +pdf: $(PDF_FILES) + +# Rule: %.tex -> %.pdf +%.pdf: %.tex + $(LATEX) $< + $(LATEX) $< + +# Clean target +.PHONY : clean +clean: + $(RM) $(LATEX_FILES) + $(RM) *.pyc *.aux *.dvi *.log *.out *~ diff --git a/doc/swig/doc/numpy_swig.html b/doc/swig/doc/numpy_swig.html new file mode 100644 index 000000000..ed127f330 --- /dev/null +++ b/doc/swig/doc/numpy_swig.html @@ -0,0 +1,1244 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> +<title>numpy.i: a SWIG Interface File for NumPy</title> +<meta name="author" content="Bill Spotz" /> +<meta name="date" content="1 December, 2007" /> +<style type="text/css"> + +/* +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $ +:Revision: $Revision: 4224 $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin-left: 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left { + clear: left } + +img.align-right { + clear: right } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font-family: serif ; + font-size: 100% } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em ; + background-color: #eeeeee } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +tt.docutils { + background-color: #eeeeee } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="numpy-i-a-swig-interface-file-for-numpy"> +<h1 class="title">numpy.i: a SWIG Interface File for NumPy</h1> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Author:</th> +<td>Bill Spotz</td></tr> +<tr class="field"><th class="docinfo-name">Institution:</th><td class="field-body">Sandia National Laboratories</td> +</tr> +<tr><th class="docinfo-name">Date:</th> +<td>1 December, 2007</td></tr> +</tbody> +</table> +<div class="contents topic"> +<p class="topic-title first"><a id="contents" name="contents">Contents</a></p> +<ul class="simple"> +<li><a class="reference" href="#introduction" id="id1" name="id1">Introduction</a></li> +<li><a class="reference" href="#using-numpy-i" id="id2" name="id2">Using numpy.i</a></li> +<li><a class="reference" href="#available-typemaps" id="id3" name="id3">Available Typemaps</a><ul> +<li><a class="reference" href="#input-arrays" id="id4" name="id4">Input Arrays</a></li> +<li><a class="reference" href="#in-place-arrays" id="id5" name="id5">In-Place Arrays</a></li> +<li><a class="reference" href="#argout-arrays" id="id6" name="id6">Argout Arrays</a></li> +<li><a class="reference" href="#argoutview-arrays" id="id7" name="id7">Argoutview Arrays</a></li> +<li><a class="reference" href="#output-arrays" id="id8" name="id8">Output Arrays</a></li> +<li><a class="reference" href="#other-common-types-bool" id="id9" name="id9">Other Common Types: bool</a></li> +<li><a class="reference" href="#other-common-types-complex" id="id10" name="id10">Other Common Types: complex</a></li> +</ul> +</li> +<li><a class="reference" href="#numpy-array-scalars-and-swig" id="id11" name="id11">NumPy Array Scalars and SWIG</a><ul> +<li><a class="reference" href="#why-is-there-a-second-file" id="id12" name="id12">Why is There a Second File?</a></li> +</ul> +</li> +<li><a class="reference" href="#helper-functions" id="id13" name="id13">Helper Functions</a><ul> +<li><a class="reference" href="#macros" id="id14" name="id14">Macros</a></li> +<li><a class="reference" href="#routines" id="id15" name="id15">Routines</a></li> +</ul> +</li> +<li><a class="reference" href="#beyond-the-provided-typemaps" id="id16" name="id16">Beyond the Provided Typemaps</a><ul> +<li><a class="reference" href="#a-common-example" id="id17" name="id17">A Common Example</a></li> +<li><a class="reference" href="#other-situations" id="id18" name="id18">Other Situations</a></li> +<li><a class="reference" href="#a-final-note" id="id19" name="id19">A Final Note</a></li> +</ul> +</li> +<li><a class="reference" href="#summary" id="id20" name="id20">Summary</a></li> +<li><a class="reference" href="#acknowledgements" id="id21" name="id21">Acknowledgements</a></li> +</ul> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id1" id="introduction" name="introduction">Introduction</a></h1> +<p>The Simple Wrapper and Interface Generator (or <a class="reference" href="http://www.swig.org">SWIG</a>) is a powerful tool for generating wrapper +code for interfacing to a wide variety of scripting languages. +<a class="reference" href="http://www.swig.org">SWIG</a> can parse header files, and using only the code prototypes, +create an interface to the target language. But <a class="reference" href="http://www.swig.org">SWIG</a> is not +omnipotent. For example, it cannot know from the prototype:</p> +<pre class="literal-block"> +double rms(double* seq, int n); +</pre> +<p>what exactly <tt class="docutils literal"><span class="pre">seq</span></tt> is. Is it a single value to be altered in-place? +Is it an array, and if so what is its length? Is it input-only? +Output-only? Input-output? <a class="reference" href="http://www.swig.org">SWIG</a> cannot determine these details, +and does not attempt to do so.</p> +<p>If we designed <tt class="docutils literal"><span class="pre">rms</span></tt>, we probably made it a routine that takes an +input-only array of length <tt class="docutils literal"><span class="pre">n</span></tt> of <tt class="docutils literal"><span class="pre">double</span></tt> values called <tt class="docutils literal"><span class="pre">seq</span></tt> +and returns the root mean square. The default behavior of <a class="reference" href="http://www.swig.org">SWIG</a>, +however, will be to create a wrapper function that compiles, but is +nearly impossible to use from the scripting language in the way the C +routine was intended.</p> +<p>For <a class="reference" href="http://www.python.org">python</a>, the preferred way of handling +contiguous (or technically, <em>strided</em>) blocks of homogeneous data is +with the module <a class="reference" href="http://numpy.scipy.org">NumPy</a>, which provides full +object-oriented access to multidimensial arrays of data. Therefore, +the most logical <a class="reference" href="http://www.python.org">python</a> interface for the <tt class="docutils literal"><span class="pre">rms</span></tt> function would be +(including doc string):</p> +<pre class="literal-block"> +def rms(seq): + """ + rms: return the root mean square of a sequence + rms(numpy.ndarray) -> double + rms(list) -> double + rms(tuple) -> double + """ +</pre> +<p>where <tt class="docutils literal"><span class="pre">seq</span></tt> would be a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array of <tt class="docutils literal"><span class="pre">double</span></tt> values, and its +length <tt class="docutils literal"><span class="pre">n</span></tt> would be extracted from <tt class="docutils literal"><span class="pre">seq</span></tt> internally before being +passed to the C routine. Even better, since <a class="reference" href="http://numpy.scipy.org">NumPy</a> supports +construction of arrays from arbitrary <a class="reference" href="http://www.python.org">python</a> sequences, <tt class="docutils literal"><span class="pre">seq</span></tt> +itself could be a nearly arbitrary sequence (so long as each element +can be converted to a <tt class="docutils literal"><span class="pre">double</span></tt>) and the wrapper code would +internally convert it to a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array before extracting its data +and length.</p> +<p><a class="reference" href="http://www.swig.org">SWIG</a> allows these types of conversions to be defined via a +mechanism called typemaps. This document provides information on how +to use <tt class="docutils literal"><span class="pre">numpy.i</span></tt>, a <a class="reference" href="http://www.swig.org">SWIG</a> interface file that defines a series of +typemaps intended to make the type of array-related conversions +described above relatively simple to implement. For example, suppose +that the <tt class="docutils literal"><span class="pre">rms</span></tt> function prototype defined above was in a header file +named <tt class="docutils literal"><span class="pre">rms.h</span></tt>. To obtain the <a class="reference" href="http://www.python.org">python</a> interface discussed above, +your <a class="reference" href="http://www.swig.org">SWIG</a> interface file would need the following:</p> +<pre class="literal-block"> +%{ +#define SWIG_FILE_WITH_INIT +#include "rms.h" +%} + +%include "numpy.i" + +%init %{ +import_array(); +%} + +%apply (double* IN_ARRAY1, int DIM1) {(double* seq, int n)}; +%include "rms.h" +</pre> +<p>Typemaps are keyed off a list of one or more function arguments, +either by type or by type and name. We will refer to such lists as +<em>signatures</em>. One of the many typemaps defined by <tt class="docutils literal"><span class="pre">numpy.i</span></tt> is used +above and has the signature <tt class="docutils literal"><span class="pre">(double*</span> <span class="pre">IN_ARRAY1,</span> <span class="pre">int</span> <span class="pre">DIM1)</span></tt>. The +argument names are intended to suggest that the <tt class="docutils literal"><span class="pre">double*</span></tt> argument +is an input array of one dimension and that the <tt class="docutils literal"><span class="pre">int</span></tt> represents +that dimension. This is precisely the pattern in the <tt class="docutils literal"><span class="pre">rms</span></tt> +prototype.</p> +<p>Most likely, no actual prototypes to be wrapped will have the argument +names <tt class="docutils literal"><span class="pre">IN_ARRAY1</span></tt> and <tt class="docutils literal"><span class="pre">DIM1</span></tt>. We use the <tt class="docutils literal"><span class="pre">%apply</span></tt> directive to +apply the typemap for one-dimensional input arrays of type <tt class="docutils literal"><span class="pre">double</span></tt> +to the actual prototype used by <tt class="docutils literal"><span class="pre">rms</span></tt>. Using <tt class="docutils literal"><span class="pre">numpy.i</span></tt> +effectively, therefore, requires knowing what typemaps are available +and what they do.</p> +<p>A <a class="reference" href="http://www.swig.org">SWIG</a> interface file that includes the <a class="reference" href="http://www.swig.org">SWIG</a> directives given +above will produce wrapper code that looks something like:</p> +<pre class="literal-block"> + 1 PyObject *_wrap_rms(PyObject *args) { + 2 PyObject *resultobj = 0; + 3 double *arg1 = (double *) 0 ; + 4 int arg2 ; + 5 double result; + 6 PyArrayObject *array1 = NULL ; + 7 int is_new_object1 = 0 ; + 8 PyObject * obj0 = 0 ; + 9 +10 if (!PyArg_ParseTuple(args,(char *)"O:rms",&obj0)) SWIG_fail; +11 { +12 array1 = obj_to_array_contiguous_allow_conversion( +13 obj0, NPY_DOUBLE, &is_new_object1); +14 npy_intp size[1] = { +15 -1 +16 }; +17 if (!array1 || !require_dimensions(array1, 1) || +18 !require_size(array1, size, 1)) SWIG_fail; +19 arg1 = (double*) array1->data; +20 arg2 = (int) array1->dimensions[0]; +21 } +22 result = (double)rms(arg1,arg2); +23 resultobj = SWIG_From_double((double)(result)); +24 { +25 if (is_new_object1 && array1) Py_DECREF(array1); +26 } +27 return resultobj; +28 fail: +29 { +30 if (is_new_object1 && array1) Py_DECREF(array1); +31 } +32 return NULL; +33 } +</pre> +<p>The typemaps from <tt class="docutils literal"><span class="pre">numpy.i</span></tt> are responsible for the following lines +of code: 12--20, 25 and 30. Line 10 parses the input to the <tt class="docutils literal"><span class="pre">rms</span></tt> +function. From the format string <tt class="docutils literal"><span class="pre">"O:rms"</span></tt>, we can see that the +argument list is expected to be a single <a class="reference" href="http://www.python.org">python</a> object (specified +by the <tt class="docutils literal"><span class="pre">O</span></tt> before the colon) and whose pointer is stored in +<tt class="docutils literal"><span class="pre">obj0</span></tt>. A number of functions, supplied by <tt class="docutils literal"><span class="pre">numpy.i</span></tt>, are called +to make and check the (possible) conversion from a generic <a class="reference" href="http://www.python.org">python</a> +object to a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array. These functions are explained in the +section <a class="reference" href="#helper-functions">Helper Functions</a>, but hopefully their names are +self-explanatory. At line 12 we use <tt class="docutils literal"><span class="pre">obj0</span></tt> to construct a <a class="reference" href="http://numpy.scipy.org">NumPy</a> +array. At line 17, we check the validity of the result: that it is +non-null and that it has a single dimension of arbitrary length. Once +these states are verified, we extract the data buffer and length in +lines 19 and 20 so that we can call the underlying C function at line +22. Line 25 performs memory management for the case where we have +created a new array that is no longer needed.</p> +<p>This code has a significant amount of error handling. Note the +<tt class="docutils literal"><span class="pre">SWIG_fail</span></tt> is a macro for <tt class="docutils literal"><span class="pre">goto</span> <span class="pre">fail</span></tt>, refering to the label at +line 28. If the user provides the wrong number of arguments, this +will be caught at line 10. If construction of the <a class="reference" href="http://numpy.scipy.org">NumPy</a> array +fails or produces an array with the wrong number of dimensions, these +errors are caught at line 17. And finally, if an error is detected, +memory is still managed correctly at line 30.</p> +<p>Note that if the C function signature was in a different order:</p> +<pre class="literal-block"> +double rms(int n, double* seq); +</pre> +<p>that <a class="reference" href="http://www.swig.org">SWIG</a> would not match the typemap signature given above with +the argument list for <tt class="docutils literal"><span class="pre">rms</span></tt>. Fortunately, <tt class="docutils literal"><span class="pre">numpy.i</span></tt> has a set of +typemaps with the data pointer given last:</p> +<pre class="literal-block"> +%apply (int DIM1, double* IN_ARRAY1) {(int n, double* seq)}; +</pre> +<p>This simply has the effect of switching the definitions of <tt class="docutils literal"><span class="pre">arg1</span></tt> +and <tt class="docutils literal"><span class="pre">arg2</span></tt> in lines 3 and 4 of the generated code above, and their +assignments in lines 19 and 20.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id2" id="using-numpy-i" name="using-numpy-i">Using numpy.i</a></h1> +<p>The <tt class="docutils literal"><span class="pre">numpy.i</span></tt> file is currently located in the <tt class="docutils literal"><span class="pre">numpy/docs/swig</span></tt> +sub-directory under the <tt class="docutils literal"><span class="pre">numpy</span></tt> installation directory. Typically, +you will want to copy it to the directory where you are developing +your wrappers. If it is ever adopted by <a class="reference" href="http://www.swig.org">SWIG</a> developers, then it +will be installed in a standard place where <a class="reference" href="http://www.swig.org">SWIG</a> can find it.</p> +<p>A simple module that only uses a single <a class="reference" href="http://www.swig.org">SWIG</a> interface file should +include the following:</p> +<pre class="literal-block"> +%{ +#define SWIG_FILE_WITH_INIT +%} +%include "numpy.i" +%init %{ +import_array(); +%} +</pre> +<p>Within a compiled <a class="reference" href="http://www.python.org">python</a> module, <tt class="docutils literal"><span class="pre">import_array()</span></tt> should only get +called once. This could be in a C/C++ file that you have written and +is linked to the module. If this is the case, then none of your +interface files should <tt class="docutils literal"><span class="pre">#define</span> <span class="pre">SWIG_FILE_WITH_INIT</span></tt> or call +<tt class="docutils literal"><span class="pre">import_array()</span></tt>. Or, this initialization call could be in a +wrapper file generated by <a class="reference" href="http://www.swig.org">SWIG</a> from an interface file that has the +<tt class="docutils literal"><span class="pre">%init</span></tt> block as above. If this is the case, and you have more than +one <a class="reference" href="http://www.swig.org">SWIG</a> interface file, then only one interface file should +<tt class="docutils literal"><span class="pre">#define</span> <span class="pre">SWIG_FILE_WITH_INIT</span></tt> and call <tt class="docutils literal"><span class="pre">import_array()</span></tt>.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id3" id="available-typemaps" name="available-typemaps">Available Typemaps</a></h1> +<p>The typemap directives provided by <tt class="docutils literal"><span class="pre">numpy.i</span></tt> for arrays of different +data types, say <tt class="docutils literal"><span class="pre">double</span></tt> and <tt class="docutils literal"><span class="pre">int</span></tt>, and dimensions of different +types, say <tt class="docutils literal"><span class="pre">int</span></tt> or <tt class="docutils literal"><span class="pre">long</span></tt>, are identical to one another except +for the C and <a class="reference" href="http://numpy.scipy.org">NumPy</a> type specifications. The typemaps are +therefore implemented (typically behind the scenes) via a macro:</p> +<pre class="literal-block"> +%numpy_typemaps(DATA_TYPE, DATA_TYPECODE, DIM_TYPE) +</pre> +<p>that can be invoked for appropriate <tt class="docutils literal"><span class="pre">(DATA_TYPE,</span> <span class="pre">DATA_TYPECODE,</span> +<span class="pre">DIM_TYPE)</span></tt> triplets. For example:</p> +<pre class="literal-block"> +%numpy_typemaps(double, NPY_DOUBLE, int) +%numpy_typemaps(int, NPY_INT , int) +</pre> +<p>The <tt class="docutils literal"><span class="pre">numpy.i</span></tt> interface file uses the <tt class="docutils literal"><span class="pre">%numpy_typemaps</span></tt> macro to +implement typemaps for the following C data types and <tt class="docutils literal"><span class="pre">int</span></tt> +dimension types:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">signed</span> <span class="pre">char</span></tt></li> +<li><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span></tt></li> +<li><tt class="docutils literal"><span class="pre">short</span></tt></li> +<li><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt></li> +<li><tt class="docutils literal"><span class="pre">int</span></tt></li> +<li><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt></li> +<li><tt class="docutils literal"><span class="pre">long</span></tt></li> +<li><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt></li> +<li><tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt></li> +<li><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></tt></li> +<li><tt class="docutils literal"><span class="pre">float</span></tt></li> +<li><tt class="docutils literal"><span class="pre">double</span></tt></li> +</ul> +</blockquote> +<p>In the following descriptions, we reference a generic <tt class="docutils literal"><span class="pre">DATA_TYPE</span></tt>, which +could be any of the C data types listed above, and <tt class="docutils literal"><span class="pre">DIM_TYPE</span></tt> which +should be one of the many types of integers.</p> +<p>The typemap signatures are largely differentiated on the name given to +the buffer pointer. Names with <tt class="docutils literal"><span class="pre">FARRAY</span></tt> are for FORTRAN-ordered +arrays, and names with <tt class="docutils literal"><span class="pre">ARRAY</span></tt> are for C-ordered (or 1D arrays).</p> +<div class="section"> +<h2><a class="toc-backref" href="#id4" id="input-arrays" name="input-arrays">Input Arrays</a></h2> +<p>Input arrays are defined as arrays of data that are passed into a +routine but are not altered in-place or returned to the user. The +<a class="reference" href="http://www.python.org">python</a> input array is therefore allowed to be almost any <a class="reference" href="http://www.python.org">python</a> +sequence (such as a list) that can be converted to the requested type +of array. The input array signatures are</p> +<p>1D:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">IN_ARRAY1[ANY]</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY1,</span> <span class="pre">int</span> <span class="pre">DIM1</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY1</span> <span class="pre">)</span></tt></li> +</ul> +</blockquote> +<p>2D:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">IN_ARRAY2[ANY][ANY]</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY2,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY2</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_FARRAY2,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_FARRAY2</span> <span class="pre">)</span></tt></li> +</ul> +</blockquote> +<p>3D:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">IN_ARRAY3[ANY][ANY][ANY]</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY3,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY3</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_FARRAY3,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_FARRAY3</span> <span class="pre">)</span></tt></li> +</ul> +</blockquote> +<p>The first signature listed, <tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">IN_ARRAY[ANY]</span> <span class="pre">)</span></tt> is for +one-dimensional arrays with hard-coded dimensions. Likewise, +<tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">IN_ARRAY2[ANY][ANY]</span> <span class="pre">)</span></tt> is for two-dimensional arrays +with hard-coded dimensions, and similarly for three-dimensional.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id5" id="in-place-arrays" name="in-place-arrays">In-Place Arrays</a></h2> +<p>In-place arrays are defined as arrays that are modified in-place. The +input values may or may not be used, but the values at the time the +function returns are significant. The provided <a class="reference" href="http://www.python.org">python</a> argument +must therefore be a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array of the required type. The in-place +signatures are</p> +<p>1D:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">INPLACE_ARRAY1[ANY]</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY1,</span> <span class="pre">int</span> <span class="pre">DIM1</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY1</span> <span class="pre">)</span></tt></li> +</ul> +</blockquote> +<p>2D:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">INPLACE_ARRAY2[ANY][ANY]</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY2,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY2</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_FARRAY2,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_FARRAY2</span> <span class="pre">)</span></tt></li> +</ul> +</blockquote> +<p>3D:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">INPLACE_ARRAY3[ANY][ANY][ANY]</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY3,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY3</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_FARRAY3,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_FARRAY3</span> <span class="pre">)</span></tt></li> +</ul> +</blockquote> +<p>These typemaps now check to make sure that the <tt class="docutils literal"><span class="pre">INPLACE_ARRAY</span></tt> +arguments use native byte ordering. If not, an exception is raised.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id6" id="argout-arrays" name="argout-arrays">Argout Arrays</a></h2> +<p>Argout arrays are arrays that appear in the input arguments in C, but +are in fact output arrays. This pattern occurs often when there is +more than one output variable and the single return argument is +therefore not sufficient. In <a class="reference" href="http://www.python.org">python</a>, the convential way to return +multiple arguments is to pack them into a sequence (tuple, list, etc.) +and return the sequence. This is what the argout typemaps do. If a +wrapped function that uses these argout typemaps has more than one +return argument, they are packed into a tuple or list, depending on +the version of <a class="reference" href="http://www.python.org">python</a>. The <a class="reference" href="http://www.python.org">python</a> user does not pass these +arrays in, they simply get returned. For the case where a dimension +is specified, the python user must provide that dimension as an +argument. The argout signatures are</p> +<p>1D:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">ARGOUT_ARRAY1[ANY]</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">ARGOUT_ARRAY1,</span> <span class="pre">int</span> <span class="pre">DIM1</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">ARGOUT_ARRAY1</span> <span class="pre">)</span></tt></li> +</ul> +</blockquote> +<p>2D:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">ARGOUT_ARRAY2[ANY][ANY]</span> <span class="pre">)</span></tt></li> +</ul> +</blockquote> +<p>3D:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">ARGOUT_ARRAY3[ANY][ANY][ANY]</span> <span class="pre">)</span></tt></li> +</ul> +</blockquote> +<p>These are typically used in situations where in C/C++, you would +allocate a(n) array(s) on the heap, and call the function to fill the +array(s) values. In <a class="reference" href="http://www.python.org">python</a>, the arrays are allocated for you and +returned as new array objects.</p> +<p>Note that we support <tt class="docutils literal"><span class="pre">DATA_TYPE*</span></tt> argout typemaps in 1D, but not 2D +or 3D. This is because of a quirk with the <a class="reference" href="http://www.swig.org">SWIG</a> typemap syntax and +cannot be avoided. Note that for these types of 1D typemaps, the +<a class="reference" href="http://www.python.org">python</a> function will take a single argument representing <tt class="docutils literal"><span class="pre">DIM1</span></tt>.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id7" id="argoutview-arrays" name="argoutview-arrays">Argoutview Arrays</a></h2> +<p>Argoutview arrays are for when your C code provides you with a view of +its internal data and does not require any memory to be allocated by +the user. This can be dangerous. There is almost no way to guarantee +that the internal data from the C code will remain in existence for +the entire lifetime of the <a class="reference" href="http://numpy.scipy.org">NumPy</a> array that encapsulates it. If +the user destroys the object that provides the view of the data before +destroying the <a class="reference" href="http://numpy.scipy.org">NumPy</a> array, then using that array my result in bad +memory references or segmentation faults. Nevertheless, there are +situations, working with large data sets, where you simply have no +other choice.</p> +<p>The C code to be wrapped for argoutview arrays are characterized by +pointers: pointers to the dimensions and double pointers to the data, +so that these values can be passed back to the user. The argoutview +typemap signatures are therefore</p> +<p>1D:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY1</span> <span class="pre">)</span></tt></li> +</ul> +</blockquote> +<p>2D:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY2</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_FARRAY2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2</span> <span class="pre">)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_FARRAY2</span> <span class="pre">)</span></tt></li> +</ul> +</blockquote> +<p>3D:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY3)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_FARRAY3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3)</span></tt></li> +<li><tt class="docutils literal"><span class="pre">(</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_FARRAY3)</span></tt></li> +</ul> +</blockquote> +<p>Note that arrays with hard-coded dimensions are not supported. These +cannot follow the double pointer signatures of these typemaps.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id8" id="output-arrays" name="output-arrays">Output Arrays</a></h2> +<p>The <tt class="docutils literal"><span class="pre">numpy.i</span></tt> interface file does not support typemaps for output +arrays, for several reasons. First, C/C++ return arguments are +limited to a single value. This prevents obtaining dimension +information in a general way. Second, arrays with hard-coded lengths +are not permitted as return arguments. In other words:</p> +<pre class="literal-block"> +double[3] newVector(double x, double y, double z); +</pre> +<p>is not legal C/C++ syntax. Therefore, we cannot provide typemaps of +the form:</p> +<pre class="literal-block"> +%typemap(out) (TYPE[ANY]); +</pre> +<p>If you run into a situation where a function or method is returning a +pointer to an array, your best bet is to write your own version of the +function to be wrapped, either with <tt class="docutils literal"><span class="pre">%extend</span></tt> for the case of class +methods or <tt class="docutils literal"><span class="pre">%ignore</span></tt> and <tt class="docutils literal"><span class="pre">%rename</span></tt> for the case of functions.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id9" id="other-common-types-bool" name="other-common-types-bool">Other Common Types: bool</a></h2> +<p>Note that C++ type <tt class="docutils literal"><span class="pre">bool</span></tt> is not supported in the list in the +<a class="reference" href="#available-typemaps">Available Typemaps</a> section. NumPy bools are a single byte, while +the C++ <tt class="docutils literal"><span class="pre">bool</span></tt> is four bytes (at least on my system). Therefore:</p> +<pre class="literal-block"> +%numpy_typemaps(bool, NPY_BOOL, int) +</pre> +<p>will result in typemaps that will produce code that reference +improper data lengths. You can implement the following macro +expansion:</p> +<pre class="literal-block"> +%numpy_typemaps(bool, NPY_UINT, int) +</pre> +<p>to fix the data length problem, and <a class="reference" href="#input-arrays">Input Arrays</a> will work fine, +but <a class="reference" href="#in-place-arrays">In-Place Arrays</a> might fail type-checking.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id10" id="other-common-types-complex" name="other-common-types-complex">Other Common Types: complex</a></h2> +<p>Typemap conversions for complex floating-point types is also not +supported automatically. This is because <a class="reference" href="http://www.python.org">python</a> and <a class="reference" href="http://numpy.scipy.org">NumPy</a> are +written in C, which does not have native complex types. Both +<a class="reference" href="http://www.python.org">python</a> and <a class="reference" href="http://numpy.scipy.org">NumPy</a> implement their own (essentially equivalent) +<tt class="docutils literal"><span class="pre">struct</span></tt> definitions for complex variables:</p> +<pre class="literal-block"> +/* Python */ +typedef struct {double real; double imag;} Py_complex; + +/* NumPy */ +typedef struct {float real, imag;} npy_cfloat; +typedef struct {double real, imag;} npy_cdouble; +</pre> +<p>We could have implemented:</p> +<pre class="literal-block"> +%numpy_typemaps(Py_complex , NPY_CDOUBLE, int) +%numpy_typemaps(npy_cfloat , NPY_CFLOAT , int) +%numpy_typemaps(npy_cdouble, NPY_CDOUBLE, int) +</pre> +<p>which would have provided automatic type conversions for arrays of +type <tt class="docutils literal"><span class="pre">Py_complex</span></tt>, <tt class="docutils literal"><span class="pre">npy_cfloat</span></tt> and <tt class="docutils literal"><span class="pre">npy_cdouble</span></tt>. However, it +seemed unlikely that there would be any independent (non-<a class="reference" href="http://www.python.org">python</a>, +non-<a class="reference" href="http://numpy.scipy.org">NumPy</a>) application code that people would be using <a class="reference" href="http://www.swig.org">SWIG</a> to +generate a <a class="reference" href="http://www.python.org">python</a> interface to, that also used these definitions +for complex types. More likely, these application codes will define +their own complex types, or in the case of C++, use <tt class="docutils literal"><span class="pre">std::complex</span></tt>. +Assuming these data structures are compatible with <a class="reference" href="http://www.python.org">python</a> and +<a class="reference" href="http://numpy.scipy.org">NumPy</a> complex types, <tt class="docutils literal"><span class="pre">%numpy_typemap</span></tt> expansions as above (with +the user's complex type substituted for the first argument) should +work.</p> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id11" id="numpy-array-scalars-and-swig" name="numpy-array-scalars-and-swig">NumPy Array Scalars and SWIG</a></h1> +<p><a class="reference" href="http://www.swig.org">SWIG</a> has sophisticated type checking for numerical types. For +example, if your C/C++ routine expects an integer as input, the code +generated by <a class="reference" href="http://www.swig.org">SWIG</a> will check for both <a class="reference" href="http://www.python.org">python</a> integers and +<a class="reference" href="http://www.python.org">python</a> long integers, and raise an overflow error if the provided +<a class="reference" href="http://www.python.org">python</a> integer is too big to cast down to a C integer. With the +introduction of <a class="reference" href="http://numpy.scipy.org">NumPy</a> scalar arrays into your <a class="reference" href="http://www.python.org">python</a> code, you +might conceivably extract an integer from a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array and attempt +to pass this to a <a class="reference" href="http://www.swig.org">SWIG</a>-wrapped C/C++ function that expects an +<tt class="docutils literal"><span class="pre">int</span></tt>, but the <a class="reference" href="http://www.swig.org">SWIG</a> type checking will not recognize the <a class="reference" href="http://numpy.scipy.org">NumPy</a> +array scalar as an integer. (Often, this does in fact work -- it +depends on whether <a class="reference" href="http://numpy.scipy.org">NumPy</a> recognizes the integer type you are using +as inheriting from the <a class="reference" href="http://www.python.org">python</a> integer type on the platform you are +using. Sometimes, this means that code that works on a 32-bit machine +will fail on a 64-bit machine.)</p> +<p>If you get a <a class="reference" href="http://www.python.org">python</a> error that looks like the following:</p> +<pre class="literal-block"> +TypeError: in method 'MyClass_MyMethod', argument 2 of type 'int' +</pre> +<p>and the argument you are passing is an integer extracted from a +<a class="reference" href="http://numpy.scipy.org">NumPy</a> array, then you have stumbled upon this problem. The +solution is to modify the <a class="reference" href="http://www.swig.org">SWIG</a> type conversion system to accept +<a class="reference" href="http://numpy.scipy.org">Numpy</a> array scalars in addition to the standard integer types. +Fortunately, this capabilitiy has been provided for you. Simply copy +the file:</p> +<pre class="literal-block"> +pyfragments.swg +</pre> +<p>to the working build directory for you project, and this problem will +be fixed. It is suggested that you do this anyway, as it only +increases the capabilities of your <a class="reference" href="http://www.python.org">python</a> interface.</p> +<div class="section"> +<h2><a class="toc-backref" href="#id12" id="why-is-there-a-second-file" name="why-is-there-a-second-file">Why is There a Second File?</a></h2> +<p>The <a class="reference" href="http://www.swig.org">SWIG</a> type checking and conversion system is a complicated +combination of C macros, <a class="reference" href="http://www.swig.org">SWIG</a> macros, <a class="reference" href="http://www.swig.org">SWIG</a> typemaps and <a class="reference" href="http://www.swig.org">SWIG</a> +fragments. Fragments are a way to conditionally insert code into your +wrapper file if it is needed, and not insert it if not needed. If +multiple typemaps require the same fragment, the fragment only gets +inserted into your wrapper code once.</p> +<p>There is a fragment for converting a <a class="reference" href="http://www.python.org">python</a> integer to a C +<tt class="docutils literal"><span class="pre">long</span></tt>. There is a different fragment that converts a <a class="reference" href="http://www.python.org">python</a> +integer to a C <tt class="docutils literal"><span class="pre">int</span></tt>, that calls the rountine defined in the +<tt class="docutils literal"><span class="pre">long</span></tt> fragment. We can make the changes we want here by changing +the definition for the <tt class="docutils literal"><span class="pre">long</span></tt> fragment. <a class="reference" href="http://www.swig.org">SWIG</a> determines the +active definition for a fragment using a "first come, first served" +system. That is, we need to define the fragment for <tt class="docutils literal"><span class="pre">long</span></tt> +conversions prior to <a class="reference" href="http://www.swig.org">SWIG</a> doing it internally. <a class="reference" href="http://www.swig.org">SWIG</a> allows us +to do this by putting our fragment definitions in the file +<tt class="docutils literal"><span class="pre">pyfragments.swg</span></tt>. If we were to put the new fragment definitions +in <tt class="docutils literal"><span class="pre">numpy.i</span></tt>, they would be ignored.</p> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id13" id="helper-functions" name="helper-functions">Helper Functions</a></h1> +<p>The <tt class="docutils literal"><span class="pre">numpy.i</span></tt> file containes several macros and routines that it +uses internally to build its typemaps. However, these functions may +be useful elsewhere in your interface file. These macros and routines +are implemented as fragments, which are described briefly in the +previous section. If you try to use one or more of the following +macros or functions, but your compiler complains that it does not +recognize the symbol, then you need to force these fragments to appear +in your code using:</p> +<pre class="literal-block"> +%fragment("NumPy_Fragments"); +</pre> +<p>in your <a class="reference" href="http://www.swig.org">SWIG</a> interface file.</p> +<div class="section"> +<h2><a class="toc-backref" href="#id14" id="macros" name="macros">Macros</a></h2> +<blockquote> +<dl class="docutils"> +<dt><strong>is_array(a)</strong></dt> +<dd>Evaluates as true if <tt class="docutils literal"><span class="pre">a</span></tt> is non-<tt class="docutils literal"><span class="pre">NULL</span></tt> and can be cast to a +<tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt>.</dd> +<dt><strong>array_type(a)</strong></dt> +<dd>Evaluates to the integer data type code of <tt class="docutils literal"><span class="pre">a</span></tt>, assuming <tt class="docutils literal"><span class="pre">a</span></tt> can +be cast to a <tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt>.</dd> +<dt><strong>array_numdims(a)</strong></dt> +<dd>Evaluates to the integer number of dimensions of <tt class="docutils literal"><span class="pre">a</span></tt>, assuming +<tt class="docutils literal"><span class="pre">a</span></tt> can be cast to a <tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt>.</dd> +<dt><strong>array_dimensions(a)</strong></dt> +<dd>Evaluates to an array of type <tt class="docutils literal"><span class="pre">npy_intp</span></tt> and length +<tt class="docutils literal"><span class="pre">array_numdims(a)</span></tt>, giving the lengths of all of the dimensions +of <tt class="docutils literal"><span class="pre">a</span></tt>, assuming <tt class="docutils literal"><span class="pre">a</span></tt> can be cast to a <tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt>.</dd> +<dt><strong>array_size(a,i)</strong></dt> +<dd>Evaluates to the <tt class="docutils literal"><span class="pre">i</span></tt>-th dimension size of <tt class="docutils literal"><span class="pre">a</span></tt>, assuming <tt class="docutils literal"><span class="pre">a</span></tt> +can be cast to a <tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt>.</dd> +<dt><strong>array_data(a)</strong></dt> +<dd>Evaluates to a pointer of type <tt class="docutils literal"><span class="pre">void*</span></tt> that points to the data +buffer of <tt class="docutils literal"><span class="pre">a</span></tt>, assuming <tt class="docutils literal"><span class="pre">a</span></tt> can be cast to a <tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt>.</dd> +<dt><strong>array_is_contiguous(a)</strong></dt> +<dd>Evaluates as true if <tt class="docutils literal"><span class="pre">a</span></tt> is a contiguous array. Equivalent to +<tt class="docutils literal"><span class="pre">(PyArray_ISCONTIGUOUS(a))</span></tt>.</dd> +<dt><strong>array_is_native(a)</strong></dt> +<dd>Evaluates as true if the data buffer of <tt class="docutils literal"><span class="pre">a</span></tt> uses native byte +order. Equivalent to <tt class="docutils literal"><span class="pre">(PyArray_ISNOTSWAPPED(a))</span></tt>.</dd> +<dt><strong>array_is_fortran(a)</strong></dt> +<dd>Evaluates as true if <tt class="docutils literal"><span class="pre">a</span></tt> is FORTRAN ordered.</dd> +</dl> +</blockquote> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id15" id="routines" name="routines">Routines</a></h2> +<blockquote> +<p><strong>pytype_string()</strong></p> +<blockquote> +<p>Return type: <tt class="docutils literal"><span class="pre">char*</span></tt></p> +<p>Arguments:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">PyObject*</span> <span class="pre">py_obj</span></tt>, a general <a class="reference" href="http://www.python.org">python</a> object.</li> +</ul> +<p>Return a string describing the type of <tt class="docutils literal"><span class="pre">py_obj</span></tt>.</p> +</blockquote> +<p><strong>typecode_string()</strong></p> +<blockquote> +<p>Return type: <tt class="docutils literal"><span class="pre">char*</span></tt></p> +<p>Arguments:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">int</span> <span class="pre">typecode</span></tt>, a <a class="reference" href="http://numpy.scipy.org">NumPy</a> integer typecode.</li> +</ul> +<p>Return a string describing the type corresponding to the <a class="reference" href="http://numpy.scipy.org">NumPy</a> +<tt class="docutils literal"><span class="pre">typecode</span></tt>.</p> +</blockquote> +<p><strong>type_match()</strong></p> +<blockquote> +<p>Return type: <tt class="docutils literal"><span class="pre">int</span></tt></p> +<p>Arguments:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">int</span> <span class="pre">actual_type</span></tt>, the <a class="reference" href="http://numpy.scipy.org">NumPy</a> typecode of a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array.</li> +<li><tt class="docutils literal"><span class="pre">int</span> <span class="pre">desired_type</span></tt>, the desired <a class="reference" href="http://numpy.scipy.org">NumPy</a> typecode.</li> +</ul> +<p>Make sure that <tt class="docutils literal"><span class="pre">actual_type</span></tt> is compatible with +<tt class="docutils literal"><span class="pre">desired_type</span></tt>. For example, this allows character and +byte types, or int and long types, to match. This is now +equivalent to <tt class="docutils literal"><span class="pre">PyArray_EquivTypenums()</span></tt>.</p> +</blockquote> +<p><strong>obj_to_array_no_conversion()</strong></p> +<blockquote> +<p>Return type: <tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt></p> +<p>Arguments:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">PyObject*</span> <span class="pre">input</span></tt>, a general <a class="reference" href="http://www.python.org">python</a> object.</li> +<li><tt class="docutils literal"><span class="pre">int</span> <span class="pre">typecode</span></tt>, the desired <a class="reference" href="http://numpy.scipy.org">NumPy</a> typecode.</li> +</ul> +<p>Cast <tt class="docutils literal"><span class="pre">input</span></tt> to a <tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt> if legal, and ensure that +it is of type <tt class="docutils literal"><span class="pre">typecode</span></tt>. If <tt class="docutils literal"><span class="pre">input</span></tt> cannot be cast, or the +<tt class="docutils literal"><span class="pre">typecode</span></tt> is wrong, set a <a class="reference" href="http://www.python.org">python</a> error and return <tt class="docutils literal"><span class="pre">NULL</span></tt>.</p> +</blockquote> +<p><strong>obj_to_array_allow_conversion()</strong></p> +<blockquote> +<p>Return type: <tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt></p> +<p>Arguments:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">PyObject*</span> <span class="pre">input</span></tt>, a general <a class="reference" href="http://www.python.org">python</a> object.</li> +<li><tt class="docutils literal"><span class="pre">int</span> <span class="pre">typecode</span></tt>, the desired <a class="reference" href="http://numpy.scipy.org">NumPy</a> typecode of the resulting +array.</li> +<li><tt class="docutils literal"><span class="pre">int*</span> <span class="pre">is_new_object</span></tt>, returns a value of 0 if no conversion +performed, else 1.</li> +</ul> +<p>Convert <tt class="docutils literal"><span class="pre">input</span></tt> to a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array with the given <tt class="docutils literal"><span class="pre">typecode</span></tt>. +On success, return a valid <tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt> with the correct +type. On failure, the <a class="reference" href="http://www.python.org">python</a> error string will be set and the +routine returns <tt class="docutils literal"><span class="pre">NULL</span></tt>.</p> +</blockquote> +<p><strong>make_contiguous()</strong></p> +<blockquote> +<p>Return type: <tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt></p> +<p>Arguments:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">PyArrayObject*</span> <span class="pre">ary</span></tt>, a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array.</li> +<li><tt class="docutils literal"><span class="pre">int*</span> <span class="pre">is_new_object</span></tt>, returns a value of 0 if no conversion +performed, else 1.</li> +<li><tt class="docutils literal"><span class="pre">int</span> <span class="pre">min_dims</span></tt>, minimum allowable dimensions.</li> +<li><tt class="docutils literal"><span class="pre">int</span> <span class="pre">max_dims</span></tt>, maximum allowable dimensions.</li> +</ul> +<p>Check to see if <tt class="docutils literal"><span class="pre">ary</span></tt> is contiguous. If so, return the input +pointer and flag it as not a new object. If it is not contiguous, +create a new <tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt> using the original data, flag it +as a new object and return the pointer.</p> +</blockquote> +<p><strong>obj_to_array_contiguous_allow_conversion()</strong></p> +<blockquote> +<p>Return type: <tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt></p> +<p>Arguments:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">PyObject*</span> <span class="pre">input</span></tt>, a general <a class="reference" href="http://www.python.org">python</a> object.</li> +<li><tt class="docutils literal"><span class="pre">int</span> <span class="pre">typecode</span></tt>, the desired <a class="reference" href="http://numpy.scipy.org">NumPy</a> typecode of the resulting +array.</li> +<li><tt class="docutils literal"><span class="pre">int*</span> <span class="pre">is_new_object</span></tt>, returns a value of 0 if no conversion +performed, else 1.</li> +</ul> +<p>Convert <tt class="docutils literal"><span class="pre">input</span></tt> to a contiguous <tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt> of the +specified type. If the input object is not a contiguous +<tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt>, a new one will be created and the new object +flag will be set.</p> +</blockquote> +<p><strong>require_contiguous()</strong></p> +<blockquote> +<p>Return type: <tt class="docutils literal"><span class="pre">int</span></tt></p> +<p>Arguments:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">PyArrayObject*</span> <span class="pre">ary</span></tt>, a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array.</li> +</ul> +<p>Test whether <tt class="docutils literal"><span class="pre">ary</span></tt> is contiguous. If so, return 1. Otherwise, +set a <a class="reference" href="http://www.python.org">python</a> error and return 0.</p> +</blockquote> +<p><strong>require_native()</strong></p> +<blockquote> +<p>Return type: <tt class="docutils literal"><span class="pre">int</span></tt></p> +<p>Arguments:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">PyArray_Object*</span> <span class="pre">ary</span></tt>, a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array.</li> +</ul> +<p>Require that <tt class="docutils literal"><span class="pre">ary</span></tt> is not byte-swapped. If the array is not +byte-swapped, return 1. Otherwise, set a <a class="reference" href="http://www.python.org">python</a> error and +return 0.</p> +</blockquote> +<p><strong>require_dimensions()</strong></p> +<blockquote> +<p>Return type: <tt class="docutils literal"><span class="pre">int</span></tt></p> +<p>Arguments:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">PyArrayObject*</span> <span class="pre">ary</span></tt>, a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array.</li> +<li><tt class="docutils literal"><span class="pre">int</span> <span class="pre">exact_dimensions</span></tt>, the desired number of dimensions.</li> +</ul> +<p>Require <tt class="docutils literal"><span class="pre">ary</span></tt> to have a specified number of dimensions. If the +array has the specified number of dimensions, return 1. +Otherwise, set a <a class="reference" href="http://www.python.org">python</a> error and return 0.</p> +</blockquote> +<p><strong>require_dimensions_n()</strong></p> +<blockquote> +<p>Return type: <tt class="docutils literal"><span class="pre">int</span></tt></p> +<p>Arguments:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">PyArrayObject*</span> <span class="pre">ary</span></tt>, a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array.</li> +<li><tt class="docutils literal"><span class="pre">int*</span> <span class="pre">exact_dimensions</span></tt>, an array of integers representing +acceptable numbers of dimensions.</li> +<li><tt class="docutils literal"><span class="pre">int</span> <span class="pre">n</span></tt>, the length of <tt class="docutils literal"><span class="pre">exact_dimensions</span></tt>.</li> +</ul> +<p>Require <tt class="docutils literal"><span class="pre">ary</span></tt> to have one of a list of specified number of +dimensions. If the array has one of the specified number of +dimensions, return 1. Otherwise, set the <a class="reference" href="http://www.python.org">python</a> error string +and return 0.</p> +</blockquote> +<p><strong>require_size()</strong></p> +<blockquote> +<p>Return type: <tt class="docutils literal"><span class="pre">int</span></tt></p> +<p>Arguments:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">PyArrayObject*</span> <span class="pre">ary</span></tt>, a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array.</li> +<li><tt class="docutils literal"><span class="pre">npy_int*</span> <span class="pre">size</span></tt>, an array representing the desired lengths of +each dimension.</li> +<li><tt class="docutils literal"><span class="pre">int</span> <span class="pre">n</span></tt>, the length of <tt class="docutils literal"><span class="pre">size</span></tt>.</li> +</ul> +<p>Require <tt class="docutils literal"><span class="pre">ary</span></tt> to have a specified shape. If the array has the +specified shape, return 1. Otherwise, set the <a class="reference" href="http://www.python.org">python</a> error +string and return 0.</p> +</blockquote> +<p><strong>require_fortran()</strong></p> +<blockquote> +<p>Return type: <tt class="docutils literal"><span class="pre">int</span></tt></p> +<p>Arguments:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">PyArrayObject*</span> <span class="pre">ary</span></tt>, a <a class="reference" href="http://numpy.scipy.org">NumPy</a> array.</li> +</ul> +<p>Require the given <tt class="docutils literal"><span class="pre">PyArrayObject</span></tt> to to be FORTRAN ordered. If +the the <tt class="docutils literal"><span class="pre">PyArrayObject</span></tt> is already FORTRAN ordered, do nothing. +Else, set the FORTRAN ordering flag and recompute the strides.</p> +</blockquote> +</blockquote> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id16" id="beyond-the-provided-typemaps" name="beyond-the-provided-typemaps">Beyond the Provided Typemaps</a></h1> +<p>There are many C or C++ array/<a class="reference" href="http://numpy.scipy.org">NumPy</a> array situations not covered by +a simple <tt class="docutils literal"><span class="pre">%include</span> <span class="pre">"numpy.i"</span></tt> and subsequent <tt class="docutils literal"><span class="pre">%apply</span></tt> directives.</p> +<div class="section"> +<h2><a class="toc-backref" href="#id17" id="a-common-example" name="a-common-example">A Common Example</a></h2> +<p>Consider a reasonable prototype for a dot product function:</p> +<pre class="literal-block"> +double dot(int len, double* vec1, double* vec2); +</pre> +<p>The <a class="reference" href="http://www.python.org">python</a> interface that we want is:</p> +<pre class="literal-block"> +def dot(vec1, vec2): + """ + dot(PyObject,PyObject) -> double + """ +</pre> +<p>The problem here is that there is one dimension argument and two array +arguments, and our typemaps are set up for dimensions that apply to a +single array (in fact, <a class="reference" href="http://www.swig.org">SWIG</a> does not provide a mechanism for +associating <tt class="docutils literal"><span class="pre">len</span></tt> with <tt class="docutils literal"><span class="pre">vec2</span></tt> that takes two <a class="reference" href="http://www.python.org">python</a> input +arguments). The recommended solution is the following:</p> +<pre class="literal-block"> +%apply (int DIM1, double* IN_ARRAY1) {(int len1, double* vec1), + (int len2, double* vec2)} +%rename (dot) my_dot; +%exception my_dot { + $action + if (PyErr_Occurred()) SWIG_fail; +} +%inline %{ +double my_dot(int len1, double* vec1, int len2, double* vec2) { + if (len1 != len2) { + PyErr_Format(PyExc_ValueError, + "Arrays of lengths (%d,%d) given", + len1, len2); + return 0.0; + } + return dot(len1, vec1, vec2); +} +%} +</pre> +<p>If the header file that contains the prototype for <tt class="docutils literal"><span class="pre">double</span> <span class="pre">dot()</span></tt> +also contains other prototypes that you want to wrap, so that you need +to <tt class="docutils literal"><span class="pre">%include</span></tt> this header file, then you will also need a <tt class="docutils literal"><span class="pre">%ignore</span> +<span class="pre">dot;</span></tt> directive, placed after the <tt class="docutils literal"><span class="pre">%rename</span></tt> and before the +<tt class="docutils literal"><span class="pre">%include</span></tt> directives. Or, if the function in question is a class +method, you will want to use <tt class="docutils literal"><span class="pre">%extend</span></tt> rather than <tt class="docutils literal"><span class="pre">%inline</span></tt> in +addition to <tt class="docutils literal"><span class="pre">%ignore</span></tt>.</p> +<p><strong>A note on error handling:</strong> Note that <tt class="docutils literal"><span class="pre">my_dot</span></tt> returns a +<tt class="docutils literal"><span class="pre">double</span></tt> but that it can also raise a <a class="reference" href="http://www.python.org">python</a> error. The +resulting wrapper function will return a <a class="reference" href="http://www.python.org">python</a> float +representation of 0.0 when the vector lengths do not match. Since +this is not <tt class="docutils literal"><span class="pre">NULL</span></tt>, the <a class="reference" href="http://www.python.org">python</a> interpreter will not know to check +for an error. For this reason, we add the <tt class="docutils literal"><span class="pre">%exception</span></tt> directive +above for <tt class="docutils literal"><span class="pre">my_dot</span></tt> to get the behavior we want (note that +<tt class="docutils literal"><span class="pre">$action</span></tt> is a macro that gets expanded to a valid call to +<tt class="docutils literal"><span class="pre">my_dot</span></tt>). In general, you will probably want to write a <a class="reference" href="http://www.swig.org">SWIG</a> +macro to perform this task.</p> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id18" id="other-situations" name="other-situations">Other Situations</a></h2> +<p>There are other wrapping situations in which <tt class="docutils literal"><span class="pre">numpy.i</span></tt> may be +helpful when you encounter them.</p> +<blockquote> +<ul> +<li><p class="first">In some situations, it is possible that you could use the +<tt class="docutils literal"><span class="pre">%numpy_templates</span></tt> macro to implement typemaps for your own +types. See the <a class="reference" href="#other-common-types-bool">Other Common Types: bool</a> or <a class="reference" href="#other-common-types-complex">Other Common +Types: complex</a> sections for examples. Another situation is if +your dimensions are of a type other than <tt class="docutils literal"><span class="pre">int</span></tt> (say <tt class="docutils literal"><span class="pre">long</span></tt> for +example):</p> +<pre class="literal-block"> +%numpy_typemaps(double, NPY_DOUBLE, long) +</pre> +</li> +<li><p class="first">You can use the code in <tt class="docutils literal"><span class="pre">numpy.i</span></tt> to write your own typemaps. +For example, if you had a four-dimensional array as a function +argument, you could cut-and-paste the appropriate +three-dimensional typemaps into your interface file. The +modifications for the fourth dimension would be trivial.</p> +</li> +<li><p class="first">Sometimes, the best approach is to use the <tt class="docutils literal"><span class="pre">%extend</span></tt> directive +to define new methods for your classes (or overload existing ones) +that take a <tt class="docutils literal"><span class="pre">PyObject*</span></tt> (that either is or can be converted to a +<tt class="docutils literal"><span class="pre">PyArrayObject*</span></tt>) instead of a pointer to a buffer. In this +case, the helper routines in <tt class="docutils literal"><span class="pre">numpy.i</span></tt> can be very useful.</p> +</li> +<li><p class="first">Writing typemaps can be a bit nonintuitive. If you have specific +questions about writing <a class="reference" href="http://www.swig.org">SWIG</a> typemaps for <a class="reference" href="http://numpy.scipy.org">NumPy</a>, the +developers of <tt class="docutils literal"><span class="pre">numpy.i</span></tt> do monitor the +<a class="reference" href="mailto:Numpy-discussion@scipy.org">Numpy-discussion</a> and +<a class="reference" href="mailto:Swig-user@lists.sourceforge.net">Swig-user</a> mail lists.</p> +</li> +</ul> +</blockquote> +</div> +<div class="section"> +<h2><a class="toc-backref" href="#id19" id="a-final-note" name="a-final-note">A Final Note</a></h2> +<p>When you use the <tt class="docutils literal"><span class="pre">%apply</span></tt> directive, as is usually necessary to use +<tt class="docutils literal"><span class="pre">numpy.i</span></tt>, it will remain in effect until you tell <a class="reference" href="http://www.swig.org">SWIG</a> that it +shouldn't be. If the arguments to the functions or methods that you +are wrapping have common names, such as <tt class="docutils literal"><span class="pre">length</span></tt> or <tt class="docutils literal"><span class="pre">vector</span></tt>, +these typemaps may get applied in situations you do not expect or +want. Therefore, it is always a good idea to add a <tt class="docutils literal"><span class="pre">%clear</span></tt> +directive after you are done with a specific typemap:</p> +<pre class="literal-block"> +%apply (double* IN_ARRAY1, int DIM1) {(double* vector, int length)} +%include "my_header.h" +%clear (double* vector, int length); +</pre> +<p>In general, you should target these typemap signatures specifically +where you want them, and then clear them after you are done.</p> +</div> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id20" id="summary" name="summary">Summary</a></h1> +<p>Out of the box, <tt class="docutils literal"><span class="pre">numpy.i</span></tt> provides typemaps that support conversion +between <a class="reference" href="http://numpy.scipy.org">NumPy</a> arrays and C arrays:</p> +<blockquote> +<ul class="simple"> +<li>That can be one of 12 different scalar types: <tt class="docutils literal"><span class="pre">signed</span> <span class="pre">char</span></tt>, +<tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span></tt>, <tt class="docutils literal"><span class="pre">short</span></tt>, <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt>, <tt class="docutils literal"><span class="pre">int</span></tt>, +<tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">long</span></tt>, <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt>, <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt>, +<tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt> and <tt class="docutils literal"><span class="pre">double</span></tt>.</li> +<li>That support 41 different argument signatures for each data type, +including:<ul> +<li>One-dimensional, two-dimensional and three-dimensional arrays.</li> +<li>Input-only, in-place, argout and argoutview behavior.</li> +<li>Hard-coded dimensions, data-buffer-then-dimensions +specification, and dimensions-then-data-buffer specification.</li> +<li>Both C-ordering ("last dimension fastest") or FORTRAN-ordering +("first dimension fastest") support for 2D and 3D arrays.</li> +</ul> +</li> +</ul> +</blockquote> +<p>The <tt class="docutils literal"><span class="pre">numpy.i</span></tt> interface file also provides additional tools for +wrapper developers, including:</p> +<blockquote> +<ul class="simple"> +<li>A <a class="reference" href="http://www.swig.org">SWIG</a> macro (<tt class="docutils literal"><span class="pre">%numpy_typemaps</span></tt>) with three arguments for +implementing the 41 argument signatures for the user's choice of +(1) C data type, (2) <a class="reference" href="http://numpy.scipy.org">NumPy</a> data type (assuming they match), and +(3) dimension type.</li> +<li>Nine C macros and 13 C functions that can be used to write +specialized typemaps, extensions, or inlined functions that handle +cases not covered by the provided typemaps.</li> +</ul> +</blockquote> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id21" id="acknowledgements" name="acknowledgements">Acknowledgements</a></h1> +<p>Many people have worked to glue <a class="reference" href="http://www.swig.org">SWIG</a> and <a class="reference" href="http://numpy.scipy.org">NumPy</a> together (as well +as <a class="reference" href="http://www.swig.org">SWIG</a> and the predecessors of <a class="reference" href="http://numpy.scipy.org">NumPy</a>, Numeric and numarray). +The effort to standardize this work into <tt class="docutils literal"><span class="pre">numpy.i</span></tt> began at the 2005 +<a class="reference" href="http://scipy.org">SciPy</a> Conference with a conversation between +Fernando Perez and myself. Fernando collected helper functions and +typemaps from Eric Jones, Michael Hunter, Anna Omelchenko and Michael +Sanner. Sebastian Hasse and Georg Holzmann have also provided +additional error checking and use cases. The work of these +contributors has made this end result possible.</p> +</div> +</div> +<div class="footer"> +<hr class="footer" /> +Generated on: 2007-12-01 18:17 UTC. +Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source. + +</div> +</body> +</html> diff --git a/doc/swig/doc/numpy_swig.pdf b/doc/swig/doc/numpy_swig.pdf Binary files differnew file mode 100644 index 000000000..1d4642cf7 --- /dev/null +++ b/doc/swig/doc/numpy_swig.pdf diff --git a/doc/swig/doc/numpy_swig.txt b/doc/swig/doc/numpy_swig.txt new file mode 100644 index 000000000..bfde018bf --- /dev/null +++ b/doc/swig/doc/numpy_swig.txt @@ -0,0 +1,950 @@ +========================================== + numpy.i: a SWIG Interface File for NumPy +========================================== + +:Author: Bill Spotz +:Institution: Sandia National Laboratories +:Date: 1 December, 2007 + +.. contents:: + +Introduction +============ + +The Simple Wrapper and Interface Generator (or `SWIG +<http://www.swig.org>`_) is a powerful tool for generating wrapper +code for interfacing to a wide variety of scripting languages. +`SWIG`_ can parse header files, and using only the code prototypes, +create an interface to the target language. But `SWIG`_ is not +omnipotent. For example, it cannot know from the prototype:: + + double rms(double* seq, int n); + +what exactly ``seq`` is. Is it a single value to be altered in-place? +Is it an array, and if so what is its length? Is it input-only? +Output-only? Input-output? `SWIG`_ cannot determine these details, +and does not attempt to do so. + +If we designed ``rms``, we probably made it a routine that takes an +input-only array of length ``n`` of ``double`` values called ``seq`` +and returns the root mean square. The default behavior of `SWIG`_, +however, will be to create a wrapper function that compiles, but is +nearly impossible to use from the scripting language in the way the C +routine was intended. + +For `python <http://www.python.org>`_, the preferred way of handling +contiguous (or technically, *strided*) blocks of homogeneous data is +with the module `NumPy <http://numpy.scipy.org>`_, which provides full +object-oriented access to multidimensial arrays of data. Therefore, +the most logical `python`_ interface for the ``rms`` function would be +(including doc string):: + + def rms(seq): + """ + rms: return the root mean square of a sequence + rms(numpy.ndarray) -> double + rms(list) -> double + rms(tuple) -> double + """ + +where ``seq`` would be a `NumPy`_ array of ``double`` values, and its +length ``n`` would be extracted from ``seq`` internally before being +passed to the C routine. Even better, since `NumPy`_ supports +construction of arrays from arbitrary `python`_ sequences, ``seq`` +itself could be a nearly arbitrary sequence (so long as each element +can be converted to a ``double``) and the wrapper code would +internally convert it to a `NumPy`_ array before extracting its data +and length. + +`SWIG`_ allows these types of conversions to be defined via a +mechanism called typemaps. This document provides information on how +to use ``numpy.i``, a `SWIG`_ interface file that defines a series of +typemaps intended to make the type of array-related conversions +described above relatively simple to implement. For example, suppose +that the ``rms`` function prototype defined above was in a header file +named ``rms.h``. To obtain the `python`_ interface discussed above, +your `SWIG`_ interface file would need the following:: + + %{ + #define SWIG_FILE_WITH_INIT + #include "rms.h" + %} + + %include "numpy.i" + + %init %{ + import_array(); + %} + + %apply (double* IN_ARRAY1, int DIM1) {(double* seq, int n)}; + %include "rms.h" + +Typemaps are keyed off a list of one or more function arguments, +either by type or by type and name. We will refer to such lists as +*signatures*. One of the many typemaps defined by ``numpy.i`` is used +above and has the signature ``(double* IN_ARRAY1, int DIM1)``. The +argument names are intended to suggest that the ``double*`` argument +is an input array of one dimension and that the ``int`` represents +that dimension. This is precisely the pattern in the ``rms`` +prototype. + +Most likely, no actual prototypes to be wrapped will have the argument +names ``IN_ARRAY1`` and ``DIM1``. We use the ``%apply`` directive to +apply the typemap for one-dimensional input arrays of type ``double`` +to the actual prototype used by ``rms``. Using ``numpy.i`` +effectively, therefore, requires knowing what typemaps are available +and what they do. + +A `SWIG`_ interface file that includes the `SWIG`_ directives given +above will produce wrapper code that looks something like:: + + 1 PyObject *_wrap_rms(PyObject *args) { + 2 PyObject *resultobj = 0; + 3 double *arg1 = (double *) 0 ; + 4 int arg2 ; + 5 double result; + 6 PyArrayObject *array1 = NULL ; + 7 int is_new_object1 = 0 ; + 8 PyObject * obj0 = 0 ; + 9 + 10 if (!PyArg_ParseTuple(args,(char *)"O:rms",&obj0)) SWIG_fail; + 11 { + 12 array1 = obj_to_array_contiguous_allow_conversion( + 13 obj0, NPY_DOUBLE, &is_new_object1); + 14 npy_intp size[1] = { + 15 -1 + 16 }; + 17 if (!array1 || !require_dimensions(array1, 1) || + 18 !require_size(array1, size, 1)) SWIG_fail; + 19 arg1 = (double*) array1->data; + 20 arg2 = (int) array1->dimensions[0]; + 21 } + 22 result = (double)rms(arg1,arg2); + 23 resultobj = SWIG_From_double((double)(result)); + 24 { + 25 if (is_new_object1 && array1) Py_DECREF(array1); + 26 } + 27 return resultobj; + 28 fail: + 29 { + 30 if (is_new_object1 && array1) Py_DECREF(array1); + 31 } + 32 return NULL; + 33 } + +The typemaps from ``numpy.i`` are responsible for the following lines +of code: 12--20, 25 and 30. Line 10 parses the input to the ``rms`` +function. From the format string ``"O:rms"``, we can see that the +argument list is expected to be a single `python`_ object (specified +by the ``O`` before the colon) and whose pointer is stored in +``obj0``. A number of functions, supplied by ``numpy.i``, are called +to make and check the (possible) conversion from a generic `python`_ +object to a `NumPy`_ array. These functions are explained in the +section `Helper Functions`_, but hopefully their names are +self-explanatory. At line 12 we use ``obj0`` to construct a `NumPy`_ +array. At line 17, we check the validity of the result: that it is +non-null and that it has a single dimension of arbitrary length. Once +these states are verified, we extract the data buffer and length in +lines 19 and 20 so that we can call the underlying C function at line +22. Line 25 performs memory management for the case where we have +created a new array that is no longer needed. + +This code has a significant amount of error handling. Note the +``SWIG_fail`` is a macro for ``goto fail``, refering to the label at +line 28. If the user provides the wrong number of arguments, this +will be caught at line 10. If construction of the `NumPy`_ array +fails or produces an array with the wrong number of dimensions, these +errors are caught at line 17. And finally, if an error is detected, +memory is still managed correctly at line 30. + +Note that if the C function signature was in a different order:: + + double rms(int n, double* seq); + +that `SWIG`_ would not match the typemap signature given above with +the argument list for ``rms``. Fortunately, ``numpy.i`` has a set of +typemaps with the data pointer given last:: + + %apply (int DIM1, double* IN_ARRAY1) {(int n, double* seq)}; + +This simply has the effect of switching the definitions of ``arg1`` +and ``arg2`` in lines 3 and 4 of the generated code above, and their +assignments in lines 19 and 20. + +Using numpy.i +============= + +The ``numpy.i`` file is currently located in the ``numpy/docs/swig`` +sub-directory under the ``numpy`` installation directory. Typically, +you will want to copy it to the directory where you are developing +your wrappers. If it is ever adopted by `SWIG`_ developers, then it +will be installed in a standard place where `SWIG`_ can find it. + +A simple module that only uses a single `SWIG`_ interface file should +include the following:: + + %{ + #define SWIG_FILE_WITH_INIT + %} + %include "numpy.i" + %init %{ + import_array(); + %} + +Within a compiled `python`_ module, ``import_array()`` should only get +called once. This could be in a C/C++ file that you have written and +is linked to the module. If this is the case, then none of your +interface files should ``#define SWIG_FILE_WITH_INIT`` or call +``import_array()``. Or, this initialization call could be in a +wrapper file generated by `SWIG`_ from an interface file that has the +``%init`` block as above. If this is the case, and you have more than +one `SWIG`_ interface file, then only one interface file should +``#define SWIG_FILE_WITH_INIT`` and call ``import_array()``. + +Available Typemaps +================== + +The typemap directives provided by ``numpy.i`` for arrays of different +data types, say ``double`` and ``int``, and dimensions of different +types, say ``int`` or ``long``, are identical to one another except +for the C and `NumPy`_ type specifications. The typemaps are +therefore implemented (typically behind the scenes) via a macro:: + + %numpy_typemaps(DATA_TYPE, DATA_TYPECODE, DIM_TYPE) + +that can be invoked for appropriate ``(DATA_TYPE, DATA_TYPECODE, +DIM_TYPE)`` triplets. For example:: + + %numpy_typemaps(double, NPY_DOUBLE, int) + %numpy_typemaps(int, NPY_INT , int) + +The ``numpy.i`` interface file uses the ``%numpy_typemaps`` macro to +implement typemaps for the following C data types and ``int`` +dimension types: + + * ``signed char`` + * ``unsigned char`` + * ``short`` + * ``unsigned short`` + * ``int`` + * ``unsigned int`` + * ``long`` + * ``unsigned long`` + * ``long long`` + * ``unsigned long long`` + * ``float`` + * ``double`` + +In the following descriptions, we reference a generic ``DATA_TYPE``, which +could be any of the C data types listed above, and ``DIM_TYPE`` which +should be one of the many types of integers. + +The typemap signatures are largely differentiated on the name given to +the buffer pointer. Names with ``FARRAY`` are for FORTRAN-ordered +arrays, and names with ``ARRAY`` are for C-ordered (or 1D arrays). + +Input Arrays +------------ + +Input arrays are defined as arrays of data that are passed into a +routine but are not altered in-place or returned to the user. The +`python`_ input array is therefore allowed to be almost any `python`_ +sequence (such as a list) that can be converted to the requested type +of array. The input array signatures are + +1D: + + * ``( DATA_TYPE IN_ARRAY1[ANY] )`` + * ``( DATA_TYPE* IN_ARRAY1, int DIM1 )`` + * ``( int DIM1, DATA_TYPE* IN_ARRAY1 )`` + +2D: + + * ``( DATA_TYPE IN_ARRAY2[ANY][ANY] )`` + * ``( DATA_TYPE* IN_ARRAY2, int DIM1, int DIM2 )`` + * ``( int DIM1, int DIM2, DATA_TYPE* IN_ARRAY2 )`` + * ``( DATA_TYPE* IN_FARRAY2, int DIM1, int DIM2 )`` + * ``( int DIM1, int DIM2, DATA_TYPE* IN_FARRAY2 )`` + +3D: + + * ``( DATA_TYPE IN_ARRAY3[ANY][ANY][ANY] )`` + * ``( DATA_TYPE* IN_ARRAY3, int DIM1, int DIM2, int DIM3 )`` + * ``( int DIM1, int DIM2, int DIM3, DATA_TYPE* IN_ARRAY3 )`` + * ``( DATA_TYPE* IN_FARRAY3, int DIM1, int DIM2, int DIM3 )`` + * ``( int DIM1, int DIM2, int DIM3, DATA_TYPE* IN_FARRAY3 )`` + +The first signature listed, ``( DATA_TYPE IN_ARRAY[ANY] )`` is for +one-dimensional arrays with hard-coded dimensions. Likewise, +``( DATA_TYPE IN_ARRAY2[ANY][ANY] )`` is for two-dimensional arrays +with hard-coded dimensions, and similarly for three-dimensional. + +In-Place Arrays +--------------- + +In-place arrays are defined as arrays that are modified in-place. The +input values may or may not be used, but the values at the time the +function returns are significant. The provided `python`_ argument +must therefore be a `NumPy`_ array of the required type. The in-place +signatures are + +1D: + + * ``( DATA_TYPE INPLACE_ARRAY1[ANY] )`` + * ``( DATA_TYPE* INPLACE_ARRAY1, int DIM1 )`` + * ``( int DIM1, DATA_TYPE* INPLACE_ARRAY1 )`` + +2D: + + * ``( DATA_TYPE INPLACE_ARRAY2[ANY][ANY] )`` + * ``( DATA_TYPE* INPLACE_ARRAY2, int DIM1, int DIM2 )`` + * ``( int DIM1, int DIM2, DATA_TYPE* INPLACE_ARRAY2 )`` + * ``( DATA_TYPE* INPLACE_FARRAY2, int DIM1, int DIM2 )`` + * ``( int DIM1, int DIM2, DATA_TYPE* INPLACE_FARRAY2 )`` + +3D: + + * ``( DATA_TYPE INPLACE_ARRAY3[ANY][ANY][ANY] )`` + * ``( DATA_TYPE* INPLACE_ARRAY3, int DIM1, int DIM2, int DIM3 )`` + * ``( int DIM1, int DIM2, int DIM3, DATA_TYPE* INPLACE_ARRAY3 )`` + * ``( DATA_TYPE* INPLACE_FARRAY3, int DIM1, int DIM2, int DIM3 )`` + * ``( int DIM1, int DIM2, int DIM3, DATA_TYPE* INPLACE_FARRAY3 )`` + +These typemaps now check to make sure that the ``INPLACE_ARRAY`` +arguments use native byte ordering. If not, an exception is raised. + +Argout Arrays +------------- + +Argout arrays are arrays that appear in the input arguments in C, but +are in fact output arrays. This pattern occurs often when there is +more than one output variable and the single return argument is +therefore not sufficient. In `python`_, the convential way to return +multiple arguments is to pack them into a sequence (tuple, list, etc.) +and return the sequence. This is what the argout typemaps do. If a +wrapped function that uses these argout typemaps has more than one +return argument, they are packed into a tuple or list, depending on +the version of `python`_. The `python`_ user does not pass these +arrays in, they simply get returned. For the case where a dimension +is specified, the python user must provide that dimension as an +argument. The argout signatures are + +1D: + + * ``( DATA_TYPE ARGOUT_ARRAY1[ANY] )`` + * ``( DATA_TYPE* ARGOUT_ARRAY1, int DIM1 )`` + * ``( int DIM1, DATA_TYPE* ARGOUT_ARRAY1 )`` + +2D: + + * ``( DATA_TYPE ARGOUT_ARRAY2[ANY][ANY] )`` + +3D: + + * ``( DATA_TYPE ARGOUT_ARRAY3[ANY][ANY][ANY] )`` + +These are typically used in situations where in C/C++, you would +allocate a(n) array(s) on the heap, and call the function to fill the +array(s) values. In `python`_, the arrays are allocated for you and +returned as new array objects. + +Note that we support ``DATA_TYPE*`` argout typemaps in 1D, but not 2D +or 3D. This is because of a quirk with the `SWIG`_ typemap syntax and +cannot be avoided. Note that for these types of 1D typemaps, the +`python`_ function will take a single argument representing ``DIM1``. + +Argoutview Arrays +----------------- + +Argoutview arrays are for when your C code provides you with a view of +its internal data and does not require any memory to be allocated by +the user. This can be dangerous. There is almost no way to guarantee +that the internal data from the C code will remain in existence for +the entire lifetime of the `NumPy`_ array that encapsulates it. If +the user destroys the object that provides the view of the data before +destroying the `NumPy`_ array, then using that array my result in bad +memory references or segmentation faults. Nevertheless, there are +situations, working with large data sets, where you simply have no +other choice. + +The C code to be wrapped for argoutview arrays are characterized by +pointers: pointers to the dimensions and double pointers to the data, +so that these values can be passed back to the user. The argoutview +typemap signatures are therefore + +1D: + + * ``( DATA_TYPE** ARGOUTVIEW_ARRAY1, DIM_TYPE* DIM1 )`` + * ``( DIM_TYPE* DIM1, DATA_TYPE** ARGOUTVIEW_ARRAY1 )`` + +2D: + + * ``( DATA_TYPE** ARGOUTVIEW_ARRAY2, DIM_TYPE* DIM1, DIM_TYPE* DIM2 )`` + * ``( DIM_TYPE* DIM1, DIM_TYPE* DIM2, DATA_TYPE** ARGOUTVIEW_ARRAY2 )`` + * ``( DATA_TYPE** ARGOUTVIEW_FARRAY2, DIM_TYPE* DIM1, DIM_TYPE* DIM2 )`` + * ``( DIM_TYPE* DIM1, DIM_TYPE* DIM2, DATA_TYPE** ARGOUTVIEW_FARRAY2 )`` + +3D: + + * ``( DATA_TYPE** ARGOUTVIEW_ARRAY3, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3)`` + * ``( DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DATA_TYPE** ARGOUTVIEW_ARRAY3)`` + * ``( DATA_TYPE** ARGOUTVIEW_FARRAY3, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3)`` + * ``( DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DATA_TYPE** ARGOUTVIEW_FARRAY3)`` + +Note that arrays with hard-coded dimensions are not supported. These +cannot follow the double pointer signatures of these typemaps. + +Output Arrays +------------- + +The ``numpy.i`` interface file does not support typemaps for output +arrays, for several reasons. First, C/C++ return arguments are +limited to a single value. This prevents obtaining dimension +information in a general way. Second, arrays with hard-coded lengths +are not permitted as return arguments. In other words:: + + double[3] newVector(double x, double y, double z); + +is not legal C/C++ syntax. Therefore, we cannot provide typemaps of +the form:: + + %typemap(out) (TYPE[ANY]); + +If you run into a situation where a function or method is returning a +pointer to an array, your best bet is to write your own version of the +function to be wrapped, either with ``%extend`` for the case of class +methods or ``%ignore`` and ``%rename`` for the case of functions. + +Other Common Types: bool +------------------------ + +Note that C++ type ``bool`` is not supported in the list in the +`Available Typemaps`_ section. NumPy bools are a single byte, while +the C++ ``bool`` is four bytes (at least on my system). Therefore:: + + %numpy_typemaps(bool, NPY_BOOL, int) + +will result in typemaps that will produce code that reference +improper data lengths. You can implement the following macro +expansion:: + + %numpy_typemaps(bool, NPY_UINT, int) + +to fix the data length problem, and `Input Arrays`_ will work fine, +but `In-Place Arrays`_ might fail type-checking. + +Other Common Types: complex +--------------------------- + +Typemap conversions for complex floating-point types is also not +supported automatically. This is because `python`_ and `NumPy`_ are +written in C, which does not have native complex types. Both +`python`_ and `NumPy`_ implement their own (essentially equivalent) +``struct`` definitions for complex variables:: + + /* Python */ + typedef struct {double real; double imag;} Py_complex; + + /* NumPy */ + typedef struct {float real, imag;} npy_cfloat; + typedef struct {double real, imag;} npy_cdouble; + +We could have implemented:: + + %numpy_typemaps(Py_complex , NPY_CDOUBLE, int) + %numpy_typemaps(npy_cfloat , NPY_CFLOAT , int) + %numpy_typemaps(npy_cdouble, NPY_CDOUBLE, int) + +which would have provided automatic type conversions for arrays of +type ``Py_complex``, ``npy_cfloat`` and ``npy_cdouble``. However, it +seemed unlikely that there would be any independent (non-`python`_, +non-`NumPy`_) application code that people would be using `SWIG`_ to +generate a `python`_ interface to, that also used these definitions +for complex types. More likely, these application codes will define +their own complex types, or in the case of C++, use ``std::complex``. +Assuming these data structures are compatible with `python`_ and +`NumPy`_ complex types, ``%numpy_typemap`` expansions as above (with +the user's complex type substituted for the first argument) should +work. + +NumPy Array Scalars and SWIG +============================ + +`SWIG`_ has sophisticated type checking for numerical types. For +example, if your C/C++ routine expects an integer as input, the code +generated by `SWIG`_ will check for both `python`_ integers and +`python`_ long integers, and raise an overflow error if the provided +`python`_ integer is too big to cast down to a C integer. With the +introduction of `NumPy`_ scalar arrays into your `python`_ code, you +might conceivably extract an integer from a `NumPy`_ array and attempt +to pass this to a `SWIG`_-wrapped C/C++ function that expects an +``int``, but the `SWIG`_ type checking will not recognize the `NumPy`_ +array scalar as an integer. (Often, this does in fact work -- it +depends on whether `NumPy`_ recognizes the integer type you are using +as inheriting from the `python`_ integer type on the platform you are +using. Sometimes, this means that code that works on a 32-bit machine +will fail on a 64-bit machine.) + +If you get a `python`_ error that looks like the following:: + + TypeError: in method 'MyClass_MyMethod', argument 2 of type 'int' + +and the argument you are passing is an integer extracted from a +`NumPy`_ array, then you have stumbled upon this problem. The +solution is to modify the `SWIG`_ type conversion system to accept +`Numpy`_ array scalars in addition to the standard integer types. +Fortunately, this capabilitiy has been provided for you. Simply copy +the file:: + + pyfragments.swg + +to the working build directory for you project, and this problem will +be fixed. It is suggested that you do this anyway, as it only +increases the capabilities of your `python`_ interface. + +Why is There a Second File? +--------------------------- + +The `SWIG`_ type checking and conversion system is a complicated +combination of C macros, `SWIG`_ macros, `SWIG`_ typemaps and `SWIG`_ +fragments. Fragments are a way to conditionally insert code into your +wrapper file if it is needed, and not insert it if not needed. If +multiple typemaps require the same fragment, the fragment only gets +inserted into your wrapper code once. + +There is a fragment for converting a `python`_ integer to a C +``long``. There is a different fragment that converts a `python`_ +integer to a C ``int``, that calls the rountine defined in the +``long`` fragment. We can make the changes we want here by changing +the definition for the ``long`` fragment. `SWIG`_ determines the +active definition for a fragment using a "first come, first served" +system. That is, we need to define the fragment for ``long`` +conversions prior to `SWIG`_ doing it internally. `SWIG`_ allows us +to do this by putting our fragment definitions in the file +``pyfragments.swg``. If we were to put the new fragment definitions +in ``numpy.i``, they would be ignored. + +Helper Functions +================ + +The ``numpy.i`` file containes several macros and routines that it +uses internally to build its typemaps. However, these functions may +be useful elsewhere in your interface file. These macros and routines +are implemented as fragments, which are described briefly in the +previous section. If you try to use one or more of the following +macros or functions, but your compiler complains that it does not +recognize the symbol, then you need to force these fragments to appear +in your code using:: + + %fragment("NumPy_Fragments"); + +in your `SWIG`_ interface file. + +Macros +------ + + **is_array(a)** + Evaluates as true if ``a`` is non-``NULL`` and can be cast to a + ``PyArrayObject*``. + + **array_type(a)** + Evaluates to the integer data type code of ``a``, assuming ``a`` can + be cast to a ``PyArrayObject*``. + + **array_numdims(a)** + Evaluates to the integer number of dimensions of ``a``, assuming + ``a`` can be cast to a ``PyArrayObject*``. + + **array_dimensions(a)** + Evaluates to an array of type ``npy_intp`` and length + ``array_numdims(a)``, giving the lengths of all of the dimensions + of ``a``, assuming ``a`` can be cast to a ``PyArrayObject*``. + + **array_size(a,i)** + Evaluates to the ``i``-th dimension size of ``a``, assuming ``a`` + can be cast to a ``PyArrayObject*``. + + **array_data(a)** + Evaluates to a pointer of type ``void*`` that points to the data + buffer of ``a``, assuming ``a`` can be cast to a ``PyArrayObject*``. + + **array_is_contiguous(a)** + Evaluates as true if ``a`` is a contiguous array. Equivalent to + ``(PyArray_ISCONTIGUOUS(a))``. + + **array_is_native(a)** + Evaluates as true if the data buffer of ``a`` uses native byte + order. Equivalent to ``(PyArray_ISNOTSWAPPED(a))``. + + **array_is_fortran(a)** + Evaluates as true if ``a`` is FORTRAN ordered. + +Routines +-------- + + **pytype_string()** + + Return type: ``char*`` + + Arguments: + + * ``PyObject* py_obj``, a general `python`_ object. + + Return a string describing the type of ``py_obj``. + + + **typecode_string()** + + Return type: ``char*`` + + Arguments: + + * ``int typecode``, a `NumPy`_ integer typecode. + + Return a string describing the type corresponding to the `NumPy`_ + ``typecode``. + + **type_match()** + + Return type: ``int`` + + Arguments: + + * ``int actual_type``, the `NumPy`_ typecode of a `NumPy`_ array. + + * ``int desired_type``, the desired `NumPy`_ typecode. + + Make sure that ``actual_type`` is compatible with + ``desired_type``. For example, this allows character and + byte types, or int and long types, to match. This is now + equivalent to ``PyArray_EquivTypenums()``. + + + **obj_to_array_no_conversion()** + + Return type: ``PyArrayObject*`` + + Arguments: + + * ``PyObject* input``, a general `python`_ object. + + * ``int typecode``, the desired `NumPy`_ typecode. + + Cast ``input`` to a ``PyArrayObject*`` if legal, and ensure that + it is of type ``typecode``. If ``input`` cannot be cast, or the + ``typecode`` is wrong, set a `python`_ error and return ``NULL``. + + + **obj_to_array_allow_conversion()** + + Return type: ``PyArrayObject*`` + + Arguments: + + * ``PyObject* input``, a general `python`_ object. + + * ``int typecode``, the desired `NumPy`_ typecode of the resulting + array. + + * ``int* is_new_object``, returns a value of 0 if no conversion + performed, else 1. + + Convert ``input`` to a `NumPy`_ array with the given ``typecode``. + On success, return a valid ``PyArrayObject*`` with the correct + type. On failure, the `python`_ error string will be set and the + routine returns ``NULL``. + + + **make_contiguous()** + + Return type: ``PyArrayObject*`` + + Arguments: + + * ``PyArrayObject* ary``, a `NumPy`_ array. + + * ``int* is_new_object``, returns a value of 0 if no conversion + performed, else 1. + + * ``int min_dims``, minimum allowable dimensions. + + * ``int max_dims``, maximum allowable dimensions. + + Check to see if ``ary`` is contiguous. If so, return the input + pointer and flag it as not a new object. If it is not contiguous, + create a new ``PyArrayObject*`` using the original data, flag it + as a new object and return the pointer. + + + **obj_to_array_contiguous_allow_conversion()** + + Return type: ``PyArrayObject*`` + + Arguments: + + * ``PyObject* input``, a general `python`_ object. + + * ``int typecode``, the desired `NumPy`_ typecode of the resulting + array. + + * ``int* is_new_object``, returns a value of 0 if no conversion + performed, else 1. + + Convert ``input`` to a contiguous ``PyArrayObject*`` of the + specified type. If the input object is not a contiguous + ``PyArrayObject*``, a new one will be created and the new object + flag will be set. + + + **require_contiguous()** + + Return type: ``int`` + + Arguments: + + * ``PyArrayObject* ary``, a `NumPy`_ array. + + Test whether ``ary`` is contiguous. If so, return 1. Otherwise, + set a `python`_ error and return 0. + + + **require_native()** + + Return type: ``int`` + + Arguments: + + * ``PyArray_Object* ary``, a `NumPy`_ array. + + Require that ``ary`` is not byte-swapped. If the array is not + byte-swapped, return 1. Otherwise, set a `python`_ error and + return 0. + + **require_dimensions()** + + Return type: ``int`` + + Arguments: + + * ``PyArrayObject* ary``, a `NumPy`_ array. + + * ``int exact_dimensions``, the desired number of dimensions. + + Require ``ary`` to have a specified number of dimensions. If the + array has the specified number of dimensions, return 1. + Otherwise, set a `python`_ error and return 0. + + + **require_dimensions_n()** + + Return type: ``int`` + + Arguments: + + * ``PyArrayObject* ary``, a `NumPy`_ array. + + * ``int* exact_dimensions``, an array of integers representing + acceptable numbers of dimensions. + + * ``int n``, the length of ``exact_dimensions``. + + Require ``ary`` to have one of a list of specified number of + dimensions. If the array has one of the specified number of + dimensions, return 1. Otherwise, set the `python`_ error string + and return 0. + + + **require_size()** + + Return type: ``int`` + + Arguments: + + * ``PyArrayObject* ary``, a `NumPy`_ array. + + * ``npy_int* size``, an array representing the desired lengths of + each dimension. + + * ``int n``, the length of ``size``. + + Require ``ary`` to have a specified shape. If the array has the + specified shape, return 1. Otherwise, set the `python`_ error + string and return 0. + + + **require_fortran()** + + Return type: ``int`` + + Arguments: + + * ``PyArrayObject* ary``, a `NumPy`_ array. + + Require the given ``PyArrayObject`` to to be FORTRAN ordered. If + the the ``PyArrayObject`` is already FORTRAN ordered, do nothing. + Else, set the FORTRAN ordering flag and recompute the strides. + + +Beyond the Provided Typemaps +============================ + +There are many C or C++ array/`NumPy`_ array situations not covered by +a simple ``%include "numpy.i"`` and subsequent ``%apply`` directives. + +A Common Example +---------------- + +Consider a reasonable prototype for a dot product function:: + + double dot(int len, double* vec1, double* vec2); + +The `python`_ interface that we want is:: + + def dot(vec1, vec2): + """ + dot(PyObject,PyObject) -> double + """ + +The problem here is that there is one dimension argument and two array +arguments, and our typemaps are set up for dimensions that apply to a +single array (in fact, `SWIG`_ does not provide a mechanism for +associating ``len`` with ``vec2`` that takes two `python`_ input +arguments). The recommended solution is the following:: + + %apply (int DIM1, double* IN_ARRAY1) {(int len1, double* vec1), + (int len2, double* vec2)} + %rename (dot) my_dot; + %exception my_dot { + $action + if (PyErr_Occurred()) SWIG_fail; + } + %inline %{ + double my_dot(int len1, double* vec1, int len2, double* vec2) { + if (len1 != len2) { + PyErr_Format(PyExc_ValueError, + "Arrays of lengths (%d,%d) given", + len1, len2); + return 0.0; + } + return dot(len1, vec1, vec2); + } + %} + +If the header file that contains the prototype for ``double dot()`` +also contains other prototypes that you want to wrap, so that you need +to ``%include`` this header file, then you will also need a ``%ignore +dot;`` directive, placed after the ``%rename`` and before the +``%include`` directives. Or, if the function in question is a class +method, you will want to use ``%extend`` rather than ``%inline`` in +addition to ``%ignore``. + +**A note on error handling:** Note that ``my_dot`` returns a +``double`` but that it can also raise a `python`_ error. The +resulting wrapper function will return a `python`_ float +representation of 0.0 when the vector lengths do not match. Since +this is not ``NULL``, the `python`_ interpreter will not know to check +for an error. For this reason, we add the ``%exception`` directive +above for ``my_dot`` to get the behavior we want (note that +``$action`` is a macro that gets expanded to a valid call to +``my_dot``). In general, you will probably want to write a `SWIG`_ +macro to perform this task. + +Other Situations +---------------- + +There are other wrapping situations in which ``numpy.i`` may be +helpful when you encounter them. + + * In some situations, it is possible that you could use the + ``%numpy_templates`` macro to implement typemaps for your own + types. See the `Other Common Types: bool`_ or `Other Common + Types: complex`_ sections for examples. Another situation is if + your dimensions are of a type other than ``int`` (say ``long`` for + example):: + + %numpy_typemaps(double, NPY_DOUBLE, long) + + * You can use the code in ``numpy.i`` to write your own typemaps. + For example, if you had a four-dimensional array as a function + argument, you could cut-and-paste the appropriate + three-dimensional typemaps into your interface file. The + modifications for the fourth dimension would be trivial. + + * Sometimes, the best approach is to use the ``%extend`` directive + to define new methods for your classes (or overload existing ones) + that take a ``PyObject*`` (that either is or can be converted to a + ``PyArrayObject*``) instead of a pointer to a buffer. In this + case, the helper routines in ``numpy.i`` can be very useful. + + * Writing typemaps can be a bit nonintuitive. If you have specific + questions about writing `SWIG`_ typemaps for `NumPy`_, the + developers of ``numpy.i`` do monitor the + `Numpy-discussion <mailto:Numpy-discussion@scipy.org>`_ and + `Swig-user <mailto:Swig-user@lists.sourceforge.net>`_ mail lists. + +A Final Note +------------ + +When you use the ``%apply`` directive, as is usually necessary to use +``numpy.i``, it will remain in effect until you tell `SWIG`_ that it +shouldn't be. If the arguments to the functions or methods that you +are wrapping have common names, such as ``length`` or ``vector``, +these typemaps may get applied in situations you do not expect or +want. Therefore, it is always a good idea to add a ``%clear`` +directive after you are done with a specific typemap:: + + %apply (double* IN_ARRAY1, int DIM1) {(double* vector, int length)} + %include "my_header.h" + %clear (double* vector, int length); + +In general, you should target these typemap signatures specifically +where you want them, and then clear them after you are done. + +Summary +======= + +Out of the box, ``numpy.i`` provides typemaps that support conversion +between `NumPy`_ arrays and C arrays: + + * That can be one of 12 different scalar types: ``signed char``, + ``unsigned char``, ``short``, ``unsigned short``, ``int``, + ``unsigned int``, ``long``, ``unsigned long``, ``long long``, + ``unsigned long long``, ``float`` and ``double``. + + * That support 41 different argument signatures for each data type, + including: + + + One-dimensional, two-dimensional and three-dimensional arrays. + + + Input-only, in-place, argout and argoutview behavior. + + + Hard-coded dimensions, data-buffer-then-dimensions + specification, and dimensions-then-data-buffer specification. + + + Both C-ordering ("last dimension fastest") or FORTRAN-ordering + ("first dimension fastest") support for 2D and 3D arrays. + +The ``numpy.i`` interface file also provides additional tools for +wrapper developers, including: + + * A `SWIG`_ macro (``%numpy_typemaps``) with three arguments for + implementing the 41 argument signatures for the user's choice of + (1) C data type, (2) `NumPy`_ data type (assuming they match), and + (3) dimension type. + + * Nine C macros and 13 C functions that can be used to write + specialized typemaps, extensions, or inlined functions that handle + cases not covered by the provided typemaps. + +Acknowledgements +================ + +Many people have worked to glue `SWIG`_ and `NumPy`_ together (as well +as `SWIG`_ and the predecessors of `NumPy`_, Numeric and numarray). +The effort to standardize this work into ``numpy.i`` began at the 2005 +`SciPy <http://scipy.org>`_ Conference with a conversation between +Fernando Perez and myself. Fernando collected helper functions and +typemaps from Eric Jones, Michael Hunter, Anna Omelchenko and Michael +Sanner. Sebastian Hasse and Georg Holzmann have also provided +additional error checking and use cases. The work of these +contributors has made this end result possible. diff --git a/doc/swig/doc/testing.html b/doc/swig/doc/testing.html new file mode 100644 index 000000000..3622550df --- /dev/null +++ b/doc/swig/doc/testing.html @@ -0,0 +1,482 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> +<title>Testing the numpy.i Typemaps</title> +<meta name="author" content="Bill Spotz" /> +<meta name="date" content="6 April, 2007" /> +<style type="text/css"> + +/* +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $ +:Revision: $Revision: 4224 $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin-left: 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left { + clear: left } + +img.align-right { + clear: right } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font-family: serif ; + font-size: 100% } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em ; + background-color: #eeeeee } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +tt.docutils { + background-color: #eeeeee } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="testing-the-numpy-i-typemaps"> +<h1 class="title">Testing the numpy.i Typemaps</h1> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Author:</th> +<td>Bill Spotz</td></tr> +<tr class="field"><th class="docinfo-name">Institution:</th><td class="field-body">Sandia National Laboratories</td> +</tr> +<tr><th class="docinfo-name">Date:</th> +<td>6 April, 2007</td></tr> +</tbody> +</table> +<div class="contents topic"> +<p class="topic-title first"><a id="contents" name="contents">Contents</a></p> +<ul class="simple"> +<li><a class="reference" href="#introduction" id="id1" name="id1">Introduction</a></li> +<li><a class="reference" href="#testing-organization" id="id2" name="id2">Testing Organization</a></li> +<li><a class="reference" href="#testing-header-files" id="id3" name="id3">Testing Header Files</a></li> +<li><a class="reference" href="#testing-source-files" id="id4" name="id4">Testing Source Files</a></li> +<li><a class="reference" href="#testing-swig-interface-files" id="id5" name="id5">Testing SWIG Interface Files</a></li> +<li><a class="reference" href="#testing-python-scripts" id="id6" name="id6">Testing Python Scripts</a></li> +</ul> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id1" id="introduction" name="introduction">Introduction</a></h1> +<p>Writing tests for the <tt class="docutils literal"><span class="pre">numpy.i</span></tt> <a class="reference" href="http://www.swig.org">SWIG</a> +interface file is a combinatorial headache. At present, 12 different +data types are supported, each with 23 different argument signatures, +for a total of 276 typemaps supported "out of the box". Each of these +typemaps, in turn, might require several unit tests in order to verify +expected behavior for both proper and improper inputs. Currently, +this results in 1,020 individual unit tests that are performed when +<tt class="docutils literal"><span class="pre">make</span> <span class="pre">test</span></tt> is run in the <tt class="docutils literal"><span class="pre">numpy/docs/swig</span></tt> subdirectory.</p> +<p>To facilitate this many similar unit tests, some high-level +programming techniques are employed, including C and <a class="reference" href="http://www.swig.org">SWIG</a> macros, +as well as <a class="reference" href="http://www.python.org">python</a> inheritance. The +purpose of this document is to describe the testing infrastructure +employed to verify that the <tt class="docutils literal"><span class="pre">numpy.i</span></tt> typemaps are working as +expected.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id2" id="testing-organization" name="testing-organization">Testing Organization</a></h1> +<p>There are three indepedent testing frameworks supported, for one-, +two-, and three-dimensional arrays respectively. For one-dimensional +arrays, there are two C++ files, a header and a source, named:</p> +<pre class="literal-block"> +Vector.h +Vector.cxx +</pre> +<p>that contain prototypes and code for a variety of functions that have +one-dimensional arrays as function arguments. The file:</p> +<pre class="literal-block"> +Vector.i +</pre> +<p>is a <a class="reference" href="http://www.swig.org">SWIG</a> interface file that defines a python module <tt class="docutils literal"><span class="pre">Vector</span></tt> +that wraps the functions in <tt class="docutils literal"><span class="pre">Vector.h</span></tt> while utilizing the typemaps +in <tt class="docutils literal"><span class="pre">numpy.i</span></tt> to correctly handle the C arrays.</p> +<p>The <tt class="docutils literal"><span class="pre">Makefile</span></tt> calls <tt class="docutils literal"><span class="pre">swig</span></tt> to generate <tt class="docutils literal"><span class="pre">Vector.py</span></tt> and +<tt class="docutils literal"><span class="pre">Vector_wrap.cxx</span></tt>, and also executes the <tt class="docutils literal"><span class="pre">setup.py</span></tt> script that +compiles <tt class="docutils literal"><span class="pre">Vector_wrap.cxx</span></tt> and links together the extension module +<tt class="docutils literal"><span class="pre">_Vector.so</span></tt> or <tt class="docutils literal"><span class="pre">_Vector.dylib</span></tt>, depending on the platform. This +extension module and the proxy file <tt class="docutils literal"><span class="pre">Vector.py</span></tt> are both placed in a +subdirectory under the <tt class="docutils literal"><span class="pre">build</span></tt> directory.</p> +<p>The actual testing takes place with a <a class="reference" href="http://www.python.org">python</a> script named:</p> +<pre class="literal-block"> +testVector.py +</pre> +<p>that uses the standard <a class="reference" href="http://www.python.org">python</a> library module <tt class="docutils literal"><span class="pre">unittest</span></tt>, which +performs several tests of each function defined in <tt class="docutils literal"><span class="pre">Vector.h</span></tt> for +each data type supported.</p> +<p>Two-dimensional arrays are tested in exactly the same manner. The +above description applies, but with <tt class="docutils literal"><span class="pre">Matrix</span></tt> substituted for +<tt class="docutils literal"><span class="pre">Vector</span></tt>. For three-dimensional tests, substitute <tt class="docutils literal"><span class="pre">Tensor</span></tt> for +<tt class="docutils literal"><span class="pre">Vector</span></tt>. For the descriptions that follow, we will reference the +<tt class="docutils literal"><span class="pre">Vector</span></tt> tests, but the same information applies to <tt class="docutils literal"><span class="pre">Matrix</span></tt> and +<tt class="docutils literal"><span class="pre">Tensor</span></tt> tests.</p> +<p>The command <tt class="docutils literal"><span class="pre">make</span> <span class="pre">test</span></tt> will ensure that all of the test software is +built and then run all three test scripts.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id3" id="testing-header-files" name="testing-header-files">Testing Header Files</a></h1> +<p><tt class="docutils literal"><span class="pre">Vector.h</span></tt> is a C++ header file that defines a C macro called +<tt class="docutils literal"><span class="pre">TEST_FUNC_PROTOS</span></tt> that takes two arguments: <tt class="docutils literal"><span class="pre">TYPE</span></tt>, which is a +data type name such as <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt>; and <tt class="docutils literal"><span class="pre">SNAME</span></tt>, which is a +short name for the same data type with no spaces, e.g. <tt class="docutils literal"><span class="pre">uint</span></tt>. This +macro defines several function prototypes that have the prefix +<tt class="docutils literal"><span class="pre">SNAME</span></tt> and have at least one argument that is an array of type +<tt class="docutils literal"><span class="pre">TYPE</span></tt>. Those functions that have return arguments return a +<tt class="docutils literal"><span class="pre">TYPE</span></tt> value.</p> +<p><tt class="docutils literal"><span class="pre">TEST_FUNC_PROTOS</span></tt> is then implemented for all of the data types +supported by <tt class="docutils literal"><span class="pre">numpy.i</span></tt>:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">signed</span> <span class="pre">char</span></tt></li> +<li><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span></tt></li> +<li><tt class="docutils literal"><span class="pre">short</span></tt></li> +<li><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt></li> +<li><tt class="docutils literal"><span class="pre">int</span></tt></li> +<li><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt></li> +<li><tt class="docutils literal"><span class="pre">long</span></tt></li> +<li><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt></li> +<li><tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt></li> +<li><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></tt></li> +<li><tt class="docutils literal"><span class="pre">float</span></tt></li> +<li><tt class="docutils literal"><span class="pre">double</span></tt></li> +</ul> +</blockquote> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id4" id="testing-source-files" name="testing-source-files">Testing Source Files</a></h1> +<p><tt class="docutils literal"><span class="pre">Vector.cxx</span></tt> is a C++ source file that implements compilable code +for each of the function prototypes specified in <tt class="docutils literal"><span class="pre">Vector.h</span></tt>. It +defines a C macro <tt class="docutils literal"><span class="pre">TEST_FUNCS</span></tt> that has the same arguments and works +in the same way as <tt class="docutils literal"><span class="pre">TEST_FUNC_PROTOS</span></tt> does in <tt class="docutils literal"><span class="pre">Vector.h</span></tt>. +<tt class="docutils literal"><span class="pre">TEST_FUNCS</span></tt> is implemented for each of the 12 data types as above.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id5" id="testing-swig-interface-files" name="testing-swig-interface-files">Testing SWIG Interface Files</a></h1> +<p><tt class="docutils literal"><span class="pre">Vector.i</span></tt> is a <a class="reference" href="http://www.swig.org">SWIG</a> interface file that defines python module +<tt class="docutils literal"><span class="pre">Vector</span></tt>. It follows the conventions for using <tt class="docutils literal"><span class="pre">numpy.i</span></tt> as +described in the <a class="reference" href="numpy_swig.html">numpy.i documentation</a>. It +defines a <a class="reference" href="http://www.swig.org">SWIG</a> macro <tt class="docutils literal"><span class="pre">%apply_numpy_typemaps</span></tt> that has a single +argument <tt class="docutils literal"><span class="pre">TYPE</span></tt>. It uses the <a class="reference" href="http://www.swig.org">SWIG</a> directive <tt class="docutils literal"><span class="pre">%apply</span></tt> as +described in the <a class="reference" href="numpy_swig.html">numpy.i documentation</a> to apply the provided +typemaps to the argument signatures found in <tt class="docutils literal"><span class="pre">Vector.h</span></tt>. This macro +is then implemented for all of the data types supported by +<tt class="docutils literal"><span class="pre">numpy.i</span></tt>. It then does a <tt class="docutils literal"><span class="pre">%include</span> <span class="pre">"Vector.h"</span></tt> to wrap all of +the function prototypes in <tt class="docutils literal"><span class="pre">Vector.h</span></tt> using the typemaps in +<tt class="docutils literal"><span class="pre">numpy.i</span></tt>.</p> +</div> +<div class="section"> +<h1><a class="toc-backref" href="#id6" id="testing-python-scripts" name="testing-python-scripts">Testing Python Scripts</a></h1> +<p>After <tt class="docutils literal"><span class="pre">make</span></tt> is used to build the testing extension modules, +<tt class="docutils literal"><span class="pre">testVector.py</span></tt> can be run to execute the tests. As with other +scripts that use <tt class="docutils literal"><span class="pre">unittest</span></tt> to facilitate unit testing, +<tt class="docutils literal"><span class="pre">testVector.py</span></tt> defines a class that inherits from +<tt class="docutils literal"><span class="pre">unittest.TestCase</span></tt>:</p> +<pre class="literal-block"> +class VectorTestCase(unittest.TestCase): +</pre> +<p>However, this class is not run directly. Rather, it serves as a base +class to several other python classes, each one specific to a +particular data type. The <tt class="docutils literal"><span class="pre">VectorTestCase</span></tt> class stores two strings +for typing information:</p> +<blockquote> +<dl class="docutils"> +<dt><strong>self.typeStr</strong></dt> +<dd>A string that matches one of the <tt class="docutils literal"><span class="pre">SNAME</span></tt> prefixes used in +<tt class="docutils literal"><span class="pre">Vector.h</span></tt> and <tt class="docutils literal"><span class="pre">Vector.cxx</span></tt>. For example, <tt class="docutils literal"><span class="pre">"double"</span></tt>.</dd> +<dt><strong>self.typeCode</strong></dt> +<dd>A short (typically single-character) string that represents a +data type in numpy and corresponds to <tt class="docutils literal"><span class="pre">self.typeStr</span></tt>. For +example, if <tt class="docutils literal"><span class="pre">self.typeStr</span></tt> is <tt class="docutils literal"><span class="pre">"double"</span></tt>, then +<tt class="docutils literal"><span class="pre">self.typeCode</span></tt> should be <tt class="docutils literal"><span class="pre">"d"</span></tt>.</dd> +</dl> +</blockquote> +<p>Each test defined by the <tt class="docutils literal"><span class="pre">VectorTestCase</span></tt> class extracts the python +function it is trying to test by accessing the <tt class="docutils literal"><span class="pre">Vector</span></tt> module's +dictionary:</p> +<pre class="literal-block"> +length = Vector.__dict__[self.typeStr + "Length"] +</pre> +<p>In the case of double precision tests, this will return the python +function <tt class="docutils literal"><span class="pre">Vector.doubleLength</span></tt>.</p> +<p>We then define a new test case class for each supported data type with +a short definition such as:</p> +<pre class="literal-block"> +class doubleTestCase(VectorTestCase): + def __init__(self, methodName="runTest"): + VectorTestCase.__init__(self, methodName) + self.typeStr = "double" + self.typeCode = "d" +</pre> +<p>Each of these 12 classes is collected into a <tt class="docutils literal"><span class="pre">unittest.TestSuite</span></tt>, +which is then executed. Errors and failures are summed together and +returned as the exit argument. Any non-zero result indicates that at +least one test did not pass.</p> +</div> +</div> +<div class="footer"> +<hr class="footer" /> +Generated on: 2007-04-06 21:21 UTC. +Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source. + +</div> +</body> +</html> diff --git a/doc/swig/doc/testing.pdf b/doc/swig/doc/testing.pdf Binary files differnew file mode 100644 index 000000000..9ffcf7575 --- /dev/null +++ b/doc/swig/doc/testing.pdf diff --git a/doc/swig/doc/testing.txt b/doc/swig/doc/testing.txt new file mode 100644 index 000000000..bfd5218e8 --- /dev/null +++ b/doc/swig/doc/testing.txt @@ -0,0 +1,173 @@ +============================ +Testing the numpy.i Typemaps +============================ + +:Author: Bill Spotz +:Institution: Sandia National Laboratories +:Date: 6 April, 2007 + +.. contents:: + +Introduction +============ + +Writing tests for the ``numpy.i`` `SWIG <http://www.swig.org>`_ +interface file is a combinatorial headache. At present, 12 different +data types are supported, each with 23 different argument signatures, +for a total of 276 typemaps supported "out of the box". Each of these +typemaps, in turn, might require several unit tests in order to verify +expected behavior for both proper and improper inputs. Currently, +this results in 1,020 individual unit tests that are performed when +``make test`` is run in the ``numpy/docs/swig`` subdirectory. + +To facilitate this many similar unit tests, some high-level +programming techniques are employed, including C and `SWIG`_ macros, +as well as `python <http://www.python.org>`_ inheritance. The +purpose of this document is to describe the testing infrastructure +employed to verify that the ``numpy.i`` typemaps are working as +expected. + +Testing Organization +==================== + +There are three indepedent testing frameworks supported, for one-, +two-, and three-dimensional arrays respectively. For one-dimensional +arrays, there are two C++ files, a header and a source, named:: + + Vector.h + Vector.cxx + +that contain prototypes and code for a variety of functions that have +one-dimensional arrays as function arguments. The file:: + + Vector.i + +is a `SWIG`_ interface file that defines a python module ``Vector`` +that wraps the functions in ``Vector.h`` while utilizing the typemaps +in ``numpy.i`` to correctly handle the C arrays. + +The ``Makefile`` calls ``swig`` to generate ``Vector.py`` and +``Vector_wrap.cxx``, and also executes the ``setup.py`` script that +compiles ``Vector_wrap.cxx`` and links together the extension module +``_Vector.so`` or ``_Vector.dylib``, depending on the platform. This +extension module and the proxy file ``Vector.py`` are both placed in a +subdirectory under the ``build`` directory. + +The actual testing takes place with a `python`_ script named:: + + testVector.py + +that uses the standard `python`_ library module ``unittest``, which +performs several tests of each function defined in ``Vector.h`` for +each data type supported. + +Two-dimensional arrays are tested in exactly the same manner. The +above description applies, but with ``Matrix`` substituted for +``Vector``. For three-dimensional tests, substitute ``Tensor`` for +``Vector``. For the descriptions that follow, we will reference the +``Vector`` tests, but the same information applies to ``Matrix`` and +``Tensor`` tests. + +The command ``make test`` will ensure that all of the test software is +built and then run all three test scripts. + +Testing Header Files +==================== + +``Vector.h`` is a C++ header file that defines a C macro called +``TEST_FUNC_PROTOS`` that takes two arguments: ``TYPE``, which is a +data type name such as ``unsigned int``; and ``SNAME``, which is a +short name for the same data type with no spaces, e.g. ``uint``. This +macro defines several function prototypes that have the prefix +``SNAME`` and have at least one argument that is an array of type +``TYPE``. Those functions that have return arguments return a +``TYPE`` value. + +``TEST_FUNC_PROTOS`` is then implemented for all of the data types +supported by ``numpy.i``: + + * ``signed char`` + * ``unsigned char`` + * ``short`` + * ``unsigned short`` + * ``int`` + * ``unsigned int`` + * ``long`` + * ``unsigned long`` + * ``long long`` + * ``unsigned long long`` + * ``float`` + * ``double`` + +Testing Source Files +==================== + +``Vector.cxx`` is a C++ source file that implements compilable code +for each of the function prototypes specified in ``Vector.h``. It +defines a C macro ``TEST_FUNCS`` that has the same arguments and works +in the same way as ``TEST_FUNC_PROTOS`` does in ``Vector.h``. +``TEST_FUNCS`` is implemented for each of the 12 data types as above. + +Testing SWIG Interface Files +============================ + +``Vector.i`` is a `SWIG`_ interface file that defines python module +``Vector``. It follows the conventions for using ``numpy.i`` as +described in the `numpy.i documentation <numpy_swig.html>`_. It +defines a `SWIG`_ macro ``%apply_numpy_typemaps`` that has a single +argument ``TYPE``. It uses the `SWIG`_ directive ``%apply`` as +described in the `numpy.i documentation`_ to apply the provided +typemaps to the argument signatures found in ``Vector.h``. This macro +is then implemented for all of the data types supported by +``numpy.i``. It then does a ``%include "Vector.h"`` to wrap all of +the function prototypes in ``Vector.h`` using the typemaps in +``numpy.i``. + +Testing Python Scripts +====================== + +After ``make`` is used to build the testing extension modules, +``testVector.py`` can be run to execute the tests. As with other +scripts that use ``unittest`` to facilitate unit testing, +``testVector.py`` defines a class that inherits from +``unittest.TestCase``:: + + class VectorTestCase(unittest.TestCase): + +However, this class is not run directly. Rather, it serves as a base +class to several other python classes, each one specific to a +particular data type. The ``VectorTestCase`` class stores two strings +for typing information: + + **self.typeStr** + A string that matches one of the ``SNAME`` prefixes used in + ``Vector.h`` and ``Vector.cxx``. For example, ``"double"``. + + **self.typeCode** + A short (typically single-character) string that represents a + data type in numpy and corresponds to ``self.typeStr``. For + example, if ``self.typeStr`` is ``"double"``, then + ``self.typeCode`` should be ``"d"``. + +Each test defined by the ``VectorTestCase`` class extracts the python +function it is trying to test by accessing the ``Vector`` module's +dictionary:: + + length = Vector.__dict__[self.typeStr + "Length"] + +In the case of double precision tests, this will return the python +function ``Vector.doubleLength``. + +We then define a new test case class for each supported data type with +a short definition such as:: + + class doubleTestCase(VectorTestCase): + def __init__(self, methodName="runTest"): + VectorTestCase.__init__(self, methodName) + self.typeStr = "double" + self.typeCode = "d" + +Each of these 12 classes is collected into a ``unittest.TestSuite``, +which is then executed. Errors and failures are summed together and +returned as the exit argument. Any non-zero result indicates that at +least one test did not pass. |