fmprb.h – real numbers represented as floating-point balls

This type is now obsolete: use arb_t instead.

An fmprb_t represents a ball over the real numbers.

Types, macros and constants

fmprb_struct
fmprb_t

An fmprb_struct consists of a pair of fmpr_struct:s. An fmprb_t is defined as an array of length one of type fmprb_struct, permitting an fmprb_t to be passed by reference.

fmprb_ptr

Alias for fmprb_struct *, used for vectors of numbers.

fmprb_srcptr

Alias for const fmprb_struct *, used for vectors of numbers when passed as constant input to functions.

FMPRB_RAD_PREC

The precision used for operations on the radius. This is small enough to fit in a single word, currently 30 bits.

fmprb_midref(x)

Macro returning a pointer to the midpoint of x as an fmpr_t.

fmprb_radref(x)

Macro returning a pointer to the radius of x as an fmpr_t.

Memory management

void fmprb_init(fmprb_t x)

Initializes the variable x for use. Its midpoint and radius are both set to zero.

void fmprb_clear(fmprb_t x)

Clears the variable x, freeing or recycling its allocated memory.

fmprb_ptr _fmprb_vec_init(slong n)

Returns a pointer to an array of n initialized fmprb_struct:s.

void _fmprb_vec_clear(fmprb_ptr v, slong n)

Clears an array of n initialized fmprb_struct:s.

Assignment and rounding

void fmprb_set(fmprb_t y, const fmprb_t x)

Sets y to a copy of x.

void fmprb_set_round(fmprb_t y, const fmprb_t x, slong prec)

Sets y to a copy of x, rounded to prec bits.

void fmprb_set_fmpr(fmprb_t y, const fmpr_t x)
void fmprb_set_si(fmprb_t y, slong x)
void fmprb_set_ui(fmprb_t y, ulong x)
void fmprb_set_fmpz(fmprb_t y, const fmpz_t x)

Sets y exactly to x.

void fmprb_set_fmpq(fmprb_t y, const fmpq_t x, slong prec)

Sets y to the rational number x, rounded to prec bits.

void fmprb_set_fmpz_2exp(fmprb_t x, const fmpz_t y, const fmpz_t exp)

Sets x to y multiplied by 2 raised to the power exp.

void fmprb_set_round_fmpz_2exp(fmprb_t y, const fmpz_t x, const fmpz_t exp, slong prec)

Sets x to y multiplied by 2 raised to the power exp, rounding the result to prec bits.

Assignment of special values

void fmprb_zero(fmprb_t x)

Sets x to zero.

void fmprb_one(fmprb_t x)

Sets x to the exact integer 1.

void fmprb_pos_inf(fmprb_t x)

Sets x to positive infinity, with a zero radius.

void fmprb_neg_inf(fmprb_t x)

Sets x to negative infinity, with a zero radius.

void fmprb_zero_pm_inf(fmprb_t x)

Sets x to \([0 \pm \infty]\), representing the whole extended real line.

void fmprb_indeterminate(fmprb_t x)

Sets x to \([\operatorname{NaN} \pm \infty]\), representing an indeterminate result.

Input and output

void fmprb_print(const fmprb_t x)

Prints the internal representation of x.

void fmprb_printd(const fmprb_t x, slong digits)

Prints x in decimal. The printed value of the radius is not adjusted to compensate for the fact that the binary-to-decimal conversion of both the midpoint and the radius introduces additional error.

Random number generation

void fmprb_randtest(fmprb_t x, flint_rand_t state, slong prec, slong mag_bits)

Generates a random ball. The midpoint and radius will both be finite.

void fmprb_randtest_exact(fmprb_t x, flint_rand_t state, slong prec, slong mag_bits)

Generates a random number with zero radius.

void fmprb_randtest_precise(fmprb_t x, flint_rand_t state, slong prec, slong mag_bits)

Generates a random number with radius at most \(2^{-\mathrm{prec}}\) the magnitude of the midpoint.

void fmprb_randtest_wide(fmprb_t x, flint_rand_t state, slong prec, slong mag_bits)

Generates a random number with midpoint and radius chosen independently, possibly giving a very large interval.

void fmprb_randtest_special(fmprb_t x, flint_rand_t state, slong prec, slong mag_bits)

Generates a random interval, possibly having NaN or an infinity as the midpoint and possibly having an infinite radius.

