nerdamer 1.1.13 → 2.0.0-rc.1

package/output/solve/classes/FunctionSolver.js

@@ -0,0 +1,433 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FunctionSolver = void 0;
+const decimal_js_1 = __importDefault(require("decimal.js"));
+const Expression_1 = require("../../core/classes/expression/Expression");
+const errors_1 = require("../../core/errors");
+const DEFAULT_LOWER_BOUND = -100;
+const DEFAULT_UPPER_BOUND = 100;
+const DEFAULT_DERIVATIVE_STEP = 1e-15;
+const DEFAULT_MAX_ITERATIONS = 200;
+const DEFAULT_STEP_SIZE = 0.1;
+const DEFAULT_TOLERANCE = 1e-14;
+const DEFAULT_MAX_ROOTS = 20;
+const BRENT_METHOD = 'Brent';
+const NEWTON_RAPHSON_METHOD = 'NewtonRaphson';
+const DEFAULT_ROOT_FINDING_METHOD = BRENT_METHOD;
+/**
+ * Searches a fixed interval for real roots of a univariate expression.
+ *
+ * @remarks
+ * {@link roots} scans the configured interval from its center toward both
+ * endpoints. It refines sign-changing intervals with Brent's method or
+ * Newton-Raphson, verifies residuals, merges nearby results, and returns roots
+ * in ascending order. This is a heuristic search: an even-multiplicity root
+ * can be missed unless a scan point lands sufficiently close to it, and
+ * periodic functions are limited by both the interval and `maxRoots`.
+ *
+ * Calculations use the ambient `decimal.js` precision. An Expression supplied
+ * to the constructor is retained rather than copied, and the public settings
+ * may be adjusted before a search.
+ *
+ * @example
+ * ```ts
+ * const solver = new FunctionSolver('cos(x)-x', 'x', {
+ *     lowerBound: 0,
+ *     upperBound: 1,
+ * });
+ * const roots = solver.roots();
+ * ```
+ */
+class FunctionSolver {
+    derivativeStep;
+    func;
+    lowerBound;
+    maxIters;
+    maxRoots;
+    method;
+    stepSize;
+    tolerance;
+    upperBound;
+    variable;
+    verbose;
+    /**
+     * Creates a real-root solver for the configured search interval.
+     *
+     * @param func - Expression to evaluate, or a string parsed as an Expression.
+     * @param variable - Variable to substitute. When omitted, the expression must
+     * contain at most one variable.
+     * @param options - Search interval, refinement method, and tolerances.
+     * @throws {@link core!UnsupportedOperationError} If `variable` is omitted and the
+     * expression contains more than one variable.
+     */
+    constructor(func, variable, options = {}) {
+        this.func = typeof func === 'string' ? Expression_1.Expression.create(func) : func;
+        this.lowerBound = new decimal_js_1.default(options.lowerBound ?? DEFAULT_LOWER_BOUND);
+        this.upperBound = new decimal_js_1.default(options.upperBound ?? DEFAULT_UPPER_BOUND);
+        this.derivativeStep = new decimal_js_1.default(options.derivativeStep ?? DEFAULT_DERIVATIVE_STEP);
+        this.maxIters = options.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+        this.variable = variable ?? this.getVariable();
+        this.stepSize = options.stepSize ?? DEFAULT_STEP_SIZE;
+        this.tolerance = new decimal_js_1.default(options.tolerance ?? DEFAULT_TOLERANCE);
+        this.maxRoots = options.maxRoots ?? DEFAULT_MAX_ROOTS;
+        this.verbose = options.verbose ?? false;
+        this.method = options.method ?? DEFAULT_ROOT_FINDING_METHOD;
+    }
+    calculateIntervals() {
+        const lower = this.lowerBound;
+        const upper = this.upperBound;
+        const step = new decimal_js_1.default(this.stepSize);
+        const length = upper.minus(lower);
+        const center = lower.plus(length.dividedBy(2).floor());
+        let x = center;
+        let u = center;
+        const intervals = [];
+        const lowerDistance = center.minus(lower);
+        const upperDistance = upper.minus(center);
+        const maxInterval = lowerDistance.greaterThan(upperDistance)
+            ? lowerDistance
+            : upperDistance;
+        for (let offset = new decimal_js_1.default(0); offset.lessThan(maxInterval); offset = offset.plus(step)) {
+            const y = x.minus(step);
+            const v = u.plus(step);
+            // Add the lower interval if it is still within bounds.
+            if (y.greaterThanOrEqualTo(lower)) {
+                intervals.push([x, y]);
+            }
+            // Add the upper interval if it is still within bounds.
+            if (v.lessThanOrEqualTo(upper)) {
+                intervals.push([u, v]);
+            }
+            x = y;
+            u = v;
+        }
+        return intervals;
+    }
+    getVariable() {
+        const variables = this.func.variables();
+        // This function can only handle univariate function
+        if (variables.length > 1) {
+            throw new errors_1.UnsupportedOperationError((0, errors_1.message)('univariateInputOnly'));
+        }
+        return variables[0];
+    }
+    /**
+     * Refines a bracket using Brent's combination of bisection, secant, and
+     * inverse-quadratic interpolation.
+     *
+     * @param a - First bracket endpoint.
+     * @param b - Second bracket endpoint.
+     * @returns Refinement metadata. Invalid brackets and exhausted iterations are
+     * represented in the returned {@link Root}; they are not thrown.
+     */
+    Brent(a, b) {
+        // Convert inputs to Decimal
+        let aVal = new decimal_js_1.default(a);
+        let bVal = new decimal_js_1.default(b);
+        const tol = this.tolerance;
+        let fa = this.evaluate(aVal);
+        let fb = this.evaluate(bVal);
+        const error = new decimal_js_1.default(Infinity);
+        // Check if root is at endpoint
+        if (fa.abs().lessThan(tol)) {
+            return {
+                root: aVal,
+                iterations: 0,
+                converged: false,
+                error: error,
+                errorMsg: (0, errors_1.message)('endPointIsRoot'),
+            };
+        }
+        if (fb.abs().lessThan(tol)) {
+            return {
+                root: bVal,
+                iterations: 0,
+                converged: true,
+                error: error,
+                errorMsg: (0, errors_1.message)('endPointIsRoot'),
+            };
+        }
+        const x = fa.times(fb);
+        // Ensure f(a) and f(b) have opposite signs
+        if (x.greaterThan(0)) {
+            return {
+                root: x,
+                iterations: 0,
+                converged: true,
+                error: error,
+                errorMsg: (0, errors_1.message)('differentSignsAtEndPointsRequired'),
+            };
+        }
+        // Ensure |f(a)| >= |f(b)|
+        if (fa.abs().lessThan(fb.abs())) {
+            [aVal, bVal] = [bVal, aVal];
+            [fa, fb] = [fb, fa];
+        }
+        let c = aVal;
+        let fc = fa;
+        let mflag = true;
+        let d = new decimal_js_1.default(0);
+        for (let iter = 0; iter < this.maxIters; iter++) {
+            let s;
+            // Use inverse quadratic interpolation if f(a), f(b), f(c) are distinct
+            if (!fa.equals(fc) && !fb.equals(fc)) {
+                s = aVal
+                    .times(fb)
+                    .times(fc)
+                    .dividedBy(fa.minus(fb).times(fa.minus(fc)))
+                    .plus(bVal
+                    .times(fa)
+                    .times(fc)
+                    .dividedBy(fb.minus(fa).times(fb.minus(fc))))
+                    .plus(c
+                    .times(fa)
+                    .times(fb)
+                    .dividedBy(fc.minus(fa).times(fc.minus(fb))));
+            }
+            else {
+                // Use secant method
+                s = bVal.minus(fb.times(bVal.minus(aVal)).dividedBy(fb.minus(fa)));
+            }
+            // Conditions for bisection
+            const condition1 = s.lessThan(new decimal_js_1.default(3).times(aVal).plus(bVal).dividedBy(4)) ||
+                s.greaterThan(bVal);
+            const condition2 = mflag && s.minus(bVal).abs().greaterThanOrEqualTo(bVal.minus(c).abs().dividedBy(2));
+            const condition3 = !mflag && s.minus(bVal).abs().greaterThanOrEqualTo(c.minus(d).abs().dividedBy(2));
+            const condition4 = mflag && bVal.minus(c).abs().lessThan(tol);
+            const condition5 = !mflag && c.minus(d).abs().lessThan(tol);
+            if (condition1 || condition2 || condition3 || condition4 || condition5) {
+                // Use bisection
+                s = aVal.plus(bVal).dividedBy(2);
+                mflag = true;
+            }
+            else {
+                mflag = false;
+            }
+            const fs = this.evaluate(s);
+            d = c;
+            c = bVal;
+            fc = fb;
+            // Update interval
+            if (fa.times(fs).lessThan(0)) {
+                bVal = s;
+                fb = fs;
+            }
+            else {
+                aVal = s;
+                fa = fs;
+            }
+            // Ensure |f(a)| >= |f(b)|
+            if (fa.abs().lessThan(fb.abs())) {
+                [aVal, bVal] = [bVal, aVal];
+                [fa, fb] = [fb, fa];
+            }
+            const conditionA = fb.abs().lessThan(tol);
+            const conditionB = bVal.minus(aVal).abs().lessThan(tol);
+            // Check convergence
+            if (conditionA || conditionB) {
+                return {
+                    root: bVal,
+                    iterations: iter,
+                    converged: true,
+                    error: conditionA ? fb.abs().minus(tol) : bVal.minus(aVal).abs(),
+                };
+            }
+        }
+        return {
+            root: x,
+            iterations: this.maxIters,
+            converged: false,
+            error: error,
+            errorMsg: (0, errors_1.message)('convergenceFailed', { iter: String(this.maxIters) }),
+        };
+    }
+    /** Approximates the derivative with a central difference. */
+    df(x, h) {
+        const xPlusH = x.plus(h);
+        const xMinusH = x.minus(h);
+        const fPlusH = this.evaluate(xPlusH);
+        const fMinusH = this.evaluate(xMinusH);
+        // Central difference formula: (f(x+h) - f(x-h)) / (2h)
+        return fPlusH.minus(fMinusH).dividedBy(h.times(2));
+    }
+    /**
+     * Evaluates the configured expression at a real value.
+     *
+     * @throws {@link core!UnexpectedInputError} If evaluation does not produce a scalar
+     * Expression.
+     */
+    evaluate(at) {
+        const value = this.func.evaluate({ [this.variable]: at });
+        if (!Expression_1.Expression.isExpression(value)) {
+            throw new errors_1.UnexpectedInputError((0, errors_1.message)('unsupportedType'));
+        }
+        if (!value.isNUM()) {
+            throw new errors_1.UnexpectedInputError((0, errors_1.message)('wrongInput', {
+                expected: 'a real numeric value',
+                received: value.text(),
+            }));
+        }
+        return value.getMultiplier().toDecimal();
+    }
+    /**
+     * Refines a root from an initial guess using Newton-Raphson and a numerical
+     * derivative.
+     *
+     * @returns Refinement metadata, including non-convergence or a zero derivative.
+     */
+    NewtonRaphson(guess) {
+        const tol = this.tolerance;
+        const h = new decimal_js_1.default(this.derivativeStep);
+        let x = new decimal_js_1.default(guess);
+        let iterations = 0;
+        let error = new decimal_js_1.default(Infinity);
+        for (let i = 0; i < this.maxIters; i++) {
+            const fx = this.evaluate(x);
+            const fpx = this.df(x, h);
+            // Check for zero derivative (would cause division by zero)
+            if (fpx.isZero()) {
+                return {
+                    root: x,
+                    iterations: i,
+                    converged: false,
+                    error: fx.abs(),
+                    errorMsg: (0, errors_1.message)('zeroDerivative', { x: x.toString() }),
+                };
+            }
+            // Newton-Raphson update: x_new = x - f(x) / f'(x)
+            const xNew = x.minus(fx.dividedBy(fpx));
+            // Calculate error as the absolute difference between iterations
+            error = xNew.minus(x).abs();
+            iterations = i + 1;
+            // Check for convergence
+            if (error.lessThanOrEqualTo(tol)) {
+                return {
+                    root: xNew,
+                    iterations,
+                    converged: true,
+                    error,
+                };
+            }
+            x = xNew;
+        }
+        // Did not converge within max iterations
+        return {
+            root: x,
+            iterations,
+            converged: false,
+            error,
+        };
+    }
+    /**
+     * Searches the configured interval for real roots.
+     *
+     * @returns Verified, deduplicated roots in ascending order, limited by
+     * `maxRoots`. Failed evaluations and failed refinements are skipped.
+     */
+    roots() {
+        const bVal = this.upperBound;
+        const tol = this.tolerance;
+        const roots = [];
+        let exit = false;
+        const evaluationCache = new Map();
+        const evaluatePoint = (point) => {
+            const key = point.toString();
+            let value = evaluationCache.get(key);
+            if (value === undefined) {
+                value = this.evaluate(point);
+                evaluationCache.set(key, value);
+            }
+            return value;
+        };
+        const addRoot = (root) => {
+            if (this.evaluate(root).abs().lessThan(tol)) {
+                roots.push(root);
+            }
+            // Check if the maximum number of roots was reached. If so we're done
+            if (roots.length >= this.maxRoots) {
+                exit = true;
+            }
+        };
+        const intervals = this.calculateIntervals();
+        for (const interval of intervals) {
+            if (exit) {
+                return roots.sort((a, b) => a.comparedTo(b)).map(x => Expression_1.Expression.create(x));
+            }
+            try {
+                const x1 = new decimal_js_1.default(interval[0]);
+                const x2 = new decimal_js_1.default(interval[1]);
+                const f1 = evaluatePoint(x1);
+                const f2 = evaluatePoint(x2);
+                // Check if root is at subdivision point
+                if (f1.abs().lessThan(tol)) {
+                    // Avoid duplicates
+                    if (roots.length === 0 ||
+                        x1
+                            .minus(roots[roots.length - 1])
+                            .abs()
+                            .greaterThan(tol.times(10))) {
+                        addRoot(x1);
+                    }
+                }
+                // Check for sign change
+                if (f1.times(f2).lessThan(0)) {
+                    try {
+                        let calculation;
+                        switch (this.method) {
+                            case NEWTON_RAPHSON_METHOD: {
+                                // Start at the center of the interval
+                                const centerOfInterval = x2.minus(x1).div(2).plus(x1);
+                                calculation = this.NewtonRaphson(centerOfInterval);
+                                break;
+                            }
+                            case BRENT_METHOD: {
+                                calculation = this.Brent(x1, x2);
+                                break;
+                            }
+                            default: {
+                                calculation = this.Brent(x1, x2);
+                            }
+                        }
+                        if (calculation.converged) {
+                            const root = calculation.root;
+                            // Avoid duplicate roots (within tolerance)
+                            let isDuplicate = false;
+                            for (const existingRoot of roots) {
+                                if (root.minus(existingRoot).abs().lessThan(tol.times(10))) {
+                                    isDuplicate = true;
+                                    break;
+                                }
+                            }
+                            if (!isDuplicate) {
+                                addRoot(root);
+                            }
+                        }
+                    }
+                    catch { }
+                }
+            }
+            catch { }
+        }
+        // Check the final endpoint separately so a root exactly on the upper bound is not missed.
+        // Like endpoints visited during the scan, it may be outside the function's real domain.
+        try {
+            const lastPoint = bVal;
+            const fLast = evaluatePoint(lastPoint);
+            if (fLast.abs().lessThan(tol)) {
+                if (roots.length === 0 ||
+                    lastPoint
+                        .minus(roots[roots.length - 1])
+                        .abs()
+                        .greaterThan(tol.times(10))) {
+                    addRoot(lastPoint);
+                }
+            }
+        }
+        catch { }
+        return roots.sort((a, b) => a.comparedTo(b)).map(x => Expression_1.Expression.create(x));
+    }
+}
+exports.FunctionSolver = FunctionSolver;

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

