nerdamer 2.0.0-rc.1 → 2.0.0

package/output/core/classes/parser/scripting/scope.d.ts

@@ -2,34 +2,7 @@ import { Scope } from '../../../common/classes/Scope';
 import { Expression } from '../../expression/Expression';
 import type { ExpressionInput, ParserEntity } from '../../../types';
 import type { DeferredFunctionArgument } from '../types';
-/**
- * Adds a known value to a variable in the parser
- * @param a
- * @param b
- */
-export declare function assign(a: ExpressionInput, b: ParserEntity | string): ParserEntity;
-/**
- * Converts colon-style LET bindings into the alternating name/value scopes consumed by LET.
- */
+export declare function assign(a: ExpressionInput, b: ParserEntity | string | DeferredFunctionArgument): ParserEntity;
 export declare function normalizeLetArguments(argumentScopes: Scope[]): Scope[];
-/**
- * Evaluates sequential local bindings and restores only those bindings after the body.
- *
- * Arguments are alternating variable/value pairs followed by a body expression. Each value
- * is evaluated after earlier bindings have been installed, so later initializers can reference
- * earlier locals. Ordinary assignment is reused for validation and storage. Any assignment to
- * a name not declared by LET keeps its normal parser behavior.
- *
- * @param args Deferred variable/value pairs followed by the deferred body.
- * @returns The body's result.
- */
 export declare function LET(...args: DeferredFunctionArgument[]): ParserEntity;
-/**
- * Removes a known parser value by variable name.
- *
- * Parser calls defer the argument so an assigned variable can be read as its name rather than
- * substituted value. Direct callers may still pass an Expression or string.
- *
- * @param x Variable name or deferred variable-name expression.
- */
 export declare function unassign(x: Expression | string | DeferredFunctionArgument): Expression;

package/output/core/classes/parser/scripting/scope.js

@@ -10,32 +10,41 @@ const Settings_1 = require("../../../Settings");
 const Expression_1 = require("../../expression/Expression");
 const utils_1 = require("../../expression/utils");
 const constants_1 = require("../constants");
+const controlFlowSignals_1 = require("../controlFlowSignals");
 const Parser_1 = require("../Parser");
 const Token_1 = require("../Token");
-/**
- * Adds a known value to a variable in the parser
- * @param a
- * @param b
- */
+const controlFlow_1 = require("./controlFlow");
 function assign(a, b) {
     a = Expression_1.Expression.create(a);
-    if (typeof b === 'string') {
-        b = Parser_1.Parser.parse(b);
-    }
-    // We can only assign to plain variables
     if (Expression_1.Expression.isExpression(a) && !a.isPlainVariable()) {
         throw new errors_1.UnexpectedInputError((0, errors_1.message)('plainVariableExpected', { input: String(a) }));
     }
-    // We cannot assign to restricted values
     if (Settings_1.RESTRICTED.includes(a.value)) {
         throw new errors_1.AssignmentError((0, errors_1.message)('restrictedVariableName', { name: a.value }));
     }
-    Parser_1.Parser.KNOWN_VALUES[a.value] = b;
-    return b;
+    let value;
+    try {
+        if (typeof b === 'function') {
+            value = b();
+        }
+        else if (typeof b === 'string') {
+            value = Parser_1.Parser.parse(b);
+        }
+        else {
+            value = b;
+        }
+    }
+    catch (error) {
+        if (controlFlowSignals_1.NullSignal.isNullSignal(error)) {
+            // A no-result RHS is assignment's one special case. It is equivalent to x:x:
+            // preserve an existing binding, or leave an unbound name unresolved.
+            return Parser_1.Parser.KNOWN_VALUES[a.value]?.copy() ?? a;
+        }
+        throw error;
+    }
+    Parser_1.Parser.KNOWN_VALUES[a.value] = value;
+    return value;
 }
