<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
<!-- And munged by Dave's special Python script -->
<html>
<head>
<title>SWIG and Python</title>
</head>

<body bgcolor="#ffffff">
<a name="n0"></a><h1>9 SWIG and Python</h1><p><ul>
<li> <a href="#n1">Preliminaries</a>
<li> <a href="#n2">Building Python Extensions under Windows 95/NT</a>
<li> <a href="#n3">The low-level Python/C interface</a>
<li> <a href="#n4">Python shadow classes</a>
<li> <a href="#n5">About the Examples</a>
<li> <a href="#n6">Solving a simple heat-equation</a>
<li> <a href="#n7">Wrapping a C library</a>
<li> <a href="#n8">Putting it all together</a>
<li> <a href="#n9">Exception handling</a>
<li> <a href="#n10">Remapping C datatypes with typemaps</a>
<li> <a href="#n11">Implementing C callback functions in Python</a>
<li> <a href="#n12">Other odds and ends</a>
<li> <a href="#n13">The gory details of shadow classes</a>
</ul>

This chapter describes SWIG's support of Python. Many of the example presented here will have a scientific bias given Python's increasing use in scientific applications (this is how I primarily use Python), but the techniques are widely applicable to other areas.<p>
<a name="n1"></a><h2> Preliminaries</h2>
SWIG 1.1 works with Python 1.3 and Python 1.4. Given the choice, you should use the latest version of Python. You should also determine if your system supports shared libraries and dynamic loading. SWIG will work with or without dynamic loading, but the compilation process will vary.<p>
<a name="n14"></a><h3> Running SWIG</h3>
To build a Python module, run SWIG using the <tt>-python</tt> option :<p>
<p>
<blockquote><pre>%swig -python example.i
</pre></blockquote>
<p>
This will produce 2 files. The file <tt>example_wrap.c</tt> contains all of the C code needed to build a Python module and a documentation file describes the resulting interface. To build a Python module, you will need to compile the file <tt>example_wrap.c</tt> and link it with the rest of your program (and possibly Python itself). When working with shadow classes, SWIG will also produce a <tt>.py</tt> file, but this is described later.<p>
<a name="n15"></a><h3> Getting the right header files</h3>
In order to compile, you need to locate the following directories that are part of the Python distribution :<p>
<p>
For Python 1.3 :<p>
<p>
<blockquote><pre>/usr/local/include/Py 
/usr/local/lib/python/lib
</pre></blockquote>
<p>
For Python 1.4 :<p>
<p>
<blockquote><pre>/usr/local/include/python1.4
/usr/local/lib/python1.4/config

</pre></blockquote>
The exact location may vary on your machine, but the above locations are typical. <p>
<a name="n16"></a><h3> Compiling a dynamic module</h3>
To build a shared object file, you need to compile your module in a manner similar to the following (shown for Irix):<p>
<p>
<blockquote><pre>% swig -python example.i
% gcc -c example.c
% gcc -c example_wrap.c -DHAVE_CONFIG_H -I/usr/local/include/python1.4 \
	-I/usr/local/lib/python1.4/config
% ld -shared example.o example_wrap.o -o examplemodule.so

</pre></blockquote>
Unfortunately, the process of building a shared object file varies on every single machine so you may need to read up on the man pages for your C compiler and linker.<p>
<p>
When building a dynamic module, the name of the output file is important. If the name of your SWIG module is "<tt>example</tt>", the name of the corresponding object file should be "<tt>examplemodule.so</tt>" (or equivalent depending on your machine). The name of the module is specified using the <tt>%module</tt> directive or<tt> -module</tt> command line option.<p>
<p>
While dynamic loading is the preferred method for making SWIG modules, it is not foolproof and not supported on all machines.  In these cases, you can rebuild the Python interpreter with your extensions added.<p>
<a name="n17"></a><h3> Rebuilding the Python interpreter (aka. static linking)</h3>
The normal procedure for adding a new module to Python involves finding the Python source, adding an entry to the <tt>Modules/Setup</tt> file, and rebuilding the interpreter using the Python Makefile. While it's possible to simplify the process by using the VPATH feature of `make', I've always found the process to be a little too complicated. <p>
<p>
SWIG provides an extremely easy, although somewhat unconventional, mechanism for rebuilding Python using SWIG's library feature. When you want to build a static version of Python, simply make an interface file like this :<p>
<p>
<blockquote><pre>%module example

extern int fact(int);
extern int mod(int, int);
extern double My_variable;

%include embed.i              // Include code for a static version of Python

</pre></blockquote>
The <tt>embed.i</tt> library file includes supporting code that contains everything needed to rebuild Python. To build your module, simply do the following :<p>
<p>
<blockquote><pre>% swig -python example.i
% gcc example.c example_wrap.c -DHAVE_CONFIG_H -I/usr/local/include/python1.4 \
	-I/usr/local/lib/python1.4/config \
	-L/usr/local/lib/python1.4/config -lModules -lPython -lObjects -lParser -lm \
	-o mypython

</pre></blockquote>
On some machines, you may need need to supply additional libraries on the link line. In particular, you may need to supply <tt>-lsocket</tt>,<tt> -lnsl</tt>, and <tt>-ldl</tt>. <p>
<p>
It is also possible to add the embed.i library to an existing interface by running SWIG as follows :<p>
<p>
<blockquote><pre>% swig -python -lembed.i example.i

</pre></blockquote>
The <tt>embed.i</tt> file uses all of the modules that are currently being used in your installed version of Python. Thus, your new version of Python will be identical to the old one except with your new module added. If you have configured Python to use modules such as <tt>tkinter,</tt> you may need to supply linkage to the Tcl/Tk libraries and X11 libraries.<p>
<p>
Python's <tt>main()</tt> program is rather unfriendly towards C++ code, but SWIG's <tt>embed.i</tt> module provides a replacement that can be compiled with the C++ compiler--making it easy to build C++ Python extensions.<p>
<p>
The <tt>embed.i</tt> library should only be used with Python 1.4. If you are using Python 1.3, you should use the file <tt>embed13.i</tt> instead (this can be done by making a symbolic link in the SWIG library) or simply using the <tt>-l</tt> option.<p>
<a name="n18"></a><h3> Using your module</h3>
To use your module in Python, simply use Python's import command. The process is identical regardless of whether or not you used dynamic loading or rebuilt the Python interpreter :<p>
<p>
<blockquote><pre>% python
&gt;&gt;&gt; import example
&gt;&gt;&gt; example.fact(4)
24
&gt;&gt;&gt;

</pre></blockquote>
<a name="n19"></a><h3> Compilation problems and compiling with C++</h3>
For the most part, compiling a Python module is straightforward, but there are a number of potential problems :<p>
<p>
<ul>
<li>Dynamic loading is not supported on all machines. If you can't get a module to build, you might try building a new version of Python using static linking instead.
<li>In order to build C++ modules, you may need to link with the C++ compile using a command like `<tt>c++ -shared example_wrap.o example.o -o examplemodule.so</tt>'
<li>If building a dynamic C++ module using g++, you may also need to link against <tt>libgcc.a</tt>, <tt>libg++.a</tt>, and <tt>libstc++.a</tt> libraries.
<li>Make sure you are using the correct header files and libraries. A module compiled with Python 1.3 headers probably won't work with Python 1.4.
</ul>
<a name="n2"></a><h2> Building Python Extensions under Windows 95/NT</h2>
Building a SWIG extension to Python under Windows 95/NT is roughly similar to the process used with Unix.   Normally, you will want to produce a DLL that can be loaded into the Python interpreter.    This section covers the process of using SWIG with Microsoft Visual C++ 4.x although the procedure may be similar with other compilers.   SWIG currently supports both the basic Python release and Pythonwin.  In order to build extensions, you will need to download the source distribution to these packages as you will need the Python header files.<p>
<a name="n20"></a><h3> Running SWIG from Developer Studio</h3>
If you are developing your application within Microsoft developer studio, SWIG can be invoked as a custom build option.      The process roughly follows these steps :<p>
<p>
<ul>
<li>Open up a new workspace and use the AppWizard to select a DLL project.
<li>Add both the SWIG interface file (the .i file), any supporting C files, and the name of the wrapper file that will be created by SWIG (ie. <tt>example_wrap.c</tt>).   Note : If using C++, choose a different suffix for the wrapper file such as <tt>example_wrap.cxx</tt>. Don't worry if the wrapper file doesn't exist yet--Developer Studio will keep a reference to it around.
<li>Select the SWIG interface file and go to the settings menu.   Under settings, select the "Custom Build" option.
<li>Enter "SWIG" in the description field.
<li>Enter "<tt>swig -python -o $(ProjDir)\$(InputName)_wrap.c $(InputPath)</tt>" in the "Build command(s) field"
<li>Enter "<tt>$(ProjDir)\$(InputName)_wrap.c</tt>" in the "Output files(s) field".
<li>Next, select the settings for the entire project and go to "C++:Preprocessor". Add the include directories for your Python installation under "Additional include directories".
<li>Define the symbol  __WIN32__ under preprocessor options.  
<li>Finally, select the settings for the entire project and go to "Link Options".  Add the Python library  file to your link libraries.  For example "python14.lib".  Also, set the name of the output file to match the name of your Python module (ie. example.dll).
<li>Build your project.
</ul>
<p>
Now, assuming all went well, SWIG will be automatically invoked when you build your project.  Any changes made to the interface file will result in SWIG being automatically invoked to produce a new version of the wrapper file.  To run your new Python extension, simply run Python and use the <tt>import</tt> command as normal. For example :<p>
<p>
<blockquote><pre>
MSDOS &gt; python
&gt;&gt;&gt; import example
&gt;&gt;&gt; print example.fact(4)
24
&gt;&gt;&gt;
</pre></blockquote>
<a name="n21"></a><h3> Using NMAKE</h3>
Alternatively, SWIG extensions can be built by writing a Makefile for NMAKE.   Make sure the environment variables for MSVC++ are available and the MSVC++ tools are in your path.   Now, just write a short Makefile like this :<p>
<p>
<blockquote><pre># Makefile for building a Python extension

SRCS          = example.c
IFILE         = example
INTERFACE     = $(IFILE).i
WRAPFILE      = $(IFILE)_wrap.c

# Location of the Visual C++ tools (32 bit assumed)

TOOLS         = c:\msdev
TARGET        = example.dll
CC            = $(TOOLS)\bin\cl.exe
LINK          = $(TOOLS)\bin\link.exe
INCLUDE32     = -I$(TOOLS)\include
MACHINE       = IX86

# C Library needed to build a DLL

DLLIBC        = msvcrt.lib oldnames.lib  

# Windows libraries that are apparently needed
WINLIB        = kernel32.lib advapi32.lib user32.lib gdi32.lib comdlg32.lib 
winspool.lib

# Libraries common to all DLLs
LIBS          = $(DLLIBC) $(WINLIB) 

# Linker options
LOPT      = -debug:full -debugtype:cv /NODEFAULTLIB /RELEASE /NOLOGO \
             /MACHINE:$(MACHINE) -entry:_DllMainCRTStartup@12 -dll

# C compiler flags

CFLAGS        = /Z7 /Od /c /nologo
PY_INCLUDE    = -Id:\python-1.4\Include -Id:\python-1.4 -Id:\python-1.4\Pc
PY_LIB        = d:\python-1.4\vc40\python14.lib
PY_FLAGS = /D__WIN32__

python::
	swig -python -o $(WRAPFILE) $(INTERFACE)
	$(CC) $(CFLAGS) $(PY_FLAGS) $(PY_INCLUDE) $(SRCS) $(WRAPFILE)
	set LIB=$(TOOLS)\lib
	$(LINK) $(LOPT) -out:example.dll $(LIBS) $(PY_LIB) example.obj example_wrap.obj


</pre></blockquote>
<p>
To build the extension, run NMAKE (you may need to run <tt>vcvars32</tt> first). This is a pretty simplistic Makefile, but hopefully its enough to get you started.   <p>
<a name="n3"></a><h2> The low-level Python/C interface</h2>
The SWIG Python module is based upon a basic low-level interface that provides access to C functions, variables, constants, and C++ classes. This low-level interface is often used to create more sophisticated interfaces (such as shadow classes) so it may be hidden in practice.<p>
<a name="n22"></a><h3> Modules</h3>
The SWIG <tt>%module</tt> directive specifies the name of the Python module. If you specified `<tt>%module example</tt>', then everything found in a SWIG interface file will be contained within the Python `<tt>example</tt>' module.  Make sure you don't use the same name as a built-in Python command or standard module or your results may be unpredictable. <p>
<a name="n23"></a><h3> Functions</h3>
C/C++ functions are mapped directly into a matching Python function. For example :<p>
<p>
<blockquote><pre>%module example
extern int fact(int n);

