myokit 1.38.0__py3-none-any.whl → 1.39.0__py3-none-any.whl

myokit/formats/cellml/v2/_api.py

@@ -10,13 +10,11 @@ import warnings
 
 import myokit
 
+from myokit.formats import is_integer_string, is_real_number_string
+
 
 # Data types
 _cellml_identifier = re.compile(r'^[a-zA-Z][a-zA-Z0-9_]*$')
-_cellml_integer = re.compile(r'^[+-]?[0-9]+$')
-_real = r'[+-]?(([0-9]*\.[0-9]+)|([0-9]+\.?[0-9]*))'
-_cellml_basic_real = re.compile(r'^' + _real + r'$')
-_cellml_real = re.compile(r'^' + _real + r'([eE][+-]?[0-9]+)?$')
 
 
 def is_identifier(name):
@@ -32,27 +30,6 @@ def is_identifier(name):
     return _cellml_identifier.match(name) is not None
 
 
-def is_integer_string(text):
-    """
-    Tests if the given ``text`` is a valid CellML 2.0 integer string.
-    """
-    return _cellml_integer.match(text) is not None
-
-
-def is_basic_real_number_string(text):
-    """
-    Tests if the given ``text`` is a valid CellML 2.0 basic real number string.
-    """
-    return _cellml_basic_real.match(text) is not None
-
-
-def is_real_number_string(text):
-    """
-    Tests if the given ``text`` is a valid CellML 2.0 basic real number string.
-    """
-    return _cellml_real.match(text) is not None
-
-
 def clean_identifier(name):
     """
     Checks if ``name`` is a valid CellML 2.0 identifier and if not attempts to
@@ -70,8 +47,7 @@ def clean_identifier(name):
     if is_identifier(clean):
         return clean
     raise ValueError(
-        'Unable to create a valid CellML 2.0 identifier from "' + str(name)
-        + '".')
+        f'Unable to create a valid CellML 2.0 identifier from "{name}".')
 
 
 def create_unit_name(unit):
@@ -133,6 +109,16 @@ def create_unit_name(unit):
     return name
 
 
+def is_prefixed_number(expr):
+    """
+    Checks if ``expr`` is a :class:`myokit.Number`, wrapped in any number of
+    prefix plus or minus operators.
+    """
+    while isinstance(expr, (myokit.PrefixPlus, myokit.PrefixMinus)):
+        expr = expr[0]
+    return isinstance(expr, myokit.Number)
+
+
 class AnnotatableElement:
     """
     Represents a CellML 2.0 element that can be annotated (using a public dict
@@ -262,7 +248,7 @@ class Component(AnnotatableElement):
             parent._children.add(self)
 
     def __str__(self):
-        return 'Component[@name="' + self._name + '"]'
+        return f'Component[@name="{self._name}"]'
 
     def _validate(self):
         """
@@ -298,7 +284,8 @@ class Model(AnnotatableElement):
 
     - Imports are not supported.
     - Reset rules are not supported.
-    - Using variables in ``initial_value`` attributes is not supported.
+    - Using variables in ``initial_value`` attributes is supported, as long as
+      they have constant values.
     - Defining new base units is not supported.
     - All equations must be of the form ``x = ...`` or ``dx/dt = ...``.
     - Models that take derivatives with respect to more than one variable are
@@ -401,39 +388,36 @@ class Model(AnnotatableElement):
             interface_2 = 'public'
         else:
             raise CellMLError(
-                'Unable to connect ' + str(variable_1) + ' to '
-                + str(variable_2) + ': connections can only be made between'
-                ' components that are siblings or have a parent-child'
-                ' relationship.')
+                f'Unable to connect {variable_1} to {variable_2}: connections'
+                ' can only be made between components that are siblings or'
+                ' have a parent-child relationship.')
 
         # Check the variables' interfaces.
         if interface_1 not in variable_1.interface():
             raise CellMLError(
-                'Unable to connect ' + str(variable_1) + ' to '
-                + str(variable_2) + ': variable_1 requires the ' + interface_1
-                + ' interface, but is set to ' + variable_1.interface() + '.')
+                f'Unable to connect {variable_1} to {variable_2}: variable_1'
+                f' requires the {interface_1} interface, but is set to'
+                f' {variable_1.interface()}.')
         if interface_2 not in variable_2.interface():
             raise CellMLError(
-                'Unable to connect ' + str(variable_1) + ' to '
-                + str(variable_2) + ': variable_2 requires the ' + interface_2
-                + ' interface, but is set to ' + variable_2.interface() + '.')
+                f'Unable to connect {variable_1} to {variable_2}: variable_2'
+                f' requires the {interface_2} interface, but is set to'
+                f' {variable_2.interface()}.')
 
         # Check the variables' units.
         unit_1 = variable_1.units().myokit_unit()
         unit_2 = variable_2.units().myokit_unit()
         if not myokit.Unit.can_convert(unit_1, unit_2):
             raise CellMLError(
-                'Unable to connect ' + str(variable_1) + ' to '
-                + str(variable_2) + ': Connected variables must have'
-                ' compatible units. Found ' + str(variable_1.units())
-                + ' and ' + str(variable_2.units()) + '.')
+                f'Unable to connect {variable_1} to {variable_2}: Connected'
+                ' variables must have compatible units. Found'
+                f' {variable_1.units()} and {variable_2.units()}.')
 
         # Check the variables aren't already connected
         if variable_1 in variable_2._cset:
             raise CellMLError(
-                'Variables cannot be connected twice: ' + str(variable_1)
-                + ' is already in the connected variable set of '
-                + str(variable_2) + '.')
+                f'Variables cannot be connected twice: {variable_1} is already'
+                f' in the connected variable set of {variable_2}.')
 
         # Connect the variables, by merging their connected variable sets.
         ConnectedVariableSet._merge(variable_1._cset, variable_2._cset)
@@ -600,6 +584,35 @@ class Model(AnnotatableElement):
         # Create CellML model
         m = Model(name, version)
 
+        # Check if we need to create a Myokit model where all initial variables
+        # are either numbers or names of local variables.
+        states_to_fix = []
+        for state in model.states():
+            e = state.initial_value()
+            if isinstance(e, myokit.Number):
+                continue
+            if isinstance(e, myokit.Name):
+                # Compare parents: note, nested variables can't be referenced
+                # here, so this check is sufficient
+                if e.var().parent() == state.parent():
+                    continue
+            states_to_fix.append(state.qname())
+        if states_to_fix:
+            model = model.clone()
+            for state in states_to_fix:
+                state = model.get(state)
+                value = state.initial_value()
+                if is_prefixed_number(value):
+                    # Don't make variables for x = -1
+                    state.set_initial_value(value.eval())
+                else:
+                    # But do for `1 + exp(3)`, or `a + b`
+                    init_var = state.parent().add_variable_allow_renaming(
+                        state.name() + '_init')
+                    init_var.set_rhs(value)
+                    init_var.set_unit(state.unit())
+                    state.set_initial_value(init_var.lhs())
+
         # Valid model always has a time variable
         time = model.time()
 
@@ -793,7 +806,12 @@ class Model(AnnotatableElement):
 
                 # Promote states and set rhs and initial value
                 elif variable.is_state():
-                    v.set_initial_value(variable.initial_value(True))
+                    init = variable.initial_value()
+                    if is_prefixed_number(init):
+                        # Pass in float, in case unit not specified
+                        v.set_initial_value(init.eval())
+                    else:
+                        v.set_initial_value(init.clone(subst=subst))
                     v.set_equation(myokit.Equation(lhs, rhs))
 
                 # Store literals (single number) in initial value
@@ -842,7 +860,7 @@ class Model(AnnotatableElement):
 
         # Create model
         m = myokit.Model(cmodel.name())
-        m.meta['author'] = 'Myokit CellML 2 API'
+        m.meta['mmt_authors'] = 'Myokit CellML 2 API'
 
         # Copy meta data
         for key, value in cmodel.meta.items():
@@ -926,8 +944,9 @@ class Model(AnnotatableElement):
 
                     # Promote states
                     if variable.is_state():
-                        init = variable.initial_value().eval()
-                        v.promote(0 if init is None else init)
+                        init = variable.initial_value()
+                        v.promote(
+                            0 if init is None else init.clone(subst=var_map))
 
                     # Set time variable
                     if variable is voi:
@@ -967,11 +986,11 @@ class Model(AnnotatableElement):
         elif variable not in self._voi._cset:
             voi = self.variable_of_integration()
             raise CellMLError(
-                'Cannot set ' + str(variable) + ' as variable of integration,'
-                ' the variable ' + str(voi) + ' has already been set.')
+                f'Cannot set {variable} as variable of integration, the'
+                f' variable {voi} has already been set.')
 
     def __str__(self):
-        return 'Model[@name="' + self._name + '"]'
+        return f'Model[@name="{self._name}"]'
 
     def units(self):
         """
@@ -1006,7 +1025,7 @@ class Model(AnnotatableElement):
                 free.add(cset)
                 if self._voi not in cset:
                     for var in cset:
-                        warnings.warn('No value set for ' + str(var) + '.')
+                        warnings.warn(f'No value set for {var}.')
 
         # Check that there's at most one free variable.
         if len(free) > 1:
@@ -1015,20 +1034,20 @@ class Model(AnnotatableElement):
         # Check that the variable of integration is a free variable
         voi = self.variable_of_integration()
         if not (voi is None or voi.is_free()):
-            msg = 'Variable of integration ' + str(voi) + ' must be a free'
-            msg += ' variable, but has '
+            msg = (f'Variable of integration {voi} must be a free variable,'
+                   ' but has ')
             if voi.has_equation():
                 var = voi.equation_variable()
                 if voi is var:
                     msg += 'equation.'
                 else:
-                    msg += 'equation (set by ' + str(var) + ').'
+                    msg += f'equation (set by {var}).'
             else:
                 var = voi.initial_value_variable()
                 if voi is var:
                     msg += 'initial value.'
                 else:
-                    msg += 'initial value (set by ' + str(var) + ').'
+                    msg += f'initial value (set by {var}).'
             raise CellMLError(msg)
 
     def variable_of_integration(self):
@@ -1083,7 +1102,7 @@ class Units:
                 'Units name must be a valid CellML identifier.')
         if not predefined and name in self._si_units:
             raise CellMLError(
-                'Units name "' + name + '" overlaps with a predefined name.')
+                f'Units name "{name}" overlaps with a predefined name.')
         self._name = name
 
         # Check and store Myokit unit