void fmprb_get_rand_fmpq(fmpq_t q, flint_rand_t state, const fmprb_t x, slong bits)

Sets q to a random rational number from the interval represented by x. A denominator is chosen by multiplying the binary denominator of x by a random integer up to bits bits.

The outcome is undefined if the midpoint or radius of x is non-finite, or if the exponent of the midpoint or radius is so large or small that representing the endpoints as exact rational numbers would cause overflows.

Radius and interval operations

void fmprb_add_error_fmpr(fmprb_t x, const fmpr_t err)

Adds err, which is assumed to be nonnegative, to the radius of x.

void fmprb_add_error_2exp_si(fmprb_t x, slong e)
void fmprb_add_error_2exp_fmpz(fmprb_t x, const fmpz_t e)

Adds \(2^e\) to the radius of x.

void fmprb_add_error(fmprb_t x, const fmprb_t err)

Adds the supremum of err, which is assumed to be nonnegative, to the radius of x.

void fmprb_union(fmprb_t z, const fmprb_t x, const fmprb_t y, slong prec)

Sets z to a ball containing both x and y.

void fmprb_get_abs_ubound_fmpr(fmpr_t u, const fmprb_t x, slong prec)

Sets u to the upper bound of the absolute value of x, rounded up to prec bits. If x contains NaN, the result is NaN.

void fmprb_get_abs_lbound_fmpr(fmpr_t u, const fmprb_t x, slong prec)

Sets u to the lower bound of the absolute value of x, rounded down to prec bits. If x contains NaN, the result is NaN.

void fmprb_get_interval_fmpz_2exp(fmpz_t a, fmpz_t b, fmpz_t exp, const fmprb_t x)

Computes the exact interval represented by x, in the form of an integer interval multiplied by a power of two, i.e. \(x = [a, b] \times 2^{\mathrm{exp}}\).

The outcome is undefined if the midpoint or radius of x is non-finite, or if the difference in magnitude between the midpoint and radius is so large that representing the endpoints exactly would cause overflows.

void fmprb_set_interval_fmpr(fmprb_t x, const fmpr_t a, const fmpr_t b, slong prec)

Sets x to a ball containing the interval \([a, b]\). We require that \(a \le b\).

slong fmprb_rel_error_bits(const fmprb_t x)

Returns the effective relative error of x measured in bits, defined as the difference between the position of the top bit in the radius and the top bit in the midpoint, plus one. The result is clamped between plus/minus FMPR_PREC_EXACT.

slong fmprb_rel_accuracy_bits(const fmprb_t x)

Returns the effective relative accuracy of x measured in bits, equal to the negative of the return value from fmprb_rel_error_bits.

slong fmprb_bits(const fmprb_t x)

Returns the number of bits needed to represent the absolute value of the mantissa of the midpoint of x, i.e. the minimum precision sufficient to represent x exactly. Returns 0 if the midpoint of x is a special value.

void fmprb_trim(fmprb_t y, const fmprb_t x)

Sets y to a trimmed copy of x: rounds x to a number of bits equal to the accuracy of x (as indicated by its radius), plus a few guard bits. The resulting ball is guaranteed to contain x, but is more economical if x has less than full accuracy.

int fmprb_get_unique_fmpz(fmpz_t z, const fmprb_t x)

If x contains a unique integer, sets z to that value and returns nonzero. Otherwise (if x represents no integers or more than one integer), returns zero.

Comparisons

int fmprb_is_zero(const fmprb_t x)

Returns nonzero iff the midpoint and radius of x are both zero.

int fmprb_is_nonzero(const fmprb_t x)

Returns nonzero iff zero is not contained in the interval represented by x.

int fmprb_is_one(const fmprb_t x)

Returns nonzero iff x is exactly 1.

int fmprb_is_finite(fmprb_t x)

Returns nonzero iff the midpoint and radius of x are both finite floating-point numbers, i.e. not infinities or NaN.

int fmprb_is_exact(const fmprb_t x)

Returns nonzero iff the radius of x is zero.

int fmprb_is_int(const fmprb_t x)

Returns nonzero iff x is an exact integer.

int fmprb_equal(const fmprb_t x, const fmprb_t y)

Returns nonzero iff x and y are equal as balls, i.e. have both the same midpoint and radius.