</pre></blockquote>
gets turned into the Python function <tt>example.fact(n)</tt> :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; import example
&gt;&gt;&gt; print example.fact(4)
24
&gt;&gt;&gt;
</pre></blockquote>
<a name="n24"></a><h3> Variable Linking</h3>
SWIG provides access to C/C++ global variables, but the mechanism is slightly different than one might expect due to the object model used in Python. When you type the following in Python :<p>
<p>
<blockquote><pre>a = 3.4

</pre></blockquote>
"a" becomes a name for an object containing the value 3.4. If you later type<p>
<p>
<blockquote><pre>b = a

</pre></blockquote>
Then "a" and "b" are both names for the object containing the value 3.4. In other words, there is only one object containing 3.4 and "a" and "b" are both names that refer to it. This is a very different model than that used in C. For this reason, there is no mechanism for mapping "assignment" in Python onto C global variables (because assignment is Python is really a naming operation).<p>
<p>
To provide access to C global variables, SWIG creates a special Python object called `<tt>cvar</tt>' that is added to each SWIG generated module. This object is used to access global variables  as follows :<p>
<blockquote><pre>
// SWIG interface file with global variables
%module example
...
extern int My_variable;
extern double density;
...
</pre></blockquote>
<p>
Now in Python :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; import example
&gt;&gt;&gt; # Print out value of a C global variable
&gt;&gt;&gt; print example.cvar.My_variable
4
&gt;&gt;&gt; # Set the value of a C global variable
&gt;&gt;&gt; example.cvar.density = 0.8442
&gt;&gt;&gt; # Use in a math operation
&gt;&gt;&gt; example.cvar.density = example.cvar.density*1.10
</pre></blockquote>
<p>
Just remember, all C globals need to be prefixed with a "<tt>cvar.</tt>" and you will be set. If you would like to use a name other than "<tt>cvar</tt>", it can be changed using the <tt>-globals</tt> option :<p>
<p>
<blockquote><pre>% swig -python -globals myvar example.i

</pre></blockquote>
Some care is in order when importing multiple SWIG modules. If you use the "<tt>from &lt;file&gt; import *</tt>" style of importing, you will get a name clash on the variable `<tt>cvar</tt>' and will only be able to access global variables from the last module loaded. SWIG does not create <tt>cvar</tt> if there are no global variables in a module.<p>
<a name="n25"></a><h3> Constants</h3>
C/C++ constants are installed as new Python objects containing the appropriate value. These constants are given the same name as the corresponding C constant. "Constants" are not guaranteed to be constants in Python---in other words, you are free to change them and suffer the consequences!<p>
<a name="n26"></a><h3> Pointers</h3>
Pointers to C/C++ objects are represented as character strings such as the following :<p>
<p>
<blockquote><pre>_100f8e2_Vector_p

</pre></blockquote>
A NULL pointer is represented by the string "NULL". You can also explicitly create a NULL pointer consisting of the value 0 and a type such as :<p>
<p>
<blockquote><pre>_0_Vector_p

</pre></blockquote>
To some Python users, the idea of representing pointers as strings may seem strange, but keep in mind that pointers are meant to be opaque objects. In practice, you may never notice that pointers are character strings. There is also a certain efficiency in using this representation as it is easy to pass pointers around between modules and it is unnecessary to rely on a new Python datatype. Eventually, pointers may be represented as special Python objects, but the string representation works remarkably well so there has been little need to replace it.<p>
<a name="n27"></a><h3> Structures </h3>
The low-level SWIG interface only provides a simple interface to C structures. For example :<p>
<p>
<blockquote><pre>struct Vector {
	double x,y,z;
};

</pre></blockquote>
gets mapped into the following collection of C functions :<p>
<p>
<blockquote><pre>double Vector_x_get(Vector *obj)
double Vector_x_set(Vector *obj, double x)
double Vector_y_get(Vector *obj)
double Vector_y_set(Vector *obj, double y)
double Vector_z_get(Vector *obj)
double Vector_z_set(Vector *obj, double z)

</pre></blockquote>
These functions are then used in the resulting Python interface. For example :<p>
<p>
<blockquote><pre># v is a Vector that got created somehow
&gt;&gt;&gt; Vector_x_get(v)
3.5
&gt;&gt;&gt; Vector_x_set(v,7.8)       # Change x component
&gt;&gt;&gt; print Vector_x_get(v), Vector_y_get(v), Vector_z_get(v)
7.8 -4.5 0.0
&gt;&gt;&gt; 
</pre></blockquote>
<p>
Similar access is provided for unions and the data members of C++ classes.<p>
<a name="n28"></a><h3> C++ Classes</h3>
C++ classes are handled by building a set of low level accessor functions. Consider the following class :<p>
<p>
<blockquote><pre>class List {
public:
  List();
  ~List();
  int  search(char *item);
  void insert(char *item);
  void remove(char *item);
  char *get(int n);
  int  length;
static void print(List *l);
};
</pre></blockquote>
<p>
When wrapped by SWIG, the following functions will be created :<p>
<p>
<blockquote><pre>List    *new_List();
void     delete_List(List *l);
int      List_search(List *l, char *item);
void     List_insert(List *l, char *item);
void     List_remove(List *l, char *item);
char    *List_get(List *l, int n);
int      List_length_get(List *l);
int      List_length_set(List *l, int n);
void     List_print(List *l);

</pre></blockquote>
Within Python, these functions used to access the C++ class :<p>
<blockquote><pre>
&gt;&gt;&gt; l = new_List()
&gt;&gt;&gt; List_insert(l,"Ale")
&gt;&gt;&gt; List_insert(l,"Stout")
&gt;&gt;&gt; List_insert(l,"Lager")
&gt;&gt;&gt; List_print(l)
Lager
Stout
Ale
&gt;&gt;&gt; print List_length_get(l)
3
&gt;&gt;&gt; print l
_1008560_List_p
&gt;&gt;&gt;

</pre></blockquote>
C++ objects are really just pointers. Member functions and data are accessed by simply passing a pointer into a collection of accessor functions that take the pointer as the first argument.<p>
<p>
While somewhat primitive, the low-level SWIG interface provides direct and flexible access to C++ objects. As it turns out, a more elegant method of accessing structures and classes is available using shadow classes.<p>
<a name="n4"></a><h2> Python shadow classes</h2>
The low-level interface generated by SWIG provides access to C structures and C++ classes, but it doesn't look much like a class that might be created in Python. However, it is possible to use the low-level C interface to write a Python class that looks like the original C++ class. In this case, the Python class is said to "shadow" the C++ class.  That is, it behaves like the original class, but is really just a wrapper around a C++ class.<p>
<a name="n29"></a><h3> A simple example</h3>
For our earlier List class, a Python shadow class could be written by hand like this :<p>
<p>
<blockquote><pre>class List:
	def __init__(self):
		self.this = new_List()
	def __del__(self):
		delete_List(self.this)
	def search(self,item):
		return List_search(self.this,item)
	def insert(self,item):
		List_insert(self.this,item)
	def remove(self,item):
		List_remove(self.this,item)
	def get(self,n):
		return List_get(self.this,n)
	def __getattr__(self,name):
		if name == "length" : return List_length_get(self.this))
		else : return self.__dict__[name]
	def __setattr__(self,name,value):
		if name == "length": List_length_set(self.this,value)
		else : self.__dict__[name] = value
</pre></blockquote>
<p>
When used in a Python script, we can use the class as follows :<p>
<blockquote><pre>

&gt;&gt;&gt; l = List()
&gt;&gt;&gt; l.insert("Ale")
&gt;&gt;&gt; l.insert("Stout")
&gt;&gt;&gt; l.insert("Lager")
&gt;&gt;&gt; List_print(l.this)
Lager
Stout
Ale
&gt;&gt;&gt; l.length
3
</pre></blockquote>
<p>
Obviously, this is a much nicer interface than before--and it only required a small amount of Python coding.<p>
<a name="n30"></a><h3> Why write shadow classes in Python?</h3>
While one could wrap C/C++ objects directly into Python as new Python types, this approach has a number of problems. First, as the C/C++ code gets complicated, the resulting wrapper code starts to become extremely ugly. It also becomes hard to handle inheritance and more advanced language features. A second, and more serious problem, is that Python "types" created in C can not be subclassed or used in the same way as one might use a real Python class. As a result, it is not possible to do interesting things like create Python classes that inherit from C++ classes.  <p>
<p>
By writing shadow classes in Python instead of C, the classes become real Python classes that can be used as base-classes in an inheritance hierarchy or for other applications. Writing the shadow classes in Python also greatly simplies coding complexity as writing in Python is much easier than trying to accomplish the same thing in C. Finally, by writing shadow classes in Python, they are easy to modify and can be changed without ever recompiling any of the C code.   The downside to this approach is worse performance--a concern for some users.<p>
<p>
The problems of combining C++ and Python have been of great interest to the Python community.   SWIG is primarily concerned with accessing C++ from Python.   Readers who are interested in more than this (and the idea of accessing Python classes from C++) are encouraged to look into the MESS extension which aims to provide a tighter integration between C++ and Python.  The recently announced GRAD package also shows much promise and provides very comprehensive C++/Python interface.<p>
<a name="n31"></a><h3> Automated shadow class generation</h3>
SWIG can automatically generate shadow classes if you use the <tt>-shadow</tt> option :<p>
<p>
<blockquote><pre>swig -python -shadow interface.i

</pre></blockquote>
This will create the following two files :<p>
<p>
<blockquote><pre>interface_wrap.c
module.py
</pre></blockquote>
<p>
The file <tt>interface_wrap.c</tt> contains the normal SWIG C/C++ wrappers. The file <tt>module.py</tt> contains the Python code corresponding to shadow classes. The name of this file will be the same as specified by the <tt>%module</tt> directive in the SWIG interface file.<p>
<p>
Associated with the two files are TWO Python modules. The C module `<tt>modulec</tt>' contains the low-level C interface that would have been created without the <tt>-shadow</tt> option. The Python module `<tt>module</tt>' contains the Python shadow classes that have been built around the low-level interface. To use the module, simply use `<tt>import module</tt>'. For all practical purposes, the `<tt>modulec</tt>' module is completely hidden although you can certainly use it if you want to.<p>
<a name="n32"></a><h3> Compiling modules with shadow classes</h3>
To compile a module involving shadow classes, you can use the same procedure as before except that the module name now has an extra `<tt>c</tt>' appended to the name. Thus, an interface file like this <p>
<p>
<blockquote><pre>%module example
... a bunch of declarations ...

</pre></blockquote>
might be compiled as follows :<p>
<p>
<blockquote><pre>% swig -python -shadow example.i
% gcc -c example.c example_wrap.c -I/usr/local/include/python1.4 \
	-I/usr/local/lib/python1.4/config -DHAVE_CONFIG_H
% ld -shared example.o example_wrap.o -o examplecmodule.so

</pre></blockquote>
Notice the naming of `<tt>examplecmodule.so</tt>' as opposed to `<tt>examplemodule.so</tt>' that would have been created without shadow classes.<p>
<p>
When using static linking, no changes need to be made to the compilation process.<p>
<a name="n33"></a><h3> Where to go for more information</h3>
Shadow classes turn out to be so useful that they are used almost all of the time with SWIG. All of the examples presented here will assume that shadow classes have been enabled. The precise implementation of shadow classes is described at the end of this chapter and is not necessary  to effectively use SWIG.<p>
<a name="n5"></a><h2> About the Examples</h2>
The next few sections will go through a series of Python examples of varying complexity. These examples are designed to illustrate how SWIG can be used to integrate C/C++ and Python in a variety of ways. Some of the things that will be covered include :<p>
<p>
<ul>
<li>Controlling a simple C++ program with Python
<li>Wrapping a C library.
<li>Adding Python methods to existing C++ classes
<li>Accessing arrays and other common data structures.
<li>Building reusable components.
<li>Writing C/C++ callback functions in Python.
</ul>
<a name="n6"></a><h2> Solving a simple heat-equation</h2>
In this example, we will show how Python can be used to control a simple physics application--in this case, some C++ code for solving a 2D heat equation.  This example is probably overly simplistic, but hopefully it's enough to give you some ideas.<p>
<a name="n34"></a><h3> The C++ code </h3>
Our simple application consists of the following two files :<p>
<blockquote><pre>
// File : pde.h
// Header file for Heat equation solver

#include &lt;math.h&gt;
#include &lt;stdio.h&gt;

// A simple 2D Grid structure 

// A simple structure for holding a 2D grid of values
struct Grid2d {
  Grid2d(int ni, int nj);
  ~Grid2d();
  double **data;
  int      xpoints;
  int      ypoints;
};

