Generic Flonums
1 Introduction
2 Type
gfl?
gfl
gflcopy
gfl-init-exponent
gfl-init-bits
3 Conversions
real->gfl
gfl->real
bigfloat->gfl
gfl->bigfloat
ordinal->gfl
gfl->ordinal
string->gfl
gfl->string
4 Parameters
gfl-exponent
gfl-bits
gfl-rounding-mode
gfl-verbose?
5 Constants
pi.gfl
phi.gfl
euler.gfl
catalan.gfl
log2.gfl
+  nan.gfl
+  inf.gfl
+  max.gfl
+  min.gfl
0.gfl
-0.gfl
-min.gfl
-max.gfl
-inf.gfl
10.gfl
9.gfl
8.gfl
7.gfl
6.gfl
5.gfl
4.gfl
3.gfl
2.gfl
1.gfl
-1.gfl
-2.gfl
-3.gfl
-4.gfl
-5.gfl
-6.gfl
-7.gfl
-8.gfl
-9.gfl
-10.gfl
6 Predicates
gflzero?
gflpositive?
gflnegative?
gflinfinite?
gflnan?
gflsubnormal?
gfl=
gfl>
gfl<
gfl>=
gfl<=
7 Mathematical Operations
gfl+
gfl-
gfl*
gfl/
gflsqr
gflabs
gflsgn
gflmax
gflmin
gflmod
gflremainder
gfldim
gflagm
gflfma
gflsqrt
gfl1/  sqrt
gflcbrt
gflroot
gflhypot
gfllog
gfllog2
gfllog10
gflexp
gflexp2
gflexp10
gfllog1p
gflexpm1
gflexpt
gflsin
gflcos
gfltan
gflasin
gflacos
gflatan
gflatan2
gflsinh
gflcosh
gfltanh
gflasinh
gflacosh
gflatanh
gflcsc
gflsec
gflcot
gflcsch
gflsech
gflcoth
gflsin+  cos
gflsinh+  cosh
gflgamma
gfllgamma
gfldigamma
gflerf
gflerfc
gfleint
gflli2
gflzeta
gflj0
gflj1
gfljn
gfly0
gfly1
gflyn
gflai
8 Rounding
gflceiling
gflfloor
gflround
gfltruncate
gflrint
9 Miscellaneous
gflcopysign
gfls-between
gflnext
gflprev
gflstep
8.3

Generic Flonums

Brett Saiki <bksaiki@gmail.com>

 (require generic-flonum) package: generic-flonum

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
  1. properly emulate subnormal arithmetic

  2. 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.

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.