Todo:: Keep up-to-date..

Introduction

The goal of this page is to track the development status of the integration of CellML into openCMISS. It is envisioned that this page will form the basis of user and programmer documentation for the use of CellML models in openCMISS.

It also serves as Andre's test on the use of doxygen for documenting openCMISS developments.

Objectives

A brief outline of the objectives to be achieved through the use of CellML in openCMISS.

User defined math at run time

As with old cm, the driving force for the use of CellML in openCMISS is providing the ability for users to use their own cellular models in multiscale physiome style models and computational simulations. This is seen as a specialisation of the more general definition of a user defined field backed by one or more CellML models. Fields defined thus can be applied to many different problems, although we will have to wait and see how general we can make this.

Multiple models and parameterizations

Any field defined by CellML models needs to be able to handle different CellML models defined over the DOF's of the field. Additionally, each model can have many different parameterizations throughout the domain of interest.

Similarity with specialised tools

openCMISS is a general simulation tool for physiome models. As such, there are many tools more suited to the development and validation of the various mathematical models used in a physiome model. CellML is seen as the way models developed in such tools can be utilised in openCMISS.

When using CellML this way, users want to be assured that the CellML models will behave similarly as they do in the original tools. The use of CellML simulation metadata in the definition of the computable objects created for each CellML model is seen as the way to achieve this objective.

Current Status

Background

