@johnhenry/math-sample 0.0.1 → 0.1.0

package/dist/series.js

@@ -0,0 +1,158 @@
+import { assertCount, assertRange } from "./budget.js";
+/** Evaluate `sum a_k (x - x0)^k` for `k <= order` by Horner's rule. */
+export function evaluateTaylor(coefficients, x0, x, order = coefficients.length - 1) {
+    const top = Math.min(order, coefficients.length - 1);
+    let acc = 0;
+    for (let k = top; k >= 0; k--)
+        acc = acc * (x - x0) + coefficients[k];
+    return acc;
+}
+function cleanSamples(x, y) {
+    // enforce: gaps not first/last/adjacent
+    const xs = [];
+    const ys = [];
+    for (let k = 0; k < x.length; k++) {
+        const yy = y[k];
+        if (Number.isFinite(yy)) {
+            xs.push(x[k]);
+            ys.push(yy);
+        }
+        else if (ys.length > 0 && !Number.isNaN(ys[ys.length - 1])) {
+            xs.push(x[k]);
+            ys.push(Number.NaN);
+        }
+    }
+    while (ys.length > 0 && Number.isNaN(ys[ys.length - 1])) {
+        ys.pop();
+        xs.pop();
+    }
+    return { x: Float64Array.from(xs), y: Float64Array.from(ys) };
+}
+function grid(domain, n) {
+    assertRange("domain", domain);
+    assertCount("samples", n);
+    const x = new Float64Array(n);
+    for (let k = 0; k < n; k++)
+        x[k] = k === n - 1 ? domain.max : domain.min + ((domain.max - domain.min) * k) / (n - 1);
+    return x;
+}
+/**
+ * Taylor partial sums of the given coefficients (`a_k = f^(k)(x0) / k!`) about `x0`, one curve per requested
+ * order, over a uniform grid. With `@johnhenry/math`, `taylorCoefficients` in `@johnhenry/math-sample/expr`
+ * produces the coefficients from an expression.
+ */
+export function sampleTaylorPartialSums(coefficients, x0, domain, orders, samples = 400) {
+    const x = grid(domain, samples);
+    const curves = orders.map((order) => {
+        if (!Number.isInteger(order) || order < 0)
+            throw new RangeError(`order must be a non-negative integer, got ${order}`);
+        const y = new Float64Array(samples);
+        for (let k = 0; k < samples; k++)
+            y[k] = evaluateTaylor(coefficients, x0, x[k], order);
+        return cleanSamples(x, y);
+    });
+    return { orders: [...orders], curves };
+}
+/**
+ * Partial sums of a function series `sum_{k=from}^{n} term(k, x)`, one curve per order `n`, computed
+ * in a single pass over `k` so each term is evaluated once per sample.
+ */
+export function sampleSeriesPartialSums(term, from, domain, orders, samples = 400) {
+    if (!Number.isInteger(from))
+        throw new RangeError("from must be an integer");
+    const x = grid(domain, samples);
+    const sorted = [...new Set(orders)].sort((a, b) => a - b);
+    for (const o of sorted)
+        if (!Number.isInteger(o) || o < from)
+            throw new RangeError(`order ${o} must be an integer >= from (${from})`);
+    const sums = new Float64Array(samples);
+    const byOrder = new Map();
+    let k = from;
+    for (const o of sorted) {
+        for (; k <= o; k++)
+            for (let i = 0; i < samples; i++)
+                sums[i] = sums[i] + term(k, x[i]);
+        byOrder.set(o, cleanSamples(x, Float64Array.from(sums)));
+    }
+    return { orders: [...orders], curves: orders.map((o) => byOrder.get(o)) };
+}
+/** Partial sums of the numeric series `sum_{k=from}^{to} term(k)`, with an Aitken limit estimate. */
+export function partialSums(term, from, to) {
+    if (!Number.isInteger(from) || !Number.isInteger(to) || to < from)
+        throw new RangeError("need integers from <= to");
+    const partial = new Float64Array(to - from + 1);
+    let s = 0;
+    for (let k = from; k <= to; k++) {
+        s += term(k);
+        partial[k - from] = s;
+    }
+    let limitEstimate = Number.NaN;
+    const n = partial.length;
+    if (n >= 3) {
+        const a = partial[n - 3];
+        const b = partial[n - 2];
+        const c = partial[n - 1];
+        const den = c - 2 * b + a;
+        limitEstimate = den === 0 ? c : c - ((c - b) * (c - b)) / den;
+    }
+    return { partial, from, limitEstimate };
+}
+/**
+ * Fourier coefficients of `f` on `[a, b]` taken as one period, by the midpoint rule on `samples` points
+ * (exact for trig polynomials below the Nyquist order, being a full-period rule; for a function with jumps the coefficients carry
+ * ordinary O(1/samples) quadrature error). `terms` is the highest harmonic. Trig form:
+ * `a0/2 + sum a_k cos(k w x) + b_k sin(k w x)` about the interval centre.
+ */
+export function fourierCoefficients(f, period, terms, samples = 4096) {
+    assertRange("period", period);
+    assertCount("terms", terms, 1);
+    assertCount("samples", samples, 4);
+    const L = (period.max - period.min) / 2;
+    const center = (period.max + period.min) / 2;
+    const a = new Float64Array(terms);
+    const b = new Float64Array(terms);
+    const vals = new Float64Array(samples);
+    for (let i = 0; i < samples; i++)
+        vals[i] = f(period.min + ((period.max - period.min) * (i + 0.5)) / samples); // midpoint
+    let a0 = 0;
+    for (let i = 0; i < samples; i++)
+        a0 += vals[i];
+    a0 = (2 * a0) / samples;
+    for (let k = 1; k <= terms; k++) {
+        let sa = 0;
+        let sb = 0;
+        for (let i = 0; i < samples; i++) {
+            const t = Math.PI * k * (((i + 0.5) / samples) * 2 - 1);
+            sa += vals[i] * Math.cos(t);
+            sb += vals[i] * Math.sin(t);
+        }
+        a[k - 1] = (2 * sa) / samples;
+        b[k - 1] = (2 * sb) / samples;
+    }
+    return { halfPeriod: L, center, a0, a, b };
+}
+/** Value of the Fourier partial sum with harmonics up to `n` at `x`. */
+export function evaluateFourier(c, x, n = c.a.length) {
+    const top = Math.min(n, c.a.length);
+    const w = Math.PI / c.halfPeriod;
+    let s = c.a0 / 2;
+    for (let k = 1; k <= top; k++) {
+        const t = k * w * (x - c.center);
+        s += c.a[k - 1] * Math.cos(t) + c.b[k - 1] * Math.sin(t);
+    }
+    return s;
+}
+/** One curve per harmonic count in `orders` (0 = just the constant term). */
+export function sampleFourierPartialSums(c, domain, orders, samples = 400) {
+    const x = grid(domain, samples);
+    const curves = orders.map((n) => {
+        if (!Number.isInteger(n) || n < 0)
+            throw new RangeError(`order must be a non-negative integer, got ${n}`);
+        const y = new Float64Array(samples);
+        for (let i = 0; i < samples; i++)
+            y[i] = evaluateFourier(c, x[i], n);
+        return cleanSamples(x, y);
+    });
+    return { orders: [...orders], curves };
+}
+//# sourceMappingURL=series.js.map

package/dist/series.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"series.js","sourceRoot":"","sources":["../src/series.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/math-sample",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Pure-ESM, DOM-free, Web-Worker-safe 1D function sampling for plotting: adaptive sampling with NaN gaps and discontinuity detection, a DPR-aware viewport model, nice ticks, and SVG path output. Typed arrays out.",
   "type": "module",
   "publishConfig": {
@@ -54,7 +54,7 @@
   "author": "John Henry",
   "license": "MIT",
   "peerDependencies": {
-    "@johnhenry/math": "^0.1.0"
+    "@johnhenry/math": ">=0.2.0 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@johnhenry/math": {
@@ -62,7 +62,7 @@
     }
   },
   "devDependencies": {
-    "@johnhenry/math": "^0.1.0",
+    "@johnhenry/math": "^0.2.0",
     "@types/node": "^22.10.0",
     "typescript": "^5.9.0"
   },

package/src/budget.ts

@@ -0,0 +1,72 @@
+import { type CancelSignal, SampleCancelledError } from "./sample.ts";
+
+/**
+ * A work limit for the 2D/3D samplers. When it runs out the sampler stops at a
+ * row boundary and returns what it has, with a {@link Progress} saying where
+ * it stopped (it does not throw).
+ */
+export interface Budget {
+  /** Most function evaluations ("cells") the call may spend. Checked per row/slab. */
+  maxCells?: number;
+  /** Wall-clock limit in milliseconds. Checked per row/slab, so a single row can overrun it. */
+  maxMillis?: number;
+  /** Clock override for tests; default `performance.now` when present, else `Date.now`. */
+  now?: () => number;
+}
+
+export interface Cancellable {
+  signal?: CancelSignal;
+  isCancelled?: () => boolean;
+}
+
+export interface Progress {
+  /** Rows (or slabs, or steps) completed. */
+  rows: number;
+  /** Rows the full job needed. */
+  of: number;
+  complete: boolean;
+  /** Why it stopped early. Absent when `complete`. */
+  reason?: "cells" | "time";
+}
+
+/** Tracks a {@link Budget} and cancellation for one call. */
+export class Meter {
+  private readonly start: number;
+  private spent = 0;
+  private readonly now: () => number;
+  private readonly budget: Budget | undefined;
+  private readonly cancel: Cancellable | undefined;
+  constructor(budget: Budget | undefined, cancel: Cancellable | undefined) {
+    this.budget = budget;
+    this.cancel = cancel;
+    this.now = budget?.now ?? (typeof performance !== "undefined" ? () => performance.now() : () => Date.now());
+    this.start = this.now();
+  }
+  /** Throws on cancellation; returns a reason when the budget cannot afford `cost` more evaluations. */
+  check(cost: number): "cells" | "time" | undefined {
+    if (this.cancel?.signal?.aborted || this.cancel?.isCancelled?.()) throw new SampleCancelledError();
+    const b = this.budget;
+    if (b?.maxCells !== undefined && this.spent + cost > b.maxCells) return "cells";
+    if (b?.maxMillis !== undefined && this.now() - this.start > b.maxMillis) return "time";
+    return undefined;
+  }
+  spend(n: number): void {
+    this.spent += n;
+  }
+  get cells(): number {
+    return this.spent;
+  }
+}
+
+export function progress(rows: number, of: number, reason?: "cells" | "time"): Progress {
+  return reason === undefined ? { rows, of, complete: rows >= of } : { rows, of, complete: false, reason };
+}
+
+export function assertCount(name: string, n: number, min = 2): void {
+  if (!Number.isInteger(n) || n < min) throw new RangeError(`${name} must be an integer >= ${min}, got ${n}`);
+}
+
+export function assertRange(name: string, d: { min: number; max: number }): void {
+  if (!Number.isFinite(d.min) || !Number.isFinite(d.max) || !(d.min < d.max))
+    throw new RangeError(`${name} must be finite with min < max`);
+}

package/src/complex.ts

@@ -0,0 +1,327 @@
+import { assertCount, assertRange, type Budget, type Cancellable, Meter, type Progress, progress } from "./budget.ts";
+import type { Domain } from "./sample.ts";
+
+/** A complex function over plain numbers: `(re, im) -> [re, im]`. */
+export type ComplexFn = (re: number, im: number) => readonly [number, number];
+
+export interface ComplexRasterOptions extends Budget, Cancellable {
+  /** Pixels across (real axis). Default 128. */
+  width?: number;
+  /** Pixels down (imaginary axis). Default 128. */
+  height?: number;
+}
+
+/**
+ * Grid of `f(z)` values for domain colouring. Row 0 is the *smallest* imaginary part (mathematical
+ * orientation); flip when drawing to a canvas. Cells where `f` is not finite hold `NaN` in all four arrays
+ * (a pole shows as `abs = Infinity` only if `f` returned an infinite modulus with finite parts; otherwise NaN).
+ * `arg` is in `(-PI, PI]`.
+ */
+export interface ComplexRaster {
+  width: number;
+  /** Rows completed (may be fewer than requested when the budget ran out). */
+  height: number;
+  re: Float32Array;
+  im: Float32Array;
+  abs: Float32Array;
+  arg: Float32Array;
+  progress: Progress;
+}
+
+/** Sample `f` at the centre of each cell of a `width` x `height` grid over the rectangle. */
+export function sampleComplexRaster(
+  f: ComplexFn,
+  reDomain: Domain,
+  imDomain: Domain,
+  options: ComplexRasterOptions = {},
+): ComplexRaster {
+  const width = options.width ?? 128;
+  const height = options.height ?? 128;
+  assertCount("width", width, 1);
+  assertCount("height", height, 1);
+  assertRange("re domain", reDomain);
+  assertRange("im domain", imDomain);
+  const meter = new Meter(options, options);
+  const re = new Float32Array(width * height).fill(Number.NaN);
+  const im = new Float32Array(width * height).fill(Number.NaN);
+  const abs = new Float32Array(width * height).fill(Number.NaN);
+  const arg = new Float32Array(width * height).fill(Number.NaN);
+  let rows = 0;
+  let reason: "cells" | "time" | undefined;
+  for (let j = 0; j < height; j++) {
+    reason = meter.check(width);
+    if (reason) break;
+    const y = imDomain.min + ((imDomain.max - imDomain.min) * (j + 0.5)) / height;
+    for (let i = 0; i < width; i++) {
+      const x = reDomain.min + ((reDomain.max - reDomain.min) * (i + 0.5)) / width;
+      const w = f(x, y);
+      const k = j * width + i;
+      if (Number.isFinite(w[0]) && Number.isFinite(w[1])) {
+        re[k] = w[0];
+        im[k] = w[1];
+        abs[k] = Math.hypot(w[0], w[1]);
+        arg[k] = Math.atan2(w[1], w[0]);
+      }
+    }
+    meter.spend(width);
+    rows++;
+  }
+  return {
+    width,
+    height: rows,
+    re: re.slice(0, width * rows),
+    im: im.slice(0, width * rows),
+    abs: abs.slice(0, width * rows),
+    arg: arg.slice(0, width * rows),
+    progress: progress(rows, height, reason),
+  };
+}
+
+export interface ConformalLine {
+  /** `"re"`: the image of the vertical line `Re z = value`; `"im"`: of the horizontal line `Im z = value`. */
+  kind: "re" | "im";
+  value: number;
+  /** Image points; `NaN` rows are gaps (never first, last or adjacent). */
+  x: Float64Array;
+  y: Float64Array;
+}
+
+export interface ConformalGridOptions {
+  /** Vertical grid lines (constant real part), evenly spaced including both edges. Default 11. */
+  reLines?: number;
+  /** Horizontal grid lines (constant imaginary part). Default 11. */
+  imLines?: number;
+  /** Samples along each line. Default 200. */
+  samplesPerLine?: number;
+  /** Image points with modulus above this become gaps (poles). Default 1e6. */
+  bound?: number;
+  /** Segments whose image is longer than this become gaps (branch cuts). Default: no limit. */
+  maxStep?: number;
+}
+
+/** The image under `f` of a rectangular grid of lines: where the grid lines go, drawn as the conformal-map picture. */
+export function conformalGrid(
+  f: ComplexFn,
+  reDomain: Domain,
+  imDomain: Domain,
+  options: ConformalGridOptions = {},
+): ConformalLine[] {
+  const nRe = options.reLines ?? 11;
+  const nIm = options.imLines ?? 11;
+  const n = options.samplesPerLine ?? 200;
+  const bound = options.bound ?? 1e6;
+  assertCount("reLines", nRe, 1);
+  assertCount("imLines", nIm, 1);
+  assertCount("samplesPerLine", n);
+  assertRange("re domain", reDomain);
+  assertRange("im domain", imDomain);
+  const lines: ConformalLine[] = [];
+  const trace = (kind: "re" | "im", value: number, d: Domain): ConformalLine => {
+    const xs: number[] = [];
+    const ys: number[] = [];
+    let pending = false;
+    let px = Number.NaN;
+    let py = Number.NaN;
+    for (let k = 0; k < n; k++) {
+      const s = k === n - 1 ? d.max : d.min + ((d.max - d.min) * k) / (n - 1);
+      const w = kind === "re" ? f(value, s) : f(s, value);
+      const good = Number.isFinite(w[0]) && Number.isFinite(w[1]) && Math.hypot(w[0], w[1]) <= bound;
+      if (!good) {
+        pending = xs.length > 0;
+        px = Number.NaN;
+        continue;
+      }
+      const cut =
+        options.maxStep !== undefined && !Number.isNaN(px) && Math.hypot(w[0] - px, w[1] - py) > options.maxStep;
+      if ((pending || cut) && xs.length > 0) {
+        xs.push(Number.NaN);
+        ys.push(Number.NaN);
+      }
+      xs.push(w[0]);
+      ys.push(w[1]);
+      px = w[0];
+      py = w[1];
+      pending = false;
+    }
+    return { kind, value, x: Float64Array.from(xs), y: Float64Array.from(ys) };
+  };
+  for (let i = 0; i < nRe; i++)
+    lines.push(
+      trace("re", nRe === 1 ? reDomain.min : reDomain.min + ((reDomain.max - reDomain.min) * i) / (nRe - 1), imDomain),
+    );
+  for (let j = 0; j < nIm; j++)
+    lines.push(
+      trace("im", nIm === 1 ? imDomain.min : imDomain.min + ((imDomain.max - imDomain.min) * j) / (nIm - 1), reDomain),
+    );
+  return lines;
+}
+
+export interface ZeroOrPole {
+  re: number;
+  im: number;
+  kind: "zero" | "pole";
+  /** Multiplicity (zero) or order (pole), from the winding number of the cell it was found in. */
+  order: number;
+  /** `false` when the local refinement did not converge and `re`/`im` is only the cell centre. */
+  refined: boolean;
+}
+
+export interface ZerosPolesOptions extends Budget, Cancellable {
+  /** Cells per side of the search grid. Default 24. */
+  grid?: number;
+  /** Convergence tolerance on the root position. Default 1e-10 (relative to the rectangle size). */
+  tolerance?: number;
+}
+
+export interface ZerosPoles {
+  items: ZeroOrPole[];
+  progress: Progress;
+}
+
+const wrap = (d: number) => {
+  while (d > Math.PI) d -= 2 * Math.PI;
+  while (d < -Math.PI) d += 2 * Math.PI;
+  return d;
+};
+
+/**
+ * Zeros and poles of `f` inside a rectangle, by the argument principle: the winding number of `f` around each
+ * grid cell is (zeros - poles) inside it; non-zero cells are refined with Newton's method (on `f` for a
+ * zero, on `1/f` for a pole, scaled by the multiplicity). A zero and a pole inside one cell cancel and are missed:
+ * raise `grid`. The search grid is offset by an irrational fraction of a cell and extended past the
+ * rectangle, so round-number domains do not put roots on cell edges; results inside the rectangle (or on its edge) are
+ * kept and results within the tolerance are merged. `progress.rows` counts grid rows searched.
+ */
+export function findZerosAndPoles(
+  f: ComplexFn,
+  reDomain: Domain,
+  imDomain: Domain,
+  options: ZerosPolesOptions = {},
+): ZerosPoles {
+  const grid = options.grid ?? 24;
+  assertCount("grid", grid, 1);
+  assertRange("re domain", reDomain);
+  assertRange("im domain", imDomain);
+  const size = Math.max(reDomain.max - reDomain.min, imDomain.max - imDomain.min);
+  const tol = (options.tolerance ?? 1e-10) * size;
+  const meter = new Meter(options, options);
+  const dx = (reDomain.max - reDomain.min) / grid;
+  const dy = (imDomain.max - imDomain.min) / grid;
+  const found: ZeroOrPole[] = [];
+
+  const argAt = (x: number, y: number): number => {
+    const w = f(x, y);
+    if (w[0] === 0 && w[1] === 0) return Number.NaN; // an exact zero has no argument
+    return Math.atan2(w[1], w[0]);
+  };
+  // winding of f along segment p->q, subdividing until the phase moves < 1 rad per piece
+  const segment = (x0: number, y0: number, a0: number, x1: number, y1: number, a1: number, depth: number): number => {
+    const d = wrap(a1 - a0);
+    // a minimum depth keeps a high-order root from aliasing a whole turn (3 theta moving 2 pi in one piece)
+    if ((depth >= 4 && Math.abs(d) < 1) || depth >= 14) return d;
+    const xm = (x0 + x1) / 2;
+    const ym = (y0 + y1) / 2;
+    const am = argAt(xm, ym);
+    return segment(x0, y0, a0, xm, ym, am, depth + 1) + segment(xm, ym, am, x1, y1, a1, depth + 1);
+  };
+  const winding = (x0: number, y0: number, x1: number, y1: number): number => {
+    const pts: Array<[number, number]> = [
+      [x0, y0],
+      [x1, y0],
+      [x1, y1],
+      [x0, y1],
+      [x0, y0],
+    ];
+    const args = pts.map(([x, y]) => argAt(x, y));
+    if (args.some((a) => !Number.isFinite(a))) return Number.NaN;
+    let total = 0;
+    for (let k = 0; k < 4; k++) {
+      const p = pts[k] as [number, number];
+      const q = pts[k + 1] as [number, number];
+      total += segment(p[0], p[1], args[k] as number, q[0], q[1], args[k + 1] as number, 0);
+    }
+    return Math.round(total / (2 * Math.PI));
+  };
+
+  const newton = (
+    x: number,
+    y: number,
+    kind: "zero" | "pole",
+    order: number,
+    box: [number, number, number, number],
+  ) => {
+    const g = (a: number, b: number): [number, number] => {
+      const w = f(a, b);
+      if (kind === "zero") return [w[0], w[1]];
+      const m = w[0] * w[0] + w[1] * w[1];
+      return [w[0] / m, -w[1] / m]; // 1/f
+    };
+    let zx = x;
+    let zy = y;
+    for (let it = 0; it < 60; it++) {
+      const [gr, gi] = g(zx, zy);
+      if (!Number.isFinite(gr) || !Number.isFinite(gi)) return undefined;
+      const h = 1e-7 * Math.max(1, Math.abs(zx), Math.abs(zy));
+      const [ar, ai] = g(zx + h, zy);
+      const dr = (ar - gr) / h; // derivative of an analytic function = d/dx
+      const di = (ai - gi) / h;
+      const den = dr * dr + di * di;
+      if (!(den > 0) || !Number.isFinite(den)) return undefined;
+      // step = order * g / g'
+      const sr = (order * (gr * dr + gi * di)) / den;
+      const si = (order * (gi * dr - gr * di)) / den;
+      zx -= sr;
+      zy -= si;
+      if (Math.hypot(sr, si) < tol) {
+        const pad = 0.5 * Math.max(dx, dy);
+        if (zx < box[0] - pad || zx > box[1] + pad || zy < box[2] - pad || zy > box[3] + pad) return undefined;
+        return [zx, zy] as const;
+      }
+      if (!Number.isFinite(zx) || !Number.isFinite(zy)) return undefined;
+    }
+    return undefined;
+  };
+
+  // The search grid is shifted by an irrational fraction of a cell and extended by one cell on each side, so
+  // roots and poles on a round-number domain (z^3 - z on [-2, 2]) sit inside cells, not on their edges or
+  // corners. Candidates outside the requested rectangle are discarded at the end.
+  const OFFSET = 0.3819660112501051;
+  const gx0 = reDomain.min - (1 - OFFSET) * dx;
+  const gy0 = imDomain.min - (1 - OFFSET) * dy;
+  const cells = grid + 1;
+  const slack = 1e-9 * size;
+  const insideRect = (x: number, y: number) =>
+    x >= reDomain.min - slack && x <= reDomain.max + slack && y >= imDomain.min - slack && y <= imDomain.max + slack;
+  let rows = 0;
+  let reason: "cells" | "time" | undefined;
+  for (let j = 0; j < cells; j++) {
+    reason = meter.check(cells * 4);
+    if (reason) break;
+    for (let i = 0; i < cells; i++) {
+      const x0 = gx0 + i * dx;
+      const y0 = gy0 + j * dy;
+      let w = winding(x0, y0, x0 + dx, y0 + dy);
+      let ex = 0;
+      if (Number.isNaN(w)) {
+        // f is zero or non-finite on this cell's boundary (an exact root/pole on an edge): retry slightly inflated
+        ex = 0.0123 * dx;
+        w = winding(x0 - ex, y0 - 0.0123 * dy, x0 + dx + ex, y0 + dy + 0.0123 * dy);
+      }
+      if (!Number.isFinite(w) || w === 0) continue;
+      const kind = w > 0 ? "zero" : "pole";
+      const order = Math.abs(w);
+      const cx = x0 + dx / 2;
+      const cy = y0 + dy / 2;
+      const refined = newton(cx, cy, kind, order, [x0, x0 + dx, y0, y0 + dy]);
+      const [rx, ry] = refined ?? [cx, cy];
+      if (!insideRect(rx, ry)) continue;
+      if (found.some((p) => p.kind === kind && Math.hypot(p.re - rx, p.im - ry) < Math.max(tol * 1e3, 1e-7 * size)))
+        continue;
+      found.push({ re: rx, im: ry, kind, order, refined: refined !== undefined });
+    }
+    meter.spend(cells * 4);
+    rows++;
+  }
+  found.sort((a, b) => a.re - b.re || a.im - b.im);
+  return { items: found, progress: progress(rows, cells, reason) };
+}