nerdamer 1.1.13 → 2.0.0-rc.2

package/output/core/classes/polynomial/SparsePolynomial.d.ts

@@ -0,0 +1,221 @@
+/**
+ * @module sparsePolynomial
+ *
+ * Sparse polynomial storage with exact bigint coefficients and exponents.
+ *
+ * External references consulted for monomial representation and ordering:
+ * - SymPy monomial operations:
+ *   https://github.com/sympy/sympy/blob/120ee85f346f6292b763cc195afda4f907260d4a/sympy/polys/monomials.py
+ * - SymPy lexicographic, graded lexicographic, and graded reverse lexicographic orders:
+ *   https://github.com/sympy/sympy/blob/120ee85f346f6292b763cc195afda4f907260d4a/sympy/polys/orderings.py
+ * - SymPy coefficient content and primitive-part operations:
+ *   https://github.com/sympy/sympy/blob/120ee85f346f6292b763cc195afda4f907260d4a/sympy/polys/densetools.py
+ * - SymPy sparse polynomial division:
+ *   https://github.com/sympy/sympy/blob/120ee85f346f6292b763cc195afda4f907260d4a/sympy/polys/sparsetools.py
+ */
+export type MonomialOrder = 'lex' | 'grlex' | 'grevlex';
+export type SparsePolynomialTerm = Readonly<{
+    coefficient: bigint;
+    exponents: readonly bigint[];
+}>;
+/**
+ * Sparse polynomial with bigint coefficients and bigint exponents.
+ *
+ * The variable count is part of the polynomial rather than inferred from its support.
+ * Exponent vectors therefore have one exact entry for every variable, including zero
+ * polynomials and constants. The internal map key is an encoding detail and is never
+ * exposed or parsed by polynomial algorithms.
+ */
+export declare class SparsePolynomial {
+    private readonly termsByKey;
+    readonly variableCount: number;
+    /**
+     * Creates a sparse polynomial in a ring with a fixed number of variables.
+     *
+     * Duplicate monomials are combined and zero coefficients are removed.
+     *
+     * @param variableCount - Number of variables in the polynomial ring.
+     * @param terms - Terms with exponent vectors of exactly variableCount entries.
+     */
+    constructor(variableCount: number, terms?: Iterable<SparsePolynomialTerm>);
+    /**
+     * Verifies that an exponent vector belongs to a ring and contains only
+     * non-negative exact integer exponents.
+     */
+    private static assertExponents;
+    /**
+     * Compares exponent vectors using the three global monomial orders required by
+     * the polynomial algorithms.
+     */
+    static compareMonomials(a: readonly bigint[], b: readonly bigint[], order: MonomialOrder): number;
+    /** Creates a constant polynomial in a ring with variableCount variables. */
+    static constant(variableCount: number, coefficient: bigint): SparsePolynomial;
+    /**
+     * Encodes an exponent vector only for map identity.
+     *
+     * The polynomial retains the exponent vector beside the key, so no decoder exists.
+     */
+    private static keyOf;
+    /** Creates a one-term polynomial. */
+    static monomial(variableCount: number, coefficient: bigint, exponents: readonly bigint[]): SparsePolynomial;
+    /** Creates the variable at variableIndex with coefficient one. */
+    static variable(variableCount: number, variableIndex: number): SparsePolynomial;
+    /** Creates the zero polynomial in a ring with variableCount variables. */
+    static zero(variableCount: number): SparsePolynomial;
+    /**
+     * Adds another polynomial in the same ring.
+     *
+     * Like monomials are combined exactly and zero coefficients are removed from
+     * the returned polynomial.
+     */
+    add(other: SparsePolynomial): SparsePolynomial;
+    /**
+     * Returns the coefficient of one monomial.
+     *
+     * @param exponents - Exact exponent vector for the requested monomial.
+     */
+    coefficient(exponents: readonly bigint[]): bigint;
+    /**
+     * Returns the coefficient polynomial at one exact power of a selected variable.
+     *
+     * The selected variable remains in the ring with exponent zero so recursive
+     * algorithms can preserve the original coordinate layout.
+     */
+    coefficientIn(variableIndex: number, exponent: bigint): SparsePolynomial;
+    /** Returns the constant coefficient, or zero when the constant monomial is absent. */
+    constantTerm(): bigint;
+    /**
+     * Returns the positive greatest common divisor of all coefficients.
+     *
+     * The zero polynomial has coefficient content zero.
+     */
+    content(): bigint;
+    /**
+     * Returns the degree in one variable.
+     *
+     * The zero polynomial has no degree and returns null.
+     */
+    degree(variableIndex: number): bigint | null;
+    /**
+     * Differentiates with respect to one ring variable.
+     *
+     * Coefficients and exponents stay in bigint arithmetic, including exponents
+     * above JavaScript's safe-integer range.
+     */
+    derivative(variableIndex: number): SparsePolynomial;
+    /**
+     * Divides every term by one monomial when the quotient stays in the integer
+     * polynomial ring.
+     *
+     * Returns null when any coefficient or exponent is not exactly divisible.
+     */
+    divideByMonomial(divisor: SparsePolynomialTerm): SparsePolynomial | null;
+    /**
+     * Divides all coefficients by an integer scalar.
+     *
+     * @throws RangeError When the scalar is zero or does not divide every coefficient.
+     */
+    divideByScalarExact(divisor: bigint): SparsePolynomial;
+    /**
+     * Divides by one polynomial using exact integer coefficient arithmetic.
+     *
+     * Returns null as soon as the current leading term is not exactly divisible
+     * by the divisor leading term. A successful result therefore has zero
+     * remainder in the selected monomial order.
+     */
+    divideExact(divisor: SparsePolynomial, order?: MonomialOrder): SparsePolynomial | null;
+    /** Returns whether both polynomials have the same ring and exact nonzero terms. */
+    equals(other: SparsePolynomial): boolean;
+    /**
+     * Substitutes one variable with an exact integer while retaining the same ring.
+     *
+     * Terms that become like terms after substitution are combined in the result.
+     */
+    evaluateVariable(variableIndex: number, value: bigint): SparsePolynomial;
+    /**
+     * Substitutes several variables with exact integers in one sparse traversal.
+     *
+     * The selected coordinates remain in the polynomial ring with exponent zero.
+     */
+    evaluateVariables(variableIndices: readonly number[], values: readonly bigint[]): SparsePolynomial;
+    /** Returns whether the polynomial is zero or contains only a constant term. */
+    isConstant(): boolean;
+    /** Returns whether the polynomial has no nonzero terms. */
+    isZero(): boolean;
+    /**
+     * Returns the coefficient polynomial of the highest power of one variable.
+     *
+     * The selected coordinate remains present with exponent zero.
+     */
+    leadingCoefficientIn(variableIndex: number): SparsePolynomial | null;
+    /**
+     * Returns the leading term under the requested monomial order.
+     *
+     * Variable priority follows exponent-vector index order.
+     */
+    leadingTerm(order?: MonomialOrder): SparsePolynomialTerm | null;
+    /**
+     * Applies an exact bigint transformation to every stored coefficient while
+     * preserving the existing monomial keys and exponent vectors.
+     */
+    mapCoefficients(mapper: (coefficient: bigint) => bigint): SparsePolynomial;
+    /** Returns the largest absolute coefficient, or zero for the zero polynomial. */
+    maxAbsoluteCoefficient(): bigint;
+    /**
+     * Multiplies by another polynomial in the same ring.
+     *
+     * Monomial exponents are added as bigints. The constructor combines products
+     * that land on the same monomial and removes coefficients that cancel to zero.
+     */
+    multiply(other: SparsePolynomial): SparsePolynomial;
+    /**
+     * Computes the difference of two monomial-scaled polynomials in one sparse
+     * traversal. This avoids constructing the monomial factors and multiplication
+     * results used by fraction-free S-polynomials.
+     */
+    monomialScaleSubtract(leftScalar: bigint, leftMonomialExponents: readonly bigint[], other: SparsePolynomial, rightScalar: bigint, rightMonomialExponents: readonly bigint[]): SparsePolynomial;
+    /**
+     * Computes a scaled subtraction where the right polynomial is also multiplied
+     * by one monomial. This avoids constructing the two scaled intermediate
+     * polynomials used by fraction-free reduction.
+     */
+    scaleSubtractMonomial(leftScalar: bigint, other: SparsePolynomial, rightScalar: bigint, monomialExponents: readonly bigint[]): SparsePolynomial;
+    /**
+     * Returns the additive inverse of this polynomial.
+     */
+    negate(): SparsePolynomial;
+    /**
+     * Makes the leading coefficient positive without changing coefficient content.
+     */
+    normalizeLeadingSign(order?: MonomialOrder): SparsePolynomial;
+    /** Raises the polynomial to a non-negative exact integer power. */
+    pow(exponent: bigint): SparsePolynomial;
+    /**
+     * Divides by positive coefficient content while preserving the polynomial sign.
+     */
+    primitivePart(): SparsePolynomial;
+    /**
+     * Multiplies every coefficient by an exact integer scalar.
+     */
+    scale(scalar: bigint): SparsePolynomial;
+    /**
+     * Subtracts another polynomial in the same ring.
+     */
+    subtract(other: SparsePolynomial): SparsePolynomial;
+    /** Number of stored nonzero terms. */
+    get termCount(): number;
+    /**
+     * Returns a copy of the stored terms.
+     *
+     * The exponent arrays themselves are frozen so callers cannot alter polynomial storage.
+     */
+    terms(): readonly SparsePolynomialTerm[];
+    /**
+     * Returns the largest total degree among the stored monomials.
+     *
+     * The zero polynomial has no total degree and returns null.
+     */
+    totalDegree(): bigint | null;
+    /** Returns the variable indices that occur with a positive exponent. */
+    variables(): readonly number[];
+}