juniper-recurrence-model 0.1.0__py3-none-any.whl

juniper_recurrence_model/__init__.py

@@ -0,0 +1,27 @@
+"""juniper-recurrence-model — the model-specific core for the juniper-recurrence app.
+
+The selected model is **P3-C (LMU + Approach-C)**: a closed-form, variable-Δt Legendre
+Memory Unit discretisation (C1-clean, irregular-Δt-native). This package ships the Δt-native
+memory unit (:class:`VariableStepLMUMemory`), the fixed-order LMU regressor
+(:class:`LMURegressor`) implementing juniper-model-core's ``TrainableModel`` interface, and a
+lean loader (:func:`load_sequence_npz`) for the WS-1 3-D sequence NPZ contract.
+
+See the design of record ``notes/JUNIPER_RECURRENCE_MODEL_DETAILED_DESIGN_2026-06-14.md`` and
+the WS-4 build plan ``notes/JUNIPER_RECURRENCE_WS4_MODEL_BUILD_PLAN_2026-06-15.md`` (juniper-ml).
+"""
+
+from juniper_recurrence_model._version import __version__
+from juniper_recurrence_model.data import SequenceData, load_sequence_npz, sequence_data_from_arrays
+from juniper_recurrence_model.model import LMURegressor, LMUSerializer
+from juniper_recurrence_model.units import VariableStepLMUMemory, lmu_matrices
+
+__all__ = [
+    "__version__",
+    "LMURegressor",
+    "LMUSerializer",
+    "SequenceData",
+    "load_sequence_npz",
+    "sequence_data_from_arrays",
+    "VariableStepLMUMemory",
+    "lmu_matrices",
+]

juniper_recurrence_model/_version.py

@@ -0,0 +1,7 @@
+"""Single source of truth for the juniper-recurrence-model version.
+
+Kept import-free so setuptools can parse ``__version__`` statically at build
+time (``[tool.setuptools.dynamic]`` in pyproject.toml) without importing numpy.
+"""
+
+__version__ = "0.1.0"

juniper_recurrence_model/data.py

