phaseprobe 0.2.0__py3-none-any.whl

phaseprobe/errors.py

@@ -0,0 +1,31 @@
+"""PhaseProbe exception hierarchy and documented process exit codes."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    """Stable CLI exit-code contract."""
+
+    OK = 0
+    POLICY_FAILED = 1
+    INVALID_INPUT = 2
+    NUMERICAL_FAILURE = 3
+    INTERNAL_ERROR = 4
+
+
+class PhaseProbeError(Exception):
+    """Base class for expected PhaseProbe failures."""
+
+
+class ConfigurationError(PhaseProbeError):
+    """Raised when a configuration or user input is invalid."""
+
+
+class NumericalFailure(PhaseProbeError):
+    """Raised when integration produces an invalid state or solver failure."""
+
+
+class IntegrityError(PhaseProbeError):
+    """Raised when a replay fixture fails integrity validation."""

phaseprobe/examples/__init__.py

@@ -0,0 +1 @@
+"""Reference model definitions used by reproducible optional-dependency examples."""

phaseprobe/examples/scipy_models.py

@@ -0,0 +1,151 @@
+"""Genuine SciPy-backed Lorenz and Lotka-Volterra reference adapters."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+
+import numpy as np
+import numpy.typing as npt
+
+from phaseprobe.adapters.scipy import SolveIVPAdapter
+from phaseprobe.types import (
+    InvariantResult,
+    Parameters,
+    Scalar,
+    SimulationTrace,
+    State,
+    Tolerances,
+)
+
+FloatArray = npt.NDArray[np.float64]
+
+
+def lorenz_rhs(time: float, state: FloatArray, parameters: Parameters) -> tuple[float, ...]:
+    """Classic Lorenz equations; time is accepted by the solve_ivp contract."""
+
+    x, y, z = state
+    sigma = parameters["sigma"]
+    rho = parameters["rho"]
+    beta = parameters["beta"]
+    return (sigma * (y - x), x * (rho - z) - y, x * y - beta * z)
+
+
+def lorenz_observable(time: float, state: State, parameters: Parameters) -> Mapping[str, Scalar]:
+    x, y, z = state
+    return {"x": x, "y": y, "z": z, "radius": math.sqrt(x * x + y * y + z * z)}
+
+
+def lorenz_classifier(trace: SimulationTrace, tolerances: Tolerances) -> str:
+    bound = tolerances.get("state_bound", 100.0)
+    maximum = max(abs(value) for point in trace.points for value in point.state)
+    return "bounded-finite-window" if maximum <= bound else "declared-bound-exceeded"
+
+
+def lorenz_invariants(
+    trace: SimulationTrace, parameters: Parameters, tolerances: Tolerances
+) -> list[InvariantResult]:
+    bound = tolerances.get("state_bound", 100.0)
+    maximum = max(abs(value) for point in trace.points for value in point.state)
+    return [
+        InvariantResult(
+            name="declared-state-bound",
+            passed=maximum <= bound,
+            measured=maximum,
+            tolerance=bound,
+            detail="Maximum absolute state over the declared finite observation window.",
+        )
+    ]
+
+
+def lorenz_adapter(values: Mapping[str, object]) -> SolveIVPAdapter:
+    """Factory named by the explicit CLI configuration."""
+
+    return SolveIVPAdapter.from_config(
+        name="lorenz-scipy",
+        rhs=lorenz_rhs,
+        values=values,
+        observable=lorenz_observable,
+        classifier=lorenz_classifier,
+        invariant=lorenz_invariants,
+    )
+
+
+def predator_prey_rhs(time: float, state: FloatArray, parameters: Parameters) -> tuple[float, ...]:
+    prey, predator = state
+    alpha = parameters["alpha"]
+    beta = parameters["beta"]
+    delta = parameters["delta"]
+    gamma = parameters["gamma"]
+    return (
+        alpha * prey - beta * prey * predator,
+        delta * prey * predator - gamma * predator,
+    )
+
+
+def _first_integral(state: State, parameters: Parameters) -> float:
+    prey, predator = state
+    if prey <= 0.0 or predator <= 0.0:
+        return math.inf
+    return (
+        parameters["delta"] * prey
+        - parameters["gamma"] * math.log(prey)
+        + parameters["beta"] * predator
+        - parameters["alpha"] * math.log(predator)
+    )
+
+
+def predator_prey_observable(
+    time: float, state: State, parameters: Parameters
+) -> Mapping[str, Scalar]:
+    return {
+        "prey": state[0],
+        "predator": state[1],
+        "first_integral": _first_integral(state, parameters),
+    }
+
+
+def predator_prey_classifier(trace: SimulationTrace, tolerances: Tolerances) -> str:
+    positive = all(point.state[0] > 0.0 and point.state[1] > 0.0 for point in trace.points)
+    return "positive-oscillation" if positive else "non-positive-population"
+
+
+def predator_prey_invariants(
+    trace: SimulationTrace, parameters: Parameters, tolerances: Tolerances
+) -> list[InvariantResult]:
+    threshold = tolerances.get("invariant_drift", 1e-8)
+    reference = _first_integral(trace.points[0].state, parameters)
+    drift = max(abs(_first_integral(point.state, parameters) - reference) for point in trace.points)
+    minimum_population = min(value for point in trace.points for value in point.state)
+    return [
+        InvariantResult(
+            name="lotka-volterra-first-integral-drift",
+            passed=math.isfinite(drift) and drift <= threshold,
+            measured=drift,
+            tolerance=threshold,
+            detail="Maximum absolute drift of the declared Lotka-Volterra first integral.",
+        ),
+        InvariantResult(
+            name="positive-populations",
+            passed=minimum_population > 0.0,
+            measured=minimum_population,
+            tolerance=0.0,
+            detail="Minimum retained population; the policy requires a value strictly above zero.",
+        ),
+    ]
+
+
+def predator_prey_adapter(values: Mapping[str, object]) -> SolveIVPAdapter:
+    """Factory named by the explicit CLI configuration."""
+
+    return SolveIVPAdapter.from_config(
+        name="predator-prey-scipy",
+        rhs=predator_prey_rhs,
+        values=values,
+        observable=predator_prey_observable,
+        classifier=predator_prey_classifier,
+        invariant=predator_prey_invariants,
+    )
+
+
+__all__ = ["lorenz_adapter", "predator_prey_adapter"]

