CellML

An interface for importing CellML 1.0 and up is provided, as well as an export to CellML 1.0.

Importing

Myokit can import most models listed in the CellML electrophysiology repository.

However, most CellML models contain a hard-coded stimulus current which will cause problems for the solver. These must rewritten manually to use Myokit’s pacing system.

In the following example we show how to import the Beeler-Reuter model from the CellML database.

  1. Find and download the model file (beeler_reuter_1977.cellml).
  2. Open the GUI and select Convert > Import model from CellML.
  3. Have a look at the imported code. Apart from the messy representation of the meta-data, everything should be in order.
  4. Run the embedded script or explorer. You should see something like this:
../_images/br_cellml_bad_thumb.png
  1. To fix this, scroll down to the stimulus section. It should look like this:

    [stimulus_protocol]
    Istim = piecewise(engine.time >= IstimStart and engine.time <= ...
        in [A/m^2]
    IstimStart = 10 [ms]
    IstimEnd = 50000 [ms]
    IstimAmplitude = 0.5 [A/m^2]
    IstimPeriod = 1000 [ms]
    IstimPulseDuration = 1 [ms]
    

    Replace the piecewise statement with a formulation using the external pace variable:

    [stimulus_protocol]
    IstimAmplitude = 0.5 [A/m^2]
    level = 0 bind pace
    Istim = level * IstimAmplitude [A/m^2]
    

    Next, use the information from IstimStart, IStimPeriod and IStimPulseDuration to update the pacing protocol on the next tab:

    # Level  Start    Length   Period   Multiplier
    1.0      10.0     1.0      1000.0   0
    
  2. Validate the model and try again. Now that the simulation engine knows where the discontinuities are, you should get the expected result:

../_images/br_cellml_good_thumb.png

The same procedure can be followed for any other valid model in the database.

Model quality

Please keep in mind that the quality of available CellML models may vary. Some models are incomplete, contain errors or are not written in valid CellML. In addition, some models contain experimental features such as random variation or partial differential equations. These are not currently part of the CellML standard and are not supported by Myokit.

Limitations

CellML is built with a larger scope in mind than Myokit and includes a few oddities such as <arccsch>, which were included ” because they are reasonably straightforward to translate to computer code” (CellML 1.0 specification). Below is a list of the CellML features Myokit does not support.

CellML 1.0

Differential algebraic equations (DAEs)
Myokit has no support for DAEs, so model that contain them cannot be imported. However, these models can manually be rewritten to a form supported by Myokit.
<factorial>
The factorial operation is not common in cell models or in programming math libraries (C for example, does not include it). In addition, note that 13! > 2^32 and 21! > 2^64 so that there is only a very small subset of factorials that we can easily compute. At the time of writing, July 2015, none of the cardiac models in the CellML electrophysiology repository use this feature.
<reaction>
The <reaction> element and its children are used to specify biochemical pathways without an explicit mathematical form. Since there are plenty of tools for pathways already, Myokit does not support them. At the time of writing, July 2015, none of the models in the CellML electrophysiology repository use this feature.
<semantics>
The <semantics> element and its children can be used to specify both a meaningful set of equations and a pretty set of equations. Since Myokit has only one way of displaying equations, this is not supported. At the time of writing, July 2015, none of the models in the CellML electrophysiology repository use this feature.

CellML 1.1

<import>
The import element introduced in CellML 1.1 is currently not supported, but this may change in the future.

Optional features

Unit conversion
Myokit’s CellML import does not perform automatic unit conversion, but it will warn if inconsistent units are found.
Scripting
CellML scripting is not supported by Myokit.

Exporting

Myokit provides an export to CellML 1.0. Since Myokit separates the model from the pacing protocol, but most CellML based tools do not expect this, Myokit has an option to embed a hardcoded stimulus protocol in exported CellML files. This is enabled by default but can be disabled when exporting models via the API (see CellMLExporter).

Note that the protocol has a default duration of 2ms, making it suitable for most older models but not the more modern ones. For models that require shorter stimulus currents, adapt the CellML model by searching for a component named “stimulus” (or “stimulus_2” if that name was already taken) and changing the “duration” variable.

OpenCOR

A few notes about OpenCOR:

  1. The OpenCOR manual states that, “a model that requires a stimulus protocol should have the maximum step value of the CVODE solver set to the length of the stimulus”. Since most models have a stimulus protocol you’ll usually have to set the maximum step size on the “simulation” tab for models to work in OpenCOR.
  2. OpenCOR has been known to complain about nested piecewise functions. If these are present it seems to run anyway.

API

The standard interfaces for importing and exporting are provided:

myokit.formats.cellml.importers()

Returns a dict of all importers available in this module.

class myokit.formats.cellml.CellMLImporter(verbose=False)

This:class:Importer <myokit.formats.Importer> imports a model definition from CellML.

clear_warnings()

Clears any currently set warnings.

component(path, model)

Imports a component from the given path and adds it to the given model.

The importer may pose restraints on the used model. For example, the model may be required to contain a variable labelled “membrane_potential”. For details, check the documentation of the individual importers.

The created myokit.Component is returned. A myokit.ImportError will be raised if any errors occur.

has_warnings()

Returns True if this logger has any warnings.

info()

Returns a string containing information about this importer.

is_live()

Returns True if live logging is enabled and any logged messages are directly printed to stdout.

log(*text)

Writes text to the log. Text fragments given as separate arguments will be written to the log as separate lines.

log_flair(text)

Logs a single text fragment centered on the line, surrounded by lines of hyphens:

------------------------------------------------------------
                         Like this!
------------------------------------------------------------
log_line()

Writes a horizontal line (——) to the log.

log_warnings()

Writes all the logged warnings to the log and clears the warnings buffer.

model(path)

Reads a CellML file and returns a:class:myokit.Model.

protocol(path)

Imports a protocol from the given path.

The created myokit.Protocol is returned. A myokit.ImportError will be raised if any errors occur.

set_live(enabled=True)

When live logging is enabled, all log data will be written to stdout immediatly.

set_log_line_width(width)

Changes the line width used by this text logger.

supports_component()

Returns a bool indicating if component import is supported.

supports_model()

Returns True.

supports_protocol()

Returns a bool indicating if protocol import is supported.

text()

Returns the logged text.

warn(message)

Logs a warning to the warnings list.

warnings()

Returns an iterator over all warnings currently set

myokit.formats.cellml.exporters()

Returns a dict of all exporters available in this module.

class myokit.formats.cellml.CellMLExporter

This:class:Exporter <myokit.formats.Exporter> creates a CellML model.

clear_warnings()

Clears any currently set warnings.

custom_unit_name(unit)

Creates an almost readable name for a custom Myokit unit.

has_warnings()

Returns True if this logger has any warnings.

is_live()

Returns True if live logging is enabled and any logged messages are directly printed to stdout.

log(*text)

Writes text to the log. Text fragments given as separate arguments will be written to the log as separate lines.

log_flair(text)

Logs a single text fragment centered on the line, surrounded by lines of hyphens:

------------------------------------------------------------
                         Like this!
------------------------------------------------------------
log_line()

Writes a horizontal line (——) to the log.

log_warnings()

Writes all the logged warnings to the log and clears the warnings buffer.

model(path, model, protocol=None, add_hardcoded_pacing=True, pretty_xml=True)

Writes a CellML model to the given filename.

Arguments:

path
The path/filename to write the generated code too.
model
The model to export
protocol
This argument will be ignored: protocols are not supported by CellML.
add_hardcoded_pacing
Set this to True to add a hardcoded pacing signal to the model file. This requires the model to have a variable bound to pace.
pretty_xml
Set this to True to write the output in formatted “pretty” xml.

Notes about CellML export:

  • CellML expects a unit for every number present in the model. Since Myokit allows but does not enforce this, the resulting CellML file may only validate with unit checking disabled.
  • Files downloaded from the CellML repository typically have a pacing stimulus embedded in them, while Myokit views models and pacing protocols as separate things. To generate a model file with a simple embbeded protocol, add the optional argument add_hardcoded_pacing=True.
runnable(path, model, protocol=None)

Exports a myokit.Model and optionally a myokit.Protocol to something that can be run or compiled.

The output will be stored in the directory path. A myokit.ExportError will be raised if any errors occur.

set_live(enabled=True)

When live logging is enabled, all log data will be written to stdout immediatly.

set_log_line_width(width)

Changes the line width used by this text logger.

supports_model()

Returns True.

supports_runnable()

Returns True if this exporter supports export of a model and optional protocol to a runnable piece of code.

text()

Returns the logged text.

warn(message)

Logs a warning to the warnings list.

warnings()

Returns an iterator over all warnings currently set

myokit.formats.cellml.ewriters()

Returns a dict of all expression writers available in this module.

class myokit.formats.cellml.CellMLExpressionWriter(units)

Writes equations for variables using CellML’s version of MathML.

Differences from normal MathML:

  1. Only content MathML is supported
  2. Variable names are always written as unames.
  3. Every number defines an attribute cellml:units

The expression writer requires a single argument units. This should be a mapping of Myokit units to string unit names.

eq(eq, element=None)

Converts an equation to a string.

The optional argument element can be used to pass in an ElementTree element. If given, this element will be updated with the generated xml and nothing will be returned.

ex(e, element=None)

Converts an expression to a string.

The optional argument element can be used to pass in an ElementTree element. If given, this element will be updated with the generated xml and nothing will be returned.

set_element_tree_class(et)

By default this ExpressionWriter uses the xml.etree.cElementTree module. This method can be used to change this behaviour by passing in a reference to a different implementation.

set_lhs_function(f)

This expression writer always uses unames, setting an LHS function is not supported.

set_mode(presentation=False)

This expression writer only supports content MathML, so this method does nothing.

set_time_variable(time)

Sets the time variable to use for this expression writer’s derivatives.

class myokit.formats.cellml.CellMLError(message)

Raised when a fatal error occurs when importing CellML