E-CELL2 User's Manual
Chapter 3 Basic Operation
[Chapter 1:Chapter 2:Chapter 4:Chapter 5:Chapter 6][Top]

INDEX

1 Introduction
2 Basic Operation
2.1 Starting the E-CELL2 System
2.2 Loading Rule Files
2.3 Loading Script Files
2.4 Executing Simulations
2.5 Changing Step Sizes
2.6 Displaying Simulation Results
2.6.1 Using Tracers
2.6.2 Using SubstanceWindows
2.6.3 Using ReactorWindows
2.7 Saving Simulation Results
2.8 Shutting down the E-CELL2 System
2.9 E-CELL2 Batch Mode and Loggers
3 Interfaces
3.1 ControlPanel
3.2 FileSelector
3.3 Tracer
3.4 EntrySelector
3.5 SubstanceWindow
3.6 ReactorWindow
3.7 PreferenceWindow
4 E-CELL2 Script Files
4.1 What are Script Files?
4.2 Script File Syntax
4.3 Sample Script File
4.4 Explanation of Sample Script File
4.5 List of Script File Commands

1 Introduction

In this chapter, the basic operation of the E-CELL2 System will be explained. It will be assumed that users have already mastered the overall operating procedures for E-CELL2, which have been explained in "Chapter 2 Tutorial". Please refer to Chapter 2 if necessary. Two modes, a GUI mode and a batch mode, exist in E-CELL2. In this chapter, most of the explanations will be on the former mode(GUI mode). In "Section 2 Basic Operation", the startup and shutdown of the E-CELL2 System in GUI mode will be explained briefly first. Operations in batch mode will be explained in "Section 2.9 E-CELL2 Batch Mode and Loggers". Loggers, newly implemented for the E-CELL2 System, are mechanisms that continuously save simulation results in real-time. Details of the operation procedures will be explained in "Section 3 Interfaces". Script files, which improve the operation of E-CELL2, will be explained in detail in "Section 4 E-CELL2 Script Files".

The E-CELL2 System requires data files called rule files for running simulations. Rule files will be explained in Chapter 4. Also, to create new models, new Reactors need to be constructed. Reactors will be explained in detail in Chapter 5. After reading through these chapters, one should be able conduct basic modeling using the E-CELL2 System. Please note that the guaranteed accuracy of calculation for GUI mode and batch mode is different; it is 64 bits and 80 bits respectively.

2 Basic Operation

2.1 Starting the E-CELL2 System

To start the E-CELL2 System, please click on the "Standard" shortcut in the desktop, or select [Start]-[Program]-[E-CELL2]-[standard]. E-CELL2 for the standard reactor model will start.

After the E-CELL2 System starts, the E-CELL2 ControlPanel will first displayed first.

If a script file called "default.ecs" is located under the E-CELL2 startup directory (The model directories under C\:E-CELL2, in a standard install), the file will automatically be loaded. However, please note that if the "LoadRule" command does not exist in the script file, while the "NewInterface" command or the "Run" command does exist, an error will occur and the file will be non-executable. The details regarding script files are explained in Section 4 of this chapter.

It is also possible to load settings with the file by adding options when directly starting ECELL2.BAT from the command line. The options are shown below.

-a classname Designates the default Accumulator class (Refer to Chapter 4).
-c If this option is designated, and if a cell state file is loaded when the simulation elapsed time is 0, the simulation elapsed time recorded in the cell state file will be set to the present simulation progress time. In all other cases, the simulation progress time will not change even if a cell state file is loaded. For details regarding cell state files, please refer to Section 2.7 in this chapter.
-dStarts in debug mode.
-f filename.ecsLoads the designated scriptfile.
-hDisplays a list of options.
-t directory_nameDesignates the target directory for writing the temporary files.
-u integer_valueDesignates the number of times Postern Reactors are called at the time of initialization. For details, please refer to the explanation of Postern Reactors in Chapter 5.

