contrib/sb-mpfr/README.md

   1 SB-MPFR
   2 =======
   3
   4 MPFR integration for SBCL
   5
   6 The MPFR library [1] provides arbitrary precision arithmetic on
   7 floating-point numbers. It makes use of the GMP library and therefore
   8 SB-MPFR requires SB-GMP [2]. Contrary to SB-GMP the SB-MPFR contrib does
   9 not deeply integrate with any standard Common Lisp functions. However,
  10 the SB-MPFR provides several function with equivalent names of
  11 standard function and similar interface, e.g. SB-MPFR:COERCE,
  12 SB-MPFR:SIN etc.
  13
  14 Rounding
  15 --------
  16
  17 The rounding mode for SB-MPFR is defined by the value of
  18 *MPFR-RND*. Possible values are :MPFR_RNDNA, :MPFR_RNDN, :MPFR_RNDZ,
  19 :MPFR_RNDU, :MPFR_RNDD, :MPFR_RNDA, :MPFR_RNDF which implement the
  20 corresponding rounding modes from MPFR and are members of the type
  21 MPFR_RND_ENUM.
  22
  23 Precision
  24 ---------
  25
  26 MPFR allows to define the preicision of a computation or newly created
  27 floating-points. This can either be set via the SB-MPFR:WITH-PRECISION
  28 macro which takes the number of bits and an expression body as
  29 arguments, or via SB-MPFR:SET-PRECISION which sets the precision until
  30 further change.
  31
  32 Example, function to compute PI with 400 bits precision:
  33
  34     (defun sample-pi ()
  35       (sb-mpfr:set-precision 400)
  36       (sb-mpfr:const-pi))
  37
  38     CL-USER> (sample-pi)
  39     .31415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679821480865132823066470e+1
  40     -1
  41
  42     (defun sample-pi-x (x)
  43       (sb-mpfr:with-precision x
  44         (sb-mpfr:const-pi)))
  45
  46     CL-USER> (sample-pi-x 42)
  47     .31415926535901e+1
  48     1
  49     CL-USER> (sample-pi-x 142)
  50     .31415926535897932384626433832795028841971697e+1
  51     1
  52
  53 Second Return Value
  54 -------------------
  55
  56 Almost every MPFR-related function returns a second value. This value
  57 is of the ternary set {-1, 0, 1}. If the ternary value is zero, it
  58 means that the value stored in the destination variable is the exact
  59 result of the corresponding mathematical function. If the ternary
  60 value is positive (resp. negative), it means the value stored in the
  61 destination variable is greater (resp. lower) than the exact
  62 result. The returned value depends on the current rounding mode. Refer
  63 to [1] for further details.
  64
  65
  66 Number Creation
  67 ---------------
  68
  69 Creating arbitrary precision floating points can be achieved in two
  70 ways. First, by coercing a standard CL non-complex number with
  71 SB-MPFR:COERCE.
  72
  73     CL-USER> (sb-mpfr:coerce 1.0d0 'sb-mpfr:mpfr-float)
  74     .10000000000000000e+1
  75     CL-USER> (sb-mpfr:coerce 1/2 'sb-mpfr:mpfr-float)
  76     .50000000000000000e+0
  77
  78 The second method uses the ready maco #M:
  79
  80     CL-USER> #M"1.5"
  81     .15000000000000000e+1
  82     CL-USER> (setf *print-readably* t)
  83     T
  84     CL-USER> #M"1.5"
  85     #M"15000000000000000@-16"
  86
  87 Exports and Functions
  88 ---------------------
  89
  90 The following functions, macros and symbols are exported from the SB-MPFR package:
  91
  92     ;; +mpfr-precision+ is a pseudo-constant
  93     ;; Do not set via LET but use the two methods below!
  94     #:+mpfr-precision+
  95     #:set-precision
  96     #:with-precision
  97     ;; parameters and types
  98     #:*mpfr-rnd*
  99     #:*mpfr-base*
 100     #:mpfr-float
 101     ;; arithmetic operations
 102     #:make-mpfr-float
 103     #:mpfr-float-to-string
 104     #:add
 105     #:sub
 106     #:mul
 107     #:square
 108     #:div
 109     #:sqrt
 110     #:reciprocal-sqrt
 111     #:cubic-root
 112     #:k-root
 113     #:power
 114     #:negate
 115     #:abs
 116     #:dim
 117     #:mul-2-raised
 118     #:div-2-raised
 119     ;; special functions
 120     #:log
 121     #:log2
 122     #:log10
 123     #:exp
 124     #:exp2
 125     #:exp10
 126     #:cos
 127     #:sin
 128     #:tan
 129     #:sin-cos
 130     #:sec
 131     #:csc
 132     #:cot
 133     #:acos
 134     #:asin
 135     #:atan
 136     #:cosh
 137     #:sinh
 138     #:tanh
 139     #:sinh-cosh
 140     #:sech
 141     #:csch
 142     #:coth
 143     #:acosh
 144     #:asinh
 145     #:atanh
 146     #:fac
 147     #:log1p
 148     #:expm1
 149     #:eint
 150     #:li2
 151     #:gamma
 152     #:lngamma
 153     #:digamma
 154     #:zeta
 155     #:erf
 156     #:erfc
 157     #:j0
 158     #:j1
 159     #:jn
 160     #:y0
 161     #:y1
 162     #:yn
 163     #:ai
 164     #:arithmetic-geometric-mean
 165     #:hypot
 166     #:fma
 167     #:fms
 168     #:sum
 169     ;; comparison functions and predicates
 170     #:nan-p
 171     #:infinityp
 172     #:integerp
 173     #:numberp
 174     #:zerop
 175     #:regularp
 176     #:compare
 177     #:compare-2exp
 178     #:compare-abs
 179     #:>
 180     #:>=
 181     #:<
 182     #:<=
 183     #:=
 184     #:/=
 185     #:unorderedp
 186     ;; constants
 187     #:const-log2
 188     #:const-pi
 189     #:const-euler
 190     #:const-catalan
 191     ;; miscellaneous functions
 192     #:clear-underflow
 193     #:clear-overflow
 194     #:clear-div-by-zero
 195     #:clear-nan-flag
 196     #:clear-inex-flag
 197     #:clear-erange-flag
 198     #:set-underflow-flag
 199     #:set-overflow-flag
 200     #:set-div-by-zero-flag
 201     #:set-nan-flag
 202     #:set-inex-flag
 203     #:set-erange-flag
 204     #:clear-flags
 205     #:underflowp
 206     #:overflowp
 207     #:div-by-zero-p
 208     #:nanflag-p
 209     #:inexflag-p
 210     #:erangeflag-p
 211     ;; random number generation
 212     #:urandomb
 213     #:urandom
 214     ;; rounding
 215     #:rounded-int
 216     #:rounded-int-ceiling
 217     #:rounded-int-floor
 218     #:rounded-int-round
 219     #:rounded-int-truncate
 220     #:fractional
 221     #:ceiling
 222     #:floor
 223     #:round
 224     #:truncate
 225     #:modf
 226     #:fmod
 227     #:remainder
 228     #:remainder-quot
 229     ;; conversion
 230     #:coerce
 231     ;; special constants
 232     #:*mpfr-version*
 233     #:*mpfr-features*
 234
 235
 236
 237 [1] http://www.mpfr.org/mpfr-current/mpfr.html
 238 [2] https://github.com/sfrank/sb-gmp