nerdamer 1.1.13 → 2.0.0-rc.2

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

@@ -0,0 +1,56 @@
+/**
+ * @module sparsePolynomialAdapter
+ *
+ * Conversion from Nerdamer's expression-facing polynomial forms to the exact
+ * integer sparse polynomial representation.
+ */
+import { Expression } from '../expression/Expression';
+import { SparsePolynomial } from './SparsePolynomial';
+import type { Polynomial } from './Polynomial';
+/**
+ * Converts an integer-coefficient polynomial expression directly to sparse form.
+ *
+ * Sums, products, and non-negative integer powers are evaluated with sparse
+ * polynomial arithmetic, so callers do not need to construct the legacy Polynomial
+ * representation first. Variables are ordered by ascending degree and then by name.
+ */
+export declare function expressionToSparsePolynomial(expression: Expression): Readonly<{
+    polynomial: SparsePolynomial;
+    variables: readonly string[];
+}>;
+/**
+ * Converts a rational-coefficient polynomial expression directly to integer sparse form.
+ *
+ * The supplied variables define the sparse ring coordinates. Rational denominators are
+ * carried separately while sums, products, and non-negative integer powers are evaluated,
+ * then reduced against common integer coefficient content.
+ */
+export declare function expressionToIntegerSparsePolynomial(expression: Expression, variables: readonly string[]): Readonly<{
+    polynomial: SparsePolynomial;
+    denominator: bigint;
+}>;
+/**
+ * Converts a Polynomial with rational numeric coefficients to an integer sparse
+ * polynomial by clearing one common positive denominator.
+ *
+ * The supplied variables define the sparse ring coordinates and must include every
+ * variable in the polynomial.
+ */
+export declare function polynomialToIntegerSparsePolynomial(polynomial: Polynomial, variables: readonly string[]): Readonly<{
+    polynomial: SparsePolynomial;
+    denominator: bigint;
+}>;
+/**
+ * Converts a Polynomial to an exact sparse polynomial over the integers.
+ *
+ * Coefficients must already be integers; use
+ * {@link polynomialToIntegerSparsePolynomial} when rational coefficients should be
+ * cleared first.
+ */
+export declare function polynomialToSparsePolynomial(polynomial: Polynomial, variables: readonly string[]): SparsePolynomial;
+/**
+ * Converts an exact sparse polynomial directly to an Expression.
+ *
+ * Conversion does not pass through Polynomial, so bigint exponents remain exact.
+ */
+export declare function sparsePolynomialToExpression(polynomial: SparsePolynomial, variables: readonly string[]): Expression;

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

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * @module sparsePolynomialAdapter
+ *
+ * Conversion from Nerdamer's expression-facing polynomial forms to the exact
+ * integer sparse polynomial representation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expressionToSparsePolynomial = expressionToSparsePolynomial;
+exports.expressionToIntegerSparsePolynomial = expressionToIntegerSparsePolynomial;
+exports.polynomialToIntegerSparsePolynomial = polynomialToIntegerSparsePolynomial;
+exports.polynomialToSparsePolynomial = polynomialToSparsePolynomial;
+exports.sparsePolynomialToExpression = sparsePolynomialToExpression;
+const errors_1 = require("../../errors");
+const bigint_1 = require("../../functions/bigint/bigint");
+const Expression_1 = require("../expression/Expression");
+const shortcuts_1 = require("../expression/shortcuts");
+const SparsePolynomial_1 = require("./SparsePolynomial");
+/**
+ * Converts an integer-coefficient polynomial expression directly to sparse form.
+ *
+ * Sums, products, and non-negative integer powers are evaluated with sparse
+ * polynomial arithmetic, so callers do not need to construct the legacy Polynomial
+ * representation first. Variables are ordered by ascending degree and then by name.
+ */
+function expressionToSparsePolynomial(expression) {
+    const sourceVariables = expression.variables().sort();
+    const variableIndices = new Map(sourceVariables.map((variable, index) => [variable, index]));
+    function powerOf(current) {
+        const power = current.getPower();
+        if (!power.isInteger() || power.sign() < 0) {
+            throw new errors_1.PolynomialError((0, errors_1.message)('notAPolynomial'));
+        }
+        return power.getMultiplier().numerator;
+    }
+    function integerMultiplier(current) {
+        const multiplier = current.getMultiplier();
+        if (multiplier.denominator !== 1n) {
+            throw new Error((0, errors_1.message)('integerRequired'));
+        }
+        return multiplier.numerator;
+    }
+    function convert(current) {
+        const variableCount = sourceVariables.length;
+        if (current.isNUM()) {
+            return SparsePolynomial_1.SparsePolynomial.constant(variableCount, integerMultiplier(current));
+        }
+        if (current.isVAR()) {
+            const variableIndex = variableIndices.get(current.value);
+            if (variableIndex === undefined) {
+                throw new errors_1.PolynomialError((0, errors_1.message)('notAPolynomial'));
+            }
+            const exponents = new Array(variableCount).fill(0n);
+            exponents[variableIndex] = powerOf(current);
+            return SparsePolynomial_1.SparsePolynomial.monomial(variableCount, integerMultiplier(current), exponents);
+        }
+        if (current.isSum()) {
+            let sum = SparsePolynomial_1.SparsePolynomial.zero(variableCount);
+            for (const term of current.elementsArray()) {
+                sum = sum.add(convert(term));
+            }
+            return sum.pow(powerOf(current)).scale(integerMultiplier(current));
+        }
+        if (current.isProduct()) {
+            let product = SparsePolynomial_1.SparsePolynomial.constant(variableCount, 1n);
+            for (const factor of current.elementsArray()) {
+                product = product.multiply(convert(factor));
+            }
+            return product.pow(powerOf(current)).scale(integerMultiplier(current));
+        }
+        throw new errors_1.PolynomialError((0, errors_1.message)('notAPolynomial'));
+    }
+    const source = convert(expression);
+    const order = sourceVariables
+        .map((variable, index) => ({
+        variable,
+        index,
+        degree: source.degree(index) ?? 0n,
+    }))
+        .sort((left, right) => {
+        if (left.degree < right.degree) {
+            return -1;
+        }
+        if (left.degree > right.degree) {
+            return 1;
+        }
+        return left.variable.localeCompare(right.variable);
+    });
+    const variables = order.map(entry => entry.variable);
+    if (order.every((entry, index) => entry.index === index)) {
+        return { polynomial: source, variables };
+    }
+    const terms = source.terms().map(term => ({
+        coefficient: term.coefficient,
+        exponents: order.map(entry => term.exponents[entry.index]),
+    }));
+    return {
+        polynomial: new SparsePolynomial_1.SparsePolynomial(source.variableCount, terms),
+        variables,
+    };
+}
+/**
+ * Converts a rational-coefficient polynomial expression directly to integer sparse form.
+ *
+ * The supplied variables define the sparse ring coordinates. Rational denominators are
+ * carried separately while sums, products, and non-negative integer powers are evaluated,
+ * then reduced against common integer coefficient content.
+ */
+function expressionToIntegerSparsePolynomial(expression, variables) {
+    const selected = new Set();
+    for (const variable of variables) {
+        if (selected.has(variable)) {
+            throw new RangeError((0, errors_1.message)('sparseAdapterVariablesUnique'));
+        }
+        selected.add(variable);
+    }
+    for (const variable of expression.variables()) {
+        if (!selected.has(variable)) {
+            throw new RangeError((0, errors_1.message)('sparseAdapterVariablesIncludeEvery'));
+        }
+    }
+    const variableCount = variables.length;
+    const variableIndices = new Map(variables.map((variable, index) => [variable, index]));
+    function powerOf(current) {
+        const power = current.getPower();
+        if (!power.isInteger() || power.sign() < 0) {
+            throw new errors_1.PolynomialError((0, errors_1.message)('notAPolynomial'));
+        }
+        return power.getMultiplier().numerator;
+    }
+    function normalize(polynomial, denominator) {
+        if (polynomial.isZero()) {
+            return { polynomial, denominator: 1n };
+        }
+        const divisor = (0, bigint_1.GCD)(polynomial.content(), denominator);
+        return divisor === 1n
+            ? { polynomial, denominator }
+            : {
+                polynomial: polynomial.divideByScalarExact(divisor),
+                denominator: denominator / divisor,
+            };
+    }
+    function applyPowerAndMultiplier(current, polynomial, denominator) {
+        const exponent = powerOf(current);
+        const multiplier = current.getMultiplier();
+        return normalize(polynomial.pow(exponent).scale(multiplier.numerator), denominator ** exponent * multiplier.denominator);
+    }
+    function convert(current) {
+        const multiplier = current.getMultiplier();
+        if (current.isNUM()) {
+            return normalize(SparsePolynomial_1.SparsePolynomial.constant(variableCount, multiplier.numerator), multiplier.denominator);
+        }
+        if (current.isVAR()) {
+            const variableIndex = variableIndices.get(current.value);
+            if (variableIndex === undefined) {
+                throw new errors_1.PolynomialError((0, errors_1.message)('notAPolynomial'));
+            }
+            const exponents = new Array(variableCount).fill(0n);
+            exponents[variableIndex] = powerOf(current);
+            return normalize(SparsePolynomial_1.SparsePolynomial.monomial(variableCount, multiplier.numerator, exponents), multiplier.denominator);
+        }
+        if (current.isSum()) {
+            let polynomial = SparsePolynomial_1.SparsePolynomial.zero(variableCount);
+            let denominator = 1n;
+            for (const term of current.elementsArray()) {
+                const converted = convert(term);
+                const commonDenominator = (0, bigint_1.LCM)(denominator, converted.denominator);
+                polynomial = polynomial
+                    .scale(commonDenominator / denominator)
+                    .add(converted.polynomial.scale(commonDenominator / converted.denominator));
+                denominator = commonDenominator;
+            }
+            return applyPowerAndMultiplier(current, polynomial, denominator);
+        }
+        if (current.isProduct()) {
+            let polynomial = SparsePolynomial_1.SparsePolynomial.constant(variableCount, 1n);
+            let denominator = 1n;
+            for (const factor of current.elementsArray()) {
+                const converted = convert(factor);
+                polynomial = polynomial.multiply(converted.polynomial);
+                denominator *= converted.denominator;
+            }
+            return applyPowerAndMultiplier(current, polynomial, denominator);
+        }
+        throw new errors_1.PolynomialError((0, errors_1.message)('notAPolynomial'));
+    }
+    const converted = convert(expression);
+    const terms = [...converted.polynomial.terms()].sort((left, right) => -SparsePolynomial_1.SparsePolynomial.compareMonomials(left.exponents, right.exponents, 'lex'));
+    return {
+        polynomial: new SparsePolynomial_1.SparsePolynomial(variableCount, terms),
+        denominator: converted.denominator,
+    };
+}
+/**
+ * Converts a Polynomial with rational numeric coefficients to an integer sparse
+ * polynomial by clearing one common positive denominator.
+ *
+ * The supplied variables define the sparse ring coordinates and must include every
+ * variable in the polynomial.
+ */
+function polynomialToIntegerSparsePolynomial(polynomial, variables) {
+    return expressionToIntegerSparsePolynomial(polynomial.getExpression(), variables);
+}
+/**
+ * Converts a Polynomial to an exact sparse polynomial over the integers.
+ *
+ * Coefficients must already be integers; use
+ * {@link polynomialToIntegerSparsePolynomial} when rational coefficients should be
+ * cleared first.
+ */
+function polynomialToSparsePolynomial(polynomial, variables) {
+    const converted = polynomialToIntegerSparsePolynomial(polynomial, variables);
+    if (converted.denominator !== 1n) {
+        throw new Error((0, errors_1.message)('integerRequired'));
+    }
+    return converted.polynomial;
+}
+/**
+ * Converts an exact sparse polynomial directly to an Expression.
+ *
+ * Conversion does not pass through Polynomial, so bigint exponents remain exact.
+ */
+function sparsePolynomialToExpression(polynomial, variables) {
+    if (variables.length !== polynomial.variableCount) {
+        throw new RangeError((0, errors_1.message)('sparseExpressionConversionNameCount'));
+    }
+    let result = (0, shortcuts_1.zero)();
+    for (const term of polynomial.terms()) {
+        let expression = Expression_1.Expression.Number(term.coefficient);
+        for (let variableIndex = 0; variableIndex < variables.length; variableIndex++) {
+            const exponent = term.exponents[variableIndex];
+            if (exponent === 0n) {
+                continue;
+            }
+            const variable = Expression_1.Expression.Variable(variables[variableIndex]);
+            expression = expression.times(exponent === 1n ? variable : variable.pow(Expression_1.Expression.Number(exponent)));
+        }
+        result = result.plus(expression);
+    }
+    return result;
+}

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

