XPP � Matlab interface

� Robert Clewley, August 2004 version.



This document describes three Matlab utilities that provide an elementary interface between Matlab and Bard Ermentrout�s XPP software. They have been tested on Linux and Windows platforms, but not yet on Macs. There should be no problem using these functions on Macs, but please let me know if there are. I have assumed the name of the XPP command in Mac OS is xppaut. If this is not the case on your computer then the command string can be passed explicitly to the Matlab function that calls XPP (see below).


The principal use of the utilities is to run large batch jobs which involve several range parameters, or to change parameters or initial conditions interactively with XPP as part of a numerical search algorithm. Matlab�s internal differential equation solvers are often slower than their equivalent implementations in XPP, and for large coupled systems they are less intuitive to code in my opinion. While there is some overhead involved in loading an ASCII-format simulation data file into Matlab for every XPP batch run, I have found the loss of speed a small price to pay for the added convenience. I compared XPP�s internal range facility, over two parameters, with an equivalent Matlab script that implemented the same ranges, and found that my Matlab scripts ran approximately 30% slower.(Omitting auxiliary variables from the version of the ODE file manipulated by these utilities can cut this overhead substantially.)


Additionally, these utilities provide a means to post-process XPP simulation data with any of the statistical functions built into Matlab, or your own. For instance, the included utility GetCrossings finds threshold crossings in continuous-time data (e.g. spike times in neural membrane potentials), from which spiking frequencies are easily computed. This means that less experienced XPP users may therefore find that they can interact with XPP without having to learn to write dynamically linked C library functions, or to cunningly hack �exotic� XPP solutions to their data processing needs (no offense, Bard :).


Two utilities (ChangeXPPodeFile and ChangeXPPsetFile) are designed to provide a simple way for the user to change initial conditions and parameter values of named variables and parameters in either an XPP �.ode� or �.set� file that you have already set up. Keeping backups of these files is very important before you let these utilities stomp all over your carefully-tuned parameter set. The values to be changed in the XPP files are set up using a Matlab structure array, which resembles a C structure array. For instance, if you wanted to change two parameters and one initial condition for an ODE, you could build the following structure array in a Matlab script. The array can be in any order, provided every entry is a structure having precisely three fields: type (string, either �IC� or �PAR�), name (string, a valid name of a variable or parameter in the ODE file), and val (any finite real number).







mypars(1).type = �IC�

mypars(2).type = �PAR�

mypars(3).type = �PAR�

mypars(1).name = �x�

mypars(2).name = �a�

mypars(3).name = �c�

mypars(1).val = 0.5

mypars(2).val = 3.1e-5

mypars(3).val = 100



The function RunXPP is a simple way to run XPP as a command-line executed call from within Matlab, that allows specification of a SET file or the re-seeding of the random number generator. The ODE or SET files should already be changed using the above utilities before calling RunXPP.


The final utility, GetCrossings, gives a simple method to take a loaded data set and search for threshold crossings within particular variables� time-courses. The threshold is an argument to the function, as is the direction of threshold traversal, which is specified the same way as for the global command in XPP.


Also included is an ODE file, HH_slowNa.ode, describing a model for a Hodgkin-Huxley neuron with a slow potassium current, and a Matlab script, meshplot_example.m, for calculating the frequency response as two parameters are varied, the current drive and the slow potassium maximal conductance. The script produces a 3-dimensional plot of the frequency response surface, which is included as the file freq_mesh.fig. This script combines the use of all the included utilities, and can be used as a basis for development of your own scripts and functions. It contains numerous comments.


Finally, if you have any error reports or suggestions for development of these functions please email me.


Description of the Matlab functions


Change parameters / initial conditions in XPP ODE file


success = ChangeXPPodeFile(filename, parset)


ChangeXPPodeFile changes the values of the parameters and initial conditions named in the parset structure by directly modifying the named ODE file. The return value success is a boolean.


All initial conditions to be changed must be explicitly declared in the ODE file using init or i, not using the format x(0) for a variable x, etc. Also, implicitly-declared zero initial conditions cannot be altered by this function. This function has to be able to find an explicit declaration of the initial condition in order to change it. For the latter occasions, you might find it better to use the ChangeXPPsetFile function instead, along with the setfile option of RunXPP. 'number' declarations in XPP are also not supported as range parameters.


Input arguments:

filename must end with the extension '.ode'

parset is a structure array with fields type, name, and val. The type must be one of the strings 'PAR' or 'IC'.



Change parameters / initial conditions in XPP SET file


success = ChangeXPPsetFile(filename, parset)


ChangeXPPsetFile changes the values of the parameters and initial conditions named in the parset structure by directly modifying the named SET file. The return value success is a boolean.


Input arguments:

filename should end with the extension '.set'

parset is a structure array with fields type, name, and val. The type must be one of the strings 'PAR' or 'IC'.



Run XPP in silent mode


success = RunXPP(odeFilename, setFilename, newseed, xppname)

RunXPP runs the XPP executable that is assumed to be in the local directory on the ODE file odeFilename (with extension �.ode�). The optional string argument setFilename can be set to the name of a SET file which will be used by the silent runs of XPP. The optional boolean argument newseed (default is false) that signals XPP to re-seed its random number generator, for instance when running simulations involving random variables. The final, optional, argument xppname additionally specifies the name of the XPP executable file if the default name �xppaut� that is assumed by RunXPP is not correct. The return value success is a boolean.



Convert simulation output data into threshold crossing times


crossings = GetCrossings(data, threshold, maxcrossings, dirn, indices, verboseTog)


GetCrossings takes an array of simulation data with time in the first column, variables in remaining columns, and a threshold crossing value. This function detects threshold crossings in the direction given by dirn in all variables. Use dirn = -1 for decreasing threshold crossings, 1 for increasing threshold crossings. Use dirn = 0 for detection of all threshold crossings, in either direction. Linear interpolation is used to find the crossing times accurately. The optional 5th argument indices is a list of indices to select from the variable columns (when there are mixture of spiking and non-spiking variables present in the passed data set). If it is omitted, all the variable columns are searched.


The result is an array, crossings, having dimensions |indices| by maxcrossings. In each of the rows are the crossing times of each variable in the passed data set. maxcrossings is set to 100 by default if it is omitted. However, if maxcrossings is set at 0, the function returns a cell array of crossing time cell arrays, with rows of length equal to the number of crossings in the data.


The final, optional, boolean argument verboseTog controls suppression of warning messages (defaults to false).