2.2 Loading Rule Files

Rule(eri) files, which are data files describing information that is necessary for the E-CELL2 System to run simulations, must be loaded prior to executing simulation. To load Rule(eri) files, please select [Load Rule] from the [File] menu in the ControlPanel, and then select the appropriate Rule(eri)file from the newly displayed FileSelector window.

Please note that if Rule files are loaded more than 2 times, E-CELL2 will display an error message.

2.3 Loading Script Files

If a file called "default.ecs" is located under the E-CELL2 startup directory, the file will automatically be loaded at the time of startup. Please note that if an error occurs during the loading process, there is a possibility that E-CELL2 will abnormally shut down.

Script(ecs)files are files for controlling and automating simulation and interfaces. Script(ecs)files need not be loaded. To load a Script file, please select [Load Script] from the [File] menu in the ControlPanel, and then select the appropriate Script(ecs)file from the newly displayed FileSelector window.

Please refer to the startup option "-c".

2.4 Executing Simulations

If the "Start" button in the ControlPanel is clicked after loading a rule file, the time progress within the simulation system will be displayed in the time counter. To stop simulation, please press the "Stop" button. Also, if the "Step" button next to the "Stop" button is clicked, a single time step-worth of simulation will be executed.

2.5 Changing Step Sizes

A step refers to a single cycle that first calculates the rates of reactions, and then updates the quantities of the affected Substances. At default, the size of an integration time step is 1/1000 seconds. To change the size of this time step, please select [PreferenceWindow] from the [Windows] menu in the ControlPanel, and then input a numerical value in the text box that will be displayed. This can also be designated using ecs files.

If the step size is increased, the time necessary for simulation will be shorter, but will result in an increase in error. On the other hand, if the step size is decreased, the time necessary for simulation will be longer, but will result in a decrease in error.

2.6 Displaying Simulation Results

In the default settings, user interfaces are updated once every 100 integration calculations. This interval can be changed in the ecs file.

2.6.1 Using Tracers

Tracers display the simulation results as a 2-dimensional graph. In the vertical axis, the changes in the quantity/concentration of Substances, or the changes in the activity of Reactors are displayed. In the horizontal axis on the other hand, the time is displayed. To display a new TracerWindow, please select [Tracer] from the [NewInterface] in the ControlPanel. To display a new Substance or Reactor in the Tracer, please click on the "Add" button at the bottom. An EntrySelector will then be displayed. Please select the appropriate Substance or Reactor.

Please note that what Substances describe does not necessarily refer to "molecules" of strict chemical terminology. It may be voluntary particles such as ions and radicals. However, in this manual we will use the term "molecule" for convenience.

The selected Substances and Reactors will be displayed with the colored square checkboxes in the Traces display area. If simulation starts in this state, the state of the Substance or Reactor will be represented by a graph of the same color as the square next to the checkbox.

2.6.2 Using SubstanceWindows

To display or change the quantities of substances, SubstanceWindows are used. To display a SubstanceWindow, please select [SubstanceWindow] from the [NewInterface] menu in the ControlPanel. An EntrySelector will then be displayed. Please select the appropriate Substance. If the "OK" button is clicked, a SubstanceWindow will be displayed.

In the SubstanceWindow, the ID and the substance name are displayed from the top. Below this, the number of molecules is displayed on the left, and the concentration on the right. If simulation is in a stopped state, these two values can be directly changed. After clicking on the displayed values to be changed and inputting new numbers, please press the return key to actually change the values. The number of molecules can be changed also by using the up and down buttons on the bottom.

2.6.3 Using ReactorWindows

To observe the rates of reactions, and the substrates and products that are involved, ReactorWindows are used. To display a ReactorWindow, please select [ReactorWindow] from the [NewInterface] menu in the ControlPanel. An EntrySelector will then be displayed. Please select the appropriate Reactor. If the "OK" button is clicked, a ReactorWindow will be displayed.