@@ -0,0 +1,103 @@
+"""Load a 3-D sequence NPZ artifact (the WS-1 contract) into arrays for the regressor.
+
+The authoritative, full-contract validator is juniper-data-client's
+``validate_npz_contract`` — the juniper-recurrence *app* calls it on the data-fetch path.
+This module is the lean, **numpy-only model-side reader**: it pulls the per-split arrays
+:class:`~juniper_recurrence_model.LMURegressor` consumes (``X`` / ``y`` / ``dt`` /
+``target_dt`` / ``seq_lengths``) out of the NPZ key layout (per-split suffixes
+``_train`` / ``_test`` / ``_full``) and applies the minimal ``dt`` rules the model relies on.
+It deliberately takes **no** juniper-data-client dependency, keeping this package numpy-only.
+
+The WS-1 3-D contract (juniper-data#168; ``DELTA_T_HANDLING`` §6): ``X_{split}`` is ``(W, L, F)``;
+``dt_{split}`` is ``(W, L)`` with ``dt[:, 0] == 0`` and ``dt >= 0`` (or absolute ``t_{split}``,
+from which ``dt`` is derived); ``y_reg_{split}`` is the regression target (one per window);
+``target_dt_{split}`` (horizon) and ``seq_lengths_{split}`` (valid step count) are optional.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+__all__ = ["SequenceData", "load_sequence_npz", "sequence_data_from_arrays"]
+
+
+@dataclass(frozen=True)
+class SequenceData:
+    """One split of a 3-D sequence artifact, ready for :class:`LMURegressor`.
+
+    ``X`` is ``(W, L, F)``; ``y`` is ``(W, output_dim)``; ``dt`` is ``(W, L)`` with
+    ``dt[:, 0] == 0``. ``target_dt`` ``(W,)`` and ``seq_lengths`` ``(W,)`` are optional.
+    """
+
+    X: np.ndarray
+    y: np.ndarray
+    dt: np.ndarray
+    target_dt: np.ndarray | None = None
+    seq_lengths: np.ndarray | None = None
+
+    def fit_kwargs(self) -> dict[str, Any]:
+        """The auxiliary-array keywords for ``LMURegressor.fit`` / ``predict`` (the D3 contract)."""
+        kwargs: dict[str, Any] = {"dt": self.dt}
+        if self.target_dt is not None:
+            kwargs["target_dt"] = self.target_dt
+        if self.seq_lengths is not None:
+            kwargs["seq_lengths"] = self.seq_lengths
+        return kwargs
+
+
+def load_sequence_npz(path: Any, split: str = "train") -> SequenceData:
+    """Read one ``split`` (``"train"`` / ``"test"`` / ``"full"``) of a 3-D sequence ``.npz``."""
+    with np.load(path, allow_pickle=False) as handle:
+        arrays = {key: handle[key] for key in handle.files}
+    return sequence_data_from_arrays(arrays, split)
+
+
+def sequence_data_from_arrays(arrays: dict[str, np.ndarray], split: str = "train") -> SequenceData:
+    """Build a :class:`SequenceData` from an in-memory NPZ array mapping.
+
+    Reads ``X_{split}`` (required, 3-D), the regression target ``y_reg_{split}`` (preferred;
+    falls back to ``y_{split}``), and the timing channel ``dt_{split}`` (or derives it from
+    ``t_{split}``). ``target_dt_{split}`` / ``seq_lengths_{split}`` are read when present.
+    Applies the minimal model-side ``dt`` checks (a strict subset of ``validate_npz_contract``).
+    """
+    if f"X_{split}" not in arrays:
+        raise ValueError(f"NPZ artifact is missing required key 'X_{split}'")
+    X = np.asarray(arrays[f"X_{split}"])
+    if X.ndim != 3:
+        raise ValueError(f"X_{split} must be 3-D (W, L, F) for a sequence artifact; got {X.ndim}-D")
+    n_windows, lookback = int(X.shape[0]), int(X.shape[1])
+
+    # Regression target: prefer y_reg, fall back to y.
+    if f"y_reg_{split}" in arrays:
+        y = np.asarray(arrays[f"y_reg_{split}"])
+    elif f"y_{split}" in arrays:
+        y = np.asarray(arrays[f"y_{split}"])
+    else:
+        raise ValueError(f"missing regression target: neither 'y_reg_{split}' nor 'y_{split}' present")
+    if y.ndim == 1:
+        y = y[:, None]
+
+    # Timing: dt directly, or derived from absolute t (matches the contract's t/dt consistency).
+    dt_key, t_key = f"dt_{split}", f"t_{split}"
+    if dt_key in arrays:
+        dt = np.asarray(arrays[dt_key], dtype=float)
+    elif t_key in arrays:
+        t = np.asarray(arrays[t_key], dtype=float)
+        dt = np.zeros_like(t)
+        dt[:, 1:] = np.diff(t, axis=1)
+    else:
+        raise ValueError(f"a 3-D artifact needs at least one of 'dt_{split}' / 't_{split}'")
+    if dt.shape != (n_windows, lookback):
+        raise ValueError(f"{dt_key} shape {dt.shape} != {(n_windows, lookback)}")
+    if np.any(dt < 0):
+        raise ValueError(f"{dt_key} has negative gaps")
+    if n_windows and np.any(dt[:, 0] != 0):
+        raise ValueError(f"{dt_key}[:, 0] must be 0 by convention")
+
+    target_dt = np.asarray(arrays[f"target_dt_{split}"]).reshape(n_windows) if f"target_dt_{split}" in arrays else None
+    seq_lengths = np.asarray(arrays[f"seq_lengths_{split}"]).reshape(n_windows) if f"seq_lengths_{split}" in arrays else None
+
+    return SequenceData(X=X, y=y, dt=dt, target_dt=target_dt, seq_lengths=seq_lengths)

juniper_recurrence_model/model.py

@@ -0,0 +1,261 @@
+"""Fixed-order Δt-native LMU regressor — ``juniper-model-core`` ``TrainableModel``.
+
+This is the WS-4 model layer: a standalone, fixed-order, irregular-Δt-native
+Legendre Memory Unit **regressor** that satisfies ``juniper_model_core.TrainableModel``.
+It wraps the fixed :class:`~juniper_recurrence_model.units.VariableStepLMUMemory` cell
+with the only trained surface — a closed-form least-squares **readout**.
+
+Design (ratified decisions D-WS4-1…3, plan
+``notes/JUNIPER_RECURRENCE_WS4_MODEL_BUILD_PLAN_2026-06-15.md`` in juniper-ml):
+
+* **D-WS4-1 — per-feature identity read-in.** Each of the ``F`` input features drives its
+  own order-``d`` memory through the *same* fixed ``A``/``B``/θ (no trained projection); the
+  per-window memory state is the concatenation ``M ∈ ℝ^{F·d}``. Only the readout is trained.
+* **D-WS4-2 — ``target_dt`` as a readout feature.** When supplied, the irregular forecast
+  horizon is concatenated to the readout design matrix.
+* **D-WS4-3 — standalone.** No cascor cascade head; this regressor has its own readout.
+
+Because the memory matrices are fixed (never differentiated) and the readout is linear, the
+whole model is a closed-form ``lstsq`` solve over an LMU-memory feature map — **numpy-only,
+no autodiff framework**. This is the structural twin of ``juniper_model_core``'s
+``ReferenceLinearModel`` with its ``_flatten(X)`` feature map replaced by a dt-aware
+LMU-memory rollout. (A trained projection read-in / nonlinear readout — the point at which
+torch would enter — is a deferred increment.)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+import numpy as np
+from juniper_model_core import ModelSerializer, TaskType, Topology, TrainableModel, TrainingEvent, TrainResult
+
+from juniper_recurrence_model.units.lmu_varstep import VariableStepLMUMemory
+
+__all__ = ["LMURegressor", "LMUSerializer"]
+
+
+def _regression_metrics(y_true: np.ndarray, y_pred: np.ndarray) -> dict[str, float]:
+    """Canonical regression metrics (``REGRESSION_METRIC_KEYS``); never ``accuracy`` (RK-6)."""
+    err = y_pred - y_true
+    mse = float(np.mean(err**2))
+    mae = float(np.mean(np.abs(err)))
+    ss_res = float(np.sum(err**2))
+    ss_tot = float(np.sum((y_true - y_true.mean(axis=0)) ** 2))
+    r2 = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
+    return {"mse": mse, "rmse": mse**0.5, "mae": mae, "r2": r2, "loss": mse}
+
+
+class LMURegressor(TrainableModel):
+    """Fixed-order Δt-native LMU regressor (per-feature identity read-in + linear readout).
+
+    Parameters
+    ----------
+    d:
+        LMU memory order (Legendre coefficients per feature). Practical range ~4..64.
+    theta:
+        Memory window length, in the same real-time units as ``dt`` (e.g. calendar days).
+        ``None`` (default) resolves it data-drivenly at ``fit``: the median per-window total
+        elapsed time ``median(sum(dt, axis=1))``, falling back to the window length ``T`` when
+        ``dt`` is absent or non-positive.
+    ridge:
+        L2 penalty on the readout (the bias column is never penalised). ``0.0`` (default)
+        uses a plain min-norm least-squares solve — which lets the readout memorise a tiny
+        set exactly (the overfit-tiny guarantee) and mirrors the reference model.
+    time_unit:
+        Declared real-time unit of ``dt`` / ``theta`` (carried in the topology meta).
+    random_seed:
+        Stored for the contract; the closed-form fit is deterministic regardless.
+    """
+
+    def __init__(self, d: int = 16, theta: float | None = None, *, ridge: float = 0.0, time_unit: str = "steps", random_seed: int | None = 0) -> None:
+        self.task_type: TaskType = "regression"
+        self.random_seed = random_seed
+        self.d = int(d)
+        self.theta: float | None = None if theta is None else float(theta)
+        self.ridge = float(ridge)
+        self.time_unit = str(time_unit)
+        # When theta is data-driven (None) the fixed memory is built in fit(); see fit().
+        self._memory = None if self.theta is None else VariableStepLMUMemory(self.d, self.theta)
+        self._coef: np.ndarray | None = None
+        self._in_shape: tuple[int, ...] = ()
+        self._out_shape: tuple[int, ...] = ()
+        self._n_features: int | None = None
+        self._uses_target_dt: bool = False
+        self._metrics: dict[str, float] = {}
+
+    # ----- feature map (shared by fit and predict) -----------------------------------
+    @staticmethod
+    def _readout_index(n: int, n_steps: int, readout_mask: np.ndarray | None, seq_lengths: np.ndarray | None) -> np.ndarray:
+        """Per-sample index of the readout step (the last valid step, many-to-one)."""
+        if seq_lengths is not None:
+            return np.clip(np.asarray(seq_lengths, dtype=int) - 1, 0, n_steps - 1)
+        if readout_mask is not None:
+            mask = np.asarray(readout_mask, dtype=bool)
+            reversed_mask = mask[:, ::-1]
+            has_true = reversed_mask.any(axis=1)
+            last_true = n_steps - 1 - np.argmax(reversed_mask, axis=1)
+            return np.where(has_true, last_true, n_steps - 1)
+        return np.full(n, n_steps - 1, dtype=int)
+
+    def _features(self, X: np.ndarray, dt: np.ndarray | None, target_dt: np.ndarray | None, readout_mask: np.ndarray | None, seq_lengths: np.ndarray | None) -> np.ndarray:
+        X = np.asarray(X, dtype=float)
+        if X.ndim != 3:
+            raise ValueError(f"X must be 3-D (n, T, F); got shape {X.shape}")
+        n, n_steps, n_features = X.shape
+        if self._n_features is not None and n_features != self._n_features:
+            raise ValueError(f"expected F={self._n_features} features, got {n_features}")
+        if dt is None:
+            dt = np.zeros((n, n_steps))
+            dt[:, 1:] = 1.0  # uniform unit-spacing fallback (bare predict(X) — no timing supplied)
+        trajectory = self._memory.rollout_batch(X, dt)  # (n, T, F, d)
+        idx = self._readout_index(n, n_steps, readout_mask, seq_lengths)
+        memory_state = trajectory[np.arange(n), idx].reshape(n, n_features * self.d)  # (n, F*d)
+        columns = [memory_state]
+        if self._uses_target_dt:
+            horizon = np.zeros(n) if target_dt is None else np.asarray(target_dt, dtype=float).reshape(n)
+            columns.append(horizon[:, None])
+        columns.append(np.ones((n, 1)))  # bias
+        return np.concatenate(columns, axis=1)
+
+    # ----- TrainableModel contract ---------------------------------------------------
+    def fit(self, X: np.ndarray, y: np.ndarray, *, X_val: np.ndarray | None = None, y_val: np.ndarray | None = None, on_event: Any = None, **kw: Any) -> TrainResult:
+        X = np.asarray(X, dtype=float)
+        y = np.asarray(y, dtype=float)
+        if X.ndim != 3:
+            raise ValueError(f"X must be 3-D (n, T, F); got shape {X.shape}")
+        if y.ndim == 3:
+            raise NotImplementedError("dense many-to-many readout is a deferred WS-4 increment; supply one target per window (y of shape (n,) or (n, output_dim))")
+        if y.ndim == 1:
+            y = y[:, None]
+        n, n_steps, n_features = X.shape
+        self._in_shape = (n_steps, n_features)
+        self._n_features = n_features
+        self._out_shape = (int(y.shape[1]),)
+        self._uses_target_dt = kw.get("target_dt") is not None
+        # Resolve a data-driven theta (median per-window elapsed time) when not pinned,
+        # then build the fixed LMU memory. A pinned theta is used as-is.
+        if self.theta is None:
+            window_dt = kw.get("dt")
+            theta = float(np.median(np.sum(np.asarray(window_dt, dtype=float), axis=1))) if window_dt is not None else float(n_steps)
+            self.theta = theta if theta > 0 else float(n_steps)
+        if self._memory is None:
+            self._memory = VariableStepLMUMemory(self.d, self.theta)
+
+        seq = 0
+        if on_event is not None:
+            on_event(TrainingEvent("training_start", {"n_samples": int(n)}, seq))
+            seq += 1
+
+        design = self._features(X, kw.get("dt"), kw.get("target_dt"), kw.get("readout_mask"), kw.get("seq_lengths"))
+        if self.ridge > 0.0:
+            gram = design.T @ design
+            penalty = self.ridge * np.eye(gram.shape[0])
+            penalty[-1, -1] = 0.0  # never regularise the bias column
+            coef = np.linalg.solve(gram + penalty, design.T @ y)
+        else:
+            coef, *_ = np.linalg.lstsq(design, y, rcond=None)
+        self._coef = coef
+        self._metrics = _regression_metrics(y, design @ coef)
+
+        if on_event is not None:
+            on_event(TrainingEvent("epoch_end", {"epoch": 0, "metrics": dict(self._metrics)}, seq))
+            seq += 1
+            on_event(TrainingEvent("training_end", {"metrics": dict(self._metrics)}, seq))
+        return TrainResult(final_metrics=dict(self._metrics), n_epochs=1, history=[dict(self._metrics)], stopped_reason="converged")
+
+    def predict(self, X: np.ndarray, *, dt: np.ndarray | None = None, target_dt: np.ndarray | None = None, readout_mask: np.ndarray | None = None, seq_lengths: np.ndarray | None = None) -> np.ndarray:
+        """Continuous predictions for ``X``.
+
+        The signature widens the ``TrainableModel.predict(X)`` contract with *optional*
+        sequence keywords (the ABC checks the method name, not the signature). When ``dt``
+        is omitted — as the conformance kit calls it — a uniform unit grid is assumed; real
+        callers pass ``dt`` (and ``target_dt`` when the model was fit with one) to engage the
+        Δt path. Never returns an ``argmax`` (RK-6 — collapsing to labels is classification-only).
+        """
+        if self._coef is None:
+            raise RuntimeError("model is not fitted")
+        X = np.asarray(X, dtype=float)
+        design = self._features(X, dt, target_dt, readout_mask, seq_lengths)
+        return (design @ self._coef).reshape((X.shape[0], *self._out_shape))
+
+    def metrics(self) -> dict[str, float]:
+        return dict(self._metrics)
+
+    def describe_topology(self) -> Topology:
+        return {
+            "model_type": "lmu",
+            "nodes": [
+                {"id": "input", "kind": "input", "frozen": True},
+                {"id": "memory", "kind": "memory", "frozen": True},
+                {"id": "output", "kind": "output", "frozen": False},
+            ],
+            "edges": [
+                {"src": "input", "dst": "memory", "recurrent": False},
+                {"src": "memory", "dst": "memory", "recurrent": True},
+                {"src": "memory", "dst": "output", "recurrent": False},
+            ],
+            "meta": {
+                "n_units": 0,
+                "task_type": self.task_type,
+                "theta": self.theta,
+                "d": self.d,
+                "time_unit": self.time_unit,
+                "n_features": self._n_features,
+            },
+        }
+
+    @property
+    def input_shape(self) -> tuple[int, ...]:
+        return self._in_shape
+
+    @property
+    def output_shape(self) -> tuple[int, ...]:
+        return self._out_shape
+
+
+class LMUSerializer(ModelSerializer):
+    """Lossless ``.npz`` + JSON serializer for :class:`LMURegressor`.
+
+    Persists the trained readout coefficients plus the hyperparameters; the fixed memory
+    eigendecomposition is recomputed from ``d``/θ on load (deterministic), so reloaded
+    predictions are bit-identical (the conformance kit's lossless-round-trip assertion).
+    """
+
+    def save(self, model: TrainableModel, path: str | os.PathLike[str]) -> None:
+        if not isinstance(model, LMURegressor):
+            raise TypeError("LMUSerializer only serializes LMURegressor")
+        if model._coef is None:
+            raise RuntimeError("cannot serialize an unfitted model")
+        meta = {
+            "d": model.d,
+            "theta": model.theta,
+            "ridge": model.ridge,
+            "time_unit": model.time_unit,
+            "random_seed": model.random_seed,
+            "task_type": model.task_type,
+            "in_shape": list(model._in_shape),
+            "out_shape": list(model._out_shape),
+            "n_features": model._n_features,
+            "uses_target_dt": model._uses_target_dt,
+            "metrics": model._metrics,
+        }
+        np.savez(os.fspath(path), coef=model._coef, meta=json.dumps(meta))
+
+    def load(self, path: str | os.PathLike[str]) -> LMURegressor:
+        resolved = os.fspath(path)
+        if not resolved.endswith(".npz"):
+            resolved = resolved + ".npz"
+        with np.load(resolved, allow_pickle=False) as data:
+            coef = data["coef"]
+            meta = json.loads(str(data["meta"]))
+        model = LMURegressor(d=meta["d"], theta=meta["theta"], ridge=meta["ridge"], time_unit=meta["time_unit"], random_seed=meta["random_seed"])
+        model._coef = coef
+        model._in_shape = tuple(meta["in_shape"])
+        model._out_shape = tuple(meta["out_shape"])
+        model._n_features = meta["n_features"]
+        model._uses_target_dt = bool(meta["uses_target_dt"])
+        model._metrics = {key: float(value) for key, value in meta["metrics"].items()}
+        return model

