nerdamer 1.1.13 → 2.0.0-rc.2

package/output/solve/classes/PolynomialSolver.js

@@ -0,0 +1,492 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolynomialSolver = void 0;
+const decimal_js_1 = __importDefault(require("decimal.js"));
+const Complex_1 = require("../../core/classes/complex/Complex");
+const Expression_1 = require("../../core/classes/expression/Expression");
+const Polynomial_1 = require("../../core/classes/polynomial/Polynomial");
+const errors_1 = require("../../core/errors");
+const bigint_1 = require("../../core/functions/bigint/bigint");
+const DEFAULT_PRECISION = 50;
+const DEFAULT_EPSILON = 1e-14;
+const ABERTH_MAX_ITERATIONS = 100;
+const ABERTH_INITIAL_ANGLE_OFFSET = 0.4;
+const ABERTH_RADIUS_SCALE = 0.9;
+const ABERTH_ROOT_SPACING_SCALE = 0.01;
+const ABERTH_CONVERGENCE_SCALE = 1e-2;
+const NEWTON_MAX_ITERATIONS = 20;
+const NEWTON_CONVERGENCE_SCALE = 1e-6;
+const NATIVE_EPSILON_SCALE = 16;
+/**
+ * Finds all complex roots of a univariate polynomial numerically.
+ *
+ * Coefficient arrays use ascending powers: the element at index `k` is the
+ * coefficient of `x^k`. Expression, Polynomial, and string inputs are converted directly
+ * to numerical complex coefficients before solving. Linear and quadratic inputs are handled
+ * directly; higher degrees use simultaneous Aberth iteration followed by
+ * Newton refinement.
+ *
+ * @remarks
+ * The solver temporarily changes the global `decimal.js` precision while
+ * {@link roots} runs and restores the previous precision before returning.
+ * The requested precision controls the numerical work, while `epsilon`
+ * controls convergence and cleanup of numerical noise. Roots are returned
+ * once per polynomial degree, so repeated roots can appear as repeated nearby
+ * approximations.
+ *
+ * This class finds numerical roots; it does not certify completeness or exact
+ * multiplicities for ill-conditioned polynomials.
+ *
+ * @example
+ * ```ts
+ * const solver = new PolynomialSolver('x^2+1', 'x');
+ * const roots = solver.roots();
+ * ```
+ */
+class PolynomialSolver {
+    degree;
+    eps;
+    p;
+    precision;
+    /**
+     * Creates a polynomial root solver.
+     *
+     * @param input - A polynomial expression, Polynomial, polynomial string, or ascending-power
+     * Decimal coefficients.
+     * @param variable - Variable expected in polynomial or string input. It is used to reject
+     * a conflicting variable or multivariate polynomial.
+     * @param precision - Working `decimal.js` precision used while finding roots.
+     * @param epsilon - Numerical convergence tolerance. Defaults to `1e-14`.
+     * @throws {@link core!UnexpectedInputError} If symbolic input is multivariate, uses a
+     * variable different from `variable`, or has nonnumeric coefficients.
+     */
+    constructor(input, variable, precision = DEFAULT_PRECISION, epsilon) {
+        let coefficients;
+        if (Array.isArray(input)) {
+            coefficients = input.map(coefficient => new Complex_1.Complex(coefficient, 0));
+        }
+        else {
+            const polynomialInput = Polynomial_1.Polynomial.isPolynomial(input);
+            const expression = polynomialInput
+                ? input.getExpression()
+                : typeof input === 'string'
+                    ? Expression_1.Expression.create(input)
+                    : input;
+            const variables = polynomialInput ? input.variables : expression.variables();
+            if (!expression.isPolynomialLike()) {
+                throw new errors_1.PolynomialError((0, errors_1.message)('notAPolynomial'));
+            }
+            if (variables.length > 1 ||
+                (variables.length === 1 && variable && variables[0] !== variable)) {
+                throw new errors_1.UnexpectedInputError((0, errors_1.message)('tooManyUnknowns'));
+            }
+            const coefficientVariable = variable ?? variables[0];
+            const coefficientExpressions = coefficientVariable === undefined
+                ? [expression]
+                : expression.coeffs(coefficientVariable).toArray();
+            const numericComponents = coefficientExpressions.map(coefficient => {
+                const real = coefficient.realPart();
+                const imaginary = coefficient.imagPart();
+                if (!real.isNUM() || !imaginary.isNUM()) {
+                    throw new errors_1.UnexpectedInputError((0, errors_1.message)('wrongInput', {
+                        expected: 'numeric polynomial coefficients',
+                        received: coefficient.text(),
+                    }));
+                }
+                return {
+                    real: real.getMultiplier(),
+                    imaginary: imaginary.getMultiplier(),
+                };
+            });
+            const exactRationals = numericComponents.every(component => !component.real.asDecimal && !component.imaginary.asDecimal);
+            if (exactRationals) {
+                const commonDenominator = (0, bigint_1.LCM)(...numericComponents.flatMap(component => [
+                    component.real.denominator,
+                    component.imaginary.denominator,
+                ]));
+                coefficients = numericComponents.map(component => {
+                    const real = component.real.numerator *
+                        (commonDenominator / component.real.denominator);
+                    const imaginary = component.imaginary.numerator *
+                        (commonDenominator / component.imaginary.denominator);
+                    return new Complex_1.Complex(new decimal_js_1.default(String(real)), new decimal_js_1.default(String(imaginary)));
+                });
+            }
+            else {
+                coefficients = numericComponents.map(component => new Complex_1.Complex(component.real.toDecimal(), component.imaginary.toDecimal()));
+            }
+        }
+        // Reverse the coefficients so p[0] is the leading coefficient
+        this.p = coefficients.slice().reverse();
+        this.degree = this.p.length - 1;
+        this.eps = epsilon || new decimal_js_1.default(DEFAULT_EPSILON);
+        this.precision = precision;
+    }
+    /**
+     * Aberth method: simultaneous approximation of all roots
+     * More stable than deflation for high-degree polynomials
+     */
+    aberthMethod(P) {
+        const n = P.length - 1;
+        // Initialize roots on a circle
+        const roots = [];
+        const radius = this.rootMagnitudeBound(P);
+        for (let k = 0; k < n; k++) {
+            const angle = new decimal_js_1.default(2).mul(Math.PI).mul(k).div(n).plus(ABERTH_INITIAL_ANGLE_OFFSET);
+            const r = radius
+                .mul(ABERTH_RADIUS_SCALE)
+                .mul(new decimal_js_1.default(1).plus(new decimal_js_1.default(k).mul(ABERTH_ROOT_SPACING_SCALE).div(n)));
+            roots.push(new Complex_1.Complex(r.mul(decimal_js_1.default.cos(angle)), r.mul(decimal_js_1.default.sin(angle))));
+        }
+        const epsSquared = this.eps.mul(this.eps);
+        const convergenceTolerance = this.eps.mul(ABERTH_CONVERGENCE_SCALE);
+        const convergenceToleranceSquared = convergenceTolerance.mul(convergenceTolerance);
+        // Aberth iterations
+        for (let iter = 0; iter < ABERTH_MAX_ITERATIONS; iter++) {
+            let maxChangeSquared = new decimal_js_1.default(0);
+            const newRoots = [];
+            for (let i = 0; i < n; i++) {
+                const z = roots[i];
+                // Compute P(z) and P'(z) together.
+                const [pz, dpz] = this.evaluateWithDerivative(P, z);
+                if (dpz.absSquared().lessThan(epsSquared)) {
+                    newRoots.push(z);
+                    continue;
+                }
+                // Compute Aberth correction
+                const newton = pz.div(dpz);
+                // Sum of 1/(z_i - z_j) for j != i
+                let sum = new Complex_1.Complex(0, 0);
+                for (let j = 0; j < n; j++) {
+                    if (i !== j) {
+                        const diff = z.sub(roots[j]);
+                        if (diff.absSquared().greaterThan(epsSquared)) {
+                            sum = sum.add(diff.reciprocal());
+                        }
+                    }
+                }
+                // Aberth correction: w = N(z) / (1 - N(z) * sum)
+                const denom = new Complex_1.Complex(1, 0).sub(newton.mul(sum));
+                const correction = denom.absSquared().lessThan(epsSquared)
+                    ? newton
+                    : newton.div(denom);
+                const newZ = z.sub(correction);
+                newRoots.push(newZ);
+                const changeSquared = correction.absSquared();
+                if (changeSquared.greaterThan(maxChangeSquared)) {
+                    maxChangeSquared = changeSquared;
+                }
+            }
+            for (let i = 0; i < n; i++) {
+                roots[i] = newRoots[i];
+            }
+            // Check convergence
+            if (maxChangeSquared.lessThan(convergenceToleranceSquared)) {
+                break;
+            }
+        }
+        // Final refinement with Newton's method
+        for (let i = 0; i < n; i++) {
+            roots[i] = this.newtonRefine(P, roots[i]);
+        }
+        return roots;
+    }
+    complexSqrt(z) {
+        const mag = z.abs();
+        if (mag.isZero()) {
+            return new Complex_1.Complex(0, 0);
+        }
+        const x = z.re;
+        const y = z.im;
+        if (y.abs().lessThan(this.eps)) {
+            if (x.greaterThanOrEqualTo(0)) {
+                return new Complex_1.Complex(x.sqrt(), 0);
+            }
+            else {
+                return new Complex_1.Complex(0, x.neg().sqrt());
+            }
+        }
+        const w = mag.plus(x.abs()).div(2).sqrt();
+        if (x.greaterThanOrEqualTo(0)) {
+            return new Complex_1.Complex(w, y.div(w.mul(2)));
+        }
+        else {
+            const absY = y.abs();
+            const imPart = y.greaterThanOrEqualTo(0) ? w : w.neg();
+            return new Complex_1.Complex(absY.div(w.mul(2)), imPart);
+        }
+    }
+    /**
+     * Evaluates a polynomial and its derivative together using Horner's method.
+     */
+    evaluateWithDerivative(P, z) {
+        const n = P.length - 1;
+        let value = P[0];
+        let derivative = P[0];
+        for (let i = 1; i < n; i++) {
+            value = value.mul(z).add(P[i]);
+            derivative = derivative.mul(z).add(value);
+        }
+        value = value.mul(z).add(P[n]);
+        return [value, derivative];
+    }
+    finalize(roots, asExpressions, precision, cleanupComponents = true) {
+        // Restore the precision
+        decimal_js_1.default.set({ precision: precision });
+        if (asExpressions) {
+            return roots.map(root => {
+                let re = root.re;
+                let im = root.im;
+                if (cleanupComponents) {
+                    const magnitude = root.abs();
+                    const componentTolerance = magnitude.mul(this.eps);
+                    re = root.re.abs().lt(componentTolerance) ? new decimal_js_1.default(0) : root.re;
+                    im = root.im.abs().lt(componentTolerance) ? new decimal_js_1.default(0) : root.im;
+                }
+                const retval = Expression_1.Expression.create(re).plus(Expression_1.Expression.Img().times(im));
+                return retval;
+            });
+        }
+        return roots;
+    }
+    isNumericalRoot(root) {
+        let residual = this.p[0];
+        let scale = this.p[0].abs();
+        const magnitude = root.abs();
+        for (let i = 1; i < this.p.length; i++) {
+            residual = residual.mul(root).add(this.p[i]);
+            scale = scale.mul(magnitude).plus(this.p[i].abs());
+        }
+        const tolerance = this.eps.mul(scale.plus(1));
+        return residual.absSquared().lte(tolerance.mul(tolerance));
+    }
+    /**
+     * Uses native double-precision arithmetic to locate starting points for Decimal refinement.
+     *
+     * Returning `null` leaves the existing Decimal Aberth implementation responsible for the
+     * complete solve.
+     */
+    nativeAberthSeeds(P) {
+        const n = P.length - 1;
+        const nativeP = [];
+        for (const coefficient of P) {
+            const re = coefficient.re.toNumber();
+            const im = coefficient.im.toNumber();
+            if (!Number.isFinite(re) || !Number.isFinite(im)) {
+                return null;
+            }
+            nativeP.push({ re, im });
+        }
+        const leadMagnitude = Math.hypot(nativeP[0].re, nativeP[0].im);
+        if (!Number.isFinite(leadMagnitude) || leadMagnitude === 0) {
+            return null;
+        }
+        const radius = this.rootMagnitudeBound(P).toNumber();
+        if (!Number.isFinite(radius)) {
+            return null;
+        }
+        const roots = [];
+        for (let k = 0; k < n; k++) {
+            const angle = (2 * Math.PI * k) / n + ABERTH_INITIAL_ANGLE_OFFSET;
+            const r = radius *
+                ABERTH_RADIUS_SCALE *
+                (1 + (k * ABERTH_ROOT_SPACING_SCALE) / n);
+            roots.push({ re: r * Math.cos(angle), im: r * Math.sin(angle) });
+        }
+        const nativeTolerance = Math.max(this.eps.toNumber(), Number.EPSILON * NATIVE_EPSILON_SCALE);
+        const epsSquared = nativeTolerance * nativeTolerance;
+        for (let iter = 0; iter < ABERTH_MAX_ITERATIONS; iter++) {
+            let maxChangeSquared = 0;
+            const newRoots = [];
+            for (let i = 0; i < n; i++) {
+                const z = roots[i];
+                let valueRe = nativeP[0].re;
+                let valueIm = nativeP[0].im;
+                let derivativeRe = nativeP[0].re;
+                let derivativeIm = nativeP[0].im;
+                for (let k = 1; k < n; k++) {
+                    const nextValueRe = valueRe * z.re - valueIm * z.im + nativeP[k].re;
+                    const nextValueIm = valueRe * z.im + valueIm * z.re + nativeP[k].im;
+                    const nextDerivativeRe = derivativeRe * z.re - derivativeIm * z.im + nextValueRe;
+                    const nextDerivativeIm = derivativeRe * z.im + derivativeIm * z.re + nextValueIm;
+                    valueRe = nextValueRe;
+                    valueIm = nextValueIm;
+                    derivativeRe = nextDerivativeRe;
+                    derivativeIm = nextDerivativeIm;
+                }
+                const finalValueRe = valueRe * z.re - valueIm * z.im + nativeP[n].re;
+                const finalValueIm = valueRe * z.im + valueIm * z.re + nativeP[n].im;
+                const derivativeMagnitudeSquared = derivativeRe * derivativeRe + derivativeIm * derivativeIm;
+                if (!Number.isFinite(finalValueRe) ||
+                    !Number.isFinite(finalValueIm) ||
+                    !Number.isFinite(derivativeMagnitudeSquared)) {
+                    return null;
+                }
+                if (derivativeMagnitudeSquared < epsSquared) {
+                    newRoots.push(z);
+                    continue;
+                }
+                const newtonRe = (finalValueRe * derivativeRe + finalValueIm * derivativeIm) /
+                    derivativeMagnitudeSquared;
+                const newtonIm = (finalValueIm * derivativeRe - finalValueRe * derivativeIm) /
+                    derivativeMagnitudeSquared;
+                let sumRe = 0;
+                let sumIm = 0;
+                for (let j = 0; j < n; j++) {
+                    if (i === j) {
+                        continue;
+                    }
+                    const diffRe = z.re - roots[j].re;
+                    const diffIm = z.im - roots[j].im;
+                    const diffMagnitudeSquared = diffRe * diffRe + diffIm * diffIm;
+                    if (diffMagnitudeSquared > epsSquared) {
+                        sumRe += diffRe / diffMagnitudeSquared;
+                        sumIm -= diffIm / diffMagnitudeSquared;
+                    }
+                }
+                const productRe = newtonRe * sumRe - newtonIm * sumIm;
+                const productIm = newtonRe * sumIm + newtonIm * sumRe;
+                const denomRe = 1 - productRe;
+                const denomIm = -productIm;
+                const denomMagnitudeSquared = denomRe * denomRe + denomIm * denomIm;
+                let correctionRe = newtonRe;
+                let correctionIm = newtonIm;
+                if (denomMagnitudeSquared >= epsSquared) {
+                    correctionRe =
+                        (newtonRe * denomRe + newtonIm * denomIm) / denomMagnitudeSquared;
+                    correctionIm =
+                        (newtonIm * denomRe - newtonRe * denomIm) / denomMagnitudeSquared;
+                }
+                const newRoot = {
+                    re: z.re - correctionRe,
+                    im: z.im - correctionIm,
+                };
+                const changeSquared = correctionRe * correctionRe + correctionIm * correctionIm;
+                if (!Number.isFinite(newRoot.re) ||
+                    !Number.isFinite(newRoot.im) ||
+                    !Number.isFinite(changeSquared)) {
+                    return null;
+                }
+                newRoots.push(newRoot);
+                maxChangeSquared = Math.max(maxChangeSquared, changeSquared);
+            }
+            for (let i = 0; i < n; i++) {
+                roots[i] = newRoots[i];
+            }
+            if (maxChangeSquared < epsSquared) {
+                break;
+            }
+        }
+        return roots.map(root => new Complex_1.Complex(new decimal_js_1.default(root.re), new decimal_js_1.default(root.im)));
+    }
+    /**
+     * Refine a single root using Newton's method
+     */
+    newtonRefine(P, z) {
+        const epsSquared = this.eps.mul(this.eps);
+        const convergenceTolerance = this.eps.mul(NEWTON_CONVERGENCE_SCALE);
+        const convergenceToleranceSquared = convergenceTolerance.mul(convergenceTolerance);
+        for (let iter = 0; iter < NEWTON_MAX_ITERATIONS; iter++) {
+            const [pz, dpz] = this.evaluateWithDerivative(P, z);
+            if (pz.absSquared().lessThan(convergenceToleranceSquared)) {
+                break;
+            }
+            if (dpz.absSquared().lessThan(epsSquared)) {
+                break;
+            }
+            const correction = pz.div(dpz);
+            const newZ = z.sub(correction);
+            if (correction.abs().lessThan(convergenceTolerance.mul(newZ.abs().plus(1)))) {
+                z = newZ;
+                break;
+            }
+            z = newZ;
+        }
+        return z;
+    }
+    /**
+     * Computes a Lagrange-Fujiwara upper bound for root magnitudes.
+     *
+     * For a polynomial with leading coefficient a_n, every root lies within
+     * 2 * max(|a_(n-i) / a_n|^(1/i)). This is substantially tighter than the
+     * simple Cauchy bound for polynomials with large middle coefficients.
+     *
+     * @see https://doi.org/10.1016/S0377-0427(03)00381-9
+     */
+    rootMagnitudeBound(P) {
+        let maxCandidate = new decimal_js_1.default(0);
+        const leadingMagnitude = P[0].abs();
+        for (let i = 1; i < P.length; i++) {
+            const ratio = P[i].abs().div(leadingMagnitude);
+            if (!ratio.isZero()) {
+                const candidate = ratio.pow(new decimal_js_1.default(1).div(i));
+                if (candidate.greaterThan(maxCandidate)) {
+                    maxCandidate = candidate;
+                }
+            }
+        }
+        return maxCandidate.mul(2);
+    }
+    solveQuadratic(p) {
+        const a = p[0];
+        const b = p[1];
+        const c = p[2];
+        const b2 = b.mul(b);
+        const ac4 = a.mul(c).scale(4);
+        const disc = b2.sub(ac4);
+        const sqrtDisc = this.complexSqrt(disc);
+        const twoA = a.scale(2);
+        const negB = b.neg();
+        return [negB.add(sqrtDisc).div(twoA), negB.sub(sqrtDisc).div(twoA)];
+    }
+    roots(asExpressions = true) {
+        // Store the currently used precision
+        const precision = decimal_js_1.default.precision;
+        // Set the precision to a high number. Default = 50
+        decimal_js_1.default.set({ precision: this.precision });
+        // Remove leading zeros and normalize
+        let poly = [...this.p];
+        let deg = this.degree;
+        while (deg > 0 && poly[0].re.isZero() && poly[0].im.isZero()) {
+            poly.shift();
+            deg--;
+        }
+        if (deg === 0) {
+            return this.finalize([], asExpressions, precision);
+        }
+        const lead = poly[0];
+        poly = poly.map(c => c.div(lead));
+        if (deg === 1) {
+            return this.finalize([poly[1].neg()], asExpressions, precision);
+        }
+        if (deg === 2) {
+            // Quadratic roots are computed analytically, so preserve small components instead of
+            // treating them as iterative noise.
+            return this.finalize(this.solveQuadratic(poly), asExpressions, precision, false);
+        }
+        // Native doubles are sufficient to locate ordinary roots. Refine those seeds with
+        // Decimal arithmetic and accept them only when every root passes the existing residual check.
+        const nativeSeeds = this.nativeAberthSeeds(poly);
+        if (nativeSeeds) {
+            const nativeRoots = nativeSeeds.map(root => this.newtonRefine(poly, root));
+            if (nativeRoots.length === deg &&
+                nativeRoots.every(root => this.isNumericalRoot(root))) {
+                return this.finalize(nativeRoots, asExpressions, precision);
+            }
+        }
+        // Fall back to the Decimal Aberth implementation when native seeding is unavailable
+        // or does not survive Decimal refinement and validation.
+        const roots = this.aberthMethod(poly);
+        return this.finalize(roots, asExpressions, precision);
+    }
+    validatedRoots(asExpressions = true) {
+        const precision = decimal_js_1.default.precision;
+        decimal_js_1.default.set({ precision: this.precision });
+        const roots = this.roots(false).filter(root => this.isNumericalRoot(root));
+        return this.finalize(roots, asExpressions, precision);
+    }
+}
+exports.PolynomialSolver = PolynomialSolver;

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

