@johnmorrisdotca/uchusen-rockets 0.19.1 → 0.20.0

package/dist/physics/index.d.ts

@@ -0,0 +1,17 @@
+export type { Vec3 } from "./vector.ts";
+export { eccentricAnomaly, elementsOf, stateAtTrueAnomaly, stateOf, timeToTrueAnomaly } from "./elements.ts";
+export type { Elements, StateVector } from "./elements.ts";
+export { gravityAt } from "./gravity.ts";
+export type { GravityBody, Zonal } from "./gravity.ts";
+export { path, propagate, step } from "./propagate.ts";
+export type { Acceleration, Method, PropagateOptions, State } from "./propagate.ts";
+export { burnSeconds, deltaV, exhaustSpeedOf, massAfter, massFlow, thrustAt } from "./rocket.ts";
+export type { Engine } from "./rocket.ts";
+export { burnStart, directionOf, flyBurn, flyPlan, impulse } from "./burns.ts";
+export type { Burn, BurnResult, Centre, Direction, FlyOptions, PlannedBurn } from "./burns.ts";
+export { biElliptic, crossings, nodes, planeChange, relativeInclination, speedChangeFor } from "./transfers.ts";
+export type { Node } from "./transfers.ts";
+export { angularAcceleration, fireFor, gravityGradientTorque, holdDirection, killRotation, quatFromAxisAngle, rotateVector, spinFor, stepCraft, stepSpin, thrusterPush, torqueLimits, turnBy, unrotateVector } from "./attitude.ts";
+export type { Craft, CraftForces, Quat, Spin, Thruster, Torque, TorqueLimits } from "./attitude.ts";
+export { airVelocity, atmosphereAt, dragAcceleration, dynamicPressure, EARTH_ATMOSPHERE, MARS_ATMOSPHERE, machNumber, standardAtmosphere, VENUS_ATMOSPHERE } from "./atmosphere.ts";
+export type { Air, AtmosphereLayer, AtmosphereModel } from "./atmosphere.ts";

package/dist/physics/index.js

@@ -0,0 +1,8 @@
+export { eccentricAnomaly, elementsOf, stateAtTrueAnomaly, stateOf, timeToTrueAnomaly } from "./elements.js";
+export { gravityAt } from "./gravity.js";
+export { path, propagate, step } from "./propagate.js";
+export { burnSeconds, deltaV, exhaustSpeedOf, massAfter, massFlow, thrustAt } from "./rocket.js";
+export { burnStart, directionOf, flyBurn, flyPlan, impulse } from "./burns.js";
+export { biElliptic, crossings, nodes, planeChange, relativeInclination, speedChangeFor } from "./transfers.js";
+export { angularAcceleration, fireFor, gravityGradientTorque, holdDirection, killRotation, quatFromAxisAngle, rotateVector, spinFor, stepCraft, stepSpin, thrusterPush, torqueLimits, turnBy, unrotateVector } from "./attitude.js";
+export { airVelocity, atmosphereAt, dragAcceleration, dynamicPressure, EARTH_ATMOSPHERE, MARS_ATMOSPHERE, machNumber, standardAtmosphere, VENUS_ATMOSPHERE } from "./atmosphere.js";

package/dist/physics/propagate.d.ts