juniper_recurrence_model/units/__init__.py

@@ -0,0 +1,9 @@
+"""Recurrent / continuous-time memory units for juniper-recurrence.
+
+Currently exposes the Δt-native Legendre Memory Unit (Approach-C). Additional unit
+kinds (e.g. a self-recurrent RCC candidate, P1) may be added as the framework grows.
+"""
+
+from juniper_recurrence_model.units.lmu_varstep import VariableStepLMUMemory, lmu_matrices
+
+__all__ = ["VariableStepLMUMemory", "lmu_matrices"]

juniper_recurrence_model/units/lmu_varstep.py

@@ -0,0 +1,237 @@
+"""Δt-native Legendre Memory Unit (Approach-C).
+
+A Legendre Memory Unit (LMU; Voelker, Kajić & Eliasmith 2019, NeurIPS) maintains a
+continuous-time representation of an input's recent history by orthogonalising it onto
+the Legendre polynomial basis over a sliding window of length ``theta``. Its linear
+memory state obeys
+
+    theta * m'(t) = A @ m(t) + B * u(t)
+
+with **fixed, closed-form** matrices ``A`` (``d x d``) and ``B`` (``d x 1``) — the
+HiPPO-LegT operator (Gu et al. 2020). Because the system is *linear*, its exact
+discretisation is a matrix exponential — no numerical ODE solver is required.
+
+**Approach C — the irregular-Δt win.** Standard LMU implementations bake the discrete
+``Abar``/``Bbar`` as constants for one fixed step. The only change needed for
+irregularly-sampled data is to evaluate them at the *actual* per-step gap ``dt_k`` — i.e.
+the dataset's ``dt`` channel *is* the discretisation step (the same role the per-step
+``Delta`` parameter plays in S4/Mamba). This is done in closed form via a one-time
+eigendecomposition of the fixed ``A``, so each step costs only ``d`` scalar exponentials.
+
+**C1-clean (first-principles).** No ODE solver, no autodiff-through-solver — only scalar
+exponentials of the eigenvalues of a FIXED, closed-form matrix. ``A`` and ``B`` are not
+learned and not data-dependent; only the read-in (features -> drive ``u``) and the readout
+(memory -> output) are trained, and they live outside this module.
+
+Verified reference: the numerics here match ``util/ad-hoc/verify_delta_t_reference_code.py``
+in juniper-ml (numpy 2.4.4 / Python 3.13): ``A`` (d=16) max eigenvalue real part = -6.49
+(stable); delayed-sinusoid reconstruction ``e_reg`` ≈ 0.035 and grid-invariant
+``e_irr`` ≈ 0.039–0.043 (≈1.15×). See
+``notes/JUNIPER_RECURSE_DELTA_T_HANDLING_2026-06-05.md`` §8 and
+``notes/JUNIPER_RECURRENCE_MODEL_DETAILED_DESIGN_2026-06-14.md`` Part 3.
+
+References
+---------
+- Voelker, Kajić & Eliasmith (2019). Legendre Memory Units. NeurIPS.
+- Gu, Dao, Ermon, Rudra & Ré (2020). HiPPO. NeurIPS; arXiv:2008.07669.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.polynomial.legendre import Legendre
+
+__all__ = ["lmu_matrices", "VariableStepLMUMemory"]
+
+# Below this magnitude an eigenvalue is treated as zero for the removable
+# singularity in (exp(z) - 1) / lambda. LegT's A has no zero eigenvalue, but the
+# guard keeps the code correct for hygiene / other bases.
+_LAMBDA_ZERO_TOL = 1e-12
+
+
+def lmu_matrices(d: int) -> tuple[np.ndarray, np.ndarray]:
+    """Return the fixed, closed-form Legendre (HiPPO-LegT) state matrices.
+
+    Parameters
+    ----------
+    d:
+        Memory order (number of Legendre coefficients). Practical range ~4..64;
+        the eigenvector matrix of ``A`` becomes ill-conditioned for large ``d``.
+
+    Returns
+    -------
+    (A, B):
+        ``A`` of shape ``(d, d)`` and ``B`` of shape ``(d, 1)``. These depend only
+        on ``d`` — they are not learned and not data-dependent.
+    """
+    if d < 1:
+        raise ValueError(f"order d must be >= 1, got {d}")
+    A = np.zeros((d, d))
+    B = np.zeros((d, 1))
+    for i in range(d):
+        B[i, 0] = (2 * i + 1) * ((-1) ** i)
+        for j in range(d):
+            A[i, j] = (2 * i + 1) * (-1.0 if i < j else (-1.0) ** (i - j + 1))
+    return A, B
+
+
+class VariableStepLMUMemory:
+    """Irregular-Δt-native LMU memory (Approach-C).
+
+    The linear LMU memory, exactly discretised at an arbitrary per-step real gap
+    ``dt`` via the zero-order-hold update
+
+        m_{k+1} = Abar(dt) @ m_k + Bbar(dt) * u_k
+
+    where ``Abar``/``Bbar`` are computed from a one-time eigendecomposition of the
+    fixed matrix ``A``::
+
+        z_i      = lambda_i * dt / theta
+        Abar(dt) = V @ diag(exp(z_i))            @ Vinv
+        Bbar(dt) = V @ diag(expm1(z_i) / lam_i)  @ (Vinv @ B)
+
+    ``expm1`` (not ``exp(z) - 1``) avoids catastrophic cancellation at small ``z``.
+    Stability is automatic for ``dt > 0`` because every eigenvalue has negative real
+    part, so ``|exp(z_i)| < 1`` and ``Abar`` is a contraction.
+
+    Parameters
+    ----------
+    d:
+        Memory order (see :func:`lmu_matrices`).
+    theta:
+        Memory window length, in the *same real-time units* as ``dt`` (e.g. calendar
+        days for the equities use-case).
+    """
+
+    def __init__(self, d: int, theta: float) -> None:
+        if theta <= 0:
+            raise ValueError(f"theta must be > 0, got {theta}")
+        self.d = int(d)
+        self.theta = float(theta)
+        A, B = lmu_matrices(self.d)
+        lam, V = np.linalg.eig(A)
+        # Precomputed once; depend only on (d, theta).
+        self.lam = lam
+        self.V = V
+        self.Vinv = np.linalg.inv(V)
+        self.VinvB = self.Vinv @ B
+
+    def step_matrices(self, dt: float) -> tuple[np.ndarray, np.ndarray]:
+        """Return ``(Abar, Bbar)`` for a single real gap ``dt`` (both real-valued)."""
+        z = self.lam * (dt / self.theta)
+        Abar = (self.V * np.exp(z)) @ self.Vinv
+        with np.errstate(divide="ignore", invalid="ignore"):
+            fac = np.expm1(z) / self.lam
+        fac = np.where(np.abs(self.lam) < _LAMBDA_ZERO_TOL, dt / self.theta, fac)
+        Bbar = (self.V * fac) @ self.VinvB
+        return Abar.real, Bbar.real
+
+    def rollout(self, u: np.ndarray, dt: np.ndarray) -> np.ndarray:
+        """Roll the memory over a 1-D input ``u`` with per-step gaps ``dt``.
+
+        Zero-order-hold convention: ``u[k-1]`` is held constant across the interval
+        ``(t[k-1], t[k]]`` of length ``dt[k]``. ``dt[0]`` is unused (empty window);
+        the returned ``out[0]`` is the zero initial state.
+
+        Parameters
+        ----------
+        u:
+            Scalar drive per step, shape ``(n,)``.
+        dt:
+            Per-step elapsed real time, shape ``(n,)``; ``dt[k] > 0`` for ``k >= 1``.
+
+        Returns
+        -------
+        np.ndarray
+            Memory trajectory of shape ``(n, d)``.
+        """
+        u = np.asarray(u, dtype=float)
+        dt = np.asarray(dt, dtype=float)
+        if u.ndim != 1 or dt.ndim != 1 or u.shape[0] != dt.shape[0]:
+            raise ValueError(f"u and dt must be 1-D and equal length; got {u.shape}, {dt.shape}")
+        n = u.shape[0]
+        m = np.zeros((self.d, 1))
+        out = np.zeros((n, self.d))
+        for k in range(1, n):
+            if dt[k] <= 0:
+                raise ValueError(f"dt[{k}]={dt[k]} must be > 0 for k >= 1")
+            Abar, Bbar = self.step_matrices(float(dt[k]))
+            m = Abar @ m + Bbar * u[k - 1]
+            out[k] = m[:, 0]
+        return out
+
+    def rollout_batch(self, u: np.ndarray, dt: np.ndarray) -> np.ndarray:
+        """Batched, multi-channel ZOH rollout, integrated in the eigenbasis.
+
+        Rolls ``F`` independent input channels through this *same* fixed LMU memory
+        operator, for a batch of ``n`` sequences, with per-(sequence, step) real gaps
+        ``dt``. Channel ``f`` of sequence ``i`` evolves exactly as :meth:`rollout`
+        would for the 1-D drive ``u[i, :, f]`` — this is the per-feature identity
+        read-in of the recurrence regressor (each feature drives its own memory).
+
+        The recurrence is integrated in the eigenbasis of the fixed matrix ``A`` so a
+        step is an elementwise scaling by ``exp(z)`` rather than a per-sequence ``d×d``
+        matmul. The memory matrices are never differentiated (C1-clean); this returns
+        plain arrays with no autograd graph.
+
+        Parameters
+        ----------
+        u:
+            Per-step channel drives, shape ``(n, T, F)`` (``(n, T)`` is accepted and
+            treated as a single channel, ``F == 1``).
+        dt:
+            Per-step elapsed real time, shape ``(n, T)``. ``dt[:, 0]`` is unused (empty
+            initial window). Gaps must be ``>= 0``; ``dt == 0`` is a *no-op* step (the
+            memory is held and the step's drive is ignored), so padded tails past
+            ``seq_lengths`` pass through harmlessly. Negative gaps are a contract
+            violation.
+
+        Returns
+        -------
+        np.ndarray
+            Real memory trajectory of shape ``(n, T, F, d)``; ``out[:, 0]`` is the zero
+            initial state.
+
+        Notes
+        -----
+        Returns the full trajectory (needed for parity testing and a future dense
+        many-to-many readout); a many-to-one consumer keeps only the readout step.
+        A per-``dt``-bucket cache of ``exp(z)`` / ``expm1(z)/λ`` is a future
+        optimisation when ``dt`` is quantised (e.g. integer calendar-day gaps).
+        """
+        u = np.asarray(u, dtype=float)
+        if u.ndim == 2:
+            u = u[:, :, None]
+        if u.ndim != 3:
+            raise ValueError(f"u must be (n, T, F) or (n, T); got shape {u.shape}")
+        dt = np.asarray(dt, dtype=float)
+        n, n_steps, n_channels = u.shape
+        if dt.shape != (n, n_steps):
+            raise ValueError(f"dt must have shape {(n, n_steps)} to match u; got {dt.shape}")
+        if np.any(dt < 0):
+            raise ValueError("dt must be >= 0 everywhere (dt == 0 is a held/no-op step)")
+
+        lam = self.lam[None, :]  # (1, d)
+        vinv_b = self.VinvB[:, 0]  # (d,) — B projected into the eigenbasis
+        # eigen-coordinate state, complex: p[i, :, f] are the eigen-coefficients of memory f.
+        p = np.zeros((n, self.d, n_channels), dtype=np.complex128)
+        out = np.zeros((n, n_steps, n_channels, self.d), dtype=float)
+        for k in range(1, n_steps):
+            z = lam * (dt[:, k][:, None] / self.theta)  # (n, d)
+            ez = np.exp(z)
+            with np.errstate(divide="ignore", invalid="ignore"):
+                fac = np.expm1(z) / lam
+            fac = np.where(np.abs(self.lam)[None, :] < _LAMBDA_ZERO_TOL, dt[:, k][:, None] / self.theta, fac)
+            gain = fac * vinv_b[None, :]  # (n, d) per-eigenmode input gain
+            p = ez[:, :, None] * p + gain[:, :, None] * u[:, k - 1, :][:, None, :]
+            out[:, k] = np.einsum("ij,njf->nif", self.V, p).real.transpose(0, 2, 1)
+        return out
+
+    def decode_weights(self, rho: float) -> np.ndarray:
+        """Readout weights to reconstruct the input at delay ``rho * theta`` into the past.
+
+        Uses shifted-Legendre evaluation: ``w[i] = P_i(2*rho - 1)`` for ``i in 0..d-1``,
+        with ``rho in [0, 1]`` (0 = now, 1 = the full window ago).
+        """
+        x = 2.0 * float(rho) - 1.0
+        return np.array([Legendre.basis(i)(x) for i in range(self.d)])

juniper_recurrence_model-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: juniper-recurrence-model
+Version: 0.1.0
+Summary: Δt-native Legendre Memory Unit (Approach-C) and recurrent model core for the juniper-recurrence application
+Author: Paul Calnon
+License: MIT
+Project-URL: Homepage, https://github.com/pcalnon/juniper-recurrence
+Project-URL: Repository, https://github.com/pcalnon/juniper-recurrence
+Project-URL: Issues, https://github.com/pcalnon/juniper-recurrence/issues
+Keywords: juniper,recurrence,lmu,legendre,state-space,time-series,irregular-dt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: juniper-model-core<0.2.0,>=0.1.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+
+# juniper-recurrence-model
+
+The model-specific core for the [juniper-recurrence](https://github.com/pcalnon/juniper-recurrence)
+application — the selected model **P3-C (LMU + Approach-C)**.
+
+This package ships the **Δt-native Legendre Memory Unit (Approach-C)** — a closed-form,
+variable-step LMU discretisation that is the only first-principles-clean ("C1") option natively
+handling irregularly-sampled time series — **and** `FixedOrderLMURegressor`, the recurrent model
+implementing the shared [`juniper-model-core`](https://github.com/pcalnon/juniper-ml)
+`TrainableModel` interface (now that that package has landed). The regressor keeps the LMU memory
+**fixed** and trains only a linear readout in **closed form** (least squares — no BPTT, fully
+deterministic); it passes model-core's conformance kit unchanged, making it the WS-4 refactor
+template (a non-cascor model on the shared model seam).
+
+Design of record (in juniper-ml):
+[`notes/JUNIPER_RECURRENCE_MODEL_DETAILED_DESIGN_2026-06-14.md`](https://github.com/pcalnon/juniper-ml/blob/main/notes/JUNIPER_RECURRENCE_MODEL_DETAILED_DESIGN_2026-06-14.md).
+
+## Why Approach-C
+
+An LMU's linear memory obeys `theta * m'(t) = A·m(t) + B·u(t)` with **fixed, closed-form** matrices.
+Because the system is linear, its *exact* discretisation is a matrix exponential — **no ODE solver,
+no autodiff-through-solver**. For irregular sampling, the discrete update is simply evaluated at the
+real per-step gap `dt`: the dataset's `dt` channel *is* the discretisation step. `A`/`B` are never
+trained; only the read-in/readout are. That is the entire C1-clean, irregular-Δt-native story.
+
+## Install
+
+```bash
+pip install juniper-recurrence-model          # once published
+pip install -e ".[test]"                       # local development
+```
+
+numpy-only at the core (the memory is a fixed linear recurrence requiring no autodiff).
+
+## Quick start
+
+```python
+import numpy as np
+from juniper_recurrence_model import VariableStepLMUMemory
+
+mem = VariableStepLMUMemory(d=16, theta=1.0)   # order 16, window 1.0 (same unit as dt)
+
+# Irregularly-sampled input: u driven on a non-uniform time grid
+t = np.cumsum(np.r_[0.0, np.random.default_rng(0).uniform(0.02, 0.08, 239)])
+dt = np.empty_like(t); dt[0] = 0.0; dt[1:] = np.diff(t)
+u = np.sin(2.0 * t)
+
+m = mem.rollout(u, dt)                          # (240, 16) memory trajectory
+w = mem.decode_weights(rho=1.0)                 # read the input one full window ago
+reconstruction = m @ w
+```
+
+## Trainable model (`FixedOrderLMURegressor`)
+
+The package also exposes `FixedOrderLMURegressor`, a `juniper-model-core` `TrainableModel`. The
+LMU memory is fixed; only a linear readout is fit, in closed form (least squares — no BPTT, fully
+deterministic). It is Δt-native: pass per-step gaps `dt` (`(n, T)`) and an optional `readout_mask`
+to `fit` / `predict`; both default to uniform gaps and the final step, so the bare ABC
+`predict(X)` works too. It reports canonical regression metrics (`mse`, `rmse`, `mae`, `r2`).
+
+```python
+import numpy as np
+from juniper_recurrence_model import FixedOrderLMURegressor, LMURegressorSerializer
+
+n, T, F = 48, 6, 3
+X = np.random.default_rng(0).normal(size=(n, T, F))
+y = X.reshape(n, -1) @ np.random.default_rng(1).normal(size=(T * F, 1))
+dt = np.zeros((n, T)); dt[:, 1:] = np.random.default_rng(2).integers(1, 4, size=(n, T - 1))
+
+model = FixedOrderLMURegressor(d=6)             # theta resolved data-driven from dt at fit time
+result = model.fit(X, y, dt=dt)                 # closed-form readout solve
+preds = model.predict(X, dt=dt)                 # (n, 1)
+print(result.final_metrics["r2"], model.describe_topology()["model_type"])
+
+LMURegressorSerializer().save(model, "/tmp/lmu")   # writes /tmp/lmu.npz (lossless round-trip)
+```
+
+`FixedOrderLMURegressor` passes model-core's conformance kit unchanged
+(`tests/test_lmu_conformance.py`), proving the WS-4 refactor template.
+
+## Verified behaviour
+
+| Check | Result |
+|---|---|
+| `A` (d=16) max eigenvalue real part | **−6.49** (< 0 → stable) |
+| Reconstruction RMSE `e_reg` (regular grid) | **≈ 0.035** (< 0.05) |
+| Grid-invariance `e_irr` (irregular grid) | **≈ 0.039–0.043** (≈1.15× `e_reg`; < 3·`e_reg` + 0.02) |
+
+Pinned by `tests/test_lmu_grid_invariance.py`. Numerics match the reference
+`util/ad-hoc/verify_delta_t_reference_code.py` in juniper-ml.
+
+## Numerical guardrails
+
+- Keep `d ≲ 64` — the eigenvector matrix of `A` becomes ill-conditioned for large `d`
+  (Padé scaling-and-squaring is the documented fallback for larger orders).
+- Stability is automatic for `dt > 0` (`Re(λ) < 0 ⇒ |e^z| < 1`).
+- `dt` may be quantised (e.g. integer calendar-day gaps) and `Abar`/`Bbar` cached per bucket.
+
+## Versioning
+
+PEP 440 + [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Consumers should pin
+`juniper-recurrence-model>=A.B,<A+1`. See [`CHANGELOG.md`](./CHANGELOG.md).
+
+## License
+
+MIT — see [LICENSE](https://github.com/pcalnon/juniper-recurrence/blob/main/LICENSE).

juniper_recurrence_model-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+juniper_recurrence_model/__init__.py,sha256=kXarPjfWwsYocqN3jmZEaQ2UGPJ285nXzb446YKy744,1231
+juniper_recurrence_model/_version.py,sha256=fg_FQVJvTdOUQfPfpolQ1-cWCD1f2983FcSYCau5mwI,253
+juniper_recurrence_model/data.py,sha256=wzSxdFWFlm4qzVFE2dqyNCpZum8tVZz6rAcm5BH69dU,4835
+juniper_recurrence_model/model.py,sha256=1loA0fBbtXznhN1r2qPyDsDLZR45SBE1T-XWw7QKNM4,13108
+juniper_recurrence_model/units/__init__.py,sha256=0iKyCzag1nsqfg7d8FDax6vpcP3dY5BXvsgSr46rwsQ,387
+juniper_recurrence_model/units/lmu_varstep.py,sha256=JtUXX1xRqGioZWpF_-dL0FqRJ06ZV1-KQ0m7qOJpY-Q,10459
+juniper_recurrence_model-0.1.0.dist-info/METADATA,sha256=IAyMGWAFvTNYMI7KXaQR0jz05kvtcpR8XXMi411Tdsc,6221
+juniper_recurrence_model-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+juniper_recurrence_model-0.1.0.dist-info/top_level.txt,sha256=8n0jDVpLTQtGiyJNhg4sq7Voz4wbKrY-74or_KcTMvs,25
+juniper_recurrence_model-0.1.0.dist-info/RECORD,,

juniper_recurrence_model-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

juniper_recurrence_model-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+juniper_recurrence_model