SBML API

In addition to the SBML importer, Myokit contains an API to represent SBML models, along with methods to read SBML documents. These methods are used under the hood by the importer.

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

SBML Model API

class myokit.formats.sbml.Compartment(model, sid)

Represents a compartment in SBML; to create a compartment use model.add_compartment().

A compartment acts as a Quantity, where the value represents the compartment’s size.

Arguments:

model

The myokit.formats.sbml.Model this compartment is in.

sid

This compartment’s SId.

initial_value()
Returns a myokit.Expression for this quantity’s initial value,

or None if not set.

is_rate()

Returns True if this quantity’s value is defined through a rate, else False.

set_initial_value(value)

Sets a myokit.Expression for this quantity’s initial value.

set_size_units(units)

Sets the myokit.Unit for this compartment’s size.

set_spatial_dimensions(dimensions)

Sets the dimensionality of this compartment’s size (usually 1, 2, or 3); this is used to determine the units for the compartment size in the case that they are not explicitly set.

set_value(value, is_rate=False)

Sets a myokit.Expression for this quantity’s value.

Arguments:

value

An expression. The values of any myokit.Name objects in the expression must be either subclasses of myokit.formats.sbml.api.Quantity or of myokit.formats.sbml.api.CSymbolVariable.

rate

Set to True if the expression gives the rate of change of this variable.

sid()

Returns this compartment’s sid.

size_units()

Returns the units of this compartment’s size.

If not set explicitly, the units will be retrieved from the model. If not set there either, units of dimensionless are returned.

spatial_dimensions()

Returns this compartment’s spatial dimensions, or None if not set.

value()

Returns a myokit.Expression for this quantity’s value, or None if not set.

class myokit.formats.sbml.CSymbolVariable(definition_url)

Represents a CSymbol that can appear in SBML expressions, but which has a predetermind value and/or meaning, e.g. “time”.

definition_url()

Returns the definitionUrl for this CSymbolVariable.

class myokit.formats.sbml.Model(name=None)

Represents a model in SBML.

Arguments:

name

A user-friendly name for this model.

add_compartment(sid)

Adds a myokit.formats.sbml.Compartment to this model.

add_parameter(sid, is_constant=True)

Adds a myokit.formats.sbml.Parameter to this model.

add_reaction(sid)

Adds a myokit.formats.sbml.Reaction to this model.

add_species(compartment, sid, is_amount=False, is_constant=False, is_boundary=False)

Adds a myokit.formats.sbml.Species to this model (located in the given compartment).

add_unit(unitsid, unit)

Adds a user unit with the given unitsid and myokit unit.

add_unit_if_possible(unit)

Adds a unit to the model if it’s not already present or in the set of base units, and returns the unit’s name.

area_units()

Returns the default compartment size units for 2-dimensional compartments, or dimensionless if not set.

assignable(sid)

Returns the Compartment, Species, SpeciesReference, or Parameter referenced by the given SId.

assignable_or_csymbol(identifier)

Like assignable(), but will also return a CSymbolVariable if the given identifier is a known CSymbol definitionUrl.

base_unit(unitsid)

Returns an SBML base unit, raises an SBMLError if not supported.

compartment(sid)

Returns the compartment with the given sid.

compartments()

Returns a list of all compartments in this model.

conversion_factor()

Returns the Parameter acting as global species conversion factor, or None if not set, see Species.conversion_factor().

extent_units()

Returns the default extent units in this model, or dimensionless if not set.

static from_myokit_model(model: Model) → Model

Creates an SBML model from a myokit.Model.

has_units() → bool

Returns True if this model has any units defined.

length_units()

Returns the default compartment size units for 1-dimensional compartments, or dimensionless if not set.

myokit_model()

Converts this SBML model to a myokit.Model.

SBML IDs are used for naming components and variables. If an ID starts with an underscore, the myokit name will be converted to underscore<name>.

Compartments defined by the SBML file are mapped to Myokit Components.

name()

Returns this model’s name.

notes()

Returns a string of notes (if set), or None.

parameter(sid)

Returns the Parameter with the given id.

parameters()

Returns a list of all parameters in this model.

reaction(sid)

Returns the Reaction with the given id.

reactions()

Returns a list of all reactions in this model.

set_area_units(units)

Sets the default compartment size units for 2-dimensional compartments.

set_conversion_factor(factor)