phaseprobe/generate.py

@@ -0,0 +1,72 @@
+"""Safe deterministic pytest generation from validated replay fixtures."""
+
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from phaseprobe.replay import validate_fixture, verify_replay
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratedTest:
+    """Generated fixed-template test and copied integrity-protected fixture."""
+
+    test_path: Path
+    fixture_path: Path
+
+
+def _safe_name(value: object) -> str:
+    candidate = re.sub(r"[^a-z0-9]+", "_", str(value).lower()).strip("_")
+    return candidate[:64] or "model"
+
+
+def generate_regression_test(fixture: Path, output_directory: Path) -> GeneratedTest:
+    """Validate evidence, copy its fixture, and emit a non-extensible pytest template."""
+
+    payload = validate_fixture(fixture)
+    verification = verify_replay(fixture)
+    if not verification.ok:
+        raise ValueError(
+            "replay fixture does not reproduce; refusing to generate a regression test"
+        )
+    model_name = _safe_name(payload.get("model"))
+    output_directory.mkdir(parents=True, exist_ok=True)
+    fixture_directory = output_directory / "fixtures"
+    fixture_directory.mkdir(exist_ok=True)
+    copied_fixture = fixture_directory / f"{model_name}-replay.json"
+    shutil.copyfile(fixture, copied_fixture)
+    test_path = output_directory / f"test_{model_name}_transition.py"
+    baseline = payload.get("baseline")
+    metadata = baseline.get("execution_metadata") if isinstance(baseline, dict) else None
+    adapter_configuration = (
+        metadata.get("adapter_configuration") if isinstance(metadata, dict) else None
+    )
+    scipy_backed = (
+        isinstance(adapter_configuration, dict)
+        and adapter_configuration.get("adapter") == "scipy.solve_ivp"
+    )
+    scipy_import = "import pytest\n" if scipy_backed else ""
+    scipy_guard = (
+        '\npytest.importorskip("scipy")\npytestmark = pytest.mark.scipy\n' if scipy_backed else ""
+    )
+    source = f'''"""Generated by PhaseProbe from a validated replay fixture."""
+
+from pathlib import Path
+
+{scipy_import}
+from phaseprobe.replay import verify_replay
+{scipy_guard}
+
+FIXTURE = Path(__file__).parent / "fixtures" / "{model_name}-replay.json"
+
+
+def test_{model_name}_transition_replays() -> None:
+    """Re-execute model/config/seed and verify the fixture's declared replay policy."""
+    result = verify_replay(FIXTURE)
+    assert result.ok, result.as_dict()
+'''
+    test_path.write_text(source, encoding="utf-8", newline="\n")
+    return GeneratedTest(test_path=test_path, fixture_path=copied_fixture)