// Simple class for solving a heat equation */
class Heat2d {
private:
  Grid2d    *work;                         // Temporary grid, needed for solver
  double    h,k;                           // Grid spacing
public:    
  Heat2d(int ni, int nj); 
  ~Heat2d();
  Grid2d    *grid;                         // Data
  double     dt;                           // Timestep
  double     time;                         // Elapsed time
  void       solve(int nsteps);            // Run for nsteps
  void       set_temp(double temp);        // Set temperature
};
</pre></blockquote>
<p>
The supporting C++ code implements a simple partial differential equation solver and some operations on the grid data structure.   The precise implementation isn't important here, but all of the code can be found in the "<tt>Examples/python/manual" </tt>directory of the SWIG distribution. <p>
<a name="n35"></a><h3> Making a quick and dirty Python module</h3>
Given our simple application, making a Python module is easy.  Simply use the following SWIG interface file :<p>
<p>
<blockquote><pre>// File : pde.i
%module pde
%{
#include "pde.h"
%}

%include pde.h

</pre></blockquote>
Since <tt>pde.h</tt> is fairly simple, we can simply include it directly into our interface file using <tt>%include</tt>.  However, we also need to make sure we also include it in the <tt>%{,%}</tt> block--otherwise we'll get a huge number of compiler errors when we compile the resulting wrapper file.  <p>
<p>
To build the module simply run SWIG with the following options<p>
<p>
<blockquote><pre>swig -python -shadow pde.i
</pre></blockquote>
<p>
and compile using the techniques described in the beginning of this chapter.<p>
<a name="n36"></a><h3> Using  our new module</h3>
We are now ready to use our new module.   To do this, we can simply write a Python script like this :<p>
<p>
<blockquote><pre># A fairly uninteresting example

from pde import *

h = Heat2d(50,50)          # Creates a new "problem"

h.set_temp(1.0)
print "Dt = ", h.dt

# Solve something

for i in range(0,25):	
	h.solve(100)
	print "time = ", h.time

</pre></blockquote>
<p>
When run, we get rather exciting output such as the following :<p>
<blockquote><pre>
Dt =  2.5e-05
time =  0.0025
time =  0.005
time =  0.0075
...
time =  0.06
time =  0.0625

</pre></blockquote>
(okay, it's not that exciting--well, maybe it is if you don't get out much).<p>
<p>
While this has only been a simple example it is important to note that we could have just as easily written the same thing in C++. For example :<p>
<p>
<blockquote><pre>// Python example written in C++

#include "pde.h"
#include &lt;stdio.h&gt;

int main(int argc, char **argv) {

  Heat2d *h;

  h = new Heat2d(50,50);
  printf("Dt = %g\n", h-&gt;dt);
  
  h-&gt;set_temp(1.0);

  for (int i = 0; i &lt; 25; i++) {
    h-&gt;solve(100);
    printf("time = %g\n", h-&gt;time);
  }
}

</pre></blockquote>
For the most part, the code looks identical (although the Python version is simpler).  As for performance, the Python version runs less than 1% slower than the C++ version on my machine.  Given that most of the computational work is written in C++, there is very little performance penalty for writing the outer loop of our calculation in Python in this case.<p>
<p>
Unfortunately, our Python version suffers a number of drawbacks.  Most notably, there is no way for us to access any of the grid data (which is easily accomplished in C++). However, there are ways to fix this :<p>
<a name="n37"></a><h3> Accessing array data</h3>
Let's modify our heat equation problem so that we can access grid data directly from Python.   This can be done by modifying our interface file as follows :<p>
<blockquote><pre>
%module pde
%{
#include "pde.h"
%}

%include pde.h

// Add a few "helper" functions to extract grid data 
%inline %{
double  Grid2d_get(Grid2d *g, int i, int j) {
      return g-&gt;data[i][j];
}
void    Grid2d_set(Grid2d *g, int i, int j, double val) {
      g-&gt;data[i][j] = val;
}
%}

</pre></blockquote>
Rather than modifying our C++ code, it is easy enough to supply a few accessor functions directly in our interface file.  These function may only be used from Python so this approach makes sense and it helps us keep our C++ code free from unnecessary clutter.   The <tt>%inline</tt> directive is a convenient method for adding helper functions since the functions you declare show up in the interface automatically.<p>
<p>
We can now use our accessor functions to write a more sophisticated Python script :<p>
<p>
<blockquote><pre># An example using our set/get functions

from pde import *

# Set up an initial condition
def initcond(h):
	h.set_temp(0.0)
	nx = h.grid.xpoints
	for i in range(0,nx):
		Grid2d_set(h.grid,i,0,1.0)                        # Set grid values

# Dump out to a file
def dump(h,filename):
	f = open(filename,"w")
	nx = h.grid.xpoints
	ny = h.grid.ypoints
	for i in range(0,nx):
		for j in range(0,ny):
			f.write(str(Grid2d_get(h.grid,i,j))+"\n")  # Get grid value
	f.close()

# Set up a problem and run it

h = Heat2d(50,50)
initcond(h)
fileno = 1
for i in range(0,25):
	h.solve(100)
	dump(h,"Dat"+str(fileno))
	print "time = ", h.time
	fileno = fileno+1

</pre></blockquote>
<p>
We now have a Python script that can create a grid, set up an initial condition, run a simulation, and dump a collection of datafiles.  So, with just a little supporting code in our interface file, we can start to do useful work from Python.  <p>
<a name="n38"></a><h3> Use Python for control, C for performance</h3>
Now that it is possible to access grid data from Python, it is possible to quickly write code for all sorts of operations.   However, Python may not provide enough performance for certain operations.  For example, the <tt>dump()</tt> function in the previous example may become quite slow as problem sizes increase.   Thus, we might consider writing it in C++ such as the follows:<p>
<p>
<blockquote><pre>void dump(Heat2d *h, char *filename) {
      FILE *f;
      int   i,j;

      f = fopen(filename,"w");
      for (i = 0; i &lt; h-&gt;grid-&gt;xpoints; i++)
	for (j = 0; j &lt; h-&gt;grid-&gt;ypoints; j++)
	  fprintf(f,"%0.17f\n",h-&gt;grid-&gt;data[i][j]);
      fclose(f);
}
</pre></blockquote>
<p>
To use this new function, simple put its declaration in the SWIG interface file and get rid of the old Python version.  The Python script won't know that you changed the implementation.<p>
<a name="n39"></a><h3> Getting even more serious about array access</h3>
We have provided access to grid data using a pair of get/set functions.  However, using these functions is a little clumsy because they always have to be called as a separate function like this :<p>
<p>
<blockquote><pre>Grid2d_set(grid,i,j,1.0)
</pre></blockquote>
<p>
It might make more sense to make the get/set functions appear like  member functions of the <tt>Grid2D</tt> class.   That way we could use them like this :<p>
<p>
<blockquote><pre>grid.set(i,j,1.0)
grid.get(i,j)

</pre></blockquote>
SWIG provides a simple technique for doing this as illustrated in the following interface file :<p>
<p>
<blockquote><pre>%module pde
%{
#include "pde.h"
%}
%include pde.h

// Add a few "helper" functions to extract grid data 
%{
    double  Grid2d_get(Grid2d *g, int i, int j) {
      return g-&gt;data[i][j];
    }
    void    Grid2d_set(Grid2d *g, int i, int j, double val) {
      g-&gt;data[i][j] = val;
    }
%}

// Now add these helper functions as methods of Grid2d

%addmethods Grid2d {
    double get(int i, int j);              // Gets expanded to Grid2d_get()
    void   set(int i, int j, double val);  // Gets expanded to Grid2d_set()
}
</pre></blockquote>
<p>
The <tt>%addmethods</tt> directive tells SWIG that you want to add new functions to an existing C++ class or C structure for the purposes of building an interface.   In reality, SWIG leaves the original C++ class unchanged, but the resulting Python interface will have some new functions that appear to be class members.<p>
<p>
SWIG uses a naming convention for adding methods to a class.  If you have a class <tt>Foo</tt> and you add a member function <tt>bar(args),</tt> SWIG will look for a function called <tt>Foo_bar(this,args)</tt> that implements the desired functionality.   You can write this function yourself, as in the previous interface file, but you can also just supply the code immediately after a declaration like this :<p>
<blockquote><pre>
%module pde
%{
#include "pde.h"
%}
%include pde.h

// Add some new accessor methods to the Grid2D class
%addmethods Grid2d {
  double get(int i, int j) {
    return self-&gt;data[i][j];
  };
  void set(int i, int j, double val) {
    self-&gt;data[i][j] = val;
  };
};

</pre></blockquote>
<p>
In this case, SWIG will take the supplied code, and automatically generate a function for the method.  The special variable "<tt>self</tt>" is used to hold a pointer to the corresponding object.  The <tt>self </tt>pointer is exactly like the C++ "<tt>this</tt>" pointer, except that the name has been changed in order to remind you that you aren't really writing a real class member function.  (Actually, the real reason we can't use "this" is because the C++ compiler will start complaining!)<p>
<p>
 Finally, it is worth noting that the <tt>%addmethods</tt> directive may also be used inside a class definition like this :<p>
<p>
<blockquote><pre>struct Grid2d {
  Grid2d(int ni, int nj);
  ~Grid2d();
  double **data;
  int      xpoints;
  int      ypoints;
  %addmethods {
	double get(int i, int j);
	void   set(int i, int j, double value);
  }
};

</pre></blockquote>
This latter case is really only useful if the C++ class definition is included in the SWIG interface file itself.   If you are pulling the class definition out of a separate file or a C++ header file, using a separate <tt>%addmethods</tt> directive is preferable.  It doesn't matter if the <tt>%addmethods</tt> directive appears before or after the real class definition--SWIG will correctly associate the two definitions.<p>
<p>
Okay, enough talk.  By adding the set/get functions as methods, we can now change our Python script to look like this (changes are underlined) :<p>
<p>
<blockquote><pre># An example using our new set/get functions

from pde import *

# Set up an initial condition

def initcond(h):
	h.set_temp(0.0)
	nx = h.grid.xpoints
	for i in range(0,nx):
		h.grid.set(i,0,1.0)         # Note changed interface

# Dump out to a file
def dump(h,filename):
	f = open(filename,"w")
	nx = h.grid.xpoints
	ny = h.grid.ypoints
	for i in range(0,nx):
		for j in range(0,ny):
			f.write(str(h.grid.get(i,j))+"\n")
	f.close()

# Set up a problem and run it

h = Heat2d(50,50)
initcond(h)
fileno = 1

for i in range(0,25):
	h.solve(100)
	h.dump("Dat"+str(fileno))
	print "time = ", h.time
	fileno = fileno+1

</pre></blockquote>
<p>
Now it's starting to look a little better, but we can do even better...<p>
<a name="n40"></a><h3> Implementing special Python methods in C</h3>
Now that you're getting into the spirit of things, let's make it so that we can access our <tt>Grid2D</tt> data like a Python array.  As it turns out, we can do this with a little trickery in the SWIG interface file.  Don't forget to put on your Python wizard cap...<p>
<p>
<blockquote><pre>// SWIG interface file with Python array methods added
%module pde
%{
#include "pde.h"
%}

%include pde.h

%inline %{
  // Define a new Grid2d row class 
  struct Grid2dRow {
    Grid2d *g;       // Grid
    int    row;      // Row number
    // These functions are used by Python to access sequence types (lists, tuples, ...)
    double __getitem__(int i) {
      return g-&gt;data[row][i];
    };
    void __setitem__(int i, double val) {
      g-&gt;data[row][i] = val;
    };
  };
%}

// Now add a __getitem__ method to Grid2D to return a row
%addmethods Grid2d {
  Grid2dRow __getitem__(int i) {
    Grid2dRow r;
    r.g = self;
    r.row = i;
    return r;
  };
};
</pre></blockquote>
<p>
We have now replaced our get/set functions with<tt> the __getitem__</tt> and <tt>__setitem__</tt> functions that Python needs to access arrays.  We have also added a special <tt>Grid2dRow</tt> class.  This is needed to allow us to make a funny kind of "multidimensional" array in Python (this may take a few minutes of thought to figure out). Using this new interface file, we can now write a Python script like this :<p>
<p>
<blockquote><pre># An example script using our array access functions

from pde import *

# Set up an initial condition

def initcond(h):
	h.set_temp(0.0)
	nx = h.grid.xpoints
	for i in range(0,nx):
		h.grid[i][0] = 1.0            # Note nice array access

# Set up a problem and run it

h = Heat2d(50,50)
initcond(h)
fileno = 1

for i in range(0,25):
	h.solve(100)
	h.dump("Dat"+str(fileno))
	print "time = ", h.time
	fileno = fileno+1

# Calculate average temperature over the region

sum = 0.0
for i in range(0,h.grid.xpoints):
	for j in range(0,h.grid.ypoints):
		sum = sum + h.grid[i][j]        # Note nice array access

avg = sum/(h.grid.xpoints*h.grid.ypoints)

