@johnmorrisdotca/uchusen-rockets 0.10.0 → 0.11.0

package/dist/journey/countdown.js

@@ -0,0 +1,56 @@
+/**
+ * The engine preheat bar before ignition: ten segments and a percent. It fills from 13 seconds before lift-off to 3 seconds before, and is full after.
+ * @param missionS Mission seconds from lift-off (negative before).
+ * @returns The percent (0 to 100), how many of the ten segments are full, and how full the next one is (0 to 1).
+ * @example
+ * ```ts
+ * import { preheat } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(preheat(-8.5));
+ * ```
+ */
+export function preheat(missionS) {
+    const share = Math.max(0, Math.min(1, (missionS + 13) / 10));
+    const percent = Math.round(share * 100);
+    const full = Math.min(10, Math.floor(share * 10));
+    return { percent, full, partial: full >= 10 ? 0 : share * 10 - full };
+}
+/**
+ * The ignition count: IGNITION IN 3, 2, 1, then 0 from lift-off, with how far round the ring dial has gone.
+ * @param missionS Mission seconds from lift-off (negative before).
+ * @returns The number to show (3, 2, 1 or 0) and the ring's sweep (0 to 1).
+ * @example
+ * ```ts
+ * import { ignition } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(ignition(-2.2), ignition(0));
+ * ```
+ */
+export function ignition(missionS) {
+    if (missionS >= 0)
+        return { count: 0, ring: 1 };
+    return { count: Math.max(0, Math.min(3, Math.ceil(-missionS))), ring: Math.max(0, Math.min(1, (missionS + 3) / 3)) };
+}
+/**
+ * The timer before and during the braking burn: DECELERATION BURN IN until it starts, DECELERATION COMPLETE IN while it runs, nothing after.
+ * @param trip A planned trip.
+ * @param missionS Mission seconds from lift-off.
+ * @returns Which timer, and its seconds; or null when there is none to show.
+ * @example
+ * ```ts no-run
+ * import { burnTimer, type Trip } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * declare const trip: Trip;
+ * console.log(burnTimer(trip, 10));
+ * ```
+ */
+export function burnTimer(trip, missionS) {
+    const braking = trip.phases.find((phase) => phase.id === "brake" || phase.id === "decelerate" || phase.id === "flyby");
+    if (!braking || missionS < 0)
+        return null;
+    if (missionS < braking.startS)
+        return { kind: "burn-in", seconds: braking.startS - missionS };
+    if (missionS < braking.endS)
+        return { kind: "complete-in", seconds: braking.endS - missionS };
+    return null;
+}

package/dist/journey/crafts.d.ts

