3D milling school — the interaction rules of 200 swimmers

synthetic underdamped multi-particle linear sparsity large-scale 3D

Two hundred fish swim around a landmark and organise into a mill: a rotating torus in which everyone circles the same axis in the same direction, a state many fish schools adopt. A 3D tracking rig records only their positions. From these tracks alone, can we learn the rules each individual follows — how it swims, what holds it near the centre, how it reacts to its neighbours — with error bars, and check that these rules, simulated, rebuild the mill?

Each swimmer is an inertial, self-propelled particle:

\[\dot{\mathbf{v}}_p = -k\,\mathbf{x}_p + \bigl(\alpha - \beta\,|\mathbf{v}_p|^2\bigr)\,\mathbf{v}_p + \sum_{q \ne p} \Bigl[\phi(r_{pq})\,\hat{\mathbf{r}}_{pq} + \psi(r_{pq})\,(\mathbf{v}_q - \mathbf{v}_p)\Bigr] + \sqrt{2D}\,\boldsymbol{\xi}_p .\]

The self-propulsion term makes each fish cruise at the preferred speed \(v_0 = \sqrt{\alpha/\beta}\); \(-k\,\mathbf{x}\) is a weak pull towards the centre (a landmark); \(\phi(r)\) is the positional interaction (short-range repulsion, weak mid-range attraction; positive values attract), \(\psi(r)\) the velocity alignment with neighbours, and \(D\) the strength of the random part of the swimming. With 200 individuals every frame contains 19 900 pairs.

The recipe: build a generic dictionary of one-body terms and pair kernels from SFI’s built-in bases, fit it to the positions, let PASTIS choose the terms, read the interaction kernels with confidence bands, and validate by simulating the inferred school.

Note

This is an advanced example (underdamped, 200 interacting individuals). Start with the main gallery if you are new to SFI.

Tags

synthetic · underdamped · multi-particle · linear · sparsity · large-scale · 3D

stamp_output()
[Generated: 2026-10-18 10:21]

The school, and what the tracker gives us

The ground truth is written with the same building blocks we will use for inference: one-body terms X() and V(), and pair kernels from SFI.bases.pairs. The parameters: centre pull \(k = 0.06\), propulsion \(\alpha = \beta = 0.4\) (cruising speed \(v_0 = 1\)), repulsion \(\phi_{\rm rep}(r) = -2\,e^{-r^2/2\cdot 0.5^2}\), attraction \(\phi_{\rm att}(r) = 0.01\,e^{-r^2/2\cdot 2^2}\) (weak per pair, but summed over many neighbours), alignment \(\psi(r) = 0.05\,e^{-r^2/2}\) and noise \(D = 0.01\). The school starts on a ring; the first 10 time units are discarded, and the mill is still tightening when the recording begins.

from SFI.bases import V, X
from SFI.bases.pairs import gaussian_kernels, pair_velocity_difference, radial_pair_basis, scalar_pair_basis
from SFI.langevin import UnderdampedProcess

d, N = 3, 200
v = V(dim=d)
swim = v & (v.dot(v) * v)                        # (α - β|v|²) v : two terms


def alignment(kernels):
    return (scalar_pair_basis(kernels, dim=d) * pair_velocity_difference(dim=d)).dispatch_pairs()


B_true = (X(dim=d) & swim
          & radial_pair_basis(gaussian_kernels([0.5, 2.0]), dim=d).dispatch_pairs()
          & alignment(gaussian_kernels([1.0])))
k, alpha, eps, c_att, a_align, D_true = 0.06, 0.4, 2.0, 0.01, 0.05, 0.01
school = UnderdampedProcess(B_true, D=D_true,
                            theta_F=jnp.array([-k, alpha, -alpha, -eps, c_att, a_align]))

k1, k2 = random.split(random.PRNGKey(7))
angle = 2 * np.pi * np.arange(N) / N
ring = np.stack([np.cos(angle), np.sin(angle), 0 * angle], axis=1)
tangent = np.stack([-np.sin(angle), np.cos(angle), 0 * angle], axis=1)
school.initialize(jnp.asarray(ring / np.sqrt(k)) + 0.3 * random.normal(k1, (N, d)), v0=jnp.asarray(tangent))

