@johnhenry/math 0.0.0

package/dist/Symbolic.d.ts

@@ -0,0 +1,501 @@
+import { Rational } from "./Rational.ts";
+import type { Structure } from "./Structure.ts";
+export type FuncName = "sin" | "cos" | "tan" | "exp" | "ln" | "sqrt" | "asin" | "acos" | "atan" | "sinh" | "cosh" | "tanh" | "cot" | "sec" | "csc" | "asinh" | "acosh" | "atanh" | "coth" | "sech" | "csch" | "acot" | "asec" | "acsc" | "acoth" | "asech" | "acsch" | "abs" | "log10" | "log2" | "cbrt" | "floor" | "ceil" | "round" | "sign" | "trunc" | "expm1" | "log1p" | "sigmoid" | "erf" | "relu";
+/** Elementary functions that take exactly two `Expr` operands (see the `call2` `Expr` variant). */
+export type BinaryFuncName = "atan2" | "hypot" | "min" | "max" | "gcd" | "lcm";
+/** Comparison operators (see the `cmp` `Expr` variant). Evaluate to `1`/`0` (boolean-as-number). */
+export type CmpOp = "lt" | "le" | "gt" | "ge" | "eq" | "ne";
+export type Expr = {
+    type: "const";
+    value: number;
+} | {
+    type: "var";
+    name: string;
+} | {
+    type: "add";
+    left: Expr;
+    right: Expr;
+} | {
+    type: "sub";
+    left: Expr;
+    right: Expr;
+} | {
+    type: "mul";
+    left: Expr;
+    right: Expr;
+} | {
+    type: "div";
+    left: Expr;
+    right: Expr;
+} | {
+    type: "pow";
+    base: Expr;
+    exp: Expr;
+} | {
+    type: "neg";
+    arg: Expr;
+} | {
+    type: "func";
+    name: FuncName;
+    arg: Expr;
+} | {
+    type: "call2";
+    name: BinaryFuncName;
+    left: Expr;
+    right: Expr;
+} | {
+    type: "cmp";
+    op: CmpOp;
+    left: Expr;
+    right: Expr;
+} | {
+    type: "piecewise";
+    branches: {
+        cond: Expr;
+        expr: Expr;
+    }[];
+    otherwise: Expr;
+} | {
+    type: "sum";
+    variable: string;
+    from: Expr;
+    to: Expr;
+    body: Expr;
+} | {
+    type: "product";
+    variable: string;
+    from: Expr;
+    to: Expr;
+    body: Expr;
+};
+/**
+ * Every function name {@link Symbolic.parse} recognizes — canonical spellings
+ * plus alternate ones like `arcsin` — for consumers (e.g. a UI's implicit-
+ * multiplication preprocessor) that need to know what counts as a known
+ * identifier without hand-duplicating this list.
+ */
+export declare const FUNCTION_NAMES: readonly string[];
+export type Assumption = "positive" | "negative" | "nonnegative" | "nonpositive" | "nonzero";
+export declare class NotIntegrableError extends Error {
+    constructor(message?: string);
+}
+export declare class NonLinearSystemError extends Error {
+    constructor(message?: string);
+}
+export declare class SingularSystemError extends Error {
+    constructor(message?: string);
+}
+export declare class SeriesDivergesError extends Error {
+    constructor(message?: string);
+}
+export declare class UndeclaredVariableError extends Error {
+    readonly names: string[];
+    constructor(names: string[]);
+}
+export declare class SystemDidNotConvergeError extends Error {
+    constructor(message?: string);
+}
+export declare class IntegrationSingularityError extends Error {
+    constructor(message?: string);
+}
+/**
+ * No longer thrown internally -- `differentiate` now handles `product` via
+ * the logarithmic-derivative identity (see `diff`/`diffTraced`'s `case
+ * "product":`). Kept exported for backward compatibility with any code
+ * that imports/catches it.
+ */
+export declare class ProductNotDifferentiableError extends Error {
+    constructor(message?: string);
+}
+export declare class NotSeparableError extends Error {
+    constructor(message?: string);
+}
+export declare class NoClosedFormError extends Error {
+    constructor(message?: string);
+}
+export declare class DegenerateOdeError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Thrown by {@link Symbolic.solve} when `expr` is identically zero (e.g.
+ * `solve("0")`) -- every real number is a solution. Distinct from `[]`,
+ * which means "verified no real solution" (e.g. `x^2 + 1`).
+ */
+export declare class InfiniteSolutionsError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Result of {@link Symbolic.solveOdeClosedForm}. When the implicit relation
+ * produced by the chosen method (H(y) = G(x) + C, or the linear-ODE
+ * analog) can be algebraically solved for `y`, `explicit` is `true` and
+ * `y` holds that closed form. Otherwise `explicit` is `false` and
+ * `implicitRelation` holds an "expr implicitly equals zero" expression in
+ * both `x` and `y` (same zero-equals convention {@link Symbolic.solve}/
+ * {@link Symbolic.solveSystem} already use elsewhere in this file) --
+ * still a genuine closed-form solution, just not isolated for `y`.
+ */
+export interface OdeClosedFormResult {
+    explicit: boolean;
+    y?: Expr;
+    implicitRelation?: Expr;
+}
+export declare class Symbolic {
+    /** Parse an expression string such as `"sin(x^2) + 3*x"` into an AST. */
+    static parse(input: string): Expr;
+    static differentiate(expr: Expr | string, variable?: string): Expr;
+    /**
+     * Like {@link differentiate}, but also returns a bottom-up trace of every
+     * differentiation rule applied — one step per subexpression, innermost
+     * first — for a "show your work" UI. Each step's `input`/`output` are
+     * unsimplified, matching the mechanical rule application; `result` is the
+     * final simplified derivative (same as `differentiate` would return).
+     */
+    static differentiateSteps(expr: Expr | string, variable?: string): {
+        steps: DifferentiationStep[];
+        result: Expr;
+    };
+    static simplify(expr: Expr | string): Expr;
+    /**
+     * Simplifies `expr` with additional domain knowledge about specific
+     * variables (e.g. "x is positive"), unlocking simplifications that aren't
+     * sound in general -- `sqrt(x^2) -> x` requires x >= 0 (otherwise the
+     * correct simplification is |x|), and `abs(x) -> x`/`-x` requires knowing
+     * x's sign. Runs ordinary `simplify` first, then a second tree-walk pass
+     * applying the specific patterns each assumption unlocks, then
+     * `simplify`s once more in case a rewrite exposes a further reduction
+     * (e.g. `sqrt(x^2)*2` -> `x*2` -> could combine with a like term
+     * elsewhere).
+     *
+     * NON-GOALS: a small, explicit pattern set (`sqrt(x^2)`, `abs(x)`), not a
+     * general constraint-propagation/theorem-proving simplifier; assumptions
+     * are a flat per-variable fact (`Assumption`), not compound/derived
+     * assumptions (e.g. "x+y is positive" isn't expressible).
+     */
+    static simplifyAssuming(expr: Expr | string, assumptions: Record<string, Assumption>): Expr;
+    /** Symbolic anti-derivative (elementary rules; throws {@link NotIntegrableError} otherwise). */
+    static integrate(expr: Expr | string, variable?: string): Expr;
+    /**
+     * Definite integral of `expr` over `[lower, upper]` with respect to
+     * `variable`. Tries the elementary symbolic antiderivative first
+     * (evaluating `F(upper) - F(lower)`); falls back to adaptive-Simpson
+     * numeric quadrature when {@link integrate} would throw
+     * {@link NotIntegrableError}. `env` binds any other free variables/
+     * constants appearing in `expr` (same convention as {@link evaluate}/
+     * {@link compile}); if `env` also happens to bind `variable`, the
+     * integration bound always wins.
+     *
+     * `lower > upper` needs no special-casing -- both the closed-form
+     * `F(upper) - F(lower)` and {@link Numerical.adaptiveSimpson} are
+     * antisymmetric in their two bounds (verified directly against
+     * `adaptiveSimpson`'s implementation), so reversed bounds just negate
+     * the result, matching the standard ∫[a,b] = -∫[b,a] convention.
+     *
+     * Detects (best-effort) a singularity strictly inside `(lower, upper)` --
+     * e.g. `1/x` from -1 to 1 -- via {@link hasInteriorSingularity} and throws
+     * {@link IntegrationSingularityError} rather than silently returning a
+     * finite-looking but meaningless value, for both the closed-form path (a
+     * naive `F(upper) - F(lower)` is wrong across a pole even when `F` itself
+     * evaluates to finite numbers at both ends) and the numeric fallback.
+     *
+     * NON-GOAL: the detector is a bounded-effort numeric heuristic (see its
+     * own doc comment), not an analytic proof -- a sufficiently narrow
+     * singularity can in principle still slip through uniform sampling.
+     *
+     * @throws {IntegrationSingularityError} if an interior singularity is detected.
+     */
+    static integrateDefinite(expr: Expr | string, lower: number, upper: number, variable?: string, env?: Record<string, number>): number;
+    /**
+     * Attempts a closed-form (symbolic) solution to the first-order initial
+     * value problem `dy/dx = dyDxExpr(x, y)`, `y(x0) = y0`, trying five
+     * elementary methods in order -- all built entirely on {@link integrate}'s
+     * existing elementary-rule coverage, not new integration machinery:
+     *
+     * 1. **Separable**: if `dyDxExpr` factors as `g(x)*h(y)` (including the
+     *    degenerate cases `h(y)=1` or `g(x)=1`), integrates
+     *    `∫(1/h(y))dy = ∫g(x)dx + C`, solves for `C` numerically from
+     *    `(x0,y0)`, and tries to isolate `y`.
+     * 2. **Linear first-order**: if `dyDxExpr` is affine in `y` (i.e.
+     *    `dy/dx + p(x)*y = q(x)` for some `p`,`q` depending only on `x`),
+     *    solves via the integrating factor `μ(x)=exp(∫p(x)dx)`.
+     * 3. **Homogeneous**: if `dyDxExpr` depends only on the ratio `y/x`
+     *    (tested by substituting `y=v·x` and checking whether `x` cancels
+     *    out), the substitution reduces it to a separable equation in `v`
+     *    and `x`, reusing method 1.
+     * 4. **Bernoulli**: if `dyDxExpr` has the shape `q(x)·y^n - p(x)·y`
+     *    (`n != 0, 1`), the substitution `w=y^(1-n)` reduces it to a linear
+     *    equation in `w` and `x`, reusing method 2.
+     * 5. **Exact**: if `dyDxExpr` is a quotient `P/Q`, cross-multiplying
+     *    gives `M dx + N dy = 0` with `M=P`, `N=-Q`; when `∂M/∂y ≡ ∂N/∂x`
+     *    (verified numerically at probe points), a potential function
+     *    `F(x,y)` with `∂F/∂x=M`, `∂F/∂y=N` is constructed by integration,
+     *    giving the (usually implicit) solution `F(x,y) = F(x0,y0)`.
+     *    Deliberately tried LAST: the four methods above produce cleaner,
+     *    usually-explicit results where they apply, and many equations match
+     *    both (any separable quotient is also exact, for example) -- exact
+     *    only picks up quotients none of the others could handle.
+     *
+     * All five paths legitimately fail on realistic inputs whose required
+     * antiderivative isn't in {@link integrate}'s elementary coverage -- that
+     * surfaces as {@link NoClosedFormError}. An equation matching none of the
+     * five structural patterns (e.g. a genuinely nonlinear/non-homogeneous
+     * case like a Riccati equation) surfaces as {@link NotSeparableError}.
+     * Second-order ODEs remain out of scope here (but see
+     * {@link solveOde2ndOrderConstCoeff} for the constant-coefficient
+     * homogeneous case).
+     *
+     * @throws {NotSeparableError} if no method's structural pattern matches.
+     * @throws {NoClosedFormError} if a method matches but its required integral(s) aren't elementary.
+     */
+    static solveOdeClosedForm(dyDxExpr: Expr | string, x0: number, y0: number, xVar?: string, yVar?: string): OdeClosedFormResult;
+    /**
+     * Closed-form solution to the second-order, constant-coefficient,
+     * *homogeneous* linear ODE `a*y'' + b*y' + c*y = 0`, given
+     * `y(x0)=y0`, `y'(x0)=yPrime0` -- a separate method from
+     * {@link solveOdeClosedForm} (not an extension of it): that method
+     * represents a first-order equation as a single `dy/dx=f(x,y)` `Expr`,
+     * but this file has no AST node for a second derivative, so a
+     * second-order equation is instead specified directly by its three
+     * numeric coefficients. Built directly from the characteristic
+     * equation's roots (`a*r^2+b*r+c=0`) via basic algebra -- no calls to
+     * {@link integrate}, unlike every first-order method above.
+     *
+     * Three cases by discriminant `disc = b^2 - 4ac`:
+     * 1. `disc > 0`: two distinct real roots `r1,r2`; general solution
+     *    `y = C1*e^(r1*x) + C2*e^(r2*x)`, `C1`/`C2` from the 2x2 linear
+     *    system the two initial conditions impose.
+     * 2. `disc ≈ 0` (tolerance `1e-9`): repeated root `r=-b/(2a)`; general
+     *    solution `y = (C1+C2*x)*e^(r*x)`.
+     * 3. `disc < 0`: complex conjugate roots `α±iβ`; general solution
+     *    `y = e^(α*x)*(C1*cos(β*x)+C2*sin(β*x))`.
+     *
+     * NON-GOALS: homogeneous only -- no forcing term `f(x)` on the
+     * right-hand side (a nonhomogeneous `a*y''+b*y'+c*y=f(x)` would need
+     * undetermined coefficients or variation of parameters, out of scope
+     * for this pass); no third-order-or-higher or non-constant-coefficient
+     * support.
+     *
+     * @throws {DegenerateOdeError} if `a === 0` (not actually second-order).
+     */
+    static solveOde2ndOrderConstCoeff(a: number, b: number, c: number, x0: number, y0: number, yPrime0: number): Expr;
+    /** Taylor expansion of `expr` about `center` up to `order`, as an expression. */
+    static taylor(expr: Expr | string, variable?: string, center?: number, order?: number): Expr;
+    /** Replace every occurrence of a variable with a sub-expression (e.g. for changing variables or plugging in a solved value). */
+    static substitute(expr: Expr | string, variable: string, replacement: Expr | string): Expr;
+    /** Distribute multiplication over addition/subtraction and expand small integer powers of sums, e.g. `(x+1)^2 -> x^2+2*x+1`. */
+    static expand(expr: Expr | string): Expr;
+    /**
+     * Every distinct variable name referenced anywhere in `expr`, sorted. This
+     * is auto-detection, not validation -- see {@link assertVariables} for a
+     * strict-mode check against a declared list.
+     */
+    static freeVariables(expr: Expr | string): string[];
+    /**
+     * Strict-mode companion to {@link freeVariables}: throws
+     * {@link UndeclaredVariableError} if `expr` references any variable
+     * outside `declared`. Useful to catch typos or ambiguous-parse fallout
+     * before they silently become spurious sliders/parameters or silently
+     * evaluate to `NaN`.
+     */
+    static assertVariables(expr: Expr | string, declared: string[]): void;
+    /**
+     * @param options.declaredVariables When provided, throws
+     * {@link UndeclaredVariableError} if `expr` references any variable
+     * outside this list, instead of the default behavior of silently
+     * resolving an undeclared variable to `NaN` via a missing `env` entry.
+     */
+    static evaluate(expr: Expr | string, env?: Record<string, number>, options?: {
+        declaredVariables?: string[];
+    }): number;
+    /**
+     * Compile `expr` into a closure tree, walking the AST once instead of on
+     * every call. Prefer this over {@link evaluate} when the same expression is
+     * evaluated many times (e.g. sampling a curve across hundreds of x values).
+     *
+     * @param options.declaredVariables Same strict-mode check as
+     * {@link evaluate}, checked once up front rather than per call.
+     */
+    static compile(expr: Expr | string, options?: {
+        declaredVariables?: string[];
+    }): (env: Record<string, number>) => number;
+    /**
+     * Evaluates `expr` exactly over {@link Rational} arithmetic instead of
+     * floats (e.g. `1/3` stays an exact fraction, not `0.333...`). Throws
+     * whenever the expression isn't exactly representable -- any `func`/
+     * `call2` node (sin/cos/sqrt/atan2/etc. are generally irrational) or a
+     * `pow` whose exponent isn't an integer -- so callers should fall back to
+     * a plain float evaluation on catch. `cmp` evaluates to exactly `1`/`0`
+     * via `Rational.compare`; `piecewise` selects the branch exactly (first
+     * `cond` whose Rational is nonzero).
+     */
+    static evaluateExact(expr: Expr | string, env?: Record<string, Rational>): Rational;
+    /**
+     * Evaluates `expr` by folding it through an arbitrary {@link Structure}'s
+     * own algebra instead of native JS math, so e.g. plotting can work over
+     * Z/7Z instead of the reals. Throws on any `func`/`call2` node (no
+     * general meaning over an abstract structure), a `pow` whose exponent
+     * isn't a literal integer constant, or an ordering comparison (`lt`/`le`/
+     * `gt`/`ge` -- several structures, e.g. quaternions, have no order
+     * compatible with their ring operations). `eq`/`ne` and `piecewise` work
+     * over any structure via its own `.equality()`.
+     */
+    static evaluateOverStructure<T>(expr: Expr | string, structure: Structure<T>, env?: Record<string, T>): T;
+    static toString(expr: Expr | string): string;
+    /** Render `expr` as a LaTeX string, e.g. `"x/2"` -> `"\\frac{x}{2}"`. */
+    static toLatex(expr: Expr | string): string;
+    /**
+     * Parse a LaTeX math string into an `Expr` — the reverse of {@link toLatex}.
+     * Round-trips everything `toLatex` produces: `\frac{a}{b}`, `\sqrt{a}` /
+     * `\sqrt[3]{a}` (as `cbrt`) / `\sqrt[n]{a}`, `\left(...\right)`,
+     * `\left|...\right|` (absolute value), `\left\lfloor...\right\rfloor` /
+     * `\left\lceil...\right\rceil`, `\log_{10}`/`\log_{2}`, `\cdot`/`\times`,
+     * `\pi`, `^{...}` exponents, `_{...}` subscripts, the named unary function
+     * commands (`\sin`, `\arcsin`, `\sinh`, `\operatorname{sech}`, ...), and the
+     * two-argument `BinaryFuncName` commands (`\min`, `\max`, `\gcd`,
+     * `\operatorname{atan2}`, `\operatorname{hypot}`, `\operatorname{lcm}`).
+     * Spacing commands (`\,`, `\;`, `\!`, `\quad`) are ignored.
+     *
+     * @throws on LaTeX constructs with no `Expr` equivalent, e.g. `\int` or `\sum`.
+     */
+    static fromLatex(latex: string): Expr;
+    /**
+     * Solve `expr = 0` for `variable`, returning every *real* root @johnhenry/math
+     * can find as an exact `Expr` (rationals and `sqrt`-radicals where
+     * possible) — complex roots are not returned (e.g. `x^2 + 1` yields `[]`).
+     * Supports polynomials up to degree 6: linear and quadratic are solved in
+     * closed form; degree ≥ 3 is solved by repeatedly finding a rational root
+     * (rational root theorem) and deflating via synthetic division, so a cubic
+     * or quartic with only irrational/complex roots left over after rational
+     * deflation cannot be fully solved this way.
+     *
+     * @throws if `expr` isn't a polynomial in `variable` of degree ≤ 6, or if a
+     *   degree ≥ 3 factor has no rational root to deflate on.
+     * @throws {InfiniteSolutionsError} if `expr` is identically zero (e.g.
+     *   `solve("0")`) -- every real number is a solution, a different result
+     *   shape from `[]` (which means "verified no real solution").
+     */
+    static solve(expr: Expr | string, variable?: string): Expr[];
+    /**
+     * Solve a system of linear equations, each written in the same "expr
+     * implicitly equals zero" convention as {@link solve} (no `=` operator
+     * needed -- e.g. `"2*x + y - 5"` means `2x+y=5`). Requires exactly one
+     * equation per variable (a square system) with a unique solution.
+     *
+     * NON-GOAL (v1): nonlinear systems are not supported -- throws
+     * {@link NonLinearSystemError}. A future multivariable-Newton extension
+     * (seeded from an initial guess, iterating via the Jacobian) would slot in
+     * here as a fallback when linearity detection fails, but is out of scope now.
+     *
+     * @throws {NonLinearSystemError} if any equation isn't linear in `variables`.
+     * @throws {SingularSystemError} if the coefficient matrix is singular/rank-deficient.
+     */
+    static solveSystem(equations: (Expr | string)[], variables: string[]): Record<string, number>;
+    /**
+     * Numerically solves a square system of (possibly nonlinear) equations
+     * via multivariable Newton's method with a finite-difference Jacobian,
+     * starting from `initialGuess` (default: all 1s). Unlike `solveSystem`,
+     * this never throws `NonLinearSystemError` -- a genuinely linear system
+     * just converges in one Newton step, since Newton's method reduces to a
+     * single linear solve whenever the Jacobian is already constant. Added as
+     * a separate opt-in method (not `solveSystem`'s new default behavior) so
+     * `solveSystem`'s existing "throw on nonlinear" contract, and the tests
+     * that rely on it, stay unchanged -- callers who want a nonlinear-capable
+     * solve opt in explicitly.
+     *
+     * Each Newton step is damped by a backtracking line search: the full step
+     * is tried first, halved up to 20 times until it actually reduces the
+     * residual norm (or leaves the function's domain), rather than being
+     * taken unconditionally -- this is what keeps a merely-nearby (not
+     * exact) initial guess from overshooting past a real root, the concrete
+     * failure mode plain undamped Newton has no defense against.
+     *
+     * NON-GOALS: still no trust-region step (backtracking damps the step
+     * length but never changes its *direction* the way a trust region
+     * would), so a genuinely bad initial guess -- one on the wrong side of a
+     * local max/min of the residual, not just far from the root -- can still
+     * fail to converge; only ever finds one root near the initial guess, not
+     * every root of a system with multiple solutions.
+     *
+     * @throws {SystemDidNotConvergeError} if the residual doesn't shrink
+     *   below tolerance within the iteration budget, if evaluation produces a
+     *   non-finite value (e.g. leaving the function's domain) at some step,
+     *   or if no damped step size improves the residual at some iterate.
+     */
+    static solveSystemNumeric(equations: (Expr | string)[], variables: string[], initialGuess?: number[]): Record<string, number>;
+    /**
+     * Numerically spot-checks that `candidate` is (approximately) a root of
+     * `equation` (the same "implicitly equals zero" convention `solve` uses):
+     * substitutes `candidate` for `variable` and checks the result is near
+     * zero. A lightweight reviewer/verification pass over a CAS result, not a
+     * proof of exactness -- catches an outright wrong candidate (e.g. from a
+     * heuristic search or a downstream bug) before it's presented, using the
+     * same probe-and-compare technique this codebase's own test suite already
+     * relies on for anything heuristic.
+     */
+    static verifySolution(equation: Expr | string, variable: string, candidate: number, env?: Record<string, number>, tolerance?: number): boolean;
+    /**
+     * The `solveSystem`/`solveSystemNumeric` analog of {@link verifySolution}:
+     * substitutes `solution` into every equation and requires all of them to
+     * land near zero.
+     */
+    static verifySystemSolution(equations: (Expr | string)[], solution: Record<string, number>, tolerance?: number): boolean;
+    /**
+     * Sum `expr` over integer values of `variable` from `from` to `to`
+     * (inclusive); `to` may be `Infinity` for an infinite series. A finite
+     * range is a plain partial sum. An infinite range first tries to recognize
+     * `expr` as a geometric series (`c·r^(a·variable+b)`, closed form
+     * `c·r^(a·from+b)/(1-r^a)`), falling back to numeric partial summation with
+     * a convergence/divergence check otherwise.
+     *
+     * `variable` defaults to `"n"` (not `"x"`), matching conventional
+     * summation-index notation.
+     *
+     * NON-GOALS: no general convergence-radius/ratio-test analysis beyond a
+     * simple term-growth divergence heuristic; no summation acceleration
+     * (Euler transform etc.) for slowly-converging or conditionally-convergent
+     * alternating series; closed-form recognition covers geometric series
+     * only, not arbitrary known series (no telescoping, no p-series/zeta
+     * recognition).
+     *
+     * If the term-magnitude stopping rule alone can't confirm convergence
+     * within the term budget (e.g. `Σ 1/n^2`, a slowly-decaying polynomial
+     * tail the per-term check isn't a valid proxy for), a second pass tries
+     * an integral-test tail bound instead of immediately declaring divergence:
+     * see {@link estimateConvergentTail}'s own doc comment for how. This
+     * recovers the correct value for a genuinely convergent slow-decay
+     * series without weakening the divergence check for a genuinely
+     * divergent one (e.g. `Σ 1/n`) -- the tail estimator itself confirms
+     * whether the integral is actually shrinking before trusting it.
+     *
+     * @throws {SeriesDivergesError} if the numeric fallback (including the
+     *   integral-test tail estimate) still can't confirm convergence within
+     *   its budget, or detects the terms growing.
+     */
+    static sumSeries(expr: Expr | string, from: number, to: number, variable?: string, env?: Record<string, number>): number;
+    /**
+     * Factor a polynomial in `variable`: extracts a common numeric GCD and
+     * common power of `variable`, then repeatedly pulls out rational linear
+     * factors `(variable - r)` via the rational root theorem, falling back to
+     * the quadratic formula for a final degree-2 remainder. Any remaining
+     * factor @johnhenry/math can't reduce further (e.g. an irreducible cubic) is
+     * left as-is. Returns `expr` unchanged (simplified) if it isn't a
+     * polynomial in `variable`.
+     */
+    static factor(expr: Expr | string, variable?: string): Expr;
+    /**
+     * Numeric limit of `expr` as `variable` approaches `point`. Falls back to
+     * L'Hopital's rule (repeated symbolic differentiation of numerator and
+     * denominator) whenever direct evaluation of a `div` node hits a `0/0` or
+     * `∞/∞` indeterminate form.
+     */
+    static limit(expr: Expr | string, variable?: string, point?: number, direction?: "left" | "right" | "both"): number;
+}
+/** One rule application recorded by {@link Symbolic.differentiateSteps}. */
+export interface DifferentiationStep {
+    /** Human-readable name of the differentiation rule applied, e.g. "Product Rule". */
+    rule: string;
+    /** The subexpression this rule was applied to. */
+    input: Expr;
+    /** The (unsimplified) derivative of `input` produced by this rule. */
+    output: Expr;
+}
+//# sourceMappingURL=Symbolic.d.ts.map

package/dist/Symbolic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Symbolic.d.ts","sourceRoot":"","sources":["../src/Symbolic.ts"],"names":[],"mappings":"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"}