@johnmorrisdotca/uchusen-rockets 0.19.1 → 0.20.0

package/dist/physics/burns.js

@@ -0,0 +1,157 @@
+import { propagate } from "./propagate.js";
+import { burnSeconds, deltaV, massFlow } from "./rocket.js";
+import { addScaled, cross, length, scale, sub } from "./vector.js";
+const unit = (v) => {
+    const l = length(v);
+    if (!(l > 0))
+        throw new RangeError("a direction needs a length");
+    return scale(v, 1 / l);
+};
+/**
+ * The unit vector a direction points along, for a craft at a position and speed relative to the body it orbits.
+ * @param direction The direction.
+ * @param position The craft's position from the body's centre, metres.
+ * @param velocity The craft's speed relative to the body, metres a second.
+ * @returns A unit vector in the frame.
+ * @example
+ * ```ts
+ * import { directionOf } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(directionOf("normal", [7_000_000, 0, 0], [0, 7_500, 0]));
+ * ```
+ */
+export function directionOf(direction, position, velocity) {
+    switch (direction) {
+        case "prograde":
+            return unit(velocity);
+        case "retrograde":
+            return scale(unit(velocity), -1);
+        case "normal":
+            return unit(cross(position, velocity));
+        case "antinormal":
+            return scale(unit(cross(position, velocity)), -1);
+        case "radial-out":
+            return unit(position);
+        case "radial-in":
+            return scale(unit(position), -1);
+        default:
+            return unit(direction);
+    }
+}
+const ORIGIN = () => ({ position: [0, 0, 0], velocity: [0, 0, 0] });
+/**
+ * A change of speed all at once (an impulsive burn), as a planning tool treats a short burn.
+ * @param state The craft before the burn.
+ * @param dv The change of speed, metres a second.
+ * @param direction Which way.
+ * @param centre Where the body the craft orbits is; left out, at the origin and still.
+ * @returns The craft just after: the same place and time, the new speed.
+ * @example
+ * ```ts
+ * import { elementsOf, impulse } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const after = impulse({ t: 0, position: [6_778_000, 0, 0], velocity: [0, 7_669, 0] }, 2_400, "prograde");
+ * console.log(((elementsOf(3.986004418e14, after.position, after.velocity).apoapsis - 6_378_137) / 1000).toFixed(0), "km apogee");
+ * ```
+ */
+export function impulse(state, dv, direction, centre = ORIGIN) {
+    const c = centre(state.t);
+    const along = directionOf(direction, sub(state.position, c.position), sub(state.velocity, c.velocity));
+    return { ...state, velocity: addScaled(state.velocity, along, dv) };
+}
+/**
+ * When to start a burn so that it is centred on a planned point, as Orbiter's plane-alignment display times one: the point's time less half the burn.
+ * @param centreTime When the planned point is reached, seconds.
+ * @param seconds How long the burn lasts, seconds.
+ * @returns When to start, seconds.
+ * @example
+ * ```ts
+ * import { burnStart } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(burnStart(1_000, 120));
+ * ```
+ */
+export const burnStart = (centreTime, seconds) => centreTime - seconds / 2;
+/**
+ * Flies one burn from a state: gravity and the engine's thrust together, the mass falling at the engine's flow, the thrust kept along its direction as the craft moves.
+ * @param start The craft when the engine lights.
+ * @param mass Its mass then, kilograms.
+ * @param burn The engine, the direction, and how long or how much.
+ * @param options The step, the gravity, the centre and the dry mass.
+ * @returns Where the craft is when the engine stops, and what the burn did.
+ * @throws {RangeError} When the burn has no length, or would use all the mass with no `dryMass` above zero.
+ * @example
+ * ```ts
+ * import { exhaustSpeedOf, flyBurn, gravityAt } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const earth = [{ gm: 3.986004418e14, position: [0, 0, 0] as const }];
+ * const raise = flyBurn({ t: 0, position: [6_778_000, 0, 0], velocity: [0, 7_669, 0] }, 20_000, { engine: { thrust: 91_189, exhaustSpeed: exhaustSpeedOf(314) }, direction: "prograde", dv: 100 }, { step: 1, gravity: (_t, p) => gravityAt(p, earth) });
+ * console.log(raise.seconds.toFixed(1), "s,", raise.mass.toFixed(0), "kg left");
+ * ```
+ */
+export function flyBurn(start, mass, burn, options) {
+    const throttle = burn.throttle ?? 1;
+    const flow = massFlow(burn.engine, throttle);
+    const thrust = flow * burn.engine.exhaustSpeed;
+    let seconds = burn.seconds ?? (burn.dv !== undefined ? burnSeconds(burn.engine, mass, burn.dv, throttle) : NaN);
+    if (!(seconds >= 0) || !Number.isFinite(seconds))
+        throw new RangeError("a burn needs seconds, or a dv and an engine that is lit");
+    const reserve = options.dryMass ?? 0;
+    const longest = flow > 0 ? (mass - reserve) / flow : Infinity;
+    // With nothing held back, a burn that empties the craft has no finite answer: the thrust over the mass grows without limit, and so does the change of speed.
+    if (!(reserve > 0) && seconds >= longest)
+        throw new RangeError("a burn that uses all the mass has no finite change of speed: give a dryMass above zero, and it stops there");
+    const short = seconds > longest;
+    if (short)
+        seconds = Math.max(0, longest);
+    const centre = options.centre ?? ORIGIN;
+    const t0 = start.t;
+    const acceleration = (t, p, v) => {
+        const c = centre(t);
+        const push = directionOf(burn.direction, sub(p, c.position), sub(v, c.velocity));
+        return addScaled(options.gravity(t, p, v), push, thrust / (mass - flow * (t - t0)));
+    };
+    const state = seconds > 0 ? propagate(start, seconds, { step: options.step, method: options.burnMethod ?? "rk4", acceleration }) : start;
+    const end = mass - flow * seconds;
+    return { state, mass: end, seconds, dv: deltaV(burn.engine.exhaustSpeed, mass, end), propellant: mass - end, short };
+}
+/**
+ * Flies a plan: coasts to each burn, starting it so that its middle falls at its planned time, flies it, and coasts on to the end.
+ * @param start The craft at the start.
+ * @param mass Its mass then, kilograms.
+ * @param burns The planned burns, in any order; they must not overlap.
+ * @param end The time to stop, seconds (after the last burn).
+ * @param options The step, the gravity, the centre, the dry mass and the methods.
+ * @returns The craft at `end`, its mass, and what each burn did, in time order.
+ * @example
+ * ```ts
+ * import { elementsOf, exhaustSpeedOf, flyPlan, gravityAt } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const earth = [{ gm: 3.986004418e14, position: [0, 0, 0] as const }];
+ * const engine = { thrust: 91_189, exhaustSpeed: exhaustSpeedOf(314) };
+ * const flown = flyPlan({ t: 0, position: [6_778_000, 0, 0], velocity: [0, 7_669, 0] }, 20_000, [{ at: 600, engine, direction: "prograde", dv: 100 }], 3_600, { step: 5, gravity: (_t, p) => gravityAt(p, earth) });
+ * console.log(((elementsOf(3.986004418e14, flown.state.position, flown.state.velocity).apoapsis - 6_378_137) / 1000).toFixed(0), "km apogee");
+ * ```
+ */
+export function flyPlan(start, mass, burns, end, options) {
+    let state = start;
+    let left = mass;
+    const done = [];
+    const coast = (to) => {
+        if (to < state.t - 1e-9)
+            throw new RangeError(`the plan goes back in time at ${to} s: burns overlap, or one starts before the craft is there`);
+        if (to > state.t)
+            state = propagate(state, to - state.t, { step: options.step, method: options.coastMethod ?? "sy4", acceleration: options.gravity });
+    };
+    for (const burn of [...burns].sort((a, b) => a.at - b.at)) {
+        const lit = burn.engine;
+        const seconds = burn.seconds ?? burnSeconds(lit, left, burn.dv ?? NaN, burn.throttle ?? 1);
+        coast(burnStart(burn.at, seconds));
+        const result = flyBurn(state, left, { ...burn, seconds }, options);
+        done.push(result);
+        state = result.state;
+        left = result.mass;
+    }
+    coast(end);
+    return { state, mass: left, burns: done };
+}