In the ReactorWindow, the Reactor class, entry name, and the name of the reaction will be displayed from the top. Below these, the activity per second will be displayed.

This is in a simple display mode. To observe the substrates and products involved in the reaction, please click the "ShowList" button on the top left. A new display area will then be added to the bottom. Starting from the left, the list of substrates, products, enzymes, and effectors will be displayed.

2.7 Saving Simulation Results

To save the simulation results displayed in Tracers, please click the "Save" button on the bottom left corner of the TracerWindow. A directory called "Data" will be created under the directory that the E-CELL2 System has been executed. In addition, subdirectories will be created according to the structure of the System. Also, data files in ecd format will be created for each Substance or Reactor. A data file in ecd format is usually composed of a header, more than 5 "-"(dashes) lined up that represent the end of the header, the data body, and "///"(3 slashes) that represent the end of the file. What has been improved compared to E-CELL1 is that the time, instantaneous quantity, average quantity, maximum quantity, minimum quantity, instantaneous concentration, average concentration, maximum concentration, and minimum concentration can now be outputted in E-CELL2.

Header of an ecd file
key wordvalue
DATAname of data
SIZEnumber of columns and rows
LABELlegend of each column
NOTEoptional comments

Example of an ecd file for E-CELL2

DATA: /CELL/CYTOPLASM:E.ab-0:Quantity
DATA: /CELL/CYTOPLASM:P:Quantity
SIZE: 5 102
LABEL: time current-quantity mean-quantity max-quantity min-quantity
NOTE:

----------------------
0       0       0       0       0
0.100000000000000064    624     314.66  624     6
0.20000000000000016     1247    938.65  1247    630
0.300000000000000192    1871    1562.5  1871    1254
0.40000000000000032     2495    2186.19 2495    1877
0.50000000000000032     3118    2809.73999999999968     3118    2501
0.600000000000000384    3742    3433.15 3742    3125
0.700000000000000512    4365    4056.4  4365    3748
0.80000000000000064     4988    4679.5  4988    4371
0.90000000000000064     5611    5302.47999999999936     5611    4994
1.00000000000000064     6234    5925.27 6234    5617
1.0999999999999896      6856    6547.95 6856    6240
1.19999999999997856     7479    7170.48 7479    6862
1.29999999999996768     8101    7792.86 8101    7485
(Omission)
///

To suspend simulation and save the states of the substances for the whole model, please select [Save Cell State] from the [File] menu in the ControlPanel. Please save the file with an appropriate name, with the ".cs" extension. The states of the models saved here can be loaded by selecting [Load Cell State] from the same [File] menu. Simulations can thus be resumed from the states that have been saved.

2.8 Shutting Down the E-CELL2 System

If [Quit] is selected from the [File] menu in the ControlPanel, a confirmation dialog will be displayed. If the "OK" button is clicked, the E-CELL2 System will shut down.

2.9 E-CELL2 Batch Mode and Loggers

E-CELL2 provides a batch mode that is executable from command lines. Please start the command prompt(MS-DOS prompt), and then move to the directory that E-CELL2 has been install to. In a standard install, "C:\E-CELL2\standard" is the location of the startup batch of E-CELL2 for the standard reactor model. The E-CELL2 startup batches for each model are located in "C:\E-CELL\model name".

If "ECELL2BB.BAT -h" is typed, a list of the options will be displayed. The options are the same as in GUI mode(Please refer to Section 2.1). ECELL2BB.BAT is the batch file for MS-DOS, and describes the PATH of the directory that the dynamically linked Reactor libraries(DLL) are housed in. In PATH, the designation of a DLL-housing folder(e.g. DLLRB) for batch mode is necessary. To execute simulation in batch mode, it is necessary to include the "-f" option when loading the script file(ecs). If simply typed "ECELL2BB.BAT", it will load "default.ecs". For details on script files, please refer to Section 4 in this chapter.

