myokit 1.35.4__py3-none-any.whl → 1.36.1__py3-none-any.whl

myokit/_sim/cvodessim.py

@@ -238,6 +238,7 @@ class Simulation(myokit.CModule):
 
         # Last state reached before error
         self._error_state = None
+        self._error_inputs = None
 
         # Starting time
         self._time = 0
@@ -387,6 +388,28 @@ class Simulation(myokit.CModule):
         finally:
             myokit.tools.rmtree(d_build, silent=True)
 
+    def crash_inputs(self):
+        """
+        If the last call to :meth:`Simulation.pre()` or
+        :meth:`Simulation.run()` resulted in an error, this will return the
+        last "inputs" (time, pace, etc) reached during that simulation.
+
+        Will return ``None`` if no simulation was run or the simulation did not
+        result in an error.
+        """
+        return dict(self._error_inputs) if self._error_inputs else None
+
+    def crash_state(self):
+        """
+        If the last call to :meth:`Simulation.pre()` or
+        :meth:`Simulation.run()` resulted in an error, this will return the
+        last state reached during that simulation.
+
+        Will return ``None`` if no simulation was run or the simulation did not
+        result in an error.
+        """
+        return list(self._error_state) if self._error_state else None
+
     def default_state(self):
         """
         Returns the default state.
@@ -402,60 +425,83 @@ class Simulation(myokit.CModule):
             return [list(x) for x in self._s_default_state]
         return None
 
-    def last_state(self):
+    def eval_derivatives(self, y=None, pacing=None):
         """
-        If the last call to :meth:`Simulation.pre()` or
-        :meth:`Simulation.run()` resulted in an error, this will return the
-        last state reached during that simulation.
+        Deprecated alias of :meth:`evaluate_derivatives`.
 
-        Will return ``None`` if no simulation was run or the simulation did not
-        result in an error.
+        Note that while :meth:`eval_derivatives` used the :meth:`state()` as
+        default, the new method uses :meth:`default_state()`.
         """
-        return list(self._error_state) if self._error_state else None
+        # Deprecated on 2024-03-08
+        import warnings
+        warnings.warn(
+            'The method `myokit.Simulation.eval_derivatives` is deprecated,'
+            ' please use `evaluate_derivatives(state=sim.state())` instead.'
+        )
+        if y is None:
+            y = self.state()
+        return self.evaluate_derivatives(y, pacing)
 
-    def eval_derivatives(self, y=None, pacing=None):
+    def evaluate_derivatives(self, state=None, inputs=None):
         """
-        Evaluates and returns the state derivatives.
+        Evaluates and returns the state derivatives for the given ``state`` and
+        ``inputs``.
+
+        If no ``state`` is given, the value returned by :meth:`default_state()`
+        is used.
 
-        The state to evaluate for can be given as ``y``. If no state is given
-        the current simulation state is used.
+        An optional dict ``inputs`` can be passed in to set the values of
+        time and other inputs (e.g. pacing values). If "time" is not set in
+        ``inputs``, the value 0 will be used, regardless of the current
+        simulation. Similarly, if pacing values are not set in ``inputs``, 0
+        will be used regardless of the protocols or the current time.
 
