@johnmorrisdotca/uchusen-rockets 0.19.1 → 0.20.0

package/dist/physics/atmosphere.js

@@ -0,0 +1,246 @@
+// The air: temperature, pressure and density with height for the Earth, Mars and Venus, the 1976 U.S. Standard Atmosphere, and what the
+// air does to a craft (its speed through the air, the dynamic pressure, the Mach number and the drag). Pure.
+// Ported from Orbiter (https://github.com/orbitersim/orbiter): the layered models of Src/Celbody/Atmosphere/EarthAtm2006/EarthAtm2006.cpp,
+// MarsAtm2006/MarsAtm2006.cpp and VenusAtm2006/VenusAtm2006.cpp (clbkConstants and clbkParams: each layer's base, temperature, lapse rate,
+// pressure and density, the geopotential height from the planet's radius, and the height above which the model has no air), the speed of
+// sound of Src/Orbiter/Planet.h (AtmSoundSpeed), the airspeed and dynamic pressure of Src/Orbiter/Vesselbase.cpp (air turning with the
+// planet, no wind), and the drag of a drag element of Src/Orbiter/Vessel.cpp (CD times the dynamic pressure, against the airflow).
+// Copyright (c) 2000-2026 Martin Schweiger, MIT licence (LICENSES/Orbiter-MIT.txt). Changed in the port: the three models are tables of
+// layers read by one function in place of three nested if-chains, with the same numbers. Not ported: Orbiter's Jacchia 71-Gill model and
+// the NRLMSISE-00 model, which need the Sun's activity, and NRLMSISE-00's C code, which is not Orbiter's own.
+// Written here: standardAtmosphere, from the defining constants and equations of U.S. Standard Atmosphere, 1976 (NOAA, NASA and the U.S.
+// Air Force, NASA-TM-X-74335), its tables 2, 3 and 4.
+import { cross, length, scale, sub } from "./vector.js";
+/**
+ * The Earth's air as Orbiter 2006 models it (Orbiter's EarthAtm2006: "a simple static atmosphere model", its own description, ending at 200 km).
+ *
+ * @example
+ * ```ts
+ * import { atmosphereAt, EARTH_ATMOSPHERE } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(atmosphereAt(EARTH_ATMOSPHERE, 0).pressure);
+ * ```
+ */
+export const EARTH_ATMOSPHERE = {
+    name: "Earth (Orbiter 2006)",
+    radius: 6.37101e6,
+    g0R: 0.0341643,
+    gasConstant: 286.91,
+    gamma: 1.4,
+    limit: 200e3,
+    layers: [
+        { base: 0, temperature: 288.16, lapse: -6.5e-3, pressure: 1.01325e5, density: 1.225 },
+        { base: 11e3, temperature: 216.66, lapse: 0, pressure: 2.26323e4, density: 0.36392 },
+        { base: 25e3, temperature: 216.66, lapse: 3e-3, pressure: 2488.726, density: 0.0400179 },
+        { base: 47e3, temperature: 282.66, lapse: 0, pressure: 120.4524, density: 0.00148459 },
+        { base: 53e3, temperature: 282.66, lapse: -4.5e-3, pressure: 58.32623, density: 0.000718878 },
+        { base: 79e3, temperature: 165.66, lapse: 0, pressure: 1.009601, density: 2.12319e-5 },
+        { base: 90e3, temperature: 165.66, lapse: 4e-3, pressure: 0.1044559, density: 2.19671e-6 },
+        { base: 105e3, temperature: 225.66, lapse: 0, pressure: 0.007454273, density: 1.15082e-7 },
+    ],
+};
+/**
+ * Mars's air as Orbiter 2006 models it (Orbiter's MarsAtm2006), ending at 100 km.
+ *
+ * @example
+ * ```ts
+ * import { atmosphereAt, MARS_ATMOSPHERE } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(atmosphereAt(MARS_ATMOSPHERE, 0).pressure);
+ * ```
+ */
+export const MARS_ATMOSPHERE = {
+    name: "Mars (Orbiter 2006)",
+    radius: 3.38992e6,
+    g0R: 0.0197275,
+    gasConstant: 188.92,
+    gamma: 1.2941,
+    limit: 100e3,
+    layers: [
+        { base: 0, temperature: 195, lapse: 2.5e-3, pressure: 610, density: 0.02 },
+        { base: 2e3, temperature: 200, lapse: 0, pressure: 4.99534e2, density: 1.59687e-2 },
+        { base: 4e3, temperature: 200, lapse: -2e-3, pressure: 4.101e2, density: 1.31097e-2 },
+        { base: 14e3, temperature: 180, lapse: 0, pressure: 1.45061e2, density: 5.1524e-3 },
+        { base: 20e3, temperature: 180, lapse: -1.5e-3, pressure: 7.51564e1, density: 2.66947e-3 },
+        { base: 30e3, temperature: 165, lapse: 0, pressure: 2.39322e1, density: 9.27323e-4 },
+    ],
+};
+/**
+ * Venus's air as Orbiter 2006 models it (Orbiter's VenusAtm2006), ending at 200 km.
+ *
+ * @example
+ * ```ts
+ * import { atmosphereAt, VENUS_ATMOSPHERE } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(atmosphereAt(VENUS_ATMOSPHERE, 0).temperature);
+ * ```
+ */
+export const VENUS_ATMOSPHERE = {
+    name: "Venus (Orbiter 2006)",
+    radius: 6.05184e6,
+    g0R: 0.0469506,
+    gasConstant: 188.92,
+    gamma: 1.2857,
+    limit: 200e3,
+    layers: [
+        { base: 0, temperature: 750, lapse: -0.009, pressure: 9.2e6, density: 65 },
+        { base: 30e3, temperature: 480, lapse: -0.00833, pressure: 8.967687e5, density: 9.89979 },
+        { base: 60e3, temperature: 230, lapse: 0, pressure: 1.421879e4, density: 3.274408e-1 },
+        { base: 70e3, temperature: 230, lapse: -0.0025, pressure: 1.846393e3, density: 4.252010e-2 },
+        { base: 90e3, temperature: 180, lapse: 0, pressure: 1.849556e1, density: 5.442431e-4 },
+    ],
+};
+const NO_AIR = { temperature: 0, pressure: 0, density: 0, speedOfSound: 0 };
+/**
+ * The air of a layered model at a height above the surface (Orbiter's `clbkParams`): the geometric height is turned into geopotential height, the layer below it is found, and the temperature, pressure and density follow from that layer.
+ * @param model The model.
+ * @param altitude The geometric height above the reference radius, metres (below 0 the lowest layer goes on down).
+ * @returns The air there; all zero above the model's limit, as Orbiter has no air there.
+ * @example
+ * ```ts
+ * import { atmosphereAt, EARTH_ATMOSPHERE } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const air = atmosphereAt(EARTH_ATMOSPHERE, 30_000);
+ * console.log(air.temperature.toFixed(1), "K,", air.pressure.toFixed(0), "Pa,", air.density.toFixed(4), "kg/m^3");
+ * ```
+ */
+export function atmosphereAt(model, altitude) {
+    if (altitude > model.limit)
+        return NO_AIR;
+    const h = (altitude * model.radius) / (model.radius + altitude);
+    const layers = model.layers;
+    let layer = layers[0];
+    for (const candidate of layers)
+        if (h > candidate.base)
+            layer = candidate;
+    let temperature;
+    let e;
+    let t = 1;
+    if (layer.lapse === 0) {
+        temperature = layer.temperature;
+        e = Math.exp((-model.g0R / layer.temperature) * (h - layer.base));
+    }
+    else {
+        temperature = (h - layer.base) * layer.lapse + layer.temperature;
+        t = temperature / layer.temperature;
+        e = Math.pow(t, -model.g0R / layer.lapse);
+    }
+    return { temperature, pressure: layer.pressure * e, density: (layer.density * e) / t, speedOfSound: Math.sqrt(model.gamma * model.gasConstant * temperature) };
+}
+// U.S. Standard Atmosphere, 1976: table 2 (adopted constants), table 3 (sea-level air) and table 4 (the layers to 86 km).
+const R_STAR = 8.31432e3;
+const G0 = 9.80665;
+const R0 = 6.356766e6;
+const T0 = 288.15;
+const P0 = 1.01325e5;
+const GAMMA = 1.4;
+const AIR = [
+    [28.0134, 0.78084],
+    [31.9988, 0.209476],
+    [39.948, 0.00934],
+    [44.00995, 0.000314],
+    [20.183, 0.00001818],
+    [4.0026, 0.00000524],
+    [83.8, 0.00000114],
+    [131.3, 0.000000087],
+    [16.04303, 0.000002],
+    [2.01594, 0.0000005],
+];
+const M0 = AIR.reduce((sum, [m, f]) => sum + m * f, 0);
+const BASES = [0, 11e3, 20e3, 32e3, 47e3, 51e3, 71e3];
+const LAPSES = [-6.5e-3, 0, 1e-3, 2.8e-3, 0, -2.8e-3, -2e-3];
+const TOP = 84.852e3;
+const STANDARD_LAYERS = [];
+{
+    let temperature = T0;
+    let pressure = P0;
+    BASES.forEach((base, b) => {
+        STANDARD_LAYERS.push({ base, lapse: LAPSES[b], temperature, pressure });
+        const next = BASES[b + 1] ?? TOP;
+        const end = temperature + LAPSES[b] * (next - base);
+        pressure = LAPSES[b] === 0 ? pressure * Math.exp((-G0 * M0 * (next - base)) / (R_STAR * temperature)) : pressure * Math.pow(temperature / end, (G0 * M0) / (R_STAR * LAPSES[b]));
+        temperature = end;
+    });
+}
+/**
+ * The 1976 U.S. Standard Atmosphere from 5 km below sea level to 86 km, worked from its defining constants and equations (its tables 2, 3 and 4): seven layers of fixed temperature gradient in geopotential height, the sea-level air's mean molecular weight from its table 3, the hydrostatic equation and the gas law.
+ * @param altitude The geometric height above sea level, metres, from -5,000 to 86,000.
+ * @returns The air there (the temperature is the molecular-scale temperature, the same as the kinetic temperature below 80 km), or null outside those heights.
+ * @example
+ * ```ts
+ * import { standardAtmosphere } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const air = standardAtmosphere(11_000);
+ * console.log(air?.temperature.toFixed(3), "K,", air?.pressure.toFixed(0), "Pa");
+ * ```
+ */
+export function standardAtmosphere(altitude) {
+    if (!(altitude >= -5_000 && altitude <= 86_000))
+        return null;
+    const h = (R0 * altitude) / (R0 + altitude);
+    let layer = STANDARD_LAYERS[0];
+    for (const candidate of STANDARD_LAYERS)
+        if (h >= candidate.base)
+            layer = candidate;
+    const temperature = layer.temperature + layer.lapse * (h - layer.base);
+    const pressure = layer.lapse === 0 ? layer.pressure * Math.exp((-G0 * M0 * (h - layer.base)) / (R_STAR * layer.temperature)) : layer.pressure * Math.pow(layer.temperature / temperature, (G0 * M0) / (R_STAR * layer.lapse));
+    return { temperature, pressure, density: (pressure * M0) / (R_STAR * temperature), speedOfSound: Math.sqrt((GAMMA * R_STAR * temperature) / M0) };
+}
+/**
+ * A craft's speed through the air, for air that turns with its planet and no wind (Orbiter's airspeed): its speed relative to the planet less the speed of the air where it is, `v - w x r`.
+ * @param position The craft's position from the planet's centre, metres.
+ * @param velocity Its speed relative to the planet's centre, metres a second.
+ * @param spin The planet's turn rate as a vector along its pole, radians a second (`[0, 0, 7.292115e-5]` for the Earth in an equatorial frame).
+ * @returns The velocity through the air, metres a second.
+ * @example
+ * ```ts
+ * import { airVelocity } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(airVelocity([6_778_000, 0, 0], [0, 7_669, 0], [0, 0, 7.292115e-5]));
+ * ```
+ */
+export const airVelocity = (position, velocity, spin) => sub(velocity, cross(spin, position));
+/**
+ * The dynamic pressure of the air on a craft, `rho v^2 / 2` (Orbiter's `dynp`).
+ * @param density The air's density, kg/m^3.
+ * @param airspeed The speed through the air, metres a second.
+ * @returns The dynamic pressure, pascals.
+ * @example
+ * ```ts
+ * import { dynamicPressure } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(dynamicPressure(0.4, 400));
+ * ```
+ */
+export const dynamicPressure = (density, airspeed) => 0.5 * density * airspeed * airspeed;
+/**
+ * The Mach number: the speed through the air over the speed of sound there (Orbiter's `atmM`).
+ * @param airspeed The speed through the air, metres a second.
+ * @param air The air, from {@link atmosphereAt} or {@link standardAtmosphere}.
+ * @returns The Mach number; 0 where there is no air.
+ * @example
+ * ```ts
+ * import { atmosphereAt, EARTH_ATMOSPHERE, machNumber } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(machNumber(600, atmosphereAt(EARTH_ATMOSPHERE, 11_000)).toFixed(2));
+ * ```
+ */
+export const machNumber = (airspeed, air) => (air.speedOfSound > 0 ? airspeed / air.speedOfSound : 0);
+/**
+ * The drag on a craft as an acceleration: `-(rho |v| v / 2) Cd A / m`, against its velocity through the air (Orbiter's drag element: its drag coefficient times the dynamic pressure, along the airflow).
+ * @param density The air's density, kg/m^3.
+ * @param air The velocity through the air, from {@link airVelocity}, metres a second.
+ * @param dragArea The drag coefficient times the reference area, `Cd A`, m^2.
+ * @param mass The craft's mass, kilograms.
+ * @returns The acceleration, metres a second squared.
+ * @example
+ * ```ts
+ * import { atmosphereAt, dragAcceleration, EARTH_ATMOSPHERE } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(dragAcceleration(atmosphereAt(EARTH_ATMOSPHERE, 60_000).density, [0, 7_000, 0], 1.3 * 12, 9_000));
+ * ```
+ */
+export function dragAcceleration(density, air, dragArea, mass) {
+    const speed = length(air);
+    return speed > 0 ? scale(air, (-0.5 * density * speed * dragArea) / mass) : [0, 0, 0];
+}

