CellML2CΒΆ

CellML2C is a test application that is part of the testing framework of the CellML API. OpenCOR uses essentially the same code when it generates code to perform a simulation, but currently the useful debugging information is not presented to the user. Similarly, PMR2 makes use of the same code to generate the various format procedural codes from a model exposure, but that is only available for exposures. OpenCMISS also uses this code.

To have access to CellML2C you need to build the CellML API yourself, which is not too difficult.

CellML2C is executed as follows:

$> CellML2C <model URL>

Any URL can be provided, including URLs to remote files such as the model repository and local files. For example, with this test model:

$> CellML2C path/to/valid-test-model.xml

Depending on your platform, you may need to play a bit to get relative local URLs to correctly work with CellML2C and models with imports. Executing the above command (for ABI users) which will result in the following C code being generated:

/* Model is correctly constrained.
 * No equations needed Newton-Raphson evaluation.
 * The rate and state arrays need 0 entries.
 * The algebraic variables array needs 0 entries.
 * The constant array needs 2 entries.
 * Variable storage is as follows:
 * * Target sin in component sin
 * * * Variable type: constant
 * * * Variable index: 1
 * * * Variable storage: CONSTANTS[1]
 * * Target x in component sin
 * * * Variable type: constant
 * * * Variable index: 0
 * * * Variable storage: CONSTANTS[0]
 */
void SetupFixedConstants(double* CONSTANTS, double* RATES, double* STATES)
{
/* Constant x */
CONSTANTS[0] = 1.0;
/* Constant actual_sin */
CONSTANTS[1] =  sin(CONSTANTS[0]);
}
void EvaluateVariables(double VOI, double* CONSTANTS, double* RATES, double* STATES, double* ALGEBRAIC)
{
}
void ComputeRates(double VOI, double* STATES, double* RATES, double* CONSTANTS, double* ALGEBRAIC)
{
}

and having produced some code, CellML2C is letting you know that your model is most-likely complete (but it does not rule out errors in variable connections, units, etc.). It is sometimes useful to check the first comment block in the generated code which describes the variables in the model which are present in the generated code. If variables you are expecting to be state variables show up as constant or a model parameter shows up as a state variable, then it might suggest something to look into.

If your model is not complete, CellML2C will be unable to generate procedural code from the model. In this case you will receive some potentially useful information that might help debug the model. When you get an error message from CellML2C such as Model is unsuitably constrained you’ll also get a list of all the variables that are known about and their status. For example, with this incomplete test model:

$> CellML2C /path/to/underconstrained-test-model.xml
/* Model is unsuitably constrained (i.e. would need capabilities beyond those of the CCGS to solve).
 * The status of variables at time of error follows...
 * *  Undefined: sin
 * *  Undefined: x
 */
When you get an error like this, it is best to start at the bottom of the list of undefined variables and work your way up. For example, in this case the variable x is undefined and sin = sin(x) so sin is also undefined. There are two main errors that this might help you find in your model:
  • the model is underconstrained (such as in the above example) - this is usually due to a variable missing an initial_value attribute or perhaps you missed out the equation that defines that variable;
  • the model is overconstrained - this is usually caused by having an initial_value specified for a variable which is defined as an algebraic variable in the procedural code (e.g., the sin variable in the above example); or
  • some combination of the above.

These can help get things working, but it can be painful digging through your model(s) to find the errors.