@johnhenry/math 0.0.0

package/src/Quaternion.ts

@@ -0,0 +1,125 @@
+/**
+ * Quaternion — a number of the form `w + x·i + y·j + z·k`, the four-dimensional
+ * division algebra. Extends the idea of {@link ComplexNumber} and is the
+ * standard tool for representing and composing 3D rotations.
+ */
+export class Quaternion {
+  readonly w: number;
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+
+  static readonly Identity = new Quaternion(1, 0, 0, 0);
+  static readonly Zero = new Quaternion(0, 0, 0, 0);
+
+  constructor(w = 0, x = 0, y = 0, z = 0) {
+    this.w = w;
+    this.x = x;
+    this.y = y;
+    this.z = z;
+  }
+
+  add(q: Quaternion): Quaternion {
+    return new Quaternion(this.w + q.w, this.x + q.x, this.y + q.y, this.z + q.z);
+  }
+
+  subtract(q: Quaternion): Quaternion {
+    return new Quaternion(this.w - q.w, this.x - q.x, this.y - q.y, this.z - q.z);
+  }
+
+  scale(s: number): Quaternion {
+    return new Quaternion(this.w * s, this.x * s, this.y * s, this.z * s);
+  }
+
+  negate(): Quaternion {
+    return new Quaternion(-this.w, -this.x, -this.y, -this.z);
+  }
+
+  /** The Hamilton product (non-commutative). */
+  multiply(q: Quaternion): Quaternion {
+    return new Quaternion(
+      this.w * q.w - this.x * q.x - this.y * q.y - this.z * q.z,
+      this.w * q.x + this.x * q.w + this.y * q.z - this.z * q.y,
+      this.w * q.y - this.x * q.z + this.y * q.w + this.z * q.x,
+      this.w * q.z + this.x * q.y - this.y * q.x + this.z * q.w,
+    );
+  }
+
+  conjugate(): Quaternion {
+    return new Quaternion(this.w, -this.x, -this.y, -this.z);
+  }
+
+  dot(q: Quaternion): number {
+    return this.w * q.w + this.x * q.x + this.y * q.y + this.z * q.z;
+  }
+
+  get norm(): number {
+    return Math.hypot(this.w, this.x, this.y, this.z);
+  }
+
+  normalize(): Quaternion {
+    const n = this.norm;
+    if (n === 0) throw new Error("Cannot normalize the zero quaternion.");
+    return this.scale(1 / n);
+  }
+
+  /** Multiplicative inverse `q⁻¹ = conj(q) / |q|²`. */
+  inverse(): Quaternion {
+    const n2 = this.w * this.w + this.x * this.x + this.y * this.y + this.z * this.z;
+    if (n2 === 0) throw new Error("The zero quaternion has no inverse.");
+    return this.conjugate().scale(1 / n2);
+  }
+
+  equals(q: Quaternion): boolean {
+    return this.w === q.w && this.x === q.x && this.y === q.y && this.z === q.z;
+  }
+
+  /** A unit quaternion representing a rotation of `angle` radians about `axis`. */
+  static fromAxisAngle(axis: [number, number, number], angle: number): Quaternion {
+    const [ax, ay, az] = axis;
+    const len = Math.hypot(ax, ay, az) || 1;
+    const half = angle / 2;
+    const s = Math.sin(half) / len;
+    return new Quaternion(Math.cos(half), ax * s, ay * s, az * s);
+  }
+
+  /** Rotate a 3D vector by this (unit) quaternion, returning `[x, y, z]`. */
+  rotateVector(v: [number, number, number]): [number, number, number] {
+    const q = this.normalize();
+    const p = new Quaternion(0, v[0], v[1], v[2]);
+    const r = q.multiply(p).multiply(q.conjugate());
+    return [r.x, r.y, r.z];
+  }
+
+  /** The 3×3 rotation matrix (as `number[][]`) for this quaternion. */
+  toRotationMatrix(): number[][] {
+    const { w, x, y, z } = this.normalize();
+    return [
+      [1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w)],
+      [2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w)],
+      [2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y)],
+    ];
+  }
+
+  /** Spherical linear interpolation between two unit quaternions. */
+  static slerp(a: Quaternion, b: Quaternion, t: number): Quaternion {
+    const qa = a.normalize();
+    let qb = b.normalize();
+    let cos = qa.dot(qb);
+    if (cos < 0) {
+      qb = qb.scale(-1);
+      cos = -cos;
+    }
+    if (cos > 0.9995) return qa.add(qb.subtract(qa).scale(t)).normalize();
+    const theta0 = Math.acos(cos);
+    const theta = theta0 * t;
+    const sinTheta0 = Math.sin(theta0);
+    const s0 = Math.sin(theta0 - theta) / sinTheta0;
+    const s1 = Math.sin(theta) / sinTheta0;
+    return qa.scale(s0).add(qb.scale(s1));
+  }
+
+  toString(): string {
+    return `${this.w} + ${this.x}i + ${this.y}j + ${this.z}k`;
+  }
+}

