E-Cell Simulation Environment Version 3.1.100 User's Manual (Draft: Dec. 18, 2003) | ||
---|---|---|
Prev | Chapter 3. Modeling with E-Cell | Next |
Usually an EM has one or more Stepper and one or more System statements. These statements are top-level elements of the file. General structure of an EM file may look like this:
STEPPER_0 STEPPER_1 ... STEPPER_n SYSTEM_0 # the root system ( '/' ) SYSTEM_1 ... SYSTEM_mSTEPPER_? is a Stepper statement and SYSTEM_? is a System statement.
The model must have a System with a SystemPath '/'. This System is called the root system of the model.
System System( / ) { # ... }
The class of the root system is always
System
, no matter what
class you specify. This is because the simulator creates the
root sytem when it starts up, before loading the model
file. That is, the statement does not actually create the
root system object when loading the EML file, but just set
its property values. Consequently the class name specified
in the EML is ignored. The model file must always have
this root system statement, even if you have no property to
set.
If the model has more than one System objects, it must form a tree which starts from the root system (/). For example, the following is not a valid EM.
System System( / ) { } System System( /CELL0/MITOCHONDRION0 ) { }This is invalid because these two System objects, / and /CELL0/MITOCHONDRION0 are not connected to each other, nor form a single tree. Adding another System, /CELL0, makes it valid.
System System( / ) { } System System( /CELL0 ) { } System System( /CELL0/MITOCHONDRION0 ) { }Of course a System can have arbitrary number of sub-systems.
System System( / ) { } System System( /CELL1 ) {} System System( /CELL2 ) {} System System( /CELL3 ) {} # ...
![]() | Planned support for model composition |
---|---|
In future versions, the system will support composing a model from multiple model files (EMs or EMLs). This is not the same as the EM's file inclusion by empy preprocessor. |
If you want to define the size of a System, create a Variable with an ID 'SIZE'. If the System models a three-dimensional compartment, the SIZE here means the volume of that compartment. The unit of the volume is [L] (liter). In the next example, size of the root system is 1e-18.
System System( / ) { Variable Variable( SIZE ) # the size (volume) of this compartment { Value 1e-18; } }
If a System has no 'SIZE' Variable, then it shares the SIZE Variable with its supersystem. The root system always has its SIZE Variable. If it is not given by the model file, then the simulator automatically creates it with the default value 1.0. The following example has four System objects, and two of them (/ and /COMPARTMENT) have their own SIZE variables. Remaining two (/SUBSYSTEM and its subsystem /SUBSYSTEM/SUBSUBSYSTEM) share the SIZE Variable with the root system.
System System( / ) # SIZE == 1.0 (default) { # no SIZE } System System( /COMPARTMENT ) # SIZE == 2.0e-15 { Variable Variable( SIZE ) { Value 2.0e-15 } } System System( /SUBSYSTEM ) # SIZE == SIZE of the root sytem { # no SIZE } System System( /SUBSYSTEM/SUBSUBSYSTEM ) # SIZE == SIZE of the root system { # no SIZE }
![]() | SIZE must be a positive real number |
---|---|
Behavior of the system when zero or negative number is set to SIZE is undefined. |
![]() | Unit of the size |
---|---|
Currently, the unit of the SIZE is (10 cm)^d, where d is dimension of the System. If d is 3, it is (10 cm)^3 == liter. This specification is still under discussion, and is subject to change in future versions. |
A System statement has zero, one or more Variable and Process statements in addition to its properties.
System System( / ) { # ... properties of this System itself comes here.. Variable Variable( V0 ) {} Variable Variable( V1 ) {} # ... Variable Variable( Vn ) {} Process SomeProcess( P0 ) {} Process SomeProcess( P1 ) {} # ... Process OtherProcess( Pm ) {} }Do not put a System statement inside System.
Any Process and Variable object in the model must be connected with a Stepper by setting its StepperID property. If the StepperID of a Process is omitted, it defaults to that of its supersystm (the System the Process belongs to). StepperID of System cannot be omitted.
In the following example, the root sytem is connected to the Stepper STEPPER0, and the Process P0 and P1 belong to Steppers STEPPER0 and STEPPER1, respectively.
Stepper SomeClassOfStepper( STEPPER0 ) {} Stepper AnotherClassOfStepper( STEPPER1 ) {} System System( / ) # connected to STEPPER0 { StepperID STEPPER0; Process AProcess( P0 ) # connected to STEPPER0 { # No StepperID specified. } Process AProcess( P1 ) # connected to STEPPER1 { StepperID STEPPER1; } }
Connections between Steppers and Variables are automatically determined by the system, and cannot be specified manually. See the next section.
A Process object changes values of Variable object(s) according to a certain procedure, such as the law of mass action. What Variable objects the Process works on cannot be determined when it is programmed, but it must be specified by the modeler when the Process takes part in the simulation. VariableReferenceList property of the Process relates some Variable objects with the Process.
VariableReferenceList is a list of VariableReferences. A VariableReference, in turn, is usually a list of the following four elements:
[ reference_name FullID coefficient accessor_flag ]The last two fields can be omitted:
[ reference_name FullID coefficient ]or,
[ reference_name FullID ]These elements have the following meanings.
Reference name
This field gives a local name inside the Process to this VariableReference. Some Process classes use this name to identify particular instances of VariableReference.
Currently, this reference name must be set for all VariableReferences, even if the Process does not use the name at all.
Lexical rule for this field is the same as the Entity ID; leading alphabet or '_' with trailing alphabet, '_', and numeric characters.
FullID
This FullID specifies the Variable that this VariableReference points to.
The SystemPath of this FullID can be relative. Also, EntityType can be omitted. That is, writing like this is allowed:
:.:S0instead of
Variable:/CELL:S0, if the Process exists in the System /CELL.
Coefficient (optional)
This coefficient is an integer value that defines weight of the connection between the Process and the Variable that this VariableReference points to.
If this value is a non-zero integer, then this VariableReference is said to be a mutator VariableReference, and the Process can change the value of the Variable. If the value is zero, this VariableReference is not a mutator, and the Process should not change the value of the Variable.
If the Process represents a chemical reaction, this value is usually interpreted by the Process as a stoichiometric constant. For example, if the coefficient is -1, the value of the Variable is decreased by 1 in a single occurence of the forward reaction.
If omitted, this field defaults to zero.
isAccessor flag (optional)
This is a binary flag; set either 1 (true) or 0 (false). If this isAccessor flag is false, it indicates that the behavior of Process is not affected by the Variable that this VariableReference points to. That is, the Process never reads the value of the Variable. The Process may or may not change the Variable regardless of the value of this field.
Some Process objects automatically sets this information, if it knows it never changes the value of the Variable of this VariableReference. Care should be taken when you set this flag manually, because many Process classes do not check this flag when actually read the value of the Variable.
The default is 1 (true). This field is often omitted.
![]() | How isAccessor flag is used in the simulation |
---|---|
In multi-stepper simulations, this information sometimes helps the system to run efficiently. If the system knows, for example, all Process objects in the Stepper A do not change any Variable connected to the other Stepper B, it can give B more chance to have larger stepsizes, rather than always checking whether Stepper A changed some of the Variable objects. This flag is mainly used when there are more than one Steppers. |
Consider a reaction Process in the root system, R, consumes the Variable S and produces the Variable P, taking E as the enzyme. This class of Process requires to give the enzyme as a VariableReference of name ENZYME. All the Variable objects are in the root system. In EM, VariableReferenceList of this Process may appear like this:
System System( / ) { # ... Variable Variable( S ) {} Variable Variable( P ) {} Variable Variable( E ) {} Process SomeReactionProcess( R ) { # ... VariableReferenceList [ S0 :.:S -1 ] [ P0 :.:P 1 ] [ ENZYME :.:E 0 ]; } }