Getting Started

1. Installation
2. Running Cell Programs
3. Viewing Results
4. Writing Cell Programs

Conventions: Anything in [] is optional, Anything in <> is obligatory, Anything within "" must be typed as is

Installation

Run the following commands (on a Linux system)

1. Change to the directory where you want Cell Simulator to be installed
2. Run the following commands
   gunzip -c cellsim-1.1a.tar.gz | tar xvf -
cd cellsim-1.1a/threads
gmake
cd cellsim-1.1a/cellsim
gmake
3. For Installing CellSimClient, just extract the file CellSimClient.zip in Windows 2000 or NT (You should have the OpenGL libraries and GLUT to be able to display 3-D output of the Cell Simulator)

Running Cell Programs

Cell Simulator can be run in batch mode or display mode. Batch mode is employed using the switch -batch
cellsim [-batch] [SIM-file]

Change to the cellsim directory. Some sample programs are available in the cellsim/cpa directory. You can run a sample program blastula.cpa using the following commands.
cellsim cpa/blastula.cpa cpa/kill.sim
OR
cellsim -batch cpa/blastula.cpa cpa/kill.sim

Viewing Results

1. Cell Simulator produces a file statedump.txt.
2. Copy this file into the directory containing CellSimClient.exe
3. Now run CellSimClient.exe
4. Pressing the key displays the results of the simulation
5. Press once to see the results before step X
6. Press once again to see results after step X and before step X+1

Writing Cell Programs

CPA File

The Cell Program Automaton file specifies the cell program in the form of an automaton. The automaton consists of a set of states. The CPA file contains the description of the cell states.

1. Each state is described by describing its color, emissions and transitions.
2. Omitting any of these 3 descriptions is allowed.
3. The color is described by specifying the R, G, B components. (The color is used only for display purposes).
4. The emissions are specified by listing a chemical-list
5. Each chemical-list specifies the name of a chemical and a concentration seperated (by a comma and placed within brackets). Each element in the list is seperated by a comma
6. The state transitions are listed as "condition" -> "transition"
7. A 'condition' may be listed as a 'AND' of simple conditions. A simple condition is of the form conc1 <= chemical <= conc2. Listing a condition is optional. If no condition is listed then the transition is always taken. The simulator finds the first matching condition from the list and executes it
8. Ordinary cell state transitions are listed as 'state' within brackets. Transitions include cell divisions. Cell division is shown as two comma-seperated 'states' within brackets

The format of a cell-state description is as follows

"state" <Cell-State-ID> "{"
  [ "color" <R> <G> <B> ]
  [ "emits" < "(" <chemical> "," <concentration> ")" >
            [ < "," "(" <chemical> "," <concentration> ")" > ]
  [ "transitions"
    [
      <
        "(" <value1> "<=" <chemical> "<=" <value2> ")" >
            [ "&" < "(" <value1> "<=" <chemical> "<=" <value2> ")" > ]
      >
    ]
    "->"
    <
      [ < "(" <state> ")" > |
        < "(" <state>, <state> ")"
              [ < "axis" > |
                < "normal-X" > |
                < "normal-Y" > |
              ]
        >
      ] ";"
    >			
  ]
}

A sample CPA file is listed below

state s1 {
        color 127 0 0
        emits (chemA, 0.1)
        transitions
                (0 <= chemA <= 0.3665) -> (s1, s1) axis;
                -> (s1);
}

This CPA file has only one state s1. It will show as Dark Red in the CellSimClient Display Window. It emits 'chemA' with a concentration of 0.1. If it senses a concentration of 'chemA' between 0 and 0,3665, it divides axially into 2 cells with states s1 and s1. [Also read another example in the cpa directory: blastula.cpa]

SIM File

The sim file contains instructions for the simulator. SIM files can be used to test the working of your program in hostile conditions. Cell death in a region, introduction of hostile cells etc can be done The SIM File is organised as a set of instructions one per line. The format of each line of the SIM file is as follows

The <instruction> is executed at the specified <cycle-number> Each succeding line must have a <cycle-number> more than or equal to that on the previous line. Prefixing a line by # causes that line to be ignored

There are four kinds of instructions

1. new

   This instruction creates a new cell with specified parameters. It takes 7 parameters.

   1. Cell State (0 onwards)
   2. X-coordinate (-1.0 to 1.0)
   3. Y-coordinate (-1.0 to 1.0)
   4. Z-coordinate (-1.0 to 1.0)
   5. Radius (0.0 to 1.0)
   6. Axis angle (in radians)
   7. Normal angle (in radians)
2. kill

   This instruction kills all cells located within a specified region. A cell is within a region if the cell's center is within the region. Currently only circular regions are supported. It takes 4 parameters.

   1. X-coordinate (-1.0 to 1.0)
   2. Y-coordinate (-1.0 to 1.0)
   3. Z-coordinate (-1.0 to 1.0)
   4. Radius (0.0 to 1.0)

3. random

   This instruction creates a specified number of cells with specified random parameters. It takes 15 parameters

   1. Number of cells
   2. Staring Cell State (0 onwards)
   3. Ending Cell State (0 onwards)
   4. Minimum X-coordinate (-1.0 to 1.0)
   5. Maximum X-coordinate (-1.0 to 1.0)
   6. Minimum Y-coordinate (-1.0 to 1.0)
   7. Maximum Y-coordinate (-1.0 to 1.0)
   8. Minimum Z-coordinate (-1.0 to 1.0)
   9. Maximum Z-coordinate (-1.0 to 1.0)
   10. Minimum radius (0.0 to 1.0)
   11. Maximum Radius (0.0 to 1.0)
   12. Axis start angle (in radians)
   13. Axis end angle (in radians)
   14. Normal start angle (in radians)
   15. Normal end angle (in radians)

4. stop

   This instruction ends the simulation. It takes no parameters.

EXAMPLE SIM FILE

0: new 1 0.0 0.0 0.0 1.0 0.0 0.0  
0: new 2 0.1 0.0 0.0 1.0 0.0 0.0  
0: random 10 1 3 -0.5 0.5 -0.5 0.5 0.0 0.0 0.02 0.06 0.0 6.283 0.0 6.283
5: kill 0.0 0.0 0.0 0.5
#8: kill 0.0 0.0 0.0 0.8
#8: kill 0.0 0.0 0.0 0.9
10: stop

University of Virginia Department of Computer Science Programming the Swarm

Sponsored by the National Science Foundation

David Evans evans@cs.virginia.edu Selvin George selvin@cs.virginia.edu