Site navigation:


Installation and getting started

  1. Installation and setup
    1. Python version and library dependencies
      1. PyDSTool 0.84 -- 0.89
      2. PyDSTool 0.83.3 and earlier
      3. For C-based integrator and AUTO support (optional)
        1. 64-bit machines
      4. Windows-specific information
        1. Vista
      5. Mac-specific information
      6. Working platforms
      7. Other library issues
    2. Integrated Development Environment (IDE)
    3. Installing PyDSTool
    4. Setting up on Linux / OS X
      1. Python installation quirks for C/Fortran-based integrators (Dopri and Radau)
        1. 64 bit Mac specifics
      2. Path
      3. Linear algebra library problems with SciPy
      4. Configuring MatPlotLib for interactive plotting
      5. Supporting C-code integrators
        1. Install SWIG
        2. Compiler problems with SciPy
    5. Setting up on Win32
      1. Path
      2. Linear algebra library issues
      3. Configuring MatPlotLib for interactive plotting
      4. Supporting C-code integrators
        1. MinGW (or Cygwin) gcc
        2. Create libpython23.a (for Python 2.3 and earlier only)
        3. Tweak distutils (for Python 2.2 and earlier only)
        4. Install SWIG
        5. Compiler availability
  2. Compatibility between PyDSTool 0.84 data files and earlier versions
  3. Running the tests and examples
  4. First steps and basic orientation
    1. Assumed background
    2. Introspection
    3. Object APIs
    4. Running the built-in regression tests and examples
    5. Tutorial and next steps


1. Installation and setup

1.1. Python version and library dependencies

Further information about the package dependencis mentioned here can be found from the page Numeric And Scientific at the main python site. Depending on your platform, which you should first read about below, you have multiple options for installing python and the small number of other dependencies.

1.1.1 PyDSTool 0.90.x

This version series requires Python 2.6-7 or 3.3+. Further support for 2.6 has been removed. Installation and setup is best achieved by pip install pydstool (from pypi) or using Debian's apt-get. You can also download the installer package from github or sourceforge, then run sudo python setup.py install from within that directory.

IMPORTANT FOR WINDOWS USERS: The Numpy dependency is not yet properly supported on 64-bit Windows platforms. Although a third-party installer such as Anaconaa will install, it will not have the correct header files to allow distutils to work with PyDSTool to build C-based vector field definitions. You must install your whole python-numpy-scipy-matplotlib stack in 32-bit mode to enable access to these features!

On older Mac systems, and especially if you still use the fink package manager as the basis of your python installation, you may need to coerce the OS to install as a 32-bit package, and use 'sudo' (super user do) to enable permission to write to a system-controlled location for python's site-packages directory. If so, you might need to install with a command such as:

sudo ARCHFLAGS="-arch i386" FFLAGS="-m32" CFLAGS="-m32" LDFLAGS="-m32" ARCH="i386" pip install PyDSTool. Equally, you put those environment variable flags into your .bashrc or similar startup script using EXPORT. After such a pip command, you will also have to visit your site-packages and set all users to have read and execute permissions, using sudo chmod -R a+rx PyDSTool*

Further details about dependecies and sources are given in the README included with the package, which is also displayed here. A FAQ is also provided in the package.

1.1.2. PyDSTool 0.84 -- 0.89

PyDSTool requires Python version 2.4-2.7 (download it here). It is not yet tested on later versions (3.x) and will not work. I will fix this in due course. Multiple versions of python can usually be installed on a machine concurrently, although I don't recommend it.

PyDSTool relies on the following packages, which can be installed in this order over Python before using PyDSTool:

Optional packages:

1.1.3. PyDSTool 0.83.3 and earlier [NOT RECOMENDED FOR NEW USERS]

PyDSTool requires Python version 2.3.5 or 2.4 (download it here). Users have reported difficulties with some components of PyDSTool working properly with Python 2.3.4 (which has inferior support for pickling), and so we now recommend one of the 2.3.5 releases.

PyDSTool relies on the following packages, which can be installed in this order over Python 2.3.5 before using PyDSTool:

1.1.3. For C-based integrator and AUTO support (optional)

You can try PyDSTool without installing these additional packages, but you will be able to use only the scipy-provided VODE integrator. It is at least an order of magnitude slower to solve ODEs with this integrator because of the way it has been wrapped, in particular its use of Python callback functions and the overhead created in being able to detect events using this solver using our pure Python code.