@@ -0,0 +1,110 @@
+import { type Vec3 } from "./vector.ts";
+/**
+ * Where a craft is and how fast it goes at a time: seconds from any start the caller picks, metres and metres a second.
+ *
+ * @example
+ * ```ts
+ * import type { State } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const start: State = { t: 0, position: [6_778_000, 0, 0], velocity: [0, 7_669, 0] };
+ * console.log(start.t);
+ * ```
+ */
+export interface State {
+    t: number;
+    position: Vec3;
+    velocity: Vec3;
+}
+/**
+ * What pulls or pushes the craft: its acceleration (metres a second squared) at a time, place and speed. Gravity from the scene's bodies is `gravityAt(position, bodiesAt(t))`; an engine adds its thrust over the craft's mass.
+ *
+ * @example
+ * ```ts
+ * import { gravityAt, type Acceleration } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const earthOnly: Acceleration = (_t, position) => gravityAt(position, [{ gm: 3.986004418e14, position: [0, 0, 0] }]);
+ * console.log(earthOnly(0, [7_000_000, 0, 0], [0, 0, 0])[0].toFixed(3));
+ * ```
+ */
+export type Acceleration = (t: number, position: Vec3, velocity: Vec3) => Vec3;
+/**
+ * How a step is taken. `rk4` is the classic fourth-order Runge-Kutta, right for forces that depend on the speed (drag). `sy2`, `sy4`, `sy6` and `sy8` are symplectic (leapfrog and Yoshida's fourth, sixth and eighth orders): for gravity they keep the energy of an orbit from drifting over many turns.
+ *
+ * @example
+ * ```ts
+ * import type { Method } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const longCoast: Method = "sy4";
+ * console.log(longCoast);
+ * ```
+ */
+export type Method = "rk4" | "sy2" | "sy4" | "sy6" | "sy8";
+/**
+ * One step of `h` seconds.
+ * @param state Where the craft is now.
+ * @param h The step, seconds (negative to go back in time).
+ * @param acceleration What pulls or pushes the craft.
+ * @param method How the step is taken; `sy4` when left out.
+ * @returns Where the craft is `h` seconds later.
+ * @example
+ * ```ts
+ * import { gravityAt, step } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const earth = [{ gm: 3.986004418e14, position: [0, 0, 0] as const }];
+ * const next = step({ t: 0, position: [6_778_000, 0, 0], velocity: [0, 7_669, 0] }, 10, (_t, p) => gravityAt(p, earth));
+ * console.log(next.t, (next.position[1] / 1000).toFixed(2), "km");
+ * ```
+ */
+export declare function step(state: State, h: number, acceleration: Acceleration, method?: Method): State;
+/**
+ * How to propagate: the step, what pulls, and the method.
+ *
+ * @example
+ * ```ts
+ * import { gravityAt, type PropagateOptions } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const options: PropagateOptions = { step: 30, method: "sy4", acceleration: (_t, p) => gravityAt(p, [{ gm: 3.986004418e14, position: [0, 0, 0] }]) };
+ * console.log(options.step);
+ * ```
+ */
+export interface PropagateOptions {
+    /** The longest step, seconds (positive). The last step is shortened to land on the time asked. */
+    step: number;
+    acceleration: Acceleration;
+    /** `sy4` when left out. */
+    method?: Method;
+}
+/**
+ * Moves a craft forward (or back) by a span of time, in steps no longer than `options.step`.
+ * @param start Where the craft is at the start.
+ * @param seconds How long, seconds (negative to go back).
+ * @param options The step, what pulls and the method.
+ * @returns Where the craft is at `start.t + seconds`.
+ * @example
+ * ```ts
+ * import { gravityAt, propagate } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const earth = [{ gm: 3.986004418e14, position: [0, 0, 0] as const }];
+ * const start = { t: 0, position: [7_000_000, 0, 0] as const, velocity: [0, 7_546.05, 0] as const };
+ * const end = propagate(start, 5_828.5, { step: 10, acceleration: (_t, p) => gravityAt(p, earth) });
+ * console.log((end.position[0] / 1000).toFixed(1), "km, once round");
+ * ```
+ */
+export declare function propagate(start: State, seconds: number, options: PropagateOptions): State;
+/**
+ * The path a craft takes: its state at `points + 1` evenly spaced times from the start to `start.t + seconds`, for drawing an orbit or a trajectory.
+ * @param start Where the craft is at the start.
+ * @param seconds How long, seconds.
+ * @param points How many stretches the path is cut into (1 or more).
+ * @param options The step, what pulls and the method.
+ * @returns The states, the first being `start`.
+ * @example
+ * ```ts
+ * import { gravityAt, path } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const earth = [{ gm: 3.986004418e14, position: [0, 0, 0] as const }];
+ * const line = path({ t: 0, position: [7_000_000, 0, 0], velocity: [0, 7_546, 0] }, 5_828, 8, { step: 10, acceleration: (_t, p) => gravityAt(p, earth) });
+ * console.log(line.length);
+ * ```
+ */
+export declare function path(start: State, seconds: number, points: number, options: PropagateOptions): State[];

package/dist/physics/propagate.js

