@woosh/meep-engine 2.134.5 → 2.135.0

package/src/core/math/computeWholeDivisorLow.js

@@ -1,33 +1,33 @@
-import { assert } from "../assert.js";
-
-/**
- * Compute the largest positive integer divisor of a given "product" value
- * @param {number} product
- * @param {number} limit
- * @returns {number}
- */
-export function computeWholeDivisorLow(product, limit) {
-
-    assert.isNumber(product, 'product');
-    assert.isInteger(product, 'product');
-
-    assert.isNumber(limit, 'limit');
-    assert.isInteger(limit, 'limit');
-
-    assert.isFiniteNumber(limit,'limit');
-    assert.isFiniteNumber(product,'product');
-
-    let i = limit;
-
-    while (i > 1) {
-
-        if (product % i === 0) {
-            break;
-        }
-
-        i--;
-
-    }
-
-    return i;
-}
+import { assert } from "../assert.js";
+
+/**
+ * Compute the largest positive integer divisor of a given "product" value
+ * @param {number} product
+ * @param {number} limit
+ * @returns {number}
+ */
+export function computeWholeDivisorLow(product, limit) {
+
+    assert.isNumber(product, 'product');
+    assert.isInteger(product, 'product');
+
+    assert.isNumber(limit, 'limit');
+    assert.isInteger(limit, 'limit');
+
+    assert.isFinite(limit,'limit');
+    assert.isFinite(product,'product');
+
+    let i = limit;
+
+    while (i > 1) {
+
+        if (product % i === 0) {
+            break;
+        }
+
+        i--;
+
+    }
+
+    return i;
+}

package/src/core/math/linalg/eigen/eigen_values_find_spectral_gap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eigen_values_find_spectral_gap.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/eigen/eigen_values_find_spectral_gap.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,uDAHW,MAAM,EAAE,GACN,MAAM,CAoBlB"}

package/src/core/math/linalg/eigen/matrix_eigenvalues_in_place.d.ts

@@ -0,0 +1,10 @@
+/**
+ * list of eigen values square matrix (allow non-symmetric)
+ * NOTE: Modifies input matrix
+ * @template T extends ArrayLike<number>
+ * @param {T} out
+ * @param {SquareMatrix} mat
+ * @return {T}
+ */
+export function matrix_eigenvalues_in_place<T>(out: T, mat: SquareMatrix): T;
+//# sourceMappingURL=matrix_eigenvalues_in_place.d.ts.map

package/src/core/math/linalg/eigen/matrix_eigenvalues_in_place.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix_eigenvalues_in_place.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/eigen/matrix_eigenvalues_in_place.js"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,6EASC"}

package/src/core/{graph → math/linalg}/eigen/matrix_eigenvalues_in_place.js

@@ -3,19 +3,20 @@ import { matrix_qr_in_place } from "./matrix_qr_in_place.js";
 
 
 /**
- * list of eigen values square matrix (allow non symmetric)
+ * list of eigen values square matrix (allow non-symmetric)
  * NOTE: Modifies input matrix
+ * @template T extends ArrayLike<number>
+ * @param {T} out
  * @param {SquareMatrix} mat
- * @return {number[]}
+ * @return {T}
  */
