perfusio 0.1.0__py3-none-any.whl

perfusio/__init__.py

@@ -0,0 +1,38 @@
+"""perfusio — open reference implementation of self-driving perfusion bioprocess development.
+
+``perfusio`` implements the methodology of Gadiyar et al. (2026) and Hutter et al. (2021),
+providing step-wise Gaussian-process hybrid models, entity-embedding transfer learning,
+Bayesian Experimental Design, and an online-retraining digital twin for CHO perfusion
+bioreactors. It is intended as an open, citable complement to commercial platforms.
+
+References
+----------
+.. [Gadiyar2026] Gadiyar, C. J., Müller, C., Vuillemin, T., Bielser, J.-M., Souquet, J.,
+   Fagnani, A., Sokolov, M., von Stosch, M., Feidl, F., Butté, A., &
+   Cruz Bournazou, M. N. (2026). Self-Driving Development of Perfusion Processes
+   for Monoclonal Antibody Production. *Biotechnology and Bioengineering*, 123(2),
+   391–405. https://doi.org/10.1002/bit.70093
+
+.. [Hutter2021] Hutter, S., von Stosch, M., Cruz Bournazou, M. N., & Butté, A. (2021).
+   Knowledge transfer across cell lines using hybrid Gaussian process models with
+   entity embedding vectors. *Biotechnology and Bioengineering*, 118(12), 4710–4725.
+   https://doi.org/10.1002/bit.27907
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__author__ = "perfusio Contributors"
+__license__ = "Apache-2.0"
+
+from perfusio.config import DesignSpace, RunConfig
+from perfusio.states import State, StateBatch, Trajectory
+
+__all__ = [
+    "DesignSpace",
+    "RunConfig",
+    "State",
+    "StateBatch",
+    "Trajectory",
+    "__version__",
+]

perfusio/_typing.py

@@ -0,0 +1,152 @@
+"""Custom types, TypeAliases, and Protocols for ``perfusio``.
+
+This module is the single place where ``Any`` may appear (in Protocol stubs
+and adapter contracts). All other modules must import from here rather than
+using ``typing.Any`` directly.
+
+Notes
+-----
+Only import from this module using ``TYPE_CHECKING`` guards in runtime code
+to avoid circular imports and keep start-up cost low.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any, Protocol, TypeAlias, runtime_checkable
+
+import numpy as np
+import torch
+from torch import Tensor
+
+# ---------------------------------------------------------------------------
+# Scalar types
+# ---------------------------------------------------------------------------
+
+#: A Python float, int, or zero-dimensional torch tensor.
+Numeric: TypeAlias = float | int | Tensor
+
+#: A 1-D array of float32/float64 (numpy or torch).
+Vector: TypeAlias = Tensor | np.ndarray[Any, np.dtype[np.floating[Any]]]
+
+#: A 2-D array of float64.
+Matrix: TypeAlias = Tensor | np.ndarray[Any, np.dtype[np.floating[Any]]]
+
+#: A path-like object or string.
+PathLike: TypeAlias = Path | str
+
+# ---------------------------------------------------------------------------
+# Shape annotations (documentation only — not enforced at runtime)
+# ---------------------------------------------------------------------------
+#: Batch dimension over reactors.
+_B = int
+#: Number of species / tasks.
+_K = int
+#: Time steps.
+_T = int
+#: State dimension.
+_D = int
+#: GP input dimension.
+_Din = int
+
+# ---------------------------------------------------------------------------
+# Acquisition function type
+# ---------------------------------------------------------------------------
+
+#: A callable that maps (candidate_points: Tensor) -> Tensor (acquisition values).
+AcquisitionFn: TypeAlias = Callable[[Tensor], Tensor]
+
+# ---------------------------------------------------------------------------
+# Protocols
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class BioreactorConnector(Protocol):
+    """Protocol that all bioreactor data connectors must satisfy.
+
+    Both the real OPC UA client and the ambr®250 emulator implement this
+    protocol so that the :class:`~perfusio.twin.digital_twin.DigitalTwin`
+    can be tested offline.
+    """
+
+    async def read_sample(self, day: int) -> Mapping[str, float]:
+        """Return the latest at-line sample for *day*.
+
+        Parameters
+        ----------
+        day:
+            Culture day index (1-based).
+
+        Returns
+        -------
+        Mapping[str, float]
+            Species name → measured value, e.g.
+            ``{"VCD": 12.3, "Via": 97.1, "Glc": 1.8}``.
+
+        Raises
+        ------
+        ConnectionError
+            If the connector is offline and cannot recover.
+        """
+        ...
+
+    async def write_setpoints(self, setpoints: Mapping[str, float]) -> None:
+        """Write control setpoints to the reactor controller.
+
+        Parameters
+        ----------
+        setpoints:
+            Control variable name → desired value.
+
+        Raises
+        ------
+        PermissionError
+            If the connector is in read-only mode
+            (``--allow-write`` flag not provided).
+        ConnectionError
+            If the write fails.
+        """
+        ...
+
+    async def is_alive(self) -> bool:
+        """Return ``True`` if the connection is healthy."""
+        ...
+
+
+@runtime_checkable
+class Fittable(Protocol):
+    """Any object with a ``fit`` method."""
+
+    def fit(self, *args: Any, **kwargs: Any) -> None:
+        """Fit the model in-place."""
+        ...
+
+
+@runtime_checkable
+class Predictable(Protocol):
+    """Any object with a ``predict`` method returning a Tensor."""
+
+    def predict(self, x: Tensor) -> Tensor:
+        """Return point predictions at *x*."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Callback / hook types
+# ---------------------------------------------------------------------------
+
+#: A hook called after every digital-twin step with the step result.
+StepCallback: TypeAlias = Callable[..., None]
+
+#: Factory producing a fresh model instance (used by ensemble).
+ModelFactory: TypeAlias = Callable[[], Any]
+
+# ---------------------------------------------------------------------------
+# Device / dtype helpers
+# ---------------------------------------------------------------------------
+
+#: Default torch dtype — double precision everywhere.
+DEFAULT_DTYPE: torch.dtype = torch.float64
+DEFAULT_DEVICE: torch.device = torch.device("cpu")

perfusio/bed/__init__.py

@@ -0,0 +1,37 @@
+"""Bayesian Experimental Design (BED) sub-package for ``perfusio``.
+
+Implements the full BED decision loop described in Gadiyar et al. (2026) §3.2,
+including:
+
+- Objective function values (OFV) — target-tracking and multi-objective.
+- All 11 BoTorch acquisition functions (PI, EI, LogEI, UCB, qEI, qLogEI,
+  qUCB, qEHVI, qNEHVI, qNParEGO) plus constrained variants.
+- Acquisition optimisation over the design space.
+- Pareto front computation and hypervolume indicator.
+- High-level :class:`BEDPolicy` daily decision loop.
+
+Public API
+----------
+- :class:`~perfusio.bed.objectives.TargetTrackingOFV`
+- :class:`~perfusio.bed.objectives.MultiObjectiveOFV`
+- :func:`~perfusio.bed.acquisitions.build_acquisition`
+- :func:`~perfusio.bed.search.optimise_acquisition`
+- :func:`~perfusio.bed.pareto.compute_pareto_front`
+- :class:`~perfusio.bed.policies.BEDPolicy`
+"""
+
+from perfusio.bed.acquisitions import build_acquisition
+from perfusio.bed.objectives import MultiObjectiveOFV, TargetTrackingOFV
+from perfusio.bed.pareto import compute_pareto_front, hypervolume
+from perfusio.bed.policies import BEDPolicy
+from perfusio.bed.search import optimise_acquisition
+
+__all__ = [
+    "BEDPolicy",
+    "MultiObjectiveOFV",
+    "TargetTrackingOFV",
+    "build_acquisition",
+    "compute_pareto_front",
+    "hypervolume",
+    "optimise_acquisition",
+]

perfusio/bed/acquisitions.py

@@ -0,0 +1,219 @@
+"""BoTorch acquisition function factory for Bayesian Experimental Design.
+
+Provides :func:`build_acquisition`, a single entry-point that constructs any of
+the 11 acquisition functions supported by ``perfusio``:
+
+Single-objective (analytic):
+    ``PI``, ``EI``, ``LogEI``, ``UCB``
+
+Single-objective (Monte Carlo):
+    ``qEI``, ``qLogEI``, ``qUCB``
+
+Multi-objective (Monte Carlo):
+    ``qEHVI``, ``qNEHVI``, ``qNParEGO``
+
+Constrained variants are automatically applied when ``constraints`` are passed.
+
+References
+----------
+.. [Balandat2020] Balandat, M., et al. (2020). BoTorch: A Framework for
+   Efficient Monte-Carlo Bayesian Optimization. NeurIPS.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import botorch.acquisition as ba
+import botorch.acquisition.multi_objective as bamo
+import torch
+from botorch.acquisition.analytic import (
+    ExpectedImprovement,
+    LogExpectedImprovement,
+    ProbabilityOfImprovement,
+    UpperConfidenceBound,
+)
+from botorch.acquisition.monte_carlo import (
+    qExpectedImprovement,
+    qUpperConfidenceBound,
+)
+from botorch.acquisition.multi_objective.parego import qLogNParEGO
+from botorch.models.model import Model
+from torch import Tensor
+
+# Supported acquisition names
+_SINGLE_OBJ_ANALYTIC = {"PI", "EI", "LogEI", "UCB"}
+_SINGLE_OBJ_MC = {"qEI", "qLogEI", "qUCB"}
+_MULTI_OBJ_MC = {"qEHVI", "qNEHVI", "qNParEGO"}
+ALL_ACQUISITIONS = _SINGLE_OBJ_ANALYTIC | _SINGLE_OBJ_MC | _MULTI_OBJ_MC
+
+
+def build_acquisition(
+    name: str,
+    model: Model,
+    best_f: float | None = None,
+    beta: float = 0.2,
+    ref_point: list[float] | None = None,
+    partitioning: Any = None,
+    sampler: Any = None,
+    constraints: list[Callable[[Tensor], Tensor]] | None = None,
+    **kwargs: Any,
+) -> ba.AcquisitionFunction:
+    """Construct a BoTorch acquisition function by name.
+
+    Parameters
+    ----------
+    name:
+        One of: ``PI``, ``EI``, ``LogEI``, ``UCB``,
+        ``qEI``, ``qLogEI``, ``qUCB``, ``qEHVI``, ``qNEHVI``, ``qNParEGO``.
+    model:
+        Fitted BoTorch / GPyTorch surrogate model.
+    best_f:
+        Incumbent best observed value.  Required for ``PI``, ``EI``,
+        ``LogEI``, ``qEI``, ``qLogEI``.
+    beta:
+        UCB exploration parameter.  Required for ``UCB``, ``qUCB``.
+    ref_point:
+        Reference point for hypervolume-based acquisitions (``qEHVI``,
+        ``qNEHVI``).  Should be strictly dominated by all feasible points.
+    partitioning:
+        Pre-computed box decomposition (``NondominatedPartitioning``).
+        Required for ``qEHVI``.
+    sampler:
+        MC sampler (``IIDNormalSampler`` or ``SobolQMCNormalSampler``).
+        Defaults to ``SobolQMCNormalSampler(512)`` for MC acquisitions.
+    constraints:
+        Optional list of constraint callables ``c(X) <= 0`` to enforce.
+        Applied as soft-constraint penalties where available.
+    **kwargs:
+        Additional keyword arguments forwarded to the acquisition constructor.
+
+    Returns
+    -------
+    botorch.acquisition.AcquisitionFunction
+
+    Raises
+    ------
+    ValueError
+        If *name* is not a recognised acquisition type.
+    """
+    if name not in ALL_ACQUISITIONS:
+        msg = f"Unknown acquisition '{name}'. Choose one of: {sorted(ALL_ACQUISITIONS)}"
+        raise ValueError(msg)
+
+    if sampler is None and name in (_SINGLE_OBJ_MC | _MULTI_OBJ_MC):
+        from botorch.sampling.normal import SobolQMCNormalSampler
+
+        sampler = SobolQMCNormalSampler(sample_shape=torch.Size([512]))
+
+    # ── Analytic single-objective ──────────────────────────────────────────
+    if name == "PI":
+        _require(best_f, "PI", "best_f")
+        assert best_f is not None
+        return ProbabilityOfImprovement(model=model, best_f=best_f, **kwargs)
+
+    if name == "EI":
+        _require(best_f, "EI", "best_f")
+        assert best_f is not None
+        return ExpectedImprovement(model=model, best_f=best_f, **kwargs)
+
+    if name == "LogEI":
+        _require(best_f, "LogEI", "best_f")
+        assert best_f is not None
+        return LogExpectedImprovement(model=model, best_f=best_f, **kwargs)
+
+    if name == "UCB":
+        return UpperConfidenceBound(model=model, beta=beta, **kwargs)
+
+    # ── MC single-objective ────────────────────────────────────────────────
+    if name == "qEI":
+        _require(best_f, "qEI", "best_f")
+        assert best_f is not None
+        if constraints:
+            return qExpectedImprovement(
+                model=model, best_f=best_f, sampler=sampler, constraints=constraints, **kwargs
+            )
+        return qExpectedImprovement(model=model, best_f=best_f, sampler=sampler, **kwargs)
+
+    if name == "qLogEI":
+        _require(best_f, "qLogEI", "best_f")
+        assert best_f is not None
+        from botorch.acquisition.logei import qLogExpectedImprovement
+
+        return qLogExpectedImprovement(model=model, best_f=best_f, sampler=sampler, **kwargs)
+
+    if name == "qUCB":
+        return qUpperConfidenceBound(model=model, beta=beta, sampler=sampler, **kwargs)
+
+    # ── Multi-objective MC ─────────────────────────────────────────────────
+    if name == "qEHVI":
+        _require(ref_point, "qEHVI", "ref_point")
+        _require(partitioning, "qEHVI", "partitioning")
+        assert ref_point is not None
+        return bamo.qExpectedHypervolumeImprovement(
+            model=model,
+            ref_point=ref_point,
+            partitioning=partitioning,
+            sampler=sampler,
+            constraints=constraints,
+            **kwargs,
+        )
+
+    if name == "qNEHVI":
+        _require(ref_point, "qNEHVI", "ref_point")
+        assert ref_point is not None
+        # X_baseline defaults to the model's training inputs when not supplied
+        _x_bl = kwargs.pop(
+            "X_baseline",
+            model.train_inputs[0]  # pyright: ignore[reportIndexIssue]
+            if hasattr(model, "train_inputs") and model.train_inputs
+            else None,  # type: ignore[attr-defined]
+        )
+        if _x_bl is None:
+            msg = "Acquisition 'qNEHVI' requires 'X_baseline' or a fitted model with train_inputs."
+            raise ValueError(msg)
+        # Strip leading batch dim produced by batched multi-output GPs
+        if isinstance(_x_bl, Tensor) and _x_bl.dim() == 3:
+            _x_bl = _x_bl[0]
+        return bamo.qNoisyExpectedHypervolumeImprovement(
+            model=model,
+            ref_point=ref_point,
+            X_baseline=_x_bl,
+            sampler=sampler,
+            constraints=constraints,
+            **kwargs,
+        )
+
+    if name == "qNParEGO":
+        _x_bl = kwargs.pop(
+            "X_baseline",
+            model.train_inputs[0]  # pyright: ignore[reportIndexIssue]
+            if hasattr(model, "train_inputs") and model.train_inputs
+            else None,  # type: ignore[attr-defined]
+        )
+        if _x_bl is None:
+            msg = (
+                "Acquisition 'qNParEGO' requires 'X_baseline' or a fitted model with train_inputs."
+            )
+            raise ValueError(msg)
+        # Strip leading batch dim produced by batched multi-output GPs
+        if isinstance(_x_bl, Tensor) and _x_bl.dim() == 3:
+            _x_bl = _x_bl[0]
+        return qLogNParEGO(
+            model=model,
+            X_baseline=_x_bl,
+            sampler=sampler,
+            constraints=constraints,
+            **kwargs,
+        )
+
+    # Should never reach here — kept for static analysis
+    msg = f"Unhandled acquisition name: {name}"
+    raise AssertionError(msg)
+
+
+def _require(value: object | None, acq_name: str, param_name: str) -> None:
+    if value is None:
+        msg = f"Acquisition '{acq_name}' requires '{param_name}' to be provided."
+        raise ValueError(msg)