1.1.3.1. 64-bit machines

64 bit machines with 64 bit operating systems should function correctly with PyDSTool v 0.90 and later, but there may be problems on windows machines that cannot get the 64 bit version of MinGW to install.

IMPORTANT FOR WINDOWS USERS: The Numpy dependency is not yet properly supported on 64-bit Windows platforms. Although a third-party installer such as Anaconaa will install, it will not have the correct header files to allow distutils to work with PyDSTool to build C-based vector field definitions. You must install your whole python-numpy-scipy-matplotlib stack in 32-bit mode to enable access to these features!

For earlier versions of PyDSTool, users report a variety of successful and unsuccessful outcomes in their installations. In some cases, this is a limitation of how your numpy and python were installed (especially through Fink on a Mac). If you must use these earlier PyDSTool versions, there are some things you can try. If the Dopri and Radau tests don't run out of the box, try removing the '-m32' flags in the files mentioned in the FAQ that is provided in the PyDSTool root directory. If you are on linux, make sure that the 'dev' version of python is installed, as well as the 32-bit compatible libraries: these may include things like ia32-libs, libc6-i386, and libc6-dev-i386, and a 'build-essential' package (on Ubuntu).

There may also be problems with the compatibility of the compilers that numpy sees by default and those which PyDSTool tries to use. Details of investigating and resolving this for AMD and Intel linux are detailed in these notes.

1.1.4. Windows-specific information

Some people find the all-in-one platform independent distribution for scientifically-oriented Python from ActiveState, Enthought (free for academic use), or Anaconda to be preferable. Some problems with setup have been discovered with these systems, particularly to get the C integrators working in 64-bit mode especially. Always install in 32-bit mode. However, installation of the individual components from binary installers is very simple on windows, and gives you more control over the versions that will be most compatible with the current PyDSTool version.

Note that you may have problems using Windows pathnames to your PyDSTool code that use whitespace when you test the C integrators. Distutils and/or MinGW does not correctly deal with this case and you will get cryptic errors about missing files.

For the oldest versions of PyDSTool (pre 0.84), the Enthought distribution contains the recommended versions of Python, SciPy, SWIG, MinGW, IPython, among other libraries (which you may not need), but does not contain MatPlotLib. You will have to install those separately. Also (very important!), you will have to retrograde the included Numeric 24.2 (and possibly Numarray) versions simply by running their installers for the above-mentioned recommended versions available at the sites mentioned above. But unless you can't put MinGW and SWIG together yourself, I don't think you'll be in better shape than if you install all the recommended versions individually. I ended up with the same pickling error as Python 2.3.4 gave me when I tried installing with Enthought, so I don't really recommend this route. If you get it work and have any advice, please let me know so that I can update this information.

1.1.4.1. Vista

Main solution: don't use Vista! You must remove Vista's User Account Control before installing any of the python core and library software, otherwise you will get confusing error messages claiming that libraries are not present when you attempt to import them.

  1. Click Start, and then click Control Panel.

  2. In Control Panel, click User Accounts.

  3. In the User Accounts window, click User Accounts.

  4. In the User Accounts tasks window, click Turn User Account Control on or off.

  5. If UAC is currently configured in Admin Approval Mode, the User Account Control message appears. Click Continue.

  6. Clear the Use User Account Control (UAC) to help protect your computer check box, and then click OK.

  7. Click Restart Now to apply the change right away, or click Restart Later and close the User Accounts tasks window.

It might be the case that you can switch this back on once every package that you want (numpy, scipy, etc.) has been installed. I'm not certain, I don't use Vista.

You may also have to do this add the python folder installation (e.g. C:\python25) to the PATH environment variable:

  1. First go to the Windows button, and open control panel. You will need the classic view which is in the upper left hand corner.

  2. Click the System icon.

  3. Click on the Advanced system settings which is in the upper left hand corner.

  4. Once this opens, click the Advanced tab.

    1. Click the Environment Variables button.

    • b. In the second box labeled System variables, scroll down to the variable called Path and double click on this.

      c. You will need to add some text to this box. NOTE: Do not delete what is already there!! Add C:\Python25; to the front of the existing string. Then press Ok and its ready to go. It should look something like C:\Python25;%\...........

      d. Some people have reported that they need to put the C:\Python25 in double quotes... i.e. "C:\Python25";

