Team:Czech Republic/Software/Manual

Software Manual

Contents


The CeCe simulator is modular simulator primary designed for modeling signal transmission networks in microfluidics. The simulator architecture is mainly modular where functionality is provided by plugins. Each plugin is responsible for specific part of simulation (may not be used).

Applications

CLI

Simple command line application that can run prepared simulations. It takes simulation file and perform simulation with optional visualization.

Parameters:
Name Parameters Description Notes
simulation-file filepath Path to simulation file.
--plugins Prints a list of available plugins.
--help Prints help.
--visualize If simulation should be visualized.
--novisualize Don’t visualize simulation.
--fullscreen Start visualization window in fullscreen. You don’t have to specify window width and height. In that case monitor size is used.
--width int Visualization window width.
--height int Visualization window height.
--capture filepath Record video from simulation. Visualization is required. May not be available in some builds. Check --help if is supported.

Specifying --visualize or --novisualize override settings from simulation (some simulation don’t explicitly want visualize).

Keys

When CLI application is running with visualization some keys can be used.

Key Description
Q Exits application.
P Pause simulation.
S Perform one simulation step when simulation is paused.

How to run

CLI application is supported on all three platforms.

Windows x64

On Windows the ZIP package contains executable in the main directory and some subdirectories with examples and plugins. Application must be executed from command line (cmd or PowerShell).

PS > .\cece-cli.exe examples\showcase.xml

Mac OS X

Application on Mac is shipped as bundle packed in TZG package. Package contains a few directories where the most important is bin where the application is stored. The directory bin/simulator-cli.app contains everything that CLI application needs to be executed. Run it from Finder is not viable (mostly for GUI apps that doesn’t require arguments) so it must be executed from terminal. The bundle have some predefined structure where the executable is stored but it’s not important because there is bin/cece-cli.sh that allows you to run CLI app without knowledge of bundle structure.

Just run the simulator by typing this in terminal in directory of unpacked TZG package.

$ ./bin/cece-cli.sh examples/showcase.xml

Linux x64

We offer only DEB package for Ubuntu-like distributions (Ubuntu 14.10 LTS, Mint 17.2). Just double click on DEB package and everything should be installed. Then just type following into terminal.

$ cece-cli /usr/share/cece/examples/showcase.xml

Data Types

In following text there are several data types that have different meaning. You can find their meaning in following table:

