@johnhenry/math 0.0.0

package/dist/NumberTheory.d.ts

@@ -0,0 +1,49 @@
+/**
+ * NumberTheory — fast, big-integer number theory: modular exponentiation and
+ * inverse, the Chinese Remainder Theorem, Miller-Rabin primality, Pollard-rho
+ * factorisation, GCD/LCM, and the Legendre/Jacobi symbols. Everything is
+ * `bigint`-based, so it does not overflow for large inputs.
+ */
+export declare class NumberTheory {
+    /** `base^exp mod modulus`, computed by square-and-multiply. */
+    static modPow(base: bigint | number, exp: bigint | number, modulus: bigint | number): bigint;
+    /** Extended Euclid: returns `{ g, x, y }` with `a·x + b·y = g = gcd(a, b)`. */
+    static extendedGcd(a: bigint | number, b: bigint | number): {
+        g: bigint;
+        x: bigint;
+        y: bigint;
+    };
+    /** Modular inverse of `a` mod `m`, or `null` when `gcd(a, m) ≠ 1`. */
+    static modInverse(a: bigint | number, m: bigint | number): bigint | null;
+    /** Euclidean remainder, always in `[0, m)` for `m > 0`. Throws for `m === 0`. */
+    static mod(a: bigint | number, m: bigint | number): bigint;
+    /** `gcd(a, b)` (non-negative, `gcd(0, 0) === 0`). */
+    static gcd(a: bigint | number, b: bigint | number): bigint;
+    /** `lcm(a, b) = |a·b| / gcd(a, b)`, or `0` if either operand is `0`. */
+    static lcm(a: bigint | number, b: bigint | number): bigint;
+    /** LCM of a list of values (`1` for an empty list). */
+    static lcmList(values: Array<bigint | number>): bigint;
+    /**
+     * Solve a system of congruences `x ≡ remainders[i] (mod moduli[i])` for
+     * pairwise-coprime moduli. Returns `{ x, modulus }` or `null` if inconsistent.
+     */
+    static crt(remainders: Array<bigint | number>, moduli: Array<bigint | number>): {
+        x: bigint;
+        modulus: bigint;
+    } | null;
+    /** Miller-Rabin primality test (deterministic for n < 3.3·10²⁴). */
+    static isProbablePrime(n: bigint | number): boolean;
+    /** The next prime strictly greater than `n`. */
+    static nextPrime(n: bigint | number): bigint;
+    /** A single non-trivial factor of composite `n` via Pollard's rho (Brent). */
+    static pollardRho(n: bigint | number): bigint;
+    /** Full prime factorisation as sorted `[prime, exponent]` pairs. */
+    static factorize(n: bigint | number): Array<[bigint, number]>;
+    /** Euler's totient φ(n) via factorisation (big-integer safe). */
+    static eulerPhi(n: bigint | number): bigint;
+    /** The Legendre symbol `(a/p)` for an odd prime `p` (−1, 0, or 1). */
+    static legendreSymbol(a: bigint | number, p: bigint | number): number;
+    /** The Jacobi symbol `(a/n)` for odd `n > 0` (−1, 0, or 1). */
+    static jacobiSymbol(a: bigint | number, n: bigint | number): number;
+}
+//# sourceMappingURL=NumberTheory.d.ts.map

package/dist/NumberTheory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NumberTheory.d.ts","sourceRoot":"","sources":["../src/NumberTheory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH,qBAAa,YAAY;IACvB,+DAA+D;IAC/D,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAc5F,+EAA+E;IAC/E,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAgB/F,sEAAsE;IACtE,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI;IAOxE,iFAAiF;IACjF,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAM1D,qDAAqD;IACrD,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAI1D,wEAAwE;IACxE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAO1D,uDAAuD;IACvD,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM;IAItD;;;OAGG;IACH,MAAM,CAAC,GAAG,CACR,UAAU,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,EAClC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAC7B;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAgBxC,oEAAoE;IACpE,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO;IA0BnD,gDAAgD;IAChD,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAM5C,8EAA8E;IAC9E,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAqB7C,oEAAoE;IACpE,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IA8B7D,iEAAiE;IACjE,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAM3C,sEAAsE;IACtE,MAAM,CAAC,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAMrE,+DAA+D;IAC/D,MAAM,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;CAgBpE"}

package/dist/NumberTheory.js

