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).
Weak-noise diffusion estimator (overdamped)¶
Source: SFI.inference.overdamped — _D_weaknoise
Uses successive-displacement differences; suitable when localization noise is negligible.
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\).
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) >
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 fitted coefficients. In a steady state the expectation equals the entropy production rate whenever \(\nabla_v \cdot F^{+} = 0\) (standard mechanical even forces). The provisional 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.