@johnhenry/math 0.0.0

package/src/Type.ts

@@ -0,0 +1,48 @@
+import { ComplexNumber } from "./ComplexNumber.ts";
+import { Vector } from "./Vector.ts";
+import { VectorUtils } from "./VectorUtils.ts";
+
+/**
+ * Type — runtime classification used for the polymorphic `*Generic` dispatchers
+ * in {@link RealMath}/{@link ComplexMath}. Ported from Mallory's ActionScript
+ * `Type`. The string tags are preserved.
+ *
+ * Note: the AS3 version had an explicit `obj is Expression -> FUNCTION` branch,
+ * but its fall-through default was already `FUNCTION`, so the check is redundant
+ * and omitted here (an Expression still classifies as `FUNCTION`).
+ */
+export const TypeTag = {
+  NUMBER: "number",
+  VECTOR: "vector",
+  MATRIX: "matrix",
+  FUNCTION: "function",
+  ERROR: "error",
+  BOOLEAN: "boolean",
+  PERMUTATION: "permutation",
+} as const;
+
+export type TypeTag = (typeof TypeTag)[keyof typeof TypeTag];
+
+export class Type {
+  static readonly NUMBER = TypeTag.NUMBER;
+  static readonly VECTOR = TypeTag.VECTOR;
+  static readonly MATRIX = TypeTag.MATRIX;
+  static readonly FUNCTION = TypeTag.FUNCTION;
+  static readonly ERROR = TypeTag.ERROR;
+  static readonly BOOLEAN = TypeTag.BOOLEAN;
+  static readonly PERMUTATION = TypeTag.PERMUTATION;
+
+  /** Classify a runtime value into one of the {@link TypeTag} strings. */
+  static getType(obj: unknown): TypeTag {
+    if (typeof obj === "number" || obj instanceof ComplexNumber || ComplexNumber.isComplex(obj)) {
+      return TypeTag.NUMBER;
+    }
+    if (obj instanceof Vector) {
+      return VectorUtils.isMatrix(obj) ? TypeTag.MATRIX : TypeTag.VECTOR;
+    }
+    if (obj instanceof Error) return TypeTag.ERROR;
+    if (typeof obj === "boolean") return TypeTag.BOOLEAN;
+    if (typeof obj === "string") return TypeTag.ERROR;
+    return TypeTag.FUNCTION;
+  }
+}

package/src/Utilities.ts

@@ -0,0 +1,49 @@
+/**
+ * Utilities — small general-purpose helpers.
+ *
+ * In the ActionScript original the entire body of this class was commented out.
+ * The helpers were clearly intended to ship (they are referenced conceptually
+ * throughout the library and `RoundTo` is re-implemented ad hoc elsewhere), so
+ * they are revived here as ordinary functions. Array helpers that merely duplicate
+ * built-ins (`CloneArray`, `MapArray`, `isMember`) are kept for API parity.
+ */
+export class Utilities {
+  static readonly DefaultPrecision = 8;
+
+  /**
+   * Round a real number to `precision` decimal places. Extremely large
+   * magnitudes collapse to ±Infinity and denormally-small ones to 0, matching
+   * the AS3 `RoundTo` behaviour.
+   */
+  static roundTo(value: number, precision: number = Utilities.DefaultPrecision): number {
+    if (value >= Number.MAX_VALUE) return Number.POSITIVE_INFINITY;
+    if (value <= -Number.MAX_VALUE) return Number.NEGATIVE_INFINITY;
+    if (Math.abs(value) <= Number.MIN_VALUE) return 0;
+    const factor = 10 ** precision;
+    return Math.round(value * factor) / factor;
+  }
+
+  static radiansToDegrees(r: number): number {
+    return (180 / Math.PI) * r;
+  }
+
+  static degreesToRadians(d: number): number {
+    return (Math.PI / 180) * d;
+  }
+
+  /** Shallow copy of an array. */
+  static cloneArray<T>(array: readonly T[]): T[] {
+    return [...array];
+  }
+
+  /** Map `mapper` over an array (kept for parity with the AS3 API). */
+  static mapArray<T, U>(elements: readonly T[], mapper: (value: T) => U): U[] {
+    return elements.map(mapper);
+  }
+
+  /** True when `value` is (loosely) equal to a member of `group`. */
+  static isMember(value: unknown, group: readonly unknown[]): boolean {
+    // biome-ignore lint/suspicious/noDoubleEquals: faithful to AS3 loose `==` coercion semantics
+    return group.some((i) => value == i);
+  }
+}

