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

myokit/_model_api.py

@@ -1385,9 +1385,7 @@ class Model(ObjectWithMeta, VarProvider):
     def eval_state_derivatives(
             self, state=None, inputs=None, precision=myokit.DOUBLE_PRECISION,
             ignore_errors=False):
-        """
-        Deprecated alias of :meth:`evaluate_derivatives()`.
-        """
+        """ Deprecated alias of :meth:`evaluate_derivatives()`. """
         # Deprecated since 2021-08-03
         import warnings
         warnings.warn(

myokit/_myokit_version.py

@@ -14,7 +14,7 @@ __release__ = True
 #    incompatibility
 #  - Changes to revision indicate bugfixes, tiny new features
 #  - There is no significance to odd/even numbers
-__version_tuple__ = 1, 35, 0
+__version_tuple__ = 1, 35, 2
 
 # String version of the version number
 __version__ = '.'.join([str(x) for x in __version_tuple__])

myokit/_protocol.py

@@ -746,9 +746,10 @@ class PacingSystem:
     >>> pace = np.array([s.advance(t) for t in time])
 
     """
-    def __init__(self, protocol):
-        # The current time and pacing level
-        self._time = 0
+    def __init__(self, protocol, initial_time=0):
+        # The initial and current time and pacing level
+        self._initial_time = initial_time  # Needed if we add a reset()
+        self._time = initial_time
         self._pace = 0
 
         # Currently active event
@@ -758,15 +759,15 @@ class PacingSystem:
         self._tdown = None
 
         # The next time the pacing variable changes
-        self._tnext = 0
+        self._tnext = initial_time
 
         # Create a copy of the protocol
         self._protocol = protocol.clone()
         #TODO: For periodic events, set an _t0, and a _i, use them to calculate
         #      the next occurence
 
-        # Advance to time zero
-        self.advance(0)
+        # Advance to initial time
+        self.advance(initial_time)
 
     def advance(self, new_time):
         """
@@ -822,21 +823,15 @@ class PacingSystem:
         return self._pace
 
     def next_time(self):
-        """
-        Returns the next time the pacing system will halt at.
-        """
+        """ Returns the next time the pacing system will halt at. """
         return self._tnext
 
     def pace(self):
-        """
-        Returns the current value of the pacing variable.
-        """
+        """ Returns the current value of the pacing variable. """
         return self._pace
 
     def time(self):
-        """
-        Returns the current time in the pacing system.
-        """
+        """ Returns the current time in the pacing system. """
         return self._time
 
 
@@ -863,7 +858,6 @@ class TimeSeriesProtocol:
     Protocols can be compared with ``==``, which will check if the sequence of
     time value pairs is the same, and the interpolation method is the same.
     Protocols can be serialized with ``pickle``.
-
     """
 
     def __init__(self, times, values, method=None):
@@ -909,15 +903,11 @@ class TimeSeriesProtocol:
         self._method = values['method']
 
     def clone(self):
-        """
-        Returns a clone of this protocol.
-        """
+        """ Returns a clone of this protocol. """
         return TimeSeriesProtocol(self._times, self._values, self._method)
 
     def pace(self, t):
-        """
-        Returns the value of the pacing variable at time ``t``.
-        """
+        """ Returns the value of the pacing variable at time ``t``. """
         if t < self._times[0]:
             return self._values[0]
         if t > self._times[-1]:
@@ -930,13 +920,9 @@ class TimeSeriesProtocol:
         ) / (self._times[i + 1] - self._times[i])
 
     def times(self):
-        """
-        Returns a list of the times in this protocol.
-        """
+        """ Returns a list of the times in this protocol. """
         return self._times
 
     def values(self):
-        """
-        Returns a list of the values in this protocol.
-        """
+        """ Returns a list of the values in this protocol. """
         return self._values

myokit/_sim/cable.c

@@ -414,7 +414,7 @@ print(tab + '}')
     }
 
     /* Set up pacing */
-    pacing = ESys_Create(&flag_pacing);
+    pacing = ESys_Create(tmin, &flag_pacing);
     if (flag_pacing!=ESys_OK) { ESys_SetPyErr(flag_pacing); return sim_clean(); }
     flag_pacing = ESys_Populate(pacing, protocol);
     if (flag_pacing!=ESys_OK) { ESys_SetPyErr(flag_pacing); return sim_clean(); }

myokit/_sim/cable.py

@@ -35,11 +35,12 @@ class Simulation1d(myokit.CModule):
     ``time``
         The simulation time
     ``pace``
-        The pacing level, this is set if a protocol was passed in.
+        The pacing level, this is set if a protocol was passed in. Will be set
+        to 0 if no protocol is provided.
     ``diffusion_current``
         The current flowing from the cell to its neighbors. This will be
         positive when the cell is acting as a source, negative when it is
-        acting as a sink.
+        acting as a sink. Will be set to 0 if no connections are made.
 
     The variable ``time`` is set globally, meaning each cell uses the same
     value. The variables ``pace`` and ``diffusion_current`` have different

myokit/_sim/cmodel.h

@@ -482,6 +482,7 @@ Model_SetupPacing(Model model, int n_pace)
     /* Clear values */
     for (int i = 0; i < n_pace; i++) {
         model->pace_values[i] = 0;
+        /* Note: This will be overruled by the first call to SetBoundVariables */
     }
 
     return Model_OK;

myokit/_sim/cvodessim.c

@@ -192,15 +192,7 @@ Model model;        /* A model object */
 /*
  * Pacing
  */
-union PSys {
-    ESys event;
-    FSys fixed;
-};
-enum PSysType {
-    EVENT,
-    FIXED
-};
-union PSys *pacing_systems;   /* Array of pacing system (event or fixed) */
+union PSys *pacing_systems;   /* Array of pacing systems (event based or time series) */
 enum PSysType *pacing_types;  /* Array of pacing system types */
 PyObject *protocols;          /* The protocols used to generate the pacing systems */
 double* pacing;               /* Pacing values, same size as pacing_systems and pacing_types */
@@ -351,16 +343,16 @@ benchmarker_print(char* message)
 int
 rhs(realtype t, N_Vector y, N_Vector ydot, void *user_data)
 {
-    FSys_Flag flag_fpacing;
+    TSys_Flag flag_fpacing;
     UserData fdata;
     int i;
 
-    /* Fixed-form pacing? Then look-up correct value of pacing variable */
+    /* Time-series pacing? Then look-up correct value of pacing variable */
     for (int i = 0; i < n_pace; i++) {
-        if (pacing_types[i] == FIXED) {
-            pacing[i] = FSys_GetLevel(pacing_systems[i].fixed, t, &flag_fpacing);
-            if (flag_fpacing != FSys_OK) { /* This should never happen */
-                FSys_SetPyErr(flag_fpacing);
+        if (pacing_types[i] == TSys_TYPE) {
+            pacing[i] = TSys_GetLevel(pacing_systems[i].tsys, t, &flag_fpacing);
+            if (flag_fpacing != TSys_OK) { /* This should never happen */
+                TSys_SetPyErr(flag_fpacing);
                 return -1;  /* Negative value signals irrecoverable error to CVODE */
             }
         }
@@ -441,6 +433,9 @@ sim_clean(void)
         #endif
 
         /* CVode arrays */
+        #ifdef MYOKIT_DEBUG_MESSAGES
+        printf("CM ..Sundials vectors.\n");
+        #endif
         if (y != NULL) { N_VDestroy_Serial(y); y = NULL; }
         if (ylast != NULL) { N_VDestroy_Serial(ylast); ylast = NULL; }
         if (sy != NULL) { N_VDestroyVectorArray(sy, model->ns_independents); sy = NULL; }
@@ -450,9 +445,15 @@ sim_clean(void)
         }
 
         /* Root finding results */
+        #ifdef MYOKIT_DEBUG_MESSAGES
+        printf("CM ..Root-finding results.\n");
+        #endif
         free(rf_direction); rf_direction = NULL;
 
         /* Sundials objects */
+        #ifdef MYOKIT_DEBUG_MESSAGES
+        printf("CM ..Sundials objects.\n");
+        #endif
         CVodeFree(&cvode_mem); cvode_mem = NULL;
         #if SUNDIALS_VERSION_MAJOR >= 3
         SUNLinSolFree(sundense_solver); sundense_solver = NULL;
@@ -463,6 +464,9 @@ sim_clean(void)
         #endif
 
         /* User data and parameter scale array*/
+        #ifdef MYOKIT_DEBUG_MESSAGES
+        printf("CM ..Sundials user-data.\n");
+        #endif
         free(pbar);
         if (udata != NULL) {
             free(udata->p);
@@ -470,11 +474,15 @@ sim_clean(void)
         }
 
         /* Pacing systems */
+        #ifdef MYOKIT_DEBUG_MESSAGES
+        printf("CM ..Pacing systems.\n");
+        #endif
         for (int i = 0; i < n_pace; i++) {
-            if (pacing_types[i] == FIXED) {
-                FSys_Destroy(pacing_systems[i].fixed);
-            } else if (pacing_types[i] == EVENT) {
-                ESys_Destroy(pacing_systems[i].event);
+            // Note: Type is ESys, TSys, or not set!
+            if (pacing_types[i] == ESys_TYPE) {
+                ESys_Destroy(pacing_systems[i].esys);
+            } else if (pacing_types[i] == TSys_TYPE) {
+                TSys_Destroy(pacing_systems[i].tsys);
             }
         }
         free(pacing_systems); pacing_systems = NULL;
@@ -482,6 +490,9 @@ sim_clean(void)
         free(pacing); pacing = NULL;
 
         /* CModel */
+        #ifdef MYOKIT_DEBUG_MESSAGES
+        printf("CM ..CModel.\n");
+        #endif
         Model_Destroy(model); model = NULL;
 
         /* Benchmarking and profiling */
@@ -508,6 +519,10 @@ sim_clean(void)
 PyObject*
 sim_cleanx(PyObject* ex_type, const char* msg, ...)
 {
+    #ifdef MYOKIT_DEBUG_MESSAGES
+    printf("CM Entering sim_cleanx.\n");
+    #endif
+
     va_list argptr;
     char errstr[1024];
 
@@ -544,11 +559,11 @@ sim_init(PyObject *self, PyObject *args)
     int flag_cvode;
     Model_Flag flag_model;
     ESys_Flag flag_epacing;
-    FSys_Flag flag_fpacing;
+    TSys_Flag flag_fpacing;
 
     /* Pacing systems */
     ESys epacing;
-    FSys fpacing;
+    TSys fpacing;
 
     /* General purpose ints for iterating */
     int i, j;
@@ -618,7 +633,7 @@ sim_init(PyObject *self, PyObject *args)
             &bound_py,          /*  4. List: store final bound variables here */
             &literals,          /*  5. List: literal constant values */
             &parameters,        /*  6. List: parameter values */
-            &protocols,         /*   7. Event-based or fixed protocols */
+            &protocols,         /*  7. Event-based or time series protocols */
             &log_dict,          /*  8. DataLog */
             &log_interval,      /*  9. Float: log interval, or 0 */
             &log_times,         /* 10. List of logging times, or None */
@@ -955,6 +970,9 @@ sim_init(PyObject *self, PyObject *args)
      */
     n_pace = 0;
     if (protocols != Py_None) {
+        #ifdef MYOKIT_DEBUG_MESSAGES
+        printf("CM Initialising pacing systems\n");
+        #endif
         if (!PyList_Check(protocols)) {
             return sim_cleanx(PyExc_TypeError, "'protocols' must be a list.");
         }
@@ -980,43 +998,61 @@ sim_init(PyObject *self, PyObject *args)
     tnext = tmax;
 
     /*
-     * Set up event-based and/or fixed pacing.
+     * Set up event-based and/or time-series pacing.
      */
     if (protocols != Py_None) {
         for (int i = 0; i < PyList_Size(protocols); i++) {
             PyObject *protocol = PyList_GetItem(protocols, i);
             const char* protocol_type_name = Py_TYPE(protocol)->tp_name;
             if (strcmp(protocol_type_name, "Protocol") == 0) {
-                pacing_systems[i].event = ESys_Create(&flag_epacing);
-                pacing_types[i] = EVENT;
-                epacing = pacing_systems[i].event;
+
+                epacing = ESys_Create(tmin, &flag_epacing);
                 if (flag_epacing != ESys_OK) { ESys_SetPyErr(flag_epacing); return sim_clean(); }
+                pacing_systems[i].esys = epacing;
+                pacing_types[i] = ESys_TYPE;
+
                 flag_epacing = ESys_Populate(epacing, protocol);
                 if (flag_epacing != ESys_OK) { ESys_SetPyErr(flag_epacing); return sim_clean(); }
+
                 flag_epacing = ESys_AdvanceTime(epacing, tmin);
                 if (flag_epacing != ESys_OK) { ESys_SetPyErr(flag_epacing); return sim_clean(); }
+
                 t_proposed = ESys_GetNextTime(epacing, &flag_epacing);
                 pacing[i] = ESys_GetLevel(epacing, &flag_epacing);
                 tnext = fmin(t_proposed, tnext);
 
-                #ifdef MYOKIT_DEBUG_PROFILING
+                #if defined(MYOKIT_DEBUG_PROFILING)
                 benchmarker_print("CP Created event-based pacing system.");
+                #elif defined(MYOKIT_DEBUG_MESSAGES)
+                printf("CM Created an event-based pacing system\n");
                 #endif
+
             } else if (strcmp(protocol_type_name, "TimeSeriesProtocol") == 0) {
-                pacing_systems[i].fixed = FSys_Create(&flag_fpacing);
-                pacing_types[i] = FIXED;
-                fpacing = pacing_systems[i].fixed;
-                if (flag_fpacing != FSys_OK) { FSys_SetPyErr(flag_fpacing); return sim_clean(); }
-                flag_fpacing = FSys_Populate(fpacing, protocol);
-                if (flag_fpacing != FSys_OK) { FSys_SetPyErr(flag_fpacing); return sim_clean(); }
 
+                fpacing = TSys_Create(&flag_fpacing);
+                pacing_systems[i].tsys = fpacing;
+                pacing_types[i] = TSys_TYPE;
+
+                if (flag_fpacing != TSys_OK) { TSys_SetPyErr(flag_fpacing); return sim_clean(); }
+                flag_fpacing = TSys_Populate(fpacing, protocol);
+                if (flag_fpacing != TSys_OK) { TSys_SetPyErr(flag_fpacing); return sim_clean(); }
+                pacing[i] = 0;
 
-                #ifdef MYOKIT_DEBUG_PROFILING
-                benchmarker_print("CP Created fixed-form pacing system.");
+                #if defined(MYOKIT_DEBUG_PROFILING)
+                benchmarker_print("CP Created time-series pacing system.");
+                #elif defined(MYOKIT_DEBUG_MESSAGES)
+                printf("CM Added a time-series pacing system\n");
                 #endif
+
             } else {
-                printf("protocol_type_name: %s", protocol_type_name);
-                return sim_cleanx(PyExc_TypeError, "Item %d in 'protocols' is not a myokit.Protocol or myokit.TimeSeriesProtocol object.", i);
+
+                /* Pacing label defined but no protocol set. Usually happens through set_protocol(None). */
+                #if defined(MYOKIT_DEBUG_MESSAGES)
+                printf("CM Unsetting previously set protocol\n");
+                #endif
+
+                pacing_types[i] = PSys_NOT_SET;
+                pacing[i] = 0;  /* See #320 and technical note on pacing */
             }
         }
     }
@@ -1284,6 +1320,9 @@ sim_step(PyObject *self, PyObject *args)
     int flag_root;          /* Root finding flag */
     int flag_reinit = 0;    /* Set if CVODE needs to be reset during a simulation step */
 
+    /* Pacing */
+    ESys epacing;
+
     /* Multi-purpose ints for iterating */
     int i, j;
 
@@ -1521,12 +1560,10 @@ sim_step(PyObject *self, PyObject *args)
              */
             tnext = tmax;
             for (int i = 0; i < n_pace; i++) {
-                if (pacing_types[i] == EVENT) {
-                    ESys epacing = pacing_systems[i].event;
+                if (pacing_types[i] == ESys_TYPE) {
+                    epacing = pacing_systems[i].esys;
                     flag_epacing = ESys_AdvanceTime(epacing, t);
-                    if (flag_epacing != ESys_OK) {
-                        ESys_SetPyErr(flag_epacing); return sim_clean();
-                    }
+                    if (flag_epacing != ESys_OK) { ESys_SetPyErr(flag_epacing); return sim_clean(); }
                     t_proposed = ESys_GetNextTime(epacing, NULL);
                     tnext = fmin(tnext, t_proposed);
                     pacing[i] = ESys_GetLevel(epacing, NULL);

myokit/_sim/cvodessim.py

@@ -88,6 +88,19 @@ class Simulation(myokit.CModule):
 
     No variable labels are required for this simulation type.
 
+    **Multiple protocols or no protocol**
+
+    This simulation supports pacing with more than one protocol. To this end,
+    pass in a dictionary mapping pacing labels (bindings) to :class:`Protocol`
+    or :class:`TimeSeriesProtocol` objects, e.g.
+    ``protocol={'pace_1': protocol_1, 'pace_2': protocol_2}``.
+
+    For backwards compatibility, if no protocol is set and ``protocol=None``,
+    then the pacing label ``pace`` is still registered (allowing later calls to
+    add a protocol with ``set_protocol``. Alternatively, if ``protocol={}``
+    then no pacing labels will be registered, and any subsequent calls to
+    ``set_protocol`` will fail.
+
     **Storing and loading simulation objects**
 
     There are two ways to store Simulation objects to the file system: 1.
@@ -163,11 +176,13 @@ class Simulation(myokit.CModule):
         if isinstance(protocol, (myokit.Protocol, myokit.TimeSeriesProtocol)):
             protocol = {'pace': protocol}
         elif protocol is None:
-            # TODO: This can be an empty dict once #320 is resolved
+            # For backwards compatibility, we still register 'pace'. This
+            # means users can call `set_protocol` at a later time to set a
+            # protocol.
             protocol = {'pace': None}
         for label, protocol in protocol.items():
+            self._protocols.append(None)
             self._pacing_labels.append(label)
-            self._protocols.append(myokit.Protocol())
             self.set_protocol(protocol, label)
 
         # Generate C Model code, get sensitivity and constants info
@@ -1008,8 +1023,8 @@ class Simulation(myokit.CModule):
 
     def set_protocol(self, protocol, label='pace'):
         """
-        Set an event-based pacing :class:`Protocol` or a :class:`FixedProtocol`
-        for the given ``label``.
+        Set an event-based pacing :class:`Protocol` or a
+        :class:`TimeSeriesProtocol` for the given ``label``.
 
         To remove a previously set binding call this method with ``protocol =
         None``. In this case, the value of any variables bound to ``label``
@@ -1023,10 +1038,7 @@ class Simulation(myokit.CModule):
             raise ValueError('Unknown pacing label: ' + str(label))
 
         # Set new protocol
-        if protocol is None:
-            self._protocols[index] = myokit.Protocol()
-        else:
-            self._protocols[index] = protocol.clone()
+        self._protocols[index] = None if protocol is None else protocol.clone()
 
     def __setstate__(self, state):
         """

myokit/_sim/fiber_tissue.c

@@ -500,7 +500,7 @@ sim_init(PyObject* self, PyObject* args)
     //
     // Set up pacing system
     //
-    pacing = ESys_Create(&flag_pacing);
+    pacing = ESys_Create(tmin, &flag_pacing);
     if(flag_pacing!=ESys_OK) { ESys_SetPyErr(flag_pacing); return sim_clean(); }
     flag_pacing = ESys_Populate(pacing, protocol);
     if(flag_pacing!=ESys_OK) { ESys_SetPyErr(flag_pacing); return sim_clean(); }

myokit/_sim/fiber_tissue.py

@@ -56,11 +56,12 @@ class FiberTissueSimulation(myokit.CModule):
     ``time`` (global)
         The simulation time
     ``pace`` (per-cell)
-        The pacing level, this is set if a protocol was passed in.
+        The pacing level, this is set if a protocol was passed in. Will be set
+        to 0 if no protocol is provided.
     ``diffusion_current`` (per-cell)
         The current flowing from the cell to its neighbors. This will be
         positive when the cell is acting as a source, negative when it is
-        acting as a sink.
+        acting as a sink. Will be set to 0 if no connections are made.
 
     The variable ``time`` is set globally, meaning each cell uses the same
     value. The variables ``pace`` and ``diffusion_current`` have different

myokit/_sim/openclsim.c

@@ -485,7 +485,7 @@ sim_init(PyObject* self, PyObject* args)
     //
     // Set up pacing system
     //
-    pacing = ESys_Create(&flag_pacing);
+    pacing = ESys_Create(tmin, &flag_pacing);
     if(flag_pacing != ESys_OK) { ESys_SetPyErr(flag_pacing); return sim_clean(); }
     flag_pacing = ESys_Populate(pacing, protocol);
     if(flag_pacing != ESys_OK) { ESys_SetPyErr(flag_pacing); return sim_clean(); }

myokit/_sim/openclsim.py

@@ -56,7 +56,8 @@ class SimulationOpenCL(myokit.CModule):
     ``time``
         The simulation time
     ``pace``
-        The pacing level, this is set if a protocol was passed in.
+        The pacing level, this is set if a protocol was passed in. Will be set
+        to 0 if no protocol is provided.
     ``diffusion_current`` (if enabled)
         The current flowing from the cell to its neighbors. This will be
         positive when the cell is acting as a source, negative when it is
@@ -780,8 +781,8 @@ class SimulationOpenCL(myokit.CModule):
         (see the argument list below for the meaning of the variables).
 
         This can be equated to Myokit's diffusion current, but only if we
-        assume **zero-flux boundary conditions**, a **regularly spaced grid**,
-        and **no spatial heterogeneity in D** (or g).
+        assume *zero-flux boundary conditions*, a *regularly spaced grid*,
+        and *no spatial heterogeneity in D* (or g).
 
         With these assumptions, we can use finite differences to find::
 
@@ -791,13 +792,13 @@ class SimulationOpenCL(myokit.CModule):
         respect to unit membrane area.
         For models with currents normalized to area this is unproblematic, but
         to convert to models with unnormalized currents this means we have
-        added the further assumption that **each node contains some fixed
-        amount of membrane**, determined by an area A::
+        added the further assumption that *each node contains some fixed
+        amount of membrane*, determined by an area A::
 
             g = (1 / chi) * (k / (k + 1)) * D * (1 / dx^2) * A
 
         This equation can also be applied in two dimensions, but only if
-        **we assume that the conductivity matrix is diagonal**, in which case::
+        *we assume that the conductivity matrix is diagonal*, in which case::
 
             gx = (1 / chi) * (k / (k + 1)) * Dx * (1 / dx^2) * A
             gy = (1 / chi) * (k / (k + 1)) * Dy * (1 / dy^2) * A
@@ -1708,11 +1709,7 @@ class SimulationOpenCL(myokit.CModule):
         self._step_size = step_size
 
     def set_time(self, time=0):
-        """
-        Sets the current simulation time.
-        """
-        if time < 0:
-            raise ValueError('Simulation time cannot be negative')
+        """ Sets the current simulation time. """
         self._time = float(time)
 
     def shape(self):