Generic Flonums

8.12

Generic Flonums🔗ℹ

This library provides an alternate interface to MPFR (compared to math/bigfloat), emphasizing the emulation of floating-point formats such as binary128, binary16, bfloat16, etc.

1 Introduction🔗ℹ

While the math/bigfloat interface is sufficient for most high-precision computing, it is lacking in a couple areas. Mainly, it does not

properly emulate subnormal arithmetic
allow the exponent range to be changed

Normally, neither of these problems cause concern. For example, if a user intends to find an approximate value for some computation on the reals, then subnormal arithmetic or a narrower exponent range is not particular useful. However, if a user wants to know the result of a computation specifically in some format, say half-precision, then math/bigfloat is insufficient.

At half-precision, (exp -10) and (exp 20) evaluate to 4.5419e-5 and +inf.0, respectively. On the other hand, evaluating (bfexp (bf -10)) and (bfexp (bf -10)) with (bf-precision 11) returns (bf "4.5389e-5") and (bf "#e4.8523e8"). While the latter results are certainly more accurate, they do not reflect proper behavior in half-precision. The standard bigfloat library does not subnormalize the first result (no subnormal arithmetic), nor does it recognize the overflow in the second result (fixed exponent range).

This library fixes the issues mentioned above by automatically emulating subnormal arithmetic when necessary and providing a way to change the exponent range. In addition, the interface is quite similar to math/bigfloat, so it will feel familiar to anyone who has used the standard bigfloat library before. There are also a few extra operations from the C math library such as gflfma, gflmod, and gflremainder that the bigfloat library does not support.

See math/bigfloat for more information on bigfloats.

2 Type🔗ℹ

A generic flonum is a wrapper that stores a bigfloat and the significand and exponent size when it was initialized.

procedure
(gfl? v) → boolean?
v : any/c

Returns #t if v is a generic-flonum.

procedure
(gfl x) → gfl?
x : (or/c string? real?)

Constructs a generic-flonum from a string or a real number.

procedure
(gflcopy x) → gfl?
x : gfl?

Returns a generic-flonum with the same value as x except rounded at the current precision and rounding mode.

procedure
(gfl-init-exponent x) → gfl?
x : gfl?

Returns the exponent size of the generic-flonum at the time of its initialization.

procedure
(gfl-init-bits x) → gfl?
x : gfl?

Returns the sum of the exponent and significand sizes of the generic-flonum at the time of its initialization.

3 Conversions🔗ℹ

procedure
(real->gfl v) → gfl?
v : real?
procedure
(gfl->real x) → real?
x : gfl?

Converts a real v to a generic-flonum x and back.

procedure
(bigfloat->gfl v) → gfl?
v : bigfloat?
procedure
(gfl->bigfloat x) → bigfloat?
x : gfl?

Converts a bigfloat v to a generic-flonum x and back.

procedure
(ordinal->gfl o) → gfl?
o : exact-integer?
procedure
(gfl->ordinal x) → exact-integer?
x : gfl?

Like ordinal->flonum and flonum->ordinal but for generic-flonums.

procedure
(string->gfl s) → gfl?
s : string?
procedure
(gfl->string x) → string?
x : gfl?

Converts a string s to a generic-flonum x and back.

4 Parameters🔗ℹ

The standard bigfloat library defines (bf-precision) and (bf-rounding-mode) to control significand size and the rounding of results. The following parameters are similar and can be used at the same time as their bigfloat counterparts, although this behavior may change in the future.

parameter
(gfl-exponent) → exact-positive-integer?
(gfl-exponent es) → void?
es : exact-positive-integer?
= 11

A parameter that defines the current exponent size of values returned from most functions in this library. Default value is the exponent size of a flonum.

parameter
(gfl-bits) → exact-positive-integer?
(gfl-bits nb) → void?
nb : exact-positive-integer?
= 64

A parameter that defines the current sum of the exponent size and significand size of values returned from most functions in this library. More concisely, it defines the significand size indirectly. The significand size corresponds to (bf-precision) and is equal to (- (gfl-bits) (gfl-exponent)). Default value is the length of a flonum in bits.

