README for WINPP

1. INTRODUCTION
This version of WINPP comes as a winzipped file witha bunch of ODE examples
and some very minimal documentation. I don't have that much time to write
this stuff and never was very good at it. XPP which begat this program has
more extensive documentation although there are some substantial differences.
However, the basic structure of the input files is identical.

WINPP is a program designed to solve dynamical systems problems that take

several different forms: (i) ordinary differential equations (ODEs); (ii)
delay differential equations (DDEs); (iii) differential-algebraic equations
(DAEs); (iv) Volterra integro-differential equations (IDEs); (v) discrete
dynamical systems (MAPs); (vi) boundary value problems (BVP).

The basic idea is to create an input file with any text editor. This file
tells WINPP the equations, parameters, functions, etc that are to be used
in the numerical simulation. In addition, it is possible to define plot parameters,
etc within the file. The interface is based on Win95/NT and will not run
under Windows 3.*. All aspects of the simulation can be changed within the
program using the interface, but the names of variables and the dimension
of the system cannot be changed nor can a new file be loaded in without exiting
first.

To run WINPP, just click on the icon for it and then use the file
selector to choose an ODE file. Alternatively, you can type it from the
DOS prompt followed by an ODE file name:

winpp pend.ode

LOGFILE

Every time you run WINPP, the program creates a file called WPP.LOG in the
directore where WINPP is found if called by clicking on the icon or in
the initiating directory if called from the DOS Prompt. This can be
used to see any comments etc that the program produces such as error
messages etc. If you run with a bad ODE file, this will tell you what
was wrong.

SIMPLE COMMANDS

1. To integrate the equations, click on Run Go. Or just type Ctrl G.

2. Change parameters by editing the parameter windows and then clicking
on OK in the window or clicking on Go. Change initial conditions this
way as well.
3. To change the View, Click on Graphics View or Ctrl-V. Check the
Autofit box to have WINPP choose the limits. Choose 2 or 3 dimensional
plots.
4. A quick way to plot a quantity versus time is to click Graphics XvsT
or Ctrl-X.
5. Ctrl-E erases the window and Ctrl-R redraws it.
6. File Exit will get you out as will Ctrl-Q.
7. To change integration parameters, click on Numerics Int. Pars. or
type Ctrl I.
8. Click on Edit Copy to copy the picture to the clipboard and then
paste it into your own documents.
9. Use the Browser to look at the numbers from your simulation, save
the data in space delimited ascii format (to import with EXCEL, etc)
and read in similar data to plot.
10. The only hardcopy currently avaiable is POSTSCRIPT - click File
Print to create a postscript black and white or color picture.

2. INPUT FILES
The standard convention for WINPP is to name files with the extension
ODE. I will call such files ODE files. They all have the following
format. Note that there should be no spaces between a number and an
equals sign in the definions of parameters and initial values of
phase-space variables.

ODE File Format

# comment line - name of file, etc

d<name>/dt=<formula>
<name>'=<formula>
<name>(t)=<formula>
volt <name>=<formula>
<name>(t+1)=<formula>
x[n1..n2]' = ...[j] [j-1] ... <-- Arrays
markov <name> <nstates>
{t01} {t02} ... {t0k-1}
{t10} ...
...
{tk-1,0} ... {tk-1 k-1}

aux <name>=<formula>
!<name>=<formula>
<name>=<formula>
parameter <name1>=<value1>,<name2>=<value2>, ...
wiener <name1>, <name2>, ...
number <name1>=<value1>,<name2>=<value2>, ...
<name>(<x1>,<x2>,...,<xn>)=<formula>
table <name> <filename>
table <name> % <npts> <xlo> <xhi> <function(t)>
global sign {condition} {name1=form1;...}
init <name>=<value>,...
<name>(0)=<value>
bdry <expression>
0= <expression> <--- For DAEs
solv <name>=<expression> <------ For DAEs
special <name>=conv(type,npts,ncon,wgt,rootname)
fconv(type,npts,ncon,wgt,rootname,root2,function)
sparse(npts,ncon,wgt,index,rootname)
fsparse(npts,ncon,wgt,index,rootname,root2,function)
# comments
@ <name>=<value>, ...
done

INTEGRAL EQUATIONS
The general integral equation:
u(t)=f(t)+int(0,t) K(t,s,u(s))ds

becomes