@@ -0,0 +1,84 @@
+import { Expression } from '../../core/classes/expression/Expression';
+/** Options for the finite-range multi-start search performed by {@link MultivariateSolver}. */
+export interface MultivariateSolverOptions {
+    /** Lower bound for each variable (default: -10) */
+    lowerBound?: number;
+    /** Upper bound for each variable (default: 10) */
+    upperBound?: number;
+    /** Number of grid points per variable (default: 5) */
+    gridPoints?: number;
+    /** Maximum Newton-Raphson iterations per start (default: 100) */
+    maxIterations?: number;
+    /** Convergence tolerance (default: 1e-12) */
+    tolerance?: number;
+    /** Step size for numerical Jacobian (default: 1e-8) */
+    derivativeStep?: number;
+    /** Tolerance for deduplicating roots (default: 1e-8) */
+    deduplicationTolerance?: number;
+}
+/**
+ * Searches numerically for isolated real solutions of a multivariate system.
+ *
+ * Each equation is interpreted as `equation = 0`. The solver starts
+ * Newton-Raphson at every point in a Cartesian grid, approximates the Jacobian
+ * with central differences, and merges nearby converged solutions.
+ *
+ * @remarks
+ * This is a finite-range heuristic rather than a completeness proof. The number
+ * of starts is `gridPoints` raised to the number of variables, so cost grows
+ * rapidly with dimension. Singular Jacobians, failed evaluations, and starts
+ * that do not converge are discarded. Calculations use the ambient
+ * `decimal.js` precision, and the supplied equation and variable arrays are
+ * retained by the solver.
+ *
+ * The numerical linear solve requires a square Jacobian in ordinary use; this
+ * class is intended for isolated solutions of systems with as many equations
+ * as variables.
+ */
+export declare class MultivariateSolver {
+    private dedupTol;
+    private equations;
+    private gridPoints;
+    private h;
+    private lowerBound;
+    private maxIterations;
+    private tolerance;
+    private upperBound;
+    private variables;
+    /**
+     * Creates a multi-start solver over the configured limits.
+     *
+     * @param equations - Expressions interpreted as equations equal to zero.
+     * @param variables - Ordered variables corresponding to solution coordinates.
+     * @param options - Grid, iteration, differentiation, and deduplication settings.
+     */
+    constructor(equations: Expression[], variables: string[], options?: MultivariateSolverOptions);
+    /**
+     * Evaluate all equations at a point, returning a vector of Decimal values.
+     */
+    private evaluateSystem;
+    /**
+     * Generate grid starting points.
+     */
+    private generateStartingPoints;
+    /**
+     * Check if a root is a duplicate of an existing one.
+     */
+    private isDuplicate;
+    /**
+     * Compute the Jacobian matrix numerically using central differences.
+     */
+    private jacobian;
+    /**
+     * Run Newton-Raphson from a single starting point.
+     * Returns the converged root or null if it didn't converge.
+     */
+    private newtonRaphson;
+    /**
+     * Searches for roots from every configured grid point.
+     *
+     * @returns Deduplicated solutions as maps keyed in `variables` order. An empty
+     * array means that no start converged; it does not prove that no root exists.
+     */
+    roots(): Map<string, Expression>[];
+}