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¶
- 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.is_integer_string(text)¶
Tests if the given
text
is a valid CellML 2.0 integer string.
- myokit.formats.cellml.v2.is_basic_real_number_string(text)¶
Tests if the given
text
is a valid CellML 2.0 basic real number string.
- myokit.formats.cellml.v2.is_real_number_string(text)¶
Tests if the given
text
is a valid CellML 2.0 basic real number string.
- 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 not supported.Defining new base units is not supported.
All equations must be of the form
x = ...
ordx/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
andvariable_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.
- 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 givenname
.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 amyokit.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.
- 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
andunits
.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.
- 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
.
- 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.
- 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 amyokit.Equation
where anymyokit.Name
objects have a CellMLVariable
from this variable’s model as their value.
- set_initial_value(value)¶
Sets this variable’s intial value (must be a number or
None
).
- 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()
orComponent.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 aUnits
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 CellMLunit
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
orcm**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
orComponent
to use when looking upunits
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.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 givenpath
.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.