3. Commands

This section describes how a ChemCell input script is formatted and what commands are used to define a ChemCell simulation.

3.1 ChemCell input script

ChemCell executes by reading commands from a input script (text file), one line at a time. When the input script ends, ChemCell exits. Each command causes ChemCell to take some action. It may set an internal variable, read in a file, or run a simulation. Most commands have default settings, which means you only need to use the command if you wish to change the default.

In many cases, the ordering of commands in an input script is not important. However the following rules apply:

(1) ChemCell does not read your entire input script and then perform a simulation with all the settings. Rather, the input script is read one line at a time and each command takes effect when it is read. Thus this sequence of commands:

stats	 10
run      100 
run      100 

does something different than this sequence:

run      100 
stats	 10
run      100 

In the first case, statistics are printed every 10 timesteps during two simulations of 100 timesteps each. In the 2nd case, the default statistics setting (0) is used for the 1st 100 step simulation and the setting of 10 is used for the 2nd one. Thus statistics during the 1st run will only be printed at the beginning and end of the run.

(2) Some commands are only valid when they follow other commands. For example you cannot setup a reaction until the particle species it specifies have been defined.

(3) Sometimes command B will use values that can be set by command A. This means command A must precede command B in the input script if it is to have the desired effect. For example, the particles command reads a group of particles and assigns them random numbers using a random number generator. If default values are not desired, the seed command must be used before particles to tell ChemCell how to initialize the random number generator.

Many input script errors are detected by ChemCell and an ERROR or WARNING message is printed. This section gives more information on what errors mean. The documentation for each command lists restrictions on how the command can be used.

3.2 Parsing rules

Each non-blank line in the input script is treated as a command. ChemCell commands are case sensitive. Command names are lower-case, as are specified command arguments. Upper case letters may be used in file names or user-chosen ID strings.

Here is how each line in the input script is parsed by ChemCell:

(1) If the line ends with a "&" character (with no trailing whitespace), the command is assumed to continue on the next line. The next line is concatenated to the previous line by removing the "&" character and newline. This allows long commands to be continued across two or more lines.

(2) All characters from the first "#" character onward are treated as comment and discarded.

(3) The line is searched repeatedly for $ characters. If the character following the $ is "a" to "z", the two-characters sequence (e.g. $x) is replaced with the corresponding variable text. See the variable command for details.

(4) The line is broken into "words" separated by whitespace (tabs, spaces). Note that words can thus contain letters, digits, underscores, or punctuation characters.

(5) The first word is the command name. All successive words in the line are arguments.

(6) Text with spaces can be enclosed in double quotes so it will be treated as a single argument. See the print command for an example. A '#' or '$' charater in text between double quotes will also not be treated as a comment or substituted for as a variable.

3.3 Input script structure

This section describes the structure of a typical ChemCell input script. The "examples" directory in the ChemCell distribution contains many sample input scripts; the corresponding problems are discussed in this section, and animated on the ChemCell WWW Site.

A ChemCell input script typically has several stages:

1. Initialization
2. Define bins
3. Define geometry
4. Define particles
5. Define reactions
6. Settings
7. Run a simulation

The last 2 stages can be repeated as many times as desired. I.e. run a simulation, change some settings, run some more, etc. The "Define bins" and "Define geometry" stages are not used for non-spatial simulations (ODE or Gillespie). Each of the stages is now described in more detail. Remember that almost all the commands need only be used if a non-default value is desired.

(1) Initialization

Set parameters that are typically defined before the simulation domain is binned.

The relevant commands are run_style, global, volume, boundary, seed, timestep, move_style.

(2) Define bins

For spatial simulations, the simulation domain is partitioned into 3d bins using the bin command. This must be done before geometric objects or particles are created or read-in.

(3) Define geometry

The triangles and region commands are used to create geometric objects and membrane boundaries.

(4) Define particles

Particles and their attributes are created and set via these commands:

species, dimension, diffusion, count, permeable, particles, read_restart

(5) Define reactions

Reactions (zero-order, unary, binary) are defined via the reaction, react_modify, and probability commands.

(6) Settings

Before a simulation is run, a variety of settings can be specified using these commands:

balance, dump, stats, fix, restart

(7) Run a simulation

A spatial or non-spatial simulation is run using the run command.

3.4 Commands listed by category

This section lists all ChemCell commands, grouped by category. The next section lists the same commands alphabetically.

Settings:

run_style, move_style, seed, sort, balance, timestep

Geometry:

boundary, global, region, triangles, volume

Particles:

species, count, diffusion, dimension, permeable, particles, read_restart

Reactions:

reaction, react_modify, unreact, probability

Fixes:

fix, unfix

Output:

dump, restart, stats, stats_modify, dump_modify, undump, write_restart, check, debug

Actions:

bin, move_test, run,

Miscellaneous:

clear, echo, include, jump, label">log, next, print, shell, variable

3.5 Individual commands

This section lists all ChemCell commands alphabetically. The previous section lists the same commands, grouped by category.

Fix styles. See the fix command for one-line descriptions of each style or click on the style itself for a full description: