@johnhenry/math 0.0.0

package/src/Graph.ts

@@ -0,0 +1,337 @@
+/**
+ * Graph — a weighted (optionally directed) graph with the standard algorithms:
+ * breadth/depth-first traversal, Dijkstra shortest paths, minimum spanning tree
+ * (Kruskal), topological sort, connected components, cycle detection, and
+ * conversion to an adjacency matrix (feeding {@link MatrixMath}) with
+ * Floyd-Warshall all-pairs distances.
+ */
+
+export interface Edge<T> {
+  from: T;
+  to: T;
+  weight: number;
+}
+
+/**
+ * Minimal binary min-heap keyed by a numeric priority, used by
+ * {@link Graph.dijkstra} / {@link Graph.shortestPath} to pick the next
+ * closest unvisited vertex in O(log n) instead of a linear scan. Supports
+ * duplicate/stale entries (an item can be pushed more than once when its
+ * distance improves); the caller is expected to skip entries whose stored
+ * priority no longer matches the current best-known distance ("lazy
+ * deletion"), which is cheaper than a decrease-key operation.
+ */
+class MinHeap<T> {
+  private readonly items: Array<{ priority: number; value: T }> = [];
+
+  get size(): number {
+    return this.items.length;
+  }
+
+  push(value: T, priority: number): void {
+    this.items.push({ priority, value });
+    let i = this.items.length - 1;
+    while (i > 0) {
+      const parent = (i - 1) >> 1;
+      if (this.items[parent].priority <= this.items[i].priority) break;
+      [this.items[parent], this.items[i]] = [this.items[i], this.items[parent]];
+      i = parent;
+    }
+  }
+
+  pop(): { priority: number; value: T } | undefined {
+    const top = this.items[0];
+    if (top === undefined) return undefined;
+    const last = this.items.pop() as { priority: number; value: T };
+    if (this.items.length) {
+      this.items[0] = last;
+      let i = 0;
+      const n = this.items.length;
+      for (;;) {
+        const left = 2 * i + 1;
+        const right = 2 * i + 2;
+        let smallest = i;
+        if (left < n && this.items[left].priority < this.items[smallest].priority) smallest = left;
+        if (right < n && this.items[right].priority < this.items[smallest].priority) smallest = right;
+        if (smallest === i) break;
+        [this.items[smallest], this.items[i]] = [this.items[i], this.items[smallest]];
+        i = smallest;
+      }
+    }
+    return top;
+  }
+}
+
+export class Graph<T = string | number> {
+  readonly directed: boolean;
+  private readonly adjacency = new Map<T, Map<T, number>>();
+
+  constructor(directed = false) {
+    this.directed = directed;
+  }
+
+  addVertex(v: T): this {
+    if (!this.adjacency.has(v)) this.adjacency.set(v, new Map());
+    return this;
+  }
+
+  addEdge(u: T, v: T, weight = 1): this {
+    this.addVertex(u).addVertex(v);
+    (this.adjacency.get(u) as Map<T, number>).set(v, weight);
+    if (!this.directed) (this.adjacency.get(v) as Map<T, number>).set(u, weight);
+    return this;
+  }
+
+  vertices(): T[] {
+    return [...this.adjacency.keys()];
+  }
+
+  neighbors(v: T): T[] {
+    return [...(this.adjacency.get(v)?.keys() ?? [])];
+  }
+
+  edges(): Array<Edge<T>> {
+    const out: Array<Edge<T>> = [];
+    const seen = new Set<string>();
+    for (const [from, nbrs] of this.adjacency) {
+      for (const [to, weight] of nbrs) {
+        if (!this.directed) {
+          const key = JSON.stringify([from, to].map(String).sort());
+          if (seen.has(key)) continue;
+          seen.add(key);
+        }
+        out.push({ from, to, weight });
+      }
+    }
+    return out;
+  }
+
+  /** Breadth-first traversal order from `start`. */
+  bfs(start: T): T[] {
+    const visited = new Set<T>([start]);
+    const order: T[] = [];
+    const queue: T[] = [start];
+    while (queue.length) {
+      const v = queue.shift() as T;
+      order.push(v);
+      for (const n of this.neighbors(v))
+        if (!visited.has(n)) {
+          visited.add(n);
+          queue.push(n);
+        }
+    }
+    return order;
+  }
+
+  /** Depth-first traversal order from `start`. */
+  dfs(start: T): T[] {
+    const visited = new Set<T>();
+    const order: T[] = [];
+    const visit = (v: T) => {
+      visited.add(v);
+      order.push(v);
+      for (const n of this.neighbors(v)) if (!visited.has(n)) visit(n);
+    };
+    visit(start);
+    return order;
+  }
+
+  /**
+   * Shared Dijkstra core used by {@link dijkstra} and {@link shortestPath}:
+   * a binary min-heap keyed on tentative distance replaces the O(V) linear
+   * scan for "closest unvisited vertex", bringing the algorithm from
+   * O(V²) down to the standard O((V+E) log V). Stale heap entries (pushed
+   * when a shorter distance was later found) are skipped lazily instead of
+   * removed, which is cheaper than a decrease-key operation.
+   */
+  private runDijkstra(start: T): { dist: Map<T, number>; prev: Map<T, T> } {
+    const dist = new Map<T, number>();
+    const prev = new Map<T, T>();
+    for (const v of this.vertices()) dist.set(v, Number.POSITIVE_INFINITY);
+    dist.set(start, 0);
+    const visited = new Set<T>();
+    const heap = new MinHeap<T>();
+    heap.push(start, 0);
+    while (heap.size) {
+      const top = heap.pop() as { priority: number; value: T };
+      const u = top.value;
+      if (visited.has(u)) continue;
+      if (top.priority > (dist.get(u) as number)) continue; // stale entry
+      visited.add(u);
+      for (const [n, w] of this.adjacency.get(u) ?? []) {
+        if (visited.has(n)) continue;
+        const nd = (dist.get(u) as number) + w;
+        if (nd < (dist.get(n) as number)) {
+          dist.set(n, nd);
+          prev.set(n, u);
+          heap.push(n, nd);
+        }
+      }
+    }
+    return { dist, prev };
+  }
+
+  /** Dijkstra shortest-path distances from `start` (non-negative weights). */
+  dijkstra(start: T): Map<T, number> {
+    return this.runDijkstra(start).dist;
+  }
+
+  /** The shortest path from `start` to `end` as `{ distance, path }`. */
+  shortestPath(start: T, end: T): { distance: number; path: T[] } {
+    const { dist, prev } = this.runDijkstra(start);
+    if (dist.get(end) === Number.POSITIVE_INFINITY) return { distance: Number.POSITIVE_INFINITY, path: [] };
+    const path: T[] = [];
+    let cur: T | undefined = end;
+    while (cur !== undefined) {
+      path.unshift(cur);
+      cur = cur === start ? undefined : prev.get(cur);
+    }
+    return { distance: dist.get(end) as number, path };
+  }
+
+  /** Connected components (undirected graphs). */
+  connectedComponents(): T[][] {
+    const seen = new Set<T>();
+    const components: T[][] = [];
+    for (const v of this.vertices()) {
+      if (seen.has(v)) continue;
+      const comp = this.bfs(v);
+      for (const c of comp) seen.add(c);
+      components.push(comp);
+    }
+    return components;
+  }
+
+  /** Topological order for a DAG, or `null` if the graph has a cycle. */
+  topologicalSort(): T[] | null {
+    const inDegree = new Map<T, number>();
+    for (const v of this.vertices()) inDegree.set(v, 0);
+    for (const [, nbrs] of this.adjacency) for (const [to] of nbrs) inDegree.set(to, (inDegree.get(to) as number) + 1);
+    const queue = this.vertices().filter((v) => inDegree.get(v) === 0);
+    const order: T[] = [];
+    while (queue.length) {
+      const v = queue.shift() as T;
+      order.push(v);
+      for (const n of this.neighbors(v)) {
+        inDegree.set(n, (inDegree.get(n) as number) - 1);
+        if (inDegree.get(n) === 0) queue.push(n);
+      }
+    }
+    return order.length === this.vertices().length ? order : null;
+  }
+
+  /** True when the graph contains a cycle. */
+  hasCycle(): boolean {
+    if (this.directed) return this.topologicalSort() === null;
+    const seen = new Set<T>();
+    const visit = (v: T, parent: T | null): boolean => {
+      seen.add(v);
+      for (const n of this.neighbors(v)) {
+        if (!seen.has(n)) {
+          if (visit(n, v)) return true;
+        } else if (n !== parent) return true;
+      }
+      return false;
+    };
+    for (const v of this.vertices()) if (!seen.has(v) && visit(v, null)) return true;
+    return false;
+  }
+
+  /** Minimum spanning tree (Kruskal) of an undirected graph, as a list of edges. */
+  minimumSpanningTree(): Array<Edge<T>> {
+    const parent = new Map<T, T>();
+    const find = (x: T): T => {
+      while (parent.get(x) !== x) {
+        parent.set(x, parent.get(parent.get(x) as T) as T);
+        x = parent.get(x) as T;
+      }
+      return x;
+    };
+    for (const v of this.vertices()) parent.set(v, v);
+    const mst: Array<Edge<T>> = [];
+    for (const e of this.edges().sort((a, b) => a.weight - b.weight)) {
+      const ra = find(e.from);
+      const rb = find(e.to);
+      if (ra !== rb) {
+        parent.set(ra, rb);
+        mst.push(e);
+      }
+    }
+    return mst;
+  }
+
+  /** Adjacency matrix (rows/cols follow the returned `order`; `Infinity` = no edge). */
+  toAdjacencyMatrix(): { matrix: number[][]; order: T[] } {
+    const order = this.vertices();
+    const index = new Map(order.map((v, i) => [v, i]));
+    const n = order.length;
+    const matrix = Array.from({ length: n }, (_, i) =>
+      Array.from({ length: n }, (_, j) => (i === j ? 0 : Number.POSITIVE_INFINITY)),
+    );
+    for (const [from, nbrs] of this.adjacency) {
+      for (const [to, w] of nbrs) matrix[index.get(from) as number][index.get(to) as number] = w;
+    }
+    return { matrix, order };
+  }
+
+  /**
+   * Strongly connected components (Tarjan's algorithm, single DFS pass,
+   * O(V+E)) — maximal vertex sets where every vertex can reach every
+   * other via directed edges. On an undirected graph this always reduces
+   * to {@link connectedComponents} (every edge is bidirectional, so
+   * "strongly connected" and "connected" coincide) — `connectedComponents`
+   * is the more direct choice there; this method exists for directed
+   * graphs, e.g. pruning a compatibility digraph down to the vertices
+   * that can actually participate in a cycle.
+   */
+  stronglyConnectedComponents(): T[][] {
+    let index = 0;
+    const indices = new Map<T, number>();
+    const lowlink = new Map<T, number>();
+    const onStack = new Set<T>();
+    const stack: T[] = [];
+    const components: T[][] = [];
+
+    const strongconnect = (v: T): void => {
+      indices.set(v, index);
+      lowlink.set(v, index);
+      index++;
+      stack.push(v);
+      onStack.add(v);
+
+      for (const w of this.neighbors(v)) {
+        if (!indices.has(w)) {
+          strongconnect(w);
+          lowlink.set(v, Math.min(lowlink.get(v) as number, lowlink.get(w) as number));
+        } else if (onStack.has(w)) {
+          lowlink.set(v, Math.min(lowlink.get(v) as number, indices.get(w) as number));
+        }
+      }
+
+      if (lowlink.get(v) === indices.get(v)) {
+        const component: T[] = [];
+        let w: T;
+        do {
+          w = stack.pop() as T;
+          onStack.delete(w);
+          component.push(w);
+        } while (w !== v);
+        components.push(component);
+      }
+    };
+
+    for (const v of this.vertices()) if (!indices.has(v)) strongconnect(v);
+    return components;
+  }
+
+  /** All-pairs shortest distances by Floyd-Warshall. */
+  floydWarshall(): { distances: number[][]; order: T[] } {
+    const { matrix, order } = this.toAdjacencyMatrix();
+    const n = order.length;
+    const d = matrix.map((row) => [...row]);
+    for (let k = 0; k < n; k++)
+      for (let i = 0; i < n; i++)
+        for (let j = 0; j < n; j++) if (d[i][k] + d[k][j] < d[i][j]) d[i][j] = d[i][k] + d[k][j];
+    return { distances: d, order };
+  }
+}

package/src/Graph3DUtils.ts

@@ -0,0 +1,269 @@
+import type { Polygon } from "./Polygon.ts";
+import type { Vector } from "./Vector.ts";
+import { VectorUtils } from "./VectorUtils.ts";
+
+/**
+ * Graph3DUtils — helpers for turning functions and points into 3D mesh data.
+ *
+ * Ported from Mallory's ActionScript `Graph3DUtils`, which produced
+ * papervision3d `Mesh3D`/`Vertex3D`/`Face3D` objects. Those Flash libraries do
+ * not exist here, so the geometry is emitted as plain, renderer-agnostic data
+ * ({@link Mesh} = a coloured list of triangular {@link Face}s). The underlying
+ * geometry math is preserved.
+ *
+ * Bug fixes from the AS3 original:
+ *  - `nRangeVector` only worked in one dimension (it returned `null` otherwise)
+ *    and mutated its `mins`/`maxes`/`steps` arguments via `shift()`; it now
+ *    handles any dimensionality without mutating its inputs.
+ *  - `pointMatrixToMesh3D` used `alpha2` for the first material (should be
+ *    `alpha1`) and had unreachable dead code after its `return`.
+ *
+ * NOTE: `create3DCurveSegment`/`create3DPrism` reproduce the original ribbon
+ * geometry, but with one fix: the AS3 original computed `phi` by converting
+ * an `atan2` result (radians) to degrees, then passed that degrees value
+ * straight into `Math.cos`/`Math.sin` (which expect radians) — a unit
+ * mismatch, not a deliberate choice. `phi` is now kept in radians throughout.
+ * The on-screen appearance still cannot be pixel-verified against the
+ * original Flash renderer (papervision3d no longer runs anywhere), so this is
+ * a best-effort mathematical correction, not a confirmed visual match.
+ */
+
+export interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/** A triangular face. */
+export type Face = [Vec3, Vec3, Vec3];
+
+export interface Material {
+  color: number;
+  alpha: number;
+  oneSide: boolean;
+}
+
+export interface Mesh {
+  material: Material;
+  faces: Face[];
+}
+
+export interface Placement3D {
+  x: number;
+  y: number;
+  z: number;
+  scaleX: number;
+  scaleY: number;
+  scaleZ: number;
+}
+
+const v3 = (x: number, y: number, z = 0): Vec3 => ({ x, y, z });
+const asPoint = (p: Vector<number>): Vec3 => ({ x: p.x as number, y: p.y as number, z: p.z as number });
+
+export class Graph3DUtils {
+  /** Sample `binaryOperation` over a 2D grid, returning a matrix of results. */
+  static dualRangeVector<T>(
+    binaryOperation: (x: number, y: number) => T,
+    xMin = -10,
+    xMax = 10,
+    xStep = 1,
+    yMin = -10,
+    yMax = 10,
+    yStep = 1,
+  ): Vector<Vector<T>> {
+    const xValues = VectorUtils.arithmeticSequence(xMin, xMax, xStep);
+    // yValues is loop-invariant across the x loop — compute it once, not per x.
+    const yValues = VectorUtils.arithmeticSequence(yMin, yMax, yStep);
+    return VectorUtils.transform(xValues, (x) => VectorUtils.transform(yValues, (y) => binaryOperation(x, y)));
+  }
+
+  /**
+   * Sample `nOperation` over an N-dimensional grid (bug fix: the AS3 version
+   * only handled N=1 and mutated its arguments). `nOperation` receives the
+   * coordinate array for each grid point.
+   */
+  static nRangeVector<T>(
+    nOperation: (coords: number[]) => T,
+    mins: readonly number[],
+    maxes: readonly number[],
+    steps: readonly number[],
+  ): Vector<unknown> {
+    // Each dimension's sequence of values is loop-invariant across the recursion
+    // (it depends only on `dim`, not on `prefix`) — compute all of them once
+    // up front instead of recomputing per recursive call.
+    const dimValues = mins.map((min, dim) =>
+      VectorUtils.arithmeticSequence(min, maxes[dim] as number, steps[dim] as number),
+    );
+    const recurse = (dim: number, prefix: number[]): unknown => {
+      if (dim >= mins.length) return nOperation(prefix);
+      return VectorUtils.transform(dimValues[dim] as Vector<number>, (v) => recurse(dim + 1, [...prefix, v]));
+    };
+    return recurse(0, []) as Vector<unknown>;
+  }
+
+  /** Placement descriptor for a point in 3D (position + optional uniform scale from `t`). */
+  static placement3D(p: Vector<number>, altProperties: string[] | null = null): Placement3D | 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 scale = (p.t as number) !== 0 ? (p.t as number) : 1;
+    return { x: p.x as number, y: p.y as number, z: p.z as number, scaleX: scale, scaleY: scale, scaleZ: scale };
+  }
+
+  static placement3DBarGraph(p: Vector<number>): Placement3D {
+    return { x: p.x as number, y: p.y as number, z: p.z as number, scaleX: 1, scaleY: 1, scaleZ: 1 };
+  }
+
+  /** A flat two-triangle ribbon between two points (see the class NOTE). */
+  static create3DCurveSegment(
+    firstPoint: Vector<number>,
+    secondPoint: Vector<number>,
+    color = 0x000000,
+    alpha = 1,
+    planeThickness = 1,
+    planeAngle = 0,
+  ): Mesh {
+    const t = planeThickness / 2;
+    const a = asPoint(firstPoint);
+    const b = asPoint(secondPoint);
+    const phi = Math.PI / 2 - Math.atan2(b.y - a.y, b.x - a.x);
+    const a1 = v3(a.x - Math.cos(phi) * t * Math.cos(planeAngle), a.y + Math.sin(phi) * t * Math.sin(planeAngle));
+    const a2 = v3(a.x + Math.cos(phi) * t * Math.cos(planeAngle), a.y - Math.sin(phi) * t * Math.sin(planeAngle));
+    const b1 = v3(b.x - Math.cos(phi) * t * Math.cos(planeAngle), b.y + Math.sin(phi) * t * Math.sin(planeAngle));
+    const b2 = v3(b.x + Math.cos(phi) * t * Math.cos(planeAngle), b.y - Math.sin(phi) * t * Math.sin(planeAngle));
+    return {
+      material: { color, alpha, oneSide: false },
+      faces: [
+        [a1, b1, a2],
+        [b1, b2, a2],
+      ],
+    };
+  }
+
+  /** A rectangular prism (tube) between two points (see the class NOTE). */
+  static create3DPrism(
+    firstPoint: Vector<number>,
+    secondPoint: Vector<number>,
+    color = 0x000000,
+    alpha = 1,
+    planeThickness = 1,
+  ): Mesh {
+    const t = planeThickness / 2;
+    const a = asPoint(firstPoint);
+    const b = asPoint(secondPoint);
+    const phi = Math.PI / 2 - Math.atan2(b.y - a.y, b.x - a.x);
+
+    const a1 = v3(a.x - Math.cos(phi), a.y + Math.sin(phi) * t, a.z);
+    const a11 = v3(a1.x, a1.y, a1.z + t);
+    const a12 = v3(a1.x, a1.y, a1.z - t);
+    const a2 = v3(a.x + Math.cos(phi), a.y - Math.sin(phi) * t, a.z);
+    const a21 = v3(a2.x, a2.y, a2.z + t);
+    const a22 = v3(a2.x, a2.y, a2.z - t);
+    const b1 = v3(b.x - Math.cos(phi), b.y + Math.sin(phi) * t, a.z);
+    const b11 = v3(b1.x, b1.y, b1.z + t);
+    const b12 = v3(b1.x, b1.y, b1.z - t);
+    const b2 = v3(b.x + Math.cos(phi), b.y - Math.sin(phi) * t, a.z);
+    const b21 = v3(b2.x, b2.y, b2.z + t);
+    const b22 = v3(b2.x, b2.y, b2.z - t);
+
+    const faces: Face[] = [
+      [a11, a12, a22],
+      [a11, a21, a22],
+      [b11, b12, b22],
+      [b11, b21, b22],
+      [a11, a21, b21],
+      [a11, b11, b21],
+      [a21, b21, b22],
+      [a21, a22, b22],
+      [a22, b22, b12],
+      [a22, a12, b12],
+      [a12, a11, b11],
+      [a12, b12, b11],
+    ];
+    return { material: { color, alpha, oneSide: false }, faces };
+  }
+
+  /** A tube following a poly-line, as one prism mesh per segment. */
+  static vectorTo3DPrism(points: Vector<Vector<number>>, color = 0, alpha = 1, planeThickness = 1): Mesh[] {
+    const out: Mesh[] = [];
+    for (let i = 0; i < points.length - 1; i++) {
+      out.push(
+        Graph3DUtils.create3DPrism(
+          points[i] as Vector<number>,
+          points[i + 1] as Vector<number>,
+          color,
+          alpha,
+          planeThickness,
+        ),
+      );
+    }
+    return out;
+  }
+
+  /** Alias of {@link vectorTo3DPrism} (the AS3 `VectorTo3DCurve` was identical). */
+  static vectorTo3DCurve(points: Vector<Vector<number>>, color = 0, alpha = 1, planeThickness = 1): Mesh[] {
+    return Graph3DUtils.vectorTo3DPrism(points, color, alpha, planeThickness);
+  }
+
+  /** Triangulate a polygon into a mesh (fan from vertex 0). */
+  static polygonToMesh3D(polygon: Polygon, color = 0, alpha = 1): Mesh {
+    const faces: Face[] = [];
+    const degenerate = polygon.clone();
+    while (degenerate.length > 2) {
+      faces.push([asPoint(degenerate.vertex(0)), asPoint(degenerate.vertex(1)), asPoint(degenerate.vertex(2))]);
+      degenerate.splice(1, 1);
+    }
+    return { material: { color, alpha, oneSide: false }, faces };
+  }
+
+  /**
+   * Build a surface mesh from a grid (matrix) of points, as two triangle
+   * sweeps with distinct materials (bug fix: the first sweep now uses `alpha1`).
+   */
+  static pointMatrixToMesh3D(
+    vector: Vector<Vector<Vector<number>>>,
+    color1 = 0,
+    alpha1 = 1,
+    color2 = 0xffffff,
+    alpha2 = 1,
+  ): Mesh[] {
+    const width = VectorUtils.width(vector as never);
+    const height = VectorUtils.height(vector as never);
+    const at = (i: number, j: number): Vector<number> | undefined =>
+      (vector[i] as Vector<Vector<number>> | undefined)?.[j];
+
+    const faces1: Face[] = [];
+    for (let i = 0; i < width - 1; i++) {
+      for (let j = 0; j < height - 1; j++) {
+        if (at(i, j) && vector[i + 1] && at(i, j + 1)) {
+          faces1.push([
+            asPoint(at(i, j) as Vector<number>),
+            asPoint(at(i + 1, j) as Vector<number>),
+            asPoint(at(i, j + 1) as Vector<number>),
+          ]);
+        }
+      }
+    }
+
+    const faces2: Face[] = [];
+    for (let i = 1; i < width; i++) {
+      for (let j = 1; j < height; j++) {
+        if (at(i, j) && vector[i - 1] && at(i, j - 1)) {
+          faces2.push([
+            asPoint(at(i, j) as Vector<number>),
+            asPoint(at(i - 1, j) as Vector<number>),
+            asPoint(at(i, j - 1) as Vector<number>),
+          ]);
+        }
+      }
+    }
+
+    return [
+      { material: { color: color1, alpha: alpha1, oneSide: false }, faces: faces1 },
+      { material: { color: color2, alpha: alpha2, oneSide: false }, faces: faces2 },
+    ];
+  }
+}