nerdamer 1.1.13 → 2.0.0-rc.1

package/output/core/classes/equation/Equation.js

@@ -0,0 +1,350 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Equation = void 0;
+const common_1 = require("../../common/common");
+const errors_1 = require("../../errors");
+const Expression_1 = require("../expression/Expression");
+const shortcuts_1 = require("../expression/shortcuts");
+const constants_1 = require("../parser/constants");
+/**
+ * Represents a symbolic equality between two expression sides.
+ *
+ * @remarks
+ * An `Equation` stores its left- and right-hand sides as public {@link Expression}
+ * references. The constructor does not copy those expressions, so mutating a supplied
+ * expression later, or mutating {@link Equation.LHS} or {@link Equation.RHS} directly,
+ * changes the equation. Use {@link Equation.copy} when an independent equation is needed.
+ *
+ * Arithmetic methods apply an operation to both sides, but that does not by itself prove
+ * that the transformed equation has exactly the same solution set. For example, multiplying
+ * or dividing by an expression whose value may be zero requires additional domain reasoning.
+ * Solver-facing code should account for those mathematical conditions.
+ *
+ * Absolute value is not supported as an equation rewrite because applying it
+ * independently to both sides can change the solution set. {@link Equation.abs} remains only
+ * as a compatibility member of the general parser-entity surface and always throws. Callers
+ * performing a non-equivalent transformation can use {@link Equation.each} explicitly.
+ *
+ * Equation comparisons reduce each equation to its residual `LHS - RHS` and then use the
+ * corresponding {@link Expression} comparison. They compare those residual expressions;
+ * they do not establish logical or solution-set equivalence between arbitrary equations.
+ *
+ * @example
+ * ```ts
+ * const equation = new Equation(Expression.create('x + 1'), Expression.create(3));
+ * equation.text(); // "1+x=3"
+ * equation.toLHS().text(); // "-2+x=0"
+ * ```
+ */
+class Equation {
+    /** Parser entity tag used to identify equation values. */
+    dataType = constants_1.EQUATION;
+    /** Indicates that equations are not elementwise enumerable parser aggregates. */
+    isEnumerable = false;
+    /** Mutable left-hand side expression stored by this equation. */
+    LHS;
+    /**
+     * Optional parser-entity precision metadata.
+     *
+     * `Equation` itself does not currently use this value when performing equation
+     * operations or formatting its sides.
+     */
+    precision;
+    /** Mutable right-hand side expression stored by this equation. */
+    RHS;
+    /**
+     * Creates an equation from two expression objects.
+     *
+     * @remarks
+     * The supplied expressions are stored by reference rather than copied. This preserves
+     * object identity but also means subsequent mutation of either expression is visible
+     * through the equation.
+     *
+     * @param lhs - Expression to store on the left-hand side.
+     * @param rhs - Expression to store on the right-hand side.
+     */
+    constructor(lhs, rhs) {
+        this.LHS = lhs;
+        this.RHS = rhs;
+    }
+    /**
+     * Tests whether a value carries Nerdamer's equation parser-entity tag.
+     *
+     * @remarks
+     * This is a tag-based type guard rather than an `instanceof` check. It therefore
+     * recognizes compatible equation objects by their `dataType` value.
+     *
+     * @param obj - Value to inspect.
+     * @returns `true` when the value is tagged as an equation.
+     */
+    static isEquation(obj) {
+        return (0, common_1.isNerdamerNativeType)(obj, constants_1.EQUATION);
+    }
+    /**
+     * Rejects absolute value as an equation transformation.
+     *
+     * @remarks
+     * Replacing `a = b` with `|a| = |b|` is not generally solution-set preserving. This
+     * method remains on `Equation` so the general {@link ParserEntity} surface can retain
+     * its historical `abs()` member without reintroducing the unsafe transformation.
+     *
+     * Use {@link Equation.each} explicitly to transform
+     * each side and accepts responsibility for the changed equation semantics.
+     *
+     * @throws {@link core!UnsupportedOperationError} Always; absolute value is not a supported
+     * equation operation.
+     * @deprecated Absolute value is not supported for equations.
+     */
+    abs() {
+        throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+    }
+    /**
+     * Legacy alias for {@link Equation.plus}.
+     *
+     * @param x - Value to add to both sides.
+     * @returns A new equation; the current equation is not modified.
+     */
+    add(x) {
+        return this.plus(x);
+    }
+    /**
+     * Creates an independent copy of this equation and both expression sides.
+     *
+     * @returns A new equation whose left- and right-hand expressions are deep copies.
+     */
+    copy() {
+        return new Equation(this.LHS.copy(), this.RHS.copy());
+    }
+    /**
+     * Divides both sides by the same nonzero number.
+     *
+     * A symbolic divisor is rejected because Nerdamer cannot assume that it is nonzero for
+     * every solution of the equation.
+     *
+     * @param x - Nonzero numeric value by which both sides are divided.
+     * @returns A new equation; the current equation is not modified.
+     * @throws {@link core!UnsupportedOperationError} If `x` is zero or is not numeric.
+     */
+    div(x) {
+        if (Equation.isEquation(x)) {
+            throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+        }
+        const expr = Expression_1.Expression.create(x);
+        if (!expr.isNUM() || expr.isZero()) {
+            throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+        }
+        return new Equation(this.LHS.div(expr), this.RHS.div(expr));
+    }
+    /**
+     * Applies a callback to the two equation sides and rebuilds the equation from its results.
+     *
+     * @remarks
+     * The callback receives the stored left- and right-hand {@link Expression} references
+     * directly, with indices `0` and `1` respectively. Returned expressions are stored by
+     * reference in a new equation. The callback can therefore mutate the original equation
+     * if it mutates either argument before returning.
+     *
+     * Both callback results must be expressions. Other parser entities are rejected after
+     * the callback has run.
+     *
+     * @param fn - Transformation applied to the left and right sides.
+     * @returns A new equation containing the callback results.
+     * @throws {@link core!UnexpectedDataType}
+     * Thrown when either callback result is not an {@link Expression}.
+     */
+    each(fn) {
+        const lhs = fn(this.LHS, 0);
+        const rhs = fn(this.RHS, 1);
+        if (Expression_1.Expression.isExpression(lhs) && Expression_1.Expression.isExpression(rhs)) {
+            return new Equation(lhs, rhs);
+        }
+        const receivedTypes = `${constants_1.dataTypes[lhs.dataType] || typeof lhs} & ${constants_1.dataTypes[rhs.dataType] || typeof rhs}`;
+        throw new errors_1.UnexpectedDataType((0, errors_1.message)('expressionExpected', { type: receivedTypes }));
+    }
+    /**
+     * Compares this equation with another equation by comparing their residual expressions.
+     *
+     * @remarks
+     * Each equation is copied and rewritten as `LHS - RHS = 0`, then the two residual
+     * expressions are compared with {@link Expression.eq}. Equations with the same
+     * solution set are not necessarily equal by this method; for example, scaling an
+     * equation by a nonzero constant changes its residual expression.
+     *
+     * @param eq - Parser entity to compare with this equation.
+     * @returns `true` when `eq` is an equation and the two residual expressions compare equal.
+     */
+    eq(eq) {
+        if (!Equation.isEquation(eq)) {
+            return false;
+        }
+        return this.toLHS().LHS.eq(eq.toLHS().LHS);
+    }
+    /**
+     * Numerically re-evaluates both equation sides.
+     *
+     * @returns A new equation containing evaluated copies of the two sides.
+     */
+    evaluate() {
+        return this.copy().each(e => e.evaluate());
+    }
+    /**
+     * Expands both sides of a copied equation.
+     *
+     * @returns A new equation containing the expanded left- and right-hand sides.
+     */
+    expand() {
+        const retval = this.copy().each(e => e.expand());
+        return retval;
+    }
+    /**
+     * Orders this equation against another equation by comparing their residual expressions.
+     *
+     * @remarks
+     * Both equations are rewritten as `LHS - RHS = 0`, and the resulting expressions are
+     * compared with {@link Expression.gt}. This is an ordering of residual expressions,
+     * not a statement that one equation or solution set is logically greater than another.
+     *
+     * @param eq - Parser entity to compare with this equation.
+     * @returns `true` when `eq` is an equation and this residual compares greater.
+     */
+    gt(eq) {
+        if (!Equation.isEquation(eq)) {
+            return false;
+        }
+        return this.toLHS().LHS.gt(eq.toLHS().LHS);
+    }
+    /**
+     * Residual-expression comparison corresponding to `>=`.
+     *
+     * @param x - Parser entity to compare with this equation.
+     * @returns `true` when {@link Equation.gt} or {@link Equation.eq} succeeds.
+     */
+    gte(x) {
+        return this.gt(x) || this.eq(x);
+    }
+    /**
+     * Orders this equation against another equation by comparing their residual expressions.
+     *
+     * @remarks
+     * Both equations are rewritten as `LHS - RHS = 0`, and the resulting expressions are
+     * compared with {@link Expression.lt}. This is an ordering of residual expressions,
+     * not a statement that one equation or solution set is logically less than another.
+     *
+     * @param eq - Parser entity to compare with this equation.
+     * @returns `true` when `eq` is an equation and this residual compares less.
+     */
+    lt(eq) {
+        if (!Equation.isEquation(eq)) {
+            return false;
+        }
+        return this.toLHS().LHS.lt(eq.toLHS().LHS);
+    }
+    /**
+     * Residual-expression comparison corresponding to `<=`.
+     *
+     * @param x - Parser entity to compare with this equation.
+     * @returns `true` when {@link Equation.lt} or {@link Equation.eq} succeeds.
+     */
+    lte(x) {
+        return this.lt(x) || this.eq(x);
+    }
+    /**
+     * Subtracts the same value from both sides.
+     *
+     * @param x - Value to subtract from the left- and right-hand sides.
+     * @returns A new equation; the current equation is not modified.
+     */
+    minus(x) {
+        if (Equation.isEquation(x)) {
+            throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+        }
+        const expr = Expression_1.Expression.create(x);
+        return this.each(e => e.minus(expr));
+    }
+    /**
+     * Legacy alias for {@link Equation.times}.
+     *
+     * @param x - Nonzero numeric value by which both sides are multiplied.
+     * @returns This equation after mutation.
+     */
+    multiply(x) {
+        return this.times(x);
+    }
+    /**
+     * Adds the same value to both sides.
+     *
+     * @param x - Value to add to the left- and right-hand sides.
+     * @returns A new equation; the current equation is not modified.
+     */
+    plus(x) {
+        if (Equation.isEquation(x)) {
+            throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+        }
+        const expr = Expression_1.Expression.create(x);
+        return this.each(e => e.plus(expr));
+    }
+    /**
+     * Legacy alias for {@link Equation.minus}.
+     *
+     * @param x - Value to subtract from both sides.
+     * @returns A new equation; the current equation is not modified.
+     */
+    subtract(x) {
+        return this.minus(x);
+    }
+    /**
+     * Returns the canonical text form `LHS=RHS`.
+     *
+     * @returns The two side representations joined by `=`.
+     */
+    text() {
+        return `${this.LHS.text()}=${this.RHS.text()}`;
+    }
+    /**
+     * Multiplies both sides by the same nonzero number.
+     *
+     * A symbolic multiplier is rejected because it may be zero for some solutions and add
+     * solutions that were not present in the original equation.
+     *
+     * @param x - Nonzero numeric value by which both sides are multiplied.
+     * @returns This equation after mutation.
+     * @throws {@link core!UnsupportedOperationError} If `x` is zero or is not numeric.
+     */
+    times(x) {
+        if (Equation.isEquation(x)) {
+            throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+        }
+        const expr = Expression_1.Expression.create(x);
+        if (!expr.isNUM() || expr.isZero()) {
+            throw new errors_1.UnsupportedOperationError((0, errors_1.message)('unsupportedOperation'));
+        }
+        this.LHS = this.LHS.times(expr);
+        this.RHS = this.RHS.times(expr);
+        return this;
+    }
+    /**
+     * Rewrites this equation as an equivalent residual form with zero on the right.
+     *
+     * @remarks
+     * The equation and both sides are copied before `RHS` is subtracted from `LHS`, so the
+     * current equation is not modified. The result has the form `LHS - RHS = 0` and is used
+     * by solver preparation and the equation comparison methods.
+     *
+     * @returns A new equation with the residual expression on the left and zero on the right.
+     */
+    toLHS() {
+        const eq = this.copy();
+        eq.LHS = eq.LHS.minus(eq.RHS);
+        eq.RHS = (0, shortcuts_1.zero)();
+        return eq;
+    }
+    /**
+     * Returns the same canonical equation text as {@link Equation.text}.
+     *
+     * @returns The equation text representation.
+     */
+    toString() {
+        return this.text();
+    }
+}
+exports.Equation = Equation;