dt, T = 0.025, 2000                              # 40 frames per time unit
# 20 integrator substeps per frame keep the simulator's own error on D
# below the per-cent level; the first 400 frames (10 time units) are discarded.
recording = school.simulate(dt=dt, Nsteps=T, key=k2, oversampling=20, prerun=400)

From here on, the model is forgotten. All we keep is what a 3D tracker would deliver: a (frames, individuals, 3) array of positions and the frame interval — velocities and accelerations are never observed.

from SFI.trajectory import TrajectoryCollection

positions = recording.to_array()                 # (T, N, 3) — your tracking output
data = TrajectoryCollection.from_arrays(X=positions, dt=dt)

print(f"{N} individuals x {data.T} frames ({data.T * dt:.0f} time units)")
200 individuals x 2000 frames (50 time units)
mean displacement per frame 0.023, mean nearest-neighbour distance 1.02

The recording in 3D. The camera follows the school’s centre of mass and slowly circles it; each fish is coloured by its heading around the mill axis, so a coherent mill shows as a colour wheel.


A generic dictionary of rules

We do not assume the shapes of the interactions. The dictionary offers three one-body terms (centre pull \(\mathbf{x}\), and the propulsion pair \(\mathbf{v}\), \(|\mathbf{v}|^2\mathbf{v}\)) and pair kernels at three ranges — Gaussians of width 0.5, 1 and 2 — both for the positional interaction (kernel times the unit vector \(\hat{\mathbf{r}}_{pq}\)) and for alignment (kernel times the velocity difference). Nine candidates; the truth uses six of them.

kernels = gaussian_kernels([0.5, 1.0, 2.0])
B_centre = X(dim=d)
B_position = radial_pair_basis(kernels, dim=d).dispatch_pairs()
B_align = alignment(kernels)
B = B_centre & swim & B_position & B_align
theta_true = np.array([-k, alpha, -alpha, -eps, 0.0, c_att, 0.0, a_align, 0.0])
print(f"{B.n_features} candidate terms: {list(B.labels)}")
9 candidate terms: ['x', 'v', '(v·v)·v', 'r^0·gauss(σ=0.5)', 'r^0·gauss(σ=1)', 'r^0·gauss(σ=2)', '(r^0·gauss(σ=0.5))·Δv_ij', '(r^0·gauss(σ=1))·Δv_ij', '(r^0·gauss(σ=2))·Δv_ij']

Inference

The underdamped estimator reconstructs velocities and accelerations from the positions and projects the dynamics on the dictionary; the 19 900 pair sums per frame are evaluated by the basis itself. Then PASTIS selects the terms the data support.

preset="clean" declares the positions noise-free, which they are here. This matters: second differences of positions amplify localisation noise \(\sigma\) by \(1/\Delta t^2\), so the linear underdamped estimator needs \(\sigma \ll \sqrt{D\,\Delta t^3}\) — a scale printed below, under a thousandth of the distance between neighbours (about 1) here. For noisy tracks, the parametric infer_force() models the noise (see Van der Pol oscillator — underdamped inference); its cost grows with the number of pairs and is suited to small groups.

import SFI

inf = SFI.UnderdampedLangevinInference(data)
inf.compute_diffusion_constant()
inf.infer_force_linear(B, preset="clean")
inf.compute_force_error()

coeffs_full = np.asarray(inf.force_coefficients_full)
stderr_full = np.asarray(inf.force_coefficients_stderr)
print("full dictionary (z = deviation from the truth in standard errors):")
for label, c, s, true in zip(B.labels, coeffs_full, stderr_full, theta_true):
    print(f"  {label:28s} {c:+.4f} ± {s:.4f}   true {true:+.3f}   z = {(c - true) / s:+.1f}")
