[Numpy-svn] r8685 - trunk/doc/swig/doc
numpy-svn at scipy.org
numpy-svn at scipy.org
Sat Sep 4 05:52:44 EDT 2010
Author: rgommers
Date: 2010-09-04 04:52:44 -0500 (Sat, 04 Sep 2010)
New Revision: 8685
Removed:
trunk/doc/swig/doc/Makefile
trunk/doc/swig/doc/numpy_swig.html
trunk/doc/swig/doc/numpy_swig.pdf
trunk/doc/swig/doc/testing.html
trunk/doc/swig/doc/testing.pdf
Log:
DOC: remove built separate swig docs.
Deleted: trunk/doc/swig/doc/Makefile
===================================================================
--- trunk/doc/swig/doc/Makefile 2010-09-04 09:52:24 UTC (rev 8684)
+++ trunk/doc/swig/doc/Makefile 2010-09-04 09:52:44 UTC (rev 8685)
@@ -1,51 +0,0 @@
-# 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 *~
Deleted: trunk/doc/swig/doc/numpy_swig.html
===================================================================
--- trunk/doc/swig/doc/numpy_swig.html 2010-09-04 09:52:24 UTC (rev 8684)
+++ trunk/doc/swig/doc/numpy_swig.html 2010-09-04 09:52:44 UTC (rev 8685)
@@ -1,1244 +0,0 @@
-<!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 at 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>
Deleted: trunk/doc/swig/doc/numpy_swig.pdf
===================================================================
(Binary files differ)
Deleted: trunk/doc/swig/doc/testing.html
===================================================================
--- trunk/doc/swig/doc/testing.html 2010-09-04 09:52:24 UTC (rev 8684)
+++ trunk/doc/swig/doc/testing.html 2010-09-04 09:52:44 UTC (rev 8685)
@@ -1,482 +0,0 @@
-<!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 at 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>
Deleted: trunk/doc/swig/doc/testing.pdf
===================================================================
(Binary files differ)
More information about the Numpy-svn
mailing list