nerdamer 1.1.13 → 2.0.0-rc.2

package/output/algebra/polynomial/SparsePolynomialGcd.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * @module sparsePolynomialGcd
+ *
+ * Integer GCD reconstruction for the exact sparse polynomial representation.
+ *
+ * External references consulted:
+ * - SymPy multivariate Chinese remainder reconstruction and modular GCD loop:
+ *   https://github.com/sympy/sympy/blob/120ee85f346f6292b763cc195afda4f907260d4a/sympy/polys/zippel.py
+ * - SymPy Chinese Remainder Theorem implementation:
+ *   https://github.com/sympy/sympy/blob/120ee85f346f6292b763cc195afda4f907260d4a/sympy/ntheory/modular.py
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.combinePolynomialCongruences = combinePolynomialCongruences;
+exports.sparsePolynomialGcd = sparsePolynomialGcd;
+const SparsePolynomial_1 = require("../../core/classes/polynomial/SparsePolynomial");
+const errors_1 = require("../../core/errors");
+const bigint_1 = require("../../core/functions/bigint/bigint");
+const primeFactor_1 = require("../../core/functions/bigint/primeFactor");
+const modularGcd_1 = require("./modularGcd");
+const ModularSparsePolynomial_1 = require("./ModularSparsePolynomial");
+// SymPy's integer Zippel loop starts near 10^9 because larger fields sharply reduce
+// failed evaluations during sparse interpolation.
+const INITIAL_GCD_PRIME = 1000000007n;
+/** Maps a residue to the symmetric representative for one positive modulus. */
+function symmetricResidue(value, modulus) {
+    const residue = (0, bigint_1.mod)(value, modulus);
+    return residue * 2n > modulus ? residue - modulus : residue;
+}
+/** Looks up a term coefficient without interpreting the monomial key. */
+function termMap(polynomial) {
+    const terms = new Map();
+    for (const term of polynomial.terms()) {
+        terms.set(term.exponents.join(','), term);
+    }
+    return terms;
+}
+/**
+ * Combines two sparse polynomial congruences with coprime positive moduli.
+ *
+ * Missing monomials are treated as zero residues. Exponent vectors are retained
+ * from the source term and never reconstructed from the map key.
+ */
+function combinePolynomialCongruences(left, leftModulus, right, rightModulus) {
+    if (left.variableCount !== right.variableCount) {
+        throw new RangeError((0, errors_1.message)('polyRequires', { operation: 'Polynomial CRT', requirement: (0, errors_1.message)('polyReqSamePolynomialRing') }));
+    }
+    if (leftModulus <= 0n || rightModulus <= 0n) {
+        throw new RangeError((0, errors_1.message)('polyRequires', { operation: 'Polynomial CRT', requirement: (0, errors_1.message)('polyReqPositiveModuli') }));
+    }
+    if ((0, bigint_1.GCD)(leftModulus, rightModulus) !== 1n) {
+        throw new RangeError((0, errors_1.message)('polyRequires', { operation: 'Polynomial CRT', requirement: (0, errors_1.message)('polyReqCoprimeModuli') }));
+    }
+    const inverse = (0, bigint_1.invMod)(leftModulus, rightModulus);
+    if (inverse < 0n) {
+        throw new RangeError((0, errors_1.message)('polyCrtModuliInvertible'));
+    }
+    const leftTerms = termMap(left);
+    const rightTerms = termMap(right);
+    const keys = new Set([...leftTerms.keys(), ...rightTerms.keys()]);
+    const modulus = leftModulus * rightModulus;
+    const terms = [];
+    for (const key of keys) {
+        const leftTerm = leftTerms.get(key);
+        const rightTerm = rightTerms.get(key);
+        const leftCoefficient = leftTerm?.coefficient ?? 0n;
+        const rightCoefficient = rightTerm?.coefficient ?? 0n;
+        const correction = (0, bigint_1.mod)((rightCoefficient - leftCoefficient) * inverse, rightModulus);
+        const coefficient = symmetricResidue(leftCoefficient + leftModulus * correction, modulus);
+        if (coefficient !== 0n) {
+            terms.push({
+                coefficient,
+                exponents: leftTerm?.exponents ?? rightTerm?.exponents ?? [],
+            });
+        }
+    }
+    return {
+        polynomial: new SparsePolynomial_1.SparsePolynomial(left.variableCount, terms),
+        modulus,
+    };
+}
+/**
+ * Returns the integer leading coefficient after making one variable primary.
+ *
+ * Ties follow the remaining ring coordinates in their existing order, matching a
+ * lexicographic view with variableIndex moved to the front.
+ */
+function leadingCoefficientForVariable(polynomial, variableIndex) {
+    polynomial.degree(variableIndex);
+    const terms = polynomial.terms();
+    if (terms.length === 0) {
+        return 0n;
+    }
+    let leading = terms[0];
+    for (let termIndex = 1; termIndex < terms.length; termIndex++) {
+        const term = terms[termIndex];
+        if (term.exponents[variableIndex] !== leading.exponents[variableIndex]) {
+            if (term.exponents[variableIndex] > leading.exponents[variableIndex]) {
+                leading = term;
+            }
+            continue;
+        }
+        for (let index = 0; index < polynomial.variableCount; index++) {
+            if (index === variableIndex) {
+                continue;
+            }
+            if (term.exponents[index] === leading.exponents[index]) {
+                continue;
+            }
+            if (term.exponents[index] > leading.exponents[index]) {
+                leading = term;
+            }
+            break;
+        }
+    }
+    return leading.coefficient;
+}
+/** Converts an integer sparse polynomial to canonical residues modulo prime. */
+function reduceModulo(polynomial, prime) {
+    return new ModularSparsePolynomial_1.ModularSparsePolynomial(polynomial.variableCount, prime, polynomial.terms());
+}
+/** Returns the selected-variable degree vector used to compare modular images. */
+function degreeVector(polynomial, variables) {
+    return variables.map(variableIndex => polynomial.degree(variableIndex) ?? 0n);
+}
+/**
+ * Computes the integer GCD of two sparse polynomials by modular images and CRT.
+ *
+ * variables must follow polynomial-ring order and contain every active variable.
+ * The returned GCD has positive leading coefficient under lexicographic order.
+ */
+function sparsePolynomialGcd(left, right, variables) {
+    if (left.variableCount !== right.variableCount) {
+        throw new RangeError((0, errors_1.message)('polyRequires', { operation: 'Sparse polynomial GCD', requirement: (0, errors_1.message)('polyReqSamePolynomialRing') }));
+    }
+    if (variables.length === 0) {
+        throw new RangeError((0, errors_1.message)('polyRequires', { operation: 'Sparse polynomial GCD', requirement: (0, errors_1.message)('polyReqAtLeastOneVariable') }));
+    }
+    const selected = new Set();
+    let previousVariable = -1;
+    for (const variableIndex of variables) {
+        left.degree(variableIndex);
+        right.degree(variableIndex);
+        if (selected.has(variableIndex)) {
+            throw new RangeError((0, errors_1.message)('polyVariablesUnique', { operation: 'Sparse polynomial GCD' }));
+        }
+        if (variableIndex <= previousVariable) {
+            throw new RangeError((0, errors_1.message)('polyVariablesRingOrder', { operation: 'Sparse polynomial GCD' }));
+        }
+        selected.add(variableIndex);
+        previousVariable = variableIndex;
+    }
+    for (const activeVariable of [...left.variables(), ...right.variables()]) {
+        if (!selected.has(activeVariable)) {
+            throw new RangeError((0, errors_1.message)('polyInputsSelectedOnly', { operation: 'Sparse polynomial GCD' }));
+        }
+    }
+    if (left.isZero()) {
+        return right.isZero() ? right : right.normalizeLeadingSign('lex');
+    }
+    if (right.isZero()) {
+        return left.normalizeLeadingSign('lex');
+    }
+    const leftContent = left.content();
+    const rightContent = right.content();
+    const commonContent = (0, bigint_1.GCD)(leftContent, rightContent);
+    const primitiveLeft = left.primitivePart().normalizeLeadingSign('lex');
+    const primitiveRight = right.primitivePart().normalizeLeadingSign('lex');
+    const leftLeading = primitiveLeft.leadingTerm('lex');
+    const rightLeading = primitiveRight.leadingTerm('lex');
+    if (leftLeading === null || rightLeading === null) {
+        return SparsePolynomial_1.SparsePolynomial.zero(left.variableCount);
+    }
+    if (primitiveLeft.isConstant() || primitiveRight.isConstant()) {
+        return SparsePolynomial_1.SparsePolynomial.constant(left.variableCount, commonContent);
+    }
+    if (primitiveLeft.equals(primitiveRight)) {
+        return primitiveLeft.scale(commonContent);
+    }
+    if (primitiveLeft.divideExact(primitiveRight) !== null) {
+        return primitiveRight.scale(commonContent);
+    }
+    if (primitiveRight.divideExact(primitiveLeft) !== null) {
+        return primitiveLeft.scale(commonContent);
+    }
+    const leadingGcd = (0, bigint_1.GCD)(leftLeading.coefficient, rightLeading.coefficient);
+    const badPrimeFactors = variables.map(variableIndex => (0, bigint_1.GCD)(leadingCoefficientForVariable(primitiveLeft, variableIndex), leadingCoefficientForVariable(primitiveRight, variableIndex)));
+    let prime = (0, primeFactor_1.nextPrimeBig)(INITIAL_GCD_PRIME);
+    let accumulated = null;
+    let accumulatedModulus = 1n;
+    let expectedDegrees = null;
+    while (true) {
+        while (badPrimeFactors.some(factor => factor % prime === 0n)) {
+            prime = (0, primeFactor_1.nextPrimeBig)(prime + 1n);
+        }
+        const modularLeft = reduceModulo(primitiveLeft, prime);
+        const modularRight = reduceModulo(primitiveRight, prime);
+        const modularGcd = (0, modularGcd_1.modularGcdFiniteField)(modularLeft, modularRight, variables);
+        if (modularGcd === null) {
+            prime = (0, primeFactor_1.nextPrimeBig)(prime + 1n);
+            continue;
+        }
+        if (modularGcd.isConstant() && !modularGcd.isZero()) {
+            return SparsePolynomial_1.SparsePolynomial.constant(left.variableCount, commonContent);
+        }
+        const imageDegrees = degreeVector(modularGcd, variables);
+        if (expectedDegrees !== null) {
+            let degreeComparison = 0;
+            for (let index = 0; index < imageDegrees.length; index++) {
+                if (imageDegrees[index] < expectedDegrees[index]) {
+                    degreeComparison = -1;
+                    break;
+                }
+                if (imageDegrees[index] > expectedDegrees[index]) {
+                    degreeComparison = 1;
+                    break;
+                }
+            }
+            if (degreeComparison > 0) {
+                prime = (0, primeFactor_1.nextPrimeBig)(prime + 1n);
+                continue;
+            }
+            if (degreeComparison < 0) {
+                expectedDegrees = imageDegrees;
+                accumulated = null;
+                accumulatedModulus = 1n;
+            }
+        }
+        else {
+            expectedDegrees = imageDegrees;
+        }
+        const scaledImage = modularGcd.scale(leadingGcd);
+        const liftedImage = scaledImage.toSymmetricIntegerPolynomial();
+        let reconstructed;
+        let reconstructedModulus;
+        if (accumulated === null) {
+            reconstructed = liftedImage;
+            reconstructedModulus = prime;
+        }
+        else {
+            const combined = combinePolynomialCongruences(accumulated, accumulatedModulus, liftedImage, prime);
+            reconstructed = combined.polynomial;
+            reconstructedModulus = combined.modulus;
+        }
+        const stable = accumulated !== null && reconstructed.equals(accumulated);
+        accumulated = reconstructed;
+        accumulatedModulus = reconstructedModulus;
+        if (stable) {
+            const primitiveCandidate = reconstructed
+                .primitivePart()
+                .normalizeLeadingSign('lex');
+            const candidate = primitiveCandidate.scale(commonContent);
+            if (left.divideExact(candidate) !== null && right.divideExact(candidate) !== null) {
+                return candidate;
+            }
+        }
+        prime = (0, primeFactor_1.nextPrimeBig)(prime + 1n);
+    }
+}