full dictionary (z = deviation from the truth in standard errors):
  x                            -0.0593 ± 0.0007   true -0.060   z = +1.0
  v                            +0.4089 ± 0.0071   true +0.400   z = +1.2
  (v·v)·v                      -0.4057 ± 0.0064   true -0.400   z = -0.9
  r^0·gauss(σ=0.5)             -2.0024 ± 0.0135   true -2.000   z = -0.2
  r^0·gauss(σ=1)               -0.0009 ± 0.0033   true +0.000   z = -0.3
  r^0·gauss(σ=2)               +0.0101 ± 0.0006   true +0.010   z = +0.1
  (r^0·gauss(σ=0.5))·Δv_ij     +0.0483 ± 0.0229   true +0.000   z = +2.1
  (r^0·gauss(σ=1))·Δv_ij       +0.0443 ± 0.0034   true +0.050   z = -1.7
  (r^0·gauss(σ=2))·Δv_ij       +0.0005 ± 0.0004   true +0.000   z = +1.2

Every coefficient lands within about two standard errors of the truth, including the three that should vanish. Now PASTIS chooses the model:

inf.sparsify_force(criterion="PASTIS")
inf.compute_force_error()
inf.print_report()

sel = np.asarray(inf.force_support)
z_sel = (np.asarray(inf.force_coefficients) - theta_true[sel]) / np.asarray(inf.force_coefficients_stderr)
print(f"true support recovered: {set(sel.tolist()) == set(np.flatnonzero(theta_true).tolist())}; "
      f"largest |z| among the selected terms: {np.abs(z_sel).max():.1f}")
D_hat = float(np.mean(np.diag(np.asarray(inf.diffusion_average))))
print(f"diffusion D = {D_hat:.4f} (true {D_true}); noise scale sqrt(D dt^3) = {np.sqrt(D_hat * dt**3):.1e}")
  --- StochasticForceInference Report ---
Average diffusion tensor:
 [[ 1.0067335e-02 -2.0704492e-05 -2.0507641e-06]
 [-2.0704492e-05  1.0033885e-02  3.2055297e-05]
 [-2.0507641e-06  3.2055297e-05  1.0031745e-02]]
Measurement noise tensor:
 [[-2.2075950e-09 -2.1463199e-11  3.8962937e-11]
 [-2.1463199e-11 -2.3004834e-09  4.0281056e-11]
 [ 3.8962937e-11  4.0281056e-11 -1.5131112e-09]]
Force estimated information: 35696.7109375
Force: estimated normalized mean squared error (sampling only): 8.404127607805746e-05
Force Gram condition number: 4.17e+04

  Force Coefficient Table
  ─────────────────────────────────────────────────────────────────────────────────
  #    Label                      Coefficient       Std.Err     SNR  Sig
  ─────────────────────────────────────────────────────────────────────────────────
  0    x                         -5.94367e-02   5.96218e-04    99.7  **
  1    v                          4.05421e-01   6.12186e-03    66.2  **
  2    (v·v)·v                   -4.03913e-01   6.25513e-03    64.6  **
  3    r^0·gauss(σ=0.5)          -2.00453e+00   1.03505e-02   193.7  ***
  5    r^0·gauss(σ=2)             9.93043e-03   2.27747e-04    43.6  **
  7    (r^0·gauss(σ=1))·Δv_ij     5.06745e-02   8.42136e-04    60.2  **
  ─────────────────────────────────────────────────────────────────────────────────
  6/9 basis functions in support, sig: 6* / 6** / 1*** (|SNR| ≥ 2 / 10 / 100)
  (Std.err. reflects sampling error only; discretization bias is not included.)
  Zeroed (3): r^0·gauss(σ=1), (r^0·gauss(σ=0.5))·Δv_ij, (r^0·gauss(σ=2))·Δv_ij
true support recovered: True; largest |z| among the selected terms: 0.9
diffusion D = 0.0100 (true 0.01); noise scale sqrt(D dt^3) = 4.0e-04

Left: the Pareto front — information gained against model size; the selected model sits where adding a term stops paying. Right: the full nine-term fit with 1-σ error bars against the truth, on a symmetric-log scale so that the weak attraction and alignment terms show next to the repulsion (\(\phi_\ell\), \(\psi_\ell\): positional and alignment kernels of width \(\ell\)). The short-range alignment \(\psi_{0.5}\) carries the largest error bar — close pairs are rare, so the data say little about alignment at contact — and trades weight with its overlapping neighbour \(\psi_1\); PASTIS keeps only the latter.


Sparse model selection, Full dictionary — PASTIS keeps 6 / 9

The recovered rules

