Continuity Model Editor

Contents

  1. Continuity Model Editor
    1. Step 1. Select model
    2. Step 2. Edit properties
    3. Step 3. Edit equations
      1. Variable types
      2. Variables included by default
      3. Variable List
      4. Import/Export
      5. Writing Equations
    4. Step 4. View code
    5. Step 5. Compile
    6. Step 6. Set initial values
    7. Step 7. Set parameters
    8. Step 8. Submit

The Models Editor is a user-friendly way to create and edit the equations and parameters of a model and then automatically generate efficient, compiled code in Continuity. The Models Editor is used to create and edit ionic models in electrophysiology problems, constitutive equations including active stress models in biomechanics problems, and biochemical reactions in biotransport problems.

The Models Editor has eight tabs that take you through successive steps in the workflow as you progress from left to right. You can navigate the different tabs in any order, but to begin with you will find it easiest to proceed progressively from the leftmost tab (Select Model) to the rightmost tab (Submit). The example screenshot above shows the Models Editor with an ionic model.

Step 1. Select model

  • Here you choose which model (set of equations and parameters) you want to edit.

    • To create a new model, select <<add new model>> from the list

      • If the model is new (or labeled [not compiled]), be sure to go through each of the other tabs to create the equations, generate code, compile code and specify initial conditions and parameters for the model before you submit
    • To use a pre-existing model, simply select one from the list
      • The list displays models available on the server you are connected to
      • Most pre-installed models will already be labeled [compiled]. If you don ‘t wish to edit the equations, you can jump directly to the set initial values and set parameters tabs.
      • Models labeled [not compiled] or models for which you edit the equations or variables much be saved and compiled before you set parameters and submit.
    • To use a modified version of an existing model without changing the original one,
      • Select the model you want to modify

      • Click File?Save as…

      • Enter a new filename for the model and click OK

      • Select this model in the list
  • After selecting your desired model, proceed through the rest of the tabs from left to right to edit equations, generate and compile code, set initial values and parameters, and finally submit the model.

Step 2. Edit properties

  • This tab shows general information about the model such as the title, author and creation date. You can edit this information, but the changes will be saved only if you click Save file in the Compile tab.

    • File name: shows the name of the currently selected model.

      • Avoid entering spaces or illegal characters for the file name, which must be a legal file name on your server.
      • This file name uniquely identifies a model in the list.

      • If you give any model the same file name as that of already existing model, the original model will be replaced!

    • Author: The person or people who created the model

    • Title: A brief description of the model

Step 3. Edit equations

On the left in this tab is a list of all the variables in the model. This includes constants, independent variables, temporary variables and various types of dependent variable.

Variable types

When you create a new variable, the variable type can be selected from the drop-down list on the top-right corner of the Edit equations tab

  • Constants: These are assigned a fixed numerical value, or an expression that evaluates to one. These variables are inserted inline into the code to make it more efficient and to allow for compiler optimization. The “equation” for a constant is the FORTRAN 95 parameter statement assigning a constant value to the variable. A template for the correct f95 syntax will be created automatically when you create a new constant.

  • Independent variables: All independent variables required for the problem are included in the default list of variables for a new model and are locked so they can not accidentally be deleted. No more independent variables than those should be needed. These are the required input variables to the model equations and generally appear as input arguments in the resulting code. There are no equations for independent variables.

    • For electrophysiology ionic models, there is just one independent variable, time, t

    • For biomechanics constitutive equations (strain energy functions), there are five independent variables: C (the Right Cauchy-Green Deformation tensor), detC (the determinant of C), C_inverse (the inverse of C), pressure (the hydrostatic pressure Lagrange multiplier), and T (the active contractile tension).

  • Temporary variables: These are “helper variables” present in equations that are used in the course of evaluating the model equations, but not required externally to the model equation code.

  • Dependent variables: depending on the type of problem, various types of dependent variable may be available. In electrophysiology ionic models and biotransport reactions, dependent variables may be algebraic variables, state variables or spatially coupled variables. State variables are governed by ordinary differential equations (ODEs), and the corresponding equation specifies the time derivative of the variable, dStateVar_dt= …. Spatially coupled variables appear in the PDEs for the problem and must correspond to a dependent nodal variable in Continuity. In Biomechanics constitutive equations, there are scalar and tensor dependent variables. For example, stress is a tensor dependent variable represented by a 3×3 matrix.