phaseprobe/models/__init__.py

@@ -0,0 +1,36 @@
+"""Built-in deterministic model adapters."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import cast
+
+from phaseprobe.errors import ConfigurationError
+from phaseprobe.models.logistic import LogisticMapAdapter
+from phaseprobe.models.lorenz import LorenzAdapter
+from phaseprobe.models.predator_prey import PredatorPreyAdapter
+from phaseprobe.models.toggle import GeneticToggleAdapter
+from phaseprobe.types import ModelAdapter
+
+_MODELS: Mapping[str, ModelAdapter] = {
+    "logistic-map": cast(ModelAdapter, LogisticMapAdapter()),
+    "lorenz": cast(ModelAdapter, LorenzAdapter()),
+    "predator-prey": cast(ModelAdapter, PredatorPreyAdapter()),
+    "genetic-toggle": cast(ModelAdapter, GeneticToggleAdapter()),
+}
+
+
+def get_model(name: str) -> ModelAdapter:
+    """Return a built-in model adapter by stable identity."""
+
+    model = _MODELS.get(name)
+    if model is None:
+        choices = ", ".join(sorted(_MODELS))
+        raise ConfigurationError(f"unknown model {name!r}; choose one of: {choices}")
+    return model
+
+
+def model_names() -> tuple[str, ...]:
+    """Return stable built-in model names."""
+
+    return tuple(sorted(_MODELS))

phaseprobe/models/_common.py

@@ -0,0 +1,56 @@
+"""Shared validation and fixed-step integration helpers for built-in adapters."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+
+from phaseprobe.errors import ConfigurationError
+from phaseprobe.types import State
+
+Derivative = Callable[[State], State]
+
+
+def float_value(values: Mapping[str, object], name: str, default: float | None = None) -> float:
+    """Read a finite-number-shaped value; runtime finite checks happen in the engine."""
+
+    value = values.get(name, default)
+    if not isinstance(value, int | float) or isinstance(value, bool):
+        raise ConfigurationError(f"{name} must be a number")
+    return float(value)
+
+
+def initial_state(
+    config: Mapping[str, object], dimensions: Sequence[str], defaults: State
+) -> State:
+    """Read an optional named initial-state object."""
+
+    raw = config.get("initial_state")
+    if raw is None:
+        return defaults
+    if not isinstance(raw, dict):
+        raise ConfigurationError("model.initial_state must be an object")
+    values = raw
+    return tuple(float_value(values, dimension) for dimension in dimensions)
+
+
+def parameter(parameters: Mapping[str, float], name: str, default: float) -> float:
+    """Read a model parameter with a documented default."""
+
+    return float(parameters.get(name, default))
+
+
+def rk4_step(state: State, dt: float, derivative: Derivative) -> State:
+    """Advance an autonomous ODE with a deterministic classical RK4 step."""
+
+    k1 = derivative(state)
+    k2 = derivative(
+        tuple(value + 0.5 * dt * slope for value, slope in zip(state, k1, strict=False))
+    )
+    k3 = derivative(
+        tuple(value + 0.5 * dt * slope for value, slope in zip(state, k2, strict=False))
+    )
+    k4 = derivative(tuple(value + dt * slope for value, slope in zip(state, k3, strict=False)))
+    return tuple(
+        value + (dt / 6.0) * (a + 2.0 * b + 2.0 * c + d)
+        for value, a, b, c, d in zip(state, k1, k2, k3, k4, strict=False)
+    )