@@ -1110,7 +1129,7 @@ class Units:
             # If not raise error (and one that makes sense even if this was
             # called via a model or component units lookup).
             if myokit_unit is None:
-                raise CellMLError('Unknown units name "' + str(name) + '".')
+                raise CellMLError(f'Unknown units name "{name}".')
 
             # Create and store object
             obj = cls(name, myokit_unit, predefined=True)
@@ -1130,7 +1149,7 @@ class Units:
             return cls._si_units_r[myokit_unit]
         except KeyError:
             raise CellMLError(
-                'No name found for myokit unit ' + str(myokit_unit) + '.')
+                f'No name found for myokit unit f{myokit_unit}.')
 
     def myokit_unit(self):
         """
@@ -1189,14 +1208,13 @@ class Units:
                 except KeyError:
                     raise CellMLError(
                         'Units prefix must be a string from the list of known'
-                        ' prefixes or an integer string, got "' + str(prefix)
-                        + '".')
+                        f' prefixes or an integer string, got "{prefix}".')
 
             # Apply prefix to unit
 
             # float(10**309) is the first int that doesn't fit in a float
             if p > 309:
-                raise CellMLError('Unit prefix too large: 10^' + str(p))
+                raise CellMLError(f'Unit prefix too large: 10^{p}')
             unit *= 10**int(p)
 
         # Handle exponent (note: prefix is exponentiated, multiplier is not).
@@ -1205,8 +1223,8 @@ class Units:
 
             if not is_real_number_string(str(exponent).strip()):
                 raise CellMLError(
-                    'Unit exponent must be a real number string, got "'
-                    + str(multiplier) + '"')
+                    'Unit exponent must be a real number string, got'
+                    f' "{multiplier}".')
             e = float(exponent)
 
             # Apply exponent to unit
@@ -1216,8 +1234,8 @@ class Units:
         if multiplier is not None:
             if not is_real_number_string(str(multiplier).strip()):
                 raise CellMLError(
-                    'Unit multiplier must be a real number string, got "'
-                    + str(multiplier) + '"')
+                    'Unit multiplier must be a real number string, got'
+                    f' "{multiplier}".')
             m = float(multiplier)
 
             # Apply multiplier to unit
@@ -1234,7 +1252,7 @@ class Units:
         return cls._si_units.keys()
 
     def __str__(self):
-        return 'Units[@name="' + self._name + '"]'
+        return f'Units[@name="{self._name}"]'
 
     # Predefined units in CellML, name to Unit
     _si_units = {
@@ -1368,8 +1386,8 @@ class Variable(AnnotatableElement):
         except CellMLError:
             raise CellMLError(
                 'Variable units attribute must reference a units element in'
-                ' the model, or one of the predefined units, found "'
-                + str(units) + '".')
+                ' the model, or one of the predefined units, found'
+                f' "{units}".')
 
         # Check and store interfaces
         interfaces = ('none', 'public', 'private', 'public_and_private')
@@ -1398,6 +1416,19 @@ class Variable(AnnotatableElement):
         """
         Returns the equation for this variable (or its connected variable set),
         in the correct units.
