StochasticForceInference 2.0.0__tar.gz → 2.0.1__tar.gz

{stochasticforceinference-2.0.0 → 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 → stochasticforceinference-2.0.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: StochasticForceInference
-Version: 2.0.0
+Version: 2.0.1
 Summary: Stochastic Force Inference for Langevin SDEs
 Author-email: Pierre Ronceray <pierre.ronceray@univ-amu.fr>
 License: MIT
 Project-URL: Homepage, https://github.com/ronceray/StochasticForceInference
-Project-URL: Documentation, https://sfi.readthedocs.io
+Project-URL: Documentation, https://stochasticforceinference.readthedocs.io
 Project-URL: Repository, https://github.com/ronceray/StochasticForceInference
 Project-URL: Issues, https://github.com/ronceray/StochasticForceInference/issues
 Project-URL: Changelog, https://github.com/ronceray/StochasticForceInference/blob/main/CHANGELOG.md
@@ -54,6 +54,10 @@ Dynamic: license-file
 
 # Stochastic Force Inference (SFI)
 
+[![Documentation](https://readthedocs.org/projects/stochasticforceinference/badge/?version=latest)](https://stochasticforceinference.readthedocs.io/en/latest/)
+[![PyPI](https://img.shields.io/pypi/v/StochasticForceInference.svg)](https://pypi.org/project/StochasticForceInference/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/ronceray/StochasticForceInference/blob/main/LICENSE)
+
 **Infer force and diffusion fields from stochastic trajectory data.**
 
 SFI is a JAX-based Python package for learning the drift (force) and diffusion
@@ -165,14 +169,14 @@ inf.compare_to_exact(model_exact=proc)
 ## Documentation
 
 Full documentation is available at
-[sfi.readthedocs.io](https://sfi.readthedocs.io), including:
+[stochasticforceinference.readthedocs.io](https://stochasticforceinference.readthedocs.io), including:
 
-- **[Tutorial](https://sfi.readthedocs.io/en/latest/gallery/ou_demo.html)** — end-to-end walkthrough
-- **[Examples gallery](https://sfi.readthedocs.io/en/latest/gallery/index.html)** — worked examples covering sparsity, multi-particle, and SPDE inference
-- **[Model building](https://sfi.readthedocs.io/en/latest/statefunc/user_guide.html)** — composable state functions
-- **[Trajectory handling](https://sfi.readthedocs.io/en/latest/trajectory/user_guide.html)** — data ingestion, masking, degradation
-- **[Running inference](https://sfi.readthedocs.io/en/latest/inference/user_guide.html)** — estimator choice, overdamped/underdamped engines
-- **[API reference](https://sfi.readthedocs.io/en/latest/api_frontend.html)** — full autodoc
+- **[Tutorial](https://stochasticforceinference.readthedocs.io/en/latest/gallery/ou_demo.html)** — end-to-end walkthrough
+- **[Examples gallery](https://stochasticforceinference.readthedocs.io/en/latest/gallery/index.html)** — worked examples covering sparsity, multi-particle, and SPDE inference
+- **[Model building](https://stochasticforceinference.readthedocs.io/en/latest/statefunc/user_guide.html)** — composable state functions
+- **[Trajectory handling](https://stochasticforceinference.readthedocs.io/en/latest/trajectory/user_guide.html)** — data ingestion, masking, degradation
+- **[Running inference](https://stochasticforceinference.readthedocs.io/en/latest/inference/user_guide.html)** — estimator choice, overdamped/underdamped engines
+- **[API reference](https://stochasticforceinference.readthedocs.io/en/latest/api_frontend.html)** — full autodoc
 
 ## Package structure
 
@@ -192,11 +196,11 @@ guidance.
 
 ## Citation
 
-If you use SFI in your research, please cite:
-
-> Frishman, A. & Ronceray, P., *Learning force fields from stochastic
-> trajectories*, Physical Review X (2020).
-> [DOI: 10.1103/PhysRevX.10.021009](https://doi.org/10.1103/PhysRevX.10.021009)
+If you use SFI, please cite the software (see [`CITATION.cff`](CITATION.cff))
+together with the method paper(s) relevant to the features you use. See
+**[How to cite](https://stochasticforceinference.readthedocs.io/en/latest/#how-to-cite)** in the
+documentation for the full, feature-specific list (overdamped, underdamped/ULI,
+trapeze, and PASTIS references).
 
 ## License
 

{stochasticforceinference-2.0.0 → stochasticforceinference-2.0.1}/README.md

@@ -1,5 +1,9 @@
 # Stochastic Force Inference (SFI)
 
+[![Documentation](https://readthedocs.org/projects/stochasticforceinference/badge/?version=latest)](https://stochasticforceinference.readthedocs.io/en/latest/)
+[![PyPI](https://img.shields.io/pypi/v/StochasticForceInference.svg)](https://pypi.org/project/StochasticForceInference/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/ronceray/StochasticForceInference/blob/main/LICENSE)
+
 **Infer force and diffusion fields from stochastic trajectory data.**
 
 SFI is a JAX-based Python package for learning the drift (force) and diffusion
@@ -111,14 +115,14 @@ inf.compare_to_exact(model_exact=proc)
 ## Documentation
 
 Full documentation is available at
-[sfi.readthedocs.io](https://sfi.readthedocs.io), including:
+[stochasticforceinference.readthedocs.io](https://stochasticforceinference.readthedocs.io), including:
 
-- **[Tutorial](https://sfi.readthedocs.io/en/latest/gallery/ou_demo.html)** — end-to-end walkthrough
-- **[Examples gallery](https://sfi.readthedocs.io/en/latest/gallery/index.html)** — worked examples covering sparsity, multi-particle, and SPDE inference
-- **[Model building](https://sfi.readthedocs.io/en/latest/statefunc/user_guide.html)** — composable state functions
-- **[Trajectory handling](https://sfi.readthedocs.io/en/latest/trajectory/user_guide.html)** — data ingestion, masking, degradation
-- **[Running inference](https://sfi.readthedocs.io/en/latest/inference/user_guide.html)** — estimator choice, overdamped/underdamped engines
-- **[API reference](https://sfi.readthedocs.io/en/latest/api_frontend.html)** — full autodoc
+- **[Tutorial](https://stochasticforceinference.readthedocs.io/en/latest/gallery/ou_demo.html)** — end-to-end walkthrough
+- **[Examples gallery](https://stochasticforceinference.readthedocs.io/en/latest/gallery/index.html)** — worked examples covering sparsity, multi-particle, and SPDE inference
+- **[Model building](https://stochasticforceinference.readthedocs.io/en/latest/statefunc/user_guide.html)** — composable state functions
+- **[Trajectory handling](https://stochasticforceinference.readthedocs.io/en/latest/trajectory/user_guide.html)** — data ingestion, masking, degradation
+- **[Running inference](https://stochasticforceinference.readthedocs.io/en/latest/inference/user_guide.html)** — estimator choice, overdamped/underdamped engines
+- **[API reference](https://stochasticforceinference.readthedocs.io/en/latest/api_frontend.html)** — full autodoc
 
 ## Package structure
 
@@ -138,11 +142,11 @@ guidance.
 
 ## Citation
 
-If you use SFI in your research, please cite:
-
-> Frishman, A. & Ronceray, P., *Learning force fields from stochastic
-> trajectories*, Physical Review X (2020).
-> [DOI: 10.1103/PhysRevX.10.021009](https://doi.org/10.1103/PhysRevX.10.021009)
+If you use SFI, please cite the software (see [`CITATION.cff`](CITATION.cff))
+together with the method paper(s) relevant to the features you use. See
+**[How to cite](https://stochasticforceinference.readthedocs.io/en/latest/#how-to-cite)** in the
+documentation for the full, feature-specific list (overdamped, underdamped/ULI,
+trapeze, and PASTIS references).
 
 ## License
 

{stochasticforceinference-2.0.0 → 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)