Initial work has been completed, under the basicSimulationApplication branch of the openCMISS cellml subversion project (http://trac.bioeng.auckland.ac.nz/projects/opencmiss/browser/cellml/branches/basicSimulationApplication), investigating the use of the CellML C++ API implementation with a Fortran 95/2003 application environment. This evaluation was quite successful and provided a few key outcomes:

the Fortran 2003 standards for mixed language programming are superior enough that we decided to begin allowing Fortran 2003 code in openCMISS;
more that I can't remember at the moment...

openCMISS(cellml) API

The basicSimulationApplication described above (Background) primarily tested out the use of the C++ implementation of the CellML API from Fortran code. This forms the basis of the openCMISS(cellml) API, which will provide the interface used by the openCMISS(cm) CellML API implementation to interact with CellML models and metadata via the C++ CellML API implementation. As the openCMISS(cm) CellML API is implemented, the openCMISS(cellml) API will be defined and implemented.

openCMISS(cm) CellML API

Initially defined in the openCMISS powerpoint presentation and now coded into the opencmiss_cellml.f90 module, is the outline of the openCMISS(cm) CellML API. This API defines the openCMISS methods for using CellML models to define a field and will work with the openCMISS(cellml) API to interact with CellML models via the C++ implementation of the CellML API.

Development

This is where we document the status of the development. See the cellml example page (how to reference?) which demonstrates this.

openCMISS CellML Environment

The openCMISS CellML environment object (a good name/concept?) is the main interface presented to openCMISS user when a field is to be defined using CellML model(s). A specific instance of a CellML environment object contains and manages its own CellML models, parameterization fields, etc. The environment object also manages the connection of the field values for each field DOF to the CellML models defined in that environment.

Todo:: Should we now mark the field as read-only for code outside of the CellML environment? or are we smart enough to handle externally applied changes? is there a way to get callbacks or messages when the field changes?

Todo:: is this field actually used for anything inside the CellML environment or does it simply provide the descretisation at which the models, state, intermediate, and hidden parameters fields must be defined? In this case, code external to the CellML environment is responsible for getting the values it needs from the above named fields.

CMISS_CELLML::CELLML_CREATE_START

CMISS_CELLML::CELLML_CREATE_FINISH

Define the CellML models

Now that the user has a CellML environment the first step is to load in the CellML models to be used. We expect the URI provided for model imports to point to either a CellML model element or, preferably, to CellML simulation metadata.

Todo:: perhaps better to force the use of CellML simulation metadata, otherwise we need to provide methods to define the equivalent data natively in openCMISS.

CMISS_CELLML::CELLML_MODELS_CREATE_START

CMISS_CELLML::CELLML_MODEL_IMPORT

CMISS_CELLML::CELLML_MODELS_CREATE_FINISH

Map models to DOFs

Having loaded all the desired CellML models into the CellML environment we can now define the distribute of models within the domain of interest. The initial thought is to simply define a models field which has the unique model identifier of the model to use at each DOF in the field for which this CellML environment is defined.

Starting to think that a better way might be to instead map the components of the environment's field to specific variables within the models of the environment. This would allow greater flexibility in the assembly of CellML models to provide the definition of the field values. This approach would also solve the issue of mapping field components to model variables...

CMISS_CELLML::CELLML_MODELS_FIELD_CREATE_START

CMISS_CELLML::CELLML_MODELS_FIELD_GET

CMISS_CELLML::CELLML_MODELS_FIELD_CREATE_FINISH

The state field

Once we know which models are to be applied where in the field domain we can create a internal field for use in storing all the state variables of the models contained in this CellML environment. As the state variables must be stored for every DOF in the environment's field we know the structure of the state field to be created (unlike the case of intermediate and parameter variables, where further information is required to determine the field/component structure). The state field can be obtained for use by the user for either extracting/recording values or setting initial conditions.

CMISS_CELLML::CELLML_STATE_FIELD_CREATE_START

CMISS_CELLML::CELLML_STATE_FIELD_CREATE_FINISH

CMISS_CELLML::CELLML_STATE_FIELD_GET

Intermediate model variables

CellML models will typically contain many intermediate variables (algebraic) which may be of interest to the user - and may even be used to define the environment's field values? If the user of this environment is interested in any of these model variable values they must let openCMISS know that such variables are stored in a user accessible field.

CMISS_CELLML::CELLML_INTERMEDIATE_FIELD_CREATE_START

CMISS_CELLML::CELLML_INTERMEDIATE_FIELD_ADD

CMISS_CELLML::CELLML_INTERMEDIATE_FIELD_CREATE_FINISH

CMISS_CELLML::CELLML_INTERMEDIATE_FIELD_GET

Model parameterizations

Parameterization of the models contained in a given CellML environment is a two step process. First, the user must nominate all the parameter variables for which they want to override the `default' value defined in the CellML model.

CMISS_CELLML::CELLML_PARAMETERS_CREATE_START

CMISS_CELLML::CELLML_PARAMETERS_ADD

CMISS_CELLML::CELLML_PARAMETERS_CREATE_FINISH

Secondly, a user accessible field is created which allows the user to define the custom value for each parameter throughout the field's domain. The user is free to modify this field and the components in it to use the most appropriate interpolation, etc, for them to define the parameter value. Internally, this user accessible field will be mapped to a hidden field with discretization matching the environment's field.

CMISS_CELLML::CELLML_PARAMETERS_FIELD_CREATE_START

CMISS_CELLML::CELLML_PARAMETERS_FIELD_GET

CMISS_CELLML::CELLML_PARAMETERS_FIELD_CREATE_FINISH

Envrionment instantiation

Having created a CellML environment, imported models, defined parameterizations, created fields, etc., all that remains is to instantiate the environment ready to start performing computations. Environment instantiation is the point at which CellML models are turned into computable objects and distributed amongst the processors which need access to them.

CMISS_CELLML::CELLML_GENERATE

Model evaluation

Probably the largest remaining question is whether we need a specific method or collection of methods used to evaluate (increment the independent variable?) all the models in a given CellML environment. Currently, I am assuming that the CellML environment automatically handles this through the field upon which the environment is defined. Whenever openCMISS asks this field for its current values (values at some time, t?) the field knows that it is defined via a CellML environment. Therefore it asks the CellML environment to provide the current values and the envrionment works out what to update and how to do so.

Utility methods

These are methods provided by the openCMISS(cm) CellML API as utilities for use by developers.

CMISS_CELLML::CELLML_FIELD_COMPONENT_GET