                                 LotkaVolt v1.0b
                                 ===============

Contents
========

1. Introduction
2. Notice
3. File List
4. Requirements
5. Installation
6. Usage
7. Interface
  7.1. Menu
  7.2. Graph
  7.3. Species Tab
    7.3.1. Density
    7.3.2. Rate
    7.3.3. Color, Line and Points
  7.4. Parameters Tab
  7.5. Other Controls
    7.5.1. Time Step
    7.5.2. Simulation speed
    7.5.3. Start button
8. Credits
9. Release Notes
10. To Do List
11. References

-----------------------------------------------------------------------------
1. Introduction
===============

LotkaVolt is a simple non-spatial two-species competition simulation.  
It started as a Lotka-Volterra model [1] but has grown to reproduce 
other models of the same type.  Given two differential rate equations it 
numerically integrates them and displays the resulting time evolution.

-----------------------------------------------------------------------------
2. Notice
=========

LotkaVolt is free software.

There is no warranty for damages caused by using this software.

Without written permission from the author (Rik Blok), you may not
distribute modified packages of this software, and may not distribute
this software for profit.

Before you send requests, questions and bug reports to the author,
please carefully read this file and Math.txt.  However, feedback is
appreciated.

You may find the latest version of this software at
http://www.physics.ubc.ca/~blok/files.html#LotkaVolt
(The address may be changed in future.)

Rik Blok
blok@physics.ubc.ca
http://www.physics.ubc.ca/~blok/
November 6, 1998


-----------------------------------------------------------------------------
3. File List
============

LotkaVolt.exe - the main program
Math.txt      - description of the mathematical expression parser
ReadMe.txt    - this file
Source.zip    - source code (Borland C++Builder v1.0)
brown93 *.ini - sample simulation configuration files which reproduce 
                figures from reference [1]

In detail, the above configuration files represent:
brown93 Fig10.1*.ini  - Lotka-Volterra (competition) model
brown93 Fig10.11.ini  - Holling-Tanner (predator-prey) model
brown93 Fig10.15*.ini - Nicholson-Bailey (host-parasitoid) model
brown93 Fig10.19*.ini - Kermack-McKendrick (SIR epidemic) model
                        (without the "R"s)

-----------------------------------------------------------------------------
4. Requirements
===============

Supported operating systems:

	MS-Windows 95/98
	MS-Windows NT 3.51 and 4.0

This software has successfully been tested on a Pentium computer running 
Windows 95 and a Pentium II running Windows NT 4.0.  It may (?) also run 
in the Windows 3.x environment if the Win32s extension has been 
installed.

-----------------------------------------------------------------------------
5. Installation
===============

Extract and copy all files to a single directory.  The configuration 
files (*.ini) are optional.  

This program does not modify the computer in any way except that it adds 
a file LotkaVolt.ini (which contains user preferences) to the current 
directory.

To uninstall simply remove all installed files and the file
LotkaVolt.ini.

-----------------------------------------------------------------------------
6. Usage
========

Command-line:

	LotkaVolt.exe [config.ini]

where:

	config.ini (optional) - a simulation configuration file to load on
	startup.

Examples:

	LotkaVolt.exe
	LotkaVolt.exe "brown93 Fig10.1(d).ini"

-----------------------------------------------------------------------------
7. Interface
============

To use LotkaVolt you set the initial densities and rate equations
(rate-of-change of species density, an arbitrary mathematical
expression) for both species. You can optionally use constant parameters
when specifying the rates, which you specify in the Parameters Tab
(parameter name, value (real number), then optional description).  Of
course, you can also use the variable names N1 and N2 in your rate
equations, which represent the current densities.

Once you've got your model set up, choose a reasonable time step 
(increment) and hit [Start].  A plot of density vs. time for both 
species should emerge.  You can right-click on the graph to get some 
more options like printing or copying the graph to the clipboard.  

Continue reading for more details.

  7.1. Menus
  ----------

File > Load - load a configuration file from disk