ECELL2BB.BAT -f filename.ecs

The following are the contents of ECELL2BB.BAT.

SET PATHSAV=%PATH%
PATH=../BIN/WIN-BCC;DLLRB;%PATH%
ecell2b.exe -r DLLRB %1 %2 %3 %4 %5 %6 %7 %8 %9
PATH=%PATHSAV%

If the "Logger" mechanism implemented from E-CELL2 is used, it is possible to record the cell state continuously during simulation. This function was implemented for use in batch mode. For details on its usage, please refer to "Section 4.5 List of Script File Commands".

3 Interfaces

3.1 ControlPanel

The ControlPanel, which is the main interface for the E-CELL2 System, is used for operation of tasks such as reading and writing files, operating on other interfaces, and executing and stopping simulation.

If a rule file is loaded, the name of the loaded rule file will be displayed after the "Rule:" under the menu. If a script file is loaded, "Script:" and the script file name will be displayed following the rule file.

./image/basic/ControlPanel.jpg
Figure 1. ControlPanel


Pull-down menu list
FileLoad RuleLoads a rule file.
Load ScriptLoads a script file.
Load Cell StateLoads a Cell State.
Save Cell StateSaves the Cell State.
QuitShuts down the E-CELL2 System.
NewInterfaceTracerDisplays a TracerWindow.
Substance WindowDisplays a SubstanceWindow.
Reactor WindowDisplays a ReactorWindow.
WindowsMessage WindowDisplays a MessageWindow.
Preference WindowDisplays a PreferenceWindow.


Start Button
Executes simulation.

Stop Button
Stops simulation.

Step Button
Executes a step of simulation.

Time Counter
Displays the elapsed time inside the simulation system, in seconds.

3.2 FileSelector

FileSelector windows are displayed for selecting files when reading or writing files. Files can usually be selected by first clicking the directory name until the file display area becomes the appropriate directory, and then by clicking the appropriate file and the "OK" button on the bottom. To write in a new file, please click on the file name display area, then directly input the file name and click on the "OK" button.

./image/basic/FileSelecter.jpg
Figure 2. FileSelector
File Display Area
Displays a list of the files and directories that are currently selectable. By clicking on the displayed file name, the file name in the file display area on the bottom becomes that of the clicked one. By clicking on the "OK" button, the file can be selected. Files can also be selected by double-clicking the file names. If a displayed directory name is clicked, the directory displayed in the file display area on the top becomes that of the clicked one.

File Name Display Area
Displays the file name currently selected. By clicking on the displayed area, the file name can be directly inputted. If the return key or the "OK" button is clicked after input, The file will be selected.

File Type List
Displays the regular expression for restricting the files that are displayed in the file display area, using filters. In the default settings, only the files with the appropriate extensions such as *.ecs. will be displayed. To change filters, please click on the file type list and select a different file type.

OK Button
If clicked, the file currently displayed in the file name display area will be selected.

Cancel Button
If clicked, file selection will be canceled and the window will close.

3.3 Tracer

Tracers display the quantity of Substances or the activity of Reactors, using 2-dimensional graphs. Up to 8 series of data can be displayed in a single Tracer window.

image/basic/Tracer.jpg
Figure 3. Tracer
Tracer
A list of the Substances and Reactors displayed in the Tracer will be displayed. The color of the radio button on the left of the name, corresponds to the color of the graph on the bottom. Switching between the display/non display of the graphs is possible by left-clicking the button. By right-clicking the button, a SubstanceWindow will be displayed if it is a Substance, and a ReactorWindow if it is a Reactor. In a single Tracer, up to 8 Substances or Reactors can be displayed.