-export function matrix_eigenvalues_in_place(mat) {
+export function matrix_eigenvalues_in_place(out, mat) {
     const n = mat.size;
+
     matrix_householder_in_place(mat.data, n);
     matrix_qr_in_place(mat.data, n);
 
-    const result = new Float32Array(n);
-
-    mat.readDiagonal(result);
+    mat.readDiagonal(out);
 
-    return result;
+    return out;
 }

package/src/core/math/linalg/eigen/matrix_householder_in_place.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix_householder_in_place.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/eigen/matrix_householder_in_place.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,+CAHW,MAAM,EAAE,KACR,MAAM,QA0FhB"}

package/src/core/{graph → math/linalg}/eigen/matrix_householder_in_place.js

@@ -32,14 +32,20 @@ export function matrix_householder_in_place(a, n) {
             sum = sum + u[i] * u[i];
         }
 
-        const u_k_1 = u[k + 1];
-
-        const u_k_1_abs = Math.abs(u_k_1);
-        if (u_k_1_abs < EPSILON) {
+        if (sum < EPSILON * EPSILON) {
+            // sub-column already zero — nothing to reduce at this k
             continue;
         }
 
-        const sigma = Math.sqrt(sum) * u_k_1 / u_k_1_abs;
+        const u_k_1 = u[k + 1];
+        const u_k_1_abs = Math.abs(u_k_1);
+
+        // sigma = sign(u[k+1]) · ‖u‖. When u[k+1] = 0 the sign is arbitrary
+        // (entries below are still nonzero by the `sum` check above), so pick
+        // +‖u‖.
+        const sigma = u_k_1_abs < EPSILON
+            ? Math.sqrt(sum)
+            : Math.sqrt(sum) * u_k_1 / u_k_1_abs;
 
         u[k + 1] += sigma;
 

package/src/core/math/linalg/eigen/matrix_qr_in_place.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Perform QR factorization in-place.
+ * Subfunction that analyzes eigenvalues by QR decomposition.
+ *
+ * Single-shift Wilkinson iteration: deflates the trailing subdiagonal one row
+ * at a time as it converges. A complex eigenvalue pair leaves a 2×2 trailing
+ * block whose inner subdiagonal does not vanish, and this routine will spin
+ * on it indefinitely — only safe today for matrices with all-real eigenvalues.
+ *
+ * @see http://www-in.aut.ac.jp/~minemura/pub/Csimu/C/QRmethod.html
+ * @param {number[]} a Square matrix
+ * @param {number} n size of the matrix in single dimension
+ */
+export function matrix_qr_in_place(a: number[], n: number): void;
+//# sourceMappingURL=matrix_qr_in_place.d.ts.map

package/src/core/math/linalg/eigen/matrix_qr_in_place.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix_qr_in_place.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/eigen/matrix_qr_in_place.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,sCAHW,MAAM,EAAE,KACR,MAAM,QA8GhB"}

package/src/core/{graph → math/linalg}/eigen/matrix_qr_in_place.js

@@ -1,8 +1,14 @@
 const EPSILON = 1e-10;
 
 /**
- * Perform QR factorization in-place
- * Subfunction that analyzes eigenvalues by QR decomposition
+ * Perform QR factorization in-place.
+ * Subfunction that analyzes eigenvalues by QR decomposition.
+ *
+ * Single-shift Wilkinson iteration: deflates the trailing subdiagonal one row
+ * at a time as it converges. A complex eigenvalue pair leaves a 2×2 trailing
+ * block whose inner subdiagonal does not vanish, and this routine will spin
+ * on it indefinitely — only safe today for matrices with all-real eigenvalues.
+ *
  * @see http://www-in.aut.ac.jp/~minemura/pub/Csimu/C/QRmethod.html
  * @param {number[]} a Square matrix
  * @param {number} n size of the matrix in single dimension

package/src/core/{graph → math/linalg}/eigen/matrix_top_eigenvector_power_iteration.d.ts

@@ -7,9 +7,6 @@
  * 3x3 covariance, etc.). Unsuitable when the top two eigenvalues have nearly
  * equal magnitude — convergence stalls in that regime.
  *
- * NOTE: intended to live in @woosh/meep-engine under core/graph/eigen/. Kept
- * local for now.
- *
  * @param {SquareMatrix} matrix Symmetric, column-major as per SquareMatrix
  * @param {number[]|Float32Array|Float64Array} out Eigenvector is written here, length >= matrix.size
  * @param {number} [max_iterations=64]

package/src/core/math/linalg/eigen/matrix_top_eigenvector_power_iteration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix_top_eigenvector_power_iteration.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/eigen/matrix_top_eigenvector_power_iteration.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;GAcG;AACH,kFALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,mBAClC,MAAM,cACN,MAAM,GACJ,MAAM,CAoFlB"}

package/src/core/{graph → math/linalg}/eigen/matrix_top_eigenvector_power_iteration.js

@@ -16,9 +16,6 @@ function ensure_scratch(n) {
  * 3x3 covariance, etc.). Unsuitable when the top two eigenvalues have nearly
  * equal magnitude — convergence stalls in that regime.
  *
- * NOTE: intended to live in @woosh/meep-engine under core/graph/eigen/. Kept
- * local for now.
- *
  * @param {SquareMatrix} matrix Symmetric, column-major as per SquareMatrix
  * @param {number[]|Float32Array|Float64Array} out Eigenvector is written here, length >= matrix.size
  * @param {number} [max_iterations=64]

package/src/core/math/linalg/polynomial_complex_roots_aberth_ehrlich.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Find all complex roots of a univariate polynomial via Aberth–Ehrlich.
+ *
+ * The polynomial is given in ascending-power coefficient form:
+ *   p(x) = coeffs[0] + coeffs[1]·x + … + coeffs[degree]·x^degree
+ * The leading coefficient `coeffs[degree]` must be nonzero.
+ *
+ * Exactly `degree` complex numbers are written into `roots_re`/`roots_im` at
+ * index `offset`, `offset + 1`, …, `offset + degree - 1`. The order they
+ * appear in is not specified.
+ *
+ * @param {Float64Array|number[]} coeffs ascending-power, length ≥ degree + 1
+ * @param {number} degree polynomial degree, ≥ 1, ≤ 64
+ * @param {Float64Array|number[]} roots_re real parts, length ≥ offset + degree
+ * @param {Float64Array|number[]} roots_im imaginary parts, length ≥ offset + degree
+ * @param {number} offset
+ */
+export function polynomial_complex_roots_aberth_ehrlich(coeffs: Float64Array | number[], degree: number, roots_re: Float64Array | number[], roots_im: Float64Array | number[], offset: number): void;
+//# sourceMappingURL=polynomial_complex_roots_aberth_ehrlich.d.ts.map

package/src/core/math/linalg/polynomial_complex_roots_aberth_ehrlich.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polynomial_complex_roots_aberth_ehrlich.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/linalg/polynomial_complex_roots_aberth_ehrlich.js"],"names":[],"mappings":"AA6DA;;;;;;;;;;;;;;;;GAgBG;AACH,gEANW,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,YACN,YAAY,GAAC,MAAM,EAAE,YACrB,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,QAoFhB"}

package/src/core/math/linalg/polynomial_complex_roots_aberth_ehrlich.js

@@ -0,0 +1,161 @@
+import { assert } from "../../assert.js";
+
+/*
+ Find all roots of a univariate polynomial in the complex plane via
+ Aberth–Ehrlich simultaneous iteration. Real and complex roots are isolated
+ together; the caller separates real ones by inspecting the imaginary parts.
+
+ Reference: Aberth (1973), "Iteration methods for finding all zeros of a
+ polynomial simultaneously", Math. Comp. 27.
+
+ The iteration is
+
+   z_k ← z_k − w_k / (1 − w_k · Σ_{j≠k} 1/(z_k − z_j))
+
+ with w_k = p(z_k) / p'(z_k). Initial points are placed on a circle of radius
+ = Cauchy bound, with a fixed phase offset so an initial guess never lands
+ exactly on a real root (which would make the pairwise sum singular at step
+ zero). Convergence is quadratic once close.
+*/
+
+const MAX_SUPPORTED_DEGREE = 64;
+
+const ABERTH_MAX_ITERATIONS = 80;
+const ABERTH_CONVERGENCE_TOLERANCE = 1e-14;
+
+const _DERIV = new Float64Array(MAX_SUPPORTED_DEGREE);
+const _P_EVAL = new Float64Array(2);
+const _DP_EVAL = new Float64Array(2);
+
+/**
+ * Horner evaluation of polynomial p(z) at a complex z = (zr, zi).
+ * Writes [p(z).re, p(z).im] into `out`.
+ */
+function poly_eval_complex(coeffs, degree, zr, zi, out) {
+    let pr = coeffs[degree];
+    let pi = 0;
+
+    for (let i = degree - 1; i >= 0; i--) {
+        const new_pr = pr * zr - pi * zi + coeffs[i];
+        const new_pi = pr * zi + pi * zr;
+        pr = new_pr;
+        pi = new_pi;
+    }
+
+    out[0] = pr;
+    out[1] = pi;
+}
+
+/**
+ * Cauchy bound: every root z of `coeffs` satisfies |z| ≤ this value.
+ */
+function cauchy_root_magnitude_bound(coeffs, degree) {
+    const lead = Math.abs(coeffs[degree]);
+    let m = 0;
+    for (let i = 0; i < degree; i++) {
+        const a = Math.abs(coeffs[i]);
+        if (a > m) m = a;
+    }
+    return 1 + m / lead;
+}
+
+/**
+ * Find all complex roots of a univariate polynomial via Aberth–Ehrlich.
+ *
+ * The polynomial is given in ascending-power coefficient form:
+ *   p(x) = coeffs[0] + coeffs[1]·x + … + coeffs[degree]·x^degree
+ * The leading coefficient `coeffs[degree]` must be nonzero.
+ *
+ * Exactly `degree` complex numbers are written into `roots_re`/`roots_im` at
+ * index `offset`, `offset + 1`, …, `offset + degree - 1`. The order they
+ * appear in is not specified.
+ *
+ * @param {Float64Array|number[]} coeffs ascending-power, length ≥ degree + 1
+ * @param {number} degree polynomial degree, ≥ 1, ≤ 64
+ * @param {Float64Array|number[]} roots_re real parts, length ≥ offset + degree
+ * @param {Float64Array|number[]} roots_im imaginary parts, length ≥ offset + degree
+ * @param {number} offset
+ */
+export function polynomial_complex_roots_aberth_ehrlich(
+    coeffs, degree,
+    roots_re, roots_im, offset
+) {
+    assert.greaterThanOrEqual(degree, 1, 'degree');
+    assert.greaterThanOrEqual(MAX_SUPPORTED_DEGREE, degree, 'degree exceeds MAX_SUPPORTED_DEGREE');
+    assert.isNonNegativeInteger(offset, 'offset');
+
+    // derivative: _DERIV[i] = (i + 1) * coeffs[i + 1], i = 0 .. degree - 1
+    for (let i = 0; i < degree; i++) {
+        _DERIV[i] = (i + 1) * coeffs[i + 1];
+    }
+
+    const radius = cauchy_root_magnitude_bound(coeffs, degree);
+
+    // Initial points around a circle, with a small phase offset to avoid
+    // landing exactly on a real root at iteration zero.
+    const phase_offset = 0.5;
+    const two_pi_over_n = (2 * Math.PI) / degree;
+    for (let k = 0; k < degree; k++) {
+        const angle = k * two_pi_over_n + phase_offset;
+        roots_re[offset + k] = radius * Math.cos(angle);
+        roots_im[offset + k] = radius * Math.sin(angle);
+    }
+
+    for (let iter = 0; iter < ABERTH_MAX_ITERATIONS; iter++) {
+        let max_correction_sq = 0;
+
+        for (let k = 0; k < degree; k++) {
+            const zr = roots_re[offset + k];
+            const zi = roots_im[offset + k];
+
+            poly_eval_complex(coeffs, degree, zr, zi, _P_EVAL);
+            const pr = _P_EVAL[0];
+            const pi = _P_EVAL[1];
+
+            poly_eval_complex(_DERIV, degree - 1, zr, zi, _DP_EVAL);
+            const dpr = _DP_EVAL[0];
+            const dpi = _DP_EVAL[1];
+
+            // w = p / p'
+            const dp_norm_sq = dpr * dpr + dpi * dpi;
+            if (dp_norm_sq === 0) continue;
+            const inv_dp_sq = 1 / dp_norm_sq;
+            const wr = (pr * dpr + pi * dpi) * inv_dp_sq;
+            const wi = (pi * dpr - pr * dpi) * inv_dp_sq;
+
+            // S = Σ_{j≠k} 1/(z_k − z_j) in complex
+            let sr = 0, si = 0;
+            for (let j = 0; j < degree; j++) {
+                if (j === k) continue;
+                const dr = zr - roots_re[offset + j];
+                const di = zi - roots_im[offset + j];
+                const denom_sq = dr * dr + di * di;
+                if (denom_sq === 0) continue;
+                const inv_d_sq = 1 / denom_sq;
+                sr += dr * inv_d_sq;
+                si += -di * inv_d_sq;
+            }
+
+            // correction = w / (1 − w·S)
+            const ws_r = wr * sr - wi * si;
+            const ws_i = wr * si + wi * sr;
+            const denom_r = 1 - ws_r;
+            const denom_i = -ws_i;
+            const denom_sq2 = denom_r * denom_r + denom_i * denom_i;
+            if (denom_sq2 === 0) continue;
+            const inv_denom_sq2 = 1 / denom_sq2;
+            const corr_r = (wr * denom_r + wi * denom_i) * inv_denom_sq2;
+            const corr_i = (wi * denom_r - wr * denom_i) * inv_denom_sq2;
+
+            roots_re[offset + k] = zr - corr_r;
+            roots_im[offset + k] = zi - corr_i;
+
+            const corr_sq = corr_r * corr_r + corr_i * corr_i;
+            if (corr_sq > max_correction_sq) max_correction_sq = corr_sq;
+        }
+
+        if (max_correction_sq < ABERTH_CONVERGENCE_TOLERANCE * ABERTH_CONVERGENCE_TOLERANCE) {
+            break;
+        }
+    }
+}

package/src/core/math/linalg/polynomial_real_roots_in_interval.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Find all real roots of a univariate polynomial that lie inside the closed
+ * interval [lo, hi]. Roots are written to `out[out_offset ..]` in ascending
+ * order; the count of roots written is returned.
+ *
+ * @param {Float64Array|number[]} coeffs ascending power order: coeffs[i] is the coefficient of x^i
+ * @param {number} degree polynomial degree (coeffs must have at least `degree + 1` entries)
+ * @param {number} lo
+ * @param {number} hi
+ * @param {Float64Array|number[]} out
+ * @param {number} out_offset
+ * @returns {number} number of roots written
+ */
+export function polynomial_real_roots_in_interval(coeffs: Float64Array | number[], degree: number, lo: number, hi: number, out: Float64Array | number[], out_offset: number): number;
+//# sourceMappingURL=polynomial_real_roots_in_interval.d.ts.map

package/src/core/math/linalg/polynomial_real_roots_in_interval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polynomial_real_roots_in_interval.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/linalg/polynomial_real_roots_in_interval.js"],"names":[],"mappings":"AAsGA;;;;;;;;;;;;GAYG;AACH,0DARW,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,MACN,MAAM,MACN,MAAM,OACN,YAAY,GAAC,MAAM,EAAE,cACrB,MAAM,GACJ,MAAM,CAsFlB"}

package/src/core/math/linalg/polynomial_real_roots_in_interval.js

@@ -0,0 +1,200 @@
+import { assert } from "../../assert.js";
+import { solveQuadratic } from "../solveQuadratic.js";
+import { polynomial_complex_roots_aberth_ehrlich } from "./polynomial_complex_roots_aberth_ehrlich.js";
+
+/*
+ Find all real roots of a univariate polynomial that lie inside a closed interval [lo, hi].
+ Coefficient layout: coeffs[i] is the coefficient of x^i, so
+
+   p(x) = coeffs[0] + coeffs[1]*x + coeffs[2]*x^2 + ... + coeffs[degree]*x^degree
+
+ Approach:
+   1. Trim leading zeros (treat the polynomial at its effective degree).
+   2. Closed-form for degrees 1 and 2.
+   3. For degree ≥ 3, isolate all complex roots via
+      polynomial_complex_roots_aberth_ehrlich, then keep the ones whose
+      imaginary part is below a scale-relative threshold and whose real part
+      lies in [lo, hi]. Each survivor is Newton-polished against the real
+      polynomial as a sanity / precision pass.
+*/
+
+const MAX_SUPPORTED_DEGREE = 64;
+
+const SCRATCH_COEFF = new Float64Array(MAX_SUPPORTED_DEGREE + 1);
+const SCRATCH_ROOTS_RE = new Float64Array(MAX_SUPPORTED_DEGREE);
+const SCRATCH_ROOTS_IM = new Float64Array(MAX_SUPPORTED_DEGREE);
+const SCRATCH_OUT_REAL = new Float64Array(MAX_SUPPORTED_DEGREE);
+const SCRATCH_QUADRATIC = new Float64Array(2);
+const SCRATCH_EVAL = new Float64Array(2);
+
+const NEWTON_MAX_ITERATIONS = 32;
+
+// Imaginary part below this fraction of root scale is treated as real.
+const IMAG_PART_REAL_THRESHOLD = 1e-8;
+
+const NEWTON_RELATIVE_RESIDUAL_TOLERANCE = 1e-10;
+
+const DEDUPE_RELATIVE_TOLERANCE = 1e-7;
+
+function poly_eval_with_derivative(coeffs, degree, x, out) {
+    let p = coeffs[degree];
+    let dp = 0;
+
+    for (let i = degree - 1; i >= 0; i--) {
+        dp = dp * x + p;
+        p = p * x + coeffs[i];
+    }
+
+    out[0] = p;
+    out[1] = dp;
+}
+
+function max_abs_coefficient(coeffs, degree) {
+    let m = 0;
+    for (let i = 0; i <= degree; i++) {
+        const a = Math.abs(coeffs[i]);
+        if (a > m) m = a;
+    }
+    return m;
+}
+
+function root_scale_estimate(coeffs, degree) {
+    const lead = Math.abs(coeffs[degree]);
+    let m = 0;
+    for (let i = 0; i < degree; i++) {
+        const a = Math.abs(coeffs[i]);
+        if (a > m) m = a;
+    }
+    return 1 + m / lead;
+}
+
+function newton_polish_real(coeffs, degree, x_init) {
+    let x = x_init;
+
+    for (let i = 0; i < NEWTON_MAX_ITERATIONS; i++) {
+        poly_eval_with_derivative(coeffs, degree, x, SCRATCH_EVAL);
+
+        const p = SCRATCH_EVAL[0];
+        const dp = SCRATCH_EVAL[1];
+
+        if (dp === 0) break;
+
+        const step = p / dp;
+        x -= step;
+
+        if (Math.abs(step) <= Math.abs(x) * 1e-15) break;
+    }
+
+    return x;
+}
+
+function insert_sorted_unique(roots, count, value, dedupe_tolerance) {
+    let i = 0;
+    while (i < count && roots[i] < value) i++;
+
+    if (i > 0 && Math.abs(roots[i - 1] - value) <= dedupe_tolerance) return count;
+    if (i < count && Math.abs(roots[i] - value) <= dedupe_tolerance) return count;
+
+    for (let j = count; j > i; j--) roots[j] = roots[j - 1];
+    roots[i] = value;
+    return count + 1;
+}
+
+/**
+ * Find all real roots of a univariate polynomial that lie inside the closed
+ * interval [lo, hi]. Roots are written to `out[out_offset ..]` in ascending
+ * order; the count of roots written is returned.
+ *
+ * @param {Float64Array|number[]} coeffs ascending power order: coeffs[i] is the coefficient of x^i
+ * @param {number} degree polynomial degree (coeffs must have at least `degree + 1` entries)
+ * @param {number} lo
+ * @param {number} hi
+ * @param {Float64Array|number[]} out
+ * @param {number} out_offset
+ * @returns {number} number of roots written
+ */
+export function polynomial_real_roots_in_interval(
+    coeffs,
+    degree,
+    lo, hi,
+    out, out_offset
+) {
+    assert.isNonNegativeInteger(degree, 'degree');
+    assert.isNonNegativeInteger(out_offset, 'out_offset');
+    assert.greaterThanOrEqual(MAX_SUPPORTED_DEGREE, degree, 'degree exceeds MAX_SUPPORTED_DEGREE');
+
+    if (degree === 0) return 0;
+
+    const coeff_norm = max_abs_coefficient(coeffs, degree);
+    if (coeff_norm === 0) return 0;
+
+    let effective_degree = degree;
+    const leading_zero_threshold = coeff_norm * 1e-14;
+    while (effective_degree > 0 && Math.abs(coeffs[effective_degree]) <= leading_zero_threshold) {
+        effective_degree--;
+    }
+    if (effective_degree === 0) return 0;
+
+    if (effective_degree === 1) {
+        const root = -coeffs[0] / coeffs[1];
+        if (root >= lo && root <= hi) {
+            out[out_offset] = root;
+            return 1;
+        }
+        return 0;
+    }
+
+    if (effective_degree === 2) {
+        const root_count = solveQuadratic(SCRATCH_QUADRATIC, 0, coeffs[2], coeffs[1], coeffs[0]);
+        let written = 0;
+        for (let i = 0; i < root_count; i++) {
+            const r = SCRATCH_QUADRATIC[i];
+            if (r >= lo && r <= hi) {
+                if (written === 0 || Math.abs(out[out_offset + written - 1] - r) > 0) {
+                    out[out_offset + written] = r;
+                    written++;
+                }
+            }
+        }
+        return written;
+    }
+
+    for (let i = 0; i <= effective_degree; i++) SCRATCH_COEFF[i] = coeffs[i];
+
+    polynomial_complex_roots_aberth_ehrlich(
+        SCRATCH_COEFF, effective_degree,
+        SCRATCH_ROOTS_RE, SCRATCH_ROOTS_IM, 0
+    );
+
+    const root_scale = root_scale_estimate(SCRATCH_COEFF, effective_degree);
+    const imag_threshold = IMAG_PART_REAL_THRESHOLD * Math.max(1, root_scale);
+    const residual_tolerance = NEWTON_RELATIVE_RESIDUAL_TOLERANCE * coeff_norm;
+    const dedupe_tolerance = DEDUPE_RELATIVE_TOLERANCE * Math.max(1, Math.max(Math.abs(lo), Math.abs(hi)));
+
+    let unique_count = 0;
+
+    for (let i = 0; i < effective_degree; i++) {
+        const re = SCRATCH_ROOTS_RE[i];
+        const im = SCRATCH_ROOTS_IM[i];
+
+        if (!Number.isFinite(re) || !Number.isFinite(im)) continue;
+
+        if (Math.abs(im) > imag_threshold) continue;
+
+        const polished = newton_polish_real(SCRATCH_COEFF, effective_degree, re);
+        if (!Number.isFinite(polished)) continue;
+
+        poly_eval_with_derivative(SCRATCH_COEFF, effective_degree, polished, SCRATCH_EVAL);
+        if (Math.abs(SCRATCH_EVAL[0]) > residual_tolerance) continue;
+
+        if (polished < lo || polished > hi) continue;
+
+        unique_count = insert_sorted_unique(SCRATCH_OUT_REAL, unique_count, polished, dedupe_tolerance);
+    }
+
+    for (let i = 0; i < unique_count; i++) {
+        out[out_offset + i] = SCRATCH_OUT_REAL[i];
+    }
+
+    return unique_count;
+}

package/src/core/math/solveCubic.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Return real solutions for a cubic polynomial: ax³ + bx² + cx + d
+ * Repeated roots are written once each — multiplicity is not duplicated in the output.
+ * Imaginary roots are not provided.
+ *
+ * @param {number[]|Float32Array|Float64Array} result solutions are written here
+ * @param {number} result_offset offset into result array where solutions are written to
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @param {number} d
+ * @returns {number} number of real roots found (0, 1, 2, or 3)
+ */
+export function solveCubic(result: number[] | Float32Array | Float64Array, result_offset: number, a: number, b: number, c: number, d: number): number;
+//# sourceMappingURL=solveCubic.d.ts.map

package/src/core/math/solveCubic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solveCubic.d.ts","sourceRoot":"","sources":["../../../../src/core/math/solveCubic.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;GAYG;AACH,mCARW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CA+DlB"}