package/dist/physics/elements.d.ts

@@ -0,0 +1,133 @@
+import { type Vec3 } from "./vector.ts";
+/**
+ * A position and a speed, in metres and metres a second, in one frame.
+ *
+ * @example
+ * ```ts
+ * import type { StateVector } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const leo: StateVector = { position: [6_778_000, 0, 0], velocity: [0, 7_669, 0] };
+ * console.log(leo.velocity[1]);
+ * ```
+ */
+export interface StateVector {
+    position: Vec3;
+    velocity: Vec3;
+}
+/**
+ * The shape of an orbit and where on it a craft is, worked out from one position and speed (the osculating elements). Angles in radians, lengths in metres, times in seconds.
+ *
+ * @example
+ * ```ts
+ * import { elementsOf, type Elements } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const orbit: Elements = elementsOf(3.986004418e14, [7_000_000, 0, 0], [0, 7_546, 0]);
+ * console.log(orbit.e.toFixed(4), (orbit.period / 60).toFixed(1));
+ * ```
+ */
+export interface Elements {
+    /** The gravitational parameter the elements were worked with, m^3/s^2. */
+    gm: number;
+    /** Semi-major axis, metres: negative for an open (hyperbolic) path. */
+    a: number;
+    /** Eccentricity: 0 a circle, below 1 an ellipse, above 1 a hyperbola. */
+    e: number;
+    /** Inclination to the frame's x-y plane, 0 to pi. */
+    i: number;
+    /** Longitude of the ascending node, 0 to 2 pi (0 for an orbit in the plane). */
+    node: number;
+    /** Argument of periapsis, from the node, 0 to 2 pi (0 for a circle). */
+    argPeriapsis: number;
+    /** Longitude of periapsis: the node plus the argument of periapsis. */
+    longitudePeriapsis: number;
+    /** True anomaly now: the angle from periapsis to the craft. */
+    trueAnomaly: number;
+    /** Eccentric anomaly now (the hyperbolic anomaly on an open path). */
+    eccentricAnomaly: number;
+    /** Mean anomaly now. */
+    meanAnomaly: number;
+    /** Mean motion, radians a second. */
+    meanMotion: number;
+    /** Time once round, seconds; Infinity for an open path. */
+    period: number;
+    /** Distance of periapsis from the centre, metres. */
+    periapsis: number;
+    /** Distance of apoapsis from the centre, metres; Infinity for an open path. */
+    apoapsis: number;
+    /** Semi-latus rectum `a (1 - e^2)`, metres. */
+    semiLatus: number;
+    /** Seconds to the next periapsis (for an open path, to the one periapsis; negative once it is passed). */
+    timeToPeriapsis: number;
+}
+/**
+ * The eccentric anomaly from the mean anomaly: Kepler's equation `M = E - e sin E` for an ellipse, `M = e sinh E - E` for a hyperbola, solved by Newton's method with each step held to one radian, as Orbiter does.
+ * @param meanAnomaly The mean anomaly, radians.
+ * @param e The eccentricity, 0 or more (not exactly 1).
+ * @returns The eccentric anomaly (the hyperbolic anomaly when `e` is above 1), radians.
+ * @example
+ * ```ts
+ * import { eccentricAnomaly } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(eccentricAnomaly(1, 0.2).toFixed(6), eccentricAnomaly(2, 1.5).toFixed(6));
+ * ```
+ */
+export declare function eccentricAnomaly(meanAnomaly: number, e: number): number;
+/**
+ * The orbital elements of a craft about one body, from its position and speed relative to that body (Orbiter's `Elements::Calculate`).
+ * @param gm The gravitational parameter of the body (plus the craft's, which is nothing for a craft), m^3/s^2.
+ * @param position The craft's position from the body's centre, metres.
+ * @param velocity The craft's speed relative to the body, metres a second.
+ * @returns The elements: shape, plane, where the craft is on it, its period and the time to periapsis.
+ * @example
+ * ```ts
+ * import { elementsOf } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const gto = elementsOf(3.986004418e14, [6_563_000, 0, 0], [0, 10_240, 0]);
+ * console.log(((gto.apoapsis - 6_378_137) / 1000).toFixed(0), "km apogee");
+ * ```
+ */
+export declare function elementsOf(gm: number, position: Vec3, velocity: Vec3): Elements;
+/**
+ * Where a craft on a two-body orbit is a time after its elements were taken, and its speed (Orbiter's `Elements::PosVel`): Kepler's equation, with no other pull.
+ * @param elements The elements, from {@link elementsOf}.
+ * @param seconds The time since the elements were taken, seconds (negative for before).
+ * @returns The position from the body's centre (metres) and the speed (metres a second), in the frame of the elements.
+ * @example
+ * ```ts
+ * import { elementsOf, stateOf } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const orbit = elementsOf(3.986004418e14, [7_000_000, 0, 0], [0, 7_546, 0]);
+ * const later = stateOf(orbit, orbit.period / 2);
+ * console.log((later.position[0] / 1000).toFixed(0), "km");
+ * ```
+ */
+export declare function stateOf(elements: Elements, seconds: number): StateVector;
+/**
+ * Where a craft is, and its speed, when it is at a given true anomaly on its orbit (Orbiter's `Elements::PosVel_TA`).
+ * @param elements The elements, from {@link elementsOf}.
+ * @param trueAnomaly The angle from periapsis, radians (on an open path, only angles the path reaches).
+ * @returns The position from the body's centre (metres) and the speed (metres a second).
+ * @example
+ * ```ts
+ * import { elementsOf, stateAtTrueAnomaly } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const orbit = elementsOf(3.986004418e14, [6_563_000, 0, 0], [0, 10_240, 0]);
+ * const apogee = stateAtTrueAnomaly(orbit, Math.PI);
+ * console.log((apogee.position[0] / 1000).toFixed(0), "km,", Math.hypot(...apogee.velocity).toFixed(0), "m/s");
+ * ```
+ */
+export declare function stateAtTrueAnomaly(elements: Elements, trueAnomaly: number): StateVector;
+/**
+ * How long until a craft reaches a true anomaly on its orbit: Kepler's equation run backwards, as Orbiter's plane-alignment display times the nodes.
+ * @param elements The elements, from {@link elementsOf}.
+ * @param trueAnomaly The angle from periapsis to reach, radians.
+ * @returns Seconds from the time the elements were taken: 0 to one period on a closed orbit (the next time it is there); on an open path, negative if that point is already behind.
+ * @example
+ * ```ts
+ * import { elementsOf, timeToTrueAnomaly } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const orbit = elementsOf(3.986004418e14, [6_563_000, 0, 0], [0, 10_240, 0]);
+ * console.log((timeToTrueAnomaly(orbit, Math.PI) / 3600).toFixed(2), "hours to apogee");
+ * ```
+ */
+export declare function timeToTrueAnomaly(elements: Elements, trueAnomaly: number): number;

