otwin 0.2.0__py3-none-any.whl

otwin/__init__.py

@@ -0,0 +1,91 @@
+"""Otwin: digital twins whose physics is checked, not claimed.
+
+A twin built here is an energy-based model -- a bond graph in state-space form.
+Power is routed by ``J``, dissipated by ``R``, stored by ``H``, and crosses the
+boundary through ``g``. With the terminals open, stored energy cannot increase:
+not approximately, not for well-chosen parameters, not only inside the range you
+fitted. It is an algebraic property, so it holds at any step size and any
+horizon.
+
+That is a falsifiable claim, so something checks it. ``otwin-spec`` is a type
+test procedure -- reference cases with closed-form answers, and deliberately
+broken implementations proving each check catches the fault it was written for.
+
+The package follows the ISO 13374 processing blocks, so the module layout is
+the one a condition-monitoring engineer already has in their head:
+
+    otwin.io          DA   Data Acquisition       SunSpec Modbus, Modbus TCP/RTU
+    otwin.signal      DM   Data Manipulation      resampling, gaps, units
+    otwin.estimate    SD   State Detection        EKF, MHE, energy-consistent observer
+    otwin.model       HA   Health Assessment      the energy-based model itself
+    otwin.forecast    PA   Prognostic Assessment  forecasts, skill, calibrated bands
+    otwin.advise      AG   Advisory Generation    the validity envelope, and refusal
+
+Ten seconds:
+
+    >>> import numpy as np
+    >>> from otwin.model import PortHamiltonianSystem, integrate_phs
+    >>>
+    >>> # A damped oscillator: a spring, a mass, and a damper.
+    >>> osc = PortHamiltonianSystem(
+    ...     H      = lambda x: 0.5 * 2.0 * x[0]**2 + 0.5 * x[1]**2,
+    ...     grad_H = lambda x: np.array([2.0 * x[0], x[1]]),
+    ...     J      = lambda x: np.array([[0.0, 1.0], [-1.0, 0.0]]),
+    ...     R      = lambda x: np.array([[0.0, 0.0], [0.0, 0.3]]),
+    ...     g      = lambda x: np.array([[0.0], [1.0]]),
+    ...     n_states=2, n_inputs=1,
+    ... )
+    >>> t = np.linspace(0, 20, 400)
+    >>> sol = integrate_phs(osc, np.array([1.0, 0.0]), t, np.zeros((400, 1)))
+    >>> E = np.array([osc.energy(x) for x in sol["x"]])
+    >>> bool(np.all(np.diff(E) <= 1e-9))   # holds at every step, by construction
+    True
+"""
+
+__version__ = "0.2.0"
+
+from otwin.interfaces import (
+    MANIFEST_VERSION,
+    Array,
+    Baseline,
+    EmpiricalLawModel,
+    Estimator,
+    EvaluationProtocol,
+    Forecast,
+    HasEnergyGradient,
+    Integrator,
+    Interval,
+    IrreversibleModel,
+    MetricSet,
+    PortHamiltonianModel,
+    Provenance,
+    Report,
+    Splitter,
+    TwinManifest,
+    TwinModel,
+    UncertaintyModel,
+)
+
+__all__ = [
+    "__version__",
+    # The interface specification. Everything else is an implementation of it.
+    "TwinModel",
+    "PortHamiltonianModel",
+    "HasEnergyGradient",
+    "IrreversibleModel",
+    "EmpiricalLawModel",
+    "Integrator",
+    "Estimator",
+    "UncertaintyModel",
+    "Baseline",
+    "Splitter",
+    "EvaluationProtocol",
+    "Forecast",
+    "Interval",
+    "MetricSet",
+    "Report",
+    "TwinManifest",
+    "Provenance",
+    "MANIFEST_VERSION",
+    "Array",
+]

otwin/advise/__init__.py

@@ -0,0 +1,9 @@
+"""Advisory Generation (ISO 13374 block AG): what to do, or why we won't say.
+
+The interesting part of an advisory layer is not what it recommends. It is
+what it refuses. See :mod:`otwin.advise.envelope`.
+"""
+
+from .envelope import Breach, Envelope, OutsideEnvelope, Verdict
+
+__all__ = ["Envelope", "Verdict", "Breach", "OutsideEnvelope"]

otwin/advise/envelope.py