-        An optional dict ``pacing`` can be passed in that maps labels to
-        numerical values. If a label is used but not provided in ``pacing``,
-        it's value will be set to 0.
+        If any variables have been changed with `set_constant` their new value
+        will be used.
         """
         # Get state
-        if y is None:
-            y = list(self._state)
+        if state is None:
+            y = list(self._default_state)
         else:
-            y = self._model.map_to_state(y)
+            y = self._model.map_to_state(state)
 
+        # Get inputs
+        time = realtime = evaluations = 0
         pacing_values = [0.0] * len(self._pacing_labels)
-        if pacing is not None:
-            for k, v in pacing.items():
+        if inputs is not None:
+            if 'time' in inputs:
+                time = float(inputs['time'])
+                del inputs['time']
+            if 'realtime' in inputs:  # User really shouldn't, but can do this
+                realtime = float(inputs['realtime'])
+                del inputs['realtime']
+            if 'evaluations' in inputs:
+                evaluations = float(inputs['evaluations'])
+                del inputs['evaluations']
+            for k, v in inputs.items():
                 try:
                     ki = self._pacing_labels.index(k)
-                    pacing_values[ki] = float(v)
                 except ValueError:
-                    pass
+                    raise ValueError(f'Unknown binding or pacing label `{k}`.')
+                pacing_values[ki] = float(v)
+
+        # Literals and parameters: Can be changed with set_constant
+        literals = list(self._literals.values())
+        parameters = list(self._parameters.values())
 
         # Create space to store derivatives
         dy = list(self._state)
 
         # Evaluate and return
-        self._sim.eval_derivatives(
-            # 0. Time
-            0,
-            # 1. Pace
-            pacing_values,
-            # 2. State
-            y,
-            # 3. Space to store the state derivatives
-            dy,
-            # 4. Literal values
-            list(self._literals.values()),
-            # 5. Parameter values
-            list(self._parameters.values()),
+        self._sim.evaluate_derivatives(
+            time,               # 0. Time
+            pacing_values,      # 1. Pacing values
+            realtime,           # 2. Realtime
+            evaluations,        # 3. Evaluations
+            literals,           # 4. Literals
+            parameters,         # 5. Parameters
+            y,                  # 6. State
+            dy,                 # 7. Derivatives (out)
         )
         return dy
 
@@ -473,6 +519,21 @@ class Simulation(myokit.CModule):
         """
         return self._sim.number_of_steps()
 