@@ -0,0 +1,165 @@
+import type { SourceId } from "../data/sources.ts";
+/**
+ * A number with where it is from. Either `source` names a source of this package, or `estimate` says what it is worked from; one of the two is always there.
+ *
+ * @example
+ * ```ts
+ * import { CRAFTS } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const saturn = CRAFTS.find((craft) => craft.id === "saturn-v");
+ * const tli = saturn?.drive === "ballistic" ? saturn.capacityKg.tli : undefined;
+ * console.log(tli?.value, tli?.source);
+ * ```
+ */
+export interface Quantity {
+    value: number;
+    source: SourceId | null;
+    /** For a number that no source gives: what it is worked from. Shown with "est." wherever the number is. */
+    estimate?: string;
+    note?: string;
+}
+/** The kinds of orbit a launch vehicle's payload figure is given for, lowest energy first. */
+export type CapacityKind = "leo" | "gto" | "tli" | "mars";
+export interface Payload {
+    name: string;
+    massKg: Quantity;
+    /** The thrust of the engine that brakes it at arrival, newtons. */
+    thrustN?: Quantity;
+    /** What that engine can change its speed by, metres a second. */
+    dvMs?: Quantity;
+    /** Used where no thrust is given: the braking acceleration, in g. */
+    brakeG?: Quantity;
+    /** The specific impulse of the braking engine, seconds: what turns a speed change into propellant. */
+    ispS?: Quantity;
+}
+/**
+ * What of a rocket is still there at one point of a trip, drawn with the rocket's own parts: the whole rocket, or the slots that are left, of the rocket and variant named.
+ *
+ * @example
+ * ```ts
+ * import type { Stage } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const left: Stage = { rocket: "saturn-v", variant: "saturn-v", slots: ["service-module", "capsule"], name: "Apollo command and service module" };
+ * console.log(left.name);
+ * ```
+ */
+export interface Stage {
+    rocket: string;
+    variant: string;
+    /** The slots that are left, closed up into one stack; null for the whole rocket. */
+    slots: readonly string[] | null;
+    name: string;
+}
+/**
+ * A rocket that flies a Hohmann transfer: its published payloads and the spacecraft it carries.
+ *
+ * @example
+ * ```ts
+ * import { CRAFTS } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(CRAFTS.filter((craft) => craft.drive === "ballistic").map((craft) => craft.name));
+ * ```
+ */
+export interface BallisticCraft {
+    id: string;
+    name: string;
+    kind: "real";
+    drive: "ballistic";
+    /** The rocket and variant the stage draws. */
+    rocket: string;
+    variant: string;
+    capacityKg: Partial<Record<CapacityKind, Quantity>>;
+    payload: Payload;
+    /** Seconds from lift-off to the parking orbit. */
+    ascentS: Quantity;
+    /** Seconds of the departure burn, where a source gives it. */
+    departureBurnS?: Quantity;
+    /** Seconds the craft takes to turn round before the braking burn. */
+    flipS: Quantity;
+    /** What is left after each burn: the whole rocket at lift-off, the upper stage with its payload for the departure burn and the coast, the payload alone from the turn round. */
+    stages: {
+        launch: Stage;
+        upper: Stage;
+        payload: Stage;
+    };
+    /** Which way the drawing looks: `front` for a rocket with boosters on its sides, so that all of its cores show. */
+    launchView: "side" | "front";
+}
+/**
+ * A ship that burns all the way: constant acceleration, a turn round at the halfway point, the same acceleration to stop.
+ *
+ * @example
+ * ```ts
+ * import { CRAFTS } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const ship = CRAFTS.find((craft) => craft.drive === "continuous");
+ * console.log(ship?.name);
+ * ```
+ */
+export interface ContinuousCraft {
+    id: string;
+    name: string;
+    kind: "fleet";
+    drive: "continuous";
+    rocket: string;
+    variant: string;
+    /** Proper acceleration, in g. */
+    g: Quantity;
+    /** Exhaust speed as a fraction of the speed of light. */
+    exhaustOfC: Quantity;
+    dryT: Quantity;
+    payloadT: Quantity;
+    propellantT: Quantity;
+    flipS: Quantity;
+}
+/**
+ * A craft the journey can fly: a rocket on a Hohmann transfer, or a ship that burns all the way.
+ *
+ * @example
+ * ```ts
+ * import { CRAFTS, type Craft } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const first: Craft = CRAFTS[0]!;
+ * console.log(first.name, first.drive);
+ * ```
+ */
+export type Craft = BallisticCraft | ContinuousCraft;
+/**
+ * Every craft the journey offers: three real rockets and one ship of the SPX fleet. A figure names its source, or is marked as an estimate and says what it is worked from.
+ *
+ * @example
+ * ```ts
+ * import { CRAFTS } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(CRAFTS.map((craft) => craft.id));
+ * ```
+ */
+export declare const CRAFTS: readonly Craft[];
+/**
+ * What of a craft is left at a phase of its trip, to draw: the whole rocket until the ascent is over, the upper stage with its payload for the departure burn and the coast, and the payload alone from the turn round. A ship that burns all the way is whole throughout.
+ *
+ * @param craft A craft.
+ * @param phase The phase of the trip, such as `coast`.
+ * @returns The rocket, variant and slots to draw, and a name for them.
+ * @example
+ * ```ts
+ * import { craftOf, stageOf } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const saturn = craftOf("saturn-v")!;
+ * console.log(stageOf(saturn, "ascent").name, stageOf(saturn, "coast").name, stageOf(saturn, "brake").name);
+ * ```
+ */
+export declare function stageOf(craft: Craft, phase: string): Stage;
+/**
+ * A craft by its id.
+ *
+ * @param id A craft's id.
+ * @returns The craft, or undefined when there is none.
+ * @example
+ * ```ts
+ * import { craftOf } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(craftOf("sls")?.name, craftOf("nothing"));
+ * ```
+ */
+export declare const craftOf: (id: string) => Craft | undefined;