@@ -0,0 +1,122 @@
+// Moving a craft forward in time under any acceleration (gravity from the scene's bodies, an engine, or both), in fixed steps. Pure: the caller says how long, and nothing reads a clock.
+// Ported from Orbiter (https://github.com/orbitersim/orbiter), Src/Orbiter/BodyIntegrator.cpp: the linear parts of RK4_LinAng and of the
+// symplectic SY2_LinAng, SY4_LinAng, SY6_LinAng and SY8_LinAng (Yoshida's coefficients, as Orbiter has them). Copyright (c) 2000-2026
+// Martin Schweiger, MIT licence (LICENSES/Orbiter-MIT.txt). Changed in the port: the turning of the craft is left to a later step; the
+// four symplectic methods share one loop built from their weights; each step starts from a fresh acceleration where Orbiter reuses the
+// last step's; the time of each evaluation is absolute where Orbiter gives a fraction of its frame.
+import { addScaled } from "./vector.js";
+/** Yoshida's weights from the middle out, after the centre one, as Orbiter's SY4, SY6 and SY8 hold them. */
+const CBRT2 = 1.25992104989487319066654436028;
+const WEIGHTS = {
+    sy2: [],
+    sy4: [1 / (2 - CBRT2)],
+    sy6: [-0.117767998417887e1, 0.235573213359357e0, 0.784513610477560e0],
+    sy8: [0.311790812418427e0, -0.155946803821447e1, -0.167896928259640e1, 0.166335809963315e1, -0.106458714789183e1, 0.136934946416871e1, 0.629030650210433e0],
+};
+/** The kicks `d` and the drifts `c` of a symmetric symplectic method: `d` is the weights mirrored round the centre one, each drift the mean of the kicks beside it. */
+function kicksAndDrifts(weights) {
+    const centre = 1 - 2 * weights.reduce((sum, w) => sum + w, 0);
+    const d = [...[...weights].reverse(), centre, ...weights];
+    const c = [d[0] / 2, ...d.slice(1).map((w, i) => (d[i] + w) / 2), d[d.length - 1] / 2];
+    return { d, c };
+}
+const SYMPLECTIC = Object.fromEntries(Object.entries(WEIGHTS).map(([name, weights]) => [name, kicksAndDrifts(weights)]));
+function rk4(state, h, acceleration) {
+    const { t, position: p, velocity: v } = state;
+    const h2 = h / 2;
+    const a0 = acceleration(t, p, v);
+    const va = addScaled(v, a0, h2);
+    const a1 = acceleration(t + h2, addScaled(p, v, h2), va);
+    const vb = addScaled(v, a1, h2);
+    const a2 = acceleration(t + h2, addScaled(p, va, h2), vb);
+    const vc = addScaled(v, a2, h);
+    const a3 = acceleration(t + h, addScaled(p, vb, h), vc);
+    const h6 = h / 6;
+    const sum = (x0, x1, x2, x3, k) => x0[k] + 2 * (x1[k] + x2[k]) + x3[k];
+    return {
+        t: t + h,
+        position: [p[0] + sum(v, va, vb, vc, 0) * h6, p[1] + sum(v, va, vb, vc, 1) * h6, p[2] + sum(v, va, vb, vc, 2) * h6],
+        velocity: [v[0] + sum(a0, a1, a2, a3, 0) * h6, v[1] + sum(a0, a1, a2, a3, 1) * h6, v[2] + sum(a0, a1, a2, a3, 2) * h6],
+    };
+}
+function symplectic(state, h, acceleration, method) {
+    const { c, d } = SYMPLECTIC[method];
+    let position = state.position;
+    let velocity = state.velocity;
+    let section = 0;
+    for (let i = 0; i < c.length; i++) {
+        position = addScaled(position, velocity, h * c[i]);
+        section += c[i];
+        if (i < d.length)
+            velocity = addScaled(velocity, acceleration(state.t + section * h, position, velocity), h * d[i]);
+    }
+    return { t: state.t + h, position, velocity };
+}
+/**
+ * One step of `h` seconds.
+ * @param state Where the craft is now.
+ * @param h The step, seconds (negative to go back in time).
+ * @param acceleration What pulls or pushes the craft.
+ * @param method How the step is taken; `sy4` when left out.
+ * @returns Where the craft is `h` seconds later.
+ * @example
+ * ```ts
+ * import { gravityAt, step } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const earth = [{ gm: 3.986004418e14, position: [0, 0, 0] as const }];
+ * const next = step({ t: 0, position: [6_778_000, 0, 0], velocity: [0, 7_669, 0] }, 10, (_t, p) => gravityAt(p, earth));
+ * console.log(next.t, (next.position[1] / 1000).toFixed(2), "km");
+ * ```
+ */
+export function step(state, h, acceleration, method = "sy4") {
+    return method === "rk4" ? rk4(state, h, acceleration) : symplectic(state, h, acceleration, method);
+}
+/**
+ * Moves a craft forward (or back) by a span of time, in steps no longer than `options.step`.
+ * @param start Where the craft is at the start.
+ * @param seconds How long, seconds (negative to go back).
+ * @param options The step, what pulls and the method.
+ * @returns Where the craft is at `start.t + seconds`.
+ * @example
+ * ```ts
+ * import { gravityAt, propagate } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const earth = [{ gm: 3.986004418e14, position: [0, 0, 0] as const }];
+ * const start = { t: 0, position: [7_000_000, 0, 0] as const, velocity: [0, 7_546.05, 0] as const };
+ * const end = propagate(start, 5_828.5, { step: 10, acceleration: (_t, p) => gravityAt(p, earth) });
+ * console.log((end.position[0] / 1000).toFixed(1), "km, once round");
+ * ```
+ */
+export function propagate(start, seconds, options) {
+    if (!(options.step > 0))
+        throw new RangeError("step must be a positive number of seconds");
+    const count = Math.max(1, Math.ceil(Math.abs(seconds) / options.step - 1e-9));
+    const h = seconds / count;
+    let state = start;
+    for (let i = 0; i < count; i++)
+        state = step(state, h, options.acceleration, options.method);
+    return { ...state, t: start.t + seconds };
+}
+/**
+ * The path a craft takes: its state at `points + 1` evenly spaced times from the start to `start.t + seconds`, for drawing an orbit or a trajectory.
+ * @param start Where the craft is at the start.
+ * @param seconds How long, seconds.
+ * @param points How many stretches the path is cut into (1 or more).
+ * @param options The step, what pulls and the method.
+ * @returns The states, the first being `start`.
+ * @example
+ * ```ts
+ * import { gravityAt, path } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const earth = [{ gm: 3.986004418e14, position: [0, 0, 0] as const }];
+ * const line = path({ t: 0, position: [7_000_000, 0, 0], velocity: [0, 7_546, 0] }, 5_828, 8, { step: 10, acceleration: (_t, p) => gravityAt(p, earth) });
+ * console.log(line.length);
+ * ```
+ */
+export function path(start, seconds, points, options) {
+    const parts = Math.max(1, Math.floor(points));
+    const states = [start];
+    for (let i = 1; i <= parts; i++)
+        states.push(propagate(states[i - 1], seconds / parts, options));
+    return states;
+}

