myokit 1.33.9__py3-none-any.whl → 1.35.0__py3-none-any.whl

myokit/_model_api.py

@@ -4,25 +4,14 @@
 # This file is part of Myokit.
 # See http://myokit.org for copyright, sharing, and licensing details.
 #
-from __future__ import absolute_import, division
-from __future__ import print_function, unicode_literals
-
-from collections import OrderedDict
+import io
 import math
 import re
-import myokit
 
-# StringIO in Python 2 and 3
-try:
-    from cStringIO import StringIO
-except ImportError:
-    from io import StringIO
+from collections import OrderedDict
+
+import myokit
 
-# Strings in Python 2 and 3
-try:
-    basestring
-except NameError:   # pragma: no cover
-    basestring = str
 
 TAB = ' ' * 4
 NAME = re.compile(r'^[a-zA-Z]\w*$')
@@ -34,8 +23,6 @@ def check_name(name):
     Tests if the given name is a valid myokit name and raises a
     :class:`myokit.InvalidNameError` if it isn't.
     """
-    # Note: Names are stored as str (so unicode in Python3)
-    # But the regex restriction means their format is compatible with ascii.
     # Check str compatibility
     name = str(name)
 
@@ -65,7 +52,7 @@ class MetaDataContainer(dict):
             raise myokit.InvalidMetaDataNameError(
                 'The key <' + str(key) + '>'
                 ' is not a valid meta-data property identifier.')
-        return super(MetaDataContainer, self).__getitem__(key)
+        return super().__getitem__(key)
 
     def __setitem__(self, key, item):
         # Check item
@@ -75,10 +62,10 @@ class MetaDataContainer(dict):
             raise myokit.InvalidMetaDataNameError(
                 'The key <' + str(key) + '>'
                 ' is not a valid meta-data property identifier.')
-        super(MetaDataContainer, self).__setitem__(key, item)
+        super().__setitem__(key, item)
 
 
-class ObjectWithMeta(object):
+class ObjectWithMeta:
     """
     Base class for objects with meta data.
 
@@ -87,7 +74,7 @@ class ObjectWithMeta(object):
     """
 
     def __init__(self):
-        super(ObjectWithMeta, self).__init__()
+        super().__init__()
         self.meta = MetaDataContainer()
 
     def _clone_metadata(self, clone):
@@ -135,7 +122,7 @@ class ModelPart(ObjectWithMeta):
         The given parent should be a ModelPart or None. The name should be
         unique within the set of children for the given parent.
         """
-        super(ModelPart, self).__init__()
+        super().__init__()
         self._parent = parent   # This object's parent
         self._model = None      # The model this object belongs to
         self._name = str(name)  # Local name
@@ -153,7 +140,7 @@ class ModelPart(ObjectWithMeta):
         """
         Returns this object in ``mmt`` syntax.
         """
-        b = StringIO()
+        b = io.StringIO()
         self._code(b, 0)
         return b.getvalue()
 
@@ -162,7 +149,7 @@ class ModelPart(ObjectWithMeta):
         Internal version of _code(), to be implemented by all subclasses.
 
         The argument ``t`` specifies the number of tabs to indent the code
-        with. The argument ``b`` is a cStringIO buffer.
+        with. The argument ``b`` is a StringIO buffer.
         """
         raise NotImplementedError
 
@@ -249,7 +236,7 @@ class ModelPart(ObjectWithMeta):
         return self._uname
 
 
-class VarProvider(object):
+class VarProvider:
     """
     *Abstract class*
 