package/dist/physics/elements.js

@@ -0,0 +1,239 @@
+// Orbital elements from a position and a speed, and back again after a time: the two-body orbit, closed or open. Pure.
+// Ported from Orbiter (https://github.com/orbitersim/orbiter), Src/Orbiter/Element.cpp, class Elements: Calculate, EccAnomaly,
+// TrueAnomaly_from_EccAnomaly, EccAnomaly_from_TrueAnomaly, MeanAnomaly_from_EccAnomaly, RelPos, Pol2Crt, PosVel and PosVel_TA. Copyright (c) 2000-2026 Martin Schweiger, MIT licence (LICENSES/Orbiter-MIT.txt).
+// Changed in the port: a right-handed frame with z as the pole (Orbiter's is left-handed with y as the pole, so its y and z swap
+// and its H = V x R becomes R x V); no cached state; the Kepler solver may take 64 rounds where Orbiter takes 16, so a long
+// hyperbolic path still converges; an orbit in the equator's plane run backwards (i = 180 degrees) takes the equatorial branch,
+// where Orbiter divides by zero; the inclination, the node, the argument of periapsis and the true anomaly are taken with atan2 in place of
+// Orbiter's acos and sign tests (the same angles, without acos's loss of half the digits next to 0 and pi, worth a metre in low orbit
+// and a kilometre round the Sun).
+import { cross, dot, length } from "./vector.js";
+const TAU = 2 * Math.PI;
+const E_CIRCLE_LIMIT = 1e-8;
+const I_NOINC_LIMIT = 1e-8;
+const ROUNDS = 64;
+const TOLERANCE = 1e-14;
+const posAngle = (angle) => {
+    const a = angle % TAU;
+    return a >= 0 ? a : a + TAU;
+};
+const clampedAcos = (x) => Math.acos(Math.max(-1, Math.min(1, x)));
+const clampStep = (x) => Math.max(-1, Math.min(1, x));
+/**
+ * The eccentric anomaly from the mean anomaly: Kepler's equation `M = E - e sin E` for an ellipse, `M = e sinh E - E` for a hyperbola, solved by Newton's method with each step held to one radian, as Orbiter does.
+ * @param meanAnomaly The mean anomaly, radians.
+ * @param e The eccentricity, 0 or more (not exactly 1).
+ * @returns The eccentric anomaly (the hyperbolic anomaly when `e` is above 1), radians.
+ * @example
+ * ```ts
+ * import { eccentricAnomaly } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(eccentricAnomaly(1, 0.2).toFixed(6), eccentricAnomaly(2, 1.5).toFixed(6));
+ * ```
+ */
+export function eccentricAnomaly(meanAnomaly, e) {
+    const ma = meanAnomaly;
+    let big = ma;
+    if (e < 1) {
+        let res = ma - big + e * Math.sin(big);
+        if (Math.abs(res) > Math.abs(ma)) {
+            big = 0;
+            res = ma;
+        }
+        for (let i = 0; Math.abs(res) > TOLERANCE && i < ROUNDS; i++) {
+            big += clampStep(res / (1 - e * Math.cos(big)));
+            res = ma - big + e * Math.sin(big);
+        }
+    }
+    else {
+        let res = ma - e * Math.sinh(big) + big;
+        if (Math.abs(res) > Math.abs(ma)) {
+            big = 0;
+            res = ma;
+        }
+        for (let i = 0; Math.abs(res) > TOLERANCE && i < ROUNDS; i++) {
+            big += clampStep(res / (e * Math.cosh(big) - 1));
+            res = ma - e * Math.sinh(big) + big;
+        }
+    }
+    return big;
+}
+const trueFromEccentric = (ea, e) => {
+    if (e < 1)
+        return 2 * Math.atan(Math.sqrt((1 + e) / (1 - e)) * Math.tan(0.5 * ea));
+    const chea = Math.cosh(ea);
+    const tra = clampedAcos((e - chea) / (e * chea - 1));
+    return ea >= 0 ? tra : -tra;
+};
+/**
+ * The orbital elements of a craft about one body, from its position and speed relative to that body (Orbiter's `Elements::Calculate`).
+ * @param gm The gravitational parameter of the body (plus the craft's, which is nothing for a craft), m^3/s^2.
+ * @param position The craft's position from the body's centre, metres.
+ * @param velocity The craft's speed relative to the body, metres a second.
+ * @returns The elements: shape, plane, where the craft is on it, its period and the time to periapsis.
+ * @example
+ * ```ts
+ * import { elementsOf } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const gto = elementsOf(3.986004418e14, [6_563_000, 0, 0], [0, 10_240, 0]);
+ * console.log(((gto.apoapsis - 6_378_137) / 1000).toFixed(0), "km apogee");
+ * ```
+ */
+export function elementsOf(gm, position, velocity) {
+    const v2 = dot(velocity, velocity);
+    const r = length(position);
+    const h = cross(position, velocity);
+    const hl = length(h);
+    const rv = dot(position, velocity);
+    const a = (r * gm) / (2 * gm - r * v2);
+    const k = 1 / r - 1 / a;
+    const q = rv / gm;
+    const ev = [position[0] * k - velocity[0] * q, position[1] * k - velocity[1] * q, position[2] * k - velocity[2] * q];
+    const e = length(ev);
+    const closed = e < 1;
+    const hxy = Math.hypot(h[0], h[1]);
+    const i = Math.atan2(hxy, h[2]);
+    const hu = [h[0] / hl, h[1] / hl, h[2] / hl];
+    /** The angle from `from` to `to` in the orbit's plane, in the direction of motion, 0 to 2 pi. */
+    const along = (from, to) => posAngle(Math.atan2(dot(cross(from, to), hu), dot(from, to)));
+    const semiLatus = Math.max(0, a * (1 - e * e));
+    const meanMotion = closed ? Math.sqrt(gm / (a * a * a)) : Math.sqrt(gm / (-a * a * a));
+    const period = closed ? TAU / meanMotion : Infinity;
+    const inclined = i > I_NOINC_LIMIT && hxy > I_NOINC_LIMIT * hl;
+    const n = inclined ? [-h[1] / hxy, h[0] / hxy, 0] : [1, 0, 0];
+    const node = inclined ? posAngle(Math.atan2(n[1], n[0])) : 0;
+    let argPeriapsis = 0;
+    if (e > E_CIRCLE_LIMIT) {
+        if (inclined) {
+            argPeriapsis = along(n, ev);
+        }
+        else {
+            argPeriapsis = Math.atan2(ev[1], ev[0]);
+            if (argPeriapsis < 0)
+                argPeriapsis += TAU;
+        }
+    }
+    let longitudePeriapsis = node + argPeriapsis;
+    if (longitudePeriapsis >= TAU)
+        longitudePeriapsis -= TAU;
+    const trueAnomaly = along(e > E_CIRCLE_LIMIT ? ev : n, position);
+    let ea;
+    let ma;
+    let timeToPeriapsis;
+    if (closed) {
+        ea = e > E_CIRCLE_LIMIT ? Math.atan2(rv * Math.sqrt(a / gm), a - r) : trueAnomaly;
+        ma = ea - e * Math.sin(ea);
+        timeToPeriapsis = -ma / meanMotion;
+        if (timeToPeriapsis < 0)
+            timeToPeriapsis += period;
+    }
+    else {
+        const cosTrue = Math.cos(trueAnomaly);
+        ea = Math.acosh((e + cosTrue) / (1 + e * cosTrue));
+        if (trueAnomaly >= Math.PI)
+            ea = -ea;
+        ma = e * Math.sinh(ea) - ea;
+        timeToPeriapsis = -ma / meanMotion;
+    }
+    return {
+        gm,
+        a,
+        e,
+        i,
+        node,
+        argPeriapsis,
+        longitudePeriapsis,
+        trueAnomaly,
+        eccentricAnomaly: ea,
+        meanAnomaly: ma,
+        meanMotion,
+        period,
+        periapsis: a - a * e,
+        apoapsis: closed ? a + a * e : Infinity,
+        semiLatus,
+        timeToPeriapsis,
+    };
+}
+/** A point at distance `r` and angle `u` from the node, turned into the frame (Orbiter's `Pol2Crt`). */
+function toFrame(el, r, u) {
+    const so = Math.sin(u);
+    const co = Math.cos(u);
+    const st = Math.sin(el.node);
+    const ct = Math.cos(el.node);
+    const ci = Math.cos(el.i);
+    return [r * (ct * co - st * so * ci), r * (st * co + ct * so * ci), r * so * Math.sin(el.i)];
+}
+/**
+ * Where a craft on a two-body orbit is a time after its elements were taken, and its speed (Orbiter's `Elements::PosVel`): Kepler's equation, with no other pull.
+ * @param elements The elements, from {@link elementsOf}.
+ * @param seconds The time since the elements were taken, seconds (negative for before).
+ * @returns The position from the body's centre (metres) and the speed (metres a second), in the frame of the elements.
+ * @example
+ * ```ts
+ * import { elementsOf, stateOf } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const orbit = elementsOf(3.986004418e14, [7_000_000, 0, 0], [0, 7_546, 0]);
+ * const later = stateOf(orbit, orbit.period / 2);
+ * console.log((later.position[0] / 1000).toFixed(0), "km");
+ * ```
+ */
+export function stateOf(elements, seconds) {
+    const { e } = elements;
+    const ma = elements.meanAnomaly + elements.meanMotion * seconds;
+    const ta = e < E_CIRCLE_LIMIT ? ma : trueFromEccentric(eccentricAnomaly(e < 1 ? posAngle(ma) : ma, e), e);
+    return stateAtTrueAnomaly(elements, ta);
+}
+/**
+ * Where a craft is, and its speed, when it is at a given true anomaly on its orbit (Orbiter's `Elements::PosVel_TA`).
+ * @param elements The elements, from {@link elementsOf}.
+ * @param trueAnomaly The angle from periapsis, radians (on an open path, only angles the path reaches).
+ * @returns The position from the body's centre (metres) and the speed (metres a second).
+ * @example
+ * ```ts
+ * import { elementsOf, stateAtTrueAnomaly } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const orbit = elementsOf(3.986004418e14, [6_563_000, 0, 0], [0, 10_240, 0]);
+ * const apogee = stateAtTrueAnomaly(orbit, Math.PI);
+ * console.log((apogee.position[0] / 1000).toFixed(0), "km,", Math.hypot(...apogee.velocity).toFixed(0), "m/s");
+ * ```
+ */
+export function stateAtTrueAnomaly(elements, trueAnomaly) {
+    const { e, gm, semiLatus } = elements;
+    const ta = trueAnomaly;
+    const r = semiLatus / (1 + e * Math.cos(ta));
+    const muh = Math.sqrt(gm / semiLatus);
+    const vx = -muh * Math.sin(ta);
+    const vz = muh * (e + Math.cos(ta));
+    return { position: toFrame(elements, r, ta + elements.argPeriapsis), velocity: toFrame(elements, Math.hypot(vx, vz), Math.atan2(vz, vx) + elements.argPeriapsis) };
+}
+/** The mean anomaly at a true anomaly (Orbiter's `MeanAnomaly_from_TrueAnomaly`, through `EccAnomaly_from_TrueAnomaly` and `MeanAnomaly_from_EccAnomaly`). */
+function meanFromTrue(ta, e) {
+    if (e < 1) {
+        const ea = 2 * Math.atan(Math.tan(0.5 * ta) / Math.sqrt((1 + e) / (1 - e)));
+        return ea - e * Math.sin(ea);
+    }
+    const t = ta - TAU * Math.round(ta / TAU);
+    const cosTa = Math.cos(t);
+    const ea = Math.acosh((e + cosTa) / (e * cosTa + 1)) * (t >= 0 ? 1 : -1);
+    return e * Math.sinh(ea) - ea;
+}
+/**
+ * How long until a craft reaches a true anomaly on its orbit: Kepler's equation run backwards, as Orbiter's plane-alignment display times the nodes.
+ * @param elements The elements, from {@link elementsOf}.
+ * @param trueAnomaly The angle from periapsis to reach, radians.
+ * @returns Seconds from the time the elements were taken: 0 to one period on a closed orbit (the next time it is there); on an open path, negative if that point is already behind.
+ * @example
+ * ```ts
+ * import { elementsOf, timeToTrueAnomaly } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const orbit = elementsOf(3.986004418e14, [6_563_000, 0, 0], [0, 10_240, 0]);
+ * console.log((timeToTrueAnomaly(orbit, Math.PI) / 3600).toFixed(2), "hours to apogee");
+ * ```
+ */
+export function timeToTrueAnomaly(elements, trueAnomaly) {
+    const { e, meanMotion } = elements;
+    if (e < E_CIRCLE_LIMIT)
+        return posAngle(trueAnomaly - elements.meanAnomaly) / meanMotion;
+    const dm = meanFromTrue(trueAnomaly, e) - elements.meanAnomaly;
+    return e < 1 ? posAngle(dm) / meanMotion : dm / meanMotion;
+}

