Physiome CellML Environment (PCEnv) User Manual

Contents

What is PCEnv?

The Physiome CellML Environment (PCEnv) is an open source tool environment currently being developed at the Auckland Bioengineering Institute. It provides a unified way to work with CellML documents, including creating new models, editing exisiting models, and running simulations.

Opening a model

To open an exisiting CellML model choose File => Open and a dialog box pops up asking you to choose a model to open from your local filesystem. Choose a model, and click 'Open'.

The model selector

The model selector appears on the left hand side of the screen. It allows you to switch between the different models you have open.

To select a model to work on, put the mouse over your chosen model, and then click the left mouse button. You can also right-click on a model to open a menu of options. From here, you can Rename a model, Close it, or Clone it (create a copy of it - please see below for more details).

You can browse models in the model selector in three different views:

Cloning a model

Cloning models allows changes to be made to a model whilst retaining the original version of a model and its results. To clone a model, right click on the model name in the left hand pane and select 'Clone'. A new model appears in the tree, underneath the original model. Initially it is named by the date it was created. To rename this new model right-click on the model name and choose 'Rename'.

Viewing the model structure

At the top of the top-centre pane of PCEnv, there are two small buttons. One, which is selected by default, is a blue circle with a 'V' next to it. This presents a view of all constants and initial conditions defined in the model. The other button, which has a cartoon of a cell inside a set of angle brackets (<>), corresponds to a view of the entire CellML model.

Editing a model

Clicking on the latter button will present you with a 'tree' representation of the entire CellML model; including a list of all the components, variables, units, equations, and connections. In this view it becomes easy to edit a model, as discused below:

Adding new components and variables

To add a new component to a model right click on the first line of the tree, titled 'Components', and choose 'New'. A new component called 'New_component' will appear at the bottom of the list. The name of this component can be changed by clicking on it and by changing the value in the text box.

To add a new variable to a component right click on the component name and choose 'New Variable'. Next, click on the '+' sign next to the component name to expand the component. Click on 'New_variable' to change its name.

Adding mathematical equations

To add a mathematical equation to a component, right click on the component name and choose 'New Maths'. Right click on 'Mathematics' and choose 'New Equation'. Click on the '+' next to 'Mathematics', and then on 'Equation'. The bottom middle pane of the screen will change to a mathematical editor. The intention here is that you will see a display of mathematics and an editable text form of the MathML in a model (however, due to a bug in our underlying architecture, a wrong font gets selected so the math display is disabled in this release).

Creating connections

When two or more components share a particular variable it is necessary to connect those components. To create a connection between two components first, right click on 'Connections' and choose 'New'. Click on the '+' next to the connection at the bottom of the list, and add the components to be connected by clicking on 'Component_1' and choosing the appropriate component from the drop-down menu. Repeat the process for 'Component_2', then right click on the connection and choose 'New Variable Mapping'. In a similar way, choose the appropriate variable(s) to be connected from the drop-down menu.

New units