+    def last_state(self):
+        """
+        If the last call to :meth:`Simulation.pre()` or
+        :meth:`Simulation.run()` resulted in an error, this will return the
+        last state reached during that simulation.
+
+        Will return ``None`` if no simulation was run or the simulation did not
+        result in an error.
+        """
+        # Deprecated on 2024-03-08
+        import warnings
+        warnings.warn('The method `myokit.Simulation.last_state` is'
+                      ' deprecated. Please use `crash_state` instead.')
+        return self.crash_state()
+
     def pre(self, duration, progress=None, msg='Pre-pacing simulation'):
         """
         This method can be used to perform an unlogged simulation, typically to
@@ -690,6 +751,7 @@ class Simulation(myokit.CModule):
 
         # Reset error state
         self._error_state = None
+        self._error_inputs = None
 
         # Simulation times
         if duration < 0:
@@ -847,26 +909,28 @@ class Simulation(myokit.CModule):
 
                 # Store error state
                 self._error_state = state
+                self._error_inputs = {'time': bound[0]}
+                for i, label in enumerate(('realtime', 'evaluations')):
+                    if self._model.binding(label) is not None:
+                        self._error_inputs[label] = bound[1 + i]
+                for i, label in enumerate(self._pacing_labels):
+                    self._error_inputs[label] = bound[3 + i]
 
                 # Create long error message
                 txt = ['A numerical error occurred during simulation at'
-                       ' t = ' + str(t) + '.', 'Last reached state: ']
+                       ' t = ' + myokit.float.str(bound[0]) + '.',
+                       'Last reached state: ']
                 txt.extend(['  ' + x for x
                             in self._model.format_state(state).splitlines()])
                 txt.append('Inputs for binding:')
-                txt.append('  time        = ' + myokit.float.str(bound[0]))
-                txt.append('  realtime    = ' + myokit.float.str(bound[1]))
-                txt.append('  evaluations = ' + myokit.float.str(bound[2]))
-                for i, label in enumerate(self._pacing_labels):
-                    txt.append(
-                        '  ' + label + ' = ' + myokit.float.str(bound[3 + i])
-                    )
+                for key, value in self._error_inputs.items():
+                    txt.append(f'  {key} = {myokit.float.str(value)}')
                 txt.append(str(e))
 
                 # Check if state derivatives can be evaluated in Python, if
                 # not, add the error to the error message.
                 try:
-                    self._model.evaluate_derivatives(state)
+                    self._model.evaluate_derivatives(state, self._error_inputs)
                 except Exception as en:
                     txt.append(str(en))
 

myokit/_sim/mcl.h

@@ -651,6 +651,9 @@ PyObject* mcl_info_device_dict(cl_device_id device_id, size_t bufsize, char* buf
     }
 
     // Name
+    #ifdef MYOKIT_DEBUG_MESSAGES
+    printf("  Querying name\n");
+    #endif
     flag = clGetDeviceInfo(device_id, CL_DEVICE_NAME, bufsize, buffer, NULL);
     if(mcl_flag(flag)) { Py_DECREF(device); return NULL; }
     val = PyUnicode_FromString(buffer);
@@ -658,6 +661,9 @@ PyObject* mcl_info_device_dict(cl_device_id device_id, size_t bufsize, char* buf
     Py_CLEAR(val);
 
     // Vendor
+    #ifdef MYOKIT_DEBUG_MESSAGES
+    printf("  Querying vendor\n");
+    #endif
     flag = clGetDeviceInfo(device_id, CL_DEVICE_VENDOR, bufsize, buffer, NULL);
     if(mcl_flag(flag)) { Py_DECREF(device); return NULL; }
     val = PyUnicode_FromString(buffer);
@@ -665,6 +671,9 @@ PyObject* mcl_info_device_dict(cl_device_id device_id, size_t bufsize, char* buf
     Py_CLEAR(val);
 
     // Device version
+    #ifdef MYOKIT_DEBUG_MESSAGES
+    printf("  Querying device version\n");
+    #endif
     flag = clGetDeviceInfo(device_id, CL_DEVICE_VERSION, bufsize, buffer, NULL);
     if(mcl_flag(flag)) { Py_DECREF(device); return NULL; }
     val = PyUnicode_FromString(buffer);
@@ -672,6 +681,9 @@ PyObject* mcl_info_device_dict(cl_device_id device_id, size_t bufsize, char* buf
     Py_CLEAR(val);
 
     // Driver version
+    #ifdef MYOKIT_DEBUG_MESSAGES
+    printf("  Querying driver version\n");
+    #endif
     flag = clGetDeviceInfo(device_id, CL_DRIVER_VERSION, bufsize, buffer, NULL);
     if(mcl_flag(flag)) { Py_DECREF(device); return NULL; }
     val = PyUnicode_FromString(buffer);
@@ -679,6 +691,9 @@ PyObject* mcl_info_device_dict(cl_device_id device_id, size_t bufsize, char* buf
     Py_CLEAR(val);
 
     // Clock speed (MHz)
+    #ifdef MYOKIT_DEBUG_MESSAGES
+    printf("  Querying clock speed\n");
+    #endif
     flag = clGetDeviceInfo(device_id, CL_DEVICE_MAX_CLOCK_FREQUENCY, sizeof(buf_uint), &buf_uint, NULL);
     if(mcl_flag(flag)) { Py_DECREF(device); return NULL; }
     val = PyLong_FromUnsignedLong(buf_uint);
@@ -686,6 +701,9 @@ PyObject* mcl_info_device_dict(cl_device_id device_id, size_t bufsize, char* buf
     Py_CLEAR(val);
 
     // Global memory (bytes)
+    #ifdef MYOKIT_DEBUG_MESSAGES
+    printf("  Querying global memory size\n");
+    #endif
     flag = clGetDeviceInfo(device_id, CL_DEVICE_GLOBAL_MEM_SIZE, sizeof(buf_ulong), &buf_ulong, NULL);
     if(mcl_flag(flag)) { Py_DECREF(device); return NULL; }
     val = PyLong_FromUnsignedLongLong(buf_ulong);
@@ -693,6 +711,9 @@ PyObject* mcl_info_device_dict(cl_device_id device_id, size_t bufsize, char* buf
     Py_CLEAR(val);
 
     // Local memory (bytes)
+    #ifdef MYOKIT_DEBUG_MESSAGES
+    printf("  Querying local memory size\n");
+    #endif
     flag = clGetDeviceInfo(device_id, CL_DEVICE_LOCAL_MEM_SIZE, sizeof(buf_ulong), &buf_ulong, NULL);
     if(mcl_flag(flag)) { Py_DECREF(device); return NULL; }
     val = PyLong_FromUnsignedLongLong(buf_ulong);
@@ -700,6 +721,9 @@ PyObject* mcl_info_device_dict(cl_device_id device_id, size_t bufsize, char* buf
     Py_CLEAR(val);
 
     // Const memory (bytes)
+    #ifdef MYOKIT_DEBUG_MESSAGES
+    printf("  Querying max buffer size\n");
+    #endif
     flag = clGetDeviceInfo(device_id, CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE, sizeof(buf_ulong), &buf_ulong, NULL);
     if(mcl_flag(flag)) { Py_DECREF(device); return NULL; }
     val = PyLong_FromUnsignedLongLong(buf_ulong);
@@ -707,6 +731,9 @@ PyObject* mcl_info_device_dict(cl_device_id device_id, size_t bufsize, char* buf
     Py_CLEAR(val);
 
     // Computing units
+    #ifdef MYOKIT_DEBUG_MESSAGES
+    printf("  Querying max computing units\n");
+    #endif
     flag = clGetDeviceInfo(device_id, CL_DEVICE_MAX_COMPUTE_UNITS, sizeof(buf_uint), &buf_uint, NULL);
     if(mcl_flag(flag)) { Py_DECREF(device); return NULL; }
     val = PyLong_FromUnsignedLong(buf_uint);
@@ -714,6 +741,9 @@ PyObject* mcl_info_device_dict(cl_device_id device_id, size_t bufsize, char* buf
     Py_CLEAR(val);
 
     // Max workgroup size
+    #ifdef MYOKIT_DEBUG_MESSAGES
+    printf("  Querying max work group size\n");
+    #endif
     flag = clGetDeviceInfo(device_id, CL_DEVICE_MAX_WORK_GROUP_SIZE, sizeof(buf_size_t), &buf_size_t, NULL);
     if(mcl_flag(flag)) { Py_DECREF(device); return NULL; }
     val = PyLong_FromSize_t(buf_size_t);
@@ -721,6 +751,9 @@ PyObject* mcl_info_device_dict(cl_device_id device_id, size_t bufsize, char* buf
     Py_CLEAR(val);
 
     // Max workitem sizes
+    #ifdef MYOKIT_DEBUG_MESSAGES
+    printf("  Querying max work item sizes\n");
+    #endif
     flag = clGetDeviceInfo(device_id, CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS, sizeof(buf_uint), &buf_uint, NULL);
     if(mcl_flag(flag)) { Py_DECREF(device); return NULL; }
     val = PyLong_FromUnsignedLong(buf_uint);
@@ -739,6 +772,9 @@ PyObject* mcl_info_device_dict(cl_device_id device_id, size_t bufsize, char* buf
     Py_CLEAR(items_sizes_tuple);
 
     // Maximum size of a kernel parameter
+    #ifdef MYOKIT_DEBUG_MESSAGES
+    printf("  Querying maximum kernel parameter size\n");
+    #endif
     flag = clGetDeviceInfo(device_id, CL_DEVICE_MAX_PARAMETER_SIZE, sizeof(buf_size_t), &buf_size_t, NULL);
     if(mcl_flag(flag)) { Py_DECREF(device); return NULL; }
     val = PyLong_FromSize_t(buf_size_t);
@@ -834,29 +870,47 @@ mcl_info(void)
 
     // Check all platforms
     for (i=0; i<n_platforms; i++) {
+        #ifdef MYOKIT_DEBUG_MESSAGES
+        printf("Checking platform %u\n", (unsigned int)i);
+        #endif
 
         // Create platform dict
         platform = mcl_info_platform_dict(platform_ids[i], sizeof(buffer), buffer);
         if (platform == NULL) { Py_DECREF(platforms); return NULL; }
+        #ifdef MYOKIT_DEBUG_MESSAGES
+        printf("  Obtained platform info dict.\n");
+        #endif
 
         // Count devices
         flag = clGetDeviceIDs(platform_ids[i], CL_DEVICE_TYPE_ALL, MCL_MAX_DEVICES, device_ids, &n_devices);
         if (flag == CL_DEVICE_NOT_FOUND) {
             n_devices = 0;
+        } else if (flag == CL_INVALID_VALUE) {
+            // This seems to happen on Mac OS 14.4.1
+            n_devices = 0;
         } else if (mcl_flag(flag)) {
             Py_DECREF(platforms);
             return NULL;
         }
+        #ifdef MYOKIT_DEBUG_MESSAGES
+        printf("  Found %u devices.\n", (unsigned int)n_devices);
+        #endif
 
         // Create devices tuple, must decref on exception
         devices = PyTuple_New((size_t)n_devices);
 
         // Add devices
         for (j=0; j<n_devices; j++) {
+            #ifdef MYOKIT_DEBUG_MESSAGES
+            printf("    Checking device %u\n", (unsigned int)j);
+            #endif
 
             // Create device dict, must decref on exception
             device = mcl_info_device_dict(device_ids[j], sizeof(buffer), buffer);
             if (device == NULL) { Py_DECREF(platforms); Py_DECREF(devices); return NULL; }
+            #ifdef MYOKIT_DEBUG_MESSAGES
+            printf("    Obtained device info dict.\n");
+            #endif
 
             // Add device to devices tuple (steals reference)
             PyTuple_SetItem(devices, j, device);

myokit/formats/__init__.py

@@ -24,6 +24,9 @@ _EWRITERS = None
 class Exporter:
     """
     Abstract base class for exporters.