There are known problems with the PyWin32 libraries on Windows Vista which can make using python IDE functionality and graphics through IPython or PyScripter problematic.

Additionally, Python 2.5's distutils has some problems building extensions for the C-based integrators if you use path names that include spaces. I don't know if these problems have gone away for Python 2.6, but it is hard to patch distutils to fix this, and you would be better off changing your filespace to avoid spaces in filenames.

1.1.5. Mac-specific information

You will need to have installed XCode on your Mac. There is an installation disk for "Developer Tools" that comes with your Mac. You can install it from there, or download the latest version from Apple. (Getting the very latest version is not important.) However, it is very important not to install python packages into the system Framework's python. That should be left alone for the OS to use by itself. It is easy to install a co-existing python system.

You have a couple of options now for installing everything on a Mac. My recommended way is now to use "homebrew". Tested instructions are here, which sets you up with the whole scipy stack, the compilers, and OS environment variable setup. It may take quite a while to build the compilers! After that, you can simply use pip install pydstool.

An older approach, that can still work (I still use it on one of my machines) is through the "fink" package manager. You will need to have a superuser (root) account activated for fink to be able to install dependency python packages by itself. Instructions are here. I strongly recommend installing everything via your user account and selecting the 'sudo' option for fink to use the root account to make changes. You will have to give it the root password. Fink will then create a /sw directory where everything will be installed. You must ignore the python system in Framework because it's harder to configure and adapt that to our needs.

Fink-specific information:

To install with fink, I recommend the command line interface only. In a terminal window:

$ fink configure

in which you must select the use of the "unstable" branch of packages in order to get access to numpy, etc. This is not sketchy in the way that it sounds! Alternatively, if it's unclear to you how to select the unstable branch then download and install the Fink Commander application, run it and merely use its File->Preferences->Fink tab to select "Use unstable branch" and apply the changes. Then run


$ fink install scipy-py27 matplotlib-py27 ipython-py27

which may take one or more hours to complete, depending on your computer. Fink will install many dependencies (including numpy) automatically, and you can simply select all the defaults when you are queried. This will also install the optional ipython environment, which is highly recommended for use with matplotlib. Conveniently, these commands will install gcc, gfortran, and SWIG, which are necessary to run the C-based integrators Dopri and Radau and work with the AUTO package. Lastly, see the additional set-up notes below for OS X / Linux.

With fink, you will probably need to update your PATH environment variable and/or aliases in your .profile or .bashrc file (or equivalent) so that the newly-installed version is default. Edit $HOME/.profile to read like the following (adjust python version as appropriate):

. /sw/bin/init.sh
export PYTHONPATH=/sw/lib/python2.7/site-packages:$HOME/
export PYTHON=/sw/bin/python2.7
alias python='/sw/bin/python2.7'

The first line is for Fink. The second line allows your new Python system to find modules, including PyDSTool. The third line lets PyDSTool know which Python to execute. The last line is a shortcut so that you start with the correct Python.

1.1.6. Working platforms

See the list on the Travis CI page. We are still having problems with fully 64-bit builds on Windows machines when python is installed with Anaconda or Python(x,y), whose binaries typically used a Microsoft compiler that is not compatible with the gcc-built PyDSTool fast integrators. For now, one solution is to install the same MS compiler, or build your whole python system using gcc (from MinGW or Cygwin) from source. Please see the discussions on the Sourceforge forums.

1.1.7. Other library issues

MatPlotLib is the 2D graphics library used by PyDSTool at present. MatPlotLib is the de facto standard for 2D graphics in Python, and there are some extensions to 3D graphics (see mplot3D). It also requires a minimal number of additional libraries to be installed. MatPlotLib has several dependencies, depending on which backend you wish to use with it. You may have to install wxPython, PyGTK (including the development package), GLIB, tkinter, libpng, among others (automatically done with fink/homebrew on a Mac). There are some OS and IDE compatibility issues with the different backends, which are discussed further in a sub-section below.

Gnuplot is optional (apparently support for this via a SciPy interface is dwindling, although I think it fills a need), but is recommended to support basic 3-dimensional plotting.

gcc 4.0 has given us problems with g77 support for the Radau C-based integrator (see page Generators), and we recommend using only 3.X versions unless you have gfortran.

Some parts of PyDSTool versions pre-0.90 can also take advantage of Psyco optimization, although this only works for x86 platforms. (Note that Psyco is no longer maintained.)

1.2. Integrated Development Environment (IDE)