@@ -0,0 +1,172 @@
+import { Expression } from '../../core/classes/expression/Expression';
+import { SOLUTIONS_SET } from '../../core/classes/parser/constants';
+import { ValuesSet } from '../../core/classes/valuesSet/ValuesSet';
+import type { ParserValuesObject } from '../../core/classes/parser/types';
+import type { ParserEntity } from '../../core/types';
+import type { Root } from './FunctionSolver';
+/** Describes whether accepted solutions were produced by numerical strategies, symbolic strategies, or both. */
+export type SolutionsType = 'numeric' | 'symbolic' | 'mixed' | undefined;
+/** Describes whether the stored descriptors represent finite solutions, indexed families, or all values. */
+export type SolutionForm = 'finite' | 'parametric' | 'all';
+/**
+ * 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.
+ */
+export declare class SolutionSet extends ValuesSet {
+    private excluded;
+    private roots;
+    dataType: typeof SOLUTIONS_SET;
+    partial: boolean;
+    /** Solver provenance for the currently accepted descriptors. */
+    solutionsType: SolutionsType;
+    unsolved?: Expression;
+    constructor(values?: Iterable<Expression>);
+    /** Tests whether a value is specifically a solver `SolutionSet`. */
+    static isSolutionSet(obj: unknown): obj is SolutionSet;
+    /**
+     * Combines numerical/symbolic provenance without changing any other solver state.
+     */
+    private mergeSolutionsType;
+    /**
+     * 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.
+     */
+    private verifyAndAddSolution;
+    /**
+     * Replaces a parser-indexed solution while preserving Expression-only membership and
+     * uniqueness.
+     */
+    __set__(indices: number[], value: ParserEntity): void;
+    /**
+     * Adds an accepted solution unless it is already present or explicitly excluded.
+     */
+    add(x: Expression): SolutionSet;
+    /**
+     * 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: Iterable<Expression>): SolutionSet;
+    /**
+     * Stores numerical root-refinement metadata independently of the caller's object.
+     */
+    addRawRoot(root: Root): SolutionSet;
+    /**
+     * 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: Expression, forFunction: Expression, variable: string): 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: Expression[] | SolutionSet, forFunction: Expression, variable: string): 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: Iterable<Expression>): SolutionSet;
+    /**
+     * 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: SolutionSet): SolutionSet;
+    /**
+     * 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: SolutionSet): SolutionSet;
+    /** Returns an independent Expression copy at the requested insertion-order index. */
+    at(i: number): Expression | undefined;
+    /**
+     * Removes accepted solutions and all solver state so the instance can be reused.
+     */
+    clear(): this;
+    /** Returns an independent copy including exclusions and raw-root metadata. */
+    copy(): SolutionSet;
+    /**
+     * Visits or maps accepted solutions in insertion order.
+     *
+     * Returning an Expression replaces the current solution while preserving uniqueness and
+     * exclusions. Returning `void` leaves the current solution unchanged, which allows the
+     * same method to be used for straightforward inspection without a dummy `return e`.
+     */
+    each(callback: (e: Expression, i?: string | number, j?: string | number) => Expression | void): this;
+    each(callback: (e: ParserEntity, i?: string | number, j?: string | number) => ParserEntity | void): this;
+    /** Returns deep-copied accepted solution descriptors in deterministic insertion order. */
+    get elements(): Expression[];
+    evaluate(values?: ParserValuesObject): SolutionSet;
+    /**
+     * Adds exclusions and removes any matching values that were already accepted.
+     */
+    exclude(set: SolutionSet | ValuesSet): SolutionSet;
+    expand(): SolutionSet;
+    /** Visits independent Expression copies without changing this solution set. */
+    forEach(callback: (e: Expression, index: number) => void): void;
+    /** Returns an independent copy of the currently excluded values. */
+    getExcluded(): ValuesSet;
+    /**
+     * Returns independent copies of the stored numerical root-refinement records.
+     */
+    getRawRoots(): Root[];
+    /**
+     * 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(): SolutionForm;
+    /** Iterates over independent Expression copies of the accepted solutions. */
+    [Symbol.iterator](): Iterator<Expression>;
+    text(): string;
+    /** Returns deep-copied accepted solutions as a plain array. */
+    toArray(): Expression[];
+}