E-Cell Simulation Environment Version 3.1.100 User's Manual (Draft: Dec. 18, 2003) | ||
---|---|---|
Prev | Chapter 3. Modeling with E-Cell | Next |
Now you know the E-Cell's simulation model consists of what types of objects, and the objects have their properties. The next thing to understand is how the simulation model is organized: the structure of the model. But wait, learn the syntax of the E-Cell model (EM) file before proceeding to the next section would help you very much to understand the details of the structure of the model, because most of the example codes are in EM.
In E-Cell Simulation Environment, the standard file format of model description and exchange is XML-based EML (E-Cell Model description Language). Although EML is an ideal means of integrating E-Cell with other software components such as GUI model editors and databases, it is very tedious for human users to write and edit by hand.
E-Cell Model (EM) is a file format with a programming language-like syntax and a powerful embedded empy preprocessor, which is designed to be productive and intuitive especially when handled by text editors and other text processing programs. Semantics of EM and EML files are almost completely equivalent to each other, and going between these two formats is meant to be possible with no loss of information (some exceptions are comments and directions to the preprocessor in EM). The file suffix of EM files is ".em".
Although E-Cell Modeling Environment (which is under development) will provide means of more sophisticated, scalable and intelligent model construction on the basis of EML, learning syntax and semantics of EM may help you get the idea of how object model inside E-Cell is organized and how it is driven to conduct simulations. Furthermore, owing to the nature of the plain programming language-like syntax, EM can be used as a simple and intuitive tool to communicate with other E-Cell users. In fact, this manual uses EM to illustrate how the model is constructed in E-Cell
EM files can be viewed as EML generator scripts.
Before getting into the details of EM syntax, let's have a look at a tiny example. It's very simple, but you do not need to understand everything for the moment.
Example 3-1. A tiny EM example
Stepper ODE45Stepper( ODE_1 ) { # no property 5 } System System( / ) { StepperID ODE_1; 10 Variable Variable( SIZE ) { Value 1e-18; } 15 Variable Variable( S ) { Value 10000; } 20 Variable Variable( P ) { Value 0; } 25 Process MassActionFluxProcess( E ) { Name "A mass action from S to P." k 1.0; 30 VariableReferenceList [ S0 :.:S -1 ] [ P0 :.:P 1 ]; } 35 }
This example is a model of a mass-action differential
equation. In this example, the model has a Stepper
ODE_1 of class
ODE45Stepper
, which is a generic ordinary
differential equation solver. The model also has the root
system (/). The root sytem has the
StepperID property, and four Entity
objects, Variables SIZE,
S and P, and the Process
E. SIZE is a special name
of the Variable, that determines the size of the compartment.
If the compartment is three-dimensional, it means the volume of
the compartment in [L] (liter). That value is used to calculate
concentrations of other Variables. These Entity objects
have their property values of several different types. For
example, StepperID of the root system is the
string without quotes (ODE_1). The initial
value given to Value property of the
Variable S is an integer number
10000 (and this is automatically converted to
a real number 10000.0 when the Variable
gets it because the type of the Value
property is Real). Name property of the
Process E is the quoted string "A
mass action from S to P", and 'k'
of it is the real number 1.0.
VariableReferenceList property of
E is the list of two lists, which contain
strings (such as S0), and numbers (such as
-1). The list contain relative FullIDs
(such as :.:S) without quotes.
Basically an EM is (and thus an EML is) a list of just one type of directives: object instantiation. As we have seen, E-Cell's simulation models have only two types of 'objects'; Stepper and Entity. After creating an object, property values of the object must be set. Therefore the object instantiation has two steps: (1) creating the object and (2) setting properties.
The following is the general form of definition (instantiation) of an object in EM:
TYPE CLASSNAME( ID )
"""INFO (optional)"""
{
PROPERTY_NAME_1 PROPERTY_VALUE_1;
PROPERTY_NAME_2 PROPERTY_VALUE_2;
...
PROPERTY_NAME_n PROPERTY_VALUE_n;
}
where:
TYPE
The type of the object, which is one of the followings:
Stepper
Variable
Process
System
ID
This is a StepperID if the object type is Stepper. If it is System, put a SystemPath here. Fill in an Entity ID if it is a Variable or a Process.
CLASSNAME
The classname of this object. This class must be
a subclass of the baseclass defined by TYPE. For
example, if the TYPE is Process,
CLASSNAME must be a subclass of Process, such
as MassActionFluxProcess
.
INFO
An annotation for this object. This field is optional, and is not used in the simulation. A quoted single-line ("string") or a multi-line string ("""multi-line string""") can be put here.
PROPERTY
An object definition has zero or more properties.
The property starts with an unquoted property name string, followed by a property value, and ends with a semi-colon (;). For example, if the property name is Concentration and the value is 10.0, it may look like:
Real, Integer, String, and List are allowed as property value types (See the Object Properties section above).
If the value is a List, outermost brackets are omitted. For example, to put a list
[ 10 "string" [ LIST ] ]into a property slot Foo, write a line in the object definition like this:
![]() | Why the outermost brackets can be ommited? |
---|---|
All property values are lists, even if it is a scalar Real number. Remember a number '1.0' is interconvertible with a length-1 list '[ 1.0 ]'. Therefore the system can correctly interpret property values without the brackets. In other words, if the property value is bracketed, for example, the following property value Foo [ 10 [ LIST ] ];is interpreted by the system as a length-1 List [ [ 10 [ LIST ] ] ]of which the first item is a list [ 10 [ LIST ] ]This may or may not be what you intend to have. |
Before converting to EML, ecell3-em2eml command invokes the empy program to preprocess the given EM file.
By using empy, you can embed any Python expressions and statements after '@' in an EM file. Put a Python expression inside '@( python expression )', and the macro will be replated with an evaluation of the expression. If the expression is very simple, '()' can be ommited. Use '@{ pytyon statements }' to embed Python statements. For example, the following code:
@(AA='10') @AAis expanded to:
10Of course the statement can be multi-line. This code
@{ def f( str ): return str + ' is true.' } @f( 'Video Games Boost Visual Skills' )is expanded to
Video Games Boost Visual Skills is true.
empy can also be used to include other files. The following line is replaced with the content of the file foo.em immediately before the EM file is converted to an EML:
@include( 'foo.em' )
Use -E
option of
ecell3-em2eml command to see what happens
in the preprocessing. With this option, it outputs the result of the
preprocessing to standard output and stops without creating an
EML file.
It has many more nice features. See the appendix A for the full description of the empy program.
The comment character is a sharp '#'. If a line contains a '#' outside a quoted-string, anything after the character is considered a comment, and not processed by the ecell3-em2eml command.
This is processed differently from the empy comments (@#). This comment character is processed by the empy as a usual character, and does not have an effect on the preprocessor. That is, the part of the line after '#' is not ignored by empy preprocessor. To comment out an empy macro, the empy comment (@#) must be used.