FLINT3.7.0-dev
Module · 258 functions

arf.h

#include <flint/arf.h>

An arf_t holds a binary floating-point number m⋅2em \cdot 2^e with an integer mantissa mm of any length and an exponent ee of any size, or one of the special values 00, +∞+\infty, −∞-\infty and NaN. It is the type of the midpoint of an arb_t ball, and it can be used on its own as a correctly rounded floating-point type in the style of MPFR. Unlike MPFR, an arf_t has no fixed precision: the precision is a parameter of each operation, the mantissa grows and shrinks as needed, and numbers whose mantissa is short (an integer, a power of two, a double) stay short. Exponents are fmpz integers, so overflow and underflow cannot occur. There is no negative zero, no unsigned infinity and no NaN payload.

The guide Rounding, precision and the inexact flag explains the rounding modes, the inexact flag and the precision argument with examples. The representation is described in Representation of radii and midpoints.

Guides#

Representation and conventions#

An arf_struct has four words: an fmpz exponent, a size field holding the number of limbs of the mantissa and, in its lowest bit, the sign, and two words that store a mantissa of at most two limbs inline or otherwise the allocation size and a pointer to the limbs. Numbers with at most 128 bits (64 bits on a 32-bit system) therefore use no heap memory. A nonzero finite value is stored as ±0.dn−1…d0⋅2exp\pm 0.d_{n-1} \ldots d_0 \cdot 2^{\mathit{exp}} with nn limbs, the top bit of dn−1d_{n-1} set and d0≠0d_0 \ne 0, so the stored exponent exp is the ee with 2e−1≤∣x∣<2e2^{e-1} \le |x| < 2^e. A special value has size zero and the exponent encodes which one it is. arf_t is an array of one arf_struct; arf_ptr and arf_srcptr point to arrays.

A rounding mode: one of ARF_RND_DOWN, ARF_RND_UP, ARF_RND_FLOOR, ARF_RND_CEIL, ARF_RND_NEAR, or one of the relaxed modes ARF_RND_FAST and ARF_RND_ACCURATE.

Round towards zero, away from zero, towards −∞-\infty, towards +∞+\infty, and to the nearest representable number with ties to even.

Relaxed modes, accepted by division, square root and reciprocal square root (arf_div, arf_sqrt, arf_rsqrt and the functions built on them) and by the elementary functions (Elementary functions). The result differs from the exact value by at most one unit in the last place in either direction (ARF_RND_FAST), respectively by at most 0.51 units (ARF_RND_ACCURATE). The return value is the inexact flag, as with the strict modes: it is 0 if and only if the result equals the exact value (for the elementary functions, a 0 flag means an exact result, but an exact result may come with the flag 1; see Elementary functions).

More

A precision (WORD_MAX) meaning that no rounding takes place. It may only be passed to operations whose exact result is a dyadic number, such as addition, multiplication and conversion from integers, and only when that result fits in memory: adding 11 and 2−10122^{-10^{12}} exactly needs 101210^{12} bits. If in doubt, use a large finite precision and check the inexact flag instead.

Unless stated otherwise:

  • A function with prec and rnd arguments that returns int rounds its result to at most prec bits of mantissa in the direction rnd, and the rounding is correct: the result is the exact result of the operation on the exact inputs, rounded once. The return value is 0 if the result is exact and 1 if it was rounded (the inexact flag). The error is less than one unit in the last place for directed rounding and at most half a unit for ARF_RND_NEAR.
  • A function without a precision argument is exact.
  • The precision must be at least 2 bits.
  • Every function allows aliasing between its inputs and its outputs.
  • Special values follow IEEE 754 conventions: 0⋅∞0 \cdot \infty, ∞−∞\infty - \infty, 0/00/0 and −1\sqrt{-1} give NaN, and so does division of a nonzero number by zero, since there is no signed zero to choose the sign of the infinity.

Memory management#

void arf_init(arf_t x)

Initialises x to zero.

Frees the memory used by x.

Allocate a vector of n entries initialised to zero, and free such a vector.

Returns the number of bytes allocated on the heap by x, excluding sizeof(arf_struct).

Special values#

void arf_zero(arf_t x)
void arf_one(arf_t x)
void arf_nan(arf_t x)

Set x to 00, 11, +∞+\infty, −∞-\infty and NaN respectively.

int arf_is_zero(const arf_t x)
int arf_is_one(const arf_t x)
int arf_is_pos_inf(const arf_t x)
int arf_is_neg_inf(const arf_t x)
int arf_is_nan(const arf_t x)
int arf_is_inf(const arf_t x)

Return whether x is 00, 11, +∞+\infty, −∞-\infty, NaN, and ±∞\pm\infty respectively.

int arf_is_normal(const arf_t x)
int arf_is_special(const arf_t x)
int arf_is_finite(const arf_t x)

Return whether x is a finite nonzero number, whether it is one of the special values 00, ±∞\pm\infty, NaN, and whether it is finite (zero included). arf_is_finite is not the negation of arf_is_inf, because of NaN.

Assignment and rounding#

void arf_set(arf_t y, const arf_t x)
void arf_set_mpz(arf_t y, const mpz_t x)
void arf_set_fmpz(arf_t y, const fmpz_t x)
void arf_set_d(arf_t x, double v)
void arf_set_mpfr(arf_t x, const mpfr_t y)

Set the output to the exact value of the input. A double NaN gives NaN and −0.0-0.0 gives 00.

Initialise x and set it to v.

void arf_set_mpn(arf_t y, nn_srcptr x, slong xn, int sgnbit)

