StochasticForceInference 2.0.0.post1__tar.gz → 2.0.1__tar.gz

{stochasticforceinference-2.0.0.post1 → stochasticforceinference-2.0.1}/AGENTS.md

@@ -110,7 +110,8 @@ compute for robustness; route by data regime, not by habit:
 | Quick exploration / huge dataset | linear | closed form, no initial guess |
 | Measurement (localization) noise | parametric | profiles Λ; EIV instrument removes the noise bias |
 | Coarse sampling (large Δt) | parametric | RK4 flow step replaces the Euler secant |
-| Model nonlinear in θ (NN drift, gated PSF) | parametric | the L-BFGS path is the only option |
+| Non-uniform sampling (irregular `t` / per-step `dt`) | parametric | per-interval flow steps + process covariances, no resampling |
+| Model nonlinear in θ (NN drift, gated PSF) | parametric | the damped-GN / L-BFGS paths are the only option |
 | Multi-particle / interacting | either | linear for speed; parametric when noise/coarse Δt too |
 | SPDE / grid fields | linear | the (experimental) SPDE toolbox is linear-only |
 
@@ -133,30 +134,42 @@ agreement is itself a diagnostic.
   | `inf.print_report()` / `inf.report_dict()` | Human / machine summary |
   | `inf.compare_to_exact(model_exact=...)` | Validate against a known model |
   | `inf.holdout_score(test)` | Held-out NMSE on `coll.split_time(...)` test data (data-abundant scenarios only) |
+  | `inf.compute_entropy_production()` | Dissipation of the observed dynamics (after a linear force fit; both engines): rate ± error + fluctuation bias and the AIC-debiased rate (`Sdot_debiased`), in k_B.  Underdamped: positions-only via the even/odd split; `coefficients=` enables cross-fitting |
+  | `inf.time_reversal_split()` | Underdamped only: the fitted field's reversible/irreversible parts `(F_even, F_odd)` as callables |
 
 * **Parametric estimators (robust, flexible; compute-intensive).**
   Robust to measurement noise
   and finite Δt.  Methods `infer_force` and `infer_diffusion`
   (implemented in `SFI.inference.parametric_core`).  Takes a `Basis`
   (linear-in-θ; PASTIS sparsification wired) or a `PSF` (general
-  parametric family): a single RK4 flow step per observation interval
-  defines the residual, the banded residual covariance gives a
-  windowed-precision NLL, and `(D, Λ)` are profiled natively
-  (moment-estimator init + one conditional-NLL refinement).  Two inner
+  parametric family): an RK4 flow step per observation interval
+  defines the residual, the block-banded residual covariance is
+  whitened *exactly* (reverse-time banded-innovations NLL — no window
+  truncation, no tuning knobs), and `(D, Λ)` are profiled natively
+  (moment-estimator init + an exact-NLL refinement on cached fixed-θ
+  tensors).  Non-uniform sampling (a `t` vector or per-step `dt`
+  array) fits directly — force and diffusion, both engines.  Two inner
   solvers, selected by `inner="auto"`:
 
-  * `inner="gn"` — direct Gauss–Newton on the windowed Gram (the
+  * `inner="gn"` — direct Gauss–Newton on the whitened Gram (the
     linear-in-θ fast path) with the skip-trick errors-in-variables
     instrument (`eiv=True`, consistent under measurement noise).
+    Nonlinear-in-θ PSFs run the same loop as damped Gauss–Newton,
+    instrument active.
   * `inner="lbfgs"` — frozen-precision L-BFGS for non-linear-in-θ
-    families (neural-net drift, gated PSFs, …); raise `inner_maxiter`
-    for large models.  Worked example:
+    overdamped families (neural-net drift, gated PSFs, …); raise
+    `inner_maxiter` for large models (underdamped redirects to the
+    damped-GN path).  Worked example:
     [`examples/gallery/advanced/nn_force_demo.py`](examples/gallery/advanced/nn_force_demo.py).
 
+  Caveat: for (near-)clean data at coarse effective sampling pass
+  `eiv=False, n_substeps=2` — `eiv="auto"` does not inspect the noise
+  level, and the `(D, Λ)` profile can fit a spurious Λ there.
+
   Multi-particle / interacting systems are supported in both overdamped
   and underdamped regimes (the multi-particle path uses the per-edge
   `d_x(same_particle=True)` / `d_v(same_particle=True)` Jacobian
-  protocol; O(N) per window).
+  protocol; O(N) per residual).
 
   See
   [`docs/source/inference/user_guide.rst`](docs/source/inference/user_guide.rst)
