CellML 1.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 1.0 and 1.1 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¶

myokit.formats.cellml.v1.is_valid_identifier(name)¶

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

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

contains only alphanumeric characters (from the basic latin set) or underscores
contains at least one letter
does not begin with a numerical character.

The rules for 1.0 are slightly more lenient, and allow silly things like 1e2, 123 or _123 as identifiers. Because this creates issues distinguishing identifiers from numbers, Myokit always follows the 1.1 rule, even for 1.0 documents.

class myokit.formats.cellml.v1.Model(name, version='1.0')¶

Represents a CellML 1.0 or 1.1 model.

Support notes for 1.0 and 1.1:

Units with offsets are not supported, including the base units “celsius”.
Defining new base units is not supported.
Reactions are not supported.
Models that take derivatives with respect to more than one variable are not supported.
Models written as a DAE (e.g. 1 + x = 2 + y) are not supported.
cmeta:id support is limited to models, components, and variables.

Support notes for 1.1:

The new feature of using variables in initial_value attributes is not supported.
Imports (CellML 1.1) are not supported.

Support notes for 1.0:

The stricter 1.1 rule for identifiers is used for both CellML 1.0 and 1.1: a valid identifier not start with a number, and must contain at least one letter.

Arguments:

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

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.

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

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

element_with_cmeta_id(cmeta_id)¶: Returns the model, component, or variable with the given cmeta_id or raises a KeyError if no such element is found.

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.

free_variable()¶: Returns the free variable set with set_free_variable().

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

Creates a CellML Model from a myokit.Model.

The CellML version to use can be set with version, which must be either “1.0” or “1.1”.

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

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

set_free_variable(variable)¶: Tells this model which variable to regard as the free variable (with respect to which derivatives are taken).

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

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

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

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

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

add_units(name, myokit_unit)¶

Add a component-level units definition to this component.

Arguments:

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

add_variable(name, units, public_interface='none', private_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.
public_interface: The variable’s public interface.
private_interface: The variable’s private interface.

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

find_units(name)¶

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

Searches first in this component, then in its 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 component, then in its 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.

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.

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

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

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

class myokit.formats.cellml.v1.Variable(component, name, units, public_interface='none', private_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 component.
public_interface: The variable’s public interface.
private_interface: The variable’s private interface.

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

initial_value()¶: Returns this variable’s initial value, or None if it is not set.

is_free()¶

Checks if this variable has been marked as the free variable.

See Model.set_free_variable().

is_local()¶: Checks if this variable defines its own value.

is_state()¶: Checks if this variable has been marked as a state variable.

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

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

private_interface()¶: Returns this variable’s private interface.

public_interface()¶: Returns this variable’s public interface.

rhs()¶: Returns this variable’s right-hand side.

rhs_or_initial_value()¶: For non-states, returns this variable’s RHS or a myokit.Number representing the initial value if no RHS is set. For states always returns the RHS.

set_initial_value(value)¶: Sets this variable’s intial value (must be a number or None).

set_is_state(state)¶: Set whether this variable is a state variable or not.

set_rhs(rhs)¶

Sets a right-hand side expression for this variable.

The given rhs must be a myokit.Expression tree where any myokit.Name objects have a CellML Variable as their value.

source()¶

If this Variable has an “in” interface and is connected to another variable, this method returns that variable.

If not, it returns None.

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

value_source()¶

Returns the Variable that this variable derives its value from.

If the variable has a defining equation or an initial value, this will return the variable itself. If it is connected to another variable, it will follow the chain of dependencies until a variable with an equation or value is found.

class myokit.formats.cellml.v1.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.v1.AnnotatableElement(model)¶

Represents a CellML 1.0 or 1.1 element that can have a cmeta:id.

Each AnnotatableElement also has a public dict meta that can be used to story key:value (string:string) pairs, for storing meta data.

cmeta_id()¶: Returns this element’s cmeta:id if set, or None otherwise.

set_cmeta_id(cmeta_id)¶: Sets this element’s cmeta id (must be a non-empty string or None).

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

class myokit.formats.cellml.v1.UnitsError(message)¶: Raised when unsupported unit features are used.

class myokit.formats.cellml.v1.UnsupportedBaseUnitsError(units)¶: Raised when unsupported base units are used.

class myokit.formats.cellml.v1.UnsupportedUnitOffsetError¶: Raised when units with non-zero offsets are used.

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

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

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

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

CellML Parsing¶

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

Parses a CellML 1.0 or 1.1 model at the given path and returns a myokit.formats.cellml.v1.Model.

Raises a CellMLParsingError if anything goes wrong.

For notes about CellML 1.0/1.1 support, see myokit.formats.cellml.v1.Model.

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

Parses a CellML 1.0 or 1.1 model from the given string and returns a myokit.formats.cellml.v1.Model.

Raises a CellMLParsingError if anything goes wrong.

For notes about CellML 1.0/1.1 support, see myokit.formats.cellml.v1.Model.

class myokit.formats.cellml.v1.CellMLParser¶

Parses CellML 1.0 and 1.1 documents, and performs (partial) validation of a CellML document.

For notes about CellML 1.0/1.1 support, see myokit.formats.cellml.v1.Model.

flatten(element)¶: Converts an element tree to a plain text string.

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.v1.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.v1.write_file(path, model)¶: Writes a CellML 1.0 or 1.1 model to the given path.

myokit.formats.cellml.v1.write_string(model)¶: Writes a CellML 1.0 or 1.1 model to a string and returns it.

class myokit.formats.cellml.v1.CellMLWriter¶

Writes CellML 1.0 or 1.1 documents.

write(model)¶

Takes a myokit.formats.cellml.v1.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.v1.Model as input, and writes it to the given path.

See write() for details.

write_string(model)¶

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

See write() for details.

Myokit :: API and User Guide

Search

CellML 1.0 API¶

CellML Model API¶

CellML Parsing¶

CellML Writing¶