+
+        Note that this method is primarily intended to *extract* equations from
+        a CellML model, and care must be taken when using it to manipulate a
+        CellML model. Specifically:
+
+        1. If the equation was not set on this variable, but on a variable in
+           the connected variable set, the returned equation may refer to
+           non-local variables.
+        2. Similarly, if unit conversion is required, the conversion factor may
+           have a unit not defined in this model.
+
+        As a result, calling :meth:`set_equation` with the value returned by
+        :meth:`equation` is not always possible.
         """
         eq = self._cset.equation()
         if eq is None or eq.lhs.var() is self:
@@ -1451,6 +1482,11 @@ class Variable(AnnotatableElement):
         set), in the correct units.
 
         The returned value is a :class:`myokit.Expression`.
+
+        Note that, like :meth:`equation`, this method is primarily intended to
+        *extract* initial values from a CellML model. As a result, the returned
+        value may be a referenced to a variable in another component, and may
+        contain a unit conversion multiplication.
         """
         value = self._cset.initial_value()
         if value is None or self._cset.initial_value_variable() is self:
@@ -1534,6 +1570,9 @@ class Variable(AnnotatableElement):
         value.
 
         If neither is found, ``None`` will be returned.
+
+        Note that the caveats applying to :meth:`equation` and
+        :meth:`initial_value` also apply here.
         """
         eq = self.equation()
         return eq.rhs if eq is not None else self.initial_value()
@@ -1566,8 +1605,7 @@ class Variable(AnnotatableElement):
                     ' of the form `x = ...` or `dx/dt = ...`.')
             if lhs.var() is not self:
                 raise CellMLError(
-                    'Equation for ' + str(lhs.var()) + ' passed to variable '
-                    + str(self) + '.')
+                    f'Equation for f{lhs.var()} passed to variable {self}.')
 
             # Check all references are local
             for ref in lhs.references() | rhs.references():
@@ -1575,7 +1613,7 @@ class Variable(AnnotatableElement):
                 if var._component is not self._component:
                     raise CellMLError(
                         'An equation can only reference variables from the'
-                        ' same component, found: ' + str(var) + '.')
+                        f' same component, found: {var}.')
 
             # Check all units in the RHS are known, and replace numbers
             # without units with numbers in units 'dimensionless'.
@@ -1590,7 +1628,7 @@ class Variable(AnnotatableElement):
                     except CellMLError:
                         raise CellMLError(
                             'All units appearing in a variable\'s RHS must'
-                            ' be known, found: ' + str(x.unit()) + '.')
+                            f' be known, found: {x.unit()}.')
             if numbers_without_units:
                 rhs = rhs.clone(subst=numbers_without_units)
                 equation = myokit.Equation(lhs, rhs)
@@ -1600,31 +1638,71 @@ class Variable(AnnotatableElement):
 
     def set_initial_value(self, value):
         """