+
+    An exporter is a class that can produce model code or runnable code from a
+    Myokit model or a model & protocol combination (runnable).
     """
     def __init__(self):
         super().__init__()
@@ -106,15 +109,46 @@ def exporters():
 
 class ExpressionWriter:
     """
-    Base class for expression writers, that take myokit expressions as input
-    and convert them to text or other formats.
+    Base class for expression writers.
+
+    Expression writers take :class:`myokit.Expression` objects and produce code
+    in some language other than Myokit.
+
+    When implementing an expression writer, there are a few important edge
+    cases to consider:
+
+    1. Simplifications must not be made at this stage. For example, if the user
+       writes "+1" instead of "1", the code should output "+1". If
+       simplifications are desired, these should be made at an earlier stage,
+       when everything is still in symbolic form.
+
+    2. Powers (exponentiation) can be left or right-associative. In Myokit and,
+       for example, in Matlab, the expression ``a^b^c`` is interpreted as
+       ``(a^b)^c``. By in Python (and e.g. in many spreadsheet applications)
+       ``a**b**c`` is interpreted as ``a**(b**c)``, necessitating a different
+       bracket-adding logic than used in Myokit.
+
+    3. Binary operators are sometimes implemented as n-ary operators. In
+       Myokit, ``0 == 0 == 0`` is a sequence of two binary operators,
+       interpreted as ``(0 == 0) == 0``. Because ``(0 == 0)`` evaluates to
+       ``1``, this expression returns ``0`` (1 does not equal 0). In Python,
+       the expression ``0 == 0 == 0`` is a ternary (n-ary) operator,
+       interpreted as ``all_equal(0, 0, 0)``, which evaluates to ``1``. For
+       languages that use this convention, extra brackets must be added.
+
+    4. Myokit does not have increment or decrement operators ``--`` and ``++``,
+       so the expression ``--x`` is interpreted as ``-(-x)``. This is the same
+       in Python. But in C-based languages, this is interpreted as a decrement
+       operator so care must be taken to add extra brackets.
+
     """
     def __init__(self):
         self._op_map = self._build_op_map()
 
     def _build_op_map(self):
         """