package/src/Vec4.ts

@@ -0,0 +1,98 @@
+/**
+ * Vec4 — a Euclidean 4D vector `(x, y, z, w)`.
+ *
+ * This is a genuine fourth *spatial* dimension (not time): all four
+ * components are treated symmetrically, exactly like {@link Quaternion}'s
+ * imaginary triple but one dimension further. Built to support 4D geometric
+ * algebra ({@link Bivector4}, {@link Rotor4}) for applications like simulating
+ * or rendering four-dimensional space.
+ */
+export class Vec4 {
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+  readonly w: number;
+
+  static readonly Zero = new Vec4(0, 0, 0, 0);
+  static readonly Ex = new Vec4(1, 0, 0, 0);
+  static readonly Ey = new Vec4(0, 1, 0, 0);
+  static readonly Ez = new Vec4(0, 0, 1, 0);
+  static readonly Ew = new Vec4(0, 0, 0, 1);
+
+  constructor(x = 0, y = 0, z = 0, w = 0) {
+    this.x = x;
+    this.y = y;
+    this.z = z;
+    this.w = w;
+  }
+
+  static of(x: number, y: number, z: number, w: number): Vec4 {
+    return new Vec4(x, y, z, w);
+  }
+
+  add(v: Vec4): Vec4 {
+    return new Vec4(this.x + v.x, this.y + v.y, this.z + v.z, this.w + v.w);
+  }
+
+  subtract(v: Vec4): Vec4 {
+    return new Vec4(this.x - v.x, this.y - v.y, this.z - v.z, this.w - v.w);
+  }
+
+  scale(s: number): Vec4 {
+    return new Vec4(this.x * s, this.y * s, this.z * s, this.w * s);
+  }
+
+  negate(): Vec4 {
+    return this.scale(-1);
+  }
+
+  /** Euclidean inner product. */
+  dot(v: Vec4): number {
+    return this.x * v.x + this.y * v.y + this.z * v.z + this.w * v.w;
+  }
+
+  get magnitude(): number {
+    return Math.hypot(this.x, this.y, this.z, this.w);
+  }
+
+  get magnitudeSquared(): number {
+    return this.dot(this);
+  }
+
+  normalize(): Vec4 {
+    const m = this.magnitude;
+    if (m === 0) throw new Error("Cannot normalize the zero vector.");
+    return this.scale(1 / m);
+  }
+
+  lerp(v: Vec4, t: number): Vec4 {
+    return this.add(v.subtract(this).scale(t));
+  }
+
+  equals(v: Vec4, epsilon = 0): boolean {
+    if (epsilon === 0) return this.x === v.x && this.y === v.y && this.z === v.z && this.w === v.w;
+    return (
+      Math.abs(this.x - v.x) <= epsilon &&
+      Math.abs(this.y - v.y) <= epsilon &&
+      Math.abs(this.z - v.z) <= epsilon &&
+      Math.abs(this.w - v.w) <= epsilon
+    );
+  }
+
+  /** The 3D subvector `(x, y, z)` obtained by dropping the w-axis — useful when reading out the current 3D "slice" of a 4D scene. */
+  dropW(): [number, number, number] {
+    return [this.x, this.y, this.z];
+  }
+
+  toArray(): [number, number, number, number] {
+    return [this.x, this.y, this.z, this.w];
+  }
+
+  static fromArray(a: readonly [number, number, number, number]): Vec4 {
+    return new Vec4(a[0], a[1], a[2], a[3]);
+  }
+
+  toString(): string {
+    return `(${this.x}, ${this.y}, ${this.z}, ${this.w})`;
+  }
+}