package/dist/physics/gravity.d.ts

@@ -0,0 +1,53 @@
+import { type Vec3 } from "./vector.ts";
+/**
+ * A body's flattening, as the zonal terms of its gravity field: `J2`, and if given `J3` and `J4`, which is as far as Orbiter reads them.
+ *
+ * @example
+ * ```ts
+ * import type { Zonal } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const earth: Zonal = { radius: 6_378_137, pole: [0, 0, 1], j: [0.00108262545] };
+ * console.log(earth.j[0]);
+ * ```
+ */
+export interface Zonal {
+    /** The reference radius the coefficients are given for (usually the equatorial radius), metres. */
+    radius: number;
+    /** The body's north pole, a unit vector in the frame. */
+    pole: Vec3;
+    /** `[J2]`, `[J2, J3]` or `[J2, J3, J4]`, unnormalised. Further terms are ignored. */
+    j: readonly number[];
+}
+/**
+ * One body that pulls: its gravitational parameter, where it is at the time asked, and its flattening if it matters.
+ *
+ * @example
+ * ```ts
+ * import type { GravityBody } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const sun: GravityBody = { gm: 1.32712440041279419e20, position: [0, 0, 0] };
+ * console.log(sun.gm);
+ * ```
+ */
+export interface GravityBody {
+    /** Gravitational parameter, m^3/s^2. */
+    gm: number;
+    /** Where the body's centre is, metres, in the craft's frame. */
+    position: Vec3;
+    zonal?: Zonal;
+}
+/**
+ * The acceleration gravity gives a craft at a place: the sum of `gm (body - craft) / d^3` over the bodies, plus each flattened body's zonal terms (Orbiter's `SingleGacc` summed as in `PlanetarySystem::Gacc`).
+ * For the best answer give the bodies in a frame that is not itself accelerating, such as the solar system's barycentre; a frame centred on a body that the others pull leaves out that pull on the frame.
+ * @param position The craft's position, metres.
+ * @param bodies The bodies that pull, at the same time and in the same frame.
+ * @returns The acceleration, metres a second squared.
+ * @example
+ * ```ts
+ * import { gravityAt } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const g = gravityAt([6_378_137, 0, 0], [{ gm: 3.986004418e14, position: [0, 0, 0] }]);
+ * console.log(g[0].toFixed(3), "m/s^2");
+ * ```
+ */
+export declare function gravityAt(position: Vec3, bodies: readonly GravityBody[]): Vec3;