package/output/core/classes/expression/CoeffObject.d.ts

@@ -0,0 +1,100 @@
+import { Polynomial } from '../polynomial/Polynomial';
+import { Vector } from '../vector/Vector';
+import { Expression } from './Expression';
+/**
+ * Stores coefficients indexed by the power or multidegree collected from an expression.
+ *
+ * @remarks
+ * {@link Expression.coeffs} and {@link Polynomial.coeffs} use string keys. A
+ * univariate coefficient uses a key such as `"2"`; multivariate collection uses a
+ * comma-separated degree tuple such as `"1,0"`, in the same order as
+ * {@link CoeffObject.variables}.
+ *
+ * The object is mutable. The constructor retains the supplied `variables` array, and
+ * the public `coeffs` record exposes the stored expression references directly.
+ * Methods such as {@link CoeffObject.toArray} are intended for univariate numeric power
+ * keys; a multidegree key cannot be represented by that dense array form.
+ */
+export declare class CoeffObject {
+    /** Mutable coefficient expressions keyed by power or comma-separated multidegree. */
+    coeffs: {
+        [key: string]: Expression;
+    };
+    /** Variables whose order defines the degree keys in {@link coeffs}. */
+    variables: string[];
+    /**
+     * Creates an empty coefficient collection for the requested variable order.
+     *
+     * @param variables - Variables used to interpret coefficient degree keys. The array
+     * is retained by reference.
+     */
+    constructor(variables: string[]);
+    /** Rebuilds the stored degree keys and coefficients as independent polynomial terms. */
+    private buildTerms;
+    /**
+     * Adds an expression to the coefficient stored at a degree key.
+     *
+     * A new key retains `value` by reference. An existing key is replaced with the
+     * expression returned by symbolic addition.
+     *
+     * @param key - Power or comma-separated multidegree key.
+     * @param value - Coefficient contribution to accumulate.
+     */
+    add(key: string, value: Expression): void;
+    /**
+     * Visits each stored coefficient and its degree key.
+     *
+     * @param fn - Callback receiving the stored expression reference and key.
+     * @returns This coefficient object for chaining.
+     */
+    each(fn: (e: Expression, p: string) => void): this;
+    /**
+     * Returns the stored coefficient for a power or multidegree key.
+     *
+     * @param p - Key to look up.
+     * @returns The internal expression reference, or `undefined` when the key is absent.
+     */
+    getPower(p: string | number): Expression;
+    /**
+     * Tests whether a power or multidegree key is present, including an explicit zero.
+     *
+     * @param p - Key to test.
+     */
+    hasPower(p: string | number): boolean;
+    /** Returns the greatest numeric power key, or `NaN` when any key is non-numeric. */
+    max(): number;
+    /**
+     * Formats the sparse coefficient record for inspection.
+     *
+     * @param formatted - Add line breaks and indentation between entries.
+     */
+    text(formatted?: boolean): string;
+    toArray(): Expression[];
+    toArray(asNumber: false): Expression[];
+    toArray(asNumber: true): number[];
+    /** Reconstructs the stored coefficients as a native symbolic expression. */
+    toExpression(): Expression;
+    /**
+     * Builds parser text representing the stored coefficient terms.
+     *
+     * Each degree key is interpreted using the configured variable order, including
+     * comma-separated multidegrees such as `"2,1"` for `x^2*y`.
+     */
+    toParsableString(): string;
+    /**
+     * Reconstructs the coefficients as a {@link Polynomial} without reparsing ordinary terms.
+     *
+     * Coefficients that contain one of the configured polynomial variables are passed through
+     * the normal constructor so overlapping coefficient and monomial powers are canonicalized.
+     *
+     * @returns A new polynomial with independent terms and a synchronized expression.
+     */
+    toPolynomial(): Polynomial;
+    toString(): string;
+    /**
+     * Converts univariate coefficients to a dense {@link Vector} ordered by ascending power.
+     *
+     * Missing powers are represented by zero expressions.
+     */
+    toVector(): Vector;
+}

