8.11.1.3

### 5Arbitrary-Precision Floating-Point Numbers (Bigfloats) 🔗 ℹ

 (require math/bigfloat) package: math-lib

This library provides a Typed Racket interface to MPFR, a C library that provides
• A C type of arbitrary-precision floating-point numbers.

• Elementary and special functions that are efficient and proved correct.

• Well-defined semantics that correspond with the latest IEEE 754 standard.

The arbitrary-precision floating-point numbers MPFR provides and operates on are represented by the Typed Racket type Bigfloat and identified by the predicate bigfloat?.

With a few noted exceptions, bigfloat functions regard their arguments as if they were exact, regardless of their precision. Conceptually, they compute exact results using infinitely many bits, and return results with (bf-precision) bits by rounding them using (bf-rounding-mode). In practice, they use finite algorithms that have been painstakingly proved to be equivalent to that conceptual, infinite process.

MPFR is free and license-compatible with commercial software. It is distributed with Racket for Windows and Mac OS X, is installed on most Linux systems, and is easy to install on major Unix-like platforms.

#### 5.1Quick Start 🔗 ℹ

1. Set the bigfloat function result precision using (bf-precision <some-number-of-bits>).

2. Use bf to convert real values and well-formed strings to bigfloats.

3. Operate on bigfloats using bf-prefixed functions like bf+ and bfsin.

4. Convert bigfloats to real values using bigfloat->real, bigfloat->flonum, and bigfloat->integer. Format them for display using bigfloat->string.

For examples, continue through the FAQ.

#### 5.2Fictionally Asked Questions 🔗 ℹ

Why use math/bigfloat?

There are a few reasons.

Reason: Flonums have either too much or too little precision for your application.