package/src/Rational.ts

@@ -0,0 +1,148 @@
+/**
+ * Rational — an exact rational number `numerator / denominator` backed by
+ * `bigint`, always stored in lowest terms with a positive denominator. Gives the
+ * library exact (error-free) arithmetic, e.g. for exact linear algebra or
+ * polynomial GCDs.
+ */
+
+function bgcd(a: bigint, b: bigint): bigint {
+  let x = a < 0n ? -a : a;
+  let y = b < 0n ? -b : b;
+  while (y) [x, y] = [y, x % y];
+  return x;
+}
+
+const toBig = (x: bigint | number): bigint => {
+  if (typeof x === "bigint") return x;
+  if (!Number.isInteger(x)) throw new Error(`Rational requires integer inputs; got ${x}`);
+  return BigInt(x);
+};
+
+export class Rational {
+  readonly numerator: bigint;
+  readonly denominator: bigint;
+
+  static readonly Zero = new Rational(0n, 1n);
+  static readonly One = new Rational(1n, 1n);
+
+  constructor(numerator: bigint | number, denominator: bigint | number = 1n) {
+    let n = toBig(numerator);
+    let d = toBig(denominator);
+    if (d === 0n) throw new Error("Rational denominator must be non-zero.");
+    if (d < 0n) {
+      n = -n;
+      d = -d;
+    }
+    const g = bgcd(n, d) || 1n;
+    this.numerator = n / g;
+    this.denominator = d / g;
+  }
+
+  static from(value: bigint | number | Rational): Rational {
+    if (value instanceof Rational) return value;
+    if (typeof value === "bigint") return new Rational(value, 1n);
+    return Rational.fromNumber(value);
+  }
+
+  /** Best rational approximation of a float via continued fractions. */
+  static fromNumber(value: number, maxDenominator = 1_000_000): Rational {
+    if (Number.isInteger(value)) return new Rational(BigInt(value), 1n);
+    if (!Number.isFinite(value)) throw new Error("Cannot make a Rational from a non-finite number.");
+    let [h0, h1] = [0n, 1n];
+    let [k0, k1] = [1n, 0n];
+    let x = value;
+    const maxD = BigInt(maxDenominator);
+    for (let i = 0; i < 64; i++) {
+      const a = Math.floor(x);
+      const aB = BigInt(a);
+      [h0, h1] = [h1, aB * h1 + h0];
+      [k0, k1] = [k1, aB * k1 + k0];
+      if (k1 > maxD) return new Rational(h0, k0);
+      const frac = x - a;
+      if (frac < 1e-15) break;
+      x = 1 / frac;
+    }
+    return new Rational(h1, k1);
+  }
+
+  add(other: Rational): Rational {
+    return new Rational(
+      this.numerator * other.denominator + other.numerator * this.denominator,
+      this.denominator * other.denominator,
+    );
+  }
+
+  subtract(other: Rational): Rational {
+    return new Rational(
+      this.numerator * other.denominator - other.numerator * this.denominator,
+      this.denominator * other.denominator,
+    );
+  }
+
+  multiply(other: Rational): Rational {
+    return new Rational(this.numerator * other.numerator, this.denominator * other.denominator);
+  }
+
+  divide(other: Rational): Rational {
+    if (other.numerator === 0n) throw new Error("Division by zero Rational.");
+    return new Rational(this.numerator * other.denominator, this.denominator * other.numerator);
+  }
+
+  negate(): Rational {
+    return new Rational(-this.numerator, this.denominator);
+  }
+
+  reciprocal(): Rational {
+    if (this.numerator === 0n) throw new Error("Zero has no reciprocal.");
+    return new Rational(this.denominator, this.numerator);
+  }
+
+  abs(): Rational {
+    return this.numerator < 0n ? this.negate() : this;
+  }
+
+  /** Raise to an integer power (negative powers invert). */
+  pow(exponent: number): Rational {
+    if (!Number.isInteger(exponent)) throw new Error("Rational.pow requires an integer exponent.");
+    if (exponent < 0) return this.reciprocal().pow(-exponent);
+    let result = Rational.One;
+    let base: Rational = this;
+    let e = exponent;
+    while (e > 0) {
+      if (e & 1) result = result.multiply(base);
+      base = base.multiply(base);
+      e >>= 1;
+    }
+    return result;
+  }
+
+  equals(other: Rational): boolean {
+    return this.numerator === other.numerator && this.denominator === other.denominator;
+  }
+
+  /** -1, 0 or 1 depending on ordering against `other`. */
+  compare(other: Rational): number {
+    const diff = this.numerator * other.denominator - other.numerator * this.denominator;
+    return diff < 0n ? -1 : diff > 0n ? 1 : 0;
+  }
+
+  lessThan(other: Rational): boolean {
+    return this.compare(other) < 0;
+  }
+
+  get sign(): number {
+    return this.numerator < 0n ? -1 : this.numerator > 0n ? 1 : 0;
+  }
+
+  isZero(): boolean {
+    return this.numerator === 0n;
+  }
+
+  toNumber(): number {
+    return Number(this.numerator) / Number(this.denominator);
+  }
+
+  toString(): string {
+    return this.denominator === 1n ? `${this.numerator}` : `${this.numerator}/${this.denominator}`;
+  }
+}

