Software Manual

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).