dfloat.h

Returns whether the module works on this target. It requires that the module was compiled without contraction of floating-point expressions (-ffp-contract=off or the equivalent pragma), with doubles evaluated in double precision (FLT_EVAL_METHOD 0, so not with x87 arithmetic), and that fma is correctly rounded, which is tested once at run time. Where it returns 0, the other functions of this module must not be called; gr_ctx_init_dfloat returns GR_UNABLE and the power sums return 0, so that their callers fall back to other code.

Initialises ctx to a generic ring of n-term expansions, 1 \le n \le 4. The flags select the format: without DFLOAT_BALL the elements are plain dN numbers (an approximate floating-point ring), with it dNb balls (a rigorous representation of \mathbb{R}); with DFLOAT_COMPLEX the complex formats dNc or dNcb. Passing 0 or 1 selects the plain or the ball real ring with the defaults. Returns GR_UNABLE if n is out of range or dfloat_is_supported returns 0, and GR_SUCCESS otherwise.

Sets res to the double x, exactly. In the ball version a nonfinite x gives the whole real line.

Sets res to x_0 + x_1, renormalised. In the ball version, anything that does not fit in N components is added to the radius.

Sets res to the ball [x \pm \mathit{rad}]; the whole real line if x or \mathit{rad} is not finite or \mathit{rad} is negative.

Set res to 0, to 1, or (for indeterminate) to the whole real line in its normal form [0 \pm \infty].

Copy, negation and absolute value, all exact. dNb_set copies any form of the whole real line as it is; dNb_neg and dNb_abs return its normal form.

Arithmetic on the plain formats, accurate to a few ulps at 53N bits: sum, difference, product, square, product with a double, quotient, inverse, square root, reciprocal square root x^{-1/2} and multiplication by 2^e. Overflow gives infinity, and nonfinite values propagate as in double arithmetic.

Rigorous ball arithmetic. The rounding errors of the midpoint operation are added to the radius, so that exact operations on exact balls give exact results: [3 \pm 0] \cdot [3 \pm 0] = [9 \pm 0], and (2^{60} + 1) \cdot 3 is exact in d2b.

Division and inverse. Return GR_DOMAIN if the divisor is exactly zero (whatever the dividend), GR_UNABLE if it contains zero (in particular if it is the whole real line), and GR_SUCCESS otherwise, in which case res contains the quotient.

Square root. Returns GR_DOMAIN if x is entirely negative, GR_UNABLE if it contains negative numbers (and positive ones or zero), and GR_SUCCESS otherwise; \sqrt{[0 \pm 0]} = [0 \pm 0].

Reciprocal square root. Returns GR_DOMAIN if x is entirely nonpositive, GR_UNABLE if it contains zero, and GR_SUCCESS otherwise.

Sets res to x (exactly, with the radius unchanged) with the components in canonical form: |x_{i+1}| \le \operatorname{ulp}(x_i)/2 and zeros only at the end, which is the form obtained by rounding the value to nearest term by term. Works for any x whose components overlap by at most a few bits, in particular any result of this module. A nonfinite head is copied as it is by dN_canonicalise; dNb_canonicalise gives the whole real line in its normal form.

Sets res to the sum of the len doubles t_0, \ldots, t_{len-1}, rounded to N nonoverlapping components; the dropped part is discarded. The terms may be in any order, but for an accurate result they should be roughly sorted by decreasing magnitude. The array t is used as scratch space and overwritten; pass a copy if the terms are needed afterwards. res must not overlap t.

Adds |\mathit{err}| to the radius of res, rounding up; a nonfinite err gives the whole real line.

The exponential function, with the error bound DFLOAT_EXP_EPS_N. Nonfinite arguments and arguments beyond the range give the double result (infinity, 0 or NaN); dN_exp of 0 is exactly 1.

The exponential of a ball. The radius is |y| (1 + 2\varepsilon)((e^r - 1) + 2\varepsilon) for the kernel value y at the midpoint, the input radius r and the static bound \varepsilon. Where this overflows for a wide ball whose upper end h does not, the result is [0 \pm e^h]. Arguments beyond the double range give the whole real line (overflow) or a ball of radius at most 2^{-1074} around zero (underflow); \exp([0 \pm 0]) = [1 \pm 0].

The sine and cosine, with the bounds DFLOAT_TRIG_EPS_N. dN_sin_cos computes both from one argument reduction, at about 10% more than one of them, with results identical to those of dN_sin and dN_cos. Arguments beyond 2^{20}\pi/2 - 1 in absolute value are evaluated through arb_t with the same guarantee; nonfinite arguments give NaN.

The sine and cosine of a ball. The radius is \varepsilon(|m| + a) + r with a = \min(|m|, 1) for the sine and a = 1 for the cosine, for the midpoint m and the input radius r (both functions are 1-Lipschitz); a radius of 1 or more is replaced by the enclosure [0 \pm 1]. Infinite radii, nonfinite midpoints and midpoints beyond the kernel range go through arb_t. \sin([0 \pm 0]) = [0 \pm 0] and \cos([0 \pm 0]) = [1 \pm 0].

