Variable

class myokit.Variable(parent, name)

Represents a variable.

Each variable has a single defining equation. For state variables, this equation has a derivative on the left-hand side (lhs), for all other variables the lhs of the defining equation is simply the variable’s name.

Variables can be made into state variables using Variable.promote().

Variables can be made to represent an externally defined variable using Variable.set_binding(). In this case, the right hand side set for a variable will be used as an alternative in situations where the external input is not available.

Meta-data properties can be accessed via the property meta, for example model.meta['key']= 'value'.

add_variable(name)

Adds a child variable with the given name to this VarOwner.

add_variable_allow_renaming(name)

Attempts to add a child variable with the given name to this VarOwner, but uses a different name if this causes any conflicts.

The new variable’s name will be modified by appending _1, _2, etc. until the conflict is resolved.

This method can be used when symbolically manipulating a model in situations where the exact names are unimportant.

Returns the newly created variable.

binding()

Returns this variable’s binding label or None if no binding is set.

can_add_variable(name)

Returns True if a variable can be added to this VarOwner under the given name.

This method is automatically called by add_variable() and move_variable(), there is no need to call it before using these methods.

code()

Returns this object in mmt syntax.

count_equations(const=None, inter=None, state=None, bound=None, deep=False)

Returns the number of equations matching the given criteria. See equations() for an explanation of the arguments.

count_variables(const=None, inter=None, state=None, bound=None, deep=False)

Returns the number of variables matching the given criteria. See variables() for an explanation of the arguments.

demote()

Turns a state variable into an intermediary variable.

This will reset the validation status of the model this variable belongs to.

eq()

Returns this variable’s defining equation.

For state variables this will be an equation for the variable’s derivative. For ordinary variables the equation for the variable’s value is returned.

equations(const=None, inter=None, state=None, bound=None, deep=False)

Creates and returns a filtered iterator over the equations of this object’s variables.

The returned values can be filtered using the following arguments:

const=True|False|None

Set to True to return only constants’ equations. False to exclude all constants and any other value to ignore this check.

For a definition of “constant variable” see variables().

inter=True|False|None

Set to True to return only intermediary variables’ equations, False to exclude all intermediary variables and any other value to ignore this check.

For a definition of “intermediary variable” see variables().

state=True|False|None
Set to True to return only state variables’ equations, False to exclude all state variables and any other value to ignore this check.
bound=True|False|None
Set to True to return only bound variables’ equations, False to exclude all bound variables and any other value to ignore this check.
deep=True|False (by default it’s False)
Set to True to include the equations of nested variables meeting all other criteria.
eval()

Evaluates this variable’s defining equation and returns the result.

get(name, class_filter=None)

Searches for a variable with the given qname and returns it.

To return only objects of a certain class, pass it in as class_filter.

The qnames are specified relative to the VarOwner. For example, in a model with a component ina and a variable ina.h we expect the following results

>>> import myokit
... m = myokit.load_model('example')
... c = m.get('ina')        # Retrieves the component <ina>
... h = c.get('h')          # Retrieves the variable <ina.h>
... x = c.get('ina.h')      # Searches for <ina.ina.h>: KeyError!
has_ancestor(obj)

Returns True if the given object obj is an ancestor of this ModelPart.

has_equations(const=None, inter=None, state=None, bound=None, deep=False)

Returns True if there are any equations that can be returned by calling :meth:equations with the same arguments.

has_variable(name)

Returns True if the given name corresponds to a variable in this object. Accepts both single names x and qualified names x.y as input.

This function performs the same search as variable, so in most cases it will be more efficient to call variable() in a try-catch block rather than checking for existence explicitly.

has_variables(const=None, inter=None, state=None, bound=None, deep=False)

Returns True if there are any variables that can be returned by calling :meth:variables with the same arguments.

indice()

For state variables, this will return their index in the state vector. For all other variables, this will raise an exception.

is_ancestor(obj)

