Skip to content
Symi Docs
WASM / JavaScript

Signatures in the WASM / JavaScript view are TypeScript. Where the JavaScript facade wraps an operation its form is listed first; the other calling forms are the raw wasm-bindgen exports.

On this page

Numeric evaluation

Symi computes with exact numbers. A decimal approximation is produced only when one of the operations on this page is called by name, and the result is a separate NumericValue object, never a number inside an expression. No symbolic operation calls these operations, returns their results, or falls back to them when it declines: solve, integrate, simplify, and execute return exact results or decline.

Operation What it approximates Result
evaluate_numeric A closed expression, or one whose symbols are bound to values NumericValue
integrate_definite_numeric A definite integral over a real or complex path NumericValue
summation_numeric A finite or infinite sum NumericValue
find_root_numeric One root of an equation or a square system, near a start point NumericRootFindingResult
find_root_numeric_in_bracket One real root inside a bracket where the sign changes NumericRootFindingResult
polynomial_roots_numeric Every complex root of a polynomial, with multiplicities NumericPolynomialRootsResult
isolate_real_roots_numeric Every real root in an interval, as exact rational enclosures NumericRootIsolationResult
evaluate_to_float A real value, as the nearest host float host float
compile_numeric_function Expressions evaluated repeatedly in binary64 machine arithmetic host floats with a status per output, never a NumericValue

matrix.evaluate_numeric evaluates every entry of a matrix, and evaluate_numeric_bulk evaluates a list of expressions in order, returning a value or a decline for each item (see bulk operations).

Accuracy and precision#

Every numeric request takes the same four options. Python takes them as keyword arguments, JavaScript positionally, and Rust, Kotlin, and Swift as a NumericOptions record.

Option Meaning Default
significant_digits The number of significant decimal digits wanted in each component 15
accuracy certified, or estimated_allowed to accept estimates certified
maximum_precision_bits The greatest working precision, in bits; 0 keeps the default The requested precision plus 4096 bits
work_budget A cap on the work of one request, whose unit each operation states; 0 keeps the default Stated by each operation

Certified values. Under the default certified policy every printed digit is faithful: the printed decimal differs from the true value by less than one unit in its last place. When the enclosure also determines the correctly rounded string, that string is printed; a value exactly halfway between two decimals, such as 0.50.5 printed to no decimal places, can be certified only when it is known exactly. The requested digits are converted to a relative accuracy of ⌈dlog⁡210⌉+1\lceil d \log_2 10\rceil + 1 bits for dd digits, and the working precision is raised until every component meets it, by at least the precision the previous attempt lost to cancellation. A request that reaches maximum_precision_bits first declines with precision_exhausted, and the detailed report carries the best enclosure reached.

Zero and exactly real values. A component that cannot be separated from zero at the precision cap is decided exactly: a proof that it is zero returns an exact zero, as for (2+3)2−5−26(\sqrt{2}+\sqrt{3})^2 - 5 - 2\sqrt{6}, and otherwise the request declines with magnitude_below_resolution and a bound on its size. A value is exactly real only when that is proved, for example because every input is real and every function on the path is real there; a value whose imaginary enclosure merely contains zero is not exactly real. sqrt(-4) evaluates to 2*i with an exactly zero real part.

Branch cuts, jumps, and poles. Every function has the principal branch stated in its own entry, the same as in exact computation. An argument that lies on a branch cut, at a jump of a piecewise function, or at a pole is placed by an exact decision (an exact comparison, a zero proof, or a declared assumption); if none decides it, the request declines with branch_side_undecided, discontinuity_undecided, or singularity_undecided. The side of a cut is never chosen by a nearby sample. log(-2) evaluates to 0.693147180559945 + 3.14159265358979*i.

Estimated values. Under accuracy = "estimated_allowed", an expression whose certified evaluation declines only because some function has no certified method for its arguments is evaluated by a multiprecision engine instead. Such an estimate is accepted only when two runs at working precisions at least 32 bits apart agree to the requested digits, and only through kernels that can genuinely work at those precisions; estimated integrals and sums have the acceptance rules stated with their operations. The radius of an estimate is an error estimate, not a bound, and every estimated value is labelled estimated wherever it is printed or inspected. An estimated value bound to a symbol in a certified request declines with estimated_substitution.

Exact inputs. Expressions hold exact numbers only; a host float is not accepted as an expression. Where a float is accepted — a value bound to a symbol, or a start point or bracket end of root finding — it means the exact binary fraction it denotes, so a bound 0.1 evaluates to 0.1000000000000000055511151 at 25 digits. Bind rational(1, 10) for one tenth, and use rational_from_float to choose a nearby rational deliberately. A numeric value re-enters exact computation only through an explicit conversion: to_rational gives the exact midpoint of its enclosure and to_simplest_rational the simplest rational inside it.

Deferred forms. A definite integral or summation anywhere inside an evaluated expression is evaluated numerically, as integrate_definite_numeric and summation_numeric describe; a sum of at most 64 terms with integer bounds is first written out term by term, so exact zero decisions reach it. Limits, products, unevaluated derivatives, and integral transforms decline with unsupported_deferred_form.

Certified functions#

The table lists every function and constant with the arguments on which it is certified, the method, and the working precision the estimated engine can reach when estimates are allowed and no certified method covers the arguments. It is generated from the registry the evaluator consults, so it states exactly what evaluation does. A function certified only for real or exact integer arguments, or on part of the plane, is treated outside that set like a function with no certified method: a certified request declines with no_certified_kernel, and an estimate is attempted only under estimated_allowed, which may itself decline with estimate_unavailable.

Constants Certified Method Estimated evaluation
pi Yes Chudnovsky series by binary splitting Any working precision
e Yes factorial series by binary splitting Any working precision
euler_gamma Yes exponential-integral identity at an integer point, summed exactly by binary splitting Any working precision
imaginary_unit Yes exact Any working precision
Functions Certified Method Estimated evaluation
sin, cos Real and complex arguments reduction modulo pi/2, Taylor series with halving Any working precision
tan, sec, csc, cot Real and complex arguments quotients of sin and cos; poles decline Any working precision
arcsin, arccos Real and complex arguments arctangent forms on [-1, 1]; Kahan logarithmic forms elsewhere Any working precision
arctan Real and complex arguments argument halving and Taylor series; logarithmic form off the real line Any working precision
arcsec, arccsc, arccot Real and complex arguments composition with the reciprocal Any working precision
sinh, cosh, tanh Real and complex arguments exp(x) - 1 without cancellation near zero Any working precision
sech, csch, coth Real and complex arguments reciprocals of the hyperbolic functions; poles decline Any working precision
arcsinh, arccosh, arctanh Real and complex arguments log(1 + u) forms; Kahan logarithmic forms off the real domain Any working precision
arcsech, arccsch, arccoth Real and complex arguments composition with the reciprocal Any working precision
exp Real and complex arguments reduction modulo log 2, Taylor series with squaring Any working precision
log Real and complex arguments atanh series after square-root reduction; principal branch Any working precision
sqrt Real and complex arguments integer square root; principal branch Any working precision
abs, signum Real and complex arguments modulus and phase; the jump of signum at zero declines Any working precision
gamma Real and complex arguments Stirling series with the DLMF 5.11.ii bound, recurrence, reflection Any working precision
log_gamma Part of the plane, as stated principal branch on Re z > 0 by the Stirling series Any working precision
digamma Real and complex arguments asymptotic series with the DLMF 5.11.ii bound, recurrence, reflection Any working precision
polygamma Real and complex arguments Hurwitz zeta of integer order at the argument Any working precision
beta Real and complex arguments ratio of gamma values; every pole declines Any working precision
zeta Real and complex arguments Euler-Maclaurin with an explicit remainder; functional equation left of 1/2 Any working precision
hurwitz_zeta Part of the plane, as stated Euler-Maclaurin with an explicit remainder; Re a > 0 unless the order is an integer Any working precision
error_function, error_function_complementary, imaginary_error_function Real and complex arguments Taylor series with cancellation bits; the DLMF 7.12 asymptotic series for large arguments Any working precision
fresnel_sine_integral, fresnel_cosine_integral Real and complex arguments Taylor series with cancellation bits; erfc asymptotics for large real arguments Any working precision
exponential_integral, logarithmic_integral Real arguments Ein series and the E1 asymptotic series with |R_n| <= n!/|x|^n Any working precision
sine_integral, cosine_integral Real and complex arguments power series; E1(ix) asymptotics for large real arguments Any working precision
lambert_w Real and complex arguments Krawczyk test around a multiprecision seed, branch certified by the labelling identity Any working precision
jacobi_polynomial Real and complex arguments explicit sum; exact nonnegative degree Any working precision
gegenbauer_polynomial, chebyshev_polynomial_first_kind, chebyshev_polynomial_second_kind, legendre_polynomial, generalized_laguerre_polynomial, hermite_polynomial Real and complex arguments three-term recurrence; exact nonnegative degree Any working precision
binomial, falling_factorial, rising_factorial, catalan_number Real and complex arguments exact at integer arguments; finite products or gamma ratios otherwise Any working precision
stirling_first, stirling_second, bell_number, fibonacci_number, partition_count Exact integer arguments exact integer recurrences Any working precision
dirac_delta, derivative_of_dirac_delta, heaviside_step Real arguments decided by the sign of the argument; the origin is singular or on the jump Any working precision
floor, ceiling Real arguments certified when the ball lies between two integers Any working precision
conjugate, real_part, imaginary_part Real and complex arguments componentwise Any working precision
min, max Real arguments monotone in every argument; no decision needed Any working precision
polylogarithm, lerch_phi, carlson_rf, carlson_rc, carlson_rd, carlson_rj, elliptic_k, elliptic_e, elliptic_pi, elliptic_f, elliptic_e_incomplete, elliptic_pi_incomplete, jacobi_amplitude, jacobi_theta_1, jacobi_theta_2, jacobi_theta_3, jacobi_theta_4, hypergeometric_pfq, meijer_g, bessel_j, bessel_y, bessel_i, bessel_k, hankel_first_kind, hankel_second_kind, spherical_bessel_j, spherical_bessel_y, spherical_hankel_first_kind, spherical_hankel_second_kind, airy_ai, airy_bi, airy_ai_prime, airy_bi_prime None — Any working precision
jacobi_sn, jacobi_cn, jacobi_dn None — Up to 512 working bits

The relations and connectives equation, equal, not_equal, less_than, less_than_or_equal, greater_than, greater_than_or_equal, logical_and, logical_or, logical_not, implies, equivalent, exclusive_or have no numeric value and decline with not_a_number, as do the infinities, undefined, sets, and the logical constants.

Decline reasons#

A numeric evaluation that produces no value declines with one of these reasons. Python raises an exception whose reason attribute holds the reason, JavaScript throws an error naming it, and evaluate_numeric_detailed returns it in its report instead. Root finding, polynomial roots, and root isolation return their own reasons in their results; they are listed with each operation below.

