nerdamer 1.1.13 → 2.0.0-rc.1

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

@@ -0,0 +1,228 @@
+/**
+ * @module poly
+ *
+ * Core polynomial representation and operations.
+ *
+ * This file contains both univariate and multivariate utilities used by:
+ * - multivariate GCD (Zippel-style)
+ * - multivariate factorization (evaluation + Hensel lifting)
+ * - Gröbner basis computations
+ *
+ * Notes:
+ * - Univariate polynomials over Z are represented as coefficient arrays `ZPoly`.
+ * - Multivariate polynomials are represented by `MultiPoly` (see near bottom of file).
+ */
+import { MultiPoly } from './multiPoly/MultiPoly';
+/**
+ * Univariate polynomial utilities over Z[x] (bigint coefficients)
+ * and over F_p[x] (explicit modulus carried in the polynomial object).
+ *
+ * Canonical exports:
+ *  - Z[x]: z*
+ *  - F_p[x]: fp*
+ */
+export type ZPoly = bigint[];
+export type Vars = readonly string[];
+export type InternalPoly = {
+    vars: Vars;
+    terms: Map<string, bigint>;
+};
+/** Returns a trimmed copy (does not mutate input). */
+export declare function zTrim(a: ZPoly): ZPoly;
+/** True iff polynomial is identically 0. */
+export declare function zIsZero(a: ZPoly): boolean;
+export declare function zLC(a: ZPoly): bigint;
+export declare function zSub(a: ZPoly, b: ZPoly): ZPoly;
+/** Returns q iff a = b*q exactly; otherwise null. */
+export declare function zTryDivExact(a: ZPoly, b: ZPoly): ZPoly | null;
+/** Returns q such that a = b*q. Throws if division is not exact. */
+export declare function zDivExact(a: ZPoly, b: ZPoly): ZPoly;
+export declare function zScale(a: ZPoly, k: bigint): ZPoly;
+/**
+ * Normalize polynomial by extracting nonnegative content and fixing the sign
+ * so the leading coefficient is positive.
+ *
+ * - For 0 returns { content: 0, primitive: 0 }
+ * - For nonzero returns { content: c, primitive: p } where:
+ *    - c = gcd(|coeffs|) >= 1
+ *    - p has gcd(|coeffs|)=1
+ *    - LC(p) > 0
+ */
+export declare function zNormalizePrimitiveSign(a: ZPoly): {
+    content: bigint;
+    primitive: ZPoly;
+};
+/** Normalize only by sign (units in Z are ±1). Does not strip content. */
+export declare function zNormalizeSign(aIn: ZPoly): ZPoly;
+/** Primitive part with positive leading coefficient. */
+export declare function zPrimitivePart(a: ZPoly): ZPoly;
+/** Pseudo-remainder of `a` by `b` over Z[x]. */
+export declare function zPseudoRemainder(aIn: ZPoly, bIn: ZPoly): ZPoly;
+/** Primitive PRS GCD over Z[x] with positive leading coefficient. */
+export declare function zGcdPrimitivePRS(fIn: ZPoly, gIn: ZPoly): ZPoly;
+/** Full GCD over Z[x], including gcd(content(f), content(g)). */
+export declare function zGcdFull(fIn: ZPoly, gIn: ZPoly): ZPoly;
+export declare function zDerivative(a: ZPoly): ZPoly;
+/** Multiply by x^k. */
+export declare function zShift(a: ZPoly, k: number): ZPoly;
+export type FpPoly = {
+    p: bigint;
+    coeffs: ZPoly;
+};
+export declare function fpAdd(a: FpPoly, b: FpPoly): FpPoly;
+export declare function fpSub(a: FpPoly, b: FpPoly): FpPoly;
+export declare function fpScale(a: FpPoly, k: bigint): FpPoly;
+export declare function fpMul(a: FpPoly, b: FpPoly): FpPoly;
+export declare function fpDivRem(a: FpPoly, b: FpPoly): {
+    q: FpPoly;
+    r: FpPoly;
+};
+export declare function fpGCD(a: FpPoly, b: FpPoly): FpPoly;
+/** Trim and reduce coefficients modulo m (does not mutate input). */
+export declare function zTrimMod(a: ZPoly, m: bigint): ZPoly;
+/** Map coefficients to symmetric representatives modulo m (each in (-m/2, m/2]). */
+export declare function zToSymmetricMod(poly: ZPoly, m: bigint): ZPoly;
+export declare function zAddMod(a: ZPoly, b: ZPoly, m: bigint): ZPoly;
+export declare function zSubMod(a: ZPoly, b: ZPoly, m: bigint): ZPoly;
+export declare function zScaleMod(a: ZPoly, k: bigint, m: bigint): ZPoly;
+export declare function zMulMod(a: ZPoly, b: ZPoly, m: bigint): ZPoly;
+/**
+ * Polynomial long division in (Z/mZ)[x] assuming the leading coefficient of b
+ * is invertible modulo m.
+ */
+export declare function zDivRemMod(a: ZPoly, b: ZPoly, m: bigint): {
+    q: ZPoly;
+    r: ZPoly;
+};
+export declare function isOnePoly(p: MultiPoly): boolean;
+/**
+ * Return a trimmed clone of p (removes zero coefficients).
+ * MultiPoly does not guarantee trimming after every operation; keep this
+ * as the single canonical normalization entry point for algorithms.
+ */
+export declare function mvNormalize(p: MultiPoly): MultiPoly;
+/**
+ * Divide by coefficient content, returning {content, primitive}.
+ * For the zero polynomial returns {0, 0}.
+ */
+export declare function mvDivideByCoeffContent(p: MultiPoly): {
+    content: bigint;
+    primitive: MultiPoly;
+};
+/**
+ * Normalize by extracting coefficient content and fixing sign so the
+ * lex-leading term coefficient is positive.
+ *
+ * - For 0 returns { content: 0, primitive: 0 }
+ * - For nonzero returns { content: c>=1, primitive } with:
+ *    - coeff-content(primitive)=1
+ *    - lex-leading term coefficient > 0
+ */
+export declare function mvNormalizePrimitiveSignLex(p: MultiPoly): {
+    content: bigint;
+    primitive: MultiPoly;
+};
+/**
+ * Normalize the sign of a polynomial that is univariate in `varIndex` without changing its content.
+ *
+ * IMPORTANT: This is intended for evaluation/interpolation pipelines where dividing by coefficient
+ * content would introduce a point-dependent scaling and break reconstruction.
+ */
+export declare function mvNormalizeSignUnivariateInVar(p: MultiPoly, varIndex: number): MultiPoly;
+export declare function denseToKey(exps: readonly number[]): string;
+/** Return the variable indices that occur in p, sorted ascending. */
+export declare function mvVariablesSorted(p: MultiPoly): number[];
+export declare function mapCombineInPlace<K, V>(dest: Map<K, V>, src: ReadonlyMap<K, V>, combine: (a: V, b: V) => V, isZero: (v: V) => boolean, zero: () => V): void;
+/** Add two polynomials. */
+export declare function addPoly(a: MultiPoly, b: MultiPoly): MultiPoly;
+/** Subtract b from a. */
+export declare function subPoly(a: MultiPoly, b: MultiPoly): MultiPoly;
+/** Negate polynomial. */
+export declare function negPoly(a: MultiPoly): MultiPoly;
+/** Multiply all coefficients of a polynomial by a scalar. */
+export declare function scalePoly(a: MultiPoly, k: bigint): MultiPoly;
+/** Multiply polynomials. */
+export declare function mulPoly(a: MultiPoly, b: MultiPoly): MultiPoly;
+/** Structural equality of two polynomials (assumes both are already trimmed/normalized). */
+export declare function equalPoly(a: MultiPoly, b: MultiPoly): boolean;
+/**
+ * Leading term in lex order (highest exponents lexicographically).
+ * Returns the dense exponent vector (length nVars) and its coefficient.
+ */
+export declare function leadTermLex(p: MultiPoly, nVars: number): {
+    exp: number[];
+    coeff: bigint;
+} | null;
+/**
+ * Compute a conservative number of variables from the support of one or more polynomials.
+ * Returns maxVarIndex+1 across all terms (or 0 if all are zero).
+ */
+export declare function mvNumVars(...polys: MultiPoly[]): number;
+/**
+ * Exact division A/B in Z[x0..] using the canonical lex-leading-term algorithm.
+ * Returns null if division is not exact.
+ */
+export declare function mvExactDiv(A: MultiPoly, B: MultiPoly): MultiPoly | null;
+/**
+ * Exact division by a monomial (single-term polynomial).
+ * Returns null if `m` is not a monomial or division is not exact.
+ */
+export declare function mvExactDivByMonomial(p: MultiPoly, m: MultiPoly): MultiPoly | null;
+export declare function monoDividesDense(a: readonly number[], b: readonly number[]): boolean;
+export declare function monoSubDense(b: readonly number[], a: readonly number[]): number[];
+/**
+ * Substitute a single variable (by index) with an integer value.
+ * The chosen variable's exponent is set to 0 in every term.
+ */
+export declare function substituteVarIndex(p: MultiPoly, varIndex: number, value: bigint): MultiPoly;
+/**
+ * Remove a variable index from a polynomial by shifting indices > varIndex down.
+ * (Assumes the removed variable is no longer used, but handles exponents safely.)
+ */
+export declare function removeVarIndex(p: MultiPoly, varIndex: number): MultiPoly;
+/**
+ * Add a variable index to a polynomial by shifting indices >= varIndex up.
+ */
+export declare function addVarIndex(p: MultiPoly, varIndex: number): MultiPoly;
+/** Convert univariate coefficient array (number, low→high) to MultiPoly in `varIndex`. */
+export declare function fromUnivariate(coeffs: number[], varIndex?: number): MultiPoly;
+/**
+ * Convert MultiPoly to univariate coefficient array (numbers) if it only has one variable.
+ * Returns null if polynomial has more than one variable.
+ */
+export declare function toUnivariate(p: MultiPoly, varIndex?: number): number[] | null;
+/**
+ * View multivariate polynomial as univariate in varIndex with polynomial coefficients.
+ * Returns array of [coefficient polynomial, degree] pairs sorted by degree.
+ */
+export declare function viewAsUnivariate(p: MultiPoly, varIndex: number): Array<[MultiPoly, number]>;
+/** Reconstruct polynomial from univariate view. */
+export declare function fromUnivariateView(terms: Array<[MultiPoly, number]>, varIndex: number): MultiPoly;
+/**
+ * Pseudo-division of multivariate polynomials viewed as univariate in `varIndex`.
+ * Returns [q, r] such that lc(b)^k * a = q*b + r with deg(r) < deg(b) in `varIndex`.
+ */
+export declare function pseudoDivide(a: MultiPoly, b: MultiPoly, varIndex: number): [MultiPoly, MultiPoly];
+/**
+ * Primitive GCD for multivariate polynomials, computed by viewing the inputs
+ * as univariate in `varIndex` with multivariate coefficients.
+ */
+export declare function multiPolyGCD(a: MultiPoly, b: MultiPoly, varIndex: number): MultiPoly;
+/**
+ * Content of a polynomial with respect to one variable, i.e. the gcd of the
+ * coefficient-polynomials in the univariate view.
+ */
+export declare function mvContentInVar(p: MultiPoly, varIndex: number): MultiPoly;
+/**
+ * Primitive part of a polynomial relative to the univariate view in `varIndex`.
+ */
+export declare function primitivePart(p: MultiPoly, varIndex: number): MultiPoly;
+/**
+ * Extract quadratic coefficients of `p` viewed as `A*v^2 + B*v + C`.
+ * Terms with degree > 2 in `v` are silently ignored.
+ */
+export declare function quadraticCoeffsInVar(p: MultiPoly, v: number): {
+    A: MultiPoly;
+    B: MultiPoly;
+    C: MultiPoly;
+};