apn.mojo v1.0.1
Search /
API reference

apn_mojo.ball

Use a Ball to carry guaranteed bounds through a real-valued calculation. It stores an interval as a midpoint and a nonnegative radius. Every operation includes all possible results for the input intervals, even after rounding; the bounds may be wider than the smallest possible interval.

Start with calculations with guaranteed bounds for a measurement example, comparisons, and certified conversion to Float.

Balls: midpoint-radius intervals that contain every value they stand for.

Every function is scalar, one declaration per name, and returns a ball that contains the exact result for every point of its inputs. Operands may be balls or exact numbers. A context= (BallContext) sets the result precision.

Summary

Name Kind Summary
abs function The ball of abs(value).
acos function The ball of the arccosine.
acosh function The ball of the inverse hyperbolic cosine.
add function The ball of left + right.
add_error function The ball with abs(error) added to its radius.
asin function The ball of the arcsine.
asinh function The ball of the inverse hyperbolic sine.
atan function The ball of the arctangent.
atan2 function The ball of the angle of x + i y, in [-pi, pi].
atanh function The ball of the inverse hyperbolic tangent.
beta function The ball of Euler's beta function, Gamma(a) Gamma(b) / Gamma(a + b), with scipy's values at the poles.
betainc function The ball of the regularized incomplete beta function I_x(a, b), from its values at the corners of the balls, since it is monotone in each argument.
betaln function The ball of log |B(a, b)|.
bits_to_digits function Decimal digits of a precision in bits: bits * log10(2), enclosed.
canonical function The canonical ball, at precision bits, of the value that ball encloses, when ball is narrow enough to decide it.
catalan_ball function The canonical ball of Catalan's constant.
ceil_if_certain function The ceiling, when it is the same for every point of the ball.
clip function The ball of value limited to [a_min, a_max], minimum(maximum(value, a_min), a_max) (numpy's clip).
compare function How two balls compare, decided on their exact ends.
contains function Whether an exact number lies in the ball, decided exactly.
contains_ball function Whether inner lies within outer.
contains_integer function Whether some integer lies in the ball.
contains_zero function Whether 0 lies in the ball.
cos function The ball of the cosine.
cosh function The ball of the hyperbolic cosine.
digamma function The ball of the digamma function, Gamma'/Gamma.
digits_to_bits function Bits of a precision in decimal digits: digits * log2(10), enclosed.
divide function The ball of left / right.
erf function The ball of the error function.
erfc function The ball of the complementary error function, 1 - erf, without its cancellation.
erfi function The ball of the imaginary error function, -i erf(ix).
erfinv function The ball of the inverse error function, for a ball inside (-1, 1).
euler_e_ball function The canonical ball of e.
euler_gamma_ball function The canonical ball of Euler's gamma.
exp function The ball of the exponential.
exp2 function The ball of 2**x.
expi function The ball of the exponential integral Ei, the principal value for x < 0.
expm1 function The ball of exp(x) - 1.
floor_if_certain function The floor, when it is the same for every point of the ball.
fma function The ball of a * b + c, with the midpoint rounded once.
fresnel function The balls of Fresnel's integrals (S(x), C(x)), int_0^x sin(pi t**2 / 2) dt and int_0^x cos(pi t**2 / 2) dt.
gamma function The ball of euler's Gamma function.
gammainc function The ball of the regularized lower incomplete gamma function P(a, x), from its values at the corners of the balls, since it is monotone in each argument.
gammaincc function The ball of the regularized upper incomplete gamma function Q(a, x), from its values at the corners of the balls, since it is monotone in each argument.
gammaln function The ball of the logarithm of Gamma, for x > 0.
hyp1f1 function The ball of Kummer's confluent hypergeometric function M(a, b, x).
hyp2f1 function The ball of Gauss's hypergeometric function F(a, b; c; x).
intersection function The least ball at the precision that contains the common points.
lambertw function The ball of Lambert's W on branch 0 or -1.
ldexp function The ball of value * 2**exponent, scaled exactly.
ln2_ball function The canonical ball of ln 2.
log function The ball of the natural logarithm.
log10 function The ball of the base-10 logarithm.
log1p function The ball of log(1 + x).
log2 function The ball of the base-2 logarithm.
log2_10_ball function The canonical ball of log2(10).
log_ndtr function The ball of the logarithm of the standard normal distribution function.
maximum function The ball of max(s, t) over all points of the two balls (numpy's maximum).
minimum function The ball of min(s, t) over all points of the two balls (numpy's minimum).
multiply function The ball of left * right.
ndtr function The ball of the standard normal distribution function, (1 + erf(x/sqrt 2)) / 2.
ndtri function The ball of the inverse standard normal distribution function, for a ball inside (0, 1).
overlaps function Whether the balls share a point.
pi_ball function The canonical ball of pi.
poch function The ball of the Pochhammer symbol Gamma(z + m) / Gamma(z), with scipy's values at the poles.
polygamma function The ball of the polygamma function of order n.
pow function The ball of base**exponent.
pow_int function The ball of value**exponent for an integer exponent.
propagation_bound function The propagation term P_f(m, r) of the ball function f (Appendix E.11): the bound a ball [m +/- r] adds to the radius of f's kernel at m, rounded up to the 30-bit radius format.
radius_for_relative_digits function The radius of digits decimal digits of relative precision, |midpoint| * 10**-digits, rounded up to the 30-bit radius format.
reciprocal function The ball of 1 / value.
rootn function The ball of the real n-th root, n >= 1.
round_half_even_if_certain function The nearest integer (ties to even), when it is the same for every point.
round_midpoint function The ball with its midpoint rounded to precision bits, the rounding error added to the radius.
shichi function The balls of the hyperbolic sine and cosine integrals (Shi(x), Chi(x)); Chi is defined for x > 0.
sici function The balls of the sine and cosine integrals (Si(x), Ci(x)); Ci is defined for x > 0.
simplest_rational_in function The simplest rational in the ball: the least denominator, and among those the least absolute numerator.
sin function The ball of the sine.
sin_cos function The balls of the sine and the cosine.
sinh function The ball of the hyperbolic sine.
split function The two halves [m - r/2 +/- r/2] and [m + r/2 +/- r/2].
sqrt function The ball of the square root.
square function The ball of value**2.
stable_hash function A 64-bit hash of the representation, stable across processes and releases.
subtract function The ball of left - right.
tan function The ball of the tangent.
tanh function The ball of the hyperbolic tangent.
to_float_if_certain function The Float that every point of the ball rounds to, when there is one.
trim function The ball with its midpoint rounded to the bits its radius leaves meaningful: the relative accuracy plus 8, never more than it has.
union function The least ball at the precision that contains both.
zeta function The ball of the Hurwitz zeta function; zeta(x, 1) is the Riemann zeta function.
Ball struct A real ball [m +/- r]: every real number within r of m.
BallContext struct The working precision of a ball result, and the budget of functions whose cost depends on their input.
BallOrder struct How two balls compare: one of five named constants.

Functions

abs

Source: apn_mojo/ball/math.mojo

def abs(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of abs(value).

Arguments

  • value (_BallArgument): The operand.
  • context (Optional[BallContext]): The result precision; by default the operand's.

Returns

Ball: The operand or its negation away from 0, otherwise [0, upper].

Raises

Error: Only on an invalid precision or a checked size error.

acos

Source: apn_mojo/ball/elementary.mojo

def acos(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the arccosine.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the arccosine of every point; indeterminate unless the ball is within [-1, 1].

Raises

Error: Only on an invalid precision or a checked size error.

acosh

Source: apn_mojo/ball/elementary.mojo

def acosh(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the inverse hyperbolic cosine.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing acosh of every point; indeterminate unless the ball is at least 1.

Raises

Error: Only on an invalid precision or a checked size error.

add

Source: apn_mojo/ball/math.mojo

def add(
    left: _BallArgument,
    right: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of left + right.

Arguments

  • left (_BallArgument): The first operand.
  • right (_BallArgument): The second operand.
  • context (Optional[BallContext]): The result precision; by default the operands'.

Returns

Ball: A ball containing every sum; unbounded if an operand is.

Raises

Error: Only on an invalid precision or a checked size error.

add_error

Source: apn_mojo/ball/math.mojo

def add_error(value: Ball, error: _FloatArgument) raises -> Ball

The ball with abs(error) added to its radius.

Arguments

  • value (Ball): The ball.
  • error (_FloatArgument): An exact number or a Float bound.

Returns

Ball: A wider ball; unbounded for an infinite error, indeterminate for NaN.

Raises

Error: Only on a checked size error.

asin

Source: apn_mojo/ball/elementary.mojo

def asin(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the arcsine.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the arcsine of every point; indeterminate unless the ball is within [-1, 1].

Raises

Error: Only on an invalid precision or a checked size error.

asinh

Source: apn_mojo/ball/elementary.mojo

def asinh(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the inverse hyperbolic sine.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing asinh of every point.

Raises

Error: Only on an invalid precision or a checked size error.

atan

Source: apn_mojo/ball/elementary.mojo

def atan(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the arctangent.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the arctangent of every point.

Raises

Error: Only on an invalid precision or a checked size error.

atan2

Source: apn_mojo/ball/elementary.mojo

def atan2(
    y: _BallArgument,
    x: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the angle of x + i y, in [-pi, pi].

Arguments

  • y (_BallArgument): The ordinate.
  • x (_BallArgument): The abscissa.
  • context (Optional[BallContext]): The result precision; by default the larger operand precision.

Returns

Ball: A ball containing the angle of every point; [0 +/- pi] when the rectangle meets the negative real axis, where the angle jumps, and indeterminate when it contains the origin.

Raises

Error: Only on an invalid precision or a checked size error.

atanh

Source: apn_mojo/ball/elementary.mojo

def atanh(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the inverse hyperbolic tangent.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing atanh of every point; indeterminate unless the ball is within (-1, 1).

Raises

Error: Only on an invalid precision or a checked size error.

beta

Source: apn_mojo/ball/special.mojo

def beta(
    a: _BallArgument,
    b: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of Euler's beta function, Gamma(a) Gamma(b) / Gamma(a + b), with scipy's values at the poles.

Arguments

  • a (_BallArgument): The first argument, a ball or an exact number.
  • b (_BallArgument): The second argument, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the arguments' largest precision.

Returns

Ball: A ball containing the function at every pair of points; indeterminate where it is infinite.

Raises

Error: Only on an invalid precision or a checked size error.

betainc

Source: apn_mojo/ball/special.mojo

def betainc(
    a: _BallArgument,
    b: _BallArgument,
    x: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the regularized incomplete beta function I_x(a, b), from its values at the corners of the balls, since it is monotone in each argument.

Arguments

  • a (_BallArgument): The first shape, a ball or an exact number.
  • b (_BallArgument): The second shape, a ball or an exact number.
  • x (_BallArgument): The argument, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the arguments' largest precision.

Returns

Ball: A ball containing the function at every point of the balls; indeterminate where a ball leaves the domain or both shapes reach 0.

Raises

Error: Only on an invalid precision or a checked size error.

betaln

Source: apn_mojo/ball/special.mojo

def betaln(
    a: _BallArgument,
    b: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of log |B(a, b)|.

Arguments

  • a (_BallArgument): The first argument, a ball or an exact number.
  • b (_BallArgument): The second argument, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the arguments' largest precision.

Returns

Ball: A ball containing the function at every pair of points; indeterminate where it is infinite.

Raises

Error: Only on an invalid precision or a checked size error.

bits_to_digits

Source: apn_mojo/ball/significance.mojo

def bits_to_digits(
    bits: Float,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

Decimal digits of a precision in bits: bits * log10(2), enclosed.

Arguments

  • bits (Float): The precision in bits.
  • context (Optional[BallContext]): The result precision; 128 bits by default.

Returns

Ball: A ball containing bits / log2(10).

Raises

Error: Only on an invalid precision or a checked size error.

canonical

Source: apn_mojo/ball/sets.mojo

def canonical(ball: Ball, precision: Int) raises -> Optional[Ball]

The canonical ball, at precision bits, of the value that ball encloses, when ball is narrow enough to decide it.

The canonical ball is [round_down(v, p), round_up(v, p)] for the enclosed value v: its midpoint is the exact mean of the two ends, at p + 1 bits, and its radius their exact half-width. It depends only on v and p, never on how ball was computed, so a cache of the widest ball serves every narrower request the same: canonical(pi_ball(256), 64) is pi_ball(64).

Arguments

  • ball (Ball): A ball enclosing the value.
  • precision (Int): The precision p of the two ends, at least 1.

Returns

Optional[Ball]: The canonical ball, or None when either end of ball rounds differently from the other in its direction.

Raises

Error: When the precision is invalid.

catalan_ball

Source: apn_mojo/ball/constants.mojo

def catalan_ball(precision: Int = 128) raises -> Ball

The canonical ball of Catalan's constant.

Arguments

  • precision (Int): The precision p of the two ends, in bits.

Returns

Ball: [round_down(G, p), round_up(G, p)], with a midpoint of p + 1 bits.

Raises

Error: When the precision is invalid.

ceil_if_certain

Source: apn_mojo/ball/sets.mojo

def ceil_if_certain(ball: Ball) raises -> Optional[Integer]

The ceiling, when it is the same for every point of the ball.

Arguments

  • ball (Ball): The ball.

Returns

Optional[Integer]: The ceiling, or None when it varies or the ball is not finite.

Raises

Error: Only on a checked size error.

clip

Source: apn_mojo/ball/math.mojo

def clip(
    value: _BallArgument,
    a_min: _BallArgument,
    a_max: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of value limited to [a_min, a_max], minimum(maximum(value, a_min), a_max) (numpy's clip).

Arguments

  • value (_BallArgument): The operand.
  • a_min (_BallArgument): The lower limit.
  • a_max (_BallArgument): The upper limit.
  • context (Optional[BallContext]): The result precision; by default the operands' largest.

Returns

Ball: A ball containing the limited value at every point.

Raises

Error: Only on an invalid precision or a checked size error.

compare

Source: apn_mojo/ball/sets.mojo

def compare(a: Ball, b: Ball) raises -> BallOrder

How two balls compare, decided on their exact ends.

Arguments

  • a (Ball): The first ball.
  • b (Ball): The second ball.

Returns

BallOrder: less or greater when every pair of points agrees, equal for two exact equal balls, overlap otherwise (including any unbounded ball), and undefined when either is indeterminate.

Raises

Error: Only on a checked size error.

contains

Source: apn_mojo/ball/sets.mojo

def contains(ball: Ball, value: _FloatArgument) raises -> Bool

Whether an exact number lies in the ball, decided exactly.

Arguments

  • ball (Ball): The ball.
  • value (_FloatArgument): An Integer, Rational, Float or native number.

Returns

Bool: True when it lies within the ends; always for an indeterminate ball, and for any finite number in an unbounded ball.

Raises

Error: Only on a checked size error.

contains_ball

Source: apn_mojo/ball/sets.mojo

def contains_ball(outer: Ball, inner: Ball) raises -> Bool

Whether inner lies within outer.

Arguments

  • outer (Ball): The containing ball.
  • inner (Ball): The contained ball.

Returns

Bool: True when every point of inner lies in outer; always for an indeterminate outer, never for an indeterminate inner otherwise.

Raises

Error: Only on a checked size error.

contains_integer

Source: apn_mojo/ball/sets.mojo

def contains_integer(ball: Ball) raises -> Bool

Whether some integer lies in the ball.

Arguments

  • ball (Ball): The ball.

Returns

Bool: True when the ends enclose an integer; always unless finite.

Raises

Error: Only on a checked size error.

contains_zero

Source: apn_mojo/ball/sets.mojo

def contains_zero(ball: Ball) raises -> Bool

Whether 0 lies in the ball.

Arguments

  • ball (Ball): The ball.

Returns

Bool: True unless the ball is certainly nonzero.

Raises

Error: Only on a checked size error.

cos

Source: apn_mojo/ball/elementary.mojo

def cos(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the cosine.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the cosine of every point, within [-1, 1]; [0 +/- 1] past the budget.

Raises

Error: Only on an invalid precision or a checked size error.

cosh

Source: apn_mojo/ball/elementary.mojo

def cosh(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the hyperbolic cosine.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing cosh of every point.

Raises

Error: Only on an invalid precision or a checked size error.

digamma

Source: apn_mojo/ball/special.mojo

def digamma(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the digamma function, Gamma'/Gamma.

A ball containing 0 or a negative integer is indeterminate.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the function at every point.

Raises

Error: Only on an invalid precision or a checked size error.

digits_to_bits

Source: apn_mojo/ball/significance.mojo

def digits_to_bits(
    digits: Float,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

Bits of a precision in decimal digits: digits * log2(10), enclosed.

Arguments

  • digits (Float): The precision in decimal digits.
  • context (Optional[BallContext]): The result precision; 128 bits by default.

Returns

Ball: A ball containing digits * log2(10).

Raises

Error: Only on an invalid precision or a checked size error.

divide

Source: apn_mojo/ball/math.mojo

def divide(
    left: _BallArgument,
    right: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of left / right.

Arguments

  • left (_BallArgument): The dividend.
  • right (_BallArgument): The divisor.
  • context (Optional[BallContext]): The result precision; by default the operands'.

Returns

Ball: A ball containing every quotient; indeterminate when the divisor contains 0.

Raises

Error: Only on an invalid precision or a checked size error.

erf

Source: apn_mojo/ball/special.mojo

def erf(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the error function.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the function at every point.

Raises

Error: Only on an invalid precision or a checked size error.

erfc

Source: apn_mojo/ball/special.mojo

def erfc(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the complementary error function, 1 - erf, without its cancellation.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the function at every point.

Raises

Error: Only on an invalid precision or a checked size error.

erfi

Source: apn_mojo/ball/special.mojo

def erfi(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the imaginary error function, -i erf(ix).

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the function at every point.

Raises

Error: Only on an invalid precision or a checked size error.

erfinv

Source: apn_mojo/ball/special.mojo

def erfinv(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the inverse error function, for a ball inside (-1, 1).

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the function at every point; indeterminate unless the ball lies inside (-1, 1).

Raises

Error: Only on an invalid precision or a checked size error.

euler_e_ball

Source: apn_mojo/ball/constants.mojo

def euler_e_ball(precision: Int = 128) raises -> Ball

The canonical ball of e.

Arguments

  • precision (Int): The precision p of the two ends, in bits.

Returns

Ball: [round_down(e, p), round_up(e, p)], with a midpoint of p + 1 bits.

Raises

Error: When the precision is invalid.

euler_gamma_ball

Source: apn_mojo/ball/constants.mojo

def euler_gamma_ball(precision: Int = 128) raises -> Ball

The canonical ball of Euler's gamma.

Arguments

  • precision (Int): The precision p of the two ends, in bits.

Returns

Ball: [round_down(gamma, p), round_up(gamma, p)], with a midpoint of p + 1 bits.

Raises

Error: When the precision is invalid.

exp

Source: apn_mojo/ball/elementary.mojo

def exp(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the exponential.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing exp of every point.

Raises

Error: Only on an invalid precision or a checked size error.

exp2

Source: apn_mojo/ball/elementary.mojo

def exp2(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of 2**x.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing 2**x of every point.

Raises

Error: Only on an invalid precision or a checked size error.

expi

Source: apn_mojo/ball/special.mojo

def expi(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the exponential integral Ei, the principal value for x < 0.

A ball containing 0 is indeterminate.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the function at every point.

Raises

Error: Only on an invalid precision or a checked size error.

expm1

Source: apn_mojo/ball/elementary.mojo

def expm1(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of exp(x) - 1.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing exp(x) - 1 of every point.

Raises

Error: Only on an invalid precision or a checked size error.

floor_if_certain

Source: apn_mojo/ball/sets.mojo

def floor_if_certain(ball: Ball) raises -> Optional[Integer]

The floor, when it is the same for every point of the ball.

Arguments

  • ball (Ball): The ball.

Returns

Optional[Integer]: The floor, or None when it varies or the ball is not finite.

Raises

Error: Only on a checked size error.

fma

Source: apn_mojo/ball/math.mojo

def fma(
    a: _BallArgument,
    b: _BallArgument,
    c: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of a * b + c, with the midpoint rounded once.

Arguments

  • a (_BallArgument): The first factor.
  • b (_BallArgument): The second factor.
  • c (_BallArgument): The addend.
  • context (Optional[BallContext]): The result precision; by default the operands'.

Returns

Ball: A ball containing every result.

Raises

Error: Only on an invalid precision or a checked size error.

fresnel

Source: apn_mojo/ball/special.mojo

def fresnel(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Tuple[Ball, Ball]

The balls of Fresnel's integrals (S(x), C(x)), int_0^x sin(pi t**2 / 2) dt and int_0^x cos(pi t**2 / 2) dt.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Tuple[Ball, Ball]: Two balls, each containing its function at every point.

Raises

Error: Only on an invalid precision or a checked size error.

gamma

Source: apn_mojo/ball/special.mojo

def gamma(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of euler's Gamma function.

A ball containing 0 or a negative integer is indeterminate.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the function at every point.

Raises

Error: Only on an invalid precision or a checked size error.

gammainc

Source: apn_mojo/ball/special.mojo

def gammainc(
    a: _BallArgument,
    x: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the regularized lower incomplete gamma function P(a, x), from its values at the corners of the balls, since it is monotone in each argument.

Arguments

  • a (_BallArgument): The shape, a ball or an exact number.
  • x (_BallArgument): The argument, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the arguments' largest precision.

Returns

Ball: A ball containing the function at every pair of points; indeterminate where a ball reaches below 0 or both reach 0.

Raises

Error: Only on an invalid precision or a checked size error.

gammaincc

Source: apn_mojo/ball/special.mojo

def gammaincc(
    a: _BallArgument,
    x: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the regularized upper incomplete gamma function Q(a, x), from its values at the corners of the balls, since it is monotone in each argument.

Arguments

  • a (_BallArgument): The shape, a ball or an exact number.
  • x (_BallArgument): The argument, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the arguments' largest precision.

Returns

Ball: A ball containing the function at every pair of points; indeterminate where a ball reaches below 0 or both reach 0.

Raises

Error: Only on an invalid precision or a checked size error.

gammaln

Source: apn_mojo/ball/special.mojo

def gammaln(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the logarithm of Gamma, for x > 0.

A ball reaching 0 or below is indeterminate.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the function at every point.

Raises

Error: Only on an invalid precision or a checked size error.

hyp1f1

Source: apn_mojo/ball/special.mojo

def hyp1f1(
    a: _BallArgument,
    b: _BallArgument,
    x: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of Kummer's confluent hypergeometric function M(a, b, x).

Arguments

  • a (_BallArgument): The upper parameter, a ball or an exact number.
  • b (_BallArgument): The lower parameter, a ball or an exact number.
  • x (_BallArgument): The argument, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the arguments' largest precision.

Returns

Ball: A ball containing the function at every triple of points; indeterminate where b may be a non-positive integer.

Raises

Error: Only on an invalid precision or a checked size error.

hyp2f1

Source: apn_mojo/ball/special.mojo

def hyp2f1(
    a: _BallArgument,
    b: _BallArgument,
    c: _BallArgument,
    x: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of Gauss's hypergeometric function F(a, b; c; x).

Arguments

  • a (_BallArgument): The first upper parameter, a ball or an exact number.
  • b (_BallArgument): The second upper parameter, a ball or an exact number.
  • c (_BallArgument): The lower parameter, a ball or an exact number.
  • x (_BallArgument): The argument, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the arguments' largest precision.

Returns

Ball: A ball containing the function at every point of the balls; indeterminate where c may be a pole, and where x reaches 1 other than Gauss's exact value at 1, or beyond.

Raises

Error: Only on an invalid precision or a checked size error.

intersection

Source: apn_mojo/ball/sets.mojo

def intersection(
    a: Ball,
    b: Ball,
    *,
    context: Optional[BallContext] = None,
) raises -> Optional[Ball]

The least ball at the precision that contains the common points.

Arguments

  • a (Ball): The first ball.
  • b (Ball): The second ball.
  • context (Optional[BallContext]): The result precision; by default the larger of the two.

Returns

Optional[Ball]: None when the balls are disjoint, decided exactly; the other ball when one is unbounded; indeterminate when either is.

Raises

Error: Only on a checked size error.

lambertw

Source: apn_mojo/ball/special.mojo

def lambertw(
    value: _BallArgument,
    *,
    k: Int = 0,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of Lambert's W on branch 0 or -1.

A ball reaching below -1/e, or for branch -1 reaching 0 or above, is indeterminate.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • k (Int): The branch, 0 or -1.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing W at every point.

Raises

Error: For another branch, or on an invalid precision or a checked size error.

ldexp

Source: apn_mojo/ball/math.mojo

def ldexp(
    value: _BallArgument,
    exponent: Integer,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of value * 2**exponent, scaled exactly.

Arguments

  • value (_BallArgument): The operand.
  • exponent (Integer): The power of two.
  • context (Optional[BallContext]): The result precision; by default the operand's.

Returns

Ball: The scaled ball.

Raises

Error: When the exponent does not fit an Int, or on an invalid precision.

ln2_ball

Source: apn_mojo/ball/constants.mojo

def ln2_ball(precision: Int = 128) raises -> Ball

The canonical ball of ln 2.

Arguments

  • precision (Int): The precision p of the two ends, in bits.

Returns

Ball: [round_down(ln 2, p), round_up(ln 2, p)], with a midpoint of p + 1 bits.

Raises

Error: When the precision is invalid.

log

Source: apn_mojo/ball/elementary.mojo

def log(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the natural logarithm.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the logarithm of every point; indeterminate unless the ball is above 0.

Raises

Error: Only on an invalid precision or a checked size error.

log10

Source: apn_mojo/ball/elementary.mojo

def log10(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the base-10 logarithm.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the logarithm of every point; indeterminate unless the ball is above 0.

Raises

Error: Only on an invalid precision or a checked size error.

log1p

Source: apn_mojo/ball/elementary.mojo

def log1p(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of log(1 + x).

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing log(1 + x) of every point; indeterminate unless the ball is above -1.

Raises

Error: Only on an invalid precision or a checked size error.

log2

Source: apn_mojo/ball/elementary.mojo

def log2(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the base-2 logarithm.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the logarithm of every point; indeterminate unless the ball is above 0.

Raises

Error: Only on an invalid precision or a checked size error.

log2_10_ball

Source: apn_mojo/ball/constants.mojo

def log2_10_ball(precision: Int = 128) raises -> Ball

The canonical ball of log2(10).

Arguments

  • precision (Int): The precision p of the two ends, in bits.

Returns

Ball: [round_down(log2 10, p), round_up(log2 10, p)], with a midpoint of p + 1 bits.

Raises

Error: When the precision is invalid.

log_ndtr

Source: apn_mojo/ball/special.mojo

def log_ndtr(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the logarithm of the standard normal distribution function.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the function at every point.

Raises

Error: Only on an invalid precision or a checked size error.

maximum

Source: apn_mojo/ball/math.mojo

def maximum(
    left: _BallArgument,
    right: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of max(s, t) over all points of the two balls (numpy's maximum).

Arguments

  • left (_BallArgument): The first operand.
  • right (_BallArgument): The second operand.
  • context (Optional[BallContext]): The result precision; by default the operands' largest.

Returns

Ball: The operand lying wholly above the other, or the least ball over the larger lower end and the larger upper end; indeterminate when either operand is.

Raises

Error: Only on an invalid precision or a checked size error.

minimum

Source: apn_mojo/ball/math.mojo

def minimum(
    left: _BallArgument,
    right: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of min(s, t) over all points of the two balls (numpy's minimum).

Arguments

  • left (_BallArgument): The first operand.
  • right (_BallArgument): The second operand.
  • context (Optional[BallContext]): The result precision; by default the operands' largest.

Returns

Ball: The operand lying wholly below the other, or the least ball over the smaller lower end and the smaller upper end; indeterminate when either operand is.

Raises

Error: Only on an invalid precision or a checked size error.

multiply

Source: apn_mojo/ball/math.mojo

def multiply(
    left: _BallArgument,
    right: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of left * right.

Arguments

  • left (_BallArgument): The first operand.
  • right (_BallArgument): The second operand.
  • context (Optional[BallContext]): The result precision; by default the operands'.

Returns

Ball: A ball containing every product; an exact 0 times an unbounded ball is 0.

Raises

Error: Only on an invalid precision or a checked size error.

ndtr

Source: apn_mojo/ball/special.mojo

def ndtr(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the standard normal distribution function, (1 + erf(x/sqrt 2)) / 2.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the function at every point.

Raises

Error: Only on an invalid precision or a checked size error.

ndtri

Source: apn_mojo/ball/special.mojo

def ndtri(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the inverse standard normal distribution function, for a ball inside (0, 1).

Arguments

  • value (_BallArgument): The probability, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the function at every point; indeterminate unless the ball lies inside (0, 1).

Raises

Error: Only on an invalid precision or a checked size error.

overlaps

Source: apn_mojo/ball/sets.mojo

def overlaps(a: Ball, b: Ball) raises -> Bool

Whether the balls share a point.

Arguments

  • a (Ball): The first ball.
  • b (Ball): The second ball.

Returns

Bool: True when the closed intervals meet; always when either ball is not finite.

Raises

Error: Only on a checked size error.

pi_ball

Source: apn_mojo/ball/constants.mojo

def pi_ball(precision: Int = 128) raises -> Ball

The canonical ball of pi.

Arguments

  • precision (Int): The precision p of the two ends, in bits.

Returns

Ball: [round_down(pi, p), round_up(pi, p)], with a midpoint of p + 1 bits.

Raises

Error: When the precision is invalid.

poch

Source: apn_mojo/ball/special.mojo

def poch(
    z: _BallArgument,
    m: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the Pochhammer symbol Gamma(z + m) / Gamma(z), with scipy's values at the poles.

Arguments

  • z (_BallArgument): The first argument, a ball or an exact number.
  • m (_BallArgument): The second argument, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the arguments' largest precision.

Returns

Ball: A ball containing the function at every pair of points; indeterminate where it is infinite.

Raises

Error: Only on an invalid precision or a checked size error.

polygamma

Source: apn_mojo/ball/special.mojo

def polygamma(
    n: Integer,
    x: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the polygamma function of order n.

Arguments

  • n (Integer): The order, a non-negative integer.
  • x (_BallArgument): The argument, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the argument's precision.

Returns

Ball: A ball containing the function at every point; indeterminate at the poles and for n < 0.

Raises

Error: Only on an invalid precision or a checked size error.

pow

Source: apn_mojo/ball/elementary.mojo

def pow(
    base: _BallArgument,
    exponent: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of base**exponent.

An exact integer exponent gives an integer power; otherwise the base must be certainly above 0, and the result is exp(exponent log base).

Arguments

  • base (_BallArgument): The base.
  • exponent (_BallArgument): The exponent.
  • context (Optional[BallContext]): The result precision; by default the larger operand precision.

Returns

Ball: A ball containing every power; indeterminate when the base may be 0 or negative for a non-integer exponent (an exact 0 to a positive power gives 0).

Raises

Error: Only on an invalid precision or a checked size error.

pow_int

Source: apn_mojo/ball/math.mojo

def pow_int(
    value: _BallArgument,
    exponent: Integer,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of value**exponent for an integer exponent.

Arguments

  • value (_BallArgument): The base.
  • exponent (Integer): Any integer; a negative one takes the reciprocal.
  • context (Optional[BallContext]): The result precision; by default the operand's.

Returns

Ball: A ball containing every power; value**0 is exactly 1, and a negative exponent of a ball containing 0 is indeterminate.

Raises

Error: Only on an invalid precision or a checked size error.

propagation_bound

Source: apn_mojo/ball/significance.mojo

def propagation_bound[function: StaticString](
    midpoint: Float,
    radius: Float,
) raises -> Float

The propagation term P_f(m, r) of the ball function f (Appendix E.11): the bound a ball [m +/- r] adds to the radius of f's kernel at m, rounded up to the 30-bit radius format.

f P
exp, expm1 e**m (e**r - 1)
exp2 2**m (2**r - 1)
log, log2, log10 r / (m - r), divided by ln 2 or ln 10
log1p r / (1 + m - r)
sin, cos r min(1, |cos m| + r), r min(1, |sin m| + r)
atan r / (1 + d**2), d = max(0, |m| - r)
tanh min(r, 2)
asinh r / sqrt(1 + d**2)
atanh r / (1 - (|m| + r)**2)

Parameters

  • function (StaticString): The function's name, one of the table's.

Arguments

  • midpoint (Float): The ball's finite midpoint.
  • radius (Float): The ball's radius, finite and nonnegative.

Returns

Float: An upper bound of the term, with 30 bits.

Raises

Error: For another name, a negative or nonfinite radius, a nonfinite midpoint, or a ball reaching outside the function's domain (m <= r for log, 1 + m <= r for log1p, |m| + r >= 1 for atanh).

radius_for_relative_digits

Source: apn_mojo/ball/significance.mojo

def radius_for_relative_digits(midpoint: Float, digits: Float) raises -> Float

The radius of digits decimal digits of relative precision, |midpoint| * 10**-digits, rounded up to the 30-bit radius format.

Arguments

  • midpoint (Float): A finite nonzero midpoint.
  • digits (Float): The relative precision in decimal digits, finite.

Returns

Float: An upper bound of |midpoint| 10**-digits with 30 bits.

Raises

Error: For a zero or nonfinite midpoint, whose relative precision has no radius, a nonfinite or huge digits.

reciprocal

Source: apn_mojo/ball/math.mojo

def reciprocal(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of 1 / value.

Arguments

  • value (_BallArgument): The operand.
  • context (Optional[BallContext]): The result precision; by default the operand's.

Returns

Ball: A ball containing every reciprocal; indeterminate when the operand contains 0.

Raises

Error: Only on an invalid precision or a checked size error.

rootn

Source: apn_mojo/ball/elementary.mojo

def rootn(
    value: _BallArgument,
    n: Int,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the real n-th root, n >= 1.

Arguments

  • value (_BallArgument): The operand.
  • n (Int): The degree, at least 1; an odd root keeps the sign.
  • context (Optional[BallContext]): The result precision; by default the operand's precision.

Returns

Ball: A ball containing every root; indeterminate when an even root meets a negative point.

Raises

Error: When n is below 1, or on an invalid precision.

round_half_even_if_certain

Source: apn_mojo/ball/sets.mojo

def round_half_even_if_certain(ball: Ball) raises -> Optional[Integer]

The nearest integer (ties to even), when it is the same for every point.

Arguments

  • ball (Ball): The ball.

Returns

Optional[Integer]: The rounded value, or None when it varies or the ball is not finite.

Raises

Error: Only on a checked size error.

round_midpoint

Source: apn_mojo/ball/math.mojo

def round_midpoint(value: Ball, precision: Integer) raises -> Ball

The ball with its midpoint rounded to precision bits, the rounding error added to the radius.

Arguments

  • value (Ball): The ball.
  • precision (Integer): The new midpoint precision, at least 2.

Returns

Ball: A ball containing value.

Raises

Error: When the precision is invalid.

shichi

Source: apn_mojo/ball/special.mojo

def shichi(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Tuple[Ball, Ball]

The balls of the hyperbolic sine and cosine integrals (Shi(x), Chi(x)); Chi is defined for x > 0.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Tuple[Ball, Ball]: Two balls, each containing its function at every point.

Raises

Error: Only on an invalid precision or a checked size error.

sici

Source: apn_mojo/ball/special.mojo

def sici(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Tuple[Ball, Ball]

The balls of the sine and cosine integrals (Si(x), Ci(x)); Ci is defined for x > 0.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Tuple[Ball, Ball]: Two balls, each containing its function at every point.

Raises

Error: Only on an invalid precision or a checked size error.

simplest_rational_in

Source: apn_mojo/ball/sets.mojo

def simplest_rational_in(ball: Ball) raises -> Rational

The simplest rational in the ball: the least denominator, and among those the least absolute numerator.

A continued-fraction descent on the exact ends finds it; it is a loop over an explicit list of partial quotients, not a recursion. simplest_rational_in(Ball.from_interval("3.14059", "3.14259")) is 201/64, Mathematica's Rationalize[3.14159, 10^-3].

Arguments

  • ball (Ball): A finite ball.

Returns

Rational: The simplest rational in the closed interval.

Raises

Error: Unless the ball is finite.

sin

Source: apn_mojo/ball/elementary.mojo

def sin(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the sine.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the sine of every point, within [-1, 1]; [0 +/- 1] past the budget.

Raises

Error: Only on an invalid precision or a checked size error.

sin_cos

Source: apn_mojo/ball/elementary.mojo

def sin_cos(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Tuple[Ball, Ball]

The balls of the sine and the cosine.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Tuple[Ball, Ball]: (sin(value), cos(value)), each as sin and cos give it.

Raises

Error: Only on an invalid precision or a checked size error.

sinh

Source: apn_mojo/ball/elementary.mojo

def sinh(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the hyperbolic sine.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing sinh of every point.

Raises

Error: Only on an invalid precision or a checked size error.

split

Source: apn_mojo/ball/sets.mojo

def split(ball: Ball) raises -> Tuple[Ball, Ball]

The two halves [m - r/2 +/- r/2] and [m + r/2 +/- r/2].

The halves are exact: their midpoints take the precision they need, so their union is the ball itself.

Arguments

  • ball (Ball): A finite ball.

Returns

Tuple[Ball, Ball]: The lower and the upper half.

Raises

Error: Unless the ball is finite.

sqrt

Source: apn_mojo/ball/math.mojo

def sqrt(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the square root.

Arguments

  • value (_BallArgument): The operand.
  • context (Optional[BallContext]): The result precision; by default the operand's.

Returns

Ball: A ball containing every root; indeterminate when the operand reaches below 0. A lower end of exactly 0 is allowed.

Raises

Error: Only on an invalid precision or a checked size error.

square

Source: apn_mojo/ball/math.mojo

def square(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of value**2.

Arguments

  • value (_BallArgument): The operand.
  • context (Optional[BallContext]): The result precision; by default the operand's.

Returns

Ball: A ball containing every square.

Raises

Error: Only on an invalid precision or a checked size error.

stable_hash

Source: apn_mojo/ball/math.mojo

def stable_hash(value: Ball) raises -> UInt64

A 64-bit hash of the representation, stable across processes and releases.

The algorithm is APNH-64: tag 6, the kind (0 finite, 1 unbounded, 2 indeterminate), then the midpoint and the radius, each encoded as for a Float, the radius as a 30-bit Float with the default exponent bounds.

Arguments

  • value (Ball): The ball.

Returns

UInt64: The hash.

Raises

Error: Never in practice.

subtract

Source: apn_mojo/ball/math.mojo

def subtract(
    left: _BallArgument,
    right: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of left - right.

Arguments

  • left (_BallArgument): The first operand.
  • right (_BallArgument): The second operand.
  • context (Optional[BallContext]): The result precision; by default the operands'.

Returns

Ball: A ball containing every difference.

Raises

Error: Only on an invalid precision or a checked size error.

tan

Source: apn_mojo/ball/elementary.mojo

def tan(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the tangent.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing the tangent of every point; indeterminate when the ball may contain a pole, or past the budget.

Raises

Error: Only on an invalid precision or a checked size error.

tanh

Source: apn_mojo/ball/elementary.mojo

def tanh(
    value: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the hyperbolic tangent.

Arguments

  • value (_BallArgument): The operand, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the operand's precision.

Returns

Ball: A ball containing tanh of every point, within [-1, 1].

Raises

Error: Only on an invalid precision or a checked size error.

to_float_if_certain

Source: apn_mojo/ball/sets.mojo

def to_float_if_certain(
    ball: Ball,
    *,
    context: Optional[ArithmeticContext] = None,
) raises -> Optional[Float]

The Float that every point of the ball rounds to, when there is one.

Both ends of the ball are rounded, once each, to the context's format with its rounding mode. When they give the same Float with the same status, every point of the ball rounds to that Float, the true value it encloses among them. Correctly rounded functions repeat this step at higher precision until it succeeds.

Arguments

  • ball (Ball): The ball.
  • context (Optional[ArithmeticContext]): The format, rounding mode and traps; by default the midpoint's format, rounded to nearest-even.

Returns

Optional[Float]: The Float, or None when the ends round differently or the ball is not finite. A ball that contains 0 without being exactly 0 never gives a Float: its ends round to values of opposite signs.

Raises

Error: On a trapped condition of the result.

trim

Source: apn_mojo/ball/math.mojo

def trim(value: Ball) raises -> Ball

The ball with its midpoint rounded to the bits its radius leaves meaningful: the relative accuracy plus 8, never more than it has.

Arguments

  • value (Ball): The ball.

Returns

Ball: A ball containing value, with a midpoint no longer than needed.

Raises

Error: Only on a checked size error.

union

Source: apn_mojo/ball/sets.mojo

def union(
    a: Ball,
    b: Ball,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The least ball at the precision that contains both.

Arguments

  • a (Ball): The first ball.
  • b (Ball): The second ball.
  • context (Optional[BallContext]): The result precision; by default the larger of the two.

Returns

Ball: The hull; indeterminate or unbounded if either ball is.

Raises

Error: Only on a checked size error.

zeta

Source: apn_mojo/ball/special.mojo

def zeta(
    x: _BallArgument,
    q: _BallArgument,
    *,
    context: Optional[BallContext] = None,
) raises -> Ball

The ball of the Hurwitz zeta function; zeta(x, 1) is the Riemann zeta function.

Arguments

  • x (_BallArgument): The exponent, a ball or an exact number.
  • q (_BallArgument): The shift, a ball or an exact number.
  • context (Optional[BallContext]): The result precision and budget; by default the arguments' largest precision.

Returns

Ball: A ball containing the function at every pair of points; indeterminate at the poles and outside the domain.

Raises

Error: Only on an invalid precision or a checked size error.

Structs

Ball

Source: apn_mojo/ball/value.mojo

struct Ball(ImplicitlyCopyable, Writable, _BatchElement)

A real ball [m +/- r]: every real number within r of m.

A ball function returns a ball that contains the exact result for every point of its input balls; it may be wider than necessary, but never excludes the true value. A ball is finite, unbounded (any real number), or indeterminate (no information, as where a function is undefined). The midpoint is a Float of any precision; the radius has 30 bits and is rounded up.

Operation Contract
x + y, x - y, x * y, x / y, -x Encloses every result; Integer, Rational and Float operands are exact
Division by a ball containing 0 Indeterminate
Comparisons compare and the certainly_* predicates; no < or ==

Limitations

A ball has no signed zero. There are no comparison operators, since a three-valued comparison must not pass for a Bool.

Implements

Copyable, ImplicitlyCopyable, Writable, _BatchElement, _MapArgument

Ball.__init__ { #Ball.init .api-name }

def __init__(
    out self,
    value: _FloatArgument,
    *,
    precision: Optional[Int] = None,
) raises

The ball of an exact number.

An Integer, or a Rational that is a binary fraction, gives an exact ball with at least 128 bits, so arithmetic on small exact balls stays exact. A Float gives an exact ball in its own precision. Another Rational is rounded to 128 bits, with a radius covering the error. With precision, the number is rounded to that many bits instead.

Arguments

  • value (_FloatArgument): An Integer, Rational, Float or native number.
  • precision (Optional[Int]): The midpoint precision, in bits.

Raises

Error: For infinity and NaN; use Ball.unbounded() or Ball.indeterminate().

def __init__(
    out self,
    midpoint: _FloatArgument,
    radius: _FloatArgument,
    *,
    precision: Optional[Int] = None,
) raises

The ball [midpoint +/- radius].

The radius rounds up to 30 bits; a midpoint that is not exact at the precision is rounded, and its error added to the radius.

Arguments

  • midpoint (_FloatArgument): The center, an exact number.
  • radius (_FloatArgument): A nonnegative exact number; infinity gives an unbounded ball.
  • precision (Optional[Int]): The midpoint precision, in bits; by default as for Ball(midpoint).

Raises

Error: For a negative or NaN radius, or an infinite or NaN midpoint.

def __init__(out self, text: String, *, precision: Optional[Int] = None) raises

Parse a ball: a number, or the midpoint-radius form [m +/- r].

A decimal or fraction ("3.14", "1/3") is exact and rounds once to the precision, 128 bits by default, with a radius covering the error; hexadecimal and binary text ("0x1.8p0") are exact binary fractions. In [m +/- r], m rounds to nearest and r rounds up. [+/- inf] is unbounded and [nan +/- inf] indeterminate.

Arguments

  • text (String): The text.
  • precision (Optional[Int]): The midpoint precision, in bits; 128 by default.

Raises

Error: When the text is not a number or a ball.

Ball.accuracy_bits

def accuracy_bits(self) -> Int

The absolute accuracy, floor(-log2(radius)).

Returns

Int: Int.MAX for an exact ball and Int.MIN unless the ball is finite.

Ball.certainly_eq

def certainly_eq(self, other: _BallArgument) raises -> Bool

Whether both are the same exact value; an inexact ball is never certainly equal to anything.

Arguments

  • other (_BallArgument): A ball or an exact number.

Returns

Bool: True only for two exact, equal balls.

Raises

Error: Only on a checked size error.

Ball.certainly_ge

def certainly_ge(self, other: _BallArgument) raises -> Bool

Whether every point is at least every point of other.

Arguments

  • other (_BallArgument): A ball or an exact number.

Returns

Bool: True only when it is certain.

Raises

Error: Only on a checked size error.

Ball.certainly_gt

def certainly_gt(self, other: _BallArgument) raises -> Bool

Whether every point is above every point of other.

Arguments

  • other (_BallArgument): A ball or an exact number.

Returns

Bool: True only when it is certain.

Raises

Error: Only on a checked size error.

Ball.certainly_le

def certainly_le(self, other: _BallArgument) raises -> Bool

Whether every point is at most every point of other.

Arguments

  • other (_BallArgument): A ball or an exact number.

Returns

Bool: True only when it is certain.

Raises

Error: Only on a checked size error.

Ball.certainly_lt

def certainly_lt(self, other: _BallArgument) raises -> Bool

Whether every point is below every point of other.

Arguments

  • other (_BallArgument): A ball or an exact number.

Returns

Bool: True only when it is certain.

Raises

Error: Only on a checked size error.

Ball.certainly_ne

def certainly_ne(self, other: _BallArgument) raises -> Bool

Whether no point is shared with other.

Arguments

  • other (_BallArgument): A ball or an exact number.

Returns

Bool: True only when it is certain.

Raises

Error: Only on a checked size error.

Ball.certainly_negative

def certainly_negative(self) raises -> Bool

Whether every point is below 0.

Returns

Bool: True only when it is certain.

Raises

Error: Only on a checked size error.

Ball.certainly_nonnegative

def certainly_nonnegative(self) raises -> Bool

Whether every point is at least 0.

Returns

Bool: True only when it is certain.

Raises

Error: Only on a checked size error.

Ball.certainly_nonpositive

def certainly_nonpositive(self) raises -> Bool

Whether every point is at most 0.

Returns

Bool: True only when it is certain.

Raises

Error: Only on a checked size error.

Ball.certainly_nonzero

def certainly_nonzero(self) raises -> Bool

Whether 0 is outside the ball; not certainly_nonzero() is the test for a possible zero.

Returns

Bool: True only when it is certain.

Raises

Error: Only on a checked size error.

Ball.certainly_positive

def certainly_positive(self) raises -> Bool

Whether every point is above 0.

Returns

Bool: True only when it is certain.

Raises

Error: Only on a checked size error.

Ball.from_interval

def from_interval(
    low: _FloatArgument,
    high: _FloatArgument,
    *,
    precision: Optional[Int] = None,
) raises -> Self

The least ball at the precision that contains [low, high].

Arguments

  • low (_FloatArgument): The lower end, an exact number.
  • high (_FloatArgument): The upper end, at least low.
  • precision (Optional[Int]): The midpoint precision, in bits; 128 by default.

Returns

Self: A ball with midpoint (low + high) / 2 rounded to the precision.

Raises

Error: When low > high, or an end is infinite or NaN.

Ball.from_json

def from_json(
    text: String,
    *,
    limits: Optional[ConversionLimits] = None,
) raises -> Self

Read a Ball from its version-1 JSON record, without rounding.

Arguments

  • text (String): The JSON record.
  • limits (Optional[ConversionLimits]): Optional per-call conversion limits; see ConversionLimits.

Returns

Self: The Ball the record holds.

Raises

Error: When the text is not exactly that schema in canonical form.

Ball.indeterminate

def indeterminate(precision: Int = 128) raises -> Self

The ball that carries no information, as where a function is undefined.

Arguments

  • precision (Int): The midpoint precision, in bits.

Returns

Self: An indeterminate ball, with a NaN midpoint.

Raises

Error: When the precision is invalid.

Ball.is_exact

def is_exact(self) -> Bool

Whether the ball is finite with radius 0.

Returns

Bool: True for an exact ball.

Ball.is_finite

def is_finite(self) -> Bool

Whether the ball is finite.

Returns

Bool: True unless unbounded or indeterminate.

Ball.is_indeterminate

def is_indeterminate(self) -> Bool

Whether the ball is indeterminate.

Returns

Bool: True for the ball without information.

Ball.is_unbounded

def is_unbounded(self) -> Bool

Whether the ball is unbounded.

Returns

Bool: True for the ball of every real number.

Ball.lower

def lower(self) raises -> Float

The lower end, rounded down at the midpoint's precision.

Returns

Float: A Float at or below every point of the ball.

Raises

Error: Unless the ball is finite.

Ball.lower_rational

def lower_rational(self) raises -> Rational

The lower end, exactly.

Returns

Rational: midpoint - radius as a Rational.

Raises

Error: Unless the ball is finite.

Ball.magnitude_lower

def magnitude_lower(self) raises -> Float

A lower bound of abs(x) over the ball, as a 30-bit Float.

Returns

Float: The bound; 0 when the ball contains 0 or is not finite.

Raises

Error: Only on a checked size error.

Ball.magnitude_upper

def magnitude_upper(self) raises -> Float

An upper bound of abs(x) over the ball, as a 30-bit Float.

Returns

Float: The bound; infinity unless the ball is finite.

Raises

Error: Only on a checked size error.

Ball.midpoint

def midpoint(self) -> Float

The midpoint; NaN for an indeterminate ball.

Returns

Float: The midpoint.

Ball.midpoint_rational

def midpoint_rational(self) raises -> Rational

The midpoint, exactly.

Returns

Rational: The midpoint as a Rational.

Raises

Error: For an indeterminate ball.

Ball.precision

def precision(self) -> Int

The midpoint precision.

Returns

Int: The precision in bits.

Ball.radius

def radius(self) raises -> Float

The radius, exactly, as a 30-bit Float; infinity unless finite.

Returns

Float: The radius.

Raises

Error: Only on a checked size error.

Ball.relative_accuracy_bits

def relative_accuracy_bits(self) -> Int

The relative accuracy, -log2(radius / abs(midpoint)), from the exponents and at most one bit pessimistic.

Returns

Int: Int.MAX for an exact ball, at most 0 when the radius reaches the midpoint, and Int.MIN unless the ball is finite.

Ball.representation_cmp

def representation_cmp(self, other: Self) -> Int

Compare representations in a strict total order: the kind, then the midpoint by Float.representation_cmp, then the radius.

Arguments

  • other (Self): The other ball.

Returns

Int: -1, 0 or 1; 0 exactly when same_representation holds.

Ball.same_representation

def same_representation(self, other: Self) -> Bool

Whether kind, midpoint representation and radius all match.

Arguments

  • other (Self): The other ball.

Returns

Bool: True when the representations match.

Ball.sign_if_certain

def sign_if_certain(self) raises -> Optional[Int]

The sign, when the whole ball has one.

Returns

Optional[Int]: -1 or 1 when certain, 0 for the exact ball 0, otherwise None.

Raises

Error: Only on a checked size error.

Ball.to_json

def to_json(self, *, limits: Optional[ConversionLimits] = None) raises -> String

Write the version-1 JSON record: the kind, and the midpoint and the radius as complete Float records. Reading it back gives the same representation.

Arguments

  • limits (Optional[ConversionLimits]): Optional per-call conversion limits; see ConversionLimits.

Returns

String: Compact canonical JSON.

Raises

Error: When the output exceeds limits.

Ball.to_string

def to_string(self, digits: Optional[Int] = None) raises -> String

Write the ball in midpoint-radius form, [midpoint +/- radius].

Without digits, the midpoint has as many significant digits as the radius certifies; with them, that many. The printed radius has three significant digits, rounded up, and covers the rounding of the printed midpoint, so the printed ball contains this one. An exact ball whose midpoint prints exactly shows radius 0; [+/- inf] is unbounded and [nan +/- inf] indeterminate.

Arguments

  • digits (Optional[Int]): The midpoint's significant digits, at least 1.

Returns

String: The text.

Raises

Error: When digits is below 1.

Ball.unbounded

def unbounded(precision: Int = 128) raises -> Self

The ball of every real number.

Arguments

  • precision (Int): The midpoint precision, in bits.

Returns

Self: An unbounded ball with midpoint 0.

Raises

Error: When the precision is invalid.

Ball.upper

def upper(self) raises -> Float

The upper end, rounded up at the midpoint's precision.

Returns

Float: A Float at or above every point of the ball.

Raises

Error: Unless the ball is finite.

Ball.upper_rational

def upper_rational(self) raises -> Rational

The upper end, exactly.

Returns

Rational: midpoint + radius as a Rational.

Raises

Error: Unless the ball is finite.

Ball.write_to

def write_to(self, mut writer: Some[Writer])

Write to_string(), as print does.

Arguments

  • writer (mut Some[Writer]): The destination.

BallContext

Source: apn_mojo/ball/context.mojo

struct BallContext(ImplicitlyCopyable, Writable)

The working precision of a ball result, and the budget of functions whose cost depends on their input.

It is a ball function's only keyword, context=, so vmap and lift pass it through to scalar ball functions. Without a precision, a result takes the largest midpoint precision among its Ball and Float operands; exact Integer and Rational operands contribute none, and a result of exact operands alone has 128 bits. Rounding modes and traps do not apply to balls.

Implements

Copyable, ImplicitlyCopyable, Writable

BallContext.__init__ { #BallContext.init .api-name }

def __init__(
    out self,
    precision: Optional[Int] = None,
    *,
    max_precision: Optional[Int] = None,
) raises

A context with an optional working precision and budget.

Arguments

  • precision (Optional[Int]): The midpoint precision of results, in bits, at least 2.
  • max_precision (Optional[Int]): The largest working precision a function may use; by default, as the function documents.

Raises

Error: When a precision is below 2.

BallContext.max_precision

def max_precision(self) -> Optional[Int]

The budget, if one is set.

Returns

Optional[Int]: The largest working precision in bits, or None for the default.

BallContext.precision

def precision(self) -> Optional[Int]

The working precision, if one is set.

Returns

Optional[Int]: The precision in bits, or None to follow the operands.

BallContext.write_to

def write_to(self, mut writer: Some[Writer])

Write the settings, as print does.

Arguments

  • writer (mut Some[Writer]): The destination.

BallOrder

Source: apn_mojo/ball/value.mojo

struct BallOrder(Equatable, ImplicitlyCopyable, Writable)

How two balls compare: one of five named constants.

less and greater hold for every pair of points of the two balls, equal only for two exact, equal balls, overlap when no order is certain, and undefined when either ball is indeterminate.

Implements

Copyable, Equatable, ImplicitlyCopyable, Writable

Aliases

  • less
  • equal
  • greater
  • overlap
  • undefined

BallOrder.write_to

def write_to(self, mut writer: Some[Writer])

Write the name, as print does.

Arguments

  • writer (mut Some[Writer]): The destination.

Kinds, precision and exactness

A finite ball represents [m - r, m + r]. The midpoint is a Float with a chosen precision; the radius has a private 30-bit significand and rounds upward. midpoint() and radius() return the stored values as Floats. A radius of zero represents one exact point.

An unbounded ball contains every real number. An indeterminate ball has no usable enclosure, usually because part of the input is outside the function's domain. Division by an interval containing zero and a square root of an interval reaching below zero both return an indeterminate ball. A square root can accept a lower bound of exactly zero.

Pass context=BallContext(precision) to choose midpoint precision. Without one, operations use the largest midpoint precision of their Ball and Float operands. Exact integer and rational operands contribute no precision. Balls constructed from integers or binary fractions have at least 128 midpoint bits, so small exact inputs are not given an unnecessarily narrow working format. Only actual midpoint rounding adds a rounding error to the radius.

Batches of balls

Batch[Ball] supports shapes, indexing, views, masks, assignment, iteration, and printing. Apply scalar functions from apn_mojo.ball with vmap, or use lift for broadcasting binary calls, outer products, and folds with BallContext. NumPy-style functions such as batch.add and batch.exp also work on balls. min and max enclose the extreme over all points; cumsum and cumprod carry the enclosure through each prefix. Use lift for other folds. Ball batches have no arithmetic operators or batch JSON.

Mapping can also take exact-number batches as input. For example, vmap[ball.sqrt]()(integers, context=BallContext(64)) produces balls from integers. A mapped predicate returns a Mask. Supported Optional-returning functions produce a value batch and a mask showing which results exist.

Comparisons and sets

Balls have no ordinary < or ==. compare returns one of five BallOrder values: less, equal, greater, overlap, or undefined. The certainly_* predicates are true only when the relation holds for every point in the intervals. Overlap alone does not establish equality.

contains, contains_ball, and overlaps test exact interval endpoints. union returns an enclosing interval, including any gap between disjoint inputs. intersection, split, floor_if_certain, ceil_if_certain, round_half_even_if_certain, and simplest_rational_in provide set and rounding operations with their own documented result types.

Text, keys and scope

Balls support text output and parsing, representation comparisons, stable_hash, and BallKey for dictionary keys. Ordinary interval comparison and representation identity answer different questions; use the operation that matches the caller's purpose.

JSON is a version-1 record with the kind (finite, unbounded or indeterminate) and two complete Float records, the midpoint and the radius:

{"version":1,"family":"ball","kind":"finite",
 "midpoint":{"version":1,"family":"float","precision":"53","emin":"-4611686018427387904","emax":"4611686018427387903","class":"finite","sign":"+","significand":"4503599627370496","exponent":"1"},
 "radius":{"version":1,"family":"float","precision":"30","emin":"-4611686018427387904","emax":"4611686018427387903","class":"finite","sign":"+","significand":"536870912","exponent":"-29"}}

This record represents [1 +/- 2**-30]. JSON preserves the representation exactly: Ball.from_json(x.to_json()) has the same stored representation as x. The reader accepts only canonical records. The radius must have 30 bits, the default bounds, and sign +. An unbounded ball has a finite midpoint and an infinite radius; an indeterminate ball has a NaN midpoint and an infinite radius.

Printed text preserves an enclosure, not necessarily the stored representation. The printer expands the displayed radius to cover midpoint rounding, and parsing that text can widen the interval again. Use representation comparisons or BallKey when you need to distinguish stored representations.

The family is real-valued; ComplexBall in apn_mojo.complex_ball pairs two balls into a rectangle. Ball arithmetic explains the enclosure formulas and the internal radius representation.

Elementary functions

The elementary functions of apn_mojo.float have ball versions of the same names, which return a ball containing the function's value at every point of the input ball. Monotone functions evaluate a correctly rounded kernel at the two exact ends of the ball; sin and cos widen their midpoint value by a bound of the derivative and stay within [-1, 1]. A function undefined somewhere in its input ball gives an indeterminate ball: log of a ball reaching 0, asin of a ball reaching past 1, or tan of a ball that may contain a pole. atan2 gives [0 +/- pi] for a rectangle that meets the negative real axis, where the angle jumps.

A ball function does not raise when it reaches the BallContext's max_precision budget. At that point, sin and cos return [0 +/- 1], and tan returns an indeterminate ball.

Constants and canonical balls

pi_ball(p), euler_e_ball, ln2_ball, log2_10_ball, euler_gamma_ball and catalan_ball return the canonical ball of the constant at precision p: [round_down(c, p), round_up(c, p)], with a midpoint of p + 1 bits and the exact half-width as radius. It depends only on the constant and p.

canonical(ball, p) returns the canonical ball of the enclosed value, or None if the input is too wide to determine both ends. You can use this to cache the highest precision computed for a constant and serve later requests with canonical(cached, p). For pi, if that returns None, compute pi_ball(2 * p) and keep the new result. Each answer depends only on the constant and requested precision, regardless of the cache's history.

to_float_if_certain(ball, context=c) rounds both ends of a ball to the context's format and returns the Float when they agree: then every point of the ball rounds to it. It is the step that correctly rounded functions repeat at higher precision.

Special functions

The special functions of apn_mojo.float have ball versions of the same names. The monotone ones evaluate their kernel at the two ends of the ball: erf, erfc, erfi, Shi, Chi, digamma between its poles, Ei on each side of 0, and each branch of Lambert's W. Gamma and log Gamma use their monotone pieces on each side of the minimum at 1.4616...; the others widen the midpoint value by a bound of the derivative: 1 for Si and Fresnel's integrals, 1/x for Ci, and the end values of |Gamma| |psi| for Gamma between negative poles. A ball containing a pole, 0 or a negative integer for Gamma and digamma and 0 for Ei, or reaching outside the domain is indeterminate.

Significance arithmetic

For choosing a precision and certifying displayed digits, see precision and accuracy.

A precision tracked as in Mathematica is a ball radius on a logarithmic scale: d digits of relative precision mean a radius of |m| 10**-d. radius_for_relative_digits(m, d) returns that radius rounded up to the 30-bit radius format; a zero midpoint has no relative precision and raises. bits_to_digits(b) and digits_to_bits(d) convert precisions as balls, since log2 10 is irrational. propagation_bound["exp"](m, r) returns the term that the ball function adds to its kernel's radius at the midpoint, for exp, expm1, exp2, log, log2, log10, log1p, sin, cos, atan, tanh, asinh and atanh, so that a caller bounds its own errors the same way; it raises for a ball reaching outside the function's domain.