The natural logarithm and the arctangent, with the bounds above. The logarithm of a nonpositive number is -\infty (for zero) or NaN, of +\infty it is +\infty, and \log 1 = 0 exactly; arguments outside [2^{-1022}, 2^{1022}) go through arb_t. The arctangent of \pm\infty is \pm \pi/2, and \operatorname{atan} 0 = 0 exactly.

The logarithm and arctangent of a ball [m \pm r], with the radii \varepsilon |y| + r/(m - r) and \varepsilon |y| + r. dNb_log returns GR_DOMAIN if the ball is entirely nonpositive, GR_UNABLE if it is otherwise not contained in (0, \infty), and GR_SUCCESS otherwise. Infinite radii, nonfinite midpoints and midpoints beyond the kernel ranges go through arb_t.

e^x - 1 and \log(1 + x), with the bounds above, accurate also for small |x| where dN_exp and dN_log would cancel.

e^x - 1 and \log(1 + x) for balls, propagating the input radius as dNb_exp and dNb_log do. dNb_log1p returns GR_DOMAIN if the ball is entirely in (-\infty, -1], GR_UNABLE if it is otherwise not contained in (-1, \infty), and GR_SUCCESS otherwise.

Further elementary functions, as compositions of the kernels with the arithmetic (the arguments are canonicalised first). Their relative errors are about the sums of those of their parts (about 2^{-49}, 2^{-98}, 2^{-149}, 2^{-199}), except that dN_pow amplifies the error of the logarithm by |y \log x| (up to 2^{9.5} at the end of the range of the exponential) and that tan, sinh and tanh inherit absolute errors near their zeros. dN_atan2(res, y, x) follows the double atan2 for nonfinite arguments, and dN_pow gives NaN for x < 0 and noninteger y.

The same functions on balls, as the same compositions of the ball functions. dNb_tan, dNb_asin, dNb_acos and dNb_pow return a status: GR_SUCCESS if the input is inside the domain, GR_DOMAIN if it is outside, and GR_UNABLE otherwise. The domains are x \notin \pi/2 + \pi\mathbb{Z} for the tangent (never GR_DOMAIN, since the poles are irrational), |x| \le 1 for asin and acos, and for pow, x > 0, or x = 0 and y \ge 0, or x < 0 and y \in \mathbb{Z}.

Predicates and comparisons of the exact values of plain expansions: dN_equal compares values, not components, and dN_cmp and dN_sgn return -1, 0 or 1. dN_is_finite is true if every component is finite.

Ball predicates. is_exact is true for a finite ball of radius zero and is_finite for a ball that is not the whole real line. is_zero, equal, contains and contains_d answer 1 only when certain (is_zero and equal only for exact balls, contains_d only for a finite c); contains_zero and overlaps answer 0 only when certain. The whole real line contains and overlaps everything, and is contained only in the whole real line. dNb_cmp sets *res to -1, 0 or 1 and returns GR_SUCCESS when every pair of points of the balls compares the same way (or both are the same exact number), and sets *res to 0 and returns GR_UNABLE otherwise.

Return the head d_0 of the midpoint, the double nearest to it (up to ties); 0 for the whole real line.

Sets mid[0], ..., mid[N-1] to the components of the midpoint (zeros for the whole real line).

Conversions from and to arf_t and arb_t. The get functions are exact (the radius is rounded up to a mag_t). The set functions round the midpoint to N doubles by greedy rounding and, for balls, add the remainder to the radius. A nonfinite arb_t or arf_t gives the whole real line, and dNb_get_arb gives the whole real line as [0 \pm \infty].

Set res to an integer or a rational number, rounded to N doubles through an arb_t (rigorously, for the balls).

Parse a decimal string with arb_set_str (at 53N + 64 bits) and convert, rigorously for the balls. Return GR_SUCCESS, or GR_UNABLE if the string could not be parsed.

Convert to a decimal string with digits significant digits through arb_get_str (digits \le 0 selects \lfloor 53N \log_{10} 2 \rfloor + 1 digits), or print to standard output with the default number of digits. Balls are printed with their radius, and every form of the whole real line as [+/- inf]. The string must be freed with flint_free.

Random values for testing; the special versions also produce subnormal numbers, values at the ends of the double range, nonfinite values and radii from zero to infinity.

Elementwise sum, difference, product, product with the scalar c, accumulation of \pm c\, x_i into res, quotient, square root and reciprocal square root.

Set res to s \pm \sum_i x_i y_i (vec_dot) or s \pm \sum_i x_i y_{len-1-i} (vec_dot_rev), where s is initial (or zero if initial is NULL) and the sign is negative if subtract is nonzero, as _gr_vec_dot and _gr_vec_dot_rev.

Elementwise elementary functions with the same static error bounds as the scalar kernels, which they run on four arguments at a time (3 to 5 times faster per element than scalar calls). Elements that hit a special case are redone with the scalar code.