mxlpy 0.20.0__py3-none-any.whl → 0.22.0__py3-none-any.whl

mxlpy/scan.py

@@ -22,7 +22,6 @@ from typing import TYPE_CHECKING, Protocol, Self, cast
 import numpy as np
 import pandas as pd
 
-from mxlpy.integrators import DefaultIntegrator
 from mxlpy.parallel import Cache, parallelise
 from mxlpy.simulator import Result, Simulator
 from mxlpy.types import IntegratorType, ProtocolByPars, SteadyStates, TimeCourseByPars
@@ -281,7 +280,8 @@ class SteadyStateWorker(Protocol):
         model: Model,
         *,
         rel_norm: bool,
-        integrator: IntegratorType,
+        integrator: IntegratorType | None,
+        y0: dict[str, float] | None,
     ) -> TimePoint:
         """Call the worker function."""
         ...
@@ -295,7 +295,8 @@ class TimeCourseWorker(Protocol):
         model: Model,
         time_points: Array,
         *,
-        integrator: IntegratorType,
+        integrator: IntegratorType | None,
+        y0: dict[str, float] | None,
     ) -> TimeCourse:
         """Call the worker function."""
         ...
@@ -309,7 +310,8 @@ class ProtocolWorker(Protocol):
         model: Model,
         protocol: pd.DataFrame,
         *,
-        integrator: IntegratorType,
+        integrator: IntegratorType | None,
+        y0: dict[str, float] | None,
         time_points_per_step: int = 10,
     ) -> TimeCourse:
         """Call the worker function."""
@@ -320,7 +322,8 @@ def _steady_state_worker(
     model: Model,
     *,
     rel_norm: bool,
-    integrator: IntegratorType,
+    integrator: IntegratorType | None,
+    y0: dict[str, float] | None,
 ) -> TimePoint:
     """Simulate the model to steady state and return concentrations and fluxes.
 
@@ -336,7 +339,7 @@ def _steady_state_worker(
     """
     try:
         res = (
-            Simulator(model, integrator=integrator)
+            Simulator(model, integrator=integrator, y0=y0)
             .simulate_to_steady_state(rel_norm=rel_norm)
             .get_result()
         )