Sets a Parameter as global conversion factor for species, see Species.conversion_factor().

set_extent_units(units)

Sets the default units for “reaction extent”, i.e. for the kinetic law equations in reactions.

set_length_units(units)

Sets the default compartment size units for 1-dimensional compartments.

set_notes(notes=None)

Sets an optional notes string for this model.

set_substance_units(units)

Sets the default units for reaction amounts (not concentrations).

set_time_units(units)

Sets the time units used throughout the model.

set_volume_units(units)

Sets the default compartment size units for 3-dimensional compartments.

species(sid)

Returns the species with the given id.

species_list()

returns a list of all species in this model.

substance_units()

Returns the default units for reaction amounts (not concentrations), or dimensionless if not set.

time()

Returns the CSymbolVariable representing time in this model.

time_units()

Returns the default units for time, or dimensionless if not set.

unit(unitsid)

Returns a user-defined or predefined unit.

units() → Dict[str, Unit]

Returns a dict mapping sid to unit for all units in this model.

volume_units()

Returns the default compartment size units for 3-dimensional compartments, or dimensionless if not set.

class myokit.formats.sbml.ModifierSpeciesReference(species, sid=None)

Represents a reference to a modifier species in an SBML reaction.

sid()

Returns this species reference’s SId, or None if not set.

species()

Returns the species this object refers to.

class myokit.formats.sbml.Parameter(model, sid, is_constant=True)

Represents a parameter in SBML; to create a parameter use model.add_parameter().

Arguments:

model

The model this parameter is in.

sid

This parameter’s SId.

initial_value()
Returns a myokit.Expression for this quantity’s initial value,

or None if not set.

is_constant()

Returns True if this parameter is constant, else False.

is_literal()

Returns True if this parameter is a literal value.

is_rate()

Returns True if this quantity’s value is defined through a rate, else False.

set_initial_value(value)

Sets a myokit.Expression for this quantity’s initial value.

set_units(units)

Sets this parameters units to the given units.

set_value(value, is_rate=False)

Sets a myokit.Expression for this quantity’s value.

Arguments:

value

An expression. The values of any myokit.Name objects in the expression must be either subclasses of myokit.formats.sbml.api.Quantity or of myokit.formats.sbml.api.CSymbolVariable.

rate

Set to True if the expression gives the rate of change of this variable.

sid()

Returns this parameter’s sid.

units()

Returns the units this parameter is in, or None if not set.

value()

Returns a myokit.Expression for this quantity’s value, or None if not set.

class myokit.formats.sbml.Quantity

Base class for anything that has a numerical value in an SBML model, and can be set by rules, reactions, or initial assignments.

initial_value()
Returns a myokit.Expression for this quantity’s initial value,

or None if not set.

is_rate()

Returns True if this quantity’s value is defined through a rate, else False.

set_initial_value(value)

Sets a myokit.Expression for this quantity’s initial value.

set_value(value, is_rate=False)

Sets a myokit.Expression for this quantity’s value.

Arguments:

value

An expression. The values of any myokit.Name objects in the expression must be either subclasses of myokit.formats.sbml.api.Quantity or of myokit.formats.sbml.api.CSymbolVariable.

rate

Set to True if the expression gives the rate of change of this variable.

value()

Returns a myokit.Expression for this quantity’s value, or None if not set.

class myokit.formats.sbml.Reaction(model, sid)

Represents an SBML reaction; to create a reaction use Model.add_reaction().

Arguments:

model

The model this reaction is in.

sid

This reaction’s SId.

add_modifier(species, sid=None)

Adds a modifier to this reaction and returns the created object.

add_product(species, sid=None)

Adds a reaction product to this reaction and returns the created object.

add_reactant(species, sid=None)

Adds a reactant to this reaction and returns the created object.

kinetic_law()

Returns the kinetic law set for this reaction, or None if not set.

modifiers()

Returns the list of modifiers used by this reaction (as SpeciesReference objects).

products()

Returns the list of products created by this reaction (as SpeciesReference objects).

reactants()

Returns the list of reactions used by this reaction (as SpeciesReference objects).

set_kinetic_law(expression)

Sets this reaction’s kinetic law (as a myokit.Expression).

sid()

Returns this reaction’s sid.

species(sid)

Finds and returns a Species used in this reaction.

class myokit.formats.sbml.SBMLError

