CellML 2.0 API¶

In addition to the CellML importers and exporters, Myokit contains an API to represent CellML models, along with methods to read and write CellML 2.0 documents. These methods are used under the hood by the importers and exporters.

In most cases, it’s easier to avoid these methods and use the CellML Importer and Exporter instead.

CellML Model API¶

class myokit.formats.cellml.v2.Model(name, version='2.0')¶

Represents a CellML 2.0 model.

Support notes:

Imports are not supported.
Reset rules are not supported.
Using variables in initial_value attributes is supported, as long as they have constant values.
Defining new base units is not supported.
All equations must be of the form x = ... or dx/dt = ....
Models that take derivatives with respect to more than one variable are not supported.

Arguments:

name: A valid CellML identifier string.
version: A string representing the CellML version this model is in (must be ‘2.0’).

add_component(name)¶: Adds an empty component with the given name.

add_connection(variable_1, variable_2)¶: Adds a connection between variable_1 and variable_2.

add_units(name, myokit_unit)¶

Add a model-level units definition to this model.

Arguments:

name: A valid CellML identifier to use as the name
myokit_unit: A myokit.Unit object.

clone()¶: Returns a copy of this model.

component(name)¶: Returns the Component with the given name.

components()¶: Returns an iterator over this model’s components.

connections()¶: Returns an iterator over all connections in this model (as variable tuples).

find_units(name)¶

Looks up and returns a Units object with the given name.

Searches first in this model, then in the list of predefined units.

Raises a CellMLError is no unit is found.

find_units_name(myokit_unit)¶

Attempts to find a string name for the given myokit.Unit.

Searches first in this model, then in the list of predefined units. If multiple units definitions have the same myokit.Unit, the last added name is returned.

Raises a CellMLError is no appropriate unit is found.

static from_myokit_model(model, version='2.0')¶

Creates a CellML Model from a myokit.Model.

The CellML version to use can be set with version (which must be “2.0”).

myokit_model()¶: Returns this model’s myokit.Model equivalent.

name()¶: Returns this model’s name.

set_variable_of_integration(variable)¶: Marks a variable as this model’s variable of integration.

units()¶: Returns an iterator over the Units objects in this model.

validate()¶: Validates this model, raising a CellMLError if an errors are found.

variable_of_integration()¶: Returns the model’s variable of integration, if any.

version()¶: Returns the CellML version this model is in.

class myokit.formats.cellml.v2.Component(model, name)¶

Represents a model component; should not be created directly but only via Model.add_component().

add_variable(name, units, interface='none')¶

Adds a variable with the given name and units.

Arguments

name: A valid CellML identifier (string).
units: The name of a units definition known to this component or its parent model.
interface: The variable’s interface.

children()¶: Returns an iterator over any encapsulated child components.

has_children()¶: Checks if this component has any encapsulated child components.

model()¶: Return this component’s model.

name()¶: Returns this component’s name.

parent()¶: Returns this component’s parent component (or None).

set_parent(parent)¶: Sets this component as the encapsulated child of the component parent.

variable(name)¶: Returns the variable with the given name.

variables()¶: Returns an iterator over this component’s variables.

class myokit.formats.cellml.v2.Variable(component, name, units, interface='none')¶

Represents a model variable, should not be created directly but only via Component.add_variable().

Arguments

component: This variable’s parent Component.
name: This variable’s name (a valid CellML identifier string).
units: The string name of a units object known to this variable’s model.
interface: The variable’s interface.

component()¶: Returns this variable’s component.

connected_variables()¶: Returns an list of all variables connected to this one.

equation()¶

Returns the equation for this variable (or its connected variable set), in the correct units.

Note that this method is primarily intended to extract equations from a CellML model, and care must be taken when using it to manipulate a CellML model. Specifically:

If the equation was not set on this variable, but on a variable in the connected variable set, the returned equation may refer to non-local variables.
Similarly, if unit conversion is required, the conversion factor may have a unit not defined in this model.

As a result, calling set_equation() with the value returned by equation() is not always possible.

equation_variable()¶: Returns the variable from the connected variable set that provides an equation for this set (if any).

has_equation()¶: Returns True if an equation is defined in this variable’s connected variable set.

has_initial_value()¶: Returns True if an initial value is defined in this variable’s connected variable set.

has_rhs()¶: Returns True if an equation or initial value is defined in this variable’s connected variable set.

initial_value()¶

Returns the initial value for this variable (or its connected variable set), in the correct units.

The returned value is a myokit.Expression.

Note that, like equation(), this method is primarily intended to extract initial values from a CellML model. As a result, the returned value may be a referenced to a variable in another component, and may contain a unit conversion multiplication.

initial_value_variable()¶: Returns the variable from the connected variable set that provides an initial value for this set (if any).

interface()¶: Returns this variable’s interface (as a string).

is_free()¶: Returns True if this variable doesn’t define a value anywhere in its connected variable set.

is_local()¶: Returns True if this variable provides its own value, i.e. if it is the variable defining an equation (or an initial value if no equation is set) within its connected variable set.

is_state()¶: Returns True if this variable is a state variable (i.e. if its definition anywhere in the connected variable set is through a differential equation).

model()¶: Return this variable’s model.

name()¶: Returns this variable’s name.

rhs()¶

Returns an RHS for this variable, in the appropriate units.

The RHS will be derived either from a defining equation or, if no equation is found in the connected variable set, from the initial value.

