nerdamer 1.1.13 → 2.0.0-rc.1

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

@@ -0,0 +1,500 @@
+import Decimal from 'decimal.js';
+import { Expression } from '../expression/Expression';
+import { POLYNOMIAL } from '../parser/constants';
+import { Rational } from '../rational/Rational';
+import { Term } from './Term';
+import type { ExpressionInput, NerdamerInput } from '../../types';
+/** Monomial ordering labels understood by {@link Polynomial.order}. */
+export type Ordering = 'none' | 'deg' | 'lex' | 'revlex' | 'grlex' | 'grevlex' | 'byvar';
+/** Inputs accepted by polynomial conversion helpers. */
+export type PolyType = string | Polynomial | Expression;
+/** Internal expression-valued power map retained for compatibility. */
+export type TermPowerObject = Record<string, Expression>;
+export type VariableFrequency = {
+    variable: string;
+    count: number;
+    deg: number;
+};
+/** Exact values accepted when evaluating a polynomial. */
+export type EvalInputType = number | bigint | Rational;
+/**
+ * Represents a polynomial as ordered {@link Term} objects with symbolic coefficients.
+ *
+ * @remarks
+ * Construction accepts polynomial-like expression input, expands bracketed or powered
+ * sums when necessary, and collects coefficients using either the supplied variable
+ * order or the expression's alphabetically sorted variables. Negative variable powers
+ * and other non-polynomial forms are rejected.
+ *
+ * The object is mutable: ordering methods sort {@link Polynomial.terms} in place, and
+ * `gcdFree(..., true)` edits term coefficients and powers. Arithmetic methods such as
+ * {@link Polynomial.plus}, {@link Polynomial.minus}, and {@link Polynomial.times}
+ * normally return new polynomials. Public arrays and terms expose mutable internal
+ * references; callers that edit them directly must preserve ordering and keep cached
+ * term data consistent.
+ *
+ * Coefficients are stored as `Expression` values. Operations such as
+ * {@link Polynomial.evaluate} convert supplied values to {@link Rational} and use exact
+ * rational arithmetic; {@link Polynomial.at} and numeric array conversions instead use
+ * JavaScript numbers and may lose precision.
+ *
+ * Supported orderings include lexicographic, reverse lexicographic, graded
+ * lexicographic, and graded reverse lexicographic order. Univariate polynomials always
+ * use descending degree order regardless of the requested multivariate ordering.
+ *
+ * @example
+ * ```ts
+ * const polynomial = new Polynomial('x^2 + 2*x + 1', ['x']);
+ *
+ * polynomial.deg();                    // 2
+ * polynomial.toArray().map(String);    // ["1", "2", "1"]
+ * polynomial.evaluateToRational({ x: 2 }).toString(); // "5"
+ * ```
+ */
+export declare class Polynomial {
+    /** Default ordering chosen for newly parsed multivariate polynomials. */
+    static defaultOrdering: Ordering;
+    /** Runtime tag used by Nerdamer's polynomial type guard. */
+    dataType: typeof POLYNOMIAL;
+    /** Expression retained from construction or the most recent explicit rebuild. */
+    expression: Expression;
+    /** Whether the polynomial's variable list contains more than one variable. */
+    isMultivariate: boolean;
+    /** Current monomial ordering of {@link terms}. */
+    ordering: Ordering;
+    /** Terms in their current monomial order. The array is mutable. */
+    terms: Term[];
+    /** Variable order used to interpret term multidegrees. The array is mutable. */
+    variables: string[];
+    /**
+     * Constructs a polynomial from expression input or deep-copies another polynomial.
+     *
+     * @param p - Polynomial-like input or an existing polynomial to copy.
+     * @param vars - Variable names in the order used for multidegrees and monomial comparison.
+     * When omitted, variables are collected and sorted alphabetically.
+     * @param ordering - Requested monomial ordering for parsed multivariate input.
+     * @throws {@link core!PolynomialError} Thrown when the parsed expression is not polynomial-like.
+     * @throws {@link core!UnsupportedOperationError} Thrown when input cannot be converted to
+     * an expression supported by the polynomial representation.
+     */
+    constructor(p: ExpressionInput | Polynomial, vars?: string[], ordering?: Ordering);
+    /**
+     * Constructs a polynomial from dense ascending-power coefficients.
+     *
+     * @remarks
+     * Entry `arr[i]` becomes the coefficient of power `i`. When multiple variable names
+     * are supplied, their product is treated as one repeated base; this is not a general
+     * multidimensional coefficient tensor.
+     *
+     * @param arr - Coefficients ordered from constant term upward.
+     * @param vars - Variable names forming the polynomial base.
+     */
+    static fromArray(arr: NerdamerInput[], vars: string[]): Polynomial;
+    /** Reconstructs dense coefficients through the normal constructor when powers overlap coefficients. */
+    private static fromArrayCanonicalized;
+    /**
+     * Sorts by graded lexicographic order. The abs(power) is first compared and then
+     * revlex is used to break ties.
+     *
+     * @param a - First term to compare.
+     * @param b - Second term to compare.
+     * @returns A comparator value suitable for `Array.sort`.
+     */
+    static grevlex(a: Term, b: Term): number;
+    /**
+     * Sorts by graded lexicographic order. The abs(power) is first compared and then
+     * lex is used to break ties.
+     *
+     * @param a - First term to compare.
+     * @param b - Second term to compare.
+     * @returns A comparator value suitable for `Array.sort`.
+     */
+    static grlex(a: Term, b: Term): 1 | -1;
+    /**
+     * Checks if the given object is a Polynomial
+     *
+     * @param obj - Value to test.
+     * @returns Whether `obj` carries Nerdamer's polynomial discriminator.
+     */
+    static isPolynomial(obj: unknown): obj is Polynomial;
+    /**
+     * Sorts by lexicographic order. The power tuples are subtracted and the first
+     * non-negative value from the left is used to sort. Note that variables are
+     * first sorted in alphabetical order.
+     *
+     * @param a - First term to compare.
+     * @param b - Second term to compare.
+     * @returns A comparator value suitable for `Array.sort`.
+     */
+    static lex(a: Term, b: Term): 1 | -1;
+    /**
+     * Sorts an array given a specific ordering using their LT
+     *
+     * @param polyArray - Polynomials to reorder. The array itself is sorted in place.
+     * @param ordering - Monomial ordering used for each polynomial and its leading term.
+     * @returns The same sorted array after each polynomial has also been reordered.
+     */
+    static polyArraySort(polyArray: Polynomial[], ordering?: Ordering): Polynomial[];
+    /**
+     * Converts a Rational to a string suitable for polynomial construction.
+     * Handles both integers and fractions.
+     *
+     * @param r - Rational value to convert.
+     * @returns Parser text preserving an integer or fraction exactly.
+     */
+    private static rationalToString;
+    /**
+     * Sorts by reverse lexicographic order. The power tuples are subtracted and the first
+     * non-negative value from the right is used to sort
+     *
+     * @param a - First term to compare.
+     * @param b - Second term to compare.
+     * @returns A comparator value suitable for `Array.sort`.
+     */
+    static revlex(a: Term, b: Term): number;
+    /**
+     * Fetches the expression from the given object.
+     *
+     * @param p - Polynomial, expression, or parser text to convert.
+     * @returns The polynomial's stored expression reference, or the parsed expression for
+     * non-polynomial input.
+     */
+    static toExpression(p: PolyType): Expression;
+    /**
+     * Converts a string to a Polynomial. If a polynomial is provided, it's returned untouched.
+     * If a polynomial is provided and no ordering, then the polynomial's ordering will be used.
+     * If no ordering is provided for all others then the Polynomial.defaultOrdering will be used.
+     *
+     * @param p - Value to convert.
+     * @param ordering - Ordering to apply. Passing an existing polynomial may reorder it in place.
+     * @param variables - Variable order used only when constructing a new polynomial.
+     * @returns The existing polynomial or a newly constructed one.
+     */
+    static toPolynomial(p: PolyType, ordering?: Ordering, variables?: string[]): Polynomial;
+    /**
+     * Creates a copy and adds or subtracts every supplied term.
+     *
+     * @param x - Term or polynomial whose terms should be combined.
+     * @param action - Whether matching coefficients are added or subtracted.
+     * @returns A new combined polynomial.
+     */
+    private append;
+    /**
+     * Adds or removes a term from the terms array of the polynomial
+     *
+     * @param t - Term to combine or append.
+     * @param action - Coefficient operation for a matching term.
+     */
+    private appendTerm;
+    private monomialGCDTerm;
+    private updateExpression;
+    /**
+     * Numerically evaluates the univariate polynomial at a given point
+     * @param n - JavaScript number at which to evaluate the sole variable.
+     * @returns A JavaScript-number approximation.
+     * @throws {@link core!UnsupportedOperationError} Thrown for multivariate polynomials.
+     */
+    at(n: number): number;
+    /**
+     * Collects coefficients by power or multidegree.
+     *
+     * @param variable - Optional single main variable. When omitted, keys use all
+     * polynomial variables in their stored order.
+     * @returns A mutable coefficient object whose expressions are derived from this polynomial.
+     */
+    coeffs(variable?: string): import("../expression/CoeffObject").CoeffObject;
+    /**
+     * Returns the positive variable powers shared by every term.
+     *
+     * @returns A new variable-to-minimum-power record; variables absent from any term are omitted.
+     */
+    commonTermVariables(): {
+        [variable: string]: number;
+    };
+    /**
+     * Returns the coefficient of the trailing constant term.
+     *
+     * @returns The stored coefficient reference when a constant term is present, otherwise
+     * a new zero expression.
+     */
+    constantTerm(): Expression;
+    /**
+     * Returns the content of the polynomial (GCD of all coefficients).
+     * Does not rely on the Expression class.
+     *
+     * @returns A new exact rational greatest common divisor of the numeric coefficients.
+     */
+    content(): Rational;
+    /**
+     * Returns the degree of the polynomial.
+     *
+     * With no variable, this is the total degree: the largest sum of powers in any term.
+     * When a variable is supplied, this is the largest power of that variable across all
+     * terms, with every other variable treated as part of the coefficient.
+     *
+     * @param variable - Optional variable whose degree should be returned.
+     * @returns The total degree, or the degree with respect to `variable`.
+     */
+    deg(variable?: string): number;
+    /**
+     * Performs a derivative with respect to a variable using Term-based operations.
+     * Does not rely on the Expression class for differentiation.
+     *
+     * @param v - Variable to differentiate; defaults to the first stored variable.
+     * @param n - Non-negative derivative order.
+     * @returns A newly constructed polynomial; order zero returns a deep copy.
+     */
+    diff(v?: string, n?: number): Polynomial;
+    /**
+     * Divides this polynomial by another polynomial.
+     *
+     * @param p - Divisor polynomial.
+     * @returns A two-element array containing quotient and remainder as new polynomials.
+     */
+    div(p: Polynomial): Polynomial[];
+    /**
+     * Checks to see if a polynomial divides the given polynomial
+     *
+     * @param p - Polynomial whose leading term is tested as the dividend.
+     * @returns Whether this polynomial's leading term divides `p`'s leading term. This is
+     * a monomial divisibility test, not proof that the complete polynomial divides `p`.
+     */
+    divides(p: Polynomial): boolean;
+    /**
+     * Checks if two polynomials are equal
+     *
+     * @param p - Polynomial to compare.
+     * @returns Whether subtracting `p` produces the zero polynomial.
+     */
+    eq(p: Polynomial): boolean;
+    /**
+     * Evaluates the polynomial at given values using Term-based operations.
+     * Supports partial evaluation (substituting some variables while keeping others symbolic).
+     * Does not rely on the Expression class for computation.
+     *
+     * @param values - Variable names mapped to exact rational-compatible values.
+     * @returns A new partially evaluated polynomial; unmentioned variables remain symbolic.
+     */
+    evaluate(values: {
+        [variable: string]: EvalInputType;
+    }): Polynomial;
+    /**
+     * Numerically evaluates the polynomial at given values.
+     * All variables must be provided values.
+     *
+     * @param values - Values for every variable stored by the polynomial.
+     * @returns The exact rational result.
+     * @throws {@link core!UnsupportedOperationError} Thrown when any stored variable is missing.
+     */
+    evaluateToRational(values: {
+        [variable: string]: EvalInputType;
+    }): Rational;
+    /**
+     * Divides all terms by their exact numeric content and optionally their common monomial.
+     *
+     * @param reduceVariables - Also subtract the minimum shared positive power of each variable.
+     * @param mutate - Modify and return this polynomial instead of a deep copy.
+     * @returns The normalized target polynomial.
+     */
+    gcdFree(reduceVariables?: boolean, mutate?: boolean): Polynomial;
+    /**
+     * Returns the expression retained by the polynomial.
+     *
+     * @remarks
+     * This is an internal reference, not a copy. The term array is the operative
+     * representation for many methods, and direct term mutation is not guaranteed to
+     * rebuild this stored expression automatically.
+     */
+    getExpression(): Expression;
+    /**
+     * Sorts the terms by graded lexicographic order
+     * grevlex first compares their powers. If their powers are equal then it breaks ties using {@link revlex} reverse lexicographic order.
+     *
+     * @returns This polynomial after sorting its terms in place.
+     */
+    grevlexSort(): this;
+    /**
+     * Sorts the terms by graded lexicographic order
+     * grlex first compares their powers. If their powers are equal then it breaks ties using {@link lex} lexicographic order.
+     *
+     * @returns This polynomial after sorting its terms in place.
+     */
+    grlexSort(): this;
+    /**
+     * Tests whether the polynomial consists of one constant term.
+     *
+     * @returns `true` only for the one-term constant representation.
+     */
+    isConstant(): boolean;
+    /**
+     * Tests whether this polynomial has no terms or a zero leading term.
+     *
+     * @returns Whether the current term representation is zero.
+     */
+    isZero(): boolean;
+    /**
+     * Returns the leading coefficient under the current ordering.
+     *
+     * @returns The leading term's internal coefficient reference.
+     */
+    LC(): Expression;
+    /**
+     * Sorts the terms by {@link lex} lexicographic order
+     *
+     * @returns This polynomial after sorting its terms in place.
+     */
+    lexSort(): this;
+    /**
+     * Returns the leading monomial with unit coefficient.
+     *
+     * @returns A new term with copied powers and variables.
+     */
+    LM(): Term;
+    /**
+     * Returns the leading term under the current ordering.
+     *
+     * @returns The internal first term reference.
+     */
+    LT(): Term;
+    /**
+     * Gets the maximum variable occurrence in the polynomial. If two or more variables have
+     * an equal number of occurrences then they will be included in the set
+     *
+     * @returns A new record containing every variable tied for the greatest term-occurrence count.
+     * @example
+     * ```ts
+     * new Polynomial('q^3*a+2*q^2*a').maxVariableFrequency();
+     * // { a: { variable: 'a', count: 2, deg: 2 },
+     * //   q: { variable: 'q', count: 2, deg: 5 } }
+     * ```
+     */
+    maxVariableFrequency(): Record<string | number, VariableFrequency>;
+    /**
+     * Subtracts a Polynomial or a Term
+     *
+     * @param x - Term or polynomial to subtract.
+     * @returns A new polynomial. Both operands are left unchanged.
+     */
+    minus(x: Term | Polynomial): Polynomial;
+    /**
+     * Reduces each collected coefficient modulo `n`.
+     *
+     * @remarks
+     * The polynomial itself is not modified. The returned coefficient object is derived from
+     * the current polynomial and stores the reduced coefficient expressions at the same power
+     * keys.
+     *
+     * @param n - Modulus passed to the symbolic `mod` operation.
+     * @returns A coefficient object containing the coefficient remainders.
+     */
+    mod(n: ExpressionInput): import("../expression/CoeffObject").CoeffObject;
+    /**
+     * Returns a copy with the leading nonconstant coefficient normalized to one.
+     *
+     * Constant polynomials are copied without coefficient normalization.
+     *
+     * @returns A new polynomial with a unit leading coefficient when normalization applies.
+     */
+    monic(): Polynomial;
+    /**
+     * Returns the leading term's multidegree under the current ordering.
+     *
+     * @returns The leading term's cached internal multidegree array.
+     */
+    multideg(): number[] | undefined;
+    /**
+     * Gets all the numeric coefficients in the polynomial as Rationals.
+     *
+     * @returns New array containing each term coefficient's internal rational multiplier.
+     */
+    numericCoeffs(): Rational[];
+    /**
+     * Reorders the polynomial in the requested ordering if it's not already in that particular ordering.
+     *
+     * @param ordering - Requested multivariate ordering. Univariate input is always degree-sorted.
+     * @returns This polynomial after sorting its term array in place.
+     */
+    order(ordering?: Ordering): this;
+    /**
+     * Adds a Polynomial or a Term.
+     *
+     * @param x - Term or polynomial to add.
+     * @returns A new polynomial. Both operands are left unchanged.
+     */
+    plus(x: Term | Polynomial): Polynomial;
+    /**
+     * Raises the polynomial to a power.
+     *
+     * @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: ExpressionInput): Polynomial;
+    /**
+     * Sorts the terms by {@link revlex} reverse lexicographic order
+     *
+     * @returns This polynomial after sorting its terms in place.
+     */
+    revlexSort(): this;
+    /**
+     * Sorts the terms in the standard form of decreasing powers.
+     */
+    sort(): this;
+    stripMonomialGCD(other: Polynomial): {
+        mGCD: Polynomial;
+        p: Polynomial;
+        q: Polynomial;
+    };
+    /**
+     * Formats the current ordered terms as canonical parser text.
+     *
+     * @returns `"0"` for an empty/zero term representation, otherwise the joined term text.
+     */
+    text(): string;
+    /**
+     * Multiplies this polynomial by a term or polynomial.
+     *
+     * @param x - Multiplier.
+     * @returns A new polynomial. Term multiplication copies this polynomial before
+     * updating its terms; polynomial multiplication rebuilds from symbolic expressions.
+     */
+    times(x: Term | Polynomial): Polynomial;
+    /**
+     * Converts univariate coefficients to a dense ascending-power array.
+     *
+     * @param asNumbers - Convert each coefficient through JavaScript `Number`.
+     * @param variable - Optional variable to collect as the dense power index.
+     * @returns New coefficient array with missing powers filled by zero expressions.
+     */
+    toArray(asNumbers: false, variable?: string): Expression[];
+    toArray(asNumbers: true, variable?: string): number[];
+    toArray(): Expression[];
+    /**
+     * Converts dense coefficients to numerator `bigint` values.
+     *
+     * @param assertInZ - Reject coefficients whose denominator is not one.
+     * @param variable - Optional variable to collect as the dense power index.
+     * @returns New ascending-power array of coefficient numerators.
+     * @throws Error Thrown when `assertInZ` is true and a coefficient is non-integral.
+     */
+    toBigIntArray(assertInZ?: boolean, variable?: string): bigint[];
+    /**
+     * Converts dense coefficients to new `Decimal` values using their expression text.
+     *
+     * @returns An ascending-power decimal coefficient array.
+     */
+    toDecimalArray(): Decimal[];
+    /**
+     * Returns the polynomial in a form for easy debugging.
+     *
+     * @returns The same canonical term text as {@link Polynomial.text}.
+     */
+    toString(): string;
+    /**
+     * Counts each variable's term occurrences and accumulated degree.
+     *
+     * @returns A new record keyed by variable. Each entry reports its name, number of
+     * nonzero-power terms, and sum of powers across those terms.
+     */
+    variableFrequency(): Record<string, VariableFrequency>;
+}