By reading this chapter, you can get information about:
How an E-Cell's simulation model is organized. |
How to create a simulation model. |
How to write a model file in EM format. |
E-Cell's simulation model is fully object-oriented. That is, the simulation model is actually a set of objects connected each other. The objects have properties, which determine characteristics of the objects (such as a reaction rate constant if the object represent a chemical reaction) and relationships between the objects.
A simulation model of E-Cell Simulation Environment consists of the following types of objects.
Usually more than one Entity objects
One or more Stepper object(s)
The Entity class has three subclasses:
Variable
This class of objects represent state variables. A Variable object holds a scalar real-number value. A set of values of all Variable objects in a simulation model defines the state of the model at a certain point in time.
Process
This class of objects represent phenomena in the simulation model that result in changes in the values of one or more Variable objects. The way of change of the Variable values can be either discrete or continuous.
System
This class of objects define overall structure of the model. A System object can contain sets of these three types of Entity, Variable, Process, and System objects. A System can contain other Systems, and can form a tree-like structure.
A model must have one or more Stepper object(s). Each Process and System object must be connected with a Stepper object in the same model. In other words, Stepper objects in the model have non-overlapping sets of Process and System objects.
Stepper is a class which implement a specific simulation algorithm. If the model has more than one Stepper objects, the system conducts a multi-stepper simulation. In addition to the lists of Process and System objects, a Stepper has a list of Variable objects that can be read or written by its Process objects. It also has a time step interval as a positive real-number. The system schedules Stepper objects according to the step intervals, and updates the current time.
When called by the system, a Stepper object integrates values of related Variable objects to the current time (if the model has a differential component), calls zero, one or more Process objects connected with the Stepper in an order determined by its implementation of the algorithm, and determines the next time step interval. See the following chapters for details of the simulation procedure.
E-Cell Simulation Environment uses several types of identifier strings to specify the objects, such as the Entity and Stepper objects, in a simulation model.
Every Entity and Stepper object has an ID. ID is a character string of arbitrary length starting from an alphabet or '_' with succeeding alphabet, '_', and numeric characters. E-Cell Simulation Environment treats IDs in a case-sensitive way.
If the ID is used to indicate a Stepper object, it is called a Stepper ID. The ID points to an Entity object is refered to as Entity ID, or just ID.
(need EBNF here)
The SystemPath identifies a System from the tree-like hierarchy of System objects in a simulation model. It has a form of Entity ID strings joined by a character '/' (slash). As a special case, the SystemPath of the root system is /. For instance, if there is a System A, and A has a subsystem B, a SystemPath /A/B specifies the System object B. It has three parts: (1) the root system (/), (2) the System A directly under the root system, and (3) the System B just under A.
A SystemPath can be relative. The relative SystemPath does not point at a System object unless the current System is given. A SystemPath is relative if (1) it does not start with the leading / (the root system), or (2) it contains '.' (the current system) or '..' (the super-system).
A FullID (FULLy qualified IDentifier) identifies a unique Entity object in a simulation model. A FullID comprises three parts, (1) a EntityType, (2) a SystemPath, and (3) an Entity ID, joined by a character ':' (colon).
EntityType:SystemPath:ID
The EntityType is one of the following class names:
System
Process
Variable
For example, the following FullID points to a Process object of which Entity ID is 'P', in the System 'CELL' immediately under the root system (/).
FullPN (FULLy qualified Property Name) specifies a unique property (see the next section) of an Entity object in the simulation model. It has a form of a FullID and the name of the property joined by a character ':' (colon).
FullID:property_nameor,
EntityType:SystemPath:ID:property_name
The following FullPN points to 'Value' property of the Variable object Variable:/CELL:S.
Entity and Stepper objects have properties. A property is an attribute of a certain object associated with a name. Its value can be get from and set to the object.
A value of a property has a type, which is one of the followings.
Real number
(ex. 3.33e+10, 1.0)
Integer number
(ex. 3, 100)
String
String has two forms: quoted and not quoted. A quoted String can contain any ASCII characters except the quotation characters (' or "). Quotations can be omitted if the string has a form of a valid object identifier (Entity ID, Stepper ID, SystemPath, FullID, or FullPN).
If the String is triple-quoted (by ''' or """), it can contain new-line characters. (The current version still has some problems processing this.)
(ex. _C10_A, Process:/A/B:P1, "It can include spaces if double-quoted.", 'single-quote is available too, if you want to use "double-quotes" inside.')
List
The list can contain Real, Integer, and String values. This list can also contain other lists, that is, the list can be nested. A list must be surrounded by brackets ([ and ]), and the elements must be separated by space characters. In some cases outermost brackets are omitted (such as in EM files, see below).
(ex. [ A 10 [ 1.0 "a string" 1e+10 ] ] )
The system automatically convert the type of the property value if it is different from what the object in the simulator (such as Process and Variable) expects to get. That is, the system does not necessary raise an error if the type of the given value differs from the type the backend object accepts. The system tries to convert the type of the value given in the model file to the requested type by the objects in the simulator. The conversion is done by the objects in the simulator, when it gets a property value. See also the following sections.
The conversion is done in the following manner.
How property value type adaptation is conducted
From a numeric value (Real or Integer)
To a String
The number is simply converted to a character string. For example, a number 12.3 is converted to a String '12.3'.
To a list
A numeric value can be converted to a length-1 list which has that number as the first item. For example, 12.3 is equivalent to '[ 12.3 ]'.
From a String
To a numeric value (Real or Integer)
The initial portion of the String is
converted to a numeric value. The number can be
represented either in a decimal form or a
hexadecimal form. Leading white space characters
are ignored. 'INF' and 'NAN' (case-insensitive) are
converted to an infinity and a NaN (not-a-number),
respectively. If the initial portion of the
String cannot be converted to a numeric value,
it is interpreted as a zero (0.0 or 0). This
conversion procedure is equivalent to C functions
strtol
and
strtod
, according to the
destined type.
To a list
A String can be converted to a length-1 list which has that String as the first item. For example, 'string' is equivalent to '[ 'string' ]'.
From a list
To a numeric or a String value
It simply takes the first item of the list. If necessary the taken value is further converted to the destined types.
![]() | Overflow and underflow when converting a property value |
---|---|
When converting from a Real number to an Integer, or from a String to a numeric value, overflow and underflow can occur during the conversion. In this case an exception (TYPE??) is raised when the backend object attempts the conversion. |