perfusio/bed/objectives.py

@@ -0,0 +1,238 @@
+"""Objective function values (OFVs) for Bayesian Experimental Design.
+
+Implements Gadiyar et al. (2026) Eq. 7:
+
+.. math::
+    \\text{OFV}(\\mathbf{u}) =
+      \\sum_{j=1}^{3}
+      \\left( \\hat{y}_{t+j}(\\mathbf{u}) - y_{\\text{target}} \\right)^2
+
+where :math:`\\hat{y}_{t+j}` is the *j*-step-ahead hybrid model prediction
+(50th-percentile / mean) for the chosen objective species (e.g. VCD, Titer,
+viability).
+
+The OFV is used to evaluate candidate control setpoints :math:`\\mathbf{u}`
+proposed by the acquisition function.
+
+References
+----------
+.. [Gadiyar2026] Gadiyar et al. (2026), §3.2, Eq. (7).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import torch
+from torch import Tensor
+
+if TYPE_CHECKING:
+    from perfusio.hybrid.model import HybridStateSpaceModel
+
+
+@dataclass
+class TargetSpec:
+    """Specification for a single tracked species target."""
+
+    species_index: int  # column index in the state tensor
+    target: float  # target value
+    weight: float = 1.0  # relative weight in the OFV sum
+
+
+class TargetTrackingOFV:
+    """3-step-ahead squared-error OFV from Gadiyar et al. (2026) Eq. 7.
+
+    Parameters
+    ----------
+    hybrid:
+        Fitted hybrid model for forecasting.
+    targets:
+        List of :class:`TargetSpec` objects — one per tracked species.
+    horizon:
+        Prediction horizon in days.  Default 3 (Gadiyar §3.2).
+    n_samples:
+        MC rollout samples.  Default 100 (fast for BED inner loop).
+    seed:
+        Fixed random seed for reproducible OFV evaluations.
+
+    Examples
+    --------
+    >>> from perfusio.bed.objectives import TargetTrackingOFV, TargetSpec
+    >>> # assume `hybrid` is a fitted HybridStateSpaceModel
+    >>> ofv = TargetTrackingOFV(
+    ...     hybrid=hybrid,
+    ...     targets=[TargetSpec(0, target=30.0, weight=1.0)],  # VCD → 30e6 cells/mL
+    ... )
+    >>> # ofv.evaluate(c0, u_candidate)  # returns scalar Tensor
+    """
+
+    def __init__(
+        self,
+        targets: list[TargetSpec],
+        hybrid: HybridStateSpaceModel | None = None,
+        horizon: int = 3,
+        n_samples: int = 100,
+        seed: int = 42,
+    ) -> None:
+        self.hybrid = hybrid
+        self.targets = targets
+        self.horizon = horizon
+        self.n_samples = n_samples
+        self.seed = seed
+
+    def evaluate(self, c0: Tensor, u: Tensor) -> Tensor:
+        """Evaluate the OFV for a candidate control vector.
+
+        Parameters
+        ----------
+        c0:
+            Current state, shape ``(n_species,)``.
+        u:
+            Candidate control vector, shape ``(n_controls,)``.
+            Applied *constantly* over the horizon.
+
+        Returns
+        -------
+        Tensor
+            Scalar OFV value (lower = better).
+        """
+        from perfusio.hybrid.forecast import forecast_run
+
+        if self.hybrid is None:
+            msg = "TargetTrackingOFV.evaluate() requires a hybrid model; pass hybrid= at construction."
+            raise RuntimeError(msg)
+
+        u_seq = u.unsqueeze(0).expand(self.horizon, -1)
+        preds = forecast_run(
+            self.hybrid,
+            c0,
+            u_seq,
+            horizon=self.horizon,
+            n_samples=self.n_samples,
+            seed=self.seed,
+        )
+        # Use posterior mean for OFV (Gadiyar Eq. 7)
+        mean_traj = preds["mean"]  # (horizon, n_species)
+
+        ofv = torch.tensor(0.0, dtype=mean_traj.dtype)
+        for spec in self.targets:
+            k = spec.species_index
+            for j in range(self.horizon):
+                ofv = ofv + spec.weight * (mean_traj[j, k] - spec.target) ** 2
+        return ofv
+
+    def score_trajectories(self, Y: Tensor) -> Tensor:
+        """Score a batch of pre-computed trajectories against targets.
+
+        Useful for evaluating acquisition function surrogates directly on GP
+        prediction samples without running the full hybrid model.
+
+        Parameters
+        ----------
+        Y:
+            Pre-computed trajectories, shape ``(B, horizon, n_species)``.
+
+        Returns
+        -------
+        Tensor
+            OFV values, shape ``(B,)`` — higher is better (negative SSE).
+        """
+        total = torch.zeros(Y.shape[0], dtype=Y.dtype, device=Y.device)
+        for spec in self.targets:
+            vals = Y[:, :, spec.species_index]  # (B, horizon)
+            sse = ((vals - spec.target) ** 2).mean(dim=-1)  # (B,)
+            total = total - spec.weight * sse
+        return total
+
+    def evaluate_batch(self, c0: Tensor, u_batch: Tensor) -> Tensor:
+        """Evaluate OFV for a batch of candidate controls.
+
+        Parameters
+        ----------
+        c0:
+            Current state, shape ``(n_species,)``.
+        u_batch:
+            Candidate controls, shape ``(B, n_controls)``.
+
+        Returns
+        -------
+        Tensor
+            OFV values, shape ``(B,)``.
+        """
+        return torch.stack([self.evaluate(c0, u_batch[i]) for i in range(u_batch.shape[0])])
+
+
+class MultiObjectiveOFV:
+    """Vector-valued OFV for multi-objective BED.
+
+    Returns one OFV per objective (e.g. maximise titer AND minimise ammonium).
+    Used with multi-objective acquisition functions (qEHVI, qNEHVI, qNParEGO).
+
+    Parameters
+    ----------
+    hybrid:
+        Fitted hybrid model.
+    objectives:
+        List of ``(species_index, target, direction)`` tuples where
+        ``direction`` is ``+1`` for maximisation and ``-1`` for minimisation
+        (the sign is applied to the OFV before passing to botorch acqf).
+    horizon:
+        Prediction horizon.
+    n_samples:
+        MC rollout samples.
+    seed:
+        Random seed.
+    """
+
+    def __init__(
+        self,
+        hybrid: HybridStateSpaceModel,
+        objectives: list[tuple[int, float, float]],
+        horizon: int = 3,
+        n_samples: int = 100,
+        seed: int = 42,
+    ) -> None:
+        self.hybrid = hybrid
+        self.objectives = objectives
+        self.horizon = horizon
+        self.n_samples = n_samples
+        self.seed = seed
+
+    def evaluate(self, c0: Tensor, u: Tensor) -> Tensor:
+        """Return the multi-objective OFV vector for one candidate control.
+
+        Parameters
+        ----------
+        c0:
+            Current state, shape ``(n_species,)``.
+        u:
+            Candidate control, shape ``(n_controls,)``.
+
+        Returns
+        -------
+        Tensor
+            Shape ``(n_objectives,)``.  Positive values = better for botorch
+            (all objectives are negated and then passed as maximisation).
+        """
+        from perfusio.hybrid.forecast import forecast_run
+
+        u_seq = u.unsqueeze(0).expand(self.horizon, -1)
+        preds = forecast_run(
+            self.hybrid,
+            c0,
+            u_seq,
+            horizon=self.horizon,
+            n_samples=self.n_samples,
+            seed=self.seed,
+        )
+        mean_traj = preds["mean"]  # (horizon, n_species)
+
+        vals = []
+        for k, target, direction in self.objectives:
+            # Sum of squared deviations (lower = better)
+            sse = sum((mean_traj[j, k] - target) ** 2 for j in range(self.horizon))
+            # Negate so that botorch maximises (smaller SSE → larger objective)
+            vals.append(-float(direction) * sse)  # type: ignore[arg-type]
+
+        return torch.tensor(vals, dtype=mean_traj.dtype)