Model flattening

flattenCellmlModel is a little utility which provides two different algorithms for flattening CellML 1.1 model hierarchies into CellML 1.0 models. These are described in detail below.

Version Converter

The VersionConverter algorithm is Jonathan Cooper’s original model flattening algorithm updated to work with newer versions of the CellML API. It is primarily designed to flatten model hierarchies into a single CellML model document whiole maintaining the modular structure of the original source model.

This algorithm is used by calling flattenCellmlModel with the model flattening mode:

$> flattenCellmlModel model <source model URL> [output file]

if no output file is specified the generated model (if flattening is successful) will be written to the terminal - which might obscure any useful model debugging messages that are also printed to the terminal. So you would usually specify an output file:

$> flattenCellmlModel model path/to/model.xml flat-model.xml

Now you should easily see the debug output in the terminal and the flattened model is written to flat-model.xml, if the model was successfully flattened. If this hasn’t helped debug the problems with your model, but you do get a flattened model, then you might want to play with the flattened model in some of the other tools to see if that helps.

Model Compaction

Model compaction is a model flattening algorithm that I specifically developed to help debug issues in hierarchical CellML models that none of the existing tools were able to locate or inform me about. The model compaction algorithm also tries to address some of the unsupported features of the version converter algorithm and produce an accurate representation of the mathematical model without worrying about the modularity of the source model. The compacted model will consist of two components. The first component will contain all the variables defined in the model being compacted, with names altered to be unique within the component. The second component will contain all the variables, math, and initial_value’s required to fully define the model (if the source model is successfully compacted). Units will all be converted to their canonical representation in the generated model, and in some places the code tries to ensure compatible units are used. See the issues for some of the known issues when dealing with units.

This algorithm is used by calling flattenCellmlModel with the variables flattening mode (because the focus is on the variables and their relationships rather than the model itself):

$> flattenCellmlModel variables <source model URL> [output file]

As above, specifying an output file is highly recommended. Since the model compaction algorithm was developed primarily as a model debugging tool, a lot of useful information is presented to the user in the terminal following the (attempted) model compaction. If the source model is successfully compacted you will still get some information that might help debug any issues in your source model, but any errors are highlighted in the Model Compaction Report at the end of the terminal output. Also as above, taking the flattened model produced here and putting it through some of the other tools might help locate issues in your model(s).