@johnhenry/math-sample 0.0.0-stage → 0.1.0

package/src/expr.ts

@@ -0,0 +1,283 @@
+import { type Expr, Symbolic } from "@johnhenry/math";
+import type { Fn1 } from "./sample.ts";
+
+export interface CompileOptions {
+  /** The free variable that becomes the argument. Default `"x"`. */
+  variable?: string;
+  /** Fixed values for every other free variable (slider values, say). */
+  params?: Record<string, number>;
+  /**
+   * Read juxtaposition as multiplication in source text (`2x`, `3sin(x)`, `(x+1)(x-1)`), the way people
+   * type maths. Default `false`. Needs `@johnhenry/math` 0.1.0 or later; multi-letter variable names are
+   * unavailable when it is on (see `ParseOptions` in `@johnhenry/math`). Ignored when `expr` is already a parsed `Expr`.
+   */
+  implicitMultiplication?: boolean;
+}
+
+/**
+ * Compile an `@johnhenry/math` expression (source text or a parsed `Expr`)
+ * into a plain `(x) => number` the samplers take. The AST is walked once; the
+ * closure is cheap to call thousands of times. This is the only module that
+ * needs `@johnhenry/math` (an optional peer dependency), so a Worker can
+ * receive an expression string plus params, compile it here, and sample.
+ *
+ * Source text uses `@johnhenry/math`'s grammar: write `2*x`, or pass
+ * `implicitMultiplication: true` to accept `2x`.
+ */
+export function compileExpression(expr: Expr | string, options: CompileOptions = {}): Fn1 {
+  const variable = options.variable ?? "x";
+  const tree =
+    typeof expr === "string"
+      ? Symbolic.parse(expr, { implicitMultiplication: options.implicitMultiplication === true })
+      : expr;
+  const compiled = Symbolic.compile(tree);
+  const env: Record<string, number> = { ...options.params, [variable]: 0 };
+  return (x) => {
+    env[variable] = x;
+    return compiled(env);
+  };
+}
+
+type Jet = Float64Array;
+
+class JetUnsupported extends Error {}
+
+function jmul(a: Jet, b: Jet): Jet {
+  const n = a.length;
+  const c = new Float64Array(n);
+  for (let i = 0; i < n; i++) {
+    const ai = a[i] as number;
+    if (ai === 0) continue;
+    for (let j = 0; i + j < n; j++) c[i + j] = (c[i + j] as number) + ai * (b[j] as number);
+  }
+  return c;
+}
+
+function jdiv(a: Jet, b: Jet): Jet {
+  const n = a.length;
+  const c = new Float64Array(n);
+  for (let k = 0; k < n; k++) {
+    let acc = a[k] as number;
+    for (let j = 1; j <= k; j++) acc -= (b[j] as number) * (c[k - j] as number);
+    c[k] = acc / (b[0] as number);
+  }
+  return c;
+}
+
+const jconst = (v: number, n: number): Jet => {
+  const j = new Float64Array(n);
+  j[0] = v;
+  return j;
+};
+
+function jexp(a: Jet): Jet {
+  const n = a.length;
+  const e = new Float64Array(n);
+  e[0] = Math.exp(a[0] as number);
+  for (let k = 1; k < n; k++) {
+    let acc = 0;
+    for (let j = 1; j <= k; j++) acc += j * (a[j] as number) * (e[k - j] as number);
+    e[k] = acc / k;
+  }
+  return e;
+}
+
+function jln(a: Jet): Jet {
+  const n = a.length;
+  const l = new Float64Array(n);
+  l[0] = Math.log(a[0] as number);
+  for (let k = 1; k < n; k++) {
+    let acc = 0;
+    for (let j = 1; j < k; j++) acc += j * (l[j] as number) * (a[k - j] as number);
+    l[k] = ((a[k] as number) - acc / k) / (a[0] as number);
+  }
+  return l;
+}
+
+/** sin/cos (hyperbolic = true for sinh/cosh) of a jet, together. */
+function jsincos(a: Jet, hyperbolic: boolean): [Jet, Jet] {
+  const n = a.length;
+  const s = new Float64Array(n);
+  const c = new Float64Array(n);
+  s[0] = hyperbolic ? Math.sinh(a[0] as number) : Math.sin(a[0] as number);
+  c[0] = hyperbolic ? Math.cosh(a[0] as number) : Math.cos(a[0] as number);
+  for (let k = 1; k < n; k++) {
+    let ss = 0;
+    let cc = 0;
+    for (let j = 1; j <= k; j++) {
+      ss += j * (a[j] as number) * (c[k - j] as number);
+      cc += j * (a[j] as number) * (s[k - j] as number);
+    }
+    s[k] = ss / k;
+    c[k] = (hyperbolic ? cc : -cc) / k;
+  }
+  return [s, c];
+}
+
+function jpowReal(a: Jet, p: number): Jet {
+  const n = a.length;
+  const f = new Float64Array(n);
+  const a0 = a[0] as number;
+  f[0] = a0 ** p;
+  for (let k = 1; k < n; k++) {
+    let acc = 0;
+    for (let j = 1; j <= k; j++) acc += (p * j - (k - j)) * (a[j] as number) * (f[k - j] as number);
+    f[k] = acc / (k * a0);
+  }
+  return f;
+}
+
+function jpowInt(a: Jet, m: number): Jet {
+  let r = jconst(1, a.length);
+  let base = a;
+  let e = Math.abs(m);
+  while (e > 0) {
+    if (e & 1) r = jmul(r, base);
+    base = jmul(base, base);
+    e = Math.floor(e / 2);
+  }
+  return m < 0 ? jdiv(jconst(1, a.length), r) : r;
+}
+
+/** Integrate a jet's derivative: given g = f', return f with f(0) = f0. */
+function jantiderivative(g: Jet, f0: number): Jet {
+  const n = g.length;
+  const f = new Float64Array(n);
+  f[0] = f0;
+  for (let k = 1; k < n; k++) f[k] = (g[k - 1] as number) / k;
+  return f;
+}
+
+function jderivative(a: Jet): Jet {
+  const n = a.length;
+  const d = new Float64Array(n);
+  for (let k = 0; k + 1 < n; k++) d[k] = (k + 1) * (a[k + 1] as number);
+  return d;
+}
+
+function jfunc(name: string, a: Jet): Jet {
+  const n = a.length;
+  const one = jconst(1, n);
+  switch (name) {
+    case "exp":
+      return jexp(a);
+    case "ln":
+      return jln(a);
+    case "sqrt":
+      return jpowReal(a, 0.5);
+    case "cbrt":
+      return jpowReal(a, 1 / 3);
+    case "sin":
+      return jsincos(a, false)[0];
+    case "cos":
+      return jsincos(a, false)[1];
+    case "tan": {
+      const [s, c] = jsincos(a, false);
+      return jdiv(s, c);
+    }
+    case "sinh":
+      return jsincos(a, true)[0];
+    case "cosh":
+      return jsincos(a, true)[1];
+    case "tanh": {
+      const [s, c] = jsincos(a, true);
+      return jdiv(s, c);
+    }
+    case "atan": {
+      const d = jdiv(jderivative(a), jplus(one, jmul(a, a), 1));
+      return jantiderivative(d, Math.atan(a[0] as number));
+    }
+    case "asin":
+    case "acos": {
+      const inv = jpowReal(jplus(one, jmul(a, a), -1), -0.5);
+      const d = jmul(jderivative(a), inv);
+      return name === "asin"
+        ? jantiderivative(d, Math.asin(a[0] as number))
+        : jantiderivative(d.map((v) => -v) as Jet, Math.acos(a[0] as number));
+    }
+    default:
+      throw new JetUnsupported(name);
+  }
+}
+
+function jplus(a: Jet, b: Jet, sign: 1 | -1): Jet {
+  const c = new Float64Array(a.length);
+  for (let k = 0; k < a.length; k++) c[k] = (a[k] as number) + sign * (b[k] as number);
+  return c;
+}
+
+function evalJet(e: Expr, variable: string, x0: number, params: Record<string, number>, n: number): Jet {
+  const go = (t: Expr): Jet => {
+    switch (t.type) {
+      case "const":
+        return jconst(t.value, n);
+      case "var": {
+        if (t.name === variable) {
+          const j = jconst(x0, n);
+          if (n > 1) j[1] = 1;
+          return j;
+        }
+        return jconst(params[t.name] ?? Number.NaN, n);
+      }
+      case "neg":
+        return go(t.arg).map((v) => -v) as Jet;
+      case "add":
+        return jplus(go(t.left), go(t.right), 1);
+      case "sub":
+        return jplus(go(t.left), go(t.right), -1);
+      case "mul":
+        return jmul(go(t.left), go(t.right));
+      case "div":
+        return jdiv(go(t.left), go(t.right));
+      case "func":
+        return jfunc(t.name, go(t.arg));
+      case "pow": {
+        const b = go(t.base);
+        const ex = go(t.exp);
+        const constExp = ex.every((v, k) => k === 0 || v === 0);
+        if (constExp) {
+          const p = ex[0] as number;
+          if (Number.isInteger(p) && Math.abs(p) <= 256) return jpowInt(b, p);
+          return jpowReal(b, p);
+        }
+        return jexp(jmul(ex, jln(b)));
+      }
+      default:
+        throw new JetUnsupported(t.type);
+    }
+  };
+  return go(e);
+}
+
+/**
+ * Taylor coefficients `a_k = f^(k)(x0) / k!` for `k = 0..order` of an expression. They are computed by truncated
+ * power-series ("jet") arithmetic, O(order^2) per node, so order 12 of `sin(x)*exp(x)/(1+x^2)` takes well under a
+ * millisecond. Supported: `+ - * /`, powers (integer or real exponent, or a variable exponent), and `exp ln sqrt cbrt sin
+ * cos tan sinh cosh tanh atan asin acos`. Any other node falls back to repeated symbolic differentiation with
+ * simplification after every derivative, which grows quickly: keep `order` at or below 8 there. A coefficient that is
+ * not finite at `x0` (a pole, `ln(0)`) is `NaN` or `Infinity`, and the partial sums built on it are gaps.
+ */
+export function taylorCoefficients(
+  expr: Expr | string,
+  x0: number,
+  order: number,
+  options: { variable?: string; params?: Record<string, number> } = {},
+): Float64Array {
+  if (!Number.isInteger(order) || order < 0) throw new RangeError("order must be a non-negative integer");
+  const variable = options.variable ?? "x";
+  const tree: Expr = typeof expr === "string" ? Symbolic.parse(expr) : expr;
+  try {
+    return evalJet(tree, variable, x0, options.params ?? {}, order + 1);
+  } catch (err) {
+    if (!(err instanceof JetUnsupported)) throw err;
+  }
+  let term: Expr = tree;
+  const out = new Float64Array(order + 1);
+  let factorial = 1;
+  for (let k = 0; k <= order; k++) {
+    if (k > 0) factorial *= k;
+    out[k] = Symbolic.evaluate(term, { ...options.params, [variable]: x0 }) / factorial;
+    if (k < order) term = Symbolic.simplify(Symbolic.differentiate(term, variable));
+  }
+  return out;
+}

package/src/field2d.ts

@@ -0,0 +1,259 @@
+import { assertCount, assertRange, type Budget, type Cancellable, Meter, type Progress, progress } from "./budget.ts";
+import type { Domain, Samples } from "./sample.ts";
+
+export type Fn2 = (x: number, y: number) => number;
+
+export interface Grid2Options extends Budget, Cancellable {
+  /** Cells per side of the sampling grid (`grid + 1` nodes per side). Default 128. */
+  grid?: number | [number, number];
+}
+
+export interface ImplicitCurve {
+  /**
+   * Segments as rows: each segment is two rows (its endpoints) followed by one `NaN` separator row, so
+   * `Samples` gap rules hold and `runsOf` yields one run per segment (join them if you wish).
+   */
+  segments: Samples;
+  segmentCount: number;
+  progress: Progress;
+}
+
+function dims(g: number | [number, number] | undefined): [number, number] {
+  const [nx, ny] = typeof g === "number" ? [g, g] : (g ?? [128, 128]);
+  assertCount("grid", nx, 1);
+  assertCount("grid", ny, 1);
+  return [nx, ny];
+}
+
+function marching(
+  f: Fn2,
+  xDomain: Domain,
+  yDomain: Domain,
+  levels: number[],
+  options: Grid2Options,
+): { segs: number[][]; progress: Progress } {
+  const [nx, ny] = dims(options.grid);
+  assertRange("x domain", xDomain);
+  assertRange("y domain", yDomain);
+  const meter = new Meter(options, options);
+  const hx = (xDomain.max - xDomain.min) / nx;
+  const hy = (yDomain.max - yDomain.min) / ny;
+  const segs: number[][] = levels.map(() => []);
+  let prev = new Float64Array(nx + 1);
+  let cur = new Float64Array(nx + 1);
+  const row = (j: number, out: Float64Array) => {
+    const y = yDomain.min + j * hy;
+    for (let i = 0; i <= nx; i++) out[i] = f(xDomain.min + i * hx, y);
+  };
+  let reason: "cells" | "time" | undefined;
+  row(0, prev);
+  meter.spend(nx + 1);
+  let done = 0;
+  for (let j = 0; j < ny; j++) {
+    reason = meter.check(nx + 1);
+    if (reason) break;
+    row(j + 1, cur);
+    meter.spend(nx + 1);
+    const y0 = yDomain.min + j * hy;
+    for (let i = 0; i < nx; i++) {
+      const x0 = xDomain.min + i * hx;
+      const v = [prev[i], prev[i + 1], cur[i + 1], cur[i]] as number[]; // corners ccw from bottom-left
+      if (!v.every(Number.isFinite)) continue; // holes: no segments through undefined cells
+      const cx = [x0, x0 + hx, x0 + hx, x0];
+      const cy = [y0, y0, y0 + hy, y0 + hy];
+      levels.forEach((level, li) => {
+        const s = v.map((q) => q - level);
+        // edge e joins corner e and corner e+1
+        const cross = (e: number): [number, number] | undefined => {
+          const a = s[e] as number;
+          const b = s[(e + 1) % 4] as number;
+          if (a < 0 === b < 0) return undefined; // a === 0 counts as >= 0 on the positive side
+          const t = a / (a - b);
+          const ea = e;
+          const eb = (e + 1) % 4;
+          return [
+            (cx[ea] as number) + t * ((cx[eb] as number) - (cx[ea] as number)),
+            (cy[ea] as number) + t * ((cy[eb] as number) - (cy[ea] as number)),
+          ];
+        };
+        const pts: Array<[number, number] | undefined> = [0, 1, 2, 3].map(cross);
+        const idx = [0, 1, 2, 3].filter((e) => pts[e]);
+        const out = segs[li] as number[];
+        const emit = (p: [number, number], q: [number, number]) => out.push(p[0], p[1], q[0], q[1]);
+        if (idx.length === 2)
+          emit(pts[idx[0] as number] as [number, number], pts[idx[1] as number] as [number, number]);
+        else if (idx.length === 4) {
+          // saddle: the cell centre decides which corners are connected
+          const centre = ((s[0] as number) + (s[1] as number) + (s[2] as number) + (s[3] as number)) / 4;
+          const p = pts as Array<[number, number]>;
+          const bottomLeftPositive = (s[0] as number) >= 0;
+          const joinsCorner0 = centre >= 0 === bottomLeftPositive; // centre agrees with corner 0: corners 0 and 2 are linked through the middle, so the curve cuts off corners 1 and 3
+          if (joinsCorner0) {
+            emit(p[0] as [number, number], p[1] as [number, number]);
+            emit(p[2] as [number, number], p[3] as [number, number]);
+          } else {
+            emit(p[3] as [number, number], p[0] as [number, number]);
+            emit(p[1] as [number, number], p[2] as [number, number]);
+          }
+        }
+      });
+    }
+    [prev, cur] = [cur, prev];
+    done++;
+  }
+  return { segs, progress: progress(done, ny, reason) };
+}
+
+function toSamples(flat: number[]): Samples {
+  const n = flat.length / 4;
+  const x = new Float64Array(n === 0 ? 0 : n * 3 - 1);
+  const y = new Float64Array(x.length);
+  for (let s = 0; s < n; s++) {
+    const o = s * 3;
+    x[o] = flat[4 * s] as number;
+    y[o] = flat[4 * s + 1] as number;
+    x[o + 1] = flat[4 * s + 2] as number;
+    y[o + 1] = flat[4 * s + 3] as number;
+    if (s < n - 1) {
+      x[o + 2] = Number.NaN;
+      y[o + 2] = Number.NaN;
+    }
+  }
+  return { x, y };
+}
+
+/**
+ * The curve `f(x, y) = level` (default 0) by marching squares on a regular grid. A saddle cell is joined by its
+ * centre value. Cells with a non-finite corner are skipped (a hole, not a spike). With a budget,
+ * `progress.rows` counts grid rows finished.
+ */
+export function sampleImplicit(
+  f: Fn2,
+  xDomain: Domain,
+  yDomain: Domain,
+  options: Grid2Options & { level?: number } = {},
+): ImplicitCurve {
+  const { segs, progress: p } = marching(f, xDomain, yDomain, [options.level ?? 0], options);
+  const flat = segs[0] as number[];
+  return { segments: toSamples(flat), segmentCount: flat.length / 4, progress: p };
+}
+
+export interface Contours {
+  levels: number[];
+  /** One entry per level, in `levels` order. */
+  curves: Array<{ level: number; segments: Samples; segmentCount: number }>;
+  progress: Progress;
+}
+
+/**
+ * Contour lines of `f` at the given `levels`, or `count` (default 9) levels evenly spread strictly between the
+ * grid's least and greatest values. One pass over the grid for all levels.
+ */
+export function sampleContours(
+  f: Fn2,
+  xDomain: Domain,
+  yDomain: Domain,
+  options: Grid2Options & { levels?: number[]; count?: number } = {},
+): Contours {
+  let levels = options.levels;
+  if (!levels) {
+    const [nx, ny] = dims(options.grid);
+    let lo = Infinity;
+    let hi = -Infinity;
+    for (let j = 0; j <= ny; j++)
+      for (let i = 0; i <= nx; i++) {
+        const v = f(
+          xDomain.min + ((xDomain.max - xDomain.min) * i) / nx,
+          yDomain.min + ((yDomain.max - yDomain.min) * j) / ny,
+        );
+        if (Number.isFinite(v)) {
+          if (v < lo) lo = v;
+          if (v > hi) hi = v;
+        }
+      }
+    const count = options.count ?? 9;
+    levels = lo < hi ? Array.from({ length: count }, (_, k) => lo + ((hi - lo) * (k + 1)) / (count + 1)) : [];
+  }
+  const { segs, progress: p } = marching(f, xDomain, yDomain, levels, options);
+  return {
+    levels,
+    curves: levels.map((level, k) => ({
+      level,
+      segments: toSamples(segs[k] as number[]),
+      segmentCount: (segs[k] as number[]).length / 4,
+    })),
+    progress: p,
+  };
+}
+
+export interface GradientField {
+  columns: number;
+  rows: number;
+  /** Arrow tails. */
+  x: Float64Array;
+  y: Float64Array;
+  /** Components; `NaN` where either component is non-finite. */
+  u: Float64Array;
+  v: Float64Array;
+  magnitude: Float64Array;
+  maxMagnitude: number;
+  progress: Progress;
+}
+
+/** Sample the vector field `(fx, fy)` (e.g. the two partial derivatives of a scalar field) on a grid including the edges. */
+export function sampleGradient(
+  fx: Fn2,
+  fy: Fn2,
+  xDomain: Domain,
+  yDomain: Domain,
+  options: Grid2Options = {},
+): GradientField {
+  const [cols, rws] = typeof options.grid === "number" ? [options.grid, options.grid] : (options.grid ?? [16, 16]);
+  assertCount("grid", cols);
+  assertCount("grid", rws);
+  assertRange("x domain", xDomain);
+  assertRange("y domain", yDomain);
+  const meter = new Meter(options, options);
+  const n = cols * rws;
+  const X = new Float64Array(n);
+  const Y = new Float64Array(n);
+  const U = new Float64Array(n).fill(Number.NaN);
+  const V = new Float64Array(n).fill(Number.NaN);
+  const M = new Float64Array(n).fill(Number.NaN);
+  let done = 0;
+  let reason: "cells" | "time" | undefined;
+  let max = 0;
+  for (let j = 0; j < rws; j++) {
+    reason = meter.check(cols);
+    if (reason) break;
+    const y = j === rws - 1 ? yDomain.max : yDomain.min + ((yDomain.max - yDomain.min) * j) / (rws - 1);
+    for (let i = 0; i < cols; i++) {
+      const x = i === cols - 1 ? xDomain.max : xDomain.min + ((xDomain.max - xDomain.min) * i) / (cols - 1);
+      const k = j * cols + i;
+      X[k] = x;
+      Y[k] = y;
+      const a = fx(x, y);
+      const b = fy(x, y);
+      if (Number.isFinite(a) && Number.isFinite(b)) {
+        U[k] = a;
+        V[k] = b;
+        M[k] = Math.hypot(a, b);
+        if (M[k] > max) max = M[k] as number;
+      }
+    }
+    meter.spend(cols);
+    done++;
+  }
+  const m = cols * done;
+  return {
+    columns: cols,
+    rows: done,
+    x: X.slice(0, m),
+    y: Y.slice(0, m),
+    u: U.slice(0, m),
+    v: V.slice(0, m),
+    magnitude: M.slice(0, m),
+    maxMagnitude: max,
+    progress: progress(done, rws, reason),
+  };
+}

package/src/index.ts

@@ -0,0 +1,112 @@
+export type { Budget, Cancellable, Progress } from "./budget.ts";
+export {
+  type ComplexFn,
+  type ComplexRaster,
+  type ComplexRasterOptions,
+  type ConformalGridOptions,
+  type ConformalLine,
+  conformalGrid,
+  findZerosAndPoles,
+  sampleComplexRaster,
+  type ZeroOrPole,
+  type ZerosPoles,
+  type ZerosPolesOptions,
+} from "./complex.ts";
+export {
+  type Contours,
+  type GradientField,
+  type Grid2Options,
+  type ImplicitCurve,
+  sampleContours,
+  sampleGradient,
+  sampleImplicit,
+} from "./field2d.ts";
+export {
+  type Curve3,
+  type CurveFn3,
+  type CurveOptions,
+  curve3Runs,
+  type Fn2,
+  type Mesh,
+  type MeshOptions,
+  type ParametricSurfaceFn,
+  sampleParametricSurface,
+  sampleSpaceCurve,
+  sampleSurface,
+  sampleVectorField3,
+  type VectorField3,
+  type VectorField3Options,
+  type VectorFn3,
+} from "./mesh.ts";
+export {
+  type AdaptiveOdeOptions,
+  classifyFixedPoint,
+  type Field2,
+  type FixedPoint,
+  type FixedPointType,
+  integrateAdaptive,
+  integrateRk4,
+  jacobian2,
+  type OdeOptions,
+  type PhasePortrait,
+  type PhasePortraitOptions,
+  type Rk4Options,
+  type Slope,
+  type SlopeField,
+  type SlopeFieldOptions,
+  type SolutionCurveOptions,
+  type StopReason,
+  type System,
+  samplePhasePortrait,
+  sampleSlopeField,
+  sampleSolutionCurve,
+  type Trajectory,
+} from "./ode.ts";
+export {
+  type AdaptiveOptions,
+  type CancelSignal,
+  type Domain,
+  type Fn1,
+  findCrossings,
+  findDiscontinuities,
+  findIntersections,
+  findRoots,
+  type Point,
+  type RootOptions,
+  runsOf,
+  SampleCancelledError,
+  type SampleOptions,
+  type Samples,
+  sampleAdaptive,
+  sampleUniform,
+  toPoints,
+  type YRange,
+} from "./sample.ts";
+export {
+  evaluateFourier,
+  evaluateTaylor,
+  type FourierCoefficients,
+  fourierCoefficients,
+  type NumericSeries,
+  type PartialSumCurves,
+  partialSums,
+  sampleFourierPartialSums,
+  sampleSeriesPartialSums,
+  sampleTaylorPartialSums,
+} from "./series.ts";
+export { type AxesOptions, axesToSvg, type PathOptions, samplesToSvgPath, svgDocument, type XY } from "./svg.ts";
+export { formatTick, niceTicks, tickStep } from "./ticks.ts";
+export {
+  backingStoreSize,
+  fitViewport,
+  panViewport,
+  pinchZoomFactor,
+  toDataX,
+  toDataY,
+  toScreenX,
+  toScreenY,
+  type Viewport,
+  viewportFromAnchor,
+  wheelZoomFactor,
+  zoomViewport,
+} from "./viewport.ts";