u = f(t) + int{K(t,t',u)}
The convolution equation:

v(t) = exp(-t) + int(0,t) e^{-(t-s)^2}v(s) ds

would be written as:

v(t) = exp(-t) + int{exp(-t^2)#v}

If one wants to solve, say,

u(t) = exp(-t) + int(0,t) (t-t')^{-mu} K(t,t',u(t'))dt'

where 0 <= mu < 1

the form is:

u(t)= exp(-t) + int[mu]{K(t,t',u}

and for convolutions, use the form:

u(t)= exp(-t) + int[mu]{w(t)#u}

OPTIONS

The format for changing the options is:

@ name1=value1, name2=value2, ...

where { name} is one of the following and { value} is either an

integer, floating point, or string. (All names can be upper or lower
case). The first option can only be set outside the program.

** MAXSTOR={ integer} sets the total number of time steps that

will be kept in memory. The default is 5000. If you want to perform
very long integrations change this to some large number.

The remaining options can be set from within the program. They are

** XP=name sets the name of the variable to plot on the x-axis.

The default is { T}, the time-variable.
** YP=name sets the name of the variable on the y-axis.
** ZP=name sets the name of the variable on the z-axis (if the plot
is 3D.)
** AXES={2,3} determine whether a 2D or 3D plot will be
displayed.
** TOTAL=value sets the total amount of time to integrate the
equations (default is 20).
** DT=value sets the time step for the integrator (default is 0.05).
** NJMP={ integer} tells XPP how frequently to output the
solution to the ODE. The default is 1, which means at each
integration step.
** T0=value sets the starting time (default is 0).
** TRANS=value tells XPP to integrate until { T=TRANS} and then
start plotting solutions (default is 0.)
** NMESH={ integer} sets the mesh size for computing nullclines
(default is 40).
** METH={ discrete,euler,modeuler,rungekutta,adams,gear,volterra, backeul,
qualrk,stiff,cvode } sets the integration method (see below; default is
Runge-Kutta.
** DTMIN=value sets the minimum allowable timestep for the Gear
integrator.
** DTMAX=value sets the maximum allowable timestep for the Gear
integrator
** { JAC_EPS=value, NEWT_TOL=value, NEWT_ITER=value} set
parameters for the root finders.
** ATOLER=value sets the absolute tolerance for CVODE.
** TOLER=value sets the error tolerance for the Gear, adaptive RK,
and stiff integrators. It is the relative tolerance for CVODE.
** BOUND=value sets the maximum bound any plotted variable can
reach in magnitude. If any plottable quantity exceeds this, the
integrator will halt with a warning. The program will not stop
however (default is 100.)
** DELAY=value sets the maximum delay allowed in the integration
(default is 0.)
** XLO=value,YLO=value,XHI=value,YHI=value set the limits for
two-dimensional plots (defaults are 0,-2,20,2 respectively.) Note that
for three-dimensional plots, the plot is scaled to a cube with
vertices that are +/-1 and this cube is rotated and projected onto
the plane so setting these to +/-2 works well for 3D plots.
** XMAX=value, XMIN=value, YMAX=value, YMIN=value, ZMAX=value, ZMIN=value
set the scaling for three-d plots.
** POIMAP={ section,maxmin } sets up a Poincare map for
either sections of a variable or the extrema.
** POIVAR=name sets the variable name whose section you are
interested in finding.
** POIPLN=value is the value of the section; it is a floating
point.
** POISGN={ 1, -1, 0 } determines the direction of the
section.
** POISTOP=1 means to stop the integration when the section is
reached.
** RANGE=1 means that you want to run a range integration (in batch
mode).
** RANGEOVER=name, RANGESTEP=number, RANGELOW=number, RANGEHIGH=number,
RANGERESET={ Yes,No}, RANGEOLDIC={ Yes,No} all correspond to
the entries in the range integration option.
** TOR_PER=value, defined the period for a toroidal phasespace and
tells WINPP that there will be some variables on the circle.
** FOLD=name, tells WINPP that the variable <name> is to be
considered modulo the period. You can repeat this for many variables.

RESERVED WORDS

You should be aware of the following

keywords that should not be used in your ODE files for anything other
than their meaning here.

sin cos tan atan atan2 sinh cosh tanh

exp delay ln log log10 t pi if then else
asin acos heav sign ceil flr ran abs
max min normal besselj bessely erf erfc
arg1 ... arg9 @ $ + - / * ^ ** shift
| > < == >= <= != not # int sum of i'
These are mainly self-explanatory. The nonobvious ones are:

** { heav(arg1)} the step function, zero if { arg1<0} and 1 otherwise.

** { sign(arg)} which is the sign of the argument (zero has sign 0)
** { ran(arg)} produces a uniformly distributed random number
between 0 and { arg.}
** { besselj, bessely } take two arguments, n,x and return
respectively, J_n(x) and Y_n(x), the Bessel functions.
** { erf(x), erfc(x)} are the error function and the
complementary function.
** { normal(arg1,arg2)} produces a normally distributed random number
with mean { arg1} and variance { arg2}.
** { max(arg1,arg2)} produces the maximum of the two arguments
and { min} is
the minimum of them.
** { if(<exp1>)then(<exp2>)else(<exp3>)} evaluates { <exp1> }
If it is nonzero
it evaluates to { <exp2>} otherwise it is { <exp3>}. E.g. {
if(x>1)then(ln(x))else(x-1)} will lead to { ln(2)} if { x=2} and { -1
if x=0.}
** { delay(<var>,<exp>)} returns variable { <var>} delayed by the result of
evaluating { <exp>}. In order to use the delay you must inform
the program of the maximal possible delay so it can allocate storage.
(See the section on the NUMERICS menus.)
** { ceil(arg),flr(arg)} are the integer parts of{ <arg>} returning the
smallest integer greater than and the largest integer less than { <arg>}.
** { t } is the current time in the integration of the differential equation.
** { pi} is pi
** { arg1, ..., arg9} are the formal arguments for functions
** { int, #} concern Volterra equations.
** { shift(<var>,<exp>)} This operator evaluates the expression
{ <exp>} converts it to an integer and then uses this to indirectly
address a variable whose address is that of { <var>} plus the
integer value of the expression. This is a way to imitate arrays in
WINPP. For example if you defined the sequence of 5 variables, {
u0,u1,u2,u3,u4} one right after another, then { shift(u0,2)} would
return the value of { u2.}
** { sum(<ex1>,<ex2>)of(<ex3>)} is a way of summing up things.
The expressions { <ex1>,<ex1>} are evaluated and their integer
parts are used as the lower and upper limits of the sum. The index of
the sum is { i'} so that you cannot have double sums since there is
only one index. { <ex3>} is the expression to be summed and will
generally involve { i'.} For example { sum(1,10)of(i')} will
be evaluated to 55. Another example combines the sum with the shift
operator. { sum(0,4)of(shift(u0,i'))} will sum up { u0} and the
next four variables that were defined after it.

EXAMPLES

Here I present some example ODE files that you are welcome to try out.

EXAMPLE 1. DAMPED PENDULUM. This is a second order system rewritten as

a pair of first order equations. The friction is mu, the length of
the pengulum is l, mass is m, and gravity is g.

# damped pendulum pend.ode

# equations:
dx/dt = xp
dxp/dt = (-mu*xp-m*g*sin(x))/(m*l)
# energy
pe=m*g*(1-cos(x))
ke=.5*m*l*xp^2
# auxiliary plottable quantities
aux P.E.=pe
aux K.E.=ke
aux T.E=pe+ke
# parameters
param m=10,mu=2,g=9.8,l=1
param scale=0.0083333
@ bounds=1000
# initial position
x(0)=2
# end of the equation file
done

COMMENTS:
1. I have defined some extra quantities called pe and ke. These are
called "fixed variables" and are defined in terms of phase variables
and parameters etc. They are used internally but not accessible to the
user. Only phase variables (those that obey dynamics) and auxiliary
quantities can be plotted and viewed.
2. I have defined some auxiliary variables that can be viewed by the
user.
3. Run this and look at a 3D view with X along the X-axis, XP along the
Y-axis, and T along the Z-axis; use the Autofit option.

EXAMPLE 2. Stochastic equations

In this example a differential equation for voltage is coupled to a

single channel that stochastically jumps between two states, 0 and 1.

# hhnasing.ode
# single channel sodium channel with greatly enhanced single channel
# conductance.
dv/dt = -gl*(v-vl) -gna*m*(v-vna)+I
markov m 2
{0} {am(v)}
{bm(v)} {0}
#
init v=0,m=0
#
am(v)=PHI*.1e0*(.25e+02-v)/(EXP(.1e0*(.25e02-v))-.1e+01)
bm(v)=PHI*4.0e0*EXP(-v/1.8e01)
# parameters
par i=0,vna=115,vl=0,gna=.1,gl=.3,phi=1
#
done

COMMENTS:
1. The random variable, m, has two states open (1) and closed (0). The
rates of switching between the states are defined by a 2x2 array (or if
there were 5 states, 5x5) of switching rates, a_ij. The probability of
jumping from state i to state j is a_ij*dt. In WINPP, the diagonal
terms are ignored since the row sums must always be 1. Here am(v) is
the voltage-dependent rate of jumping from state 0 to state 1.
2. WINPP is case-insensitive so EXP and Exp and eXp are all the
exponential function.
3. Floating point exponents are of the form #e+#, #e-#, #e#, where # is
any number.
4. The functions am(v) and bm(v) are defined by a simple obvious
statement.
5. Run this simulation and look at the voltage and the channel states

EXAMPLE 3: Delay-differential equations

In this example, a nonlinear scalar feedback system is defined.

# delayed feedback: delay.ode

# declare all the parameters, initializing the delay to 3

p tau=3,b=4.8,a=4,p=-.8
# define the nonlinearity
f(x)=1/(1+exp(-x))
# define the right-hand sides; delaying x by tau
dx/dt = -x + f(a*x-b*delay(x,tau)+p)
x(0)=1
@ total=40,xhi=40,ylo=0,yhi=1,delay=10
# done
done

COMMENTS:
1. The "@" symbol is used to initialize internal plot and simuation
parameters so that theuser doesnt have to do it manually within the
program. Here I have set the total integrateion time to 40 and also
made the x and y axes optimal for the simulation. Finally, I have set a
parameter called "delay" which tells WINPP to allocate enough storage
so that it can access delays as far back as 10. I only needed 3 for
this simulation.
2. Within a right-hand side the function delay(x,tau) produces,
x(t-tau).
3. Run this. Then move the mouse into the plot window, hold down the
button and move around. Note how the (x,y) values are displayed. Find
the period of the oscillation. It is about 9.7

EXAMPLE 4. Integro-differential equations

Here is a simple integro-diffential equation.

# tstvol2.ode
# Volterra example from Peter Linz's book
# solution is f1=1,f2=t but it is unstable
f1(0)=1
f1(t)=exp(-t)-t^2/2 + int{exp(-t)#f1*f1}+int{f2}
f2(t)=t-t^4/24+int{t#f2*f2/(1+f1*f1)}
@ yplot=f2,total=5,xhi=5,yhi=5
done

COMMENTS:
1. The first integral operator convolves exp(-t) with f1(t)^2 and the
second one convolves t with f2(t)^2/(1+f1(t)^2)
2. yplot=f2 tell WINPP to plot f2(t).
3. Run this. Then click on Graphics Add/edit. In this dialog, click on
Add New. Make the Y axis of the new curve f1 and make the color Red.
Click on Done and then click on Graphics Redraw (Ctrl-R).

EXAMPLE 5. Differential-algebraic equations

This is a simple DAE. We want to solve:
dx/dt=y
y+x=1

# dae_ex1.ode
x'=y
0= x+y-1
x(0)=0
solv y=1
aux yy=y
done

COMMENTS:
1. The expression "0=" starting a line tells WINPP that the remaining
expression must be set to 0. The expression "solv y=1" tells WINPP that
it "y" is an algebraic variable and that an initial guess should be 1.
2. The variable that is to be solved for, y, is hidden from the user
and in order to see it, the plottable auxiliary variable yy is defined.

Here is a more complex example in which the derivative is implicitly

defined.

dx/dt + exp(dx/dt)=-x

# dae_ex2.ode
x'=xp
0= xp+exp(xp)+x
x(0)=-3.7182
solv xp=1
aux xdot=xp
@ ylo=-4,yhi=0
done

COMMENTS:
1. Note that the root solver solves for xp and this is just dx/dt.

In this last example of a DAE, we solve a relaxation oscillator by

making the tolerance for solving the root somewhat large and thus
letting numerical errors take the problem over singulities.

#dae_ex3.ode
w'=v_
0= v_*(1-v_*v_)-w
solv v_=1
aux v=v_
@ NEWT_ITER=1000,NEWT_TOL=1e-3,JAC_EPS=1e-5,METH=qualrk
done

COMMENT:
1. Plot v and w in a phase-plane

EXAMPLE 6. Boundary-value problems.

Here we solve a nonlinear boundary value problem:

x''=x^3 ;x(0)=1 ; x(1)=0

We rewrite it as a pair of first order equations. The ODE file is

# bvp.ode
x'=xp
xp'=a*x^3
bndry x-1
bndry x'
init x=0
par a=1
@ dt=.01,total=1,xhi=1,yhi=1,ylo=0
done

COMMENTS:
1. To run this, Click on Run BVP Show and repeated attempts at solving
using shooting will be shown. If a solution is found the intermediate
solutions will be erased and the final solution will be shown. The
initial value of xp is free to be chosen and will hopefully be found
to satisfy the end condition.
2. Boundary conditions are put in with the statement "bndry". The program
attempts to make them zero. A primed variable means to evaluate the
variable at the end of the integration while unprimed means to evaluate
at the beginning.
3. The total integration time is set here to 1 reflecting the length of
the domain.

Here is a very complicated boundary value problem.

Find a value of omega solving:

d (a'' - ak^2 + a'/t -a/t^2) + a(1-a^2)=0

d (k'+k/t+2ka'/a) + (omega + q a^2) =0

limit (t->0) a(t)/t exists

k(0)=0
k(1)=0
a'(1)=0

Note that 4 conditions must be satisfied (a(0)=0 is implied by the

first condition) but the system is only 3rd order. However omega is a free
parameter, so we write a differential equation for it of the form:

omega'=0

Now the system is 4 dimensional:

# gberg.ode
init a=0.0118 ap=1.18 k=0 omeg=-0.19
par d=0.177 q=0.5 sig=3
# the odes...
a'=ap
ap'=a*k*k-ap/t+a/(t*t)-a*(1-a*a)/d
k'=-k/t-2*k*ap/a-(omeg+q*a*a)/d
omeg'=0
# the boundary conditions
bndry a-t*ap
bndry k
bndry ap'
bndry k'
# set it up for the user
@ xhi=1 t0=.01,dt=.01,total=.99
done
COMMENTS:
1. Since a(t)/t is undefined in the computer as t->0, we start t at a
small value and insist that a(t) = a'(0)t for t small. We integrate
for a total of .99 since we started at t=.01.
2. It is written as a system of first order equations.
3. This equation arises when one looks for spiral wave solutions to a
system of reaction-diffusion equations.

3. WINPP Commands

A. Running a simulation. Click on Run and then one of the options. To

abort a simulation click on STOP. Initial data sre specified by typing
values in the Initial Data boxes or via the menus.

**Go** just uses the current initial data and runs for the amount of time
specified by the Numerics parameters

**Last** uses the end result of the prior intergation as initial

conditions of the current simulation.

**Mouse** lets you click on initial conditions in the graphics window.

NOTE that both axes must be phase-variables; i.e., they must satisfy
differential equations.

**Mice** lets you click on lots of initial conditions repeatedly. Click

on STOP to finish.

**New** lets you specify initial data for variables without clicking in
the initial data box which uses a font that is too small for my aging
eyes.

**More time** lets you add additional time to the integration.

**Range integrate* lets you repeat an integration while varying a

parameter or phase-variable. "Use old ICs" means that the same initial
data (except the state variable that is varied) for each integration.
"Reset storage" means that the data buffer is cleared after each
integration. NOTES: (i)The parameters are reset to their original values after
the task is completed; (ii) Only the last simulation remains in the
data buffer unless "Reset storage" is disabled; (iii) STOP stops a
single integration and ABORT ALL stops all simulations.

**Shoot** uses special initial data that are generated when fixed
points are found. See the section on fixed points.

**BVP** solves boundary value problems. "Show" shows intermediate attempts

at solution.

B. Plotting and browsing.

THE BROWSER

WINPP keeps the results of simulations in a data buffer. You can view
the numbers from the simulation by looking at the Browser. Use the
arrow keys or scroll bars to go through the numbers. There are several
commands:
**Find** will look for the closest value of one of the browser
quantities to the number specified.

**Write** will save the numbers in an ascii space delimited file.

**Load** will load data into the browser for plotting

**Get** will use the numbers in the top row of the browser as initial
data.

**Replace** lets you replace a column with some formula.

**Unreplace** unreplaces the last replace

**AddCol** lets you add a formula column to the browser. All subsequent
integrations will compute the formula.

**DelCol** lets you delete any added columns

GRAPHICS OPTIONS

WINPP lets you plot any quantity versus any other quantity.
**View**

C. Finding Fixed Points.

WINPP uses a Newton Solver to find fixed points.
** Go** uses the current initial data as a first guess
**Mouse** lets you use the mouse to guess
**Range** will find a l