print "Avg temperature = ",avg
</pre></blockquote>
<a name="n41"></a><h3> Summary (so far)</h3>
In our first example, we have taken a very simple C++ problem and wrapped it into a Python module.  With a little extra work, we have been able to provide array type access to our C++ data from Python and to write some computationally intensive operations in C++.    At this point, it would easy to write all sorts of Python scripts to set up problems, run simulations, look at the data, and to debug new operations implemented in C++.   <p>
<a name="n7"></a><h2> Wrapping a C library</h2>
In this next example, we focus on wrapping the gd-1.2 library.  gd is public domain library for fast GIF image creation written by Thomas Boutell and available on the internet.   gd-1.2 is copyright 1994,1995, Quest Protein Database Center, Cold Spring Harbor Labs.  This example assumes that you have gd-1.2 available, but you can use the ideas here to wrap other kinds of C libraries.<p>
<a name="n42"></a><h3> Preparing a module</h3>
Wrapping a C library into a Python module usually involves working with the C header files associated with a particular library.  In some cases, a header file can be used directly (without modification) with SWIG.  Other times, it may be necessary to copy the header file into a SWIG interface file and make a few touch-ups and modifications. In either case, it's usually not too difficult.<p>
<p>
To make a module, you can use the following checklist :<p>
<p>
<ul>
<li>Locate the header files associated with a package
<li>Look at the contents of the header files to see if SWIG can handle them.  In particular, SWIG can not handle excessive use of C preprocessor macros, or non-ANSI C syntax. The best way to identify problems is to simply run SWIG on the file and see what errors (if any) get reported.
<li>Make a SWIG interface file for your module specifying the name of the module, the appropriate header files, and any supporting documentation that you would like to provide.
<li>If the header file is clean, simply use SWIG's <tt>%include</tt> directive.  If not, paste the header file into your interface file and edit it until SWIG can handle it.
<li>Clean up the interface by possibly adding supporting code, deleting unnecessary functions, and eliminating clutter.
<li>Run SWIG and compile.
</ul>
<p>
In the case of the gd library, we can simply use the following SWIG interface file :<p>
<p>
<blockquote><pre>%module gd
%{
#include "gd.h"
%}

%section "gd-1.2",ignore
%include "gd.h"

// These will come in handy later
FILE *fopen(char *, char *);
void fclose(FILE *f);

</pre></blockquote>
<p>
In this file, we first tell SWIG to put all of the gd functions in a separate documentation section and to ignore all comments.   This usually helps clean up the documentation when working with raw header files.   Next, we simply include the contents of "gd.h" directly.   Finally, we provide wrappers to <tt>fopen()</tt> and <tt>fclose()</tt> since these will come in handy in our Python interface.<p>
<p>
If we give this interface file to SWIG, we will get the following output :<p>
<p>
<blockquote><pre>% swig -python -shadow  -I/usr/local/include gd.i
Generating wrappers for Python
/usr/local/include/gd.h : Line 32.  Arrays not currently supported (ignored).
/usr/local/include/gd.h : Line 33.  Arrays not currently supported (ignored).
/usr/local/include/gd.h : Line 34.  Arrays not currently supported (ignored).
/usr/local/include/gd.h : Line 35.  Arrays not currently supported (ignored).
/usr/local/include/gd.h : Line 41.  Arrays not currently supported (ignored).
/usr/local/include/gd.h : Line 42.  Arrays not currently supported (ignored).
%

</pre></blockquote>
While SWIG was able to handle most of the header file, it also ran into a few unsupported declarations---in this case, a few data structures with array members.  However, the warning messages also tell us that these declarations have simply been ignored.   Thus, we can choose to continue and build our interface anyways.  As it turns out in this case, the ignored declarations are of little or no consequence so we can ignore the warnings.<p>
<p>
If SWIG is unable to process a raw header file or if you would like to eliminate the warning messages, you can structure your interface file as follows :<p>
<p>
<blockquote><pre>%module gd
%{
#include "gd.h"
%}

%section "gd-1.2",ignore

... paste the contents of gd.h here and remove problems ...

// A few extra support functions

FILE *fopen(char *, char *);
void fclose(FILE *f);

</pre></blockquote>
This latter option requires a little more work (since you need to paste the contents of gd.h into the file and edit it), but is otherwise not much more difficult to do.   For highly complex C libraries or header files that go overboard with the C preprocessor, you may need to do this more often.  <p>
<a name="n43"></a><h3> Using the gd module</h3>
Now, that we have created a module from the gd library, we can use it in Python scripts.  The following script makes a simple image of a black background with a white line drawn on it.  Notice how we have used our wrapped versions of <tt>fopen()</tt> and <tt>fclose()</tt> to create a FILE handle for use in the gd library (there are also ways to use Python file objects, but this is described later).<p>
<p>
<blockquote><pre># Simple gd program

from gd import *

im = gdImageCreate(64,64)
black = gdImageColorAllocate(im,0,0,0)
white = gdImageColorAllocate(im,255,255,255)
gdImageLine(im,0,0,63,63,white)
out = fopen("test.gif","w")
gdImageGif(im,out)
fclose(out)
gdImageDestroy(im)

</pre></blockquote>
<p>
That was simple enough--and it only required about 5 minutes of work.  Unfortunately, our gd module still has a few problems...<p>
<a name="n44"></a><h3> Extending and fixing the gd module</h3>
While our first attempt at wrapping gd works for simple functions, there are a number of problems.   For example, the gd-1.2 library contains the following function for drawing polygons :<p>
<p>
<blockquote><pre>void gdImagePolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color);

</pre></blockquote>
The <tt>gdImagePtr</tt> type is created by another function in our module and the parameters <tt>pointsTotal</tt> and <tt>color</tt> are simple integers.  However, the 2nd argument is a pointer to an array of points as defined by the following data structure in the gd-1.2 header file :<p>
<p>
<blockquote><pre>typedef struct {
	int x, y;
} gdPoint, *gdPointPtr;

</pre></blockquote>
Unfortunately, there is no way to create a gdPoint in Python and consequently no way to call the gdImagePolygon function.   A temporary setback, but one that is not difficult to solve using the  <tt>%addmethods</tt> directive as follows :<p>
<blockquote><pre>
%module gd
%{
#include "gd.h"
%}

%include "gd.h"

// Fix up the gdPoint structure a little bit
%addmethods gdPoint {
  // Constructor to make an array of "Points"
  gdPoint(int npoints) {
    return (gdPoint *) malloc(npoints*sizeof(gdPoint));
  };
  // Destructor to destroy this array
  ~gdPoint() {
    free(self);
  };
  // Python method for array access
  gdPoint *__getitem__(int i) {
    return self+i;
  };
};

FILE *fopen(char *, char *);
void fclose(FILE *f);

</pre></blockquote>
With these simple additions, we can now create arrays of points and use the polygon function as follows :<p>
<p>
<blockquote><pre># Simple gd program

from gd import *

im = gdImageCreate(64,64)
black = gdImageColorAllocate(im,0,0,0)
white = gdImageColorAllocate(im,255,255,255)

pts = gdPoint(3);                   # Create an array of Points
pts[0].x,pts[0].y = (5,5)           # Assign a set of points
pts[1].x,pts[1].y = (60,25)
pts[2].x,pts[2].y = (16,60)

gdImagePolygon(im,pts,3,white)      # Draw a polygon from our array of points
out = fopen("test.gif","w")
gdImageGif(im,out)
fclose(out)
gdImageDestroy(im)

</pre></blockquote>
<a name="n45"></a><h3> Building a simple 2D imaging class</h3>
Now it's time to get down to business.  Using our gd-1.2 module, we can write a simple 2D imaging class that hides alot of the underlying details and provides scaling, translations, and a host of other operations.  (It's a fair amount code, but an interesting example of how one can take a simple C library and turn it into something that looks completely different).<p>
<p>
<p>
<blockquote><pre># image.py
# Generic 2D Image Class
#
# Built using the 'gd-1.2' library by Thomas Boutell
#

import gd

class Image:
	def __init__(self,width,height,xmin=0.0,ymin=0.0,xmax=1.0,ymax=1.0):
		self.im = gd.gdImageCreate(width,height)
		self.xmin   = xmin
		self.ymin   = ymin
		self.xmax   = xmax
		self.ymax   = ymax
		self.width  = width
		self.height = height
		self.dx     = 1.0*(xmax-xmin)
		self.dy     = 1.0*(ymax-ymin)
		self.xtick  = self.dx/10.0
		self.ytick  = self.dy/10.0
		self.ticklen= 3
		self.name   = "image.gif"
		gd.gdImageColorAllocate(self.im,0,0,0)        # Black
		gd.gdImageColorAllocate(self.im,255,255,255)  # White
		gd.gdImageColorAllocate(self.im,255,0,0)      # Red
		gd.gdImageColorAllocate(self.im,0,255,0)      # Green
		gd.gdImageColorAllocate(self.im,0,0,255)      # Blue

	def __del__(self):
		print "Deleting"
		gd.gdImageDestroy(self.im)
	
	# Dump out this image to a file
	def write(self,name="NONE"):
		if name == "NONE":
			name = self.name
		f = gd.fopen(name,"w")
		gd.gdImageGif(self.im,f)
		gd.fclose(f)
		self.name = name
	
	# Virtual method that derived classes define
	def draw(self):
		print "No drawing method specified."

	# A combination of write and draw
	def show(self,filename="NONE"):
		self.draw()
		self.write(filename)

	# Load up a colormap from a Python array of (R,G,B) tuples
	def colormap(self, cmap):
		for i in range(0,255):
			gd.gdImageColorDeallocate(self.im,i)
		for c in cmap:
			gd.gdImageColorAllocate(self.im,c[0],c[1],c[2])

	# Change viewing region
	def region(self,xmin,ymin,xmax,ymax):
		self.xmin = xmin
		self.ymin = ymin
		self.xmax = xmax
		self.ymax = ymax
		self.dx     = 1.0*(xmax-xmin)
		self.dy     = 1.0*(ymax-ymin)

	# Transforms a 2D point into screen coordinates
	def transform(self,x,y):
		npt = []
		ix = (x-self.xmin)/self.dx*self.width + 0.5
		iy = (self.ymax-y)/self.dy*self.height + 0.5
		return (ix,iy)

	# A few graphics primitives
	def clear(self,color):
		gd.gdImageFilledRectangle(self.im,0,0,self.width,self.height,color)

	def plot(self,x,y,color):
		ix,iy = self.transform(x,y)
		gd.gdImageSetPixel(self.im,ix,iy,color)

	def line(self,x1,y1,x2,y2,color):
		ix1,iy1 = self.transform(x1,y1)
		ix2,iy2 = self.transform(x2,y2)
		gd.gdImageLine(self.im,ix1,iy1,ix2,iy2,color)

	def box(self,x1,y1,x2,y2,color):
		ix1,iy1 = self.transform(x1,y1)
		ix2,iy2 = self.transform(x2,y2)
		gd.gdImageRectangle(self.im,ix1,iy1,ix2,iy2,color)

	def solidbox(self,x1,y1,x2,y2,color):
		ix1,iy1 = self.transform(x1,y1)
		ix2,iy2 = self.transform(x2,y2)
		gd.gdImageFilledRectangle(self.im,ix1,iy1,ix2,iy2,color)
	
	def arc(self,cx,cy,w,h,s,e,color):
		ix,iy = self.transform(cx,cy)
		iw = (x - self.xmin)/self.dx * self.width
		ih = (y - self.ymin)/self.dy * self.height
		gd.gdImageArc(self.im,ix,iy,iw,ih,s,e,color)

	def fill(self,x,y,color):
		ix,iy = self.transform(x,y)
		gd.gdImageFill(self,ix,iy,color)

	def axis(self,color):
		self.line(self.xmin,0,self.xmax,0,color)
		self.line(0,self.ymin,0,self.ymax,color)
		x = -self.xtick*(int(-self.xmin/self.xtick)+1)
		while x &lt;= self.xmax:
		    ix,iy = self.transform(x,0)
		    gd.gdImageLine(self.im,ix,iy-self.ticklen,ix,iy+self.ticklen,color)
		    x = x + self.xtick
		y = -self.ytick*(int(-self.ymin/self.ytick)+1)
		while y &lt;= self.ymax:
		    ix,iy = self.transform(0,y)
		    gd.gdImageLine(self.im,ix-self.ticklen,iy,ix+self.ticklen,iy,color)
		    y = y + self.ytick

	# scalex(s).  Scales the x-axis.  s is given as a scaling factor
	def scalex(self,s):
		xc = self.xmin + self.dx/2.0
		dx = self.dx*s
		xmin = xc - dx/2.0
		xmax = xc + dx/2.0
		self.region(xmin,self.ymin,xmax,self.ymax)

	# scaley(s).  Scales the y-axis.  
	def scaley(self,s):
		yc = self.ymin + self.dy/2.0
		dy = self.dy*s
		ymin = yc - dy/2.0
		ymax = yc + dy/2.0
		self.region(self.xmin,ymin,self.xmax,ymax)

	# Zooms a current image.  s is given as a percent 
	def zoom(self,s):
		s = 100.0/s
		self.scalex(s)
		self.scaley(s)

	# Move image left.  s is given in range 0,100. 100 moves a full screen left
	def left(self,s):
		dx = self.dx*s/100.0
		xmin = self.xmin + dx
		xmax = self.xmax + dx
		self.region(xmin,self.ymin,xmax,self.ymax)

	# Move image right.  s is given in range 0,100. 100 moves a full screen right
	def right(self,s):
		self.left(-s)

	# Move image down.  s is given in range 0,100. 100 moves a full screen down
	def down(self,s):
		dy = self.dy*s/100.0
		ymin = self.ymin + dy
		ymax = self.ymax + dy
		self.region(self.xmin,ymin,self.xmax,ymax)

	# Move image up.  s is given in range 0,100. 100 moves a full screen up
	def up(self,s):
		self.down(-s)

	# Center image
	def center(self,x,y):
		self.right(50-x)
		self.up(50-y)
	

