juniper-recurrence-model 0.1.0__tar.gz

juniper_recurrence_model-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,106 @@
+# 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/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-0.1.0/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-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-0.1.0/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-0.1.0/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"]