universal-physics-tensor 9.0.0 → 10.0.0

package/dist/numerical/spacetime-metrics.js

@@ -6,27 +6,39 @@
  * 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 { C_SI, G_SI, M_SUN_SI } from '../core/constants.js';
 import { DIMENSIONLESS, 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';
+/** 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 +48,59 @@ 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 = det(src);
+    if (typeof determinant !== 'number' || !Number.isFinite(determinant) || determinant === 0) {
+        throw new Error('metric is singular at this point');
     }
-    return a.map((row) => row.slice(4));
+    const out = inv(src);
+    if (!Array.isArray(out) || out.length !== 4)
+        throw new Error('metric inverse is not a 4×4 matrix');
+    return out.map((row) => {
+        if (!Array.isArray(row) || row.length !== 4)
+            throw new Error('metric inverse is not a 4×4 matrix');
+        return row.map((v) => {
+            if (typeof v !== 'number')
+                throw new Error('metric inverse is not a 4×4 matrix');
+            return v;
+        });
+    });
 }
-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);
-        }
-    }
-    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 +115,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,9 +151,6 @@ 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);
     return (x) => {
@@ -340,7 +245,7 @@ export class MetricMassError extends Error {
 /** 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
@@ -371,7 +276,7 @@ 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 = [];
     for (const pair of pairs) {
@@ -381,7 +286,16 @@ export function metricParams(pairs, defaults) {
         const key = pair.slice(0, eq);
         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);
+        let read;
+        try {
+            read = readParameter(pair.slice(eq + 1), 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 +319,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,
@@ -420,10 +334,10 @@ export function curvatureReport(metric, pairs = []) {
         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 Error(`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 +370,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 +416,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 Error(`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');
     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 = [
@@ -590,51 +504,12 @@ export function schwarzschildCircularOrbit(opts) {
     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]];
-    };
+    // 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 };
 }
 /**
@@ -863,26 +738,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 +756,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++) {
@@ -962,24 +826,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);
@@ -1024,7 +902,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);
 }
 /**
@@ -1043,7 +921,7 @@ export function schwarzschildGeodesic(opts) {
     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);
 }
 /**