@@ -171,8 +184,9 @@ inf.infer_force_linear(basis, preset="auto")         # 2. force ("auto"/"robust"
 inf.infer_diffusion_linear()                         # 3. optional: constant sym D (default basis)
 inf.compute_force_error()                            # 4. error analysis
 inf.sparsify_force(criterion="PASTIS", p=0.1)        # 5. optional: sparsity
-inf.print_report()                                   # 6. summary
-inf.compare_to_exact(model_exact=process)            # 7. optional: validate
+inf.compute_entropy_production()                     # 6. optional: dissipation (OD & UD)
+inf.print_report()                                   # 7. summary
+inf.compare_to_exact(model_exact=process)            # 8. optional: validate
 ```
 
 **Parametric-estimator sequence:**
@@ -336,7 +350,10 @@ Use `coll.T` (frames) and `coll.d` (dimension) instead of
 - `*.bak` files, if you ever see one, are stale snapshots — ignore them.
 
 Deprecated / soon-to-be-removed symbols (do not use in new code):
-- (none currently)
+- `infer_force(..., extra_radius=)` / `infer_force(..., n_cond=)` —
+  deprecated tuning knobs, accepted but **inert** (a
+  `DeprecationWarning` fires when set).  The banded likelihood has no
+  window truncation to tune.
 
 ## 6. Testing, building, environment
 

{stochasticforceinference-2.0.0.post1 → stochasticforceinference-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: StochasticForceInference
-Version: 2.0.0.post1
+Version: 2.0.1
 Summary: Stochastic Force Inference for Langevin SDEs
 Author-email: Pierre Ronceray <pierre.ronceray@univ-amu.fr>
 License: MIT

{stochasticforceinference-2.0.0.post1 → stochasticforceinference-2.0.1}/SFI/inference/base.py

@@ -526,10 +526,15 @@ class BaseLangevinInference(ABC):
         # Entropy production
         if hasattr(self, "DeltaS"):
             print(
-                "Entropy production: inferred/bootstrapped error:",
+                "Entropy production (total Delta S, estimated error):",
                 self.DeltaS,
                 self.error_DeltaS,
             )
+            if hasattr(self, "DeltaS_debiased"):
+                print(
+                    "Entropy production, fluctuation-bias subtracted (AIC):",
+                    self.DeltaS_debiased,
+                )
 
         # Force inference metrics
         if hasattr(self, "force_predicted_MSE"):
@@ -649,6 +654,8 @@ class BaseLangevinInference(ABC):
         if hasattr(self, "DeltaS"):
             d["DeltaS"] = float(self.DeltaS)
             d["error_DeltaS"] = float(self.error_DeltaS)
+            if hasattr(self, "DeltaS_debiased"):
+                d["DeltaS_debiased"] = float(self.DeltaS_debiased)
 
         if hasattr(self, "force_coefficients"):
             d["force_coefficients"] = np.asarray(self.force_coefficients)

{stochasticforceinference-2.0.0.post1 → stochasticforceinference-2.0.1}/SFI/inference/overdamped.py

@@ -16,7 +16,7 @@ from SFI.integrate.integrand import (
 )
 from SFI.integrate.timeops import stream, timeop, velocity
 from SFI.statefunc import PSF, SF, Basis
-from SFI.utils.maths import sqrtm_psd
+from SFI.utils.maths import sqrtm_psd, stable_pinv
 
 from .result import InferenceResultSF  # fitted SF with param_cov/meta
 from .sparse import SparseScorer
@@ -403,6 +403,187 @@ class OverdampedLangevinInference(BaseLangevinInference):
         self.diffusion_scorer = SparseScorer(M=self.diffusion_moments, G=self.diffusion_G_full)
         self._update_diffusion_coefficients(self.diffusion_scorer.total_C)
 
+    def compute_entropy_production(self, *, support: str = "current") -> dict:
+        r"""Estimate the entropy production of the observed dynamics.
+
+        Projects the phase-space velocity (mean local velocity) of the data
+        onto the force basis and contracts it with the inverse average
+        diffusion — the estimator of Frishman & Ronceray, Phys. Rev. X 10,
+        021009 (2020), reconnected to the v2 moment engine.  Requires a
+        prior :meth:`infer_force_linear` fit (any preset); the Stratonovich
+        velocity moments are reused from the fit when available and computed
+        on demand otherwise.
+
+        .. physics:: Entropy production estimator (overdamped, linear basis)
+           :label: entropy-production-inference-overdamped
+           :category: Observable
+
+           .. math::
+
+              \Delta\hat S = 2\, M_v^\top G^{-1} M_v,
+              \qquad
+              M_{v,a} = \sum_t \mathrm{d}X_t \circ A^{-1}\, b_a,
+              \qquad A = 2\bar D,
+
+           .. math::
+
+              \hat{\dot S} = \frac{\Delta\hat S}{\tau_N},
+              \qquad
+              \dot S_{\mathrm{bias}} = \frac{2 N_b}{\tau_N},
+              \qquad
+              \delta \Delta S = \sqrt{2\,\Delta\hat S + (2 N_b)^2}.
+
+           :math:`\hat v = G^{-1} M_v` is the basis projection of the
+           phase-space velocity :math:`v = F - D\nabla\ln\rho`, :math:`N_b`
+           the number of basis degrees of freedom, and :math:`\tau_N` the
+           total particle-time.  The projection makes :math:`\Delta\hat S` a
+           *lower bound* on the entropy produced in the observed phase
+           space, up to the :math:`+2N_b` fluctuation bias.  The bias is
+           reported both ways: the raw plug-in value keeps it, and
+           ``DeltaS_debiased`` :math:`= \Delta\hat S - 2N_b` subtracts it.
+           This is exactly the **AIC complexity correction** applied to the
+           trajectory information: :math:`\Delta\hat S` is four times the
+           plug-in information carried by the projected velocity field, and
+           each fitted degree of freedom inflates a maximized (plug-in)
+           information by :math:`+\tfrac12` — the same counting that powers
+           the ``AIC`` criterion of ``sparsify_force``.
+
+        Parameters
+        ----------
+        support : {"current", "full"}
+            ``"current"`` (default) restricts the projection to the active
+            basis support — the full basis before sparsification, the
+            selected support after :meth:`sparsify_force` (shrinking the
+            :math:`2 N_b/\tau_N` bias).  ``"full"`` always uses the complete
+            basis.
+
+        Returns
+        -------
+        dict
+            ``{"Sdot", "Sdot_error", "Sdot_bias", "Sdot_debiased", "DeltaS",
+            "error_DeltaS", "DeltaS_debiased", "tauN", "Nb"}`` — the
+            per-particle entropy production rate, its estimated error and
+            fluctuation bias, the bias-subtracted (AIC-corrected) rate, the
+            total entropy :math:`\Delta\hat S = \hat{\dot S}\,\tau_N` with
+            error and its debiased value, the total particle-time and the
+            basis size.  All plain floats, in units of :math:`k_B` (nats).
+
+        Notes
+        -----
+        - The estimate assumes constant diffusion: the contraction uses the
+          average :math:`\bar D` even when a state-dependent field was
+          fitted (a warning is emitted in that case).  Extension point: a
+          trajectory integral of :math:`\hat v \cdot D(x)^{-1} \hat v`.
+        - ``Sdot_debiased`` can come out negative near equilibrium — that is
+          the expected fluctuation of an unbiased estimate around zero, not
+          an inconsistency.  Use the raw ``Sdot`` when a conservative
+          plug-in value is wanted, the debiased one for point estimates and
+          detection decisions.
+        - **Independent measurement noise does not bias the estimator at
+          leading order.**  The Stratonovich velocity moments are *odd*
+          under time reversal while i.i.d. (signal-independent) localization
+          noise is *even*, so the naive :math:`O(\Lambda/\Delta t)`
+          noise–increment correlation cancels exactly — per step it
+          telescopes to a boundary term.  The surviving effects are second
+          order and *not* included in the error bar: an :math:`O(\Lambda)`
+          basis-smoothing distortion (the moments see the
+          :math:`\Lambda`-blurred basis functions) and a noise-inflated
+          variance that raises the effective fluctuation bias.  A warning is
+          emitted when the estimated noise dominates the per-step diffusive
+          displacement (:math:`\mathrm{Tr}\,\Lambda \gtrsim 50\%` of
+          :math:`\mathrm{Tr}\,\bar D\,\Delta t`).  Noise *correlated with
+          the motion* — motion blur, exposure-time averaging — breaks the
+          parity cancellation and does bias the estimate: correct or
+          deconvolve it first (see :doc:`/inference/noise_and_sampling`).
+        - Parametric fits (:meth:`infer_force`) are not supported yet.  The
+          natural extension is the plug-in Stratonovich sum
+          :math:`\sum_t \mathrm{d}X_t \circ \bar D^{-1}\,
+          \tfrac12[\hat F(X_t)+\hat F(X_{t+1})]`.
+        - With weighted multi-dataset collections the normalization by the
+          unweighted :math:`\tau_N` is approximate (same caveat as
+          ``force_information``).
+        """
+        if self.metadata.get("force_method") != "linear":
+            raise RuntimeError(
+                "compute_entropy_production() requires a prior infer_force_linear() "
+                "fit; parametric fits (infer_force) are not supported yet."
+            )
+        lam = float(getattr(self, "Lambda_trace", 0.0))
+        if lam > 0.0:
+            # The leading O(Λ/Δt) noise bias cancels by time-reversal parity
+            # for signal-independent noise (the Stratonovich moments are odd,
+            # i.i.d. noise is even); what survives is second order.  Warn only
+            # when noise dominates the per-step diffusive displacement.
+            dt_val = float(self.data.peek_row(require={"dt"})["dt"])
+            diffusive_scale = float(jnp.trace(self.diffusion_average)) * dt_val
+            if lam > 0.5 * diffusive_scale:
+                logger.warning(
+                    "Strong measurement noise (Tr Lambda = %.3g, %.0f%% of "
+                    "Tr(D)*dt).  Independent noise does not bias the entropy "
+                    "estimate at leading order (parity cancellation), but "
+                    "basis smoothing and noise-inflated variance (second "
+                    "order) are NOT in the error bar — and noise correlated "
+                    "with the motion (blur) does not cancel.",
+                    lam, 100.0 * lam / max(diffusive_scale, 1e-300),
+                )
+        if self._diffusion_looks_state_dependent():
+            logger.warning(
+                "A state-dependent diffusion field was inferred; the entropy "
+                "estimator contracts with the constant average diffusion and is "
+                "only exact for constant D."
+            )
+
+        # Stratonovich v-moments: by-product of a Strato fit, else on demand.
+        if not hasattr(self, "force_v_moments"):
+            with self._structural_scope(self.force_basis):
+                self.force_v_moments = self._strato_v_moments()
+
+        if support == "current":
+            S = self.force_support
+            G_pinv = self.force_G_pinv
+        elif support == "full":
+            S = jnp.arange(self.force_v_moments.shape[0])
+            G_pinv = stable_pinv(self.force_G_full)
+        else:
+            raise ValueError(f"support must be 'current' or 'full', got {support!r}")
+
+        Mv = self.force_v_moments[S]
+        Nb = int(S.shape[0])
+        # A carries one factor of A_inv in both M_v and G, so the A-scaling
+        # cancels in G^{-1} M_v; the leading 2 restores D̄^{-1} = 2 A^{-1}.
+        DeltaS = float(2.0 * (Mv @ (G_pinv @ Mv))) if Nb > 0 else 0.0
+        tauN = float(self.data.Teff({"X", "X_plus", "dX", "dt"}))
+
+        self.DeltaS = DeltaS
+        self.error_DeltaS = float((2.0 * DeltaS + (2.0 * Nb) ** 2) ** 0.5)
+        self.DeltaS_debiased = DeltaS - 2.0 * Nb
+        self.Sdot = DeltaS / tauN
+        self.Sdot_bias = 2.0 * Nb / tauN
+        self.Sdot_debiased = self.DeltaS_debiased / tauN
+        self.Sdot_error = self.error_DeltaS / tauN
+        self.metadata["entropy_production"] = {
+            "support": support,
+            "Nb": Nb,
+            "tauN": tauN,
+        }
+        logger.info(
+            "Entropy production: DeltaS = %.4g +- %.4g "
+            "(rate %.4g +- %.4g, fluctuation bias %.4g, debiased %.4g)",
+            DeltaS, self.error_DeltaS, self.Sdot, self.Sdot_error,
+            self.Sdot_bias, self.Sdot_debiased,
+        )
+        return {
+            "Sdot": self.Sdot,
+            "Sdot_error": self.Sdot_error,
+            "Sdot_bias": self.Sdot_bias,
+            "Sdot_debiased": self.Sdot_debiased,
+            "DeltaS": self.DeltaS,
+            "error_DeltaS": self.error_DeltaS,
+            "DeltaS_debiased": self.DeltaS_debiased,
+            "tauN": tauN,
+            "Nb": Nb,
+        }
+
     def simulate_bootstrapped_trajectory(self, key, oversampling=1, simulate=True, dataset=0):
         """
         Simulate an overdamped Langevin trajectory with the inferred force and diffusion fields.
@@ -461,7 +642,7 @@ class OverdampedLangevinInference(BaseLangevinInference):
             return data_bootstrap, bootstrapped_process
         return bootstrapped_process
 
-    # ── Parametric (windowed) force inference ──
+    # ── Parametric (exact-core) force inference ──
 
     def infer_force(
         self,
@@ -478,18 +659,23 @@ class OverdampedLangevinInference(BaseLangevinInference):
         inner_maxiter: int = 80,
         extra_radius: int = 1,
     ) -> None:
-        r"""Infer the force field with the minimal parametric estimator.
-
-        Built on ``SFI.inference.parametric_core``: a single RK4 flow step
-        per observation interval defines the residual, the residual
-        covariance gives a windowed-precision NLL, and the parameters are
-        found by direct Gauss–Newton (linear-in-θ ``Basis``, with the
-        skip-trick errors-in-variables instrument) or frozen-precision
-        L-BFGS (nonlinear-in-θ ``PSF``).  ``(D, Λ)`` are profiled
-        natively: moment-estimator init, then one windowed
-        conditional-NLL refinement at the fitted θ.
-
-        .. physics:: Parametric windowed force inference (overdamped)
+        r"""Infer the force field with the exact parametric estimator.
+
+        Built on ``SFI.inference.parametric_core``: an RK4 flow step per
+        observation interval defines the residual, the block-tridiagonal
+        residual covariance is whitened *exactly* by a reverse-time
+        block-LDLᵀ innovations recursion (no window truncation, no tuning
+        knobs), and the parameters are found by direct Gauss–Newton
+        (linear-in-θ ``Basis``, with the skip-trick errors-in-variables
+        instrument) or L-BFGS (nonlinear-in-θ ``PSF``).  ``(D, Λ)`` are
+        profiled natively: moment-estimator init, then an exact banded-NLL
+        refinement at the fitted θ on cached fixed-θ tensors (zero basis
+        evaluations per profile iteration).  Non-uniform sampling is
+        supported end-to-end: datasets carrying an absolute time vector
+        ``t`` or a per-step ``dt`` array fit directly, with per-interval
+        flow steps and process covariances.
+
+        .. physics:: Parametric force inference (overdamped)
            :label: parametric-force-overdamped
            :category: Inference
 
@@ -500,10 +686,11 @@ class OverdampedLangevinInference(BaseLangevinInference):
            :math:`\Phi(x;\theta) = z(\Delta t) - x`
            (one RK4 step by default) defines the residual
            :math:`r_t = y_{t+1} - y_t - \Phi(y_t;\theta)`.
-           Residuals follow a banded Gaussian whose local precision
-           weights the Gauss–Newton normal equations; under
-           measurement noise the left factor is replaced by the
-           η-clean *skip* instrument
+           Residuals follow a block-tridiagonal Gaussian that is
+           whitened exactly (reverse-time innovations), and the
+           whitened sensitivities enter the Gauss–Newton normal
+           equations; under measurement noise the left factor is
+           replaced by the η-clean *skip* instrument
            :math:`\psi_{\rm inst} = \partial\Phi/\partial\theta`
            evaluated at the lagged clean point (``eiv=True``),
            giving a consistent estimating equation.
@@ -526,27 +713,36 @@ class OverdampedLangevinInference(BaseLangevinInference):
             Flow predictor (default ``"rk4"``, a single 4th-order step).
         n_substeps : int
             Integrator micro-steps per observation interval (default 1 —
-            the single-step minimal estimator).
+            the single-step minimal estimator).  At coarse effective
+            sampling (fast dynamics per interval) raise to 2 — the RK4
+            flow model saturates at ``n_substeps=2`` on typical chaotic
+            benchmarks.  With per-step ``dt`` the substep is
+            ``h_k = dt_k / n_substeps``.
         inner : {"auto", "gn", "lbfgs"}
-            Inner solver.  ``"auto"`` → direct Gauss–Newton for a linear
-            ``Basis``, L-BFGS for a ``PSF``.
+            Inner solver.  ``"auto"`` → Gauss–Newton (direct for a
+            linear ``Basis``, damped for a nonlinear ``PSF`` — the
+            instrument stays active); ``"lbfgs"`` forces the
+            frozen-precision quadratic route.
         eiv : {"auto", True, False, float}
             Measurement-noise errors-in-variables instrument.  ``"auto"``
             (default) → ``True`` for all models (interacting models use
             the same N-body flow for the instrument as for the residual);
             ``True`` forces the η-clean skip instrument (consistent under
             noise); ``False`` is the plain MLE; a float in ``[0, 1]``
-            blends.  Active on the GN path only.
+            blends.  ``"auto"`` does *not* inspect the noise level: for
+            (near-)clean data at coarse effective sampling pass
+            ``eiv=False`` — the ``(D, Λ)`` profile cannot separate a
+            Δt-independent Λ from the process increment structure there
+            and can fit a spurious measurement noise (see
+            :ref:`parametric-algorithm`).
         max_outer : int
             Outer Gauss–Newton / IRLS iterations (default 5).
         inner_maxiter : int
             Inner L-BFGS iterations per outer step on the PSF path
             (default 80; raise for large nonlinear families, e.g. NNs).
         extra_radius : int
-            Precision-window padding beyond the covariance bandwidth
-            (default 1).  Raise to 2–3 in the noise-dominated regime
-            β = Tr(Λ)/Tr(2DΔt) ≫ 1, where the windowed precision
-            decays slowly and the default window under-resolves it.
+            Deprecated, no effect (a ``DeprecationWarning`` fires when
+            a non-default value is passed).
 
         Updates
         -------
@@ -587,7 +783,14 @@ class OverdampedLangevinInference(BaseLangevinInference):
         F_psf = _as_psf(F)
 
         with self._structural_scope(F_psf):
-            dt_val = float(self.data.peek_row(require={"dt"})["dt"])
+            import numpy as _np
+
+            from SFI.inference.parametric_core.solve import _dt_steps
+
+            # representative Δt for logging and the reported β — the median
+            # step (identical to the single step at uniform sampling)
+            dt_val = float(_np.median(_np.concatenate(
+                [_dt_steps(ds) for ds in self.data.datasets])))
 
             logger.info(
                 "[infer_force] OD minimal parametric solve (n_params=%d, dt=%.4g, %s·n%d, basis_mode=%s)...",
@@ -600,6 +803,7 @@ class OverdampedLangevinInference(BaseLangevinInference):
                 integrator=integrator, n_substeps=n_substeps,
                 inner=inner, eiv=eiv, max_outer=max_outer,
                 inner_maxiter=inner_maxiter, extra_radius=extra_radius,
+                chunk_target_bytes=self._chunk_target_bytes,
             )
             t_elapsed = _time.perf_counter() - t0
 
@@ -689,10 +893,13 @@ class OverdampedLangevinInference(BaseLangevinInference):
         r"""Infer state-dependent diffusion D(x) from parametric residuals.
 
         Requires a prior parametric :meth:`infer_force` call.  Holds the
-        fitted force fixed and minimises the windowed conditional NLL over
-        the diffusion parameters (the log-det term makes the diffusion
-        level identifiable), reusing the same flow residuals and integrate
-        engine as the force solve.
+        fitted force fixed and minimises the exact banded NLL over the
+        diffusion parameters (the log-det term makes the diffusion level
+        identifiable) on cached fixed-θ tensors: the flow residuals and
+        stage Jacobians are computed once at :math:`\hat\theta`, so each
+        L-BFGS iteration costs linear algebra only — zero force or basis
+        evaluations.  Non-uniform sampling (``t`` vector or per-step
+        ``dt``) is supported.
 
         .. physics:: State-dependent diffusion inference (overdamped)
            :label: parametric-diffusion-overdamped
@@ -700,7 +907,7 @@ class OverdampedLangevinInference(BaseLangevinInference):
 
            With the force :math:`\hat F` held fixed, the state-dependent
            diffusion :math:`D(x;\theta_D)` is optimised by minimising the
-           windowed conditional negative log-likelihood; :math:`\Lambda`
+           exact banded negative log-likelihood; :math:`\Lambda`
            from the force inference is held fixed.  A rank-2 basis gives
            :math:`D(x) = \sum_j (\theta_D)_j\, d_j(x)`; a PSF is evaluated
            directly.
@@ -756,6 +963,7 @@ class OverdampedLangevinInference(BaseLangevinInference):
             self.data, self.force_psf, self.force_coefficients_full, D_psf,
             Lambda=Lambda, theta_D0=theta_D0,
             n_substeps=n_substeps, integrator=integrator, maxiter=maxiter,
+            chunk_target_bytes=self._chunk_target_bytes,
         )
         theta_D = res.theta_D
         self.diffusion_coefficients = theta_D
@@ -786,6 +994,61 @@ class OverdampedLangevinInference(BaseLangevinInference):
         b_right = self.force_basis @ self.A_inv
         return self.__G_matrix__(b_left, b_right, self.__force_G_mode__, "ima,imb->iab")
 
+    def _strato_v_moments(self) -> jnp.ndarray:
+        r"""Stratonovich (trapezoid) phase-space velocity moments.
+
+        Extensive, dt-weighted, mask-aware sums
+
+        .. math::
+
+           M_{v,a} = \sum_t \mathrm{d}X_t \cdot A^{-1} \cdot
+                     \tfrac12\bigl[b_a(X_t) + b_a(X_{t+1})\bigr]
+
+        — the by-product of Stratonovich force fitting and the raw material
+        of :meth:`compute_entropy_production`.
+        """
+        A = ConstOperand(self.A_inv, alias="A")
+        V = TimeOperand(velocity("dX", "dt"), alias="V")
+        B0 = ExprOperand(expr=self.force_basis, x=stream("X"), alias="B0")
+        Bp = ExprOperand(expr=self.force_basis, x=stream("X_plus"), alias="Bp")
+        prog_B0 = Integrand(
+            exprs=[B0],
+            times=[V],
+            consts=[A],
+            terms=[Term(eq="im,mn,ina->ia", ops=("V", "A", "B0"))],
+        )
+        prog_Bp = Integrand(
+            exprs=[Bp],
+            times=[V],
+            consts=[A],
+            terms=[Term(eq="im,mn,ina->ia", ops=("V", "A", "Bp"))],
+        )
+        prog_strato_vb = 0.5 * (prog_B0 + prog_Bp)
+        return integrate(
+            self.data, prog_strato_vb, reduce="sum", chunk_target_bytes=self._chunk_target_bytes
+        )
+
+    def _diffusion_looks_state_dependent(self) -> bool:
+        """Best-effort probe: does ``diffusion_inferred`` vary with x?
+
+        Used by :meth:`compute_entropy_production` to warn when a
+        state-dependent diffusion field was fitted (the estimator contracts
+        with the constant average).  Conservative: unprobeable fields count
+        as state-dependent.
+        """
+        D_sf = getattr(self, "diffusion_inferred", None)
+        if D_sf is None:
+            return False
+        try:
+            x0 = jnp.asarray(self.data.datasets[0].X[0][:1])  # (1, d)
+            x1 = x0 + 1.0 + 0.5 * jnp.abs(x0)
+            D_a = jnp.asarray(D_sf(x0))
+            D_b = jnp.asarray(D_sf(x1))
+            scale = 1.0 + float(jnp.max(jnp.abs(D_a)))
+            return bool(float(jnp.max(jnp.abs(D_a - D_b))) > 1e-6 * scale)
+        except Exception:  # pragma: no cover — conservative fallback
+            return True
+
     def _force_moments(self):
         r"""
         Compute force moments ⟨ v · A_inv · b ⟩ with Ito / Ito-shift / Strato flavors.
@@ -869,24 +1132,7 @@ class OverdampedLangevinInference(BaseLangevinInference):
         logger.debug("Computing Strato force coefficients.")
 
         # v ∘ b via trapezoid on basis
-        B0 = ExprOperand(expr=self.force_basis, x=stream("X"), alias="B0")
-        Bp = ExprOperand(expr=self.force_basis, x=stream("X_plus"), alias="Bp")
-        prog_B0 = Integrand(
-            exprs=[B0],
-            times=[V],
-            consts=[A],
-            terms=[Term(eq="im,mn,ina->ia", ops=("V", "A", "B0"))],
-        )
-        prog_Bp = Integrand(
-            exprs=[Bp],
-            times=[V],
-            consts=[A],
-            terms=[Term(eq="im,mn,ina->ia", ops=("V", "A", "Bp"))],
-        )
-        prog_strato_vb = 0.5 * (prog_B0 + prog_Bp)
-        self.force_v_moments = integrate(
-            self.data, prog_strato_vb, reduce="sum", chunk_target_bytes=self._chunk_target_bytes
-        )
+        self.force_v_moments = self._strato_v_moments()
 
         logger.debug("Computing Strato gradient term.")
 
@@ -1133,13 +1379,22 @@ def _D_noisy(**streams):
 
        Two-point estimator robust to measurement noise
        (CL Vestergaard, PC Blainey, H Flyvbjerg - Physical Review E, 2014).
+
+       Non-uniform sampling: the stencil expectation is
+       :math:`2D(\mathrm{d}t + \mathrm{d}t^-)` with the localization terms
+       cancelling at any spacing, so the denominator is the two-interval
+       mean :math:`(\mathrm{d}t + \mathrm{d}t^-)/2` — identical to
+       :math:`\mathrm{d}t` (bitwise) at uniform sampling, exactly unbiased
+       under per-step ``dt``.
     """
     dX = streams["dX"]
     dXm = streams["dX_minus"]
     dt = streams["dt"]
+    dtm = streams["dt_minus"]
     while dt.ndim < dX.ndim:
         dt = dt[..., jnp.newaxis]
-    invdt = 1.0 / dt
+        dtm = dtm[..., jnp.newaxis]
+    invdt = 1.0 / (0.5 * (dt + dtm))
     a = jnp.einsum("...m,...n->...mn", dX, dX * invdt)
     b = jnp.einsum("...m,...n->...mn", dX, dXm * invdt)
     c = jnp.einsum("...m,...n->...mn", dXm, dX * invdt)
@@ -1147,7 +1402,7 @@ def _D_noisy(**streams):
     return 0.25 * (a + 2 * b + 2 * c + d)
 
 
-_D_noisy._requires = frozenset({"dX", "dX_minus", "dt"})  # type: ignore[attr-defined]
+_D_noisy._requires = frozenset({"dX", "dX_minus", "dt", "dt_minus"})  # type: ignore[attr-defined]
 
 
 @timeop(name="D_weaknoise", batch_safe=True)
@@ -1169,19 +1424,27 @@ def _D_weaknoise(**streams):
 
        Uses successive-displacement differences; suitable when localization
        noise is negligible.
+
+       Non-uniform sampling: ``E[(dX − dX⁻)⊗(dX − dX⁻)] = 2D(dt + dt⁻)``
+       for clean data at any spacing, so the denominator is the
+       two-interval mean ``(dt + dt⁻)/2`` — bitwise-identical to ``dt``
+       at uniform sampling, exactly unbiased per-step (same
+       generalization as the noisy estimator above).
     """
     dX = streams["dX"]
     dXm = streams["dX_minus"]
     dt = streams["dt"]
+    dtm = streams["dt_minus"]
     while dt.ndim < dX.ndim:
         dt = dt[..., jnp.newaxis]
-    invdt = 1.0 / dt
+        dtm = dtm[..., jnp.newaxis]
+    invdt = 1.0 / (0.5 * (dt + dtm))
     ddx = dX - dXm
     dv = dX * invdt - dXm * invdt
     return 0.25 * jnp.einsum("...m,...n->...mn", ddx, dv)
 
 
-_D_weaknoise._requires = frozenset({"dX", "dX_minus", "dt"})  # type: ignore[attr-defined]
+_D_weaknoise._requires = frozenset({"dX", "dX_minus", "dt", "dt_minus"})  # type: ignore[attr-defined]
 
 
 @timeop(name="Lambda_meas_noise", batch_safe=True)

stochasticforceinference-2.0.1/SFI/inference/parametric_core/__init__.py

@@ -0,0 +1,32 @@
+# SFI/inference/parametric_core/ — the exact parametric estimator.
+"""
+The parametric force/diffusion estimator: RK4-flow residuals, block-banded
+residual covariance whitened *exactly* by a reverse-time block-LDLᵀ
+innovations recursion (:mod:`banded` / :mod:`runner`), errors-in-variables
+instrument, and native ``(D, Λ)`` profiling on cached fixed-θ tensors.
+Per-interval (non-uniform) dt is supported end-to-end.
+
+A single, paper-ready objective with a handful of parameters, integrating
+like ``infer_*_linear`` (Basis/PSF in → ``InferenceResultSF`` out,
+multi-particle aware).
+
+Docs: ``docs/source/inference/parametric_concept.rst`` (foundations) and
+``docs/source/inference/parametric_algorithm.rst`` (implementation).
+"""
+
+from __future__ import annotations
+
+from .solve import (
+    DiffusionSolveResult,
+    ForceSolveResult,
+    solve_diffusion_od,
+    solve_diffusion_ud,
+    solve_force_od,
+    solve_force_ud,
+)
+
+__all__ = [
+    "solve_force_od", "solve_force_ud",
+    "solve_diffusion_od", "solve_diffusion_ud",
+    "ForceSolveResult", "DiffusionSolveResult",
+]