E-CELL2 USER'S MANUAL (version 1.1 beta)

Rule Files are data files in which users specify the information required to run a simulation in E-CELL2. In this file, all substances (including enzymes), interactions (reactions) between substances, and environmental parameters such as the volume of the system are defined. Furthermore, Rule Files can also describe specifications of the integration system used for calculation.

Users can also create Reactor Files (see Chapter 3), which are programs that compute rates of particular reactions, and changes the quantity ,such as of a substance etc. according to the formula by specification of Rule Files.

2 Filling out spreadsheets

This chapter explains headers of, which divide parts and the four parts giving examples of Rule Files. The following characters are forbidden to use for describing the contents of E-CELL2 spread sheets:

2.1 Headers

In a spread sheet, it is necessary to give headers in each part. The rows containing Headers are called Header Lines, and are necessary to separate the different sections of the E-CELL2 spread sheet. The first line in every SECTION must, therefore, be a Header Line.

Figure 1 shows a typical E-CELL2 spread sheet with the Header Lines highlighted in blue.

Headers are case insensitive and can appear in any order within a single Header Line.

An optional Header, named Memo, can be added to the end of any Header Line. This is intended for miscellaneous comments, and will be ignored when the spread sheet is converted into an eri file.

2.2 The SYSTEM SECTION

The structure of the cell model and some environmental parameters for the simulation must be defined in the SYSTEM SECTION. The various compartments of the cell model are defined in the SYSTEM SECTION, together with information about the location of SYSTEMS and their volume.

The Headers used in the SYSTEM SECTION, their definitions and default values are shown in Table 1.

Header	Definition	Default Value

Type	`System`	Input required
Class	Location(`System`)	Input required
Path	`System` location in tree structure	Input required
ID	`System` ID	Input required
Name	`System` name	ID
Inside	Internal `System` (Used only in Membrane Class)	Input required for Membrane Class
Outside	External `System` (Used only in Membrane Class)	Input required for Membrane Class
VolumeIndex	FQEN of `Reactor` indicating Volume	Input required for `System`s with volume

Table 1 Headers in SYSTEM SECTION

To define a System in the SYSTEM SECTION, enter [System] in " Type " column. In the " Class " column, specify which class will be used for this System in the simulation. The four classes are Cell, Environment, Cytoplasm and Membrane. All of these classes can contain Substances and Reactors, and also have a volume parameter. However, the Environment and Membrane classes cannot contain any SubSystems. Table 2 outlines the features of the four classes.

Enter the location of the System in the " Path " column. The Path of an E-CELL2 System begins in RootSystem(/), and the subordinate Systems (Subsystems) can be defined by the user.

The complete Path must be specified, using " / " to separate directories (e.g. " /system1/system2/system3 " ). Paths are case sensitive.

FQEN, FQPN

The concept of FQEN (Fully Qualified Entry Name) is a method of indicating the location of Substances and Reactors in the tree structure of the System hierarchy. On the other hand, FQEN is a combination of the Path and ID connected by " : " (e.g. " /system0/system1/system2:ID " ). For example, if the Path is " /CELL/CYTOPLASM " and the ID is " ATP " , the FQEN would be " /CELL/CYTOPLASM:ATP " . With FQEN the differences between Systems, Substances and Reactors cannot be distinguished. Therefore this type of information is included in FQPN instead, expressed in the form of [Type] : [FQEN]. With FQPN, the above example would be written as " Substance:/CELL/CYTOPLASM:ATP " . Both FQEN and FQPN are case sensitive.

The ID attribute is a unique identifier for each System, and may not be used more than once in the same System. If the same ID is used more than once in a single System, a warning message will appear during the conversion of the txt file into the er file, and only the first of the entries will be processed. Unlike Headers, IDs are case sensitive.
Enter the ID of the System in the " ID " column, and the name of the System in the " Name " column.

When specifying the Membrane class type, the Inside and Outside columns are used to specify the Systems located on either side of the membrane. Although the current version of E-CELL2 does not utilize this information, development is underway to limit Substance access to relevant Systems only. In the above example (figure 5), the MEMBRANE System exists between the CYTOPLASM and ENVIRONMENT.