package/dist/journey/crafts.js

@@ -0,0 +1,142 @@
+const ascentEstimate = (seconds) => ({ value: seconds, source: null, estimate: "A rocket of this class reaches orbit in about eight to nine minutes; this craft's own figure is not in the sources read." });
+/**
+ * Every craft the journey offers: three real rockets and one ship of the SPX fleet. A figure names its source, or is marked as an estimate and says what it is worked from.
+ *
+ * @example
+ * ```ts
+ * import { CRAFTS } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(CRAFTS.map((craft) => craft.id));
+ * ```
+ */
+export const CRAFTS = [
+    {
+        id: "saturn-v",
+        name: "Saturn V",
+        kind: "real",
+        drive: "ballistic",
+        rocket: "saturn-v",
+        variant: "saturn-v",
+        capacityKg: {
+            leo: { value: 140_000, source: "wikipedia-saturn-v", note: "Includes the S-IVB stage and the propellant for trans-lunar injection." },
+            tli: { value: 43_500, source: "wikipedia-saturn-v" },
+        },
+        payload: {
+            name: "Apollo command and service module with the lunar module",
+            massKg: { value: 43_500, source: "wikipedia-saturn-v", note: "The trans-lunar payload." },
+            thrustN: { value: 91_189, source: "wikipedia-apollo-csm", note: "The service propulsion engine, 20,500 lbf." },
+            ispS: { value: 314, source: "wikipedia-apollo-csm", note: "The service propulsion engine's specific impulse." },
+        },
+        ascentS: { value: 700, source: "wikipedia-saturn-v", note: "The third stage's first cut-off, about 11 minutes 40 seconds after lift-off." },
+        departureBurnS: { value: 350, source: "wikipedia-saturn-v", note: "The article says the third stage burned for almost six minutes for trans-lunar injection." },
+        flipS: { value: 120, source: null, estimate: "Transposition, docking and extraction took tens of minutes; the turn before a braking burn is taken as two minutes." },
+        launchView: "side",
+        stages: {
+            launch: { rocket: "saturn-v", variant: "saturn-v", slots: null, name: "Saturn V" },
+            upper: { rocket: "saturn-v", variant: "saturn-v", slots: ["third-stage", "adapter", "service-module", "capsule"], name: "S-IVB with the Apollo spacecraft" },
+            payload: { rocket: "saturn-v", variant: "saturn-v", slots: ["service-module", "capsule"], name: "Apollo command and service module" },
+        },
+    },
+    {
+        id: "sls",
+        name: "Space Launch System",
+        kind: "real",
+        drive: "ballistic",
+        rocket: "sls",
+        variant: "block-1",
+        capacityKg: {
+            leo: { value: 95_000, source: "wikipedia-sls" },
+            tli: { value: 27_000, source: "wikipedia-sls", note: "59,500 lb." },
+        },
+        payload: {
+            name: "Orion with its service module",
+            massKg: { value: 26_375, source: "wikipedia-orion", note: "After separation from the upper stage." },
+            thrustN: { value: 26_600, source: "wikipedia-esm", note: "The AJ10 main engine of the European Service Module." },
+            dvMs: { value: 1_050, source: "wikipedia-orion", note: "What NASA's interface document says Orion can change its speed by after the upper stage." },
+        },
+        ascentS: ascentEstimate(480),
+        flipS: { value: 120, source: null, estimate: "The turn before a braking burn is taken as two minutes." },
+        launchView: "front",
+        stages: {
+            launch: { rocket: "sls", variant: "block-1", slots: null, name: "Space Launch System" },
+            upper: { rocket: "sls", variant: "block-1", slots: ["upper-stage", "service-module", "capsule"], name: "Upper stage with Orion" },
+            payload: { rocket: "sls", variant: "block-1", slots: ["service-module", "capsule"], name: "Orion" },
+        },
+    },
+    {
+        id: "falcon-heavy",
+        name: "Falcon Heavy",
+        kind: "real",
+        drive: "ballistic",
+        rocket: "falcon-heavy",
+        variant: "falcon-heavy",
+        capacityKg: {
+            leo: { value: 63_800, source: "wikipedia-falcon-heavy", note: "With every stage expended." },
+            gto: { value: 26_700, source: "wikipedia-falcon-heavy" },
+            mars: { value: 16_800, source: "wikipedia-falcon-heavy" },
+        },
+        payload: {
+            name: "A spacecraft of the Mars-transfer payload mass",
+            massKg: { value: 16_800, source: "wikipedia-falcon-heavy", note: "The Mars figure." },
+            brakeG: { value: 0.2, source: null, estimate: "The article names no spacecraft, so no engine: 0.2 g is a typical figure for a storable-propellant main engine on a craft of this mass." },
+        },
+        ascentS: ascentEstimate(540),
+        flipS: { value: 120, source: null, estimate: "The turn before a braking burn is taken as two minutes." },
+        launchView: "front",
+        stages: {
+            launch: { rocket: "falcon-heavy", variant: "falcon-heavy", slots: null, name: "Falcon Heavy" },
+            upper: { rocket: "falcon-9", variant: "block-5", slots: ["second-stage", "fairing"], name: "Upper stage with its payload" },
+            payload: { rocket: "falcon-9", variant: "block-5", slots: ["fairing"], name: "The payload in its fairing" },
+        },
+    },
+    {
+        id: "kaminari",
+        name: "ISV Kaminari, SPX-207",
+        kind: "fleet",
+        drive: "continuous",
+        rocket: "fleet-02",
+        variant: "fleet-02",
+        g: { value: 0.015, source: "uchusen-fleet-ship-02", note: "Rated proper acceleration." },
+        exhaustOfC: { value: 0.4, source: "uchusen-fleet-ship-02", note: "The fusion torch's effective exhaust speed." },
+        dryT: { value: 1_100_000, source: "uchusen-fleet-ship-02" },
+        payloadT: { value: 1_000_000, source: "uchusen-fleet-ship-02" },
+        propellantT: { value: 6_350_000, source: "uchusen-fleet-ship-02" },
+        flipS: { value: 600, source: null, estimate: "A ship 1,820 m long turned end for end by its vernier clusters: ten minutes." },
+    },
+];
+/**
+ * What of a craft is left at a phase of its trip, to draw: the whole rocket until the ascent is over, the upper stage with its payload for the departure burn and the coast, and the payload alone from the turn round. A ship that burns all the way is whole throughout.
+ *
+ * @param craft A craft.
+ * @param phase The phase of the trip, such as `coast`.
+ * @returns The rocket, variant and slots to draw, and a name for them.
+ * @example
+ * ```ts
+ * import { craftOf, stageOf } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const saturn = craftOf("saturn-v")!;
+ * console.log(stageOf(saturn, "ascent").name, stageOf(saturn, "coast").name, stageOf(saturn, "brake").name);
+ * ```
+ */
+export function stageOf(craft, phase) {
+    if (craft.drive === "continuous")
+        return { rocket: craft.rocket, variant: craft.variant, slots: null, name: craft.name };
+    if (phase === "burn" || phase === "coast")
+        return craft.stages.upper;
+    if (phase === "flip" || phase === "brake" || phase === "flyby" || phase === "arrival")
+        return craft.stages.payload;
+    return craft.stages.launch;
+}
+/**
+ * A craft by its id.
+ *
+ * @param id A craft's id.
+ * @returns The craft, or undefined when there is none.
+ * @example
+ * ```ts
+ * import { craftOf } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(craftOf("sls")?.name, craftOf("nothing"));
+ * ```
+ */
+export const craftOf = (id) => CRAFTS.find((craft) => craft.id === id);