Sets y to the integer stored in the xn limbs at x, negated if sgnbit is 1. Requires xn>0\mathit{xn} > 0 and x[xn - 1] nonzero.

void arf_set_fmpz_2exp(arf_t x, const fmpz_t man, const fmpz_t exp)

Set x to man⋅2exp\mathit{man} \cdot 2^{\mathit{exp}} exactly.

void arf_swap(arf_t y, arf_t x)

Swaps x and y without copying.

int arf_set_round(arf_t y, const arf_t x, slong prec, arf_rnd_t rnd)
int arf_set_round_mpz(arf_t y, const mpz_t x, slong prec, arf_rnd_t rnd)
int arf_set_round_fmpz(arf_t y, const fmpz_t x, slong prec, arf_rnd_t rnd)

Set the output to the input rounded to prec bits in the direction rnd, and return the inexact flag.

int arf_set_round_fmpz_2exp(arf_t y, const fmpz_t x, const fmpz_t exp, slong prec, arf_rnd_t rnd)

Sets y to x⋅2expx \cdot 2^{\mathit{exp}} rounded to prec bits in the direction rnd, and returns the inexact flag.

int arf_set_fmpq(arf_t y, const fmpq_t x, slong prec, arf_rnd_t rnd)

Sets y to the rational number x rounded to prec bits in the direction rnd, and returns the inexact flag. This is arf_fmpz_div_fmpz applied to the numerator and denominator.

void arf_neg(arf_t y, const arf_t x)
void arf_abs(arf_t y, const arf_t x)

Set y to −x-x, respectively ∣x∣|x|. Exact.

int arf_neg_round(arf_t y, const arf_t x, slong prec, arf_rnd_t rnd)

Sets y to −x-x rounded to prec bits in the direction rnd, and returns the inexact flag.

void arf_mul_2exp_si(arf_t y, const arf_t x, slong e)
void arf_mul_2exp_fmpz(arf_t y, const arf_t x, const fmpz_t e)

Set y to x⋅2ex \cdot 2^e. Exact. This is the inverse of arf_frexp.

void arf_min(arf_t z, const arf_t a, const arf_t b)
void arf_max(arf_t z, const arf_t a, const arf_t b)

Set z to the smaller, respectively larger, of a and b.

Conversion#

void arf_get_fmpz_2exp(fmpz_t man, fmpz_t exp, const arf_t x)

Sets man and exp to the integers with x=man⋅2expx = \mathit{man} \cdot 2^{\mathit{exp}} and man odd, for finite nonzero x. For x=0x = 0 both are set to 0. The result is undefined for infinite or NaN x.

void arf_frexp(arf_t man, fmpz_t exp, const arf_t x)

Writes x=m⋅2ex = m \cdot 2^e with 1/2≤∣m∣<11/2 \le |m| < 1, setting man to mm and exp to ee. A special value is copied to man, and exp is set to 0.

double arf_get_d(const arf_t x, arf_rnd_t rnd)

Returns x rounded to a double in the direction rnd, with correct rounding also on overflow (to the largest finite double or to ±∞\pm\infty, depending on the direction) and on underflow (to zero or the smallest subnormal).

int arf_get_mpfr(mpfr_t x, const arf_t y, mpfr_rnd_t rnd)

Sets x to y rounded to the precision of x with the MPFR rounding mode rnd, and returns the MPFR ternary value (−1-1, 00 or 11). An exponent outside the current MPFR exponent range gives an infinity or a zero and sets the MPFR overflow or underflow flag.

int arf_get_fmpz(fmpz_t z, const arf_t x, arf_rnd_t rnd)

Sets z to x rounded to an integer in the direction rnd (ties to even for ARF_RND_NEAR), and returns 1 if x is not an integer, 0 otherwise.

More

Returns x rounded to an integer in the direction rnd (ties to even for ARF_RND_NEAR). Raises an exception if x is infinite, NaN, or if the rounded value does not fit in an slong.

int arf_get_fmpz_fixed_fmpz(fmpz_t y, const arf_t x, const fmpz_t e)

Set y to the integer trunc⁡(x/2e)\operatorname{trunc}(x / 2^e), so that y⋅2ey \cdot 2^e is x truncated towards zero to a multiple of 2e2^e, and return 1 if truncation occurred. The size caveats of arf_get_fmpz apply.

void arf_floor(arf_t z, const arf_t x)
void arf_ceil(arf_t z, const arf_t x)
void arf_nint(arf_t z, const arf_t x)

Set z to ⌊x⌋\lfloor x \rfloor, ⌈x⌉\lceil x \rceil and the nearest integer to x with ties to even. The result is exact and never needs more bits than x; round it with arf_set_round if needed.

void arf_get_fmpq(fmpq_t y, const arf_t x)

Sets y to the exact rational value of x. Raises an exception for infinite or NaN x; the size caveats of arf_get_fmpz apply.

Comparison and bounds#

int arf_equal(const arf_t x, const arf_t y)
int arf_equal_si(const arf_t x, slong y)
int arf_equal_ui(const arf_t x, ulong y)
int arf_equal_d(const arf_t x, double y)

Return whether x and y are the same number. Unlike IEEE 754 comparison, NaN is equal to itself. For a double y, both zeros compare equal to 0 and every NaN to NaN.

int arf_cmp(const arf_t x, const arf_t y)
int arf_cmp_si(const arf_t x, slong y)
int arf_cmp_ui(const arf_t x, ulong y)
int arf_cmp_d(const arf_t x, double y)

