Physics Reference¶
This page collects the key mathematical formulas and physical equations implemented in the SFI library. Notation follows the conventions of the PASTIS paper (Ronceray, 2025) and is used consistently throughout the documentation.
Notation¶
Throughout SFI the following symbols are used consistently. Bold face denotes vectors and matrices; italic denotes scalars.
\(\mathbf{x}_t\) |
State (position) vector at time \(t\).
Shape |
\(\mathbf{v}_t\) |
Velocity, either known or reconstructed via finite differences (secant velocities). |
\(\Delta\mathbf{x}_t\) |
Displacement \(\mathbf{x}_{t+1} - \mathbf{x}_t\). |
\(\mathbf{F}(\mathbf{x})\) |
Drift / force field (Itô convention unless stated otherwise). |
\(\mathbf{D}(\mathbf{x})\) |
Diffusion tensor (Itô convention). |
\(\bar{\mathbf{D}}\) |
Empirical (time-averaged) diffusion tensor.
In code: |
\(\mathbf{B}\) |
Noise amplitude: \(\mathbf{B} = \sqrt{2\mathbf{D}}\). |
\(\mathrm{d}W_t\) |
Wiener increment (Gaussian white noise), \(\mathrm{d}W \sim \mathcal{N}(0,\,I\,\mathrm{d}t)\). |
\(b_i(\mathbf{x})\) |
Basis function \(i\) evaluated at \(\mathbf{x}\). Scalar by default; bold \(\mathbf{b}_i\) when vector-valued. |
\(\hat{F}_i\) |
Inferred coefficient for basis function \(i\). |
\(n\) |
Library (basis) size — number of basis functions. |
\(G_{ij}\) |
Gram matrix \(G_{ij} = \langle \mathbf{b}_i \cdot \bar{\mathbf{D}}^{-1} \cdot \mathbf{b}_j \rangle\). |
\(M_i\) |
Force moment \(M_i = \langle \mathbf{v}_t \cdot \bar{\mathbf{D}}^{-1} \cdot \mathbf{b}_i \rangle\). |
\(\Lambda\) |
Measurement / localization noise covariance. |
\(p_{\text{PASTIS}}\) |
PASTIS significance threshold (model selection parameter). |
Note
Code mapping: the code attribute diffusion_average corresponds
to \(\bar{\mathbf{D}}\). Older versions of SFI used the symbol
\(A = 2\bar{\mathbf{D}}\); throughout these docs we normalise to
\(\bar{\mathbf{D}}\).
Dynamical equations¶
Overdamped Langevin SDE¶
Source: SFI.inference.overdamped.OverdampedLangevinInference,
SFI.langevin.overdamped.OverdampedProcess
\(\mathbf{F}(\mathbf{x})\) is the Itô drift, \(\mathbf{D}(\mathbf{x})\) the diffusion tensor (Itô convention), and \(\mathrm{d}W_t\) a Wiener increment.
Underdamped Langevin SDE¶
Source: SFI.inference.underdamped.UnderdampedLangevinInference,
SFI.langevin.underdamped.UnderdampedProcess
Only positions \(\mathbf{x}(t)\) are observed; velocities are reconstructed from finite differences (secant velocities).
Simulation¶
Euler–Maruyama integrator (overdamped)¶
Source: SFI.langevin.overdamped — _make_step
where \(\mathbf{B} = \sqrt{2\mathbf{D}}\) and \(\boldsymbol{\xi}_t \sim \mathcal{N}(\mathbf{0}, \mathbf{I})\).
Velocity-Verlet integrator (underdamped)¶
Source: SFI.langevin.underdamped — _make_step
Stochastic splitting (kick–drift–kick):
Preserves the symplectic structure of the deterministic part.
Noise amplitude from diffusion tensor¶
Source: SFI.langevin.base — _setup_diffusion
For scalar \(\sigma\): \(\mathbf{B} = \sqrt{2\sigma}\,\mathbf{I}_d\). For constant matrix \(\mathbf{D}\): PSD matrix square root. For state-dependent \(\mathbf{D}(\mathbf{x})\): evaluated at each step.
Diffusion estimators¶
MSD diffusion estimator (overdamped)¶
Source: SFI.inference.overdamped — _D_msd
Simplest estimator; biased by measurement noise.
Vestergaard–Blainey–Flyvbjerg estimator (the "noisy" estimator)¶
Source: SFI.inference.overdamped — _D_noisy
Two-point estimator robust to measurement noise (Vestergaard, Blainey, & Flyvbjerg, Phys. Rev. E, 2014). The stencil is attached to its first point \(\mathbf{x}_t\): conditioned on \(\mathbf{x}_t\) both increments lie in the future, so the estimate is unbiased state-resolved and not only in the mean.
Weak-noise diffusion estimator (overdamped)¶
Source: SFI.inference.overdamped — _D_weaknoise
Uses successive-displacement differences, in which the drift cancels to \(O(\mathrm{d}t^2)\) without a fit; suitable when localization noise is negligible. Attached to the first point of its stencil, like the noisy estimator above.
Measurement noise estimator (overdamped)¶
Source: SFI.inference.overdamped — _Lambda
Estimates localization / measurement noise from anti-correlation of successive displacements.
MSD diffusion estimator (underdamped)¶
Source: SFI.inference.underdamped — _D_msd_uli
Weak-noise diffusion estimator (underdamped)¶
Source: SFI.inference.underdamped — _D_weaknoise_uli
Noisy diffusion estimator (underdamped)¶
Source: SFI.inference.underdamped — _D_noisy_uli
where \(a = \Delta\mathbf{x}_t \otimes \Delta\mathbf{x}_t\), \(b = \Delta\mathbf{x}_{t-1} \otimes \Delta\mathbf{x}_{t-1}\), etc. Optimally handles both signal and localization noise.
Measurement noise estimator (underdamped)¶
Source: SFI.inference.underdamped — _Lambda_uli
Same displacement products \((a\ldots f)\) as the noisy diffusion estimator. Extracts localization noise for underdamped systems.
Force inference¶
Linear force regression (overdamped)¶
Source: SFI.inference.overdamped.OverdampedLangevinInference.infer_force_linear()
\(G_{ij} = \langle \mathbf{b}_i \cdot \bar{\mathbf{D}}^{-1} \cdot \mathbf{b}_j \rangle\) is the \(\bar{\mathbf{D}}\)-weighted Gram matrix, \(M_i = \langle \mathbf{v}_t \cdot \bar{\mathbf{D}}^{-1} \cdot \mathbf{b}_i \rangle\) are the force moments, and \(n\) is the library size (number of basis functions).
Overdamped force moments¶
Source: SFI.inference.overdamped — _force_moments
Itô moments:
Stratonovich moments (trapezoid + gradient correction):
Underdamped force moments (ULI)¶
Source: SFI.inference.underdamped — _force_moments
where \(w = (1+2\ell)/3\), with \(\ell=1\) (symmetric), \(\ell=0\) (early), \(\ell=-\tfrac{1}{2}\) (anticipated).
Exact banded-innovations NLL (parametric estimators)¶
Source: SFI.inference.parametric_core — banded_nll_gram
The single-step RK4 flow residuals \(r_k = x_{k+1} - \Phi(x_k;\theta)\) carry a block-banded covariance \(\Sigma\) (overdamped: block-tridiagonal; underdamped: pentadiagonal). The block LDLᵀ factorisation \(\Sigma = L\,S\,L^\top\) has a banded unit-lower factor, so the innovations
whiten the residual stream exactly in one sequential pass, and
Whitening the regressor columns alongside yields the exact GLS Gram and moments as plain sums — no overlapping windows, no truncated precision. The default reverse-time (anti-causal) recursion keeps every errors-in-variables instrument–residual pairing measurement-noise-clean. Full construction: Parametric estimators — algorithm and parameters.
Kinematic reconstructions (ULI)¶
Source: SFI.inference.underdamped — _X_sym_uli, _V_sym_uli, _A_sym_uli, etc.
Three reconstruction modes for the unobserved velocity:
Symmetric:
Early:
Anticipated:
Error analysis¶
Force coefficient covariance & predicted error¶
Source: SFI.inference.base.BaseLangevinInference.compute_force_error()
In the estimator’s extensive normalization — \(G_{ij} = \sum_t \mathrm{d}t\;\mathbf{b}_i^\top (2\bar{\mathbf{D}})^{-1}\mathbf{b}_j\), \(M_i = \sum_t \mathrm{d}\mathbf{x}_t^\top (2\bar{\mathbf{D}})^{-1}\mathbf{b}_i\) (the fit \(G\hat F = M\) is invariant under this rescaling) — the Gram is the Hessian of the Onsager–Machlup action, hence exactly the Fisher information of the coefficients:
Assumes the sampling error dominates; measurement noise and discretization biases are not addressed.
Normalized MSE metrics (force & diffusion)¶
Source: SFI.inference.base.BaseLangevinInference.compare_to_exact()
where \(\mathbf{E} = \mathbf{D}_{\text{exact}} - \hat{\mathbf{D}}\).
Model selection¶
Source: SFI.inference.sparsity — SparseScorer, select_by_ic()
where \(\mathcal{I}(k) = \tfrac{1}{2}\,\hat{F}_B^\top M_B\) is the log-likelihood gain with \(k\) basis terms selected from a library of size \(n\), and \(n_0\) is the PASTIS prior scale.
The PASTIS significance \(p_{\text{PASTIS}}\) corresponds to the threshold above which a basis term is considered supported by the data.
Observables¶
Information functional & entropy production (overdamped)¶
Source: SFI.langevin.overdamped.OverdampedProcess.simulate()
\(I\) estimates the information content; \(S\) the entropy production (time-reversal asymmetry).
Basis functions¶
Multivariate polynomial basis¶
Source: SFI.bases.monomials_up_to()
Full polynomial dictionary up to a given total degree, optionally including velocity monomials and lifted to vector or matrix rank.
Radial pair interaction basis¶
Source: SFI.bases.pairs.radial_pair_basis()
Scalar radial kernel \(\phi_\alpha\) times the unit displacement vector. Available kernel families: exponential-polynomial, Gaussian, power-law, and compactly supported.
Discrete Laplacian on regular grid¶
Source: SFI.bases.spde.Laplacian
Finite-difference Laplacian using a cross stencil on a Cartesian grid.
Available as a composable operator via the Laplacian
class. See Spatial field inference (SPDE) for a full introduction to SPDE operators.
Additional formulas from API documentation
The following entries are collected automatically from .. physics::
directives in the API documentation:
Dynamical equations¶
Overdamped Langevin SDE (in api/SFI.inference)
[Dynamical equations] Overdamped Langevin SDE
\(F(x)\) is the Itô drift, \(D(x)\) the diffusion tensor (Itô convention), and \(\mathrm{d}\xi\) is Gaussian white noise.
Underdamped Langevin SDE (in api/SFI.inference)
[Dynamical equations] Underdamped Langevin SDE
Only positions \(x(t)\) are observed; velocities are reconstructed from finite differences.
Inference¶
State-dependent diffusion inference (overdamped) (in api/SFI.inference)
[Inference] State-dependent diffusion inference (overdamped)
With the force \(\hat F\) held fixed, the state-dependent diffusion \(D(x;\theta_D)\) is optimised by minimising the exact banded negative log-likelihood; \(\Lambda\) from the force inference is held fixed. A rank-2 basis gives \(D(x) = \sum_j (\theta_D)_j\, d_j(x)\); a PSF is evaluated directly.
Parametric force inference (overdamped) (in api/SFI.inference)
[Inference] Parametric force inference (overdamped)
The observed positions follow
\(y_t = x_t + \eta_t\) where
\(\eta \sim \mathcal{N}(0, \Lambda)\). The
deterministic flow
\(\Phi(x;\theta) = z(\Delta t) - x\)
(one RK4 step by default) defines the residual
\(r_t = y_{t+1} - y_t - \Phi(y_t;\theta)\).
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
\(\psi_{\rm inst} = \partial\Phi/\partial\theta\)
evaluated at the lagged clean point (eiv=True),
giving a consistent estimating equation.
Linear force regression (overdamped) (in api/SFI.inference)
[Inference] Linear force regression (overdamped)
\(G_{ab} = \langle b_a(x_t)\, b_b(x_t) \rangle\) is the Gram matrix, \(M_a = \langle v_t \cdot A^{-1} \cdot b_a \rangle\) are the force moments, and \(A = 2\bar D\).
Diffusion information for model selection (in api/SFI.inference)
[Inference] Diffusion information for model selection
Linear fit. \(\hat C = G^{-1}M\) solves the moment
condition \(M - GC = \sum_t s_t(C) = 0\), whose long-run
covariance is the sandwich meat \(S\) of
compute_diffusion_error(). Asymptotically
\(M \sim \mathcal N(GC,\, S)\), so the log-likelihood of a
support \(B\) (coefficients zero off \(B\)) is the
efficient (optimal-weight) minimum-distance criterion
maximised by \(\hat C_B = \mathcal F_{BB}^{-1} m_B\). On the full basis \(\hat C_B\) is the least-squares fit and \(\mathcal F^{-1} = G^{-1}SG^{-1}\) its sandwich covariance; on a sub-support it is the efficient restricted estimator, with covariance \(\mathcal F_{BB}^{-1}\). \(S\) is evaluated once, at the full-basis fit, so every support is scored in the same metric and \(2[\mathcal I(\mathrm{full}) - \mathcal I(B)]\) is the Hansen–Newey–West distance statistic, \(\chi^2_{n_0-|B|}\) when the true field lies in \(B\). The plain Gram \(\tfrac12 M^\top G^{-1}M\) is not an information: it carries the units of \(D^2\) and ignores the estimator's variance.
Parametric fit. \(\mathcal F\) is the Hessian of the banded NLL at \(\hat\theta_D\) and \(m = \mathcal F \hat\theta_D\) (the quadratic expansion of the NLL, as for the parametric force); the selected support is then re-fitted on the exact NLL.
State-dependent diffusion inference (underdamped) (in api/SFI.inference)
[Inference] State-dependent diffusion inference (underdamped)
With the force \(\hat F(x,v)\) held fixed, the state-dependent diffusion \(D(x,v;\theta_D)\) is optimised by minimising the exact banded NLL of the pentadiagonal (bandwidth-2) residual covariance; \(\Lambda\) from the force inference is held fixed.
Parametric force inference (underdamped) (in api/SFI.inference)
[Inference] Parametric force inference (underdamped)
The phase-space dynamics
\(\dot{x}=v,\;\mathrm{d}v = F(x,v)\mathrm{d}t
+ \sqrt{2D}\,\mathrm{d}W\) are factored into deterministic
flow + noise. Three-point shooting residuals follow a
pentadiagonal Gaussian that is whitened exactly
(reverse-time innovations) before entering the
Gauss–Newton normal equations; the process noise enters at
\(\Delta t^3\). Under measurement noise the left factor
is the η-clean skip instrument built from the lagged clean
position pair (eiv=True) — consistent where the naive
MLE is velocity-EIV-biased.
Error analysis¶
Normalized MSE metrics (force & diffusion) (in api/SFI.inference)
[Error analysis] Normalized MSE metrics (force & diffusion)
- where \(E = D_{\text{exact}} - \hat D\).
NMSE_diffusion = MSE_diffusion / < tr(A_inv Dh A_inv Dh) >
Diffusion coefficient covariance (sandwich estimator) (in api/SFI.inference)
[Error analysis] Diffusion coefficient covariance (sandwich estimator)
The linear diffusion fit is an ordinary least-squares projection of a local estimator \(\hat D_t\) onto the basis, \(\hat C = G^{-1} M\) with \(G = \sum_t B_t^\top B_t\) and \(M = \sum_t B_t^\top \hat D_t\). Its covariance is the sandwich
where the scores \(s_t\) are summed over particles. The local estimators use a few consecutive frames, so scores whose stencils share a frame are correlated (through shared increments, or a shared localization error); \(K\) is the stencil's frame span, read from the streams the estimator requires — scores further apart share no frame and are uncorrelated. No noise model is assumed: state-dependent diffusion, the estimator's own variance and its serial correlation all enter through the empirical scores.
Force coefficient covariance & predicted error (in api/SFI.inference)
[Error analysis] Force coefficient covariance & predicted error
Assumes the sampling error dominates; measurement noise and discretization biases are not addressed.
Model selection¶
Information criteria for sparse model selection (in api/SFI.inference)
[Model selection] Information criteria for sparse model selection
where \(\mathcal{I}(k)\) is the log-likelihood gain with k basis terms out of \(n_0\) candidates, \(\tau\) is the total trajectory time, \(p_0\) is the PASTIS significance level, and \(\gamma \in [0,1]\) controls EBIC stringency.
Observable¶
Entropy production estimator (overdamped, linear basis) (in api/SFI.inference)
[Observable] Entropy production estimator (overdamped, linear basis)
\(\hat v = G^{-1} M_v\) is the basis projection of the
phase-space velocity \(v = F - D\nabla\ln\rho\), \(N_b\)
the number of basis degrees of freedom, and \(\tau_N\) the
total particle-time. The projection makes \(\Delta\hat S\) a
lower bound on the entropy produced in the observed phase
space, up to the \(+2N_b\) fluctuation bias. The bias is
reported both ways: the raw plug-in value keeps it, and
DeltaS_debiased \(= \Delta\hat S - 2N_b\) subtracts it.
This is exactly the AIC complexity correction applied to the
trajectory information: \(\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 \(+\tfrac12\) — the same counting that powers
the AIC criterion of sparsify_force.
Entropy production estimator (underdamped, linear basis) (in api/SFI.inference)
[Observable] Entropy production estimator (underdamped, linear basis)
with \(b^{\pm}(x,v) = \tfrac12[b(x,v) \pm b(x,-v)]\), the ULI symmetric kinematics \((\hat x, \hat v, \hat a)\), and \(C\) the coefficients. In a steady state the expectation equals the entropy production rate whenever \(\nabla_v \cdot F^{+} = 0\) (standard mechanical even forces).
Finite \(\Delta t\). The moment objects carry
\(O(h)\) kinematic biases (\(h = \Delta t\)), removed by
the counterterm \(\Delta S_{\Delta t} = C^\top K C + l^\top
C\) of _entropy_dt_programs(), valid for any \(C\). The
coefficients are the force fit's, with its own finite-\(\Delta
t\) and noise properties; their first-order kinematic bias is
reported as Sdot_dt_bias (see Notes). The fluctuation scale
is set by the odd
quadratic
\(Q^{-} = 2\,C^\top G^{--} C
\approx \int \hat F^{-}\!\cdot \bar D^{-1} \hat F^{-}\,\mathrm{d}t\)
— the log ratio's two large contributions fluctuate even where
their means cancel:
where \(N^{-} = \operatorname{rank} G^{--}\) counts the odd-sector degrees of freedom (this reduces to the overdamped formula, where the odd sector is everything) and \(\delta\Delta S_{\mathrm{block}}\) is an empirical block-variance estimate that additionally captures the slowly-correlated fluctuations of the \(F^{+}\!\cdot\bar D^{-1} F^{-}\) current term.
Basis functions¶
Multivariate polynomial basis (in api/SFI.bases)
[Basis functions] Multivariate polynomial basis
Full polynomial dictionary up to a given total degree, optionally including velocity monomials and lifted to vector or matrix rank.
Radial pair interaction basis (in api/SFI.bases.pairs)
[Basis functions] Radial pair interaction basis
Scalar radial kernel \(\phi_\alpha\) times the unit displacement vector. Available kernel families: exponential-polynomial, Gaussian, power-law, and compactly supported.