</pre></blockquote>
Our image class provides a number of methods for creating images, plotting points, making lines, and other graphical objects.  We have also provided some methods for moving and scaling the image.   Now, let's use this image class to do some interesting things :<p>
<p>
<a name="n46"></a><h3> A mathematical function  plotter </h3>
Here's  a simple class that can be used to plot mathematical functions :<p>
<p>
<blockquote><pre># funcplot.py

from image import *

class PlotFunc(Image):
	def __init__(self,func,xmin,ymin,xmax,ymax,width=500,height=500):
		Image.__init__(self,width,height,xmin,ymin,xmax,ymax)
		self.func = func            # The function being plotted
		self.npoints = 100          # Number of samples
		self.color = 1
	def draw(self):
		self.clear(0)
		lastx = self.xmin
		lasty = self.func(lastx)
		dx = 1.0*(self.xmax-self.xmin)/self.npoints
		x = lastx+dx
		for i in range(0,self.npoints):
			y = self.func(x)
			self.line(lastx,lasty,x,y,self.color)
			lastx = x
			lasty = y
			x = x + dx
		self.axis(1)

</pre></blockquote>
Most of the functionality is implemented in our base image class so this is pretty simple.  However, if we wanted to make a GIF image of a mathematical function, we could just do this :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; from funcplot import *
&gt;&gt;&gt; import math
&gt;&gt;&gt; p = PlotFunc(lambda x: 0.5*math.sin(x)+0.75*math.sin(2*x)-0.6*math.sin(3*x),
                 -10,-2,10,2)
&gt;&gt;&gt; p.show("plot.gif")

</pre></blockquote>
Which would produce the following GIF image :<p>
<p><center><img src="ch9.1.png"></center><p>
<p>
<p>
<a name="n47"></a><h3> Plotting an unstructured mesh</h3>
Of course, perhaps we want to plot something a little more complicated like a mesh. Recently, a colleague came to me with some unstructured mesh data contained in a pair of ASCII formatted files.   These files contained a collection of points, and a list of connectivities defining a mesh on these points.   Reading and plotting this data in Python turned out to be relatively easy using the following script and our image base class :<p>
<p>
<blockquote><pre># plotmesh.py
# Plots an unstructured mesh stored as an ASCII file
from image import *
import string

class PlotMesh(Image):
	def __init__(self,filename,xmin,ymin,xmax,ymax,width=500,height=500):
		Image.__init__(self,width,height,xmin,ymin,xmax,ymax)
		# read in a mesh file in pieces
		pts = []
		# Read in data points
		atoi = string.atoi
		atof = string.atof
		f = open(filename+".pts","r")
		npoints = atoi(f.readline())
		for i in range(0,npoints):
			l = string.split(f.readline())
			pts.append((atof(l[0]),atof(l[1])))
		f.close()	

		# Read in mesh data
		f = open(filename+".tris","r")
		ntris = string.atoi(f.readline())
		tris = [ ]
		for i in range(0,ntris):
			l = string.split(f.readline())
			tris.append((atoi(l[0])-1,atoi(l[1])-1,atoi(l[2])-1,atoi(l[3])))
		f.close()

	# Set up local attributes
		self.pts = pts
		self.npoints = npoints
		self.tris = tris
		self.ntris = ntris

	# Draw mesh
	def draw(self):
		self.clear(0);
		i = 0
		while i &lt; self.ntris:
			tri = self.tris[i]
			pt1 = self.pts[tri[0]]
			pt2 = self.pts[tri[1]]
			pt3 = self.pts[tri[2]]
			# Now draw the mesh
			self.triangle(pt1[0],pt1[1],pt2[0],pt2[1],pt3[0],pt3[1],tri[3]);
			i = i + 1

	# Draw a triangle
	def triangle(self,x1,y1,x2,y2,x3,y3,color):
		self.line(x1,y1,x2,y2,color)
		self.line(x2,y2,x3,y3,color)
		self.line(x3,y3,x1,y1,color)

</pre></blockquote>
This class simply reads the data into a few Python lists, has a drawing function for making a plot, and adds a special method for making triangles.  Making a plot is now easy, just do this :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; from plotmesh.py import *
&gt;&gt;&gt; mesh = PlotMesh("mesh",5,0,35,25)
&gt;&gt;&gt; mesh.show("mesh.gif")

</pre></blockquote>
This produces the following GIF image :<p>
<p><center><img src="ch9.2.png"></center><p>
<p>
<p>
When run interactively, we can also use simple commands to zoom in and move the image around. For example :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; mesh = PlotMesh("mesh",5,0,35,25)
&gt;&gt;&gt; mesh.zoom(200)                   # Enlarge by 200%
&gt;&gt;&gt; mesh.left(50)                    # Move image half a screen to left
&gt;&gt;&gt; mesh.show()
&gt;&gt;&gt;
</pre></blockquote>
<p>
While a Python-only implementation would be unsuitable for huge datasets, performance critical operations could be moved to C and used in conjunction with our Image base class.  <p>
<a name="n48"></a><h3> From C to SWIG to Python</h3>
This example illustrates a number of things that are possible with SWIG and Python.  First, it is usually relatively easy to build a Python interface to an existing C library.    With a little extra work, it is possible to improve the interface by adding a few support functions such as our Point  extensions.  Finally, once in Python, it is possible to encapsulate C libraries in new kinds of Python objects and classes.  We built a simple Image base class and used it to plot mathematical functions and unstructured 2D mesh data---two entirely different tasks, yet easily accomplished with a small amount of Python code.   If we later decided to use a different C library such as OpenGL, we could wrap it in SWIG, change the Image base class appropriately , and use the function and mesh plotting examples  without modification.   I think this is pretty cool.<p>
<a name="n8"></a><h2> Putting it all together</h2>
Finally, let's combine our heat equation solver and graphics module into a single application.   To do this, we first need to know how to combine two different SWIG generated modules. When different SWIG modules need to be combined, there are a number of things you can do.<p>
<a name="n49"></a><h3> Merging modules</h3>
Two SWIG modules can be combined into a single module if you make an interface file like this :<p>
<p>
<blockquote><pre>%module package
%include pde.i
%include gd.i
</pre></blockquote>
<p>
This will combine everything in both interface files into a single super-module called "package". The advantage to this approach is that it is extremely quick and easy.  The disadvantage is that the module names of "pde" and "gd" will be lost.  If you had a bunch of scripts that relied on those names, they would no longer work.    Thus, combining modules in this way is probably only a good idea if the modules are closely related.<p>
<a name="n50"></a><h3> Using dynamic loading</h3>
If your system supports dynamic loading, you can build each SWIG module into a separate dynamically loadable module and load each one individually into Python.  This is the preferred approach if it is supported on your system.   SWIG wrapper files declare virtually everything as "static" so using dynamic loading with multiple SWIG generated modules will not usually cause any namespace clashes.  <p>
<a name="n51"></a><h3> Use static linking</h3>
As an alternative to dynamic loading, you can use a special form of the <tt>%module</tt> directive as follows :<p>
<p>
<blockquote><pre>%module package, pdec, gdc
%include embed.i