If neither is found, None will be returned.

Note that the caveats applying to equation() and initial_value() also apply here.

rhs_variable()¶: Returns the variable that defines the RHS for this variable’s connected variable set (or None).

set_equation(equation)¶

Sets a defining equation for this variable.

The given equation must be a myokit.Equation where any myokit.Name objects have a CellML Variable from this variable’s model as their value.

set_initial_value(value)¶

Sets this variable’s intial value: must be a number, a local variable, or None.

Numbers can be specified as number types, strings, or myokit.Number objects (wrapped in prefix plus or minus operators). If a myokit.Number is passed in, it should have the same units as this variable. Variables can be passed in as strings or myokit.Name objects.

units()¶: Returns the units this variable is in (as a Units object).

class myokit.formats.cellml.v2.Units(name, myokit_unit, predefined=False)¶

Represents a CellML units definition; should not be created directly but only via Model.add_units() or Component.add_units().

Arguments:

name: A string name, used to refer to these units in the model.
myokit_unit: A myokit.Unit representing these units.
predefined: Set to True when creating an object for a predefined name. This is only used internally.

classmethod find_units(name)¶

Searches for a predefined unit with the given name and returns a Units object representing it.

If no such unit is found a CellMLError is raised.

classmethod find_units_name(myokit_unit)¶

Attempts to find a string name for the given myokit.Unit.

Raises a CellMLError is no appropriate unit is found.

myokit_unit()¶: Returns the Myokit.Unit equivalent for this units definition.

name()¶: Returns the string name for this units definition.

classmethod parse_unit_row(units, prefix=None, exponent=None, multiplier=None, context=None)¶

Creates a myokit.Unit using the information found in a single CellML unit element.

Arguments

units: The name of the units to start from.
prefix: An optional argument that can be either a string from one of the predefined units prefixes, or an integer. If an integer is given the unit is scaled by 10**prefix. Used to make e.g. cm.
exponent: An optional exponent (power) for this unit, used to make e.g. m**2 or cm**2.
multiplier: An optional multiplier for this unit, used to make e.g. inches. Note that exponentiation affects prefixes, but not multipliers.
context: An optional Model or Component to use when looking up units names. If not given, only the SI units will be supported.

classmethod si_unit_names()¶: Returns an iterator over the predefined unit names.

class myokit.formats.cellml.v2.AnnotatableElement¶: Represents a CellML 2.0 element that can be annotated (using a public dict meta that stores key:value pairs).

class myokit.formats.cellml.v2.CellMLError(message)¶: Raised when an invalid CellML 2.0 model is created or detected, or when a model uses CellML features that Myokit does not support.

myokit.formats.cellml.v2.is_identifier(name)¶

Tests if the given name is a valid CellML 2.0 identifier.

This method returns True if (and only if) the identifier

begins with a letter (from the basic latin set)
only contains letters, numbers, and underscores.

myokit.formats.cellml.v2.clean_identifier(name)¶

Checks if name is a valid CellML 2.0 identifier and if not attempts to make it into one.

Raises a ValueError if it can’t create a valid identifier.

myokit.formats.cellml.v2.create_unit_name(unit)¶: Creates an almost readable name for a Myokit unit.

CellML Parsing¶

myokit.formats.cellml.v2.parse_file(path)¶

Parses a CellML 2.0 model at the given path and returns a myokit.formats.cellml.v2.Model.

Raises a CellMLParsingError if anything goes wrong.

For notes about CellML 2.0 support, see myokit.formats.cellml.v2.Model.

myokit.formats.cellml.v2.parse_string(text)¶

Parses a CellML 2.0 model from the given string and returns a myokit.formats.cellml.v2.Model.

Raises a CellMLParsingError if anything goes wrong.

For notes about CellML 2.0 support, see myokit.formats.cellml.v2.Model.

class myokit.formats.cellml.v2.CellMLParser¶

Parses CellML 2.0 documents, and performs (partial) validation.

For notes about CellML 2.0 support, see myokit.formats.cellml.v2.Model.

parse(root)¶: Parses and validates a CellML document rooted in the given elementtree element.

parse_file(path)¶: Parses and validates the CellML file at path and returns a CellML Model.

parse_string(text)¶: Parses and validates the CellML XML in the string text and returns a CellML model.

class myokit.formats.cellml.v2.CellMLParsingError(message, element=None)¶

Raised if an error occurs during CellML parsing.

The argument element can be used to pass in an element that caused the error.

CellML Writing¶

myokit.formats.cellml.v2.write_file(path, model)¶: Writes a CellML 2.0 model to the given path.

myokit.formats.cellml.v2.write_string(model)¶: Writes a CellML 2.0 model to a string and returns it.

class myokit.formats.cellml.v2.CellMLWriter¶

Writes CellML 2.0 documents.

write(model)¶

Takes a myokit.formats.cellml.v2.Model as input, and creates an ElementTree that represents it.

If the model contains any variables that have an oxmeta meta data property, this will be annotated with RDF tags suitable for use with the Cardiac Electrophysiology Web Lab.

write_file(path, model)¶

Takes a myokit.formats.cellml.v2.Model as input, and writes it to the given path.

See write() for details.

write_string(model)¶

Takes a myokit.formats.cellml.v2.Model as input, and converts it to an XML string.

See write() for details.

Myokit :: API and User Guide

Search

CellML 2.0 API¶

CellML Model API¶

CellML Parsing¶

CellML Writing¶