package/output/algebra/polynomial/SparsePolynomialMultivariateFactor.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @module sparsePolynomialMultivariateFactor
+ *
+ * Evaluation configuration for Wang/EEZ multivariate integer factorization.
+ *
+ * External references consulted:
+ * - Wang/EEZ evaluation-point tests and lifting pipeline:
+ *   https://github.com/sympy/sympy/blob/120ee85f346f6292b763cc195afda4f907260d4a/sympy/polys/factortools.py
+ */
+import { SparsePolynomial } from '../../core/classes/polynomial/SparsePolynomial';
+import type { SparsePolynomialSquareFreeFactorization } from './SparsePolynomialFactor';
+type WangSpecialization = Readonly<{
+    values: readonly bigint[];
+    content: bigint;
+    polynomial: SparsePolynomial;
+}>;
+export type WangEvaluation = WangSpecialization & Readonly<{
+    factors: readonly SparsePolynomial[];
+}>;
+export type WangConfiguration = Readonly<{
+    evaluation: WangEvaluation;
+    polynomial: SparsePolynomial;
+    factors: readonly SparsePolynomial[];
+    leadingCoefficients: readonly SparsePolynomial[];
+}>;
+export type WangBivariateConfiguration = WangConfiguration;
+/**
+ * Tests one Wang/EEZ specialization.
+ *
+ * The first selected variable remains symbolic and every later variable is replaced by
+ * the corresponding integer value. A usable specialization preserves the degree in the
+ * main variable and has square-free primitive part.
+ */
+export declare function testWangEvaluationPoint(polynomial: SparsePolynomial, variables: readonly number[], values: readonly bigint[]): WangEvaluation | null;
+/**
+ * Builds a Wang configuration with reconstructed factor leading coefficients.
+ *
+ * The main-variable leading coefficient is factored recursively over the tail
+ * variables. A single active tail variable uses the univariate factorizer; larger
+ * coefficient rings recurse through multivariate factorization.
+ */
+export declare function testWangConfiguration(polynomial: SparsePolynomial, variables: readonly number[], values: readonly bigint[]): WangConfiguration | null;
+/** Builds a bivariate Wang configuration through the general reconstruction path. */
+export declare function testWangBivariateConfiguration(polynomial: SparsePolynomial, variables: readonly number[], value: bigint): WangBivariateConfiguration | null;
+/** Lifts a Wang configuration using the reusable multivariate Hensel implementation. */
+export declare function liftWangConfiguration(configuration: WangConfiguration, variables: readonly number[], prime: bigint): readonly SparsePolynomial[] | null;
+/** Lifts one bivariate Wang configuration modulo a prime. */
+export declare function liftWangBivariateConfiguration(configuration: WangBivariateConfiguration, variables: readonly number[], prime: bigint): readonly SparsePolynomial[] | null;
+/**
+ * Factors a primitive square-free multivariate integer polynomial.
+ *
+ * A Wang configuration supplies the specialized factors and reconstructed leading
+ * coefficients. Modular lifts are retried with increasing primes until centered integer
+ * factors reconstruct the original polynomial exactly.
+ */
+export declare function factorSquareFreeMultivariateInteger(polynomial: SparsePolynomial, variables: readonly number[]): readonly SparsePolynomial[];
+/** Factors a primitive square-free bivariate polynomial over the integers. */
+export declare function factorSquareFreeBivariateInteger(polynomial: SparsePolynomial, variables: readonly number[]): readonly SparsePolynomial[];
+/**
+ * Completely factors a multivariate integer polynomial.
+ *
+ * Numeric content is returned separately. Main-variable content is factored in the
+ * remaining variables before the primitive portion enters Wang lifting.
+ */
+export declare function factorMultivariateInteger(polynomial: SparsePolynomial, variables: readonly number[]): SparsePolynomialSquareFreeFactorization;
+/** Completely factors a bivariate integer polynomial. */
+export declare function factorBivariateInteger(polynomial: SparsePolynomial, variables: readonly number[]): SparsePolynomialSquareFreeFactorization;
+/**
+ * Finds the nearest Wang configuration whose leading coefficients can be reconstructed
+ * from the specialized factorization.
+ */
+export declare function findWangConfiguration(polynomial: SparsePolynomial, variables: readonly number[]): WangConfiguration;
+/** Finds the nearest bivariate Wang configuration. */
+export declare function findWangBivariateConfiguration(polynomial: SparsePolynomial, variables: readonly number[]): WangBivariateConfiguration;
+/**
+ * Finds the nearest usable Wang/EEZ evaluation point in deterministic integer shells.
+ *
+ * The origin is tested first, followed by the boundary of [-1,1]^n, [-2,2]^n, and so
+ * on. Search continues until a specialization preserves leading degree and is square-free.
+ */
+export declare function findWangEvaluationPoint(polynomial: SparsePolynomial, variables: readonly number[]): WangEvaluation;
+export {};