Summing the selected terms gives each rule as a function, with a 95 % band from the coefficient covariance (coeff_block() and kernel_predict_ci()). The shaded histograms show where the data live — speeds for the propulsion, pair distances for the kernels: a rule is only measured where it is sampled.

from SFI.inference import kernel_predict_ci

speeds = np.linspace(0.0, 1.6, 200)
c_swim, cov_swim = inf.coeff_block(swim)
J = np.stack([speeds, speeds**3], axis=1)        # propulsion along v: c1 s + c2 s^3
swim_mean = J @ c_swim
swim_half = 1.96 * np.sqrt(np.einsum("ri,ij,rj->r", J, cov_swim, J))

r_eval = np.linspace(0.05, 8.0, 300)
ci_pos = kernel_predict_ci(r_eval, kernels, *inf.coeff_block(B_position))
ci_ali = kernel_predict_ci(r_eval, kernels, *inf.coeff_block(B_align))
true_pos = theta_true[3:6] @ ci_pos["phi"]
true_ali = theta_true[6:9] @ ci_ali["phi"]
v0_hat = np.sqrt(-c_swim[0] / c_swim[1])
print(f"cruising speed sqrt(alpha/beta) = {v0_hat:.3f} (true 1)")
Propulsion $(\alpha-\beta s^2)\,s$, Positional $\phi(r)$  (>0: attraction), Alignment $\psi(r)$
cruising speed sqrt(alpha/beta) = 1.002 (true 1)

Do the inferred rules rebuild the mill?

The fit never looked at collective properties. We simulate the inferred model (simulate_bootstrapped_trajectory()), starting from the first recorded frame, for as long as the recording. oversampling=10 substeps per frame keep the integrator’s error far below the collective fluctuations compared here.

boot, _ = inf.simulate_bootstrapped_trajectory(key=random.PRNGKey(11), oversampling=10)
positions_boot = boot.to_array()

Side by side, from the same starting snapshot: the recording and the school simulated from the inferred rules (same camera path).


Quantitatively, two order parameters: the polarisation \(P = |\langle\hat{\mathbf{v}}\rangle|\) (a school swimming in one direction has \(P \approx 1\)) and the milling order \(M = |\langle\hat{\mathbf{r}}\times\hat{\mathbf{v}}\rangle|\), with \(\hat{\mathbf{r}}\) the direction from the centre of mass (a perfect mill has \(M = 1\)). Velocities come from the positions by finite differences.

def order_parameters(coll):
    x, u = coll.to_array(), coll.velocity_array(scheme="central")
    u = u / np.linalg.norm(u, axis=-1, keepdims=True)
    r = x - x.mean(axis=1, keepdims=True)
    r = r / np.linalg.norm(r, axis=-1, keepdims=True)
    return np.linalg.norm(u.mean(axis=1), axis=-1), np.linalg.norm(np.cross(r, u).mean(axis=1), axis=-1)


for name, coll in [("recording", data), ("inferred model", boot)]:
    P, M = order_parameters(coll)
    print(f"{name:15s}: milling M = {M.mean():.2f} ± {M.std():.2f},  polarisation P = {P.mean():.2f} ± {P.std():.2f}")
recording      : milling M = 0.88 ± 0.03,  polarisation P = 0.06 ± 0.02
inferred model : milling M = 0.88 ± 0.03,  polarisation P = 0.10 ± 0.03

Below: the order parameters in time, and the distributions of speed, nearest-neighbour distance and distance from the centre — the thickness and the hole of the torus.


Milling M (solid), polarisation P (dotted)
recording      : mean speed 0.933, nearest neighbour 1.02, distance from centre 3.87
inferred model : mean speed 0.934, nearest neighbour 1.02, distance from centre 3.86

The school simulated from the inferred rules mills as strongly as the recorded one — including the tightening of the mill over the first ten time units — and neither translates (low polarisation in both). Its speeds, spacing and torus profile match the recording: rules learned from individual accelerations reproduce the collective state they were never fitted to.

Thumbnail


Total running time of the script: (7 minutes 7.154 seconds)

🏷 Tags: synthetic, underdamped, multi-particle, linear, sparsity, large-scale, 3D

Gallery generated by Sphinx-Gallery