Variables included by default

  • Depending on the type of problem, some variables will be included by default when you create a new model.
  • For electrophysiology, these are included by default:

    • t: current time

    • V: voltage

  • For biomechanics, these are included by default:

    • C: Right Cauchy-Green Deformation Tensor

    • detC: Determinant of Right Cauchy-Green Deformation Tensor

    • C_inverse: Inverse of Right Cauchy-Green Deformation Tensor

    • pressure: Hydrostatic pressure Lagrange multiplier

    • stress: Second Piola-Kirchhoff Stress Tensor

Variable List

  • This is a list of all the variables used by the current model.

  • The order of the variables in the list is important, as a variable can be used in equations only if defined above the variable currently being modified. To change the order, use the Shift Up and Shift Down buttons.

  • You can add new and remove existing variables as needed by using the Insert Variable and Delete Variable buttons.

    • When inserting variables, be sure to select the appropriate variable type from the drop-down list.
    • When deleting variables, ensure that the variable isn’t required in any of the model equations.

Import/Export

  • The Import/Export button will open the Continuity Table Manager.

  • You can save an entire equation model (all variables, values, parameters, etc.) this way for use later or for collaboration purposes.
  • If you already have a saved equation model file, you can import it in to use that model.

  • See the Continuity Table Manager help page for more details.

Writing Equations

  • Equations are required for most variable types except independent variables.

  • The syntax for editing equations is FORTRAN 95 expressions (case insensitive) embellished with some XML-like markup.

  • Adjustable (non-constant) parameters in equations are always represented as an XML node using the following convention <param_name>. When the equations are parsed by Continuity, a list of parameters is generated in the Set Parameters tab, and the identifier param_name is used in the FORTRAN code.

  • More powerful python-derived syntax can be inlined with the f95 expressions by using the <mat>special code here</mat> markup. The resulting Python can generate valid code for matrix operations etc.

Step 4. View code

  • This is where you can see how the source code for the model actually looks. Currently, the code is generated in FORTRAN 95.
  • The formatted code has syntax highlighting
  • Variables and parameters are hyperlinked to their definition in the Models Editor.
    • Variables are hyperlinked in red
    • Parameters are hyperlinked in blue
  • You can save the code as a a raw text file:

    • Select Window?View Fortran

    • Select File?Save…

Step 5. Compile

  • This tab is where you can save the model and compile it.

  • Any changes you made in the Edit properties or Edit equations tabs can be updated by clicking the Save file

    • Note that you must still re-compile if you want the changes to have any effect on the problem your working on

    • If the Filename currently entered in Edit properties is not already used, this model will show up as a new one in the list. Otherwise, any changes made to the model will be updated in the existing file.

  • Click Compile if you want to compile a new model for the first time or re-compile another model after making some changes.

    • Select which machine to use to compile the code. If your server does not have the required environment to compile or if you are not sure, select webservice from the drop down list

    • Compiling should take no more than 3 minutes.
    • You will get a message indicating whether compilation succeeded or failed. If it failed, the message will provide a link that gives more information on the problem.

  • Saving and compiling are only dependent on the two Edit tabs before this Compile tab. You can make changes in the next two tabs without having to re-compile.

Step 6. Set initial values

  • For problems that include ordinary differential equations, an initial value needs to be specified for state variables, spatially coupled variables and algebraic variables. All variables defined in Edit equations that require an initial value will automatically appear in the list in this tab.

Step 7. Set parameters

  • If any equation in the model requires one or more parameters, each parameter should be enclosed in angle brackets in the equation, as shown below:

    • ans = <my_parameter1>*some_variable^<my_parameter2>

  • Also added to this list are three conductivity variables associated with the spatially coupled variable in electrophysioloy problems. These variables can only be set to Fields (not a value).

  • These parameters will automatically appear in the list in this tab. Note that no parameters can be added or deleted, as they are automatically populated from the equations.

Step 8. Submit

  • Simply click the Submit button to send all the equation data.