File > Save - save the current configuration to file
	
File > Exit - exit program

Run > Start/Pause/Continue - commence integrating the rate equations 
with the current configuration (toggle).  Also available from the Start 
button and the graph pop-up menu.

Run > Reset - erase all accumulated data and reset time to zero.  As 
data accumulates performance degrades and the computer may become low on 
memory. To improve performance and avoid a possible error, use this 
option to clear all data.  Also available from the graph pop-up menu.

Graph > Copy to clipboard - copy the graph to the clipboard (as a 
Windows metafile) for insertion into other documents.  Also available 
from the graph pop-up menu.

Graph > Print - print graph to current printer.  If you have problems 
printing try changing the species colours to shades of gray.  Adds a 
legend to the graph when printing.

Graph > Save as bitmap - save graph to disk as a color bitmap

Help > About - information about LotkaVolt

  ---------------------------------------------------------------------------
  7.2. Graph
  ----------

The graph displays the evolving densities of the two populations over 
time. Display of the data series is controlled from the Species Tab.  
The vertical axis represents the densities of the two species (the 
values N1 and N2) and the horizontal axis represents time.

Right-clicking on the graph brings up a pop-up menu with the following 
options:

Running - (default action) toggles between running (check mark) and 
paused.  Same as "Run > Start/Pause/Continue" menu option.

Copy - same as menu option "Graph > Copy to clipboard"

Print - same as menu option "Graph > Print"

Save as Bitmap - same as menu option "Graph > Save as bitmap"

  ---------------------------------------------------------------------------
  7.3. Species Tab
  ----------------

The Species Tab allows you to specify the properties particular to each
species.  

    7.3.1. Density

The density is a generic term for the instantaneous value of the property you
are modelling.  This may represent population density, absolute number, 
temperature, or anything the model is meant to represent.  The value must be 
non-negative.  These densities are stored within the variables N1 and N2, 
respectively.

    -------------------------------------------------------------------------
    7.3.2. Rate

The core of the model is contained within the two rate equations for the 
species which describe the time rate-of-change of the densities (N1 and 
N2).

	d N1                d N2
	---- = ...,	        ---- = ....
	 dt                  dt

The species density time evolution is calculated by numerically 
integrating the above rates via

	N1(t+dt) = N1(t) + dt * dN1/dt
	N2(t+dt) = N2(t) + dt * dN2/dt

where dt is the Time Step (see Other Controls).  The equations are 
solved simultaneously meaning that if the rates depend on N1 and N2, 
these values, calculated at time t, are substituted into both equations 
before the new values at time t+dt are computed.

The rate equations may be mathematical expressions involving numbers, 
operators, functions, constant parameters (see the Parameters Tab), and 
the variables N1 and N2.  Valid operators and functions are listed in 
the file Math.txt.  Note that the rate equations are case-INsensitive: 
dN1/dt = -n1 is interpreted the same as dN1/dt = -N1.

If your model is in the form of a map, such as

	a(t+1) = f(a(t), b(t))
	b(t+1) = g(a(t), b(t))

where f() and g() are functions, then you can rewrite this in terms of 
rates by using a time step of 1 and setting

	dN1/dt = f(N1,N2) - N1
	dN2/dt = g(N1,N2) - N2

where N1 represents a and N2 represents b.

    -------------------------------------------------------------------------
    7.3.3. Color, Lines and Points

The display of each species in the graph can be customized by specifying 
the color to use and whether to display lines, points, or both.  Points 
improve visibility but are costly in speed intensive runs.  For maximum 
speed temporarily disable both lines AND points until you have acquired 
sufficient data.

  ---------------------------------------------------------------------------
  7.4. Parameters Tab
  -------------------

You can specify constant parameters which are available to both rate 
equations in the Parameters Tab.  The grid supports up to 20 parameters 
which are set by by specifying a variable name (in the Name column) and 
a numerical value (in the Value column).  You can also add a description 
of the parameter in the Description column.  The parameters can be 
reordered by grabbing the button to the left of each row and dragging it
up or down.  Valid variable names are described in the file Math.txt.

