universal-physics-tensor 0.47.1 → 1.0.2

package/dist/cases/brownian-sphere.js

@@ -0,0 +1,353 @@
+/**
+ * Applied case: a Brownian sphere tracked in a fluid — the diffusion
+ * coefficient and mean-square displacement from the particle's radius and the
+ * fluid's viscosity and temperature, with the regime checks that make the
+ * Stokes–Einstein scalar applicable.
+ *
+ * The atlas bridge `ab-stokes-einstein` derives D = k_BT/(6πηa) from the
+ * Langevin model and Stokes drag, with Re ≤ 0.1 and m/(γt) ≤ 0.01. This case
+ * evaluates it for a named geometry (radius, or diameter through an exact
+ * alternate) and fluid, computes Re from the particle's own velocity scales,
+ * includes the displaced-fluid added mass in the momentum relaxation time, and
+ * evaluates the hydrodynamic memory (the Basset force) that the bridge does not
+ * check: the full MSD with fluid inertia, and the correction it makes at t.
+ * Given a distance to a plane wall, it applies the wall's drag corrections to D.
+ *
+ * `CE-stokes-einstein` is encoded only up to its 6π (scalar-up-to-constant);
+ * the 6π here comes from Stokes drag, not from that entry.
+ *
+ * @module cases/brownian-sphere
+ */
+import { K_B_SI } from '../core/constants.js';
+import { adaptiveSimpson } from './quadrature.js';
+import { check, requirePositive } from './types.js';
+const ID = 'case-brownian-sphere';
+/** Standard gravity (CGPM 1901), for the sedimentation speed. @internal */
+export const G_STANDARD = 9.80665;
+/** The thresholds `ab-stokes-einstein` states: Re ≤ 0.1 and τ_p/t ≤ 0.01. @internal */
+export const MAX_RE = 0.1;
+export const MAX_TAU_P_RATIO = 0.01;
+/** Ceiling on the memory term's own share of the MSD, |MSD_H/MSD_OU − 1|. @internal */
+export const MAX_MEMORY_CORRECTION = 0.01;
+/** (v_s t)²/(2Dt) ceiling along gravity when the vertical axis is tracked. @internal */
+export const MAX_DRIFT_RATIO = 0.01;
+/** Ceiling on |MSD/MSD_wall − 1|: the wall's correction to the tracked MSD is negligible. @internal */
+export const MAX_WALL_CORRECTION = 0.01;
+/** Ceiling on the last retained Faxén term (a/h)⁵/16 over the series' value. @internal */
+export const MAX_FAXEN_LAST_TERM = 0.01;
+/** Ceiling on √(2 D_⊥ t)/(h − a): the height, and so D_∥ and D_⊥, barely change over t. @internal */
+export const MAX_WALL_EXCURSION = 0.1;
+/** t − τ(1 − e^{−t/τ}) in units of τ, i.e. x − (1 − e^{−x}), without its cancellation at small x. @internal */
+export function ballisticDeficit(x) {
+    return x < 1e-3 ? x * x * (1 / 2 - x / 6 + (x * x) / 24 - (x * x * x) / 120) : x + Math.expm1(-x);
+}
+/**
+ * MSD/(2Dt) per axis for a sphere with fluid inertia: added mass and the Basset
+ * memory force, in an unbounded incompressible fluid, velocities in equilibrium.
+ *
+ * The velocity autocorrelation has the Laplace transform
+ * Ĉ(s) = k_BT/(M s + γ(1 + √(s τ_f))), M = m + m_f/2, from the frequency-dependent
+ * Stokes drag γ(1 + √(sτ_f)) + s m_f/2 (Stokes 1851; the Basset 1888 term is its
+ * √s part; Hinch 1975, J. Fluid Mech. 72, 499; Clercx & Schram 1992, Phys. Rev.
+ * A 46, 1942). Its poles in √s both have negative real part, so Ĉ has none on the
+ * principal sheet and C(t) is the branch-cut integral
+ * C(t) = (k_BT/πγ) ∫₀^∞ e^{−ut} √(τ_f u)/((1 − τ_p u)² + τ_f u) du, τ_p = M/γ.
+ * Then ⟨Δx²⟩ = 2∫₀ᵗ (t − s) C(s) ds, and with v = ut,
+ * MSD/(2Dt) = (1/π) ∫₀^∞ √(βv) (v − 1 + e^{−v}) / (v² ((1 − αv)² + βv)) dv, α = τ_p/t, β = τ_f/t,
+ * integrated here over ln v by adaptive Simpson, split at v = 1, 1/β and around
+ * the near-resonance at v = 1/α (width √(β/α) in ln v; β/α ≤ 9 for any densities).
+ *
+ * Limits: → 1 − 2√(τ_f/(πt)) + (τ_f − τ_p)/t for t ≫ τ_p, τ_f (expanding Ĉ in √s),
+ * whose second derivative is the VACF tail k_BT/(12 ρ_f (πνt)^{3/2}); → t/(2τ_p)
+ * for t ≪ τ_p, i.e. ⟨Δx²⟩ → (k_BT/M) t². Requires β > 0: without memory the
+ * poles reach the principal sheet and this integral no longer holds them.
+ * @internal
+ */
+export function hydrodynamicMsdRatio(alpha, beta) {
+    const f = (y) => {
+        const v = Math.exp(y);
+        const lag = 1 - alpha * v;
+        return (Math.sqrt(beta * v) * (ballisticDeficit(v) / v)) / (lag * lag + beta * v);
+    };
+    const peak = -Math.log(alpha);
+    const w = Math.min(1, Math.sqrt(beta / alpha));
+    const points = [0, -Math.log(beta), peak, ...[1, 2, 4].flatMap((k) => [peak - k * w, peak + k * w])].sort((x, y) => x - y);
+    // The integrand falls as v^{3/2} below and v^{−3/2} above the breakpoints: e^{−75} at ±50 in ln v.
+    const edges = [points[0] - 50, ...points, points[points.length - 1] + 50];
+    let sum = 0;
+    for (let k = 1; k < edges.length; k++)
+        if (edges[k] > edges[k - 1])
+            sum += adaptiveSimpson(f, edges[k - 1], edges[k], 1e-12);
+    return sum / Math.PI;
+}
+/**
+ * D_∥/D₀ for a sphere translating parallel to a plane wall, centre at h:
+ * 1 − (9/16)ξ + (1/8)ξ³ − (45/256)ξ⁴ − (1/16)ξ⁵, ξ = a/h (Faxén 1923, method of
+ * reflections, as quoted in Happel & Brenner 1965, Low Reynolds Number
+ * Hydrodynamics, ch. 7). A series in a/h, truncated:
+ * its error is not bounded here, and near contact it misses the logarithmic
+ * lubrication divergence of the drag.
+ * @internal
+ */
+export function faxenParallel(aOverH) {
+    const x = aOverH;
+    return 1 - (9 / 16) * x + (1 / 8) * x ** 3 - (45 / 256) * x ** 4 - (1 / 16) * x ** 5;
+}
+/**
+ * λ = F/(6πηaU) for a sphere approaching a plane wall head-on, centre at h > a,
+ * exact in Stokes flow (Brenner 1961, Chem. Eng. Sci. 16, 242, bispherical coordinates):
+ * λ = (4/3) sinh α Σₙ n(n+1)/((2n−1)(2n+3)) · [(2 sinh(2n+1)α + (2n+1) sinh 2α) /
+ * (4 sinh²(n+½)α − (2n+1)² sinh²α) − 1], cosh α = h/a. D_⊥ = D₀/λ.
+ *
+ * The bracket is rewritten over 4 sinh²(n+½)α so that no sinh overflows; its
+ * terms fall as e^{−(2n+1)α}, so near contact (α → 0) the sum needs ~40/α terms,
+ * and the low-n denominators lose ~α⁻² of relative precision to cancellation.
+ * Limits: λ → 1 + (9/8)(a/h) far away (Lorentz 1907); λ → a/δ + (1/5) ln(a/δ) +
+ * 0.971 as the gap δ = h − a → 0 (Cox & Brenner 1967, Chem. Eng. Sci. 22, 1753).
+ * @throws Error if h/a ≤ 1.
+ * @internal
+ */
+export function brennerPerpendicular(hOverA) {
+    if (!(hOverA > 1))
+        throw new Error(`brennerPerpendicular: need h/a > 1 (got ${hOverA})`);
+    const al = Math.acosh(hOverA);
+    const s = Math.sinh(al);
+    const s2a = Math.sinh(2 * al);
+    let sum = 0;
+    for (let n = 1;; n++) {
+        const x = (n + 0.5) * al;
+        const k = 2 * n + 1;
+        const inv4Sinh2 = Math.exp(-2 * x) / Math.expm1(-2 * x) ** 2;
+        const cothMinus1 = 2 / Math.expm1(2 * x);
+        const bracket = (cothMinus1 + k * s2a * inv4Sinh2 + k * k * s * s * inv4Sinh2) / (1 - k * k * s * s * inv4Sinh2);
+        const term = ((n * (n + 1)) / ((2 * n - 1) * (2 * n + 3))) * bracket;
+        sum += term;
+        if (term < 1e-17 * sum)
+            break;
+        if (n > 1e7)
+            throw new Error(`brennerPerpendicular: no convergence at h/a = ${hOverA}`);
+    }
+    return (4 / 3) * s * sum;
+}
+export const BROWNIAN_SPHERE_CASE = {
+    id: ID,
+    title: 'Brownian sphere in a fluid (particle geometry, fluid conditions)',
+    parameters: [
+        { key: 'T_K', quantity: 'temperature', symbol: 'T', unit: 'K', meaning: 'absolute temperature of the fluid, > 0 K', temperature: 'absolute' },
+        { key: 'eta_Pa_s', quantity: 'dynamic viscosity', symbol: 'η', unit: 'Pa*s', meaning: 'viscosity of the fluid at T (water at 20 °C ≈ 1.0e-3 Pa·s), > 0' },
+        {
+            key: 'a_m',
+            quantity: 'particle radius',
+            symbol: 'a',
+            unit: 'm',
+            meaning: 'hydrodynamic radius of the sphere, > 0',
+            geometry: 'radius',
+            alternates: [{ key: 'diameter_m', meaning: 'the diameter 2a of the sphere', toKey: 0.5 }],
+        },
+        { key: 'rho_p_kg_per_m3', quantity: 'particle density', symbol: 'ρ_p', unit: 'kg/m^3', meaning: 'mass density of the sphere (silica ≈ 2000), > 0' },
+        { key: 'rho_f_kg_per_m3', quantity: 'fluid density', symbol: 'ρ_f', unit: 'kg/m^3', meaning: 'mass density of the fluid (water ≈ 998), > 0' },
+        { key: 't_s', quantity: 'lag time', symbol: 't', unit: 's', meaning: 'the time over which the displacement is measured, > 0' },
+        { key: 'd', quantity: 'tracked dimensions', symbol: 'd', unit: '', meaning: 'number of Cartesian axes tracked: 1, 2 (a microscope image plane, horizontal) or 3' },
+        {
+            key: 'h_m',
+            quantity: 'distance to a wall',
+            symbol: 'h',
+            unit: 'm',
+            meaning: "distance from the sphere's centre to one plane horizontal wall (a coverslip), > a; leave out when no wall is within many radii",
+            geometry: 'separation',
+            optional: true,
+        },
+    ],
+    governing: {
+        parent: [
+            'm dv/dt = −γ v + ξ(t),  ⟨ξ_i(t) ξ_j(t′)⟩ = 2γ k_BT δ_ij δ(t − t′)   (Langevin, a 3-vector equation; model-langevin)',
+            'η ∇²u = ∇p,  ∇·u = 0,  u = v on the sphere (no slip), u → 0 far away   (Stokes creeping flow, a field; model-stokes-drag) ⇒ γ = 6πηa',
+            'm dv/dt = −γ v − (m_f/2) dv/dt − 6a²√(πηρ_f) ∫_{−∞}^t v′(s)/√(t − s) ds + ξ(t), ξ coloured by the same kernel   ' +
+                '(unsteady Stokes flow: added mass and the Basset memory force; Hinch 1975)',
+        ],
+        scalar: [
+            'D = k_BT/(6πηa)   (Stokes–Einstein; ab-stokes-einstein)',
+            '⟨|Δr|²⟩ = 2 d D t  over the d tracked axes',
+        ],
+        distinction: 'The parents are a vector stochastic equation for the velocity and a field equation for the flow around the sphere; ' +
+            'the scalar keeps one isotropic number D and a mean-square displacement linear in t. Dropped: the velocity as a ' +
+            'state (the ballistic regime t ≲ τ_p), the flow field (and with it the hydrodynamic memory for t ≲ τ_f), the shape ' +
+            'beyond the radius, and every anisotropy.',
+    },
+    observable: 'MSD_m2',
+    outputs: [
+        { key: 'gamma_kg_per_s', symbol: 'γ', unit: 'kg/s', meaning: 'Stokes drag coefficient 6πηa' },
+        { key: 'D_m2_per_s', symbol: 'D', unit: 'm^2/s', meaning: 'diffusion coefficient k_BT/(6πηa)' },
+        { key: 'MSD_m2', symbol: '⟨|Δr|²⟩', unit: 'm^2', meaning: 'mean-square displacement 2dDt over the tracked axes' },
+        { key: 'rms_displacement_m', symbol: '√⟨|Δr|²⟩', unit: 'm', meaning: 'root-mean-square displacement over the tracked axes' },
+        { key: 'm_kg', symbol: 'm', unit: 'kg', meaning: 'particle mass (4/3)πa³ρ_p' },
+        { key: 'tau_p_s', symbol: 'τ_p', unit: 's', meaning: 'momentum relaxation time (m + m_f/2)/γ, with the displaced-fluid added mass m_f/2' },
+        { key: 'tau_f_s', symbol: 'τ_f', unit: 's', meaning: 'vorticity diffusion time ρ_f a²/η over one radius (hydrodynamic memory)' },
+        { key: 'v_sed_m_per_s', symbol: 'v_s', unit: 'm/s', meaning: 'Stokes sedimentation speed (2/9)(ρ_p − ρ_f) g a²/η; negative means the sphere rises' },
+        { key: 'Re', symbol: 'Re', unit: '', meaning: 'ρ_f a max(√(k_BT/m), |v_s|)/η — radius-based; a diameter-based Re is twice this' },
+        { key: 'MSD_langevin_m2', symbol: '⟨|Δr|²⟩_L', unit: 'm^2', meaning: 'the Langevin parent: 2dD[t − τ(1 − e^{−t/τ})], τ = m/γ (bare mass)' },
+        { key: 'langevin_deviation', symbol: 'MSD/MSD_L − 1', unit: '', meaning: 'relative excess of the diffusive MSD over the Langevin one' },
+        {
+            key: 'MSD_hydro_m2',
+            symbol: '⟨|Δr|²⟩_H',
+            unit: 'm^2',
+            meaning: 'the Langevin–Basset parent: added mass and hydrodynamic memory, unbounded incompressible fluid (branch-cut integral of its Laplace-domain VACF)',
+        },
+        { key: 'hydro_correction_m2', symbol: '⟨|Δr|²⟩_H − ⟨|Δr|²⟩', unit: 'm^2', meaning: 'what inertia and memory change in the MSD at t; ≈ −4dD√(τ_f t/π) at t ≫ τ_f' },
+        { key: 'hydro_deviation', symbol: 'MSD/MSD_H − 1', unit: '', meaning: 'relative excess of the diffusive MSD over the Langevin–Basset one' },
+        {
+            key: 'memory_correction',
+            symbol: 'MSD_H/MSD_OU − 1',
+            unit: '',
+            meaning: "the memory force's own share: MSD_H against the Ornstein–Uhlenbeck MSD with the same τ_p (added mass, no memory)",
+        },
+        { key: 'D_parallel_m2_per_s', symbol: 'D_∥', unit: 'm^2/s', meaning: 'D beside the wall, parallel to it: D·(Faxén series in a/h); null without h_m' },
+        { key: 'D_perp_m2_per_s', symbol: 'D_⊥', unit: 'm^2/s', meaning: 'D normal to the wall: D/λ, λ from Brenner\'s exact series; null without h_m' },
+        { key: 'MSD_wall_m2', symbol: '⟨|Δr|²⟩_w', unit: 'm^2', meaning: '2t(d_∥ D_∥ + d_⊥ D_⊥): the tracked horizontal axes parallel to the wall, a third one normal to it; null without h_m' },
+        { key: 'wall_deviation', symbol: 'MSD/MSD_w − 1', unit: '', meaning: 'relative excess of the unbounded-fluid MSD over the wall-corrected one; null without h_m' },
+    ],
+    comparison: {
+        reference: 'the parent Langevin model (bare mass, white noise; it has neither added mass nor hydrodynamic memory)',
+        valueKey: 'MSD_m2',
+        referenceKey: 'MSD_langevin_m2',
+        deviationKey: 'langevin_deviation',
+        method: 'closed form of the Ornstein–Uhlenbeck MSD, velocities starting in equilibrium',
+    },
+    conditions: [
+        'a rigid sphere released at r = 0; its displacement density starts as δ(r) and spreads as a Gaussian of variance 2Dt per axis',
+        'no-slip boundary on the sphere; the fluid is at rest far from it (no imposed flow; no wall within many radii, or with h_m one plane no-slip wall)',
+        'fluid in thermal equilibrium at T; one isolated particle (dilute: no hydrodynamic interaction with others)',
+    ],
+    notIncluded: [
+        'walls other than one plane: a second wall, a channel or a curved surface; and, with h_m, the spread of heights the sphere samples (D_∥, D_⊥ are taken at h)',
+        'localization error and camera motion blur of the tracking, which offset and bias the measured MSD',
+        'fluid compressibility: the incompressible memory kernel gives ⟨v²⟩ = k_BT/(m + m_f/2) at t = 0; sound restores k_BT/m over a/c_s (Zwanzig & Bixon 1970)',
+        'the memory force near a wall: MSD_hydro is the unbounded-fluid result, and a wall within √(νt) changes the memory tail',
+        'the rotational diffusion of the sphere, and any non-spherical shape',
+    ],
+    measurement: [
+        'single-particle tracking: fit ⟨|Δr|²⟩(t) over the d tracked axes, slope 2dD; compare D and MSD_m2 at the chosen lag ' +
+            '(with N independent displacements the relative scatter of the MSD is ≈ √(2/(dN)))',
+        'subtract the static localization offset 2dσ_loc² (measured on an immobilized particle) before comparing',
+        'dynamic light scattering: the field autocorrelation decays at Γ = D q², an independent route to the same D',
+    ],
+    links: [
+        { id: 'ab-stokes-einstein', role: 'the derivation D = k_BT/(6πηa) with its regime Re ≤ 0.1, m/(γt) ≤ 0.01 (`upt atlas ab-stokes-einstein`)' },
+        { id: 'ab-langevin-diffusion', role: 'the overdamped coarse-graining D = k_BT/γ and its ballistic counterexample' },
+        { id: 'model-stokes-drag', role: 'the creeping-flow drag γ = 6πηa' },
+        { id: 'CE-stokes-einstein', role: 'encoded only up to its dimensionless 6π (scalar-up-to-constant); the 6π here is from Stokes drag' },
+    ],
+    examples: {
+        valid: {
+            args: ['T_K=293.15', 'eta_Pa_s=1e-3', 'a_m=1um', 'rho_p_kg_per_m3=2000', 'rho_f_kg_per_m3=998', 't_s=1', 'd=2', 'h_m=100um'],
+            note: 'a 1 µm-radius silica sphere in water at 20 °C, 100 µm above the coverslip, tracked in the image plane over 1 s',
+            fails: [],
+        },
+        failures: [
+            {
+                args: ['T_K=293.15', 'eta_Pa_s=1e-3', 'a_m=1um', 'rho_p_kg_per_m3=2000', 'rho_f_kg_per_m3=998', 't_s=1us', 'd=2'],
+                note: 'the same sphere over 1 µs: still ballistic (t ≈ 2τ_p) and inside the hydrodynamic memory time',
+                fails: ['overdamped', 'memory'],
+            },
+            {
+                args: ['T_K=293.15', 'eta_Pa_s=1e-3', 'a_m=50um', 'rho_p_kg_per_m3=7800', 'rho_f_kg_per_m3=998', 't_s=100', 'd=3'],
+                note: 'a 50 µm-radius steel sphere tracked in 3-D: it sinks at ≈ 3.7 cm/s, Re ≈ 1.9, and the drift swamps diffusion',
+                fails: ['creeping-flow', 'drift'],
+            },
+            {
+                args: ['T_K=293.15', 'eta_Pa_s=1e-3', 'a_m=1um', 'rho_p_kg_per_m3=1050', 'rho_f_kg_per_m3=998', 't_s=50ms', 'd=2', 'h_m=3um'],
+                note: 'a 1 µm-radius polystyrene sphere 3 µm (centre) above the coverslip: the wall slows D_∥ by ≈ 19%',
+                fails: ['wall'],
+            },
+            {
+                args: ['T_K=293.15', 'eta_Pa_s=1e-3', 'a_m=1um', 'rho_p_kg_per_m3=1050', 'rho_f_kg_per_m3=998', 't_s=50ms', 'd=2', 'h_m=1.2um'],
+                note: 'the same sphere with a 0.2 µm gap: past the range of the Faxén series, and its height changes by more than the gap allows over t',
+                fails: ['faxen-range', 'wall', 'wall-static'],
+            },
+        ],
+    },
+    /** Evaluate the Stokes-Einstein MSD and regime checks for the supplied Brownian-sphere inputs. */
+    regimeAt(inputs, outputs) {
+        const re = outputs.Re;
+        const m = outputs.m_kg;
+        const gamma = outputs.gamma_kg_per_s;
+        const t = inputs.t_s;
+        if (re == null || m == null || gamma == null || t == null)
+            return '';
+        return `upt regime diffusion --at Re=${re} m=${m} gamma=${gamma} t=${t}`;
+    },
+    run(i) {
+        requirePositive(ID, i, ['T_K', 'eta_Pa_s', 'a_m', 'rho_p_kg_per_m3', 'rho_f_kg_per_m3', 't_s']);
+        const { T_K: T, eta_Pa_s: eta, a_m: a, rho_p_kg_per_m3: rhoP, rho_f_kg_per_m3: rhoF, t_s: t, d } = i;
+        if (d !== 1 && d !== 2 && d !== 3)
+            throw new Error(`${ID}: d must be 1, 2 or 3 (got ${d})`);
+        const kT = K_B_SI * T;
+        const gamma = 6 * Math.PI * eta * a;
+        const D = kT / gamma;
+        const msd = 2 * d * D * t;
+        const volume = (4 / 3) * Math.PI * a ** 3;
+        const m = volume * rhoP;
+        const tauP = (m + 0.5 * volume * rhoF) / gamma;
+        const tauF = (rhoF * a * a) / eta;
+        const vSed = ((2 / 9) * (rhoP - rhoF) * G_STANDARD * a * a) / eta;
+        const re = (rhoF * a * Math.max(Math.sqrt(kT / m), Math.abs(vSed))) / eta;
+        const tauBare = m / gamma;
+        const msdLangevin = 2 * d * D * tauBare * ballisticDeficit(t / tauBare);
+        const msdHydro = msd * hydrodynamicMsdRatio(tauP / t, tauF / t);
+        const msdAddedMass = 2 * d * D * tauP * ballisticDeficit(t / tauP);
+        const memory = msdHydro / msdAddedMass - 1;
+        const checks = [
+            check('creeping-flow', 'creeping flow around the sphere, Re ≪ 1', 'ρ_f a max(√(k_BT/m), |v_s|)/η', re, '<=', MAX_RE, "the threshold ab-stokes-einstein states: a chosen machine form of Re ≪ 1"),
+            check('overdamped', 'overdamped times t ≫ τ_p', '(m + m_f/2)/(γ t)', tauP / t, '<=', MAX_TAU_P_RATIO, "ab-stokes-einstein's m/(γt) ≤ 0.01, with the added mass m_f/2 included (stricter)"),
+            check('memory', 'past the hydrodynamic memory, t ≫ τ_f = ρ_f a²/η', '|MSD_H/MSD_OU − 1|', Math.abs(memory), '<=', MAX_MEMORY_CORRECTION, 'chosen threshold: the Basset memory changes the MSD by ≤ 1% at t (computed, not estimated; ≈ 2√(τ_f/(πt)) at t ≫ τ_f)'),
+        ];
+        const unchecked = ['the particle is a rigid sphere and a is its hydrodynamic radius (a coating or a shell changes it)'];
+        let wall = null;
+        if (i.h_m !== undefined) {
+            const h = i.h_m;
+            if (!Number.isFinite(h) || !(h > a))
+                throw new Error(`${ID}: h_m must be a finite distance > a_m, centre to wall (got ${h})`);
+            const faxen = faxenParallel(a / h);
+            const lambda = brennerPerpendicular(h / a);
+            const dPar = D * faxen;
+            const dPerp = D / lambda;
+            const msdWall = 2 * t * (Math.min(d, 2) * dPar + (d === 3 ? dPerp : 0));
+            wall = { dPar, dPerp, msdWall };
+            const excursion = Math.sqrt(2 * dPerp * t) + (Math.abs(vSed) * t) / lambda;
+            checks.push(check('faxen-range', 'the Faxén series in a/h holds for D_∥', '(a/h)⁵/16 ÷ (D_∥/D)', (a / h) ** 5 / 16 / faxen, '<=', MAX_FAXEN_LAST_TERM, 'chosen threshold: the last retained term is ≤ 1% of the series — a size estimate of the truncation, not a bound; D_⊥ (Brenner) is exact at any h > a'), check('wall', 'the wall correction to the tracked MSD is negligible', '|MSD/MSD_w − 1|', Math.abs(msd / msdWall - 1), '<=', MAX_WALL_CORRECTION, 'chosen threshold: the unbounded-fluid D is then within 1% for the tracked axes; otherwise read MSD_wall_m2'), check('wall-static', 'the height barely changes over t', '(√(2 D_⊥ t) + |v_s| t/λ)/(h − a)', excursion / (h - a), '<=', MAX_WALL_EXCURSION, 'chosen threshold: diffusion plus wall-slowed sedimentation normal to the wall move the sphere by ≤ 10% of the gap, so D_∥, D_⊥ taken at h hold over t'));
+            unchecked.push('the wall is plane, rigid, no-slip and horizontal, and the gap h − a is many molecular sizes and roughness heights (no surface forces, no lubrication-scale slip)');
+        }
+        if (d === 3) {
+            checks.push(check('drift', 'sedimentation drift negligible along gravity over t', '(v_s t)²/(2 D t)', (vSed * t) ** 2 / (2 * D * t), '<=', MAX_DRIFT_RATIO, 'chosen threshold: the vertical MSD then carries ≤ 1% from the deterministic drift'));
+        }
+        else {
+            unchecked.push(`the ${d === 1 ? 'tracked axis is' : 'tracked axes are'} horizontal, so sedimentation (${Number(Math.abs(vSed * t).toPrecision(3))} m over t) moves the sphere out of the plane but not along ${d === 1 ? 'it' : 'them'}`);
+        }
+        return {
+            outputs: {
+                gamma_kg_per_s: gamma,
+                D_m2_per_s: D,
+                MSD_m2: msd,
+                rms_displacement_m: Math.sqrt(msd),
+                m_kg: m,
+                tau_p_s: tauP,
+                tau_f_s: tauF,
+                v_sed_m_per_s: vSed,
+                Re: re,
+                MSD_langevin_m2: msdLangevin,
+                langevin_deviation: msd / msdLangevin - 1,
+                MSD_hydro_m2: msdHydro,
+                hydro_correction_m2: msdHydro - msd,
+                hydro_deviation: msd / msdHydro - 1,
+                memory_correction: memory,
+                D_parallel_m2_per_s: wall?.dPar ?? null,
+                D_perp_m2_per_s: wall?.dPerp ?? null,
+                MSD_wall_m2: wall?.msdWall ?? null,
+                wall_deviation: wall === null ? null : msd / wall.msdWall - 1,
+            },
+            checks,
+            unchecked,
+        };
+    },
+};
+//# sourceMappingURL=brownian-sphere.js.map

