arf.h
#include <flint/arf.h>An arf_t holds a binary floating-point number with an integer mantissa of any length and an exponent of any size, or one of the special values , , 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 with limbs, the top bit of set and , so the stored exponent exp is the with . 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 , towards , 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).
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 and exactly needs bits. If in doubt, use a large finite precision and check the inexact flag instead.
Unless stated otherwise:
- A function with
precandrndarguments that returnsintrounds its result to at mostprecbits of mantissa in the directionrnd, 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 forARF_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: , , and 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_vec_clear(arf_ptr v, slong n)Allocate a vector of n entries initialised to zero, and free such a vector.
slong arf_allocated_bytes(const arf_t x)Returns the number of bytes allocated on the heap by x, excluding sizeof(arf_struct).
Special values#
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 , , , , NaN, and 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 , , 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_ui(arf_t x, ulong v)void arf_set_si(arf_t x, slong v)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_mpfr(arf_t x, const mpfr_t y)Set the output to the exact value of the input. A double NaN gives NaN and gives .
void arf_init_set_ui(arf_t x, ulong v)void arf_init_set_si(arf_t x, slong v)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 and x[xn - 1] nonzero.
void arf_set_si_2exp_si(arf_t x, slong man, slong exp)void arf_set_ui_2exp_si(arf_t x, ulong man, slong exp)void arf_set_fmpz_2exp(arf_t x, const fmpz_t man, const fmpz_t exp)Set x to exactly.
int arf_set_round(arf_t y, const arf_t x, slong prec, arf_rnd_t rnd)int arf_set_round_si(arf_t x, slong v, slong prec, arf_rnd_t rnd)int arf_set_round_ui(arf_t x, ulong v, 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.
Sets y to 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.
Set y to , respectively . Exact.
int arf_neg_round(arf_t y, const arf_t x, slong prec, arf_rnd_t rnd)Sets y to 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 . Exact. This is the inverse of arf_frexp.
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 and man odd, for finite nonzero x. For both are set to 0. The result is undefined for infinite or NaN x.
Writes with , setting man to and exp to . A special value is copied to man, and exp is set to 0.
Returns x rounded to a double in the direction rnd, with correct rounding also on overflow (to the largest finite double or to , 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 (, or ). 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.
slong arf_get_si(const arf_t x, arf_rnd_t rnd)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)int arf_get_fmpz_fixed_si(fmpz_t y, const arf_t x, slong e)Set y to the integer , so that is x truncated towards zero to a multiple of , and return 1 if truncation occurred. The size caveats of arf_get_fmpz apply.
Set z to , 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_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_si(const arf_t x, slong y)int arf_cmp_ui(const arf_t x, ulong y)Return a negative number, zero or a positive number according as , or . 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 with , with the same return convention as arf_cmp.
int arf_cmp_2exp_si(const arf_t x, slong e)int arf_cmpabs_2exp_si(const arf_t x, slong e)Compare , respectively , with .
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.
Sets e to the exponent of the lowest nonzero bit of x, that is, to the exponent of arf_get_fmpz_2exp, so that is an odd multiple of . Sets e to 0 for a special value.
int arf_is_int(const arf_t x)int arf_is_int_2exp_si(const arf_t x, slong e)Return whether x is an integer, respectively an integer multiple of .
void arf_abs_bound_lt_2exp_fmpz(fmpz_t b, const arf_t x)void arf_abs_bound_le_2exp_fmpz(fmpz_t b, const arf_t x)Set b to the smallest integer with , respectively , for finite nonzero x. The result is undefined for special values.
slong arf_abs_bound_lt_2exp_si(const arf_t x)Returns the smallest integer with , clamped to . Returns for zero and 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 . An infinite or NaN x gives 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 .
void mag_fast_init_set_arf(mag_t y, const arf_t x)Initialises y to an upper bound for , 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 , where is the exponent of y (): 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 , with 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#
void arf_init_set_shallow(arf_t z, const arf_t x)void arf_init_set_mag_shallow(arf_t y, const mag_t x)void arf_init_neg_shallow(arf_t z, const arf_t x)void arf_init_neg_mag_shallow(arf_t z, const mag_t x)Initialise the output as a shallow copy of x or of , sharing its limbs, without allocating memory.
Arithmetic#
int arf_add(arf_ptr z, arf_srcptr x, arf_srcptr y, slong prec, arf_rnd_t rnd)int arf_add_si(arf_ptr z, arf_srcptr x, slong y, slong prec, arf_rnd_t rnd)int arf_add_ui(arf_ptr z, arf_srcptr x, ulong y, slong prec, arf_rnd_t rnd)int arf_add_fmpz(arf_ptr z, arf_srcptr x, const fmpz_t y, slong prec, arf_rnd_t rnd)Set z to , correctly rounded.
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 , correctly rounded.
int arf_sub(arf_ptr z, arf_srcptr x, arf_srcptr y, slong prec, arf_rnd_t rnd)int arf_sub_si(arf_ptr z, arf_srcptr x, slong y, slong prec, arf_rnd_t rnd)int arf_sub_ui(arf_ptr z, arf_srcptr x, ulong y, slong prec, arf_rnd_t rnd)int arf_sub_fmpz(arf_ptr z, arf_srcptr x, const fmpz_t y, slong prec, arf_rnd_t rnd)Set z to , correctly rounded.
int arf_mul(arf_ptr z, arf_srcptr x, arf_srcptr y, slong prec, arf_rnd_t rnd)int arf_mul_ui(arf_ptr z, arf_srcptr x, ulong y, slong prec, arf_rnd_t rnd)int arf_mul_si(arf_ptr z, arf_srcptr x, slong y, slong prec, arf_rnd_t rnd)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 , correctly rounded.
Sets z to , correctly rounded.
int arf_addmul(arf_ptr z, arf_srcptr x, arf_srcptr y, slong prec, arf_rnd_t rnd)int arf_addmul_ui(arf_ptr z, arf_srcptr x, ulong y, slong prec, arf_rnd_t rnd)int arf_addmul_si(arf_ptr z, arf_srcptr x, slong y, slong prec, arf_rnd_t rnd)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(arf_ptr z, arf_srcptr x, arf_srcptr y, slong prec, arf_rnd_t rnd)int arf_submul_ui(arf_ptr z, arf_srcptr x, ulong y, slong prec, arf_rnd_t rnd)int arf_submul_si(arf_ptr z, arf_srcptr x, slong 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 , respectively , with a single rounding (fused multiply-add).
int arf_fma(arf_ptr res, arf_srcptr x, arf_srcptr y, arf_srcptr z, slong prec, arf_rnd_t rnd)Sets res to with a single rounding.
Sets z to with a single rounding.
int arf_div(arf_ptr z, arf_srcptr x, arf_srcptr y, slong prec, arf_rnd_t rnd)int arf_div_ui(arf_ptr z, arf_srcptr x, ulong y, slong prec, arf_rnd_t rnd)int arf_ui_div(arf_ptr z, ulong x, arf_srcptr y, slong prec, arf_rnd_t rnd)int arf_div_si(arf_ptr z, arf_srcptr x, slong y, slong prec, arf_rnd_t rnd)int arf_si_div(arf_ptr z, slong x, arf_srcptr y, slong prec, arf_rnd_t rnd)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)Set z to , correctly rounded for the strict modes. Division by zero gives NaN. The relaxed modes ARF_RND_FAST and ARF_RND_ACCURATE are accepted.
int arf_sqrt(arf_ptr z, arf_srcptr x, slong prec, arf_rnd_t rnd)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 , correctly rounded for the strict modes. A negative x gives NaN. The relaxed modes are accepted.
int arf_rsqrt(arf_ptr z, arf_srcptr x, slong prec, arf_rnd_t rnd)Sets z to , correctly rounded for the strict modes. A negative x gives NaN and gives . The relaxed modes are accepted.
Sets z to , correctly rounded. A negative x gives NaN.
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 ) and costs a few more evaluations; exact results and arguments for which the value is a simple number times with a tiny (tiny arguments, huge arguments of , 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 , , resp. . The results are exact at , and resp. for an integer are exact (and rounded once). Arguments beyond 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 , , resp. . The exact cases are , of a power of two, of a power of ten and . A negative argument (below for log1p) gives NaN, zero (resp. ) gives .
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(0) = 1). arf_sin_cos computes the sine and the cosine together (res1 and res2 must be distinct). The results at are exact; infinite arguments, and arguments beyond in absolute value, give NaN (as do the poles of cot and csc at zero).
int arf_sin_pi(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)int arf_cos_pi(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)int arf_sin_cos_pi(arf_ptr res1, arf_ptr res2, arf_srcptr x, slong prec, arf_rnd_t rnd)int arf_tan_pi(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)int arf_cot_pi(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)int arf_sec_pi(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)int arf_csc_pi(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)int arf_sinc_pi(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)The trigonometric functions of and . The values at the multiples of (zeros, , poles: NaN) and of tan_pi, cot_pi at the odd multiples of () 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_atan2(arf_ptr res, arf_srcptr y, 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)int arf_atan_pi(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)int arf_asin_pi(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)int arf_acos_pi(arf_ptr res, arf_srcptr x, slong prec, arf_rnd_t rnd)The inverse trigonometric functions, their reciprocal versions ( with , , , NaN outside their domains), and the first three divided by . arf_atan2 follows the usual conventions, with for (including ) and for , , and the infinities as in C99. The exact cases are the zeros and the dyadic multiples of of the functions divided by (e.g. ).
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 and at (sinh: , cosh: , tanh, coth: , sech, csch: 0); the poles of coth and csch at zero give NaN. sinh, cosh, sech and csch give NaN beyond , 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 with at , acoth inside with at , asech outside with at 0, acsch at 0).
int arf_pow(arf_ptr res, arf_srcptr x, arf_srcptr y, slong prec, arf_rnd_t rnd)Sets res to with the sign of for an odd integer (a negative with a non-integer gives NaN). The conventions for the special values are those of C99 (pow): and for any resp. , or , 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, ); the inexact cases are decided by the retries. NaN when 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 , resp. , correctly rounded (from the tabulated of mp_real).
Sums and dot products#
Sets s to the sum of the len entries of terms with a single rounding, and returns the inexact flag.
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 with a single rounding, where is initial (0 if initial is NULL) and the entries are read with strides xstep and ystep. Returns the inexact flag.
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 with both parts correctly rounded. Bit 0 of the return value is the inexact flag of and bit 1 that of .
MoreSets , with the same conventions as arf_complex_mul, but faster.
Input and output#
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.
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 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 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 when at least one of x and y is a special value.
int arf_mul_rnd_any(arf_ptr z, arf_srcptr x, arf_srcptr y, slong prec, arf_rnd_t rnd)int arf_mul_rnd_down(arf_ptr z, arf_srcptr x, arf_srcptr y, slong prec)The implementations of arf_mul: for any rounding mode, and for ARF_RND_DOWN.
int _arf_mul_prefer_full(slong xn, slong yn, slong n)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 (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 , 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.
int _arf_get_integer_mpn(nn_ptr y, nn_srcptr x, slong xn, slong exp)Writes the integer part of the number with mantissa (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.
void _arf_promote(arf_t x, slong n)void _arf_demote(arf_t x)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)void _arf_set_mpn_canonical_copy(arf_ptr z, nn_srcptr d, 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 (top bit set), standing for the value
for an exponent which stays with the caller, as does the sign. A kernel writes its result into with limbs, normalised with the bits below prec zero, and sets *zexp to the correction of the natural exponent of the operation ( 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 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).
arf_rnd_t _arf_rnd_resolve(arf_rnd_t rnd, int sgnbit)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.
Rounds the exact value , where x has a nonzero top limb (leading zero bits allowed), to prec bits in the sign-free mode rnd, writing the normalised limbs res with the bits below prec zero: the result is . Returns the inexact flag. res may be x or lie below it in the same buffer (in-place rounding; then ).
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 normalised limbs a and the limb g below them, which together approximate a value to within ulps of g (in either direction for side = 0, strictly above the approximation for side = 1, strictly below it for side = ), rounds the value to bits when the guard limb certifies the rounding: writes the limbs to res (which may be a, or lie below it in the same buffer), sets exp to the change of the exponent (, 0 or 1) and returns 1, the value being inexact. Returns when the window does not certify the rounding; the exact value must then be computed.
int _arf_rounding_certain(nn_srcptr a, slong an, slong e, slong prec)Whether rounding (an approximation of a value within units of , on either side) to prec bits gives the same result as rounding , in every strict rounding mode, with inexact: the bits of a from bit 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.
int _arf_mpn_increment(nn_ptr res, slong rn, slong sb)int _arf_mpn_decrement(nn_ptr res, slong rn, slong sb)The normalised limbs res, whose bits below sb are zero, moved up or down by one unit of . The increment returns the carry (1 when the result is a power of two, with the exponent increased); the decrement returns when res was a power of two, the result being the 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 truncated to limbs, within an ulp of 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)The quotient , the reciprocal , the square root of and its reciprocal, correctly rounded to prec bits in the sign-free mode rnd into , returning the inexact flag, with *zexp the correction to the natural exponent: for the quotient (the correction 0 or 1), for the reciprocal (1 or 2), and for the roots of with given, for and for (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.
Morevoid _arf_mpn_div_approx(nn_ptr z, slong * zexp, nn_srcptr x, slong xn, nn_srcptr y, slong yn, slong prec)As above, but the 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 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 ulp.
Morevoid _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 with a normalised mantissa, a nonzero magnitude and an slong exponent far from overflow (the callers scale extreme operands). The _approx flavour writes 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 with , written as and . The quotient with , and takes the signs of the operands and returns those of the parts. The square root is with for and for (the imaginary part has the sign of ); the reciprocal square root is resp. with and (the imaginary part has the sign opposite to ). The outputs may alias the operands' limbs.
void _arf_mul_tmp_cleanup(void)void _arf_add_tmp_cleanup(void)Free the thread-local scratch space of multiplication and addition; registered with flint_register_cleanup_function and called by flint_cleanup.
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).
@misc{flint-doc-arf-index,
author = {{The FLINT team}},
title = {{arf.h (module overview)}},
howpublished = {FLINT: Fast Library for Number Theory, documentation, version 3.7.0-dev},
year = {2026},
url = {https://flintlib.org/doc/arf/index.html},
note = {Generated 2026-11-20}
}