universal-physics-tensor 9.0.0 → 11.0.0

package/dist/numerical/spacetime-metrics.js

@@ -6,27 +6,43 @@
  * node uses the same mostly-plus signature. The Kretschmann scalar does not
  * depend on that choice.
  *
- * Schwarzschild Christoffel symbols are the closed form. Riemann, Ricci and
- * Kretschmann are a 4th-order finite difference of the metric, checked in
- * tests against the closed forms (Schwarzschild Kretschmann, flat-dust FLRW
- * Ricci scalar, Kerr Kretschmann). Kerr geodesics in Boyer–Lindquist
- * coordinates, including inclined ones, take their initial data from the
- * Carter constant and are integrated with the second-order geodesic equation.
+ * Schwarzschild and Kerr Christoffel symbols are closed forms; the Kerr
+ * ones come from the analytic metric derivatives through the one Christoffel
+ * builder (`computeChristoffelTensor`). Riemann, Ricci and Kretschmann are
+ * the finite-difference curvature stack of `curvature-lowering-helpers.ts`
+ * (`christoffelAt`, `riemannUpperAt`, `lowerFirstIndex`) and
+ * `computeKretschmann`, checked in tests against the closed forms
+ * (Schwarzschild Kretschmann, flat-dust FLRW Ricci scalar, Kerr
+ * Kretschmann). The metric inverse is MathTS `inv`. Kerr geodesics in
+ * Boyer–Lindquist coordinates, including inclined ones, take their initial
+ * data from the Carter constant and are integrated with the second-order
+ * geodesic equation by `integrateGeodesic` (`geodesic-integrator.ts`).
+ * This module holds no curvature or geodesic arithmetic of its own.
  *
  * @module numerical/spacetime-metrics
  * @internal
  */
-import { solveODESystem } from '@danielsimonjr/mathts-functions';
+import { det, inv } from '@danielsimonjr/mathts-functions';
+import { splitAssignment } from '../core/assignment.js';
+import { relDiff, withinMixed } from '../core/compare.js';
+import { numberFrom, numberMatrixFrom } from '../core/mathts-read.js';
 import { C_SI, G_SI, M_SUN_SI } from '../core/constants.js';
-import { DIMENSIONLESS, LENGTH, MASS, MASS_DENSITY, TIME, VELOCITY } from '../dimensional/types.js';
+import { DIMENSIONLESS, GRAVITATIONAL_CONSTANT, LENGTH, MASS, MASS_DENSITY, TIME, VELOCITY } from '../dimensional/types.js';
+import { UnitError } from '../dimensional/units.js';
 import { readParameter } from './binding-value.js';
-/** The signature this module differentiates. */
+import { computeChristoffelTensor } from './connection-lowering-helpers.js';
+import { christoffelAt, lowerFirstIndex, riemannUpperAt } from './curvature-lowering-helpers.js';
+import { integrateGeodesic as integrateGeodesicRK4 } from './geodesic-integrator.js';
+import { computeKretschmann } from './kretschmann.js';
+import { MathTSEngine } from './mathts-engine.js';
+import { schwarzschildRadius } from './schwarzschild.js';
+/** The signature this module differentiates; `CurvatureReport.signature` is its type. */
 export const METRIC_SIGNATURE = '(-,+,+,+)';
 /**
  * Printed with every curvature report. The line element and the canonical
  * Einstein-equation metric node share this mostly-plus signature.
  */
-export const METRIC_SIGNATURE_NOTE = 'Line element signature (−,+,+,+), the same mostly-plus signature as the Schwarzschild fixture ' +
+const METRIC_SIGNATURE_NOTE = 'Line element signature (−,+,+,+), the same mostly-plus signature as the Schwarzschild fixture ' +
     'and as the canonical Einstein-equation metric node. ' +
     'The Kretschmann scalar does not depend on that choice.';
 const Z = 1e-8;