@@ -0,0 +1,230 @@
+/**
+ * NumberTheory — fast, big-integer number theory: modular exponentiation and
+ * inverse, the Chinese Remainder Theorem, Miller-Rabin primality, Pollard-rho
+ * factorisation, GCD/LCM, and the Legendre/Jacobi symbols. Everything is
+ * `bigint`-based, so it does not overflow for large inputs.
+ */
+const big = (x) => (typeof x === "bigint" ? x : BigInt(x));
+const babs = (x) => (x < 0n ? -x : x);
+function bgcd(a, b) {
+    let x = babs(a);
+    let y = babs(b);
+    while (y)
+        [x, y] = [y, x % y];
+    return x;
+}
+// Deterministic Miller-Rabin witnesses (valid for all n < 3.3·10^24).
+const MR_WITNESSES = [2n, 3n, 5n, 7n, 11n, 13n, 17n, 19n, 23n, 29n, 31n, 37n];
+export class NumberTheory {
+    /** `base^exp mod modulus`, computed by square-and-multiply. */
+    static modPow(base, exp, modulus) {
+        const m = big(modulus);
+        if (m === 1n)
+            return 0n;
+        let b = ((big(base) % m) + m) % m;
+        let e = big(exp);
+        let result = 1n;
+        while (e > 0n) {
+            if (e & 1n)
+                result = (result * b) % m;
+            b = (b * b) % m;
+            e >>= 1n;
+        }
+        return result;
+    }
+    /** Extended Euclid: returns `{ g, x, y }` with `a·x + b·y = g = gcd(a, b)`. */
+    static extendedGcd(a, b) {
+        let [oldR, r] = [big(a), big(b)];
+        let [oldS, s] = [1n, 0n];
+        let [oldT, t] = [0n, 1n];
+        while (r !== 0n) {
+            const q = oldR / r;
+            [oldR, r] = [r, oldR - q * r];
+            [oldS, s] = [s, oldS - q * s];
+            [oldT, t] = [t, oldT - q * t];
+        }
+        // Negative inputs can leave oldR negative even though a*x + b*y = oldR still
+        // holds; flip all three signs so g matches gcd()'s non-negative convention.
+        if (oldR < 0n)
+            return { g: -oldR, x: -oldS, y: -oldT };
+        return { g: oldR, x: oldS, y: oldT };
+    }
+    /** Modular inverse of `a` mod `m`, or `null` when `gcd(a, m) ≠ 1`. */
+    static modInverse(a, m) {
+        const mod = big(m);
+        const { g, x } = NumberTheory.extendedGcd(((big(a) % mod) + mod) % mod, mod);
+        if (g !== 1n)
+            return null;
+        return ((x % mod) + mod) % mod;
+    }
+    /** Euclidean remainder, always in `[0, m)` for `m > 0`. Throws for `m === 0`. */
+    static mod(a, m) {
+        const modulus = big(m);
+        if (modulus === 0n)
+            throw new RangeError("NumberTheory.mod: modulus must be non-zero");
+        return ((big(a) % modulus) + modulus) % modulus;
+    }
+    /** `gcd(a, b)` (non-negative, `gcd(0, 0) === 0`). */
+    static gcd(a, b) {
+        return bgcd(big(a), big(b));
+    }
+    /** `lcm(a, b) = |a·b| / gcd(a, b)`, or `0` if either operand is `0`. */
+    static lcm(a, b) {
+        const A = big(a);
+        const B = big(b);
+        if (A === 0n || B === 0n)
+            return 0n;
+        return babs(A * B) / bgcd(A, B);
+    }
+    /** LCM of a list of values (`1` for an empty list). */
+    static lcmList(values) {
+        return values.reduce((acc, v) => NumberTheory.lcm(acc, big(v)), 1n);
+    }
+    /**
+     * Solve a system of congruences `x ≡ remainders[i] (mod moduli[i])` for
+     * pairwise-coprime moduli. Returns `{ x, modulus }` or `null` if inconsistent.
+     */
+    static crt(remainders, moduli) {
+        let x = 0n;
+        let mod = 1n;
+        for (let i = 0; i < remainders.length; i++) {
+            const ri = ((big(remainders[i]) % big(moduli[i])) + big(moduli[i])) % big(moduli[i]);
+            const mi = big(moduli[i]);
+            const inv = NumberTheory.modInverse(mod, mi);
+            if (inv === null)
+                return null;
+            const diff = ((((ri - x) * inv) % mi) + mi) % mi;
+            x += mod * diff;
+            mod *= mi;
+            x = ((x % mod) + mod) % mod;
+        }
+        return { x, modulus: mod };
+    }
+    /** Miller-Rabin primality test (deterministic for n < 3.3·10²⁴). */
+    static isProbablePrime(n) {
+        const num = big(n);
+        if (num < 2n)
+            return false;
+        for (const p of [2n, 3n, 5n, 7n, 11n, 13n, 17n, 19n, 23n, 29n, 31n, 37n]) {
+            if (num === p)
+                return true;
+            if (num % p === 0n)
+                return false;
+        }
+        let d = num - 1n;
+        let r = 0n;
+        while ((d & 1n) === 0n) {
+            d >>= 1n;
+            r++;
+        }
+        witness: for (const a of MR_WITNESSES) {
+            if (a >= num)
+                continue;
+            let x = NumberTheory.modPow(a, d, num);
+            if (x === 1n || x === num - 1n)
+                continue;
+            for (let i = 0n; i < r - 1n; i++) {
+                x = (x * x) % num;
+                if (x === num - 1n)
+                    continue witness;
+            }
+            return false;
+        }
+        return true;
+    }
+    /** The next prime strictly greater than `n`. */
+    static nextPrime(n) {
+        let candidate = big(n) + 1n;
+        while (!NumberTheory.isProbablePrime(candidate))
+            candidate++;
+        return candidate;
+    }
+    /** A single non-trivial factor of composite `n` via Pollard's rho (Brent). */
+    static pollardRho(n) {
+        const num = big(n);
+        // n <= 1 has no non-trivial factor to find: `f(v) = (v*v+c) % 1n` collapses
+        // to 0 for every c, so `d = gcd(0, 1) = 1n` forever and the loop below never
+        // terminates. Reject degenerate inputs up front instead of hanging.
+        if (num <= 1n)
+            throw new RangeError("NumberTheory.pollardRho: n must be greater than 1");
+        if (num % 2n === 0n)
+            return 2n;
+        for (let c = 1n;; c++) {
+            let x = 2n;
+            let y = 2n;
+            let d = 1n;
+            const f = (v) => (v * v + c) % num;
+            while (d === 1n) {
+                x = f(x);
+                y = f(f(y));
+                d = bgcd(babs(x - y), num);
+            }
+            if (d !== num)
+                return d;
+        }
+    }
+    /** Full prime factorisation as sorted `[prime, exponent]` pairs. */
+    static factorize(n) {
+        let num = babs(big(n));
+        // 0 has no well-defined prime factorization (every prime divides it, with
+        // no finite exponent) -- unlike 1, whose factorization is the empty
+        // product. Without this guard `0n % p === 0n` and `0n / p === 0n` forever,
+        // so the trial-division loop below never terminates.
+        if (num === 0n)
+            throw new RangeError("NumberTheory.factorize: n must be non-zero");
+        const counts = new Map();
+        const add = (p) => counts.set(p, (counts.get(p) ?? 0) + 1);
+        for (const p of [2n, 3n, 5n, 7n, 11n, 13n]) {
+            while (num % p === 0n) {
+                add(p);
+                num /= p;
+            }
+        }
+        const stack = num > 1n ? [num] : [];
+        while (stack.length) {
+            const m = stack.pop();
+            if (m === 1n)
+                continue;
+            if (NumberTheory.isProbablePrime(m)) {
+                add(m);
+                continue;
+            }
+            const factor = NumberTheory.pollardRho(m);
+            stack.push(factor, m / factor);
+        }
+        return [...counts.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    }
+    /** Euler's totient φ(n) via factorisation (big-integer safe). */
+    static eulerPhi(n) {
+        let result = babs(big(n));
+        for (const [p] of NumberTheory.factorize(n))
+            result = (result / p) * (p - 1n);
+        return result;
+    }
+    /** The Legendre symbol `(a/p)` for an odd prime `p` (−1, 0, or 1). */
+    static legendreSymbol(a, p) {
+        const P = big(p);
+        const ls = NumberTheory.modPow(a, (P - 1n) / 2n, P);
+        return ls === P - 1n ? -1 : Number(ls);
+    }
+    /** The Jacobi symbol `(a/n)` for odd `n > 0` (−1, 0, or 1). */
+    static jacobiSymbol(a, n) {
+        let A = ((big(a) % big(n)) + big(n)) % big(n);
+        let N = big(n);
+        let result = 1;
+        while (A !== 0n) {
+            while (A % 2n === 0n) {
+                A /= 2n;
+                const r = N % 8n;
+                if (r === 3n || r === 5n)
+                    result = -result;
+            }
+            [A, N] = [N, A];
+            if (A % 4n === 3n && N % 4n === 3n)
+                result = -result;
+            A %= N;
+        }
+        return N === 1n ? result : 0;
+    }
+}
+//# sourceMappingURL=NumberTheory.js.map

package/dist/NumberTheory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NumberTheory.js","sourceRoot":"","sources":["../src/NumberTheory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,GAAG,GAAG,CAAC,CAAkB,EAAU,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AACpF,MAAM,IAAI,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEtD,SAAS,IAAI,CAAC,CAAS,EAAE,CAAS;IAChC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAChB,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAChB,OAAO,CAAC;QAAE,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,OAAO,CAAC,CAAC;AACX,CAAC;AAED,sEAAsE;AACtE,MAAM,YAAY,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAE9E,MAAM,OAAO,YAAY;IACvB,+DAA+D;IAC/D,MAAM,CAAC,MAAM,CAAC,IAAqB,EAAE,GAAoB,EAAE,OAAwB;QACjF,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACjB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;YACd,IAAI,CAAC,GAAG,EAAE;gBAAE,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YACtC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YAChB,CAAC,KAAK,EAAE,CAAC;QACX,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,+EAA+E;IAC/E,MAAM,CAAC,WAAW,CAAC,CAAkB,EAAE,CAAkB;QACvD,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACzB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;YAChB,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;YACnB,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9B,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9B,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QAChC,CAAC;QACD,6EAA6E;QAC7E,4EAA4E;QAC5E,IAAI,IAAI,GAAG,EAAE;YAAE,OAAO,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QACvD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;IACvC,CAAC;IAED,sEAAsE;IACtE,MAAM,CAAC,UAAU,CAAC,CAAkB,EAAE,CAAkB;QACtD,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACnB,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC;QAC7E,IAAI,CAAC,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC;QAC1B,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;IACjC,CAAC;IAED,iFAAiF;IACjF,MAAM,CAAC,GAAG,CAAC,CAAkB,EAAE,CAAkB;QAC/C,MAAM,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,OAAO,KAAK,EAAE;YAAE,MAAM,IAAI,UAAU,CAAC,4CAA4C,CAAC,CAAC;QACvF,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC;IAClD,CAAC;IAED,qDAAqD;IACrD,MAAM,CAAC,GAAG,CAAC,CAAkB,EAAE,CAAkB;QAC/C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IAED,wEAAwE;IACxE,MAAM,CAAC,GAAG,CAAC,CAAkB,EAAE,CAAkB;QAC/C,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACjB,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACjB,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,uDAAuD;IACvD,MAAM,CAAC,OAAO,CAAC,MAA8B;QAC3C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,GAAW,EAAE,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,GAAG,CACR,UAAkC,EAClC,MAA8B;QAE9B,IAAI,CAAC,GAAG,EAAE,CAAC;QACX,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YACrF,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1B,MAAM,GAAG,GAAG,YAAY,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAC7C,IAAI,GAAG,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC9B,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC;YACjD,CAAC,IAAI,GAAG,GAAG,IAAI,CAAC;YAChB,GAAG,IAAI,EAAE,CAAC;YACV,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QAC9B,CAAC;QACD,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IAC7B,CAAC;IAED,oEAAoE;IACpE,MAAM,CAAC,eAAe,CAAC,CAAkB;QACvC,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,GAAG,GAAG,EAAE;YAAE,OAAO,KAAK,CAAC;QAC3B,KAAK,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;YACzE,IAAI,GAAG,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC3B,IAAI,GAAG,GAAG,CAAC,KAAK,EAAE;gBAAE,OAAO,KAAK,CAAC;QACnC,CAAC;QACD,IAAI,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,GAAG,EAAE,CAAC;QACX,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC;YACvB,CAAC,KAAK,EAAE,CAAC;YACT,CAAC,EAAE,CAAC;QACN,CAAC;QACD,OAAO,EAAE,KAAK,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC;YACtC,IAAI,CAAC,IAAI,GAAG;gBAAE,SAAS;YACvB,IAAI,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;YACvC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,GAAG,EAAE;gBAAE,SAAS;YACzC,KAAK,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;gBACjC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;gBAClB,IAAI,CAAC,KAAK,GAAG,GAAG,EAAE;oBAAE,SAAS,OAAO,CAAC;YACvC,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gDAAgD;IAChD,MAAM,CAAC,SAAS,CAAC,CAAkB;QACjC,IAAI,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;QAC5B,OAAO,CAAC,YAAY,CAAC,eAAe,CAAC,SAAS,CAAC;YAAE,SAAS,EAAE,CAAC;QAC7D,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,8EAA8E;IAC9E,MAAM,CAAC,UAAU,CAAC,CAAkB;QAClC,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACnB,4EAA4E;QAC5E,6EAA6E;QAC7E,oEAAoE;QACpE,IAAI,GAAG,IAAI,EAAE;YAAE,MAAM,IAAI,UAAU,CAAC,mDAAmD,CAAC,CAAC;QACzF,IAAI,GAAG,GAAG,EAAE,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC;QAC/B,KAAK,IAAI,CAAC,GAAG,EAAE,GAAI,CAAC,EAAE,EAAE,CAAC;YACvB,IAAI,CAAC,GAAG,EAAE,CAAC;YACX,IAAI,CAAC,GAAG,EAAE,CAAC;YACX,IAAI,CAAC,GAAG,EAAE,CAAC;YACX,MAAM,CAAC,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;YAC3C,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;gBAChB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;gBACT,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBACZ,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YAC7B,CAAC;YACD,IAAI,CAAC,KAAK,GAAG;gBAAE,OAAO,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,MAAM,CAAC,SAAS,CAAC,CAAkB;QACjC,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACvB,0EAA0E;QAC1E,oEAAoE;QACpE,2EAA2E;QAC3E,qDAAqD;QACrD,IAAI,GAAG,KAAK,EAAE;YAAE,MAAM,IAAI,UAAU,CAAC,4CAA4C,CAAC,CAAC;QACnF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAEnE,KAAK,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;YAC3C,OAAO,GAAG,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC;gBACtB,GAAG,CAAC,CAAC,CAAC,CAAC;gBACP,GAAG,IAAI,CAAC,CAAC;YACX,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC,MAAM,EAAE,CAAC;YACpB,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,EAAY,CAAC;YAChC,IAAI,CAAC,KAAK,EAAE;gBAAE,SAAS;YACvB,IAAI,YAAY,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpC,GAAG,CAAC,CAAC,CAAC,CAAC;gBACP,SAAS;YACX,CAAC;YACD,MAAM,MAAM,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YAC1C,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxF,CAAC;IAED,iEAAiE;IACjE,MAAM,CAAC,QAAQ,CAAC,CAAkB;QAChC,IAAI,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC;YAAE,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAC9E,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,sEAAsE;IACtE,MAAM,CAAC,cAAc,CAAC,CAAkB,EAAE,CAAkB;QAC1D,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACjB,MAAM,EAAE,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;QACpD,OAAO,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,+DAA+D;IAC/D,MAAM,CAAC,YAAY,CAAC,CAAkB,EAAE,CAAkB;QACxD,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAC9C,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACf,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;YAChB,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC;gBACrB,CAAC,IAAI,EAAE,CAAC;gBACR,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;gBACjB,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE;oBAAE,MAAM,GAAG,CAAC,MAAM,CAAC;YAC7C,CAAC;YACD,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAChB,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE;gBAAE,MAAM,GAAG,CAAC,MAAM,CAAC;YACrD,CAAC,IAAI,CAAC,CAAC;QACT,CAAC;QACD,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/dist/Numerical.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Numerical — numerical-methods toolkit: root finding (bisection, secant,
+ * Newton, Brent), quadrature (composite trapezoid/Simpson, adaptive Simpson,
+ * Gauss-Legendre), ODE integration (Euler, RK4 for systems), and nonlinear
+ * curve fitting (Levenberg-Marquardt). Complements the simpler
+ * `integrateN`/`differentiateN`/`solveN` in {@link RealMath}.
+ */
+type Fn = (x: number) => number;
+/** A first-order ODE system `dy/dt = f(t, y)`. */
+type ODE = (t: number, y: number[]) => number[];
+/** A parametric model `y = model(x, params)`, e.g. `(x, [a, b]) => a * Math.exp(b * x)`. */
+type Model = (x: number, params: number[]) => number;
+export interface ODEStep {
+    t: number;
+    y: number[];
+}
+export interface LevenbergMarquardtResult {
+    params: number[];
+    /** sqrt of the sum of squared residuals at `params`. */
+    residualNorm: number;
+    iterations: number;
+    converged: boolean;
+}
+export declare class Numerical {
+    /** Find a root of `f` in `[a, b]` by bisection (requires a sign change). */
+    static bisection(f: Fn, a: number, b: number, tolerance?: number, maxIterations?: number): number;
+    /** Find a root of `f` by the secant method from two starting guesses. */
+    static secant(f: Fn, x0: number, x1: number, tolerance?: number, maxIterations?: number): number;
+    /** Newton's method; if `df` is omitted, a numeric derivative is used. */
+    static newton(f: Fn, x0: number, df?: Fn, tolerance?: number, maxIterations?: number): number;
+    /** Brent's method: robust bracketing root finder combining bisection and interpolation. */
+    static brent(f: Fn, a: number, b: number, tolerance?: number, maxIterations?: number): number;
+    /** Composite trapezoidal rule with `n` subintervals. */
+    static trapezoid(f: Fn, a: number, b: number, n?: number): number;
+    /** Composite Simpson's rule with `n` (rounded up to even) subintervals. */
+    static simpson(f: Fn, a: number, b: number, n?: number): number;
+    /** Adaptive Simpson quadrature to a target error tolerance. */
+    static adaptiveSimpson(f: Fn, a: number, b: number, tolerance?: number, maxDepth?: number): number;
+    /** 5-point Gauss-Legendre quadrature on `[a, b]`. */
+    static gaussLegendre(f: Fn, a: number, b: number): number;
+    /** Explicit Euler integration of a first-order system from `t0` to `t1`. */
+    static euler(f: ODE, y0: number[], t0: number, t1: number, h?: number): ODEStep[];
+    /** Classical fourth-order Runge-Kutta integration of a first-order system. */
+    static rk4(f: ODE, y0: number[], t0: number, t1: number, h?: number): ODEStep[];
+    /**
+     * Nonlinear least-squares curve fitting via Levenberg-Marquardt: finds
+     * `params` minimizing `sum((model(xs[i], params) - ys[i])^2)`, starting
+     * from `params0`. The Jacobian of `model` with respect to `params` is
+     * estimated by central finite differences (generalizes `newton`'s
+     * optional-df-else-numeric-derivative convention to a vector of
+     * parameters). `lambda` is the Marquardt damping factor -- scaled against
+     * each parameter's own row of `JᵀJ` (not a plain identity, the original
+     * Levenberg damping) so differently-scaled parameters damp comparably --
+     * grown 10x on a rejected step (safer, more like gradient descent) and
+     * shrunk 10x on an accepted one (faster, more like Gauss-Newton near the
+     * optimum).
+     *
+     * `converged` is true once *either* the sum of squared residuals itself
+     * drops below `tolerance` (a near-exact fit) *or* at least one step has
+     * improved it and further steps stop improving it meaningfully (no
+     * damped step improves it at all, or the relative improvement has
+     * dropped below 1e-12) -- deliberately not "the residual itself is near
+     * zero" as the only success criterion, since real (noisy) data's true
+     * best fit essentially never drives the residual anywhere near
+     * `tolerance`, even when the fit has genuinely converged to the best
+     * achievable parameters; requiring near-zero residual would wrongly
+     * report `converged: false` for every realistic (as opposed to
+     * synthetic/noiseless) dataset.
+     *
+     * NON-GOALS: no bounds/constraints on `params`; only ever finds one local
+     * minimum near `params0`, the same "no guarantee of the global optimum"
+     * caveat as `newton`. Returns `converged: false` (with the best `params`
+     * found, not a throw) when no step ever improved on `params0` at all --
+     * a model/data pairing that can't be fit usefully isn't a numerical error
+     * the way a divergent root-find is, but is still worth flagging distinctly
+     * from "converged to some local optimum, however good or mediocre."
+     */
+    static levenbergMarquardt(model: Model, params0: number[], xs: number[], ys: number[], options?: {
+        lambda0?: number;
+        tolerance?: number;
+        maxIterations?: number;
+    }): LevenbergMarquardtResult;
+}
+export {};
+//# sourceMappingURL=Numerical.d.ts.map

package/dist/Numerical.d.ts.map

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