package/dist/physics/rocket.d.ts

@@ -0,0 +1,105 @@
+/**
+ * A rocket engine as Orbiter describes a thruster: its thrust in vacuum, its exhaust speed in vacuum and, if it loses thrust in air, the exhaust speed at a reference pressure.
+ *
+ * @example
+ * ```ts
+ * import { exhaustSpeedOf, type Engine } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const sps: Engine = { thrust: 91_189, exhaustSpeed: exhaustSpeedOf(314) };
+ * console.log(sps.exhaustSpeed.toFixed(0), "m/s");
+ * ```
+ */
+export interface Engine {
+    /** Thrust in vacuum at full throttle, newtons. */
+    thrust: number;
+    /** Exhaust speed in vacuum, metres a second (specific impulse times standard gravity). */
+    exhaustSpeed: number;
+    /** The exhaust speed (metres a second) at a pressure (pascals), such as at sea level, for an engine that loses thrust in air. Left out, the thrust is the same at every pressure. */
+    reference?: {
+        exhaustSpeed: number;
+        pressure: number;
+    };
+}
+/**
+ * An exhaust speed from a specific impulse: `isp g0`.
+ * @param ispSeconds The specific impulse, seconds.
+ * @returns The exhaust speed, metres a second.
+ * @example
+ * ```ts
+ * import { exhaustSpeedOf } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(exhaustSpeedOf(311).toFixed(1));
+ * ```
+ */
+export declare const exhaustSpeedOf: (ispSeconds: number) => number;
+/**
+ * The propellant an engine burns, kilograms a second: its vacuum thrust over its vacuum exhaust speed, times the throttle. In air the flow stays the same and the thrust falls (see {@link thrustAt}), as in Orbiter.
+ * @param engine The engine.
+ * @param throttle 0 to 1; 1 when left out.
+ * @returns The mass flow, kg/s.
+ * @example
+ * ```ts
+ * import { exhaustSpeedOf, massFlow } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(massFlow({ thrust: 91_189, exhaustSpeed: exhaustSpeedOf(314) }).toFixed(2), "kg/s");
+ * ```
+ */
+export declare const massFlow: (engine: Engine, throttle?: number) => number;
+/**
+ * An engine's thrust at an outside pressure: the vacuum thrust times `max(0, 1 - p (v0 - vref) / (pref v0))`, Orbiter's straight-line model through the vacuum and the reference exhaust speeds.
+ * @param engine The engine.
+ * @param pressure The outside pressure, pascals (0 in space).
+ * @param throttle 0 to 1; 1 when left out.
+ * @returns The thrust, newtons.
+ * @example
+ * ```ts
+ * import { exhaustSpeedOf, thrustAt } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const engine = { thrust: 1_000_000, exhaustSpeed: exhaustSpeedOf(330), reference: { exhaustSpeed: exhaustSpeedOf(300), pressure: 101_325 } };
+ * console.log(thrustAt(engine, 0), thrustAt(engine, 101_325).toFixed(0));
+ * ```
+ */
+export declare function thrustAt(engine: Engine, pressure: number, throttle?: number): number;
+/**
+ * The rocket equation (Tsiolkovsky's): the speed a burn gives, `v ln(m0 / m1)`.
+ * @param exhaustSpeed The exhaust speed, metres a second.
+ * @param startMass The mass before the burn, kilograms.
+ * @param endMass The mass after it, kilograms (more than 0, at most `startMass`).
+ * @returns The change of speed, metres a second.
+ * @example
+ * ```ts
+ * import { deltaV, exhaustSpeedOf } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(deltaV(exhaustSpeedOf(314), 30_000, 20_000).toFixed(0), "m/s");
+ * ```
+ */
+export declare const deltaV: (exhaustSpeed: number, startMass: number, endMass: number) => number;
+/**
+ * The rocket equation turned round: the mass left after a change of speed, `m0 exp(-dv / v)`.
+ * @param exhaustSpeed The exhaust speed, metres a second.
+ * @param startMass The mass before the burn, kilograms.
+ * @param dv The change of speed, metres a second.
+ * @returns The mass after the burn, kilograms; `startMass - massAfter(...)` is the propellant burned.
+ * @example
+ * ```ts
+ * import { exhaustSpeedOf, massAfter } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log((30_000 - massAfter(exhaustSpeedOf(314), 30_000, 1_000)).toFixed(0), "kg burned");
+ * ```
+ */
+export declare const massAfter: (exhaustSpeed: number, startMass: number, dv: number) => number;
+/**
+ * How long an engine must burn, at a steady throttle in vacuum, to change a craft's speed by `dv`: the propellant the rocket equation asks for over the engine's mass flow.
+ * @param engine The engine.
+ * @param startMass The mass before the burn, kilograms.
+ * @param dv The change of speed, metres a second.
+ * @param throttle 0 to 1; 1 when left out.
+ * @returns The burn's length, seconds (Infinity at zero throttle).
+ * @example
+ * ```ts
+ * import { burnSeconds, exhaustSpeedOf } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(burnSeconds({ thrust: 91_189, exhaustSpeed: exhaustSpeedOf(314) }, 30_000, 1_000).toFixed(1), "s");
+ * ```
+ */
+export declare function burnSeconds(engine: Engine, startMass: number, dv: number, throttle?: number): number;