</pre></blockquote>
This will build a static version of Python with 3 C extension modules added (<tt>package</tt>, <tt>pdec</tt>, and <tt>gdc</tt>).  When using this technique, the names of the modules refer to the low-level SWIG generated C/C++ modules.  Since shadow classes are being used, these modules must have an extra `c' appended to the name (thus, "pdec" and "gdc" instead of "pde" and "gd").   The extra modules specified with the <tt>%modules</tt> directive do not necessarily have to be SWIG-generated modules. In practice, almost any kind of Python module can be listed here.  It should also be noted that extra modules names are completely ignored if the <tt>embed.i </tt>library file is not used.<p>
<a name="n52"></a><h3> Building large  multi-module systems</h3>
By default, SWIG includes the C code for the SWIG type-checker and variable linking into every module.  However, when, building systems involving large numbers of SWIG modules,  common code such as the SWIG pointer type-checker and variable linking extensions can be shared if you run SWIG with the <tt>-c</tt> option.  For example :<p>
<p>
<blockquote><pre>% swig -c -python graphics.i
% swig -c -python network.i
% swig -c -python analysis.i
% swig -c -python math.i
% gcc -c graphics_wrap.c network_wrap.c analysis_wrap.c math_wrap.c
% ld -shared graphics_wrap.o -lswigpy -o graphicsmodule.so 
% ld -shared network_wrap.o -lswigpy -o networkmodule.so 
% ld -shared analysis_wrap.o -lswigpy -o analysismodule.so 
% ld -shared math_wrap.o -o -lswigpy mymathmodule.so 

</pre></blockquote>
<tt>swigpy</tt> is a special purpose library that contains the SWIG pointer type checker and other support code (see the <tt>Misc</tt> subdirectory of the SWIG distribution). When used in this manner, the same support code will be used for all of the modules.   The <tt>swigpy</tt> library can also be applied when static linking is being used.  See the Advanced Topics chapter for more information about using SWIG with multiple modules.<p>
<a name="n53"></a><h3> A complete application</h3>
The following Python script shows an application that combines our C++ heat equation solver, our gd library, and our Image base class that we developed. <p>
<p>
<blockquote><pre># Solve the heat equation.
# Make a series of data files
# Make a movie of GIF images

from pde import *
from image import *
import string

# Image class
class HeatImg(Image):
	def __init__(self,h,width=300,height=300):
		Image.__init__(self,width,height,0.0,0.0,1.0,1.0)
		self.h = h
		# Create a greyscale colormap
		cmap = []
		for i in range(0,255):
			cmap.append((i,i,i))
		self.colormap(cmap)
		self.cmin = 0.0
		self.cmax = 1.0
		self.imgno = 1
	def draw(self):
		self.clear(0)
		dx = 1.0/(self.h.grid.xpoints-2)
		dy = 1.0/(self.h.grid.ypoints-2)
		i = 1
		x = 0.0
		while i &lt; self.h.grid.xpoints:
			j = 1;
			y = 0.0
			while j &lt; self.h.grid.ypoints:
				c = int((self.h.grid[i][j]-self.cmin)/(self.cmax- 
					 self.cmin)*255)
				self.solidbox(x,y+dy,x+dx,y,c)
				j = j + 1
				y = y + dy
			i = i + 1
			x = x + dx
		self.name = "image"+string.zfill(self.imgno,4)+".gif"
		self.imgno = self.imgno+1

# Set up an initial condition
def initcond(h):
	h.set_temp(0.0)
	nx = h.grid.xpoints
	for i in range(0,nx):
		h.grid[i][0] = 1.0

# Set up a problem and run it
h = Heat2d(50,50)

# Make an image object
img = HeatImg(h)

initcond(h)
fileno = 1

# Run it
for i in range(0,25):
	h.solve(100)
	h.dump("Dat"+str(fileno))
	img.show()
	print "time = ", h.time
	fileno = fileno+1

# Calculate average temperature and exit
sum = 0.0
for i in range(0,h.grid.xpoints):
	for j in range(0,h.grid.ypoints):
		sum = sum + h.grid[i][j]
avg = sum/(h.grid.xpoints*h.grid.ypoints)
print "Avg temperature = ",avg
</pre></blockquote>
<p>
When run, we now get a collection of datafiles and series of images like this :<p>
<p><center><img src="ch9.3.png"></center><p>
<p>
<p>
Thus, we have a simple physics application that only takes about 1 page of Python code, runs a simulation, creates data files, and a movie of images.  We can easily change any aspect of the simulation, interactively query variables and examine data.  New procedures can be written and tested in Python and later implemented in C++ if needed.   More importantly, we have an application that is actually fun to use and modify (well, at least I think so).<p>
<a name="n9"></a><h2> Exception handling </h2>
The SWIG <tt>%except</tt> directive can be used to create a user-definable exception handler in charge of converting exceptions in your C/C++ program into Python exceptions.  The chapter on exception handling contains more details, but suppose you have a C++ class like the following :<p>
<blockquote><pre>
class RangeError {};   // Used for an exception

class DoubleArray {
  private:
    int n;
    double *ptr;
  public:
    // Create a new array of fixed size
    DoubleArray(int size) {
      ptr = new double[size];
      n = size;
    }
    // Destroy an array
    ~DoubleArray() {
       delete ptr;
    }
    // Return the length of the array
    int   length() {
      return n;
    }

    // Get an item from the array and perform bounds checking.
    double getitem(int i) {
      if ((i &gt;= 0) &amp;&amp; (i &lt; n))
        return ptr[i];
      else
        throw RangeError();
    }

    // Set an item in the array and perform bounds checking.
    void setitem(int i, double val) {
      if ((i &gt;= 0) &amp;&amp; (i &lt; n))
        ptr[i] = val;
      else {
        throw RangeError();
      }
    }
  };
</pre></blockquote>
<p>
The functions associated with this class can throw a range exception for an out-of-bounds array access.   We can catch this in our Python extension by specifying the following in an interface file :<p>
<p>
<blockquote><pre>%except(python) {
  try {
    $function
  }
  catch (RangeError) {
    PyErr_SetString(PyExc_IndexError,"index out-of-bounds");
    return NULL;
  }
}

</pre></blockquote>
When the C++ class throws a RangeError exception, our wrapper functions will catch it, turn it into a Python exception, and allow a graceful death as opposed to just having some sort of mysterious program crash.     Since SWIG's exception handling is user-definable, we are not limited to C++ exception handling.   Please see the chapter on exception handling for more details and using the <tt>exception.i</tt> library for writing language-independent exception handlers.<p>
<p>
Python exceptions can be raised using the <tt>PyErr_SetString()</tt> function as shown above.  The following table provides a list of the different Python exceptions available.<p>
<center><img src="ch9.table.1.png"></center><p>
<p>
<a name="n10"></a><h2> Remapping C datatypes with typemaps</h2>
This section describes how SWIG's treatment of various C/C++ datatypes can be remapped using the SWIG <tt>%typemap</tt> directive.   While not required, this section assumes some familiarity with  Python's C API.   The reader is advised to consult  the Python reference manual or one of the books on Python.  A glance at the chapter on SWIG typemaps will also be useful.  <p>
<a name="n54"></a><h3> What is a typemap?</h3>
A typemap is mechanism by which SWIG's processing of a particular C datatype can be overridden.   A simple typemap might look like this :<p>
<p>
<blockquote><pre>%module example

%typemap(python,in) int {
	$target = (int) PyLong_AsLong($source);
	printf("Received an integer : %d\n",$target);
}
extern int fact(int n);
</pre></blockquote>
<p>
Typemaps require a language  name,  method name, datatype, and conversion code.  For Python, "python" should be used as the language name. The "in" method in this example refers to an input argument of a function. The datatype `int' tells SWIG that we are remapping integers.  The supplied code is used to convert from a <tt>PyObject *</tt> to the corresponding C datatype.  Within the supporting C code, the variable <tt>$source</tt> contains the source data (the <tt>PyObject</tt> in this case) and <tt>$target</tt> contains the destination of a conversion.  <p>
<p>
When this example is compiled into a Python module, it will operate as follows :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; from example import *
&gt;&gt;&gt; fact(6)
Received an integer : 6
720
</pre></blockquote>
<p>
A full discussion of typemaps can be found in the main SWIG users reference.  We will primarily be concerned with Python typemaps here.<p>
<a name="n55"></a><h3> Python typemaps</h3>
The following typemap methods are available to Python modules :<p>
<p>
<tt>%typemap(python,in)	</tt>Converts Python objects to input function arguments<p>
<tt>%typemap(python,out)</tt>	Converts return value of a C function to a Python object<p>
<tt>%typemap(python,varin)	</tt>Assigns a global variable from a Python object<p>
<tt>%typemap(python,varout)</tt>	Returns a global variable as a Python object<p>
<tt>%typemap(python,freearg)</tt>	Cleans up a function argument (if necessary)<p>
<tt>%typemap(python,argout)</tt>	Output argument processing<p>
<tt>%typemap(python,ret)</tt>	Cleanup of function return values<p>
<tt>%typemap(python,const)</tt>	Creation of Python constants<p>
<tt>%typemap(memberin)</tt>	Setting of C++ member data<p>
<tt>%typemap(memberout)</tt>	Return of C++ member data<p>
<tt>%typemap(python,check)</tt>	Checks function input values.<p>
<a name="n56"></a><h3> Typemap variables</h3>
The following variables may be used within the C code used in a typemap:<p>
<p>
<tt>$source</tt>	Source value of a conversion<p>
<tt>$target</tt>	Target of conversion (where the result should be stored)<p>
<tt>$type</tt>	C datatype being remapped<p>
<tt>$mangle</tt>	Mangled version of data (used for pointer type-checking)<p>
<tt>$value</tt>	Value of a constant (const typemap only)<p>
<a name="n57"></a><h3> Name based type conversion</h3>
Typemaps are based both on the datatype and an optional name attached to a datatype.   For example :<p>
<p>
<blockquote><pre>%module foo

// This typemap will be applied to all char ** function arguments
%typemap(python,in) char ** { ... }

// This typemap is applied only to char ** arguments named `argv'
%typemap(python,in) char **argv { ... }

</pre></blockquote>
In this example, two typemaps are applied to the <tt>char **</tt> datatype.  However, the second typemap will only be applied to arguments named `<tt>argv</tt>'.  A named typemap will always override an unnamed typemap.<p>
<p>
Due to the name-based nature of typemaps, it is important to note that typemaps are independent of typedef declarations.  For example :<p>
<p>
<blockquote><pre>%typemap(python, in) double {
	... get a double ...
}
void foo(double);            // Uses the above typemap
typedef double Real;
void bar(Real);              // Does not use the above typemap (double != Real)

</pre></blockquote>
To get around this problem, the <tt>%apply</tt> directive can be used as follows :<p>
<blockquote><pre>
%typemap(python,in) double {
	... get a double ...
}
void foo(double);

typedef double Real;         // Uses typemap
%apply double { Real };      // Applies all "double" typemaps to Real.
void bar(Real);              // Now uses the same typemap.
</pre></blockquote>
<a name="n58"></a><h3> Converting  Python list to a char ** </h3>
A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings.   The following SWIG interface file allows a Python list object to be used as a <tt>char **</tt> object.<p>
<p>
<blockquote><pre>%module argv

// This tells SWIG to treat char ** as a special case
%typemap(python,in) char ** {
  /* Check if is a list */
  if (PyList_Check($source)) {
    int size = PyList_Size($source);
    int i = 0;
    $target = (char **) malloc((size+1)*sizeof(char *));
    for (i = 0; i &lt; size; i++) {
      PyObject *o = PyList_GetItem($source,i);
      if (PyString_Check(o))
	$target[i] = PyString_AsString(PyList_GetItem($source,i));
      else {
	PyErr_SetString(PyExc_TypeError,"list must contain strings");
	free($target);
	return NULL;
      }
    }
    $target[i] = 0;
  } else {
    PyErr_SetString(PyExc_TypeError,"not a list");
    return NULL;
  }
}

// This cleans up the char ** array we malloc'd before the function call
%typemap(python,freearg) char ** {
  free((char *) $source);
}

// This allows a C function to return a char ** as a Python list
%typemap(python,out) char ** {
  int len,i;
  len = 0;
  while ($source[len]) len++;
  $target = PyList_New(len);
  for (i = 0; i &lt; len; i++) {
    PyList_SetItem($target,i,PyString_FromString($source[i]));
  }
}

// Now a few test functions
%inline %{
int print_args(char **argv) {
    int i = 0;
    while (argv[i]) {
         printf("argv[%d] = %s\n", i,argv[i]);
         i++;
    }
    return i;
}

// Returns a char ** list 

char **get_args() {
    static char *values[] = { "Dave", "Mike", "Susan", "John", "Michelle", 0};
    return &amp;values[0];
}
%}

</pre></blockquote>
When this module is compiled, our wrapped C functions now operate as follows :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; from argv import *
&gt;&gt;&gt; print_args(["Dave","Mike","Mary","Jane","John"])
argv[0] = Dave
argv[1] = Mike
argv[2] = Mary
argv[3] = Jane
argv[4] = John
5
&gt;&gt;&gt; get_args()
[`Dave', `Mike', `Susan', `John', `Michelle']
&gt;&gt;&gt;

</pre></blockquote>
Our type-mapping makes the Python interface to these functions more natural and easy to use.     <p>
<a name="n59"></a><h3> Converting a Python file object to a FILE *</h3>
In our previous example involving gd-1.2, we had to write wrappers around <tt>fopen()</tt> and <tt>fclose()</tt> so that we could provide gd with a <tt>FILE *</tt> pointer.  However, we could have used a typemap like this instead :<p>
<p>
<blockquote><pre>// Type mapping for grabbing a FILE * from Python

%typemap(python,in) FILE * {
  if (!PyFile_Check($source)) {
      PyErr_SetString(PyExc_TypeError, "Need a file!");
      return NULL;
  }
  $target = PyFile_AsFile($source);
}
</pre></blockquote>
<p>
Now, we can rewrite one of our earlier examples like this :<p>
<p>
<blockquote><pre># Simple gd program

from gd import *

im = gdImageCreate(64,64)
black = gdImageColorAllocate(im,0,0,0)
white = gdImageColorAllocate(im,255,255,255)
gdImageLine(im,0,0,63,63,white)
f = open("test.gif","w")               # Create a Python file object
gdImageGif(im,f)                       # Pass to a C function as FILE *
f.close()
gdImageDestroy(im)
</pre></blockquote>
<a name="n60"></a><h3> Using typemaps to return arguments</h3>
A common problem in some C programs is that values may be returned in arguments rather than in the return value of a function.  For example :<p>
<p>
<blockquote><pre>/* Returns a status value and two values in out1 and out2 */
int spam(double a, double b, double *out1, double *out2) {
	... Do a bunch of stuff ...
	*out1 = result1;
	*out2 = result2;
	return status;
};

</pre></blockquote>
A named typemap can be used to handle this case as follows :<p>
<p>
<blockquote><pre>%module outarg

// This tells SWIG to treat an double * argument with name 'OutValue' as
// an output value.  We'll append the value to the current result which 
// is guaranteed to be a List object by SWIG.

%typemap(python,argout) double *OutValue {
	PyObject *o;
	o = PyFloat_FromDouble(*$source);
	if ((!$target) || ($target == Py_None)) {
		$target = o;
	} else {
		if (!PyList_Check($target)) {
			PyObject *o2 = $target;
			$target = PyList_New(0);
			PyList_Append($target,o2);
			Py_XDECREF(o2);
		}
		PyList_Append($target,o);
		Py_XDECREF(o);
	}
}
int spam(double a, double b, double *OutValue, double *OutValue);

</pre></blockquote>
With this typemap, we first check to see if any result exists.  If so, we turn it into a list and append our new output value to it.   If this is the only result, we simply return it normally. For our sample function, there are three output values so the function will return a list of 3 elements.   As written, our function needs to take 4 arguments, the last two being pointers to doubles.   We may not want to pass anything into these arguments if they are only used to hold output values so we could change this as follows :<p>
<blockquote><pre>
%typemap(python,ignore) double *OutValue(double temp) {
	$target = &amp;temp;       /* Assign the pointer to a local variable */
}

</pre></blockquote>
Now, in a Python script,  we could do this :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; a = spam(4,5)
&gt;&gt;&gt; print a
[0, 2.45, 5.0]
&gt;&gt;&gt;
</pre></blockquote>
<a name="n61"></a><h3> Mapping Python tuples into small arrays</h3>
In some applications, it is sometimes desirable to pass small arrays of numbers as arguments. For example :<p>
<p>
<blockquote><pre>extern void set_direction(double a[4]);       // Set direction vector
</pre></blockquote>
<p>
This too, can be handled used typemaps as follows :<p>
<p>
<blockquote><pre>// Grab a 4 element array as a Python 4-tuple
%typemap(python,in) double[4](double temp[4]) {   // temp[4] becomes a local variable
  int i;
  if (PyTuple_Check($source)) {
    if (!PyArg_ParseTuple($source,"dddd",temp,temp+1,temp+2,temp+3)) {
      PyErr_SetString(PyExc_TypeError,"tuple must have 4 elements");
      return NULL;
    }
    $target = &amp;temp[0];
  } else {
    PyErr_SetString(PyExc_TypeError,"expected a tuple.");
    return NULL;
  }
}

</pre></blockquote>
This allows our <tt>set_direction</tt> function to be called from Python as follows :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; set_direction((0.5,0.0,1.0,-0.25))

