E-Cell3 Model Editor Manual

Introduction

Ecell3 ModelEditor is a graphical user interface utilizing python, gtk and gnome canvas for visualization, creation and modification of ecell3 model files (.eml). ModelEditor is available both on Linux ( target platform

Download and Install

ModelEditor source is part of the Ecell3 simulation environment code, once you install ecell3 you get ModelEditor installed, too. Source code can be found in the CVS repository of ecell project at http://sourceforge.net/projects/ecell . Binary RPM packages for Fedora Core 2 operating system, tarballs and source rpm packages are available from here.

To install ecell3 and ModelEditor, please follow instructions here: http://ecell.sourceforge.net/download.html.

In the target Fedora Core 2 operational system only one package is not up-to date: gnome-python2-canvas-2.0.2. This package is in the development tree for FC3. Until then linux users can build it from source, the tarball is located at:

ftp://ftp.gnome.org/pub/gnome/sources/gnome-python/2.0/gnome-python-2.0.3.tar.gz

Invocation

To start ModelEditor under Linux type:

ecell3-model-editor

optionally you can specify an eml file to be loaded upon startup by:

ecell3-model-editor -f filename

Operations on Main Window

Load model:

1. Using Main Window menu: click on File > Open Model or File > Open Recent

  1. Using Main Window buttons: click on the Open button



Save model:

1. Using Main Window menu: File > Save Model or File > Save Model As

  1. Using Main Window buttons: Click on the Save button



3. Save model with new filename: File menu> Save Model As

Undo/Redo:

  1. Using Main Window: click on the Undo button to undo an action or Redo button to redo an action.



2. Using PathwayEditor window: Right click on the Layout, a menu will be shown, click on Undo option to undo an action or Redo option to redo an action.

LayoutManager Window

On LayoutManager Window the user can create, delete, copy and show layouts.

Layouts are abstract objects that contain the coordinate positions of entities of a model. One entity can appear on multiple layouts. Layouts can visualized on PathwayEditor windows.

To pop up LayoutManager window, press on the big Layout button on MainWindow.

1. Creating Layout: Click the Create button on the Layout Manager Window.

2. Showing Layout: Select the layout from Layout Name list, click on the Show button.

3. Renaming Layout: Select a layout to be renamed, enter a new Layout name.

  1. Deleting Layout: Select a layout name to be deleted, click the Delete button.

Copying a layout: not yet implemented.

StepperWindow

On StepperWindow the user can create, delete, rename steppers, change the class of the stepper and modify stepper properties.

To invoke StepperWindow push on the Stepper button on MainWindow.


  1. Creating a stepper: In the Stepper Window click on the Add button to add a new stepper.

  2. Modify stepper properties: Click on the PropertyList tab on the right side of the window and the list of properties belonging to the stepper can be seen. The list contains property name, value, flags, property type. The value field can be edited if either the settable or saveable flags are set. If the property type is INTEGER, FLOAT or STRING the property values can be edited in the list where they appear. Properties of NESTED_LIST and MULTILINE type can be edited on specific dialog windows. The special property editor windows can be displayed by right clicking on the property and choosing “edit” from the upcoming menu.

    If the class of the stepper allows dynamic addition of properties the Add button is sensitive and the user can add new properties to the stepper.
    Delete flags are set for properties added by user action.

  3. Changing class of a stepper: Select a stepper from StepperList. Under the Summary tab, change the stepper class through the ClassName dropdownlist.

  1. Renaming a stepper:

  1. From StepperList: Click on the stepper to be renamed from the StepperList, enter a new name.

  2. From Summary tab: Click on the stepper to be renamed in the StepperList, enter a new name in the ID field.



PathwayEditor Window

On PathwayEditor window the user can create and modify 2D graphical representation of the model. Each PathwayEditor visualizes a layout consisting of systems, process, variables and connections between process and variables called variable references in ecell modeling language.

To invoke PathwayEditor with a brand new and empty layout push on the big Pathway button on Mainwindow.

To invoke PathwayEditor with an already created layout, press Show button on LayoutManager window.

Layouts contain only the entities of your choice but all layouts show the root system ('System::/') by default. Entities not shown on the layout can be displayed by right clicking on the canvas space and choose the “Show Variable”, “Show Process” or Show System” menupoints that contain all undisplayed entities belonging to the system whose canvasspace was clicked upon.

Systems

  1. Creating a system: Click on the System button on the palette, then click on the layout canvas. If there is no space left on the canvas for a new system, the system will not be created.

  1. Renaming a system: Double click on the system, the ObjectEditor window will be popped up. Change the name by entering a new name in the ID field.

ObjectEditor > Summary > ID

  1. Resizing a system:

    1. Double click on the system, an ObjectEditor window will be popped up. Click the ShapeProperty tab, enter a new width and height in the width and height fields respectively.

ObjectEditor > ShapeProperty > Width

    1. Drag the outline of the system to the left, right, up, down, or diagonally.

  1. Moving a system: Drag the system to any available space within its parent system.

  1. Deleting a system: Right click on the system, a pop up menu will be shown. Click on “delete from layout” option to delete the system just from the Layout, so the model will still contain it. Click on “delete from model” option to delete it permanently from the model.

  1. Changing system properties: Double click on the system, an ObjectEditor window will be popped up. Click on the PropertyList tab on the ObjectEditor window and the list of properties belonging to the system can be seen. The list contains propertyname, value, flags, propertytype. The value field can be edited if either the settable or saveable flags are set.

    If the property type is INTEGER, FLOAT or STRING the property values can be edited in the list where they appear. Properties of NESTED_LIST and MULTILINE type can be edited on specific dialog windows. The special property editor windows can be displayed by right clicking on the property and choosing “edit” from the upcoming menu.




Processes

  1. Creating a process: click on the Process button on the palette, click on the layout. A default name will be given.

  1. Changing class for a process: Double click on the process, an ObjectEditor window will be popped up. Change the process class using the ClassName dropdownlist under the Summary tab.

ObjectEditor > Summary > ClassName

  1. Deleting a process: Right click on the process, a pop up menu will be displayed. Click on delete from layout option to delete the process from the Layout, or click on deletefrommodel option to delete it permanently from the model.

  1. Moving a process: Drag the process to any available space within its parent system.

  1. Renaming a process: In the ObjectEditor window, enter a new name in the ID field under Summary tab.

    ObjectEditor > Summary > ID

  2. Change process properties: Double click on the system, an ObjectEditor window will be popped up. Click on the PropertyList tab on the ObjectEditor window and the list of properties belonging to the process can be seen. The list contains propertyname, value, flags, propertytype. The value field can be edited if either the settable or saveable flags are set. If the property type is INTEGER, FLOAT or STRING the property values can be edited in the list where they appear. Properties of NESTED_LIST and MULTILINE type can be edited on specific dialog windows. The special property editor windows can be displayed by right clicking on the property and choosing “edit” from the upcoming menu. If the class of the process allows dynamic addition of properties, the Add button is sensitive and the user can add new properties to the process.
    Delete flags are set for properties added by user action.

  1. Change shape properties: In the ObjectEditor window, click the ShapeProperty tab.

ObjectEditor > ShapeProperty



Variable

  1. Creating a variable: click on the Variable button on the palette, click on the layout.

  1. Deleting a variable: Right click on the variable; a popup menu will be displayed.

Click on delete from layout option to delete the variable from the Layout, or click on deletefrommodel option to delete it permanently from the model.

  1. Moving a variable: Drag the variable to any available space.

  1. Renaming a variable: In the ObjectEditor window, enter a new name in the ID field under the Summary tab.

ObjectEditor > Summary > ID

  1. Change variable properties: Double click on the variable, an ObjectEditor window will be popped up. Click on the PropertyList tab on the ObjectEditor window and the list of properties belonging to the variablecan be seen. The list contains propertyname, value, flags, propertytype. The value field can be edited if either the settable or saveable flags are set. If the property type is INTEGER, FLOAT or STRING the property values can be edited in the list where they appear. Properties of NESTED_LIST and MULTILINE type can be edited on specific dialog windows. The special property editor windows can be displayed by right clicking on the property and choosing “edit” from the upcoming menu.

  1. Change shape properties: In the ObjectEditor window, click the ShapeProperty tab.

ObjectEditor > ShapeProperty


Connection

A connection is the graphical representation of a variablereference, practically an arrow between a process and a variable. The direction of the arrow is determined by the coefficient of the variablereference, if the coefficient is negative, the arrow points toward the process, if the coefficient is positive, the arrow points toward the variable.

  1. Creating a connection: Move the mouse over to one of the small dots on the outline of a process and then drag it over to a dot on any variable outline. A connection will be shown between process and variable.

  1. Change varrefname (Variable reference name): Double click on the connection, a ConnectionObjectEditor window will pop up. Change the name by entering a new name in the Name field

ConnectionObjectEditor > Variable Reference > Name

  1. Change coefficient: In the ConnectionObjectEditor window, enter a new coefficient in the Coefficient field.

ConnectionObjectEditor > Variable Reference > Coefficient

  1. Change line properties:

  1. Change the Arrow Style: select the arrow style from the Arrow Style dropdownlist

  2. Change the Arrow Type: select the arrow type from the Arrow Type dropdownlist

  3. Change the Arrow Color: Click on Select Color button, a color chooser will be displayed

ConnectionObjectEditor > Line Property



Preferences Window

Preferences Window is currently used only for setting Autosave parameters.



Desc Files

Descriptor files are plain text files that contain important information about ecell3 entity and stepper classes, most importantly the propertylist, types of properties, default values of properties and attribute flags of properties. The descriptor filenames are classname.desc and are located in ecell/dm for built in classes. If you create your own process or stepper classes, you also have to create a .desc file to enable ModelEditor handle the new classes.
Currently a descriptor file contains 3 entries a general string description of the class, a flag indicating whether the class allows creating properties other than the default properties of the class and a list of built in properties, type, access flags, default values of these properties.
The format of the descriptor file can easily be explained through this example that is actually the descriptor file of the builtin class Variable.





Variable.desc
# general description of the class
DESCRIPTION=Variable
                                                                                
# whether class allows new properties (other then the hardcoded ones) created by modeleditor
ACCEPTNEWPROPERTY=False
                                                                                
# propertyname, type, defaultvalue, flags
# flags are: (settable, gettable, loadable, saveable) 1 means True, 0 means false
# type can be: NESTED_LIST, STRING, MULTILINE, INTEGER, FLOAT
PROPERTYLIST
Fixed, INTEGER, 0, 1111
MolarConc, FLOAT, 0.0, 1100
Name, STRING, "", 1111
NumberConc, FLOAT, 0.0, 1100
TotalVelocity, FLOAT, 0.0, 0100
Value, FLOAT, 0.0, 1111
Velocity, FLOAT, 0.0, 0100
END