parameter
(gfl-rounding-mode) → (symbols 'nearest 'zero 'up 'down 'away)
(gfl-rounding-mode rm) → void?
rm : (symbols 'nearest 'zero 'up 'down 'away)
= 'nearest

A parameter that determines the mode used to round the result of most functions in this library. Note that (bf-rounding-mode) accepts all values except 'away.

parameter
(gfl-verbose?) → boolean?
(gfl-verbose? b) → void?
b : boolean?
= #t

A parameter that controls the verbosity when printing generic-flonums. When set to true, generic-flonums are printed in a custom format: "#<gfl[es, nb]: v>". When set to false, generic-flonums are printed in a format similar to bigfloats: "(gfl v)".

5 Constants🔗ℹ

value
pi.gfl : gfl?
value
phi.gfl : gfl?
value
euler.gfl : gfl?
value
catalan.gfl : gfl?
value
log2.gfl : gfl?

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

value
+nan.gfl : gfl?
value
+inf.gfl : gfl?
value
+max.gfl : gfl?
value
+min.gfl : gfl?
value
0.gfl : gfl?
value
-0.gfl : gfl?
value
-min.gfl : gfl?
value
-max.gfl : gfl?
value
-inf.gfl : gfl?

Constants corresponding to +nan.0, +inf.0, +max.0, +min.0, 0.0, -0.0, -min.0, -max.0, and -inf.0.

value
10.gfl : gfl?
value
9.gfl : gfl?
value
8.gfl : gfl?
value
7.gfl : gfl?
value
6.gfl : gfl?
value
5.gfl : gfl?
value
4.gfl : gfl?
value
3.gfl : gfl?
value
2.gfl : gfl?
value
1.gfl : gfl?
value
-1.gfl : gfl?
value
-2.gfl : gfl?
value
-3.gfl : gfl?
value
-4.gfl : gfl?
value
-5.gfl : gfl?
value
-6.gfl : gfl?
value
-7.gfl : gfl?
value
-8.gfl : gfl?
value
-9.gfl : gfl?
value
-10.gfl : gfl?

More constants.

6 Predicates🔗ℹ

procedure
(gflzero? x) → boolean?
  x : gfl?
procedure
(gflpositive? x) → boolean?
  x : gfl?
procedure
(gflnegative? x) → boolean?
  x : gfl?
procedure
(gflinfinite? x) → boolean?
  x : gfl?
procedure
(gflnan? x) → boolean?
  x : gfl?

Unary predicates corresponding to zero?, positive?, negative?, infinite?, and nan?.

procedure
(gflsubnormal? x) → boolean?
x : gfl?

Returns #t if x is a subnormal value.

procedure
(gfl= x) → boolean?
  x : gfl?
procedure
(gfl> x) → boolean?
  x : gfl?
procedure
(gfl< x) → boolean?
  x : gfl?
procedure
(gfl>= x) → boolean?
  x : gfl?
procedure
(gfl<= x) → boolean?
  x : gfl?

Standard comparators corresponding to =, >, <, >=, and <=. Infinities are larger or smaller than any other value, and comparing to +nan.gfl always returns #f.

7 Mathematical Operations🔗ℹ

procedure
(gfl+ x ...) → gfl?
  x : gfl?
procedure
(gfl- x y ...) → gfl?
  x : gfl?
  y : gfl?
procedure
(gfl* x ...) → gfl?
  x : gfl?
procedure
(gfl/ x y ...) → gfl?
  x : gfl?
  y : gfl?
procedure
(gflsqr x) → gfl?
  x : gfl?
procedure
(gflabs x) → gfl?
  x : gfl?
procedure
(gflsgn x) → gfl?
  x : gfl?

Standard arithmetic functions, corresponding to +, -, *, /, sqr, abs, sgn. Similar to bf/, division by zero returns +nan.gfl.

When giving more than two arguments, gfl+ and gfl- compute the answer without any intermediate rounding.

procedure
(gflmax x ...) → gfl?
x : gfl?
procedure
(gflmin x ...) → gfl?
x : gfl?

Returns the maximum and minimum of their arguments, respectively. When given no arguments, gflmin returns +inf.gfl, and gflmax returns -inf.gfl.

Unlike bfmin and bfmax, these functions are C99 compliant and will only return +nan.gfl if all arguments are +nan.gfl.

procedure
(gflmod x y) → gfl?
  x : gfl?
  y : gfl?
procedure
(gflremainder x y) → gfl?
  x : gfl?
  y : gfl?

Returns the modulo and remainder of x and y.

procedure
(gfldim x y) → gfl?
x : gfl?
y : gfl?

Returns (gfl- x y) if (gfl> x y), and 0.gfl otherwise. Equivalent to (gflmax (gfl- x y) 0.gfl).

procedure
(gflagm x y) → gfl?
x : gfl?
y : gfl?

Returns the arithmetic-geometric mean of x and y.

procedure
(gflfma x y z) → gfl?
  x : gfl?
  y : gfl?
  z : gfl?

Computes (gfl+ (gfl* x y) z) without intermediate overflow or rounding.

procedure
(gflsqrt x) → gfl?
  x : gfl?
procedure
(gfl1/sqrt x) → gfl?
  x : gfl?
procedure
(gflcbrt x) → gfl?
  x : gfl?

Returns the square root, the reciprocal square root, and the cube root of x.

procedure
(gflroot x n) → gfl?
x : gfl?
n : exact-nonnegative-integer?

Returns the n-th root of x. n must be a nonnegative fixnum.

procedure
(gflhypot x) → gfl?
x : gfl?

Returns (gflsqrt (gfl+ (gflsqr x) (gflsqr y))) without intermediate overflow or rounding.

procedure
(gfllog x) → gfl?
  x : gfl?
procedure
(gfllog2 x) → gfl?
  x : gfl?
procedure
(gfllog10 x) → gfl?
  x : gfl?

Returns the log of x in base e, 2, and 10.

procedure
(gflexp x) → gfl?
  x : gfl?
procedure
(gflexp2 x) → gfl?
  x : gfl?
procedure
(gflexp10 x) → gfl?
  x : gfl?

Returns the exponential of x in base e, 2, and 10.

procedure
(gfllog1p x) → gfl?
x : gfl?
procedure
(gflexpm1 x) → gfl?
x : gfl?

Computes (gfllog (gfl+ 1.gfl x)) and (gfl- (gflexp x) 1.gfl).

procedure
(gflexpt x) → gfl?
x : gfl?

Function corresponding to expt.

procedure
(gflsin x) → gfl?
  x : gfl?
procedure
(gflcos x) → gfl?
  x : gfl?
procedure
(gfltan x) → gfl?
  x : gfl?
procedure
(gflasin x) → gfl?
  x : gfl?
procedure
(gflacos x) → gfl?
  x : gfl?
procedure
(gflatan x) → gfl?
  x : gfl?
procedure
(gflatan2 x y) → gfl?
  x : gfl?
  y : gfl?

Standard trigonmetric functions and their inverses.

procedure
(gflsinh x) → gfl?
  x : gfl?
procedure
(gflcosh x) → gfl?
  x : gfl?
procedure
(gfltanh x) → gfl?
  x : gfl?
procedure
(gflasinh x) → gfl?
  x : gfl?
procedure
(gflacosh x) → gfl?
  x : gfl?
procedure
(gflatanh x) → gfl?
  x : gfl?

Standard hyperbolic functions and their inverses.

procedure
(gflcsc x) → gfl?
  x : gfl?
procedure
(gflsec x) → gfl?
  x : gfl?
procedure
(gflcot x) → gfl?
  x : gfl?

Standard reciprocal trigonometric functions.

procedure
(gflcsch x) → gfl?
  x : gfl?
procedure
(gflsech x) → gfl?
  x : gfl?
procedure
(gflcoth x) → gfl?
  x : gfl?

Standard reciprocal hyperbolic functions.

procedure
(gflsin+cos x) →
gfl? gfl?
x : gfl?

Simultaneously computes the sine and cosine of x.

procedure
(gflsinh+cosh x) →
gfl? gfl?
x : gfl?

Simultaneously computes the hyperbolic sine and cosine of x.

procedure
(gflgamma x) → gfl?
  x : gfl?
procedure
(gfllgamma x) → gfl?
  x : gfl?
procedure
(gfldigamma x) → gfl?
  x : gfl?

Compute the gamma, log-gamma, and digamma function.

procedure
(gflerf x) → gfl?
x : gfl?
procedure
(gflerfc x) → gfl?
x : gfl?

Compute the error function and complementary error function.

procedure
(gfleint x) → gfl?
x : gfl?

Returns the exponetial integral of x.

procedure
(gflli2 x) → gfl?
x : gfl?

Returns the dilogarithm of x.

procedure
(gflzeta x) → gfl?
x : gfl?

Computes the Riemann zeta function.

procedure
(gflj0 x) → gfl?
  x : gfl?
procedure
(gflj1 x) → gfl?
  x : gfl?
procedure
(gfljn n x) → gfl?
  n : exact-integer?
  x : gfl?
procedure
(gfly0 x) → gfl?
  x : gfl?
procedure
(gfly1 x) → gfl?
  x : gfl?
procedure
(gflyn n x) → gfl?
  n : exact-integer?
  x : gfl?

Compute the Bessel functions. The first three correspond to Bessel functions of the first kind of order 0, 1, and n, while the other three correspond to Bessel functions of the second kind of order 0, 1, and n.

procedure
(gflai x) → gfl?
x : gfl?

Computes the Airy function of the first kind.

8 Rounding🔗ℹ

procedure
(gflceiling x) → gfl?
  x : gfl?
procedure
(gflfloor x) → gfl?
  x : gfl?
procedure
(gflround x) → gfl?
  x : gfl?
procedure
(gfltruncate x) → gfl?
  x : gfl?

Like ceiling, floor, round, and truncate, but for generic-flonums.

procedure
(gflrint x) → gfl?
x : gfl?

Rounds x to the nearest integer in the direction specified by (gfl-rounding-mode).

9 Miscellaneous🔗ℹ

procedure
(gflcopysign x y) → gfl?
x : gfl?
y : gfl?

Returns a generic-flonum with the magnitude of x and the sign of y.

procedure
(gfls-between x y) → gfl?
  x : gfl?
  y : gfl?
procedure
(gflnext x) → gfl?
  x : gfl?
procedure
(gflprev x) → gfl?
  x : gfl?
procedure
(gflstep x n) → gfl?
  x : gfl?
  n : exact-integer?

Like flonums-between, flnext, flprev, and flstep, but for generic-flonums.

1	Introduction
2	Type
3	Conversions
4	Parameters
5	Constants
6	Predicates
7	Mathematical Operations
8	Rounding
9	Miscellaneous