@johnhenry/math 0.0.0

package/src/GraphUtils.ts

@@ -0,0 +1,159 @@
+import type { Polygon } from "./Polygon.ts";
+import type { Vector } from "./Vector.ts";
+import { VectorUtils } from "./VectorUtils.ts";
+
+/**
+ * GraphUtils — helpers for turning functions and points into 2D drawing data.
+ *
+ * Ported from Mallory's ActionScript `GraphUtils`, which mutated Flash
+ * `DisplayObject`s and drew into a `Graphics` context. Since neither exists
+ * outside Flash, the drawing operations are re-targeted to emit renderer-
+ * agnostic data — placement descriptors and vector paths — which the original
+ * comments themselves noted would be a cleaner separation. `if(point.x)`-style
+ * truthiness checks (which dropped legitimate zero coordinates) are fixed.
+ */
+
+export interface Placement2D {
+  x: number;
+  y: number;
+  scaleX: number;
+  scaleY: number;
+}
+
+export interface BarPlacement2D {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  scaleY: number;
+}
+
+export interface StrokeStyle {
+  thickness: number;
+  color: number;
+  alpha: number;
+  pixelHinting: boolean;
+  scaleMode: string;
+  caps: string | null;
+  joints: string | null;
+  miterLimit: number;
+}
+
+export interface FillStyle {
+  color: number;
+  alpha: number;
+}
+
+export interface PathCommand {
+  op: "moveTo" | "lineTo";
+  x: number;
+  y: number;
+}
+
+export interface Path2D {
+  stroke: StrokeStyle;
+  fill?: FillStyle;
+  commands: PathCommand[];
+}
+
+const point = (p: Vector<number>) => ({ x: p.x as number, y: p.y as number, z: p.z as number, t: p.t as number });
+
+export class GraphUtils {
+  /** Sample `unaryOperation` across `[xMin, xMax]` in `xStep` increments. */
+  static singleRangeVector<T>(unaryOperation: (x: number) => T, xMin = -10, xMax = 10, xStep = 1): Vector<T> {
+    const xValues = VectorUtils.arithmeticSequence(xMin, xMax, xStep);
+    return VectorUtils.transform(xValues, unaryOperation);
+  }
+
+  /**
+   * Placement descriptor for a point. With `altProperties`, maps each component
+   * to a named property; otherwise x/y position and (from z) a uniform scale.
+   */
+  static placement(p: Vector<number>, altProperties: string[] | null = null): Placement2D | Record<string, number> {
+    if (altProperties) {
+      const out: Record<string, number> = {};
+      const max = Math.max(p.length, altProperties.length);
+      for (let i = 0; i < max; i++) out[altProperties[i] as string] = p[i] as number;
+      return out;
+    }
+    const { x, y, z } = point(p);
+    const scale = z !== 0 ? Math.abs(z) : 1;
+    return { x, y, scaleX: scale, scaleY: scale };
+  }
+
+  /** Placement descriptor for a bar in a bar graph. */
+  static barPlacement(p: Vector<number>, barWidth = 40): BarPlacement2D {
+    const { x, y } = point(p);
+    return { x, y: 0, width: barWidth, height: y, scaleY: y < 0 ? -1 : 1 };
+  }
+
+  static placements(
+    points: Vector<Vector<number>>,
+    altProperties: string[] | null = null,
+  ): Array<Placement2D | Record<string, number>> {
+    return [...points].map((p) => GraphUtils.placement(p, altProperties));
+  }
+
+  static barPlacements(points: Vector<Vector<number>>, barWidth = 40): BarPlacement2D[] {
+    return [...points].map((p) => GraphUtils.barPlacement(p, barWidth));
+  }
+
+  /** A poly-line path through the given points. */
+  static vectorToCurve(
+    points: Vector<Vector<number>>,
+    thickness = 0,
+    color = 0,
+    alpha = 1,
+    pixelHinting = false,
+    scaleMode = "normal",
+    caps: string | null = null,
+    joints: string | null = null,
+    miterLimit = 3,
+  ): Path2D {
+    const stroke: StrokeStyle = { thickness, color, alpha, pixelHinting, scaleMode, caps, joints, miterLimit };
+    const commands: PathCommand[] = [];
+    if (points.length > 0) {
+      const first = point(points[0] as Vector<number>);
+      commands.push({ op: "moveTo", x: first.x, y: first.y });
+      for (let i = 1; i < points.length; i++) {
+        const pt = point(points[i] as Vector<number>);
+        commands.push({ op: "lineTo", x: pt.x, y: pt.y });
+      }
+    }
+    return { stroke, commands };
+  }
+
+  /** A filled, closed path tracing a polygon's edges. */
+  static polygonToCurve(
+    polygon: Polygon,
+    strokeThickness = 0,
+    strokeColor = 0,
+    strokeAlpha = 1,
+    fillColor = 0xffffff,
+    fillAlpha = 1,
+    pixelHinting = false,
+    scaleMode = "normal",
+    caps: string | null = null,
+    joints: string | null = null,
+    miterLimit = 3,
+  ): Path2D {
+    const stroke: StrokeStyle = {
+      thickness: strokeThickness,
+      color: strokeColor,
+      alpha: strokeAlpha,
+      pixelHinting,
+      scaleMode,
+      caps,
+      joints,
+      miterLimit,
+    };
+    const commands: PathCommand[] = [];
+    const start = point(polygon.vertex(0));
+    commands.push({ op: "moveTo", x: start.x, y: start.y });
+    for (let i = 1; i <= polygon.edgeCount; i++) {
+      const pt = point(polygon.vertex(i));
+      commands.push({ op: "lineTo", x: pt.x, y: pt.y });
+    }
+    return { stroke, fill: { color: fillColor, alpha: fillAlpha }, commands };
+  }
+}

