#lang scribble/doc
@(require scribble/manual
scribble/struct
scribblings/icons)
@title[#:tag "mathematical-functions"]{Mathematical Functions}
@local-table-of-contents[]
This chapter describes the basic mathematical constants and functions provided by the PLT Scheme Science Collection.
The constants and functions described in this chapter are defined in the @filepath{math.ss} file in the science collection and are made available using the form:
@defmodule[(planet williams/science/math)]
@section{Mathematical Constants}
The following table shows the mathematical constants defined by the PLT Scheme Science Collection:
@(make-table
'boxed
(list
(list (make-flow (list @t{@scheme[e]}))
(make-flow (list @t{The base of the exponentials, @math{e}})))
(list (make-flow (list @t{@scheme[log2e]}))
(make-flow (list @t{The base two logarithm of @math{e}, @math{log_2 e}})))
(list (make-flow (list @t{@scheme[log10e]}))
(make-flow (list @t{The base ten logarithm of @math{e}, @math{log_10 e}})))
(list (make-flow (list @t{@scheme[sqrt2]}))
(make-flow (list @t{The square root of two, @math{√2}})))
(list (make-flow (list @t{@scheme[sqrt1/2]}))
(make-flow (list @t{The square root of one half, @math{√½}})))
(list (make-flow (list @t{@scheme[sqrt3]}))
(make-flow (list @t{The square root of three, @math{√3}})))
(list (make-flow (list @t{@scheme[pi]}))
(make-flow (list @t{The constant pi, @math{π}})))
(list (make-flow (list @t{@scheme[pi/2]}))
(make-flow (list @t{Pi divided by two, @math{π/2}})))
(list (make-flow (list @t{@scheme[pi/4]}))
(make-flow (list @t{Pi divided by four, @math{π/4}})))
(list (make-flow (list @t{@scheme[sqrtpi]}))
(make-flow (list @t{The square root of pi, @math{√π}})))
(list (make-flow (list @t{@scheme[2/sqrtpi]}))
(make-flow (list @t{Two divided by the square root of pi, @math{2/√π}})))
(list (make-flow (list @t{@scheme[1/pi]}))
(make-flow (list @t{The reciprocal of pi, @math{1/π}})))
(list (make-flow (list @t{@scheme[2/pi]}))
(make-flow (list @t{Twice the reciprocal of pi, @math{2/π}})))
(list (make-flow (list @t{@scheme[ln10]}))
(make-flow (list @t{The natural log of ten, @math{ln 10} or @math{log_e 10}})))
(list (make-flow (list @t{@scheme[ln2]}))
(make-flow (list @t{The natural log of two, @math{ln 2} or @math{log_e 2}})))
(list (make-flow (list @t{@scheme[lnpi]}))
(make-flow (list @t{The natural log of pi, @math{ln π} or @math{log_e π}})))
(list (make-flow (list @t{@scheme[euler]}))
(make-flow (list @t{Euler's constant, @math{γ}})))
))
@section{Testing for Infinities and Not-a-Number}
PLT Scheme provides @scheme[+inf.0] (positive infinity), @scheme[-inf.0] (negative infinity), @scheme[+nan.0] (not a number), and @scheme[-nan.0] (same as @scheme[+nan.0]) as inexact numerical constants. The following functions are provided as a convenience for checking for infinities and not-a-number.
@defproc[(nan? (x any/c)) boolean?]{
Returns true, @scheme[#t], if @scheme[x] is not-a-number (i.e., equivalent to @scheme[+nan.0] or, equivalently, @scheme[-nan.0]), and false, @scheme[#f], otherwise. Note that this is not the same as @scheme[(not (number? x))], which is true if @scheme[x] is not a number.}
@defproc[(infinite? (x any/c)) boolean?]{
Returns 1 if @scheme[x] is positive infinity (i.e., equivalent to @scheme[+inf.0]), -1 if @scheme[x] is negative infinity (i.e., equivalent to @scheme[-inf.0]), and false, @scheme[#f], otherwise. Note that @scheme[(finite? x)] is not equivalent to @scheme[(not (infinite? x))], since both @scheme[finite?] and @scheme[infinite?] return false, @scheme[#f] for anything that is not a real number.}
@defproc[(finite? (x any/c)) boolean?]{
Returns true, @scheme[#t], if @scheme[x] is a finite real number and false, @scheme[#f], otherwise. Note that @scheme[(finite? x)] is not equivalent to @scheme[(not (infinite? x))], since both @scheme[finite?] and @scheme[infinite?] return false, @scheme[#f] for anything that is not a real number.}
@section{Elementary Functions}
The following functions provide some elementary mathematical functions that are not provide by PLT Scheme.
@defproc[(log1p (x real?)) number?]{
Computes the value of @math{log(1 + x)} in a way that is accurate for small @scheme[x].}
@defproc[(expm1 (x real?)) real?]{
Computes the value of @math{exp(x - 1)} in a way that is accurate for small @scheme[x].}
@defproc[(hypot (x real?) (y real?)) real?]{
Computes the value of @math{(x^2 + y^2)}@superscript{½} in a way that avoids overflow.}
@defproc[(acosh (x real?)) real?]{
Computes the value of the hyperbolic arccosine, @math{arccosh}, of @scheme[x].}
@defproc[(asinh (x real?)) real?]{
Computes the value of the hyperbolic arcsine, @math{arcsinh}, of @scheme[x].}
@defproc[(atahh (x real?)) real?]{
Computes the value of the hyperbolic arctangent, @math{arctanh}, of @scheme[x].}
@defproc[(ldexp (x real?) (e integer?)) real?]{
Computes the value of @math{x × 2^e}.}
@defproc[(frexp (x real?)) (values real? integer?)]{
Splits the real number @scheme[x] into a normalized fraction @math{f} and exponent @math{e} such that @math{x = f × 2^e} and @math{0.5 ≤ f < 1}. The function returns @math{f} and @math{e} as multiple values. If @scheme[x] is zero, both @math{f} and @math{e} are returned as zero.}
@section{Testing the Sign of Numbers}
@defproc[(sign (x real?)) (integer-in -1 1)]{
Returns the sign of @scheme[x] as 1 if @math{x ≥ 0} and -1 if @math{x < 0}. Note that the sign of zero is positive, regardless of its floating-point sign bit.}
@section{Approximate Comparisons of Real Numbers}
It is sometimes useful to be able to compare two real (in particular, floating-point) numbers approximately to allow for rounding and truncation errors. The following functions implements the approximate floating-point comparison algorithm proposed by D.E. Knuth in Section 4.2.2 of @italic{Seminumerical Algorithms} (3rd edition) @cite["Knuth"].
@defproc[(fcmp (x real?) (y real?) (epsilon real?)) (integer-in -1 1)]{
Determines whether @scheme[x] and @scheme[y] are approximately equal to within a relative accuracy, @scheme[epsilon]. The relative accuracy is measured using an interval of @math{2 × delta}, where @math{delta = 2^k × epsilon} and @math{k} is the maximum base 2 exponent of @scheme[x] and @scheme[y] as computed by the function @scheme[frexp]. If @scheme[x] and @scheme[y] lie within this interval, they are considered equal and the function returns 0. Otherwise, if @math{x < y}, the function returns -1, or if @math{x > y>}, the function returns 1.}
The implementation of this function is based on the packege @schemefont{fcmp} by T.C. Belding.