-        Sets this variable's intial value (must be a number or ``None``).
+        Sets this variable's intial value: must be a number, a local variable,
+        or ``None``.
+
+        Numbers can be specified as number types, strings, or
+        :class:`myokit.Number` objects (wrapped in prefix plus or minus
+        operators). If a :class:`myokit.Number` is passed in, it should have
+        the same units as this variable. Variables can be passed in as strings
+        or :class:`myokit.Name` objects.
         """
         # Allow unsetting with ``None``
-        if value is not None:
+        if value is None:
+            self._cset.set_initial_value(self, None)
+            return
 
-            # Check value is a real number string
-            if isinstance(value, str):
-                if is_real_number_string(value):
-                    value = float(value)
-                else:
+        # Allow string input
+        if isinstance(value, str):
+            if is_real_number_string(value):
+                value = myokit.Number(value, self._units.myokit_unit())
+            elif is_identifier(value):
+                try:
+                    value = self._component.variable(value)
+                except KeyError:
+                    raise CellMLError('Unknown local variable specified as'
+                                      f' variable initial_value: "{value}".')
+                value = myokit.Name(value)
+            else:
+                raise CellMLError(
+                    'If given, a variable initial_value must be a real number'
+                    f' or the name of a local variable, found "{value}".')
+
+        # Allow expression input
+        elif isinstance(value, myokit.Expression):
+            if is_prefixed_number(value):
+                if self._units.myokit_unit() != value.eval_unit():
                     raise CellMLError(
-                        'If given, a variable initial_value must be a real'
-                        ' number (using variables as initial values is not'
-                        ' supported).')
+                        'If specified as a myokit.Number, an initial value'
+                        ' must have the same units as the variable, found'
+                        f' {value.eval_unit()} for variable in'
+                        f' {self._units.myokit_unit()}.')
+                value = myokit.Number(value.eval(), self._units.myokit_unit())
+            elif isinstance(value, myokit.Name):
+                if value.var()._component is not self._component:
+                    raise CellMLError(
+                        'Non-local variable specified as variable initial'
+                        f' value "{value.var()}".')
             else:
-                value = float(value)
+                raise CellMLError(
+                    'If given, a variable initial_value must be a real number'
+                    f' or a local variable, found {type(value)}.')
 
-            value = myokit.Number(value, self._units.myokit_unit())
+        # Allow numeric input
+        else:
+            try:
+                value = myokit.Number(value, self._units.myokit_unit())
+            except (ValueError, TypeError):
+                raise CellMLError(
+                    'If given, a variable initial_value must be a real number'
+                    f' or a local variable, found "{value}".')
 
         # Store
         self._cset.set_initial_value(self, value)
 
     def __str__(self):
         return (
-            'Variable[@name="' + self._name + '"] in ' + str(self._component))
+            f'Variable[@name="{self._name}"] in {self._component}')
 
     def units(self):
         """
