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 printed to no decimal places, can be certified only
when it is known exactly. The requested digits are converted to a relative
accuracy of bits for 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 , 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 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#
api::numeric::Session method
pub fn evaluate_numeric(
&self,
input_expression: &Expression,
options: NumericOptions,
) -> Result<NumericValue, ApiError>Calling forms
api::numeric::Expression method: api::numeric::Expression::evaluate_numeric
pub fn evaluate_numeric(
&self,
options: NumericOptions,
) -> Result<NumericValue, ApiError>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#
api::numeric::Session method
pub fn evaluate_numeric_with_substitutions(
&self,
input_expression: &Expression,
options: NumericOptions,
substitutions: &[(Expression, Expression)],
numeric_substitutions: &[(Expression, NumericValue)],
) -> Result<NumericValue, ApiError>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#
api::numeric::Session method
pub fn evaluate_numeric_detailed(
&self,
input_expression: &Expression,
options: NumericOptions,
substitutions: &[(Expression, Expression)],
numeric_substitutions: &[(Expression, NumericValue)],
) -> Result<NumericEvaluationReport, ApiError>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#
api::numeric::Matrix method
pub fn evaluate_numeric(
&self,
options: NumericOptions,
) -> Result<NumericMatrix, ApiError>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.
api re_export
pub use numeric::NumericValue;A complex number approximated by a ball in each component, with an accuracy that says whether the radii are proved bounds or estimates.
api::numeric::NumericValue method
pub fn accuracy(&self) -> NumericAccuracyWhether the radii are proved bounds (certified) or estimates (estimated).
api::numeric::NumericValue method
pub fn achieved_relative_precision_bits(&self) -> Option<u64>The relative accuracy in bits, or None when both components are exact.
api::numeric::NumericValue method
pub fn certified_sign(&self) -> Option<i64>The proved sign of a real value, -1, 0, or 1; None when the value is not known to be real, is an estimate, or its ball meets zero.
api::numeric::NumericValue method
pub fn contains_zero(&self) -> boolWhether zero lies within the stated radius of both components.
api::numeric::NumericValue method
pub fn error_bound(&self) -> Option<NumericValue>A proved bound on the distance from the printed midpoint to the true value, for a certified value; None for an estimate.
api::numeric::NumericValue method
pub fn error_estimate(&self) -> Option<NumericValue>The estimated distance from the midpoint to the true value, for an estimate; None for a certified value.
api::numeric::NumericValue method
pub fn imaginary_part(&self) -> NumericValueThe imaginary part, as a real numeric value with the same accuracy.
api::numeric::NumericValue method
pub fn is_exactly_real(&self) -> boolWhether the value is known to be real: its imaginary part is exactly zero.
api::numeric::NumericValue method
pub fn is_exactly_zero(&self) -> boolWhether the value is known to be exactly zero.
api::numeric::NumericValue method
pub fn real_part(&self) -> NumericValueThe real part, as a real numeric value with the same accuracy.
api::numeric::NumericValue method
pub fn requested_significant_digits(&self) -> u32The number of significant digits the value was requested with.
api::numeric::NumericValue method
pub fn summary(&self) -> StringThe value at its requested digits followed by its accuracy, for display.
api::numeric::NumericValue method
pub fn to_complex_f64(&self) -> (f64, f64)The nearest binary64 numbers to the real and imaginary midpoints.
api::numeric::NumericValue method
pub fn to_decimal_string(
&self,
significant_digits: u32,
) -> Result<String, ApiError>The value in decimal with at most significant_digits faithful digits per component.
api::numeric::NumericValue method
pub fn to_f64(&self) -> Result<f64, ApiError>The nearest binary64 number to the midpoint of a value known to be exactly real.
api::numeric::NumericValue method
pub fn to_latex(
&self,
significant_digits: u32,
) -> Result<String, ApiError>The value in LaTeX with at most significant_digits faithful digits per component.
api::numeric::NumericValue method
pub fn to_rational(&self) -> Result<Expression, ApiError>The exact midpoint as an exact expression: the value of the approximation, not of the quantity approximated.
api::numeric::NumericValue method
pub fn to_simplest_rational(&self) -> Result<Expression, ApiError>The simplest rational inside each component's ball, as an exact expression.
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.
api re_export
pub use numeric::NumericEvaluationReport;Everything an explicit numeric evaluation found out, whether or not it produced a value.
api::numeric::NumericEvaluationReport method
pub fn absolute_bound(&self) -> Option<NumericValue>A proved bound on the modulus of the value, for a magnitude_below_resolution decline.
api::numeric::NumericEvaluationReport method
pub fn best_enclosure(&self) -> Option<NumericValue>The last certified enclosure reached before a decline, if any.
api::numeric::NumericEvaluationReport method
pub fn certified_attempts(&self) -> u32The number of certified ball evaluations performed.
api::numeric::NumericEvaluationReport method
pub fn decline_reason(&self) -> Option<NumericDeclineReason>Why no value was produced, when none was.
api::numeric::NumericEvaluationReport method
pub fn estimated_heads(&self) -> Vec<String>The heads the estimated engine evaluated; empty unless the value is an estimate.
api::numeric::NumericEvaluationReport method
pub fn exact_decisions(&self) -> u32The number of undecided balls settled by an exact decision.
api::numeric::NumericEvaluationReport method
pub fn heads(&self) -> Vec<String>The builtin heads and constants of the evaluated expression, by name.
api::numeric::NumericEvaluationReport method
pub fn responsible_heads(&self) -> Vec<String>The heads without a certified kernel, for a no_certified_kernel decline.
api::numeric::NumericEvaluationReport method
pub fn status(&self) -> NumericEvaluationStatusWhether a value was produced (evaluated) or not (declined).
api::numeric::NumericEvaluationReport method
pub fn substitution_symbol(&self) -> Option<String>The symbol whose bound value was rejected, for a substitution decline.
api::numeric::NumericEvaluationReport method
pub fn summary(&self) -> StringA one-line description of the outcome.
api::numeric::NumericEvaluationReport method
pub fn unbound_symbols(&self) -> Vec<String>The free symbols left without a value, by name, for an unbound_symbol decline.
api::numeric::NumericEvaluationReport method
pub fn value(&self) -> Option<NumericValue>The value, when one was produced.
api::numeric::NumericEvaluationReport method
pub fn working_precision_bits(&self) -> u32The 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.
api re_export
pub use numeric::NumericMatrix;A matrix of numeric values, one per entry of an evaluated matrix.
api::numeric::NumericMatrix method
pub fn columns(&self) -> usizeThe number of columns.
api::numeric::NumericMatrix method
pub fn entries(&self) -> Vec<NumericValue>Every entry in row-major order.
api::numeric::NumericMatrix method
pub fn entry(
&self,
row: usize,
column: usize,
) -> Result<NumericValue, ApiError>The numeric value of one entry.
api::numeric::NumericMatrix method
pub fn rows(&self) -> usizeThe number of rows.
NumericOptions#
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.
api re_export
pub use numeric::NumericOptions;The options every explicit numeric operation takes.
api::numeric::NumericOptions field
pub accuracy:Which kinds of result are accepted.
api::numeric::NumericOptions method
pub fn from_fields(
significant_digits: u64,
accuracy: &str,
maximum_precision_bits: u64,
work_budget: u64,
) -> SelfOptions from their fields, with the accuracy policy named by its spelling. An unrecognized spelling means certified, and values beyond the 32-bit range saturate.
api::numeric::NumericOptions field
pub maximum_precision_bits:The greatest working precision in bits, or 0 for the requested precision plus 4096 bits.
api::numeric::NumericOptions method
pub fn new(significant_digits: u32) -> SelfCertified options for significant_digits digits with the default limits.
api::numeric::NumericOptions field
pub significant_digits:The number of significant decimal digits wanted in each component; at least one.
api::numeric::NumericOptions method
pub fn with_accuracy(self, accuracy: NumericAccuracyPolicy) -> SelfThese options with a different accuracy policy.
api::numeric::NumericOptions method
pub fn with_maximum_precision_bits(
self,
maximum_precision_bits: u32,
) -> SelfThese options with a working-precision cap in bits, 0 restoring the default.
api::numeric::NumericOptions method
pub fn with_work_budget(self, work_budget: u32) -> SelfThese options with a per-round evaluation budget, 0 restoring the default.
api::numeric::NumericOptions field
pub work_budget:The greatest number of evaluations per round of precision refinement, or 0 for the default of 64.
evaluate_to_float#
api::numeric::Session method
pub fn evaluate_to_float(
&self,
input_expression: &Expression,
) -> Result<f64, ApiError>Calling forms
api::numeric::Expression method: api::numeric::Expression::evaluate_to_float
pub fn evaluate_to_float(&self) -> Result<f64, ApiError>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:
on with , and on with
. 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.
for 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#
api::analysis::Session method
pub fn integrate_definite_numeric<'a, VariableType>(
&self,
input_expression: &Expression,
variable: VariableType,
lower: &Expression,
upper: &Expression,
options: NumericOptions,
) -> Result<NumericValue, ApiError>
where
VariableType: Into<VariableLike<'a>>,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 or at , 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 or , 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#
api::analysis::Session method
pub fn summation_numeric<'a, VariableType>(
&self,
summand: &Expression,
index: VariableType,
lower: &Expression,
upper: &Expression,
options: NumericOptions,
) -> Result<NumericValue, ApiError>
where
VariableType: Into<VariableLike<'a>>,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 is a rational function ; if its limit
has modulus below one, terms are added until a bound is
proved on the whole remaining tail, which then contributes at most
. When the summand is times a constant and
is proved completely monotone and tending to zero (for example ,
, , ), the tail is accelerated by
the Cohen–Villegas–Zagier weights, whose error after terms is at most
. A sum of such parts is certified part by part. So
and are certified, while
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
or , or Gauss's test applies, as for .
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 , 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#
api::analysis::Session method
pub fn isolate_real_roots_numeric<'a, VariableType>(
&self,
input_expression: &Expression,
variable: VariableType,
lower: &Expression,
upper: &Expression,
precision_bits: u32,
work_budget: u32,
) -> Result<NumericRootIsolationResult, ApiError>
where
VariableType: Into<VariableLike<'a>>,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#
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.
api re_export
pub use results::NumericRootIsolationResult;The typed result of an explicitly requested certified numerical root search.
isolation_verdict#
api::results::NumericRootIsolationResult method
pub fn verdict(&self) -> NumericRootIsolationVerdictGetter on NumericRootIsolationResult: whether the search ran or declined.
isolation_coverage#
api::results::NumericRootIsolationResult method
pub fn coverage(&self) -> Option<NumericRootCoverage>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#
api::results::NumericRootIsolationResult method
pub fn enclosures(&self) -> Vec<NumericRootEnclosure>Getter on NumericRootIsolationResult: the disjoint certified enclosures, in
ascending order.
isolation_unresolved_regions#
api::results::NumericRootIsolationResult method
pub fn unresolved_regions(&self) -> Vec<NumericRootUnresolvedRegion>Getter on NumericRootIsolationResult: the regions the search could neither
clear of roots nor resolve into an enclosure.
isolation_precision_bits#
api::results::NumericRootIsolationResult method
pub fn precision_bits(&self) -> Option<u32>Getter on NumericRootIsolationResult: the working precision the accepted
enclosures were produced at.
isolation_decline_reason#
api::results::NumericRootIsolationResult method
pub fn decline_reason(
&self,
) -> Option<NumericRootIsolationDeclineReason>Getter on NumericRootIsolationResult: why the search did not run, present
exactly when the verdict is declined.
isolation_complete#
api::results::NumericRootIsolationResult method
pub fn complete(&self) -> boolGetter on NumericRootIsolationResult: whether every root of the requested
domain is accounted for by an enclosure.
NumericRootEnclosure#
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.
api re_export
pub use results::NumericRootEnclosure;One certified enclosure of a real root, with exact rational bounds.
enclosure_lower#
api::results::NumericRootEnclosure method
pub fn lower(&self) -> ExpressionGetter on NumericRootEnclosure: the exact rational lower bound of the
enclosure.
enclosure_upper#
api::results::NumericRootEnclosure method
pub fn upper(&self) -> ExpressionGetter on NumericRootEnclosure: the exact rational upper bound of the
enclosure.
enclosure_status#
api::results::NumericRootEnclosure method
pub fn status(&self) -> NumericRootEnclosureStatusGetter on NumericRootEnclosure: what the search proved about the roots inside
this enclosure.
NumericRootUnresolvedRegion#
One region the search could neither clear nor resolve. An absent endpoint means the region reaches the corresponding infinity.
api re_export
pub use results::NumericRootUnresolvedRegion;One region a certified numerical root search could neither clear nor resolve.
Calling forms
Type: api::results::NumericRootUnresolvedRegion
pub struct NumericRootUnresolvedRegionunresolved_region_lower#
api::results::NumericRootUnresolvedRegion method
pub fn lower(&self) -> Option<Expression>Getter on NumericRootUnresolvedRegion: the lower endpoint of the region,
absent when the region reaches negative infinity.
unresolved_region_upper#
api::results::NumericRootUnresolvedRegion method
pub fn upper(&self) -> Option<Expression>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#
api::root_finding::Session method
pub fn find_root_numeric<'a, IteratorType, VariableType>(
&self,
equations: &[Expression],
variables: IteratorType,
start: &[Expression],
domain: NumericRootFindingDomain,
method: NumericRootFindingMethod,
options: NumericOptions,
) -> Result<NumericRootFindingResult, ApiError>
where
IteratorType: IntoIterator<Item = VariableType>,
VariableType: Into<VariableLike<'a>>,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#
api::root_finding::Session method
pub fn find_root_numeric_in_bracket<'a, VariableType>(
&self,
equation: &Expression,
variable: VariableType,
lower: &Expression,
upper: &Expression,
options: NumericOptions,
) -> Result<NumericRootFindingResult, ApiError>
where
VariableType: Into<VariableLike<'a>>,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.
api re_export
pub use root_finding::NumericRootFindingResult;The result of an explicit numerical root-finding request.
api::root_finding::NumericRootFindingResult method
pub fn decline_reason(&self) -> Option<NumericRootFindingDeclineReason>Why no root was returned, for a declined request.
api::root_finding::NumericRootFindingResult method
pub fn domain(&self) -> NumericRootFindingDomainThe domain searched: real or complex once resolved.
api::root_finding::NumericRootFindingResult method
pub fn iterations(&self) -> u32The number of iteration or bracketing steps taken.
api::root_finding::NumericRootFindingResult method
pub fn method(&self) -> NumericRootFindingMethodThe method that located the root, or the requested method of a declined request.
api::root_finding::NumericRootFindingResult method
pub fn multiplicity_estimate(&self) -> Option<u32>For one equation, the estimated multiplicity of an estimated root.
api::root_finding::NumericRootFindingResult method
pub fn residuals(&self) -> Vec<NumericValue>One residual per equation: a certified enclosure of the equation over a certified root's enclosure, or its value at an estimated root; empty for a declined request.
api::root_finding::NumericRootFindingResult method
pub fn status(&self) -> NumericRootFindingStatuscertified, converged_uncertified, or declined.
api::root_finding::NumericRootFindingResult method
pub fn summary(&self) -> StringThe outcome in one line: each variable's value, or the decline reason.
api::root_finding::NumericRootFindingResult method
pub fn unbound_symbols(&self) -> Vec<String>The symbols that are not variables, for an unbound_symbol decline.
api::root_finding::NumericRootFindingResult method
pub fn value(&self, name: &str) -> Option<NumericValue>The value of one variable, by name, when a root was returned.
api::root_finding::NumericRootFindingResult method
pub fn values(&self) -> Vec<NumericValue>One value per variable, in the variables' order; empty for a declined request.
api::root_finding::NumericRootFindingResult method
pub fn variable_values(&self) -> Vec<(String, NumericValue)>Each variable's name paired with its value, in the variables' order.
api::root_finding::NumericRootFindingResult method
pub fn variables(&self) -> Vec<String>The variable names, in the order the values are given.
api::root_finding::NumericRootFindingResult method
pub fn working_precision_bits(&self) -> u32The last working precision used, in bits.
Numerical polynomial roots#
polynomial_roots_numeric#
api::polynomial_roots::Session method
pub fn polynomial_roots_numeric<'a, VariableType>(
&self,
polynomial: &Expression,
variable: VariableType,
options: NumericOptions,
) -> Result<NumericPolynomialRootsResult, ApiError>
where
VariableType: Into<VariableLike<'a>>,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.
api re_export
pub use polynomial_roots::NumericPolynomialRootsResult;The result of an explicit numerical polynomial root request.
Calling forms
Type: api::polynomial_roots::NumericPolynomialRootsResult
pub struct NumericPolynomialRootsResultapi::polynomial_roots::NumericPolynomialRootsResult method
pub fn complete(&self) -> boolWhether every root of the polynomial is listed: true exactly for a certified result.
api::polynomial_roots::NumericPolynomialRootsResult method
pub fn decline_reason(
&self,
) -> Option<NumericPolynomialRootsDeclineReason>Why no roots were returned, for a declined request.
api::polynomial_roots::NumericPolynomialRootsResult method
pub fn degree(&self) -> u32The exact degree of the polynomial; zero for a declined request.
api::polynomial_roots::NumericPolynomialRootsResult method
pub fn iterations(&self) -> u32The number of multiprecision iteration sweeps taken.
api::polynomial_roots::NumericPolynomialRootsResult method
pub fn multiplicities(&self) -> Vec<u32>The exact multiplicity of each root, in the order of the values.
api::polynomial_roots::NumericPolynomialRootsResult method
pub fn status(&self) -> NumericPolynomialRootsStatuscertified or declined.
api::polynomial_roots::NumericPolynomialRootsResult method
pub fn summary(&self) -> StringThe outcome in one line: each root with its multiplicity, or the decline reason.
api::polynomial_roots::NumericPolynomialRootsResult method
pub fn unbound_symbols(&self) -> Vec<String>The symbols other than the variable, for an unbound_symbol decline.
api::polynomial_roots::NumericPolynomialRootsResult method
pub fn values(&self) -> Vec<NumericValue>Each distinct root once, in canonical order; empty for a declined request.
api::polynomial_roots::NumericPolynomialRootsResult method
pub fn variable(&self) -> StringThe name of the polynomial's variable.
api::polynomial_roots::NumericPolynomialRootsResult method
pub fn working_precision_bits(&self) -> u32The 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#
api::numeric_functions::Session method
pub fn compile_numeric_function(
&self,
outputs: impl Into<NumericFunctionOutputs>,
variables: &[Expression],
options: NumericFunctionOptions,
) -> Result<CompiledNumericFunction, ApiError>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
. 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 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 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
is undecided, because no enclosure of the exact
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 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 is
, 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 is non_real,
but at its rounded value is while the
exact value is ; since no enclosure of 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 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
, where the rounded 3*x is exactly , 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 ,
is 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 , 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 at point is at index
. 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
; 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 flat outputs and
variables, jacobian() is an -by- matrix of outputs: the
derivative of flat output with respect to variable is output
, whatever the shape of the function. derivative(variable)
keeps the outputs in their order and the function's shape. A function
with no variables has no Jacobian, and jacobian() declines with
empty_jacobian.
use symi::api::prelude::*;
use symi::api::NumericFunctionOptions;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let session = Session::new();
let x = session.symbol("x");
let y = session.symbol("y");
let outputs = [session.parse("sin(x)*y")?, session.parse("sin(x)/y")?];
let variables = [x, y];
let function =
session.compile_numeric_function(&outputs, &variables, NumericFunctionOptions::default())?;
println!("{:?} {:?}", function.output_shape(), function.evaluate_real(&[0.5, 2.0])?);
let batch = function.evaluate_batch_real(&[0.5, 2.0, 1.0, 0.0], 2)?;
println!("{:?} {:?}", batch.real_values(), batch.statuses());
println!("{:?}", function.jacobian()?.evaluate_real(&[0.0, 2.0])?);
let enclosure = function.evaluate_intervals(&[0.0, 1.0], &[1.0, 2.0])?;
println!("{:?} {:?}", enclosure.lower_bounds(), enclosure.upper_bounds());
let capabilities = function.capabilities()?;
println!("{:?} {:?}", capabilities.direct_heads(), capabilities.jacobian_available());
Ok(())
}api re_export
pub use numeric_functions::CompiledNumericFunction;An immutable portable binary64 function compiled from exact expressions.
Calling forms
Type: api::numeric_functions::CompiledNumericFunction
pub struct CompiledNumericFunctionapi::numeric_functions::capabilities::CompiledNumericFunction method
pub fn capabilities(
&self,
) -> Result<NumericFunctionCapabilities, ApiError>Reports what this function can do and how, derived from its lowered program and the kernel registry.
api::numeric_functions::CompiledNumericFunction method
pub fn derivative(
&self,
variable: &Expression,
) -> Result<CompiledNumericFunction, ApiError>Compiles checked exact derivatives of every output with respect to one declared variable.
api::numeric_functions::CompiledNumericFunction method
pub fn domain(&self) -> NumericFunctionDomainReturns the domain selected when this immutable function was compiled.
api::numeric_functions::CompiledNumericFunction method
pub fn evaluate(
&self,
arguments: &[MachineComplex],
) -> Result<Vec<MachineComplex>, ApiError>Evaluates all outputs at complex binary64 inputs, failing if any requested output fails.
api::numeric_functions::CompiledNumericFunction method
pub fn evaluate_batch(
&self,
coordinates: &[MachineComplex],
point_count: usize,
) -> Result<NumericFunctionBatch, ApiError>Evaluates a complex flat coordinate buffer at an explicit number of points.
api::numeric_functions::CompiledNumericFunction method
pub fn evaluate_batch_complex(
&self,
real_coordinates: &[f64],
imaginary_coordinates: &[f64],
point_count: usize,
) -> Result<NumericFunctionBatch, ApiError>Evaluates split real and imaginary flat coordinate buffers at an explicit number of points.
api::numeric_functions::CompiledNumericFunction method
pub fn evaluate_batch_real(
&self,
coordinates: &[f64],
point_count: usize,
) -> Result<NumericFunctionBatch, ApiError>Evaluates a real flat coordinate buffer at an explicit number of points.
api::numeric_functions::CompiledNumericFunction method
pub fn evaluate_detailed(
&self,
arguments: &[MachineComplex],
) -> Result<NumericFunctionEvaluation, ApiError>Evaluates every output independently and retains the result or status of each one.
api::numeric_functions::CompiledNumericFunction method
pub fn evaluate_detailed_complex(
&self,
real_arguments: &[f64],
imaginary_arguments: &[f64],
) -> Result<NumericFunctionEvaluation, ApiError>Evaluates every output independently at one point given as split real and imaginary coordinates of equal length, the coordinate of each variable being real + i * imaginary, and retains the result or status of each one, as [CompiledNumericFunction::evaluate_detailed] does.
api::numeric_functions::CompiledNumericFunction method
pub fn evaluate_detailed_real(
&self,
arguments: &[f64],
) -> Result<NumericFunctionEvaluation, ApiError>Evaluates every output independently at one real point and retains the result or status of each one, as [CompiledNumericFunction::evaluate_detailed] does.
api::numeric_functions::interval_evaluation::CompiledNumericFunction method
pub fn evaluate_intervals(
&self,
lower_bounds: &[f64],
upper_bounds: &[f64],
) -> Result<NumericFunctionIntervalEvaluation, ApiError>Encloses every output over one box of real inputs.
api::numeric_functions::CompiledNumericFunction method
pub fn evaluate_real(
&self,
arguments: &[f64],
) -> Result<Vec<f64>, ApiError>Evaluates all outputs at real binary64 inputs, failing if any output has no real value.
api::numeric_functions::interval_evaluation::CompiledNumericFunction method
pub fn interval_bridged_kernels(&self) -> Vec<String>Returns the heads of this function that interval evaluation encloses through certified ball kernels, which cost far more than directed arithmetic, sorted.
api::numeric_functions::interval_evaluation::CompiledNumericFunction method
pub fn interval_directed_kernels(&self) -> Vec<String>Returns the heads of this function that interval evaluation encloses with outward-rounded binary64 arithmetic alone, sorted.
api::numeric_functions::interval_evaluation::CompiledNumericFunction method
pub fn interval_unsupported_kernels(&self) -> Vec<String>Returns the heads of this function that have no interval kernel, sorted. An output that reaches one of them has no enclosure.
api::numeric_functions::CompiledNumericFunction method
pub fn is_stale(&self) -> boolReturns whether a session reset has retired this function.
api::numeric_functions::CompiledNumericFunction method
pub fn jacobian(&self) -> Result<CompiledNumericFunction, ApiError>Compiles the checked Jacobian in row-major output-by-variable order.
api::numeric_functions::CompiledNumericFunction method
pub fn output_count(&self) -> usizeReturns the ordered scalar-output count produced by point evaluation.
api::numeric_functions::CompiledNumericFunction method
pub fn output_dimensions(&self) -> Vec<usize>Returns the dimensions of the output shape: none for a scalar, the length of a vector, and the rows then the columns of a matrix.
api::numeric_functions::CompiledNumericFunction method
pub fn output_shape(&self) -> NumericFunctionShapeReturns the shape the outputs were compiled in.
api::numeric_functions::CompiledNumericFunction method
pub fn variable_count(&self) -> usizeReturns the ordered variable count required by point evaluation.
NumericFunctionBatch#
What a batch evaluation returns. The entry at index of every member below describes output at point .
| 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.
api re_export
pub use numeric_functions::NumericFunctionBatch;Flat, point-major results of one checked compiled-function batch evaluation.
api::numeric_functions::NumericFunctionBatch method
pub fn all_evaluated(&self) -> boolReturns whether every output of every point has a machine value.
api::numeric_functions::NumericFunctionBatch method
pub fn bridge_used(&self) -> Vec<bool>Returns, per output, whether a certified bridge computed a value the output depends on.
api::numeric_functions::NumericFunctionBatch method
pub fn diagnostics(&self) -> &[MachineDiagnosticFlags]Returns the non-certifying machine diagnostics aligned with the values.
api::numeric_functions::NumericFunctionBatch method
pub fn guard_refined(&self) -> Vec<bool>Returns, per output, whether a semantic guard the output depends on needed a working precision above the one it is first attempted at.
api::numeric_functions::NumericFunctionBatch method
pub fn imaginary_values(&self) -> Vec<f64>Returns the imaginary binary64 components in point-major output order.
api::numeric_functions::NumericFunctionBatch method
pub fn output_count(&self) -> usizeReturns the number of flattened scalar outputs each point carries.
api::numeric_functions::NumericFunctionBatch method
pub fn output_dimensions(&self) -> Vec<usize>Returns the dimensions of the output shape of each point: none for a scalar, the length of a vector, and the rows then the columns of a matrix.
api::numeric_functions::NumericFunctionBatch method
pub fn output_shape(&self) -> NumericFunctionShapeReturns the shape the outputs of each point were compiled in.
api::numeric_functions::NumericFunctionBatch method
pub fn point_count(&self) -> usizeReturns the explicit number of points requested, including for zero-variable functions.
api::numeric_functions::NumericFunctionBatch method
pub fn real_values(&self) -> Vec<f64>Returns the real binary64 components in point-major output order.
api::numeric_functions::NumericFunctionBatch method
pub fn require_all_evaluated(&self) -> Result<(), ApiError>Fails with the first output, in point-major order, that has no machine value.
api::numeric_functions::NumericFunctionBatch method
pub fn status_codes(&self) -> Vec<u8>Returns the per-output status codes in point-major output order; see [NumericFunctionOutputStatus::code].
api::numeric_functions::NumericFunctionBatch method
pub fn statuses(&self) -> Vec<NumericFunctionOutputStatus>Returns the per-output statuses in point-major output order.
api::numeric_functions::NumericFunctionBatch method
pub fn underflow_observed(&self) -> Vec<bool>Returns, per output, whether a nonzero quantity was observed as a subnormal or zero.
api::numeric_functions::NumericFunctionBatch method
pub fn values(&self) -> &[MachineComplex]Returns the machine values in point-major, flattened output order.
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 of every
member below describe flat output .
| 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 -th branch of a piecewise value, its condition at
and its value at . 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 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.
use symi::api::prelude::*;
use symi::api::NumericFunctionOptions;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let session = Session::new();
let x = session.symbol("x");
let outputs = [session.parse("sqrt(x) + 1")?, session.parse("exp(x)")?];
let function = session.compile_numeric_function(
&outputs,
std::slice::from_ref(&x),
NumericFunctionOptions::default(),
)?;
let evaluation = function.evaluate_detailed_real(&[-4.0])?;
println!("{:?} {:?}", evaluation.statuses(), evaluation.real_values());
println!("{:?} {:?}", evaluation.failure_path(0)?, evaluation.failure_path(1)?);
Ok(())
}api re_export
pub use numeric_functions::NumericFunctionEvaluation;The detailed result of one compiled numeric-function point evaluation.
Calling forms
Type: api::numeric_functions::NumericFunctionEvaluation
pub struct NumericFunctionEvaluationapi::numeric_functions::NumericFunctionEvaluation method
pub fn all_evaluated(&self) -> boolReturns whether every output has a machine value.
api::numeric_functions::NumericFunctionEvaluation method
pub fn bridge_used(&self) -> Vec<bool>Returns, per output, whether a certified bridge computed a value the output depends on.
api::numeric_functions::NumericFunctionEvaluation method
pub fn failure_path(
&self,
output: usize,
) -> Result<Option<Vec<usize>>, ApiError>Returns the child indices from the root of one output to the node its failure arose at, as [NumericFunctionOutput::failure_path] gives them; None for an evaluated output and for a status decided before any operation. Fails for an output position at or past the output count.
api::numeric_functions::NumericFunctionEvaluation method
pub fn guard_refined(&self) -> Vec<bool>Returns, per output, whether a semantic guard the output depends on needed a working precision above the one it is first attempted at.
api::numeric_functions::NumericFunctionEvaluation method
pub fn imaginary_values(&self) -> Vec<f64>Returns the imaginary binary64 component of each output, NaN where the output has no value.
api::numeric_functions::NumericFunctionEvaluation field
pub machine_approximation:This result is a binary64 machine approximation, never a certified numeric value.
api::numeric_functions::NumericFunctionEvaluation method
pub fn output_count(&self) -> usizeReturns the number of flattened scalar outputs.
api::numeric_functions::NumericFunctionEvaluation method
pub fn output_dimensions(&self) -> Vec<usize>Returns the dimensions of the output shape: none for a scalar, the length of a vector, and the rows then the columns of a matrix.
api::numeric_functions::NumericFunctionEvaluation method
pub fn output_shape(&self) -> NumericFunctionShapeReturns the shape the outputs were compiled in.
api::numeric_functions::NumericFunctionEvaluation field
pub outputs:Results in the exact output order supplied at compilation, a matrix flattened row-major.
api::numeric_functions::NumericFunctionEvaluation method
pub fn real_values(&self) -> Vec<f64>Returns the real binary64 component of each output, NaN where the output has no value.
api::numeric_functions::NumericFunctionEvaluation method
pub fn require_all_evaluated(&self) -> Result<(), ApiError>Fails with the first output that has no machine value.
api::numeric_functions::NumericFunctionEvaluation field
pub shape:The shape the outputs were compiled in.
api::numeric_functions::NumericFunctionEvaluation method
pub fn status_codes(&self) -> Vec<u8>Returns the status code of each output; see [NumericFunctionOutputStatus::code].
api::numeric_functions::NumericFunctionEvaluation method
pub fn statuses(&self) -> Vec<NumericFunctionOutputStatus>Returns the status of each output.
api::numeric_functions::NumericFunctionEvaluation method
pub fn underflow_observed(&self) -> Vec<bool>Returns, per output, whether a nonzero quantity was observed as a subnormal or zero.
NumericFunctionIntervalEvaluation#
api re_export
pub use numeric_functions::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.
Calling forms
api::numeric_functions re_export: api::numeric_functions::NumericFunctionIntervalEvaluation
pub use interval_evaluation::NumericFunctionIntervalEvaluation;Type: api::numeric_functions::interval_evaluation::NumericFunctionIntervalEvaluation
pub struct NumericFunctionIntervalEvaluationapi::numeric_functions::interval_evaluation::NumericFunctionIntervalEvaluation method
pub fn all_enclosed(&self) -> boolReturns whether every output has a valid enclosure.
api::numeric_functions::interval_evaluation::NumericFunctionIntervalEvaluation method
pub fn definedness(&self) -> Vec<NumericFunctionDefinedness>Returns, per output, where on the box it has a real value.
api::numeric_functions::interval_evaluation::NumericFunctionIntervalEvaluation method
pub fn enclosure_valid(&self) -> Vec<bool>Returns, per output, whether its bounds are a proved enclosure of every real value it takes on the box.
api::numeric_functions module
pub mod interval_evaluation;api::numeric_functions::interval_evaluation::NumericFunctionIntervalEvaluation method
pub fn lower_bounds(&self) -> Vec<f64>Returns the lower bound of each output's enclosure, possibly negative infinity; NaN where the enclosure is not valid.
api::numeric_functions::interval_evaluation::NumericFunctionIntervalEvaluation method
pub fn output_count(&self) -> usizeReturns the number of flattened scalar outputs.
api::numeric_functions::interval_evaluation::NumericFunctionIntervalEvaluation method
pub fn output_dimensions(&self) -> Vec<usize>Returns the dimensions of the output shape: none for a scalar, the length of a vector, and the rows then the columns of a matrix.
api::numeric_functions::interval_evaluation::NumericFunctionIntervalEvaluation method
pub fn output_shape(&self) -> NumericFunctionShapeReturns the shape the outputs were compiled in.
api::numeric_functions::interval_evaluation::NumericFunctionIntervalEvaluation method
pub fn proved_continuous(&self) -> Vec<bool>Returns, per output, whether it is proved real and continuous at every point of the box. false means continuity was not established, not that the output is discontinuous.
api::numeric_functions::interval_evaluation::NumericFunctionIntervalEvaluation method
pub fn statuses(&self) -> Vec<NumericFunctionOutputStatus>Returns the status of each output: evaluated exactly when its enclosure is valid.
api::numeric_functions::interval_evaluation::NumericFunctionIntervalEvaluation method
pub fn upper_bounds(&self) -> Vec<f64>Returns the upper bound of each output's enclosure, possibly positive infinity; NaN where the enclosure is not valid.
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 |
NumericFunctionCapabilities#
api::numeric_functions::capabilities::NumericFunctionGuardKind variant
AssumptionCheck,An output carries captured requirements, or a derivative output its differentiability condition, that some accepted input can fail, judged at the exact dyadic value of each input before its value is reported. A condition every accepted input satisfies, such as the realness of the inputs of a real function, is decided when compiling and needs none.
api::numeric_functions::capabilities::NumericFunctionGuardKind variant
BranchSide,An operation with a branch cut and a computed operand; when the rounded operand lies on the cut, the exact operand decides whether its value is kept.
api::numeric_functions::capabilities::NumericFunctionGuardKind variant
CertifiedPredicate,A condition compares a computed quantity, decided on certified values of its operands computed from the exact inputs.
api::numeric_functions::capabilities::NumericFunctionGuardKind variant
Discontinuity,A floor, ceiling, signum, or Heaviside step of a computed operand, whose jump is decided on a certified value of the operand computed from the exact inputs.
api::numeric_functions::capabilities::NumericFunctionGuardKind variant
ExactInputComparison,A piecewise or connective condition compares inputs with inputs or with exact rational constants, decided exactly on the inputs' dyadic values at no extra cost.
api re_export
pub use numeric_functions::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.
Calling forms
api::numeric_functions re_export: api::numeric_functions::NumericFunctionCapabilities
pub use capabilities::NumericFunctionCapabilities;Type: api::numeric_functions::capabilities::NumericFunctionCapabilities
pub struct NumericFunctionCapabilitiesapi re_export
pub use numeric_functions::NumericFunctionGuardKind;Public re_export placement for NumericFunctionGuardKind.
Calling forms
api::numeric_functions re_export: api::numeric_functions::NumericFunctionGuardKind
pub use capabilities::NumericFunctionGuardKind;Type: api::numeric_functions::capabilities::NumericFunctionGuardKind
pub enum NumericFunctionGuardKindapi::numeric_functions::capabilities::NumericFunctionGuardKind variant
PoleTest,An operation that can meet a pole at its rounded operands; when it does, the certified kernel at the exact operands decides whether the expression has a pole there.
api::numeric_functions::capabilities::NumericFunctionGuardKind variant
RealnessTest,An operation of a real function that can leave the real line; when an output's binary64 value is not real, the exact output decides whether it is non_real, real, or undecided.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn accuracy(&self) -> StringThe result category of every value: machine_approximation, which carries no implied digits and no error radius.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn arithmetic_format(&self) -> StringThe machine format of every input, intermediate, and result: binary64.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn backends(&self) -> Vec<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.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn bridged_heads(&self) -> Vec<String>The heads the function calls that run through a certified bridge, sorted: each builtin whose certified ball kernel has no binary64 counterpart, by its head, and factorial for the factorial of a computed argument. A bridged value is the correctly rounded value of the certified kernel at the exact operands, computed from the exact inputs, and costs a certified kernel evaluation. A function compiled with only direct kernels allowed lists none.
api::numeric_functions module
pub mod capabilities;api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn derivative_variables(&self) -> Vec<String>The variables, in argument order, with respect to which [CompiledNumericFunction::derivative] compiles.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn direct_heads(&self) -> Vec<String>The heads the function calls that run directly on binary64 register operands, sorted: each builtin by its head, and the program's own operations as sum, product, power (whatever the exponent), and factorial. Comparisons and piecewise selection are not listed.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn domain(&self) -> NumericFunctionDomainThe input and result domain chosen at compilation.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn guard_kinds(&self) -> Vec<NumericFunctionGuardKind>The kinds of checks the function performs at an evaluation point, in declaration order of [NumericFunctionGuardKind]. A function with none never pays for a check; an exact input comparison costs no more than the comparison, a certified predicate and a discontinuity cost a certified evaluation wherever they are executed, and a pole test and a branch side cost one only at a point whose rounded operand reaches the pole or the cut.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn interval_bridged_kernels(&self) -> Vec<String>The heads interval evaluation encloses through certified ball kernels, sorted.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn interval_directed_kernels(&self) -> Vec<String>The heads interval evaluation encloses with outward-rounded binary64 arithmetic alone, sorted.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn interval_unsupported_kernels(&self) -> Vec<String>The heads that have no interval kernel, sorted.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn jacobian_available(&self) -> boolWhether [CompiledNumericFunction::jacobian] compiles.
api::numeric_functions::capabilities::NumericFunctionGuardKind method
pub fn name(self) -> &'static strReturns the stable lowercase spelling used by host bindings.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn output_dimensions(&self) -> Vec<usize>The dimensions of the output shape: none for a scalar, the length of a vector, and the rows then the columns of a matrix.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn output_shape(&self) -> NumericFunctionShapeThe shape the outputs were compiled in.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn requirement_symbols(&self) -> Vec<String>The names of the symbols the captured requirements of the outputs, and the differentiability conditions of derivative outputs, mention, sorted. Every one is an input variable.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn unsupported_capabilities(&self) -> Vec<String>The capabilities the function does not have, one entry per refusal, aligned with [NumericFunctionCapabilities::unsupported_reasons]: derivative (once for each variable whose derivative declines), jacobian, interval_evaluation, and interval_enclosure (once for each head without an interval kernel).
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn unsupported_reasons(&self) -> Vec<String>Why each entry of [NumericFunctionCapabilities::unsupported_capabilities] is unsupported; a refused derivative or Jacobian gives its compile decline.
api::numeric_functions::capabilities::NumericFunctionCapabilities method
pub fn variables(&self) -> Vec<String>The names of the input variables, in argument order.
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.
NumericFunctionCompileDecline#
api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason variant
BridgeRequired,An output calls a head that has a certified kernel but no binary64 one, and only direct binary64 kernels are allowed.
api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason variant
DuplicateVariable,A variable repeats an earlier one.
api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason variant
EmptyJacobian,A function of no variables has no Jacobian.
api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason variant
EmptyOutputs,No output was given.
api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason variant
EstimatedOnlyHead,An output calls a head that has only an estimated kernel.
api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason variant
NotASymbol,A variable is not a symbol.
api re_export
pub use numeric_functions::NumericFunctionCompileDecline;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.
Calling forms
api::numeric_functions re_export: api::numeric_functions::NumericFunctionCompileDecline
pub use compile_decline::NumericFunctionCompileDecline;Type: api::numeric_functions::compile_decline::NumericFunctionCompileDecline
pub struct NumericFunctionCompileDeclineapi re_export
pub use numeric_functions::NumericFunctionCompileDeclineReason;Public re_export placement for NumericFunctionCompileDeclineReason.
Calling forms
api::numeric_functions re_export: api::numeric_functions::NumericFunctionCompileDeclineReason
pub use compile_decline::NumericFunctionCompileDeclineReason;Type: api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason
pub enum NumericFunctionCompileDeclineReasonapi::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason variant
ResourceExhausted,Lowering, or the checked differentiation of an output, reached a resource ceiling, or the certified root evaluator could not prepare an algebraic constant.
api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason variant
UnboundVariable,A free symbol of an output, or a symbol its captured requirements mention, is not one of the variables.
api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason variant
UnknownProvenance,The facts an output depends on were never recorded, so its requirements cannot be checked.
api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason variant
UnsupportedCondition,A condition is not a predicate: it is neither a comparison, a connective, nor a truth value.
api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason variant
UnsupportedHead,An output calls a head with neither a binary64 kernel nor a certified bridge, calls a head 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.
api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason variant
UnsupportedNode,An output contains a node with no machine value: a deferred derivative, integral, sum, product, or transform, or a set or other non-number. For a derivative, the node has no admitted derivative rule or is not holomorphic.
api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason variant
UnsupportedRequirement,A captured requirement of an output cannot be checked at a point, or the derivative of an output is proved differentiable nowhere.
api::numeric_functions module
pub mod compile_decline;api::numeric_functions::compile_decline::NumericFunctionCompileDecline method
pub fn head(&self) -> Option<&str>The spelling of the refused head, or of the refused node's kind (such as integral or polynomial_root), when a node is refused.
api::numeric_functions::compile_decline::NumericFunctionCompileDecline method
pub fn message(&self) -> StringThe explanation, naming the reason and everything the decline locates.
api::numeric_functions::compile_decline::NumericFunctionCompileDeclineReason method
pub fn name(self) -> &'static strReturns the stable lowercase spelling used by host diagnostics.
api::numeric_functions::compile_decline::NumericFunctionCompileDecline method
pub fn output(&self) -> Option<usize>The position of the output that contains the refused node or requirement, when the decline concerns one output.
api::numeric_functions::compile_decline::NumericFunctionCompileDecline method
pub fn path(&self) -> &[usize]The child indices from the output's root to the refused node; empty for the output itself or when the decline concerns no node.
api::numeric_functions::compile_decline::NumericFunctionCompileDecline method
pub fn reason(&self) -> NumericFunctionCompileDeclineReasonWhy compilation declined.
api::numeric_functions::compile_decline::NumericFunctionCompileDecline method
pub fn symbol(&self) -> Option<&str>The name of a symbol that is not one of the variables.
api::numeric_functions::compile_decline::NumericFunctionCompileDecline method
pub fn variable(&self) -> Option<usize>The position in the variable list of a variable that is not a symbol or repeats an earlier one.
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:
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
-th branch of a piecewise value, its condition at and its value at
. 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#
api::numeric_functions::output_shape::NumericFunctionOutputs variant
Matrix(Matrix)A concrete matrix of scalar expressions. A matrix always has at least one entry.
api re_export
pub use numeric_functions::NumericFunctionOutputs;The outputs compile_numeric_function takes, and the shape its results keep. There are three shapes, told apart by their number of dimensions:
Calling forms
api::numeric_functions re_export: api::numeric_functions::NumericFunctionOutputs
pub use output_shape::NumericFunctionOutputs;Type: api::numeric_functions::output_shape::NumericFunctionOutputs
pub enum NumericFunctionOutputsapi re_export
pub use numeric_functions::NumericFunctionShape;Public re_export placement for NumericFunctionShape.
Calling forms
api::numeric_functions re_export: api::numeric_functions::NumericFunctionShape
pub use output_shape::NumericFunctionShape;Type: api::numeric_functions::output_shape::NumericFunctionShape
pub enum NumericFunctionShapeapi::numeric_functions::output_shape::NumericFunctionOutputs variant
Scalar(Expression)One scalar expression.
api::numeric_functions::output_shape::NumericFunctionShape variant
Scalar,One scalar output.
api::numeric_functions::output_shape::NumericFunctionOutputs variant
Vector(Vec<Expression>)An ordered list of scalar expressions; an empty list declines with empty_outputs.
api::numeric_functions::output_shape::NumericFunctionShape method
pub fn dimensions(self) -> Vec<usize>Returns the dimensions of the shape: none for a scalar, the length of a vector, and the rows then the columns of a matrix.
api::numeric_functions::output_shape::NumericFunctionShape method
pub fn name(self) -> &'static strReturns the stable lowercase spelling of the kind of shape: scalar, vector, or matrix.
api::numeric_functions::output_shape::NumericFunctionShape method
pub fn output_count(self) -> usizeReturns the number of flattened scalar outputs the shape holds.
api::numeric_functions module
pub mod output_shape;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#
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.
api re_export
pub use numeric_functions::NumericFunctionOptions;Options controlling compilation of a portable binary64 numeric function.
Calling forms
Type: api::numeric_functions::NumericFunctionOptions
pub struct NumericFunctionOptionsapi::numeric_functions::NumericFunctionOptions field
pub domain:The requested input and result domain.
api::numeric_functions::NumericFunctionOptions field
pub fast_kernels_only:Whether compilation must reject a kernel outside the direct binary64 implementation.
api::numeric_functions::NumericFunctionOptions method
pub fn from_fields(domain: &str, fast_kernels_only: bool) -> SelfOptions from their fields, with the domain named by its spelling. An unrecognized spelling means real.
Floats and exact rationals#
rational_from_float#
api::analysis::Session method
pub fn rational_from_float(
&self,
value: f64,
maximum_denominator: u64,
) -> Result<Expression, ApiError>Closest rational with denominator max_denominator (the
Fraction.limit_denominator algorithm). Raises on non-finite input.
Example#
Values of a constant, a definite integral, and a sum, and an estimate that has to be asked for.
use symi::api::prelude::*;
use symi::api::{NumericAccuracyPolicy, NumericOptions};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let session = Session::new();
let x = session.symbol("x");
println!("{}", session.evaluate_numeric(&session.pi(), NumericOptions::new(30))?);
let integrand = session.parse("exp(-x^3)")?;
let zero = session.integer(0);
let one = session.integer(1);
println!(
"{}",
session.integrate_definite_numeric(&integrand, &x, &zero, &one, NumericOptions::new(20))?
);
let summand = session.parse("(-1)^(k+1)/k")?;
println!(
"{}",
session.summation_numeric(&summand, "k", &one, &session.infinity(), NumericOptions::new(20))?
);
let bessel = session.parse("bessel_j(0, 3)")?;
let estimates = NumericOptions::new(15).with_accuracy(NumericAccuracyPolicy::EstimatedAllowed);
println!("{}", session.evaluate_numeric(&bessel, estimates)?.summary());
Ok(())
}Additional API#
evaluate_matrix_numeric#
api::numeric::Session method
pub fn evaluate_matrix_numeric(
&self,
matrix: &Matrix,
options: NumericOptions,
) -> Result<NumericMatrix, ApiError>Evaluate every entry of a matrix numerically; the first entry that declines makes the whole evaluation decline.
api::numeric#
api module
pub mod numeric;Explicitly requested numeric evaluation: numeric values, their options, and their reports.
api::numeric_functions#
api module
pub mod numeric_functions;Portable binary64 functions compiled once from exact scalar expressions.
api::polynomial_roots#
api module
pub mod polynomial_roots;Explicitly requested certified numerical roots of a polynomial in one variable.
api::root_finding#
api module
pub mod root_finding;Explicitly requested numerical root finding from a start point or in a bracket.
BulkNumericOutcome#
api re_export
pub use numeric::BulkNumericOutcome;One ordered result of evaluate_numeric_bulk.
BulkNumericOutcome.diagnostic#
api::numeric::BulkNumericOutcome method
pub fn diagnostic(&self) -> Option<Diagnostic>The diagnostic, when the element did not evaluate.
BulkNumericOutcome.index#
api::numeric::BulkNumericOutcome method
pub fn index(&self) -> usizeThe original input position.
BulkNumericOutcome.value#
api::numeric::BulkNumericOutcome method
pub fn value(&self) -> Option<NumericValue>The numeric value, when the element evaluated.
DEFAULT_SIGNIFICANT_DIGITS#
api::numeric constant
pub const DEFAULT_SIGNIFICANT_DIGITS: u32 = core_value::DEFAULT_SIGNIFICANT_DIGITS;The number of significant digits a numeric request uses when none is given.
NumericAccuracy#
api re_export
pub use numeric::NumericAccuracy;What is known about the error of a numeric value.
NumericAccuracy.Certified#
api::numeric::NumericAccuracy variant
Certified,Each radius is a proved bound: the true value lies within it.
NumericAccuracy.Estimated#
api::numeric::NumericAccuracy variant
Estimated,Each radius is an estimate of the error, not a bound.
NumericAccuracy.name#
api::numeric::NumericAccuracy method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.
NumericAccuracyPolicy#
api re_export
pub use numeric::NumericAccuracyPolicy;Which kinds of result an explicit numeric request accepts.
NumericAccuracyPolicy.Certified#
api::numeric::NumericAccuracyPolicy variant
Certified,Only certified values, whose every printed digit is proved; the default.
NumericAccuracyPolicy.EstimatedAllowed#
api::numeric::NumericAccuracyPolicy variant
EstimatedAllowed,Certified values where a certified kernel exists, and estimated values otherwise.
NumericAccuracyPolicy.from_name#
api::numeric::NumericAccuracyPolicy method
pub fn from_name(name: &str) -> Result<Self, ApiError>The policy with this spelling.
NumericAccuracyPolicy.name#
api::numeric::NumericAccuracyPolicy method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.
NumericDeclineError#
api re_export
pub use numeric::NumericDeclineError;The error of an explicit numeric request that produced no value.
NumericDeclineError.message#
api::numeric::NumericDeclineError method
pub fn message(&self) -> &strThe explanation, including any hint on how to obtain a value.
NumericDeclineError.reason#
api::numeric::NumericDeclineError method
pub fn reason(&self) -> NumericDeclineReasonWhy no value was produced.
NumericDeclineReason#
api re_export
pub use numeric::NumericDeclineReason;Why an explicit numeric request produced no value.
NumericDeclineReason.BranchSideUndecided#
api::numeric::NumericDeclineReason variant
BranchSideUndecided,An argument stays on a branch cut at every precision and its side was not decided exactly.
NumericDeclineReason.DiscontinuityUndecided#
api::numeric::NumericDeclineReason variant
DiscontinuityUndecided,An argument stays on a jump or an undecidable condition at every precision.
NumericDeclineReason.EstimateUnavailable#
api::numeric::NumericDeclineReason variant
EstimateUnavailable,Estimates were allowed, but no estimate was accepted.
NumericDeclineReason.EstimatedSubstitution#
api::numeric::NumericDeclineReason variant
EstimatedSubstitution,An estimated value was bound to a symbol of a certified request.
NumericDeclineReason.IntegralNotCertified#
api::numeric::NumericDeclineReason variant
IntegralNotCertified,A definite integral could not be certified; estimates must be allowed explicitly.
NumericDeclineReason.MagnitudeBelowResolution#
api::numeric::NumericDeclineReason variant
MagnitudeBelowResolution,A component could not be separated from zero and was not proved to be zero.
NumericDeclineReason.NoCertifiedKernel#
api::numeric::NumericDeclineReason variant
NoCertifiedKernel,A head has no certified kernel for its arguments; estimates must be allowed explicitly.
NumericDeclineReason.NotANumber#
api::numeric::NumericDeclineReason variant
NotANumber,The expression does not denote a number.
NumericDeclineReason.NotExactlyReal#
api::numeric::NumericDeclineReason variant
NotExactlyReal,A real result was asked of a value not known to be exactly real.
NumericDeclineReason.OutsideDomain#
api::numeric::NumericDeclineReason variant
OutsideDomain,An argument lies outside the set on which its function is defined.
NumericDeclineReason.PrecisionExhausted#
api::numeric::NumericDeclineReason variant
PrecisionExhausted,The precision cap or work budget was reached before the digits were certified.
NumericDeclineReason.ResourceLimit#
api::numeric::NumericDeclineReason variant
ResourceLimit,A number left the representable range of the arithmetic.
NumericDeclineReason.SeriesDivergent#
api::numeric::NumericDeclineReason variant
SeriesDivergent,A sum is proved divergent.
NumericDeclineReason.Singularity#
api::numeric::NumericDeclineReason variant
Singularity,The expression is evaluated exactly at a pole, branch point, or logarithmic singularity.
NumericDeclineReason.SingularityUndecided#
api::numeric::NumericDeclineReason variant
SingularityUndecided,An argument stays on a pole or branch point at every precision and no exact decision placed it.
NumericDeclineReason.SubstitutionAssumptionUndecided#
api::numeric::NumericDeclineReason variant
SubstitutionAssumptionUndecided,Whether a bound value satisfies the assumptions declared on its symbol is undecided.
NumericDeclineReason.SubstitutionViolatesAssumption#
api::numeric::NumericDeclineReason variant
SubstitutionViolatesAssumption,A bound value provably violates an assumption declared on its symbol.
NumericDeclineReason.SummationNotCertified#
api::numeric::NumericDeclineReason variant
SummationNotCertified,A sum could not be certified; estimates must be allowed explicitly.
NumericDeclineReason.UnboundSymbol#
api::numeric::NumericDeclineReason variant
UnboundSymbol,A free symbol of the expression has no bound value.
NumericDeclineReason.UnsupportedDeferredForm#
api::numeric::NumericDeclineReason variant
UnsupportedDeferredForm,The expression contains a deferred form that is not evaluated numerically.
NumericDeclineReason.name#
api::numeric::NumericDeclineReason method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.
NumericEvaluationStatus#
api re_export
pub use numeric::NumericEvaluationStatus;Whether a numeric evaluation produced a value.
NumericEvaluationStatus.Declined#
api::numeric::NumericEvaluationStatus variant
Declined,No value was produced; the report says why.
NumericEvaluationStatus.Evaluated#
api::numeric::NumericEvaluationStatus variant
Evaluated,A value was produced.
NumericEvaluationStatus.name#
api::numeric::NumericEvaluationStatus method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.
NumericFunctionDefinedness#
api re_export
pub use numeric_functions::NumericFunctionDefinedness;Public re_export placement for NumericFunctionDefinedness.
Calling forms
api::numeric_functions re_export: api::numeric_functions::NumericFunctionDefinedness
pub use interval_evaluation::NumericFunctionDefinedness;Type: api::numeric_functions::interval_evaluation::NumericFunctionDefinedness
pub enum NumericFunctionDefinednessNumericFunctionDefinedness.Everywhere#
api::numeric_functions::interval_evaluation::NumericFunctionDefinedness variant
Everywhere,The output is proved real at every point of the box.
NumericFunctionDefinedness.Nowhere#
api::numeric_functions::interval_evaluation::NumericFunctionDefinedness variant
Nowhere,The output is proved real at no point of the box.
NumericFunctionDefinedness.Somewhere#
api::numeric_functions::interval_evaluation::NumericFunctionDefinedness variant
Somewhere,The output is proved real at some point of the box and proved not real at another.
NumericFunctionDefinedness.Unknown#
api::numeric_functions::interval_evaluation::NumericFunctionDefinedness variant
Unknown,None of the other three was proved.
NumericFunctionDefinedness.name#
api::numeric_functions::interval_evaluation::NumericFunctionDefinedness method
pub fn name(self) -> &'static strReturns the stable lowercase spelling used by host records.
NumericFunctionDomain#
api re_export
pub use numeric_functions::NumericFunctionDomain;The input and result domain a compiled numeric function accepts.
NumericFunctionDomain.Complex#
api::numeric_functions::NumericFunctionDomain variant
Complex,Arguments and results use principal complex binary64 arithmetic.
NumericFunctionDomain.Real#
api::numeric_functions::NumericFunctionDomain variant
Real,Every argument and every successful result must be real.
NumericFunctionDomain.from_name#
api::numeric_functions::NumericFunctionDomain method
pub fn from_name(name: &str) -> Result<Self, ApiError>Reads a domain from its stable lowercase spelling.
NumericFunctionDomain.name#
api::numeric_functions::NumericFunctionDomain method
pub fn name(self) -> &'static strReturns the stable lowercase spelling used by host bindings.
NumericFunctionFailurePath#
api re_export
pub use numeric_functions::NumericFunctionFailurePath;Where in its output the failure of one output of a detailed evaluation arose.
Calling forms
Type: api::numeric_functions::NumericFunctionFailurePath
pub struct NumericFunctionFailurePathNumericFunctionFailurePath.output#
api::numeric_functions::NumericFunctionFailurePath field
pub output:The flat position of the output.
NumericFunctionFailurePath.path#
api::numeric_functions::NumericFunctionFailurePath field
pub path:The child indices from the output's root node to the node that failed.
NumericFunctionOutput#
api re_export
pub use numeric_functions::NumericFunctionOutput;One output of a detailed machine evaluation.
NumericFunctionOutput.diagnostics#
api::numeric_functions::NumericFunctionOutput field
pub diagnostics:The output's non-certifying machine diagnostics.
NumericFunctionOutput.failure_path#
api::numeric_functions::NumericFunctionOutput field
pub failure_path:The node the failure arose at, for a status an operation of the output produced: the first operation, in canonical dependency order within the region the point executed, whose own computation failed; a selection none of whose branches applies; or, for non_real, the first operation along non-real operands whose value left the real line. None for an evaluated output and for a status decided before any operation, from a captured requirement or a derivative's differentiability condition.
NumericFunctionOutput.status#
api::numeric_functions::NumericFunctionOutput field
pub status:Whether this output succeeded or why it did not.
NumericFunctionOutput.value#
api::numeric_functions::NumericFunctionOutput field
pub value:The binary64 result when this output succeeded.
NumericFunctionOutputStatus#
api re_export
pub use numeric_functions::NumericFunctionOutputStatus;The status of one output of a detailed machine evaluation.
Calling forms
Type: api::numeric_functions::NumericFunctionOutputStatus
pub enum NumericFunctionOutputStatusNumericFunctionOutputStatus.AssumptionViolated#
api::numeric_functions::NumericFunctionOutputStatus variant
AssumptionViolated,The exact binary64 inputs violate requirements captured at compilation.
NumericFunctionOutputStatus.DerivativeNotEstablished#
api::numeric_functions::NumericFunctionOutputStatus variant
DerivativeNotEstablished,The output is a derivative, and the condition under which its formula is the derivative was not proved at the exact inputs. This is not a proof that the derivative does not exist there.
NumericFunctionOutputStatus.DomainError#
api::numeric_functions::NumericFunctionOutputStatus variant
DomainError,The exact operand of a selected operation lies outside the operation's domain, as a non-integer argument of a function defined only at integers does.
NumericFunctionOutputStatus.Evaluated#
api::numeric_functions::NumericFunctionOutputStatus variant
Evaluated,The output has a binary64 machine value.
NumericFunctionOutputStatus.InconsistentProgram#
api::numeric_functions::NumericFunctionOutputStatus variant
InconsistentProgram,The validated instruction stream was internally inconsistent.
NumericFunctionOutputStatus.InvalidArithmetic#
api::numeric_functions::NumericFunctionOutputStatus variant
InvalidArithmetic,The machine operation produced NaN.
NumericFunctionOutputStatus.InvalidInput#
api::numeric_functions::NumericFunctionOutputStatus variant
InvalidInput,The point supplied NaN, infinity, or a non-real value to a real function.
NumericFunctionOutputStatus.KernelUnavailable#
api::numeric_functions::NumericFunctionOutputStatus variant
KernelUnavailable,A certified bridge declined for these operands: its kernel has no certified value there, or none that determines a binary64 number within its precision and resource limits.
NumericFunctionOutputStatus.NoMatchingBranch#
api::numeric_functions::NumericFunctionOutputStatus variant
NoMatchingBranch,Every condition of a piecewise value the output selects is false at the exact inputs, so no branch applies.
NumericFunctionOutputStatus.NonReal#
api::numeric_functions::NumericFunctionOutputStatus variant
NonReal,A real-only operation or output had a non-real value.
NumericFunctionOutputStatus.Overflow#
api::numeric_functions::NumericFunctionOutputStatus variant
Overflow,An intermediate exceeded binary64 range.
NumericFunctionOutputStatus.Pole#
api::numeric_functions::NumericFunctionOutputStatus variant
Pole,The expression has a pole at the exact inputs: the exact operands of a selected operation are at one of its poles.
NumericFunctionOutputStatus.RoundingFailure#
api::numeric_functions::NumericFunctionOutputStatus variant
RoundingFailure,A rounded operand reached a pole or a branch cut of a selected operation that the exact operand avoids, so binary64 arithmetic gives no value there although the exact expression has one.
NumericFunctionOutputStatus.UndecidedAssumption#
api::numeric_functions::NumericFunctionOutputStatus variant
UndecidedAssumption,Captured requirements could not be proved or disproved at the exact binary64 inputs.
NumericFunctionOutputStatus.UndecidedCondition#
api::numeric_functions::NumericFunctionOutputStatus variant
UndecidedCondition,A branch condition, the jump of a floor, ceiling, signum, or Heaviside step, or whether an operand is at a pole or on a branch cut could not be decided at the exact inputs within the precision limit of the semantic guards.
NumericFunctionOutputStatus.UnsupportedKernel#
api::numeric_functions::NumericFunctionOutputStatus variant
UnsupportedKernel,The compiled program has no portable kernel for the selected instruction.
NumericFunctionOutputStatus.code#
api::numeric_functions::NumericFunctionOutputStatus method
pub fn code(self) -> u8Returns the stable small integer that stands for this status in a compact status buffer: evaluated is zero and every other status is nonzero.
NumericFunctionOutputStatus.name#
api::numeric_functions::NumericFunctionOutputStatus method
pub fn name(self) -> &'static strReturns the stable lowercase spelling used by host batch records.
NumericPolynomialRootsDeclineReason#
api re_export
pub use polynomial_roots::NumericPolynomialRootsDeclineReason;Why a numerical polynomial root request returned no roots.
Calling forms
Type: api::polynomial_roots::NumericPolynomialRootsDeclineReason
pub enum NumericPolynomialRootsDeclineReasonNumericPolynomialRootsDeclineReason.BudgetExhausted#
api::polynomial_roots::NumericPolynomialRootsDeclineReason variant
BudgetExhausted,The iteration budget ran out.
NumericPolynomialRootsDeclineReason.CoefficientNotANumber#
api::polynomial_roots::NumericPolynomialRootsDeclineReason variant
CoefficientNotANumber,A coefficient is not a finite number.
NumericPolynomialRootsDeclineReason.ConstantPolynomial#
api::polynomial_roots::NumericPolynomialRootsDeclineReason variant
ConstantPolynomial,The polynomial is a nonzero constant, so it has no roots.
NumericPolynomialRootsDeclineReason.DegreeUndecided#
api::polynomial_roots::NumericPolynomialRootsDeclineReason variant
DegreeUndecided,Whether the leading coefficient is zero could not be decided.
NumericPolynomialRootsDeclineReason.MultiplicityUndecided#
api::polynomial_roots::NumericPolynomialRootsDeclineReason variant
MultiplicityUndecided,A zero decision that the multiplicities depend on could not be made.
NumericPolynomialRootsDeclineReason.NoCertifiedKernel#
api::polynomial_roots::NumericPolynomialRootsDeclineReason variant
NoCertifiedKernel,A coefficient has a head with no certified kernel.
NumericPolynomialRootsDeclineReason.NotAPolynomial#
api::polynomial_roots::NumericPolynomialRootsDeclineReason variant
NotAPolynomial,The expression is not a polynomial in the variable.
NumericPolynomialRootsDeclineReason.PrecisionExhausted#
api::polynomial_roots::NumericPolynomialRootsDeclineReason variant
PrecisionExhausted,The roots were not separated to the requested digits within the precision cap.
NumericPolynomialRootsDeclineReason.UnboundSymbol#
api::polynomial_roots::NumericPolynomialRootsDeclineReason variant
UnboundSymbol,A coefficient mentions a symbol other than the variable.
NumericPolynomialRootsDeclineReason.ZeroPolynomial#
api::polynomial_roots::NumericPolynomialRootsDeclineReason variant
ZeroPolynomial,The polynomial is zero, so every number is a root.
NumericPolynomialRootsDeclineReason.name#
api::polynomial_roots::NumericPolynomialRootsDeclineReason method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.
NumericPolynomialRootsStatus#
api re_export
pub use polynomial_roots::NumericPolynomialRootsStatus;What a numerical polynomial root request returned.
Calling forms
Type: api::polynomial_roots::NumericPolynomialRootsStatus
pub enum NumericPolynomialRootsStatusNumericPolynomialRootsStatus.Certified#
api::polynomial_roots::NumericPolynomialRootsStatus variant
Certified,Every root is listed with its exact multiplicity, and every value is certified to the requested digits.
NumericPolynomialRootsStatus.Declined#
api::polynomial_roots::NumericPolynomialRootsStatus variant
Declined,No roots were returned.
NumericPolynomialRootsStatus.name#
api::polynomial_roots::NumericPolynomialRootsStatus method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.
NumericRootCoverage#
api re_export
pub use results::NumericRootCoverage;How much of the requested domain a certified numerical root search accounted for.
NumericRootCoverage.Partial#
api::results::NumericRootCoverage variant
Partial,Regions remain where the search could neither find nor exclude a root.
NumericRootCoverage.RequestedInterval#
api::results::NumericRootCoverage variant
RequestedInterval,Every real root inside the requested interval is among the enclosures.
NumericRootCoverage.WholeRealLine#
api::results::NumericRootCoverage variant
WholeRealLine,Every real root of the expression is among the enclosures, over the whole real line.
NumericRootCoverage.name#
api::results::NumericRootCoverage method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.
NumericRootEnclosureStatus#
api re_export
pub use results::NumericRootEnclosureStatus;What a certified numerical root search proved about the roots inside one enclosure.
NumericRootEnclosureStatus.ExactRationalRoot#
api::results::NumericRootEnclosureStatus variant
ExactRationalRoot,The enclosure is a single point at which the expression is exactly zero.
NumericRootEnclosureStatus.ExactlyOneRoot#
api::results::NumericRootEnclosureStatus variant
ExactlyOneRoot,The enclosure holds exactly one root, proved by a sign change across a monotone stretch.
NumericRootEnclosureStatus.name#
api::results::NumericRootEnclosureStatus method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.
NumericRootFindingDeclineReason#
api re_export
pub use root_finding::NumericRootFindingDeclineReason;Why a numerical root-finding request returned no root.
Calling forms
Type: api::root_finding::NumericRootFindingDeclineReason
pub enum NumericRootFindingDeclineReasonNumericRootFindingDeclineReason.AssumptionUndecided#
api::root_finding::NumericRootFindingDeclineReason variant
AssumptionUndecided,Whether the root satisfies the assumptions declared on a variable is undecided.
NumericRootFindingDeclineReason.BracketHasNoSignChange#
api::root_finding::NumericRootFindingDeclineReason variant
BracketHasNoSignChange,The bracket's endpoint values are not certified to have opposite signs.
NumericRootFindingDeclineReason.BudgetExhausted#
api::root_finding::NumericRootFindingDeclineReason variant
BudgetExhausted,The step budget or the precision cap ran out.
NumericRootFindingDeclineReason.CertificationFailed#
api::root_finding::NumericRootFindingDeclineReason variant
CertificationFailed,The iteration converged but no root was proved, as at a multiple root.
NumericRootFindingDeclineReason.ContinuityUndecided#
api::root_finding::NumericRootFindingDeclineReason variant
ContinuityUndecided,Continuity of the equation over the bracket could not be established.
NumericRootFindingDeclineReason.EvaluationFailedAtIterate#
api::root_finding::NumericRootFindingDeclineReason variant
EvaluationFailedAtIterate,The equations could not be evaluated at the start or at an iterate.
NumericRootFindingDeclineReason.InvalidStart#
api::root_finding::NumericRootFindingDeclineReason variant
InvalidStart,The start point or bracket is unusable.
NumericRootFindingDeclineReason.LeftDomain#
api::root_finding::NumericRootFindingDeclineReason variant
LeftDomain,A real-domain iterate or value left the real numbers, or the root violates a declared assumption.
NumericRootFindingDeclineReason.MethodNotApplicable#
api::root_finding::NumericRootFindingDeclineReason variant
MethodNotApplicable,The method does not apply to this request.
NumericRootFindingDeclineReason.NoCertifiedKernel#
api::root_finding::NumericRootFindingDeclineReason variant
NoCertifiedKernel,A head has no certified kernel.
NumericRootFindingDeclineReason.NoConvergence#
api::root_finding::NumericRootFindingDeclineReason variant
NoConvergence,The iteration did not converge.
NumericRootFindingDeclineReason.NotComplexDifferentiable#
api::root_finding::NumericRootFindingDeclineReason variant
NotComplexDifferentiable,A head of the equations is not complex-differentiable, so the complex domain does not apply.
NumericRootFindingDeclineReason.SingularJacobian#
api::root_finding::NumericRootFindingDeclineReason variant
SingularJacobian,The Jacobian is singular at an iterate.
NumericRootFindingDeclineReason.SystemNotSquare#
api::root_finding::NumericRootFindingDeclineReason variant
SystemNotSquare,The number of equations differs from the number of variables, or is zero.
NumericRootFindingDeclineReason.UnboundSymbol#
api::root_finding::NumericRootFindingDeclineReason variant
UnboundSymbol,A symbol of the equations is not one of the variables.
NumericRootFindingDeclineReason.name#
api::root_finding::NumericRootFindingDeclineReason method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.
NumericRootFindingDomain#
api re_export
pub use root_finding::NumericRootFindingDomain;Where a numerical root is sought.
NumericRootFindingDomain.Automatic#
api::root_finding::NumericRootFindingDomain variant
Automatic,The real numbers when every variable is declared real (a positive or negative variable counts, since a root is finite), and the complex numbers otherwise.
NumericRootFindingDomain.Complex#
api::root_finding::NumericRootFindingDomain variant
Complex,Complex roots of complex-differentiable equations.
NumericRootFindingDomain.Real#
api::root_finding::NumericRootFindingDomain variant
Real,Real roots only; every value of the equations must be real along the way.
NumericRootFindingDomain.from_name#
api::root_finding::NumericRootFindingDomain method
pub fn from_name(name: &str) -> Result<Self, ApiError>The domain with this spelling.
NumericRootFindingDomain.name#
api::root_finding::NumericRootFindingDomain method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.
NumericRootFindingMethod#
api re_export
pub use root_finding::NumericRootFindingMethod;The iteration that locates a numerical root.
NumericRootFindingMethod.Automatic#
api::root_finding::NumericRootFindingMethod variant
Automatic,Newton's method when the Jacobian can be evaluated and Broyden's method otherwise; for one complex equation from a real start, Muller's method when Newton's method stalls. In a bracket, ITP bracketing.
NumericRootFindingMethod.Bracketing#
api::root_finding::NumericRootFindingMethod variant
Bracketing,ITP bracketing in a sign-changing real bracket.
NumericRootFindingMethod.Muller#
api::root_finding::NumericRootFindingMethod variant
Muller,Muller's method, for one equation in the complex domain.
NumericRootFindingMethod.Newton#
api::root_finding::NumericRootFindingMethod variant
Newton,Damped Newton iteration with the exact symbolic Jacobian.
NumericRootFindingMethod.Secant#
api::root_finding::NumericRootFindingMethod variant
Secant,The secant method in one variable and Broyden's method in several.
NumericRootFindingMethod.from_name#
api::root_finding::NumericRootFindingMethod method
pub fn from_name(name: &str) -> Result<Self, ApiError>The method with this spelling.
NumericRootFindingMethod.name#
api::root_finding::NumericRootFindingMethod method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.
NumericRootFindingStatus#
api re_export
pub use root_finding::NumericRootFindingStatus;What a numerical root-finding request returned.
NumericRootFindingStatus.Certified#
api::root_finding::NumericRootFindingStatus variant
Certified,Every value encloses a root, and every requested digit is faithful.
NumericRootFindingStatus.ConvergedUncertified#
api::root_finding::NumericRootFindingStatus variant
ConvergedUncertified,The iteration converged without a proof; the values are estimates, returned only when estimates were allowed.
NumericRootFindingStatus.Declined#
api::root_finding::NumericRootFindingStatus variant
Declined,No root was returned.
NumericRootFindingStatus.name#
api::root_finding::NumericRootFindingStatus method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.
NumericRootIsolationDeclineReason#
api re_export
pub use results::NumericRootIsolationDeclineReason;Why a certified numerical root search produced no report.
Calling forms
Type: api::results::NumericRootIsolationDeclineReason
pub enum NumericRootIsolationDeclineReasonNumericRootIsolationDeclineReason.DomainEmpty#
api::results::NumericRootIsolationDeclineReason variant
DomainEmpty,The requested interval admits no value.
NumericRootIsolationDeclineReason.DomainNotExactlyRational#
api::results::NumericRootIsolationDeclineReason variant
DomainNotExactlyRational,A requested endpoint named neither an exact rational nor an infinity.
NumericRootIsolationDeclineReason.ExpressionIdenticallyZero#
api::results::NumericRootIsolationDeclineReason variant
ExpressionIdenticallyZero,The expression vanishes identically, so its roots are not isolated points.
NumericRootIsolationDeclineReason.PrimitiveNotCertified#
api::results::NumericRootIsolationDeclineReason variant
PrimitiveNotCertified,Some head of the expression has no certified enclosure.
NumericRootIsolationDeclineReason.UnboundedDomainNotSupported#
api::results::NumericRootIsolationDeclineReason variant
UnboundedDomainNotSupported,A search over the whole real line needs a shape whose roots can be counted completely.
NumericRootIsolationDeclineReason.name#
api::results::NumericRootIsolationDeclineReason method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.
NumericRootIsolationVerdict#
api re_export
pub use results::NumericRootIsolationVerdict;Whether a certified numerical root search ran or declined.
NumericRootIsolationVerdict.Declined#
api::results::NumericRootIsolationVerdict variant
Declined,The search did not run.
NumericRootIsolationVerdict.Isolated#
api::results::NumericRootIsolationVerdict variant
Isolated,The search ran and produced certified enclosures.
NumericRootIsolationVerdict.name#
api::results::NumericRootIsolationVerdict method
pub fn name(&self) -> &'static strThe stable lowercase spelling shared by every binding.