package/src/Vector.ts

@@ -0,0 +1,189 @@
+/**
+ * Vector — an `Array` subclass that doubles as a mathematical vector / matrix row.
+ *
+ * Ported from Mallory's ActionScript `Vector` (`dynamic class Vector extends Array`).
+ * In the original the class was used both as a plain sequence container and, when
+ * nested (a Vector of Vectors), as a matrix. That dual role is preserved here.
+ *
+ * Modernisations & bug fixes relative to the AS3 original:
+ *  - `setElement` no longer infinitely recurses when the target slot holds a
+ *    falsy value (the AS3 version looped forever whenever `this[index]` was
+ *    `0`/`null`/`undefined`). It now pads with the placeholder and assigns.
+ *  - The `x`/`y`/`z`/`t` accessors return a genuinely stored `0` instead of
+ *    silently coercing every falsy slot to `0`.
+ *  - `toXML` returns a `string` (AS3 `XML` no longer exists in JS land).
+ *  - The class is generic and iterable (inherited from `Array`).
+ */
+export class Vector<T = unknown> extends Array<T> {
+  /** A shared, empty vector — mirrors AS3 `Vector.Empty`. */
+  static readonly Empty: Vector<never> = new Vector<never>();
+
+  /**
+   * Build a Vector from the given elements.
+   *
+   * NOTE on the single-number case: because `Array` (and therefore this
+   * subclass) treats `new Vector(n)` as "create a sparse vector of length n",
+   * that behaviour is retained — it is also what `Array.prototype` methods rely
+   * on via `Symbol.species` when they allocate result vectors. Use
+   * {@link Vector.of} or {@link Vector.from} to wrap a literal single number.
+   */
+  constructor(length: number);
+  constructor(...rest: T[]);
+  constructor(...rest: T[]) {
+    // Reproduce Array's constructor contract: a lone number means "length".
+    if (rest.length === 1 && typeof rest[0] === "number") {
+      super(rest[0] as number);
+    } else {
+      super(...rest);
+    }
+  }
+
+  /** Ensure `map`/`filter`/`slice`/etc. produce plain `Vector`s, not typed views. */
+  static override get [Symbol.species](): ArrayConstructor {
+    return Array as unknown as ArrayConstructor;
+  }
+
+  /** Convert any array-like into a Vector (shallow). Mirrors AS3 `ArrayToVector`. */
+  static fromArray<U>(array: Iterable<U>): Vector<U> {
+    const v = new Vector<U>();
+    for (const e of array) v.push(e);
+    return v;
+  }
+
+  /**
+   * Parse the `<vector>` form produced by {@link toXML} (best-effort inverse:
+   * numeric coordinates become numbers, everything else stays a string).
+   */
+  static fromXML(xml: string): Vector<number | string> {
+    const out = new Vector<number | string>();
+    for (const match of xml.matchAll(/<coordinate>(.*?)<\/coordinate>/g)) {
+      const raw = match[1] as string;
+      const n = Number(raw);
+      out.push(raw !== "" && !Number.isNaN(n) ? n : raw);
+    }
+    return out;
+  }
+
+  /**
+   * Parse the bracketed form produced by {@link toString} (best-effort inverse:
+   * numeric elements become numbers, everything else stays a trimmed string).
+   */
+  static fromString(str: string, seperator = ",", leftBracket = "[", rightBracket = "]"): Vector<number | string> {
+    let s = str.trim();
+    if (s.startsWith(leftBracket)) s = s.slice(leftBracket.length);
+    if (s.endsWith(rightBracket)) s = s.slice(0, s.length - rightBracket.length);
+    const out = new Vector<number | string>();
+    if (s === "") return out;
+    for (const part of s.split(seperator)) {
+      const t = part.trim();
+      const n = Number(t);
+      out.push(t !== "" && !Number.isNaN(n) ? n : t);
+    }
+    return out;
+  }
+
+  /** String representation, e.g. `[1,2,3]`. */
+  override toString(seperator = ",", leftBracket = "[", rightBracket = "]"): string {
+    let out = leftBracket;
+    for (let i = 0; i < this.length; i++) {
+      out += this[i] != null ? String(this[i]) : String(null);
+      if (i !== this.length - 1) out += seperator;
+    }
+    return out + rightBracket;
+  }
+
+  /** XML-ish serialisation, kept for compatibility with the AS3 API. */
+  toXML(): string {
+    const parts: string[] = [];
+    for (let i = 0; i < this.length; i++) {
+      parts.push(`<coordinate>${this[i]}</coordinate>`);
+    }
+    return `<vector>${parts.join("")}</vector>`;
+  }
+
+  /** Return the element at `index` (defaults to the first). */
+  getElement(index = 0): T | undefined {
+    return this[index];
+  }
+
+  /** Remove and return the element at `index`. */
+  removeElement(index = 0): T | undefined {
+    return this.splice(index, 1)[0];
+  }
+
+  /**
+   * Set the element at `index`, padding with `placeHolder` if the vector is too
+   * short. Returns the previously stored value (or `undefined`).
+   *
+   * Bug fix: the AS3 version recursed infinitely whenever the slot was falsy.
+   */
+  setElement(newElement: T, index = 0, placeHolder: T | null = null): T | undefined {
+    while (this.length < index) this.push(placeHolder as T);
+    const previous = this[index];
+    this[index] = newElement;
+    return previous;
+  }
+
+  /**
+   * Insert `newElement` at `index`. With no index (or a negative one) it is
+   * appended. If `index` is beyond the current end, the gap is filled with
+   * `placeHolder`. Returns the resulting length.
+   */
+  addElement(newElement: T | null = null, index = -1, placeHolder: T | null = null): number {
+    if (index < 0) return this.push(newElement as T);
+    while (index > this.length) this.push(placeHolder as T);
+    this.splice(index, 0, newElement as T);
+    return this.length;
+  }
+
+  // The x/y/z/t accessors let a Vector act as a 1-to-4 dimensional point.
+  private coord(i: number): T | 0 {
+    return i < this.length && this[i] != null ? (this[i] as T) : 0;
+  }
+
+  get x(): T | 0 {
+    return this.coord(0);
+  }
+  get y(): T | 0 {
+    return this.coord(1);
+  }
+  get z(): T | 0 {
+    return this.coord(2);
+  }
+  get t(): T | 0 {
+    return this.coord(3);
+  }
+
+  set x(value: T) {
+    this.setElement(value, 0);
+  }
+  set y(value: T) {
+    this.setElement(value, 1);
+  }
+  set z(value: T) {
+    this.setElement(value, 2);
+  }
+  set t(value: T) {
+    this.setElement(value, 3);
+  }
+
+  /**
+   * Clone the vector. When `deep` is true (default) nested Vectors are cloned
+   * recursively, so a matrix is duplicated rather than sharing its rows.
+   */
+  clone(deep = true): Vector<T> {
+    const out = new Vector<T>();
+    for (let i = 0; i < this.length; i++) {
+      const el = this[i];
+      out[i] = deep && el instanceof Vector ? (el.clone() as unknown as T) : (el as T);
+    }
+    return out;
+  }
+
+  /** Return a new vector with the elements in reverse order. */
+  reversed(): Vector<T> {
+    const out = new Vector<T>();
+    for (let i = 0; i < this.length; i++) out[i] = this[this.length - 1 - i] as T;
+    return out;
+  }
+}

