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.
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).
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.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 ⌈dlog210⌉+1 bits for d 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, 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.
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
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.
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−1020 does
not_exactly_real
A real result, such as a host float, was asked of a value not known to be exactly real
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.
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.
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.
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.
Type
classNumericValue
A complex number approximated by a ball in each component, labelled certified or estimated.
NumericValue method
__complex__()->complex
The nearest complex number to the midpoint.
NumericValue method
__float__()->float
The nearest float of a value known to be exactly real.
NumericValue method
__repr__()->str
The value with its accuracy label.
NumericValue method
__str__()->str
The value at its requested digits.
NumericValue property
accuracy:str
Whether the radii are proved bounds ("certified") or estimates ("estimated").
NumericValue property
achieved_relative_precision_bits: Optional[int]
The relative accuracy in bits, or None when both components are exact.
NumericValue method
certified_sign()-> Optional[int]
The proved sign of a real value as -1, 0, or 1, or None when it is not proved.
NumericValue method
contains_zero()->bool
Whether zero lies within the stated radius of both components.
NumericValue method
error_bound()-> Optional[NumericValue]
A proved bound on the error of a certified value, or None for an estimate.
NumericValue method
error_estimate()-> Optional[NumericValue]
The estimated error of an estimate, or None for a certified value.
NumericValue method
imaginary_part()-> NumericValue
The imaginary part, as a real numeric value with the same accuracy.
NumericValue method
is_exactly_real()->bool
Whether the value is known to be real: its imaginary part is exactly zero.
NumericValue method
is_exactly_zero()->bool
Whether the value is known to be exactly zero.
NumericValue method
real_part()-> NumericValue
The real part, as a real numeric value with the same accuracy.
NumericValue property
requested_significant_digits:int
The number of significant digits the value was requested with.
NumericValue method
summary()->str
The value at its requested digits followed by its accuracy.
NumericValue method
to_complex_f64()->tuple[float,float]
The nearest floats to the real and imaginary midpoints.
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.
Type
classNumericEvaluationReport
Everything an explicit numeric evaluation found out, whether or not it produced a value.
NumericEvaluationReport method
__repr__()->str
The outcome in one line.
NumericEvaluationReport property
absolute_bound: Optional[NumericValue]
A proved bound on the modulus, for a magnitude_below_resolution decline.
NumericEvaluationReport property
best_enclosure: Optional[NumericValue]
The last certified enclosure reached before a decline.
NumericEvaluationReport property
certified_attempts:int
The number of certified ball evaluations performed.
NumericEvaluationReport property
decline_reason: Optional[str]
Why no value was produced, when none was.
NumericEvaluationReport property
estimated_heads:list[str]
The heads the estimated engine evaluated; empty unless the value is an estimate.
NumericEvaluationReport property
exact_decisions:int
The number of undecided balls settled by an exact decision.
NumericEvaluationReport property
heads:list[str]
The builtin heads and constants of the evaluated expression.
NumericEvaluationReport property
responsible_heads:list[str]
The heads without a certified kernel, for a no_certified_kernel decline.
NumericEvaluationReport property
status:str
"evaluated" when a value was produced, "declined" otherwise.
NumericEvaluationReport property
substitution_symbol: Optional[str]
The symbol whose bound value was rejected, for a substitution decline.
NumericEvaluationReport method
summary()->str
A one-line description of the outcome.
NumericEvaluationReport property
unbound_symbols:list[str]
The free symbols left without a value, for an unbound_symbol decline.
Not exposed by the Python 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.
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(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:
W0 on [−1/e,∞) with W0≥−1, and W−1 on [−1/e,0) with
W−1≤−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) for k=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.
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 xlogx or 1/x at 0, 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+φ) or cos(ωx+φ), 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.
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) is a rational function R(k); if its limit
has modulus below one, terms are added until a bound ∣R(k)∣≤q<1 is
proved on the whole remaining tail, which then contributes at most
∣t(N)∣q/(1−q). When the summand is (−1)kh(k) times a constant and
h is proved completely monotone and tending to zero (for example 1/k,
1/(2k+1)2, 1/k, 1/(klogk)), the tail is accelerated by
the Cohen–Villegas–Zagier weights, whose error after n terms is at most
h(N)/Tn(3). A sum of such parts is certified part by part. So
∑1/k! and ∑(−1)k+1/k are certified, while
∑1/k3 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 or ∑(−1)k, or Gauss's test applies, as for ∑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/(klog2k), declines with
estimate_unavailable.
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 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.
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.
Type
classNumericRootIsolationResult
The report from an explicitly requested certified numerical root search.
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.
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.
Type
classNumericRootEnclosure
One certified enclosure of a real root, with exact rational bounds.
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 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 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.
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.
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.
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/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=227 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/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=1 is undecided, because no enclosure of the exact sinπ=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.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=1 is
iπ, 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/2 is non_real,
but at x=1 its rounded value is −1+1.2⋅10−16i while the
exact value is −1; since no enclosure of sinπ 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=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/3, where the rounded 3*x is exactly −1, is the large finite value
of Γ just beside that pole, not pole. An argument that is an exact
integer is read as that integer, so binomial(x, y) at x=−1,
y=2 is 1 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/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.
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
Batch layout. Coordinates are one flat buffer in point-major order: the
coordinate of variable j at point p is at index
p⋅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; 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 m flat outputs and n
variables, jacobian() is an m-by-n matrix of outputs: the
derivative of flat output k with respect to variable j is output
k⋅n+j, whatever the shape of the function. derivative(variable)
keeps the m outputs in their order and the function's shape. A function
with no variables has no Jacobian, and jacobian() declines with
empty_jacobian.
Two outputs sharing sin(x), a batch with a point that has no value, a
constant function, the Jacobian, and an enclosure over a box.
An immutable binary64 function compiled from exact expressions.
CompiledNumericFunction method
__call__(*arguments: Any)-> Any
Evaluate every output at one point given as positional arguments, one per variable. A real function takes and returns floats. A complex function takes floats or complex numbers and returns complex numbers. The result has the compiled shape: one number for a scalar, a list for a vector, and a list of rows for a matrix. It raises if any output has no machine value.
CompiledNumericFunction method
__repr__()->str
The repr() text: the function's shape and domain. It reports staleness instead of failing.
CompiledNumericFunction method
capabilities()-> NumericFunctionCapabilities
Report what this function can do and how; derivative and Jacobian availability come from compiling them once.
What a batch evaluation returns. The entry at index
p⋅output_count+k of every member below describes output
k at point p.
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.
Type
classNumericFunctionBatch
The point-major results of one compiled-function batch evaluation.
NumericFunctionBatch method
__repr__()->str
The repr() text: the batch shape and whether every output was evaluated.
NumericFunctionBatch property
all_evaluated:bool
Whether every output of every point has a machine value.
NumericFunctionBatch property
bridge_used: Any
Point-major observations, as a read-only byte buffer of zeros and ones aligned with real_values, of whether a certified bridge computed a value the output depends on.
NumericFunctionBatch property
guard_refined: Any
Point-major observations, as a read-only byte buffer of zeros and ones aligned with real_values, of whether a semantic guard the output depends on needed a working precision above its first one.
NumericFunctionBatch property
imaginary_values: Any
Point-major imaginary parts as a read-only float64 buffer aligned with real_values.
NumericFunctionBatch property
output_count:int
The number of flattened scalar outputs each point carries.
NumericFunctionBatch property
output_shape:list[int]
The dimensions of the output shape of each point: [] for a scalar, [length] for a vector, and [rows, columns] for a matrix.
NumericFunctionBatch property
point_count:int
The explicit number of points represented by this batch.
NumericFunctionBatch property
real_values: Any
Point-major real parts as a read-only float64 buffer; an entry whose status is not "evaluated" is a placeholder.
NumericFunctionBatch method
require_all_evaluated()->None
Raise for the first output that has no machine value; return nothing otherwise.
NumericFunctionBatch property
status_codes: Any
Point-major output status codes as a read-only byte buffer aligned with real_values: zero for an evaluated output and the documented nonzero code of its status otherwise.
NumericFunctionBatch property
statuses:list[str]
Point-major output status names aligned with real_values.
NumericFunctionBatch property
underflow_observed: Any
Point-major underflow observations as a read-only byte buffer of zeros and ones aligned with real_values.
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 k of every
member below describe flat output k.
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
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 i-th branch of a piecewise value, its condition at
2i and its value at 2i+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 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.
Python
import symi
context = symi.Context()
x = context.symbol("x")
function = context.compile_numeric_function([context.parse("sqrt(x) + 1"), context.exp(x)],[x])
evaluation = function.evaluate_detailed_real([-4.0])print(evaluation.statuses, evaluation.real_values)print(evaluation.failure_path(0), evaluation.failure_path(1))
Type
classNumericFunctionEvaluation
The value or status of every output of a compiled function at one point.
NumericFunctionEvaluation method
__repr__()->str
The repr() text: the output count and the status of each output.
NumericFunctionEvaluation property
all_evaluated:bool
Whether every output has a machine value.
NumericFunctionEvaluation property
bridge_used:list[bool]
Whether a certified bridge computed a value each output depends on.
NumericFunctionEvaluation method
failure_path(output:int)-> Optional[list[int]]
The child indices from the root of output output to the node its failure arose at; None for an evaluated output and for a status decided before any operation.
NumericFunctionEvaluation property
guard_refined:list[bool]
Whether a semantic guard each output depends on needed a working precision above its first one.
NumericFunctionEvaluation property
imaginary_values:list[float]
The imaginary part of each output, NaN where the output has no value.
NumericFunctionEvaluation property
output_count:int
The number of flattened scalar outputs; every list below has one entry per output.
NumericFunctionEvaluation property
output_shape:list[int]
The dimensions of the output shape: [] for a scalar, [length] for a vector, and [rows, columns] for a matrix.
NumericFunctionEvaluation property
real_values:list[float]
The real part of each output, NaN where the output has no value.
NumericFunctionEvaluation method
require_all_evaluated()->None
Raise for the first output that has no machine value; return nothing otherwise.
NumericFunctionEvaluation property
status_codes:list[int]
The status code of each output: zero for an evaluated output and the documented nonzero code of its status otherwise.
NumericFunctionEvaluation property
statuses:list[str]
The status name of each output.
NumericFunctionEvaluation property
underflow_observed:list[bool]
Whether a nonzero quantity was observed as a subnormal or zero on the way to each output.
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
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
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.
Type
classNumericFunctionCapabilities
What a compiled function can do and how, derived from its program and the kernel registry.
NumericFunctionCapabilities method
__repr__()->str
The repr() text: the variables, the shape, the domain, and the direct heads.
NumericFunctionCapabilities property
accuracy:str
The result category of every value: "machine_approximation", with no implied digits and no error radius.
NumericFunctionCapabilities property
arithmetic_format:str
The machine format of every input, intermediate, and result: "binary64".
NumericFunctionCapabilities property
backends:list[str]
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.
NumericFunctionCapabilities property
bridged_heads:list[str]
The heads the function runs through certified bridges, sorted: builtins by name, and "factorial" for the factorial of a computed argument.
NumericFunctionCapabilities property
derivative_variables:list[str]
The variables, in argument order, with respect to which derivative compiles.
NumericFunctionCapabilities property
direct_heads:list[str]
The heads the function runs directly on binary64 registers, sorted: builtins by name, and "sum", "product", "power", and "factorial" for its own operations.
NumericFunctionCapabilities property
domain:str
The input and result domain chosen at compilation: "real" or "complex".
NumericFunctionCapabilities property
guard_kinds:list[str]
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".
NumericFunctionCapabilities property
interval_bridged_kernels:list[str]
The heads interval evaluation encloses through certified ball kernels.
NumericFunctionCapabilities property
interval_directed_kernels:list[str]
The heads interval evaluation encloses with outward-rounded binary64 arithmetic alone.
NumericFunctionCapabilities property
interval_unsupported_kernels:list[str]
The heads with no interval kernel.
NumericFunctionCapabilities property
jacobian_available:bool
Whether jacobian compiles.
NumericFunctionCapabilities property
output_shape:list[int]
The dimensions of the output shape: [] for a scalar, [length] for a vector, and [rows, columns] for a matrix.
NumericFunctionCapabilities property
requirement_symbols:list[str]
The names of the symbols the outputs' captured requirements mention, sorted.
NumericFunctionCapabilities property
unsupported_capabilities:list[str]
The capabilities the function lacks, one per refusal, aligned with unsupported_reasons.
NumericFunctionCapabilities property
unsupported_reasons:list[str]
Why each entry of unsupported_capabilities is unsupported.
NumericFunctionCapabilities property
variables:list[str]
The names of the input variables, in argument order.
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
i-th branch of a piecewise value, its condition at 2i and its value at
2i+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.
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.
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.