package/dist/physics/gravity.js

@@ -0,0 +1,78 @@
+// The pull on a craft from the bodies of a scene: each a point mass, and a body's flattening (its J2, J3 and J4 terms) where the caller gives it. Pure.
+// Ported from Orbiter (https://github.com/orbitersim/orbiter), Src/Orbiter/Psys.cpp: SingleGacc, the J-coefficient branch of
+// SingleGacc_perturbation, and PlanetarySystem::Gacc. Copyright (c) 2000-2026 Martin Schweiger, MIT licence (LICENSES/Orbiter-MIT.txt).
+// Changed in the port: a right-handed frame; Orbiter's polar unit vector (er x (er x pole)) is written out as -(pole - s r) / cos(latitude),
+// and the cosine of the latitude in each polar term cancels it, so nothing is divided by zero over a pole; the bodies are a list the
+// caller hands in, at the time asked, in place of Orbiter's planetary system; Orbiter's spherical-harmonic (Pines) model is not ported.
+import {} from "./vector.js";
+const EPS = 1e-10;
+/** The pull of a flattened body beyond its point mass, at `offset` (the craft from the body's centre, metres), at distance `d`. */
+function zonalPull(gm, zonal, offset, d) {
+    const [j2 = 0, j3 = 0, j4 = 0] = zonal.j;
+    const rr = zonal.radius / d;
+    let rrn = rr * rr;
+    let jn = j2 * rrn;
+    if (Math.abs(jn) <= EPS)
+        return [0, 0, 0];
+    const r = [offset[0] / d, offset[1] / d, offset[2] / d];
+    const p = zonal.pole;
+    const s = r[0] * p[0] + r[1] * p[1] + r[2] * p[2];
+    const s2 = s * s;
+    let radial = 1.5 * jn * (1 - 3 * s2);
+    let polar = 3 * jn * s;
+    if (zonal.j.length > 1) {
+        rrn *= rr;
+        jn = j3 * rrn;
+        if (Math.abs(jn) > EPS) {
+            radial += 2 * jn * s * (3 - 5 * s2);
+            polar += 1.5 * jn * (-1 + 5 * s2);
+            if (zonal.j.length > 2) {
+                rrn *= rr;
+                jn = j4 * rrn;
+                if (Math.abs(jn) > EPS) {
+                    radial += -0.625 * jn * (3 + s2 * (-30 + 35 * s2));
+                    polar += 2.5 * jn * s * (-3 + 7 * s2);
+                }
+            }
+        }
+    }
+    const t0 = gm / (d * d);
+    const along = radial - polar * s;
+    return [-t0 * (along * r[0] + polar * p[0]), -t0 * (along * r[1] + polar * p[1]), -t0 * (along * r[2] + polar * p[2])];
+}
+/**
+ * The acceleration gravity gives a craft at a place: the sum of `gm (body - craft) / d^3` over the bodies, plus each flattened body's zonal terms (Orbiter's `SingleGacc` summed as in `PlanetarySystem::Gacc`).
+ * For the best answer give the bodies in a frame that is not itself accelerating, such as the solar system's barycentre; a frame centred on a body that the others pull leaves out that pull on the frame.
+ * @param position The craft's position, metres.
+ * @param bodies The bodies that pull, at the same time and in the same frame.
+ * @returns The acceleration, metres a second squared.
+ * @example
+ * ```ts
+ * import { gravityAt } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const g = gravityAt([6_378_137, 0, 0], [{ gm: 3.986004418e14, position: [0, 0, 0] }]);
+ * console.log(g[0].toFixed(3), "m/s^2");
+ * ```
+ */
+export function gravityAt(position, bodies) {
+    let ax = 0;
+    let ay = 0;
+    let az = 0;
+    for (const body of bodies) {
+        const dx = body.position[0] - position[0];
+        const dy = body.position[1] - position[1];
+        const dz = body.position[2] - position[2];
+        const d = Math.hypot(dx, dy, dz);
+        const k = body.gm / (d * d * d);
+        ax += dx * k;
+        ay += dy * k;
+        az += dz * k;
+        if (body.zonal) {
+            const extra = zonalPull(body.gm, body.zonal, [-dx, -dy, -dz], d);
+            ax += extra[0];
+            ay += extra[1];
+            az += extra[2];
+        }
+    }
+    return [ax, ay, az];
+}