Note that this is not the same thing as testing whether both x and y certainly represent the same real number, unless either x or y is exact (and neither contains NaN). To test whether both operands might represent the same mathematical quantity, use fmprb_overlaps() or fmprb_contains(), depending on the circumstance.

int fmprb_is_positive(const fmprb_t x)
int fmprb_is_nonnegative(const fmprb_t x)
int fmprb_is_negative(const fmprb_t x)
int fmprb_is_nonpositive(const fmprb_t x)

Returns nonzero iff all points p in the interval represented by x satisfy, respectively, \(p > 0\), \(p \ge 0\), \(p < 0\), \(p \le 0\). If x contains NaN, returns zero.

int fmprb_overlaps(const fmprb_t x, const fmprb_t y)

Returns nonzero iff x and y have some point in common. If either x or y contains NaN, this function always returns nonzero (as a NaN could be anything, it could in particular contain any number that is included in the other operand).

int fmprb_contains_fmpr(const fmprb_t x, const fmpr_t y)
int fmprb_contains_fmpq(const fmprb_t x, const fmpq_t y)
int fmprb_contains_fmpz(const fmprb_t x, const fmpz_t y)
int fmprb_contains_si(const fmprb_t x, slong y)
int fmprb_contains_mpfr(const fmprb_t x, const mpfr_t y)
int fmprb_contains_zero(const fmprb_t x)
int fmprb_contains(const fmprb_t x, const fmprb_t y)

Returns nonzero iff the given number (or ball) y is contained in the interval represented by x.

If x is contains NaN, this function always returns nonzero (as it could represent anything, and in particular could represent all the points included in y). If y contains NaN and x does not, it always returns zero.

int fmprb_contains_negative(const fmprb_t x)
int fmprb_contains_nonpositive(const fmprb_t x)
int fmprb_contains_positive(const fmprb_t x)
int fmprb_contains_nonnegative(const fmprb_t x)

Returns nonzero iff there is any point p in the interval represented by x satisfying, respectively, \(p < 0\), \(p \le 0\), \(p > 0\), \(p \ge 0\). If x contains NaN, returns nonzero.

Arithmetic

void fmprb_neg(fmprb_t y, const fmprb_t x)

Sets y to the negation of x.

void fmprb_abs(fmprb_t y, const fmprb_t x)

Sets y to the absolute value of x. No attempt is made to improve the interval represented by x if it contains zero.

void fmprb_add(fmprb_t z, const fmprb_t x, const fmprb_t y, slong prec)
void fmprb_add_ui(fmprb_t z, const fmprb_t x, ulong y, slong prec)
void fmprb_add_si(fmprb_t z, const fmprb_t x, slong y, slong prec)
void fmprb_add_fmpz(fmprb_t z, const fmprb_t x, const fmpz_t y, slong prec)
void fmprb_add_fmpr(fmprb_t z, const fmprb_t x, const fmpr_t y, slong prec)

Sets \(z = x + y\), rounded to prec bits. The precision can be FMPR_PREC_EXACT provided that the result fits in memory.

void fmprb_sub(fmprb_t z, const fmprb_t x, const fmprb_t y, slong prec)
void fmprb_sub_ui(fmprb_t z, const fmprb_t x, ulong y, slong prec)
void fmprb_sub_si(fmprb_t z, const fmprb_t x, slong y, slong prec)
void fmprb_sub_fmpz(fmprb_t z, const fmprb_t x, const fmpz_t y, slong prec)

Sets \(z = x - y\), rounded to prec bits. The precision can be FMPR_PREC_EXACT provided that the result fits in memory.

void fmprb_mul(fmprb_t z, const fmprb_t x, const fmprb_t y, slong prec)
void fmprb_mul_ui(fmprb_t z, const fmprb_t x, ulong y, slong prec)
void fmprb_mul_si(fmprb_t z, const fmprb_t x, slong y, slong prec)
void fmprb_mul_fmpz(fmprb_t z, const fmprb_t x, const fmpz_t y, slong prec)

Sets \(z = x \times y\), rounded to prec bits. The precision can be FMPR_PREC_EXACT provided that the result fits in memory.

void fmprb_mul_2exp_si(fmprb_t y, const fmprb_t x, slong e)
void fmprb_mul_2exp_fmpz(fmprb_t y, const fmprb_t x, const fmpz_t e)