Reason Meaning
unbound_symbol A free symbol has no bound value; there is no partial evaluation of an expression with free symbols
substitution_violates_assumption A bound value provably violates an assumption declared on its symbol
substitution_assumption_undecided Whether a bound value satisfies the assumptions declared on its symbol is undecided
estimated_substitution An estimated value was bound to a symbol of a certified request
singularity The expression is evaluated exactly at a pole, a branch point, or a logarithmic singularity
outside_domain An argument lies outside the set on which its function is defined, such as a non-integer summation bound
singularity_undecided An argument stays on a pole or branch point at every precision and no exact decision placed it
branch_side_undecided An argument stays on a branch cut at every precision and its side was not decided exactly
discontinuity_undecided An argument stays on a jump or an undecidable condition at every precision
no_certified_kernel A function has no certified method for its arguments; the message names it and the policy that would accept an estimate
estimate_unavailable Estimates were allowed, but no estimate was accepted
precision_exhausted The precision cap or the work budget was reached before the digits were certified
magnitude_below_resolution A component could not be separated from zero and was not proved to be zero
not_a_number The expression is not a number: a relation, a set, an infinity, or undefined
unsupported_deferred_form The expression contains a deferred form other than a definite integral or sum
integral_not_certified A definite integral could not be certified; estimates must be allowed explicitly
summation_not_certified A sum could not be certified; estimates must be allowed explicitly
series_divergent A sum is proved divergent
resource_limit A number left the range the arithmetic can represent, as e−1020e^{-10^{20}} does
not_exactly_real A real result, such as a host float, was asked of a value not known to be exactly real

Evaluating expressions#

evaluate_numeric#

Raw WebAssembly: Default context