package/src/RealMath.ts

@@ -0,0 +1,346 @@
+import { Vector } from "./Vector.ts";
+import { VectorUtils } from "./VectorUtils.ts";
+
+/**
+ * RealMath — arithmetic, trigonometry, numeric calculus and probability over
+ * real numbers, as plain exported functions (no wrapping class — a `static`
+ * method bag buys nothing over top-level functions for pure scalar math).
+ * Ported from Mallory's ActionScript `RealMath`.
+ *
+ * Matrix operations were dropped: `Structure.realField()` already provides
+ * generic linear algebra, and {@link MatrixMath} covers heavier real-only
+ * needs (LU/QR/Cholesky/SVD). Sample statistics (`mean`/`variance`/percentiles/
+ * regression/etc.) moved to {@link Statistics}, which is real-only by nature
+ * (order-dependent stats don't generalize to complex numbers).
+ *
+ * Bugs fixed from the AS3 original:
+ *  - `subtract` returned `a*b` (!).
+ *  - `equal` ignored its tolerance argument (`Math.abs(a-b) <= 0`).
+ *  - `integrateN` used a nonsensical sample point and had an unreachable return.
+ *  - `differentiateN` was a forward difference despite claiming to be symmetric.
+ *  - `crossProduct` read index 3 for the z-component and used truthiness tests.
+ */
+
+type RVec = Vector<number>;
+type Unary = (x: number) => number;
+
+// -- constants ---------------------------------------------------------------
+
+export const Zero = 0;
+export const One = 1;
+export const E = Math.E;
+export const PI = Math.PI;
+export const PHI = 1.61803399;
+export const PositiveInfinity = Infinity;
+export const NegativeInfinity = -Infinity;
+
+// -- Chapter 1: utilities -----------------------------------------------------
+
+export function radiansToDegrees(r: number): number {
+  return (180 / Math.PI) * r;
+}
+
+export function degreesToRadians(d: number): number {
+  return (Math.PI / 180) * d;
+}
+
+// -- Chapter 2: comparison -----------------------------------------------------
+
+/** Equality within `distance` (bug fix: AS3 ignored the tolerance). */
+export function equal(a: number, b: number, distance = 0): boolean {
+  return Math.abs(a - b) <= distance;
+}
+
+export function compare(a: number, b: number): number {
+  if (a > b) return 1;
+  if (a < b) return -1;
+  return 0;
+}
+
+export function lessThan(a: number, b: number): boolean {
+  return a < b;
+}
+
+export function greaterThan(a: number, b: number): boolean {
+  return a > b;
+}
+
+// -- Chapter 3: unary -----------------------------------------------------------
+
+export function negative(a = 0): number {
+  return -a;
+}
+
+/** `1/a` (matches `divide`'s directed-infinity convention rather than always returning NaN). */
+export function reciprocal(a = 1): number {
+  return 1 / a;
+}
+
+/** Round away tiny floating-point noise (rounds to 10 decimal places). */
+export function identity(a = 1): number {
+  return roundTo(a);
+}
+
+// -- Chapter 4: binary -----------------------------------------------------------
+
+export function add(a = 0, b = 0): number {
+  return a + b;
+}
+
+/** Subtraction (bug fix: AS3 returned `a*b`). */
+export function subtract(a = 0, b = 0): number {
+  return a - b;
+}
+
+export function multiply(a = 1, b = 1): number {
+  return a * b;
+}
+
+export function divide(a = 1, b = 1): number {
+  if (b === 0) {
+    if (a > 0) return Infinity;
+    if (a < 0) return -Infinity;
+    return NaN;
+  }
+  return a / b;
+}
+
+// -- Chapter 5: exponential / logarithmic -----------------------------------------
+
+export function power(a = 1, exponent = 1): number {
+  return a ** exponent;
+}
+
+export function square(a = 1): number {
+  return a ** 2;
+}
+
+export function squareRoot(a = 1): number {
+  return Math.sqrt(a);
+}
+
+export function logarithm(a = 1, base = Math.E): number {
+  return Math.log(a) / Math.log(base);
+}
+
+// -- Chapter 6: trigonometry -----------------------------------------------------
+
+export function sine(a = 0): number {
+  return identity(Math.sin(a));
+}
+export function cosine(a = 0): number {
+  return identity(Math.cos(a));
+}
+export function tangent(a = 0): number {
+  return identity(Math.tan(a));
+}
+export function cosecant(a = 0): number {
+  return identity(1 / Math.sin(a));
+}
+export function secant(a = 0): number {
+  return identity(1 / Math.cos(a));
+}
+export function cotangent(a = 0): number {
+  return identity(1 / Math.tan(a));
+}
+
+export function hyperbolicSine(a: number): number {
+  return identity(0.5 * (Math.exp(a) - Math.exp(-a)));
+}
+export function hyperbolicCosine(a: number): number {
+  return identity(0.5 * (Math.exp(a) + Math.exp(-a)));
+}
+export function hyperbolicTangent(a: number): number {
+  return hyperbolicSine(a) / hyperbolicCosine(a);
+}
+export function hyperbolicCosecant(a: number): number {
+  return 1 / hyperbolicSine(a);
+}
+export function hyperbolicSecant(a: number): number {
+  return 1 / hyperbolicCosine(a);
+}
+export function hyperbolicCotangent(a: number): number {
+  return hyperbolicCosine(a) / hyperbolicSine(a);
+}
+
+// -- Chapter 7: series, algebra, calculus -----------------------------------------
+
+export function sumSeries(unaryOperation: Unary, start = 0, end = 0): number {
+  return VectorUtils.collapse(
+    VectorUtils.transform(VectorUtils.arithmeticSequence(start, end), unaryOperation),
+    (a, b) => a + b,
+    0,
+  ) as number;
+}
+
+export function productSeries(unaryOperation: Unary, start = 0, end = 0): number {
+  return VectorUtils.collapse(
+    VectorUtils.transform(VectorUtils.arithmeticSequence(start, end), unaryOperation),
+    (a, b) => a * b,
+    1,
+  ) as number;
+}
+
+/**
+ * Newton–Raphson root finder for `unaryOperation(x) == target`.
+ *
+ * Bug fix: the AS3 version updated `guess -= (f(guess) - target)`, i.e. Newton
+ * with an assumed derivative of 1 — it diverges for almost any nonlinear
+ * function. Here the derivative is estimated numerically ({@link differentiateN})
+ * so the iteration actually converges, and unbounded recursion is replaced by a
+ * bounded loop.
+ */
+export function solveN(
+  unaryOperation: Unary,
+  target: number,
+  desiredAccuracy = 0.01,
+  guess = 0,
+  maxIterations = 10000,
+): number {
+  let x = guess;
+  for (let i = 0; i < maxIterations; i++) {
+    const difference = unaryOperation(x) - target;
+    if (Math.abs(difference) <= desiredAccuracy) return x;
+    const slope = differentiateN(unaryOperation, x, 1e-6);
+    if (slope === 0 || !Number.isFinite(slope)) break;
+    x = x - difference / slope;
+  }
+  return x;
+}
+
+/**
+ * Numeric integral via the midpoint rule (bug fix: the AS3 code sampled at
+ * `2*lowerLimit+interval` and had an unreachable return).
+ */
+export function integrateN(unaryOperation: Unary, lowerLimit: number, upperLimit: number, interval = 0.01): number {
+  if (interval <= 0) throw new RangeError(`RealMath.integrateN: interval must be positive, got ${interval}`);
+  let result = 0;
+  for (let x = lowerLimit; x < upperLimit; x += interval) {
+    result += unaryOperation(x + interval / 2);
+  }
+  return interval * result;
+}
+
+/**
+ * Numeric derivative via the symmetric difference quotient (bug fix: the AS3
+ * code was a forward difference despite the "symmetric" comment).
+ */
+export function differentiateN(unaryOperation: Unary, point: number, limit = 0.01): number {
+  if (limit <= 0) throw new RangeError(`RealMath.differentiateN: limit must be positive, got ${limit}`);
+  return (unaryOperation(point + limit) - unaryOperation(point - limit)) / (2 * limit);
+}
+
+// -- Chapter 9: probability -----------------------------------------------------
+
+export function normalDistribution(mean: number, sDev: number): Unary {
+  return (x: number) => (1 / (sDev * Math.sqrt(2 * Math.PI))) * Math.E ** (-0.5 * ((x - mean) / sDev) ** 2);
+}
+
+export function standardNormalDistribution(x: number): number {
+  return normalDistribution(0, 1)(x);
+}
+
+export function normalProbability(
+  x: number,
+  mean: number,
+  sDev: number,
+  negativeInfinityApproximation = -5,
+  integrationInterval = 0.0001,
+): number {
+  return integrateN(normalDistribution(mean, sDev), negativeInfinityApproximation, x, integrationInterval);
+}
+
+export function standardNormalProbability(z: number, negativeInfinityApproximation = -5, interval = 0.0001): number {
+  return integrateN(standardNormalDistribution, negativeInfinityApproximation, z, interval);
+}
+
+// -- Chapter 8: precision & randomness -----------------------------------------
+
+/** Round to `precision` decimal places (replaces the buggy Flex NumberFormatter). */
+export function roundTo(num: number, precision = 10): number {
+  if (!Number.isFinite(num)) return num;
+  const factor = 10 ** precision;
+  return Math.round(num * factor) / factor;
+}
+
+/** Uniform random in `[min(r1,r2), max(r1,r2)]`. */
+export function random(r1 = 1, r2 = 0, _inclusive = true): number {
+  const low = Math.min(r1, r2);
+  const high = Math.max(r1, r2);
+  return low + Math.random() * (high - low);
+}
+
+/** Placeholder for the random.org fetch; always falls back to {@link random}. */
+export function randomOrg(lower = 0, upper = 1, inclusive = true, fallback = true): number {
+  if (fallback) return random(lower, upper, inclusive);
+  return 0;
+}
+
+export function jitter(a: number, magnitude = 0.1): number {
+  return a + (2 * Math.random() - 1) * magnitude;
+}
+
+// -- Part II Chapter 1: vectors -----------------------------------------------
+
+export function addVector(alpha: RVec, beta: RVec): RVec {
+  return VectorUtils.combine(alpha, beta, add) as RVec;
+}
+
+export function scaleVector(alpha: RVec, scalar: number): RVec {
+  return VectorUtils.transform(alpha, (x) => multiply(scalar, x));
+}
+
+export function negativeVector(alpha: RVec): RVec {
+  return scaleVector(alpha, -1);
+}
+
+export function subtractVector(alpha: RVec, beta: RVec): RVec {
+  return addVector(alpha, negativeVector(beta));
+}
+
+export function dotProduct(alpha: RVec, beta: RVec): number {
+  const collapsable = VectorUtils.combine(alpha, beta, multiply, 0) as RVec;
+  return VectorUtils.collapse(collapsable, add) as number;
+}
+
+/**
+ * 3D cross product (bug fix: the AS3 code read index 3 for the z-component
+ * and used truthiness tests that dropped legitimate zero components).
+ */
+export function crossProduct(alpha: RVec, beta: RVec): RVec {
+  const a = [0, 0, 0];
+  const b = [0, 0, 0];
+  for (let i = 0; i < 3; i++) {
+    if (i < alpha.length && alpha[i] != null) a[i] = alpha[i] as number;
+    if (i < beta.length && beta[i] != null) b[i] = beta[i] as number;
+  }
+  const i = a[1] * b[2] - a[2] * b[1];
+  const j = a[2] * b[0] - a[0] * b[2];
+  const k = a[0] * b[1] - a[1] * b[0];
+  return Vector.fromArray([i, j, k]);
+}
+
+export function kroneckerProduct(A: RVec, B: RVec): RVec {
+  let kronecker = VectorUtils.constantVector(A.length, null as unknown as number) as Vector<unknown>;
+  kronecker = VectorUtils.fillByIndex(kronecker, (i) => scaleVector(B, A[i] as number));
+  return VectorUtils.flattenSDLevels(kronecker, 2) as RVec;
+}
+
+export function distanceVector(alpha: RVec, beta: RVec, norm = 2): number {
+  return pNorm(subtractVector(alpha, beta), norm);
+}
+
+export function pNorm(alpha: RVec, norm = 2): number {
+  if (norm === 0) return Math.max(...VectorUtils.transform(alpha, Math.abs));
+  const summable = VectorUtils.transform(alpha, (x) => Math.abs(x) ** norm);
+  const sum = VectorUtils.collapse(summable, (a, b) => a + b, 0) as number;
+  return sum ** (1 / norm);
+}
+
+export function magnitudeVector(alpha: RVec): number {
+  return pNorm(alpha, 2);
+}
+
+export function angleBetween(alpha: RVec, beta: RVec): number {
+  return Math.acos(dotProduct(alpha, beta) / (magnitudeVector(alpha) * magnitudeVector(beta)));
+}