In E-CELL2, the System volume is given by a Reactor (see Chapter 5 for details). When defining Systems, therefore, the volume is not specified directly as an attribute of the system. The volume(L) of a System is expressed as the activity of a Reactor, and can be specified in the VolumeIndex column using its FQEN. The user must ensure that the Reactor specified here is defined in the REACTOR SECTION of the spreadsheet. There are some cases where specification of System volume is unnecessary. For example, volume need not be specified for the MEMBRANE System as above. However, it is necessary to define the VolumeIndex of a System if Reactor calculations require Substance concentrations, or if the amount of Substances are specified as concentration values (in the CONC column of the SUBSTANCE SECTION). This is because volume information is necessary to convert concentration values into molecular quantity values used internally by E-CELL2.

2.3 The SUBSTANCE SECTION

All Substances used in the simulation must be defined in the Rule Files. Information concerning each Substance is specified in the SUBSTANCE SECTION.

Header	Definition	Default Value

Type	[Substance]	Input required
Class	Usually, [Substance]. This can be blank.	Input required
Path	Location (`System`) of `Substance`	Input required
ID	`Substance` ID	Input required
Name	`Substance` name	ID
QTY	Initial quantity of `Substance`(incompatible with Conc)	0
CONC	Initial concentration of `Substance` in M (mol/l)(incompatible with QTY)	QTY
Arg_tag	In case accumulation method of decimal numbers to be specified[Accumulator]	This can be blank
Arg_coeff	Accumulation method of decimal numbers are chosen[Accumulator class]	Input required if Accumulator is specified in Arg_tag

Table 3 List of Headers in the SUBSTANCE SECTION

In the " Class " column, specify the Class used in each row. At present, only " Substance " can be specified as a Class in the SUBSTANCE SECTION. Therefore, type " Substance " in the " Class " column.The software will assign " Substance " as a Class by default if this column is left blank.

Enter the System location of Substance in the Path column. The Path is denoted using " / " characters as delimiters between parent and child systems (e.g. " /system1/system2/system3 " ),same as the Path column in the System Section.Note that in cases where two Substances with the same ID and Name exist in different Systems, E-CELL2 recognizes them as different Substances. This attribute is case sensitive.

Specify the Substance ID and Name in the " ID " and " Name " columns. These entries are case sensitive.

The " QTY " (Quantity) attribute defines the initial quantity of molecules. The QTY attribute cannot be used with the CONC attribute. If both values are defined, a warning message will appear and only the QTY value alone will be loaded into E-CELL2. If neither the QTY nor CONC values are specified, the QTY value will be set to zero. The " Fix " option can be used to make the value constant. Refer to the later section for the fix function.

Enter Concentration M (mol/l) of Substances in the " CONC " column. When converting er files to eri files, concentration values are converted to QTY values at runtime using the volume specified in the " init_act " column of REACTOR SECTION in system, and the Avogadro constant. The values of QTY and CONC are exclusive of each other (only one should be specified), and if Conc cell is left blank, Qty value would be printed in eri file. Similarly, note that when VolumeIndex is not specified even if Conc value is specified, it will be assumed as Volume=0. The value can be fixed using Fix function.

The Fix Function

The Fix function sets QTY or CONC values to be constant during simulation, as specified substance is not influenced by increase and decrease of Reactor. Enter the word " Fix " below the QTY or CONC value.

Accumulators

The Accumulator class encapsulates methods to accumulate substance quantities. When specifying Accumulators, enter the word " Accumulator " in Arg_tag column, and specify the Accumulator class name in the Arg_coeff column.

A list of available classes is shown below (Table.4). However, calculation accuracy has not been guaranteed when specifying the different accumulation method for every substance.

Type the Accumulator class which encapsulated the accumulation method of substance in Arg_coeff.

Classname

Function

ReserveAccumulator

Utilizes reserve accumulation methods where integers and decimals of a number are calculated separately. Only integers are expressed in the simulation while decimal numbers are reserved. When reserved decimal values become greater than or equal to 1.0, or less than 0.0, the integer value is incremented or decremented.
For example:

The amount of change	Integers	Decimal numbers
initial value	0	0
0.8	0	0.8
0.8	1	0.6
0.8	2	0.4

SimpleAccumulator

Calculates real numbers directly. Decimal numbers will be expressed as decimal numbers instead of integers. Precision is dependent on the CPU and compiler, with a maximum of 18 digits for an i386 CPU, and 15 digits for an alpha CPU.

