CellML

Methods to import and export CellML 1.0, 1.1, and 2.0 are provided. For further CellML functions, see CellML 1 API and CellML 2 API.

Importing

Myokit can import most models listed in the CellML electrophysiology repository. (Although take care, some of the CellML versions of models are known to have issues. This is usually mentioned in their documentation).

Adapting an embedded stimulus current

Most CellML models contain a hard-coded stimulus current. Myokit will try to detect these stimulus currents and replace them by an appropriate myokit.Protocol. However, if this fails, the stimulus will need to be converted by hand, which is described below.

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. You should find a stimulus current implemented as pace * IstimAmplitude. This has automatically been added when you imported the model.
4. If you run the code, you should see an action potential!

Now let’s import the model in code, without automatic conversion:

1. In a script, load the Myokit formats module (import myokit.formats) and create a CellMLImporter: i = myokit.formats.importer('cellml').
2. Import the model, using i.model('beeler_reuter_1977.cellml').
3. Have a look at the generated code. You should see the hardcoded stimulus that was present in the CellML file.
4. Run the embedded script or explorer. You should see something like this:

5. 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
   

6. Validate the model and try again. Now that the simulation engine knows where the discontinuities are, you should get the expected result:

The same procedure can be followed for any other valid model in the database. An automated version of this procedure is implemented as myokit.lib.guess.remove_embedded_protocol().

Exporting

Myokit provides an export to CellML 1.0, 1.1, and 2.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 can be done by passing a myokit Protocol to the exporter along with the model to export.

Imports, exporters, and expression writers

myokit.formats.cellml.importers()

Returns a dict of all importers available in this module.

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

This Importer imports a model definition from CellML.

model(path)

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

supports_model()

Returns True.

class myokit.formats.cellml.CellMLImporterError(message)

Raised if an error occurs when importing CellML.

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.

model(path, model, protocol=None, version='1.0')

Writes a CellML model to the given filename.

Arguments:

path

The path/filename to write the generated code to.

model

The model to export

protocol

If given, an attempt will be made to convert the protocol to an expression and insert it into the model before exporting. See myokit.lib.guess.add_embedded_protocol() for details.

version

The CellML version to write (1.0, 1.1, or 2.0).

post_export_info()

Optional method that returns a string containing information about this exporter, to be shown after the export is completed.

runnable(path, model, protocol=None, *args)

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.

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.

class myokit.formats.cellml.CellML1Exporter

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

model(path, model, protocol=None)

Writes a CellML model to the given filename.

Arguments:

path

The path/filename to write the generated code to.

model

The model to export

protocol

If given, an attempt will be made to convert the protocol to an expression and insert it into the model before exporting. See myokit.lib.guess.add_embedded_protocol() for details.

version

The CellML version to write (1.0, 1.1, or 2.0).

post_export_info()

Optional method that returns a string containing information about this exporter, to be shown after the export is completed.

runnable(path, model, protocol=None, *args)

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.

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.

class myokit.formats.cellml.CellML2Exporter

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

model(path, model, protocol=None)

Writes a CellML model to the given filename.

Arguments:

path

The path/filename to write the generated code to.

model

The model to export

protocol

If given, an attempt will be made to convert the protocol to an expression and insert it into the model before exporting. See myokit.lib.guess.add_embedded_protocol() for details.

version

The CellML version to write (1.0, 1.1, or 2.0).

post_export_info()

Optional method that returns a string containing information about this exporter, to be shown after the export is completed.

runnable(path, model, protocol=None, *args)

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.

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.

myokit.formats.cellml.ewriters()

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

class myokit.formats.cellml.CellMLExpressionWriter(version='1.0')

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

To use, create an expression writer, then pass in a method to set good variable names with set_lhs_function(), and a method to look up unit names with set_unit_function().

eq(eq, element=None)

Converts an equation to a string.

The optional argument element can be used to pass in an lxml.etree.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 lxml.etree.ElementTree element. If given, this element will be updated with the generated xml and nothing will be returned.

set_lhs_function(f)

Sets a naming function, will be called to get the variable name from a

myokit.Name (derivatives will be handled separately).

The argument f should be a function that takes a myokit.Name as input and returns a string.

set_mode(presentation=False)

This expression writer only supports content MathML.

set_time_variable(time)

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

set_unit_function(f)

Sets a unit lookup function, which will be used to convert a myokit.Unit to a CellML units name.