Return a negative number, zero or a positive number according as x<yx < y, x=yx = y or x>yx > y. If either argument is NaN, the result is 0.

int arf_cmpabs(const arf_t x, const arf_t y)
int arf_cmpabs_ui(const arf_t x, ulong y)
int arf_cmpabs_d(const arf_t x, double y)
int arf_cmpabs_mag(const arf_t x, const mag_t y)
int arf_mag_cmpabs(const mag_t x, const arf_t y)

Compare ∣x∣|x| with ∣y∣|y|, with the same return convention as arf_cmp.

int arf_cmp_2exp_si(const arf_t x, slong e)

Compare xx, respectively ∣x∣|x|, with 2e2^e.

int arf_sgn(const arf_t x)

Returns −1-1, 00 or 11 according to the sign of x, and 0 for NaN.

Returns the number of bits of the odd mantissa of x, that is, the smallest precision at which x is exactly representable, and 0 for a special value.

void arf_bot(fmpz_t e, const arf_t x)

Sets e to the exponent of the lowest nonzero bit of x, that is, to the exponent of arf_get_fmpz_2exp, so that xx is an odd multiple of 2e2^e. Sets e to 0 for a special value.

int arf_is_int(const arf_t x)

Return whether x is an integer, respectively an integer multiple of 2e2^e.

Set b to the smallest integer with ∣x∣<2b|x| < 2^b, respectively ∣x∣≤2b|x| \le 2^b, for finite nonzero x. The result is undefined for special values.

Returns the smallest integer bb with ∣x∣<2b|x| < 2^b, clamped to [−ARF_PREC_EXACT,ARF_PREC_EXACT][-\mathrm{ARF\_PREC\_EXACT}, \mathrm{ARF\_PREC\_EXACT}]. Returns −ARF_PREC_EXACT-\mathrm{ARF\_PREC\_EXACT} for zero and ARF_PREC_EXACT\mathrm{ARF\_PREC\_EXACT} for infinities and NaN.

Conversion to and from mag#

void arf_get_mag(mag_t y, const arf_t x)
void arf_get_mag_lower(mag_t y, const arf_t x)

Set y to an upper, respectively lower, bound for ∣x∣|x|. An infinite or NaN x gives +∞+\infty for the upper bound.

void arf_set_mag(arf_t y, const mag_t x)

Sets y to the value of x. Exact.

void mag_init_set_arf(mag_t y, const arf_t x)

Initialises y and sets it to an upper bound for ∣x∣|x|.

Initialises y to an upper bound for ∣x∣|x|, for finite x whose exponent is small enough for the mag_fast_ functions. Nothing is checked.

void arf_mag_set_ulp(mag_t z, const arf_t y, slong prec)

Sets z to 2e−prec2^{e - \mathit{prec}}, where ee is the exponent of y (2e−1≤∣y∣<2e2^{e-1} \le |y| < 2^e): one unit in the last place of a prec-bit number of the size of y. Raises an exception for a special y.

void arf_mag_add_ulp(mag_t z, const mag_t x, const arf_t y, slong prec)
void arf_mag_fast_add_ulp(mag_t z, const mag_t x, const arf_t y, slong prec)

Set z to an upper bound for x+2e−precx + 2^{e - \mathit{prec}}, with ee the exponent of y. This adds the rounding error of a prec-bit operation with result y to the radius x. The fast version requires small exponents; the other raises an exception for a special y.

Shallow copies#

Initialise the output as a shallow copy of x or of −x-x, sharing its limbs, without allocating memory.

More

Arithmetic#

int arf_add_fmpz(arf_ptr z, arf_srcptr x, const fmpz_t y, slong prec, arf_rnd_t rnd)

Set z to x+yx + y, correctly rounded.

More
int arf_add_fmpz_2exp(arf_ptr z, arf_srcptr x, const fmpz_t y, const fmpz_t exp, slong prec, arf_rnd_t rnd)

Sets z to x+y⋅2expx + y \cdot 2^{\mathit{exp}}, correctly rounded.

int arf_sub_fmpz(arf_ptr z, arf_srcptr x, const fmpz_t y, slong prec, arf_rnd_t rnd)

Set z to x−yx - y, correctly rounded.

int arf_mul_mpz(arf_ptr z, arf_srcptr x, const mpz_t y, slong prec, arf_rnd_t rnd)
int arf_mul_fmpz(arf_ptr z, arf_srcptr x, const fmpz_t y, slong prec, arf_rnd_t rnd)

Set z to xyxy, correctly rounded.

More
int arf_neg_mul(arf_t z, const arf_t x, const arf_t y, slong prec, arf_rnd_t rnd)

Sets z to −xy-xy, correctly rounded.

int arf_addmul_mpz(arf_ptr z, arf_srcptr x, const mpz_t y, slong prec, arf_rnd_t rnd)
int arf_addmul_fmpz(arf_ptr z, arf_srcptr x, const fmpz_t y, slong prec, arf_rnd_t rnd)
int arf_submul_mpz(arf_ptr z, arf_srcptr x, const mpz_t y, slong prec, arf_rnd_t rnd)
int arf_submul_fmpz(arf_ptr z, arf_srcptr x, const fmpz_t y, slong prec, arf_rnd_t rnd)

Set z to z+xyz + xy, respectively z−xyz - xy, with a single rounding (fused multiply-add).

Sets res to xy+zxy + z with a single rounding.

More
int arf_sosq(arf_t z, const arf_t x, const arf_t y, slong prec, arf_rnd_t rnd)