Returns True if this object is an ancestor of the given ModelPart` object.

is_bound()

Returns True if a binding label has been added to this variable.

is_constant()

Returns True if this variable is constant.

Myokit doesn’t discern between mathematical and physical constants, parameters etc. Anything that doesn’t change during a simulation is termed a constant. Note that this specifically excludes variables bound to external inputs.

is_intermediary()

Returns True if this variable is an intermediary variable, i.e. not a constant or a state variable (and not bound to an external variable).

is_labelled()

Returns True if a label has been added to this variable.

is_literal()

Returns True if this variable’s expression contains only literal values.

is_nested()

Returns True if this variable’s parent is another variable.

is_referenced()

Returns True if other variables reference this variable’s lhs. For states, this means it only returns True if other variables depend on this variable’s derivative.

is_state()

Returns True if this variable is a state variable.

label()

Returns this variable’s label or None if no label is set.

lhs()

Returns the left-hand side of the equation defining this variable.

For state variables this will be a myokit.Derivative, for all others this should be a myokit.Name.

model()

Returns the model this object belongs to (if set).

move_variable(variable, new_parent, new_name=None)

Moves the given variable to another VarOwner new_parent. In addition, this method can be used to rename variables (either with or without moving them).

name()

Returns this object’s name.

parent(kind=None)

Returns this object’s parent.

If the optional variable kind is set, the method will scan until an instance of the requested type is found.

promote(state_value=0)

Turns this variable into a state variable with a current state value given by state_value.

This will reset the validation status of the model this variable belongs to.

pyfunc(use_numpy=True, arguments=False)

Returns a python function that evaluates this variable as a function of the state variables it depends on.

The argument names used by the returned function will be the variables’ unames, ordered alphabetically.

If the function runs in “numpy-mode”, which is enabled by default, the vector ready versions of log, exp etc are used and piecewise statements are evaluated using an array ready piecewise function. To disable this functionality, set use_numpy=False.

To obtain more information about the arguments in the created function handle, set the optional argument arguments to True. With this setting, the function will return a tuple (handle, vars) where handle is the function handle and vars is a list of myokit.LhsExpression objects in the same order as the function arguments.

qname(hide=None)

Returns this object’s fully qualified name. That is, an object named y with a parent named x will return the string x.y. If y has a child z its qname will be x.y.z.

If the optional argument hide is set to this object’s parent the parent qualifier will be omitted.

refs_by(state_refs=False)

Returns an iterator over the set of Variables that refer to this variable in their defining equation.

For state variables, there are two things to take into account:

  1. By default, only references to this variable’s defining LhsExpression (I.E. the one returned by lhs()) are returned. For a state variable x, this means the returned result contains all variables referring to dot(x). To get an iterator over the variables referring to x add the optional attribute state_refs=True. For non-state variables this setting will trigger a ValueError.
  2. In cases where dot(x) = f(x), the returned iterator will _not_ include x in the list of variables depending on x.
refs_to(state_refs=False)

Returns an iterator over the set of Variables that this variable’s defining equation refers to.

By default, this will _not_ include references to a state variable’s value. To obtain a list of state variables whose value is referenced, use state_refs=True.

remove_variable(variable, recursive=False)

Removes the given variable from this VarOwner and from the model.

If recursive is True, any child variables will be deleted as well.

rename(new_name)

Renames this variable.

rhs()

Returns the right-hand side of the equation defining this variable.

For state variables this will be the expression for their derivative, for all others an expression for their value is returned.

set_binding(binding)

Adds a unique binding label to this variable, indicating it can be used as an entry point for external inputs.

To remove a binding, call set_binding(None).

Adding or removing binding labels resets the model’s validation status.

set_label(label=None)

Adds a unique label for this variable, indicated that its value can be read by external users.

To remove a label call set_label(None).

set_rhs(rhs)

Changes the expression for this variable’s right hand side (rhs).

For state variables, this updates their derivative. For all others this will update the expression for their value.

Expressions can be specified using myokit.Expression objects, but floats or strings that can be parsed into expressions are also allowed:

# Ways of setting x = 2
x.set_rhs(myokit.Number(2))
x.set_rhs(2)
x.set_rhs(2.0)
x.set_rhs('2')
# Ways of setting x = 1 + y
x.set_rhs(myokit.Plus(myokit.Number(1), myokit.Name(y)))
x.set_rhs('1 + y')

Calling set_rhs will reset the validation status of the model this variable belongs to.

set_state_value(value)

If this variable is a state variable, its current value will be updated. For all other variables this raises an exception.

set_unit(unit=None)

Changes this variable’s unit. The unit can be set to any valid Unit object, or None to remove the unit.

state_value()

For state variables, this will return their current value. For all other variables, this will raise an exception.

uname()

Returns a globally unique name for this object.

unit()

Returns the unit specified for this variable. If no unit was set, the unit “dimensionless” is returned.

Variables’ units are set using Variable.set_unit() or using the in keyword in .mmt files. The unit set for a variable is the unit this variable’s expression _should_ have. This allows expressions to be validated by computing the resulting unit of an expression and comparing it with the value set for the variable.

validate(fix_crudely=False)

Attempts to check this variable’s validity, raises errors if it isn’t.

An attempt to crudely “fix” the variable can be made by setting fix_crudely to True.

value()

Will return the value of this variable’s defining right-hand side expression.

var(name)

Searches for the given variable and returns it if found. Accepts both single names x and qualified names x.y as input.

variables(const=None, inter=None, state=None, bound=None, deep=False, sort=False)

Creates and returns a filtered iterator over the contained variables.

The returned values can be filtered using the following arguments:

const=True|False|None

Constants are defined as variables that do not depend on state variables or derivatives. In other words, any variable whose value can be determined before starting an ODE solving routine.

Set to True to return only constants, False to exclude all constants and any other value to ignore this check.

inter=True|False|None

Intermediary variables are those variables that are not constant but are not part of the state. In other words, intermediary variables are the variables that need to be calculated at every step of an ODE solving routine before calculating the ODE derivatives and updating the state.

Set to True to return only intermediary variables, False to exclude all intermediary variables and any other value to ignore this check.

state=True|False|None
Set to True to return only state variables, False to exclude all state variables and any other value to ignore this check.
bound=True|False|None
Set to True to return only variables bound to an external value, False to exclude all bound variables and any other value to forgo this check.
deep=True|False (by default it’s False)
Set to True to return nested variables meeting all other criteria.
sort=True|False (by default it’s False)
Set to True to return the variables in a consistent order.