Raised if something goes wrong when working with an SBML model.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class myokit.formats.sbml.Species(compartment, sid, is_amount, is_constant, is_boundary)

Represents an SBML species; to create a species use Compartment.add_species().

Arguments:

compartment

The Compartment that this species is in.

sid

This species’s SId.

is_amount

Whether this species value is represented as an amount (if false, it is represented as a concentration, which depends on the size of the compartment it is in).

is_constant

Whether or not this species is constant.

is_boundary

Whether or not this species is at the boundary of a reaction.

compartment()

Returns the Compartment that this species is in.

conversion_factor()

Returns the Parameter acting as conversion factor for this species, or the model default if not set (and None if that isn’t set either).

When calculating the rate of change of the species, multiplying by this factor converts from the species units to “number of reaction events”.

initial_value()

Returns a myokit.Expression (or None) for this species’ initial value, and a boolean indicating whether initial value is provided in amount (True) or in concentration (False).

is_amount()

Returns True only if this species is defined as an amount (not a concentration).

is_boundary()

Returns True only if this species is at a reaction boundary.

is_constant()

Returns True only if this species is constant.

is_rate()

Returns True if this quantity’s value is defined through a rate, else False.

set_conversion_factor(factor)

Sets a Parameter as conversion factor for this species, see conversion_factor().

set_initial_value(value, in_amount=None)

Sets a myokit.Expression for this species’ initial value.

in_amount is a boolean that indicates whether the initial value is measured in amount (True) or concentration (False). If set to None value is treated to have the same units as the species.

set_substance_units(units)

Sets the units this species amount (not concentration) is in.

set_value(value, is_rate=False)

Sets a myokit.Expression for this quantity’s value.

Arguments:

value

An expression. The values of any myokit.Name objects in the expression must be either subclasses of myokit.formats.sbml.api.Quantity or of myokit.formats.sbml.api.CSymbolVariable.

rate

Set to True if the expression gives the rate of change of this variable.

sid()

Returns this species’s sid.

substance_units()

Returns the units an amount of this species (not a concentration) is in, or the model default if not set.

value()

Returns a myokit.Expression for this quantity’s value, or None if not set.

class myokit.formats.sbml.SpeciesReference(species, sid=None)

Represents a reference to a reactant or product species in an SBML reaction.

A species reference acts as a Quantity, where the value represents the species’ stoichiometry.

initial_value()
Returns a myokit.Expression for this quantity’s initial value,

or None if not set.

is_rate()

Returns True if this quantity’s value is defined through a rate, else False.

set_initial_value(value)

Sets a myokit.Expression for this quantity’s initial value.

set_value(value, is_rate=False)

Sets a myokit.Expression for this quantity’s value.

Arguments:

value

An expression. The values of any myokit.Name objects in the expression must be either subclasses of myokit.formats.sbml.api.Quantity or of myokit.formats.sbml.api.CSymbolVariable.

rate

Set to True if the expression gives the rate of change of this variable.

sid()

Returns this species reference’s SId, or None if not set.

species()

Returns the species this object refers to.

value()

Returns a myokit.Expression for this quantity’s value, or None if not set.

SBML Parsing

class myokit.formats.sbml.SBMLParser

Parses SBML models, creating an SBML Model structure that can be converted to a myokit.Model object.

Support notes:

  • SBML older than Level 2 version 1 is unlikely to work.

  • Algebraic rules are not supported.

  • Constraints are not supported.

  • Events are not supported.

  • Function definitions are not supported.

  • Local parameters in reactions are not supported.

  • Units “celsius” are not supported.

  • Since SBML does not support units in equations, variable units will be set, but RHS units will not.

parse(element)

Parses an SBML document rooted in the given ElementTree element and returns a myokit.Model.

parse_file(path)

Parses the SBML file at path and returns a myokit.Model.

parse_string(text)

Parses the SBML XML in the string text and returns a myokit.Model.

class myokit.formats.sbml.SBMLParsingError(message, element=None)

Thrown if an error occurs when parsing SBML.

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

SBML Writing

myokit.formats.sbml.write_file(path: str, model: Model)

Writes an SBML model to the given path.

myokit.formats.sbml.write_string(model: Model) → str

Writes an SBML model to a string and returns it.

class myokit.formats.sbml.SBMLWriter

Writes SBML documents