package/dist/physics/attitude.d.ts

@@ -0,0 +1,342 @@
+import { type Vec3 } from "./vector.ts";
+/**
+ * An attitude as a unit quaternion `[w, x, y, z]`: the rotation that takes a vector of the craft's own frame into the scene's frame.
+ *
+ * @example
+ * ```ts
+ * import { rotateVector, type Quat } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const level: Quat = [1, 0, 0, 0];
+ * console.log(rotateVector(level, [0, 1, 0]));
+ * ```
+ */
+export type Quat = readonly [number, number, number, number];
+/**
+ * The quaternion of a turn by an angle about an axis.
+ * @param axis The axis, any length but not zero.
+ * @param angle The angle, radians, right-handed about the axis.
+ * @returns The unit quaternion.
+ * @example
+ * ```ts
+ * import { quatFromAxisAngle, rotateVector } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(rotateVector(quatFromAxisAngle([0, 0, 1], Math.PI / 2), [1, 0, 0]).map((x) => x.toFixed(3)));
+ * ```
+ */
+export declare function quatFromAxisAngle(axis: Vec3, angle: number): Quat;
+/**
+ * A vector of the craft's frame in the scene's frame.
+ * @param q The attitude.
+ * @param v The vector in the craft's frame.
+ * @returns The same vector in the scene's frame.
+ * @example
+ * ```ts
+ * import { quatFromAxisAngle, rotateVector } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(rotateVector(quatFromAxisAngle([1, 0, 0], Math.PI / 2), [0, 1, 0]).map((x) => x.toFixed(3)));
+ * ```
+ */
+export declare function rotateVector(q: Quat, v: Vec3): Vec3;
+/**
+ * A vector of the scene's frame in the craft's frame: the inverse of {@link rotateVector}.
+ * @param q The attitude.
+ * @param v The vector in the scene's frame.
+ * @returns The same vector in the craft's frame.
+ * @example
+ * ```ts
+ * import { quatFromAxisAngle, unrotateVector } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(unrotateVector(quatFromAxisAngle([1, 0, 0], Math.PI / 2), [0, 0, 1]).map((x) => x.toFixed(3)));
+ * ```
+ */
+export declare const unrotateVector: (q: Quat, v: Vec3) => Vec3;
+/**
+ * Turns an attitude by a rotation given in the craft's own frame (a rotation vector: its direction the axis, its length the angle in radians), as Orbiter's `Quaternion::Rotate` does with the turn rate times the step.
+ * @param q The attitude.
+ * @param rotation The rotation, in the craft's frame.
+ * @returns The new attitude.
+ * @example
+ * ```ts
+ * import { rotateVector, turnBy } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(rotateVector(turnBy([1, 0, 0, 0], [0, 0, Math.PI]), [1, 0, 0]).map((x) => x.toFixed(3)));
+ * ```
+ */
+export declare function turnBy(q: Quat, rotation: Vec3): Quat;
+/**
+ * Euler's equations for a body with principal moments of inertia along its own axes: the angular acceleration a torque gives, `I^-1 (torque - w x I w)` (Orbiter's `RigidBody::EulerInv_full`).
+ * @param inertia The principal moments of inertia about the craft's x, y and z axes, kg m^2.
+ * @param torque The torque, in the craft's frame, N m.
+ * @param omega The turn rate, in the craft's frame, radians a second.
+ * @returns The angular acceleration, in the craft's frame, radians a second squared.
+ * @example
+ * ```ts
+ * import { angularAcceleration } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(angularAcceleration([1_000, 2_000, 2_500], [0, 0, 50], [0, 0, 0]));
+ * ```
+ */
+export declare function angularAcceleration(inertia: Vec3, torque: Vec3, omega: Vec3): Vec3;
+/**
+ * The torque a body's gravity puts on a long craft (the gravity gradient), `3 gm / r^3 (u x I u)` with `u` the unit vector to the body in the craft's frame (Orbiter's `RigidBody::GetTorque`, without its damping). It turns a long craft to point at the body.
+ * @param gm The body's gravitational parameter, m^3/s^2.
+ * @param toBody The body's centre from the craft, in the craft's frame, metres.
+ * @param inertia The principal moments of inertia, kg m^2.
+ * @returns The torque, in the craft's frame, N m.
+ * @example
+ * ```ts
+ * import { gravityGradientTorque } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(gravityGradientTorque(3.986004418e14, [-4_800_000, 4_800_000, 0], [100_000, 10_000, 100_000]));
+ * ```
+ */
+export declare function gravityGradientTorque(gm: number, toBody: Vec3, inertia: Vec3): Vec3;
+/**
+ * A craft's attitude and turn rate at a time. The turn rate is in the craft's own frame, radians a second.
+ *
+ * @example
+ * ```ts
+ * import type { Spin } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const still: Spin = { t: 0, q: [1, 0, 0, 0], omega: [0, 0, 0] };
+ * console.log(still.omega);
+ * ```
+ */
+export interface Spin {
+    t: number;
+    q: Quat;
+    omega: Vec3;
+}
+/**
+ * What turns the craft: the torque in its own frame (N m) at a time, attitude and turn rate.
+ *
+ * @example
+ * ```ts
+ * import type { Torque } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const steady: Torque = () => [0, 0, 10];
+ * console.log(steady(0, [1, 0, 0, 0], [0, 0, 0]));
+ * ```
+ */
+export type Torque = (t: number, q: Quat, omega: Vec3) => Vec3;
+/**
+ * One step of a craft's turning: the fourth-order Runge-Kutta step Orbiter takes for the angular state (the angular half of `RK4_LinAng`).
+ * @param spin The attitude and turn rate now.
+ * @param h The step, seconds.
+ * @param inertia The principal moments of inertia, kg m^2.
+ * @param torque What turns the craft.
+ * @returns The attitude and turn rate `h` seconds later.
+ * @example
+ * ```ts
+ * import { stepSpin } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const next = stepSpin({ t: 0, q: [1, 0, 0, 0], omega: [0, 0, 0] }, 1, [1_000, 1_000, 1_000], () => [0, 0, 10]);
+ * console.log(next.omega[2]);
+ * ```
+ */
+export declare function stepSpin(spin: Spin, h: number, inertia: Vec3, torque: Torque): Spin;
+/**
+ * Turns a craft forward by a span of time, in steps no longer than `options.step`.
+ * @param start The attitude and turn rate at the start.
+ * @param seconds How long, seconds.
+ * @param options The step, the moments of inertia and what turns the craft (no torque when left out).
+ * @returns The attitude and turn rate at `start.t + seconds`.
+ * @example
+ * ```ts
+ * import { spinFor } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const tumbling = spinFor({ t: 0, q: [1, 0, 0, 0], omega: [0.1, 0.01, 0] }, 60, { step: 0.1, inertia: [1_000, 2_000, 3_000] });
+ * console.log(tumbling.omega.map((x) => x.toFixed(4)));
+ * ```
+ */
+export declare function spinFor(start: Spin, seconds: number, options: {
+    step: number;
+    inertia: Vec3;
+    torque?: Torque;
+}): Spin;
+/**
+ * One thruster: where it is and which way it pushes, in the craft's frame, its thrust and exhaust speed.
+ *
+ * @example
+ * ```ts
+ * import type { Thruster } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const quad: Thruster = { position: [2, 10, 0], direction: [0, 0, 1], thrust: 445, exhaustSpeed: 2_800 };
+ * console.log(quad.thrust);
+ * ```
+ */
+export interface Thruster {
+    /** Where its push acts, from the craft's centre of mass, metres. */
+    position: Vec3;
+    /** Which way it pushes the craft, a unit vector (the exhaust goes the other way). */
+    direction: Vec3;
+    /** Thrust at full level, newtons. */
+    thrust: number;
+    /** Exhaust speed, metres a second. */
+    exhaustSpeed: number;
+}
+/**
+ * What a set of thrusters does at given levels: the force and the torque on the craft (`position x force` for each, Orbiter's thruster torque) and the propellant they burn.
+ * @param thrusters The thrusters.
+ * @param levels Each one's level, 0 to 1, in the same order (missing ones are off).
+ * @returns The force (N) and torque (N m), in the craft's frame, and the mass flow (kg/s).
+ * @example
+ * ```ts
+ * import { thrusterPush } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const pair = [{ position: [1, 0, 0] as const, direction: [0, 1, 0] as const, thrust: 100, exhaustSpeed: 2_800 }, { position: [-1, 0, 0] as const, direction: [0, -1, 0] as const, thrust: 100, exhaustSpeed: 2_800 }];
+ * console.log(thrusterPush(pair, [1, 1]));
+ * ```
+ */
+export declare function thrusterPush(thrusters: readonly Thruster[], levels: readonly number[]): {
+    force: Vec3;
+    torque: Vec3;
+    massFlow: number;
+};
+/**
+ * The largest torque a craft's thrusters can give about each of its axes, each way: for each axis and sense, the thrusters that turn the craft that way, all at full (Orbiter's `MaxAngularMoment` of the attitude groups).
+ *
+ * @example
+ * ```ts
+ * import type { TorqueLimits } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const limits: TorqueLimits = { positive: [400, 400, 200], negative: [400, 400, 200] };
+ * console.log(limits.positive[2]);
+ * ```
+ */
+export interface TorqueLimits {
+    /** About +x, +y and +z, N m (0 or more). */
+    positive: Vec3;
+    /** About -x, -y and -z, N m (0 or more). */
+    negative: Vec3;
+}
+/**
+ * The torque limits of a set of thrusters. Each thruster belongs to the group of the axis it turns the craft about most, as Orbiter's attitude groups (pitch up and down, yaw left and right, bank left and right) are set up.
+ * @param thrusters The thrusters.
+ * @returns The largest torque about each axis, each way.
+ * @example
+ * ```ts
+ * import { torqueLimits } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const pair = [{ position: [1, 0, 0] as const, direction: [0, 1, 0] as const, thrust: 100, exhaustSpeed: 2_800 }, { position: [-1, 0, 0] as const, direction: [0, -1, 0] as const, thrust: 100, exhaustSpeed: 2_800 }];
+ * console.log(torqueLimits(pair));
+ * ```
+ */
+export declare function torqueLimits(thrusters: readonly Thruster[]): TorqueLimits;
+/**
+ * Fires the thrusters for a wanted torque: each attitude group at the level that gives its axis's share, held to full, as Orbiter fires a group at the level its navcomp asks for.
+ * @param thrusters The thrusters.
+ * @param torque The torque wanted, in the craft's frame, N m.
+ * @returns Each thruster's level (0 to 1), and what they do together: the force, the torque (which may differ a little from the one wanted, when a group also turns the craft about another axis) and the mass flow.
+ * @example
+ * ```ts
+ * import { fireFor } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const pair = [{ position: [1, 0, 0] as const, direction: [0, 1, 0] as const, thrust: 100, exhaustSpeed: 2_800 }, { position: [-1, 0, 0] as const, direction: [0, -1, 0] as const, thrust: 100, exhaustSpeed: 2_800 }];
+ * console.log(fireFor(pair, [0, 0, 50]).levels);
+ * ```
+ */
+export declare function fireFor(thrusters: readonly Thruster[], torque: Vec3): {
+    levels: number[];
+    force: Vec3;
+    torque: Vec3;
+    massFlow: number;
+};
+/**
+ * The autopilot's kill-rotation mode (Orbiter's navcomp): a tenth of the torque that would stop the turning in one control step, `(-I w / dt + w x I w) / 10`, held to what the thrusters can give. Orbiter switches the mode off once the turn rate is below 1e-5 radians a second.
+ * @param spin The attitude and turn rate.
+ * @param inertia The principal moments of inertia, kg m^2.
+ * @param limits What the thrusters can give.
+ * @param dt The control step, seconds (the time until the autopilot looks again).
+ * @returns The torque to apply, in the craft's frame, N m.
+ * @example
+ * ```ts
+ * import { killRotation } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const limits = { positive: [200, 200, 200] as const, negative: [200, 200, 200] as const };
+ * console.log(killRotation({ t: 0, q: [1, 0, 0, 0], omega: [0.05, 0, 0] }, [1_000, 1_000, 1_000], limits, 0.1));
+ * ```
+ */
+export declare function killRotation(spin: Spin, inertia: Vec3, limits: TorqueLimits, dt: number): Vec3;
+/**
+ * The autopilot's turn-and-hold mode (Orbiter's navcomp prograde, retrograde, normal and antinormal modes, for any direction): it asks for a turn rate towards the target of 5 degrees a second, less within 20 degrees of it, and gives the torque that reaches that rate in one control step, each axis held to 40 per cent of its thrusters. With a roof direction it also rolls the craft so that its roof axis points there; without one it stops the roll.
+ * @param spin The attitude and turn rate.
+ * @param inertia The principal moments of inertia, kg m^2.
+ * @param limits What the thrusters can give.
+ * @param dt The control step, seconds.
+ * @param target The direction to point the nose at, in the scene's frame.
+ * @param options The craft's nose and roof axes in its own frame (`[0, 1, 0]` and `[0, 0, 1]` when left out: this package's rockets stand along +y), and the roof's direction in the scene's frame if the roll is to be held.
+ * @returns The torque to apply, in the craft's frame, N m.
+ * @example
+ * ```ts
+ * import { holdDirection } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const limits = { positive: [200, 200, 200] as const, negative: [200, 200, 200] as const };
+ * console.log(holdDirection({ t: 0, q: [1, 0, 0, 0], omega: [0, 0, 0] }, [1_000, 1_000, 1_000], limits, 0.1, [1, 0, 0]));
+ * ```
+ */
+export declare function holdDirection(spin: Spin, inertia: Vec3, limits: TorqueLimits, dt: number, target: Vec3, options?: {
+    nose?: Vec3;
+    roofAxis?: Vec3;
+    roof?: Vec3;
+}): Vec3;
+/**
+ * A craft whose place and attitude move together: where it is, how fast it goes, which way it points and how it turns.
+ *
+ * @example
+ * ```ts
+ * import type { Craft } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const parked: Craft = { t: 0, position: [6_778_000, 0, 0], velocity: [0, 7_669, 0], q: [1, 0, 0, 0], omega: [0, 0, 0] };
+ * console.log(parked.q);
+ * ```
+ */
+export interface Craft {
+    t: number;
+    position: Vec3;
+    velocity: Vec3;
+    q: Quat;
+    omega: Vec3;
+}
+/**
+ * What moves a craft: its acceleration in the scene's frame (gravity, and an engine's thrust along the nose, which depends on the attitude) and the torque in its own frame.
+ *
+ * @example
+ * ```ts
+ * import { gravityAt, rotateVector, type CraftForces } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const earth = [{ gm: 3.986004418e14, position: [0, 0, 0] as const }];
+ * const pushAlongNose: CraftForces = {
+ *   inertia: [1_000, 1_000, 1_000],
+ *   acceleration: (_t, p, _v, q) => {
+ *     const g = gravityAt(p, earth);
+ *     const push = rotateVector(q, [0, 0.1, 0]);
+ *     return [g[0] + push[0], g[1] + push[1], g[2] + push[2]];
+ *   },
+ *   torque: () => [0, 0, 1],
+ * };
+ * console.log(pushAlongNose.inertia);
+ * ```
+ */
+export interface CraftForces {
+    /** The principal moments of inertia, kg m^2. */
+    inertia: Vec3;
+    acceleration: (t: number, position: Vec3, velocity: Vec3, q: Quat) => Vec3;
+    /** No torque when left out. */
+    torque?: Torque;
+}
+/**
+ * One step of a craft's place and attitude together: Orbiter's `RK4_LinAng`, the fourth-order Runge-Kutta step with the position, the speed, the attitude and the turn rate moved as one, so a push along the nose follows the turning nose.
+ * @param craft The craft now.
+ * @param h The step, seconds.
+ * @param forces What moves it.
+ * @returns The craft `h` seconds later.
+ * @example
+ * ```ts
+ * import { gravityAt, stepCraft } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const next = stepCraft({ t: 0, position: [6_778_000, 0, 0], velocity: [0, 7_669, 0], q: [1, 0, 0, 0], omega: [0, 0, 0.01] }, 1, { inertia: [1_000, 1_000, 1_000], acceleration: (_t, p) => gravityAt(p, [{ gm: 3.986004418e14, position: [0, 0, 0] }]) });
+ * console.log(next.t, next.omega);
+ * ```
+ */
+export declare function stepCraft(craft: Craft, h: number, forces: CraftForces): Craft;