package/dist/journey/index.d.ts

@@ -0,0 +1,11 @@
+export { AU_KM, AU_M, C, DAY_S, G0, GM_KM3_S2, LY_M, PARKING_ALTITUDE_KM, PERIOD_DAYS, YEAR_S } from "./constants.ts";
+export { circularSpeed, escapeBurn, flipAndBurn, hohmann, kepler, synodicPeriod } from "./physics.ts";
+export type { BodySource, Stop } from "./bodies.ts";
+export { CRAFTS, craftOf, stageOf } from "./crafts.ts";
+export type { BallisticCraft, ContinuousCraft, Craft, Quantity, Stage } from "./crafts.ts";
+export { bestDate, planTrip, windows } from "./trip.ts";
+export type { Phase, Trip, Verdict, Window } from "./trip.ts";
+export { placeAt, playSeconds, stateAt } from "./timeline.ts";
+export type { Place, PlaySpeed, State } from "./timeline.ts";
+export { burnTimer, ignition, preheat } from "./countdown.ts";
+export { astronomicalUnits, duration, gWords, kilometres, lightTime, percentOfLight, speedWords, tonnesWords } from "./words.ts";

package/dist/journey/index.js

@@ -0,0 +1,8 @@
+// Journey mode: the arithmetic and the plan of a trip between places in the solar system. Pure: no DOM, no three.js, no dependency (a page hands it a `BodySource`).
+export { AU_KM, AU_M, C, DAY_S, G0, GM_KM3_S2, LY_M, PARKING_ALTITUDE_KM, PERIOD_DAYS, YEAR_S } from "./constants.js";
+export { circularSpeed, escapeBurn, flipAndBurn, hohmann, kepler, synodicPeriod } from "./physics.js";
+export { CRAFTS, craftOf, stageOf } from "./crafts.js";
+export { bestDate, planTrip, windows } from "./trip.js";
+export { placeAt, playSeconds, stateAt } from "./timeline.js";
+export { burnTimer, ignition, preheat } from "./countdown.js";
+export { astronomicalUnits, duration, gWords, kilometres, lightTime, percentOfLight, speedWords, tonnesWords } from "./words.js";