phaseprobe/models/logistic.py

@@ -0,0 +1,63 @@
+"""Logistic-map adapter and finite-period classifier."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+
+from phaseprobe.models._common import initial_state, parameter
+from phaseprobe.types import InvariantResult, Parameters, State, Tolerances, TracePoint
+
+
+class LogisticMapAdapter:
+    """The discrete logistic map ``x[n+1] = r*x[n]*(1-x[n])``."""
+
+    name = "logistic-map"
+    identity = "phaseprobe.builtin.logistic-map:v1"
+    dimensions = ("x",)
+
+    def initial_state(self, config: Mapping[str, object], seed: int) -> State:
+        del seed
+        return initial_state(config, self.dimensions, (0.2,))
+
+    def step(self, state: State, parameters: Parameters, dt: float) -> State:
+        del dt
+        r = parameter(parameters, "r", 3.44)
+        x = state[0]
+        return (r * x * (1.0 - x),)
+
+    def observe(self, state: State) -> Mapping[str, float]:
+        return {"x": state[0]}
+
+    def classify(self, trace: Sequence[TracePoint], tolerances: Tolerances) -> str:
+        values = [point.state[0] for point in trace]
+        tolerance = tolerances.get("period", 1e-8)
+        for period in (1, 2, 4, 8, 16):
+            if len(values) < 4 * period:
+                continue
+            tail = values[-4 * period :]
+            error = max(
+                abs(tail[index] - tail[index - period]) for index in range(period, len(tail))
+            )
+            if error <= tolerance:
+                return f"period-{period}"
+        return "aperiodic-or-unresolved"
+
+    def invariants(
+        self,
+        trace: Sequence[TracePoint],
+        parameters: Parameters,
+        tolerances: Tolerances,
+    ) -> list[InvariantResult]:
+        del parameters, tolerances
+        values = [point.state[0] for point in trace]
+        violation = max((max(-value, value - 1.0, 0.0) for value in values), default=0.0)
+        return [
+            InvariantResult(
+                name="unit-interval-boundedness",
+                passed=math.isfinite(violation) and violation == 0.0,
+                measured=violation,
+                tolerance=0.0,
+                detail="For 0 <= r <= 4 and 0 <= x <= 1, retained states should remain in [0, 1].",
+            )
+        ]

phaseprobe/models/lorenz.py

@@ -0,0 +1,64 @@
+"""Lorenz-system adapter for finite-time trajectory-divergence evidence."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+
+from phaseprobe.models._common import initial_state, parameter, rk4_step
+from phaseprobe.types import InvariantResult, Parameters, State, Tolerances, TracePoint
+
+
+class LorenzAdapter:
+    """Classical three-variable Lorenz equations integrated with fixed-step RK4."""
+
+    name = "lorenz"
+    identity = "phaseprobe.builtin.lorenz:v1"
+    dimensions = ("x", "y", "z")
+
+    def initial_state(self, config: Mapping[str, object], seed: int) -> State:
+        del seed
+        return initial_state(config, self.dimensions, (1.0, 1.0, 1.0))
+
+    def step(self, state: State, parameters: Parameters, dt: float) -> State:
+        sigma = parameter(parameters, "sigma", 10.0)
+        rho = parameter(parameters, "rho", 28.0)
+        beta = parameter(parameters, "beta", 8.0 / 3.0)
+
+        def derivative(current: State) -> State:
+            x, y, z = current
+            return (sigma * (y - x), x * (rho - z) - y, x * y - beta * z)
+
+        return rk4_step(state, dt, derivative)
+
+    def observe(self, state: State) -> Mapping[str, float]:
+        x, y, z = state
+        return {"x": x, "y": y, "z": z, "radius": math.sqrt(x * x + y * y + z * z)}
+
+    def classify(self, trace: Sequence[TracePoint], tolerances: Tolerances) -> str:
+        del tolerances
+        signs = {point.state[0] >= 0.0 for point in trace}
+        if len(signs) > 1:
+            return "two-lobe-finite-time-trajectory"
+        if trace and trace[-1].state[0] >= 0.0:
+            return "positive-lobe-finite-time-trajectory"
+        return "negative-lobe-finite-time-trajectory"
+
+    def invariants(
+        self,
+        trace: Sequence[TracePoint],
+        parameters: Parameters,
+        tolerances: Tolerances,
+    ) -> list[InvariantResult]:
+        del parameters
+        bound = tolerances.get("state_bound", 100.0)
+        measured = max((abs(value) for point in trace for value in point.state), default=0.0)
+        return [
+            InvariantResult(
+                name="declared-finite-state-bound",
+                passed=math.isfinite(measured) and measured <= bound,
+                measured=measured,
+                tolerance=bound,
+                detail="A diagnostic finite-time bound, not a mathematical invariant of the Lorenz system.",
+            )
+        ]