@@ -463,7 +450,7 @@ class VarOwner(ModelPart, VarProvider):
     """
 
     def __init__(self, parent, name):
-        super(VarOwner, self).__init__(parent, name)
+        super().__init__(parent, name)
         self._variables = {}
         # Set component
         self._component = self
@@ -720,9 +707,7 @@ class VarOwner(ModelPart, VarProvider):
         """ See :meth:`VarProvider._resolve(). """
         def sa(name):
             # Suggest alternative
-            m = self.model()
-            (var, sug, msg) = m.suggest_variable(name)
-            return msg
+            return self.model().suggest_variable(name)[2]
 
         # Try resolving as an alias
         try:
@@ -772,7 +757,7 @@ class Model(ObjectWithMeta, VarProvider):
     Variables stored inside components can be accessed using :meth:`get()` or
     :meth:`values()`. Values defined through their derivative make up the
     model state and can be accessed using :meth:`states()`. States have
-    initial values accessible through :meth:`inits()`.
+    initial values accessible through :meth:`initial_values()`.
 
     A model's validity can be checked using :meth:`is_valid()`, which returns
     the latest validation status and :meth:`validate()`, which (re)validates
@@ -787,20 +772,20 @@ class Model(ObjectWithMeta, VarProvider):
     For consistency with components, variables, and expressions, models cannot
     be compared with ``==`` (which will only return ``True`` if both operands
     are the same object). Checking if models are the same in other senses can
-    be done with :meth:`is_similar`. Models can be serialised with ``pickle``.
+    be done with :meth:`is_similar`. Models can be serialized with ``pickle``.
     """
 
     def __init__(self, name=None):
-        super(Model, self).__init__()
+        super().__init__()
 
         # A dictionary of components
         self._components = {}
 
         # The model's state variables
-        self._state = []
+        self._state_vars = []
 
-        # The model's current state (list of floats)
-        self._current_state = []
+        # The model's initial state, as a list of Expressions
+        self._state_init = []
 
         # A dict mapping binding names to variables
         self._bindings = {}
@@ -1087,9 +1072,11 @@ class Model(ObjectWithMeta, VarProvider):
         for c in self._components.values():
             c._clone1(clone)
 
-        # Clone state
-        for k, v in enumerate(self._state):
-            clone.get(v.qname()).promote(self._current_state[k])
+        # Create states
+        # Note that the order in which promote() is called determines the
+        # state ordering, so this happens here and not in the Variable class.
+        for k, v in enumerate(self._state_vars):
+            clone.get(v.qname()).promote()
 
         # Create mapping of old var references to new references
         var_map = {}
@@ -1110,6 +1097,11 @@ class Model(ObjectWithMeta, VarProvider):
         for prefix, prepend in self._reserved_uname_prefixes.items():
             clone.reserve_unique_name_prefix(prefix, prepend)
 
+        # Copy initial state expressions
+        for k, v in enumerate(self._state_vars):
+            clone.get(v.qname()).set_initial_value(
+                self._state_init[k].clone(subst=lhs_map))
+
         # Return
         return clone
 
@@ -1119,7 +1111,7 @@ class Model(ObjectWithMeta, VarProvider):
 
         Line numbers can be added by setting ``line_numbers=True``.
         """
-        b = StringIO()
+        b = io.StringIO()
         b.write('[[model]]\n')
         self._code(b, 0)
         if line_numbers:
@@ -1141,17 +1133,15 @@ class Model(ObjectWithMeta, VarProvider):
         self._code_meta(b, 0)
 
         # Initial state
-        if self._state:
+        if self._state_vars:
             pre = t * TAB
             b.write(pre + '# Initial values\n')
-            names = [eq.lhs.code() for eq in self.inits()]
+            names = [v.qname() for v in self._state_vars]
+            values = [e.code() for e in self._state_init]
             n = max([len(name) for name in names])
-            names = iter(names)
-            for eq in self.inits():
-                name = next(names)
-                b.write(
-                    pre + name + ' ' * (n - len(name)) + ' = ' + eq.rhs.code()
-                    + '\n')
+            for name, value in zip(names, values):
+                b.write(pre + name + ' ' * (n - len(name)) + ' = '
+                        + value + '\n')
             b.write(pre + '\n')
         else:
             # No initial state? Then add newline
@@ -1243,7 +1233,7 @@ class Model(ObjectWithMeta, VarProvider):
         """
         Returns the number of state variables in this model.
         """
-        return len(self._state)
+        return len(self._state_vars)
 
     def create_unique_names(self):
         """
@@ -1357,7 +1347,7 @@ class Model(ObjectWithMeta, VarProvider):
         # Insert new state (if required)
         if state is not None:
             new_state = self.map_to_state(state)
-            for state, value in zip(self._state, new_state):
+            for state, value in zip(self._state_vars, new_state):
                 values[myokit.Name(state)] = value
             state = None
 
@@ -1390,7 +1380,7 @@ class Model(ObjectWithMeta, VarProvider):
                     values[eq.lhs] = eq.rhs.eval(values, precision=precision)
 
         # Return calculated state
-        return [values[state.lhs()] for state in self._state]
+        return [values[state.lhs()] for state in self._state_vars]
 
     def eval_state_derivatives(
             self, state=None, inputs=None, precision=myokit.DOUBLE_PRECISION,
@@ -1489,14 +1479,14 @@ class Model(ObjectWithMeta, VarProvider):
     def format_state(self, state=None, state2=None,
                      precision=myokit.DOUBLE_PRECISION):
         """
-        Converts the given list of floating point numbers to a string where
-        each line has the format ``<full_qualified_name> = <float_value>``.
+        Converts a sequence of floating point numbers to a string where each
+        line has the format ``<full_qualified_name> = <float_value>``.
 
         Arguments:
 
         ``state=None``
-            The state to show derivatives for. If no state is given the state
-            returned by :meth:`state` is used.
+            The state to display. If no state is given this model's (evaluated)
+            :meth:`<initial_values()>initial values` are used.
         ``state2=None``
             An optional second state, to be shown next to ``state`` for
             comparison.
@@ -1505,19 +1495,19 @@ class Model(ObjectWithMeta, VarProvider):
             :meth:`myokit.float.str` when formatting the state values.
 
         """
-        n = len(self._state)
-        if state is not None:
+        n = len(self._state_vars)
+        if state is None:
+            state = self.initial_values(as_floats=True)
+        else:
             if len(state) != n:
                 raise ValueError(
-                    'Argument `state` must be a list of (' + str(n)
+                    'Argument `state` must be a sequence of (' + str(n)
                     + ') floating point numbers.')
-        else:
-            state = self.state()
 
         if state2 is not None:
             if len(state2) != n:
                 raise ValueError(
-                    'Argument `state2` must be a list of (' + str(n)
+                    'Argument `state2` must be a sequence of (' + str(n)
                     + ') floating point numbers.')
 
         out = []
@@ -1541,35 +1531,35 @@ class Model(ObjectWithMeta, VarProvider):
         Like :meth:`format_state` but displays the derivatives along with
         each state's value.
 
-
         Arguments:
 
         ``state=None``
-            The state to display. If no state is given the state returned by
-            :meth:`state` is used.
+            The state to show derivatives for. If no state is given this
+            model's (evaluated) :meth:`<initial_values()>initial values` are
+            used.
         ``derivatives=None``
-            An optional list of evaluated derivatives. If not given, the values
-            will be calculed from ``state`` using :meth:`eval_derivatives()`.
+            An optional list or other sequence of evaluated derivatives. If not
+            given, the values will be calculed from ``state`` using
+            :meth:`eval_derivatives()`.
         ``precision=myokit.DOUBLE_PRECISION``
             An optional precision argument to use when evaluating the state
             derivatives, and to pass into :meth:`myokit.float.str` when
             formatting the state values and derivatives.
 
         """
-        n = len(self._state)
+        n = len(self._state_vars)
         if state is None:
-            state = self.state()
+            state = self.initial_values(as_floats=True)
         elif len(state) != n:
             raise ValueError(
-                'Argument `state` must be a list of (' + str(n)
+                'Argument `state` must be a sequence of (' + str(n)
                 + ') floating point numbers.')
 
         if derivatives is None:
-            derivatives = self.evaluate_derivatives(
-                state, precision=precision)
+            derivatives = self.evaluate_derivatives(state, precision=precision)
         elif len(derivatives) != n:
             raise ValueError(
-                'Argument `deriv` must be a list of (' + str(n)
+                'Argument `derivatives` must be a sequence of (' + str(n)
                 + ') floating point numbers.')
 
         out = []
@@ -1746,7 +1736,7 @@ class Model(ObjectWithMeta, VarProvider):
             'as external_component, or a string if only one '
             'component is provided'
         )
-        if isinstance(new_name, basestring):
+        if isinstance(new_name, str):
             if len(external_component) != 1:
                 raise TypeError(new_name_error_str)
             new_name = [new_name]
@@ -1754,7 +1744,7 @@ class Model(ObjectWithMeta, VarProvider):
             try:
                 ok = (
                     len(new_name) == len(external_component) and
-                    all(isinstance(name, basestring) for name in new_name)
+                    all(isinstance(name, str) for name in new_name)
                 )
                 if not ok:
                     raise TypeError(new_name_error_str)
@@ -1802,6 +1792,9 @@ class Model(ObjectWithMeta, VarProvider):
             for var in comp.variables():
                 vars_ref.update(var.refs_to(state_refs=False))
                 vars_ref.update(var.refs_to(state_refs=True))
+                if var.is_state():
+                    vars_ref.update(
+                        [e.var() for e in var.initial_value().references()])
             vars_ref.update(comp._alias_map.values())
             vars_ref -= set(comp.variables())
             vars_ref = [x for x in vars_ref if not x.is_nested()]
@@ -1830,7 +1823,7 @@ class Model(ObjectWithMeta, VarProvider):
                             'The variable <' + self_var.qname() + '> in the'
                             ' given var_map\'s values is not part of this'
                             ' model.')
-                elif isinstance(self_var, basestring):
+                elif isinstance(self_var, str):
                     try:
                         self_var = self.var(self_var)
                     except KeyError:
@@ -1852,7 +1845,7 @@ class Model(ObjectWithMeta, VarProvider):
                             'The variable <' + ext_var.qname() + '> in the'
                             ' given var_map\'s keys but is not part of the'
                             ' source model.')
-                elif isinstance(ext_var, basestring):
+                elif isinstance(ext_var, str):
                     try:
                         ext_var = ext_model.var(ext_var)
                     except KeyError:
@@ -1877,8 +1870,8 @@ class Model(ObjectWithMeta, VarProvider):
                 if ext_var in vars_to_map:
                     var_map[ext_var] = self_var
 
-        # add variables to var_map that map to other imported components
-        # but will be reassigned to the clone later
+        # Add variables to var_map that map to other imported components but
+        # will be reassigned to the clone later
         for l in map_to_clone:
             for ext_var in l:
                 if ext_var not in var_map:
@@ -1963,19 +1956,29 @@ class Model(ObjectWithMeta, VarProvider):
                             ' mismatch: ' + str(e))
 
         # Clone component pt 1: create, meta data, empty variables
-        new_component = []
+        new_component = []  # List of components
         for i, comp in enumerate(external_component):
             new_component.append(comp._clone1(self, new_name[i]))
 
-            for var in comp.variables(state=True):
-                # Clone states
-                # TODO: Not sure why clone() code doesn't do this?
-                new_component[i].get(var.qname(comp)).promote(
-                    var.state_value())
             # Now we can add variable to var_map if needed
             for var in map_to_clone[i]:
                 var_map[var] = new_component[i].get(var.qname(comp))
 
+        # Clone states, preserving the state order
+        # Note: The order in which promote() is called determines the order
+        # of the states in the new component. (This is one of the reasons that
+        # the component._clone1 method called above doesn't call promote.)
+        new_states = []     # New states, from all components
+        state_map = {}      # New-state to old state
+        for old_comp, comp in zip(external_component, new_component):
+            for ext_var in old_comp.variables(state=True):
+                var = comp.get(ext_var.name())
+                state_map[var] = ext_var
+                new_states.append(var)
+        new_states.sort(key=lambda var: state_map[var].index())
+        for var in new_states:
+            var.promote()   # Initial value is set later
+
         # Create mapping of old var references to new references
         # This is a mapping from Name(var) and Derivative(Name(var)) objects
         # to new myokit.Expressions referencing the target model's variables
@@ -1991,9 +1994,10 @@ class Model(ObjectWithMeta, VarProvider):
                     lhs_map[myokit.Derivative(myokit.Name(ext_var))] = \
                         myokit.Derivative(myokit.Name(self_var))
 
-        # Next, add all entries in the var_map. If unit conversion is enabled,
-        # this may include the addition of unit conversion factors
-
+        # Next, add all entries in the var_map to the lhs_map. If unit
+        # conversion is enabled, this may include the addition of unit
+        # conversion factors (so some Names in lhs_map will be mapped onto
+        # Multiply expressions).
         for ext_var, self_var in var_map.items():
             # Substitute in either a reference to self_var, or an expression
             # that converts self_var to the units ext_var's equation expects.
@@ -2022,6 +2026,11 @@ class Model(ObjectWithMeta, VarProvider):
         for i, comp in enumerate(external_component):
             comp._clone2(new_component[i], lhs_map, var_map)
 
+        # Clone initial values
+        for var in new_states:
+            var.set_initial_value(
+                state_map[var].initial_value().clone(subst=lhs_map))
+
         # Time unit conversion? Then update all derivatives.
         if time_factor is not None:
             for comp in new_component:
@@ -2031,15 +2040,32 @@ class Model(ObjectWithMeta, VarProvider):
                         var.set_rhs(
                             myokit.Multiply(rhs, myokit.Number(time_factor)))
 
+    def initial_values(self, as_floats=False):
+        """
+        Returns a list of the model's initial values.
+
+        By default, expressions are returned, but this can be changed to
+        a list of floats by setting ``as_floats=True``.
+        """
+        if as_floats:
+            if any(not e.is_literal() for e in self._state_init):
+                self.validate()  # Check for cycles before evaluating
+            return [float(y) for y in self._state_init]
+        return list(self._state_init)
+
     def inits(self):
         """
-        Returns an iterator over the ``Equation`` objects defining this model's
-        current state.
+        Deprecated method: Returns an iterator over the ``Equation`` objects
+        defining this model's initial values.
         """
+        # Deprecated since 2023-02-22
+        import warnings
+        warnings.warn('The method `inits` is deprecated.')
+
         def StateDefIterator(model):
-            for k, var in enumerate(model._state):
-                yield Equation(
-                    myokit.Name(var), myokit.Number(self._current_state[k]))
+            for var, value in zip(model._state_vars, model._state_init):
+                yield Equation(myokit.Name(var), value)
+
         return StateDefIterator(self)
 
     def is_similar(self, other, check_unames=False):
@@ -2134,10 +2160,13 @@ class Model(ObjectWithMeta, VarProvider):
 
     def load_state(self, filename):
         """
-        Sets the model state using data from a file formatted in any style
-        accepted by :func:`myokit.parse_state`.
+        Deprecated method: Sets the model's initial values using data from a
+        file formatted in any style accepted by :func:`myokit.map_to_state`.
         """
-        self.set_state(myokit.load_state(filename, self))
+        # Deprecated since 2023-02-22
+        import warnings
+        warnings.warn('The method `load_state` is deprecated.')
+        self.set_initial_values(myokit.load_state(filename, self))
 
     def map_component_dependencies(
             self, omit_states=True, omit_constants=False):
@@ -2160,7 +2189,7 @@ class Model(ObjectWithMeta, VarProvider):
         not ``[B,C]``.
 
         By default, dependencies on state variables' current values are
-        omitted. This behaviour can be changed by setting ``omit_states`` to
+        omitted. This behavior can be changed by setting ``omit_states`` to
         ``False``.
 
         To omit all dependencies on constants, set ``omit_constants`` to
@@ -2340,7 +2369,7 @@ class Model(ObjectWithMeta, VarProvider):
         dependencies will be added to the dependency lists of their parents.
 
         By default, dependencies on state variables' current values are
-        omitted. This behaviour can be changed by setting ``omit_states`` to
+        omitted. This behavior can be changed by setting ``omit_states`` to
         ``False``.
 
         In case of a dependency such as::
@@ -2484,7 +2513,7 @@ class Model(ObjectWithMeta, VarProvider):
         dependencies will be added to the dependency lists of their parents.
 
         By default, dependencies on state variables' current values are
-        omitted. This behaviour can be changed by setting ``omit_states`` to
+        omitted. This behavior can be changed by setting ``omit_states`` to
         ``False``. Dependencies on constants are included by default, but this
         can be changed by setting ``omit_constants`` to ``True``.
         """
@@ -2555,7 +2584,7 @@ class Model(ObjectWithMeta, VarProvider):
 
         """
         n = self.count_states()
-        if isinstance(state, basestring):
+        if isinstance(state, str):
             # String given. Parse into name:float map or list
             state = myokit.parse_state(state)
         if isinstance(state, dict):
@@ -2592,45 +2621,6 @@ class Model(ObjectWithMeta, VarProvider):
         except KeyError:
             return None
 
-    def prepare_bindings(self, labels):
-        """
-        Takes a mapping of binding labels to internal references as input and
-        returns a mapping of variables to internal references. All variables
-        appearing in the map will have their right hand side set to zero. All
-        bindings not mapped to any internal reference will be deleted.
-
-        The argument ``mapping`` should take the form::
-
-            labels = {
-                'binding_label_1' : internal_name_1,
-                'binding_label_2' : internal_name_2,
-                ...
-                }
-
-        The returned dictionary will have the form::
-
-            variables = {
-                variable_x : internal_name_1,
-                variable_y : internal_name_2,
-                ...
-                }
-
-        Unsupported bindings (i.e. bindings not appearing in ``labels``) will
-        be ignored.
-        """
-        unused = []
-        variables = {}
-        for label, var in self._bindings.items():
-            try:
-                variables[var] = labels[label]
-            except KeyError:
-                unused.append(var)
-                continue
-            var.set_rhs(0)
-        for var in unused:
-            var.set_binding(None)
-        return variables
-
     def __reduce__(self):
         """
         Pickles the model.
@@ -2701,7 +2691,7 @@ class Model(ObjectWithMeta, VarProvider):
 
         This method does not affect the model's validation status.
         """
-        n = len(self._state)
+        n = len(self._state_vars)
         if len(order) != n:
             raise ValueError(
                 'The given list must contain the same number of entries as'
@@ -2719,11 +2709,11 @@ class Model(ObjectWithMeta, VarProvider):
                     'Duplicate entry in order specification: "'
                     + str(v.qname()) + '".')
             state.append(v)
-            current.append(self._current_state[v._indice])
-        self._state = state
-        self._current_state = current
+            current.append(self._state_init[v._index])
+        self._state_vars = state
+        self._state_init = current
         for k, v in enumerate(state):
-            v._indice = k
+            v._index = k
 
     def remove_component(self, component):
         """
@@ -2771,7 +2761,7 @@ class Model(ObjectWithMeta, VarProvider):
             time_unit = time.unit()
 
         # Scan all states
-        for state in self._state:
+        for state in self._state_vars:
 
             # Search for references to dot(state)
             refs = list(state.refs_by())
@@ -2842,8 +2832,8 @@ class Model(ObjectWithMeta, VarProvider):
         """
         Resets the indices of this model's state variables.
         """
-        for k, v in enumerate(self._state):
-            v._indice = k
+        for k, v in enumerate(self._state_vars):
+            v._index = k
 
     def _reset_validation(self):
         """
@@ -2853,7 +2843,11 @@ class Model(ObjectWithMeta, VarProvider):
 
     def _resolve(self, name):
         """ See :meth:`VarProvider._resolve(). """
-        return self.get(name)
+        try:
+            return self.get(name)
+        except KeyError:
+            raise myokit.UnresolvedReferenceError(
+                name, self.suggest_variable(name)[2])
 
     def resolve_interdependent_components(self):
         """