@@ -0,0 +1,294 @@
+"""The twin can say no.
+
+A model that always returns a number is not being careful, it is being polite.
+Every forecast this library produces carries a validity envelope: the operating
+range the model was actually identified over, the horizon it was actually
+validated to, and whether its intervals have actually been checked against
+held-out data. Ask outside that envelope and you get a refusal with a reason,
+not a plausible number.
+
+This is the ISO 13374 Advisory Generation block (AG), and it is the difference
+between a twin and a plotting library. A confident wrong answer about when a
+40 MWh bank reaches end of life costs more than no answer at all.
+
+The envelope is read from the :class:`~otwin.interfaces.TwinManifest` -- the
+same record that says what was estimated, under which split protocol, and at
+what measured coverage. Nothing here is inferred. If the manifest does not
+record that something was checked, the answer is that it was not checked, and
+``not yet checked`` is not the same as ``fine``.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+
+class OutsideEnvelope(RuntimeError):
+    """The question falls outside what this twin has been shown to answer."""
+
+    def __init__(self, verdict: "Verdict"):
+        self.verdict = verdict
+        super().__init__(verdict.explain())
+
+
+@dataclass(frozen=True)
+class Breach:
+    """One reason a request falls outside the envelope."""
+
+    kind: str
+    detail: str
+    observed: float | None = None
+    limit: float | None = None
+
+    def __str__(self) -> str:
+        if self.observed is None or self.limit is None:
+            return f"{self.kind}: {self.detail}"
+        return (
+            f"{self.kind}: {self.detail} "
+            f"(asked for {self.observed:g}, validated to {self.limit:g})"
+        )
+
+
+@dataclass
+class Verdict:
+    """What the twin is willing to say, and why.
+
+    Attributes:
+        answerable: Whether the question is inside the validated envelope.
+        breaches: Every reason it is not. Empty when ``answerable``.
+        checked: Every check that ran and passed -- so a clean verdict is
+            evidence rather than silence.
+    """
+
+    answerable: bool
+    breaches: list[Breach] = field(default_factory=list)
+    checked: list[str] = field(default_factory=list)
+
+    def __bool__(self) -> bool:
+        return self.answerable
+
+    def explain(self) -> str:
+        if self.answerable:
+            passed = "; ".join(self.checked) or "no checks configured"
+            return f"inside the validated envelope ({passed})"
+        lines = ["outside the validated envelope:"]
+        lines += [f"  - {b}" for b in self.breaches]
+        lines.append("")
+        lines.append(
+            "This is a refusal, not a failure. The twin has not been shown to "
+            "answer this question, and returning a number anyway would hide that."
+        )
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "answerable": self.answerable,
+            "breaches": [
+                {
+                    "kind": b.kind,
+                    "detail": b.detail,
+                    "observed": b.observed,
+                    "limit": b.limit,
+                }
+                for b in self.breaches
+            ],
+            "checked": list(self.checked),
+        }
+
+
+@dataclass
+class Envelope:
+    """The range over which a twin has been shown to work.
+
+    Args:
+        state_bounds: Per-state ``(low, high)`` the model was identified over.
+            ``None`` for a state leaves it unconstrained.
+        max_horizon: Longest forecast horizon that was actually validated, in
+            steps. ``None`` means no horizon was validated -- which is a
+            refusal for every horizon, not a licence for all of them.
+        requires_validated: Refuse if the manifest does not record a
+            leakage-free validation. Default True.
+        requires_calibrated: Refuse if interval coverage was never measured.
+            Only applies to requests that ask for an interval.
+        max_extrapolation: How far outside ``state_bounds`` to tolerate, as a
+            fraction of each range. 0.0 means none at all.
+
+    Example:
+        >>> env = Envelope(state_bounds=[(0.0, 1.0)], max_horizon=500)
+        >>> v = env.check(state=[0.4], horizon=100)
+        >>> bool(v)
+        True
+        >>> v = env.check(state=[0.4], horizon=900)
+        >>> bool(v)
+        False
+        >>> print(v.breaches[0])
+        horizon: beyond the validated forecast horizon (asked for 900, validated to 500)
+    """
+
+    state_bounds: list[tuple[float, float] | None] | None = None
+    max_horizon: int | None = None
+    requires_validated: bool = True
+    requires_calibrated: bool = True
+    max_extrapolation: float = 0.0
+
+    # ------------------------------------------------------------------
+    @classmethod
+    def from_manifest(cls, manifest: Any, **overrides: Any) -> "Envelope":
+        """Build an envelope from what a fitted twin actually recorded.
+
+        Reads ``validation`` and ``calibration`` off a
+        :class:`~otwin.interfaces.TwinManifest`. Fields the manifest does not
+        carry stay ``None``, which is a refusal rather than a default.
+        """
+        validation = getattr(manifest, "validation", None) or {}
+        kwargs: dict[str, Any] = {
+            "max_horizon": validation.get("horizon"),
+            "state_bounds": validation.get("state_bounds"),
+        }
+        kwargs.update(overrides)
+        return cls(**kwargs)
+
+    # ------------------------------------------------------------------
+    def check(
+        self,
+        state: npt.ArrayLike | None = None,
+        horizon: int | None = None,
+        manifest: Any = None,
+        wants_interval: bool = False,
+    ) -> Verdict:
+        """Decide whether this question is inside the envelope.
+
+        Args:
+            state: The operating point the forecast starts from.
+            horizon: Steps ahead being requested.
+            manifest: The fitted twin's record, for the validation and
+                calibration checks.
+            wants_interval: Whether the caller is asking for an uncertainty
+                band. Calibration is only required if they are.
+
+        Returns:
+            A :class:`Verdict`. Truthy when the question can be answered.
+        """
+        breaches: list[Breach] = []
+        checked: list[str] = []
+
+        if horizon is not None:
+            if self.max_horizon is None:
+                breaches.append(
+                    Breach(
+                        "horizon",
+                        "no forecast horizon has been validated for this twin",
+                    )
+                )
+            elif horizon > self.max_horizon:
+                breaches.append(
+                    Breach(
+                        "horizon",
+                        "beyond the validated forecast horizon",
+                        float(horizon),
+                        float(self.max_horizon),
+                    )
+                )
+            else:
+                checked.append(f"horizon {horizon} <= {self.max_horizon}")
+
+        if state is not None and self.state_bounds is None:
+            # Symmetric with the horizon check above. An operating range that
+            # was never recorded is a refusal, not a licence.
+            #
+            # The previous version skipped this branch entirely when
+            # `state_bounds` was None, so a twin with no recorded range
+            # returned a clean verdict for any operating point at all -- a
+            # state of charge of 1e12 came back answerable with zero breaches.
+            # `from_manifest` already states the intended rule: fields the
+            # manifest does not carry stay None, "which is a refusal rather
+            # than a default". That held for `max_horizon` and not for this.
+            breaches.append(
+                Breach(
+                    "state",
+                    "no operating range has been recorded for this twin, so no "
+                    "operating point can be shown to be inside it",
+                )
+            )
+        elif state is not None and self.state_bounds is not None:
+            x = np.atleast_1d(np.asarray(state, dtype=float))
+            if len(x) != len(self.state_bounds):
+                breaches.append(
+                    Breach(
+                        "state",
+                        f"envelope describes {len(self.state_bounds)} states, "
+                        f"got {len(x)}",
+                    )
+                )
+            else:
+                for i, (value, bound) in enumerate(
+                    zip(x, self.state_bounds, strict=True)
+                ):
+                    if bound is None:
+                        continue
+                    lo, hi = float(bound[0]), float(bound[1])
+                    slack = self.max_extrapolation * (hi - lo)
+                    if value < lo - slack:
+                        breaches.append(
+                            Breach(
+                                "state",
+                                f"state {i} below the identified range",
+                                float(value),
+                                lo - slack,
+                            )
+                        )
+                    elif value > hi + slack:
+                        breaches.append(
+                            Breach(
+                                "state",
+                                f"state {i} above the identified range",
+                                float(value),
+                                hi + slack,
+                            )
+                        )
+                if not any(b.kind == "state" for b in breaches):
+                    checked.append("operating point inside the identified range")
+
+        if manifest is not None:
+            if self.requires_validated:
+                if not getattr(manifest, "is_validated", False):
+                    breaches.append(
+                        Breach(
+                            "validation",
+                            "this twin has never been validated under a "
+                            "leakage-free protocol",
+                        )
+                    )
+                else:
+                    checked.append("validated, leakage-free")
+
+            if wants_interval and self.requires_calibrated:
+                calibration = getattr(manifest, "calibration", None) or {}
+                if calibration.get("empirical_coverage") is None:
+                    breaches.append(
+                        Breach(
+                            "calibration",
+                            "interval coverage has never been measured, so the "
+                            "band has no demonstrated meaning",
+                        )
+                    )
+                else:
+                    checked.append(
+                        f"coverage measured at {calibration['empirical_coverage']:.2f}"
+                    )
+
+        return Verdict(answerable=not breaches, breaches=breaches, checked=checked)
+
+    # ------------------------------------------------------------------
+    def require(self, **kwargs: Any) -> Verdict:
+        """Like :meth:`check`, but raises :class:`OutsideEnvelope` on refusal.
+
+        Use this at the boundary of anything automated. A dispatch decision
+        should stop, not proceed with a caveat nobody reads.
+        """
+        verdict = self.check(**kwargs)
+        if not verdict:
+            raise OutsideEnvelope(verdict)
+        return verdict

otwin/estimate/__init__.py

@@ -0,0 +1,80 @@
+"""State estimation — the ISO 13374 **State Detection (SD)** block.
+
+ISO 13374 lays out six processing blocks for condition monitoring: Data
+Acquisition, Data Manipulation, **State Detection**, Health Assessment,
+Prognostic Assessment, and Advisory Generation. This package is the third. It
+is the block that turns a *simulation* into a *twin*.
+
+Without it, :mod:`otwin.model` gives you a physically correct trajectory that
+drifts away from the real machine the moment the initial condition, a
+parameter, or an unmodelled disturbance is slightly wrong — and nothing ever
+pulls it back. State detection closes that loop: measurements come in, the
+estimated state is corrected, and the twin tracks the asset instead of merely
+resembling it. Everything downstream depends on it. Health assessment scores a
+state; prognostics extrapolate one; advisory generation acts on one. If the
+state is wrong, all three are confidently wrong.
+
+What is here
+------------
+
+:class:`ExtendedKalmanFilter`
+    The workhorse. Continuous model, discrete measurements, RK4 propagation
+    with a matched transition Jacobian, Joseph-form covariance.
+
+:class:`KalmanFilter`
+    The exact linear filter. Its job is to be the closed-form answer that the
+    EKF is verified against, and to be the right tool when the model really is
+    linear.
+
+:class:`MovingHorizonEstimator`
+    When the state has hard physical limits — state of charge in ``[0, 1]``,
+    non-negative absolute temperature, a valve between shut and open — and an
+    estimate outside them would be acted on downstream.
+
+:class:`EnergyConsistentObserver`
+    For port-Hamiltonian twins. A Kalman correction knows nothing about the
+    stored energy ``H(x)`` and will happily push it uphill with no input to
+    have supplied it, destroying the passivity guarantee that the model was
+    built to provide. This observer bounds every correction by the energy that
+    actually flowed through the ports. See :mod:`otwin.estimate.energy`.
+
+A note on ``R_meas``
+--------------------
+
+Throughout this package the measurement-noise covariance is called ``R_meas``,
+never ``R``. In :mod:`otwin.model` ``R`` is the dissipation matrix of a
+port-Hamiltonian system. Both objects appear in the same call sites here, they
+are both square, both symmetric, and both positive semidefinite, so a mix-up
+type-checks, runs, and produces wrong estimates that look right. The name is
+ugly on purpose.
+
+Example:
+    >>> import numpy as np
+    >>> from otwin.estimate import ExtendedKalmanFilter
+    >>> class Decay:
+    ...     def rhs(self, x, u, t):
+    ...         return -0.5 * x
+    ...     def observe(self, x, u, t):
+    ...         return x.copy()
+    >>> ekf = ExtendedKalmanFilter(Decay(), Q=np.array([[1e-6]]),
+    ...                            R_meas=np.array([[1e-2]]),
+    ...                            P0=np.array([[1.0]]), x0=np.array([0.0]))
+    >>> ts = np.linspace(0.0, 2.0, 21)
+    >>> res = ekf.filter(np.exp(-0.5 * ts).reshape(-1, 1), None, ts)
+    >>> res.x.shape
+    (21, 1)
+"""
+
+from .energy import EnergyConsistentObserver, EnergyFilterResult
+from .kalman import ExtendedKalmanFilter, FilterResult
+from .linear import KalmanFilter
+from .mhe import MovingHorizonEstimator
+
+__all__ = [
+    "EnergyConsistentObserver",
+    "EnergyFilterResult",
+    "ExtendedKalmanFilter",
+    "FilterResult",
+    "KalmanFilter",
+    "MovingHorizonEstimator",
+]