Name Description Example
int Integer value. 5, -3
uint Unsigned integer value. 5
float Floating point value. 5.3
string String value. hello world
expression Expression. Can contains parameters that are defined by parameter element. 10 * 5 + 3 * sin(alpha)
plugin-name Name of existing plugin. cell
name Similar to string. print
unit[?] SI unit based on specified symbol in square braces. Accepts value without unit symbol but if symbol is specified it must match the unit type (prefix are supported). Value without symbol have unspecified size, but mostly corresponds to basic unit specified by simulator (um, s, ng). 0, 30um/s, 1.3m/s2, 0.01/s, 5um/us
vector[?] Value of two values separated by space. In case the second value is not supplied it is same as the first one. 10um/s 1um/s, 0 0
color Color value. Value can be name of predefined color or in CSS color definition format (#RRGGBB). red, #0000FF
it Simulation iteration number. 10, 55
range[?] Range of values. Values can be separated by dash ‘-’. If dash is not present the meaning is: X-X. 10, 10-15
array[?] List of values of same type. 10 10 -5, a b c d e f g

Data Tables

Data tables are way how the simulator stores data within simulation. Anything can store data in named data table and when simulation ends those data tables are stored into CSV files in current working directory.

All data is stored in memory during simulation and are stored into file when simulation ends. This cause a large memory requirements depending on stored data.


Loaders

Loaders are responsible for loading different type of source files. They understand the source file and create simulation from them.

Reactions

This loader loads simple files that contains reaction rules and some parameters. Syntax of reaction rules is same as stochastic-reaction plugins.

@iterations 500
@dt 1s
null > 0.3 > A;
A > 0.1 > B + C;

Lines that begins with @ symbol are considered as directives that setups simulation. Remaining lines are parsed by reactions parser and used as program for cell.

Coresponding XML file looks like:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<simulation dt="1s" iterations="500">
    <program name="__local__" language="stochastic-reactions-intercellular">
<![CDATA[
        null > 0.3 > A;
        A > 0.1 > B + C;
]]>
    </program>
    <object class="cell.Yeast" programs="__local__" />
</simulation>

List of available directives:

Directive Parameters Description Example
iterations int Number of simulation iterations. @iterations 100
dt time Simulation iteration step. @dt 10s
molecule string, int Initial amount of specified molecule. @molecule A 500
parameter string, expression Set simulation parameter that can be used in reaction rules. @parameter kA 0.3

XML

Basic and most supported loader. It loads simulation from valid XML file. Some basic knowledge of XML files is required. The simplest simulation file looks like:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<simulation dt="1s">
</simulation>

<simulation dt="1s"> </simulation></source> This simulation does almost nothing just runs with iteration time step 1 second.

In the simulation element can be several other elements that specifies the simulation. Those elements can have sub-elements but that mostly depends on element type and used plugin.

Basic elements:

Simulator core defines following elements and their parameters.

Simulation

The XML file root element. It must be always present.

Name Type Default Description
world-size vector[unit[m]] - Simulation world size.
dt unit[s] - Simulation time step.
iterations uint 0 Number of simulation iterations. 0 means unlimited.
background color white Background color.
text-color color background inverse Color of UI text.
text-size uint 30 UI text size.
show-simulation-time bool false If simulation time should be rendered.

Init

This element defines program that is executed before the simulation is started. It’s good for simulation scene initialization in cases when manual specification is hard to write.

Name Type Default Description
language plugin-name - Language in element content.

Plugin

Explicitly loads required plugin. Plugin is implicitly loaded and when is needed but in some cases there is need for explicit load and configuration.

Name Type Default Description
name plugin-name - Plugin name.
Additional attributes are passed to plugin configuration.

Module

Adds module to simulation.

Name Type Default Description
name plugin-name(.module-name) - Name of required module. In most cases you can specify only plugin name but some plugins offsers more modules so you can specify which one you want by adding a suffix.
Additional attributes are passed to module configuration.

Program

Defines a program that is available for objects. Programs are not executed until are assigned to objects.

Name Type Default Description
name string - Unique program name.
language plugin-name - Language in which is the program written.

Object

Adds an object into simulation. Objects are physical entities that can be affected during simulation.

Name Type Default Description
class plugin-name.name - Unique program name.
visible bool true If object is rendered.
position vector[unit[m]] 0 0 Initial object position. 0 0 is in middle of the world.
velocity vector[unit[m/s]] 0 0 Initial object velocity.
density unit[g/m3] 1 Initial object density.
programs array[string] - A list of object programs.

Obstacle

Adds a physical obstacle into simulation. There are 3 different types of obstacles. Each of them require different attributes.

Name Type Default Description
visible bool true If object is rendered.
position vector[unit[m]] 0 0 Initial object position. 0 0 is in middle of the world.
type string - Type of obstacle. Possible values: circle, rectangle, polygon.
radius unit[m] - Circle radius. Required for circle type.
size vector[unit[m]] - Rectangle size. Required for rectangle type.
vertices array[vector[unit[m]]] - A list of vertices. Required for polygon type.

Plugins

List of available plugins supplied within official distribution. Depending on how the simulator is built, some plugins can be builtin and rest of them can be extern as shared libraries (dll / dynlib / so).

Some of them may not be available on your platform, so check the list by calling application with --plugins flag.

Agglutination

This plugin enables simulation object sticking. When two simulation object collides they might be bound together and after some time the bound can be removed. This is based on bond definition where you can specify required molecules in both collided cells to create a bond. Specifying association and dissociation constant you indirectly defines probability of bond creation and destruction.

Example:

Example defines bonds between cells.

<module name="agglutination">
  <bond ligand="LM1" receptor="LM3" association-constant="50" disassociation-constant="1" />
  <bond ligand="LM2" receptor="LM4" association-constant="20" disassociation-constant="10" />
  <bond ligand="LM5" receptor="LM6" association-constant="1"  disassociation-constant="0" />
</module>

Bonds

Parameters:
Name Type Default Description
ligand name - Name of the first molecule.
receptor name - Name of the second molecule.
association-constant float - Bond association constant.
disassociation-constant float - Bond dissociation constant.

Background

Plugin that renders defined image in each iteration.

Example:

<module name="background" image="background.png" />

Parameters:
Name Type Default Description
image path - Used background image.

Cell

Plugin offers things usefull to working with cells.

Objects

Objects offered by cell plugin:

Name Description
cell.Cell Common cell object.
cell.Yeast Yeast cell.

All object share common (unavailable) ancestor that have following properties:

Property Type Default Description Example
volume unit[m3] 100um3 Cell volume. 300um3
volume-max unit[m3] 100um3 Maximum cell volume. 300um3
growth-rate unit[m3/s] 0 Cell growth rate. 3um3/s
saturation-gfp unit[/m3] 20/um3 Number of “GFP” molecules required to have full green color. 100/um3
saturation-rfp unit[/m3] 20/um3 Number of “RFP” molecules required to have full red color. 100/um3
saturation-yfp unit[/m3] 20/um3 Number of “YFP” molecules required to have full yellow color. 100/um3
saturation-cfp unit[/m3] 20/um3 Number of “CFP” molecules required to have full cyan color. 100/um3
saturation-bfp unit[/m3] 20/um3 Number of “BFP” molecules required to have full blue color. 100/um3

Cell can have set initial amount of molecule at the beginning.

<object class="cell.Yeast">
  <molecule name="GFP" amount="500" />
</object>

Yeast

Property Type Default Description Example
volume-bud-create unit[m3] 42um3 Yeast volume when a bud is created. 300um3
volume-bud-release unit[m3] 35um3 Bud volume when is release. 300um3

Programs

store-molecules

Program that stores amount of all molecules in current iteration to molecules data table. It stores object identifier to distinguish between multiple cells.

<object class="cell.Yeast" programs="cell.store-molecules" />

Stored data:
  • iteration - Iteration number.
  • totalTime - Simulation time in seconds.
  • id - Object identifier.
  • ... - Column given by molecule name and value is amount of that molecule.

Cell Python

Adds access to cell plugin objects from Python.

Objects

Name Parent Description
cell.BaseCell simulator.Object Base cell object.
cell.Yeast cell.BaseCell Yeast cell.

Object cell.BaseCell

Base class for all cell objects.

Properties:
Name Type Description
volume float Cell volume
growthRate float Cell growth rate.
Methods:
Name Return Arguments Description
moleculeCount float string Return amount of required molecule stored in cell.
kill - - Kills the cell.

Object cell.Yeast

Nothing special.

Diffusion

The main module adds support for global diffusion in simulation. Diffusion can handle any number of separate signals. They cannot affect each other.

Example:

Enables diffusion with two signals named GFP and RFP with diffusion and degradation rates. Those signals have specified colors how they are rendered.

<module name="diffusion" grid="100">
  <signal name="GFP" diffusion-rate="30um2/s" degradation-rate="0.1/s" color="green" />
  <signal name="RFP" diffusion-rate="5um2/s" color="red" saturation="1uM" />
</module>

Parameters:
Name Type Default Description
grid vector[uint] - Diffusion grid size.
background color transparent Background color.

Signals

You can specify any number of different signals, there is no limitation. Each signal is specified separately.

Parameters:
Name Type Default Description
name string - Signal name.
diffusion-rate unit[m2/s] - Diffusion rate.
degradation-rate unit[/s] 0/s Degradation rate.
color color Predefined Signal color when the module is rendered.
saturation unit[mol/m3] 1umol/um3 Defines concentration when signal color is 100%.

Additional modules

store-state

Module that stores values from signal grid of all signals into diffusion data table.

Example:

Store diffusion data for all iterations.

<module name="diffusion.store-state" />

Stored data:
  • iteration - Iteration number.
  • totalTime - Simulation time in seconds.
  • x - Grid X coordinate.
  • y - Grid Y coordinate.
  • ... - Column given by molecule name and value is amount of that molecule in grid cell.

Diffusion Python

Python language binding for diffusion plugin.

Example:

This module generates in every iteration some diffusion signal inside defined circle.

<module name="python:generate"><![CDATA[
import math

def update(dt, simulation):
    diffusion = simulation.useModule("diffusion")
    size = diffusion.gridSize
    radius = size.x / 20
    signalAmount = 1
    signalId = diffusion.getSignalId("S1")

    for x in range(-radius, radius + 1):
        for y in range(-radius, radius + 1):
            if (math.sqrt(x * x + y * y) <= radius):
                diffusion.setSignal(signalId, size.x / 2 + x, size.y / 2 + y, signalAmount)
]]></module>

Class diffusion.Module

Diffusion module wrapping class.

Properties:
Name Type Description
gridSize vector[uint] Grid size.
signalCount uint Number of registered diffusion signals.
Methods:
Name Return Arguments Description
getSignalId int string Returns signal identifier from signal name.
getSignal float string, int, int Return signal value of given signal at given coordinates.
setSignal - string, int, int, float Change signal value of given signal at given coordinates.

Diffusion Streamlines

Without this plugin/module the streamlines does not affect diffusion. Just simply add:

<module name="diffusion-streamlines" />

It doesn’t require from diffusion and streamlines module to have same grid sizes.

Object generator

Module that generates specified object with some probability and parameters.

Example:

This example create module that generates different Yeast cells in each iteration with some probability.

<module name="object-generator">
  <object class="cell.Yeast" probability="0.004" programs="make-gfp" position-min="-80um -30um" position-max="-78um 30um" />
  <object class="cell.Yeast" probability="0.004" programs="make-rfp" position-min="-80um -30um" position-max="-78um 30um" />
  <object class="cell.Yeast" probability="0.004">
    <molecule name="GFP" amount="1000" />
  </object>
  <object class="cell.Yeast" probability="0.005" />
</module>

Objects

Object definition is same as for object in simulation just some additional parameters are required.

Parameters:
Name Type Default Description
probability unit[] - Probability of object spawning in iteration.
position-min vector[unit[m]] Left side of simulation scene. Minimum position where object can be spawned.
position-max vector[unit[m]] Left side of simulation scene. Maximum position where object can be spawned.
active array[range[it]] - List of ranges when is generator active.
Changing simulation time step affects spawning probability.

Obstacles image

Plugin generate obstacles from graycolored image by finding contours.

Example:

<plugin name="obstacles-image" image="obstacles.png" />

Parameters:
Name Type Default Description
image path - Path to source file. Path is relative to same directory as simulation file.

Picture

Module that can store scene picture into file.

Example:

Stores scene picture each 100 iterations into file with name pic_$1.png in directory pictures.

<module name="picture" pattern="pictures/pic_$1.png" iteration="100" />

Parameters:
Name Type Default Description
pattern string image_$1.png Path to output file. Pattern can have special $1 sequence that is replaced by iteration number.
iteration int 1 Number of iteration to skip before store picture (~ store each Nth iteration).
If pattern contains directory that directory must exist. ## Python

Python support for dynamic programming.

Python plugin doesn’t support unit data type and float type is used instead.

Programs

Dynamic program generated from Python source code. Called (function call) once in each iteration per object that uses this program.

# Optional initialization code

# Required function prototype.
# object: Object that owns this program.
# simulation: Current simulation.
# dt: Current iteration time step.
def call(object, simulation, dt):
    pass

Modules

Dynamic modules generated from Python source code. Module’s update function is called once in each iteration.

# Optional initialization code

# Optional function prototype
# @param simulator.Simulation    simulation Current simulation.
# @param simulator.Configuration config     Configuration from XML file.
def configure(simulation, config):
    pass
    
# Recommended function prototype
# @param simulator.Simulation simulation Current simulation.
# @param float                dt         Current iteration  time step.
def update(simulation, dt):
    pass
    
# Optional function prototype.
# @param render.Context       context    Rendering context.
# @param simulator.Simulation simulation Current simulation.
def draw(context, simulation):
    pass

Classes

There are some wrappers around simulator core classes.

class simulator.Configuration

Configuration class.

Methods:
Name Return Arguments Description
get string string Returns configuration value under given name.

class simulator.Simulation

Main simulation class that contains everything about simulation.

Properties:

Name Type Description
worldSize vector[float] Simulation scene/world size.
iteration uint Current iteration number.
iterations uint Total number of required iterations. Can be 0, if there is no limitation.
timeStep float Simulation time step.
totalTime float Total time spend in simulation in seconds.
objectsCount uint Number of objects in scene.
Methods:
Name Return Arguments Description
useModule simulator.Module string Returns required module. If module is not used, it is created by with default configuration.
buildObject simulator.Object string, bool Create a new object. The first argument is class name and second one is if object should be static (non-movable).

class simulator.Module

Base class for all modules. It doesn’t offer anything.

class simulator.Object

Basic simulation object.

Properties:

Name Type Description
id uint Grid size.
position vector[float] Number of different signals.
rotation float Object rotation in radians.
velocity vector[float] Object velocity.
Methods:
Name Return Arguments Description
useProgram - string Add program with given name to object.

Stochastic reactions - Intracellular

Allows to specify reactions rules that are stochastically being executed inside the cell.

The syntax is similar to one in NFSim.

This reaction changes molecule A to molecule B with rate 1. In other words, when this reaction occurs, one molecule A gets substracted and one molecule B gets added.

A > 1 > B;

This reaction changes one molecule A into molecules B and C.

A > 1 > B + C;

If you need reaction to happen only when some other molecule is present, take a look at following reaction. This reaction subtracts A and B, and adds C + B. Therefore, this reaction changes A to C only when B is present. Please note you can’t use this concept with environmental reactions.

A + B > 3 > C + B;

This reaction creates complex C from 2 molecules of A. That means that at least two As are required for this reaction to occur.

A + A > 2 > C;

This reaction uses keyword null and represents expression of A. No molecule gets substracted and one molecule of A gets added.

null > 2 > A;

Similarly, this reaction represents degradation of A.

A > 5 > null;

The two reactions above can be easily rewritten like this using reversible reaction syntax. First rate is rate of reaction going back, and second rate is for reaction going forward.

A < 5, 2 > null;
null < 2, 5 > A;

Another keywords which help user to make his reaction rules more understandable are if, and and or.

if not C and D and E:  A + B > 1 > C;

This reaction merges A and B into C, but this reaction can occur only when there is no molecule of C present and simultaneously there must be D and E present. You can combine as many logic combinations as you can. Please note that and is prior to or, this means that following reaction only occur when there is either A or B and C together present in the cell.

if A or B and C: D > 1 > E;

We want to make your reactions easily tunable, so we included the principle of threshold. The following reaction get executed only when there is 500 molecules of B present in the cell.

If B > 500: A > 1 > C;
Example:

Defines reactions that create molecules GFP and A with some degradation.

<parameter name="K1" value="20" />
<program name="make" language="stochastic-reactions-intracellular"><![CDATA[
  if A > K1: null > 1.505149978 > GFP;
  GFP > 0.001 > null;
  null < 0.5, 0.8 > A;
]]></program>

Stochastic reactions - Intercellular

Allows to specify reactions program that happens in surrounding environment. Plugin is an extension of intracellular reactions.

Extension’s functionality lies in keyword env which is abbreviation for environment, which handles absorbing the molecules inside the cell or producing them outside. Please note that env must be alone on its side of reaction rule.

Plugin requires properly set diffusion module with signals that have same name as molecules released into environment.

This plugin extends basic Intracellular reactions functionality with two types of reactions, expression and absorption.

Expression of molecule A is either represented using:

A > 1 > env;

or using:

null > 1 > env_A;

Please note that those two representations are not exactly the same although they lead to the same result. In first example there must be molecule A present in the cell, after executing the reaction the molecule gets substracted and added to the environment. Therefore this reaction represents transportation of molecule outside the cell. In second reaction, the molecule is added and released directly to the environment in single step.

Representation of absorption:

env > 1 > A;

This reaction follows the same concept. Subtracts molecule from environment and adds inside the cell. However, you may not want the molecules to get absorbed, you may only want to detect if those molecules are outside.

if env_A: B > 1 > C;

Extended conditional reactions are the key. Usage is completely the same as you know from standard intracellular reactions, just add the env_ prefix before molecule name. The threshold functionality is of course kept too.

<parameter name="T1" value="20uM" />

if env_A > T1: B > 1 > C;
Example:

This example is production of A molecules and releasing them with some rate into diffusion.

<program name="expression-of-A" language="stochastic-reactions-intercellular"><![CDATA[
  null > 50 > env_A;
]]></program>

Streamlines

Module that simulate streamlines in whole scene. It using Lattice Boltzman method to calculate velocities in simulation grid. Simulation can handle static and even dynamic obstacles. Dynamic obstacles are moving objects in scene. Dynamic obstacles (i.e. objects) are affected by computed velocities.

There are some limitations that come from Lattice Boltzman method. Maximum velocity is limited by grid size, time step and scene/world size. If the velocity is higher than this limit, it’s changed to the maximum otherwise the streamlines simulation crashes.

Example:

<module name="streamlines" grid="200" inlet-velocity="300um/s" kinematic-viscosity="0.658mm2/s" />

Parameters:
Name Type Default Description
grid vector[uint] - Simulation grid size.
layout 4x string barrier outlet barrier inlet Defines scene layout. Four values define layout in order: top right bottom left. Possible values are: none, barrier, inlet, outlet.
inlet-velocity unit[m/s] 0 Velocity for all inlets.
inlet-velocities 4x unit[m/s] 0 0 0 0 Specific inlet velocities for layout.
kinematic-viscosity unit[m2/s] 0.658mm/s Fluid kinematic viscosity.

Additional modules

store-state

Module that stores velicities from grid into streamlines data table.

Example:

<module name="streamlines.store-state" />

This module generates a huge amount of data so use with caution.
Stored data:
  • iteration - Iteration number.
  • totalTime - Simulation time in seconds.
  • x - Grid X coordinate.
  • y - Grid Y coordinate.
  • velX - Velocity in specified grid cell, X coordinate.
  • velY - Velocity in specified grid cell, Y coordinate.

Additional programs

store-object-state

Module that stores object position and velicities into object-state data table.

Example:

<object ... programs="streamlines.store-object-state" />

Stored data:
  • iteration - Iteration number.
  • totalTime - Simulation time in seconds.
  • id - Object identifier.
  • x - Object X world coordinate.
  • y - Object Y world coordinate.
  • velX - Object velocity, X coordinate.
  • velY - Object velocity, Y coordinate.

Streamlines Python

Python language binding for streamlines plugin.

Example:

This module generates in every iteration some diffusion signal inside defined circle.

<module name="python:generate"><![CDATA[
layouts = [
    ["barrier", "outlet", "barrier", "inlet"],
    ["barrier", "inlet", "barrier", "outlet"]
]

mode = 1

def update(dt, simulation):
    global mode
    module = simulation.useModule("streamlines")

    if (simulation.iteration % 200 == 0):
        module.setLayout(layouts[mode % 2])
        module.initBarriers(simulation)
        mode = mode + 1
]]></module>

Constants:

Name Type Description
LEFT uint Left side.
RIGHT uint Right side.
TOP uint Top side.
BOTTOM uint Bottom side.

Class streamlines.Module

Streamlines module wrapping class.

Methods:
Name Return Arguments Description
setLayout int string, string, string, string Set streamlines layout. Top, right, bottom, left. Possible values barrier, inlet, outlet, none.
initBarriers float - Initialize barriers after setLayout call.
setInletVelocity - int, float Change inlet velocity for specific scene side (see constants).