Graph Display Area
Simulation results will be displayed as graphs. The vertical axis represents the number of molecules(or concentration), whereas the horizontal axis represents time. If left-clicked in the graph area, a gray cross with its vertex at the point that was clicked will be displayed. If there are multiple TracerWindows being displayed, the gray crosses will be displayed in the same coordinates for all of them. Please note that there are a few points to be careful about regarding synchronous cross cursors. For example, if the scales of 2 windows differ by a lot, even if a cross is displayed in one of the Tracers, the coordinates of the cross may be near 0 in the other Tracer and therefore may not be displayed. In this case, the coordinates on the bottom of the window will also not be displayed. However, if the area is enlarged, the cross will appear. Also, if the Tracer in the enlarged state is clicked, crosses will appear in the corresponding points. To clear the gray cross, please click anywhere outside the graph display area. Also, regions can be enlarged by dragging and creating rectangles with the right mouse button. To cancel the enlarged state and return to the default state, please double-click on the right mouse button.
image/basic/TracerExpand.jpg
Figure 4. Tracer(Expanded display)


Coordinates Display Area
The coordinates of the gray cross that is displayed when the graph is left-clicked will be displayed on the left. On the other hand, the coordinates of the mouse cursor will be displayed on the right.

Close Button
Closes the TracerWindow.

Add Button
Displays a new EntrySelector, and then displays the newly selected Substance or Reactor in the Tracer.

Save Button
Saves the time-series data that is displayed in the Tracer, into a file. The saved data is composed of 5 columns; "time", "instantaneous quantity", "average quantity", "maximum quantity", and "minimum quantity".

3.4 EntrySelector

EntrySelectors are used when selecting Substances or Reactors. Please click on the folder icon in the System selection dialog on the left. If the appropriate System has been displayed, please select the appropriate items from the Substance and Reactor selection dialog, and then click on the "OK" button on the bottom. By using the switch button on the top right, what is selected by the Tracers(Substance or Reactor), can be selected beforehand.


./image/basic/EnterySelecter.jpg
Figure 5. EntrySelector
Switch Button
Used for switching between Substance and Reactor when called by Tracers.

System Selection Dialog
The System in a hierarchal structure is displayed. To display the lower levels, please click on the folder icon.

Substance, Reactor Selection Dialog
Substances or Reactors will be displayed. If dragged, multiple selections are possible. Also, if clicked while the Ctrl key is pressed, separately located items can be selected.

OK Button
Finalizes the selection.

Cancel Button
Cancels the selection, and closes the window.

3.5 SubstanceWindow

image/basic/SubstanceWindow.jpg
Figure 6. SubstanceWindow
FIX Button
If this button is checked, the quantity will not change during simulation.

Quantity Display Area
Displays the quantity(number of molecules) of the Substance. When simulation is in a stopped state, its numerical value can be changed by clicking this area.

Concentration Display Area
Displays the concentration of the Substance. When simulation is in a stopped state, its numerical value can be changed by clicking this area.

3.6 ReactorWindow

Normal Display Mode

image/basic/ReactorWindow.jpg
Figure 7. ReactorWindow(Normal Display)

Detailed Display Mode Switch Button
Switches display to detailed display.

Detailed Display Mode

image/basic/ReactorWindowDetail.jpg
Figure 8. ReactorWindow(Detailed Display)

Normal Display Mode Switch Button
Switches display to normal display.

Reactant Display Area
Displays a list of the parameters on the right, and a list of the substrates, products, catalysts, and effectors on the bottom(from the left).

3.7 PreferenceWindow

image/basic/PreferenceWindow.jpg
Figure 9. PreferenceWindow
Step Interval
Changes the interval of a computation step.

Window Update Interval
Changes the interval of Tracer updating.

4 E-CELL2 Script Files

4.1 What are Script Files?

Script files are files for batch-processing the startup and shutdown of the E-CELL2 System, the control of simulation such as the recording of its results, and the control of its interfaces that display results.

Script files are text files, and can therefore be created using normal text editors.

4.2 Script File Syntax