package/src/GroupTheory.ts

@@ -0,0 +1,214 @@
+import { Permutation } from "./Permutation.ts";
+
+/**
+ * GroupTheory — algorithms over a finite group given as a set of elements plus a
+ * binary operation and an equality test. Composes with {@link Structure} (pass
+ * `structure.multiply`/`structure.add`) and {@link Permutation} (pass
+ * `Permutation.compose`). Covers Cayley tables, axiom checking, element orders,
+ * generated subgroups, cosets, Lagrange's index, and group actions/orbits.
+ */
+
+type BinOp<T> = (a: T, b: T) => T;
+type Eq<T> = (a: T, b: T) => boolean;
+
+const contains = <T>(arr: readonly T[], x: T, eq: Eq<T>): boolean => arr.some((y) => eq(x, y));
+
+export class GroupTheory {
+  /** The Cayley (multiplication) table: `table[i][j] = op(elements[i], elements[j])`. */
+  static cayleyTable<T>(elements: readonly T[], op: BinOp<T>): T[][] {
+    return elements.map((a) => elements.map((b) => op(a, b)));
+  }
+
+  /** True when the set is closed under `op`. */
+  static isClosed<T>(elements: readonly T[], op: BinOp<T>, eq: Eq<T>): boolean {
+    for (const a of elements) for (const b of elements) if (!contains(elements, op(a, b), eq)) return false;
+    return true;
+  }
+
+  /** The identity element, or `null` if none exists. */
+  static findIdentity<T>(elements: readonly T[], op: BinOp<T>, eq: Eq<T>): T | null {
+    for (const e of elements) {
+      if (elements.every((a) => eq(op(e, a), a) && eq(op(a, e), a))) return e;
+    }
+    return null;
+  }
+
+  /** True when `op` is associative over the set (O(n³) check). */
+  static isAssociative<T>(elements: readonly T[], op: BinOp<T>, eq: Eq<T>): boolean {
+    for (const a of elements)
+      for (const b of elements) for (const c of elements) if (!eq(op(op(a, b), c), op(a, op(b, c)))) return false;
+    return true;
+  }
+
+  /** True when every element has an inverse relative to `identity`. */
+  static hasInverses<T>(elements: readonly T[], op: BinOp<T>, eq: Eq<T>, identity: T): boolean {
+    return elements.every((a) => elements.some((b) => eq(op(a, b), identity) && eq(op(b, a), identity)));
+  }
+
+  /** Verify all four group axioms (closure, associativity, identity, inverses). */
+  static isGroup<T>(elements: readonly T[], op: BinOp<T>, eq: Eq<T>): boolean {
+    if (!GroupTheory.isClosed(elements, op, eq)) return false;
+    const id = GroupTheory.findIdentity(elements, op, eq);
+    if (id === null) return false;
+    return GroupTheory.isAssociative(elements, op, eq) && GroupTheory.hasInverses(elements, op, eq, id);
+  }
+
+  /** True when the group is also abelian (commutative). */
+  static isAbelian<T>(elements: readonly T[], op: BinOp<T>, eq: Eq<T>): boolean {
+    for (const a of elements) for (const b of elements) if (!eq(op(a, b), op(b, a))) return false;
+    return true;
+  }
+
+  /** The order of an element: the least `k ≥ 1` with `elementᵏ = identity`. */
+  static elementOrder<T>(element: T, op: BinOp<T>, eq: Eq<T>, identity: T, max = 100000): number {
+    let acc = element;
+    for (let k = 1; k <= max; k++) {
+      if (eq(acc, identity)) return k;
+      acc = op(acc, element);
+    }
+    throw new Error("Element order exceeded the search bound (is the group finite?).");
+  }
+
+  /**
+   * The subgroup generated by `generators`: the closure of the generators (and
+   * the identity) under `op`. `identity` may be supplied when it is not itself a
+   * generator; otherwise closure alone recovers it for a finite group — except
+   * when `generators` is empty, in which case there is nothing to multiply out
+   * and `identity` must be supplied explicitly to get the trivial subgroup
+   * `[identity]` back (omitting it returns `[]`, since no identity can be
+   * discovered from zero elements and `op` alone).
+   */
+  static closure<T>(generators: readonly T[], op: BinOp<T>, eq: Eq<T>, identity?: T, cap = 100000): T[] {
+    const elements: T[] = [];
+    if (identity !== undefined) elements.push(identity);
+    for (const g of generators) if (!contains(elements, g, eq)) elements.push(g);
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (let i = 0; i < elements.length; i++) {
+        for (const g of generators) {
+          const p = op(elements[i] as T, g);
+          if (!contains(elements, p, eq)) {
+            elements.push(p);
+            changed = true;
+            if (elements.length > cap) throw new Error("Closure exceeded the size cap.");
+          }
+        }
+      }
+    }
+    return elements;
+  }
+
+  /** True when `sub` is a subgroup of `group` under `op`. */
+  static isSubgroup<T>(sub: readonly T[], group: readonly T[], op: BinOp<T>, eq: Eq<T>): boolean {
+    if (!sub.every((s) => contains(group, s, eq))) return false;
+    return GroupTheory.isGroup(sub, op, eq);
+  }
+
+  /** The distinct left cosets `gH` of subgroup `H` in `group`. */
+  static leftCosets<T>(subgroup: readonly T[], group: readonly T[], op: BinOp<T>, eq: Eq<T>): T[][] {
+    const cosets: T[][] = [];
+    const seen: T[] = [];
+    for (const g of group) {
+      if (contains(seen, g, eq)) continue;
+      const coset = subgroup.map((h) => op(g, h));
+      cosets.push(coset);
+      for (const c of coset) if (!contains(seen, c, eq)) seen.push(c);
+    }
+    return cosets;
+  }
+
+  /** Lagrange index `[G : H] = |G| / |H|`. */
+  static index<T>(group: readonly T[], subgroup: readonly T[]): number {
+    return group.length / subgroup.length;
+  }
+
+  /** The orbit of `x` under a group action, given the generators and the action map. */
+  static orbit<T, X>(x: X, generators: readonly T[], action: (g: T, x: X) => X, eqX: Eq<X>, cap = 100000): X[] {
+    const orbit: X[] = [x];
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (let i = 0; i < orbit.length; i++) {
+        for (const g of generators) {
+          const y = action(g, orbit[i] as X);
+          if (!contains(orbit, y, eqX)) {
+            orbit.push(y);
+            changed = true;
+            if (orbit.length > cap) throw new Error("Orbit exceeded the size cap.");
+          }
+        }
+      }
+    }
+    return orbit;
+  }
+
+  /** The cyclic group Zₙ as `{0, …, n-1}` under addition mod n. */
+  static cyclicGroup(n: number): { elements: number[]; op: BinOp<number>; identity: number } {
+    return {
+      elements: Array.from({ length: n }, (_, i) => i),
+      op: (a, b) => (a + b) % n,
+      identity: 0,
+    };
+  }
+
+  /**
+   * The dihedral group Dₙ (order 2n): symmetries of a regular n-gon, as
+   * permutations of its n vertices `{0, …, n-1}`. n rotations `ρₖ: i ↦ (i+k)
+   * mod n` plus n reflections `σₖ: i ↦ (k-i) mod n` (reflecting through the
+   * axis fixing vertex k/2 when k is even, or the edge midpoint between
+   * ⌊k/2⌋ and ⌈k/2⌉ when k is odd). For n=3 this is exactly (element-for-
+   * element, not just isomorphic) {@link symmetricGroup}(3) — the two
+   * constructions coincide since S₃ has only 6 permutations total, matching
+   * D₃'s own order 2·3=6.
+   */
+  static dihedralGroup(n: number): Array<Permutation<number>> {
+    const domain = Array.from({ length: n }, (_, i) => i);
+    const mod = (x: number) => ((x % n) + n) % n;
+    const rotations = Array.from(
+      { length: n },
+      (_, k) =>
+        new Permutation(
+          domain,
+          domain.map((i) => mod(i + k)),
+        ),
+    );
+    const reflections = Array.from(
+      { length: n },
+      (_, k) =>
+        new Permutation(
+          domain,
+          domain.map((i) => mod(k - i)),
+        ),
+    );
+    return [...rotations, ...reflections];
+  }
+
+  /**
+   * The stabilizer of `x` under a group action: the elements of `group`
+   * fixing `x`. Complements {@link orbit} — the orbit-stabilizer theorem
+   * (`|orbit(x)| · |stabilizer(x)| = |G|`) holds for any finite group action.
+   */
+  static stabilizer<T, X>(x: X, group: readonly T[], action: (g: T, x: X) => X, eqX: Eq<X>): T[] {
+    return group.filter((g) => eqX(action(g, x), x));
+  }
+
+  /** The symmetric group Sₙ: every permutation of `{0, …, n-1}`. */
+  static symmetricGroup(n: number): Array<Permutation<number>> {
+    const domain = Array.from({ length: n }, (_, i) => i);
+    const results: Array<Permutation<number>> = [];
+    const permute = (arr: number[], k: number) => {
+      if (k === arr.length) {
+        results.push(new Permutation(domain, [...arr]));
+        return;
+      }
+      for (let i = k; i < arr.length; i++) {
+        [arr[k], arr[i]] = [arr[i], arr[k]];
+        permute(arr, k + 1);
+        [arr[k], arr[i]] = [arr[i], arr[k]];
+      }
+    };
+    permute([...domain], 0);
+    return results;
+  }
+}

