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></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=

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





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>





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