@@ -2887,9 +2881,39 @@ class Model(ObjectWithMeta, VarProvider):
 
     def save_state(self, filename):
         """
-        Saves the model state to a file.
+        Deprecated method: Saves the model state to a file (as floats).
         """
-        return myokit.save_state(filename, self.state(), self)
+        # Deprecated since 2023-02-22
+        import warnings
+        warnings.warn('The method `save_state` is deprecated.')
+
+        return myokit.save_state(
+            filename, self.initial_values(as_floats=True), self)
+
+    def set_initial_values(self, values):
+        """
+        Sets this model's initial values.
+
+        The ``values`` must be specified as either a list of floats,
+        expressions, and/or strings; or as a dict or string in a format
+        accepted by :meth:`map_to_state`.
+        """
+        # Use map to state?
+        if isinstance(values, str) or isinstance(values, dict):
+            self._state_init = [
+                myokit.Number(x) for x in self.map_to_state(values)]
+        elif len(values) != len(self._state_vars):
+            raise ValueError('Wrong number of initial values, expecting '
+                             + str(len(self._state_vars)) + '.')
+        else:
+            # Parsing of arguments without making changes, in case it fails.
+            expr = []
+            for var, value in zip(self._state_vars, values):
+                expr.append(var._set_initial_value(value, False))
+
+            # Set all at once, and reset validation status
+            self._state_init = expr
+            self._valid = None
 
     def set_name(self, name=None):
         """
@@ -2914,10 +2938,14 @@ class Model(ObjectWithMeta, VarProvider):
 
     def set_state(self, state):
         """
