Basics

Details

Tutorials

Files

Oscill8 Documentation: Quick Start

• Installation

  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 MSDN Downloads). 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/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!

• Getting your model into Oscill8

  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 bifurcation studies.
  

  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:
  

  1. 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.
  
  
  2. 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.
  
  
  
  
  

• Using the Workspace

  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.