RoundDownAccumulator

Numbers are rounded down to the integer. Numbers after the decimal point are ignored. (e.g. if the calculated result of a reactor 5.25, the value is expressed as 5).

RoundOffAccumulator

Numbers are rounded up or down to the nearest whole number. (e.g. if the calculated result of a reactor is 5.74, the value is expressed as 6).

MonteCarloAccumulator

Integers and decimal numbers are calculated separately. Decimal numbers calculated by reactors are converted to integers stochastically. (e.g. if the calculated result is 3.4, the integer is expressed the number 3 on probability 0.6, number 4 on probability 0.4.)

Table 4 List of Accumulator Classes

2.4 The REACTOR SECTION

The REACTOR SECTION defines reactions and other interactions involving the Substances defined in the SUBSTANCE SECTION, interaction between substances for example, as well as equations controlling dynamic environmental variables such as the System volumes. In this section, specific instances of Reactors are defined, by specifying the class of Reactor to be used, as well as information on its substrates, products, and stoichiometry.

Header	Definition	Default Value

Type	[Reactor]	Input required
Class	`Reactor` name	Input required
Path	Location (`System`)	Input required
ID	Reaction ID (Add " ! " before the ID when using PReactors)	Input required
Name	Reaction name	ID
init_act	Initial value of `Reactor` activity	Input required except special cases (VolumeIndex is defined.etc)
S_ID	Substrate ID	Input required
S_Path	Substrate location(System)	Path
S_Coeff	Stoichiometric coefficient of Substrate	1
P_ID	Product ID	Input required
P_Path	Product location(System)	Path
P_Coeff	Stoichiometric coefficient of Product	1
C_ID	Catalyst ID	Input required
C_Path	Catalyst location	Path
arg_tag	Name of constant (used in the reaction equation)	Input required if it is required for Reactor
arg_coeff	Value of constant	Input required if arg_tag is specified
E_ID	`Substance` which affect reaction (Effector)	Input required
E_Path	Effector location(System)	Path
E_Coeff	Coefficient of Effector (depends on Reactor)	1

Table 5 List of Headers in REACTOR SECTION

Specify the class of Reactor to be used in the " Class " column. In the above example, the MichaelisBiBiReactor, which is based on Michaelis-Menten kinetics has been specified. The bottom two lines of the example define the Reactors for System volume. Details for all other standard Reactor types can be found in in the spec sheets, distributed anywhere, maybe through our web site. The reaction ID is specified in the " ID " column. If the reaction uses Postern Reactors, add the character " ! " before the ID name. The Type, Class and ID attributes are case sensitive.

The location of the reaction is specified in the " Path " column. The definition of " Path " is the same as in the other sections. In the above example, the reaction occurs in " /CELL/CYTOPLASM " . Note that this attribute is case sensitive.

Specify the name of the reaction in the " Name " column. If this cell is left blank, the information in the ID cell will be used as the Name attribute when converting to eri.

It is desirable to give Name that is easy to identify whether it has volume for Reactor with volume. If the reaction uses a Postern Reactor, it is necessary to add the character " ! " before the ID name(refer Chapter 5). Note that it is not guaranteed when using " ! " in the beginning of conventional Reactor ID like FluxReactor system.

The " init_act " column is used when it is necessary before starting the simulation. This activity of a Reactor is calculated in each step of calculation. This value must be specified for Reactors which are specified as the VolumeIndex for a System in the SYSTEM SECTION. This int_act is specified as an initial value when the E-CELL2 system read an activity value for the Reactor. If this value is not defined, E-CELL2 will automatically assume a value of zero for volume, resulting in simulation error. The above example is a ConstantParameterReactor representing System volume, with the initial volume defined.

The attribute S_ID is the ID of the substrate(s), and S_Path is the Path specifying the location of the substrate(s). In the above example, " ATP " and " Glc " in the CYTOPLASM act as substrates in the defined reaction. The S_Coeff attribute is used to specify the stoichiometric coefficient for each substrate.

The P_ID attribute is the ID of a product, and P_Path is the Path specifying the location(System) of the product. In the example above, the products " ADP " and " G6P " are located in the CYTOPLASM. The P_Coeff attribute is used to specify the stoichiometric coefficient for each product.