package/dist/cases/brownian-sphere.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brownian-sphere.js","sourceRoot":"","sources":["../../src/cases/brownian-sphere.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,eAAe,EAAoB,MAAM,YAAY,CAAC;AAEtE,MAAM,EAAE,GAAG,sBAAsB,CAAC;AAElC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAC;AAElC,uFAAuF;AACvF,MAAM,CAAC,MAAM,MAAM,GAAG,GAAG,CAAC;AAC1B,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC,uFAAuF;AACvF,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAE1C,wFAAwF;AACxF,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC,uGAAuG;AACvG,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAExC,0FAA0F;AAC1F,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAExC,qGAAqG;AACrG,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAEtC,+GAA+G;AAC/G,MAAM,UAAU,gBAAgB,CAAC,CAAS;IACxC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACpG,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa,EAAE,IAAY;IAC9D,MAAM,CAAC,GAAG,CAAC,CAAS,EAAE,EAAE;QACtB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,GAAG,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;QAC1B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;IACpF,CAAC,CAAC;IACF,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC9B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3H,mGAAmG;IACnG,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,CAAC,CAAE,GAAG,EAAE,EAAE,GAAG,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,GAAG,EAAE,CAAC,CAAC;IAC5E,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,KAAK,CAAC,CAAC,CAAE,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAE;YAAE,GAAG,IAAI,eAAe,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAE,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,KAAK,CAAC,CAAC;IACjI,OAAO,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC;AACvB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,MAAM,CAAC,GAAG,MAAM,CAAC;IACjB,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACvF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,MAAM,GAAG,CAAC,CAAC;IACzF,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACxB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9B,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,GAAI,CAAC,EAAE,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QAC7D,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,CAAC,UAAU,GAAG,CAAC,GAAG,GAAG,GAAG,SAAS,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC;QACjH,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;QACrE,GAAG,IAAI,IAAI,CAAC;QACZ,IAAI,IAAI,GAAG,KAAK,GAAG,GAAG;YAAE,MAAM;QAC9B,IAAI,CAAC,GAAG,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,MAAM,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;AAC3B,CAAC;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,EAAE,EAAE,EAAE;IACN,KAAK,EAAE,kEAAkE;IACzE,UAAU,EAAE;QACV,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,0CAA0C,EAAE,WAAW,EAAE,UAAU,EAAE;QAC7I,EAAE,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iEAAiE,EAAE;QACzJ;YACE,GAAG,EAAE,KAAK;YACV,QAAQ,EAAE,iBAAiB;YAC3B,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,GAAG;YACT,OAAO,EAAE,wCAAwC;YACjD,QAAQ,EAAE,QAAQ;YAClB,UAAU,EAAE,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,+BAA+B,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;SAC1F;QACD,EAAE,GAAG,EAAE,iBAAiB,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,iDAAiD,EAAE;QACnJ,EAAE,GAAG,EAAE,iBAAiB,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,8CAA8C,EAAE;QAC7I,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,uDAAuD,EAAE;QAC9H,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,oFAAoF,EAAE;QAClK;YACE,GAAG,EAAE,KAAK;YACV,QAAQ,EAAE,oBAAoB;YAC9B,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,GAAG;YACT,OAAO,EAAE,gIAAgI;YACzI,QAAQ,EAAE,YAAY;YACtB,QAAQ,EAAE,IAAI;SACf;KACF;IACD,SAAS,EAAE;QACT,MAAM,EAAE;YACN,qHAAqH;YACrH,sIAAsI;YACtI,kHAAkH;gBAChH,4EAA4E;SAC/E;QACD,MAAM,EAAE;YACN,yDAAyD;YACzD,4CAA4C;SAC7C;QACD,WAAW,EACT,qHAAqH;YACrH,iHAAiH;YACjH,oHAAoH;YACpH,0CAA0C;KAC7C;IACD,UAAU,EAAE,QAAQ;IACpB,OAAO,EAAE;QACP,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,8BAA8B,EAAE;QAC7F,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,mCAAmC,EAAE;QAC/F,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,qDAAqD,EAAE;QACjH,EAAE,GAAG,EAAE,oBAAoB,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,qDAAqD,EAAE;QAC5H,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,2BAA2B,EAAE;QAC9E,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,mFAAmF,EAAE;QAC1I,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,yEAAyE,EAAE;QAChI,EAAE,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,qFAAqF,EAAE;QACpJ,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,iFAAiF,EAAE;QACjI,EAAE,GAAG,EAAE,iBAAiB,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,oEAAoE,EAAE;QAC3I,EAAE,GAAG,EAAE,oBAAoB,EAAE,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,4DAA4D,EAAE;QACvI;YACE,GAAG,EAAE,cAAc;YACnB,MAAM,EAAE,WAAW;YACnB,IAAI,EAAE,KAAK;YACX,OAAO,EAAE,iJAAiJ;SAC3J;QACD,EAAE,GAAG,EAAE,qBAAqB,EAAE,MAAM,EAAE,qBAAqB,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,6EAA6E,EAAE;QAClK,EAAE,GAAG,EAAE,iBAAiB,EAAE,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,mEAAmE,EAAE;QAC3I;YACE,GAAG,EAAE,mBAAmB;YACxB,MAAM,EAAE,kBAAkB;YAC1B,IAAI,EAAE,EAAE;YACR,OAAO,EAAE,kHAAkH;SAC5H;QACD,EAAE,GAAG,EAAE,qBAAqB,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,8EAA8E,EAAE;QACrJ,EAAE,GAAG,EAAE,iBAAiB,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,6EAA6E,EAAE;QAChJ,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,qHAAqH,EAAE;QACxL,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,0FAA0F,EAAE;KAClK;IACD,UAAU,EAAE;QACV,SAAS,EAAE,uGAAuG;QAClH,QAAQ,EAAE,QAAQ;QAClB,YAAY,EAAE,iBAAiB;QAC/B,YAAY,EAAE,oBAAoB;QAClC,MAAM,EAAE,+EAA+E;KACxF;IACD,UAAU,EAAE;QACV,8HAA8H;QAC9H,mJAAmJ;QACnJ,4GAA4G;KAC7G;IACD,WAAW,EAAE;QACX,6JAA6J;QAC7J,mGAAmG;QACnG,yJAAyJ;QACzJ,wHAAwH;QACxH,qEAAqE;KACtE;IACD,WAAW,EAAE;QACX,sHAAsH;YACpH,mFAAmF;QACrF,yGAAyG;QACzG,4GAA4G;KAC7G;IACD,KAAK,EAAE;QACL,EAAE,EAAE,EAAE,oBAAoB,EAAE,IAAI,EAAE,yGAAyG,EAAE;QAC7I,EAAE,EAAE,EAAE,uBAAuB,EAAE,IAAI,EAAE,4EAA4E,EAAE;QACnH,EAAE,EAAE,EAAE,mBAAmB,EAAE,IAAI,EAAE,iCAAiC,EAAE;QACpE,EAAE,EAAE,EAAE,oBAAoB,EAAE,IAAI,EAAE,kGAAkG,EAAE;KACvI;IACD,QAAQ,EAAE;QACR,KAAK,EAAE;YACL,IAAI,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC;YAC5H,IAAI,EAAE,gHAAgH;YACtH,KAAK,EAAE,EAAE;SACV;QACD,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,SAAS,EAAE,KAAK,CAAC;gBACjH,IAAI,EAAE,+FAA+F;gBACrG,KAAK,EAAE,CAAC,YAAY,EAAE,QAAQ,CAAC;aAChC;YACD;gBACE,IAAI,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,SAAS,EAAE,KAAK,CAAC;gBAClH,IAAI,EAAE,8GAA8G;gBACpH,KAAK,EAAE,CAAC,eAAe,EAAE,OAAO,CAAC;aAClC;YACD;gBACE,IAAI,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,CAAC;gBAC7H,IAAI,EAAE,iGAAiG;gBACvG,KAAK,EAAE,CAAC,MAAM,CAAC;aAChB;YACD;gBACE,IAAI,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,CAAC;gBAC/H,IAAI,EAAE,kIAAkI;gBACxI,KAAK,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,CAAC;aAC9C;SACF;KACF;IACD,kGAAkG;IAClG,QAAQ,CAAC,MAAM,EAAE,OAAO;QACtB,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;QACvB,MAAM,KAAK,GAAG,OAAO,CAAC,cAAc,CAAC;QACrC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC;QACrB,IAAI,EAAE,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI;YAAE,OAAO,EAAE,CAAC;QACrE,OAAO,gCAAgC,EAAE,MAAM,CAAC,UAAU,KAAK,MAAM,CAAC,EAAE,CAAC;IAC3E,CAAC;IACD,GAAG,CAAC,CAAC;QACH,eAAe,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,KAAK,CAAC,CAAC,CAAC;QAChG,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,eAAe,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAA2B,CAAC;QAC/H,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,EAAE,8BAA8B,CAAC,GAAG,CAAC,CAAC;QAC5F,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC;QACtB,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC,CAAC;QACpC,MAAM,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;QACrB,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1B,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1C,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;QACxB,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,GAAG,GAAG,MAAM,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC;QAC/C,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;QAClC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,UAAU,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;QAClE,MAAM,EAAE,GAAG,CAAC,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;QAC1E,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC;QAC1B,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,GAAG,gBAAgB,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC;QACxE,MAAM,QAAQ,GAAG,GAAG,GAAG,oBAAoB,CAAC,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC;QAChE,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,gBAAgB,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QACnE,MAAM,MAAM,GAAG,QAAQ,GAAG,YAAY,GAAG,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG;YACb,KAAK,CAAC,eAAe,EAAE,yCAAyC,EAAE,+BAA+B,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EACjH,0EAA0E,CAAC;YAC7E,KAAK,CAAC,YAAY,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,eAAe,EAClG,mFAAmF,CAAC;YACtF,KAAK,CAAC,QAAQ,EAAE,kDAAkD,EAAE,oBAAoB,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,qBAAqB,EACrI,uHAAuH,CAAC;SAC3H,CAAC;QACF,MAAM,SAAS,GAAG,CAAC,mGAAmG,CAAC,CAAC;QACxH,IAAI,IAAI,GAA4D,IAAI,CAAC;QACzE,IAAI,CAAC,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,GAAG,EAAE,8DAA8D,CAAC,GAAG,CAAC,CAAC;YAC9H,MAAM,KAAK,GAAG,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACnC,MAAM,MAAM,GAAG,oBAAoB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC3C,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC;YACvB,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC;YACzB,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACxE,IAAI,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YAChC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC;YAC3E,MAAM,CAAC,IAAI,CACT,KAAK,CAAC,aAAa,EAAE,uCAAuC,EAAE,qBAAqB,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,mBAAmB,EACvI,sJAAsJ,CAAC,EACzJ,KAAK,CAAC,MAAM,EAAE,sDAAsD,EAAE,iBAAiB,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,OAAO,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAC7I,4GAA4G,CAAC,EAC/G,KAAK,CAAC,aAAa,EAAE,kCAAkC,EAAE,kCAAkC,EAAE,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,kBAAkB,EACxI,uJAAuJ,CAAC,CAC3J,CAAC;YACF,SAAS,CAAC,IAAI,CACZ,kKAAkK,CACnK,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACZ,MAAM,CAAC,IAAI,CACT,KAAK,CAAC,OAAO,EAAE,qDAAqD,EAAE,kBAAkB,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAC3H,eAAe,EAAE,mFAAmF,CAAC,CACxG,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,SAAS,CAAC,IAAI,CACZ,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,kBAAkB,kCAAkC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,8DAA8D,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAC1N,CAAC;QACJ,CAAC;QACD,OAAO;YACL,OAAO,EAAE;gBACP,cAAc,EAAE,KAAK;gBACrB,UAAU,EAAE,CAAC;gBACb,MAAM,EAAE,GAAG;gBACX,kBAAkB,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;gBAClC,IAAI,EAAE,CAAC;gBACP,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,IAAI;gBACb,aAAa,EAAE,IAAI;gBACnB,EAAE,EAAE,EAAE;gBACN,eAAe,EAAE,WAAW;gBAC5B,kBAAkB,EAAE,GAAG,GAAG,WAAW,GAAG,CAAC;gBACzC,YAAY,EAAE,QAAQ;gBACtB,mBAAmB,EAAE,QAAQ,GAAG,GAAG;gBACnC,eAAe,EAAE,GAAG,GAAG,QAAQ,GAAG,CAAC;gBACnC,iBAAiB,EAAE,MAAM;gBACzB,mBAAmB,EAAE,IAAI,EAAE,IAAI,IAAI,IAAI;gBACvC,eAAe,EAAE,IAAI,EAAE,KAAK,IAAI,IAAI;gBACpC,WAAW,EAAE,IAAI,EAAE,OAAO,IAAI,IAAI;gBAClC,cAAc,EAAE,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,CAAC;aAC9D;YACD,MAAM;YACN,SAAS;SACV,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/cases/damped-resonator.d.ts