Examples:
 > (flsqrt 3.0) 1.7320508075688772 > pi 3.141592653589793 > (bf-precision 16) > (bfsqrt (bf 3)) (bf #e1.73206) > (bf-precision 179) > pi.bf (bf #e3.141592653589793238462643383279502884197169399375105819)

A flonum has a 53-bit significand (we’ll say it has 53 bits of precision) and an 11-bit exponent. A bigfloat has an arbitrary precision of at least 2 bits and a 31-bit exponent.

Reason: To compute ridiculously large or small numbers with confidence.

Examples:
 > (bf-precision 128) > (bfexp (bfexp (bfexp (bf 3)))) (bf "2.050986436051648895105860942072054674579e229520860") > (bflog (bflog (bflog (bfexp (bfexp (bfexp (bf 3))))))) (bf 3)

Reason: To verify your floating-point hardware.

IEEE 754-2008 stipulates that conforming implementations must correctly round the results of all operations. Roughly speaking, results can’t be more than half a bit off, where the bit in question is the least significant in the significand.

Of course, implementations don’t always adhere to standards. For example, on my old laptop, evaluating (exp 400) results in 5.221469689764346e+173. Note the last four decimal digits in the significand: 4346. But they should be 4144:
 > (bf-precision 53) > (bigfloat->flonum (bfexp (bf 400))) 5.221469689764144e+173
My new laptop computes 5.221469689764144e+173 as it should.

Reason: To control rounding of the least significant bit.

IEEE 754 provides for different rounding modes for the smallest bit of a flonum result, such as round to even and round toward zero. We might use this to implement interval arithmetic correctly, by rounding lower bounds downward and upper bounds upward. But there isn’t a portable way to set the rounding mode!

MPFR allows the rounding mode to be different for any operation, and math/bigfloat exposes this capability using the parameter bf-rounding-mode.

When shouldn’t I use math/bigfloat?

When you need raw speed. Bigfloat functions can be hundreds to thousands of times slower than flonum functions.

That’s not to say that they’re inefficient. For example, bflog implements the algorithm with the best known asymptotic complexity. It just doesn’t run directly on hardware, and it can’t take fixed-precision-only shortcuts.

Why are there junk digits on the end of (bf 1.1)?

That’s approximately the value of the flonum 1.1. Use (bf #e1.1) or (bf "1.1") to make the junk go away. In general, you should prefer to convert exact rationals and strings to bigfloats.

Why is the last digit of pi.bf not rounded correctly?

All the bits but the last is exact, and the last bit is correctly rounded. This doesn’t guarantee that the last digit will be.

A decimal digit represents at most log(10)/log(2) ≈ 3.3 bits. This is an irrational number, so the decimal/bit boundary never lines up except at the decimal point. Thus, the last decimal digit of any bigfloat must represent fewer than 3.3 bits, so it’s wrong more often than not. But it’s the last bit that counts.

#### 5.3Type and Constructors 🔗 ℹ

 syntax
 procedure(bigfloat? v) → Boolean v : Any
An opaque type that represents an arbitrary-precision floating-point number, or a bigfloat, and the opaque type’s predicate.

 procedure(bf x) → Bigfloat x : (U String Real) (bf sig exp) → Bigfloat sig : Integer exp : Integer
The one-argument variant converts a string or real x to a bigfloat.

 > (bf-precision 128) > (bf 4) (bf 4) > (bf 1/7) (bf #e0.1428571428571428571428571428571428571426) > (bf 41/10) (bf #e4.099999999999999999999999999999999999995) > (bf "not a number") bf: expected a well-formed decimal number; given "not a number" > (bf "15e200000000") (bf "1.499999999999999999999999999999999999998e200000001")

In the last example, the result of (bf "15e200000000") is displayed as a string conversion because the exact rational number would be very large.

* It can be a good idea if you’re testing a flonum implementation of a function against a bigfloat implementation.

Converting from flonum literals is usually a bad idea* because flonums have only 53 bits precision. Prefer to pass exact rationals and strings to bf.

The two-argument variant converts a signed significand sig and a power of 2 exp to a bigfloat. Generally, (bf sig exp) = (bf (* sig (expt 2 exp))), but the two-argument variant is much faster, especially for large exp.

Examples:
 > (bf 200 56) (bf 14411518807585587200) > (bf (* 200 (expt 2 56))) (bf 14411518807585587200)

The bfrandom function generates random bigfloats between 0 and 1 using the two-argument variant in this way:
 > (require (only-in math/base random-bits)) > (bf-precision 64) > (bf (random-bits 64) -64) (bf #e0.416872969910248753552)

 procedure
Returns a uniformly distributed random bigfloat in the interval [0,1].

 procedure(bfcopy x) → Bigfloat x : Bigfloat
Returns the (bf-precision)-bit bigfloat closest to x, under the current bf-rounding-mode.

A common pattern to compute bigfloats in higher precision is
> (bf-precision 64)
 > (bfcopy (parameterize ([bf-precision  (+ (bf-precision) 10)]) (bf/ (bf+ 1.bf (bfsqrt 5.bf)) 2.bf)))

(bf #e1.61803398874989484821)

This example computes the golden ratio (phi.bf) with 10 bits more than requested, to make up for triple rounding error.

#### 5.4Accessors and Conversion Functions 🔗 ℹ

 procedure x : Bigfloat
Returns the number of bits in the significand of x. This is almost always the value of (bf-precision) when x was created.

 procedure(bigfloat-signbit x) → (U 0 1) x : Bigfloat
Returns the sign bit of the significand of x.

Examples:
 > (bigfloat-signbit -1.bf) 1 > (bigfloat-signbit 0.bf) 0 > (bigfloat-signbit -0.bf) 1 > (bigfloat-signbit -inf.bf) 1

 procedure x : Bigfloat
 procedure x : Bigfloat
Return the signed significand or exponent of x.

To access the significand and exponent at the same time, use bigfloat->sig+exp.

 procedure x : Bigfloat
Returns the signed significand and exponent of x.

If (values sig exp) = (bigfloat->sig+exp x), its value as an exact rational is (* sig (expt 2 exp)). In fact, bigfloat->rational converts bigfloats to rationals in exactly this way, after ensuring that (bfrational? x) is #t.

This function and the two-argument variant of bf are mutual inverses.

 procedure x : Bigfloat
 procedure x : Bigfloat
 procedure x : Bigfloat
 procedure x : Bigfloat
Convert bigfloats to integer, exact rational, real and flonum values respectively.

bigfloat->integer, bigfloat->rational and bigfloat->real return values that can be converted exactly back to x using bf. For the first two, this is done by raising an error if x is not respectively integer or rational. On the other hand, bigfloat->real returns +inf.0, -inf.0 or +nan.0 when x is not a rational bigfloat.

bigfloat->flonum rounds x to 53 bits precision to fit the value into a flonum, using the current value of bf-rounding-mode.

> (bf-precision 64)
> (bigfloat->integer (bf 21/10))
 bigfloat->integer: contract violation expected: bfinteger? given: (bf #e2.09999999999999999991)

> (bigfloat->integer (bfround (bf 21/10)))

2

> (define x (bf 1/7))

> (bigfloat->flonum x)

0.14285714285714285

> (bigfloat->rational x)

10540996613548315209/73786976294838206464

> (rationalize (bigfloat->rational x) (expt 2 (- (bf-precision))))

1/7

> (bf= x (bf (bigfloat->rational x)))

#t

Be careful with exact conversions. Bigfloats with large exponents may not fit in memory as integers or exact rationals. Worse, they might fit, but have all your RAM and swap space for lunch.

 procedure x : Bigfloat
 procedure s : String
Convert a bigfloat x to a string s and back.

The string returned by bigfloat->string includes enough digits that string->bigfloat can reconstruct the bigfloat precisely. In other words, string->bigfloat is a left inverse of bigfloat->string.

If s isn’t a well-formed decimal number with an optional exponent part, string->bigfloat returns #f. (In contrast, (bf s) raises an error.)

Examples:
 > (bf-precision 64) > (bigfloat->string (bf 4)) "4" > (bigfloat->string (bf 1/10000)) "1.00000000000000000001e-4" > (string->bigfloat "0.14285714285714285714") (bf #e0.142857142857142857141) > (string->bigfloat "square root of two") #f > (string->bigfloat (bigfloat->string pi.bf)) (bf #e3.14159265358979323851) > pi.bf (bf #e3.14159265358979323851)

#### 5.5Parameters 🔗 ℹ

 parameter (bf-precision bits) → void? bits : Integer
A parameter that determines the precision of bigfloats returned from most bigfloat functions. Exceptions are noted in the documentation for functions that do not use bf-precision.

For nonzero, rational bigfloats, the number of bits bits includes the leading one bit. For example, to simulate 64-bit floating point, use (bf-precision 53) even though flonums have a 52-bit significand, because the one bit is implicit in a flonum.

This parameter has a guard that ensures (bf-precision) is between bf-min-precision and bf-max-precision.

 parameter(bf-rounding-mode) → (U 'nearest 'zero 'up 'down) (bf-rounding-mode mode) → void? mode : (U 'nearest 'zero 'up 'down)
A parameter that determines the mode used to round the results of most bigfloat functions. Conceptually, rounding is applied to infinite-precision results to fit them into (bf-precision) bits.

 value
Equal to 2, because single-bit bigfloats can’t be correctly rounded.

 value
The largest value of (bf-precision). This is platform-dependent, and probably much larger than you’ll ever need.

#### 5.6Constants 🔗 ℹ

Most bigfloat “constants” are actually identifier macros that expand to the application of a zero-argument function. This allows, for example, pi.bf to depend on the current value of bf-precision, and allows all of them to be constructed lazily. Most constants are memoized, possibly at multiple precisions.

 value
 value
 value
 value
 value
Approximations of π, φ, γ, G and log(2).

Examples:
 > (bf-precision 10) > pi.bf (bf #e3.1406) > (bf-precision 179) > pi.bf (bf #e3.141592653589793238462643383279502884197169399375105819) > phi.bf bf #e1.618033988749894848204586834365638117720309179805762863) > gamma.bf (bf #e0.5772156649015328606065120900824024310421593359399235988) > catalan.bf (bf #e0.9159655941772190150546035149323841107741493742816721343) > log2.bf (bf #e0.6931471805599453094172321214581765680755001343602552545)

 value
 value
 value
 value
 value
 value
 value
 value
 value
 value
Bigfloat constants corresponding to -inf.0, -max.0 -min.0, -0.0, 0.0, +min.0, +max.0, +inf.0, +nan.0 and epsilon.0.

The constants -inf.bf, -0.bf, 0.bf, +inf.bf, and +nan.bf have fixed precision.

 value
 value
 value
 value
 value
 value
 value
 value
 value
 value
 value
 value
 value
 value
 value
 value
 value
 value
 value
 value
More fixed-precision bigfloat constants.

#### 5.7Predicates 🔗 ℹ

 procedure(bfzero? x) → Boolean x : Bigfloat
 procedure x : Bigfloat
 procedure x : Bigfloat
 procedure x : Bigfloat
 procedure(bfeven? x) → Boolean x : Bigfloat
 procedure(bfodd? x) → Boolean x : Bigfloat
 procedure x : Bigfloat
 procedure x : Bigfloat
 procedure(bfnan? x) → Boolean x : Bigfloat
Unary predicates corresponding to zero?, positive?, negative?, integer?, even?, odd?, rational?, infinite? and nan?.

 procedure(bf= x y) → Boolean x : Bigfloat y : Bigfloat
 procedure(bf> x y) → Boolean x : Bigfloat y : Bigfloat
 procedure(bf< x y) → Boolean x : Bigfloat y : Bigfloat
 procedure(bf>= x y) → Boolean x : Bigfloat y : Bigfloat
 procedure(bf<= x y) → Boolean x : Bigfloat y : Bigfloat
Standard comparison functions. As is usual, infinities are either greater or less than any other bigfloat, and every comparison returns #f when either argument is +nan.bf.

#### 5.8Rounding 🔗 ℹ

 procedure x : Bigfloat
 procedure(bffloor x) → Bigfloat x : Bigfloat
 procedure x : Bigfloat
 procedure(bfround x) → Bigfloat x : Bigfloat
Like truncate, floor, ceiling and round, but for bigfloats.

Rounding is to the nearest integer, with ties broken by rounding to even.

Examples:
 > (bfround (bf 1.5)) (bf 2) > (bfround (bf 2.5)) (bf 2) > (bfround (bf -1.5)) (bf -2) > (bfround (bf -2.5)) (bf -2)

 procedure(bffrac x) → Bigfloat x : Bigfloat
Returns the fractional part of x, with the same sign as x.

 procedure(bfrint x) → Bigfloat x : Bigfloat
Rounds x to the nearest integer bigfloat, in the direction specified by (bf-rounding-mode).

#### 5.9Mathematical Operations 🔗 ℹ

 procedure(bfmax x ...) → Bigfloat x : Bigfloat
 procedure(bfmin x ...) → Bigfloat x : Bigfloat
Return the maximum and minimum of their arguments, respectively.

When given no arguments, bfmin returns +inf.bf, and bfmax returns -inf.bf.

 procedure(bf+ x ...) → Bigfloat x : Bigfloat
 procedure(bf* x ...) → Bigfloat x : Bigfloat
 procedure(bf- x y ...) → Bigfloat x : Bigfloat y : Bigfloat
 procedure(bf/ x y ...) → Bigfloat x : Bigfloat y : Bigfloat
 procedure(bfsqr x) → Bigfloat x : Bigfloat
 procedure(bfabs x) → Bigfloat x : Bigfloat
 procedure(bfsgn x) → Bigfloat x : Bigfloat
Standard arithmetic functions, corresponding to +, *, -, /, sqr, abs and sgn.

When bf+ and bf- are given more than two arguments, they compute the answers in a way that incurs rounding error only once.

 procedure(bfsqrt x) → Bigfloat x : Bigfloat
 procedure(bf1/sqrt x) → Bigfloat x : Bigfloat
 procedure(bfcbrt x) → Bigfloat x : Bigfloat
Return the square root, reciprocal square root, and cube root of x.

 procedure(bfroot x n) → Bigfloat x : Bigfloat n : Integer
Returns the nth root of x. n must be a nonnegative fixnum.

 procedure(bfhypot x y) → Bigfloat x : Bigfloat y : Bigfloat
Computes (bfsqrt (bf+ (bfsqr x) (bfsqr y))) without uncessary overflow, incurring rounding error only once. See flhypot for an example using flonums.

 procedure(bflog x) → Bigfloat x : Bigfloat
 procedure(bflog2 x) → Bigfloat x : Bigfloat
 procedure(bflog10 x) → Bigfloat x : Bigfloat
Return the log of x in base e, 2 and 10.

 procedure(bfexp x) → Bigfloat x : Bigfloat
 procedure(bfexp2 x) → Bigfloat x : Bigfloat
 procedure(bfexp10 x) → Bigfloat x : Bigfloat
Return the exponential of x in base e, 2 and 10.

 procedure(bflog1p x) → Bigfloat x : Bigfloat
 procedure(bfexpm1 x) → Bigfloat x : Bigfloat
Like (bflog (bf+ 1.bf x)) and (bf- (bfexp x) 1.bf), but correct when x is near zero. See fllog1p for motivation and examples.

 procedure(bfexpt x y) → Bigfloat x : Bigfloat y : Bigfloat
Computes xy. See flexpt and expt.

 procedure(bfsin x) → Bigfloat x : Bigfloat
 procedure(bfcos x) → Bigfloat x : Bigfloat
 procedure(bftan x) → Bigfloat x : Bigfloat
 procedure(bfasin x) → Bigfloat x : Bigfloat
 procedure(bfacos x) → Bigfloat x : Bigfloat
 procedure(bfatan x) → Bigfloat x : Bigfloat
 procedure(bfatan2 y x) → Bigfloat y : Bigfloat x : Bigfloat
Standard trigonometric functions and their inverses.

 procedure(bfsinh x) → Bigfloat x : Bigfloat
 procedure(bfcosh x) → Bigfloat x : Bigfloat
 procedure(bftanh x) → Bigfloat x : Bigfloat
 procedure(bfasinh x) → Bigfloat x : Bigfloat
 procedure(bfacosh x) → Bigfloat x : Bigfloat
 procedure(bfatanh x) → Bigfloat x : Bigfloat
Standard hyperbolic functions and their inverses.

 procedure(bfsec x) → Bigfloat x : Bigfloat
 procedure(bfcsc x) → Bigfloat x : Bigfloat
 procedure(bfcot x) → Bigfloat x : Bigfloat
Standard reciprocal trigonometric functions. MPFR does not implement their inverses.

 procedure(bfsech x) → Bigfloat x : Bigfloat
 procedure(bfcsch x) → Bigfloat x : Bigfloat
 procedure(bfcoth x) → Bigfloat x : Bigfloat
Standard reciprocal hyperbolic functions. MPFR does not implement their inverses.

 procedure x : Bigfloat
Simultaneously computes the sine and cosine of x.

 procedure x : Bigfloat
Simultaneously computes the hyperbolic sine and cosine of x.

 procedure x : Integer
Returns the factorial of x.

 procedure(bfremainder n m) → Bigfloat n : Bigfloat m : Bigfloat
Returns the remainder analogous to the Racket remainder function. When m is equal to zero, +nan.bf is returned.

 procedure(bfgamma x) → Bigfloat x : Bigfloat
Computes the gamma function, a generalization of the factorial function.

 procedure x : Bigfloat
 procedure(bflog-gamma/sign x) → (Values Bigfloat (U -1 1)) x : Bigfloat
Computes the log-gamma function, or the log of the absolute value of the gamma function. bflog-gamma/sign additionally returns the sign of (bfgamma x).

 procedure(bfpsi0 x) → Bigfloat x : Bigfloat
Computes the digamma function, the logarithmic derivative of the gamma function.

 procedure(bfeint x) → Bigfloat x : Bigfloat
Returns the exponential integral of x.

 procedure(bfli2 x) → Bigfloat x : Bigfloat
Returns the dilogarithm of x, or the polylogarithm of order 2.

 procedure(bfzeta x) → Bigfloat x : Bigfloat
Computes the Riemann zeta function.

 procedure(bferf x) → Bigfloat x : Bigfloat
 procedure(bferfc x) → Bigfloat x : Bigfloat

 procedure(bfbesj0 x) → Bigfloat x : Bigfloat
 procedure(bfbesj1 x) → Bigfloat x : Bigfloat
 procedure(bfbesj n x) → Bigfloat n : Integer x : Bigfloat
 procedure(bfbesy0 x) → Bigfloat x : Bigfloat
 procedure(bfbesy1 x) → Bigfloat x : Bigfloat
 procedure(bfbesy n x) → Bigfloat n : Integer x : Bigfloat
These compute Bessel functions.

A “j” in the name indicates that a function computes a Bessel function of the first kind. A “y” indicates the second kind.

The “j” or “y” is followed by the order: zero, one, or n (user-specified).

 procedure(bfagm x y) → bigfloat x : Bigfloat y : Bigfloat
Returns the arithmetic-geometric mean of x and y. Typically, this isn’t directly useful, but it’s used in some asymptotically fast algorithms such as the one that computes bflog.

#### 5.10Low-level Functions 🔗 ℹ

 procedure x : Bigfloat
 procedure n : Integer
 procedure x : Bigfloat y : Bigfloat
 procedure(bfstep x n) → Bigfloat x : Bigfloat n : Integer
 procedure(bfnext x) → Bigfloat x : Bigfloat
 procedure(bfprev x) → Bigfloat x : Bigfloat

The major difference is that these operate using (bf-precision) bits. Additionally, unlike other bigfloat functions, all of these convert their bigfloat arguments to (bf-precision) bits.

 procedure(bfshift x n) → Bigfloat x : Bigfloat n : Integer
Like arithmetic-shift, but for bigfloats. More precisely, this returns (bf* x (bfexpt (bf 2) (bf n))), but is much faster.

 procedure x : Bigfloat
Bigfloats are canonicalized before hashing, to ensure that equality implies an equal hash. If x is nonzero and rational, returns a new bigfloat with no more bits of precision than are necessary to encode x exactly, by removing all low-order zeros from the significand and adjusting the exponent.

For zero or non-rational x, returns -inf.bf, -0.bf, 0.bf, +inf.bf, or +nan.bf, depending on the value of x.

Two nonzero, rational bigfloats are equal? if and only if their canonicalized significands and exponents are equal. Two zero or non-rational bigfloats are equal? if and only if their canonicalizations are eq?.

Canonicalizing bigfloats won’t change answers computed from them.

Examples:
 > (bf-precision 64) > (define x (bf 1 -2)) > x (bf #e0.25) > (bfcanonicalize x) (bf #e0.25) > (bigfloat-precision x) 64 > (bigfloat-precision (bfcanonicalize x)) 2