To delete a parameter simply erase its name from the leftmost column and 
it will not be used when evaluating the rate equations.

If you enter an illegal value for a parameter it will be replaced by 
zero when you start the simulation.

  ---------------------------------------------------------------------------
  7.5. Other Controls
  -------------------

    7.5.1. Time Step

As mentioned above the simulation evolves by numerically integrating the 
two rate equations according to the following equations:

	N1(t+dt) = N1(t) + dt * dN1/dt
	N2(t+dt) = N2(t) + dt * dN2/dt

where dt is the time step or increment.  This value can be adjusted via 
the Time Step edit box, it must be a positive value.  A larger value 
results in faster, but rougher integration and a smaller value gives a 
slower but more precise simulation.  Sometimes the dynamics depend 
strongly on the time increment, too large a value give wildly erratic 
dynamics.  To test for this, you should always repeat your simulation 
with several different time increments.  An example of this effect can 
be found in the configuration file "brown93 Fig10.11.ini".  As the time 
step is increased from 0.01 the oscillations grow larger until, near 
dt=1, the populations crash.

    -------------------------------------------------------------------------
    7.5.2. Simulation speed

You can adjust the speed at which the simulation is played out with this
trackbar.  Each increment cuts in half the pause between time steps 
(subject to computer resources).  At maximum speed there is no delay and 
the display is updated less frequently than the calculations which greatly
improves the speed.  Unfortunately, this also leads to an unavoidable flicker
in the graph.  To eliminate the flicker, reduce the simulation speed.

    -------------------------------------------------------------------------
    7.5.3. Start button

This is just a shortcut button to allow you to start/pause the simulation.
It behaves the same as the "Run > Start" menu option.

-----------------------------------------------------------------------------
8. Credits
==========

This software is possible due to support from the Peter Wall Institute 
for Advanced Studies, Crisis Points Group 
(http://www.geog.ubc.ca/crpoints/).  Thanks especially to Michael
Baumann for jogging my interest in biological modelling and Bea Beisner
for her helpful comments.  Thanks also to Dr. Birger Bergersen allowing
me the scholastic freedom to work on this project.

This program was made possible by the generous sharing of program segments
(components) by various experts.  Thanks to:

- Grahame Grieve <grahame@kestral.com.au> and Kestral Computing for
their TxyGraph component (the graph)

- Lucian Wischik <ljw1004@cus.cam.ac.uk> for his TAnimTimer component (a
high-resolution timer) <http://www.wischik.com/lu>

- Alin Flaider <aflaidar@datalog.ro> and Stefan Hoffmeister
<Stefan.Hoffmeister@Uni-Passau.de> for their TParser component
(mathematical expression parser)

- Brad Stowers for his TDFSColorButton component (color select button)
<http://www.pobox.com/~bstowers/delphi/>

- Fedor Koshevnikov <fkozh@usa.net>, Igor Pavluk <ipavluk@usa.net> and
Serge Korolev <korolev@usa.net> for their TFormStorage component (part
of the RxLib library) <http://rx.demo.ru>

-----------------------------------------------------------------------------
9. Release Notes
================

v1.0b November 6, 1998
	- fixed cropped labels seen on some resolutions/font sizes
	- plot colors and options (lines/points) saved between sessions
v1.0  May 8, 1998
	- cosmetic changes
	- major speed improvement
	- fuller documentation
v0.1  April 30, 1998
	- limited release


-----------------------------------------------------------------------------
10. To Do List
==============

- a help file (and improve this documentation)
- save data to a file (eg. comma-separated values)
- add a simultaneous phase plane plot?
- support explicit time-dependence in rate equations


-----------------------------------------------------------------------------
11. References
==============

[1]	Brown D and Rothery P (1993) 'Models in Biology: Mathematics, 
	Statistics and Computing' (Wiley)