Script files are loaded one line at a time, from the top. In script files, one command is described per line, except for the NewInterface command. The insertion of a new line in a single command is not allowed. To declare a command inside a NewInterface such as AddTrace, please describe it directly under the NewInterface command that it belongs to, inserting a space or a tab at the beginning of each line.

The text between the "#" symbol until the end of the line are comments that will be ignored.

4.3 Sample Script File

A sample script file is shown below.

TmpDir C:\E-CELL2\temp
LoadRule sample.eri

NewInterface Tracer trace1
  AddTrace Substance:/CELL/CYTOPLASM:A
  AddTrace Reactor:/CELL/CYTOPLASM:R1
  SaveAt 45

NewInterface SubstanceWindow test-sw
  Substance /CELL/CYTOPLASM:A

Run 500
Stop

There have been a few changes made from the E-CELL1 System. What indicates the path of the Reactors, is included in the startup batch file ECELL2.BAT or ECELL2BB.BAT. It has been made to describe the PATH when loading. Therefore, the "ReactorPath" command cannot be used.

TmpDir is a directory for saving temporary files. If the command does not exist, the "temp" directory under E-CELL2's installation directory is used. If the directory designated for TmpDir does not exist, the E-CELL2 System will terminate when executing simulation.

4.4 Explanation of Sample Script File

The first line designates the target location for writing the temporary files, whereas the second line designates the rule file to be loaded.

Lines 4 to 7 display a TracerWindow called Trace1, and are carry out a few settings. Line 5 designates the addition of a Substance called A to the Tracer, whereas line 6 designates the addition of a Reactor called R1. Line 7 designates the saving of the state of the Tracer after 45 seconds.

Lines 9 and 10 open a SubstanceWindow.

Line 12 designates the execution of simulation for 500 seconds, whereas line 13 designates the termination of the simulation.

4.5 List of Script File Commands

CommandContents
Accumulator class name Designates the default Accumulator class. For details, please refer to Chapter 4 Section 2.4.. Has to be described before LoadRule.
TmpDir directory Writes the temporary file generated during simulation, to the path designated in the argument. ../temp is designated at default. Has to be described before LoadRule.
LoadRule filenameLoads the rule file designated in the argument.
StepInterval secondDesignates the integration time interval in seconds. The default value is 0.001. Has to be described after LoadRule and before Run.
UpdateInterval countDesignates the user interface update interval in natural numbers. The default value is 100. The user interface is therefore updated once every 100 integration steps. Has to be described after LoadRule and before Run.
SaveCellState file_nameSaves the simulation state in the designated file. Has to be described after Run.
LoadCellState file_nameLoads the simulation state that is saved in the designated file. Has to be describe after Run.
Run secondsExecutes simulation for the duration(time within the simulation system) designated in the argument.
StopStops simulation. Has no arguments.
ExitShuts down E-CELL2. Has no arguments.
NewInterface interface, name A command for creating new interfaces. Requires 2 arguments; the type of the interface, and the name of the interface.
Commands Declared within NewInterface
CommandContents
Geometry (X1)x(Y1)+/-(X2)+/-(Y2) Designates the size and the display coordinates of the interface. However, because it only takes one argument, it is described like the following.
(X1)x(Y1)+/-(X2)+/-(Y2)
However, (X1) and (Y1) denote the width and height respectively. Also, (X2) and (Y2) denote the x coordinate and y coordinate for the top left corner of the window. If it is +, the top left becomes the base. If it is -, the bottom right becomes the base.
The difference between E-CELL1 is that if the location of the window is designated in the above rule, but does not fit in the Windows screen, the location of the screen will automatically be fixed so that it does fit in the Windows screen.

Commands for Each Interface


E-CELL2 User's Manual
Last Update $Date: 2003/3/18 $.
Copyright: Keio University and Mitsui Knowledge Industry Co., Ltd. 2000-2003
Chapter 3 Basic Operation
[Chapter 1:Chapter 2:Chapter 4:Chapter 5:Chapter 6][Top]