@@ -1705,9 +1783,8 @@ class ConnectedVariableSet:
             equation_variable = set2._equation_variable
         elif set2._equation is not None:
             raise CellMLError(
-                'Multiple equations defined in connected variable set: '
-                + str(set1._equation_variable) + ' and '
-                + str(set2._equation_variable) + '.')
+                'Multiple equations defined in connected variable set:'
+                f' {set1._equation_variable} and {set2._equation_variable}.')
 
         # Get initial value
         initial_value = set1._initial_value
@@ -1717,9 +1794,9 @@ class ConnectedVariableSet:
             initial_value_variable = set2._initial_value_variable
         elif set2._initial_value is not None:
             raise CellMLError(
-                'Multiple initial values defined in connected variable set: '
-                + str(set1._initial_value_variable) + ' and '
-                + str(set2._initial_value_variable) + '.')
+                'Multiple initial values defined in connected variable set:'
+                f' {set1._initial_value_variable} and'
+                f' {set2._initial_value_variable}.')
 
         # Create new set
         cset = ConnectedVariableSet()
@@ -1741,8 +1818,8 @@ class ConnectedVariableSet:
         if self._equation_variable not in (variable, None):
             raise CellMLError(
                 'Unable to change equation: the equation in this connected'
-                ' variable set is already defined by '
-                + str(self._equation_variable) + '.')
+                ' variable set is already defined by'
+                f' {self._equation_variable}.')
 
         # Update
         self._equation = equation
@@ -1750,14 +1827,14 @@ class ConnectedVariableSet:
 
     def set_initial_value(self, variable, value=None):
         """
-        Sets the ``initial_value`` for this variable set, as defined for
+        Sets the ``initial_value`` for this variable set, as defined in
         ``variable``.
         """
         if self._initial_value_variable not in (variable, None):
             raise CellMLError(
                 'Unable to change initial value: the initial value in this'
-                ' connected variable set is already defined by '
-                + str(self._initial_value_variable) + '.')
+                ' connected variable set is already defined by'
+                f' {self._initial_value_variable}.')
 
         # Update
         self._initial_value = value
@@ -1774,13 +1851,12 @@ class ConnectedVariableSet:
         if isinstance(self._equation.lhs, myokit.Derivative):
             if self._initial_value is None:
                 raise CellMLError(
-                    'No initial value set for state variable '
-                    + str(self._equation_variable) + '.')
+                    'No initial value set for state variable'
+                    f' {self._equation_variable}.')
         elif self._initial_value is not None:
-            msg = 'Overdefined variable: ' + str(self._equation_variable)
-            msg += ' has both a (non-ODE) equation and an initial value'
+            msg = (f'Overdefined variable: {self._equation_variable} has both'
+                   ' a (non-ODE) equation and an initial value')
             if self._initial_value_variable is not self._equation_variable:
-                msg += ' (set by ' + str(self._initial_value_variable) + ')'
-            msg += '.'
-            raise CellMLError(msg)
+                msg += f' (set by {self._initial_value_variable})'
+            raise CellMLError(f'{msg}.')