nerdamer 1.1.13 → 2.0.0-rc.2

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

@@ -0,0 +1,430 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Term = void 0;
+const common_1 = require("../../common/common");
+const bigint_1 = require("../../functions/bigint/bigint");
+const numeric_1 = require("../../functions/numeric");
+const utils_1 = require("../../functions/utils");
+const Expression_1 = require("../expression/Expression");
+const constants_1 = require("../parser/constants");
+/**
+ * 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.
+ */
+class Term {
+    /** Mutable symbolic coefficient. */
+    coeff;
+    /** Runtime tag used by Nerdamer's term type guard. */
+    dataType = constants_1.TERM;
+    /** Lazily cached expression representation. */
+    expression;
+    /** Number of variables whose power is positive. */
+    length;
+    /** Lazily cached multidegree in {@link variables} order. */
+    multidegArray;
+    /** Mutable powers keyed by variable name. */
+    powers;
+    /** Lazily cached sum of all stored powers. */
+    totalPower;
+    /** Lazily cached unit-coefficient monomial text. */
+    valueString;
+    /** Sorted variable names used for multidegree and rendering order. */
+    variables;
+    /**
+     * 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, powers, variables) {
+        if (typeof powers === 'string') {
+            this.powers = {};
+            powers.split(',').forEach((x, i) => {
+                this.powers[variables[i]] = Number(x);
+            });
+        }
+        else {
+            this.powers = powers;
+        }
+        this.coeff = typeof coeff === 'string' ? Expression_1.Expression.create(coeff) : coeff;
+        this.length = this.getLength();
+        // Terms use a stable sorted variable order independent of later changes to the caller's array.
+        this.variables = [...variables].sort();
+    }
+    /**
+     * Checks if the given object is a Term
+     *
+     * @param obj - Value to test.
+     * @returns Whether `obj` carries Nerdamer's term discriminator.
+     */
+    static isTerm(obj) {
+        return (0, common_1.isNerdamerNativeType)(obj, constants_1.TERM);
+    }
+    /**
+     * Gets the total number of non-unit variables in the term
+     *
+     * @returns The number of variables with positive powers.
+     */
+    getLength() {
+        let length = 0;
+        for (const x in this.powers) {
+            if (this.powers[x] > 0) {
+                length++;
+            }
+        }
+        return length;
+    }
+    /** Recalculates degree-derived caches after term arithmetic and returns this term. */
+    update() {
+        this.updateMultiDegArray();
+        this.updateTotalPower();
+        this.length = this.getLength();
+        return this;
+    }
+    /**
+     * Forces the multidegree array to be recalculated
+     *
+     * @returns The refreshed internal multidegree array.
+     */
+    updateMultiDegArray() {
+        const retval = this.multideg(this.variables);
+        this.multidegArray = retval;
+        return retval;
+    }
+    /**
+     * Forces the total power to be recalculated
+     *
+     * @returns The refreshed total degree.
+     */
+    updateTotalPower() {
+        let retval = 0;
+        for (const x in this.powers) {
+            retval += this.deg(x);
+        }
+        this.totalPower = retval;
+        return retval;
+    }
+    /**
+     * 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) {
+        return this.getValueString() === t.getValueString();
+    }
+    /**
+     * 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() {
+        return new Term(this.coeff.copy(), { ...this.powers }, this.variables);
+    }
+    deg(v, value) {
+        if (value !== undefined) {
+            this.powers[v] = value;
+            return this;
+        }
+        return this.powers[v] || 0;
+    }
+    /**
+     * 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, n = 1) {
+        const p = this.deg(variable);
+        let retval;
+        if (n > p) {
+            retval = new Term('0', '0', []);
+        }
+        else {
+            retval = this.copy();
+            retval.powers[variable] = p - n;
+            const d = n - 1;
+            const r = (0, bigint_1.productInRange)(p - d, p);
+            retval.coeff = retval.coeff.times(BigInt(r));
+        }
+        return retval;
+    }
+    /**
+     * 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) {
+        const a = this.getMultidegArray();
+        const b = term.getMultidegArray();
+        const diff = [];
+        for (let i = 0; i < a.length; i++) {
+            diff[i] = a[i] - b[i];
+        }
+        return diff;
+    }
+    /**
+     * 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) {
+        const retval = this.copy();
+        retval.coeff = retval.coeff.div(t.coeff);
+        for (const v in t.powers) {
+            if (!retval.variables.includes(v)) {
+                retval.variables.push(v);
+            }
+            retval.deg(v, retval.deg(v) - t.deg(v));
+        }
+        return retval.update();
+    }
+    /**
+     * 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) {
+        // If it's a number, then it divides so easy check and done
+        if (this.getTotalPower() === 0) {
+            return true;
+        }
+        // Divides essentially loops through the dividend and ensures that each power is >= to the divisor for each variable
+        for (const x in this.powers) {
+            if (this.deg(x) > t.deg(x)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Checks for equality with another Term
+     *
+     * @param t - Term to compare.
+     * @returns Whether coefficient and monomial quotient equal one.
+     */
+    eq(t) {
+        return this.div(t).eqNumber(1);
+    }
+    /**
+     * Tests whether this is a constant term equal to a number.
+     *
+     * @param n - Numeric value to compare with the coefficient.
+     */
+    eqNumber(n) {
+        return (0, numeric_1.sum)(...Object.values(this.powers)) === 0 && this.coeff.eq(n);
+    }
+    /**
+     * Returns a lazily constructed expression for this term.
+     *
+     * @returns The cached internal expression reference.
+     */
+    getExpression() {
+        if (this.expression === undefined) {
+            let expression = this.coeff.copy();
+            for (const variable of this.variables) {
+                const power = this.deg(variable);
+                if (power !== 0) {
+                    expression = expression.times(Expression_1.Expression.Variable(variable).pow(power));
+                }
+            }
+            this.expression = expression;
+        }
+        return this.expression;
+    }
+    /**
+     * Returns this term's multidegree in its stored variable order.
+     *
+     * @returns The cached internal degree array.
+     */
+    getMultidegArray() {
+        let retval = this.multidegArray;
+        if (retval === undefined) {
+            retval = this.updateMultiDegArray();
+        }
+        return retval;
+    }
+    /**
+     * Returns the sum of powers in this term.
+     *
+     * @returns The cached total degree.
+     */
+    getTotalPower() {
+        let retval = this.totalPower;
+        if (retval === undefined) {
+            retval = this.updateTotalPower();
+        }
+        return retval;
+    }
+    /**
+     * 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) {
+        // If the user variables have been specified then force regeneration of the string.
+        if (this.valueString === undefined || useVariables !== undefined) {
+            if (this.getTotalPower() === 0) {
+                this.valueString = '1';
+            }
+            else {
+                const vars = useVariables || [...this.variables].sort();
+                const vArray = [];
+                for (const v of vars) {
+                    const p = this.deg(v);
+                    const pv = p === 1 ? '' : Expression_1.Expression.POW_OPR + p;
+                    if (p !== 0) {
+                        vArray.push(`${v}${pv}`);
+                    }
+                }
+                this.valueString = vArray.join('*');
+            }
+        }
+        return this.valueString;
+    }
+    /**
+     * Tests whether every stored variable power is zero.
+     *
+     * @returns Whether the term is constant, independent of its coefficient value.
+     */
+    isConstant() {
+        for (const p in this.powers) {
+            if (this.powers[p] !== 0) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Tests whether the coefficient is zero.
+     *
+     * @returns Whether the term's symbolic coefficient is zero.
+     */
+    isZero() {
+        return this.coeff.isZero();
+    }
+    /**
+     * 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, withCoeff = false) {
+        const variables = (0, utils_1.arrayAddUnique)([...this.variables], t.variables);
+        const powers = {};
+        // Calculate the max power between this and t.
+        for (const v of variables) {
+            powers[v] = Math.max(this.deg(v), t.deg(v));
+        }
+        const coeff = withCoeff
+            ? Expression_1.Expression.fromRational(this.coeff.getMultiplier().LCM(t.coeff.getMultiplier()))
+            : '1';
+        return new Term(coeff, powers, variables);
+    }
+    /**
+     * Returns the variable name with the greatest stored power.
+     */
+    max() {
+        return Object.keys(this.powers).reduce((a, b) => (this.powers[a] > this.powers[b] ? a : b));
+    }
+    /**
+     * Returns the variable name with the least stored power.
+     */
+    min() {
+        return Object.keys(this.powers).reduce((a, b) => (this.powers[a] < this.powers[b] ? a : b));
+    }
+    /**
+     * Calculates the multidegree array
+     *
+     * @param variables - Variable order for the result.
+     * @returns A new power array, using zero for missing variables.
+     */
+    multideg(variables) {
+        const arr = [];
+        for (const v of variables) {
+            arr.push(this.deg(v));
+        }
+        return arr;
+    }
+    /**
+     * Gets the text representation of the monomial
+     *
+     * @param useVariables - Optional variable rendering order.
+     * @returns Canonical parser text for the coefficient and monomial.
+     */
+    text(useVariables) {
+        let c = this.coeff.text();
+        // Wrap sums in brackets
+        if (this.coeff.isSum()) {
+            c = `(${c})`;
+        }
+        let retval;
+        // Zero times anything is zero so nothing left to do
+        if (c === '0') {
+            retval = c;
+        }
+        else {
+            let v = this.getValueString(useVariables);
+            // Remove the safety '1';
+            if (v === '1') {
+                v = '';
+            }
+            // Add multiplication sign
+            if (v) {
+                if (c === '1') {
+                    c = '';
+                }
+                else if (c === '-1') {
+                    c = '-';
+                }
+                else {
+                    c += '*';
+                }
+            }
+            retval = `${c}${v}`;
+        }
+        return retval;
+    }
+    /**
+     * Multiplies this term with the given term
+     *
+     * @param x - Multiplier term.
+     * @returns A new term with multiplied coefficients and added powers.
+     */
+    times(x) {
+        const retval = this.copy();
+        retval.coeff = retval.coeff.times(x.coeff);
+        for (const v in x.powers) {
+            if (!retval.variables.includes(v)) {
+                retval.variables.push(v);
+            }
+            retval.deg(v, retval.deg(v) + x.deg(v));
+        }
+        return retval.update();
+    }
+    /** Returns the same parser text as {@link Term.text}. */
+    toString() {
+        return this.text();
+    }
+}
+exports.Term = Term;

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

@@ -0,0 +1,18 @@
+import { Polynomial } from './Polynomial';
+import type { ExpressionInput } from '../../types';
+/**
+ * Extracts the Z Polynomial from Q.
+ * Given a polynomial with rational coefficients, returns:
+ * - zPoly: the polynomial scaled to have integer coefficients (primitive part)
+ * - content: the GCD of the integer coefficients after clearing denominators
+ * - denominator: the common denominator used to clear fractions
+ *
+ * The relationship is: original = (content / denominator) * zPoly
+ *
+ * @param x
+ */
+export declare function expressionToZPoly(x: ExpressionInput): {
+    zPoly: Polynomial;
+    content: Polynomial;
+    denominator: Polynomial;
+};

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

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expressionToZPoly = expressionToZPoly;
+const Expression_1 = require("../expression/Expression");
+const Polynomial_1 = require("./Polynomial");
+const SparsePolynomialAdapter_1 = require("./SparsePolynomialAdapter");
+/**
+ * Extracts the Z Polynomial from Q.
+ * Given a polynomial with rational coefficients, returns:
+ * - zPoly: the polynomial scaled to have integer coefficients (primitive part)
+ * - content: the GCD of the integer coefficients after clearing denominators
+ * - denominator: the common denominator used to clear fractions
+ *
+ * The relationship is: original = (content / denominator) * zPoly
+ *
+ * @param x
+ */
+function expressionToZPoly(x) {
+    const expression = Expression_1.Expression.create(x);
+    const variables = expression.variables().sort();
+    const converted = (0, SparsePolynomialAdapter_1.expressionToIntegerSparsePolynomial)(expression, variables);
+    const coefficientContent = converted.polynomial.isZero()
+        ? 1n
+        : converted.polynomial.content();
+    const primitive = coefficientContent === 1n
+        ? converted.polynomial
+        : converted.polynomial.divideByScalarExact(coefficientContent);
+    return {
+        zPoly: new Polynomial_1.Polynomial((0, SparsePolynomialAdapter_1.sparsePolynomialToExpression)(primitive, variables), [...variables], 'lex'),
+        content: new Polynomial_1.Polynomial(Expression_1.Expression.Number(coefficientContent)),
+        denominator: new Polynomial_1.Polynomial(Expression_1.Expression.Number(converted.denominator)),
+    };
+}

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

@@ -0,0 +1 @@
+export declare function loadPolynomialFunctions(): void;

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

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPolynomialFunctions = loadPolynomialFunctions;
+const dispatch_1 = require("../../dispatch");
+const functions_1 = require("./functions");
+function loadPolynomialFunctions() {
+    Object.assign(dispatch_1.mathFunctionRegistry, {
+        deg: (0, dispatch_1.systemFunction)({ fn: functions_1.deg, minArgs: 1, maxArgs: 2, distElWise: true }),
+        content: (0, dispatch_1.systemFunction)({ fn: functions_1.content, minArgs: 1, maxArgs: 1, distElWise: true }),
+        coeffs: (0, dispatch_1.systemFunction)({ fn: functions_1.coeffs, minArgs: 1, maxArgs: 2, distElWise: false }),
+        div: (0, dispatch_1.systemFunction)({ fn: functions_1.div, minArgs: 2, maxArgs: 2, distElWise: false }),
+        divide: (0, dispatch_1.systemFunction)({ fn: functions_1.divide, minArgs: 2, maxArgs: 2, distElWise: false }),
+    });
+}

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

@@ -0,0 +1,77 @@
+import { Expression } from '../expression/Expression';
+import { Vector } from '../vector/Vector';
+import { Polynomial } from './Polynomial';
+import type { ExpressionInput } from '../../types';
+/**
+ * Returns the degree of a polynomial expression.
+ *
+ * @remarks
+ * With no variable, `deg(p)` returns the total degree: the largest sum of powers in any
+ * term. With a variable, `deg(p, x)` returns the largest power of `x`, treating the other
+ * variables as coefficients. If the input cannot be converted to a polynomial, the call
+ * remains symbolic instead of throwing.
+ *
+ * @param x - Expression-like input or polynomial to inspect.
+ * @param variable - Optional variable whose degree should be returned.
+ * @returns A numeric expression for polynomial input, otherwise an unevaluated `deg(...)` call.
+ *
+ * @example
+ * ```ts
+ * deg('x^2*y^3+x').text();      // "5"
+ * deg('x^2*y^3+x', 'x').text(); // "2"
+ * deg('x^2*y^3+x', 'y').text(); // "3"
+ * ```
+ */
+export declare function deg(x: ExpressionInput | Polynomial, variable?: ExpressionInput): Expression;
+/**
+ * Returns the exact numeric content of polynomial expression input.
+ *
+ * @remarks
+ * Content means the greatest common divisor of the polynomial's numeric coefficients.
+ * For example, the content of `6*x^2+15*x*y-3*y` is `3`. This function does not choose
+ * a main variable or compute a polynomial-valued GCD of symbolic coefficient expressions.
+ * If expression conversion fails, the operation remains symbolic as `content(input)`.
+ *
+ * @param x - Expression-like input or polynomial to inspect.
+ * @returns A numeric expression for converted input, otherwise an unevaluated symbolic
+ * `content` call.
+ *
+ * @example
+ * ```ts
+ * content('6*x^2+15*x-3').text(); // "3"
+ * ```
+ */
+export declare function content(x: ExpressionInput | Polynomial): Expression;
+/**
+ * Returns polynomial coefficients as a dense Vector ordered by ascending power.
+ *
+ * When no variable is supplied, the first variable in the expression is used, matching
+ * the legacy parser helper. A constant expression therefore has the single coefficient
+ * at power zero.
+ */
+export declare function coeffs(x: ExpressionInput, variable?: ExpressionInput): Vector;
+/**
+ * Returns the quotient and remainder of polynomial division.
+ *
+ * @remarks
+ * This is the parser-facing compatibility behavior historically exposed as `div(a,b)`.
+ * It delegates to the existing polynomial division implementation. When more than one
+ * variable is present, Nerdamer treats the input as a multivariable polynomial rather than
+ * silently choosing one variable and treating the others as coefficients. If either input
+ * is not polynomial-like, the legacy fallback is preserved as `[0, dividend]`. Once both
+ * inputs are polynomial, failures from the division engine are allowed to propagate.
+ */
+export declare function div(dividend: ExpressionInput, divisor: ExpressionInput): Vector;
+/**
+ * Divides two expressions using polynomial quotient/remainder reconstruction when possible.
+ *
+ * @remarks
+ * This restores the parser-facing compatibility behavior historically exposed as
+ * `divide(a,b)`: a successful polynomial division is returned as
+ * `quotient + remainder/divisor`, so the result is a reusable symbolic expression. When
+ * more than one variable is present, Nerdamer treats the input as a multivariable polynomial
+ * rather than silently choosing a main variable. Inputs outside the polynomial domain fall
+ * back to ordinary symbolic division. Once both inputs are polynomial, failures from the
+ * division engine are allowed to propagate.
+ */
+export declare function divide(dividend: ExpressionInput, divisor: ExpressionInput): Expression;