mxlpy 0.44.0__tar.gz → 0.45.0__tar.gz

{mxlpy-0.44.0 → mxlpy-0.45.0}/.github/workflows/coverage.yml

@@ -27,7 +27,7 @@ jobs:
         run: uv sync --all-extras --all-groups
 
       - name: Run tests
-        run: uv run pytest --disable-warnings --cov --cov-report json tests/
+        run: uv run pytest -n auto --disable-warnings --cov --cov-report json tests/
 
       - name: Get coverage value
         run: python -c "import json;

{mxlpy-0.44.0 → mxlpy-0.45.0}/.github/workflows/tests.yml

@@ -33,4 +33,4 @@ jobs:
         run: uv sync --all-extras --all-groups
 
       - name: Run tests
-        run: uv run pytest --disable-warnings tests/
+        run: uv run pytest -n auto --disable-warnings tests/

{mxlpy-0.44.0 → mxlpy-0.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mxlpy
-Version: 0.44.0
+Version: 0.45.0
 Summary: A package to build metabolic models
 Author-email: Marvin van Aalst <marvin.vanaalst@gmail.com>
 Maintainer-email: Marvin van Aalst <marvin.vanaalst@gmail.com>

{mxlpy-0.44.0 → mxlpy-0.45.0}/docs/index.md

@@ -118,7 +118,7 @@ Mechanistic learning is the intersection of mechanistic modelling and machine le
 This allows combining together multiple models of arbitrary size, without having to worry about the internal state of each model.
 They are especially useful for improving the description of *boundary effects*, e.g. a dynamic description of downstream consumption.
 
-[Start learning](mxl-surrogate.ipynb){ .md-button }
+[Start learning](mxl-surrogates.ipynb){ .md-button }
 
 **Neural posterior estimation** answers the question: **what parameters could have generated the data I measured?**
 Here you use an ODE model and prior knowledge about the parameters of interest to create *synthetic data*.

{mxlpy-0.44.0 → mxlpy-0.45.0}/docs/mca.ipynb

@@ -159,6 +159,51 @@
     "plt.show()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Steady-state stability\n",
+    "\n",
+    "After finding a steady state you can classify its local stability from the eigenvalues of the Jacobian.\n",
+    "\n",
+    "`steady_state_stability` evaluates the symbolic Jacobian at the given state, computes eigenvalues with `numpy.linalg.eigvals`, and returns a `SteadyStateStability` object:\n",
+    "\n",
+    "| Field | Description |\n",
+    "|---|---|\n",
+    "| `eigenvalues` | Complex Jacobian eigenvalues |\n",
+    "| `spectral_abscissa` | Largest real part — negative ⟺ stable |\n",
+    "| `is_stable` | `True` when all real parts are negative |\n",
+    "| `has_oscillatory` | `True` when any eigenvalue has nonzero imaginary part |\n",
+    "| `classification` | `\"stable node\"` \\| `\"stable spiral\"` \\| `\"unstable node\"` \\| `\"unstable spiral\"` \\| `\"saddle point\"` \\| `\"centre\"` \\| `\"non-hyperbolic\"` |"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from mxlpy import Simulator\n",
+    "from mxlpy.mca import steady_state_stability\n",
+    "\n",
+    "model = get_upper_glycolysis()\n",
+    "ss = (\n",
+    "    Simulator(model)\n",
+    "    .simulate_to_steady_state()\n",
+    "    .get_result()\n",
+    "    .unwrap_or_err()\n",
+    "    .get_new_y0()\n",
+    ")\n",
+    "\n",
+    "stab = steady_state_stability(model, ss)\n",
+    "print(f\"Classification : {stab.classification}\")\n",
+    "print(f\"Is stable      : {stab.is_stable}\")\n",
+    "print(f\"Spectral absc. : {stab.spectral_abscissa:.4f}\")\n",
+    "print(f\"Has oscillatory: {stab.has_oscillatory}\")\n",
+    "print(f\"Eigenvalues    : {stab.eigenvalues}\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

{mxlpy-0.44.0 → mxlpy-0.45.0}/pyproject.toml

@@ -13,6 +13,8 @@ dev = [
     "pre-commit>=4.0.1",
     "pyright>=1.1.403",
     "pytest-cov>=5.0.0",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.8.0",
     "pytest>=8.3.3",
     "requests>=2.32.3",
     "ruff>=0.15.11",
@@ -78,27 +80,14 @@ maintainers = [
 name = "mxlpy"
 readme = "README.md"
 requires-python = ">=3.12"
-version = "0.44.0"
+version = "0.45.0"
 
 [project.optional-dependencies]
-jax = [
-    "diffrax>=0.7.0",
-    "equinox>=0.13",
-    "optax>=0.2.5",
-    "sympy2jax>=0.0.7",
-]
-keras = [
-    "keras>=3.9.2",
-]
-sr = [
-    "pysr>=1.5.9",
-]
-tensorflow = [
-    "tensorflow>=2.19.0",
-]
-torch = [
-    "torch>=2.5.1",
-]
+jax = ["diffrax>=0.7.0", "equinox>=0.13", "optax>=0.2.5", "sympy2jax>=0.0.7"]
+keras = ["keras>=3.9.2"]
+sr = ["pysr>=1.5.9"]
+tensorflow = ["tensorflow>=2.19.0"]
+torch = ["torch>=2.5.1"]
 
 [tool.bandit]
 skips = ["B101", "B301", "B403", "B404", "B603", "B607"]
@@ -120,12 +109,7 @@ exclude = [
     "tests/sbml/assets",
     "tmp",
 ]
-include = [
-    "docs",
-    "src",
-    "tests",
-    'publication-figures',
-]
+include = ["docs", "src", "tests", 'publication-figures']
 pythonVersion = "3.12"
 reportMissingModuleSource = "none"
 strict = []
@@ -183,10 +167,9 @@ select = ["ALL"]
     "SLF",
 ]
 "tests/sbml/assets/*" = [
+    "INP001",
     "N802",   # lowercase name
     "N803",   # lowercase name
-    "INP001",
-
 ]
 "tmp/*" = [
     "D",    # all of documentation

{mxlpy-0.44.0 → mxlpy-0.45.0}/src/mxlpy/jax/train.py

@@ -8,12 +8,14 @@ import equinox as eqx
 import jax
 import jax.numpy as jnp
 import optax
+import pandas as pd
 from tqdm.auto import trange
 
 from mxlpy.jax.models import JaxModel, Method, Ude
 
 __all__ = [
     "IntegrationSettings",
+    "LossesPerLesson",
     "grad_loss",
     "grad_loss_split",
     "make_step",
@@ -22,6 +24,8 @@ __all__ = [
     "train_only_nde",
 ]
 
+type LossesPerLesson = list[pd.Series]
+
 
 @dataclass(unsafe_hash=True)
 class IntegrationSettings:
@@ -268,8 +272,8 @@ def make_step_split[T: JaxModel](
     return loss, eqx.apply_updates(trainable, updates), opt_state
 
 
-def train[T: JaxModel](
-    model: T,
+def train[Model: JaxModel](
+    model: Model,
     *,
     ts: jax.Array,
     ys: jax.Array,
@@ -278,7 +282,7 @@ def train[T: JaxModel](
     avg_every: int = 1000,
     optim: optax.GradientTransformationExtraArgs | None = None,
     integration_settings: IntegrationSettings | None = None,
-) -> tuple[T, dict[int, float]]:
+) -> tuple[Model, LossesPerLesson]:
     """Train a JAX model through a sequence of curriculum steps.
 
     Each curriculum stage re-initialises the optimiser and uses a
@@ -307,13 +311,11 @@ def train[T: JaxModel](
     Returns
     -------
     tuple[T, dict[int, float]]
-        Best model encountered during training and a dict mapping
-        global step index to average loss.
+        Best model encountered during training and losses per curriculum lesson.
     """
     loss = 0
     acc_loss = 0
     acc_count = 0
-    global_step = 0
     optim = optax.adabelief(learning_rate=1e-4) if optim is None else optim
     best_training_loss = jnp.inf
     best_model = model
@@ -324,12 +326,14 @@ def train[T: JaxModel](
 
     y_mean = jnp.mean(ys)
     y_scale = jnp.std(ys)
-    losses = {}
+    losses_per_lesson = []
     for i, (steps, frac) in enumerate(training_steps, start=1):
         opt_state = optim.init(eqx.filter(model, eqx.is_inexact_array))
         length = math.ceil(len(ts) * frac)
         _ts = ts[:length]
         _ys = ys[:length]
+        losses = {}
+        losses_per_lesson.append(losses)
 
         with trange(steps, position=1, leave=True, dynamic_ncols=True) as pbar:
             for step in pbar:
@@ -351,18 +355,18 @@ def train[T: JaxModel](
                     best_training_loss = loss
 
                 if i == len(training_steps) and loss < target_loss:
-                    return (model, losses)
+                    return (model, [pd.Series(i) for i in losses_per_lesson])
 
                 if (step % avg_every) == 0 or step == steps - 1:
                     avg_loss = acc_loss / acc_count
                     pbar.set_postfix_str(
                         f"Avg. loss {(avg_loss):.2e} over last {acc_count} runs"
                     )
-                    global_step += acc_count
                     acc_loss = 0
                     acc_count = 0
-                    losses[global_step] = float(avg_loss)
-    return best_model, losses
+                    losses[step] = float(avg_loss)
+
+    return best_model, [pd.Series(i) for i in losses_per_lesson]
 
 
 def train_only_nde[T: Ude](
@@ -375,7 +379,7 @@ def train_only_nde[T: Ude](
     target_loss: float = 1e-4,
     optim: optax.GradientTransformationExtraArgs | None = None,
     integration_settings: IntegrationSettings | None = None,
-) -> tuple[T, dict[int, float]]:
+) -> tuple[T, LossesPerLesson]:
     """Train only the neural-network part of a UDE, keeping the ODE frozen.
 
     Partitions ``model`` into trainable (neural network) and frozen (ODE)
@@ -403,8 +407,7 @@ def train_only_nde[T: Ude](
     Returns
     -------
     tuple[T, dict[int, float]]
-        Best model encountered during training and a dict mapping
-        global step index to average loss.
+        Best model encountered during training and losses per curriculum lesson.
     """
     loss = 0
     acc_loss = 0
@@ -426,6 +429,7 @@ def train_only_nde[T: Ude](
     )
     trainable, frozen = eqx.partition(model, filter_spec)
 
+    losses_per_lesson = []
     y_mean = jnp.mean(ys)
     y_scale = jnp.std(ys)
     losses = {}
@@ -434,6 +438,8 @@ def train_only_nde[T: Ude](
         length = math.ceil(len(ts) * frac)
         _ts = ts[:length]
         _ys = ys[:length]
+        losses = {}
+        losses_per_lesson.append(losses)
 
         with trange(steps, position=1, leave=True, dynamic_ncols=True) as pbar:
             for step in pbar:
@@ -456,7 +462,10 @@ def train_only_nde[T: Ude](
                     best_training_loss = loss
 
                 if i == len(training_steps) and loss < target_loss:
-                    return (eqx.combine(trainable, frozen), losses)
+                    return (
+                        eqx.combine(trainable, frozen),
+                        [pd.Series(i) for i in losses_per_lesson],
+                    )
 
                 if (step % avg_every) == 0 or step == steps - 1:
                     avg_loss = acc_loss / acc_count
@@ -467,4 +476,4 @@ def train_only_nde[T: Ude](
                     acc_loss = 0
                     acc_count = 0
                     losses[global_step] = float(avg_loss)
-    return best_model, losses
+    return best_model, [pd.Series(i) for i in losses_per_lesson]

{mxlpy-0.44.0 → mxlpy-0.45.0}/src/mxlpy/mca.py

@@ -19,25 +19,31 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from functools import partial
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
+import numpy as np
 import pandas as pd
 from wadler_lindig import pformat
 
 from mxlpy.parallel import parallelise
 from mxlpy.scan import _steady_state_worker
+from mxlpy.symbolic.symbolic_model import to_symbolic_model
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
+    from numpy.typing import NDArray
+
     from mxlpy.integrators import IntegratorType
     from mxlpy.model import Model
 
 __all__ = [
     "ResponseCoefficients",
     "ResponseCoefficientsByPars",
+    "SteadyStateStability",
     "parameter_elasticities",
     "response_coefficients",
+    "steady_state_stability",
     "variable_elasticities",
 ]
 
@@ -382,3 +388,88 @@ class ResponseCoefficientsByPars:
     def __iter__(self) -> Iterator[pd.DataFrame]:
         """Iterate over the concentration and flux response coefficients."""
         return iter((self.variables, self.fluxes))
+
+
+###############################################################################
+# Stability analysis
+###############################################################################
+
+
+@dataclass(kw_only=True, slots=True)
+class SteadyStateStability:
+    """Local stability classification of a steady state."""
+
+    eigenvalues: NDArray[np.complexfloating[Any, Any]]
+    spectral_abscissa: float
+    is_stable: bool
+    has_oscillatory: bool
+    classification: str
+
+    def __repr__(self) -> str:
+        """Return default representation."""
+        return pformat(self)
+
+
+def steady_state_stability(
+    model: Model,
+    steady_state: dict[str, float],
+    *,
+    threshold: float = 1e-10,
+) -> SteadyStateStability:
+    """Classify local stability of a steady state via Jacobian eigenvalues.
+
+    Parameters
+    ----------
+    model
+        Model instance.
+    steady_state
+        Steady-state variable concentrations {name: value}.
+    threshold
+        Tolerance for treating real/imaginary parts as zero.
+
+    Returns
+    -------
+    SteadyStateStability
+        Eigenvalues, spectral abscissa, stability flag, oscillatory flag,
+        and a human-readable classification label.
+
+    Examples
+    --------
+        >>> from mxlpy import Simulator
+        >>> ss = Simulator(model).simulate_to_steady_state().get_new_y0()
+        >>> steady_state_stability(model, ss).classification
+        'stable node'
+
+    """
+    sym = to_symbolic_model(model)
+    J_sym = sym.jacobian()
+
+    subs: dict = {s: steady_state[name] for name, s in sym.variables.items()}
+    subs |= {s: sym.parameter_values[name] for name, s in sym.parameters.items()}
+    J_num = np.array(J_sym.subs(subs).tolist(), dtype=complex)
+    eigenvalues = np.linalg.eigvals(J_num)
+
+    real_parts = eigenvalues.real
+    spectral_abscissa = float(real_parts.max())
+    min_real = float(real_parts.min())
+    has_oscillatory = bool(np.any(np.abs(eigenvalues.imag) > threshold))
+    is_stable = spectral_abscissa < -threshold
+
+    if spectral_abscissa < -threshold:
+        classification = "stable spiral" if has_oscillatory else "stable node"
+    elif min_real > threshold:
+        classification = "unstable spiral" if has_oscillatory else "unstable node"
+    elif spectral_abscissa > threshold and min_real < -threshold:
+        classification = "saddle point"
+    elif np.all(np.abs(real_parts) <= threshold) and has_oscillatory:
+        classification = "centre"
+    else:
+        classification = "non-hyperbolic"
+
+    return SteadyStateStability(
+        eigenvalues=eigenvalues,  # pyright: ignore[reportArgumentType]
+        spectral_abscissa=spectral_abscissa,
+        is_stable=is_stable,
+        has_oscillatory=has_oscillatory,
+        classification=classification,
+    )

{mxlpy-0.44.0 → mxlpy-0.45.0}/src/mxlpy/sbml/_import.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import re
 import sys
+import types
 import unicodedata
 from importlib import util
 from typing import TYPE_CHECKING
@@ -18,7 +19,12 @@ from mxlpy.meta._via_sym_repr import (
 )
 from mxlpy.paths import default_tmp_dir
 
-__all__ = ["free_symbols", "import_from_path", "read", "valid_filename"]
+__all__ = [
+    "free_symbols",
+    "import_from_path",
+    "read",
+    "valid_filename",
+]
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -56,7 +62,7 @@ def _transform_stoichiometry(
     return SymbolicFn(k, expr=v, args=free_symbols(v))
 
 
-def _codegen(name: str, model: pysbml.transform.data.Model) -> Path:
+def _codegen(model: pysbml.transform.data.Model) -> str:
     sym = SymbolicRepr()
     for key, var in model.variables.items():
         sym.variables[key] = SymbolicVariable(
@@ -87,10 +93,7 @@ def _codegen(name: str, model: pysbml.transform.data.Model) -> Path:
                 fn_name=key, expr=der, args=free_symbols(der)
             )
 
-    path = default_tmp_dir(None, remove_old_cache=False) / f"{name}.py"
-    with path.open("w+") as f:
-        f.write(sym.generate_mxlpy())
-    return path
+    return sym.generate_mxlpy()
 
 
 def import_from_path(module_name: str, file_path: Path) -> Callable[[], Model]:
@@ -141,7 +144,7 @@ def valid_filename(value: str) -> str:
     return f"mb_{value}"
 
 
-def read(file: Path) -> Model:
+def read(file: Path, *, via_temp_file: bool = True) -> Model:
     """Import a metabolic model from an SBML file.
 
     Parameters
@@ -157,5 +160,16 @@ def read(file: Path) -> Model:
     """
     model = pysbml.load_and_transform_model(file)
     out_name = valid_filename(file.stem)
-    model_fn = import_from_path(out_name, _codegen(out_name, model))
+    model_code = _codegen(model)
+
+    model_fn: Callable[[], Model]
+    if via_temp_file:
+        path = default_tmp_dir(None, remove_old_cache=False) / f"{out_name}.py"
+        with path.open("w+") as f:
+            f.write(model_code)
+        model_fn = import_from_path(out_name, path)
+    else:
+        module = types.ModuleType(out_name)
+        exec(model_code, module.__dict__)  # noqa: S102
+        model_fn = module.create_model
     return model_fn()

{mxlpy-0.44.0 → mxlpy-0.45.0}/tests/sbml/test_import.py

@@ -77,7 +77,11 @@ def get_files(test: int) -> tuple[Model, dict, pd.DataFrame]:
     sim_settings = get_simulation_settings(path=path, prefix=prefix)
     expected = pd.read_csv(path / f"{prefix}-results.csv", index_col=0).astype(float)
     expected.columns = [i.strip() for i in expected.columns]
-    return read(file=path / f"{prefix}-sbml-l3v2.xml"), sim_settings, expected
+    return (
+        read(file=path / f"{prefix}-sbml-l3v2.xml", via_temp_file=False),
+        sim_settings,
+        expected,
+    )
 
 
 def routine(test: int) -> bool:

{mxlpy-0.44.0 → mxlpy-0.45.0}/tests/test_mca.py

@@ -7,8 +7,10 @@ import pytest
 
 from mxlpy import Model, fns
 from mxlpy.mca import (
+    SteadyStateStability,
     parameter_elasticities,
     response_coefficients,
+    steady_state_stability,
     variable_elasticities,
 )
 
@@ -180,3 +182,54 @@ def test_variable_elasticities_zero_variable_produces_nan_or_inf() -> None:
     result = variable_elasticities(model, normalized=False)
     # Division by zero → inf or NaN in the S column
     assert not np.isfinite(result["S"].to_numpy()).all()
+
+
+###############################################################################
+# steady_state_stability
+###############################################################################
+
+
+def test_steady_state_stability_returns_correct_type() -> None:
+    ss = {"A": 2.0, "B": 4.0}
+    result = steady_state_stability(linear_chain(), ss)
+    assert isinstance(result, SteadyStateStability)
+    assert isinstance(result.eigenvalues, np.ndarray)
+    assert isinstance(result.spectral_abscissa, float)
+    assert isinstance(result.is_stable, bool)
+    assert isinstance(result.has_oscillatory, bool)
+    assert isinstance(result.classification, str)
+
+
+def test_steady_state_stability_linear_chain_is_stable() -> None:
+    """Open linear chain A→B→sink is unconditionally stable."""
+    ss = {"A": 2.0, "B": 4.0}
+    result = steady_state_stability(linear_chain(), ss)
+    assert result.is_stable
+    assert result.spectral_abscissa < 0
+    assert result.classification in {"stable node", "stable spiral"}
+
+
+def test_steady_state_stability_unstable_model() -> None:
+    """Autocatalytic model dS/dt = k*S has positive eigenvalue → unstable."""
+    model = (
+        Model()
+        .add_variable("S", 1.0)
+        .add_parameter("k", 1.0)
+        .add_reaction(
+            "v1",
+            fn=fns.mass_action_1s,
+            args=["S", "k"],
+            stoichiometry={"S": 1.0},
+        )
+    )
+    result = steady_state_stability(model, {"S": 1.0})
+    assert not result.is_stable
+    assert result.spectral_abscissa > 0
+    assert result.classification in {"unstable node", "unstable spiral", "saddle point"}
+
+
+def test_steady_state_stability_spectral_abscissa_matches_eigenvalues() -> None:
+    ss = {"A": 2.0, "B": 4.0}
+    result = steady_state_stability(linear_chain(), ss)
+    max_real = max(float(ev.real) for ev in result.eigenvalues)
+    assert result.spectral_abscissa == pytest.approx(max_real)