@johnmorrisdotca/uchusen-rockets 0.19.0 → 0.20.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;