GENESIS Reference ManualMay 5, 2001: Simulations

Previous Next Table of Contents

## 15. Simulations

Broadly speaking, a GENESIS ``simulation'' consists of the following components:

- the complete collection of elements defined in the GENESIS environment at the current time (except for elements excluded by the disable routine); i.e., the elements that define the model, and accessory elements
- the object definitions that define how elements are to be interpreted (e.g., definitions of objects, classes, and so forth)
- the set of messages that provide the way information is passed among elements
- a schedule defining simulation activities and what elements are affected
- the set of simulation clocks defining the relative time for activities

Sometimes, GENESIS users refer to a ``simulation'' as a specific step-through of a given simulation setup (i.e., stepping through a simulation, as defined above, over time) -- a ``run'' of a simulation.

## 15.1 Running a Simulation

Many GENESIS routines help you construct simulations (see, for example, Elements , Messages , Clocks , and so forth). The table below lists routines that specifically deal with preparing the simulation for time-oriented runs:

Routine | Description
abort | Cleanly interrupts simulation in progress.
check | Checks various aspects of simulation for specification errors.
disable | Disables an element and its children from participating in a
| simulation.
enable | Enables previously disabled elements to participate in a
| simulation.
getstat | Returns time, step, or memory use as a function value.
reset | Resets simulation to initial conditions, including calling
| RESET actions for individual elements in the simulation.
setmethod | Sets integration method for elements to use in simulation.
showstat | Reports statistics about current simulation (time, step,
| stepsize, or memory use; or element resource use).
step | Advances the simulation by one or more steps.
stop | Completes current simulation step, stopping simulation.

The step routine might be considered the central GENESIS routine -- it runs the simulation, which is in a large part the whole point of GENESIS. In relation to the step routine, everything else you do in a GENESIS simulation script is a preparation for running the simulation.

A typical sequence of events in running a simulation is as follows:

1. Set up the simulation environment (elements, messages, clocks, etc.) Often, you will use the readcell to construct one or more cells from specifications contained in cell parameter files.
2. Run the reset routine to establish the initial state for the run:

                genesis > reset

3. Run the check routine to check for obvious specification errors:

                genesis > check

   If there are any errors, return to step 1 to revise the environment as appropriate based on the check output.
4. Run the step routine with a small step number (e.g., step 10) to test whether the simulation will run reasonably:

                genesis > step 10

   If the simulation fails or shows odd results, figure out where the problem is and return to step 1. Often, this will involve some experimentation with the step size used for the global simulation clock, as described in Simulation Clocks.
5. Run the reset routine to prepare for the full run:

                genesis > reset

6. Having determined that your simulation clocks are using an appropriate step size, run the step routine for a longer period of time. If you are not using graphics or interactive input, you may wish to place your simulation job in the background. For example:

                genesis > step -time 10.0 -background

   (The GENESIS prompt returns immediately but the simulation will have started in the background, as you can confirm using the showjobs routine.)

You may wish to practice these steps using the simple GENESIS programming example scripts in the Scripts/tutorials directory before you try to build and run your own model.

### Explicit vs. Implicit Integration Methods

The documentation for setmethod describes the various numerical integration methods that may be used when GENESIS performs a simulation. The default Exponential Euler method is a good compromise between speed, accuracy and ease of use for network models and single cell models involving a small number of compartments. Multi-compartmental models result in numerically ``stiff'' equations that are best solved with one of the implicit (Backward Euler or Crank-Nicholson) methods. The implicit methods are much faster, and allow the use of larger step sizes. But, they must be used in conjunction with the hsolve object, which takes over the computations of compartments, symcompartments, tabchannels and other selected element types. (See the documentation for hsolve and the section on Simulation Clocks.)

The following routines are designed to be used with hsolve elements:

Routine | Description
findsolvefield | Used with hsolve for input/output of values
getsolvechildname | Finds hsolve child element names
getsolvecompname | Used with hsolve to find compartment names

### Running a Simulation in the Background

To perform a GENESIS simulation in the background (for example if you want to login from home over a modem, start a simulation, and logout while the simulation continues to run), your simulation script should use no graphics, and write all output to files.