@@ -0,0 +1,23 @@
+import { type AppliedCase } from './types.js';
+/** Q floor for the single-Lorentzian (near-resonance) form of the spectrum. @internal */
+export declare const MIN_Q_LORENTZIAN = 10;
+/** (1/t_obs)/linewidth ceiling: the record resolves the line. @internal */
+export declare const MAX_RESOLUTION_RATIO = 0.1;
+/**
+ * √(k_BT/k)/A ceiling. Thermal motion of one mode is x = X cos ω_d t + Y sin ω_d t
+ * with ⟨X²⟩ = ⟨Y²⟩ = k_BT/k (equipartition), so the envelope of the ring-down
+ * plus it is Rician with ⟨A_obs²⟩ = A² + 2k_BT/k (Rice 1944); at the ceiling
+ * √(1 + 2·0.01) − 1 ≈ 0.0100.
+ * @internal
+ */
+export declare const MAX_THERMAL_RATIO = 0.1;
+/**
+ * FWHM in Hz of |∫₀ᵀ e^{−(α + iΔω)t} dt|², the near-resonance power spectrum of
+ * a ring-down x0 e^{−αt} cos(ω_d t) recorded for T. The negative-frequency
+ * pole is dropped, which is the Q ≫ 1 approximation. The peak is at Δω = 0:
+ * the integrand is positive, so |X(Δω)| ≤ X(0).
+ * @internal
+ */
+export declare function windowedLinewidthHz(alpha: number, T: number): number;
+export declare const DAMPED_RESONATOR_CASE: AppliedCase;
+//# sourceMappingURL=damped-resonator.d.ts.map