CellML provides a dictionary of standard units that may be used in variable declarations or attached to bare numbers in mathematics. These include the SI base units and some additional units commonly used in the types of biological models likely to be defined using CellML (for a list of these units please refer to the CellML 1.1 specification (http://www.cellml.org/specifications/ cellml_1.1/#sec_units). When units are required which are not included in this list, it is possible to describe them by adding a new units definition, which is based on units in the SI dictionary listed in the CellML dictionary, perhaps with a prefix (e.g. milli) or a multiplier attached.

A new unit can be added to a model in PCEnv by right clicking on 'Units' in the model tree and choosing 'New'. This new unit can be defined as either being 'base' or 'derived' by clicking on the drop-down menu next to the unit name. PCEnv allows components and models that declare variables with different units to be connected as long as variables that are mapped to one another have the same dimensions: for example feet and metre, or pound and kilogram.

Imports

CellML 1.1 allows for you to import other models. To add a new import, right click on "Imports", and choose "New". Click on the new import row. Now type a URL for the model in the box under the Type column.

You will now be able to add in Import Components (components to import) and Import Units (units to import). To add a new import component, expand the imported model, and then choose New. You will now have a new Import Component appear. The text-box under the type column (initially New_import_component) describes the name in the importing model, and the text-box under the value column describes the name in the imported model. An exactly analogous rule applies for the import units.

You can also expand "Model" to view the imported model. Changing the imported model here not recommended, as there is no way to save you changes. Instead load the imported model separately in PCEnv.

Creating a new model

To create a new model in PCEnv choose File => New and the 'create new model' dialog box appears. You can use this dialog to create a new, empty, CellML model.

In the name field, you need to enter a name for the new model. This name is displayed in the user interface as the name of the model. It is not the same as the filename, as you will be prompted to enter this when you save the model for the first time.

You can also choose which version of CellML to use. PCEnv supports two different versions of CellML, CellML 1.0 and CellML 1.1. CellML 1.0 is an older specification, and it is more widely supported in that the majority of the models in the CellML model repository (http://www.cellml.org/models) have been coded in CellML1.0. However, CellML 1.1 supports new features such as the ability to import models from a different file into your current model. Furthermore, it is anticipated that use of CellML1.1 will increase in the future, and may become the preferred standard to use.

Once the model is opened in PCEnv you are able to modify and edit the model using the features discussed above under 'Creating a new model'.

Running model simulations

The integration panel at the bottom centre pane of the screen can be used to run model simulations. It lets you set the initial conditions for a number of different parameters before starting the simulation:

ParameterDescription
Start pointThe value of the bound variable at which the initial value attributes hold. The integration will proceed from this point.
Point density The maximum number of points in the graph. Because an adaptive step size integrator is used, the actual number of points may vary. This control works by limiting the maximum density of points in any region of the graph containing two or more points.
End pointThe value of the bound variable at which the integration will stop.
Absolute epsilon value The absolute error control parameter. This is a positive real number. As values tend to zero, the error will decrease, but the time taken to run the integration will increase.
Relative epsilon value The relative error control parameter. This is a positive real number. As values tend to zero, the error will decrease, but the time taken to run the integration will increase.
Variable Scale Factor A value controlling the relative importance of getting variable values correct (as opposed to getting rates correct).
Rate Scale Factor The corresponding scale factor for rates.
Maximum Step Size An upper limit on the allowable step size.
Algorithm The stepping algorithm to use for the integration. Note that some algorithms are not suitable for stiff systems, but are faster.

The following choices for algorithm are available:
AlgorithmDescription
BDF 1-5 with solve A Backwards Euler algorithm good for stiff problems.
Adams-Moulton 1-12 An Adams-Moulton algorithm good for non-stiff problems.
Implicit Runge-Kutta (2) with solve An alternative algorithm for stiff problems.

Once you are ready to run the simulation, click the 'Integrate' button. This will run the model.

In PCEnv, there is a 1-1 relationship between integration runs and models in the model tree view. Therefore, you select previous integration runs in exactly the same way that you select models. If you want to have more than one run for the same input model, you can clone the model in the model selector. You will be prompted to do this automatically if you try to change a model after you have run it.

Viewing graphs

The graph viewer lets you plot the data from your model simulations onto a graph. This also allows you to compare graphs from two or more simulations. You can plot arbitrary values on the X and Y axes, and have an arbitrary number of traces.

To add a new trace, right click in the white area at the bottom right corner of the screen and select 'New Trace' from the popup menu. You are now able to define the different attributes of the trace by left-clicking on the appropriate column in the list, as described in the table below:

Left click on:to change:
the coloured squarethe colour of the trace
modelthe model being plotted. The default, Link Selected, means that the trace will change models as you change the model in the model selector. However, you may want to compare one model or run against another. In this case, select the first model, and choose Copy Selected Model. The trace will now be locked on this model. Now make another trace, and select the second model
XThe variable to draw on the X axis. You select a variable from the popup menu by firstly selecting a component name, and then a variable name.
YThe variable to draw on the Y axis. You select a variable from the popup menu by firstly selecting a component name, and then a variable name.
TypeThe style in which points are plotted. E.g. choose 'line' to do a line graph, or 'dot' for a dot plot.

You can disable or delete traces by right clicking on the trace, and choosing the respective options from the popup menus.

Labelling graphs

To change the title of the graph, simply select 'Untitled' in the white area above the graph and type in the new name of the plot.

Comparing two or more plots

To compare two plots simultaneously click on the 'Two graphs' button which is on the toolbar beneath the main menu and is the second icon from the right. Clicking on this icon provides a two graph view.

Zooming in and out

To zoom in on a feature of the data, click the left mouse button, drag a box over the feature, and release the mouse button. The selected box will be your new co-ordinate space.

To zoom out by 150%, right click on a zoomed in graph, and select Zoom out. To return to the original view showing all data, right click on a zoomed in graph and select Zoom full.

Re-arranging the environment

PCEnv's user interface contains many different components, and sometimes you may want one part of the environment to take up more screen space than the default. You can do this by putting the mouse over the bar that separates components of the user interface, pressing the left mouse button, and dragging the component into the part of the screen where you want it. If you try to resize a component to below the minimum size, it will fold down to zero size until you drag it back out.

To see features of your data better, try expanding your graph area to take up the whole screen.

Although only one graph panel is visible when you initially start PCEnv, there are actually two more hidden at the bottom right of the screen. This is useful if you want to compare two different graphs on separate, but lined up, axes.

Saving a model

Finally, to save a new or modified model choose 'File => Save As', and save the model to somewhere on your local file system. For instructions on how to submit a model to the CellML model repository please refer to the model repository section of the CellML website (http://www.cellml.org/models/).

Using sessions

An introduction to sessions

A session is a special file which can describe the entire environment you set up in PCEnv, including the list of models which are open and any graphs which you may have defined. It is useful because it allows you to come back to PCEnv exactly how you left it.

The default session

The default session is a special session file which is stored in your PCEnv profile directory (exactly where depends on your operating system, but don't worry, because you will never need to look at it). It provides a convenient way to save what you are doing and come back to it later.

To save the default session, choose File => Save Default Session.

To restore you default session saved earlier, choose File => Load Default Session.

A session does not actually contain the models, it only contains links to them. It is therefore important that you save your models as well as your session. Also, because sessions need cmeta IDs on variables to properly save your mathematics (it adds them automatically when saving your session) it is important to save the models after you save your session.

Exporting and importing sessions

Sometimes, you may want to export a session to give to someone else, or to keep for a long period of time. You can create such a session by choosing File => Export Session and choosing the file to save to.

You can also import a session provided by someone else by choosing File => Import Session and choosing the file to load.

Sessions will normally refer to models by a file URL. You can edit the session file after exporting if you know of a more generally valid URL for the model, and replace the URLs.

Don't forget to share your models together with your session, because session files do not contain the model itself, only a link to them.

You can find some pre-configured session files for certain models on the CellML repository. PCEnv will load them for you if you click on them and choose PCEnv as the program to open the file.