Besides specifying the -nox option when starting genesis to avoid starting XODUS, you also need to use the -notty and -batch options. GENESIS will attempt to read from stdin after the .simrc and command line script are completed. The -batch option causes genesis to exit rather than try to read stdin. -notty will avoid doing any terminal setup and cleanup procedures which can also cause this type of behaviour. You must specify both on the command line (i.e. neither option implies the other). In addition, you need to redirect output (both stdout and stderr) to a file. For example, a simple script ``batchtest.g'' might look like:

    //genesis script for a simple compartment simulation (Tutorial #1)
    //batchtest.g

    create neutral /cell
    create compartment /cell/soma
    setfield /cell/soma Rm 10 Cm 2 Em 25 inject 5

    // send output to a file
        create asc_file /out
        setfield /out    flush 1    leave_open 1
        setclock 1 1.0
        useclock /out 1
        addmsg       /cell/soma     /out       SAVE Vm

    setclock 0 0.001 // this is to make it run slowly
    reset
    step 100 -time
    exit

To run this script in the background (using the C shell), you would use:

        genesis -nox -batch -notty batchtest >& batch.log &

With the Bourne shell (or bash) it would be:

        genesis -nox -batch -notty batchtest > batch.log 2>&1 &

When performing long simulation runs in the background, you can use a disk_out, diskio, or asc_file element to save simulation results to disk at regular intervals. To save the state of the model at the end of the run, use the save or simdump command.

## 15.2 Simulation Clocks

Each element in a simulation is associated with an interval timer or ``clock''. This clock is used to determine how frequently the action associated with the element (i.e., the INIT or PROCESS listed in the simulation schedule) will be executed during the simulation process. This is particularly useful when you want components of a simulation to run at significantly different time scales.

By convention, clock number 0 is the global simulation clock or the basic simulation time step. All elements start out using clock 0 by default.

The simulator also contains an array of 100 independent clocks (this is the number of available clocks; a typical simulation only uses a few of these clocks). Each clock is identified by a number from 1 to 100 corresponding to its position in the clock array. Clocks other than clock 0 must have settings larger than that of clock 0; these settings should be integer multiples of the clock 0 setting for maximal timing precision.

The setting of a specific clock is not some ``current time'', but is the time increment used for stepping its associated elements through the simulation. The units used for time must be consistent with those used for other related variables and parameters of the simulation. For example, if membrane resistances and capacitances are expressed in kilohms and microfarads, then times should be expressed in milliseconds. To make it easier to keep track of units, many (but not all) GENESIS simulations use SI (MKS) units, and express time in seconds.

For example, suppose clock 0 has the setting 1.0 (its default setting), and you assign clock 1 the value 5. If you then have a graphical element use clock 1 for its simulation time, the graph element would perform its simulation action (e.g., receiving a message and plotting a value) only once every 5 steps taken by the other elements. This can greatly speed up a simulation, as the time increment used for the display of information can usually be much larger than that which is small enough for an accurate stepwise numerical solution of the equations governing the model.

The following GENESIS routines are used for working with simulation clocks:

Routine | Description
getclock | Returns value of specified simulation clock.
setclock | Sets time interval (step size) associated with specified clock.
showclocks | Displays currently defined clocks and their assigned values.
useclock | Specifies which clock an element should use during simulation.

### Choosing a Simulation Time Step

At each step of a simulation, each participating element typically performs one or more computations. Some elements perform a stepwise numerical integration in order to solve the state equations of the element they represent. When setting up a simulation, you will need to choose a global simulation clock step size which is small enough to give accurate results, yet is large enough to give a reasonable simulation speed.

You can empirically determine the time step used with an integration method by decreasing the time step until the differences in simulation results are within some criterion. As a starting point, you should pick a step which would yield a smooth curve if you were to make a ``connect-the-dots'' type of plot of the most rapidly varying variable. The size of the time step needed also depends on the integration method which is used. The documentation for setmethod describes the several different ways these integrals can be calculated.

Typically, you need around 10 microseconds for a neural simulation with explicit methods (like the default Exponential Euler method) and 50 to 100 microseconds with the implicit methods (Backward Euler and Crank-Nicholson). (For the implicit methods the limiting factor is often the speed of the channel kinetics.) Implicit methods are recommended when there are many small compartments in a cell model, as these result in numerically ``stiff'' equations.

There is a complication when using the implicit methods. These are inherently not object oriented, and involve the construction of an ``hsolve'' element which takes over the computations for a specified cell. (See the documentation for hsolve.)

## 15.3 GENESIS Jobs

Certain compiled C functions available in GENESIS are designed to be run as background jobs (e.g., the function XEventLoop, which oversees XODUS screen events). You can execute and monitor these background functions using the following job routines:

Routine | Description
addjob | Adds a job to the GENESIS background job table.
deletejob | Removes a job from the GENESIS job table.
setpriority | Changes priority of a GENESIS background simulation job.
showjobs | Lists all of the active GENESIS jobs and their priorities.

Previous Next Table of Contents