package/dist/journey/physics.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Speed of a circular orbit, kilometres a second.
+ * @param muKm3s2 The body's gravitational parameter, km^3/s^2.
+ * @param rKm The orbit's radius from the body's centre, km.
+ * @returns The speed, km/s.
+ * @example
+ * ```ts
+ * import { circularSpeed } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(circularSpeed(398600.4418, 6378.137 + 185).toFixed(2));
+ * ```
+ */
+export declare const circularSpeed: (muKm3s2: number, rKm: number) => number;
+/**
+ * The Hohmann transfer between two circular orbits about one body: its half-ellipse, its time and the two speed changes.
+ * @param muKm3s2 The central body's gravitational parameter, km^3/s^2.
+ * @param r1Km The starting radius, km.
+ * @param r2Km The final radius, km.
+ * @returns The semi-major axis (km), the flight time (seconds), the speed change at the start and at the end (km/s, both positive).
+ * @example
+ * ```ts
+ * import { GM_KM3_S2, hohmann } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const mars = hohmann(GM_KM3_S2.sun!, 149_597_870.7, 1.52371034 * 149_597_870.7);
+ * console.log((mars.seconds / 86400).toFixed(1), mars.dv1.toFixed(2), mars.dv2.toFixed(2));
+ * ```
+ */
+export declare function hohmann(muKm3s2: number, r1Km: number, r2Km: number): {
+    a: number;
+    seconds: number;
+    dv1: number;
+    dv2: number;
+};
+/**
+ * The burn that takes a craft from a circular parking orbit onto a path that leaves with a given speed at infinity, or, run the other way, that captures it into the same circular orbit: `sqrt(v_inf^2 + 2 mu / r) - sqrt(mu / r)`.
+ * @param muKm3s2 The body's gravitational parameter, km^3/s^2.
+ * @param rKm The parking orbit's radius, km.
+ * @param vInfKmS The speed relative to the body once far from it, km/s.
+ * @returns The speed change, km/s.
+ * @example
+ * ```ts
+ * import { escapeBurn } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(escapeBurn(398600.4418, 6378.137 + 185, 2.94).toFixed(2));
+ * ```
+ */
+export declare const escapeBurn: (muKm3s2: number, rKm: number, vInfKmS: number) => number;
+/**
+ * The time between two meetings of two bodies in circular orbits, from their periods: `1 / |1/T1 - 1/T2|`.
+ * @param period1 The first period, any unit.
+ * @param period2 The second period, in the same unit.
+ * @returns The synodic period, in that unit.
+ * @example
+ * ```ts
+ * import { synodicPeriod } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(synodicPeriod(365.256, 686.98).toFixed(1));
+ * ```
+ */
+export declare const synodicPeriod: (period1: number, period2: number) => number;
+/**
+ * Kepler's equation `M = E - e sin E`, solved for the eccentric anomaly by Newton's method.
+ * @param meanAnomaly The mean anomaly, radians.
+ * @param e The eccentricity, 0 to below 1.
+ * @returns The eccentric anomaly, radians, in the same turn as the mean anomaly.
+ * @example
+ * ```ts
+ * import { kepler } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(kepler(1, 0.2).toFixed(4));
+ * ```
+ */
+export declare function kepler(meanAnomaly: number, e: number): number;
+/** Where a craft is on a Hohmann half-ellipse `t` seconds after its burn: its distance from the centre (km), its direction (radians, from the departure direction `theta0`) and its speed (km/s). */
+export declare function transferPoint(muKm3s2: number, r1Km: number, r2Km: number, theta0: number, t: number): {
+    r: number;
+    theta: number;
+    v: number;
+};
+/** The state of a craft that has burned at constant proper acceleration `a` (m/s^2) for `t` seconds of the frame's time, from rest: distance (m), speed (m/s), Lorentz factor and time on board (s). */
+export declare function accelerating(a: number, t: number): {
+    x: number;
+    v: number;
+    gamma: number;
+    proper: number;
+};
+/**
+ * A trip of constant acceleration with a turn round in the middle: burn to the halfway point, coast while the craft turns end for end, burn the same acceleration to stop. The relativistic constant-proper-acceleration answer, which is `2 sqrt(d / a)` for slow trips.
+ * @param distanceM The distance between the two ends, in the frame in which both are at rest, metres.
+ * @param a The proper acceleration, m/s^2.
+ * @param flipSeconds How long the turn takes, during which the craft coasts at its peak speed. 0 for the textbook flip.
+ * @returns How long each burn lasts in the frame's time, the peak speed, the Lorentz factor then, the time on board and in the frame, and the rapidity at the flip.
+ * @example
+ * ```ts
+ * import { flipAndBurn, G0, LY_M } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const trip = flipAndBurn(4.37 * LY_M, G0, 0);
+ * console.log((trip.properSeconds / 31_557_600).toFixed(1), (trip.peakSpeed / 299_792_458).toFixed(3));
+ * ```
+ */
+export declare function flipAndBurn(distanceM: number, a: number, flipSeconds: number): {
+    burnSeconds: number;
+    peakSpeed: number;
+    gamma: number;
+    properSeconds: number;
+    frameSeconds: number;
+    rapidity: number;
+};
+/** The propellant a rocket of exhaust speed `ve` uses to change its speed by `dv` (the Tsiolkovsky equation): the fraction of its starting mass, 0 to 1. Both speeds in the same unit. */
+export declare const propellantFraction: (dv: number, ve: number) => number;
+/** An angle brought into -pi to pi. */
+export declare const wrapPi: (angle: number) => number;
+/** The Lorentz factor of a speed in metres a second. */
+export declare const lorentz: (v: number) => number;