</pre></blockquote>
Since our mapping copies the contents of a Python tuple into a C array, such an approach would not be recommended for huge arrays, but for small structures, this kind of scheme works fine.<p>
<a name="n62"></a><h3> Accessing array structure members</h3>
Consider the following data structure :<p>
<p>
<blockquote><pre>#define NAMELEN   32
typedef struct {
	char   name[NAMELEN];
	...
} Person;

</pre></blockquote>
By default, SWIG doesn't know how to the handle the name structure since it's an array, not a pointer.  In this case, SWIG will make the array member readonly.    However, member typemaps can be used to make this member writable from Python as follows :<p>
<p>
<blockquote><pre>%typemap(memberin) char[NAMELEN] {
	/* Copy at most NAMELEN characters into $target */
	strncpy($target,$source,NAMELEN);
}

</pre></blockquote>
Whenever a <tt>char[NAMELEN]</tt> type is encountered in a structure or class, this typemap provides a safe mechanism for setting its value.   An alternative implementation might choose to print an error message if the name was too long to fit into the field.<p>
<p>
It should be noted that the <tt>[NAMELEN]</tt> array size is attached to the typemap. A datatype involving some other kind of array would not be affected.   However, you can write a typemap to match any sized array using the <tt>ANY</tt> keyword as follows :<p>
<p>
<blockquote><pre>%typemap(memberin) char [ANY] {
	strncpy($target,$source,$dim0);
}
</pre></blockquote>
<p>
During code generation, <tt>$dim0</tt> will be filled in with the real array dimension.  <p>
<a name="n63"></a><h3> Useful Functions</h3>
When writing typemaps, it is often necessary to work directly with Python objects instead of using the conventional <tt>PyArg_ParseTuple()</tt> function that is usually used when writing Python extensions.   However, there are a number of useful Python functions available for you to use.<p>
<center>
<img src="ch9.table.2.png"><br>
<img src="ch9.table.3.png"><br>
<img src="ch9.table.4.png"><br>
<img src="ch9.table.5.png"><br>
<img src="ch9.table.6.png"><br>
<img src="ch9.table.7.png"><br>
</center><p>
<p>
<a name="n64"></a><h3> Standard  typemaps</h3>
The following typemaps show how to convert a few common kinds of objects between Python and C (and to give a better idea of how typemaps work)<p>
<center>
<img src="ch9.table.8.png"><br>
<img src="ch9.table.9.png"><br>
</center><p>
<p>
<a name="n65"></a><h3> Pointer handling</h3>
SWIG pointers are mapped into Python strings containing the hexadecimal value and type.  The following functions can be used to create and read pointer values.<p>
<center>
<img src="ch9.table.10.png">
</center><p>
<p>
These functions can be used in typemaps. For example, the following typemap makes an argument of "<tt>char *buffer</tt>" accept a pointer instead of a NULL-terminated ASCII string.<p>
<p>
<blockquote><pre>%typemap(python,in) char *buffer {
	PyObject *o;
	char     *str;
	if (!PyString_Check(o)) {
		PyErr_SetString(PyExc_TypeError,"not a string");
		return NULL;
	}
	str = PyString_AsString(o);
	if (SWIG_GetPtr(str, (void **) &amp;$target, "$mangle")) {
		PyErr_SetString(PyExc_TypeError,"not a pointer");
		return NULL;
	}
}

</pre></blockquote>
Note that the <tt>$mangle</tt> variable generates the type string associated with the datatype used in the typemap.<p>
<p>
By now you hopefully have the idea that typemaps are a powerful mechanism for building more specialized applications.  While writing typemaps can be technical, many have already been written for you.  See the Typemaps chapter for more information about using library files.<p>
<a name="n11"></a><h2> Implementing C callback functions in Python</h2>
Now that you're an expert,  we will implement  simple C callback functions in Python and use them in a C++ code.<p>
<p>
Let's say that we wanted to write a simple C++ 2D plotting widget layered on top of the gd-1.2 library.   A class definition might look like this :<p>
<p>
<blockquote><pre>// --------------------------------------------------------------------
// Create a C++ plotting "widget" using the gd-1.2 library by Thomas Boutell
//  
// This example primarily illustrates how callback functions can be
// implemented in Python.
// --------------------------------------------------------------------

#include &lt;stdio.h&gt;
extern "C" {
#include "gd.h"
}

typedef double (*PLOTFUNC)(double, void *);

class PlotWidget {
private:
  double      xmin,ymin,xmax,ymax;         // Plotting range
  PLOTFUNC    callback;                    // Callback function
  void       *clientdata;                  // Client data for callback
  int         npoints;                     // Number of points to plot
  int         width;                       // Image width
  int         height;                      // Image height
  int         black,white;                 // Some colors
  gdImagePtr  im;                          // Image pointer
  void        transform(double,double,int&amp;,int&amp;);
public:
  PlotWidget(int w, int h,double,double,double,double);
  ~PlotWidget();
  void set_method(PLOTFUNC func, void *clientdata);    // Set callback method
  void set_range(double,double,double,double);         // Set plot range
  void set_points(int np) {npoints = np;}              // Set number of points
  void plot();                                         // Make a plot
  void save(FILE *f);                                  // Save a plot to disk
};

</pre></blockquote>
The widget class hides all of the underlying implementation details so this could have just as easily been implemented on top of OpenGL, X11 or some other kind of library.   When used in C++, the widget works like this :<p>
<p>
<blockquote><pre>// Simple main program to test out our widget
#include &lt;stdio.h&gt;
#include "widget.h"
#include &lt;math.h&gt;

// Callback function
double my_func(double a, void *clientdata) {
  return sin(a);
}

int main(int argc, char **argv) {
  PlotWidget *w;
  FILE *f;

  w = new PlotWidget(500,500,-6.3,-1.5,6.3,1.5);
  w-&gt;set_method(my_func,0);              // Set callback function
  w-&gt;plot();                             // Make plot
  f = fopen("plot.gif","w");
  w-&gt;save(f);
  fclose(f);
  printf("wrote plot.gif\n");
}

</pre></blockquote>
Now suppose that we wanted to use our widget interactively from Python.  While possible, it is going to be difficult because we would really like to implement the callback function in Python, not C++.   We also don't want to go in and hack or C++ code to support this.   Fortunately, you can do it with SWIG using the following interface file :<p>
<p>
<blockquote><pre>// SWIG interface to our PlotWidget 
%module plotwidget
%{
#include "widget.h"
%}

// Grab a Python function object as a Python object.
%typemap(python,in) PyObject *pyfunc {
  if (!PyCallable_Check($source)) {
      PyErr_SetString(PyExc_TypeError, "Need a callable object!");
      return NULL;
  }
  $target = $source;
}

// Type mapping for grabbing a FILE * from Python
%typemap(python,in) FILE * {
  if (!PyFile_Check($source)) {
      PyErr_SetString(PyExc_TypeError, "Need a file!");
      return NULL;
  }
  $target = PyFile_AsFile($source);
}

// Grab the class definition
%include widget.h

%{
/* This function matches the prototype of the normal C callback
   function for our widget. However, we use the clientdata pointer
   for holding a reference to a Python callable object. */

static double PythonCallBack(double a, void *clientdata)
{
   PyObject *func, *arglist;
   PyObject *result;
   double    dres = 0;
   
   func = (PyObject *) clientdata;               // Get Python function
   arglist = Py_BuildValue("(d)",a);             // Build argument list
   result = PyEval_CallObject(func,arglist);     // Call Python
   Py_DECREF(arglist);                           // Trash arglist
   if (result) {                                 // If no errors, return double
     dres = PyFloat_AsDouble(result);
   }
   Py_XDECREF(result);
   return dres;
}
%}

// Attach a new method to our plot widget for adding Python functions
%addmethods PlotWidget {
   // Set a Python function object as a callback function
   // Note : PyObject *pyfunc is remapped with a typempap
   void set_pymethod(PyObject *pyfunc) {
     self-&gt;set_method(PythonCallBack, (void *) pyfunc);
     Py_INCREF(pyfunc);
   }
}

</pre></blockquote>
While this is certainly not a trivial SWIG interface file,  the results are quite cool.  Let's try out our new Python module :<p>
<p>
<blockquote><pre># Now use our plotting widget in variety of ways

from plotwidget import *
from math import *

# Make a plot using a normal Python function as a callback
def func1(x):
	return 0.5*sin(x)+0.25*sin(2*x)+0.125*cos(4*x)

print "Making plot1.gif..."
# Make a widget and set callback
w = PlotWidget(500,500,-10,-2,10,2)
w.set_pymethod(func1)                     # Register our Python function
w.plot()
f = open("plot1.gif","w")
w.save(f)
f.close()

# Make a plot using an anonymous function

print "Making plot2.gif..."
w1 = PlotWidget(500,500,-4,-1,4,16)
w1.set_pymethod(lambda x: x*x)            # Register x^2 as a callback
w1.plot()
f = open("plot2.gif","w")
w1.save(f)
f.close()

# Make another plot using a built-in function

print "Making plot3.gif..."
w2 = PlotWidget(500,500,-7,-1.5,7,1.5)
w2.set_pymethod(sin)                      # Register sin(x) as a callback
w2.plot()
f = open("plot3.gif","w")
w2.save(f)
f.close()
</pre></blockquote>
<p>
<p>
The "plot" method for each widget is written entirely in C++ and assumes that it is calling a callback function written in C/C++.   Little does it know that we have actually implemented this function in Python.   With a little more work, we can even write a simple function plotting tool :<p>
<p>
<blockquote><pre># Plot a function and spawn xv

import posix
import sys
import string
from plotwidget import *
from math import *

line = raw_input("Enter a function of x : ")
ranges = string.split(raw_input("Enter xmin,ymin,xmax,ymax :"),",")

print "Making a plot..."
w = PlotWidget(500,500,string.atof(ranges[0]),string.atof(ranges[1]),
               string.atof(ranges[2]),string.atof(ranges[3]))

# Turn user input into a Python function
code = "def func(x): return " + line
exec(code)

w.set_pymethod(func)
w.plot()
f = open("plot.gif","w")
w.save(f)
f.close()
posix.system("xv plot.gif &amp;")

</pre></blockquote>
<a name="n12"></a><h2> Other odds and ends</h2>
<a name="n66"></a><h3> Adding native Python functions to a SWIG module</h3>
Sometimes it is desirable to add a native Python method to a SWIG wrapper file.  Suppose you have the following Python/C function :<p>
<p>
<blockquote><pre>PyObject *spam_system(PyObject *self, PyObject *args) {
	char *command;
	int sts;
	if (!PyArg_ParseTuple(args,"s",&amp;command))
		return NULL;
	sts = system(command);
	return Py_BuildValue("i",sts);
}

</pre></blockquote>
This function can be added to a SWIG module using the following declaration :<p>
<p>
<blockquote><pre>%native(system) spam_system;        // Create a command called `system'

</pre></blockquote>
Alternatively, you can use the full function declaration like this <p>
<p>
<blockquote><pre>%native(system) PyObject *spam_system(PyObject *self, PyObject *args);
</pre></blockquote>
<p>
or<p>
<p>
<blockquote><pre>%native(system) extern PyObject *spam_system(PyObject *self, PyObject *args);
</pre></blockquote>
<a name="n13"></a><h2> The gory details of shadow classes</h2>
This section describes the process by which SWIG creates shadow classes and some of the more subtle aspects of using them.<p>
<a name="n67"></a><h3> A simple shadow class</h3>
Consider the following declaration from our previous example :<p>
<p>
<blockquote><pre>%module pde
struct Grid2d {
  Grid2d(int ni, int nj);
  ~Grid2d();
  double **data;
  int      xpoints;
  int      ypoints;
};
</pre></blockquote>
<p>
The SWIG generated class for this structure looks like the following :<p>
<p>
<blockquote><pre># This file was created automatically by SWIG.
import pdec
class Grid2dPtr :
    def __init__(self,this):
        self.this = this
        self.thisown = 0
    def __del__(self):
        if self.thisown == 1 :
            pdec.delete_Grid2d(self.this)
    def __setattr__(self,name,value):
        if name == "data" :
            pdec.Grid2d_data_set(self.this,value)
            return
        if name == "xpoints" :
            pdec.Grid2d_xpoints_set(self.this,value)
            return
        if name == "ypoints" :
            pdec.Grid2d_ypoints_set(self.this,value)
            return
        self.__dict__[name] = value
    def __getattr__(self,name):
        if name == "data" : 
            return pdec.Grid2d_data_get(self.this)
        if name == "xpoints" : 
            return pdec.Grid2d_xpoints_get(self.this)
        if name == "ypoints" : 
            return pdec.Grid2d_ypoints_get(self.this)
        return self.__dict__[name]
    def __repr__(self):
        return "&lt;C Grid2d instance&gt;"
class Grid2d(Grid2dPtr):
    def __init__(self,arg0,arg1) :
        self.this = pdec.new_Grid2d(arg0,arg1)
        self.thisown = 1

