Ecell3 Model Editor Step by step guide to model building

The purpose of this tutorial is to lead the reader through the process of creating a simple model and get quickly accommodated to the use of Model Editor.

Our example model is a Uni Uni mechanism with one transitory complex in a virtual test tube which we are going to simulate using ordinary differential equations.

The reaction should occur in a 10 ml solution of 0.01M Substrate and 0.001 M Enzyme (initial concentration).

The rate constants are:

In the reaction there are 4 substances : Enzyme, Substrate, Enzyme-Substrate complex, Product.

There are two partial reactions: ES Complex formation and Product formation.

The ES Complex formation rates can be described with the following differential equations ( these equations refer only to the partial reaction ):

The Product formation rates can be described as:

Therefore we have 4 Variables and 2 Processes.

Let's create a model in 10 steps!

1. Launch ModelEditor
   You can do it by either:
   a) Click on Modeleditor icon
   b) Type in a command prompt ( shell ):
   ecell3-model-editor
   
   As can be seen a PathwayEditor window has already opened with an empty white layout canvas. The RootSytem ('System::/') and a Default Stepper as well as the SIZE variable for RootSystem is automatically created.
   
   

2. Create 4 variables:
   Click on the Variable selector button on the Palette.
   Move the mouse over the layout canvas and place the variables on the layout by mouseclick.
   
   
   

3. Create 2 processes
   Click on the Process selector button on the Palette.
   Move the mouse over the layout sheet and place the variables on the layout by mouseclick.
   
   
   

4. Rename Variables:
   Doubleclick on Variable newVariable2, a dialogwindow called “ObjectEditor” should pop up.
   Click on the Summary tab of the dialogwindow ( if it is not already selected ) and overwrite “newVariable2” in the editbox to “Enzyme”. Press ENTER.
   
   NewVariable2 will be renamed on the layout canvas, too.
   Rename all the other variables and processes accordingly:
   newVariable1 -> Substrate
   newVariable3 -> ES_Complex ( avoid using spaces! )
   newVariable4 -> Product
   newProcess1 -> Complex_formation
   newProcess2 -> Product_formation
   
   
   

5. Connect Processes to Variables

   At first connect Complex_formation to Substrate
   Point the mouse to the small rectangle at the right side of variable Substrate and drag the mouse to the rectangle at the left side of the process Complex_formation.
   
   A connection arrow is established between the variable and the process, with an automatically generated label - X0.

   Let's then connect all the other variables to their respective processes.
   Connect Complex_formation to Enzyme, Complex_formation to ES_Complex, Product_formation to ES_Complex, Product_Formation to Product and Product_formation to Enzyme.
   
   
   

6. Set the arrows in the right direction
   It may happen that the do not always point to the right direction of the rate flux. To correct it, double click on the arrow between Complex_formation and Substrate.
   A dialogwindow called ConnectionEditor comes up.

   

   Set the coefficient to -1, if it is not already -1.( the coefficient defines the direction of flux as well as the stoichiometry ). Press ENTER. The arrow will now point towards the ComplexFormation reaction. Rename the connection to S. The process will refer to the variable by the name of the connection ( variablereference ).
   Rename and redirect all the other arrows that are pointing into the wrong direction:

   Between Enzyme and Complex_Formation: Coefficient -1, new name: E
   Between ES_Complex and Complex_Formation: new name: ES
   Between ES_Complex and Product_Formation: Coefficient -1, new name: ES
   Between Enzyme and Product_Formation: new name: E
   Between Product and Product_Formation: new name: P
   
   Notice that connections belonging to a process must have different names, however connections belonging to different processes can have same names.

7. Set process class
   Now we have to set the class of the process this will tell the Simulator which dynamic module it should use for calculating the reaction rates. We are going to use ExpressionFluxProcess, where differential equations can be freely defined by the syntax and semantics of the C++ language .
   Doubleclick on Product_Formation process. The ObjectEditor window pops up, or if it was not closed changes its content to the chosen process.
   Click on Summary tab.
   On the Class drop down list select ExpressionFlux.
   
   Repeat the operation with the other process ( Product_Formation )
   
   
   

8. Enter rate constants
   Now we have to create the property slots for our rate constants.
   Doubleclick on Complex_Formation process and select Property tab on the ObjectEditorWindow.
   Click on Add button at the bottom of Property window. A new property slot will be added to the process.
   By single mouse click both the new property and its value can be edited. Rename the new property to k1 and its value should be 2.
   Create a new property in this process called k_1 and give its value 1e-4.
   
   Create the k2 and k_2 rate constants in process Product_Formation and set their values 3e-3 and 4e-7 respectively.
   
   
   

9. Enter equations
   Select Complex_Formation process on ObjectEditor and select its Expression property on the Property tab.
   Enter the differential equation:
   (E.MolarConc*S.MolarConc*k1-ES.MolarConc*k_1)*self.getSuperSystem().SizeN_A

   E.MolarConc = [E], k1, k_1 are the rate constants, self.getSuperSystem().SizeN_A is the system size ( volume ) multiplied by the Avogadro number.

   

   The technical adjustment of multiplying with SizeN_A is necessary because ExpressionFlux is expecting the reaction rate in number of molecules, not in molar concentrations.

   Enter the differential equation for the Product_Formation process, too.
   (-P.MolarConc*E.MolarConc*k_2+ES.MolarConc*k2)*self.getSuperSystem().SizeN_A
   
   

10. Enter initial concentration values
    Enter solution volume for the model. This can be given as the Value property of the variable SIZE. This variable cannot be seen on the Layout because it was created not by us but the ModelEditor automatically.

    To be able to see it open up an EntityListWindow
    Click on SIZE variable and then select the PropertyList tab on the right side. Edit Value property, set it to 0.1 ( 100 mL).
    
    Either on EntityWindow or PathwayEditor's ObjectWindow set the MolarConc properties of Enzyme and Substrate to 0.01 and 0.001 respectively.
    
    

11. Save model
    Our model is ready for running in the Simulator!
    Click on save button and enter a filename like 'UniUni.eml'.
    
    The model will be saved.
    
    

12. Load run and evaluate model in Session Monitor
    Launch the Session Monitor application either from command prompt ( by typing gecell ) or icon.
    Load the newly created model. Create a Tracer window by selecting Enzyme, Product, ES_Complex and Substrate variables, and clicking on “View Selected” button, then run the simulation for about 6000 seconds ( set step size to 6000 secs and press on Step, not Run ).
    
    
    

13. Delete

    If we no longer need, a process or a variable we can delete them:

    On the PathwayEditor window- right click on the object and select “delete from model”, if “delete from layout” is selected the process or variable will only be deleted from the layout but stay in the model. They can be shown again, by right clicking on the PathwayEditor and selecting the “Show variable” or “Show process” options.

    On EntityWindow we can also delete Processes and Variables, either by using the “Delete” buttons or the right-click menus. Deletion on EntityWindow means deletion from the Model and from all the Layouts.
    
    

14. Redo undo, autosave
    During editing many security options save us from loosing our data.

    Any operation can be undone and redone again (including deleting whole systems ).

    In Preferences Window the user can set autosave options (e.g. interval between recurrence of , the autosave files will be found in the same directory to where the model was saved.