Chapter 10 Serious
Oscill8 Documentation: Quick Start
Currently, we only have a windows version ready for public use. (Release of a
compatible linux version is planned for June 2005). You can get the latest
release at SourceForge.
Download all installers that you're interested in (the setup and examples
installers will give you everything you need as a user) to your hard-drive and
double-click them to install (see image below). You will also need to install
.NET Framework Version 1.1 Redistributable Package in order to have the
GUI function (which you can get from
It is highly recommended at
this point that you use all the default settings the installer offers. Not doing
so may make the current version of the tool unavailable to other tools like the
At this point, you should have a working installation of Oscill8. For those
eager beavers who aren't inclined to read the rest of this document/mini-tutorial,
there are example ODE/O8M files and pre-created workspaces for you
to play with in the $OSCILL8_DIR/examples directory. If you have trouble with
anything, you can return to this document for help!
Before starting, you need to have the right-hand-sides of your ODE model, along
with initial values for the state variables and parameters, stored in a file.
For lack of a better term, we'll call this file an ODE file. The format of this
file is similar to the ODE format used by
XPPAUT, though somewhat simplified. For those of you who already have ODE
files for XPPAUT, they may very well work just fine for Oscill8 (as is more and more
compatible every day!). If you have trouble creating the workspace with a particular ODE file,
you can try using the "ode_clean.pl" perl script
found in the $OSCILL_DIR/bin directory (see utilites
for details) which will attempt to correct any features it knows Oscill8 doesn't support.
Warning: For those of you modeling physical systems,
note that in order to do proper bifurcation analysis, it is
vital that you remove all conserved quantities from your
differential equations. Failing to do so can lead to singularities
(and possibly unexpected results in the early version of the code) while conducting
For those of you in the Biology community, you can also now import SBML files. This
conversion is automatic (for files with the .xml or .sbml extension) if (and only if)
you have JigCell installed, version >= 6.0.1. Warning: until version 1.2 of Oscill8
(see the roadmap for planned release dates), we Oscill8's model
parser doesn't accept functional expressions. If you have an SBML file with functional expressions,
then you'll need to use JigCell by hand to convert to ODE. Then you can use the
"ode_clean.pl" perl script found in the $OSCILL_DIR/bin directory
(see utilitesfor details) to make the file compatible
with the current version of Oscill8.
If you don't have a particular model system in mind right now, you can use one of the
examples included in the distribution. Look in the $OSCILL8_DIR/examples/ode
Now, with the ODEs in hand, we need to import them into Oscill8. This can be done
in one of two ways:
From the command-line, you can run "
oscill8 modelfilename", where modelfilename is
either an ODE file or and SBML file. This will transparently
create an Oscill8 workspace for you in the $OSCILL8_DIR/wscache directory. The workspace
is your home for doing analysis of a particular model in Oscill8.
The other way to get started is to open Oscill8 (either from the command line, with no
arguments, or by double-clicking the icon on your desktop). Then,
click File -> New, which will open the workspace creation window (see
below). You can supply a workspace a name, a base directory in which to
create the workspace (note that the directory you give will have the workspace
name appended to it to create your workspaces home directory), a model
file (or just paste the text into the given model text box), and a few settings
concerning your model. For details on these settings,
see workspace creation settings).
Once you've entered this information,
click "OK" and your workspace will be created.
Once you've created and are in a workspace, you'll notice that several new menu
choices have appeared, including the "Workspace" and "Run" menus. In addition,
you'll see an area to the left of the workspace, which is the run navigation
area. As you do your analysis, this will be the place to return to access and
modify what it is you have created. If at any time you would prefer not to see
this run navigation area, simply click View->Run History, and you'll toggle
the run navigation off. Another area that is not visible by default is the Run
Notes, which appears just below the main graphing area (the bulk of the
interface is the graphing area). You can toggle this feature on and off via the
View menu as well.
There are context sensitive menus for both the run navigation area and the main
graphing area by which you will conduct most of your activities (until you
become familiar with the defined short cut keys). You can activate these menus
with an alternate-click (right-click for most of us).
Now, in order to do anything useful, you'll need to start a run. The easiest
run to do is the Time Series run. This will integrate your model for
the given amount of time and return a data set (and plot it) with the specified
number of data points. Other runs include One Parameter, Two Parameter,
Follow Limit Cycles, Bifurcation Search,
and Bifurcation Matching (see the roadmap for planned
release dates). Try them out and see if you can figure out how they work.
A little advice: for One Parameter runs, Oscill8 will try to find a
steady state by Newton's method.
If that fails, it will integrate the model for a long period of time
looking for a stable steady state. If that fails, it tries Newton
again from the final point of the integration. If this fails, the continuation
fails and you need to make the conditions favorable for Oscill8 to find a
steady state! This means that you need to set the parameters so that
integrating the differential equations will get you to a stable steady state
which can be used as a starting point.
For details on each of these, see details.