evaluateNumeric(
    input_expression: Expression,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericValue
Calling forms

Raw WebAssembly: Explicit context: Context.evaluateNumeric

evaluateNumeric(
    input_expression: Expression,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericValue

Raw WebAssembly: Expression method: Expression.evaluateNumeric

evaluateNumeric(
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericValue

The numeric value of an expression to significant_digits significant digits. accuracy is "certified" or "estimated_allowed"; work_budget caps the evaluations per round of precision refinement (0 keeps the default). In Python, substitutions maps symbols (or their names) to exact values, floats, or numeric values; a float is bound as the exact binary fraction it denotes. A free symbol left without a value declines with unbound_symbol: there is no partial evaluation of an expression with free symbols. The JavaScript and mobile forms take the options positionally or as a NumericOptions record and bind symbols through evaluate_numeric_with_substitutions.

evaluate_numeric_with_substitutions#

Raw WebAssembly: Default context

evaluateNumericWithSubstitutions(
    input_expression: Expression,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
    symbols: Expression[],
    values: Expression[],
    numeric_symbols: Expression[],
    numeric_values: NumericValue[],
): NumericValue
Calling forms

Raw WebAssembly: Explicit context: Context.evaluateNumericWithSubstitutions

evaluateNumericWithSubstitutions(
    input_expression: Expression,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
    symbols: Expression[],
    values: Expression[],
    numeric_symbols: Expression[],
    numeric_values: NumericValue[],
): NumericValue

The numeric value of an expression with its symbols bound to values. Python takes a dictionary from symbols (or their names) to exact values, floats, or numeric values. JavaScript takes the options positionally followed by parallel arrays: symbols[k] bound to the exact value values[k] and numericSymbols[k] bound to the numeric value numericValues[k]. A numeric value's enclosure propagates through the evaluation. Every bound value must provably satisfy the assumptions declared on its symbol: a proved violation declines with substitution_violates_assumption and an undecided one with substitution_assumption_undecided. A declaration is never evidence for the value bound to its own symbol, and an estimate proves nothing, so an estimated value bound to a symbol with declared assumptions declines as undecided unless the facts hold for every value. An estimated value bound in a certified request declines with estimated_substitution.

evaluate_numeric_detailed#

Raw WebAssembly: Default context

evaluateNumericDetailed(
    input_expression: Expression,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
    symbols: Expression[],
    values: Expression[],
    numeric_symbols: Expression[],
    numeric_values: NumericValue[],
): NumericEvaluationReport
Calling forms

Raw WebAssembly: Explicit context: Context.evaluateNumericDetailed

evaluateNumericDetailed(
    input_expression: Expression,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
    symbols: Expression[],
    values: Expression[],
    numeric_symbols: Expression[],
    numeric_values: NumericValue[],
): NumericEvaluationReport

The same evaluation, reported rather than raised: the report holds the value or the decline reason, the best certified enclosure reached before a decline, the working precision used, and the functions evaluated.

matrix_evaluate_numeric#

Raw WebAssembly: Matrix method

evaluateNumeric(
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericMatrix

The numeric value of every entry of a matrix, evaluated as by evaluate_numeric. The first entry that declines makes the whole evaluation decline.

NumericValue#

A complex number approximated by a ball (a midpoint and a radius) in each component, with an accuracy of certified (each radius is a proved error bound) or estimated (each radius is an error estimate). A component is exact when that is known, never because its ball happens to be small; sqrt(-4) evaluates to 2*i with an exactly zero real part. Its members are accuracy, requested_significant_digits, achieved_relative_precision_bits, is_exactly_real, is_exactly_zero, contains_zero, certified_sign (the proved sign as -1, 0, or 1), real_part, imaginary_part, error_bound (certified values only), error_estimate (estimated values only), to_decimal_string, to_latex, to_f64 (exactly real values only), to_complex_f64, to_rational (the exact midpoint: the value of the approximation, not of the quantity), to_simplest_rational (the simplest rational inside each ball), and summary. Python supports str, repr, float, and complex; JavaScript supports toString and toNumber.

A decimal rendering prints at most the requested digits per component and fewer only when the ball cannot support them; a ball that supports no digit prints as the interval [lower, upper] of directed bounds. Complex values print as a + b*i.

Raw WebAssembly: NumericValue property

readonly accuracy: string

Whether the radii are proved bounds ("certified") or estimates ("estimated").

Raw WebAssembly: NumericValue property

readonly achievedRelativePrecisionBits: number | undefined

The relative accuracy in bits, or undefined when both components are exact.

Raw WebAssembly: NumericValue method

certifiedSign(): number | undefined

The proved sign of a real value as -1, 0, or 1, or undefined when it is not proved.

Raw WebAssembly: NumericValue method

containsZero(): boolean

Whether zero lies within the stated radius of both components.

Raw WebAssembly: NumericValue method

errorBound(): NumericValue | undefined

A proved bound on the error of a certified value, or undefined for an estimate.

Raw WebAssembly: NumericValue method

errorEstimate(): NumericValue | undefined

The estimated error of an estimate, or undefined for a certified value.

Raw WebAssembly: NumericValue method

imaginaryPart(): NumericValue

The imaginary part, as a real numeric value with the same accuracy.

Raw WebAssembly: NumericValue method

isExactlyReal(): boolean

Whether the value is known to be real: its imaginary part is exactly zero.

Raw WebAssembly: NumericValue method

isExactlyZero(): boolean

Whether the value is known to be exactly zero.

Raw WebAssembly: NumericValue method

realPart(): NumericValue

The real part, as a real numeric value with the same accuracy.

Raw WebAssembly: NumericValue property

readonly requestedSignificantDigits: number

The number of significant digits the value was requested with.

Raw WebAssembly: NumericValue method

summary(): string

The value at its requested digits followed by its accuracy.

Raw WebAssembly: NumericValue method

toComplexF64(): Float64Array

The nearest doubles to the real and imaginary midpoints, as [real, imaginary].

Raw WebAssembly: NumericValue method

toDecimalString(significant_digits: number): string

The value in decimal with at most significantDigits faithful digits per component.

Raw WebAssembly: NumericValue method

toF64(): number

The nearest double to the midpoint of a value known to be exactly real.

Raw WebAssembly: NumericValue method

toLatex(significant_digits: number): string

The value in LaTeX with at most significantDigits faithful digits per component.

Raw WebAssembly: NumericValue method

toNumber(): number

The nearest double of a value known to be exactly real.

Raw WebAssembly: NumericValue method

toRational(): Expression

The exact midpoint as an expression: the value of the approximation, not of the quantity.

Raw WebAssembly: NumericValue method

toSimplestRational(): Expression

The simplest rational inside each component's ball, as an expression.

Raw WebAssembly: NumericValue method

toString(): string

The value at its requested digits.

NumericEvaluationReport#

What evaluate_numeric_detailed returns. status is evaluated or declined; value is present exactly when a value was produced and decline_reason exactly when none was. unbound_symbols, substitution_symbol, and responsible_heads name what caused an unbound_symbol, substitution, or no_certified_kernel decline. best_enclosure is the last certified enclosure reached before a decline, and absolute_bound bounds the modulus of a value below resolution. working_precision_bits, certified_attempts, and exact_decisions describe the work done; heads lists the functions and constants evaluated and estimated_heads those evaluated by the estimated engine. summary is a one-line description.

Raw WebAssembly: NumericEvaluationReport property

readonly absoluteBound: NumericValue | undefined

A proved bound on the modulus, for a magnitude_below_resolution decline.

Raw WebAssembly: NumericEvaluationReport property

readonly bestEnclosure: NumericValue | undefined

The last certified enclosure reached before a decline.

Raw WebAssembly: NumericEvaluationReport property

readonly certifiedAttempts: number

The number of certified ball evaluations performed.

Raw WebAssembly: NumericEvaluationReport property

readonly declineReason: string | undefined

Why no value was produced, when none was.

Raw WebAssembly: NumericEvaluationReport property

readonly estimatedHeads: string[]

The heads the estimated engine evaluated; empty unless the value is an estimate.

Raw WebAssembly: NumericEvaluationReport property

readonly exactDecisions: number

The number of undecided balls settled by an exact decision.

Raw WebAssembly: NumericEvaluationReport property

readonly heads: string[]

The builtin heads and constants of the evaluated expression.

Raw WebAssembly: NumericEvaluationReport property

readonly responsibleHeads: string[]

The heads without a certified kernel, for a no_certified_kernel decline.

Raw WebAssembly: NumericEvaluationReport property

readonly status: string

"evaluated" when a value was produced, "declined" otherwise.

Raw WebAssembly: NumericEvaluationReport property

readonly substitutionSymbol: string | undefined

The symbol whose bound value was rejected, for a substitution decline.

Raw WebAssembly: NumericEvaluationReport method

summary(): string

A one-line description of the outcome.

Raw WebAssembly: NumericEvaluationReport property

readonly unboundSymbols: string[]

The free symbols left without a value, for an unbound_symbol decline.

Raw WebAssembly: NumericEvaluationReport property

readonly value: NumericValue | undefined

The value, when one was produced.

Raw WebAssembly: NumericEvaluationReport property

readonly workingPrecisionBits: number

The last working precision used, in bits.

NumericMatrix#

What matrix.evaluate_numeric returns: rows, columns, entry(row, column), and entries in row-major order, each entry a NumericValue.

Raw WebAssembly: NumericMatrix property

readonly columns: number

The number of columns.

Raw WebAssembly: NumericMatrix method

entries(): NumericValue[]

Every entry in row-major order.

Raw WebAssembly: NumericMatrix method

entry(row: number, column: number): NumericValue

The numeric value of one entry.

Raw WebAssembly: NumericMatrix property

readonly rows: number

The number of rows.

NumericOptions#

Not exposed by the WASM / JavaScript bindings. Available as api::NumericOptions in Rust.

The options every explicit numeric operation takes on Rust and mobile hosts: significant_digits, accuracy (certified or estimated_allowed), maximum_precision_bits, and work_budget, with 0 keeping the default for the last two.

evaluate_to_float#

Raw WebAssembly: Expression method

evaluateToFloat(): number

The nearest double to the certified real value. It raises unless the value is certified and known to be exactly real: a free symbol, a complex value, a pole, or a function without a certified kernel all raise. For a value with a stated accuracy, more digits, a complex value, or an estimate, use evaluate_numeric.

Lambert W branches#

lambert_w(z) is the principal branch W_0(z), and lambert_w(k, z) with an exact integer k is the branch W_k(z); lambert_w(0, z) canonicalises to the unary form. Every integer branch evaluates over the whole complex plane at arbitrary precision, so evaluate_numeric(lambert_w(-1)) gives W_0(-1) = -0.3181… + 1.3372…i rather than declining.

The two branches that take real values do so on exactly these intervals: W0W_0 on [−1/e,∞)[-1/e, \infty) with W0≥−1W_0 \ge -1, and W−1W_{-1} on [−1/e,0)[-1/e, 0) with W−1≤−1W_{-1} \le -1. An exactly real argument on one of those branches is evaluated in real arithmetic throughout, so evaluate_to_float succeeds and the imaginary part is exactly zero — lambert_w(-1, -0.1) gives -3.5771…. Every other branch or argument routes through the complex kernel, so lambert_w(-1, 1) has a complex value but no real one.

Wk(0)W_k(0) for k≠0k \ne 0 is a logarithmic singularity and declines; so does a non-integer or symbolic branch index, which is never silently read as the principal branch. W_0(0) = 0, W_0(e) = 1, and W_0(-1/e) = W_-1(-1/e) = -1 fold exactly at construction. The branch structure, cuts, and the safe defining identity W_k(z)*exp(W_k(z)) = z are preserved by the branch-aware result.

Numerical integration and summation#

integrate_definite_numeric#

Raw WebAssembly: Default context

integrateDefiniteNumeric(
    input_expression: Expression,
    variable: string,
    lower: Expression,
    upper: Expression,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericValue
Calling forms

Raw WebAssembly: Explicit context: Context.integrateDefiniteNumeric

integrateDefiniteNumeric(
    input_expression: Expression,
    variable: string,
    lower: Expression,
    upper: Expression,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericValue

The numerical value of a definite integral, to significant_digits significant digits. This is the explicit numerical counterpart of integrate_definite: it never integrates symbolically, and it gives the same value as evaluate_numeric of the deferred integral. The options and the decline reasons are those of numeric evaluation; the JavaScript and mobile forms take the options positionally or as a NumericOptions record.

On a finite path, real or complex (the straight segment from lower to upper), the value is certified. The path is split adaptively; each piece is integrated by a Gauss–Legendre rule whose error is bounded through the size of the integrand on an ellipse around the piece, which is used only where the integrand is proved holomorphic there. A piece ending at a singular point, such as xlog⁡x\sqrt{x}\log x or 1/x1/\sqrt{x} at 00, is bounded by a proved power bound of the integrand near the point, and a jump or a kink is enclosed by bounding the integrand on shrinking pieces around it. work_budget caps the number of pieces (0 keeps the default of 4000). A path that cannot be certified declines with integral_not_certified, and a head without a certified kernel with no_certified_kernel.

Under accuracy="estimated_allowed", a finite path that cannot be certified is estimated by tanh-sinh quadrature, and an infinite range (lower or upper an infinity) by exp-sinh or sinh-sinh quadrature, or, when the integrand oscillates with one linear phase sin⁡(ωx+φ)\sin(\omega x + \varphi) or cos⁡(ωx+φ)\cos(\omega x + \varphi), by integrating it over half periods and extrapolating the sum with Wynn's epsilon algorithm. These values are labelled estimated, and their radius is an estimate of the error from the agreement of successive rules or extrapolations. A certified request over an infinite range declines with integral_not_certified, and an estimate that does not settle, for example for a divergent integral, declines with estimate_unavailable.

summation_numeric#

Raw WebAssembly: Default context

summationNumeric(
    summand: Expression,
    index: string,
    lower: Expression,
    upper: Expression,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericValue
Calling forms

Raw WebAssembly: Explicit context: Context.summationNumeric

summationNumeric(
    summand: Expression,
    index: string,
    lower: Expression,
    upper: Expression,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericValue

The numerical value of a definite sum, to significant_digits significant digits. This is the explicit numerical counterpart of the deferred summation: it never sums symbolically, and it gives the same value as evaluate_numeric of the deferred sum. The bounds must be integers or infinities; a reversed range is empty and sums to zero, and a range from negative infinity adds the reflected series. The options and the decline reasons are those of numeric evaluation; the JavaScript and mobile forms take the options positionally or as a NumericOptions record.

A finite range is added up term by term and is certified. An infinite range is certified in two ways. When the summand is a hypergeometric term — a rational function of the index times factorials, binomials, Gamma values, and powers c^k — the ratio t(k+1)/t(k)t(k+1)/t(k) is a rational function R(k)R(k); if its limit has modulus below one, terms are added until a bound ∣R(k)∣≤q<1|R(k)| \le q < 1 is proved on the whole remaining tail, which then contributes at most ∣t(N)∣ q/(1−q)|t(N)|\,q/(1-q). When the summand is (−1)kh(k)(-1)^k h(k) times a constant and hh is proved completely monotone and tending to zero (for example 1/k1/k, 1/(2k+1)21/(2k+1)^2, 1/k1/\sqrt{k}, 1/(klog⁡k)1/(k \log k)), the tail is accelerated by the Cohen–Villegas–Zagier weights, whose error after nn terms is at most h(N)/Tn(3)h(N)/T_n(3). A sum of such parts is certified part by part. So ∑1/k!\sum 1/k! and ∑(−1)k+1/k\sum (-1)^{k+1}/k are certified, while ∑1/k3\sum 1/k^3 is not. A finite range with more terms than work_budget (0 keeps the default of 100000) uses the same tail bounds.

A series is declined with series_divergent, under every accuracy policy, when its divergence is proved: the ratio shows the terms do not tend to zero, as for ∑2k\sum 2^k or ∑(−1)k\sum (-1)^k, or Gauss's test applies, as for ∑1/k\sum 1/k. Any other series that cannot be certified declines with summation_not_certified. Under accuracy="estimated_allowed" it is estimated instead: an alternating series by the Cohen–Villegas–Zagier weights, and any other by Richardson extrapolation of its partial sums and then Wynn's epsilon algorithm. An estimate is accepted only when the terms visibly tend to zero and successive extrapolations agree; its radius is an estimate of the error, and it is labelled estimated. A sum whose terms are all exactly real is exactly real even when estimated. An estimate that does not settle, as for the very slowly convergent ∑1/(klog⁡2k)\sum 1/(k \log^2 k), declines with estimate_unavailable.

Certified numerical root isolation#

Numerical root finding is an operation the caller asks for by name. Nothing in symbolic solving reaches it, and it never publishes an approximation as an exact root: what it returns are exact rational bounds, each carrying a proof that a root lies between them, together with the regions it could not settle.

isolate_real_roots_numeric#

Raw WebAssembly: Default context

isolateRealRootsNumeric(
    input_expression: Expression,
    variable: string,
    lower: Expression,
    upper: Expression,
    precision_bits: number,
    work_budget: number,
): NumericRootIsolationResult
Calling forms

Raw WebAssembly: Explicit context: Context.isolateRealRootsNumeric

isolateRealRootsNumeric(
    input_expression: Expression,
    variable: string,
    lower: Expression,
    upper: Expression,
    precision_bits: number,
    work_budget: number,
): NumericRootIsolationResult

Isolate the real roots of an expression over a closed interval or, with infinite endpoints, over the whole real line. precision_bits is the width each enclosure is refined toward; work_budget caps the certified evaluations the search may spend and takes the operation's own default when it is zero.

Two routes answer a request. A polynomial plus one exponential, P(x) + c*exp(a*x + b) with rational data, has a complete real-root count over the whole line: each derivative drops the polynomial degree until only a nonvanishing exponential is left, so the critical points are known exactly enough to make every monotone stretch carry at most one root. Everything else is answered over a bounded interval by exclusion and subdivision, which can prove completeness there but not beyond it, so an unbounded request outside the complete family declines rather than guessing.

An enclosure is certified by directed-rounding interval arithmetic over exact rational bounds. The primitives that carry a proved bound are rational constants, pi, e, sums, products, integer powers, rational powers of a positive base, exp, log, sqrt, sin, cos, tan, sinh, cosh, tanh, and abs; an expression reaching any other head declines with primitive_not_certified, because a bound nobody proved is not a bound.

NumericRootIsolationResult#

Not exposed by the WASM / JavaScript bindings. Available as NumericRootIsolationResult in Python, api::NumericRootIsolationResult in Rust.

What isolate_real_roots_numeric returns. Its coverage is the claim about completeness and is never inferred from the enclosure list: an even-multiplicity root, an exhausted work budget, and a value too close to zero to separate all leave a region unresolved rather than being dropped. Its members are:

Member Meaning Present
verdict isolated or declined Always
coverage whole_real_line, requested_interval, or partial Exactly when the verdict is isolated
enclosures The disjoint certified enclosures, in ascending order Exactly when the verdict is isolated
unresolved_regions The regions the search could neither clear nor resolve Exactly when the verdict is isolated
precision_bits The working precision the accepted enclosures were produced at Exactly when the verdict is isolated
decline_reason Why the search did not run Exactly when the verdict is declined
complete Whether every root of the requested domain is accounted for Always

The decline reasons are domain_not_exactly_rational, domain_empty, expression_identically_zero, primitive_not_certified, and unbounded_domain_not_supported.

isolation_verdict#

Raw WebAssembly: NumericRootIsolationResult property

readonly verdict: string

Getter on NumericRootIsolationResult: whether the search ran or declined.

isolation_coverage#

Raw WebAssembly: NumericRootIsolationResult property

readonly coverage: string | undefined

Getter on NumericRootIsolationResult: how much of the requested domain the enclosures account for. whole_real_line is a strictly stronger claim than requested_interval, and partial says regions remain.

isolation_enclosures#

Raw WebAssembly: NumericRootIsolationResult property

readonly enclosures: NumericRootEnclosure[]

Getter on NumericRootIsolationResult: the disjoint certified enclosures, in ascending order.

isolation_unresolved_regions#

Raw WebAssembly: NumericRootIsolationResult property

readonly unresolvedRegions: NumericRootUnresolvedRegion[]

Getter on NumericRootIsolationResult: the regions the search could neither clear of roots nor resolve into an enclosure.

isolation_precision_bits#

Raw WebAssembly: NumericRootIsolationResult property

readonly precisionBits: number | undefined

Getter on NumericRootIsolationResult: the working precision the accepted enclosures were produced at.

isolation_decline_reason#

Raw WebAssembly: NumericRootIsolationResult property

readonly declineReason: string | undefined

Getter on NumericRootIsolationResult: why the search did not run, present exactly when the verdict is declined.

isolation_complete#

Raw WebAssembly: NumericRootIsolationResult property

readonly complete: boolean

Getter on NumericRootIsolationResult: whether every root of the requested domain is accounted for by an enclosure.

NumericRootEnclosure#

Not exposed by the WASM / JavaScript bindings. Available as NumericRootEnclosure in Python, api::NumericRootEnclosure in Rust.

One certified enclosure of a real root. Its lower and upper are exact rational expressions, and its status is exactly_one_root when a sign change across a monotone stretch proved the root unique inside, or exact_rational_root when the expression vanishes exactly at a rational point and the enclosure has collapsed onto it.

enclosure_lower#

Raw WebAssembly: NumericRootEnclosure property

readonly lower: Expression

Getter on NumericRootEnclosure: the exact rational lower bound of the enclosure.

enclosure_upper#

Raw WebAssembly: NumericRootEnclosure property

readonly upper: Expression

Getter on NumericRootEnclosure: the exact rational upper bound of the enclosure.

enclosure_status#

Raw WebAssembly: NumericRootEnclosure property

readonly status: string

Getter on NumericRootEnclosure: what the search proved about the roots inside this enclosure.

NumericRootUnresolvedRegion#

Not exposed by the WASM / JavaScript bindings. Available as NumericRootUnresolvedRegion in Python, api::NumericRootUnresolvedRegion in Rust.

One region the search could neither clear nor resolve. An absent endpoint means the region reaches the corresponding infinity.

unresolved_region_lower#

Raw WebAssembly: NumericRootUnresolvedRegion property

readonly lower: Expression | undefined

Getter on NumericRootUnresolvedRegion: the lower endpoint of the region, absent when the region reaches negative infinity.

unresolved_region_upper#

Raw WebAssembly: NumericRootUnresolvedRegion property

readonly upper: Expression | undefined

Getter on NumericRootUnresolvedRegion: the upper endpoint of the region, absent when the region reaches positive infinity.

Numerical root finding#

A numerical root is found only when the caller asks for one by name; no symbolic operation calls these operations or falls back to them. A result is certified only with a proof, converged_uncertified only when estimates were allowed explicitly, and otherwise declined with a typed reason.

find_root_numeric#

Raw WebAssembly: Default context

findRootNumeric(
    equations: Expression[],
    variables: string[],
    start: Expression[],
    domain: string,
    method: string,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericRootFindingResult
Calling forms

Raw WebAssembly: Explicit context: Context.findRootNumeric

findRootNumeric(
    equations: Expression[],
    variables: string[],
    start: Expression[],
    domain: string,
    method: string,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericRootFindingResult

Find one root of the square system equations = 0 near start, one start value per variable, real or complex. An equation a = b is read as a - b = 0. In Python, equations and variables may be single items or lists, and start a number (floats and complex numbers are read exactly), an expression, a numeric value, a list of these, or a dictionary keyed by variable. JavaScript takes arrays and positional options; Rust and mobile hosts take a NumericOptions record.

domain is real, complex, or automatic, which means real exactly when every variable is declared real (a positive or negative variable counts). In the real domain the start and every iterate are real, and every value of the equations must be real. method chooses the iteration: newton (damped Newton iteration with the exact symbolic Jacobian and a precision that grows as the iterates converge), secant (the secant method in one variable and Broyden's method in several, which need no derivative), muller (Muller's method for one complex equation, which reaches complex roots from real starts), or automatic (Newton's method; Broyden's method when the Jacobian cannot be evaluated; Muller's method for one complex equation from a real start when Newton's method stalls).

A root is certified by the Krawczyk test: a box around the approximation is proved to contain exactly one root, and every requested digit of every coordinate is faithful. A coordinate proved to be a small rational, and a component proved to vanish (for example the real part of a root on the imaginary axis, by the conjugation symmetry of the equations), is returned exactly. A coordinate that vanishes but is not proved to be zero is given as an enclosure of zero whose width is below the requested precision relative to the largest coordinate of the root. A multiple root, or equations with a function that has no certified kernel, cannot be certified: under accuracy = "estimated_allowed" such a root is returned as converged_uncertified, with values whose error is estimated from two runs at separated precisions and, for one equation, a multiplicity_estimate. A root that violates an assumption declared on a variable declines with left_domain. work_budget caps the iteration steps (0 means 200).

The decline reasons are invalid_start, system_not_square, method_not_applicable, unbound_symbol, not_complex_differentiable (the complex domain with a function such as abs or floor), bracket_has_no_sign_change, continuity_undecided, evaluation_failed_at_iterate, left_domain, assumption_undecided, singular_jacobian, no_convergence, budget_exhausted, certification_failed, and no_certified_kernel.

find_root_numeric_in_bracket#

Raw WebAssembly: Default context

findRootNumericInBracket(
    equation: Expression,
    variable: string,
    lower: Expression,
    upper: Expression,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericRootFindingResult
Calling forms

Raw WebAssembly: Explicit context: Context.findRootNumericInBracket

findRootNumericInBracket(
    equation: Expression,
    variable: string,
    lower: Expression,
    upper: Expression,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericRootFindingResult

Find one real root of equation = 0 in the bracket [lower, upper], whose ends are exact rational numbers (Python reads floats exactly) at which the equation's values have opposite signs. The endpoint signs are certified, and the equation's continuity over the bracket is established by certified enclosures of it over pieces of the bracket, so the returned value encloses a root; a root of odd multiplicity is found as readily as a simple one. The value is not claimed to be the only root in the bracket. The bracket is narrowed by the ITP method; work_budget caps its steps.

NumericRootFindingResult#

What both operations return. Its members are:

Member Meaning Present
status certified, converged_uncertified, or declined Always
variables The variable names, in the order of the values Always
values One NumericValue per variable Unless declined
value(variable) The value of one variable, by name Unless declined
variable_values Python: a dictionary from name to value; mobile: ordered pairs Unless declined
residuals One per equation: a certified enclosure over a certified root, or the value at an estimated root Unless declined
iterations The iteration or bracketing steps taken Always
method The method that located the root (newton, secant, muller, or bracketing) Always
domain real or complex Always
multiplicity_estimate The estimated multiplicity of an estimated root of one equation For converged_uncertified with one equation
working_precision_bits The last working precision used Always
decline_reason Why no root was returned Exactly when declined
unbound_symbols The symbols that are not variables For an unbound_symbol decline

summary describes the outcome in one line.

Raw WebAssembly: NumericRootFindingResult property

readonly declineReason: string | undefined

Why no root was returned, when none was.

Raw WebAssembly: NumericRootFindingResult property

readonly domain: string

The domain searched, "real" or "complex".

Raw WebAssembly: NumericRootFindingResult property

readonly iterations: number

The number of iteration or bracketing steps taken.

Raw WebAssembly: NumericRootFindingResult property

readonly method: string

The method that located the root, or the requested method of a declined search.

Raw WebAssembly: NumericRootFindingResult property

readonly multiplicityEstimate: number | undefined

For one equation, the estimated multiplicity of an estimated root.

Raw WebAssembly: NumericRootFindingResult property

readonly residuals: NumericValue[]

One residual per equation: certified over a certified root, or at an estimated one.

Raw WebAssembly: NumericRootFindingResult property

readonly status: string

"certified", "converged_uncertified", or "declined".

Raw WebAssembly: NumericRootFindingResult method

summary(): string

The outcome in one line.

Raw WebAssembly: NumericRootFindingResult property

readonly unboundSymbols: string[]

The symbols that are not variables, for an unbound_symbol decline.

Raw WebAssembly: NumericRootFindingResult method

value(name: string): NumericValue | undefined

The numeric value of one variable, by name, when a root was returned.

Raw WebAssembly: NumericRootFindingResult property

readonly values: NumericValue[]

One numeric value per variable; empty when the search declined.

Raw WebAssembly: NumericRootFindingResult property

readonly variables: string[]

The variable names, in the order of the values.

Raw WebAssembly: NumericRootFindingResult property

readonly workingPrecisionBits: number

The last working precision used, in bits.

Numerical polynomial roots#

polynomial_roots_numeric#

Raw WebAssembly: Default context

polynomialRootsNumeric(
    polynomial: Expression,
    variable: string,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericPolynomialRootsResult
Calling forms

Raw WebAssembly: Explicit context: Context.polynomialRootsNumeric

polynomialRootsNumeric(
    polynomial: Expression,
    variable: string,
    significant_digits: number,
    accuracy: string,
    maximum_precision_bits: number,
    work_budget: number,
): NumericPolynomialRootsResult

Find every complex root of a polynomial in one variable numerically, each once with its exact multiplicity. An equation a = b is read as a - b = 0. The coefficients may be exact rationals or closed constant expressions such as pi, sqrt(2), or 1 + 2*i; a coefficient that mentions another symbol declines with unbound_symbol. Like every numeric operation it runs only when asked for by name.

All roots are approximated together by the Aberth–Ehrlich iteration and then proved: each is enclosed in a disc shown, from the coefficients' certified enclosures, to hold exactly one root, and every requested digit of every component is faithful. The multiplicities come from an exact square-free decomposition, so a multiple root is listed once with its multiplicity rather than as a cluster of nearby values. When all the coefficients are real, a root proved real has an exactly zero imaginary part and complex roots come in exactly conjugate pairs; a root proved to lie on the imaginary axis has an exactly zero real part; and a root proved to be a small rational, such as 2 or 1 + i, is returned exactly. A component that is not proved zero but is smaller than the root's modulus by more than the requested precision (for example the imaginary part of a real root of a polynomial with non-real coefficients) is given as an enclosure of zero with that bound.

The roots are listed with the real roots first, in increasing order, and then the others by real part and then imaginary part. The result is complete: the multiplicities add up to the degree. Estimates are never returned whatever accuracy allows; a request that cannot be certified declines. work_budget caps the multiprecision iteration sweeps (0 means 2048).

The decline reasons are not_a_polynomial, zero_polynomial (every number is a root), constant_polynomial (no root at all), unbound_symbol, degree_undecided (whether the leading coefficient is zero could not be decided), multiplicity_undecided, no_certified_kernel, coefficient_not_a_number, precision_exhausted, and budget_exhausted.

NumericPolynomialRootsResult#

What polynomial_roots_numeric returns. Its members are:

Member Meaning Present
status certified or declined Always
variable The name of the polynomial's variable Always
degree The exact degree of the polynomial Unless declined
values Each distinct root once, as a NumericValue, in the order above Unless declined
multiplicities The exact multiplicity of each root, in the order of the values Unless declined
complete Whether every root is listed; true exactly when certified Always
working_precision_bits The last working precision used Always
iterations The multiprecision iteration sweeps taken Always
decline_reason Why no roots were returned Exactly when declined
unbound_symbols The symbols other than the variable For an unbound_symbol decline

summary describes the outcome in one line.

Raw WebAssembly: NumericPolynomialRootsResult property

readonly complete: boolean

Whether every root is listed: true exactly for a certified result.

Raw WebAssembly: NumericPolynomialRootsResult property

readonly declineReason: string | undefined

Why no roots were returned, when none were.

Raw WebAssembly: NumericPolynomialRootsResult property

readonly degree: number

The exact degree of the polynomial; zero when the request declined.

Raw WebAssembly: NumericPolynomialRootsResult property

readonly iterations: number

The number of multiprecision iteration sweeps taken.

Raw WebAssembly: NumericPolynomialRootsResult property

readonly multiplicities: Uint32Array

The exact multiplicity of each root, in the order of the values.

Raw WebAssembly: NumericPolynomialRootsResult property

readonly status: string

"certified" or "declined".

Raw WebAssembly: NumericPolynomialRootsResult method

summary(): string

The outcome in one line.

Raw WebAssembly: NumericPolynomialRootsResult property

readonly unboundSymbols: string[]

The symbols other than the variable, for an unbound_symbol decline.

Raw WebAssembly: NumericPolynomialRootsResult property

readonly values: NumericValue[]

Each distinct root once, real roots first in increasing order; empty when declined.

Raw WebAssembly: NumericPolynomialRootsResult property

readonly variable: string

The name of the polynomial's variable.

Raw WebAssembly: NumericPolynomialRootsResult property

readonly workingPrecisionBits: number

The last working precision used, in bits.

Compiled machine functions#

A compiled numeric function evaluates exact expressions many times in binary64 machine arithmetic. Its results are a separate category, machine_approximation: they carry no error bound and no promised number of digits, they are never a NumericValue, and cancellation or ill-conditioning can leave few correct digits. Use evaluate_numeric when digits or a proof are needed. What a compiled function does guarantee is its semantics: branches, domains, and captured assumptions are decided from the exact value of each input, and an output that has no value says why instead of returning a number.

Compiling lowers the expressions once into a register program: every distinct subexpression is one register, shared by all outputs, and constants are prepared once. An exact algebraic constant, such as a root returned by polynomial_root, is prepared once as its correctly rounded float by the certified root evaluator, and decisions that read it, such as a comparison with it, are taken on its exact value. Evaluation runs that program in a portable interpreter; no machine code is generated, so a compiled function behaves the same on every host, including the ones that forbid generating code at run time. Operations are executed in the order the expression gives them, without reassociation or fused multiply-add.

compile_numeric_function#

Raw WebAssembly: Default context

compileNumericFunction(
    outputs: any,
    variables: Expression[],
    domain: string,
    fast_kernels_only: boolean,
): CompiledNumericFunction
Calling forms

Raw WebAssembly: Explicit context: Context.compileNumericFunction

compileNumericFunction(
    outputs: any,
    variables: Expression[],
    domain: string,
    fast_kernels_only: boolean,
): CompiledNumericFunction

Compiles a scalar, a vector, or a matrix of expressions once. variables is an explicit ordered list of distinct symbols and fixes the argument order; no alphabetical order is inferred, an unused variable is allowed, and every free symbol of every output must be listed. So must every symbol the session had declared an assumption about when an output was built, because the output is valid only under those assumptions and each one is checked at every point; compile in a session without unrelated assumptions to keep the argument list short. An empty variable list compiles a constant function. domain is real (real inputs, and an output that is not real has the status non_real) or complex (principal complex arithmetic throughout). A real function does not replace a principal complex power by a real root: (-8)^(1/3) is not real. Rust, Kotlin, and Swift take the two options as a NumericFunctionOptions record; JavaScript takes them positionally. Compilation declines when an output contains anything without a machine kernel, such as a sum, a set, an undefined function, or a special function that has only an estimated kernel, such as bessel_j, and the decline names the reason, the output, and the node; see NumericFunctionCompileDecline.

A host float denotes its exact binary value. Positive and negative zero are the same number when a branch or a domain is decided.

Outputs and shape. outputs is one expression (a scalar), an ordered list of expressions (a vector), or a matrix; see NumericFunctionOutputs. Every result lists the outputs flat, a matrix in row-major order, and output_shape says how to read them back. A list of one expression is a vector of length one, not a scalar, and neither is a one-by-one matrix. An empty list of outputs declines with empty_outputs; a matrix always has at least one entry. Shape is only metadata: no matrix arithmetic is done in machine arithmetic.

Conditions. A piecewise condition is a comparison or a combination of comparisons with and, or, not, and the other connectives; a condition that is not a predicate declines with unsupported_condition. A comparison of inputs with one another or with exact rational constants, such as x > 1/10, is decided exactly on the inputs' binary values and costs no more than the comparison: x > 1/10 holds at the float 0.1, which lies above 1/101/10. A comparison of a computed quantity, such as x^2 < 4 or sqrt(x*x + 1) == x, is decided by a semantic guard (below), never on the rounded values: at x=227x = 2^{27} the rounded sqrt(x*x + 1) equals x, but the exact one does not, and the condition is false.

Semantic guards. A rounded value cannot decide anything that jumps with it. So the branch of a computed condition, the integer of floor and ceiling and the sign of signum and heaviside_step of a computed argument, whether an operation is at a pole, and which side of a branch cut its argument lies on are decided on the exact inputs: the quantities involved are computed again from the exact value of each input with certified ball arithmetic, at a working precision raised until the decision is proved, and that decision is used. floor(3*x) is 0 at the float nearest 1/31/3 although the rounded 3*x is exactly 1. A decision that is still not proved at the precision limit gives undecided_condition, never a guess: floor(sin(pi*x)) at x=1x = 1 is undecided, because no enclosure of the exact sin⁡π=0\sin \pi = 0 excludes the jump. A comparison, floor, ceiling, signum, or heaviside_step of a computed argument pays this cost wherever it is evaluated; a pole or a branch cut is decided only at a point where the rounded argument reaches it. There, a pole of the exact expression gives pole, and an exact argument that avoids the pole gives rounding_failure: 1/(x - 1/4) at x=0.25x = 0.25 is a pole, and 1/(x - 1/10) at the float 0.1, where the rounded denominator is zero but the exact one is not, is a rounding failure. A rounded argument on a branch cut keeps its value when the exact argument lies on the same cut, as log(x - 2) at x=1x = 1 is iπi\pi, and is a rounding failure when the exact argument is off the cut. The realness of a real function's output is decided the same way: an output whose binary64 value has a nonzero imaginary part is non_real only when the exact output is proved not real. exp(i*pi*x) at x=1/2x = 1/2 is non_real, but at x=1x = 1 its rounded value is −1+1.2⋅10−16i-1 + 1.2 \cdot 10^{-16} i while the exact value is −1-1; since no enclosure of sin⁡π\sin \pi is exactly zero, the status there is undecided_condition, never non_real. An exact output whose imaginary part is proved zero keeps the real part of its machine value. Away from those points the binary64 value stands, with the accuracy of any machine value: tan(pi*x/2) at x=1x = 1 is a large finite number, because the rounded argument misses the pole that the exact argument is at, just as 1/(x - 1/10) near the float 0.1 is a large number of few correct digits. Guards are never disabled, not even by fast_kernels_only. The guards a function contains are listed by capabilities() as guard_kinds, and guard_refined marks each batch output whose guard needed more than its first working precision.

Certified bridges. A special function with a certified kernel and no binary64 one, such as gamma, zeta, error_function, lambert_w, or the factorial of a computed argument, runs through a certified bridge: its arguments are computed again from the exact inputs, the certified kernel is evaluated on them at a precision raised until both ends of its result round to the same float, and that float is the value. A bridged value is therefore the correctly rounded value of the function at its exact arguments, and every decision inside it is taken there: gamma(3*x) at minus the float nearest 1/31/3, where the rounded 3*x is exactly −1-1, is the large finite value of Γ\Gamma just beside that pole, not pole. An argument that is an exact integer is read as that integer, so binomial(x, y) at x=−1x = -1, y=2y = 2 is 11 rather than a pole of its gamma form, and a function defined only at integers, such as stirling_second, has the status domain_error at any other argument, including stirling_second(3*x, 2) at the float nearest 1/31/3, whose exact 3*x is not an integer. The order of polygamma, the degree of an orthogonal polynomial, and the branch of lambert_w must be integer literals; a computed one declines with unsupported_head. A bridge costs a certified kernel evaluation, usually microseconds rather than nanoseconds, and a function that must not pay it is compiled with fast_kernels_only, which declines it with bridge_required. When the kernel has no certified value at the operands, or none that settles a float within its limits, as for log_gamma of a negative number, the output has the status kernel_unavailable. The heads a function bridges are listed by capabilities() as bridged_heads, and bridge_used marks each batch output that depends on one.

CompiledNumericFunction#

The immutable function compile_numeric_function returns. It belongs to the session that compiled it: resetting the session makes it stale, and later changes to the session's assumptions do not change it.

Member Meaning
variable_count, output_count The number of inputs each point takes and of flat outputs each point produces
output_shape The dimensions of the output shape: [] for a scalar, [length] for a vector, [rows, columns] for a matrix
domain real or complex
is_stale Whether a session reset has retired the function
evaluate_real(arguments) The outputs at one real point, as floats; fails naming the first output that has no real machine value
evaluate_detailed_real(arguments) A NumericFunctionEvaluation: the value or the status of every output at one real point, with its flags and where each failure arose
evaluate_detailed_complex(real_arguments, imaginary_arguments) The same at one complex point, given as two lists of equal length; a real function refuses a nonzero imaginary coordinate
evaluate_batch_real(coordinates, point_count) A NumericFunctionBatch for many real points
evaluate_batch_complex(real_coordinates, imaginary_coordinates, point_count) The same for complex points, given as two buffers of equal length
derivative(variable) The compiled exact derivative of every output with respect to one input variable, in the same shape
jacobian() The compiled exact Jacobian: a matrix with one row per flat output and one column per variable
evaluate_intervals(lower_bounds, upper_bounds) A NumericFunctionIntervalEvaluation: a proved enclosure of every output over one box of real inputs
interval_directed_kernels, interval_bridged_kernels, interval_unsupported_kernels The heads of this function that interval evaluation encloses with outward-rounded arithmetic, encloses through certified kernels, and cannot enclose
capabilities() A NumericFunctionCapabilities: what the function can do and how, including whether its derivatives compile

Batch layout. Coordinates are one flat buffer in point-major order: the coordinate of variable jj at point pp is at index p⋅variable_count+jp \cdot \text{variable\_count} + j. point_count is always given explicitly, so a batch of a constant function and an empty batch are unambiguous. The buffer length must be exactly point_count⋅variable_count\text{point\_count} \cdot \text{variable\_count}; a wrong length, or a batch whose results would not fit the memory allowance of one call, is refused as a whole before anything is evaluated. There is no broadcasting.

Per-point failures. A point with a NaN or infinite coordinate, or with a non-real coordinate for a real function, gets the status invalid_input on every output and does not disturb the other points. A piecewise function evaluates only the branch its condition selects, so piecewise(1/x if x != 0, 0 otherwise) is 0 at zero. A requirement the expression was simplified under is checked at every point: sqrt(x^2) refined to x under x > 0 has the status assumption_violated at a negative input.

Requirement checks. Requirements are compiled with the function, never re-read from the session, and each of their facts is checked the cheapest way that decides it as exactly as the assumption system does. A fact that holds at every input the function accepts costs nothing at all: every input is finite, the inputs of a real function are real, and a fact about constants alone is decided once when compiling. A fact about inputs and exact rational constants — an order, an equality, a disequality, or a predicate such as integer(n) or positive(x) — is decided exactly on the inputs' binary values: integer(n) holds at the float 2.0 and fails at 2.5, and x != 0 fails at -0.0. A fact about a computed quantity, such as x^2 - 2 > 0, is decided like a semantic guard (above), on certified values computed from the exact inputs at a precision raised until the fact is proved or refuted. Only a fact these cannot express, such as an order involving an undefined function, is judged by the assumption system at the point, which costs about a microsecond. A fact that is still undecided gives undecided_assumption.

Derivatives. derivative and jacobian differentiate exactly and never use finite differences. Each derivative output carries the condition under which it is the derivative, so the derivative of abs(x) has the status derivative_not_established at zero instead of a value. That status says only that differentiability was not proved at the point, not that the derivative does not exist there. A derivative of a derivative keeps the condition of every earlier one. The requirements the differentiated function carries stay requirements of its derivative and are checked first: the derivative of sqrt(x^2) refined to x under x > 0 is assumption_violated at a negative input. A complex function is differentiated as a holomorphic function, and derivative declines when it is not one, naming the output and the node that is not holomorphic.

Host conventions. Python accepts a contiguous one-dimensional native-endian float64 buffer (array('d', ...), a memoryview, or a contiguous float64 NumPy array) and refuses a list, a strided view, or another item type; evaluate_batch_real_list takes a list and allocates the buffer. The input is copied before the interpreter lock is released. Calling the function with one positional argument per variable evaluates one point and returns it in the compiled shape: a float for a scalar, a list for a vector, and a list of rows for a matrix, with complex numbers for a complex function. JavaScript takes Float64Array inputs (a subarray is accepted) and copies them; pointCount must be a non-negative integer. Kotlin and Swift take and return lists of doubles, and one call evaluates the whole batch.

A batch whose total work is large enough is split into contiguous point ranges evaluated in parallel when the session runs in automatic execution mode. The result is identical to the sequential one. In threaded WebAssembly, where arbitrary-precision arithmetic cannot run on several workers at once without queuing, a function whose every point computes certified values (a certified kernel bridge or a guard on computed operands) is evaluated sequentially, and the realness of a real function's outputs is decided after the parallel ranges.

Jacobian layout. For a function with mm flat outputs and nn variables, jacobian() is an mm-by-nn matrix of outputs: the derivative of flat output kk with respect to variable jj is output k⋅n+jk \cdot n + j, whatever the shape of the function. derivative(variable) keeps the mm outputs in their order and the function's shape. A function with no variables has no Jacobian, and jacobian() declines with empty_jacobian.

The compiled-function classes are part of the generated raw layer.

JavaScript
const raw = require("./symi-wasm/pkg-node/symi_wasm.js");

const context = new raw.Context();
const x = () => context.symbol("x");
const y = () => context.symbol("y");
const compiled = context.compileNumericFunction(
    [context.sin(x()).multiply(y()), context.sin(x()).divide(y())],
    [x(), y()],
    "real",
    false,
);
console.log(Array.from(compiled.outputShape), Array.from(compiled.evaluateReal(new Float64Array([0.5, 2]))));

const batch = compiled.evaluateBatchReal(new Float64Array([0.5, 2, 1, 0]), 2);
console.log(Array.from(batch.realValues), batch.statuses);

console.log(Array.from(compiled.jacobian().evaluateReal(new Float64Array([0, 2]))));

const enclosure = compiled.evaluateIntervals(new Float64Array([0, 1]), new Float64Array([1, 2]));
console.log(Array.from(enclosure.lowerBounds), Array.from(enclosure.upperBounds));

const capabilities = compiled.capabilities();
console.log(capabilities.directHeads, capabilities.backends, capabilities.jacobianAvailable);

Raw WebAssembly: CompiledNumericFunction method

capabilities(): NumericFunctionCapabilities

Report what this function can do and how; derivative and Jacobian availability come from compiling them once.

Raw WebAssembly: CompiledNumericFunction method

derivative(variable: Expression): CompiledNumericFunction

Compile the checked exact derivative of every output with respect to one input variable.

Raw WebAssembly: CompiledNumericFunction property

readonly domain: string

The input and result domain chosen at compilation: "real" or "complex".

Raw WebAssembly: CompiledNumericFunction method

evaluateBatchComplex(
    real_coordinates: Float64Array,
    imaginary_coordinates: Float64Array,
    point_count: number,
): NumericFunctionBatch

Evaluate split real and imaginary Float64Array coordinates at point_count points.

Raw WebAssembly: CompiledNumericFunction method

evaluateBatchReal(
    coordinates: Float64Array,
    point_count: number,
): NumericFunctionBatch

Evaluate a Float64Array of real coordinates at point_count points. The coordinates are copied before evaluation.

Raw WebAssembly: CompiledNumericFunction method

evaluateDetailedComplex(
    real_arguments: Float64Array,
    imaginary_arguments: Float64Array,
): NumericFunctionEvaluation

Evaluate every output at one point given as split real and imaginary Float64Array coordinates, keeping the value or the status of each.

Raw WebAssembly: CompiledNumericFunction method

evaluateDetailedReal(arguments: Float64Array): NumericFunctionEvaluation

Evaluate every output at one real point given as a Float64Array, keeping the value or the status of each.

Raw WebAssembly: CompiledNumericFunction method

evaluateIntervals(
    lower_bounds: Float64Array,
    upper_bounds: Float64Array,
): NumericFunctionIntervalEvaluation

Enclose every output over one box of real inputs, given as Float64Arrays holding one finite lower and upper bound for each variable in variable order.

Raw WebAssembly: CompiledNumericFunction method

evaluateReal(arguments: Float64Array): Float64Array

Evaluate every output at one real point; throws if any output has no real machine value. The result is a new Float64Array owned by JavaScript.

Raw WebAssembly: CompiledNumericFunction property

readonly intervalBridgedKernels: string[]

The heads interval evaluation encloses through certified ball kernels.

Raw WebAssembly: CompiledNumericFunction property

readonly intervalDirectedKernels: string[]

The heads interval evaluation encloses with outward-rounded binary64 arithmetic alone.

Raw WebAssembly: CompiledNumericFunction property

readonly intervalUnsupportedKernels: string[]

The heads with no interval kernel; an output that reaches one has no enclosure.

Raw WebAssembly: CompiledNumericFunction property

readonly isStale: boolean

Whether resetting the owner context has retired this compiled function.

Raw WebAssembly: CompiledNumericFunction method

jacobian(): CompiledNumericFunction

Compile the checked exact Jacobian, flattened row-major as outputs by variables.

Raw WebAssembly: CompiledNumericFunction property

readonly outputCount: number

The ordered number of flattened scalar outputs.

Raw WebAssembly: CompiledNumericFunction property

readonly outputShape: Uint32Array

The dimensions of the output shape as a new array: [] for a scalar, [length] for a vector, and [rows, columns] for a matrix.

Raw WebAssembly: CompiledNumericFunction property

readonly variableCount: number

The ordered number of scalar input variables.

NumericFunctionBatch#

What a batch evaluation returns. The entry at index p⋅output_count+kp \cdot \text{output\_count} + k of every member below describes output kk at point pp.

Member Meaning
point_count, output_count The number of points and of flat outputs each point carries
output_shape The dimensions of the output shape of each point, as on the function
real_values, imaginary_values The real and imaginary parts of each output; an entry whose status is not evaluated is a placeholder with no meaning
statuses Why each output has or lacks a value
status_codes The same statuses as one byte each (Python and JavaScript); zero means evaluated
underflow_observed Whether a nonzero quantity was seen as a subnormal or as zero on the way to this output; it does not prove the exact value is zero
bridge_used Whether a certified bridge computed a value this output depends on
guard_refined Whether a semantic guard this output depends on needed more than its first working precision before its decision was proved
all_evaluated Whether every status is evaluated
require_all_evaluated() Fails naming the first output that has no value

In Python the value members, underflow_observed, bridge_used, guard_refined, and status_codes are read-only memoryview objects that stay valid after the batch object is released; in JavaScript they are new typed arrays owned by JavaScript. Reading statuses builds one text per output, so a large batch is cheaper to inspect through all_evaluated and status_codes.

Status Code Meaning
evaluated 0 The output has a machine value
invalid_input 1 The point has a NaN, infinite, or (for a real function) non-real coordinate
domain_error 2 The exact argument of a bridged or guarded function is outside its domain, such as a non-integer argument of a function defined only at integers
pole 3 The expression has a pole at the exact inputs, such as a division by an exact zero
overflow 4 An intermediate exceeded the binary64 range; an overflow is never reported as infinity
invalid_arithmetic 5 An operation produced no number
non_real 6 A real function's output is proved not real at the exact inputs, or a real-only operation received an argument proved not real
unsupported_kernel 7 The selected branch needs an operation without a machine kernel
undecided_condition 8 A branch condition, the jump of a floor, ceiling, signum, or heaviside_step, whether an argument is at a pole or on a branch cut, or whether a real function's output is real could not be decided at the exact inputs within the precision limit
assumption_violated 9 The exact inputs violate a requirement captured at compilation
undecided_assumption 10 A captured requirement could neither be proved nor refuted at the exact inputs
inconsistent_program 11 An internal consistency check failed
kernel_unavailable 12 A certified bridge has no certified value at these operands, or none that settles a float within its precision and resource limits
rounding_failure 13 A rounded argument reached a pole or a branch cut that the exact argument avoids, so binary64 arithmetic has no value there although the exact expression has one
no_matching_branch 14 Every condition of a piecewise function the output selects is false at the exact inputs
derivative_not_established 15 A derivative output whose differentiability condition is not proved at the exact inputs; it does not prove the derivative fails to exist

When an output fails, its status is the one decided first: an invalid coordinate; then a captured requirement that is violated or undecided; then, for a derivative, its differentiability condition; and then the first operation, in the order the expression's children are read from left to right within the branches the point selects, whose own computation failed.

Raw WebAssembly: NumericFunctionBatch property

readonly allEvaluated: boolean

Whether every output of every point has a machine value.

Raw WebAssembly: NumericFunctionBatch property

readonly bridgeUsed: Uint8Array

Point-major observations, as a new Uint8Array of zeros and ones aligned with realValues, of whether a certified bridge computed a value the output depends on.

Raw WebAssembly: NumericFunctionBatch property

readonly guardRefined: Uint8Array

Point-major observations, as a new Uint8Array of zeros and ones aligned with realValues, of whether a semantic guard the output depends on needed a working precision above its first one.

Raw WebAssembly: NumericFunctionBatch property

readonly imaginaryValues: Float64Array

Point-major imaginary parts as a new Float64Array aligned with realValues.

Raw WebAssembly: NumericFunctionBatch property

readonly outputCount: number

The number of flattened scalar outputs each point carries.

Raw WebAssembly: NumericFunctionBatch property

readonly outputShape: Uint32Array

The dimensions of the output shape of each point as a new array: [] for a scalar, [length] for a vector, and [rows, columns] for a matrix.

Raw WebAssembly: NumericFunctionBatch property

readonly pointCount: number

The explicit number of points represented by this batch.

Raw WebAssembly: NumericFunctionBatch property

readonly realValues: Float64Array

Point-major real parts as a new Float64Array owned by JavaScript; an entry whose status is not "evaluated" is a placeholder.

Raw WebAssembly: NumericFunctionBatch method

requireAllEvaluated(): void

Throw for the first output that has no machine value; return nothing otherwise.

Raw WebAssembly: NumericFunctionBatch property

readonly statusCodes: Uint8Array

Point-major output status codes as a new Uint8Array aligned with realValues: zero for an evaluated output and the documented nonzero code of its status otherwise.

Raw WebAssembly: NumericFunctionBatch property

readonly statuses: string[]

Point-major output status names aligned with realValues.

Raw WebAssembly: NumericFunctionBatch property

readonly underflowObserved: Uint8Array

Point-major underflow observations as a new Uint8Array of zeros and ones aligned with realValues.

NumericFunctionEvaluation#

What evaluate_detailed_real and evaluate_detailed_complex return: every output at one point, each with its own value or status, so one failed output does not hide the others. The value, status, and flags at index kk of every member below describe flat output kk.

Member Meaning
output_count The number of flat outputs
output_shape The dimensions of the output shape, as on the function
real_values, imaginary_values The real and imaginary parts of each output; NaN where the output has no value
statuses Why each output has or lacks a value, with the statuses of NumericFunctionBatch
status_codes The same statuses as small integers (Python and JavaScript); zero means evaluated
underflow_observed, bridge_used, guard_refined The flags of each output, as in a batch
failure_path(output) Where in that output its failure arose, or none
all_evaluated Whether every status is evaluated
require_all_evaluated() Fails naming the first output that has no value

Failure paths. failure_path(output) lists the child indices from the output's root to the node whose failure the status reports: the terms of a sum or product, the base then the exponent of a power, the arguments of a call in order, and, for the ii-th branch of a piecewise value, its condition at 2i2i and its value at 2i+12i + 1. An empty list is the output itself. The node is the first, in that child order, whose own computation failed within the branches the point selects; a piecewise value none of whose branches applies is located at the piecewise node, a non_real value at the first node along non-real operands whose value left the real line, and an undecided realness at the output. There is no path for an evaluated output, nor for a status decided before any operation: an invalid input, a captured requirement, or a derivative's differentiability condition. sqrt(x) + 1 at −4-4 is non_real with the path [1], the square root. An output position at or past output_count is refused.

In Python the members are lists; in JavaScript real_values and imaginary_values are new Float64Arrays, the flags and codes new Uint8Arrays, and a missing path is undefined; Kotlin and Swift return lists and an optional path, and carry the statuses as their enum.

JavaScript
const raw = require("./symi-wasm/pkg-node/symi_wasm.js");

const context = new raw.Context();
const x = () => context.symbol("x");
const compiled = context.compileNumericFunction(
    [context.parse("sqrt(x) + 1"), context.exp(x())],
    [x()],
    "real",
    false,
);
const evaluation = compiled.evaluateDetailedReal(new Float64Array([-4]));
console.log(evaluation.statuses, Array.from(evaluation.realValues));
console.log(Array.from(evaluation.failurePath(0)), evaluation.failurePath(1));

Raw WebAssembly: NumericFunctionEvaluation property

readonly allEvaluated: boolean

Whether every output has a machine value.

Raw WebAssembly: NumericFunctionEvaluation property

readonly bridgeUsed: Uint8Array

Whether a certified bridge computed a value each output depends on, as a new Uint8Array of zeros and ones.

Raw WebAssembly: NumericFunctionEvaluation method

failurePath(output: number): Uint32Array | undefined

The child indices from the root of output output to the node its failure arose at, as a new array; undefined for an evaluated output and for a status decided before any operation.

Raw WebAssembly: NumericFunctionEvaluation property

readonly guardRefined: Uint8Array

Whether a semantic guard each output depends on needed a working precision above its first one, as a new Uint8Array of zeros and ones.

Raw WebAssembly: NumericFunctionEvaluation property

readonly imaginaryValues: Float64Array

The imaginary part of each output as a new Float64Array, NaN where the output has no value.

Raw WebAssembly: NumericFunctionEvaluation property

readonly outputCount: number

The number of flattened scalar outputs; every array below has one entry per output.

Raw WebAssembly: NumericFunctionEvaluation property

readonly outputShape: Uint32Array

The dimensions of the output shape as a new array: [] for a scalar, [length] for a vector, and [rows, columns] for a matrix.

Raw WebAssembly: NumericFunctionEvaluation property

readonly realValues: Float64Array

The real part of each output as a new Float64Array, NaN where the output has no value.

Raw WebAssembly: NumericFunctionEvaluation method

requireAllEvaluated(): void

Throw for the first output that has no machine value; return nothing otherwise.

Raw WebAssembly: NumericFunctionEvaluation property

readonly statusCodes: Uint8Array

The status code of each output as a new Uint8Array: zero for an evaluated output and the documented nonzero code of its status otherwise.

Raw WebAssembly: NumericFunctionEvaluation property

readonly statuses: string[]

The status name of each output.

Raw WebAssembly: NumericFunctionEvaluation property

readonly underflowObserved: Uint8Array

Whether a nonzero quantity was observed as a subnormal or zero on the way to each output, as a new Uint8Array of zeros and ones.

NumericFunctionIntervalEvaluation#

What evaluate_intervals returns: for each output, an interval that contains every real value the exact output takes at a point of the box, together with what was proved about where the output is defined and whether it is continuous. The box is one finite closed interval for each variable, given as two lists in variable order; a lower bound above its upper bound, a NaN or infinite bound, or a wrong number of bounds fails the request. Only a function compiled for the real domain can be enclosed.

Member Meaning
output_count The number of flat outputs; every member below has one entry per output
output_shape The dimensions of the output shape, as on the function
lower_bounds, upper_bounds The enclosure of each output. A bound may be infinite, which bounds nothing on that side; both are NaN where enclosure_valid is false
enclosure_valid Whether the bounds are a proved enclosure
definedness Where on the box the output has a real value: everywhere, somewhere, nowhere, or unknown
proved_continuous Whether the output is proved real and continuous at every point of the box
statuses evaluated where the enclosure is valid, and otherwise why it is not, with the statuses of NumericFunctionBatch
all_enclosed Whether every output has a valid enclosure

What an enclosure is. It is a statement about the exact function, not about binary64 evaluation: exp(x) over [0, 1000] is enclosed by [1, +infinity] and is defined everywhere, although evaluating it at 1000 overflows. A value beyond the binary64 range keeps a finite bound on the near side, such as [1.797...e308, +infinity]. An enclosure may be wider than the true range, because interval arithmetic forgets that two occurrences of an input are the same number: x*(1 - x) over [0, 1] is enclosed by [0, 1]. It is never narrower. An enclosure that excludes zero proves the output has no zero on the box only where the output is defined; it never proves that a zero exists.

Definedness. everywhere and nowhere are proofs about every point of the box. somewhere is two proofs: the output is real at some point and is not real at some other. unknown claims nothing. The bounds enclose the values at the points where the output is real: sqrt(x) over [-1, 4] is enclosed by [0, 2] with somewhere, and 1/x over [-1, 2] by the whole real line with somewhere. An output that is real nowhere has no bounds and the status that says why (pole, non_real, or no_matching_branch). A denominator whose enclosure contains zero is not thereby proved to vanish: 1/(x*y + 1) over a box where the enclosure of x*y + 1 contains zero is unknown, not somewhere.

Continuity. proved_continuous is a proof and its absence is not a proof of a discontinuity. A piecewise function is proved continuous only on a box where a single branch applies at every point; where two branches can apply, their ranges are both enclosed and continuity is not established, whether or not the branches agree where they meet.

Branches. Only branches that can apply somewhere on the box are evaluated. A branch guarded by a comparison between an input and a constant is enclosed on the part of the box where the comparison can hold, so piecewise(1/x if x != 0, 0 otherwise) over [-1, 1] is defined everywhere, with an unbounded enclosure.

Assumptions. A requirement the expression was simplified under, and the condition under which a derivative is the derivative, must be proved at every point of the box. Otherwise the output has no enclosure and the status undecided_assumption, or assumption_violated when the requirement fails at every point; the box is never silently shrunk to where the requirement holds. A derivative whose differentiability condition is not proved at every point of the box has the status derivative_not_established and unknown definedness, since the derivative may exist where differentiability was not proved.

Unsupported cases. An output has the status unsupported_kernel and no enclosure when it reaches an operation with no interval kernel for its operands: a power with a non-literal exponent on a base that is not positive, an inverse reciprocal function (arcsec, arccsc, arccot, arcsech, arccsch, arccoth) over an interval containing zero, a two-argument logarithm whose base interval contains one, or piecewise functions nested more than 128 deep. It has the status non_real and no enclosure when a non-real intermediate value feeds an operation that could make it real again, such as abs(sqrt(x)) over a box with negative x.

Cost. Sums, products, integer powers, square roots, and the functions in the first row below are enclosed by binary64 arithmetic rounded outward, each operation checked against the exact result in integer arithmetic. The functions in the second row, and powers with any other exponent, are enclosed from certified values at the ends of each interval on which the function is monotone; each such value costs a certified kernel evaluation, far more than an arithmetic operation. interval_bridged_kernels lists the ones a given function uses. The functions in the third row are evaluated at points through certified bridges and have no interval kernel, so an output that reaches one has the status unsupported_kernel and no enclosure.

Functions Binary64 evaluation Interval evaluation
sqrt, abs, signum, floor, ceiling, conjugate, real_part, imaginary_part, min, max Direct Outward-rounded binary64 arithmetic
sin, cos, tan, sec, csc, cot, arcsin, arccos, arctan, sinh, cosh, tanh, sech, csch, coth, arcsinh, arccosh, arctanh, arcsec, arccsc, arccot, arcsech, arccsch, arccoth, exp, log Direct Certified values at the ends of each monotone piece
digamma, gamma, log_gamma, polygamma, beta, zeta, hurwitz_zeta, error_function, error_function_complementary, imaginary_error_function, fresnel_sine_integral, fresnel_cosine_integral, exponential_integral, sine_integral, cosine_integral, logarithmic_integral, lambert_w, jacobi_polynomial, gegenbauer_polynomial, chebyshev_polynomial_first_kind, chebyshev_polynomial_second_kind, legendre_polynomial, generalized_laguerre_polynomial, hermite_polynomial, binomial, falling_factorial, rising_factorial, stirling_first, stirling_second, bell_number, catalan_number, fibonacci_number, partition_count, heaviside_step Certified bridge None

Raw WebAssembly: NumericFunctionIntervalEvaluation property

readonly allEnclosed: boolean

Whether every output has a valid enclosure.

Raw WebAssembly: NumericFunctionIntervalEvaluation property

readonly definedness: string[]

Where on the box each output has a real value: "everywhere", "somewhere", "nowhere", or "unknown".

Raw WebAssembly: NumericFunctionIntervalEvaluation property

readonly enclosureValid: Uint8Array

Whether each output's bounds are a proved enclosure, as a new Uint8Array of zeros and ones.

Raw WebAssembly: NumericFunctionIntervalEvaluation property

readonly lowerBounds: Float64Array

The lower bound of each output's enclosure as a new Float64Array, possibly -Infinity; NaN where the enclosure is not valid.

Raw WebAssembly: NumericFunctionIntervalEvaluation property

readonly outputCount: number

The number of flattened scalar outputs; every array below has one entry per output.

Raw WebAssembly: NumericFunctionIntervalEvaluation property

readonly outputShape: Uint32Array

The dimensions of the output shape as a new array: [] for a scalar, [length] for a vector, and [rows, columns] for a matrix.

Raw WebAssembly: NumericFunctionIntervalEvaluation property

readonly provedContinuous: Uint8Array

Whether each output is proved real and continuous at every point of the box, as a new Uint8Array of zeros and ones; zero means continuity was not established.

Raw WebAssembly: NumericFunctionIntervalEvaluation property

readonly statuses: string[]

The status name of each output: "evaluated" exactly where its enclosure is valid.

Raw WebAssembly: NumericFunctionIntervalEvaluation property

readonly upperBounds: Float64Array

The upper bound of each output's enclosure as a new Float64Array, possibly Infinity; NaN where the enclosure is not valid.

NumericFunctionCapabilities#

What capabilities() returns: what a compiled function can do and how it does it. Every entry is derived from the function's own register program and the kernel registry, the same inventory the table above is generated from; no separate list of supported features exists. Asking costs a compilation of each derivative and of the Jacobian the first time, because availability is the outcome of actually compiling them; the answer is then kept on the function. A stale function is refused.

Member Meaning
variables The names of the input variables, in argument order
output_shape The dimensions of the output shape, as on the function
domain real or complex
arithmetic_format binary64, the format of every input, intermediate, and result
accuracy machine_approximation: no implied digits and no error radius
backends cpu_register, which runs point and batch evaluation, and, for a real-domain function, cpu_interval, which runs interval evaluation
direct_heads The heads the function runs directly on binary64 registers, sorted: each builtin by name, and sum, product, power, and factorial for the program's own operations. A square root is a power here, because it is computed as the principal power with exponent one half
bridged_heads The heads the function runs through certified bridges, sorted: each builtin by name, and factorial for the factorial of a computed argument
guard_kinds The checks made at an evaluation point before a branch or a value is trusted, in this order: exact_input_comparison (a condition comparing inputs with inputs or exact rational constants, decided exactly at no extra cost), certified_predicate (a condition comparing a computed quantity), discontinuity (a floor, ceiling, signum, or heaviside_step of a computed argument), pole_test (an operation that can meet a pole at its rounded argument), branch_side (an operation with a branch cut and a computed argument), realness_test (a real function with an operation that can leave the real line, such as a logarithm, a non-integer power, or the imaginary unit), and assumption_check (a captured requirement, or a derivative's differentiability condition, that some accepted input can fail, judged at the exact inputs). A certified predicate and a discontinuity cost a certified evaluation wherever they are evaluated, a pole test and a branch side only where the rounded argument reaches the pole or the cut, and a realness test only where an output's binary64 value is not real. A function with none pays for no check
requirement_symbols The names of the symbols the outputs' captured requirements and derivative differentiability conditions mention, sorted; each is an input variable
derivative_variables The variables, in argument order, with respect to which derivative compiles
jacobian_available Whether jacobian compiles
interval_directed_kernels, interval_bridged_kernels, interval_unsupported_kernels The interval kernel lists, as on the function
unsupported_capabilities, unsupported_reasons Two aligned lists: each capability the function lacks and why

An unsupported capability is derivative (once for each variable whose derivative declines, the reason naming the variable and giving the compile decline), jacobian (with its compile decline, which for a function of no variables is empty_jacobian), interval_evaluation (for a function compiled for the complex domain), or interval_enclosure (once for each head that has no interval kernel). floor(x) + signum(y) over x and y has the derivative with respect to y only, since no rule establishes where floor is differentiable, so neither the derivative with respect to x nor the Jacobian is available.

A derivative is valid only where the differentiated output is differentiable, and that condition is checked at every point where it can fail; it then has the guard kind assumption_check. The derivative of abs(x) reports signum as its direct head, assumption_check as its guard, and x as its requirement symbol. The derivative of a smooth real function, such as sin(x)*y, needs only real inputs, which a real function always has, so it has no assumption_check and checks nothing at a point; x and y are still its requirement symbols.

Kotlin and Swift return the guard kinds as the enum UniffiNumericFunctionGuardKind; Python and JavaScript return their names.

Raw WebAssembly: NumericFunctionCapabilities property

readonly accuracy: string

The result category of every value: "machine_approximation", with no implied digits and no error radius.

Raw WebAssembly: NumericFunctionCapabilities property

readonly arithmeticFormat: string

The machine format of every input, intermediate, and result: "binary64".

Raw WebAssembly: NumericFunctionCapabilities property

readonly backends: string[]

The backends that can run the function: "cpu_register" for point and batch evaluation, and "cpu_interval" for interval evaluation of a real-domain function.

Raw WebAssembly: NumericFunctionCapabilities property

readonly bridgedHeads: string[]

The heads the function runs through certified bridges, sorted: builtins by name, and "factorial" for the factorial of a computed argument.

Raw WebAssembly: NumericFunctionCapabilities property

readonly derivativeVariables: string[]

The variables, in argument order, with respect to which derivative compiles.

Raw WebAssembly: NumericFunctionCapabilities property

readonly directHeads: string[]

The heads the function runs directly on binary64 registers, sorted: builtins by name, and "sum", "product", "power", and "factorial" for its own operations.

Raw WebAssembly: NumericFunctionCapabilities property

readonly domain: string

The input and result domain chosen at compilation: "real" or "complex".

Raw WebAssembly: NumericFunctionCapabilities property

readonly guardKinds: string[]

The kinds of checks made at an evaluation point, in a fixed order: "exact_input_comparison", "certified_predicate", "discontinuity", "pole_test", "branch_side", "realness_test", and "assumption_check".

Raw WebAssembly: NumericFunctionCapabilities property

readonly intervalBridgedKernels: string[]

The heads interval evaluation encloses through certified ball kernels.

Raw WebAssembly: NumericFunctionCapabilities property

readonly intervalDirectedKernels: string[]

The heads interval evaluation encloses with outward-rounded binary64 arithmetic alone.

Raw WebAssembly: NumericFunctionCapabilities property

readonly intervalUnsupportedKernels: string[]

The heads with no interval kernel.

Raw WebAssembly: NumericFunctionCapabilities property

readonly jacobianAvailable: boolean

Whether jacobian compiles.

Raw WebAssembly: NumericFunctionCapabilities property

readonly outputShape: Uint32Array

The dimensions of the output shape as a new array: [] for a scalar, [length] for a vector, and [rows, columns] for a matrix.

Raw WebAssembly: NumericFunctionCapabilities property

readonly requirementSymbols: string[]

The names of the symbols the outputs' captured requirements mention, sorted.

Raw WebAssembly: NumericFunctionCapabilities property

readonly unsupportedCapabilities: string[]

The capabilities the function lacks, one per refusal, aligned with unsupportedReasons.

Raw WebAssembly: NumericFunctionCapabilities property

readonly unsupportedReasons: string[]

Why each entry of unsupportedCapabilities is unsupported.

Raw WebAssembly: NumericFunctionCapabilities property

readonly variables: string[]

The names of the input variables, in argument order.

NumericFunctionCompileDecline#

Not exposed by the WASM / JavaScript bindings. Available as api::NumericFunctionCompileDecline in Rust.

Why compile_numeric_function, derivative, or jacobian declined, and where. Rust returns it as ApiError::NumericFunctionDeclined, with reason, output, path, head, variable, symbol, and message. Python raises an exception carrying the same values as the attributes reason, output, path, head, variable, and symbol; JavaScript, Kotlin, and Swift raise an error whose message names them:

Text
numeric function compilation declined (unsupported_head): the head has no machine kernel; head `dirac_delta`; output 0, path [0]
Reason Meaning
unsupported_node An output contains a node with no machine value: a deferred form, or a set or other non-number; for a derivative, a node with no admitted derivative rule or one that is not holomorphic
unsupported_head An output calls a function with neither a binary64 kernel nor a certified bridge, calls one with an argument count it does not accept or with a computed order, degree, or branch where an integer literal is required, or calls an undefined function
estimated_only_head An output calls a function that has only an estimated kernel, such as airy_ai
bridge_required fast_kernels_only is set and an output calls a function that runs through a certified bridge, such as gamma
unsupported_condition A condition is not a predicate: neither a comparison, a connective, nor a truth value
unbound_variable A free symbol of an output, or a symbol its captured requirements mention, is not a variable
duplicate_variable A variable repeats an earlier one
not_a_symbol A variable is not a symbol
empty_outputs No output was given
unknown_provenance The facts an output depends on were not recorded, as for a deserialized expression, so its requirements cannot be checked
unsupported_requirement A captured requirement cannot be checked at a point, as a declaration about an undefined function cannot, or a derivative is proved differentiable nowhere
resource_exhausted Compiling or differentiating reached a resource ceiling, or the certified root evaluator could not prepare an algebraic constant (head polynomial_root) as a correctly rounded binary64 value
empty_jacobian A function of no variables has no Jacobian

output is the flat position of the output concerned (row-major in a matrix), and path the child indices from that output's root to the refused node, empty for the output itself. Children are counted as the function reads them: the terms of a sum or product in the expression's canonical order, the base then the exponent of a power, the arguments of a call, the operands of a comparison or connective, and, for the ii-th branch of a piecewise value, its condition at 2i2i and its value at 2i+12i + 1. head spells the refused function, or the kind of a refused node such as finite_set; symbol names a symbol that is not a variable; and variable is the position of a variable that is not a symbol or repeats one. Every branch is compiled, so a refused node declines even in a branch no input would select.

When several things would decline, the first in this order is reported: no outputs; the variables, position by position; an output without recorded provenance; a resource ceiling; the first refused node of the first output that has one, a node's children left to right before the node; and then, output by output, a requirement symbol that is not a variable or a requirement that cannot be checked. A derivative or jacobian decline that comes from differentiation names the output being differentiated and the path into it.

NumericFunctionOutputs#

Not exposed by the WASM / JavaScript bindings. Available as api::NumericFunctionOutputs in Rust.

The outputs compile_numeric_function takes, and the shape its results keep. There are three shapes, told apart by their number of dimensions:

Shape Outputs output_shape Calling the Python function returns
Scalar one expression [] a number
Vector an ordered list of expressions [length] a list
Matrix a matrix, flattened row-major [rows, columns] a list of rows

Python takes an expression (or an integer or fraction), a list or tuple of them, or a Matrix. JavaScript takes an Expression, an array of Expressions, or a Matrix; as with every array of expressions passed to the raw layer, the objects passed are taken over by the call and cannot be used again. Kotlin and Swift take the generated choice UniffiNumericFunctionOutputs (Scalar, Vector, or Matrix). In Rust, NumericFunctionOutputs has the same three variants, and an expression, a slice, array, or vector of expressions, or a Matrix converts into it, so any of them can be passed to compile_numeric_function directly. Rust reads the shape as a NumericFunctionShape (Scalar, Vector { length }, or Matrix { rows, columns }), with dimensions() giving the list the other hosts return; a NumericFunctionEvaluation carries it as shape. Rust also takes a point as a slice of MachineComplex in evaluate and evaluate_detailed, and each NumericFunctionOutput of the latter carries its failure_path as a record of the output's position and the path that failure_path(output) returns, such as [3, 0] for the first term of the second branch's value.

NumericFunctionOptions#

Not exposed by the WASM / JavaScript bindings. Available as api::NumericFunctionOptions in Rust.

The options compile_numeric_function takes on Rust and mobile hosts: domain (real or complex) and fast_kernels_only, which makes compilation decline with bridge_required instead of running a function through a certified bridge.

Floats and exact rationals#

rational_from_float#

Raw WebAssembly: Default context

rationalFromFloat(value: number, max_denominator: bigint): Expression
Calling forms

Raw WebAssembly: Explicit context: Context.rationalFromFloat

rationalFromFloat(value: number, max_denominator: bigint): Expression

Closest rational with denominator ≤\leq max_denominator (the Fraction.limit_denominator algorithm). Raises on non-finite input.

Example#

This family is not part of the recommended JavaScript facade in this release. Call it through the generated symi.raw layer, whose entries are listed with their wasm-bindgen signatures above, and read Migration for the ownership rules that apply there.

Additional API#

BulkNumericOutcome#

BulkNumericOutcome.diagnostic#

Raw WebAssembly: BulkNumericOutcome property

readonly diagnostic: string | undefined

The item diagnostic when the item declined or failed.

BulkNumericOutcome.index#

Raw WebAssembly: BulkNumericOutcome property

readonly index: number

The original input position of this outcome.

BulkNumericOutcome.value#

Raw WebAssembly: BulkNumericOutcome property

readonly value: NumericValue | undefined

The numeric value when the item evaluated.

Symi documentation · WASM / JavaScript