phaseprobe/models/predator_prey.py

@@ -0,0 +1,86 @@
+"""Lotka-Volterra predator-prey adapter with a conserved-quantity diagnostic."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+
+from phaseprobe.models._common import initial_state, parameter, rk4_step
+from phaseprobe.types import InvariantResult, Parameters, State, Tolerances, TracePoint
+
+
+class PredatorPreyAdapter:
+    """Conservative two-species Lotka-Volterra equations."""
+
+    name = "predator-prey"
+    identity = "phaseprobe.builtin.predator-prey:v1"
+    dimensions = ("prey", "predator")
+
+    def initial_state(self, config: Mapping[str, object], seed: int) -> State:
+        del seed
+        return initial_state(config, self.dimensions, (10.0, 5.0))
+
+    def step(self, state: State, parameters: Parameters, dt: float) -> State:
+        alpha = parameter(parameters, "alpha", 1.1)
+        beta = parameter(parameters, "beta", 0.4)
+        delta = parameter(parameters, "delta", 0.1)
+        gamma = parameter(parameters, "gamma", 0.4)
+
+        def derivative(current: State) -> State:
+            prey, predator = current
+            return (
+                alpha * prey - beta * prey * predator,
+                delta * prey * predator - gamma * predator,
+            )
+
+        return rk4_step(state, dt, derivative)
+
+    def observe(self, state: State) -> Mapping[str, float]:
+        return {"prey": state[0], "predator": state[1]}
+
+    def classify(self, trace: Sequence[TracePoint], tolerances: Tolerances) -> str:
+        del tolerances
+        if not trace:
+            return "unresolved"
+        minima = [min(point.state[index] for point in trace) for index in (0, 1)]
+        return "bounded-positive-oscillation" if min(minima) > 0.0 else "invalid-population"
+
+    def invariants(
+        self,
+        trace: Sequence[TracePoint],
+        parameters: Parameters,
+        tolerances: Tolerances,
+    ) -> list[InvariantResult]:
+        alpha = parameter(parameters, "alpha", 1.1)
+        beta = parameter(parameters, "beta", 0.4)
+        delta = parameter(parameters, "delta", 0.1)
+        gamma = parameter(parameters, "gamma", 0.4)
+        tolerance = tolerances.get("invariant_drift", 1e-5)
+
+        def conserved(state: State) -> float:
+            prey, predator = state
+            if prey <= 0.0 or predator <= 0.0:
+                return math.inf
+            return (
+                delta * prey - gamma * math.log(prey) + beta * predator - alpha * math.log(predator)
+            )
+
+        values = [conserved(point.state) for point in trace]
+        drift = max((abs(value - values[0]) for value in values), default=0.0)
+        min_population = min((value for point in trace for value in point.state), default=0.0)
+        return [
+            InvariantResult(
+                name="lotka-volterra-conserved-quantity",
+                passed=math.isfinite(drift) and drift <= tolerance,
+                measured=drift,
+                tolerance=tolerance,
+                detail="Maximum retained drift from the initial value of the analytic first integral.",
+            ),
+            InvariantResult(
+                name="positive-populations",
+                passed=min_population > 0.0,
+                measured=min_population,
+                tolerance=0.0,
+                detail="Both populations must remain strictly positive over the retained trajectory.",
+            ),
+        ]

phaseprobe/models/toggle.py

@@ -0,0 +1,73 @@
+"""Small mutually repressing genetic-toggle adapter."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+
+from phaseprobe.models._common import initial_state, parameter, rk4_step
+from phaseprobe.types import InvariantResult, Parameters, State, Tolerances, TracePoint
+
+
+class GeneticToggleAdapter:
+    """Dimensionless two-gene mutual-repression model."""
+
+    name = "genetic-toggle"
+    identity = "phaseprobe.builtin.genetic-toggle:v1"
+    dimensions = ("u", "v")
+
+    def initial_state(self, config: Mapping[str, object], seed: int) -> State:
+        del seed
+        return initial_state(config, self.dimensions, (3.0, 0.2))
+
+    def step(self, state: State, parameters: Parameters, dt: float) -> State:
+        alpha_u = parameter(parameters, "alpha_u", 3.0)
+        alpha_v = parameter(parameters, "alpha_v", 3.0)
+        hill_u = parameter(parameters, "hill_u", 2.0)
+        hill_v = parameter(parameters, "hill_v", 2.0)
+
+        def derivative(current: State) -> State:
+            u, v = current
+            return (
+                alpha_u / (1.0 + v**hill_v) - u,
+                alpha_v / (1.0 + u**hill_u) - v,
+            )
+
+        return rk4_step(state, dt, derivative)
+
+    def observe(self, state: State) -> Mapping[str, float]:
+        u, v = state
+        return {"u": u, "v": v, "difference": u - v}
+
+    def classify(self, trace: Sequence[TracePoint], tolerances: Tolerances) -> str:
+        if not trace:
+            return "unresolved"
+        threshold = tolerances.get("dominance", 0.05)
+        difference = trace[-1].state[0] - trace[-1].state[1]
+        if difference > threshold:
+            return "u-dominant"
+        if difference < -threshold:
+            return "v-dominant"
+        return "balanced"
+
+    def invariants(
+        self,
+        trace: Sequence[TracePoint],
+        parameters: Parameters,
+        tolerances: Tolerances,
+    ) -> list[InvariantResult]:
+        del parameters
+        bound = tolerances.get("state_bound", 10.0)
+        values = [value for point in trace for value in point.state]
+        low = min(values, default=0.0)
+        high = max(values, default=0.0)
+        violation = max(-low, high - bound, 0.0)
+        return [
+            InvariantResult(
+                name="nonnegative-declared-bound",
+                passed=math.isfinite(violation) and violation == 0.0,
+                measured=violation,
+                tolerance=0.0,
+                detail=f"Concentrations must remain in the declared interval [0, {bound:g}].",
+            )
+        ]