package/dist/physics/rocket.js

@@ -0,0 +1,102 @@
+// An engine's thrust and the propellant it burns, and the rocket equation: what a burn changes the speed by, the mass left and how long it takes. Pure.
+// Ported from Orbiter (https://github.com/orbitersim/orbiter): the propellant flow `thrust / isp0` of Vessel::UpdateThrustForces and the
+// thrust's scaling in air of ThrusterAtmScale (Src/Orbiter/Vessel.cpp and Vessel.h, with the pfac of Vessel::CreateThruster), and the
+// rocket equation `isp * log(m0 / (m0 - m))` of the DeltaGlider's fuel display (Src/Vessel/DeltaGlider/FuelMfd.cpp).
+// Copyright (c) 2000-2026 Martin Schweiger, MIT licence (LICENSES/Orbiter-MIT.txt). Orbiter's "Isp" is an exhaust speed in metres a second,
+// as `exhaustSpeed` is here; `exhaustSpeedOf` turns a specific impulse in seconds into one. Changed in the port: functions of plain
+// numbers in place of a vessel's thrusters and tanks; a tank's efficiency factor is left out.
+import { G0 } from "../journey/constants.js";
+const clampThrottle = (throttle) => Math.max(0, Math.min(1, throttle));
+/**
+ * An exhaust speed from a specific impulse: `isp g0`.
+ * @param ispSeconds The specific impulse, seconds.
+ * @returns The exhaust speed, metres a second.
+ * @example
+ * ```ts
+ * import { exhaustSpeedOf } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(exhaustSpeedOf(311).toFixed(1));
+ * ```
+ */
+export const exhaustSpeedOf = (ispSeconds) => ispSeconds * G0;
+/**
+ * The propellant an engine burns, kilograms a second: its vacuum thrust over its vacuum exhaust speed, times the throttle. In air the flow stays the same and the thrust falls (see {@link thrustAt}), as in Orbiter.
+ * @param engine The engine.
+ * @param throttle 0 to 1; 1 when left out.
+ * @returns The mass flow, kg/s.
+ * @example
+ * ```ts
+ * import { exhaustSpeedOf, massFlow } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(massFlow({ thrust: 91_189, exhaustSpeed: exhaustSpeedOf(314) }).toFixed(2), "kg/s");
+ * ```
+ */
+export const massFlow = (engine, throttle = 1) => (engine.thrust * clampThrottle(throttle)) / engine.exhaustSpeed;
+/**
+ * An engine's thrust at an outside pressure: the vacuum thrust times `max(0, 1 - p (v0 - vref) / (pref v0))`, Orbiter's straight-line model through the vacuum and the reference exhaust speeds.
+ * @param engine The engine.
+ * @param pressure The outside pressure, pascals (0 in space).
+ * @param throttle 0 to 1; 1 when left out.
+ * @returns The thrust, newtons.
+ * @example
+ * ```ts
+ * import { exhaustSpeedOf, thrustAt } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const engine = { thrust: 1_000_000, exhaustSpeed: exhaustSpeedOf(330), reference: { exhaustSpeed: exhaustSpeedOf(300), pressure: 101_325 } };
+ * console.log(thrustAt(engine, 0), thrustAt(engine, 101_325).toFixed(0));
+ * ```
+ */
+export function thrustAt(engine, pressure, throttle = 1) {
+    const vacuum = engine.thrust * clampThrottle(throttle);
+    const ref = engine.reference;
+    if (!ref || !(ref.exhaustSpeed > 0) || !(ref.pressure > 0))
+        return vacuum;
+    const pfac = (engine.exhaustSpeed - ref.exhaustSpeed) / (ref.pressure * engine.exhaustSpeed);
+    return vacuum * Math.max(0, 1 - pressure * pfac);
+}
+/**
+ * The rocket equation (Tsiolkovsky's): the speed a burn gives, `v ln(m0 / m1)`.
+ * @param exhaustSpeed The exhaust speed, metres a second.
+ * @param startMass The mass before the burn, kilograms.
+ * @param endMass The mass after it, kilograms (more than 0, at most `startMass`).
+ * @returns The change of speed, metres a second.
+ * @example
+ * ```ts
+ * import { deltaV, exhaustSpeedOf } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(deltaV(exhaustSpeedOf(314), 30_000, 20_000).toFixed(0), "m/s");
+ * ```
+ */
+export const deltaV = (exhaustSpeed, startMass, endMass) => exhaustSpeed * Math.log(startMass / endMass);
+/**
+ * The rocket equation turned round: the mass left after a change of speed, `m0 exp(-dv / v)`.
+ * @param exhaustSpeed The exhaust speed, metres a second.
+ * @param startMass The mass before the burn, kilograms.
+ * @param dv The change of speed, metres a second.
+ * @returns The mass after the burn, kilograms; `startMass - massAfter(...)` is the propellant burned.
+ * @example
+ * ```ts
+ * import { exhaustSpeedOf, massAfter } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log((30_000 - massAfter(exhaustSpeedOf(314), 30_000, 1_000)).toFixed(0), "kg burned");
+ * ```
+ */
+export const massAfter = (exhaustSpeed, startMass, dv) => startMass * Math.exp(-dv / exhaustSpeed);
+/**
+ * How long an engine must burn, at a steady throttle in vacuum, to change a craft's speed by `dv`: the propellant the rocket equation asks for over the engine's mass flow.
+ * @param engine The engine.
+ * @param startMass The mass before the burn, kilograms.
+ * @param dv The change of speed, metres a second.
+ * @param throttle 0 to 1; 1 when left out.
+ * @returns The burn's length, seconds (Infinity at zero throttle).
+ * @example
+ * ```ts
+ * import { burnSeconds, exhaustSpeedOf } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(burnSeconds({ thrust: 91_189, exhaustSpeed: exhaustSpeedOf(314) }, 30_000, 1_000).toFixed(1), "s");
+ * ```
+ */
+export function burnSeconds(engine, startMass, dv, throttle = 1) {
+    const flow = massFlow(engine, throttle);
+    return flow > 0 ? (startMass - massAfter(engine.exhaustSpeed, startMass, dv)) / flow : Infinity;
+}

