Note
Go to the end to download the full example code.
Custom basis with extras — traps in measured light fields¶
When does a force model need hand-written code? Rarely: per-experiment constants, recorded drives and dataset-specific coefficients are all expressible with built-in symbols. The exception is physics the symbol algebra cannot express — typically a measured object such as an image. This page shows both, on one dataset.
Three experiments trap a colloid in an optical tweezer at different positions and temperatures. In each, the particle also feels a weak speckle light pattern, recorded as an image and stored with the experiment. The force is
with a shared stiffness \(k\) and light coupling \(\alpha\), an unknown trap centre \(\mathbf x^0_e\) per experiment, and the measured intensity map \(I_e\).
The trap is built from built-in symbols: a shared linear term plus a per-experiment constant via
dataset_indicator().The light force needs
make_basis(): a function that interpolates the gradient of the experiment’s image, read fromextras.
Tags
synthetic · overdamped · 2D · custom-basis · extras · multi-experiment
stamp_output()
[Generated: 2026-10-17 23:30]
Three experiments, three recorded light fields¶
Each experiment stores its intensity gradient — computed once from the
recorded image on a pixel grid — in extras_global. Images are
smoothed random speckle patterns, normalised to \([0, 1]\).
from scipy.ndimage import gaussian_filter
L, n_pix = 3.0, 64 # image covers [-L, L]² with n_pix² pixels
h = 2 * L / (n_pix - 1) # pixel size
def speckle_image(seed):
rng = np.random.default_rng(seed)
img = gaussian_filter(rng.normal(size=(n_pix, n_pix)), sigma=4, mode="wrap")
return (img - img.min()) / (img.max() - img.min())
experiments = [ # trap centre, diffusion (temperature), image seed
{"x0": np.array([1.0, 0.5]), "D": 0.2, "seed": 1},
{"x0": np.array([-0.5, 1.0]), "D": 0.5, "seed": 2},
{"x0": np.array([0.0, -0.8]), "D": 1.0, "seed": 3},
]
for exp in experiments:
exp["image"] = speckle_image(exp["seed"])
exp["grad"] = np.stack(np.gradient(exp["image"], h)) # (2, n_pix, n_pix): ∂I/∂x, ∂I/∂y
The custom brick: interpolated image gradient¶
The basis function receives the state and the experiment’s extras, and
returns the vector feature \(-\nabla I_e(\mathbf x)\), bilinearly
interpolated between pixels. extras_keys declares what it reads;
the inference engine delivers each dataset’s own image.
from jax.scipy.ndimage import map_coordinates
from SFI.statefunc import make_basis
def light_force(x, *, extras):
"""-∇I at x, bilinear interpolation of the stored gradient images."""
pix = (x + L) / h # (2,) pixel coordinates
coords = [pix[0:1], pix[1:2]]
g = extras["light_grad"]
gx = map_coordinates(g[0], coords, order=1, mode="nearest")
gy = map_coordinates(g[1], coords, order=1, mode="nearest")
return -jnp.concatenate([gx, gy])[:, None] # (dim, 1 feature)
B_light = make_basis(light_force, dim=2, rank=1, n_features=1,
extras_keys=("light_grad",), labels=["-∇I"])
Simulate¶
Each experiment is simulated with its own centre, temperature and image; the shared parameters are \(k = 2\) and \(\alpha = 0.5\). The collections are then pooled into one multi-experiment dataset.
from SFI.bases import X, unit_vector_basis
from SFI.langevin import OverdampedProcess
k_true, alpha_true = 2.0, 0.5
dt, Nsteps = 0.01, 50_000
key = random.PRNGKey(42)
runs = []
for i, exp in enumerate(experiments):
# F = -k x + k x0 + alpha (-∇I): a combination of the three bricks
proc = OverdampedProcess(
F=X(dim=2) & unit_vector_basis(2) & B_light, D=exp["D"],
theta_F=jnp.array([-k_true, *(k_true * exp["x0"]), alpha_true]),
)
proc.set_extras(extras_global={"light_grad": jnp.asarray(exp["grad"])})
proc.initialize(jnp.asarray(exp["x0"]))
key, sub = random.split(key)
runs.append(proc.simulate(dt=dt, Nsteps=Nsteps, key=sub, prerun=200, oversampling=10))
coll = runs[0].concat(runs[1:], weights="pool")
print(f"{len(coll.datasets)} experiments × {runs[0].T} frames")
3 experiments × 50000 frames
The first 30 time units of each trajectory over its light field; crosses mark the trap centres.
Infer: built-in trap + custom light brick¶
dataset_indicator(3) * unit_vector_basis(2, axes=[a]) gives each
experiment its own constant force along axis a — the
\(k\,\mathbf x^0_e\) of its trap — while X(dim=2) carries the
shared stiffness. We add all quadratic monomials as distractors and
let PASTIS decide what the data support. The data are clean
(simulated without measurement noise), so we use the clean-data
estimators: "WeakNoise" diffusion, in which the drift cancels, and
preset="clean".
from SFI import OverdampedLangevinInference
from SFI.bases import dataset_indicator, monomials_degree
offsets = [dataset_indicator(3) * unit_vector_basis(2, axes=[a]) for a in range(2)]
B_trap = X(dim=2) & offsets[0] & offsets[1]
B = B_trap & B_light & monomials_degree(2, dim=2, rank="vector")
inf = OverdampedLangevinInference(coll)
inf.compute_diffusion_constant(method="WeakNoise")
inf.infer_force_linear(B, preset="clean")
inf.compute_force_error()
inf.sparsify_force(criterion="PASTIS")
inf.compute_force_error()
inf.print_report()
--- StochasticForceInference Report ---
Average diffusion tensor:
[[0.56453913 0.00066402]
[0.00066402 0.5662467 ]]
Measurement noise tensor:
[[5.9539903e-05 1.7721217e-05]
[1.7721215e-05 1.1084135e-04]]
Force estimated information: 1593.017578125
Force: estimated normalized mean squared error (sampling only): 0.002197088272270115
Force Gram condition number: 33.9
Force Coefficient Table
───────────────────────────────────────────────────────────────────
# Label Coefficient Std.Err SNR Sig
───────────────────────────────────────────────────────────────────
0 x -2.04454e+00 3.75057e-02 54.5 **
1 ds0·e0 2.03537e+00 5.96470e-02 34.1 **
2 ds1·e0 -9.19723e-01 5.41270e-02 17.0 **
4 ds0·e1 1.02123e+00 5.09750e-02 20.0 **
5 ds1·e1 2.06690e+00 6.18089e-02 33.4 **
6 ds2·e1 -1.54068e+00 5.69527e-02 27.1 **
7 -∇I 5.44740e-01 5.60514e-02 9.7 *
───────────────────────────────────────────────────────────────────
7/14 basis functions in support, sig: 7* / 6** / 0*** (|SNR| ≥ 2 / 10 / 100)
(Std.err. reflects sampling error only; discretization bias is not included.)
Zeroed (7): ds2·e0, x0^2·e0, x0^2·e1, (x0·x1)·e0, (x0·x1)·e1, x1^2·e0, x1^2·e1
The Pareto front shows the selection: the information gained by the best model of each size rises until seven terms are in, then flattens. PASTIS stops there; AIC, less strict, would admit one more.
The selected model is the true one: the shared stiffness, the per-experiment offsets and the light coupling, while the quadratic terms are pruned (so is the x-offset of experiment 3, whose trap sits at \(x = 0\)). Dividing each offset by \(\hat k\) gives the trap centres.
labels = list(B.labels)
support = list(np.asarray(inf.force_support))
coef = dict(zip(support, np.asarray(inf.force_coefficients)))
err = dict(zip(support, np.asarray(inf.force_coefficients_stderr)))
i_k, i_light = labels.index(B_trap.labels[0]), labels.index("-∇I")
k_hat = -coef[i_k]
print(f"k = {k_hat:.3f} ± {err[i_k]:.3f} (true {k_true})")
print(f"alpha = {coef.get(i_light, 0.0):.3f} ± {err.get(i_light, 0.0):.3f} (true {alpha_true})")
for e, exp in enumerate(experiments):
c = [coef.get(labels.index(f"ds{e}·e{a}"), 0.0) for a in range(2)]
print(f"experiment {e + 1}: x0 = ({c[0] / k_hat:+.3f}, {c[1] / k_hat:+.3f})"
f" (true ({exp['x0'][0]:+.2f}, {exp['x0'][1]:+.2f}))")
k = 2.045 ± 0.038 (true 2.0)
alpha = 0.545 ± 0.056 (true 0.5)
experiment 1: x0 = (+0.996, +0.499) (true (+1.00, +0.50))
experiment 2: x0 = (-0.450, +1.011) (true (-0.50, +1.00))
experiment 3: x0 = (+0.000, -0.754) (true (+0.00, -0.80))
Three temperatures, one force fit¶
The experiments run at different temperatures, but the force fit used a
single pooled diffusion constant. That does not bias the coefficients
— a linear regression is unbiased whatever its weights — but the
per-experiment temperatures are worth having. They come out of a
diffusion fit on the same indicator idea,
dataset_indicator(3) * identity_matrix_basis(2), with the same
clean-data local estimator as above.
from SFI.bases import identity_matrix_basis
inf.infer_diffusion_linear(dataset_indicator(3) * identity_matrix_basis(2), M_mode="WeakNoise")
inf.compute_diffusion_error()
D_hat = np.asarray(inf.diffusion_coefficients).ravel()
D_err = np.asarray(inf.diffusion_coefficients_stderr).ravel()
for e, exp in enumerate(experiments):
print(f"experiment {e + 1}: D = {D_hat[e]:.3f} ± {D_err[e]:.3f} (true {exp['D']})")
experiment 1: D = 0.200 ± 0.001 (true 0.2)
experiment 2: D = 0.498 ± 0.003 (true 0.5)
experiment 3: D = 0.998 ± 0.005 (true 1.0)
Does the pooled model reproduce each experiment?¶
simulate_bootstrapped_trajectory()
with dataset=e collapses the pooled model to experiment e — its
trap centre, its temperature and its recorded light field — and
simulates it for as long as the recording.
boots = [inf.simulate_bootstrapped_trajectory(random.PRNGKey(10 + e), dataset=e)[0]
for e in range(len(experiments))]
Each bootstrap follows its recording, including the distortions the speckle imprints on the trap.
Summary¶
Situation |
Building block |
|---|---|
Per-experiment constant or coefficient (linear estimators) |
|
Per-experiment parameter in a parametric model |
|
Recorded scalar drive or metadata |
|
Measured field, lookup table, anything not expressible in symbols |
|
Thumbnail¶
Total running time of the script: (0 minutes 34.359 seconds)