@@ -0,0 +1,222 @@
+import { Expression } from '../expression/Expression';
+import { TERM } from '../parser/constants';
+/** Powers keyed by variable name. Missing variables have degree zero. */
+export type PowersObject = Record<string, number>;
+/**
+ * Represents one coefficient-monomial term in a {@link Polynomial}.
+ *
+ * @remarks
+ * A term stores an `Expression` coefficient, a mutable variable-to-power record, and
+ * a sorted copy of the supplied variable names. The coefficient and a power object
+ * supplied to the constructor are retained by reference; {@link Term.copy} creates
+ * independent copies of both.
+ *
+ * Multidegree, total power, expression, and value text are computed lazily and cached.
+ * Arithmetic methods return new terms and refresh their derived degree fields. Direct
+ * mutation of {@link Term.coeff}, {@link Term.powers}, or the setter overload of
+ * {@link Term.deg} does not invalidate every cached field, so callers should prefer a
+ * copied/reconstructed term when cached values may already have been read.
+ */
+export declare class Term {
+    /** Mutable symbolic coefficient. */
+    coeff: Expression;
+    /** Runtime tag used by Nerdamer's term type guard. */
+    dataType: typeof TERM;
+    /** Lazily cached expression representation. */
+    expression?: Expression;
+    /** Number of variables whose power is positive. */
+    length: number;
+    /** Lazily cached multidegree in {@link variables} order. */
+    multidegArray?: number[];
+    /** Mutable powers keyed by variable name. */
+    powers: PowersObject;
+    /** Lazily cached sum of all stored powers. */
+    totalPower?: number;
+    /** Lazily cached unit-coefficient monomial text. */
+    valueString?: string;
+    /** Sorted variable names used for multidegree and rendering order. */
+    variables: string[];
+    /**
+     * Creates a term from a coefficient and monomial powers.
+     *
+     * @param coeff - Expression coefficient or parser text. Existing expressions are retained.
+     * @param powers - Power record or comma-separated degrees aligned with `variables`.
+     * An object power record is retained by reference.
+     * @param variables - Variable order to interpret string powers. The term stores a sorted copy.
+     */
+    constructor(coeff: Expression | string, powers: PowersObject | string, variables: string[]);
+    /**
+     * Checks if the given object is a Term
+     *
+     * @param obj - Value to test.
+     * @returns Whether `obj` carries Nerdamer's term discriminator.
+     */
+    static isTerm(obj: unknown): obj is Term;
+    /**
+     * Gets the total number of non-unit variables in the term
+     *
+     * @returns The number of variables with positive powers.
+     */
+    private getLength;
+    /** Recalculates degree-derived caches after term arithmetic and returns this term. */
+    private update;
+    /**
+     * Forces the multidegree array to be recalculated
+     *
+     * @returns The refreshed internal multidegree array.
+     */
+    private updateMultiDegArray;
+    /**
+     * Forces the total power to be recalculated
+     *
+     * @returns The refreshed total degree.
+     */
+    private updateTotalPower;
+    /**
+     * Tests whether two terms have the same unit-coefficient monomial.
+     *
+     * @param t - Term to compare.
+     * @returns Whether their rendered variable-and-power components match.
+     */
+    canAddOrSubtract(t: Term): boolean;
+    /**
+     * Creates an independently mutable copy of this term.
+     *
+     * @returns A term with copied coefficient, powers, and variable array. Lazy caches are rebuilt on demand.
+     */
+    copy(): Term;
+    /**
+     * Returns the degree of one variable.
+     *
+     * @param v - Variable whose power is read.
+     * @returns The stored power, or zero when the variable is absent.
+     */
+    deg(v: string): number;
+    /**
+     * Assigns the degree of one variable.
+     *
+     * @param v - Variable whose power is written.
+     * @param value - New numeric power.
+     * @returns This term after assignment. Lazy caches are not invalidated automatically.
+     */
+    deg(v: string, value: number): Term;
+    /**
+     * Differentiates this term with respect to one variable.
+     *
+     * @param variable - Differentiation variable.
+     * @param n - Non-negative derivative order.
+     * @returns A new differentiated term, or a zero term when `n` exceeds the power.
+     */
+    diff(variable: string, n?: number): Term;
+    /**
+     * Subtracts another term's multidegree from this term's multidegree.
+     *
+     * @param term - Term whose degree tuple is subtracted.
+     * @returns A new component-wise difference array in this term's variable order.
+     */
+    difference(term: Term): number[];
+    /**
+     * Divides this term by the provided term
+     *
+     * @param t - Divisor term.
+     * @returns A new quotient term; negative powers are permitted by this low-level operation.
+     */
+    div(t: Term): Term;
+    /**
+     * Checks if one term can divide another.
+     *
+     * @param t - Candidate dividend term.
+     * @returns Whether every power in this term is no greater than the corresponding power in `t`.
+     */
+    divides(t: Term): boolean;
+    /**
+     * Checks for equality with another Term
+     *
+     * @param t - Term to compare.
+     * @returns Whether coefficient and monomial quotient equal one.
+     */
+    eq(t: Term): boolean;
+    /**
+     * Tests whether this is a constant term equal to a number.
+     *
+     * @param n - Numeric value to compare with the coefficient.
+     */
+    eqNumber(n: number | string): boolean;
+    /**
+     * Returns a lazily constructed expression for this term.
+     *
+     * @returns The cached internal expression reference.
+     */
+    getExpression(): Expression;
+    /**
+     * Returns this term's multidegree in its stored variable order.
+     *
+     * @returns The cached internal degree array.
+     */
+    getMultidegArray(): number[];
+    /**
+     * Returns the sum of powers in this term.
+     *
+     * @returns The cached total degree.
+     */
+    getTotalPower(): number;
+    /**
+     * Formats the monomial with a unit coefficient.
+     *
+     * @param useVariables - Optional variable order used for this rendering.
+     * @returns Parser text such as `x^2*y`, or `1` for a constant term.
+     */
+    getValueString(useVariables?: string[]): string;
+    /**
+     * Tests whether every stored variable power is zero.
+     *
+     * @returns Whether the term is constant, independent of its coefficient value.
+     */
+    isConstant(): boolean;
+    /**
+     * Tests whether the coefficient is zero.
+     *
+     * @returns Whether the term's symbolic coefficient is zero.
+     */
+    isZero(): boolean;
+    /**
+     * Calculates the LCM of two terms with numeric coefficients
+     * TODO: Extend to non-numeric coefficients
+     *
+     * @param t - Other monomial term.
+     * @param withCoeff - Include the exact numeric coefficient LCM instead of using one.
+     * @returns A new term containing maximum powers for the union of variables.
+     */
+    LCM(t: Term, withCoeff?: boolean): Term;
+    /**
+     * Returns the variable name with the greatest stored power.
+     */
+    max(): string;
+    /**
+     * Returns the variable name with the least stored power.
+     */
+    min(): string;
+    /**
+     * Calculates the multidegree array
+     *
+     * @param variables - Variable order for the result.
+     * @returns A new power array, using zero for missing variables.
+     */
+    multideg(variables: string[]): number[];
+    /**
+     * Gets the text representation of the monomial
+     *
+     * @param useVariables - Optional variable rendering order.
+     * @returns Canonical parser text for the coefficient and monomial.
+     */
+    text(useVariables?: string[]): string;
+    /**
+     * Multiplies this term with the given term
+     *
+     * @param x - Multiplier term.
+     * @returns A new term with multiplied coefficients and added powers.
+     */
+    times(x: Term): Term;
+    /** Returns the same parser text as {@link Term.text}. */
+    toString(): string;
+}