Sets y to x multiplied by \(2^e\).

void fmprb_inv(fmprb_t z, const fmprb_t x, slong prec)

Sets z to the multiplicative inverse of x.

void fmprb_div(fmprb_t z, const fmprb_t x, const fmprb_t y, slong prec)
void fmprb_div_ui(fmprb_t z, const fmprb_t x, ulong y, slong prec)
void fmprb_div_si(fmprb_t z, const fmprb_t x, slong y, slong prec)
void fmprb_div_fmpz(fmprb_t z, const fmprb_t x, const fmpz_t y, slong prec)
void fmprb_div_fmpr(fmprb_t z, const fmprb_t x, const fmpr_t y, slong prec)
void fmprb_fmpz_div_fmpz(fmprb_t y, const fmpz_t num, const fmpz_t den, slong prec)
void fmprb_ui_div(fmprb_t z, ulong x, const fmprb_t y, slong prec)

Sets \(z = x / y\), rounded to prec bits. If y contains zero, z is set to \(0 \pm \infty\). Otherwise, error propagation uses the rule

\[\left| \frac{x}{y} - \frac{x+\xi_1 a}{y+\xi_2 b} \right| = \left|\frac{x \xi_2 b - y \xi_1 a}{y (y+\xi_2 b)}\right| \le \frac{|xb|+|ya|}{|y| (|y|-b)}\]

where \(-1 \le \xi_1, \xi_2 \le 1\), and where the triangle inequality has been applied to the numerator and the reverse triangle inequality has been applied to the denominator.

void fmprb_addmul(fmprb_t z, const fmprb_t x, const fmprb_t y, slong prec)
void fmprb_addmul_ui(fmprb_t z, const fmprb_t x, ulong y, slong prec)
void fmprb_addmul_si(fmprb_t z, const fmprb_t x, slong y, slong prec)
void fmprb_addmul_fmpz(fmprb_t z, const fmprb_t x, const fmpz_t y, slong prec)

Sets \(z = z + x \times y\), rounded to prec bits. The precision can be FMPR_PREC_EXACT provided that the result fits in memory.

void fmprb_submul(fmprb_t z, const fmprb_t x, const fmprb_t y, slong prec)
void fmprb_submul_ui(fmprb_t z, const fmprb_t x, ulong y, slong prec)
void fmprb_submul_si(fmprb_t z, const fmprb_t x, slong y, slong prec)
void fmprb_submul_fmpz(fmprb_t z, const fmprb_t x, const fmpz_t y, slong prec)

Sets \(z = z - x \times y\), rounded to prec bits. The precision can be FMPR_PREC_EXACT provided that the result fits in memory.

Powers and roots

void fmprb_sqrt(fmprb_t z, const fmprb_t x, slong prec)
void fmprb_sqrt_ui(fmprb_t z, ulong x, slong prec)
void fmprb_sqrt_fmpz(fmprb_t z, const fmpz_t x, slong prec)

Sets z to the square root of x, rounded to prec bits. Error propagation is done using the following rule: assuming \(m > r \ge 0\), the error is largest at \(m - r\), and we have \(\sqrt{m} - \sqrt{m-r} \le r / (2 \sqrt{m-r})\).

void fmprb_sqrtpos(fmprb_t z, const fmprb_t x, slong prec)

Sets z to the square root of x, assuming that x represents a nonnegative number (i.e. discarding any negative numbers in the input interval), and producing an output interval not containing any negative numbers (unless the radius is infinite).

void fmprb_hypot(fmprb_t z, const fmprb_t x, const fmprb_t y, slong prec)

Sets z to \(\sqrt{x^2 + y^2}\).

void fmprb_rsqrt(fmprb_t z, const fmprb_t x, slong prec)
void fmprb_rsqrt_ui(fmprb_t z, ulong x, slong prec)

Sets z to the reciprocal square root of x, rounded to prec bits. At high precision, this is faster than computing a square root.

void fmprb_root(fmprb_t z, const fmprb_t x, ulong k, slong prec)

Sets z to the k-th root of x, rounded to prec bits. As currently implemented, this function is only fast for small fixed k. For large k it is better to use fmprb_pow_fmpq() or fmprb_pow().

void fmprb_agm(fmprb_t z, const fmprb_t x, const fmprb_t y, slong prec)

Sets z to the arithmetic-geometric mean of x and y.