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).
Itô quasi-likelihood loss (nonlinear force)¶
Source: SFI.inference.overdamped — _build_force_loss_psf
Negative log-quasi-likelihood for parametric drift estimation.
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()
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 windowed conditional 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 windowed force inference (overdamped) (in api/SFI.inference)
[Inference] Parametric windowed 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 banded Gaussian whose local precision
weights 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 windowed conditional NLL on pentadiagonal (bandwidth-2) covariance windows; \(\Lambda\) from the force inference is held fixed.
Parametric windowed force inference (underdamped) (in api/SFI.inference)
[Inference] Parametric windowed 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 whose local precision weights 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.
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.