</pre></blockquote>
<a name="n68"></a><h3> Module names</h3>
Shadow classes are built using the low-level SWIG generated C interface.  This interface is named "modulec" where "module" is the name of the module specified in a SWIG interface file.   The Python code for the shadow classes is created in a file "module.py".  This is the file that should be loaded when a user wants to use the module.<p>
<a name="n69"></a><h3> Two classes</h3>
For each structure or class found in an interface file, SWIG creates two Python classes.  If a class is named "<tt>Grid2d</tt>", one of these classes will be named "<tt>Grid2dPtr</tt>" and the other named "<tt>Grid2d</tt>".  The <tt>Grid2dPtr</tt> class is used to turn wrap a Python class around an already preexisting <tt>Grid2d</tt> pointer.  For example :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; gptr = create_grid2d()         # Returns a Grid2d from somewhere
&gt;&gt;&gt; g = Grid2dPtr(gptr)            # Turn it into a Python class
&gt;&gt;&gt; g.xpoints
50
&gt;&gt;&gt;

</pre></blockquote>
The <tt>Grid2d</tt> class, on the other hand, is used when you want to create a new <tt>Grid2d</tt> object from Python.   In reality, it inherits all of the attributes of a <tt>Grid2dPtr</tt>, except that its constructor calls the corresponding C++ constructor to create a new object.    Thus, in Python, this would look something like the following :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; g = Grid2d(50,50)           # Create a new Grid2d
&gt;&gt;&gt; g.xpoints
50
&gt;&gt;&gt;

</pre></blockquote>
This two class model is a tradeoff.  In order to support C/C++ properly, it is necessary to be able to create Python objects from both pre-existing C++ objects and to create entirely new C++ objects in Python.   While this might be accomplished using a single class, it would complicate the handling of constructors considerably.  The two class model, on the other hand, works, is consistent, and is relatively easy to use.   In practice, you probably won't even be aware that there are two classes working behind the scenes.<p>
<a name="n70"></a><h3> The this pointer</h3>
Within each shadow class, the member "<tt>this</tt>" contains the actual C/C++ pointer to the object.  You can check this out yourself by typing something like this :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; g = Grid2d(50,50)
&gt;&gt;&gt; print g.this
_1008fe8_Grid2d_p
&gt;&gt;&gt;
</pre></blockquote>
<p>
Direct manipulation of the "<tt>this</tt>" pointer is generally discouraged. In fact forget that you read this.<p>
<a name="n71"></a><h3> Object ownership</h3>
Ownership is a critical issue when mixing C++ and Python.  For example, suppose I create a new object in C++, but later use it  to create a Python object.  If that object is being used elsewhere in the C++ code, we clearly don't want Python to delete the C++ object when the Python object is deleted.  Similarly, what if I create a new object in Python, but C++ saves a pointer to it and starts using it repeatedly.  Clearly, we need some notion of who owns what.  Since sorting out all of the possibilities is probably impossible, SWIG shadow classes always have an attribute "<tt>thisown</tt>" that indicates whether or not Python owns an object.  Whenever an object is created in Python, Python will be given ownership by setting <tt>thisown </tt> to <tt> 1</tt>.  When a Python class is created from a pre-existing C/C++ pointer, ownership is assumed to belong to the C/C++ code and <tt>thisown</tt> will be set to 0.<p>
<p>
Ownership of an object can be changed as necessary by changing the value of <tt>thisown</tt>.  When set, Python will call the C/C++ destructor when the object is deleted.   If it is zero, Python will never call the C/C++ destructor.<p>
<a name="n72"></a><h3> Constructors and Destructors</h3>
C++ constructors and destructors will be mapped into Python's <tt>__init__</tt> and  <tt>__del__</tt> methods respectively.  Shadow classes always contain these methods even if no constructors or destructors were available in the SWIG interface file.  The Python destructor will only call a C/C++ destructor if <tt>self.thisown</tt> is set.<p>
<a name="n73"></a><h3> Member data</h3>
Member data of an object is accessed through Python's <tt>__getattr__</tt> and <tt>__setattr__</tt> methods.<p>
<a name="n74"></a><h3> Printing</h3>
SWIG automatically creates a Python<tt> __repr__</tt> method for each class.  This forces the class to be relatively well-behaved when printing or being used interactively in the Python interpreter.<p>
<a name="n75"></a><h3> Shadow Functions</h3>
Suppose you have the following declarations in an interface file :<p>
<p>
<blockquote><pre>%module vector
struct Vector {
	Vector();
	~Vector();
	double x,y,z;
};

Vector addv(Vector a, Vector b);

</pre></blockquote>
By default, the function <tt>addv</tt> will operate on <tt>Vector</tt> pointers, not Python classes.  However, the SWIG Python module is smart enough to know that <tt>Vector</tt> has been wrapped into a Python class so it will create the following replacement for the <tt>addv()</tt> function.<p>
<p>
<blockquote><pre>def addv(a,b):
	result = VectorPtr(vectorc.addv(a.this,b.this))
	result.thisown = 1
	return result

</pre></blockquote>
Function arguments are modified to use the "this" pointer of a Python Vector object.  The result is a pointer to the result which has been allocated by malloc or new (this behavior is described in the chapter on SWIG basics), so we simply create a new VectorPtr with the return value.  Since the result involved an implicit malloc, we set the ownership to 1 indicating that the result is to be owned by Python and that it should be deleted when the Python object is deleted.  As a result, operations like this  are perfectly legal and result in no memory leaks :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; v = add(add(add(add(a,b),c),d),e)

</pre></blockquote>
Substitution of complex datatypes occurs for all functions and member functions involving structure or class definitions.  It is rarely necessary to use the low-level C interface when working with shadow classes.<p>
<a name="n76"></a><h3> Nested objects</h3>
SWIG shadow classes support nesting of complex objects.  For example, suppose you had the following interface file :<p>
<p>
<blockquote><pre>%module particle

typedef struct {
  Vector();
  double x,y,z;
} Vector;

typedef struct {
  Particle();
 ~Particle();
  Vector r;
  Vector v;
  Vector f;
  int    type;
} Particle;

</pre></blockquote>
<p>
In this case you will be able to access members as follows :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; p = Particle()
&gt;&gt;&gt; p.r.x = 0.0
&gt;&gt;&gt; p.r.y = -1.5
&gt;&gt;&gt; p.r.z = 2.0
&gt;&gt;&gt; p.v = addv(v1,v2)
&gt;&gt;&gt; ...

</pre></blockquote>
Nesting of objects is implemented using Python's<tt> __setattr__</tt> and <tt>__getattr__</tt> functions. In this case, they would look like this :<p>
<p>
<blockquote><pre>class ParticlePtr:
	...
	def __getattr__(self,name):
		if name == "r":
			return particlec.VectorPtr(Particle_r_get(self.this))
		elif name == "v":
			return particlec.VectorPtr(Particle_v_get(self.this))
		...
	
	def __setattr__(self,name,value):
		if name == "r":
			particlec.Particle_r_set(self.this,value.this)
		elif name == "v":
			particlec.Particle_v_set(self.this,value.this)
		...

</pre></blockquote>
The attributes of any given object are only converted into a Python object when referenced. This approach is more memory efficient, faster if you have a large collection of objects that aren't examined very often, and works with recursive structure definitions such as :<p>
<p>
<blockquote><pre>struct Node {
	char *name;
	struct Node *next;
};
</pre></blockquote>
<p>
Nested structures such as the following are also supported by SWIG. These types of structures tend to arise frequently in database and information processing applications.<p>
<p>
<blockquote><pre>typedef struct {  
	unsigned int dataType;
	union {
		int       intval;
		double    doubleval;
		char     *charval;
		void     *ptrvalue;
		long      longval;
		struct {
			int    i;
			double f;
			void   *v;
			char name[32];
              } v;
	} u;
} ValueStruct;

</pre></blockquote>
Access is provided in an entirely natural manner,<p>
<p>
<blockquote><pre>&gt;&gt;&gt; v = new_ValueStruct()       # Create a ValueStruct somehow
&gt;&gt;&gt; v.dataType
1
&gt;&gt;&gt; v.u.intval
45
&gt;&gt;&gt; v.u.longval
45
&gt;&gt;&gt; v.u.v.v = _0_void_p
&gt;&gt;&gt;

</pre></blockquote>
To support the embedded structure definitions, SWIG has to extract the internal structure definitions and use them to create new Python classes.  In this example, the following shadow classes are created :<p>
<p>
<blockquote><pre># Class corresponding to union u member
class ValueStruct_u :
	...
# Class corresponding to struct v member of union u
class ValueStruct_u_v :
	...
</pre></blockquote>
<p>
The names of the new classes are formed by appending the member names of each embedded structure.<p>
<a name="n77"></a><h3> Inheritance and shadow classes</h3>
Since shadow classes are implemented in Python, you can use any of the automatically generated classes as a base class for more Python classes.  However, you need to be extremely careful when using multiple inheritance.  When multiple inheritance is used, at most ONE SWIG generated shadow class can be involved.  If multiple SWIG generated classes are used in a multiple inheritance hierarchy, you will get name clashes on the <tt>this</tt> pointer, the <tt>__getattr__</tt> and <tt>__setattr__</tt> functions won't work properly and the whole thing will probably crash and burn. Perhaps it's best to think of multiple inheritance as a big hammer that can be used to solve alot of problems, but it hurts quite alot if you accidently drop it on your foot.... <p>
<a name="n78"></a><h3> Methods that return new objects</h3>
By default SWIG assumes that constructors are the only functions returning new objects to Python.  However, you may have other functions that return new objects as well.  For example :<p>
<blockquote><pre>
Vector *cross_product(Vector *v1, Vector *v2) {
	Vector *result = new Vector();
	result = ... compute cross product ...
	return result;
}

</pre></blockquote>
When the value is returned to Python, we want Python to assume ownership.  The brute force way to do this is to simply change the value of thisown.  For example :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; v = cross_product(a,b)
&gt;&gt;&gt; v.thisown = 1                        # Now Python owns it

</pre></blockquote>
Unfortunately, this is ugly and it doesn't work if we use the result as a  temporary value :<p>
<p>
<blockquote><pre>w = vector_add(cross_product(a,b),c)     # Results in a memory leak
</pre></blockquote>
<p>
However, you can provide a hint to SWIG when working with such a function as shown :<p>
<p>
<blockquote><pre>// C Function returning a new object
%new Vector *cross_product(Vector *v1, Vector *v2);

</pre></blockquote>
The <tt>%new</tt> directive only provides a hint that the function is returning a new object.  The Python module will assign proper ownership of the object when this is used.<p>
<a name="n79"></a><h3> Performance concerns and hints</h3>
Shadow classing is primarily intended to be a convenient way of accessing C/C++ objects from Python.   However, if you're directly manipulating huge arrays of complex objects from Python, performance may suffer greatly.  In these cases, you should consider implementing the functions in C or thinking of ways to optimize the problem.<p>
<p>
There are a number of ways to optimize programs that use shadow classes.  Consider the following  two code fragments involving the <tt>Particle</tt> data structure in a previous example :<p>
<p>
<blockquote><pre>def force1(p1,p2):
	dx = p2.r.x - p1.r.x
	dy = p2.r.y - p1.r.y
	dz = p2.r.z - p1.r.z
	r2 = dx*dx + dy*dy + dz*dz
	f = 1.0/(r2*math.sqrt(r2))
	p1.f.x = p1.f.x + f*dx
	p2.f.x = p2.f.x - f*dx
	p1.f.y = p1.f.y + f*dy
	p2.f.y = p2.f.y - f*dy
	p1.f.z = p1.f.z + f*dz
	p2.f.z = p2.f.z - f*dz

def force2(p1,p2):
	r1 = p1.r
	r2 = p2.r
	dx = r2.x - r1.x
	dy = r2.y - r1.y
	dz = r2.z - r1.z
	r2 = dx*dx + dy*dy + dz*dz
	f = 1.0/(r2*math.sqrt(r2))
	f1 = p1.f
	f2 = p2.f
	f1.x = f1.x + f*dx
	f2.x = f2.x - f*dx
	f1.y = f1.y + f*dy
	f2.y = f2.y - f*dy
	f1.z = f1.z + f*dz
	f2.z = f2.z - f*dz

</pre></blockquote>
The first calculation simply works with each Particle structure directly.  Unfortunately, it performs alot of dereferencing of objects.  If the calculation is restructured to use temporary variables as shown in force2, it will run significantly faster--in fact, on my machine, the second code fragment runs more than twice as fast as the first one.<p>
<p>
If performance is even more critical you can use the low-level C interface which eliminates all of the overhead of going through Python's class mechanism (at the expense of coding simplicity). When Python shadow classes are used, the low level C interface can still be used by importing the `modulec' module where `module' is the name of the module you used in the SWIG interface file.<p>

<p><hr>

<address>SWIG 1.1 - Last Modified : Mon Aug  4 10:47:07 1997</address>
</body>
</html>