Sets z to x2+y2x^2 + y^2 with a single rounding.

int arf_div_fmpz(arf_ptr z, arf_srcptr x, const fmpz_t y, slong prec, arf_rnd_t rnd)
int arf_fmpz_div(arf_ptr z, const fmpz_t x, arf_srcptr y, slong prec, arf_rnd_t rnd)
int arf_fmpz_div_fmpz(arf_ptr z, const fmpz_t x, const fmpz_t y, slong prec, arf_rnd_t rnd)

Set z to x/yx / y, correctly rounded for the strict modes. Division by zero gives NaN. The relaxed modes ARF_RND_FAST and ARF_RND_ACCURATE are accepted.

More
int arf_sqrt_ui(arf_t z, ulong x, slong prec, arf_rnd_t rnd)
int arf_sqrt_fmpz(arf_t z, const fmpz_t x, slong prec, arf_rnd_t rnd)

Set z to x\sqrt{x}, correctly rounded for the strict modes. A negative x gives NaN. The relaxed modes are accepted.

More

Sets z to 1/x1/\sqrt{x}, correctly rounded for the strict modes. A negative x gives NaN and x=0x = 0 gives +∞+\infty. The relaxed modes are accepted.

More

Sets z to x1/kx^{1/k}, correctly rounded. A negative x gives NaN.

More

Elementary functions#

The elementary functions of arf are correctly rounded in the strict modes and return the inexact flag, like the arithmetic operations; the relaxed modes ARF_RND_FAST and ARF_RND_ACCURATE give results within one resp. 0.51 units in the last place, somewhat faster; their inexact flag is 0 only for an exact result, but arf_pow and arf_exp10 do not look for exact powers in these modes, so that an exact power may come with the flag 1. Any exponents are supported: the arguments and the results may have bignum exponents. Exact precision (ARF_PREC_EXACT) is not supported.

The cost is that of one evaluation at slightly more than prec bits: mantissas of one and two limbs at up to one resp. two limbs of precision are evaluated in registers on 64-bit machines, close to the speed of the nfloat functions, and larger ones by the fixed-point kernels of mp_real, which are also used by nfloat and arb. In the strict modes a hard case, a value very close to a rounding boundary, is rare (of probability about 2−202^{-20}) and costs a few more evaluations; exact results and arguments for which the value is a simple number times 1+δ1 + \delta with a tiny δ\delta (tiny arguments, huge arguments of tanh⁡\tanh, and so on) are recognised and cost nothing. The algorithms are described in Correctly rounded elementary functions and Elementary functions.