package/dist/cases/damped-resonator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"damped-resonator.d.ts","sourceRoot":"","sources":["../../src/cases/damped-resonator.ts"],"names":[],"mappings":"AAiBA,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAItE,yFAAyF;AACzF,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAoBpE;AAED,eAAO,MAAM,qBAAqB,EAAE,WAqKnC,CAAC"}

package/dist/cases/damped-resonator.js

@@ -0,0 +1,224 @@
+/**
+ * Applied case: the free ring-down of a damped resonator, read out over a
+ * finite record — the envelope and displacement at a chosen time, the
+ * linewidth, and what a record of length t_obs can resolve of it.
+ *
+ * The atlas holds the damped spring (`model-damped-spring`), its exact RLC
+ * equivalent (`ab-damped-rlc`) and its overdamped reduction
+ * (`ab-damped-massless`). This case evaluates the underdamped solution for a
+ * given f0 and Q, refuses it when the resonator is not underdamped, and checks
+ * the record length against the linewidth it is meant to resolve. The
+ * rectangular-window spectrum of the truncated ring-down is computed in
+ * closed form, near resonance, for comparison. Given the temperature and the
+ * mode's stiffness, it checks the envelope against the thermal motion.
+ *
+ * @module cases/damped-resonator
+ */
+import { K_B_SI } from '../core/constants.js';
+import { check, requirePositive } from './types.js';
+const ID = 'case-damped-resonator';
+/** Q floor for the single-Lorentzian (near-resonance) form of the spectrum. @internal */
+export const MIN_Q_LORENTZIAN = 10;
+/** (1/t_obs)/linewidth ceiling: the record resolves the line. @internal */
+export const MAX_RESOLUTION_RATIO = 0.1;
+/**
+ * √(k_BT/k)/A ceiling. Thermal motion of one mode is x = X cos ω_d t + Y sin ω_d t
+ * with ⟨X²⟩ = ⟨Y²⟩ = k_BT/k (equipartition), so the envelope of the ring-down
+ * plus it is Rician with ⟨A_obs²⟩ = A² + 2k_BT/k (Rice 1944); at the ceiling
+ * √(1 + 2·0.01) − 1 ≈ 0.0100.
+ * @internal
+ */
+export const MAX_THERMAL_RATIO = 0.1;
+/**
+ * FWHM in Hz of |∫₀ᵀ e^{−(α + iΔω)t} dt|², the near-resonance power spectrum of
+ * a ring-down x0 e^{−αt} cos(ω_d t) recorded for T. The negative-frequency
+ * pole is dropped, which is the Q ≫ 1 approximation. The peak is at Δω = 0:
+ * the integrand is positive, so |X(Δω)| ≤ X(0).
+ * @internal
+ */
+export function windowedLinewidthHz(alpha, T) {
+    const oneMinusE = -Math.expm1(-alpha * T);
+    const E = 1 - oneMinusE;
+    // (1 − E)² + 4E sin²(ΔωT/2) is 1 − 2E cos(ΔωT) + E² without its cancellation near Δω = 0.
+    const power = (dw) => (oneMinusE ** 2 + 4 * E * Math.sin((dw * T) / 2) ** 2) / (alpha * alpha + dw * dw);
+    const half = power(0) / 2;
+    const h = (alpha + 1 / T) / 200;
+    let lo = 0;
+    let hi = h;
+    for (let k = 1; power(hi) > half; k++) {
+        if (k > 1e6)
+            throw new Error(`${ID}: no half-power point found (α = ${alpha}, T = ${T})`);
+        lo = hi;
+        hi += h;
+    }
+    for (let k = 0; k < 80; k++) {
+        const mid = (lo + hi) / 2;
+        if (power(mid) > half)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return (lo + hi) / 2 / Math.PI;
+}
+export const DAMPED_RESONATOR_CASE = {
+    id: ID,
+    title: 'Damped resonator ring-down (damping, finite observation time)',
+    parameters: [
+        { key: 'f0_Hz', quantity: 'natural frequency', symbol: 'f0', unit: 'Hz', meaning: 'undamped natural frequency ω0/2π = √(k/m)/2π, > 0' },
+        { key: 'Q', quantity: 'quality factor', symbol: 'Q', unit: '', meaning: 'Q = ω0 m/b (for an RLC: √(L/C)/R), > 0' },
+        { key: 'x0_m', quantity: 'initial displacement', symbol: 'x0', unit: 'm', meaning: 'displacement at release, from rest' },
+        { key: 't_s', quantity: 'read-out time', symbol: 't', unit: 's', meaning: 'time after release at which x and the envelope are read, ≥ 0' },
+        { key: 't_obs_s', quantity: 'record length', symbol: 't_obs', unit: 's', meaning: 'length of the recorded ring-down, starting at release, > 0' },
+        { key: 'T_K', quantity: 'temperature', symbol: 'T', unit: 'K', meaning: 'temperature of the damping bath, > 0 K; give with k_N_per_m for the thermal floor', temperature: 'absolute', optional: true },
+        {
+            key: 'k_N_per_m',
+            quantity: 'mode stiffness',
+            symbol: 'k',
+            unit: 'N/m',
+            meaning: 'effective stiffness of the mode at the read-out point, > 0 (for an RLC read as charge: 1/C in 1/F, not N/m); give with T_K',
+            optional: true,
+        },
+    ],
+    governing: {
+        parent: [
+            'ρA ∂²w/∂t² + c ∂w/∂t + EI ∂⁴w/∂z⁴ = 0 with the structure\'s boundary conditions   (e.g. a cantilever: a field w(z, t) with many modes)',
+            'one mode, w = φ(z) x(t), read at one point:  m x″ + b x′ + k x = 0   (model-damped-spring; for a circuit L q″ + R q′ + q/C = 0, ab-damped-rlc)',
+        ],
+        scalar: [
+            'x(t) = x0 e^{−αt} [cos ω_d t + (α/ω_d) sin ω_d t],  α = ω0/(2Q),  ω_d = ω0 √(1 − 1/(4Q²))   (Q > 1/2)',
+            'envelope x0 e^{−αt}/√(1 − 1/(4Q²));  linewidth Δf = f0/Q;  resolution of a record 1/t_obs',
+        ],
+        distinction: 'The parent is a field w(z, t) with infinitely many modes and a mode shape; the scalar keeps one mode\'s amplitude ' +
+            'x(t) at the read-out point, with all loss lumped into a viscous (velocity-proportional) Q. Dropped: the other modes ' +
+            'and their coupling, the mode shape, and any frequency or amplitude dependence of the damping (structural damping ' +
+            'gives a different Q(f)).',
+    },
+    observable: 'envelope_m',
+    outputs: [
+        { key: 'alpha_per_s', symbol: 'α', unit: 's^-1', meaning: 'amplitude decay rate ω0/(2Q) = b/(2m)' },
+        { key: 'tau_s', symbol: 'τ', unit: 's', meaning: 'amplitude ring-down time 1/α = Q/(πf0)' },
+        { key: 'linewidth_Hz', symbol: 'Δf', unit: 'Hz', meaning: 'f0/Q: FWHM of the velocity (absorbed-power) response, exact at any Q; the displacement response approaches it for Q ≫ 1' },
+        { key: 'f_d_Hz', symbol: 'f_d', unit: 'Hz', meaning: 'damped oscillation frequency f0 √(1 − 1/(4Q²))' },
+        { key: 'x_m', symbol: 'x(t)', unit: 'm', meaning: 'displacement at t, released from rest at x0' },
+        { key: 'envelope_m', symbol: 'A(t)', unit: 'm', meaning: 'ring-down envelope at t: the amplitude a peak-detecting read-out sees' },
+        { key: 'resolution_Hz', symbol: '1/t_obs', unit: 'Hz', meaning: 'frequency resolution of the record' },
+        { key: 'linewidth_windowed_Hz', symbol: 'Δf_T', unit: 'Hz', meaning: 'FWHM of the power spectrum of the truncated ring-down (rectangular window, near resonance)' },
+        { key: 'windowed_excess', symbol: 'Δf_T/Δf − 1', unit: '', meaning: 'how much the finite record broadens the measured line' },
+        { key: 'x_th_rms_m', symbol: '√⟨x²⟩_th', unit: 'm', meaning: 'thermal RMS displacement √(k_BT/k) of the mode (equipartition); null without T_K and k_N_per_m' },
+        {
+            key: 'envelope_rms_m',
+            symbol: '√⟨A²⟩',
+            unit: 'm',
+            meaning: 'RMS envelope with the thermal motion added: √(A² + 2k_BT/k), the Rice second moment; null without T_K and k_N_per_m',
+        },
+    ],
+    conditions: [
+        'released from rest: x(0) = x0, x′(0) = 0; free ring-down, no drive after release',
+        'linear restoring force: the amplitude is small enough that f0 does not depend on it (ax-cubic-spring-lc records why a hardening spring is not this model)',
+        'the record starts at release and lasts t_obs; its spectrum is that of a rectangular window',
+    ],
+    comparison: {
+        reference: 'the linewidth an infinitely long record would show, f0/Q',
+        valueKey: 'linewidth_windowed_Hz',
+        referenceKey: 'linewidth_Hz',
+        deviationKey: 'windowed_excess',
+        method: 'closed-form transform of the truncated ring-down, half-power point by bisection',
+    },
+    notIncluded: [
+        'the detector noise floor; and the thermal drive of the resonator unless T_K and k_N_per_m are given (its equilibrium amplitude √(k_BT/k) is the fluctuation–dissipation partner of its damping; compare case-resistor-noise)',
+        'frequency drift of f0 over the record',
+        'window shapes other than rectangular, and the negative-frequency image of the line (the Q ≫ 1 approximation)',
+        'the other modes of the structure',
+    ],
+    measurement: [
+        'ring-down: fit ln A(t) against t; the slope −α gives Q = πf0/α; compare the measured envelope at t with envelope_m',
+        'spectrum: the FWHM of the recorded line is linewidth_windowed_Hz, which approaches linewidth_Hz only when the record resolves it',
+        'for an RLC circuit read the capacitor voltage: f0 = 1/(2π√(LC)), Q = √(L/C)/R (ab-damped-rlc)',
+    ],
+    links: [
+        { id: 'model-damped-spring', role: 'm x″ + b x′ + k x = 0, the single-mode equation evaluated here' },
+        { id: 'ab-damped-rlc', role: 'the same equation for an RLC circuit, an exact equivalence' },
+        { id: 'ab-damped-massless', role: 'the overdamped reduction, for the regime where this case refuses (Q ≤ 1/2)' },
+        { id: 'ax-cubic-spring-lc', role: 'the refuted claim that a nonlinear (cubic) spring maps onto the linear circuit' },
+    ],
+    examples: {
+        valid: {
+            args: ['f0_Hz=1kHz', 'Q=1000', 'x0_m=1um', 't_s=0.1', 't_obs_s=20', 'T_K=300', 'k_N_per_m=1'],
+            note: 'a 1 kHz, Q = 1000 resonator (1 Hz line), 1 N/m at 300 K, read 0.1 s after release, recorded for 20 s',
+            fails: [],
+        },
+        failures: [
+            {
+                args: ['f0_Hz=1kHz', 'Q=1000', 'x0_m=1um', 't_s=0.1', 't_obs_s=1'],
+                note: 'the same resonator recorded for 1 s: the 1 Hz resolution cannot resolve the 1 Hz line',
+                fails: ['resolved'],
+            },
+            {
+                args: ['f0_Hz=1kHz', 'Q=0.3', 'x0_m=1um', 't_s=0.1', 't_obs_s=20'],
+                note: 'Q = 0.3 is overdamped: there is no ring-down, and the underdamped formulas are refused',
+                fails: ['underdamped', 'single-lorentzian'],
+            },
+            {
+                args: ['f0_Hz=1kHz', 'Q=1000', 'x0_m=100pm', 't_s=1', 't_obs_s=20', 'T_K=300', 'k_N_per_m=1'],
+                note: 'released from 100 pm and read after 1 s (≈ 3 ring-down times): the envelope, ≈ 4 pm, sits below the 64 pm thermal motion',
+                fails: ['above-thermal'],
+            },
+        ],
+    },
+    /** Evaluate the underdamped ring-down outputs and checks for the supplied resonator inputs. */
+    run(i) {
+        requirePositive(ID, i, ['f0_Hz', 'Q', 't_obs_s']);
+        const { f0_Hz: f0, Q, x0_m: x0, t_s: t, t_obs_s: tObs } = i;
+        if (!Number.isFinite(x0))
+            throw new Error(`${ID}: x0_m must be finite (got ${x0})`);
+        if (!Number.isFinite(t) || t < 0)
+            throw new Error(`${ID}: t_s must be a finite number ≥ 0 (got ${t})`);
+        const w0 = 2 * Math.PI * f0;
+        const alpha = w0 / (2 * Q);
+        const linewidth = f0 / Q;
+        const underdamped = Q > 0.5;
+        const root = underdamped ? Math.sqrt(1 - 1 / (4 * Q * Q)) : NaN;
+        const wd = w0 * root;
+        const decay = Math.exp(-alpha * t);
+        const windowed = underdamped ? windowedLinewidthHz(alpha, tObs) : null;
+        const envelope = underdamped ? (Math.abs(x0) * decay) / root : null;
+        const checks = [
+            check('underdamped', 'underdamped: the solution rings (Q > 1/2)', 'Q', Q, '>', 0.5, 'exact: at Q ≤ 1/2 the solution is a sum of real exponentials, with no ring-down, f_d or envelope'),
+            check('single-lorentzian', 'high Q: the line near f0 is one Lorentzian', 'Q', Q, '>=', MIN_Q_LORENTZIAN, 'chosen threshold for Q ≫ 1: the windowed spectrum drops the negative-frequency pole'),
+            check('resolved', 'the record resolves the line: 1/t_obs ≪ f0/Q', '(1/t_obs)/(f0/Q)', 1 / tObs / linewidth, '<=', MAX_RESOLUTION_RATIO, 'chosen threshold for ≪ 1; see windowed_excess for the broadening it allows'),
+            check('in-record', 'the read-out time lies inside the record', 't/t_obs', t / tObs, '<=', 1, 'exact: an envelope read after the record ends was not measured'),
+        ];
+        const unchecked = underdamped
+            ? ['the damping is viscous (velocity-proportional) and the same over the whole ring-down']
+            : ['for Q ≤ 1/2 the displacement is x0 (r₂e^{r₁t} − r₁e^{r₂t})/(r₂ − r₁) with real r₁, r₂; this case does not evaluate it'];
+        if ((i.T_K === undefined) !== (i.k_N_per_m === undefined))
+            throw new Error(`${ID}: give T_K and k_N_per_m together, or neither`);
+        let xTh = null;
+        if (i.T_K !== undefined) {
+            requirePositive(ID, i, ['T_K', 'k_N_per_m']);
+            xTh = Math.sqrt((K_B_SI * i.T_K) / i.k_N_per_m);
+            if (envelope !== null) {
+                checks.push(check('above-thermal', 'the ring-down stands above the thermal motion at t', '√(k_BT/k)/A(t)', xTh / envelope, '<=', MAX_THERMAL_RATIO, 'chosen threshold: the RMS envelope √(A² + 2k_BT/k) then exceeds A by ≤ 1%'));
+            }
+            unchecked.push('the thermal motion is in equilibrium with the damping bath at T and uncorrelated with the release; the read-out adds no noise of its own');
+        }
+        return {
+            outputs: {
+                alpha_per_s: alpha,
+                tau_s: 1 / alpha,
+                linewidth_Hz: linewidth,
+                f_d_Hz: underdamped ? f0 * root : null,
+                x_m: underdamped ? x0 * decay * (Math.cos(wd * t) + (alpha / wd) * Math.sin(wd * t)) : null,
+                envelope_m: envelope,
+                resolution_Hz: 1 / tObs,
+                linewidth_windowed_Hz: windowed,
+                windowed_excess: windowed === null ? null : windowed / linewidth - 1,
+                x_th_rms_m: xTh,
+                envelope_rms_m: xTh === null || envelope === null ? null : Math.sqrt(envelope * envelope + 2 * xTh * xTh),
+            },
+            checks,
+            unchecked,
+        };
+    },
+};
+//# sourceMappingURL=damped-resonator.js.map