package/dist/journey/physics.js

@@ -0,0 +1,154 @@
+// The arithmetic of a trip: circular and escape speeds, the Hohmann transfer, leaving and entering a gravity well, Kepler's equation, the synodic period and constant acceleration with a flip.
+// Newtonian where the speeds are slow, relativistic (constant proper acceleration) for the flip and burn, which reduces to the Newtonian answer in the solar system. Pure: no clock, no DOM, no dependency.
+import { C } from "./constants.js";
+const TAU = 2 * Math.PI;
+/**
+ * Speed of a circular orbit, kilometres a second.
+ * @param muKm3s2 The body's gravitational parameter, km^3/s^2.
+ * @param rKm The orbit's radius from the body's centre, km.
+ * @returns The speed, km/s.
+ * @example
+ * ```ts
+ * import { circularSpeed } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(circularSpeed(398600.4418, 6378.137 + 185).toFixed(2));
+ * ```
+ */
+export const circularSpeed = (muKm3s2, rKm) => Math.sqrt(muKm3s2 / rKm);
+/**
+ * The Hohmann transfer between two circular orbits about one body: its half-ellipse, its time and the two speed changes.
+ * @param muKm3s2 The central body's gravitational parameter, km^3/s^2.
+ * @param r1Km The starting radius, km.
+ * @param r2Km The final radius, km.
+ * @returns The semi-major axis (km), the flight time (seconds), the speed change at the start and at the end (km/s, both positive).
+ * @example
+ * ```ts
+ * import { GM_KM3_S2, hohmann } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const mars = hohmann(GM_KM3_S2.sun!, 149_597_870.7, 1.52371034 * 149_597_870.7);
+ * console.log((mars.seconds / 86400).toFixed(1), mars.dv1.toFixed(2), mars.dv2.toFixed(2));
+ * ```
+ */
+export function hohmann(muKm3s2, r1Km, r2Km) {
+    const a = (r1Km + r2Km) / 2;
+    const seconds = Math.PI * Math.sqrt((a * a * a) / muKm3s2);
+    const dv1 = Math.abs(Math.sqrt(muKm3s2 / r1Km) * (Math.sqrt((2 * r2Km) / (r1Km + r2Km)) - 1));
+    const dv2 = Math.abs(Math.sqrt(muKm3s2 / r2Km) * (1 - Math.sqrt((2 * r1Km) / (r1Km + r2Km))));
+    return { a, seconds, dv1, dv2 };
+}
+/**
+ * The burn that takes a craft from a circular parking orbit onto a path that leaves with a given speed at infinity, or, run the other way, that captures it into the same circular orbit: `sqrt(v_inf^2 + 2 mu / r) - sqrt(mu / r)`.
+ * @param muKm3s2 The body's gravitational parameter, km^3/s^2.
+ * @param rKm The parking orbit's radius, km.
+ * @param vInfKmS The speed relative to the body once far from it, km/s.
+ * @returns The speed change, km/s.
+ * @example
+ * ```ts
+ * import { escapeBurn } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(escapeBurn(398600.4418, 6378.137 + 185, 2.94).toFixed(2));
+ * ```
+ */
+export const escapeBurn = (muKm3s2, rKm, vInfKmS) => Math.sqrt(vInfKmS * vInfKmS + (2 * muKm3s2) / rKm) - Math.sqrt(muKm3s2 / rKm);
+/**
+ * The time between two meetings of two bodies in circular orbits, from their periods: `1 / |1/T1 - 1/T2|`.
+ * @param period1 The first period, any unit.
+ * @param period2 The second period, in the same unit.
+ * @returns The synodic period, in that unit.
+ * @example
+ * ```ts
+ * import { synodicPeriod } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(synodicPeriod(365.256, 686.98).toFixed(1));
+ * ```
+ */
+export const synodicPeriod = (period1, period2) => 1 / Math.abs(1 / period1 - 1 / period2);
+/**
+ * Kepler's equation `M = E - e sin E`, solved for the eccentric anomaly by Newton's method.
+ * @param meanAnomaly The mean anomaly, radians.
+ * @param e The eccentricity, 0 to below 1.
+ * @returns The eccentric anomaly, radians, in the same turn as the mean anomaly.
+ * @example
+ * ```ts
+ * import { kepler } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * console.log(kepler(1, 0.2).toFixed(4));
+ * ```
+ */
+export function kepler(meanAnomaly, e) {
+    const turns = Math.floor(meanAnomaly / TAU);
+    const m = meanAnomaly - turns * TAU;
+    let big = e < 0.8 ? m : Math.PI;
+    for (let i = 0; i < 30; i += 1) {
+        const step = (big - e * Math.sin(big) - m) / (1 - e * Math.cos(big));
+        big -= step;
+        if (Math.abs(step) < 1e-13)
+            break;
+    }
+    return big + turns * TAU;
+}
+/** Where a craft is on a Hohmann half-ellipse `t` seconds after its burn: its distance from the centre (km), its direction (radians, from the departure direction `theta0`) and its speed (km/s). */
+export function transferPoint(muKm3s2, r1Km, r2Km, theta0, t) {
+    const a = (r1Km + r2Km) / 2;
+    const e = Math.abs(r2Km - r1Km) / (r1Km + r2Km);
+    const outward = r2Km >= r1Km;
+    const n = Math.sqrt(muKm3s2 / (a * a * a));
+    const big = kepler((outward ? 0 : Math.PI) + n * t, e);
+    const nu = 2 * Math.atan2(Math.sqrt(1 + e) * Math.sin(big / 2), Math.sqrt(1 - e) * Math.cos(big / 2));
+    const r = a * (1 - e * Math.cos(big));
+    return { r, theta: theta0 + (outward ? nu : nu - Math.PI), v: Math.sqrt(muKm3s2 * (2 / r - 1 / a)) };
+}
+/** The state of a craft that has burned at constant proper acceleration `a` (m/s^2) for `t` seconds of the frame's time, from rest: distance (m), speed (m/s), Lorentz factor and time on board (s). */
+export function accelerating(a, t) {
+    const s = (a * t) / C;
+    const root = Math.sqrt(1 + s * s);
+    return { x: ((C * C) / a) * (root - 1), v: (a * t) / root, gamma: root, proper: (C / a) * Math.asinh(s) };
+}
+/**
+ * A trip of constant acceleration with a turn round in the middle: burn to the halfway point, coast while the craft turns end for end, burn the same acceleration to stop. The relativistic constant-proper-acceleration answer, which is `2 sqrt(d / a)` for slow trips.
+ * @param distanceM The distance between the two ends, in the frame in which both are at rest, metres.
+ * @param a The proper acceleration, m/s^2.
+ * @param flipSeconds How long the turn takes, during which the craft coasts at its peak speed. 0 for the textbook flip.
+ * @returns How long each burn lasts in the frame's time, the peak speed, the Lorentz factor then, the time on board and in the frame, and the rapidity at the flip.
+ * @example
+ * ```ts
+ * import { flipAndBurn, G0, LY_M } from "@johnmorrisdotca/uchusen-rockets/journey";
+ *
+ * const trip = flipAndBurn(4.37 * LY_M, G0, 0);
+ * console.log((trip.properSeconds / 31_557_600).toFixed(1), (trip.peakSpeed / 299_792_458).toFixed(3));
+ * ```
+ */
+export function flipAndBurn(distanceM, a, flipSeconds) {
+    // distance = 2 x(tb) + v(tb) flip, with x and v the burn's own: increasing in tb, so bisect.
+    const reach = (tb) => {
+        const s = accelerating(a, tb);
+        return 2 * s.x + s.v * flipSeconds;
+    };
+    let lo = 0;
+    let hi = Math.max(1, Math.sqrt(distanceM / a) * 2);
+    while (reach(hi) < distanceM)
+        hi *= 2;
+    for (let i = 0; i < 200; i += 1) {
+        const mid = (lo + hi) / 2;
+        if (reach(mid) < distanceM)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const burnSeconds = (lo + hi) / 2;
+    const peak = accelerating(a, burnSeconds);
+    return {
+        burnSeconds,
+        peakSpeed: peak.v,
+        gamma: peak.gamma,
+        properSeconds: 2 * peak.proper + flipSeconds / peak.gamma,
+        frameSeconds: 2 * burnSeconds + flipSeconds,
+        rapidity: Math.asinh((a * burnSeconds) / C),
+    };
+}
+/** The propellant a rocket of exhaust speed `ve` uses to change its speed by `dv` (the Tsiolkovsky equation): the fraction of its starting mass, 0 to 1. Both speeds in the same unit. */
+export const propellantFraction = (dv, ve) => 1 - Math.exp(-dv / ve);
+/** An angle brought into -pi to pi. */
+export const wrapPi = (angle) => angle - TAU * Math.round(angle / TAU);
+/** The Lorentz factor of a speed in metres a second. */
+export const lorentz = (v) => 1 / Math.sqrt(1 - (v / C) ** 2);