@@ -348,7 +351,8 @@ def _steady_state_worker(
 def _time_course_worker(
     model: Model,
     time_points: Array,
-    integrator: IntegratorType,
+    y0: dict[str, float] | None,
+    integrator: IntegratorType | None,
 ) -> TimeCourse:
     """Simulate the model to steady state and return concentrations and fluxes.
 
@@ -364,7 +368,7 @@ def _time_course_worker(
     """
     try:
         res = (
-            Simulator(model, integrator=integrator)
+            Simulator(model, integrator=integrator, y0=y0)
             .simulate_time_course(time_points=time_points)
             .get_result()
         )
@@ -381,7 +385,8 @@ def _protocol_worker(
     model: Model,
     protocol: pd.DataFrame,
     *,
-    integrator: IntegratorType = DefaultIntegrator,
+    integrator: IntegratorType | None,
+    y0: dict[str, float] | None,
     time_points_per_step: int = 10,
 ) -> TimeCourse:
     """Simulate the model over a protocol and return concentrations and fluxes.
@@ -399,8 +404,8 @@ def _protocol_worker(
     """
     try:
         res = (
-            Simulator(model, integrator=integrator)
-            .simulate_over_protocol(
+            Simulator(model, integrator=integrator, y0=y0)
+            .simulate_protocol(
                 protocol=protocol,
                 time_points_per_step=time_points_per_step,
             )
@@ -430,7 +435,7 @@ def steady_state(
     rel_norm: bool = False,
     cache: Cache | None = None,
     worker: SteadyStateWorker = _steady_state_worker,
-    integrator: IntegratorType = DefaultIntegrator,
+    integrator: IntegratorType | None = None,
 ) -> SteadyStates:
     """Get steady-state results over supplied values.
 
@@ -479,6 +484,7 @@ def steady_state(
                 worker,
                 rel_norm=rel_norm,
                 integrator=integrator,
+                y0=None,
             ),
             model=model,
         ),
@@ -486,8 +492,8 @@ def steady_state(
         cache=cache,
         parallel=parallel,
     )
-    concs = pd.DataFrame({k: v.variables.T for k, v in res.items()}).T
-    fluxes = pd.DataFrame({k: v.fluxes.T for k, v in res.items()}).T
+    concs = pd.DataFrame({k: v.variables.T for k, v in res}).T
+    fluxes = pd.DataFrame({k: v.fluxes.T for k, v in res}).T
     idx = (
         pd.Index(to_scan.iloc[:, 0])
         if to_scan.shape[1] == 1
@@ -506,8 +512,8 @@ def time_course(
     y0: dict[str, float] | None = None,
     parallel: bool = True,
     cache: Cache | None = None,
+    integrator: IntegratorType | None = None,
     worker: TimeCourseWorker = _time_course_worker,
-    integrator: IntegratorType = DefaultIntegrator,
 ) -> TimeCourseByPars:
     """Get time course for each supplied parameter.
 
@@ -559,6 +565,8 @@ def time_course(
 
 
     """
+    # We update the initial conditions separately here, because `to_scan` might also
+    # contain initial conditions.
     if y0 is not None:
         model.update_variables(y0)
 
@@ -569,6 +577,7 @@ def time_course(
                 worker,
                 time_points=time_points,
                 integrator=integrator,
+                y0=None,  # See comment above
             ),
             model=model,
         ),
@@ -576,8 +585,8 @@ def time_course(
         cache=cache,
         parallel=parallel,
     )
-    concs = cast(dict, {k: v.variables for k, v in res.items()})
-    fluxes = cast(dict, {k: v.fluxes for k, v in res.items()})
+    concs = cast(dict, {k: v.variables for k, v in res})
+    fluxes = cast(dict, {k: v.fluxes for k, v in res})
     return TimeCourseByPars(
         parameters=to_scan,
         variables=pd.concat(concs, names=["n", "time"]),
@@ -595,7 +604,7 @@ def time_course_over_protocol(
     parallel: bool = True,
     cache: Cache | None = None,
     worker: ProtocolWorker = _protocol_worker,
-    integrator: IntegratorType = DefaultIntegrator,
+    integrator: IntegratorType | None = None,
 ) -> ProtocolByPars:
     """Get protocol series for each supplied parameter.
 
@@ -626,6 +635,8 @@ def time_course_over_protocol(
         TimeCourseByPars: Protocol series results for each parameter set.
 
     """
+    # We update the initial conditions separately here, because `to_scan` might also
+    # contain initial conditions.
     if y0 is not None:
         model.update_variables(y0)
 
@@ -637,6 +648,7 @@ def time_course_over_protocol(
                 protocol=protocol,
                 time_points_per_step=time_points_per_step,
                 integrator=integrator,
+                y0=None,
             ),
             model=model,
         ),
@@ -644,8 +656,8 @@ def time_course_over_protocol(
         cache=cache,
         parallel=parallel,
     )
-    concs = cast(dict, {k: v.variables for k, v in res.items()})
-    fluxes = cast(dict, {k: v.fluxes for k, v in res.items()})
+    concs = cast(dict, {k: v.variables for k, v in res})
+    fluxes = cast(dict, {k: v.fluxes for k, v in res})
     return ProtocolByPars(
         parameters=to_scan,
         protocol=protocol,

mxlpy/simulator.py

@@ -10,7 +10,7 @@ Classes:
 
 from __future__ import annotations
 
-import warnings
+import logging
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Literal, Self, cast, overload
 
@@ -27,6 +27,8 @@ if TYPE_CHECKING:
     from mxlpy.model import Model
     from mxlpy.types import Array, ArrayLike, IntegratorProtocol, IntegratorType
 
+_LOGGER = logging.getLogger(__name__)
+
 __all__ = [
     "Result",
     "Simulator",
@@ -67,15 +69,15 @@ class Result:
     """Simulation results."""
 
     model: Model
-    _raw_variables: list[pd.DataFrame]
-    _parameters: list[dict[str, float]]
-    _dependent: list[pd.DataFrame] = field(default_factory=list)
+    raw_variables: list[pd.DataFrame]
+    raw_parameters: list[dict[str, float]]
+    raw_args: list[pd.DataFrame] = field(default_factory=list)
 
     @property
     def variables(self) -> pd.DataFrame:
         """Simulation variables."""
         return self.get_variables(
-            include_derived=True,
+            include_derived_variables=True,
             include_readouts=True,
             concatenated=True,
             normalise=None,
@@ -90,49 +92,50 @@ class Result:
         """Iterate over the concentration and flux response coefficients."""
         return iter((self.variables, self.fluxes))
 
-    def _get_dependent(
-        self,
-        *,
-        include_readouts: bool = True,
-    ) -> list[pd.DataFrame]:
+    def _compute_args(self) -> list[pd.DataFrame]:
         # Already computed
-        if len(self._dependent) > 0:
-            return self._dependent
+        if len(self.raw_args) > 0:
+            return self.raw_args
 
         # Compute new otherwise
-        for res, p in zip(self._raw_variables, self._parameters, strict=True):
+        for res, p in zip(self.raw_variables, self.raw_parameters, strict=True):
             self.model.update_parameters(p)
-            self._dependent.append(
-                self.model.get_dependent_time_course(
+            self.raw_args.append(
+                self.model.get_args_time_course(
                     variables=res,
-                    include_readouts=include_readouts,
+                    include_variables=True,
+                    include_parameters=True,
+                    include_derived_parameters=True,
+                    include_derived_variables=True,
+                    include_reactions=True,
+                    include_surrogate_outputs=True,
+                    include_readouts=True,
                 )
             )
-        return self._dependent
+        return self.raw_args
 
-    def _select_variables(
+    def _select_data(
         self,
         dependent: list[pd.DataFrame],
         *,
-        include_derived: bool,
-        include_readouts: bool,
+        include_variables: bool = False,
+        include_parameters: bool = False,
+        include_derived_parameters: bool = False,
+        include_derived_variables: bool = False,
+        include_reactions: bool = False,
+        include_surrogate_outputs: bool = False,
+        include_readouts: bool = False,
     ) -> list[pd.DataFrame]:
-        names = self.model.get_variable_names()
-        if include_derived:
-            names.extend(self.model.get_derived_variable_names())
-        if include_readouts:
-            names.extend(self.model.get_readout_names())
-        return [i.loc[:, names] for i in dependent]
-
-    def _select_fluxes(
-        self,
-        dependent: list[pd.DataFrame],
-        *,
-        include_surrogates: bool,
-    ) -> list[pd.DataFrame]:
-        names = self.model.get_reaction_names()
-        if include_surrogates:
-            names.extend(self.model.get_surrogate_reaction_names())
+        names = self.model.get_arg_names(
+            include_time=False,
+            include_variables=include_variables,
+            include_parameters=include_parameters,
+            include_derived_parameters=include_derived_parameters,
+            include_derived_variables=include_derived_variables,
+            include_reactions=include_reactions,
+            include_surrogate_outputs=include_surrogate_outputs,
+            include_readouts=include_readouts,
+        )
         return [i.loc[:, names] for i in dependent]
 
     def _adjust_data(
@@ -148,11 +151,93 @@ class Result:
             return pd.concat(data, axis=0)
         return data
 
+    @overload
+    def get_args(  # type: ignore
+        self,
+        *,
+        include_variables: bool = True,
+        include_parameters: bool = False,
+        include_derived_parameters: bool = False,
+        include_derived_variables: bool = True,
+        include_reactions: bool = True,
+        include_surrogate_outputs: bool = False,
+        include_readouts: bool = False,
+        concatenated: Literal[False],
+        normalise: float | ArrayLike | None = None,
+    ) -> list[pd.DataFrame]: ...
+
+    @overload
+    def get_args(
+        self,
+        *,
+        include_variables: bool = True,
+        include_parameters: bool = False,
+        include_derived_parameters: bool = False,
+        include_derived_variables: bool = True,
+        include_reactions: bool = True,
+        include_surrogate_outputs: bool = False,
+        include_readouts: bool = False,
+        concatenated: Literal[True],
+        normalise: float | ArrayLike | None = None,
+    ) -> pd.DataFrame: ...
+
+    @overload
+    def get_args(
+        self,
+        *,
+        include_variables: bool = True,
+        include_parameters: bool = False,
+        include_derived_parameters: bool = False,
+        include_derived_variables: bool = True,
+        include_reactions: bool = True,
+        include_surrogate_outputs: bool = False,
+        include_readouts: bool = False,
+        concatenated: bool = True,
+        normalise: float | ArrayLike | None = None,
+    ) -> pd.DataFrame: ...
+
+    def get_args(
+        self,
+        *,
+        include_variables: bool = True,
+        include_parameters: bool = False,
+        include_derived_parameters: bool = False,
+        include_derived_variables: bool = True,
+        include_reactions: bool = True,
+        include_surrogate_outputs: bool = False,
+        include_readouts: bool = False,
+        concatenated: bool = True,
+        normalise: float | ArrayLike | None = None,
+    ) -> pd.DataFrame | list[pd.DataFrame]:
+        """Get the variables over time.
+
+        Examples:
+            >>> Result().get_variables()
+            Time            ATP      NADPH
+            0.000000   1.000000   1.000000
+            0.000100   0.999900   0.999900
+            0.000200   0.999800   0.999800
+
+        """
+        variables = self._select_data(
+            self._compute_args(),
+            include_variables=include_variables,
+            include_parameters=include_parameters,
+            include_derived_parameters=include_derived_parameters,
+            include_derived_variables=include_derived_variables,
+            include_reactions=include_reactions,
+            include_surrogate_outputs=include_surrogate_outputs,
+            include_readouts=include_readouts,
+        )
+        return self._adjust_data(
+            variables, normalise=normalise, concatenated=concatenated
+        )
+
     @overload
     def get_variables(  # type: ignore
         self,
         *,
-        include_derived: bool = True,
+        include_derived_variables: bool = True,
         include_readouts: bool = True,
         concatenated: Literal[False],
         normalise: float | ArrayLike | None = None,
@@ -162,7 +247,7 @@ class Result:
     def get_variables(
         self,
         *,
-        include_derived: bool = True,
+        include_derived_variables: bool = True,
         include_readouts: bool = True,
         concatenated: Literal[True],
         normalise: float | ArrayLike | None = None,
@@ -172,7 +257,7 @@ class Result:
     def get_variables(
         self,
         *,
-        include_derived: bool = True,
+        include_derived_variables: bool = True,
         include_readouts: bool = True,
         concatenated: bool = True,
         normalise: float | ArrayLike | None = None,
@@ -181,7 +266,7 @@ class Result:
     def get_variables(
         self,
         *,
-        include_derived: bool = True,
+        include_derived_variables: bool = True,
         include_readouts: bool = True,
         concatenated: bool = True,
         normalise: float | ArrayLike | None = None,
@@ -196,16 +281,17 @@ class Result:
             0.000200   0.999800   0.999800
 
         """
-        if not include_derived and not include_readouts:
+        if not include_derived_variables and not include_readouts:
             return self._adjust_data(
-                self._raw_variables,
+                self.raw_variables,
                 normalise=normalise,
                 concatenated=concatenated,
             )
 
-        variables = self._select_variables(
-            self._get_dependent(),
-            include_derived=include_derived,
+        variables = self._select_data(
+            self._compute_args(),
+            include_variables=True,
+            include_derived_variables=include_derived_variables,
             include_readouts=include_readouts,
         )
         return self._adjust_data(
@@ -259,9 +345,10 @@ class Result:
             pd.DataFrame: DataFrame of fluxes.
 
         """
-        fluxes = self._select_fluxes(
-            self._get_dependent(),
-            include_surrogates=include_surrogates,
+        fluxes = self._select_data(
+            self._compute_args(),
+            include_reactions=True,
+            include_surrogate_outputs=include_surrogates,
         )
         return self._adjust_data(
             fluxes,
@@ -295,7 +382,7 @@ class Result:
         """
         return dict(
             self.get_variables(
-                include_derived=False,
+                include_derived_variables=False,
                 include_readouts=False,
             ).iloc[-1]
         )
@@ -335,7 +422,7 @@ class Simulator:
         self,
         model: Model,
         y0: dict[str, float] | None = None,
-        integrator: IntegratorType = DefaultIntegrator,
+        integrator: IntegratorType | None = None,
         *,
         use_jacobian: bool = False,
         test_run: bool = True,
@@ -354,7 +441,7 @@ class Simulator:
         self.model = model
         self.y0 = model.get_initial_conditions() if y0 is None else y0
 
-        self._integrator_type = integrator
+        self._integrator_type = DefaultIntegrator if integrator is None else integrator
         self._time_shift = None
         self.variables = None
         self.dependent = None
@@ -386,7 +473,7 @@ class Simulator:
                 )
 
             except Exception as e:  # noqa: BLE001
-                warnings.warn(str(e), stacklevel=2)
+                _LOGGER.warning(str(e), stacklevel=2)
 
         y0 = self.y0
         self.integrator = self._integrator_type(
@@ -431,7 +518,7 @@ class Simulator:
         # model._get_rhs sorts the return array by model.get_variable_names()
         # Do NOT change this ordering
         results_df = pd.DataFrame(
-            results,
+            data=results,
             index=time,
             columns=self.model.get_variable_names(),
         )
@@ -445,7 +532,7 @@ class Simulator:
 
         if self.simulation_parameters is None:
             self.simulation_parameters = []
-        self.simulation_parameters.append(self.model.parameters)
+        self.simulation_parameters.append(self.model.get_parameter_values())
 
     def simulate(
         self,
@@ -472,6 +559,13 @@ class Simulator:
         if self._time_shift is not None:
             t_end -= self._time_shift
 
+        prior_t_end: float = (
+            0.0 if (variables := self.variables) is None else variables[-1].index[-1]
+        )
+        if t_end <= prior_t_end:
+            msg = "End time point has to be larger than previous end time point"
+            raise ValueError(msg)
+
         time, results = self.integrator.integrate(t_end=t_end, steps=steps)
 
         self._handle_simulation_results(time, results, skipfirst=True)
@@ -495,17 +589,33 @@ class Simulator:
             Self: The Simulator instance with updated results.
 
         """
+        time_points = np.array(time_points, dtype=float)
+
         if self._time_shift is not None:
-            time_points = np.array(time_points, dtype=float)
             time_points -= self._time_shift
 
+        # Check if end is actually larger
+        prior_t_end: float = (
+            0.0 if (variables := self.variables) is None else variables[-1].index[-1]
+        )
+        if time_points[-1] <= prior_t_end:
+            msg = "End time point has to be larger than previous end time point"
+            raise ValueError(msg)
+
+        # Remove points which are smaller than previous t_end
+        if not (larger := time_points >= prior_t_end).all():
+            msg = f"Overlapping time points. Removing: {time_points[~larger]}"
+            _LOGGER.warning(msg)
+            time_points = time_points[larger]
+
         time, results = self.integrator.integrate_time_course(time_points=time_points)
         self._handle_simulation_results(time, results, skipfirst=True)
         return self
 
-    def simulate_over_protocol(
+    def simulate_protocol(
         self,
         protocol: pd.DataFrame,
+        *,
         time_points_per_step: int = 10,
     ) -> Self:
         """Simulate the model over a given protocol.
@@ -524,10 +634,81 @@ class Simulator:
             The Simulator instance with updated results.
 
         """
+        t_start = (
+            0.0 if (variables := self.variables) is None else variables[-1].index[-1]
+        )
+
         for t_end, pars in protocol.iterrows():
             t_end = cast(pd.Timedelta, t_end)
             self.model.update_parameters(pars.to_dict())
-            self.simulate(t_end.total_seconds(), steps=time_points_per_step)
+            self.simulate(t_start + t_end.total_seconds(), steps=time_points_per_step)
+            if self.variables is None:
+                break
+        return self
+
+    def simulate_protocol_time_course(
+        self,
+        protocol: pd.DataFrame,
+        time_points: ArrayLike,
+        *,
+        time_points_as_relative: bool = False,
+    ) -> Self:
+        """Simulate the model over a given protocol.
+
+        Examples:
+            >>> Simulator(model).simulate_over_protocol(
+            ...     protocol,
+            ...     time_points=np.array([1.0, 2.0, 3.0], dtype=float),
+            ... )
+
+        Args:
+            protocol: DataFrame containing the protocol.
+            time_points: Array of time points for which to return the simulation values.
+            time_points_as_relative: Interpret time points as relative time
+
+        Notes:
+            This function will return **both** the control points of the protocol as well
+            as the time points supplied in case they don't match.
+
+        Returns:
+            The Simulator instance with updated results.
+
+        """
+        t_start = (
+            0.0 if (variables := self.variables) is None else variables[-1].index[-1]
+        )
+
+        protocol = protocol.copy()
+        protocol.index = (
+            cast(pd.TimedeltaIndex, protocol.index) + pd.Timedelta(t_start, unit="s")
+        ).total_seconds()
+
+        time_points = np.array(time_points, dtype=float)
+        if time_points_as_relative:
+            time_points += t_start
+
+        # Error handling
+        if time_points[-1] <= t_start:
+            msg = "End time point has to be larger than previous end time point"
+            raise ValueError(msg)
+
+        larger = time_points > protocol.index[-1]
+        if any(larger):
+            msg = f"Ignoring time points outside of protocol range:\n {time_points[larger]}"
+            _LOGGER.warning(msg)
+
+        # Continue with logic
+        full_time_points = protocol.index.join(time_points, how="outer")
+
+        for t_end, pars in protocol.iterrows():
+            self.model.update_parameters(pars.to_dict())
+
+            self.simulate_time_course(
+                time_points=full_time_points[
+                    (full_time_points > t_start) & (full_time_points <= t_end)
+                ]
+            )
+            t_start = t_end
             if self.variables is None:
                 break
         return self
@@ -590,8 +771,8 @@ class Simulator:
             return None
         return Result(
             model=self.model,
-            _raw_variables=variables,
-            _parameters=parameters,
+            raw_variables=variables,
+            raw_parameters=parameters,
         )
 
     def update_parameter(self, parameter: str, value: float) -> Self: