@johnhenry/math-sample 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,245 @@
-# Temporary Holding Version
+# @johnhenry/math-sample
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sampling for plots (1D curves, 2D implicit/contour/gradient fields, 3D meshes, complex rasters, ODEs, series), as a library with no DOM in it. Give it a `(x) => number`
+(or an `@johnhenry/math` expression) and a viewport; get back `Float64Array`s
+with the poles and jumps already turned into gaps, plus the viewport maths,
+"nice" ticks and SVG path output a plot needs. Pure ESM, zero runtime
+dependencies, no globals beyond the language: it runs unchanged in a Web
+Worker, so a plotter can send it *sources and a viewport*, and transfer the
+arrays back.
+
+```bash
+npm install @johnhenry/math-sample
+```
+
+```ts
+import { sampleAdaptive, samplesToSvgPath, axesToSvg, niceTicks } from "@johnhenry/math-sample";
+import { compileExpression } from "@johnhenry/math-sample/expr"; // needs @johnhenry/math
+
+const f = compileExpression("a*sin(x)", { params: { a: 2 } });
+const view = { xMin: -10, xMax: 10, yMin: -6, yMax: 6 };
+
+const s = sampleAdaptive(f, { min: view.xMin, max: view.xMax }, 400, {
+  visibleYRange: { min: view.yMin, max: view.yMax },
+});
+s.x; s.y;                                    // Float64Array, NaN in y = gap
+samplesToSvgPath(s, view, 600, 300);         // "M0.00 150.00 L1.50 ..."
+```
+
+## API
+
+### Samples
+
+`Samples` is `{ x: Float64Array; y: Float64Array }`. A row with `y = NaN` is a
+gap: do not draw between its neighbours. Gaps are never first, last or
+adjacent to another gap, so `runsOf(samples)` (half-open row ranges) is exactly
+the polylines to draw.
+
+| Function | Does |
+|---|---|
+| `sampleUniform(f, domain, n, options?)` | `n` evenly spaced evaluations, both ends included |
+| `sampleAdaptive(f, domain, n, options?)` | the same base grid, with cells bisected where the curve bends |
+| `runsOf(samples)` | `[start, end)` row ranges of consecutive data |
+| `findDiscontinuities(samples)` | `{ before, after }` points either side of every gap |
+| `findCrossings(samples, signedDistance)` | interpolated crossings of a boundary (`y => y` is the x-axis); not across gaps |
+| `findRoots(f, domain, { resolution? })` | sign changes on a grid, polished by bisection; poles rejected |
+| `findIntersections(f, g, domain, opts?)` | roots of `f - g`, each with `y = f(x)` |
+| `toPoints(samples)` | `[x, y \| null][]`, JSON-safe |
+
+`f` is any `(x: number) => number`. Domains are `{ min, max }` (finite, `min < max`);
+`n` is an integer >= 2. Bad input throws `RangeError`.
+
+**Options (all samplers):**
+
+- `visibleYRange: { min, max }`: the y-range on screen. A sample far outside it
+  (a pole's finite but enormous shoulders) is treated as a gap, and the curve
+  is capped with an interpolated point just inside the edge, so it runs up to
+  the border of the plot instead of stopping short. Also sets the default
+  tolerance and, for `sampleAdaptive`, enables jump detection (`sampleUniform` does not detect jumps).
+- `signal` (`{ aborted: boolean }`, so any `AbortSignal`) and `isCancelled: () => boolean`:
+  checked every 256 evaluations; either one makes the sampler throw
+  `SampleCancelledError`. `isCancelled: () => generation !== latest` is the
+  generation-counter pattern for pan/zoom.
+
+**Options (`sampleAdaptive`):**
+
+- `maxDepth` (4): bisections per base cell.
+- `tolerance`: a cell is split while its midpoint is further than this, in y
+  units, from the straight line through its ends. Default `1e-4` of the visible
+  y span, so zooming in refines more and zooming out less; with no
+  `visibleYRange`, `1e-3`.
+- `jumpFraction` (0.5 with `visibleYRange`; off without): a cell still this far
+  apart (as a fraction of the y span) at `maxDepth`, whose height has not
+  shrunk as it was halved, is a jump (a step, a pole) and becomes a gap. A
+  steep slope loses height as it is halved, so it stays connected. `Infinity` turns it off.
+
+### Viewport
+
+`Viewport` is `{ xMin, xMax, yMin, yMax }`. Everything is unit-agnostic: use CSS
+pixels or device pixels, as long as width and height agree.
+
+`toScreenX/toScreenY(v, viewport, size)`, `toDataX/toDataY(s, viewport, size)`,
+`panViewport(v, dxPx, dyPx, w, h)` (content follows the pointer),
+`zoomViewport(v, factor, sx, sy, w, h)` (the data under the cursor stays put),
+`viewportFromAnchor(...)`, `wheelZoomFactor(deltaY, step?)`,
+`pinchZoomFactor(startDist, currentDist)`, `fitViewport(x, y, padding?)`, and
+`backingStoreSize(cssW, cssH, dpr)` which returns `{ width, height, scale }` for
+sizing a canvas: set `canvas.width/height` to those, `ctx.scale(scale, scale)`,
+and draw in CSS pixels. A non-finite or non-positive `dpr` counts as 1.
+
+### Ticks
+
+`niceTicks(min, max, target = 6)` gives round values (1, 2 or 5 times a power of
+ten) with no float drift (`0.3`, not `0.30000000000000004`). `tickStep` is the
+step it chose, and `formatTick(v, step)` labels with matching decimals.
+Degenerate or non-finite ranges give `[]`.
+
+### SVG
+
+`samplesToSvgPath(samples, viewport, w, h, { digits = 2 })` returns path data,
+one `M ... L ...` subpath per run. `axesToSvg(viewport, w, h, { targetTickCount, stroke, labelFill, fontSize })`
+returns `<line>`/`<text>` elements with inline attributes (axes at zero, or
+hugging the nearest edge with labels flipped inward). `svgDocument(w, h, content)`
+wraps them.
+
+### Expressions (`@johnhenry/math-sample/expr`)
+
+`compileExpression(exprOrSource, { variable = "x", params = {} })` returns a
+`(x) => number` from an `@johnhenry/math` `Expr` or source string. This is the
+only entry that needs `@johnhenry/math`, which is an **optional peer
+dependency**; the main entry never imports it. In a Worker: post the source
+string and params, compile there, sample, and `postMessage` the arrays with
+`[s.x.buffer, s.y.buffer]` as transferables.
+
+## 2D and 3D samplers, ODEs, series (part 2/3)
+
+All of these take plain functions, return typed arrays, and never draw spikes: a
+non-finite value is a **hole** (a gap row in curves, a skipped vertex in meshes,
+`NaN` in rasters). The grid and field samplers (`sampleSurface`, `sampleParametricSurface`,
+`sampleSpaceCurve`, `sampleVectorField3`, `sampleComplexRaster`, `findZerosAndPoles`, `sampleSlopeField`,
+`samplePhasePortrait` (field pass), `sampleImplicit`, `sampleContours`, `sampleGradient`) accept a
+**budget** and the cancellation options of part 1 (`signal`, `isCancelled`, which throw
+`SampleCancelledError`). `conformalGrid`, the ODE integrators, and the series/Fourier samplers do not take a budget
+(they are bounded by their own `samplesPerLine`, `maxSteps`, `samples` arguments):
+
+```ts
+{ maxCells?: number; maxMillis?: number; now?: () => number }
+```
+
+When the budget runs out the sampler stops at a row (or slab) boundary and
+**returns what it has** with `progress: { rows, of, complete, reason? }`
+(`reason` is `"cells"` or `"time"`), so a UI can say "stopped at row 120 of 161:
+the time limit". The time limit is checked per row, so one row can overrun it.
+
+### 3D (typed-array meshes)
+
+| Function | Returns |
+|---|---|
+| `sampleSurface(f(x, y), xDomain, yDomain, { columns, rows, zRange, ...budget })` | `Mesh` for `z = f(x, y)` |
+| `sampleParametricSurface(f(u, v) => [x, y, z], uDomain, vDomain, opts)` | `Mesh` |
+| `sampleSpaceCurve(f(t) => [x, y, z], tDomain, { samples, maxStep, ...budget })` | `Curve3` |
+| `curve3Runs(curve)` | `[start, end)` row ranges of consecutive data |
+| `sampleVectorField3(f(x, y, z) => [a, b, c], xD, yD, zD, { grid, ...budget })` | `VectorField3` |
+
+`Mesh` is `{ positions: Float32Array, normals: Float32Array, indices: Uint32Array, valid: Uint8Array,
+vertexCount, columns, rows, bounds, progress }` (3 floats per vertex; triangles are counter-clockwise
+seen from the side the normals point to, which is `+z` for `sampleSurface`, and `dP/du x dP/dv` for a
+parametric surface). A hole vertex has `NaN` position, zero normal and `valid = 0`, and **no triangle
+references it**, so GPU upload needs no special casing. `zRange` also turns a pole's huge but finite
+shoulders into holes. A quad with one hole corner keeps its other triangle. `bounds` covers valid vertices
+(`NaN`s when there are none). A valid vertex whose own normal degenerates (the poles of a sphere parameterisation) borrows
+a neighbouring vertex's normal. Mind the sign: `dP/du x dP/dv` on the usual sphere parameterisation
+`(sin v cos u, sin v sin u, cos v)` points **inward**; swap the arguments or negate a component for outward normals.
+`Curve3` is `{ positions: Float64Array (3 per row), t, count, progress }` with `NaN` rows as gaps (never first,
+last or adjacent). `VectorField3` is `{ origins, vectors, magnitudes: Float32Array, maxMagnitude, count,
+skipped, progress }`; points where the field is non-finite are dropped and counted in `skipped`.
+
+### Complex functions
+
+`ComplexFn` is `(re, im) => [re, im]`.
+
+- `sampleComplexRaster(f, reDomain, imDomain, { width, height })`: `{ re, im, abs, arg: Float32Array,
+  width, height, progress }` sampled at cell centres, row 0 at the smallest imaginary part; `arg` in
+  `(-PI, PI]`. Colour it yourself (hue from `arg`, brightness from `abs`).
+- `conformalGrid(f, reDomain, imDomain, { reLines, imLines, samplesPerLine, bound, maxStep })`: the image of a
+  rectangular grid of lines as `{ kind: "re" | "im", value, x, y }[]`; `NaN` gaps where `|f| > bound` (a pole)
+  or a step exceeds `maxStep` (a branch cut).
+- `findZerosAndPoles(f, reDomain, imDomain, { grid, tolerance })`: argument principle on every grid cell
+  (winding number = zeros - poles), then Newton on `f` or `1/f` scaled by the multiplicity. Returns
+  `{ items: { re, im, kind, order, refined }[] }`. A zero and a pole in one cell cancel, and two distinct
+  roots in one cell are reported as one root of the combined order (Newton's step scaled by that order may fail to converge,
+  giving `refined: false` at the cell centre): raise `grid` if you suspect it. A genuine multiple root (`z^3`) reports
+  its multiplicity once with `refined: true`. The search grid is offset by an irrational fraction of a cell and
+  extended past the rectangle, so roots and poles on round-number domains and on grid vertices are found; results
+  outside the rectangle are dropped.
+
+### ODEs
+
+- `sampleSlopeField(f(x, y), xDomain, yDomain, { columns, rows })`: slopes and unit directions
+  (`dirX`, `dirY`; vertical slopes are `(0, +-1)`; `NaN` where undefined).
+- `integrateRk4(f(t, y[]) => number[], t0, y0[], tEnd, { steps })` and `integrateAdaptive(...,
+  { atol, rtol, hMin, hMax })` (Dormand-Prince 5(4)): a `Trajectory { t, y (steps x dim), dim, steps,
+  reason }` where `reason` is `"end" | "blowup" | "maxSteps" | "stopped" | "stepTooSmall"`. Either direction in
+  `t`. `stop(t, y)` ends the run; `blowup` (default 1e12) catches finite-time singularities cleanly.
+- `sampleSolutionCurve(f(x, y), x0, y0, xDomain, { method: "adaptive" | "rk4" })`: the solution through a
+  point both ways as `Samples`, ending (not spiking) at an asymptote.
+- `samplePhasePortrait(F(x, y) => [dx, dy], xDomain, yDomain, { grid, seeds, tMax, fixedPointStarts })`:
+  `{ field, trajectories, fixedPoints, progress }`. Fixed points are found by Newton from a grid of starts
+  and classified from the Jacobian by `classifyFixedPoint(J)`: `stable/unstable node`, `saddle`,
+  `stable/unstable spiral`, `center`, the star/degenerate case, or `non-hyperbolic` (det ~ 0; linearisation
+  says nothing). A `center` is a linear classification: the nonlinear system may spiral.
+
+### Series
+
+- `taylorCoefficients(expr, x0, order)` (in `/expr`, needs `@johnhenry/math`; computed by power-series arithmetic, so order
+  12 or more is instant for `+ - * /`, powers, `exp ln sqrt sin cos tan sinh cosh tanh atan asin acos`; any other function
+  falls back to repeated symbolic differentiation, keep `order` <= 8 there) then
+  `sampleTaylorPartialSums(coefficients, x0, domain, orders, samples)`: one curve per order.
+- `sampleSeriesPartialSums(term(k, x), from, domain, orders, samples)`: function-series partial sums in
+  one pass over `k` (each term evaluated once per sample).
+- `partialSums(term(k), from, to)`: numeric partial sums plus an Aitken delta-squared `limitEstimate`
+  (a hint, not a convergence proof).
+- `fourierCoefficients(f, { min, max }, terms)` (midpoint rule on 4096 samples by default; the interval is one
+  period), `evaluateFourier`, `sampleFourierPartialSums(coefficients, domain, orders)`. Trig form
+  `a0/2 + sum a_k cos(k pi (x - c) / L) + b_k sin(...)`. A function with jumps shows the Gibbs overshoot, as it should.
+
+### 2D (implicit, contours, gradient)
+
+- `sampleImplicit(f(x, y), xDomain, yDomain, { grid, level })`: marching squares, saddle cells settled by the
+  centre value. Segments come back as `Samples` rows: two endpoints then a `NaN` row per segment, so
+  `runsOf` gives one run per segment. Cells with a non-finite corner are skipped.
+- `sampleContours(f, xDomain, yDomain, { grid, levels | count })`: one pass for all levels; default levels are
+  spread strictly between the grid's least and greatest value.
+- `sampleGradient(fx, fy, xDomain, yDomain, { grid })`: arrow tails and components with magnitudes.
+
+## What it does not do (yet)
+
+- **Implicit multiplication is opt-in.** `2x` fails to parse by default; write
+  `2*x`, or pass `compileExpression(src, { implicitMultiplication: true })`
+  (needs `@johnhenry/math` 0.1.0+; multi-letter variable names such as `theta`
+  then become products, use `x_1`).
+- **No interval-robust implicit mode.** `sampleImplicit` is a plain grid; thin features narrower
+  than a cell and isolated points can be missed (the quadtree/interval variant needs
+  `Symbolic.evaluateInterval`, johnhenry/math#108). Segments are not joined into long polylines.
+- **Meshes are uniform grids.** No adaptive refinement for surfaces or space curves; normals come from
+  finite differences of the vertex grid (one-sided at holes and edges), not from analytic gradients.
+- **Budgets stop at row boundaries**, and the time limit is only checked there. The ODE integrators take
+  `maxSteps`, not a budget.
+- **Polar/parametric 2D curves and 3D adaptive sampling** are not here; wrap `sampleSpaceCurve`
+  (with `z = 0`) or sample a parametric function through `sampleUniform` on each coordinate.
+- **Gaps from steep or fast-oscillating functions.** Jump detection is a
+  heuristic; a function that oscillates faster than the grid resolves can read
+  as a jump. Raise the resolution or `maxDepth`, or set `jumpFraction: Infinity`.
+- **Double-root and tangent roots are missed** by `findRoots` (no sign change).
+- **No memoization or debouncing.** Callers own caching; use `isCancelled` to
+  drop stale work.
+- **Typed output is `Float64Array` only.** Convert with `Float32Array.from(s.y)`
+  if you need less.
+
+## Tests
+
+`npm test -w @johnhenry/math-sample`. Golden values from NumPy, SciPy
+(`brentq`) and SymPy (pole locations) are committed in `test/fixtures/goldens.json`;
+regenerate with `scripts/generate-goldens.py` (the tests never call Python).
+Behaviour was designed against [mallory](https://github.com/johnhenry/mallory)'s
+samplers (MIT, same author); the code here is a rewrite.

package/dist/budget.d.ts

@@ -0,0 +1,47 @@
+import { type CancelSignal } 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 declare class Meter {
+    private readonly start;
+    private spent;
+    private readonly now;
+    private readonly budget;
+    private readonly cancel;
+    constructor(budget: Budget | undefined, cancel: Cancellable | undefined);
+    /** Throws on cancellation; returns a reason when the budget cannot afford `cost` more evaluations. */
+    check(cost: number): "cells" | "time" | undefined;
+    spend(n: number): void;
+    get cells(): number;
+}
+export declare function progress(rows: number, of: number, reason?: "cells" | "time"): Progress;
+export declare function assertCount(name: string, n: number, min?: number): void;
+export declare function assertRange(name: string, d: {
+    min: number;
+    max: number;
+}): void;
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAwB,MAAM,aAAa,CAAC;AAEtE;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;IAClB,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC3B;AAED,6DAA6D;AAC7D,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;gBACrC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS;IAMvE,sGAAsG;IACtG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS;IAOjD,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAGtB,IAAI,KAAK,IAAI,MAAM,CAElB;CACF;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAEtF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,IAAI,CAElE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAG/E"}

package/dist/budget.js

@@ -0,0 +1,44 @@
+import { SampleCancelledError } from "./sample.js";
+/** Tracks a {@link Budget} and cancellation for one call. */
+export class Meter {
+    start;
+    spent = 0;
+    now;
+    budget;
+    cancel;
+    constructor(budget, cancel) {
+        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) {
+        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) {
+        this.spent += n;
+    }
+    get cells() {
+        return this.spent;
+    }
+}
+export function progress(rows, of, reason) {
+    return reason === undefined ? { rows, of, complete: rows >= of } : { rows, of, complete: false, reason };
+}
+export function assertCount(name, n, min = 2) {
+    if (!Number.isInteger(n) || n < min)
+        throw new RangeError(`${name} must be an integer >= ${min}, got ${n}`);
+}
+export function assertRange(name, d) {
+    if (!Number.isFinite(d.min) || !Number.isFinite(d.max) || !(d.min < d.max))
+        throw new RangeError(`${name} must be finite with min < max`);
+}
+//# sourceMappingURL=budget.js.map

package/dist/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,oBAAoB,EAAE,MAAM,aAAa,CAAC;AA+BtE,6DAA6D;AAC7D,MAAM,OAAO,KAAK;IACC,KAAK,CAAS;IACvB,KAAK,GAAG,CAAC,CAAC;IACD,GAAG,CAAe;IAClB,MAAM,CAAqB;IAC3B,MAAM,CAA0B;IACjD,YAAY,MAA0B,EAAE,MAA+B;QACrE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,GAAG,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,WAAW,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAC5G,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC1B,CAAC;IACD,sGAAsG;IACtG,KAAK,CAAC,IAAY;QAChB,IAAI,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,IAAI,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE;YAAE,MAAM,IAAI,oBAAoB,EAAE,CAAC;QACnG,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;QACtB,IAAI,CAAC,EAAE,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ;YAAE,OAAO,OAAO,CAAC;QAChF,IAAI,CAAC,EAAE,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,SAAS;YAAE,OAAO,MAAM,CAAC;QACvF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,KAAK,CAAC,CAAS;QACb,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;IAClB,CAAC;IACD,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF;AAED,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,EAAU,EAAE,MAAyB;IAC1E,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3G,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,CAAS,EAAE,GAAG,GAAG,CAAC;IAC1D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG;QAAE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,0BAA0B,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;AAC9G,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,CAA+B;IACvE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;QACxE,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,gCAAgC,CAAC,CAAC;AAClE,CAAC"}

package/dist/complex.d.ts

@@ -0,0 +1,79 @@
+import { type Budget, type Cancellable, type 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 declare function sampleComplexRaster(f: ComplexFn, reDomain: Domain, imDomain: Domain, options?: ComplexRasterOptions): ComplexRaster;
+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 declare function conformalGrid(f: ComplexFn, reDomain: Domain, imDomain: Domain, options?: ConformalGridOptions): ConformalLine[];
+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;
+}
+/**
+ * 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 declare function findZerosAndPoles(f: ComplexFn, reDomain: Domain, imDomain: Domain, options?: ZerosPolesOptions): ZerosPoles;
+//# sourceMappingURL=complex.d.ts.map

package/dist/complex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"complex.d.ts","sourceRoot":"","sources":["../src/complex.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,MAAM,EAAE,KAAK,WAAW,EAAS,KAAK,QAAQ,EAAY,MAAM,aAAa,CAAC;AACtH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,qEAAqE;AACrE,MAAM,MAAM,SAAS,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE9E,MAAM,WAAW,oBAAqB,SAAQ,MAAM,EAAE,WAAW;IAC/D,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,YAAY,CAAC;IACjB,EAAE,EAAE,YAAY,CAAC;IACjB,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,SAAS,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,aAAa,CAyCf;AAED,MAAM,WAAW,aAAa;IAC5B,4GAA4G;IAC5G,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,CAAC,EAAE,YAAY,CAAC;IAChB,CAAC,EAAE,YAAY,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uHAAuH;AACvH,wBAAgB,aAAa,CAC3B,CAAC,EAAE,SAAS,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,aAAa,EAAE,CAiDjB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,gGAAgG;IAChG,KAAK,EAAE,MAAM,CAAC;IACd,gGAAgG;IAChG,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,iBAAkB,SAAQ,MAAM,EAAE,WAAW;IAC5D,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAQD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,CAAC,EAAE,SAAS,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,iBAAsB,GAC9B,UAAU,CA+HZ"}