package/src/IntUtils.ts

@@ -0,0 +1,200 @@
+/**
+ * IntUtils — convert integers (and numeric strings) into English words.
+ *
+ * Ported from Mallory's ActionScript `IntUtils`. The peculiar comma-joined
+ * grouping of the original output is preserved so behaviour is unchanged, but
+ * two spelling bugs are fixed: "fourty" → "forty" and "ninty" → "ninety".
+ *
+ * Passing a string lets you exceed JS's safe-integer range, exactly as the AS3
+ * version did to sidestep ActionScript's number limits.
+ */
+export class IntUtils {
+  private static readonly ONES = [
+    "zero",
+    "one",
+    "two",
+    "three",
+    "four",
+    "five",
+    "six",
+    "seven",
+    "eight",
+    "nine",
+    "ten",
+    "eleven",
+    "twelve",
+    "thirteen",
+    "fourteen",
+    "fifteen",
+    "sixteen",
+    "seventeen",
+    "eighteen",
+    "nineteen",
+  ];
+
+  // index 2..9 => tens words (forty/ninety fixed from AS3 "fourty"/"ninty").
+  private static readonly TENS: Record<number, string> = {
+    2: "twenty",
+    3: "thirty",
+    4: "forty",
+    5: "fifty",
+    6: "sixty",
+    7: "seventy",
+    8: "eighty",
+    9: "ninety",
+  };
+
+  /** Accepted group suffixes (units, thousands, millions, …). */
+  static readonly ActualNames = [
+    "",
+    "-thousand",
+    "-million",
+    "-billion",
+    "-trillion",
+    "-quadrillion",
+    "-quintillion",
+    "-sextillion",
+    "-septillion",
+    "-octillion",
+    "-nonillion",
+    "-decillion",
+  ];
+
+  /** Whimsical fall-back names once the real ones run out. */
+  static readonly FakeNames = ["ZILLION!!!", "-BAJILLION!!!", "-AGAZILLION!!!"];
+
+  private static toInt(s: string): number {
+    const n = Number.parseInt(s, 10);
+    return Number.isNaN(n) ? 0 : n;
+  }
+
+  /** Words for the last three digits (0–999) of a number. */
+  static toWordsTriple(num = 0): string {
+    if (num < 20) return IntUtils.ONES[num] ?? "";
+
+    const numString = num.toString();
+    const lowerPlace = IntUtils.toInt(numString.charAt(numString.length - 1));
+    const tensPlace = IntUtils.toInt(numString.charAt(numString.length - 2));
+
+    let intString = "";
+    if (lowerPlace !== 0) {
+      const tens = IntUtils.TENS[tensPlace];
+      if (tens) intString = `${tens}-${IntUtils.toWordsTriple(lowerPlace)}`;
+    } else {
+      intString = IntUtils.TENS[tensPlace] ?? "";
+    }
+
+    if (num < 100) return intString;
+
+    const lastTwo = IntUtils.toInt(`${tensPlace}${lowerPlace}`);
+    const hundredsPlace = IntUtils.toInt(numString.charAt(numString.length - 3));
+
+    if (lastTwo !== 0) {
+      return `${IntUtils.toWordsTriple(hundredsPlace)}-hundred-${IntUtils.toWordsTriple(lastTwo)}`;
+    }
+    return `${IntUtils.toWordsTriple(hundredsPlace)}-hundred`;
+  }
+
+  /** Suffix for the group at `index` (0 = units, 1 = thousands, …). */
+  static numberGroupNames(index = 0): string {
+    return index < IntUtils.ActualNames.length
+      ? (IntUtils.ActualNames[index] as string)
+      : (IntUtils.FakeNames[0] as string);
+  }
+
+  /** Convert an integer (or its string form) to English words. */
+  static toWords(num: number | string): string {
+    let negative = false;
+    let value = num;
+
+    if (typeof value === "string") {
+      if (value.charAt(0) === "-") {
+        negative = true;
+        value = value.substring(1);
+      }
+    } else if (value < 0) {
+      negative = true;
+      value = value * -1;
+    }
+
+    let numString = value.toString().split(",").join("");
+    const groups: number[] = [];
+    while (numString.length > 0) {
+      const take = numString.length > 2 ? 3 : numString.length > 1 ? 2 : 1;
+      groups.unshift(IntUtils.toInt(numString.substring(numString.length - take)));
+      numString = numString.substr(0, numString.length - take);
+    }
+
+    if (groups.length === 1) {
+      const single = IntUtils.toWordsTriple(groups[0]);
+      return negative ? `negative ${single}` : single;
+    }
+
+    const parts = groups
+      .map((g, i) => (g === 0 ? null : IntUtils.toWordsTriple(g) + IntUtils.numberGroupNames(groups.length - i - 1)))
+      .filter((p): p is string => p !== null);
+
+    const joined = parts.join(",");
+    return negative ? `negative ${joined}` : joined;
+  }
+
+  // Irregular ordinal suffixes for the last word of a words-string (one..twelve
+  // don't all follow the plain "+th" rule: eight/nine/twelve drop a letter).
+  private static readonly ORDINAL_IRREGULARS: Record<string, string> = {
+    one: "first",
+    two: "second",
+    three: "third",
+    four: "fourth",
+    five: "fifth",
+    eight: "eighth",
+    nine: "ninth",
+    twelve: "twelfth",
+  };
+
+  /** Ordinal words: "twenty-first", "one-hundredth", "twentieth", "eighth", … */
+  static toWordsOrdinal(num: number | string): string {
+    const originalString = IntUtils.toWords(num);
+    const lastHyphen = originalString.lastIndexOf("-");
+    const prefix = lastHyphen === -1 ? "" : originalString.substring(0, lastHyphen + 1);
+    const lastWord = lastHyphen === -1 ? originalString : originalString.substring(lastHyphen + 1);
+
+    const irregular = IntUtils.ORDINAL_IRREGULARS[lastWord];
+    if (irregular) return `${prefix}${irregular}`;
+
+    // Tens words (twenty, thirty, … ninety) take "-ieth" in place of the "y".
+    if (lastWord.endsWith("y")) return `${prefix}${lastWord.slice(0, -1)}ieth`;
+
+    return `${originalString}th`;
+  }
+
+  /** Ordinal words with a leading "one-" stripped ("one-hundredth" → "hundredth"). */
+  static toWordsOrdinalLazy(num: number | string): string {
+    const ordinal = IntUtils.toWordsOrdinal(num);
+    if (ordinal.substring(0, 4) === "one-") return ordinal.substring(4);
+    return ordinal;
+  }
+
+  /** Convert a decimal number (or string) to English words. */
+  static toWordsDecimal(num: number | string): string | null {
+    const str = num.toString();
+    if (str.lastIndexOf(".") === -1) return IntUtils.toWords(str);
+
+    const integer = str.split(".")[0] ?? "";
+    const decimal = str.split(".")[1] ?? "";
+
+    const pluralFraction = decimal.length > 0 && decimal.charAt(decimal.length - 1) !== "1";
+
+    let finalString: string;
+    if ((!integer || IntUtils.toWords(integer) === "zero") && decimal.length > 0) {
+      finalString = `${IntUtils.toWords(decimal)} ${IntUtils.toWordsOrdinalLazy(10 ** decimal.length)}`;
+    } else if ((!decimal || IntUtils.toWords(decimal) === "zero") && integer.length > 0) {
+      finalString = IntUtils.toWords(integer);
+    } else if (!(integer || decimal)) {
+      return null;
+    } else {
+      finalString = `${IntUtils.toWords(integer)} and ${IntUtils.toWords(decimal)} ${IntUtils.toWordsOrdinalLazy(10 ** decimal.length)}`;
+    }
+
+    return pluralFraction ? `${finalString}s` : finalString;
+  }
+}