int arf_exp(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_expm1(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_exp2(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_exp10(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)

Sets res to exe^x, ex−1e^x - 1, 2x2^x resp. 10x10^x. The results are exact at x=0x = 0, and 2x2^x resp. 10x10^x for an integer xx are exact (and rounded once). Arguments beyond 2max⁡(128,2 prec)2^{\max(128, 2 \, \mathit{prec})} in absolute value (where arb_exp gives up as well) give NaN; within that range the exponent of the result may be a bignum.

int arf_log(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_log2(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_log10(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_log1p(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)

Sets res to log⁡x\log x, log⁡2x\log_2 x, log⁡10x\log_{10} x resp. log⁡(1+x)\log(1 + x). The exact cases are log⁡1=0\log 1 = 0, log⁡2\log_2 of a power of two, log⁡10\log_{10} of a power of ten and log⁡(1+0)=0\log(1 + 0) = 0. A negative argument (below −1-1 for log1p) gives NaN, zero (resp. −1-1) gives −∞-\infty.

int arf_sin(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_cos(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_sin_cos(arf_ptr res1, arf_ptr res2, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_tan(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_cot(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_sec(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_csc(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_sinc(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)

The trigonometric functions, their reciprocals and sinc⁡x=sin⁡(x)/x\operatorname{sinc} x = \sin(x) / x (sinc(0) = 1). arf_sin_cos computes the sine and the cosine together (res1 and res2 must be distinct). The results at x=0x = 0 are exact; infinite arguments, and arguments beyond 2max⁡(65536,4 prec)2^{\max(65536, 4 \, \mathit{prec})} in absolute value, give NaN (as do the poles of cot and csc at zero).

int arf_sin_cos_pi(arf_ptr res1, arf_ptr res2, arf_srcptr x, slong prec, arf_rnd_t rnd)

The trigonometric functions of πx\pi x and sinc⁡(πx)=sin⁡(πx)/(πx)\operatorname{sinc}(\pi x) = \sin(\pi x) / (\pi x). The values at the multiples of 1/21/2 (zeros, ±1\pm 1, poles: NaN) and of tan_pi, cot_pi at the odd multiples of 1/41/4 (±1\pm 1) are exact. The argument is reduced exactly, so there is no magnitude limit (tiny arguments are handled, for any exponent).

int arf_atan(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_asin(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_acos(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_acot(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_asec(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_acsc(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)

The inverse trigonometric functions, their reciprocal versions (acot⁡x=atan⁡(1/x)\operatorname{acot} x = \operatorname{atan}(1/x) with acot⁡(0)=π/2\operatorname{acot}(0) = \pi/2, asec⁡x=acos⁡(1/x)\operatorname{asec} x = \operatorname{acos}(1/x), acsc⁡x=asin⁡(1/x)\operatorname{acsc} x = \operatorname{asin}(1/x), NaN outside their domains), and the first three divided by π\pi. arf_atan2 follows the usual conventions, with atan2⁡(0,x)=0\operatorname{atan2}(0, x) = 0 for x≥0x \ge 0 (including +∞+\infty) and π\pi for x<0x < 0, atan2⁡(y,0)=±π/2\operatorname{atan2}(y, 0) = \pm \pi/2, and the infinities as in C99. The exact cases are the zeros and the dyadic multiples of π\pi of the functions divided by π\pi (e.g. atan_pi⁡(±1)=±1/4\operatorname{atan\_pi}(\pm 1) = \pm 1/4).

int arf_sinh(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_cosh(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_sinh_cosh(arf_ptr res1, arf_ptr res2, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_tanh(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_coth(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_sech(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_csch(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)

The hyperbolic functions and their reciprocals. Exact at x=0x = 0 and at ±∞\pm\infty (sinh: ±∞\pm\infty, cosh: +∞+\infty, tanh, coth: ±1\pm 1, sech, csch: 0); the poles of coth and csch at zero give NaN. sinh, cosh, sech and csch give NaN beyond 2max⁡(128,2 prec)2^{\max(128, 2 \, \mathit{prec})}, like exp.

int arf_asinh(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_acosh(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_atanh(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_acoth(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_asech(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)
int arf_acsch(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)

The inverse hyperbolic functions and their reciprocal versions, composed of log1p, sqrt and the arithmetic of arf like the inverse trigonometric functions. NaN outside the domains (acosh below 1, atanh outside [−1,1][-1, 1] with ±∞\pm\infty at ±1\pm 1, acoth inside (−1,1)(-1, 1) with ±∞\pm\infty at ±1\pm 1, asech outside (0,1](0, 1] with +∞+\infty at 0, acsch at 0).

Sets res to xy=eylog⁡∣x∣x^y = e^{y \log |x|} with the sign of xx for an odd integer yy (a negative xx with a non-integer yy gives NaN). The conventions for the special values are those of C99 (pow): x0=1x^0 = 1 and 1y=11^y = 1 for any xx resp. yy, 0y=00^y = 0 or +∞+\infty, and so on. The result is exact, and reported so, whenever it is a dyadic number (powers of two, integer powers, roots of perfect powers, y=±1/2y = \pm 1/2); the inexact cases are decided by the retries. NaN when ∣ylog⁡∣x∣∣|y \log |x|| reaches the limit of exp.

int arf_const_pi(arf_ptr res, slong prec, arf_rnd_t rnd)
int arf_const_pi_mul_2exp(arf_ptr res, slong k, int neg, slong prec, arf_rnd_t rnd)

Sets res to π\pi, resp. (−1)negπ2k(-1)^{\mathit{neg}} \pi 2^k, correctly rounded (from the tabulated π/4\pi/4 of mp_real).

Sums and dot products#

int arf_sum(arf_t s, arf_srcptr terms, slong len, slong prec, arf_rnd_t rnd)

Sets s to the sum of the len entries of terms with a single rounding, and returns the inexact flag.

More
int arf_dot(arf_t res, const arf_t initial, int subtract, arf_srcptr x, slong xstep, arf_srcptr y, slong ystep, slong len, slong prec, arf_rnd_t rnd)

Sets res to s+(−1)subtract∑i=0len−1xiyis + (-1)^{\mathit{subtract}} \sum_{i=0}^{\mathit{len}-1} x_i y_i with a single rounding, where ss is initial (0 if initial is NULL) and the entries are read with strides xstep and ystep. Returns the inexact flag.

More
void arf_approx_dot(arf_t res, const arf_t initial, int subtract, arf_srcptr x, slong xstep, arf_srcptr y, slong ystep, slong len, slong prec, arf_rnd_t rnd)

Computes the same dot product as arf_dot approximately: the final rounding is in the direction rnd, but the intermediate roundings are not specified, so neither correct rounding nor an error bound is guaranteed. It uses the fixed-point accumulation of arb_dot without the error bound, and is the midpoint computation of arb_approx_dot.

Complex arithmetic#

int arf_complex_mul(arf_t e, arf_t f, const arf_t a, const arf_t b, const arf_t c, const arf_t d, slong prec, arf_rnd_t rnd)
int arf_complex_mul_fallback(arf_t e, arf_t f, const arf_t a, const arf_t b, const arf_t c, const arf_t d, slong prec, arf_rnd_t rnd)

Set e+fi=(a+bi)(c+di)e + fi = (a + bi)(c + di) with both parts correctly rounded. Bit 0 of the return value is the inexact flag of ee and bit 1 that of ff.

More
int arf_complex_sqr(arf_t e, arf_t f, const arf_t a, const arf_t b, slong prec, arf_rnd_t rnd)

Sets e+fi=(a+bi)2e + fi = (a + bi)^2, with the same conventions as arf_complex_mul, but faster.

More

Input and output#

void arf_print(const arf_t x)
void arf_fprint(FILE * file, const arf_t x)

Print the exact value of x as (m * 2^e) with an odd integer mantissa, or as (0), (+inf), (-inf) or (nan), to standard output or to file.

void arf_printd(const arf_t y, slong d)
void arf_fprintd(FILE * file, const arf_t y, slong d)
char * arf_get_str(const arf_t x, slong d)

Print x in decimal with d significant digits, or return such a string (to be freed with flint_free). The decimal conversion is faithful: the error is at most one unit in the last digit.

char * arf_get_str_rnd(const arf_t x, slong d, arf_rnd_t rnd)

Return x in decimal with d significant digits, correctly rounded in the direction rnd, as a string to be freed with flint_free.

void arf_debug(const arf_t x)

Prints the internal fields of x (exponent, size, sign and limbs).

char * arf_dump_str(const arf_t x)
int arf_load_str(arf_t res, const char * data)

arf_dump_str returns a string, to be freed with flint_free, holding the exact value of x as two hexadecimal integers (mantissa and exponent), which arf_load_str reads back exactly. arf_load_str returns nonzero if the string is not in this format.

int arf_dump_file(FILE* stream, const arf_t x)
int arf_load_file(arf_t res, FILE *stream)

Write x to stream in the format of arf_dump_str, and read it back. Both return nonzero on failure. Several values written in sequence must be separated by whitespace.

Random generation#

void arf_randtest(arf_t x, flint_rand_t state, slong bits, slong mag_bits)
void arf_randtest_not_zero(arf_t x, flint_rand_t state, slong bits, slong mag_bits)
void arf_randtest_special(arf_t x, flint_rand_t state, slong bits, slong mag_bits)

Set x to a random finite number with a mantissa of at most bits bits and an exponent of at most mag_bits bits, with a non-uniform distribution that favours corner cases. The second version never returns zero; the third sometimes returns ±∞\pm\infty or NaN.

void arf_urandom(arf_t x, flint_rand_t state, slong bits, arf_rnd_t rnd)

Sets x to a uniformly distributed random number in [0,1][0, 1] with bits bits, obtained by rounding a random integer in the direction rnd.

Rounding helpers#

int arf_rounds_down(arf_rnd_t rnd, int sgnbit)
int arf_rounds_up(arf_rnd_t rnd, int sgnbit)

Return whether the strict mode rnd rounds a number with sign bit sgnbit (1 for negative) towards zero, respectively away from zero. Both return 0 for ARF_RND_NEAR.

mpfr_rnd_t arf_rnd_to_mpfr(arf_rnd_t rnd)

Returns the MPFR rounding mode corresponding to rnd (MPFR_RNDZ, MPFR_RNDA, MPFR_RNDD, MPFR_RNDU, and MPFR_RNDN for any other mode). Available only if mpfr.h is included before arf.h.

Returns the strict mode by which the standard algorithms implement a relaxed mode: ARF_RND_DOWN for ARF_RND_FAST and ARF_RND_NEAR for ARF_RND_ACCURATE. Other modes are returned unchanged.

Internal functions#

These functions are used to implement the module and ball arithmetic. Their interfaces may change.

void arf_mul_special(arf_t z, const arf_t x, const arf_t y)

Sets z to xyxy when at least one of x and y is a special value.

The implementations of arf_mul: for any rounding mode, and for ARF_RND_DOWN.

Whether the product of mantissas of xn and yn limbs of which the top n limbs are wanted is computed in full rather than as a high product: small products (up to ARF_MUL_FULL_SMALL = 64 limb products), and the shapes for which the general high product would form the full product anyway (_flint_mpn_mulhigh_prefer_full).

int _arf_set_round_ui(arf_t x, ulong v, int sgnbit, slong prec, arf_rnd_t rnd)

Sets x to ±v\pm v (negative if sgnbit is 1) rounded to prec bits.

int _arf_set_round_uiui(arf_t z, slong * fix, ulong hi, ulong lo, int sgnbit, slong prec, arf_rnd_t rnd)

Sets the mantissa of z to the two-limb value (hi,lo)(\mathit{hi}, \mathit{lo}), negated if sgnbit is 1, rounded to prec bits. Requires a nonzero value. Writes the exponent shift to fix without setting the exponent of z.

int _arf_set_round_mpn(arf_t y, slong * exp_shift, nn_srcptr x, slong xn, int sgnbit, slong prec, arf_rnd_t rnd)

Sets the mantissa of y to the xn limbs at x (top limb nonzero), negated if sgnbit is 1, rounded to prec bits, and returns the inexact flag. Writes the exponent shift caused by leading zero bits and by rounding up to a power of two to exp_shift without setting the exponent of y. x may point into the limbs of y.

int _arf_set_mpn_fixed(arf_t z, nn_srcptr xp, slong xn, slong fixn, int negative, slong prec, arf_rnd_t rnd)

Sets z to the fixed-point number with xn limbs of which fixn are fractional, negated if negative is set, rounded to prec bits.

Writes the integer part of the number with mantissa (x,xn)(x, \mathit{xn}) (top bit set, x[0] nonzero) and exponent exp to y, using exactly as many limbs as needed, and returns whether a fractional part was discarded.

int _arf_add_mpn(arf_t z, nn_srcptr xp, slong xn, int xsgnbit, const fmpz_t xexp, nn_srcptr yp, slong yn, int ysgnbit, flint_bitcnt_t shift, slong prec, arf_rnd_t rnd)

Adds two mantissas, the second shifted right by shift bits relative to the first, which has exponent xexp, and rounds the result into z. This is the kernel of arf_add.

int _arf_call_mpfr_func(arf_ptr r1, arf_ptr r2, int (*func)(void), arf_srcptr x, arf_srcptr y, slong prec, arf_rnd_t rnd)

Evaluates the MPFR function func (cast to a generic function pointer) on x (and y, if not NULL) at precision prec, writing one result or, if r2 is not NULL, two results. Returns the MPFR ternary value.

Switch the mantissa storage of x to a heap array of n limbs, and back to inline storage.

void _arf_set_mpn_canonical(arf_ptr z, slong n, int sgnbit)

Set the mantissa of z from the n normalised limbs a kernel wrote at the start of its buffer (allocated with ARF_GET_MPN_WRITE for at least n limbs), respectively from the limbs d in scratch: zero low limbs are stripped and a result of two or fewer limbs moves into the inline limbs, so that z is in canonical form. The exponent is left for the caller. ARF_KERNEL_DECL, ARF_KERNEL_ALLOC(zd, alloc, z, x, y) and ARF_KERNEL_FINISH(z, zd, n, sgnbit) wrap the buffer management for a kernel writing alloc limbs into z: the buffer of z itself, unless z is one of the operands x, y or the result may be short enough for the inline limbs, in which case the kernel works in scratch and the result is copied.

Limb-array kernels#

The arithmetic of long mantissas is done by kernels on limb arrays, shared with nfloat and acf. A mantissa is a normalised limb array {x,xn}\{x, \mathit{xn}\} (top bit set), standing for the value

x⋅2e−xn⋅FLINT_BITSx \cdot 2^{e - \mathit{xn} \cdot \mathtt{FLINT\_BITS}}

for an exponent ee which stays with the caller, as does the sign. A kernel writes its result into {z,rn}\{z, \mathit{rn}\} with rn=⌈prec/FLINT_BITS⌉\mathit{rn} = \lceil \mathit{prec} / \mathtt{FLINT\_BITS} \rceil limbs, normalised with the bits below prec zero, and sets *zexp to the correction of the natural exponent of the operation (ex−eye_x - e_y for a quotient, and so on); the caller adds it to that exponent. The rounded kernels take a sign-free mode (ARF_RND_DOWN, ARF_RND_UP or ARF_RND_NEAR; _arf_rnd_resolve gives it) and return the inexact flag: inside, they form an approximation with a guard limb, round it when the guard limb certifies that the exact value rounds the same way, and compute the exact value otherwise. The _approx kernels write rn\mathit{rn} limbs within an ulp of the magnitude of the result and nothing else: the form for nfloat, which rounds nothing. No kernel allocates memory visibly: scratch beyond a small stack buffer (ARF_MPN_STACK_LIMBS limbs, ARF_MPN_TMP_DECL, ARF_MPN_TMP_ALLOC) comes from a thread-local buffer (_arf_mpn_tmp, one buffer, not for nested use within the kernels).

The sign-free strict mode rounding a value of sign bit sgnbit in the mode rnd: ARF_RND_FLOOR and ARF_RND_CEIL become ARF_RND_DOWN or ARF_RND_UP, the relaxed modes become the strict modes of arf_rnd_relaxed_to_strict, and the others are returned as they are.

int _arf_mpn_set_round(nn_ptr res, slong * exp, nn_srcptr x, slong xn, slong prec, arf_rnd_t rnd)

Rounds the exact value (x/Bxn)2E(x / B^{\mathit{xn}}) 2^E, where x has a nonzero top limb (leading zero bits allowed), to prec bits in the sign-free mode rnd, writing the rn\mathit{rn} normalised limbs res with the bits below prec zero: the result is (res/Brn)2E+exp(\mathit{res} / B^{\mathit{rn}}) 2^{E + \mathit{exp}}. Returns the inexact flag. res may be x or lie below it in the same buffer (in-place rounding; then xn≥rn\mathit{xn} \ge \mathit{rn}).

int _arf_mpn_round_guarded(nn_ptr res, slong * exp, nn_srcptr a, slong n, ulong g, int e, slong prec, arf_rnd_t rnd, int side)

Given the nn normalised limbs a and the limb g below them, which together approximate a value to within 2e2^e ulps of g (in either direction for side = 0, strictly above the approximation for side = 1, strictly below it for side = −1-1), rounds the value to prec≤n⋅FLINT_BITS\mathit{prec} \le n \cdot \mathtt{FLINT\_BITS} bits when the guard limb certifies the rounding: writes the ⌈prec/FLINT_BITS⌉\lceil \mathit{prec} / \mathtt{FLINT\_BITS} \rceil limbs to res (which may be a, or lie below it in the same buffer), sets exp to the change of the exponent (−1-1, 0 or 1) and returns 1, the value being inexact. Returns −1-1 when the window does not certify the rounding; the exact value must then be computed.

More

Whether rounding {a,an}\{a, \mathit{an}\} (an approximation of a value PP within 2e2^e units of a0a_0, on either side) to prec bits gives the same result as rounding PP, in every strict rounding mode, with PP inexact: the bits of a from bit ee of its lowest limb up to the bit below the rounding point (at most one limb of them) are neither all zero nor all ones. The same argument as above, for an approximation whose error band is given by a bit position rather than a guard limb.

The rn\mathit{rn} normalised limbs res, whose bits below sb are zero, moved up or down by one unit of 2sb2^{\mathit{sb}}. The increment returns the carry (1 when the result is a power of two, with the exponent increased); the decrement returns −1-1 when res was a power of two, the result being the rn⋅FLINT_BITS−sb\mathit{rn} \cdot \mathtt{FLINT\_BITS} - \mathit{sb} ones just below it, normalised (the exponent decreases), else 0.

void _arf_mpn_mul_approx(nn_ptr z, slong * zexp, nn_srcptr x, slong xn, nn_srcptr y, slong yn, slong prec)

The product xyxy truncated to rn\mathit{rn} limbs, within an ulp of rn\mathit{rn} limbs: the exact product when it fits or the shape prefers it (_arf_mul_prefer_full), else the normalised high product with its guard limb dropped. z must not alias an operand.

int _arf_mpn_div(nn_ptr z, slong * zexp, nn_srcptr x, slong xn, nn_srcptr y, slong yn, slong prec, arf_rnd_t rnd)
int _arf_mpn_inv(nn_ptr z, slong * zexp, nn_srcptr y, slong yn, slong prec, arf_rnd_t rnd)
int _arf_mpn_sqrt(nn_ptr z, slong * zexp, nn_srcptr x, slong xn, int t, slong prec, arf_rnd_t rnd)
int _arf_mpn_rsqrt(nn_ptr z, slong * zexp, nn_srcptr x, slong xn, int t, slong prec, arf_rnd_t rnd)

The quotient x/yx / y, the reciprocal 1/y1 / y, the square root of xx and its reciprocal, correctly rounded to prec bits in the sign-free mode rnd into {z,rn}\{z, \mathit{rn}\}, returning the inexact flag, with *zexp the correction to the natural exponent: ex−eye_x - e_y for the quotient (the correction 0 or 1), −ey-e_y for the reciprocal (1 or 2), and for the roots of x=A⋅2ex = A \cdot 2^e with t=e mod 2t = e \bmod 2 given, (e+t)/2(e + t) / 2 for x\sqrt{x} and (1−t)−(e−t)/2(1 - t) - (e - t) / 2 for 1/x1 / \sqrt{x} (the corrections 0 or 1).

The output may alias an operand. Zero low limbs of the mantissas (nfloat pads its mantissas to a fixed length) are stripped first, so that integers and other short operands take the fast paths.

More
void _arf_mpn_div_approx(nn_ptr z, slong * zexp, nn_srcptr x, slong xn, nn_srcptr y, slong yn, slong prec)
void _arf_mpn_inv_approx(nn_ptr z, slong * zexp, nn_srcptr y, slong yn, slong prec)
void _arf_mpn_sqrt_approx(nn_ptr z, slong * zexp, nn_srcptr x, slong xn, int t, slong prec)
void _arf_mpn_rsqrt_approx(nn_ptr z, slong * zexp, nn_srcptr x, slong xn, int t, slong prec)

As above, but the rn\mathit{rn} limbs are written without rounding and without a flag (the kernels of nfloat without directed rounding): the quotients are the truncation or one ulp more (an error below an ulp, up to the truncation of operands beyond rn+2\mathit{rn} + 2 limbs; the truncation itself for a divisor with a single nonzero limb), the square root is the truncation, and the reciprocal square root is within 1+2−371 + 2^{-37} ulp.

More
void _arf_mpn_cinv_approx(nn_ptr re, slong * reexp, nn_ptr im, slong * imexp, nn_srcptr a, slong an, slong ea, nn_srcptr b, slong bn, slong eb, slong prec)
void _arf_mpn_cdiv_approx(nn_ptr re, slong * reexp, int * reneg, nn_ptr im, slong * imexp, int * imneg, nn_srcptr a, slong an, slong ea, int sa, nn_srcptr b, slong bn, slong eb, int sb, nn_srcptr c, slong cn, slong ec, int sc, nn_srcptr d, slong dn, slong ed, int sd, slong prec)
void _arf_mpn_csqrt_approx(nn_ptr re, slong * reexp, nn_ptr im, slong * imexp, nn_srcptr a, slong an, slong ea, int sa, nn_srcptr b, slong bn, slong eb, slong prec)
void _arf_mpn_crsqrt_approx(nn_ptr re, slong * reexp, nn_ptr im, slong * imexp, nn_srcptr a, slong an, slong ea, int sa, nn_srcptr b, slong bn, slong eb, slong prec)

The reciprocal, the quotient, the square root and the reciprocal square root of complex numbers given as mantissa/exponent pairs: a part is {a,an} 2ea−anB\{a, \mathit{an}\} \, 2^{e_a - \mathit{an} B} with a normalised mantissa, a nonzero magnitude and an slong exponent far from overflow (the callers scale extreme operands). The _approx flavour writes rn\mathit{rn} limbs per part, each within about an ulp of the magnitude of the result (the parts truncated), with the exponents of the parts (WORD_MIN for an exactly cancelled part of the quotient); the outputs are the magnitudes of the parts, the signs being the caller's unless stated. The reciprocal is (a−bi)t(a - b i) t with t=1/(a2+b2)t = 1/(a^2 + b^2), written as ata t and btb t. The quotient (a+bi)/(c+di)=(u+vi)t(a + b i)/(c + d i) = (u + v i) t with u=ac+bdu = a c + b d, v=bc−adv = b c - a d and t=1/(c2+d2)t = 1/(c^2 + d^2) takes the signs of the operands and returns those of the parts. The square root is (q,b/(2q))(q, b/(2q)) with q=(∣z∣+∣a∣)/2q = \sqrt{(|z| + |a|)/2} for a≥0a \ge 0 and (∣b∣/(2q),q)(|b|/(2q), q) for a<0a < 0 (the imaginary part has the sign of bb); the reciprocal square root is (Tv,bv)(T v, b v) resp. (bv,Tv)(b v, T v) with T=∣z∣+∣a∣T = |z| + |a| and v=1/2∣z∣2Tv = 1/\sqrt{2 |z|^2 T} (the imaginary part has the sign opposite to bb). The outputs may alias the operands' limbs.

More

Free the thread-local scratch space of multiplication and addition; registered with flint_register_cleanup_function and called by flint_cleanup.

Cite this page

The FLINT team, “arf.h (module overview),” FLINT: Fast Library for Number Theory, documentation, version 3.7.0-dev, 2026. https://flintlib.org/doc/arf/index.html (generated 2026-11-20).