package/dist/physics/transfers.d.ts

@@ -0,0 +1,128 @@
+import { type Elements } from "./elements.ts";
+/**
+ * The speed change at distance `r` that turns an orbit of semi-major axis `aNow` into one of `aNew`, burning along the speed (the vis-viva equation, as Orbiter's transfer display rescales a burn to keep a chosen orbit).
+ * @param gm The body's gravitational parameter, m^3/s^2.
+ * @param r The distance of the burn from the body's centre, metres.
+ * @param aNow The semi-major axis before, metres (negative for an open path).
+ * @param aNew The semi-major axis wanted, metres.
+ * @returns The change of speed, metres a second: positive to speed up (prograde), negative to slow down.
+ * @example
+ * ```ts
+ * import { speedChangeFor } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(speedChangeFor(3.986004418e14, 6_778_000, 6_778_000, (6_778_000 + 42_164_000) / 2).toFixed(1), "m/s");
+ * ```
+ */
+export declare const speedChangeFor: (gm: number, r: number, aNow: number, aNew: number) => number;
+/**
+ * The change of speed that turns a speed through an angle, and to a new size if given: `sqrt(v1^2 + v2^2 - 2 v1 v2 cos angle)`, which is `2 v sin(angle / 2)` for a pure change of plane. Orbiter's plane-alignment display estimates `v angle` instead, the cost of keeping the push normal to the plane all through the burn.
+ * @param speed The speed before, metres a second.
+ * @param angle The angle to turn through, radians.
+ * @param newSpeed The speed after; the same as before when left out.
+ * @returns The change of speed, metres a second.
+ * @example
+ * ```ts
+ * import { planeChange } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(planeChange(7_669, (10 * Math.PI) / 180).toFixed(0), "m/s for 10 degrees in low orbit");
+ * ```
+ */
+export declare function planeChange(speed: number, angle: number, newSpeed?: number): number;
+/**
+ * The bi-elliptic transfer between two circular orbits about one body: out on one half-ellipse to a far point `rb`, a burn there, and back on a second half-ellipse to the final orbit. With `rb` equal to the final radius its speed changes are the Hohmann transfer's (and its time adds the half turn of the final circle that the second leg then is).
+ * @param gm The body's gravitational parameter, m^3/s^2.
+ * @param r1 The starting radius, metres.
+ * @param r2 The final radius, metres.
+ * @param rb The far point, metres (at least the larger of `r1` and `r2`).
+ * @returns The three speed changes (metres a second, each positive), their sum, and the flight time (seconds).
+ * @example
+ * ```ts
+ * import { biElliptic } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const far = biElliptic(3.986004418e14, 6_778_000, 384_400_000, 1_000_000_000);
+ * console.log(far.total.toFixed(0), "m/s,", (far.seconds / 86_400).toFixed(1), "days");
+ * ```
+ */
+export declare function biElliptic(gm: number, r1: number, r2: number, rb: number): {
+    dv1: number;
+    dv2: number;
+    dv3: number;
+    total: number;
+    seconds: number;
+};
+/**
+ * The angle between two orbits' planes.
+ * @param a One orbit's elements.
+ * @param b The other's.
+ * @returns The angle, radians, 0 to pi.
+ * @example
+ * ```ts
+ * import { elementsOf, relativeInclination } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const gm = 3.986004418e14;
+ * const iss = elementsOf(gm, [6_778_000, 0, 0], [0, 4_766, 6_008]);
+ * const equator = elementsOf(gm, [6_778_000, 0, 0], [0, 7_669, 0]);
+ * console.log(((relativeInclination(iss, equator) * 180) / Math.PI).toFixed(1), "degrees");
+ * ```
+ */
+export declare function relativeInclination(a: Elements, b: Elements): number;
+/**
+ * One crossing of a craft's orbit with another plane: where on its orbit, how long until it is there, its speed there and the change of speed that turns it into the other plane.
+ *
+ * @example
+ * ```ts
+ * import { elementsOf, nodes, type Node } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const gm = 3.986004418e14;
+ * const crossing = nodes(elementsOf(gm, [6_778_000, 0, 0], [0, 4_766, 6_008]), elementsOf(gm, [0, 6_778_000, 0], [-7_669, 0, 0]));
+ * const next: Node | undefined = crossing?.ascending;
+ * console.log(next?.seconds.toFixed(0));
+ * ```
+ */
+export interface Node {
+    /** The craft's true anomaly there, radians. */
+    trueAnomaly: number;
+    /** Seconds from when the craft's elements were taken until it is there (the next time). */
+    seconds: number;
+    /** Its speed there, metres a second. */
+    speed: number;
+    /** An impulsive change of plane there, `2 v sin(angle / 2)`, metres a second. */
+    dv: number;
+}
+/**
+ * Where a craft's orbit crosses another orbit's plane, and when it gets there (Orbiter's plane-alignment display): the ascending node, where it passes to the north of the other plane, and the descending node.
+ * @param ship The craft's elements.
+ * @param target The elements of the orbit whose plane is wanted (another craft, a moon, or one made up for the plane).
+ * @returns The angle between the planes and the two nodes, or null when the planes are the same (no nodes).
+ * @example
+ * ```ts
+ * import { elementsOf, nodes } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const gm = 3.986004418e14;
+ * const tilted = elementsOf(gm, [6_778_000, 0, 0], [0, 4_766, 6_008]);
+ * const equator = elementsOf(gm, [6_778_000, 0, 0], [0, 7_669, 0]);
+ * const n = nodes(tilted, equator);
+ * console.log(n?.descending.seconds.toFixed(0), "s to the descending node,", n?.descending.dv.toFixed(0), "m/s there");
+ * ```
+ */
+export declare function nodes(ship: Elements, target: Elements): {
+    relativeInclination: number;
+    ascending: Node;
+    descending: Node;
+} | null;
+/**
+ * Where two orbits about one body, in one plane, cross: the points that are on both (Orbiter's transfer display, which finds where a transfer orbit meets its target's). Both orbits must share their plane; for orbits in different planes, use the {@link nodes} first.
+ * @param path The orbit flown (a transfer orbit).
+ * @param target The orbit to reach.
+ * @returns The true anomalies on `path` of the crossings, radians, 0 to 2 pi in increasing order: none, one (touching) or two (on an open path, only points it reaches).
+ * @example
+ * ```ts
+ * import { crossings, elementsOf } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const gm = 3.986004418e14;
+ * const transfer = elementsOf(gm, [6_778_000, 0, 0], [0, 9_000, 0]);
+ * const higher = elementsOf(gm, [10_000_000, 0, 0], [0, Math.sqrt(gm / 10_000_000), 0]);
+ * console.log(crossings(transfer, higher).map((nu) => ((nu * 180) / Math.PI).toFixed(1)));
+ * ```
+ */
+export declare function crossings(path: Elements, target: Elements): number[];