nerdamer 1.1.13 → 2.0.0-rc.2

package/output/solve/classes/SolutionSet.js

@@ -0,0 +1,434 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SolutionSet = void 0;
+const decimal_js_1 = __importDefault(require("decimal.js"));
+const Expression_1 = require("../../core/classes/expression/Expression");
+const constants_1 = require("../../core/classes/parser/constants");
+const ValuesSet_1 = require("../../core/classes/valuesSet/ValuesSet");
+const common_1 = require("../../core/common/common");
+const errors_1 = require("../../core/errors");
+/**
+ * A finite set of solution descriptors with solver-specific metadata.
+ *
+ * @remarks
+ * `SolutionSet` inherits the finite-set storage semantics of {@link ValuesSet}: accepted
+ * descriptors are unique by symbolic equality, insertion order has no mathematical meaning,
+ * and values exposed through {@link elements} are copies rather than mutable references into
+ * the set. A descriptor normally represents one solution, but a descriptor containing the
+ * reserved `_n` index represents a parameterized family where `_n` ranges over the integers.
+ * The special `all` descriptor represents every value of the solved variable. Consequently,
+ * {@link count} reports the number of stored descriptors, not the cardinality of the
+ * mathematical solution set.
+ *
+ * {@link solutionsType} records solver provenance: whether accepted descriptors came from
+ * numerical strategies, symbolic/exact strategies, or both. It is not inferred from the
+ * printed shape of a descriptor, so a symbolic strategy may produce a value such as `1`.
+ * The orthogonal {@link solutionForm} property is derived from representation and distinguishes
+ * finite results, `_n`-indexed parametric families, and the `all` result.
+ *
+ * The class narrows membership to {@link Expression} values and keeps rejected singular
+ * candidates and numerical root metadata alongside the accepted solutions.
+ *
+ * Excluded values are enforced solver state, not merely advisory metadata. Once a value is excluded,
+ * adding the same value does not reintroduce it; excluding an already accepted value removes
+ * it from the solution set. {@link copy} preserves accepted values, exclusions, raw roots,
+ * partial-result state, solution type, and the unresolved expression when one is present.
+ */
+class SolutionSet extends ValuesSet_1.ValuesSet {
+    excluded = new ValuesSet_1.ValuesSet();
+    roots = [];
+    dataType = constants_1.SOLUTIONS_SET;
+    partial = false;
+    /** Solver provenance for the currently accepted descriptors. */
+    solutionsType = undefined;
+    unsolved;
+    constructor(values) {
+        super();
+        if (values) {
+            for (const v of values) {
+                this.add(v);
+            }
+        }
+    }
+    /** Tests whether a value is specifically a solver `SolutionSet`. */
+    static isSolutionSet(obj) {
+        return (0, common_1.isNerdamerNativeType)(obj, constants_1.SOLUTIONS_SET);
+    }
+    /**
+     * Combines numerical/symbolic provenance without changing any other solver state.
+     */
+    mergeSolutionsType(solutionsType) {
+        if (this.solutionsType === undefined) {
+            this.solutionsType = solutionsType;
+        }
+        else if (solutionsType !== undefined && this.solutionsType !== solutionsType) {
+            this.solutionsType = 'mixed';
+        }
+    }
+    /**
+     * Verifies and admits one candidate, reporting whether it belongs to this result after
+     * verification. Keeping this decision inside the same path used by {@link addSolution}
+     * avoids mistaking a pre-existing equal descriptor for a newly verified source candidate.
+     */
+    verifyAndAddSolution(solution, forFunction, variable) {
+        let retval = false;
+        try {
+            const evaluated = forFunction
+                .evaluate({ [variable]: solution.evaluate() })
+                .expand();
+            const isClosed = evaluated.variables().length === 0;
+            // Preserve parameterized candidates that cannot yet be verified, but
+            // require every closed residual, including complex values, to be zero.
+            if ((isClosed && evaluated.isNearlyZero()) || !isClosed) {
+                const excluded = this.excluded.has(solution);
+                this.add(solution);
+                retval = !excluded;
+            }
+        }
+        catch (e) {
+            if (e instanceof errors_1.DivisionByZeroError) {
+                this.excluded.add(solution);
+                this.delete(solution);
+            }
+        }
+        return retval;
+    }
+    /**
+     * Replaces a parser-indexed solution while preserving Expression-only membership and
+     * uniqueness.
+     */
+    __set__(indices, value) {
+        if (!Expression_1.Expression.isExpression(value)) {
+            throw new errors_1.UnexpectedDataType((0, errors_1.message)('expressionExpected', { type: value.dataType }));
+        }
+        if (this.excluded.has(value)) {
+            const index = indices[0];
+            if (index < 0 || index >= this.count()) {
+                throw new RangeError((0, errors_1.message)('indexOutOfBounds', {
+                    index: String(index),
+                    type: String(this.dataType),
+                    length: String(this.count()),
+                }));
+            }
+            const current = this.at(index);
+            if (current) {
+                this.delete(current);
+            }
+        }
+        else {
+            super.__set__(indices, value);
+        }
+    }
+    /**
+     * Adds an accepted solution unless it is already present or explicitly excluded.
+     */
+    add(x) {
+        if (!Expression_1.Expression.isExpression(x)) {
+            const entity = x;
+            throw new errors_1.UnexpectedDataType((0, errors_1.message)('expressionExpected', { type: entity.dataType }));
+        }
+        if (!this.excluded.has(x)) {
+            super.add(x);
+        }
+        return this;
+    }
+    /**
+     * Adds accepted solutions while preserving uniqueness and exclusions.
+     * The iterable is validated before the set is changed, so invalid input cannot leave a
+     * partially updated result.
+     */
+    addMany(x) {
+        const values = [...x];
+        for (const value of values) {
+            if (!Expression_1.Expression.isExpression(value)) {
+                const entity = value;
+                throw new errors_1.UnexpectedDataType((0, errors_1.message)('expressionExpected', { type: entity.dataType }));
+            }
+        }
+        for (const value of values) {
+            this.add(value);
+        }
+        return this;
+    }
+    /**
+     * Stores numerical root-refinement metadata independently of the caller's object.
+     */
+    addRawRoot(root) {
+        this.roots.push({
+            root: new decimal_js_1.default(root.root),
+            iterations: root.iterations,
+            converged: root.converged,
+            error: new decimal_js_1.default(root.error),
+            errorMsg: root.errorMsg,
+        });
+        return this;
+    }
+    /**
+     * Verifies a candidate against the source expression before admitting it to the set.
+     *
+     * Parameterized candidates that cannot yet be closed numerically are preserved. Closed
+     * residuals must evaluate nearly to zero. Candidates that encounter exact division by
+     * zero are recorded as exclusions instead.
+     */
+    addSolution(solution, forFunction, variable) {
+        this.verifyAndAddSolution(solution, forFunction, variable);
+        return this;
+    }
+    /**
+     * Verifies and adds every candidate in an array or another `SolutionSet`.
+     *
+     * When the source is a `SolutionSet`, its numerical/symbolic provenance is retained if
+     * at least one source descriptor survives verification. Context-specific metadata such as
+     * exclusions, raw roots, partial state, and unresolved expressions is not transferred;
+     * use {@link append} when the complete solver result should be merged without revalidation.
+     */
+    addSolutions(arr, forFunction, variable) {
+        let source;
+        let solutions;
+        if (SolutionSet.isSolutionSet(arr)) {
+            source = arr;
+            solutions = arr.elements;
+        }
+        else {
+            solutions = arr;
+        }
+        let sourceAccepted = false;
+        for (const sol of solutions) {
+            if (this.verifyAndAddSolution(sol, forFunction, variable)) {
+                sourceAccepted = true;
+            }
+        }
+        if (source && sourceAccepted) {
+            this.mergeSolutionsType(source.solutionsType);
+        }
+        return this;
+    }
+    /**
+     * Adds a batch of numerical solutions that has already been validated against its source
+     * polynomial. Incoming values are deduplicated by their exact numeric components before
+     * storage so a numerical root batch does not require pairwise symbolic equality checks.
+     *
+     * @internal
+     */
+    addValidatedNumericalSolutions(values) {
+        const candidates = [...values];
+        const existing = this.elements;
+        const keys = new Set();
+        for (const value of candidates) {
+            if (!Expression_1.Expression.isExpression(value)) {
+                const entity = value;
+                throw new errors_1.UnexpectedDataType((0, errors_1.message)('expressionExpected', { type: entity.dataType }));
+            }
+            const real = value.isComplex() ? value.realPart() : value;
+            const imaginary = value.isComplex() ? value.imagPart() : Expression_1.Expression.Number(0);
+            if (!real.isNUM() || !imaginary.isNUM()) {
+                throw new errors_1.UnexpectedDataType((0, errors_1.message)('expressionExpected', { type: value.dataType }));
+            }
+            const realMultiplier = real.getMultiplier();
+            const imaginaryMultiplier = imaginary.getMultiplier();
+            const key = `${realMultiplier.numerator}/${realMultiplier.denominator}|` +
+                `${imaginaryMultiplier.numerator}/${imaginaryMultiplier.denominator}`;
+            if (keys.has(key) || this.excluded.has(value)) {
+                continue;
+            }
+            let present = false;
+            for (const stored of existing) {
+                if (stored.eq(value) && value.eq(stored)) {
+                    present = true;
+                    break;
+                }
+            }
+            if (!present) {
+                this.addKnownUnique(value);
+                keys.add(key);
+            }
+        }
+        return this;
+    }
+    /**
+     * Appends another solution result while preserving set and solver metadata.
+     *
+     * @remarks
+     * Exclusions are merged before accepted values so an excluded candidate cannot be
+     * reintroduced. Raw numerical-root records are copied. `partial` is combined with logical
+     * OR and differing defined solution types become `mixed`. If this set has no `unsolved`
+     * expression, the appended set's unresolved expression is copied; when both sets already
+     * carry different unresolved expressions, the receiver's value is retained because the
+     * current data model can represent only one such expression.
+     */
+    append(s) {
+        const transferUnique = this.count() === 0 && this.excluded.count() === 0;
+        this.exclude(s.getExcluded());
+        if (transferUnique) {
+            for (const solution of s.elements) {
+                this.addKnownUnique(solution);
+            }
+        }
+        else {
+            this.addMany(s.elements);
+        }
+        for (const root of s.getRawRoots()) {
+            this.addRawRoot(root);
+        }
+        this.partial = this.partial || s.partial;
+        this.mergeSolutionsType(s.solutionsType);
+        if (!this.unsolved && s.unsolved) {
+            this.unsolved = s.unsolved.copy();
+        }
+        return this;
+    }
+    /**
+     * Appends numerical solutions that were already validated by a numerical solver.
+     *
+     * This follows the same metadata and exclusion handling as {@link append}, but avoids
+     * repeating symbolic membership checks for a batch that has already been numerically
+     * validated and deduplicated.
+     *
+     * @internal
+     */
+    appendValidatedNumerical(s) {
+        this.exclude(s.getExcluded());
+        this.addValidatedNumericalSolutions(s.elements);
+        for (const root of s.getRawRoots()) {
+            this.addRawRoot(root);
+        }
+        this.partial = this.partial || s.partial;
+        this.mergeSolutionsType(s.solutionsType);
+        if (!this.unsolved && s.unsolved) {
+            this.unsolved = s.unsolved.copy();
+        }
+        return this;
+    }
+    /** Returns an independent Expression copy at the requested insertion-order index. */
+    at(i) {
+        return super.at(i);
+    }
+    /**
+     * Removes accepted solutions and all solver state so the instance can be reused.
+     */
+    clear() {
+        super.clear();
+        this.excluded.clear();
+        this.roots.length = 0;
+        this.partial = false;
+        this.solutionsType = undefined;
+        this.unsolved = undefined;
+        return this;
+    }
+    /** Returns an independent copy including exclusions and raw-root metadata. */
+    copy() {
+        const copy = new SolutionSet(this.elements);
+        copy.excluded = this.excluded.copy();
+        copy.roots = this.getRawRoots();
+        copy.solutionsType = this.solutionsType;
+        copy.partial = this.partial;
+        if (this.unsolved) {
+            copy.unsolved = this.unsolved.copy();
+        }
+        return copy;
+    }
+    each(callback) {
+        super.each((e, i, j) => {
+            if (!Expression_1.Expression.isExpression(e)) {
+                throw new errors_1.UnexpectedDataType((0, errors_1.message)('expressionExpected', { type: e.dataType }));
+            }
+            const mapped = callback(e, i, j);
+            if (mapped === undefined) {
+                return e;
+            }
+            if (!Expression_1.Expression.isExpression(mapped)) {
+                throw new errors_1.UnexpectedDataType((0, errors_1.message)('expressionExpected', { type: mapped.dataType }));
+            }
+            return mapped;
+        });
+        for (const value of this.excluded.elements) {
+            this.delete(value);
+        }
+        return this;
+    }
+    /** Returns deep-copied accepted solution descriptors in deterministic insertion order. */
+    get elements() {
+        return super.elements;
+    }
+    evaluate(values) {
+        return this.copy().each(e => e.evaluate(values));
+    }
+    /**
+     * Adds exclusions and removes any matching values that were already accepted.
+     */
+    exclude(set) {
+        const values = set.elements;
+        for (const value of values) {
+            if (!Expression_1.Expression.isExpression(value)) {
+                throw new errors_1.UnexpectedDataType((0, errors_1.message)('expressionExpected', { type: value.dataType }));
+            }
+        }
+        for (const value of values) {
+            this.excluded.add(value);
+            this.delete(value);
+        }
+        return this;
+    }
+    expand() {
+        return this.copy().each(e => e.expand());
+    }
+    /** Visits independent Expression copies without changing this solution set. */
+    forEach(callback) {
+        const values = this.elements;
+        for (let i = 0; i < values.length; i++) {
+            callback(values[i], i);
+        }
+    }
+    /** Returns an independent copy of the currently excluded values. */
+    getExcluded() {
+        return this.excluded.copy();
+    }
+    /**
+     * Returns independent copies of the stored numerical root-refinement records.
+     */
+    getRawRoots() {
+        return this.roots.map(root => ({
+            root: new decimal_js_1.default(root.root),
+            iterations: root.iterations,
+            converged: root.converged,
+            error: new decimal_js_1.default(root.error),
+            errorMsg: root.errorMsg,
+        }));
+    }
+    /**
+     * Classifies the mathematical result represented by the stored descriptors.
+     *
+     * Arbitrary symbolic parameters do not make a result parametric in this sense. The
+     * `parametric` form is reserved for solver-generated families that contain `_n`, where
+     * `_n` represents an integer index. The special `all` descriptor takes precedence if
+     * present.
+     */
+    get solutionForm() {
+        let retval = 'finite';
+        for (const solution of this.elements) {
+            if (solution.eq(constants_1.ALL_SYMBOL)) {
+                retval = 'all';
+                break;
+            }
+            if (solution.hasVariable(constants_1.INDEX_VARIABLE)) {
+                retval = 'parametric';
+            }
+        }
+        return retval;
+    }
+    /** Iterates over independent Expression copies of the accepted solutions. */
+    [Symbol.iterator]() {
+        return this.elements[Symbol.iterator]();
+    }
+    text() {
+        return super.text();
+    }
+    /** Returns deep-copied accepted solutions as a plain array. */
+    toArray() {
+        return this.elements;
+    }
+}
+exports.SolutionSet = SolutionSet;

