diff options
| -rw-r--r-- | numpy/doc/swig/doc/numpy_swig.html | 99 | ||||
| -rw-r--r-- | numpy/doc/swig/doc/numpy_swig.pdf | bin | 150618 -> 163324 bytes | |||
| -rw-r--r-- | numpy/doc/swig/doc/numpy_swig.txt | 59 |
3 files changed, 136 insertions, 22 deletions
diff --git a/numpy/doc/swig/doc/numpy_swig.html b/numpy/doc/swig/doc/numpy_swig.html index e0ad50e5a..7da4f57fc 100644 --- a/numpy/doc/swig/doc/numpy_swig.html +++ b/numpy/doc/swig/doc/numpy_swig.html @@ -5,7 +5,7 @@ <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="13 September, 2007" /> +<meta name="date" content="22 November, 2007" /> <style type="text/css"> /* @@ -302,7 +302,7 @@ ul.auto-toc { <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>13 September, 2007</td></tr> +<td>22 November, 2007</td></tr> </tbody> </table> <div class="contents topic"> @@ -319,19 +319,23 @@ ul.auto-toc { <li><a class="reference" href="#other-common-types-complex" id="id9" name="id9">Other Common Types: complex</a></li> </ul> </li> -<li><a class="reference" href="#helper-functions" id="id10" name="id10">Helper Functions</a><ul> -<li><a class="reference" href="#macros" id="id11" name="id11">Macros</a></li> -<li><a class="reference" href="#routines" id="id12" name="id12">Routines</a></li> +<li><a class="reference" href="#numpy-array-scalars-and-swig" id="id10" name="id10">NumPy Array Scalars and SWIG</a><ul> +<li><a class="reference" href="#why-is-there-a-second-file" id="id11" name="id11">Why is There a Second File?</a></li> </ul> </li> -<li><a class="reference" href="#beyond-the-provided-typemaps" id="id13" name="id13">Beyond the Provided Typemaps</a><ul> -<li><a class="reference" href="#a-common-example" id="id14" name="id14">A Common Example</a></li> -<li><a class="reference" href="#other-situations" id="id15" name="id15">Other Situations</a></li> -<li><a class="reference" href="#a-final-note" id="id16" name="id16">A Final Note</a></li> +<li><a class="reference" href="#helper-functions" id="id12" name="id12">Helper Functions</a><ul> +<li><a class="reference" href="#macros" id="id13" name="id13">Macros</a></li> +<li><a class="reference" href="#routines" id="id14" name="id14">Routines</a></li> </ul> </li> -<li><a class="reference" href="#summary" id="id17" name="id17">Summary</a></li> -<li><a class="reference" href="#acknowledgements" id="id18" name="id18">Acknowledgements</a></li> +<li><a class="reference" href="#beyond-the-provided-typemaps" id="id15" name="id15">Beyond the Provided Typemaps</a><ul> +<li><a class="reference" href="#a-common-example" id="id16" name="id16">A Common Example</a></li> +<li><a class="reference" href="#other-situations" id="id17" name="id17">Other Situations</a></li> +<li><a class="reference" href="#a-final-note" id="id18" name="id18">A Final Note</a></li> +</ul> +</li> +<li><a class="reference" href="#summary" id="id19" name="id19">Summary</a></li> +<li><a class="reference" href="#acknowledgements" id="id20" name="id20">Acknowledgements</a></li> </ul> </div> <div class="section"> @@ -703,12 +707,65 @@ work.</p> </div> </div> <div class="section"> -<h1><a class="toc-backref" href="#id10" id="helper-functions" name="helper-functions">Helper Functions</a></h1> +<h1><a class="toc-backref" href="#id10" 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. Often, 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 to 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="#id11" 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="#id12" 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.</p> <div class="section"> -<h2><a class="toc-backref" href="#id11" id="macros" name="macros">Macros</a></h2> +<h2><a class="toc-backref" href="#id13" id="macros" name="macros">Macros</a></h2> <blockquote> <dl class="docutils"> <dt><strong>is_array(a)</strong></dt> @@ -740,7 +797,7 @@ order. Equivalent to <tt class="docutils literal"><span class="pre">(PyArray_IS </blockquote> </div> <div class="section"> -<h2><a class="toc-backref" href="#id12" id="routines" name="routines">Routines</a></h2> +<h2><a class="toc-backref" href="#id14" id="routines" name="routines">Routines</a></h2> <blockquote> <p><strong>pytype_string()</strong></p> <blockquote> @@ -900,11 +957,11 @@ string and return 0.</p> </div> </div> <div class="section"> -<h1><a class="toc-backref" href="#id13" id="beyond-the-provided-typemaps" name="beyond-the-provided-typemaps">Beyond the Provided Typemaps</a></h1> +<h1><a class="toc-backref" href="#id15" 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="#id14" id="a-common-example" name="a-common-example">A Common Example</a></h2> +<h2><a class="toc-backref" href="#id16" 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); @@ -960,7 +1017,7 @@ above for <tt class="docutils literal"><span class="pre">my_dot</span></tt> to g macro to perform this task.</p> </div> <div class="section"> -<h2><a class="toc-backref" href="#id15" id="other-situations" name="other-situations">Other Situations</a></h2> +<h2><a class="toc-backref" href="#id17" 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> @@ -997,7 +1054,7 @@ developers of <tt class="docutils literal"><span class="pre">numpy.i</span></tt> </blockquote> </div> <div class="section"> -<h2><a class="toc-backref" href="#id16" id="a-final-note" name="a-final-note">A Final Note</a></h2> +<h2><a class="toc-backref" href="#id18" 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 @@ -1015,7 +1072,7 @@ where you want them, and then clear them after you are done.</p> </div> </div> <div class="section"> -<h1><a class="toc-backref" href="#id17" id="summary" name="summary">Summary</a></h1> +<h1><a class="toc-backref" href="#id19" 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> @@ -1049,7 +1106,7 @@ cases not covered by the provided typemaps.</li> </blockquote> </div> <div class="section"> -<h1><a class="toc-backref" href="#id18" id="acknowledgements" name="acknowledgements">Acknowledgements</a></h1> +<h1><a class="toc-backref" href="#id20" 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 @@ -1063,7 +1120,7 @@ result possible.</p> </div> <div class="footer"> <hr class="footer" /> -Generated on: 2007-11-20 13:58 UTC. +Generated on: 2007-11-22 18:34 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> diff --git a/numpy/doc/swig/doc/numpy_swig.pdf b/numpy/doc/swig/doc/numpy_swig.pdf Binary files differindex f266277fa..81da6aa93 100644 --- a/numpy/doc/swig/doc/numpy_swig.pdf +++ b/numpy/doc/swig/doc/numpy_swig.pdf diff --git a/numpy/doc/swig/doc/numpy_swig.txt b/numpy/doc/swig/doc/numpy_swig.txt index 4191af3b8..84c583029 100644 --- a/numpy/doc/swig/doc/numpy_swig.txt +++ b/numpy/doc/swig/doc/numpy_swig.txt @@ -4,7 +4,7 @@ :Author: Bill Spotz :Institution: Sandia National Laboratories -:Date: 13 September, 2007 +:Date: 22 November, 2007 .. contents:: @@ -387,6 +387,63 @@ Assuming these data structures are compatible with `python`_ and the user's complex type substituted for the first argument) should work. +NumPy Array Scalars and SWIG +============================ + +`SWIG`_ has sophisticated type checking for numerical types. For +example, if your C/C++ routine expects an integer as input, the code +generated by `SWIG`_ will check for both `python`_ integers and +`python`_ long integers, and raise an overflow error if the provided +`python`_ integer is too big to cast down to a C integer. With the +introduction of `NumPy`_ scalar arrays into your `python`_ code, you +might conceivably extract an integer from a `NumPy`_ array and attempt +to pass this to a `SWIG`_-wrapped C/C++ function that expects an +``int``, but the `SWIG`_ type checking will not recognize the `NumPy`_ +array scalar as an integer. (Often, this does in fact work -- it +depends on whether `NumPy`_ recognizes the integer type you are using +as inheriting from the `python`_ integer type on the platform you are +using. Often, this means that code that works on a 32-bit machine +will fail on a 64-bit machine.) + +If you get a `python`_ error that looks like the following:: + + TypeError: in method 'MyClass_MyMethod', argument 2 of type 'int' + +and the argument you are passing is an integer extracted from a +`NumPy`_ array, then you have stumbled upon this problem. The +solution is to modify the `SWIG`_ type conversion system to accept +`Numpy`_ array scalars in addition to the standard integer types. +Fortunately, this capabilitiy has been provided to you. Simply copy +the file:: + + pyfragments.swg + +to the working build directory for you project, and this problem will +be fixed. It is suggested that you do this anyway, as it only +increases the capabilities of your `python`_ interface. + +Why is There a Second File? +--------------------------- + +The `SWIG`_ type checking and conversion system is a complicated +combination of C macros, `SWIG`_ macros, `SWIG`_ typemaps and `SWIG`_ +fragments. Fragments are a way to conditionally insert code into your +wrapper file if it is needed, and not insert it if not needed. If +multiple typemaps require the same fragment, the fragment only gets +inserted into your wrapper code once. + +There is a fragment for converting a `python`_ integer to a C +``long``. There is a different fragment that converts a `python`_ +integer to a C ``int``, that calls the rountine defined in the +``long`` fragment. We can make the changes we want here by changing +the definition for the ``long`` fragment. `SWIG`_ determines the +active definition for a fragment using a "first come, first served" +system. That is, we need to define the fragment for ``long`` +conversions prior to `SWIG`_ doing it internally. `SWIG`_ allows us +to do this by putting our fragment definitions in the file +``pyfragments.swg``. If we were to put the new fragment definitions +in ``numpy.i``, they would be ignored. + Helper Functions ================ |