The Physiome CellML Environment will provide a unified way to work with CellML documents.
Initial versions provide the ability to run simulations. Full model editing capabilities have been deferred until later releases.
When you click on the New button or choose File => New, the New Model Dialog appears. You can use this dialog to create a new, empty, CellML model.
The ability to create new models is not very useful in this version of PCEnv, because you cannot add components to them, and you cannot save models back out. In future versions, this will be the way to create models de novo.
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 also need to choose a 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. CellML 1.1 adds new features, like the ability to import models from a different file into your models.
When you click on the open button, or choose File => Open, a dialog pops up asking you to choose a model to open from your local filesystem. Choose a model, and click Open.
PCEnv can open CellML 1.1 models (which can in turn import other models). You can either give an absolute URL (e.g. an http URL to a model on a webserver, or a local file:// URL), or you can give a relative URL. If you use a relative URL, PCEnv will interpret it relative to the directory where the importing model resides.
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).
You can browse models in the model selector in three different views. Change Tree lets you see models as a hierarchy of changes. Latest Versions will only show you the most recent version (each time you open a file, this will be a new entry, but when you change the file, that is a new version in the model tree view). History List shows all model versions, in the order they were created.
Models in the model selector do not disappear if you close PCEnv, and then restart it (without first logging out or restarting your computer). This is because they are stored in a separate service running on your computer, called cellml_corba_server. If you want to reset to a blank state without restarting your computer, you can kill this process (you will lose any unsaved changes). When you log out (on some platforms) or restart your computer, cellml_corba_server will be closed, and you will have to re-open your models. Note that it is possible to run two instances of PCEnv at the same time, and the model list will stay synchronised between them.
The model tree view allows you to view the model. This allows you to modify the initial_value attributes on variables. The model tree view is initially located at the top centre of the screen.
The model tree view will eventually allow editing of the entire model. However, this functionality is not exposed in this version of PCEnv, pending further study on MathML editing. For now, you can only change variables, and items underneath them in the CellML tree. However, it is not currently recommended that you change anything other than initial values, as this is not useful without also changing other parts of the model.
To change initial values, just click on the appropriate variable, and enter a value into the text box in the "Value" column.
The integration panel (initially at the bottom centre of the screen) can be used to start integration runs. It lets you enter a number of parameters before starting the integration run:
Parameter | Description |
---|---|
Start point | The 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 point | The 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) |
Algorithm | The stepping algorithm to use for the integration. Note that some algorithms are not suitable for stiff systems, but are faster. |
In the future, all the fields will be pre-filled from simulation metadata. However, at the time of release, only starting and stopping points were fully specified, so there is not yet any way to specify all the metadata.
Once you are ready to run the integration, click the Integrate button. This will run the integration.
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.
The graph viewer lets you plot the data from your integration runs onto a graph. This also allows you to compare graphs from between runs. You can plot arbitrary values on the X and Y axes, and have an arbitrary number of traces.
To add a new trace, click on the "New" button at the bottom right of the screen. You now set up parts of the trace by left-clicking on the appropriate column in the list, as listed below:
Left click on: | to change: |
---|---|
the coloured square | the colour of the trace |
model | the 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 |
X | The 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. |
Y | The 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. |
Type | The way in which points are plotted. Choose line to do a line graph, or another glyph 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.
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.
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.
It is possible to run more than one instance of PCEnv at the same time. As long as you run each instance as the same user (on the same computer), the two instances will share the same list of CellML models. Changes made from one instance will automatically get reflected in another instance of the program.
If you exit PCEnv, then start it again without restarting your computer, the models you loaded will still be there (however, you will have to re-integrate your models, as the data is kept by each PCEnv instance).
PCEnv implements this functionality using a process called cellml_corba_server. If, for some reason, you need to completely exit or restart PCEnv, you can kill the cellml_corba_server process. However, be warned that this will stop any running PCEnv instances from working correctly.