package/output/solve/classes/Solver.d.ts

@@ -0,0 +1,17 @@
+import { Expression } from '../../core/classes/expression/Expression';
+import type { ExpressionInput } from '../../core/types';
+import type Decimal from 'decimal.js';
+export declare class Solver {
+    epsilon: number;
+    newtonEpsilon: number;
+    newtonMaxIterations: number;
+    newtonMaxSymbolicIterations: number;
+    rootsPerSide: number;
+    searchRadius: number;
+    symbolicEpsilon: number;
+    getPoints(f: (x: number) => number, start?: number, step?: number): number[];
+    newton(f: (x: number) => number, point: number): number | undefined;
+    newtonSymbolic(f: Expression, p: Expression, variable: string): Decimal | undefined;
+    solve(f: ExpressionInput): number[];
+    solveSymbolic(f: ExpressionInput): Decimal[];
+}

package/output/solve/classes/Solver.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Solver = void 0;
+const diff_1 = require("../../calculus/derivative/diff");
+const Expression_1 = require("../../core/classes/expression/Expression");
+const numeric_1 = require("../../core/functions/numeric");
+class Solver {
+    // The numeric epsilon to be used
+    epsilon = 1e-13;
+    // The epsilon to be used when solving newton
+    newtonEpsilon = Number.EPSILON * 2;
+    // The maximum number of iteration for newton
+    newtonMaxIterations = 200;
+    newtonMaxSymbolicIterations = 50;
+    // The maximum roots to search for at each side
+    rootsPerSide = 10;
+    // The extend to which roots will be searched for
+    searchRadius = 100;
+    // const f = (x) => { return x ** 3 + 2 * x ** 2 - 1 }; // Gives false positives
+    symbolicEpsilon = 1e-16;
+    getPoints(f, start = 0, step = 1) {
+        const points = [];
+        // Roots found. This should be reset for each side
+        let roots = 0;
+        const testAndAdd = (point) => {
+            // Test if it's zero at that point
+            if (f(point) === 0 || Math.sign(f(point - step)) !== Math.sign(f(point + step))) {
+                points.push(point);
+                roots++;
+                return true;
+            }
+            return false;
+        };
+        const leftEnd = start - this.searchRadius;
+        const rightEnd = start + this.searchRadius;
+        // Test the right side
+        let n = start;
+        while (n < rightEnd) {
+            testAndAdd(n);
+            if (roots === this.rootsPerSide) {
+                break;
+            }
+            n += step;
+        }
+        // Test the left side
+        n = start;
+        roots = 0;
+        while (n > leftEnd) {
+            testAndAdd(n);
+            if (roots === this.rootsPerSide) {
+                break;
+            }
+            n -= step;
+        }
+        return points;
+    }
+    newton(f, point) {
+        let iters = 0;
+        let x0 = point;
+        const fp = (0, numeric_1.diff)(f);
+        let x;
+        let e;
+        do {
+            const fx0 = f(x0); //store the result of the function
+            //if the value is zero then we're done because 0 - (0/d f(x0)) = 0
+            if (x0 === 0 && fx0 === 0) {
+                x = 0;
+                break;
+            }
+            iters++;
+            if (iters > this.newtonMaxIterations) {
+                return;
+            } //maximum iterations reached
+            x = x0 - fx0 / fp(x0);
+            e = Math.abs(x - x0);
+            x0 = x;
+        } while (e > this.newtonEpsilon);
+        //check if the number is indeed zero. 1e-13 seems to give the most accurate results
+        if (Math.abs(f(x)) <= this.epsilon) {
+            return x;
+        }
+    }
+    newtonSymbolic(f, p, variable) {
+        let iters = 0;
+        let x0 = p.getMultiplier().toDecimal();
+        const fp = (0, diff_1.diff)(f, variable);
+        const values = { [variable]: p };
+        let x;
+        let e;
+        do {
+            const fx0 = f.evaluate(values);
+            if (iters++ > this.newtonMaxSymbolicIterations) {
+                return;
+            } //maximum iterations reached
+            x = x0.minus(fx0.div(fp.evaluate(values)).text({ decimal: true }));
+            // tracker = tracker.minus(fx0S.div(Expression.create(fp, values)))
+            e = x.minus(x0).abs();
+            x0 = x;
+            values[variable] = x0.isFinite() ? Expression_1.Expression.Number(x0) : x0.toString();
+        } while (e.abs().gte(this.symbolicEpsilon));
+        // console.log(tracker.toString())
+        return x;
+    }
+    solve(f) {
+        f = Expression_1.Expression.create(f);
+        const g = f.buildFunction();
+        const points = this.getPoints(g);
+        const solutions = [];
+        for (const p of points) {
+            const solution = this.newton(g, p);
+            if (solution !== undefined) {
+                solutions.push(solution);
+            }
+        }
+        return [...new Set(solutions)];
+    }
+    solveSymbolic(f) {
+        f = Expression_1.Expression.create(f);
+        const g = f.buildFunction();
+        const points = this.getPoints(g);
+        const variable = f.variables()[0];
+        const solutions = {};
+        for (const p of points) {
+            const solution = this.newtonSymbolic(f, Expression_1.Expression.Number(p), variable);
+            if (solution !== undefined) {
+                solutions[solution.toString()] = solution;
+            }
+        }
+        return Object.values(solutions);
+    }
+}
+exports.Solver = Solver;