-        Changes this model's state. Accepts any type of input handled by
-        :meth:`map_to_state`.
+        Deprecated method: use :meth:`set_initial_values` instead.
         """
-        self._current_state = self.map_to_state(state)
+        # Deprecated since 2023-02-22
+        import warnings
+        warnings.warn(
+            'The method `set_state` is deprecated. Please use'
+            ' `set_initial_values` instead.')
+        self.set_initial_values(state)
 
     def set_value(self, qname, value):
         """
@@ -2938,6 +2966,9 @@ class Model(ObjectWithMeta, VarProvider):
         The variable's equation and value are displayed, along with the value
         and formula of any nested variables and the values of all dependencies.
         """
+        # Model must be valid, or cycles can occur
+        self.validate()
+
         def format_float(number):
             s = str(number)
             if len(s) < 10:
@@ -2951,7 +2982,10 @@ class Model(ObjectWithMeta, VarProvider):
         # Add initial value
         rhs = var.rhs()
         if var.is_state():
-            out.append('Initial value = ' + str(var.state_value()))
+            value = var.initial_value()
+            out.append('Initial value = ' + value.code())
+            if not isinstance(value, myokit.Number):
+                out.append('              = ' + format_float(value))
             out.append(spacer)
         varname = var.lhs().code()
 
@@ -3237,17 +3271,22 @@ class Model(ObjectWithMeta, VarProvider):
 
     def state(self):
         """