There are many excellent resources online for comparing IDE features and styles.

At minimum, we recommend installing the platform-independent IPython IDE for PyDSTool, although IDLE on Windows (bundled with Python) works well too, and comes with its own script editor. It may be difficult to make PythonWin work with MatPlotLib, depending on the availability of the different graphics back-ends (see platform-specific notes below). Follow the platform-specific instructions later in this page for tweaking MatPlotLib to work with your IDE. We recommend Wing IDE or PyCharm for general editing and debugging, which has excellent support for small and large projects. A simple Windows alternative is PyScripter, while a simple Mac alternative is Spyder.

Note that on Windows you may need to install pyreadline, and the PyWin32 tools for optimum use of IPython (and ctypes for older Python versions pre-2.5). Latest versions of these tools can be found on SourceForge.

1.3. Installing PyDSTool (pre v 0.90 only)

The PyDSTool package does not need to be installed per se. You simply unzip it to its target directory (e.g., c:\PyDSTool\ on Windows or /Users/$HOME/ on a Mac). No call to setup (part of the distutils package) is necessary (and you do not have to copy the code to Python's lib\site-packages directory). We aim to provide a setup.py installer in version 0.90. You should not use any spaces in your path to PyDSTool if you plan to use the C-based integrators -- gcc will not work properly! This means, do not put it in your Windows "Documents and Settings" folder!

However, there are several things you may need to do in order to run PyDSTool successfully.

For instance, you will need to update your system's path so that Python can find the package. We now explain how to do this, depending on your platform.

We recommend you run the test scripts of the package dependencies (SciPy, MatPlotLib, etc.) to check that they are OK before running any PyDSTool test scripts (discussed in Section 2). In case you encounter problems, the following sub-sections describe how to configure your system correctly.

1.4. Setting up on Linux / OS X

You will need to edit the $HOME/.profile file to add a variable PYTHONPATH with all the directories leading up to PyDSTool, and a variable PYTHON set to /sw/bin/python2.7. You may also wish to make an alias for python and ipython to point to the versions in this bin directory in case of conflicts with any built-in or previously installed versions of python.

We recommend the GTKagg backend to Matplotlib, which seems to be the most reliable in its interaction with ipython on these platforms.

If you happen to use Gentoo you might find Shai Revzen's page InstallOnGentoo helpful, although Shai has other good advice there for linux systems in general. You will need a backend such as Tkinter for graphics if you don't already have one installed.

You must ensure that you have write permissions in the unzipped PyDSTool folder (a.k.a. "installation directory") for Python to write .pyc files from the .py code. You can do this with the command chmod -R a+rwx PyDSTool. This should not be necessary unless you are not the installing user and someone put PyDSTool in a root-owned folder (e.g. in python's site-packages)

1.4.1. Python installation quirks for C/Fortran-based integrators (Dopri and Radau)

Depending on your linux flavor, you may need to be add some non-default packages to your python installation to be able to use PyDSTool. For both integrators you must have the '-dev' version of python that includes the header files necessary for distutils to compile extensions using numpy types. You will need a fortran compiler (g77 or gfortran) for Radau to work.

One further quirk is that on Ubuntu Hardy with numpy 1.1 and Python 2.5, cfunc.h was provided in the "wrong" directory and needed to be copied into its parent directory in order that the standard library includes during the gcc calls to build the Dopri and Radau integrators.

1.4.1.1. 64 bit Mac specifics

Leopard and Snow Leopard are nominally 64-bit OS's, but it is common to be installing 32-bit software on these systems. If that is the case (especially packages on fink) you will need some special tweaks for getting Dopri, Radau, and AUTO (via PyCont) to work. See the notes earlier for 64 bit installation issues.

1.4.2. Path

You will need to add the following lines in your shell's rc file so that the Python interpreter knows where to find the PyDSTool package, assuming you installed PyDSTool directly in your home directory.

Using .bashrc

PYTHONPATH=$PYTHONPATH:$HOME/:$HOME/PyDSTool/:$HOME/PyDSTool/tests/
export PYTHONPATH

Using .cshrc

setenv PYTHONPATH $PYTHONPATH:$HOME/:$HOME/PyDSTool:$HOME/PyDSTool/tests/

You may also want to make sure that Python's site-packages directory is included in your path, if it is not set correctly by Python already. e.g. prepend the paths in the above examples with something like /usr/local/lib/python2.4/site-packages:.

You may have to add the following file to your Python installation, in order to instruct Python where to look for your package: /usr/local/lib/python2.7/site-packages/PyDSTool.pth. This file should contain text resembling the following:

$HOME/
$HOME/src/
$HOME/src/PyDSTool/

or whatever your PyDSTool path is. It seems that if you don't explicitly add the parent directories to this file then Python cannot see any the sub-directories.

1.4.3. Linear algebra library problems with SciPy

If the ATLAS libraries have not been properly installed as part of SciPy, you may find that certain of SciPy's linear algebra library functions (those from LAPACK, I believe) will not import. One solution is to remove the ATLAS libraries from the installation sequence of SciPy.

Some linux distributions (e.g. Fedora Core 4) have LAPACK and BLAS rpms in their "Extras" collection. Installation of these (or other ATLAS-free sources) prior to a rebuild of SciPy may make everything work as desired.

Further information can be found at the "Known installation problems" sub-section of the SciPy FAQ.

1.4.4. Configuring MatPlotLib for interactive plotting

The most recent versions of MatPlotLib should work correctly with interactively plotting by default. On a Mac or Linux installation with MatPlotLib 0.8x, the default setup may have problems with interactive plotting. For instance, we had to close the plot window to get back to the python prompt, precluding having more than one plot window open at at time. Try it as it is first, and if it works interactively then you can ignore this section.

To fix this on your system, I recommend changing the back-end used for windowing to be the highly reliable TkAgg. To do these things, download a copy of my .matplotlibrc file provided here. You can place this in your home directory's .matplotlib (hidden) directory, which will now override the built-in default rc file for matplotlib. Read more about this here. (On binary-only linux/OSX installations, the default rc file may be in /etc if you really want to edit that).

Only on older systems: If you are not using IPython, you might only be able to regain a prompt after plotting by commenting out the line "Tk.mainloop()" in the show function of site-packages/matplotlib/backends/backend_tkagg.py. If you are using a binary-based installation you will not have this option!

See this page for more information about interactive plotting. Also see this post for a discussion at the comp.lang.python newsgroup.

Also, making this change fixes a problem with XWindow session forwarding -- now local plotting graphs created on a remote terminal works if you have used ssh -X to login to the remote machine.

Lastly: Depending on your setup, you may need to remove the final show() statements from your scripts (and our test scripts) in order to have the figures appear "and" return you to the interactive prompt. For instance, I know this is what I needed to do with Python 2.4, matplotlib 0.90 on Windows XP.

1.4.5. Supporting C-code integrators

You will not need to follow these instructions to use the inbuilt (scipy-provided) VODE integrator or if you installed on a Mac with fink.

1.4.5.1. Install SWIG

SWIG is a wrapper for C/C++ sources. It allows you to use C/C++ functions and classes from withing Python with a minimum effort.

Download SWIG from http://www.swig.org. Follow the instructions to compile and build the package.

1.4.5.2. Compiler problems with SciPy

PyDStool's Radau integrator has had compatibility problems with version 4.0 of gcc, but since 2012 has been OK with later versions and 3.5. If you are expecting to use gcc to compile C code versions of vector fields (e.g. with the Dopri integrator), and you have any problems on linux, then you should ensure that the CC variable is set to gcc in the Python installation Makefile

<python_installation_root>/lib/python2.7/config/Makefile

If this is not properly set when you try to activate PyDSTool's Dopri code you may get an error (see the FAQ on the MainProjectPage).

The CC environment variable of your unix shell may also need to be set to gcc (or whatever compiler you wish to be using).

1.5. Setting up on Win32

If you only intend to use native Python/SciPy functionality within PyDSTool, you only need to follow the instructions under the Path and MatPlotLib sub-headings, otherwise to use C-based integrators you should read all of the instructions below.

1.5.1. Path

On a Windows platform, you may have to add the following file to your Python installation, in order to instruct Python where to look for your package: C:\Python27\Lib\site-packages\PyDSTool.pth. This file should contain text resembling the following:

C:\\
C:\\Tools\\
C:\\Tools\\PyDSTool\\

or whatever your PyDSTool path is. It seems that if you don't explicitly add the parent directories to this file then Python cannot see any sub-directories of it! If you are using the PythonWin IDE, you can make these changes to the path from the Tools -> Edit Python Path menu.

If you have not done so already, you may also wish to add the path to python.exe to your AUTOEXEC.BAT file and to the Windows Environment Variables (in Control Panel\System) so that python can be run directly on scripts from the command prompt. The paths of MinGW, CygWin, and SWIG will have to be added the same way if you are using those for C-based integrators.

We recommend the IDLE environment for working with PyDSTool in Windows, as it is the most easy to work with MatPlotLib.

1.5.2. Linear algebra library issues

If you install SciPy from binaries then there should be no problem getting the LAPACK and ATLAS libraries to work correctly. If you are compiling from sources you may need to follow the instructions given above for Linux / OS X platforms.

1.5.3. Configuring MatPlotLib for interactive plotting (if it doesn't work out of the box)

Make sure you install the PythonWin extensions first. See the following links for information on how to configure your system for bug-free interactive graphing with MatPlotLib.

If it has been created, your matplotlibrc file can probably be found in C:\Python27\share\matplotlib\, otherwise download a sample file provided here. You can read more about this here. This file selects the highly reliable TkAgg backend and sets the interactive option.

MatPlotLib configuration problems will depend on which IDE you choose. We recommend using IPython (with the -pylab option built into your shortcut) or IDLE (with the -n option built into your shortcut -- see below).

Instructions for IDLE:

In the start menu, change the properties for the link to idle from

C:\Python27\pythonw.exe "C:\Python27\Lib\idlelib\idle.pyw"

to

C:\Python27\pythonw.exe "C:\Python27\Lib\idlelib\idle.pyw" "-n"

For IPython:

To fix interactive plotting on your system, you might want to change the back-end used for windowing:

2. Change the "backend" line in your matplotlibrc file to TkAgg (unfortunately this option may not be compatible with the PythonWin IDE).

3. Change the "interactive" line to True.

4. If not using IPython, you might only be able to regain a prompt after plotting by commenting out the line "Tk.mainloop()" in the show function of site-packages/matplotlib/backends/backend_tkagg.py.

Now try "import pylab" from the python prompt. If you get an error about a DLL not found, it is most likely msvcp71.dll that is missing from your Windows\System directory, in which case you can download it from a reputable website such as http://dll-files.com.

1.5.4. Supporting C-code integrators

You do not need to follow these instructions to use the inbuilt (scipy-provided) VODE integrator.

1.5.4.1. MinGW (or Cygwin) gcc

Next, install MinGW gcc. This is the recommended way to use gcc with PyDSTool on Win32 platforms. There is a version of the MinGW gcc compiler available through Cygwin, but you'll still need to change the compiler name in any scripts you run that use the C integrators (see Compiler Availability subsection below).

The most recent versions of MinGW include versions of gcc are compatible with the SciPy runtime libraries. If you have problems, you can try using versions of MinGW before 3.3, and the .exe installer for version 3.1 can be downloaded here or by an internet search for "MinGW-3.1.0". Other downloads are available at http://www.mingw.org. You only need to download the installer for MinGW, which contains the whole compiler, support utilities, documentation, libraries and header files. This gcc compiler runs under Windows and compiled programs are more independent from the runtime system than when using Cygwin gcc (from what I've been told).

Once uncompressed, you should add the \bin directory of MinGW to your path environment variable. (Example : Under Windows 95/98/ME, if you installed MinGW to c:\gcc, you would add SET PATH=c:\gcc\bin;%PATH% to your AUTOEXEC.BAT.)

If installed properly, you should be able to run gcc --version anywhere.

Now, create the file c:\\Python2.7\\Lib\\distutils\\distutils.cfg or the equivalent path for your python installation. It will contain these lines:

[build]
compiler=mingw32
1.5.4.2. Create libpython23.a (for Python 2.3 and earlier only)

Note, for Python 2.4 or later you do not have to create the corresponding libpython24.a file, it is already present.

In order for PyDSTool to create Python extensions, as part of using C-based integrators, it needs to link against the Python library. Unfortunately, most Python distributions are provided with Python23.lib, a library in Microsoft Visual C++ format. GCC expects a .a file (libpython23.a to be precise.). Here's how to convert python23.lib to libpython23.a if it is not already present in your C:\python23\libs\ directory:

Download pexport (you'll have to search for that online). Get Python23.dll (it should be in C:\WINNT\System32\). Run:

pexports python23.dll > python23.def

This will extract all symbols from python23.dll and write them into python23.def. Now run:

dlltool --dllname python23.dll --def python23.def --output-lib libpython23.a

This will create libpython23.a (dlltool is part of MinGW utilities). Copy libpython23.a to C:\python23\libs\ (in the same directory as python23.lib). This trick should work for all Python versions, including future releases of Python. You can also use this trick to convert other libraries.

Advice on other web pages has also recommended copying python23.dll from C:\WINNT\System32\ to your Python libs directory.

1.5.4.3. Tweak distutils (for Python 2.2 and earlier only)

This tweak is necessary with Python 2.2, but it is fixed in 2.3.5 and later. I don't know at which version change in-between these the fix was made. So just in case you need to do it yourself...

Locate build_ext.py in your Python directory (should be somewhere around C:\Python22\Lib\distutils\command\).

Change the following two lines:

#new_sources.append(base + target_ext) # old
new_sources.append(base + '_wrap' + target_ext) # new

#swig_cmd = [swig, "-python", "-dnone", "-ISWIG"] # old
swig_cmd = [swig, "-python"] # new
1.5.4.4. Install SWIG

SWIG is a wrapper for C/C++ sources. It allows you to use C/C++ functions and classes from withing Python with a minimum effort.

Download SWIG binaries for Windows from http://www.swig.org, uncompress them and add the SWIG directory to your path in AUTOEXEC.BAT (i.e., the directory where swig.exe is located).

Set these environment variables, usually from the Control Panel\System\Advanced\Environment Variables dialog.

PYTHON_INCLUDE : Set this to the directory that contains python.h PYTHON_LIB : Set this to the python library including path for linking

Example using Python 2.3:

PYTHON_INCLUDE: d:\python23\include
PYTHON_LIB: d:\python23\libs\python23.lib

Also see http://www.mingw.org/MinGWiki/index.php/Python%20extensions.

1.5.4.5. Compiler availability

On Win32 platforms, it is assumed that "mingw32" is present in your Python installation. Any use of modules that require compilation in C will require you to be sure that you have a C compiler available and visible to PyDSTool. On Linux-type platforms, this should only require you to not provide a 'compiler' option in the initialization of any such objects, unless you wish to specify a particular compiler.

If you only use Cygwin on a Win32 platforms, you need to specify the compiler option as "cygwin" in initialization of any C-code based Generator. PyDSTool uses the numpy_distutils version of the distutils interface to the gcc compiler, although for Cygwin-based compilation you will need to add this cygwinccompiler.py file to your C:\Python23\Lib\site-packages\numpy_distutils\ directory in order to get the Radau integrator to work.

2. Compatibility of user data files between different PyDSTool versions

If you are upgrading PyDSTool from an earlier version, and you have previously saved PyDSTool or Scipy data objects, you may be able to still use loadObjects, etc. to load the data. You should keep your original scripts that generate these files in case you have to re-run them all using your new version. That is the most reliable and easiest solution. Cross-version support for the binary data files is, unfortunately, not provided, but if you insist on trying then you should try the following procedure. Load each of the saved objects you wish to convert and export all their metadata dictionaries and their arrays to their own files, then reimport those and repopulate new objects after loading them in the new version of PyDSTool. You will have to manually check that you covered all the attributes in those objects.

For pre 0.84 PyDSTool versions: if you install numarray 1.5.2 alongside numpy, this makes the old PyDSTool array classes visible to loadObjects when it tries to recover old data. This installation will not conflict with the numpy namespace if you remember not to import from numarray yourself! Note that this compatibility is not available through the numpy.oldnumeric module.

3. Running the built-in regression tests and examples

There are a number of unit tests included in the sub-directories of PyDSTool named tests/ and also a number of usage examples in the outer examples directory..

Once you have set up your system you may like to run all the tests in batch mode. This can be done by running the script /examples/run_all_tests.py, e.g. by calling python -i run_all_tests.py from the prompt, in the tests directory. There are simple switch options at the top of that file that you may need to edit in order to select whether the external compiler tests should be run (in case you do not have gcc working on your system). By default the script assumes that you have gcc working.

Note that on some platforms you will see an error report when the script tries to automatically close graph windows, to the effect of:

Fatal Python error: PyEval_RestoreThread: NULL tstate.

This error can be ignored. Depending on the settings for your matplotlib installation, you may also (a) get a slew of warnings at end of each test script, and (b) need to close any plot windows yourself in order to proceed to the next test. The batch script should report any errors that you get from the test scripts if they fail, in which case please let us know so that we can address the problem.

A few of the tests depend on files already having been created by other tests, so read the preamble of the files first if you wish to run them individually. Some of the scripts are rather substantial examples of mini-projects, and may take a long time to run and produce a lot of output. In most cases, the scripts themselves provide instruction on basic PyDSTool features and the screen output may simulate live interactions at the prompt.

The default compiler for PyDSTool in Windows is assumed to be MinGW, so if you are running Cygwin instead then you will need to add the keyword compiler='cygwin' to all initializations of C-based integrators (Dopri and Radau) in order for them to correctly access gcc through Cygwin.

Note that the most problematic issue seems to be running g77 or gfortran as part of the Radau integrator's setup. If you see g77 compiler errors as part of these tests then please let us know what the problem is and we'll try to help you figure it out. You may like to remove those scripts from the list to execute in run_all_tests.py or use Dopri instead (where possible).

PyDSTool has been successfully tested on the popular 32-bit platforms, based on the instructions given on this page (and some 64-bit platforms - see above notes). If you cannot understand why you still have problems after carefully following the above instructions then please post a message on the main User Help forum. That is preferred to emailing for general installation and setup enquiries. Please save the logs created when running the tests, and be ready to explain exactly how you installed everything so far so that I can understand what help you need.

4. First steps and basic orientation

4.1. Assumed background

In this section we will assume that you have set up PyDSTool successfully, and that you are already familiar with using Python, SciPy, and NumPy. Tutorials on these can be found at http://www.python.org, a SciPy/NumPy tutorial, and a basic NumPy tutorial. If you are used to an environment such as Matlab rather than Python, you might like to consult this page about NumPy for Matlab users. See also the PythonResources page.

4.2. Introspection

The most helpful Python feature available during an interactive PyDSTool session is introspection. There is a great article on this in the PythonResources section. Typing dir(<object_name>) will list the method and attribute names associated with that object. type(<name>) will tell you what type is associated with that name, so that you can understand how to use it.

Many PyDSTool objects have the method info, which provides various levels of detail depending on the optional "verbose level" argument. The default value for this level is usually 0, but is sometimes 1. Some objects provide even more detailed information at level 2. (For PyDSTool objects, typing help(<object_name>) is equivalent to printing the results from the info method called with its default verbose level.)

For instance, suppose we have a Pointset object p in memory.

>>> print p.info(0)
Pointset
>>> print p.info(1)
Pointset
Independent variable:
t:  [ 0.  1.  2.  3.]
Coordinates:
x0:  [ 4.456    4.11103  7.3431   5.443  ]
x1:  [-1.00336000e+001 -5.60000000e-001 -3.23221000e+000 -1.00000000e-002]
x2:  [ 300000.    4000.  330000.  280000.]

PyDSTool provides the function who, which works in a similar way to the Matlab function of the same name. This function returns information about all the PyDSTool objects currently defined. The optional keyword argument verboselevel selects the level of detail that will be displayed about each object, via the objects' info methods. An optional typelist list of PyDSTool types makes who return only objects of those types. The general-purpose pretty printer function info is also useful to display the contents of objects and dictionaries when they do not have a dedicated info method.

4.3. Object APIs

PyDSTool's API command returns a string containing all the (non-underscored) attributes and methods of an object, with their docstrings where available. The full API documentation of all PyDSTool functions, classes, constants, etc. is provided in the bundled auto-created HTML documentation (see the local README file to get started).

4.4. Running and understanding a test script

We will assume you have installed the whole package to the directory PyDSTool_package, in which there are setup metadata, the main PyDSTool directory, and the examples directory.

cd PyDSTool_package/examples
python -i interp_vode_test.py

For an interactive session, the principal import statement in a user script is

from PyDSTool import *

from which most of the names from scipy, numpy, and math, become available without prefixing, in addition to the core PyDSTool names. For convenience, scipy, numpy, and matplotlib's pyplot modules are accessible using the shorthands sp, np, and plt, respectively.

4.5. Tutorial and next steps

There are two sources of further help. Primarily, there is a growing online Tutorial. For a wider range of examples, you are encouraged to read and run the other examples in the PyDSTool/tests/ directory. Many of these contain significant code commenting to explain the set ups, and also display graphs and text-based information about the examples.


PyDSTool source code is hosted by SourceForge:

Get PyDSTool at SourceForge.net. Fast, secure and Free Open Source software downloads