package/output/solve/classes/SymbolicSolver.d.ts

@@ -0,0 +1,74 @@
+import { Expression } from '../../core/classes/expression/Expression';
+import { Polynomial } from '../../core/classes/polynomial/Polynomial';
+import type { ExpressionInput } from '../../core/types';
+/**
+ * Applies a defined set of exact transformations to one equation in one variable.
+ *
+ * Polynomial equations through degree four use closed-form formulas. Other
+ * recognized forms are solved by isolating and inverting elementary functions,
+ * exponentials, logarithmic sums, or a single square-root term. Unsupported
+ * input is reported by {@link solve} as `unsolved` so a caller can select a
+ * different strategy.
+ *
+ * @remarks
+ * This class is the symbolic strategy used by the ordinary solver; it is not a
+ * general proof procedure. Inverse-function results follow the symbolic forms
+ * implemented here, including parameterized families for direct trigonometric
+ * functions. The supplied Expression is retained, while Polynomial input is
+ * converted to its Expression representation.
+ */
+export declare class SymbolicSolver {
+    private static readonly MAX_FN_SOLVE_STEPS;
+    private input;
+    private x;
+    /**
+     * Creates a symbolic solver for `input = 0`.
+     *
+     * @param input - Polynomial or expression whose zeros are sought.
+     * @param v - Plain variable to solve for.
+     * @throws {@link core!UnexpectedInputError} If `v` is not a plain variable.
+     */
+    constructor(input: Polynomial | string | Expression, v: ExpressionInput);
+    /**
+     * Solves `coeffs[3]x^3 + coeffs[2]x^2 + coeffs[1]x + coeffs[0] = 0`
+     * with Cardano's formula.
+     *
+     * @param coeffs - Four coefficients in ascending-power order.
+     * @returns Three symbolic root expressions.
+     */
+    static cubic(coeffs: Expression[]): Expression[];
+    /**
+     * Solves `coeffs[2]x^2 + coeffs[1]x + coeffs[0] = 0` symbolically.
+     *
+     * @param coeffs - Three coefficients in ascending-power order.
+     * @returns The two quadratic-formula roots.
+     */
+    static quadratic(coeffs: Expression[]): Expression[];
+    /**
+     * Solves a quartic from five ascending-power coefficients with Ferrari's method.
+     *
+     * @param coeffs - Coefficients from the constant through fourth-degree term.
+     * @returns Four symbolic root expressions.
+     */
+    static quartic(coeffs: Expression[]): Expression[];
+    /**
+     * Attempts the supported elementary-function and radical transformations.
+     *
+     * @returns Symbolic solutions, or `undefined` when no supported transformation
+     * closes the equation.
+     */
+    private fnSolve;
+    private invertFunction;
+    /** Returns whether any node in the configured input is a function call. */
+    inputContainsFunction(): boolean;
+    /**
+     * Attempts polynomial formulas and then supported function transformations.
+     *
+     * @returns An object containing `solutions` and, when the strategy cannot
+     * solve the equation, the original `unsolved` expression.
+     */
+    solve(): {
+        solutions: Expression[];
+        unsolved: Expression | undefined;
+    };
+}