@@ -36,145 +52,53 @@ function zeros(n) {
 function mat4() {
     return [zeros(4), zeros(4), zeros(4), zeros(4)];
 }
+/** The engine the curvature helpers carry their tensors on. */
+const ENGINE = new MathTSEngine();
+/**
+ * The metric inverse, MathTS `inv`. A singular metric is this module's error,
+ * decided by MathTS `det` before the inverse is asked for, so no error text is
+ * read. `inv` and `det` are typed over every MathTS matrix kind, so their
+ * results are read back as the number and the 4×4 number array they are for a
+ * number[][] input.
+ */
 function invert4(src) {
-    const a = src.map((row, i) => {
-        const out = zeros(8);
-        for (let j = 0; j < 4; j++)
-            out[j] = row[j];
-        out[4 + i] = 1;
-        return out;
-    });
-    for (let col = 0; col < 4; col++) {
-        let pivot = col;
-        for (let r = col + 1; r < 4; r++) {
-            if (Math.abs(a[r][col]) > Math.abs(a[pivot][col]))
-                pivot = r;
-        }
-        const tmp = a[col];
-        a[col] = a[pivot];
-        a[pivot] = tmp;
-        const div = a[col][col];
-        if (!Number.isFinite(div) || Math.abs(div) < 1e-18)
-            throw new Error('metric is singular at this point');
-        for (let j = 0; j < 8; j++)
-            a[col][j] = a[col][j] / div;
-        for (let r = 0; r < 4; r++) {
-            if (r === col)
-                continue;
-            const f = a[r][col];
-            for (let j = 0; j < 8; j++)
-                a[r][j] = a[r][j] - f * a[col][j];
-        }
+    const determinant = numberFrom('det', det(src));
+    if (!Number.isFinite(determinant) || determinant === 0) {
+        throw new MetricValueError('metric is singular at this point');
     }
-    return a.map((row) => row.slice(4));
-}
-function shift(x, mu, delta) {
-    const y = [x[0], x[1], x[2], x[3]];
-    y[mu] += delta;
-    return y;
-}
-/** 4th-order central difference of a matrix-valued function. */
-function dMetric(g, x, mu, h) {
-    const at = (s) => g(shift(x, mu, s * h));
-    const a = at(-2);
-    const b = at(-1);
-    const c = at(1);
-    const d = at(2);
-    const out = mat4();
-    for (let i = 0; i < 4; i++) {
-        for (let j = 0; j < 4; j++) {
-            const av = a[i][j];
-            const bv = b[i][j];
-            const cv = c[i][j];
-            const dv = d[i][j];
-            // A component that does not change must not differentiate a huge constant
-            // (g_tt = −c²): the stencil cancels only up to a roundoff, and that
-            // roundoff divided by h is a fake Christoffel.
-            out[i][j] = av === bv && bv === cv && cv === dv ? 0 : (-dv + 8 * cv - 8 * bv + av) / (12 * h);
-        }
+    try {
+        return numberMatrixFrom('inv', inv(src), 4);
+    }
+    catch (error) {
+        throw new Error('metric inverse is not a 4×4 matrix', { cause: error });
     }
-    return out;
+}
+/** The nested-array closures the curvature helpers take, over a `MetricFn`. */
+function closuresOf(g) {
+    const at = (x) => g([x[0], x[1], x[2], x[3]]);
+    return { gFn: at, gInverseFn: (x) => invert4(at(x)) };
 }
 function blankGamma() {
     return [0, 1, 2, 3].map(() => mat4());
 }
-/** A rank-4 array of numbers, indexed [a][b][c][d]. */
-function tensor4() {
-    return [0, 1, 2, 3].map(() => [0, 1, 2, 3].map(() => [0, 1, 2, 3].map(() => [0, 0, 0, 0])));
-}
-function christoffelOf(g, x, steps) {
-    const gi = invert4(g(x));
-    const dg = [0, 1, 2, 3].map((mu) => dMetric(g, x, mu, steps[mu]));
-    const G = blankGamma();
-    for (let rho = 0; rho < 4; rho++) {
-        for (let mu = 0; mu < 4; mu++) {
-            for (let nu = mu; nu < 4; nu++) {
-                let s = 0;
-                for (let sigma = 0; sigma < 4; sigma++) {
-                    s += gi[rho][sigma] * (dg[mu][nu][sigma] + dg[nu][mu][sigma] - dg[sigma][mu][nu]);
-                }
-                const v = 0.5 * s;
-                G[rho][mu][nu] = v;
-                G[rho][nu][mu] = v;
-            }
-        }
-    }
-    return G;
+/** Γ^ρ_{μν}(x) by the finite-difference Christoffel of the curvature helpers. */
+function christoffelOf(g, x) {
+    const { gFn, gInverseFn } = closuresOf(g);
+    return christoffelAt(x, gFn, gInverseFn, 4, ENGINE);
 }
 /**
- * R^ρ_{σμν} = ∂_μ Γ^ρ_{νσ} − ∂_ν Γ^ρ_{μσ} + Γ^ρ_{μλ} Γ^λ_{νσ} − Γ^ρ_{νλ} Γ^λ_{μσ}.
- * Christoffel comes from a 4th-order difference of the metric; its coordinate
- * derivative is a central difference of that. Checked against the Schwarzschild
- * Kretschmann closed form.
+ * Christoffel, Ricci, the Ricci scalar and the Kretschmann scalar at `x`:
+ * `christoffelAt` and `riemannUpperAt` (the finite-difference Γ and R^ρ_{σμν}
+ * of the curvature helpers), the Ricci contraction R_{σν} = R^ρ_{σρν}, and
+ * `computeKretschmann` over the lowered Riemann. Checked against the
+ * Schwarzschild Kretschmann closed form.
  */
-function tensorsOf(g, x, steps) {
+function tensorsOf(g, x) {
+    const { gFn, gInverseFn } = closuresOf(g);
     const g0 = g(x);
     const gi = invert4(g0);
-    const gamma = christoffelOf(g, x, steps);
-    const partial = [];
-    for (let mu = 0; mu < 4; mu++) {
-        const h = steps[mu];
-        const plus = christoffelOf(g, shift(x, mu, h), steps);
-        const minus = christoffelOf(g, shift(x, mu, -h), steps);
-        const d = blankGamma();
-        for (let rho = 0; rho < 4; rho++) {
-            for (let a = 0; a < 4; a++) {
-                for (let b = 0; b < 4; b++) {
-                    d[rho][a][b] = (plus[rho][a][b] - minus[rho][a][b]) / (2 * h);
-                }
-            }
-        }
-        partial.push(d);
-    }
-    const up = tensor4();
-    for (let rho = 0; rho < 4; rho++) {
-        for (let sigma = 0; sigma < 4; sigma++) {
-            for (let mu = 0; mu < 4; mu++) {
-                for (let nu = 0; nu < 4; nu++) {
-                    let s = partial[mu][rho][nu][sigma] - partial[nu][rho][mu][sigma];
-                    for (let lam = 0; lam < 4; lam++) {
-                        s +=
-                            gamma[rho][mu][lam] * gamma[lam][nu][sigma] -
-                                gamma[rho][nu][lam] * gamma[lam][mu][sigma];
-                    }
-                    up[rho][sigma][mu][nu] = s;
-                }
-            }
-        }
-    }
-    const lower = tensor4();
-    for (let a = 0; a < 4; a++) {
-        for (let b = 0; b < 4; b++) {
-            for (let c = 0; c < 4; c++) {
-                for (let d = 0; d < 4; d++) {
-                    let s = 0;
-                    for (let rho = 0; rho < 4; rho++)
-                        s += g0[a][rho] * up[rho][b][c][d];
-                    lower[a][b][c][d] = s;
-                }
-            }
-        }
-    }
+    const gamma = christoffelAt(x, gFn, gInverseFn, 4, ENGINE);
+    const up = riemannUpperAt(x, gFn, gInverseFn, 4, ENGINE, gamma);
     const ricci = mat4();
     for (let sigma = 0; sigma < 4; sigma++) {
         for (let nu = 0; nu < 4; nu++) {
@@ -189,26 +113,8 @@ function tensorsOf(g, x, steps) {
         for (let b = 0; b < 4; b++)
             ricciScalar += gi[a][b] * ricci[a][b];
     }
-    let kretschmann = 0;
-    for (let a = 0; a < 4; a++) {
-        for (let b = 0; b < 4; b++) {
-            for (let c = 0; c < 4; c++) {
-                for (let d = 0; d < 4; d++) {
-                    let raised = 0;
-                    for (let ap = 0; ap < 4; ap++) {
-                        for (let bp = 0; bp < 4; bp++) {
-                            for (let cp = 0; cp < 4; cp++) {
-                                for (let dp = 0; dp < 4; dp++) {
-                                    raised += gi[a][ap] * gi[b][bp] * gi[c][cp] * gi[d][dp] * lower[ap][bp][cp][dp];
-                                }
-                            }
-                        }
-                    }
-                    kretschmann += lower[a][b][c][d] * raised;
-                }
-            }
-        }
-    }
+    const lower = lowerFirstIndex(up, g0.flat(), 4);
+    const kretschmann = computeKretschmann(lower, gi);
     return { ricciScalar, kretschmann, ricci, christoffel: gamma };
 }
 function nonzeroMatrix(m, label) {
@@ -243,11 +149,8 @@ function nonzeroGamma(G) {
     }
     return out;
 }
-function stepsFor(x) {
-    return [Math.max(Math.abs(x[0]), 1) * 1e-4, Math.max(Math.abs(x[1]), 1) * 1e-4, 1e-4, 1e-4];
-}
 function schwarzschildMetric(M, c, G) {
-    const rs = (2 * G * M) / (c * c);
+    const rs = schwarzschildRadius(M, G, c);
     return (x) => {
         const r = x[1];
         const th = x[2];
@@ -337,10 +240,25 @@ export class MetricMassError extends Error {
         this.name = 'MetricMassError';
     }
 }
+/**
+ * A value the metric library refuses: a point inside the horizon or on a
+ * pole, a Kerr point inside the ring, an unknown or repeated parameter, a
+ * token that is not `key=value`, an orbit or geodesic start the closed forms
+ * do not admit, a Newton iteration that does not converge at the given
+ * point. The CLI maps this class to exit 1; any other class is a defect and
+ * is not converted.
+ * @internal
+ */
+export class MetricValueError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MetricValueError';
+    }
+}
 /** A mass that is not positive is not a source. */
 function requirePositiveMass(M) {
     if (!(M > 0))
-        throw new MetricMassError(`${M <= 0 ? 'a non-positive' : 'a non-finite'} mass is not a source: the metric needs a positive mass`);
+        throw new MetricMassError(`${M <= 0 ? 'a non-positive' : 'a non-finite'} mass (M = ${M} kg) is not a source: the metric needs a positive mass`);
 }
 /**
  * The polar angle is a point of the spherical chart only on the open interval
@@ -350,14 +268,14 @@ function requirePositiveMass(M) {
  */
 function requirePolarInterior(theta) {
     if (!(theta > 0 && theta < Math.PI && Math.sin(theta) > 1e-9)) {
-        throw new Error(`θ must be strictly between 0 and π (got ${theta}): the poles are coordinate singularities of the spherical chart`);
+        throw new MetricValueError(`θ must be strictly between 0 and π (got ${theta}): the poles are coordinate singularities of the spherical chart`);
     }
 }
 /** SI dimension of each metric parameter. A bare number is already in that unit. */
 const PARAM_DIM = {
     M: MASS,
     c: VELOCITY,
-    G: { L: 3, M: -1, T: -2, I: 0, Theta: 0, N: 0, J: 0 },
+    G: GRAVITATIONAL_CONSTANT,
     r: LENGTH,
     a: LENGTH,
     t: TIME,
@@ -371,17 +289,30 @@ const PARAM_DIM = {
     rho: MASS_DENSITY,
 };
 /** Parse `key=value` pairs. A value is a number, a unit, or a constant expression. @internal */
-export function metricParams(pairs, defaults) {
+function metricParams(pairs, defaults) {
     const values = { ...defaults };
     const notes = [];
+    const seen = new Set();
     for (const pair of pairs) {
-        const eq = pair.indexOf('=');
-        if (eq <= 0)
-            throw new Error(`'${pair}' must be key=value`);
-        const key = pair.slice(0, eq);
+        const split = splitAssignment(pair);
+        if (split === null)
+            throw new MetricValueError(`'${pair}' must be key=value`);
+        const key = split.name;
         if (!(key in defaults))
-            throw new Error(`unknown parameter '${key}' (expected ${Object.keys(defaults).join(', ')})`);
-        const read = readParameter(pair.slice(eq + 1), PARAM_DIM[key] ?? DIMENSIONLESS);
+            throw new MetricValueError(`unknown parameter '${key}' (expected ${Object.keys(defaults).join(', ')})`);
+        if (seen.has(key))
+            throw new MetricValueError(`'${key}' is given twice ('${pair}'); give one value per parameter`);
+        seen.add(key);
+        let read;
+        try {
+            read = readParameter(split.raw, PARAM_DIM[key] ?? DIMENSIONLESS);
+        }
+        catch (e) {
+            // The reader knows the text and the dimension it was given, not which parameter held them.
+            if (e instanceof UnitError)
+                throw new UnitError(`parameter ${key}: ${e.message}`);
+            throw e;
+        }
         values[key] = read.value;
         for (const note of read.notes)
             if (!notes.includes(note))
@@ -405,7 +336,7 @@ export function curvatureReport(metric, pairs = []) {
             return m;
         };
         const x = [p.t, p.r, p.theta, p.phi];
-        const t = tensorsOf(g, x, stepsFor(x));
+        const t = tensorsOf(g, x);
         return stateCurvature(pack('minkowski', p, x, t, { ricciScalar: 0, kretschmann: 0 }, [
             'Minkowski in Cartesian-like coordinates (the angular part is not a sphere here; g_θθ = g_φφ = 1).',
             ...notes,
@@ -416,14 +347,14 @@ export function curvatureReport(metric, pairs = []) {
         const { values: p, notes } = metricParams(pairs, { M: M_SUN_SI, c: C_SI, G: G_SI, r: Number.NaN, theta: Math.PI / 2, phi: 0, t: 0 });
         requirePositiveMass(p.M);
         requirePolarInterior(p.theta);
-        const rs = (2 * p.G * p.M) / (p.c * p.c);
+        const rs = schwarzschildRadius(p.M, p.G, p.c);
         if (Number.isNaN(p.r))
             p.r = 10 * rs;
         if (!(p.r > rs))
-            throw new Error(`r must be outside the horizon (r_s = ${rs})`);
+            throw new MetricValueError(`r must be outside the horizon (r = ${p.r} m, r_s = ${rs} m)`);
         const g = schwarzschildMetric(p.M, p.c, p.G);
         const x = [p.t, p.r, p.theta, p.phi];
-        const t = tensorsOf(g, x, stepsFor(x));
+        const t = tensorsOf(g, x);
         const K = schwarzschildKretschmann(p.M, p.r, p.c, p.G);
         return stateCurvature(pack('schwarzschild', p, x, t, { kretschmann: K, ricciScalar: 0, horizon_m: rs }, [
             'Closed form: Kretschmann = 48 G² M² / (c⁴ r⁶), Ricci = 0.',
@@ -456,8 +387,8 @@ export function curvatureReport(metric, pairs = []) {
         // Christoffel in the SI metric. Ricci and Kretschmann are computed at c = 1
         // and divided by c² and c⁴: g_tt = −c² makes those scalars smaller than the
         // roundoff of an SI finite difference.
-        const tSi = tensorsOf(g, x, stepsFor(x));
-        const t1 = p.c === 1 ? tSi : tensorsOf(flrwMetric(p.a0, p.t0, p.n, p.k, 1), x, stepsFor(x));
+        const tSi = tensorsOf(g, x);
+        const t1 = p.c === 1 ? tSi : tensorsOf(flrwMetric(p.a0, p.t0, p.n, p.k, 1), x);
         const c2 = p.c * p.c;
         const t = {
             christoffel: tSi.christoffel,
@@ -502,12 +433,12 @@ export function curvatureReport(metric, pairs = []) {
     if (Number.isNaN(p.r))
         p.r = 10 * Mgeom;
     if (!(p.r > 0))
-        throw new Error(`r must be positive and outside the singularity (got ${p.r})`);
+        throw new MetricValueError(`r must be positive and outside the singularity (got r = ${p.r} m)`);
     if (Math.abs(p.a) >= p.r)
-        throw new Error('Kerr finite difference wants |a| < r and r outside the ring');
+        throw new MetricValueError('Kerr finite difference wants |a| < r and r outside the ring');
     const g = kerrMetric(Mgeom, p.a);
     const x = [p.t, p.r, p.theta, p.phi];
-    const t = tensorsOf(g, x, stepsFor(x));
+    const t = tensorsOf(g, x);
     const K = kerrKretschmann(Mgeom, p.r, p.a, p.theta);
     const aOverM = p.a / Mgeom;
     const kerrNotes = [
@@ -524,7 +455,6 @@ export function curvatureReport(metric, pairs = []) {
         'Geodesics (--geodesic) use the Carter constant. θ = π/2 is an equatorial circular orbit. Any other θ is an inclined spherical orbit with that polar turning point. ISCO and photon radii are closed forms in r/M.',
     ]));
 }
-const relDiff = (got, want) => Math.abs(got - want) / Math.max(Math.abs(want), 1e-30);
 /**
  * The headline Ricci scalar is the closed form when the finite difference
  * does not match it. A vacuum metric's finite-difference residual is not
@@ -540,14 +470,14 @@ function stateCurvature(report) {
         ricci = [];
         notes.push('Ricci is 0 for this vacuum metric. A finite-difference residual is not listed.');
     }
-    else if (exactR !== undefined && relDiff(report.ricciScalar, exactR) > 1e-2) {
+    else if (exactR !== undefined && relDiff(report.ricciScalar, exactR, 1e-30) > 1e-2) {
         ricciScalar = exactR;
         ricci = [];
         notes.push('Ricci scalar is the closed form. The finite-difference scalar, restored from a c = 1 difference by 1/c², does not match it when spatial curvature is present, so those components are not listed.');
     }
     const H2 = report.closedForm.H2;
     const rhs = report.closedForm.friedmannRhs;
-    if (H2 !== undefined && rhs !== undefined && relDiff(H2, rhs) > 1e-6) {
+    if (H2 !== undefined && rhs !== undefined && relDiff(H2, rhs, 1e-30) > 1e-6) {
         notes.push('H² and the Friedmann right-hand side differ, so this scale factor is not a solution of the Friedmann equation at the stated ρ, k and Λ. k is a curvature in 1/length²: k = 1 with c in m/s is a curvature radius of about a metre, not the dimensionless k = ±1 of geometrized cosmology.');
     }
     return { ...report, ricci, ricciScalar, notes };
@@ -589,52 +519,13 @@ export function schwarzschildCircularOrbit(opts) {
     const ut = 1 / Math.sqrt(1 - (3 * rs) / (2 * r0));
     const uphi = Omega * ut;
     if (!(f > 0) || !Number.isFinite(ut))
-        throw new Error('circular orbit needs r > 1.5 r_s');
-    // Analytic Γ for the equatorial circular orbit (θ = π/2, sin = 1, cos = 0).
-    // Equatorial reduction. The polar symbols that carry cot θ are omitted:
-    // a floating-point step off θ = π/2 makes cot θ explode.
-    const gamma = (r) => {
-        const ff = 1 - rs / r;
-        const Gma = blankGamma();
-        const set = (rho, mu, nu, v) => {
-            Gma[rho][mu][nu] = v;
-            Gma[rho][nu][mu] = v;
-        };
-        set(0, 0, 1, rs / (2 * r * (r - rs)));
-        set(1, 0, 0, (rs * ff) / (2 * r * r));
-        set(1, 1, 1, -rs / (2 * r * (r - rs)));
-        set(1, 2, 2, -(r - rs));
-        set(1, 3, 3, -(r - rs));
-        set(2, 1, 2, 1 / r);
-        set(3, 1, 3, 1 / r);
-        return Gma;
-    };
-    // state: t, r, th, phi, ut, ur, uth, uphi
-    let y = [0, r0, Math.PI / 2, 0, ut, 0, 0, uphi];
-    const accel = (s) => {
-        const Gma = gamma(s[1]);
-        const u = [s[4], s[5], s[6], s[7]];
-        const du = [0, 0, 0, 0];
-        for (let rho = 0; rho < 4; rho++) {
-            let sum = 0;
-            for (let mu = 0; mu < 4; mu++) {
-                for (let nu = 0; nu < 4; nu++)
-                    sum += Gma[rho][mu][nu] * u[mu] * u[nu];
-            }
-            du[rho] = -sum;
-        }
-        return [u[0], u[1], u[2], u[3], du[0], du[1], du[2], du[3]];
-    };
+        throw new MetricValueError('circular orbit needs r > 1.5 r_s');
+    // The closed-form Schwarzschild Christoffel symbols, polar terms included:
+    // with u^θ = 0 and θ = π/2 the polar terms stay zero to roundoff.
     const period = (2 * Math.PI) / uphi;
     const fraction = opts?.fraction ?? 0.02;
     const steps = 400;
-    const h = (period * fraction) / steps;
-    for (let n = 0; n < steps; n++) {
-        const sol = solveODESystem((_t, s) => accel(s), y, [0, h], { dt: h });
-        y = (sol.y[sol.y.length - 1] ?? y).slice();
-        y[2] = Math.PI / 2;
-        y[6] = 0;
-    }
+    const y = integrateWithChristoffel((r, theta) => schwarzschildChristoffel(M, r, theta), [0, r0, Math.PI / 2, 0, ut, 0, 0, uphi], period * fraction, steps);
     return { r0, rEnd: y[1], phiAdvance: y[3], steps };
 }
 /**
@@ -646,7 +537,7 @@ export function schwarzschildCircularOrbit(opts) {
 export function kerrIscoRadius(aOverM) {
     const chi = aOverM;
     if (!(Math.abs(chi) <= 1))
-        throw new Error('|a/M| must be at most 1');
+        throw new MetricValueError('|a/M| must be at most 1');
     const z1 = 1 + Math.cbrt(1 - chi * chi) * (Math.cbrt(1 + chi) + Math.cbrt(1 - chi));
     const z2 = Math.sqrt(3 * chi * chi + z1 * z1);
     const inner = Math.sqrt((3 - z1) * (3 + z1 + 2 * z2));
@@ -660,7 +551,7 @@ export function kerrIscoRadius(aOverM) {
 export function kerrPhotonRadius(aOverM) {
     const chi = aOverM;
     if (!(Math.abs(chi) <= 1))
-        throw new Error('|a/M| must be at most 1');
+        throw new MetricValueError('|a/M| must be at most 1');
     return {
         prograde: 2 * (1 + Math.cos((2 / 3) * Math.acos(-chi))),
         retrograde: 2 * (1 + Math.cos((2 / 3) * Math.acos(chi))),
@@ -686,7 +577,7 @@ function equatorialCircular(M, a, r, prograde) {
     const g0 = kerrMetric(M, a)([0, r, Math.PI / 2, 0]);
     const norm = -(g0[0][0] + 2 * Omega * g0[0][3] + Omega * Omega * g0[3][3]);
     if (!(norm > 0) || !Number.isFinite(Omega))
-        throw new Error('circular orbit is not timelike at this radius');
+        throw new MetricValueError('circular orbit is not timelike at this radius');
     const ut = 1 / Math.sqrt(norm);
     const uphi = Omega * ut;
     return {
@@ -729,7 +620,7 @@ function solveSpherical(M, a, r, Q, mu2, prograde) {
         const det = j11 * j22 - j12 * j21;
         const scale = Math.max(1, Math.abs(j11), Math.abs(j12), Math.abs(j21), Math.abs(j22));
         if (!Number.isFinite(det) || Math.abs(det) < 1e-18 * scale * scale)
-            throw new Error('spherical-orbit Jacobian is singular');
+            throw new MetricValueError('spherical-orbit Jacobian is singular');
         const stepE = (j22 * f1 - j12 * f2) / det;
         const stepL = (-j21 * f1 + j11 * f2) / det;
         E -= stepE;
@@ -743,7 +634,7 @@ function solveSpherical(M, a, r, Q, mu2, prograde) {
         if (settled)
             return { E, L: L * M };
     }
-    throw new Error('spherical orbit did not converge');
+    throw new MetricValueError('spherical orbit did not converge');
 }
 /**
  * Timelike spherical orbit at fixed r: R = R' = 0. `Q` is the Carter constant
@@ -754,7 +645,7 @@ export function kerrSphericalTimelike(opts) {
     const M = opts?.M ?? 1;
     const chi = opts?.aOverM ?? 0;
     if (!(M > 0) || !(Math.abs(chi) <= 1))
-        throw new Error('spherical orbit wants M > 0 and |a/M| ≤ 1');
+        throw new MetricValueError('spherical orbit wants M > 0 and |a/M| ≤ 1');
     const a = chi * M;
     const r = (opts?.rOverM ?? 10) * M;
     const Q = opts?.Q ?? 0;
@@ -778,26 +669,26 @@ export function kerrSphericalPhoton(opts) {
     const chi = opts?.aOverM ?? 0;
     const rHat = opts?.rOverM;
     if (!(M > 0) || !(Math.abs(chi) > 0 && Math.abs(chi) <= 1))
-        throw new Error('spherical photon orbit wants M > 0 and 0 < |a/M| ≤ 1');
+        throw new MetricValueError('spherical photon orbit wants M > 0 and 0 < |a/M| ≤ 1');
     if (rHat === undefined)
-        throw new Error('spherical photon orbit needs rOverM');
+        throw new MetricValueError('spherical photon orbit needs rOverM');
     const ends = kerrPhotonRadius(chi);
     const lo = Math.min(ends.prograde, ends.retrograde);
     const hi = Math.max(ends.prograde, ends.retrograde);
     if (!(rHat >= lo - 1e-9 && rHat <= hi + 1e-9)) {
-        throw new Error('spherical photon radius lies between the prograde and retrograde photon orbits');
+        throw new MetricValueError('spherical photon radius lies between the prograde and retrograde photon orbits');
     }
     const a = chi * M;
     const r = rHat * M;
     if (!(Math.abs(r - M) > 1e-9 * M))
-        throw new Error('extremal prograde photon orbit sits on the horizon');
+        throw new MetricValueError('extremal prograde photon orbit sits on the horizon');
     const Delta = r * r - 2 * M * r + a * a;
     const E = 1;
     const L = E * ((r * r + a * a) / a - (2 * r * Delta) / (a * (r - M)));
     const P = E * (r * r + a * a) - a * L;
     const Q = (P * P) / Delta - (L - a * E) ** 2;
     if (Q < -1e-8 * M * M)
-        throw new Error('no spherical photon orbit at this radius');
+        throw new MetricValueError('no spherical photon orbit at this radius');
     return { E, L, Q: Q < 0 ? 0 : Q };
 }
 /**
@@ -809,14 +700,14 @@ export function kerrTurningPointOrbit(opts) {
     const M = opts.M ?? 1;
     const chi = opts.aOverM ?? 0;
     if (!(M > 0) || !(Math.abs(chi) <= 1))
-        throw new Error('turning-point orbit wants M > 0 and |a/M| ≤ 1');
+        throw new MetricValueError('turning-point orbit wants M > 0 and |a/M| ≤ 1');
     const a = chi * M;
     const r = (opts.rOverM ?? 10) * M;
     const theta = opts.theta;
     const s = Math.sin(theta);
     const c = Math.cos(theta);
     if (!(Math.abs(s) > 1e-3) || !(Math.abs(c) > 1e-4)) {
-        throw new Error('turning-point θ must sit off the equator and off the pole');
+        throw new MetricValueError('turning-point θ must sit off the equator and off the pole');
     }
     const seed = equatorialCircular(M, a, r, opts.prograde !== false);
     let Q = seed.L * seed.L * c * c;
@@ -828,12 +719,12 @@ export function kerrTurningPointOrbit(opts) {
         L = solved.L;
         const next = c * c * (a * a * (1 - E * E) + (L * L) / (s * s));
         if (!Number.isFinite(next) || next < 0)
-            throw new Error('turning-point Carter constant left the physical range');
-        if (Math.abs(next - Q) <= 1e-9 * Math.max(1, Math.abs(next)))
+            throw new MetricValueError('turning-point Carter constant left the physical range');
+        if (withinMixed(Q, next, 1e-9))
             return { E, L, Q: next };
         Q = next;
     }
-    throw new Error('turning-point Carter constant did not converge');
+    throw new MetricValueError('turning-point Carter constant did not converge');
 }
 function kerrMetricDerivatives(M, a, r, theta) {
     const c = Math.cos(theta);
@@ -863,26 +754,15 @@ function kerrMetricDerivatives(M, a, r, theta) {
     dth[3][3] = ((2 * s * c * A + s * s * dAt) * Sigma - s * s * A * dSt) / Sigma2;
     return { dr, dth };
 }
+/**
+ * Γ^ρ_{μν} from a metric and its analytic partial derivatives, through the
+ * one Christoffel builder (`computeChristoffelTensor`). A `null` derivative
+ * is a coordinate the metric does not depend on.
+ */
 function christoffelFrom(g, dg) {
-    const gi = invert4(g);
-    const G = blankGamma();
-    for (let rho = 0; rho < 4; rho++) {
-        for (let mu = 0; mu < 4; mu++) {
-            for (let nu = mu; nu < 4; nu++) {
-                let s = 0;
-                for (let sigma = 0; sigma < 4; sigma++) {
-                    const dmu = dg[mu]?.[nu][sigma] ?? 0;
-                    const dnu = dg[nu]?.[mu][sigma] ?? 0;
-                    const dsig = dg[sigma]?.[mu][nu] ?? 0;
-                    s += gi[rho][sigma] * (dmu + dnu - dsig);
-                }
-                const v = 0.5 * s;
-                G[rho][mu][nu] = v;
-                G[rho][nu][mu] = v;
-            }
-        }
-    }
-    return G;
+    const gInverseFlat = invert4(g).flat();
+    const tensor = computeChristoffelTensor(gInverseFlat, (mu) => (dg[mu] ?? mat4()).flat(), 4, ENGINE);
+    return ENGINE.toNested(tensor);
 }
 function kerrChristoffel(M, a, r, theta) {
     const partial = kerrMetricDerivatives(M, a, r, theta);
@@ -892,7 +772,7 @@ function kerrChristoffel(M, a, r, theta) {
 export function kerrChristoffelFdGap(M, a, r, theta) {
     const x = [0, r, theta, 0];
     const analytic = kerrChristoffel(M, a, r, theta);
-    const fd = christoffelOf(kerrMetric(M, a), x, stepsFor(x));
+    const fd = christoffelOf(kerrMetric(M, a), x);
     let gap = 0;
     for (let rho = 0; rho < 4; rho++) {
         for (let mu = 0; mu < 4; mu++) {
@@ -942,18 +822,18 @@ function carterState(M, a, r, theta, E, L, Q, mu2, signR, signTheta, allowOffShe
     const c = Math.cos(theta);
     const s = Math.sin(theta);
     if (!(Math.abs(s) > 1e-6))
-        throw new Error('Boyer–Lindquist geodesic wants θ away from the poles');
+        throw new MetricValueError('Boyer–Lindquist geodesic wants θ away from the poles');
     const Sigma = r * r + a * a * c * c;
     const Delta = r * r - 2 * M * r + a * a;
     if (!(Delta > 0))
-        throw new Error('geodesic start must be outside the horizon');
+        throw new MetricValueError('geodesic start must be outside the horizon');
     const R = radialPotential(M, a, r, E, L, Q, mu2);
     const Theta = Q - c * c * (a * a * (mu2 - E * E) + (L * L) / (s * s));
     const scale = Math.max(1, E * E, L * L, Math.abs(Q));
     if (R < -1e-8 * scale && !allowOffShell)
-        throw new Error('radial potential is negative at the start');
+        throw new MetricValueError('radial potential is negative at the start');
     if (Theta < -1e-8 * scale && !allowOffShell)
-        throw new Error('polar potential is negative at the start');
+        throw new MetricValueError('polar potential is negative at the start');
     const g = kerrMetric(M, a)([0, r, theta, 0]);
     const det = g[0][0] * g[3][3] - g[0][3] * g[0][3];
     const ut = (g[3][3] * -E - g[0][3] * L) / det;
@@ -962,24 +842,38 @@ function carterState(M, a, r, theta, E, L, Q, mu2, signR, signTheta, allowOffShe
     const uth = signTheta * Math.sqrt(Math.max(Theta, 0)) / Sigma;
     return [0, r, theta, 0, ut, ur, uth, uphi];
 }
-function integrateGeodesic(gammaAt, y0, fraction, steps) {
-    const accel = (s) => {
-        const Gma = gammaAt(s[1], s[2]);
-        const u = [s[4], s[5], s[6], s[7]];
-        const du = [0, 0, 0, 0];
-        for (let rho = 0; rho < 4; rho++) {
-            let sum = 0;
-            for (let mu = 0; mu < 4; mu++)
-                for (let nu = 0; nu < 4; nu++)
-                    sum += Gma[rho][mu][nu] * u[mu] * u[nu];
-            du[rho] = -sum;
+/**
+ * The state `[t, r, θ, φ, u^t, u^r, u^θ, u^φ]` after `steps` RK4 steps of
+ * the second-order geodesic equation over an affine extent `tauEnd`, by
+ * `integrateGeodesic` of `geodesic-integrator.ts` with `gammaAt` packed into
+ * its flat layout `G[16·μ + 4·ν + ρ] = Γ^μ_{νρ}`.
+ */
+function integrateWithChristoffel(gammaAt, y0, tauEnd, steps) {
+    const christoffelFn = (x, out) => {
+        const flat = out ?? new Float64Array(64);
+        const gamma = gammaAt(x[1], x[2]);
+        for (let mu = 0; mu < 4; mu++) {
+            for (let nu = 0; nu < 4; nu++) {
+                for (let rho = 0; rho < 4; rho++)
+                    flat[16 * mu + 4 * nu + rho] = gamma[mu][nu][rho];
+            }
         }
-        return [u[0], u[1], u[2], u[3], du[0], du[1], du[2], du[3]];
+        return flat;
     };
+    const result = integrateGeodesicRK4({
+        christoffelFn,
+        x0: [y0[0], y0[1], y0[2], y0[3]],
+        v0: [y0[4], y0[5], y0[6], y0[7]],
+        tauStart: 0,
+        tauEnd,
+        steps,
+    });
+    return [...result.xFinal, ...result.vFinal];
+}
+/** `fraction` of an orbit's angular period, from the start's angular rate. */
+function orbitExtent(y0, fraction) {
     const angular = Math.max(Math.abs(y0[7]), Math.abs(y0[6]), 1e-12);
-    const h = ((2 * Math.PI) / angular) * fraction / steps;
-    const sol = solveODESystem((_t, s) => accel(s), y0.slice(), [0, steps * h], { dt: h });
-    return sol.y[sol.y.length - 1] ?? y0.slice();
+    return ((2 * Math.PI) / angular) * fraction;
 }
 function sampleOf(metric, a, y0, y1, steps, mu2) {
     const start = conservedOf(metric, a, y0, mu2);
@@ -1015,7 +909,7 @@ export function kerrGeodesic(opts) {
     const M = opts.M ?? 1;
     const chi = opts.aOverM ?? 0;
     if (!(M > 0) || !(Math.abs(chi) <= 1))
-        throw new Error('Kerr geodesic wants M > 0 and |a/M| ≤ 1');
+        throw new MetricValueError('Kerr geodesic wants M > 0 and |a/M| ≤ 1');
     const a = chi * M;
     const r = (opts.rOverM ?? 10) * M;
     const theta = opts.theta ?? Math.PI / 2;
@@ -1024,7 +918,7 @@ export function kerrGeodesic(opts) {
     const fraction = opts.fraction ?? 0.01;
     const metric = kerrMetric(M, a);
     const y0 = carterState(M, a, r, theta, opts.E, opts.L, opts.Q, mu2, opts.signR ?? 1, opts.signTheta ?? 1, opts.allowOffShell === true);
-    const y1 = integrateGeodesic((rr, th) => kerrChristoffel(M, a, rr, th), y0, fraction, steps);
+    const y1 = integrateWithChristoffel((rr, th) => kerrChristoffel(M, a, rr, th), y0, orbitExtent(y0, fraction), steps);
     return sampleOf(metric, a, y0, y1, steps, mu2);
 }
 /**
@@ -1036,14 +930,14 @@ export function kerrGeodesic(opts) {
 export function schwarzschildGeodesic(opts) {
     const M = opts.M ?? 1;
     if (!(M > 0))
-        throw new Error('Schwarzschild geodesic wants M > 0');
+        throw new MetricValueError('Schwarzschild geodesic wants M > 0');
     const r = (opts.rOverM ?? 10) * M;
     const theta = opts.theta ?? Math.PI / 2;
     const steps = opts.steps ?? 80;
     const fraction = opts.fraction ?? 0.01;
     const metric = schwarzschildMetric(M, 1, 1);
     const y0 = carterState(M, 0, r, theta, opts.E, opts.L, opts.Q, 1, opts.signR ?? 1, opts.signTheta ?? 1, false);
-    const y1 = integrateGeodesic((rr, th) => schwarzschildChristoffel(M, rr, th), y0, fraction, steps);
+    const y1 = integrateWithChristoffel((rr, th) => schwarzschildChristoffel(M, rr, th), y0, orbitExtent(y0, fraction), steps);
     return sampleOf(metric, 0, y0, y1, steps, 1);
 }
 /**
@@ -1057,7 +951,7 @@ export function kerrEquatorialCircular(opts) {
     const chi = opts?.aOverM ?? 0;
     const rOverM = opts?.rOverM ?? 10;
     if (!(M > 0) || !(Math.abs(chi) <= 1))
-        throw new Error('|a/M| must be at most 1');
+        throw new MetricValueError('|a/M| must be at most 1');
     const eq = equatorialCircular(M, chi * M, rOverM * M, opts?.prograde !== false);
     return kerrGeodesic({
         M,