Chapter 10 Serious
Oscill8 Documentation: Details
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. 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 BioSPICE dashboard.
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, there are example ODE 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 diretory.
Now, with the ODEs in hand, we need to import them into Oscill8. This can be done
in one of two ways:
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).
Run navigation hotkeys
The ODE file format used by Oscill8 is a pared down version of XPPAUT's ODE format. It includes the following elements:
In particular, one should note the lack of functional expressions and the fact that all mathematical expressions must be ALGEBRAIC combinations of velocities, state variables, and parameters. (This means NO special functions are currently defined, like "sqrt", "sin", or "exp"). The plan is to make our ODE format much more compatible with XPPAUT's format to include these missing features, but to aide users in the current situation, we have a utility that can convert XPPAUT's ODE format to ours (see ode_clean).
Currently, Oscill8 offers integration of ODE models via CVODE, an efficient stiff integrator. Oscill8 takes a fraction of a second to integrate fairly large, stiff systems with 30+ state variables by using a [relatively ;-)] efficient expression parser and CVODE.
To run a time series, navigate to one of the run menus -> "Time Series", which pops up the run configuration window (see here for detials on run configuration). For a time series, there are a few important parameters:
Naturally, the primary purpose of this tool is to ease bifurcation analysis! To that end, Oscill8 provides more than just a glorified interface to AUTO. One can run one parameter and two parameter bifurcation diagrams (via one of the run menus -> "One Parameter" or "Two Parameter") en masse. Oscill8 attempts to provide the user with as much help as possible, including:
This feature is implemented, but not yet available to the user. It will be available in release 1.3 (see the roadmap for details).
This feature is currently being implemented and will be available in release 1.3 (see the roadmap for details).
The run configuration dialog exposes parameters specific to each run type, in addition to numerical parameters used to control the algorithms. There is also a "Set Model Data" button which allows the user to change data associated with the state variables and control parameters, including
The "Settings" pulldown menu includes "Run", "ODE", and "Continuation" and allows the user to access parameters specific to those algorithms. For example, the "Continuation" settings with give the user the following window:
Here, we can control AUTO with all the usual constants. (There are a few parameters which are not exposed which control the problem type, etc--in the future, these may be exposed for raw AUTO runs if necessary). There are tooltips for each of the constants so that the user can understand what each means when it's not obvious.
Emery Conrad, $Id: details.html,v 220.127.116.11 2005/10/12 20:54:18 emeryconrad Exp $