nerdamer 1.1.13 → 2.0.0-rc.2

package/output/algebra/algorithms/arith.js

@@ -0,0 +1,324 @@
+"use strict";
+/**
+ * @module arith
+ *
+ * Low-level integer and modular arithmetic helpers used throughout the library.
+ *
+ * - All integer arithmetic is done with `bigint`.
+ * - Modular routines assume a prime modulus `p` when inverses are required.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GcdBudgetExceededError = exports.PrimeSelectionError = void 0;
+exports.abs = abs;
+exports.gcd = gcd;
+exports.pow = pow;
+exports.powN = powN;
+exports.bigIntSqrt = bigIntSqrt;
+exports.intNthRootExact = intNthRootExact;
+exports.getDivisors = getDivisors;
+exports.modNorm = modNorm;
+exports.modSymmetric = modSymmetric;
+exports.modInv = modInv;
+exports.contentBigint = contentBigint;
+exports.bigintBitLength = bigintBitLength;
+exports.nextPrime32 = nextPrime32;
+const errors_1 = require("../../core/errors");
+/**
+ * Shared integer + modular arithmetic primitives used across Zippel GCD and
+ * multivariate factorization.
+ *
+ * Design goals:
+ * - BigInt-only arithmetic for coefficient paths.
+ * - Small, stable surface area: use `abs`, `gcd`, `pow`.
+ */
+// ============================================================================
+// Integer arithmetic
+// ============================================================================
+/** Absolute value for BigInt. */
+function abs(a) {
+    return a < 0n ? -a : a;
+}
+/**
+ * Euclidean GCD for BigInt.
+ *
+ * Returns a nonnegative gcd. gcd(0,0) = 0.
+ */
+function gcd(a, b) {
+    a = abs(a);
+    b = abs(b);
+    while (b !== 0n) {
+        [a, b] = [b, a % b];
+    }
+    return a;
+}
+/**
+ * Integer exponentiation for BigInt with a nonnegative exponent.
+ *
+ * This is NOT modular exponentiation (see {@link modPow}).
+ */
+function pow(base, exp) {
+    if (exp < 0n) {
+        throw new Error((0, errors_1.message)('arithPowNegativeExponent'));
+    }
+    let b = base;
+    let e = exp;
+    let r = 1n;
+    while (e > 0n) {
+        if (e & 1n) {
+            r *= b;
+        }
+        b *= b;
+        e >>= 1n;
+    }
+    return r;
+}
+/**
+ * Integer exponentiation for BigInt with a small nonnegative JS number exponent.
+ *
+ * Convenience wrapper used throughout factorization code where exponents are known
+ * to fit in a number.
+ */
+function powN(base, exp) {
+    if (!Number.isInteger(exp) || exp < 0) {
+        throw new Error((0, errors_1.message)('arithPowNNonnegativeInteger'));
+    }
+    return pow(base, BigInt(exp));
+}
+// ============================================================================
+// Number theory helpers (BigInt)
+// ============================================================================
+/**
+ * Integer square root: floor(sqrt(n)) for n >= 0.
+ */
+function bigIntSqrt(n) {
+    if (n < 0n) {
+        throw new Error((0, errors_1.message)('arithBigIntSqrtNegative'));
+    }
+    if (n < 2n) {
+        return n;
+    }
+    // Newton iteration.
+    let x0 = n;
+    let x1 = (x0 + 1n) >> 1n;
+    while (x1 < x0) {
+        x0 = x1;
+        x1 = (x1 + n / x1) >> 1n;
+    }
+    return x0;
+}
+/**
+ * Exact n-th root if it exists.
+ * Returns r such that r^n === value, or null if value is not a perfect n-th power.
+ */
+function intNthRootExact(value, n) {
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new Error((0, errors_1.message)('arithNthRootPositiveInteger'));
+    }
+    if (value < 0n) {
+        // Only odd roots exist for negative values.
+        if ((n & 1) === 0) {
+            return null;
+        }
+        const r = intNthRootExact(-value, n);
+        return r === null ? null : -r;
+    }
+    if (value === 0n) {
+        return 0n;
+    }
+    if (value === 1n) {
+        return 1n;
+    }
+    // Exponential search for an upper bound.
+    let lo = 0n;
+    let hi = 1n;
+    while (powN(hi, n) < value) {
+        hi <<= 1n;
+    }
+    // Binary search.
+    while (lo + 1n < hi) {
+        const mid = (lo + hi) >> 1n;
+        const p = powN(mid, n);
+        if (p === value) {
+            return mid;
+        }
+        if (p < value) {
+            lo = mid;
+        }
+        else {
+            hi = mid;
+        }
+    }
+    return powN(hi, n) === value ? hi : powN(lo, n) === value ? lo : null;
+}
+/**
+ * Return positive divisors of n (n > 0) by trial division.
+ *
+ * NOTE: This is intended for small integers used in factoring heuristics.
+ */
+function getDivisors(n) {
+    if (n <= 0n) {
+        throw new Error((0, errors_1.message)('arithDivisorsPositive'));
+    }
+    const out = [];
+    const r = bigIntSqrt(n);
+    for (let d = 1n; d <= r; d++) {
+        if (n % d === 0n) {
+            out.push(d);
+            const q = n / d;
+            if (q !== d) {
+                out.push(q);
+            }
+        }
+    }
+    out.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return out;
+}
+/**
+ * Extended Euclidean algorithm.
+ *
+ * Returns `{ g, x, y }` such that `a*x + b*y = g = gcd(a,b)` (up to sign).
+ */
+function egcd(a, b) {
+    let old_r = a, r = b;
+    let old_s = 1n, s = 0n;
+    let old_t = 0n, t = 1n;
+    while (r !== 0n) {
+        const q = old_r / r;
+        [old_r, r] = [r, old_r - q * r];
+        [old_s, s] = [s, old_s - q * s];
+        [old_t, t] = [t, old_t - q * t];
+    }
+    return { g: old_r, x: old_s, y: old_t };
+}
+// ============================================================================
+// Modular arithmetic
+// ============================================================================
+/** Normalize a into the range [0, |p|). Throws if p is zero. */
+function modNorm(a, p) {
+    if (p === 0n) {
+        throw new Error((0, errors_1.message)('arithModNormNonzeroModulus'));
+    }
+    const m = abs(p);
+    const r = a % m;
+    return r < 0n ? r + m : r;
+}
+/** Map a to the symmetric residue class (-|p|/2, |p|/2]. */
+function modSymmetric(a, p) {
+    if (p === 0n) {
+        throw new Error((0, errors_1.message)('arithModSymmetricNonzeroModulus'));
+    }
+    const m = abs(p);
+    const r = modNorm(a, m);
+    const half = m / 2n;
+    return r > half ? r - m : r;
+}
+/** Modular multiplicative inverse of a mod p, where gcd(a,p)=1. */
+function modInv(a, p) {
+    const aa = modNorm(a, p);
+    if (aa === 0n) {
+        throw new Error((0, errors_1.message)('arithModInvZeroNoninvertible'));
+    }
+    const { g, x } = egcd(aa, p);
+    if (g !== 1n && g !== -1n) {
+        throw new Error((0, errors_1.message)('arithModInvNoninvertible'));
+    }
+    return modNorm(x, p);
+}
+// ============================================================================
+// Coefficient utilities
+// ============================================================================
+/**
+ * Content (GCD of coefficients) for an iterable of bigint coefficients.
+ * Returns 0n for the all-zero collection.
+ */
+function contentBigint(coeffs) {
+    let g0 = 0n;
+    for (const c of coeffs) {
+        const a = abs(c);
+        g0 = gcd(g0, a);
+        if (g0 === 1n) {
+            return 1n;
+        }
+    }
+    return g0;
+}
+// ---------------------------------------------------------------------------
+// Univariate polynomial arithmetic over F_p (coeff arrays low->high)
+// ---------------------------------------------------------------------------
+// ============================================================================
+// Misc small utilities
+// ============================================================================
+/** Bit-length of a bigint (0 -> 0). */
+function bigintBitLength(a) {
+    if (a < 0n) {
+        a = -a;
+    }
+    let bits = 0;
+    while (a > 0n) {
+        bits++;
+        a >>= 1n;
+    }
+    return bits;
+}
+/** Simple primality test for 32-bit positive integers. */
+function isPrime32(n) {
+    if (!Number.isInteger(n) || n < 2) {
+        return false;
+    }
+    if (n === 2 || n === 3) {
+        return true;
+    }
+    if ((n & 1) === 0) {
+        return false;
+    }
+    if (n % 3 === 0) {
+        return false;
+    }
+    const limit = Math.floor(Math.sqrt(n));
+    for (let d = 5; d <= limit; d += 6) {
+        if (n % d === 0 || n % (d + 2) === 0) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Next prime >= start. */
+function nextPrime32(start) {
+    let n = start;
+    if (n <= 2) {
+        return 2;
+    }
+    if ((n & 1) === 0) {
+        n++;
+    }
+    while (!isPrime32(n)) {
+        n += 2;
+    }
+    return n;
+}
+class AlgebraError extends Error {
+    /** Additional structured debugging info. Always present (possibly empty). */
+    details;
+    phase;
+    constructor(message, phase = 'unknown', details) {
+        super(message);
+        this.name = this.constructor.name;
+        this.phase = phase;
+        this.details = details ?? {};
+    }
+}
+class PrimeSelectionError extends AlgebraError {
+    constructor(message, details) {
+        super(message, 'prime-selection', details);
+    }
+}
+exports.PrimeSelectionError = PrimeSelectionError;
+/**
+ * Thrown when Zippel-style multivariate GCD exceeds its specialization / interpolation budget.
+ */
+class GcdBudgetExceededError extends AlgebraError {
+    constructor(message, details) {
+        super(message, 'budget', details);
+    }
+}
+exports.GcdBudgetExceededError = GcdBudgetExceededError;

package/output/algebra/algorithms/groebnerBase.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @module groebner
+ *
+ * Gröbner basis computation, elimination, ideal membership, and solving.
+ *
+ * This implementation is a Buchberger-style engine with:
+ * - configurable monomial order (LEX, GRLEX, GREVLEX)
+ * - sugar-strategy pair selection for performance
+ * - optional budgets and stats
+ * - fraction-free normal form helpers
+ * - elimination ideals
+ * - ideal membership testing
+ * - triangular back-substitution solver
+ *
+ * External references consulted:
+ * - SymPy Gröbner basis implementation:
+ *   https://github.com/sympy/sympy/blob/120ee85f346f6292b763cc195afda4f907260d4a/sympy/polys/groebnertools.py
+ * - Giovini, Mora, Niesi, Robbiano, Traverso, "One Sugar Cube, Please":
+ *   https://doi.org/10.1145/120694.120701
+ * - Bigatti, Caboara, Robbiano, "Computing inhomogeneous Gröbner bases":
+ *   https://doi.org/10.1016/j.jsc.2010.10.002
+ */
+import { SparsePolynomial } from '../../core/classes/polynomial/SparsePolynomial';
+/** Monomial order used for leading terms, pair processing, and reduction. */
+export type MonomialOrder = 'LEX' | 'GRLEX' | 'GREVLEX';
+/** Deterministic work counters captured when a Groebner resource budget is exceeded. */
+export type GroebnerStats = {
+    /** Critical pairs removed from the processing queue. */
+    pairsPopped: number;
+    /** Pairs skipped because their leading monomials are relatively prime. */
+    pairsSkippedProduct: number;
+    /** Pairs skipped by Buchberger's chain criterion. */
+    pairsSkippedChain: number;
+    /** Processed pairs whose reduced S-polynomial was zero. */
+    pairsReducedToZero: number;
+    /** Nonzero reduced S-polynomials appended to the working basis. */
+    basisAppends: number;
+};
+/** Controls monomial order, result normalization, pair strategy, and deterministic budgets. */
+export type GroebnerBasisOptions = {
+    /** Monomial order; defaults to `LEX`. Variable priority follows exponent index order. */
+    order?: MonomialOrder;
+    /**
+     * If true (default), return a reduced/normalized basis (canonicalize/interreduce/primitive normalize).
+     * If false, returns the raw Buchberger basis as produced by the pair loop.
+     */
+    reduced?: boolean;
+    /** Hard cap on Buchberger pair iterations (deterministic, not time-based). */
+    maxPairsPopped?: number;
+    /** Hard cap on basis size (including initial generators). */
+    maxBasisSize?: number;
+    /**
+     * Pair selection strategy.
+     * - 'sugar' (default): use sugar degree heuristic for better performance
+     * - 'fifo': simple first-in first-out (original behavior)
+     */
+    strategy?: 'sugar' | 'fifo';
+};
+/**
+ * Thrown when a Groebner pair-count or basis-size budget is exhausted.
+ *
+ * {@link GroebnerBudgetExceeded.stats} is the live counter snapshot from the aborted
+ * computation. The error keeps that object by reference and does not freeze it.
+ */
+export declare class GroebnerBudgetExceeded extends Error {
+    /** Work counters at the point the budget was exceeded. */
+    readonly stats: GroebnerStats;
+    /**
+     * @param message - Human-readable budget condition.
+     * @param stats - Counter snapshot retained on the error.
+     */
+    constructor(message: string, stats: GroebnerStats);
+}
+/**
+ * Computes a Groebner basis for exact sparse integer polynomials.
+ *
+ * The input polynomials must belong to the same ring. With `reduced: true`, the
+ * basis is interreduced, coefficient content is removed, leading signs are normalized,
+ * and exact monic normalization is applied when possible. Results are sorted
+ * deterministically and the supplied polynomials are not modified.
+ *
+ * @param polys - Ideal generators in one sparse polynomial ring.
+ * @param order - Monomial order; defaults to `LEX`.
+ * @param reduced - Return the normalized/interreduced basis; defaults to `true`.
+ * @returns New sparse basis polynomials in deterministic presentation order.
+ */
+export declare function Groebner(polys: readonly SparsePolynomial[], order?: MonomialOrder, reduced?: boolean): SparsePolynomial[];
+/**
+ * Computes a Groebner basis with ordering, strategy, and budget control.
+ *
+ * @param polys - Exact sparse integer-coefficient generators in one ring.
+ * @param opts - Ordering, normalization, pair-selection, and deterministic budget options.
+ * @returns New basis polynomials. Work statistics are exposed only when a budget is
+ * exceeded; successful calls return the basis itself.
+ * @throws {@link GroebnerBudgetExceeded} Thrown after a configured pair-count or
+ * basis-size limit is exceeded.
+ */
+export declare function groebnerBasisWithOptions(polys: readonly SparsePolynomial[], opts?: GroebnerBasisOptions): SparsePolynomial[];
+/**
+ * Computes the part of the ideal that lies in the polynomial ring generated by `keepVars`.
+ *
+ * @param polys - Exact integer-coefficient generators.
+ * @param vars - All variables in exponent-index order. Variables to eliminate must
+ * precede retained variables for lexicographic elimination.
+ * @param keepVars - Variables to retain, expected to be a suffix of `vars`.
+ * @param opts - Reduction, pair strategy, and budgets; order is always `LEX`.
+ * @returns New basis polynomials involving only retained variables.
+ * @throws {@link GroebnerBudgetExceeded} Thrown when a configured budget is exceeded.
+ */
+export declare function eliminate(polys: readonly SparsePolynomial[], vars: readonly string[], keepVars: readonly string[], opts?: Omit<GroebnerBasisOptions, 'order'>): SparsePolynomial[];
+/**
+ * Tests exact ideal membership by reducing against a computed Groebner basis.
+ *
+ * @param f - Polynomial to test.
+ * @param polys - Exact integer-coefficient ideal generators.
+ * @param order - Monomial order; defaults to `LEX`.
+ * @param opts - Pair strategy and deterministic budgets.
+ * @returns Whether the normal form of `f` is zero.
+ * @throws {@link GroebnerBudgetExceeded} Thrown when basis computation exceeds a budget.
+ */
+export declare function idealMembership(f: SparsePolynomial, polys: readonly SparsePolynomial[], order?: MonomialOrder, opts?: Omit<GroebnerBasisOptions, 'order' | 'reduced'>): boolean;
+/**
+ * Reduces a polynomial by a basis or arbitrary reducer set using fraction-free arithmetic.
+ *
+ * @remarks
+ * This does not compute or verify a Groebner basis. The result is a canonical ideal
+ * normal form only when `basis` is already a basis for the selected order.
+ *
+ * @param f - Polynomial to reduce.
+ * @param basis - Reducers, normally a Groebner basis.
+ * @param order - Monomial order used to select leading terms.
+ * @returns The primitive-normalized remainder.
+ */
+export declare function reduceByBasis(f: SparsePolynomial, basis: readonly SparsePolynomial[], order?: MonomialOrder): SparsePolynomial;
+/**
+ * Maps each solved variable to a reduced rational numerator/denominator pair.
+ *
+ * Only rational coordinates discovered by triangular back-substitution are represented.
+ */
+export type RationalSolution = Map<string, {
+    n: bigint;
+    d: bigint;
+}>;
+/**
+ * Solves a zero-dimensional polynomial system for rational coordinates.
+ *
+ * @remarks
+ * This is the low-level exact solver used with the Groebner representation, not the
+ * ordinary expression solver. It computes a reduced lexicographic basis, walks variables
+ * from least to most significant, applies the Rational Root Theorem to univariate
+ * constraints, and substitutes each partial assignment into its own basis copy.
+ * Irrational and complex roots are outside this routine's result set.
+ *
+ * @param polys - Exact integer-coefficient system generators.
+ * @param vars - Variables in lexicographic elimination order, most significant first.
+ * @param opts - Pair strategy and budgets forwarded to basis computation.
+ * @returns New solution maps. An empty array can mean inconsistency, no rational roots,
+ * or a non-finite/unsupported triangular result; these cases are not distinguished.
+ * @throws {@link GroebnerBudgetExceeded} Thrown when basis computation exceeds a budget.
+ */
+export declare function solve(polys: readonly SparsePolynomial[], vars: readonly string[], opts?: Omit<GroebnerBasisOptions, 'order' | 'reduced'>): RationalSolution[];