package/src/VectorCalculus.ts

@@ -0,0 +1,87 @@
+import { DualNumber } from "./DualNumber.ts";
+import { Symbolic } from "./Symbolic.ts";
+
+/**
+ * VectorCalculus — multivariable differential calculus: gradients, Jacobians,
+ * divergence, curl, and Hessians. Built entirely on existing exact-derivative
+ * machinery rather than a new autodiff engine: {@link gradient}/{@link jacobian}
+ * reuse {@link DualNumber} forward-mode autodiff (exact, first-order);
+ * {@link symbolicGradient} reuses {@link Symbolic} differentiation/evaluation
+ * for string-expression functions.
+ *
+ * {@link hessian} is the one approximate method — it takes central differences
+ * of the *exact* gradient (not of `f` itself), which is more accurate than a
+ * naive finite-difference Hessian without the scope of implementing
+ * second-order (hyperdual) numbers.
+ */
+export class VectorCalculus {
+  /** The gradient of a scalar field `f` at `point` (exact, via {@link DualNumber}). */
+  static gradient(f: (xs: DualNumber[]) => DualNumber, point: number[]): number[] {
+    return DualNumber.gradient(f, point);
+  }
+
+  /** The rate of change of `f` at `point` along `direction` (need not be a unit vector). */
+  static directionalDerivative(f: (xs: DualNumber[]) => DualNumber, point: number[], direction: number[]): number {
+    const norm = Math.sqrt(direction.reduce((s, d) => s + d * d, 0));
+    if (norm === 0) throw new Error("VectorCalculus.directionalDerivative: direction must be non-zero");
+    const grad = VectorCalculus.gradient(f, point);
+    return grad.reduce((s, g, i) => s + (g * (direction[i] as number)) / norm, 0);
+  }
+
+  /**
+   * The Jacobian of a vector field `f: R^n -> R^m` at `point`, as an `m × n`
+   * matrix (`J[i][j] = ∂f_i/∂x_j`). Computed via `n` forward autodiff passes,
+   * one dual-seeded input dimension at a time.
+   */
+  static jacobian(f: (xs: DualNumber[]) => DualNumber[], point: number[]): number[][] {
+    const n = point.length;
+    const columns: number[][] = [];
+    for (let i = 0; i < n; i++) {
+      const seeded = point.map((x, j) => new DualNumber(x, i === j ? 1 : 0));
+      columns.push(f(seeded).map((o) => o.deriv));
+    }
+    const m = columns[0]?.length ?? 0;
+    return Array.from({ length: m }, (_, row) => columns.map((column) => column[row] as number));
+  }
+
+  /** The divergence of a vector field `f: R^n -> R^n` at `point` (the trace of its Jacobian). */
+  static divergence(f: (xs: DualNumber[]) => DualNumber[], point: number[]): number {
+    const J = VectorCalculus.jacobian(f, point);
+    return point.reduce((sum, _, i) => sum + (J[i]?.[i] as number), 0);
+  }
+
+  /** The curl of a 3D vector field `f: R^3 -> R^3` at `point`. */
+  static curl3D(f: (xs: DualNumber[]) => DualNumber[], point: [number, number, number]): [number, number, number] {
+    const J = VectorCalculus.jacobian(f, point);
+    return [
+      (J[2]?.[1] as number) - (J[1]?.[2] as number),
+      (J[0]?.[2] as number) - (J[2]?.[0] as number),
+      (J[1]?.[0] as number) - (J[0]?.[1] as number),
+    ];
+  }
+
+  /**
+   * The Hessian of a scalar field `f` at `point`: central differences (step
+   * `h`) of the exact gradient, i.e. `H[i][j] ≈ ∂(∂f/∂x_j)/∂x_i`.
+   */
+  static hessian(f: (xs: DualNumber[]) => DualNumber, point: number[], h = 1e-4): number[][] {
+    return point.map((_, i) => {
+      const plus = point.slice();
+      const minus = point.slice();
+      plus[i] = (plus[i] as number) + h;
+      minus[i] = (minus[i] as number) - h;
+      const gradPlus = VectorCalculus.gradient(f, plus);
+      const gradMinus = VectorCalculus.gradient(f, minus);
+      return gradPlus.map((g, j) => (g - (gradMinus[j] as number)) / (2 * h));
+    });
+  }
+
+  /**
+   * The exact gradient of a string expression at `point`, via
+   * {@link Symbolic.differentiate}/{@link Symbolic.evaluate} (one partial
+   * derivative per named variable — every other variable is held constant).
+   */
+  static symbolicGradient(expr: string, variables: string[], point: Record<string, number>): number[] {
+    return variables.map((variable) => Symbolic.evaluate(Symbolic.differentiate(expr, variable), point));
+  }
+}