package/output/core/classes/expression/CoeffObject.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoeffObject = void 0;
+const errors_1 = require("../../errors");
+const Polynomial_1 = require("../polynomial/Polynomial");
+const Term_1 = require("../polynomial/Term");
+const Vector_1 = require("../vector/Vector");
+const Expression_1 = require("./Expression");
+const shortcuts_1 = require("./shortcuts");
+/**
+ * Stores coefficients indexed by the power or multidegree collected from an expression.
+ *
+ * @remarks
+ * {@link Expression.coeffs} and {@link Polynomial.coeffs} use string keys. A
+ * univariate coefficient uses a key such as `"2"`; multivariate collection uses a
+ * comma-separated degree tuple such as `"1,0"`, in the same order as
+ * {@link CoeffObject.variables}.
+ *
+ * The object is mutable. The constructor retains the supplied `variables` array, and
+ * the public `coeffs` record exposes the stored expression references directly.
+ * Methods such as {@link CoeffObject.toArray} are intended for univariate numeric power
+ * keys; a multidegree key cannot be represented by that dense array form.
+ */
+class CoeffObject {
+    /** Mutable coefficient expressions keyed by power or comma-separated multidegree. */
+    coeffs = {};
+    /** Variables whose order defines the degree keys in {@link coeffs}. */
+    variables;
+    /**
+     * Creates an empty coefficient collection for the requested variable order.
+     *
+     * @param variables - Variables used to interpret coefficient degree keys. The array
+     * is retained by reference.
+     */
+    constructor(variables) {
+        this.variables = variables;
+    }
+    /** Rebuilds the stored degree keys and coefficients as independent polynomial terms. */
+    buildTerms() {
+        const retval = [];
+        for (const powers in this.coeffs) {
+            retval.push(new Term_1.Term(new Expression_1.Expression(this.coeffs[powers]), powers, this.variables));
+        }
+        return retval;
+    }
+    /**
+     * Adds an expression to the coefficient stored at a degree key.
+     *
+     * A new key retains `value` by reference. An existing key is replaced with the
+     * expression returned by symbolic addition.
+     *
+     * @param key - Power or comma-separated multidegree key.
+     * @param value - Coefficient contribution to accumulate.
+     */
+    add(key, value) {
+        const e = this.coeffs[key];
+        this.coeffs[key] = e ? e.plus(value) : value;
+    }
+    /**
+     * Visits each stored coefficient and its degree key.
+     *
+     * @param fn - Callback receiving the stored expression reference and key.
+     * @returns This coefficient object for chaining.
+     */
+    each(fn) {
+        for (const x in this.coeffs) {
+            fn(this.coeffs[x], x);
+        }
+        return this;
+    }
+    /**
+     * Returns the stored coefficient for a power or multidegree key.
+     *
+     * @param p - Key to look up.
+     * @returns The internal expression reference, or `undefined` when the key is absent.
+     */
+    getPower(p) {
+        return this.coeffs[p];
+    }
+    /**
+     * Tests whether a power or multidegree key is present, including an explicit zero.
+     *
+     * @param p - Key to test.
+     */
+    hasPower(p) {
+        return p in this.coeffs;
+    }
+    /** Returns the greatest numeric power key, or `NaN` when any key is non-numeric. */
+    max() {
+        const powers = Object.keys(this.coeffs).map(x => {
+            return Number(x);
+        });
+        return Math.max(...powers);
+    }
+    /**
+     * Formats the sparse coefficient record for inspection.
+     *
+     * @param formatted - Add line breaks and indentation between entries.
+     */
+    text(formatted = false) {
+        const n = formatted ? '\n' : '';
+        const t = formatted ? '    ' : '';
+        const values = [];
+        const d = `, ` + n;
+        for (const x in this.coeffs) {
+            values.push(`${t}${x}: ${this.coeffs[x]}`);
+        }
+        return `{ ${n}${values.join(d)} ${n}}`;
+    }
+    /**
+     * Converts univariate coefficients to a dense array indexed by power.
+     *
+     * Missing powers are filled with new zero expressions. With `asNumber: true`, each
+     * coefficient is converted using JavaScript numeric conversion, which may lose exact
+     * precision. The method does not remove or copy coefficients already stored here.
+     *
+     * @param asNumber - Return JavaScript numbers instead of expressions.
+     * @throws {@link NaNError} Thrown when a key, such as a multidegree tuple, cannot be
+     * interpreted as a numeric univariate power.
+     */
+    toArray(asNumber = false) {
+        const max = this.max();
+        const coeffs = [];
+        if (isNaN(max)) {
+            throw new errors_1.NaNError((0, errors_1.message)('cannotCreateArrayFromNaN'));
+        }
+        for (let i = 0; i <= max; i++) {
+            let coeff = this.coeffs[i];
+            // Fill voids with zero
+            if (!coeff) {
+                coeff = (0, shortcuts_1.zero)();
+            }
+            coeffs[i] = asNumber ? Number(coeff) : coeff;
+        }
+        return coeffs;
+    }
+    /** Reconstructs the stored coefficients as a native symbolic expression. */
+    toExpression() {
+        let retval = (0, shortcuts_1.zero)();
+        for (const term of this.buildTerms()) {
+            if (!term.isZero()) {
+                retval = retval.plus(term.getExpression());
+            }
+        }
+        return retval;
+    }
+    /**
+     * Builds parser text representing the stored coefficient terms.
+     *
+     * Each degree key is interpreted using the configured variable order, including
+     * comma-separated multidegrees such as `"2,1"` for `x^2*y`.
+     */
+    toParsableString() {
+        const terms = [];
+        for (const term of this.buildTerms()) {
+            if (!term.isZero()) {
+                terms.push(term.text(this.variables));
+            }
+        }
+        return terms.join('+').replace(/\+-/g, '-');
+    }
+    /**
+     * Reconstructs the coefficients as a {@link Polynomial} without reparsing ordinary terms.
+     *
+     * Coefficients that contain one of the configured polynomial variables are passed through
+     * the normal constructor so overlapping coefficient and monomial powers are canonicalized.
+     *
+     * @returns A new polynomial with independent terms and a synchronized expression.
+     */
+    toPolynomial() {
+        const terms = this.buildTerms();
+        const requiresCanonicalization = terms.some(term => this.variables.some(variable => term.coeff.hasVariable(variable)));
+        const expression = this.toExpression();
+        let retval;
+        if (requiresCanonicalization) {
+            retval = new Polynomial_1.Polynomial(expression, this.variables);
+        }
+        else {
+            retval = new Polynomial_1.Polynomial((0, shortcuts_1.zero)(), this.variables);
+            retval.terms = terms.filter(term => !term.isZero());
+            retval.order();
+            retval.expression = expression;
+        }
+        return retval;
+    }
+    toString() {
+        return this.text();
+    }
+    /**
+     * Converts univariate coefficients to a dense {@link Vector} ordered by ascending power.
+     *
+     * Missing powers are represented by zero expressions.
+     */
+    toVector() {
+        return new Vector_1.Vector(this.toArray());
+    }
+}
+exports.CoeffObject = CoeffObject;