The C_ID attribute is the ID of the catalyst, and C_Path is the Path specifying the location of the catalyst. The C_ID and C_Path attributes are usually identical to the ID and Path of the reaction itself.

The " arg_tag " column is used to declare the constants which are used by the Reactor (this value will be used in the equation of the Reactor). The types of constants that can be used limited by the specification of each Reactor class. Since the MichaelisBiBiReactor is used in this example, the arg_tag's, KcF, KmS are declared (refer to the spec sheet for information on standard Reactors and their arg_tag). When more than one arg_tag needs to be defined, use the row below the previous arg_tag for each additional arg_tag. There is no need to re-specify the other attributes of the Reactor for the additional rows (Figure 17). The " Arg_tag " attributes are case sensitive. If the ConstantParameterReactor (the Reactor used for volume calculations in the sample rule file) is to be used, the " Value " constant must be declared in this column(Figure 20).

Enter the value of each constant in the " arg_coeff " column next to the " arg_tag " column. The values for each constant declared in the " arg_tag " column are specified here. In this example of the MichaelisBiBiReactor, the values for KcF, KmS are entered in their respective rows.

When the ConstantParameterReactor is used, the System volume should be specified here as the value of the " Value " constant (Figure 18). E-CELL2 refers to " init_act " for the initial volume (used in the first step of simulation only). In subsequent steps of simulation, E-CELL2 refers to the output of the Reactor for the volume value.

Effectors are Substances, like Substrate or Product, which influence the rate of reaction, but are synthesized or degraded by the reaction. The E_ID and E_Path attributes specify the ID and location of the effector. The E_Coeff attribute is the effector coefficient to be used in computing the rate of reaction. The use of " E_Coeff " depends on each Reactor (refer to Chapter 5).

2.5 The INCLUDE SECTION

The INCLUDE SECTION allows specification of other er files, the contents of which should be merged with the contents of this file when generating the final eri file. This function is useful when there are definitions in other er files that can be reused. The INCLUDE SECTION is omitted in cases where all the information needed for the simulation is written in one spreadsheet. Specify the other file in the INCLUDE SECTION , and the information will be printed in the eri file. In the " Type " column, the word " Include " is entered. The " Filename " column specifies the filename of the er file to be included. In the example above, a file named " sample.er " will be merged with this file when generating the final eri file.

3 Saving and Converting spread sheets

3.1 Saving spread sheets

Spread sheets must be saved in text format with the field delimiter option set to tabs, which is the format recognized by the converting script, to convert into eri file. This is written in the only format to be read by the E-CELL2 System. When creating text with tabs, it is useful to use software like EXCEL. A few samples of text files with tabs are shown in the directory " standard\SAMPLE " with the extension " .txt " . By default this directory will be " C:\E-CELL2\standard\SAMPLE " , and on Cygwin, it will be recognized as " /cygdrive/c/E-CELL2/standard/SAMPLE " . The software that helps creating Rule Files is in the directory " tools\rule " , and " C:\E-CELL2\tools2rule " is the directory when the software was installed, which is identical to , " /cygdrive/c/E-CELL2/tools/rule " on Cygwin. The Perl, language must be available on Cygwin.

3.2 Conversion of er files

To simulate in the E-CELL2 System, spread sheets must be converted into eri files using ss2er.pl, which convert spreadsheets into er files, and er2eri.sh, which convert er files into eri files. A spreadsheet is saved as a text file with tabs, so that ss2er.pl can analyze the file. In this situation, it is assumed that the directory to save the file in is " C:\E-CELL2\tools\rule " ,by default. This directory is recognized as " /cygdrive/c/E-CELL2/tools/rule " on Cygwin. After your spread sheet was finished, use " cd " command to move to this directory, and type.

This will convert the spreadsheet file into an er file. Note that the extension must be " .er " . This step is unnecessary if an er file has been written manually. Then, an er file will be converted into an eri file, which is the last type of file that the E-CELL2 System read, using er2eri.sh

Note that the extension " .er " must be omitted when use this command. When executing this shell script, the corresponding Rule Intermediate file " .eri " will be created. In the GUI mode, chose [Load Rule] in [File] menu in the ControlPanel to open the file selection window to read a " .eri " file. Refer to Section 1 of Chapter 2 for E-CELL2 startup.