Cytosim PI Cytoskeleton Simulator

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

List of commands

The configuration file should contain a succession of commands. Most command have the following syntax:

COMMAND CLASS NAME
{
PARAMETERS
}

Essential commands:

Command | Action
--- | ---
`set` | Create a new Property, and set parameter values
`change` | Change parameter values in an existing Property
`new` | Create one or many new objects
`delete` | Delete objects
`run` | Perform simulation steps
`read` | Read another config file
`write` | export formatted data with selected object properties
`import` | Import Objects from trajectory file
`export` | Export all Objects to file, with their coordinates

Other commands:

Command | Action
--- | ---
`mark` | Mark objects
`repeat` | Execute code a number of times
`stop` | Stop program
`cut` | Cut Fibers
`call` | Call a custom function

## Command set

Create a new Property (a set of parameters associated with a class).

set CLASS NAME
{
PARAMETER = VALUE
...
}

Short syntax:

set CLASS:PARAMETER NAME VALUE

CLASS should be one of the predefined object (see List of objects).
NAME can be any string, but it should start with a letter.
The command will define the given NAME for this class.

## Command change

Change the value of one (or more) parameters for property NAME of class CLASS.

change CLASS NAME
{
PARAMETER = VALUE
...
}

Short syntax:

change CLASS:PARAMETER NAME VALUE

The possible values of CLASS are in the List of objects.
The NAME should have been defined previously in the same class with `set`, but it is possible to use a star (*) to change all properties of the class.

## Command new

The command `new` creates one or more objects with given specifications:

new [MULTIPLICITY] CLASS NAME
{
position = POSITION
orientation = ROTATION
post_translation = VECTOR
post_rotation = ROTATION
mark = INTEGER
required = INTEGER
}

The possible values of CLASS are in the List of objects.
The NAME should have been defined previously in the same class with `set`.
The other parameters are:

Parameter | type | Description
--- | --- | ---
MULTIPLICITY | INTEGER | the number of objects, by default 1.
`orientation` | ROTATION | a rotation applied before translation
`position` | POSITION | a translation
`post_translation` | VECTOR | a translation applied every time after one object is created
`post_rotation` | ROTATION | a rotation applied every time after one object is created
`mark` | INTEGER | this mark is given to all objects created (default = 0).
`required` | INTEGER | cytosim will stop if it cannot create as many objects as specified (default=0)

Note that `position` only applies to movable objects, and `orientation` only applies to rotatable objects. In addition, `post_translation` and `post_rotation` are relevant only if `(MULTIPLICITY > 1)`, and do not apply to the first object.

Short syntax:

new [MULTIPLICITY] CLASS NAME ( POSITION )

Shorter syntax:

new [MULTIPLICITY] CLASS NAME

See also How to create objects

## Command delete

Delete objects:

delete [MULTIPLICITY] CLASS NAME
{
mark = INTEGER
position = POSITION
}

NAME can be '*', and the parameters mark and position are optional.

To delete all objects of the class:

delete CLASS *

To delete all objects of specified NAME:

delete CLASS NAME

To delete at most CNT objects of class NAME:

delete CNT CLASS NAME

To delete all objects with a specified mark:

delete CLASS *
{
mark = INTEGER
}

To delete all objects within a Space:

delete CLASS *
{
position = inside, SPACE
}

The SPACE must be the name of an existing Space. Only 'inside' and 'outside' are valid specifications.

## Command mark

Mark objects:

mark [MULTIPLICITY] CLASS NAME
{
mark = INTEGER
position = POSITION
}

NAME can be '*', and the parameter position is optional. The syntax is the same as for command `delete`.

## Command run

Perform simulation steps, and write frames to files. Currently, only 'run simul *' is supported.

run [NB_STEPS] simul *
{
nb_steps = INTEGER
solve = SOLVE_MODE
event = RATE, ( CODE )
nb_frames = INTEGER
prune = BOOL
}

The optional specification [NB_STEPS] enables the short syntax:

run NB_STEPS simul *

Option | Default | Action
--- | --- | ---
`nb_steps` | 1 | number of simulation steps
`solve` | 1 | Enable/disable motion of the objects
`event` | none | custom code executed stochastically with prescribed rate
`nb_frames` | 0 | number of states written to trajectory file
`prune` | true | Print only parameters that are different from default

If set, `event` defines an event occuring at a rate specified by the positive real `RATE`. The action is defined by CODE, a string enclosed with parenthesis containing cytosim commands. This code will be executed at stochastic times with the specified rate.

Example:

event = 10, ( new fiber actin { position=(rectangle 1 6); length=0.1; } )

Calling `run` will not output the initial state, but this can be done with `write`:

write state objects.cmo { append = 0 }
run 1000 simul *
{
nb_frames = 10
}

Todo:
  : add code executed at each time-step

## Command repeat

Repeat specified code.

repeat INTEGER { CODE }

## Command stop

Terminates execution

stop

## Command cut

Cut all fibers that intersect a given plane.

cut fiber NAME
{
plane = VECTOR, REAL
}

NAME can be '*' to cut all fibers. The plane is specified by a normal vector n (VECTOR) and a scalar (REAL). The plane is defined by n.x + a = 0

## Command call

Call custom function

call FUNCTION_NAME

FUNCTION_NAME should be custom?, where ? is a digit.

Todo:
  : propagate the arguments (do_set, do_new) to the custom commands

## Command include

Include another specified config file, and executes it.

include FILE_NAME
{
required = BOOL
}

By default, required = 1, and execution will terminate if the file is not found. If required is set to 0, the file will be read, but execution will continue even if the file is not found.

Todo:
  : able to specify do_set and do_new for command 'include'

## Command read

Import Objects from a frame of the specified trajectory file.

read [INTEGER] FILE_NAME

by default frame = 0, corresponding to the first frame in the file.

Note that the simulation time will be changed to match the one stored in the file, but it can be reset with:

change simul * { time=0 }

## Command write

Export to file. The general syntax is:

write WHAT FILE_NAME
{
append = BOOL
binary = BOOL
}

WHAT can be `state` or a valid argument to `report`:

If `*` is specified instead of a file name, the current trajectory file will be used if WHAT=`statee`, or the standard output for a report.

The binary option only applies if WHAT=`state`. By default:

- append = true
- binary = true

Short syntax:

write WHAT FILE_NAME

Examples:

write state objects1.cmo { append=0 }
write state objects1.txt { binary=0 }
write properties properties1.cmo { append=0 }
write fiber:length fibers.txt

Attention: For safety reason, this command is disabled for `play`.