-        Returns the current state of the model as a list of floating point
-        numbers.
+        Deprecated method, use
+        :meth:`initial_values(as_floats=True)<initial_values>` instead.
         """
-        return list(self._current_state)
+        # Deprecated since 2023-02-22
+        import warnings
+        warnings.warn(
+            'The method `state` is deprecated. Please use'
+            ' `initial_values(as_floats=True)` instead.')
+        return self.initial_values(as_floats=True)
 
     def states(self):
         """
         Returns an iterator over this model's state :class:`variable
         <myokit.Variable>` objects.
         """
-        return iter(self._state)
+        return iter(self._state_vars)
 
     def suggest_variable(self, name):
         """
@@ -3328,10 +3367,7 @@ class Model(ObjectWithMeta, VarProvider):
         "time". For a valid model, this method always returns a unique
         variable. If no time variable has been declared ``None`` is returned.
         """
-        try:
-            return self._bindings['time']
-        except KeyError:
-            return None
+        return self._bindings.get('time')
 
     def timex(self):
         """
@@ -3373,7 +3409,7 @@ class Model(ObjectWithMeta, VarProvider):
 
     def validate(self, remove_unused_variables=False):
         """
-        Attempts to check model validity, raises errors if it isn't.
+        Validates this model and raises errors if any issues are found.
 
         Small issues (e.g. unused variables) will generate warnings, which
         can be retrieved using :meth:`Model.warnings()` or
@@ -3399,6 +3435,15 @@ class Model(ObjectWithMeta, VarProvider):
                 'Invalid time variable set. Time variable must be bound to'
                 ' external value "time".')
 
+        # Test initial value expresions
+        n = len(self._state_vars)
+        if n != len(self._state_init):   # pragma: no cover
+            # Cover pragma: This can only happen if there's an API bug
+            self._valid = False
+            raise myokit.IntegrityError(
+                'Initial values list must have same size as state variables'
+                ' list.')
+
         # Validation of components, variables
         for c in self.components():
             if c._parent != self:   # pragma: no cover
@@ -3419,15 +3464,6 @@ class Model(ObjectWithMeta, VarProvider):
                     'Component called <' + c.qname() + '> found at index <'
                     + n + '>.')
 
-        # Test current state values
-        n = len(self._state)
-        if n != len(self._current_state):   # pragma: no cover
-            # Cover pragma: This can only happen if there's an API bug
-            self._valid = False
-            raise myokit.IntegrityError(
-                'Current state values list must have same size as state'
-                ' variables list.')
-
         # Find cycles, warn of unused variables
         self._validate_solvability(remove_unused_variables)
 
@@ -3481,7 +3517,7 @@ class Model(ObjectWithMeta, VarProvider):
 
         # Follow all state variables (unless already visited), all bound
         # variables and all used variables.
-        used = [x for x in self._state]
+        used = [x for x in self._state_vars]
         used += [x for x in self._bindings.values()]
         used += [x for x in self._labels.values()]
 
@@ -3547,7 +3583,7 @@ class Model(ObjectWithMeta, VarProvider):
         if not isinstance(var, ModelPart):
             var = self.suggest_variable(var)
             if var[0] is None:
-                if var[1] is None:
+                if var[1] is None:  # pragma: no cover
                     raise Exception(var[2])
                 var = var[1]
                 out.append(
@@ -3606,7 +3642,7 @@ class Component(VarOwner):
     """
 
     def __init__(self, model, name):
-        super(Component, self).__init__(model, name)
+        super().__init__(model, name)
         self._alias_map = {}    # Maps variable names to other variables names
 
     def _clone1(self, model, new_name=None):
@@ -3692,7 +3728,7 @@ class Component(VarOwner):
             var._delete(recursive=True, ignore_siblings=True)
 
         # Delete links to parent
-        super(Component, self)._delete()
+        super()._delete()
 
     def alias(self, name):
         """
@@ -3824,10 +3860,10 @@ class Variable(VarOwner):
     """
 
     def __init__(self, parent, name):
-        super(Variable, self).__init__(parent, name)
+        super().__init__(parent, name)
 
-        # Indice, only set if this is a state variable
-        self._indice = None
+        # Index, only set if this is a state variable
+        self._index = None
 
         # This variable's unit, if given, else dimensionless
         self._unit = None
@@ -3885,7 +3921,11 @@ class Variable(VarOwner):
         """
         # Set value
         if value is None:
-            value = self.state_value() if self._is_state else self._rhs.eval()
+            self.model().validate()  # Model must be valid before evaluations
+            if self._is_state:
+                value = self.initial_value(True)
+            else:
+                value = self._rhs.eval()
         else:
             value = float(value)
 
@@ -3920,7 +3960,7 @@ class Variable(VarOwner):
         The argument ``lhs_map`` should be a dictionary mapping old
         :class:`LhsExpression` objects their equivalents in the new model.
         """
-        # _indice is set by promoting (done by model)
+        # _index is set by promoting (done by model)
         # _binding
         if self._binding:
             v.set_binding(self._binding)
@@ -3942,6 +3982,10 @@ class Variable(VarOwner):
         for k in self.variables():
             k._clone2(v[k.name()], lhs_map)
 
+        # Note: initial values are stored inside the model, and the state order
+        # depends on the order in which promoting occurs, so states are only
+        # created by Model.clone()
+
     def _code(self, b, t):
         """
         Create the code for this variable and any child variables.
@@ -4081,7 +4125,12 @@ class Variable(VarOwner):
 
         # For states, update the current/initial value
         if self._is_state:
-            self.set_state_value(self.state_value() * float(fw))
+            # Number? Then just multiply. Else use expression.
+            value = self.initial_value()
+            if isinstance(value, myokit.Number):
+                self.set_initial_value(float(value) * float(fw))
+            else:
+                self.set_initial_value(myokit.Multiply(value, fw))
 
         # Update all references to the variable
         old_ref = myokit.Name(self)
@@ -4159,6 +4208,29 @@ class Variable(VarOwner):
                     ' can not be removed: it is used by ' + ' and '.join(
                         ['<' + v.qname() + '>' for v in refs]) + '.')
 
+        # Third check: Do initial values depend on this variable?
+        # Note that, instead of using a cached set in every variable, this
+        # reference is just checked by scanning all init expressions (which
+        # contain a cached set of references).
+        # Note that we don't optimise by checking if this variable is constant,
+        # as it's possible to create (invalid) models where non-constants are
+        # referenced in initial values (but validate() will pick this up!).
+        refs = set()
+        m = self.model()
+        n = myokit.Name(self)
+        for v, e in zip(m._state_vars, m._state_init):
+            if n in e.references():
+                refs.add(v)
+        if ignore_siblings:
+            # Refs from sibling variables are allowed
+            refs = refs.difference(
+                set([x for x in refs if x.has_ancestor(self._parent)]))
+        if refs:
+            raise myokit.IntegrityError(
+                'Variable <' + self.qname() + '> can not be removed: it is'
+                ' used in the inital value(s) for ' + ' and '.join(
+                    ['<' + v.qname() + '>' for v in refs]) + '.')
+
         # At this point it's OK to delete. Rest of the code makes changes,
         # shouldn't raise errors.
 
@@ -4183,7 +4255,6 @@ class Variable(VarOwner):
             self.set_label(None)
 
             # Remove any aliases
-            m = self.parent(Model)
             for c in m.components():
                 c.remove_aliases_for(self)
 
@@ -4196,7 +4267,7 @@ class Variable(VarOwner):
                 self._remove_variable_internal(kid)
 
         # Remove parent links
-        super(Variable, self)._delete()
+        super()._delete()
 
     def demote(self):
         """
@@ -4205,7 +4276,7 @@ class Variable(VarOwner):
         This will reset the validation status of the model this variable
         belongs to.
         """
-        if self._indice is None:
+        if self._index is None:
             raise Exception('Variable is not a state variable.')
 
         # Check that nobody has references to this var's derivative
@@ -4218,16 +4289,16 @@ class Variable(VarOwner):
         model = self.model()
         try:
             # Remove initial value
-            del model._current_state[self._indice]
+            del model._state_init[self._index]
 
             # Remove this variable from the state
-            del model._state[self._indice]
+            del model._state_vars[self._index]
 
             # Set lhs to name expression
             self._lhs = myokit.Name(self)
 
-            # Remove this variable's indice
-            self._indice = None
+            # Remove this variable's index
+            self._index = None
 
             # Reset other states' indices
             model._reset_indices()
@@ -4260,14 +4331,43 @@ class Variable(VarOwner):
         """
         return self._rhs.eval()
 
-    def indice(self):
+    def index(self):
         """
         For state variables, this will return their index in the state vector.
+
         For all other variables, this will raise an exception.
         """
-        if self._indice is None:
+        if self._index is None:
+            raise Exception('Only state variables have initial values.')
+        return self._index
+
+    def indice(self):
+        """ Deprecated alias of :meth:`index`. """
+
+        # Deprecated on 2023-06-07
+        import warnings
+        warnings.warn(
+            'The method `indice` is deprecated. Please use `index()` instead.')
+        return self.index()
+
+    def initial_value(self, as_float=False):
+        """
+        Returns a state variable's initial value, or raises an exception when
+        called on a non-state variable.
+
+        By default, a :class:`myokit.Expression` is returned. To evaluate and
+        return a float set ``as_float=True``.
+        """
+        if not self._is_state:
             raise Exception('Only state variables have initial values.')
-        return self._indice
+
+        model = self.model()
+        expr = model._state_init[self._index]
+        if not as_float:
+            return expr
+        if not expr.is_literal():
+            model.validate()
+        return expr.eval()
 
     def is_bound(self):
         """
@@ -4277,19 +4377,21 @@ class Variable(VarOwner):
 
     def is_constant(self):
         """
-        Returns ``True`` if this variable is constant.
+        Returns ``True`` if this variable has a constant value (even if that
+        value is defined in terms of other constants).
 
         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.
+        termed a constant. Note that this specifically excludes variables that
+        define a _binding_ to an external input.
         """
         return self._is_constant
 
     def is_intermediary(self):
         """
         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).
+        a constant, not a state variable, and not bound to an external input
+        such as time.
         """
         return self._is_intermediary
 
@@ -4301,8 +4403,7 @@ class Variable(VarOwner):
 
     def is_literal(self):
         """
-        Returns ``True`` if this variable's expression contains only literal
-        values.
+        Returns ``True`` if this variable does not depend on other variables.
         """
         return self._is_literal
 
@@ -4341,15 +4442,27 @@ class Variable(VarOwner):
         """
         return self._lhs
 
-    def promote(self, state_value=0):
+    def promote(self, initial_value=0, state_value=None):
         """
-        Turns this variable into a state variable with a current state value
-        given by ``state_value``.
+        Turns this variable into a state variable with an initial value given
+        by ``initial_value``.
 
-        This will reset the validation status of the model this variable
-        belongs to.
+        The new ``initial_value`` should be:
+
+        1. A numerical value.
+        2. A :class:`myokit.Expression`.
+        3. A string which can be parsed to a :class:`myokit.Expression`. Any
+           references to variables must be made using their fully qualified
+           names.
+
+        Note that expressions can contain references to non-nested and
+        constant-valued variables (i.e. their right-hand side is either a
+        literal expression or refers only to constants).
+
+        Calling ``promote`` will reset the validation status of the model this
+        variable belongs to.
         """
-        if self._indice is not None:
+        if self._index is not None:
             raise Exception('Variable is already a state variable')
         if not isinstance(self._parent, Component):
             raise Exception('State variables can only be added to Components.')
@@ -4357,26 +4470,40 @@ class Variable(VarOwner):
             raise Exception(
                 'State variables cannot be bound to an external value.')
 
-        # Check state value argument
-        if isinstance(state_value, myokit.Expression):
-            if not state_value.is_literal():
-                raise myokit.NonLiteralValueError(
-                    'Expressions for state values can not contain references'
-                    ' to other variables.')
+        # Deprecated on 2023-02-22
+        if state_value is not None:
+            if initial_value != 0:
+                raise Exception('Deprecated keyword argument `state_value` can'
+                                ' not be used at the same time as its'
+                                ' replacement `initial_value`.')
+            initial_value = state_value
 
+            import warnings
+            warnings.warn('The keyword argument `state_value` is deprecated.'
+                          ' Please use `initial_value` instead.')
+
+        # Handle string and number rhs's
         model = self.model()
+        if not isinstance(initial_value, myokit.Expression):
+            if isinstance(initial_value, str):
+                # Expressions are evaluated in model context
+                initial_value = myokit.parse_expression(
+                    initial_value, context=model)
+            elif initial_value is not None:
+                initial_value = myokit.Number(initial_value)
+
         try:
             # Set lhs to derivative expression
             self._lhs = myokit.Derivative(myokit.Name(self))
 
-            # Get new indice
-            self._indice = len(model._state)
+            # Get new index
+            self._index = len(model._state_vars)
 
             # Add to list of states
-            model._state.append(self)
+            model._state_vars.append(self)
 
-            # Add value to list of current values
-            model._current_state.append(float(state_value))
+            # Add initial_value to list of current values
+            model._state_init.append(initial_value)
 
             # All references to this variable are now considered references to
             # its state value
@@ -4448,9 +4575,9 @@ class Variable(VarOwner):
         # Create function
         local = {}
         if use_numpy:
-            myokit._exec(func, {'numpy': numpy}, local)
+            exec(func, {'numpy': numpy}, local)
         else:
-            myokit._exec(func, {'math': math}, local)
+            exec(func, {'math': math}, local)
         handle = local['var_pyfunc_generated']
 
         # Return
@@ -4524,7 +4651,7 @@ class Variable(VarOwner):
         self._parent.move_variable(self, self._parent, new_name)
 
     def __repr__(self):
-        if self._indice is not None:
+        if self._index is not None:
             return '<State(' + self.qname() + ')>'
         else:
             return '<Var(' + self.qname() + ')>'
@@ -4539,7 +4666,7 @@ class Variable(VarOwner):
             s_old = (self._is_bound, self._is_state, self._is_intermediary,
                      self._is_literal, self._is_constant, self._is_nested)
         self._is_bound = self._binding is not None
-        self._is_state = self._indice is not None
+        self._is_state = self._index is not None
         self._is_nested = isinstance(self._parent, Variable)
         if self._is_state or self._is_bound or self._rhs is None:
             self._is_constant = False
@@ -4586,7 +4713,7 @@ class Variable(VarOwner):
                     ' is already bound to "' + self._binding + '".')
 
             # Check if not a state
-            if self._indice is not None:
+            if self._index is not None:
                 raise myokit.InvalidBindingError(
                     'State variables cannot be bound to an external value.')
 
@@ -4606,6 +4733,42 @@ class Variable(VarOwner):
             # Reset model validation
             model._reset_validation()
 
+    def set_initial_value(self, value):
+        """
+        Sets the initial value of a state variable, or raises an exception if
+        called on a non-state variable.
+
+        The new value can be passed in as an expression, number, or a string
+        (in which case it will be parsed as an expression). Expressions can
+        refer to variables as long as they are not nested and are constant in
+        time. Variable references in strings must be made using fully qualified
+        names (``component.variable``).
+        """
+        if not self._is_state:
+            raise Exception('Only state variables have state values.')
+        self._set_initial_value(value, True)
+
+    def _set_initial_value(self, value, make_the_change):
+        """ Internal version of `set_initial_value`. """
+        # Handle strings and floats
+        model = self.model()
+        if not isinstance(value, myokit.Expression):
+            if isinstance(value, str):
+                value = myokit.parse_expression(value, context=model)
+            else:
+                value = myokit.Number(value)
+
+        # Allow internal calls to parse `value` without making a change
+        if not make_the_change:
+            return value
+
+        # Update
+        try:
+            model._state_init[self._index] = value
+        finally:
+            # Reset model validation, but not the variable cache
+            model._reset_validation()
+
     def set_label(self, label=None):
         """
         Adds a unique ``label`` for this variable, indicated that its value can
@@ -4658,7 +4821,7 @@ class Variable(VarOwner):
         """
         # Handle string and number rhs's
         if not isinstance(rhs, myokit.Expression):
-            if isinstance(rhs, basestring):
+            if isinstance(rhs, str):
                 rhs = myokit.parse_expression(rhs, context=self)
             elif rhs is not None:
                 rhs = myokit.Number(rhs)
@@ -4693,19 +4856,14 @@ class Variable(VarOwner):
 
     def set_state_value(self, value):
         """
-        If this variable is a state variable, its current value will be
-        updated. For all other variables this raises an exception.
+        Deprecated method, use :meth:`set_initial_value` instead.
         """
-        if not self._is_state:
-            raise Exception('Only state variables have state values.')
-        model = self.model()
-        if isinstance(value, myokit.Expression):
-            if not value.is_literal():
-                raise myokit.NonLiteralValueError(
-                    'Expressions for state values can not contain references'
-                    ' to other variables.')
-        model._current_state[self._indice] = float(value)
-        # No need to reset validation status or cache here.
+        # Deprecated since 2023-02-22
+        import warnings
+        warnings.warn(
+            'The method `set_state_value` is deprecated. Please use'
+            ' `set_initial_value` instead.')
+        self.set_initial_value(value)
 
     def set_unit(self, unit=None):
         """
@@ -4714,7 +4872,7 @@ class Variable(VarOwner):
         """
         if unit is None or isinstance(unit, myokit.Unit):
             self._unit = unit
-        elif isinstance(unit, basestring):
+        elif isinstance(unit, str):
             self._unit = myokit.parse_unit(unit)
         else:
             raise TypeError('Method set_unit() expects a myokit.Unit or None.')
@@ -4723,12 +4881,15 @@ class Variable(VarOwner):
 
     def state_value(self):
         """
-        For state variables, this will return their current value.
-        For all other variables, this will raise an exception.
+        Deprecated method, use
+        :meth:`initial_value(as_float=True)<initial_value>` instead.
         """
-        if not self._is_state:
-            raise Exception('Only state variables have initial values.')
-        return self.model()._current_state[self._indice]
+        # Deprecated since 2023-02-22
+        import warnings
+        warnings.warn(
+            'The method `state_value` is deprecated. Please use'
+            ' `initial_value(as_float=True)` instead.')
+        return self.initial_value(as_float=True)
 
     def unit(self, mode=myokit.UNIT_TOLERANT):
         """
@@ -4752,46 +4913,89 @@ class Variable(VarOwner):
         """
         Attempts to check this variable's validity, raises errors if it isn't.
         """
+        #
         # Validate rhs
+        #
         if self._rhs is None:
             raise myokit.MissingRhsError(self)
         self._rhs.validate()
 
-        # Partial derivatives are not allowed in an RHS
+        # RHS: No PartialDerivative objects
         if self._rhs.contains_type(myokit.PartialDerivative):
             raise myokit.IntegrityError(
                 'Partial derivatives may not appear in expressions set as'
-                ' right-hand side of a variable.')
+                ' right-hand side of a variable: <' + self.qname() + '>.')
 
-        # Initial values are not allowed in an RHS
+        # RHS: No InitialValue objects
         if self._rhs.contains_type(myokit.InitialValue):
             raise myokit.IntegrityError(
                 'Initial value operators may not appear in expressions set as'
-                ' right-hand side of a variable.')
+                ' right-hand side of a variable: <' + self.qname() + '>.')
 
-        # Conditions are not allowed as an RHS
+        # RHS: Can't evaluate to True or False
         if isinstance(self._rhs, myokit.Condition):
             raise myokit.IntegrityError(
                 'The right-hand side expression for a variable can not be a'
-                ' condition.')
+                ' condition: <' + self.qname() + '>.')
 
+        #
         # Check state variables
-        is_state = self._indice is not None
+        #
+        is_state = self._index is not None
         is_deriv = self.lhs().is_derivative()
         if is_state:
+            # Derivative is set
             if not is_deriv:        # pragma: no cover
                 raise myokit.IntegrityError(
                     'Variable <' + self.qname() + '> is listed as a state'
                     ' variable but its lhs is not a derivative.')
+
+            # Not nested
             if self._is_nested:     # pragma: no cover
                 raise myokit.IntegrityError(
                     'State variables should not be nested: <'
                     + str(self.qname()) + '>.')
+
+            # Index matches model
             m = self.model()
-            if not m._state[self._indice] == self:  # pragma: no cover
+            if not m._state_vars[self._index] == self:  # pragma: no cover
                 raise myokit.IntegrityError(
                     'State variable not listed in model state vector at'
-                    ' correct indice: <' + self.qname() + '>.')
+                    ' correct index: <' + self.qname() + '>.')
+
+            # Initial value is an expression
+            i = m._state_init[self._index]
+            if not isinstance(i, myokit.Expression):  # pragma: no cover
+                raise myokit.IntegrityError(
+                    'Initial value for <' + self.qname() + '> is not an'
+                    ' expression.')
+
+            # Init: No PartialDerivative or InitialValue operators
+            if i.contains_type(myokit.PartialDerivative):
+                raise myokit.IntegrityError(
+                    'Partial derivatives may not appear in model expressions:'
+                    ' initial value for <' + self.qname() + '>.')
+            if i.contains_type(myokit.InitialValue):
+                raise myokit.IntegrityError(
+                    'Initial values may not appear in model expressions:'
+                    ' initial value for < ' + self.qname() + '>.')
+
+            # Init: Can't evaluate to True or False
+            if isinstance(i, myokit.Condition):
+                raise myokit.IntegrityError(
+                    'The initial value for a variable can not be a'
+                    ' condition: <' + self.qname() + '>.')
+
+            # Init: No nested variables or non-constants
+            for ref in i.references():
+                var = ref.var()
+                if var.is_nested():
+                    raise myokit.IllegalReferenceInInitialValueError(self, ref)
+                if not var.is_constant():
+                    raise myokit.IntegrityError(
+                        'Initial value for variable <' + self.qname() + '> is'
+                        ' not constant: ' + i.code() + '.')
+
         elif is_deriv:  # pragma: no cover
             raise myokit.IntegrityError(
                 'A derivative was set for <' + self.qname() + '> but this is'
@@ -4851,7 +5055,7 @@ class Variable(VarOwner):
         return self._rhs.eval()
 
 
-class Equation(object):
+class Equation:
     """
     Defines an equation: a statement that a left-hand side (LHS) is equal to a
     right-hand side (RHS) expression.
@@ -4886,7 +5090,7 @@ class Equation(object):
 
     def code(self):
         """ Returns an ``.mmt`` representation of this equation. """
-        b = StringIO()
+        b = io.StringIO()
         self._lhs._code(b, None)
         b.write(' = ')
         self._rhs._code(b, None)
@@ -4932,7 +5136,7 @@ class EquationList(list, VarProvider):
         return stream(self)
 
 
-class UserFunction(object):
+class UserFunction:
     """
     Represents a user function.