XPPy

XPPy is Python interface for Bard Ermentrout's XPP. XPPy was inspired by a similar XPP-Matlab interface by Rob Clewley.

The main feature is ability to parse and change XPP's ode and set files, and run a simulation using XPP. The package contains some data wrapping classes that aid working with the data files produced by XPP (timetraces, allinfo and bifurcation files files). In addition, it contains additional plotting tools for matplotlib.

Licence

XPPy is free software: you can redistribute it and/or modify it under the terms of the 3-clause BSD licence.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the XPPy Developers nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Documentation

Since XPPy is a collection of tools I created on a course of my work, it was primary used by one person, therefore it is not extremely well documented. Nevertheless, there is a Doxygen-generated documentation for the package which you can find in the folder doc of the source distribution or online in HTML or PDF. To obtain PDF from LaTeX documentation you need to have PDFLaTeX installed. To make PDF file just go to the LaTeX documentation folder and type 'make', e.g.:

cd doc/latex
make

Moreover, every object contains docstring, which more or less explains its purpose.

Download

The latest release version is 0.7.0: xppy-0.7.0.zip, xppy-0.7.0.tar.gz.

Recent changes:

licence changed to 3-clause BSD;
fix to recognition of aux-variable lines;
improved plotDiag; can plot in given axes instead of a new figure.

Developers: XPPy is now also available on GitHub. The release will be made when it's ready.
Bugs: Please report bugs, requests etc to GitHub.

Install

Before you install XPPy you should install NumPy, which is extensively used by XPPy. Also if you want to use plotting tools (xppy.utils.plot) you should have matplotlib. Note that XPPy installation script does not check for those packages and will install anyway, the error messages will appear when you will try to import XPPy.

XPPy has a Python distutils setup script. To install XPPy just unpack the source package and change the directory, e.g.

unzip xppy-x.y.z.zip
cd xppy-x.y.z

(where x.y.z is a current version number, e.g. 1.2.3), and type the below command to install the package

python setup.py install

This command will install XPPy in as standard site-packages folder of the Python version used. If you have more then one Python on your machine, it is advisable to check which version is currently used or call a certain version of Python by writing, e.g. python2.6 instead of just python.

If you have some problems or want to know more about the installation process, please check distutils documentation first.

Before you start using XPPy make sure that path to XPP is present in your PATH variable. Easy way to check that is to type xppaut in the terminal window outside the XPP directory, that should open XPP window. Sometimes Python in Windows reads the PATH variable in a weird way. You can then add path to XPP to your PYTHONPATH variable; more on PYTHONPATH you can find in the Python documentation. If you have some problems with XPP itself, please refer to XPP documentation.

Usage

Brief information about the particular modules can be found in the README.txt file.

The below code gives an example of usage of XPPy's parser and runner.

import xppy
import pylab as pl # Just for plotting, not necessary otherwise

# XPP ode file
ode_file = 'my_model.ode'
# XPP set file, optional
set_file = 'my_model_1.set'

# Create temporary (copies) of ode and set file.
# For security reasons it is better to work on copies instead of original files.
xppy.createTmp(ode_file, set_file)

# List with papameters to change, you can use constants or variables
ib = 1.23
pars = [['par', 'app_a', 0],
        ['par', 'app_d',  2],
        ['par', 'i_hold', ib]]
# Change parameters in the temporary set file
# (you can change specific file by giving it's name as the argument)
xppy.changeSet(pars)
# To change ode file type
#xppy.changeOde(pars)

# Perform a run (Init->Go in XPP);
# use temporary files by default.
# If temporary set is present, it's going to be used;
# you can alternatively specify ode and set file as parameters.
o = xppy.run()

# Perform a run using last values as initial conditions (Init->Last in XPP).
# If no output file is given, two simulations will be run to get initial cond.
o = xppy.runLast(o)

# Output file is a class with numpy array which can be addressed using
# names of variables
print o

# Let's say that we want to print first variable called 'x' in ode file,
# so to plot time trace of 'x' just write
pl.plot(o['t'], o['x'])
# or alternatively use standard numpy approach
pl.plot(o[:,0], o[:,1])
# mixed up approach also works
pl.plot(o[:,'t'], o[:,'x'])

# If you want to work only on 't' and 'x' you can create new object
d = o[:,['t','x']]
# or in a less orthodox way
d = o[['t','x']]
# but d = o['t','x'] will not work.
# Note that in the outcome you get a numpy array object NOT a XPPy output object.

The below example shows the usage of the output class with a saved data file.

# We begin by importing the Output class
from xppy.utils.output import Output
# Let us assume that we have model file 'my_model.ode' and a simulation run of this model saved in 'run_1.dat'.
# We can now create an output object as
o = Output('my_model.ode', 'run_1.dat')
# Now we can use output object as usual, e.g.
d = o[:,['t','x']]
# Note that the order of variables is defined in the ode file.
# Therefore, make sure that data file is made with the correct ode file,
# otherwise output labels may point to different (wrong) columns.

Examples for other modules will be provided later.

How to cite XPPy?

If you want to refer to XPPy in a publication, you can use "Nowacki J. XPPy. 2011. Available at: http://seis.bris.ac.uk/~enxjn/xppy/."

@misc{xppy,
      author = {Nowacki, Jakub},
      title = {{XPPy}},
      url = {http://seis.bris.ac.uk/~enxjn/xppy/},
      year = {2011}
}