-        Returns a mapping from myokit operators to lambda functions on expr.
+        Returns a mapping from Myokit operators to lambda functions on
+        expressions.
         """
         return {
             myokit.Name: self._ex_name,
@@ -158,15 +192,11 @@ class ExpressionWriter:
         }
 
     def eq(self, q):
-        """
-        Converts an equation to a string
-        """
+        """ Converts a :class:`myokit.Equation` to a string. """
         return self.ex(q.lhs) + ' = ' + self.ex(q.rhs)
 
     def ex(self, e):
-        """
-        Converts an Expression to a string.
-        """
+        """ Converts a :class:`myokit.Expression` to a string. """
         t = type(e)
         if t not in self._op_map:   # pragma: no cover
             raise ValueError('Unknown expression type: ' + str(t))
@@ -188,9 +218,17 @@ class ExpressionWriter:
         raise NotImplementedError
 
     def _ex_prefix_plus(self, e):
+        #
+        # Note: Spaces or brackets should be used in languages where ++ is an
+        #       operator
+        #
         raise NotImplementedError
 
     def _ex_prefix_minus(self, e):
+        #
+        # Note: Spaces or brackets should be used in languages where -- is an
+        #       operator
+        #
         raise NotImplementedError
 
     def _ex_plus(self, e):
@@ -212,6 +250,10 @@ class ExpressionWriter:
         raise NotImplementedError
 
     def _ex_power(self, e):
+        #
+        # Note: Most languages agree that -a**b means -(a**b)
+        #       https://codeplea.com/exponentiation-associativity-options
+        #
         raise NotImplementedError
 
     def _ex_sqrt(self, e):
@@ -239,6 +281,11 @@ class ExpressionWriter:
         raise NotImplementedError
 
     def _ex_log(self, e):
+        #
+        # Log can have 1 or 2 arguments. If the language does not support
+        # 2-argument log, use (log(a) / log(b)), including the outer
+        # brackets (because a function is expected, which is never bracketed).
+        #
         raise NotImplementedError
 
     def _ex_log10(self, e):
@@ -253,10 +300,11 @@ class ExpressionWriter:
     def _ex_abs(self, e):
         raise NotImplementedError
 
-    def _ex_not(self, e):
-        raise NotImplementedError
-
     def _ex_equal(self, e):
+        #
+        # To obtain the desired `(0 == 0) == 0` behaviour, this and other
+        # conditions are best rendered with brackets.
+        #
         raise NotImplementedError
 
     def _ex_not_equal(self, e):
@@ -280,6 +328,9 @@ class ExpressionWriter:
     def _ex_or(self, e):
         raise NotImplementedError
 
+    def _ex_not(self, e):
+        raise NotImplementedError
+
     def _ex_if(self, e):
         raise NotImplementedError
 

myokit/formats/ansic/__init__.py

@@ -5,7 +5,7 @@
 # See http://myokit.org for copyright, sharing, and licensing details.
 #
 from ._exporter import AnsiCExporter, AnsiCCableExporter, AnsiCEulerExporter
-from ._ewriter import AnsiCExpressionWriter
+from ._ewriter import AnsiCExpressionWriter, CBasedExpressionWriter  # noqa
 
 
 # Importers
@@ -28,6 +28,7 @@ def exporters():
 # Expression writers
 _ewriters = {
     'ansic': AnsiCExpressionWriter,
+    # c-based is intended as base class only
 }