-/**
- * Converts colon-style LET bindings into the alternating name/value scopes consumed by LET.
- */
 function normalizeLetArguments(argumentScopes) {
     const normalizedScopes = [];
     for (let i = 0; i < argumentScopes.length; i++) {
@@ -44,9 +53,7 @@ function normalizeLetArguments(argumentScopes) {
         if (i < argumentScopes.length - 1) {
             for (let j = 0; j < argumentScope.length; j++) {
                 const argumentToken = argumentScope[j];
-                if (Token_1.Token.isToken(argumentToken) &&
-                    argumentToken.type === Token_1.Token.OPERATOR &&
-                    argumentToken.value === constants_1.ASSIGN) {
+                if (Token_1.Token.isToken(argumentToken) && argumentToken.type === Token_1.Token.OPERATOR && argumentToken.value === constants_1.ASSIGN) {
                     assignmentIndex = j;
                     break;
                 }
@@ -69,17 +76,6 @@ function normalizeLetArguments(argumentScopes) {
     }
     return normalizedScopes;
 }
-/**
- * Evaluates sequential local bindings and restores only those bindings after the body.
- *
- * Arguments are alternating variable/value pairs followed by a body expression. Each value
- * is evaluated after earlier bindings have been installed, so later initializers can reference
- * earlier locals. Ordinary assignment is reused for validation and storage. Any assignment to
- * a name not declared by LET keeps its normal parser behavior.
- *
- * @param args Deferred variable/value pairs followed by the deferred body.
- * @returns The body's result.
- */
 function LET(...args) {
     if (args.length < 3 || args.length % 2 === 0) {
         throw new errors_1.ParserError((0, errors_1.message)('letRequiresBindingsAndBody'));
@@ -90,8 +86,6 @@ function LET(...args) {
     let retval;
     try {
         for (let i = 0; i < args.length - 1; i += 2) {
-            // Binding names are syntax, not values. Suppress both call-scoped and known-value
-            // substitution while resolving the plain variable name.
             const nameExpression = args[i]({ inheritValues: false, substitute: false });
             if (!Expression_1.Expression.isExpression(nameExpression)) {
                 throw new errors_1.UnexpectedInputError((0, errors_1.message)('plainVariableExpected', { input: nameExpression.text() }));
@@ -111,7 +105,17 @@ function LET(...args) {
                 localNames.push(name);
             }
         }
-        retval = args[args.length - 1]({ excludeValues: localNames });
+        try {
+            retval = args[args.length - 1]({ excludeValues: localNames });
+        }
+        catch (error) {
+            if ((0, controlFlow_1.shouldConsumeLocalReturn)() && controlFlow_1.ReturnSignal.isReturnSignal(error)) {
+                retval = error.value;
+            }
+            else {
+                throw error;
+            }
+        }
     }
     finally {
         for (const [name, value] of previousValues) {
@@ -123,14 +127,6 @@ function LET(...args) {
     }
     return retval;
 }
-/**
- * Removes a known parser value by variable name.
- *
- * Parser calls defer the argument so an assigned variable can be read as its name rather than
- * substituted value. Direct callers may still pass an Expression or string.
- *
- * @param x Variable name or deferred variable-name expression.
- */
 function unassign(x) {
     let variable;
     let name;

package/output/core/classes/parser/types.d.ts

@@ -8,11 +8,6 @@ import type Decimal from 'decimal.js';
  * The type used to defined a operation function for the parser
  */
 export type Operation = (a: ParserEntity, b?: ParserEntity) => ParserEntity;
-/**
- * The comma operation returns both operands so the parser can place them back
- * on the output stack as separate values.
- */
-export type CommaOperation = (a: ParserStackValue, b: ParserStackValue) => ParserStackValue[];
 /**
  * The type used to defined a prefix for the parser
  */
@@ -88,6 +83,11 @@ export type TextOptions = {
     decimal?: boolean;
     /** Significant-digit precision used when decimal output is requested. */
     precision?: number;
+    /**
+     * Render numeric values in scientific notation with exactly this many significant digits (1–1e9).
+     * Numeric powers use scientific notation only when the formatted exponent remains exact.
+     */
+    scientific?: number;
     /** Sort sum and product elements with {@link Expression.sortFunction} before rendering. */
     sort?: boolean;
     /** Parenthesize powers for output that will be embedded in JavaScript-style expressions. */

package/output/core/classes/parser/wrappers/IndexedReference.d.ts

@@ -18,14 +18,15 @@ export declare class IndexedReference {
     isEnumerable: boolean;
     constructor(target: ParserEntity, indices: number[] | string, targetName?: string | undefined);
     static isIndexedReference(obj: unknown): obj is IndexedReference;
-    copy(): import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../collection/Collection").Collection | import("../../matrix/Matrix").Matrix | Dictionary | import("../../equation/Equation").Equation;
+    copy(): import("../../collection/Collection").Collection | import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../matrix/Matrix").Matrix | import("../../equation/Equation").Equation | Dictionary;
     eq(other: ParserEntity): boolean;
-    evaluate(): import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../collection/Collection").Collection | import("../../matrix/Matrix").Matrix | Dictionary | import("../../equation/Equation").Equation;
-    expand(): import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../collection/Collection").Collection | import("../../matrix/Matrix").Matrix | Dictionary | import("../../equation/Equation").Equation;
+    evaluate(): import("../../collection/Collection").Collection | import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../matrix/Matrix").Matrix | import("../../equation/Equation").Equation | Dictionary;
+    expand(): import("../../collection/Collection").Collection | import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../matrix/Matrix").Matrix | import("../../equation/Equation").Equation | Dictionary;
     gt(other: ParserEntity): boolean;
     gte(other: ParserEntity): boolean;
     lt(other: ParserEntity): boolean;
     lte(other: ParserEntity): boolean;
     resolve(): ParserEntity;
+    set(value: ParserEntity): void;
     text(): string;
 }

package/output/core/classes/parser/wrappers/IndexedReference.js

@@ -61,6 +61,14 @@ class IndexedReference {
         }
         return this._resolved;
     }
+    set(value) {
+        if (typeof this.indices === 'string') {
+            this.target.__set__(this.indices, value);
+        }
+        else {
+            this.target.__set__(this.indices, value);
+        }
+    }
     text() {
         return this.resolve().text();
     }

package/output/core/classes/parser/wrappers/KeyValuePair.d.ts

@@ -14,8 +14,8 @@ export declare class KeyValuePair {
     static isKeyValuePair(obj: unknown): obj is KeyValuePair;
     copy(): KeyValuePair;
     eq(): boolean;
-    evaluate(): import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../collection/Collection").Collection | import("../../matrix/Matrix").Matrix | import("../../dictionary/Dictionary").Dictionary | import("../../equation/Equation").Equation;
-    expand(): import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../collection/Collection").Collection | import("../../matrix/Matrix").Matrix | import("../../dictionary/Dictionary").Dictionary | import("../../equation/Equation").Equation;
+    evaluate(): import("../../collection/Collection").Collection | import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../matrix/Matrix").Matrix | import("../../equation/Equation").Equation | import("../../dictionary/Dictionary").Dictionary;
+    expand(): import("../../collection/Collection").Collection | import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../matrix/Matrix").Matrix | import("../../equation/Equation").Equation | import("../../dictionary/Dictionary").Dictionary;
     gt(): boolean;
     gte(): boolean;
     lt(): boolean;

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

@@ -425,6 +425,9 @@ export declare class Polynomial {
     /**
      * Raises the polynomial to a power.
      *
+     * Exact non-negative integer powers use sparse polynomial arithmetic when the
+     * coefficient domain permits it. Other exponents retain symbolic expression behavior.
+     *
      * @param p - Exponent accepted by symbolic expression powers.
      * @returns A new polynomial parsed from the powered expression.
      * @throws {@link core!PolynomialError} Thrown when the powered result is not polynomial-like.
@@ -456,7 +459,8 @@ export declare class Polynomial {
      *
      * @param x - Multiplier.
      * @returns A new polynomial. Term multiplication copies this polynomial before
-     * updating its terms; polynomial multiplication rebuilds from symbolic expressions.
+     * updating its terms. Polynomial multiplication uses exact sparse arithmetic when
+     * both operands have numeric coefficients and otherwise preserves symbolic multiplication.
      */
     times(x: Term | Polynomial): Polynomial;
     /**

package/output/core/classes/polynomial/Polynomial.js

@@ -16,6 +16,7 @@ const Expression_1 = require("../expression/Expression");
 const shortcuts_1 = require("../expression/shortcuts");
 const constants_1 = require("../parser/constants");
 const Rational_1 = require("../rational/Rational");
+const SparsePolynomialAdapter_1 = require("./SparsePolynomialAdapter");
 const Term_1 = require("./Term");
 const utils_2 = require("./utils");
 /**
@@ -80,7 +81,7 @@ class Polynomial {
      */
     constructor(p, vars, ordering) {
         if (Polynomial.isPolynomial(p)) {
-            this.expression = new Expression_1.Expression(p.expression);
+            this.expression = p.expression.copy();
             this.variables = [...p.variables];
             this.ordering = p.ordering;
             this.isMultivariate = p.isMultivariate;
@@ -101,8 +102,10 @@ class Polynomial {
             }
             // Expand the expression but only if needed. This will be needed if the value has a bracket
             // or if the expression has a power greater than one.
-            if (x.value.includes('(') || (x.isSum() && x.getPower().gt('1'))) {
+            let expandedForCoefficients = false;
+            if (x.value.includes('(') || (x.isSum() && x.getPower().gt((0, shortcuts_1.one)()))) {
                 x = (0, expand_1.expand)(x);
+                expandedForCoefficients = true;
             }
             this.expression = x;
             let variables;
@@ -123,7 +126,7 @@ class Polynomial {
             // Calculate the coefficients. Coeffs will come back as a collection of objects so for instance
             // a*x*y + b*x^2*y will come back as [a, '1,1'] & [b, '2,1']. It's preferred to have it in object form
             // TODO: this should probably be done with `coeffs`.
-            x.coeffs(...this.variables).each((coeff, powers) => {
+            (0, analysis_1.coeffs)(x, this.variables, undefined, !expandedForCoefficients).each((coeff, powers) => {
                 this.terms.push(new Term_1.Term(coeff, powers, this.variables));
             });
             // Set a blank array if none was provided or calculated
@@ -169,7 +172,7 @@ class Polynomial {
                     for (const variable of vars) {
                         powers[variable] = i;
                     }
-                    retval.terms.push(new Term_1.Term(new Expression_1.Expression(coefficient), powers, vars));
+                    retval.terms.push(new Term_1.Term(coefficient.copy(), powers, vars));
                 }
             }
             retval.order();
@@ -985,12 +988,35 @@ class Polynomial {
     /**
      * Raises the polynomial to a power.
      *
+     * Exact non-negative integer powers use sparse polynomial arithmetic when the
+     * coefficient domain permits it. Other exponents retain symbolic expression behavior.
+     *
      * @param p - Exponent accepted by symbolic expression powers.
      * @returns A new polynomial parsed from the powered expression.
      * @throws {@link core!PolynomialError} Thrown when the powered result is not polynomial-like.
      */
     pow(p) {
-        return new Polynomial(this.getExpression().pow(p), undefined, this.ordering);
+        const exponent = Expression_1.Expression.create(p);
+        const source = this.getExpression();
+        let sparseResult;
+        if (exponent.isNUM() &&
+            exponent.isInteger() &&
+            exponent.sign() >= 0 &&
+            !source.hasDecimal()) {
+            try {
+                const power = exponent.getMultiplier().numerator;
+                const variables = [...this.variables];
+                const converted = (0, SparsePolynomialAdapter_1.expressionToIntegerSparsePolynomial)(source, variables);
+                const denominator = converted.denominator ** power;
+                let expression = (0, SparsePolynomialAdapter_1.sparsePolynomialToExpression)(converted.polynomial.pow(power), variables);
+                if (denominator !== 1n) {
+                    expression = expression.div(Expression_1.Expression.Number(denominator));
+                }
+                sparseResult = new Polynomial(expression, undefined, this.ordering);
+            }
+            catch { }
+        }
+        return sparseResult ?? new Polynomial(source.pow(exponent), undefined, this.ordering);
     }
     /**
      * Sorts the terms by {@link revlex} reverse lexicographic order
@@ -1053,7 +1079,8 @@ class Polynomial {
      *
      * @param x - Multiplier.
      * @returns A new polynomial. Term multiplication copies this polynomial before
-     * updating its terms; polynomial multiplication rebuilds from symbolic expressions.
+     * updating its terms. Polynomial multiplication uses exact sparse arithmetic when
+     * both operands have numeric coefficients and otherwise preserves symbolic multiplication.
      */
     times(x) {
         let retval;
@@ -1071,7 +1098,26 @@ class Polynomial {
             retval.updateExpression();
         }
         else {
-            retval = new Polynomial(this.getExpression().times(x.getExpression()), undefined, this.ordering);
+            const leftExpression = this.getExpression();
+            const rightExpression = x.getExpression();
+            let sparseResult;
+            if (!leftExpression.hasDecimal() && !rightExpression.hasDecimal()) {
+                try {
+                    const variables = [...new Set([...this.variables, ...x.variables])].sort();
+                    const left = (0, SparsePolynomialAdapter_1.expressionToIntegerSparsePolynomial)(leftExpression, variables);
+                    const right = (0, SparsePolynomialAdapter_1.expressionToIntegerSparsePolynomial)(rightExpression, variables);
+                    const denominator = left.denominator * right.denominator;
+                    let expression = (0, SparsePolynomialAdapter_1.sparsePolynomialToExpression)(left.polynomial.multiply(right.polynomial), variables);
+                    if (denominator !== 1n) {
+                        expression = expression.div(Expression_1.Expression.Number(denominator));
+                    }
+                    sparseResult = new Polynomial(expression, undefined, this.ordering);
+                }
+                catch { }
+            }
+            retval =
+                sparseResult ??
+                    new Polynomial(leftExpression.times(rightExpression), undefined, this.ordering);
         }
         return retval;
     }

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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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[];
+}