htswanalysis/MACS/lib/gsl/gsl-1.11/doc/math.texi

   1 @cindex elementary functions
   2 @cindex mathematical functions, elementary
   3
   4 This chapter describes basic mathematical functions.  Some of these
   5 functions are present in system libraries, but the alternative versions
   6 given here can be used as a substitute when the system functions are not
   7 available.
   8
   9 The functions and macros described in this chapter are defined in the
  10 header file @file{gsl_math.h}.
  11
  12 @menu
  13 * Mathematical Constants::
  14 * Infinities and Not-a-number::
  15 * Elementary Functions::
  16 * Small integer powers::
  17 * Testing the Sign of Numbers::
  18 * Testing for Odd and Even Numbers::
  19 * Maximum and Minimum functions::
  20 * Approximate Comparison of Floating Point Numbers::
  21 @end menu
  22
  23 @node Mathematical Constants
  24 @section Mathematical Constants
  25 @cindex mathematical constants, defined as macros
  26 @cindex numerical constants, defined as macros
  27 @cindex constants, mathematical---defined as macros
  28 @cindex macros for mathematical constants
  29 The library ensures that the standard @sc{bsd} mathematical constants
  30 are defined. For reference, here is a list of the constants:
  31
  32 @table @code
  33 @item M_E
  34 @cindex e, defined as a macro
  35 The base of exponentials, @math{e}
  36
  37 @item M_LOG2E
  38 The base-2 logarithm of @math{e}, @math{\log_2 (e)}
  39
  40 @item M_LOG10E
  41 The base-10 logarithm of @math{e}, @c{$\log_{10}(e)$}
  42 @math{\log_10 (e)}
  43
  44 @item M_SQRT2
  45 The square root of two, @math{\sqrt 2}
  46
  47 @item M_SQRT1_2
  48 The square root of one-half, @c{$\sqrt{1/2}$}
  49 @math{\sqrt@{1/2@}}
  50
  51 @item M_SQRT3
  52 The square root of three, @math{\sqrt 3}
  53
  54 @item M_PI
  55 @cindex pi, defined as a macro
  56 The constant pi, @math{\pi}
  57
  58 @item M_PI_2
  59 Pi divided by two, @math{\pi/2}
  60
  61 @item M_PI_4
  62 Pi divided by four, @math{\pi/4}
  63
  64 @item M_SQRTPI
  65 The square root of pi, @math{\sqrt\pi}
  66
  67 @item M_2_SQRTPI
  68 Two divided by the square root of pi, @math{2/\sqrt\pi}
  69
  70 @item M_1_PI
  71 The reciprocal of pi, @math{1/\pi}
  72
  73 @item M_2_PI
  74 Twice the reciprocal of pi, @math{2/\pi}
  75
  76 @item M_LN10
  77 The natural logarithm of ten, @math{\ln(10)}
  78
  79 @item M_LN2
  80 The natural logarithm of two, @math{\ln(2)}
  81
  82 @item M_LNPI
  83 The natural logarithm of pi, @math{\ln(\pi)}
  84
  85 @item M_EULER
  86 @cindex Euler's constant, defined as a macro
  87 Euler's constant, @math{\gamma}
  88
  89 @end table
  90
  91 @node Infinities and Not-a-number
  92 @section Infinities and Not-a-number
  93
  94 @cindex infinity, defined as a macro
  95 @cindex IEEE infinity, defined as a macro
  96 @cindex NaN, defined as a macro
  97 @cindex Not-a-number, defined as a macro
  98 @cindex IEEE NaN, defined as a macro
  99
 100 @defmac GSL_POSINF
 101 This macro contains the IEEE representation of positive infinity,
 102 @math{+\infty}. It is computed from the expression @code{+1.0/0.0}.
 103 @end defmac
 104
 105 @defmac GSL_NEGINF
 106 This macro contains the IEEE representation of negative infinity,
 107 @math{-\infty}. It is computed from the expression @code{-1.0/0.0}.
 108 @end defmac
 109
 110 @defmac GSL_NAN
 111 This macro contains the IEEE representation of the Not-a-Number symbol,
 112 @code{NaN}. It is computed from the ratio @code{0.0/0.0}.
 113 @end defmac
 114
 115 @deftypefun int gsl_isnan (const double @var{x})
 116 This function returns 1 if @var{x} is not-a-number.
 117 @end deftypefun
 118
 119 @deftypefun int gsl_isinf (const double @var{x})
 120 This function returns @math{+1} if @var{x} is positive infinity,
 121 @math{-1} if @var{x} is negative infinity and 0 otherwise.
 122 @end deftypefun
 123
 124 @deftypefun int gsl_finite (const double @var{x})
 125 This function returns 1 if @var{x} is a real number, and 0 if it is
 126 infinite or not-a-number.
 127 @end deftypefun
 128
 129
 130 @node Elementary Functions
 131 @section Elementary Functions
 132
 133 The following routines provide portable implementations of functions
 134 found in the BSD math library.  When native versions are not available
 135 the functions described here can be used instead.  The substitution can
 136 be made automatically if you use @code{autoconf} to compile your
 137 application (@pxref{Portability functions}).
 138
 139 @deftypefun double gsl_log1p (const double @var{x})
 140 @cindex log1p
 141 @cindex logarithm, computed accurately near 1
 142 This function computes the value of @math{\log(1+x)} in a way that is
 143 accurate for small @var{x}. It provides an alternative to the BSD math
 144 function @code{log1p(x)}.
 145 @end deftypefun
 146
 147 @deftypefun double gsl_expm1 (const double @var{x})
 148 @cindex expm1
 149 @cindex exponential, difference from 1 computed accurately
 150 This function computes the value of @math{\exp(x)-1} in a way that is
 151 accurate for small @var{x}. It provides an alternative to the BSD math
 152 function @code{expm1(x)}.
 153 @end deftypefun
 154
 155 @deftypefun double gsl_hypot (const double @var{x}, const double @var{y})
 156 @cindex hypot
 157 @cindex euclidean distance function, hypot
 158 @cindex length, computed accurately using hypot
 159 This function computes the value of
 160 @c{$\sqrt{x^2 + y^2}$}
 161 @math{\sqrt@{x^2 + y^2@}} in a way that avoids overflow. It provides an
 162 alternative to the BSD math function @code{hypot(x,y)}.
 163 @end deftypefun
 164
 165 @deftypefun double gsl_hypot3 (const double @var{x}, const double @var{y}, const double @var{z})
 166 @cindex euclidean distance function, hypot
 167 @cindex length, computed accurately using hypot
 168 This function computes the value of
 169 @c{$\sqrt{x^2 + y^2 + z^2}$}
 170 @math{\sqrt@{x^2 + y^2 + z^2@}} in a way that avoids overflow.
 171 @end deftypefun
 172
 173 @deftypefun double gsl_acosh (const double @var{x})
 174 @cindex acosh
 175 @cindex hyperbolic cosine, inverse
 176 @cindex inverse hyperbolic cosine
 177 This function computes the value of @math{\arccosh(x)}. It provides an
 178 alternative to the standard math function @code{acosh(x)}.
 179 @end deftypefun
 180
 181 @deftypefun double gsl_asinh (const double @var{x})
 182 @cindex asinh
 183 @cindex hyperbolic sine, inverse
 184 @cindex inverse hyperbolic sine
 185 This function computes the value of @math{\arcsinh(x)}. It provides an
 186 alternative to the standard math function @code{asinh(x)}.
 187 @end deftypefun
 188
 189 @deftypefun double gsl_atanh (const double @var{x})
 190 @cindex atanh
 191 @cindex hyperbolic tangent, inverse
 192 @cindex inverse hyperbolic tangent
 193 This function computes the value of @math{\arctanh(x)}. It provides an
 194 alternative to the standard math function @code{atanh(x)}.
 195 @end deftypefun
 196
 197
 198 @deftypefun double gsl_ldexp (double @var{x}, int @var{e})
 199 @cindex ldexp
 200 This function computes the value of @math{x * 2^e}. It provides an
 201 alternative to the standard math function @code{ldexp(x,e)}.
 202 @end deftypefun
 203
 204 @deftypefun double gsl_frexp (double @var{x}, int * @var{e})
 205 @cindex frexp
 206 This function splits the number @math{x} into its normalized fraction
 207 @math{f} and exponent @math{e}, such that @math{x = f * 2^e} and
 208 @c{$0.5 \le f < 1$}
 209 @math{0.5 <= f < 1}. The function returns @math{f} and stores the
 210 exponent in @math{e}. If @math{x} is zero, both @math{f} and @math{e}
 211 are set to zero. This function provides an alternative to the standard
 212 math function @code{frexp(x, e)}.
 213 @end deftypefun
 214
 215 @node Small integer powers
 216 @section Small integer powers
 217
 218 A common complaint about the standard C library is its lack of a
 219 function for calculating (small) integer powers.  GSL provides some simple
 220 functions to fill this gap.  For reasons of efficiency, these functions
 221 do not check for overflow or underflow conditions.
 222
 223 @deftypefun double gsl_pow_int (double @var{x}, int @var{n})
 224 This routine computes the power @math{x^n} for integer @var{n}.  The
 225 power is computed efficiently---for example, @math{x^8} is computed as
 226 @math{((x^2)^2)^2}, requiring only 3 multiplications.  A version of this
 227 function which also computes the numerical error in the result is
 228 available as @code{gsl_sf_pow_int_e}.
 229 @end deftypefun
 230
 231 @deftypefun double gsl_pow_2 (const double @var{x})
 232 @deftypefunx double gsl_pow_3 (const double @var{x})
 233 @deftypefunx double gsl_pow_4 (const double @var{x})
 234 @deftypefunx double gsl_pow_5 (const double @var{x})
 235 @deftypefunx double gsl_pow_6 (const double @var{x})
 236 @deftypefunx double gsl_pow_7 (const double @var{x})
 237 @deftypefunx double gsl_pow_8 (const double @var{x})
 238 @deftypefunx double gsl_pow_9 (const double @var{x})
 239 These functions can be used to compute small integer powers @math{x^2},
 240 @math{x^3}, etc. efficiently. The functions will be inlined when
 241 @code{HAVE_INLINE} is defined, so that use of these functions
 242 should be as efficient as explicitly writing the corresponding
 243 product expression.
 244 @end deftypefun
 245
 246 @example
 247 #include <gsl/gsl_math.h>
 248 double y = gsl_pow_4 (3.141)  /* compute 3.141**4 */
 249 @end example
 250
 251 @node Testing the Sign of Numbers
 252 @section Testing the Sign of Numbers
 253
 254 @defmac GSL_SIGN (x)
 255 This macro returns the sign of @var{x}. It is defined as @code{((x) >= 0
 256 ? 1 : -1)}. Note that with this definition the sign of zero is positive
 257 (regardless of its @sc{ieee} sign bit).
 258 @end defmac
 259
 260 @node Testing for Odd and Even Numbers
 261 @section Testing for Odd and Even Numbers
 262
 263 @defmac GSL_IS_ODD (n)
 264 This macro evaluates to 1 if @var{n} is odd and 0 if @var{n} is
 265 even. The argument @var{n} must be of integer type.
 266 @end defmac
 267
 268 @defmac GSL_IS_EVEN (n)
 269 This macro is the opposite of @code{GSL_IS_ODD(n)}. It evaluates to 1 if
 270 @var{n} is even and 0 if @var{n} is odd. The argument @var{n} must be of
 271 integer type.
 272 @end defmac
 273
 274 @node Maximum and Minimum functions
 275 @section Maximum and Minimum functions
 276
 277 @defmac GSL_MAX (a, b)
 278 @cindex maximum of two numbers
 279 This macro returns the maximum of @var{a} and @var{b}. It is defined as
 280 @code{((a) > (b) ? (a):(b))}.
 281 @end defmac
 282
 283 @defmac GSL_MIN (a, b)
 284 @cindex minimum of two numbers
 285 This macro returns the minimum of @var{a} and @var{b}. It is defined as
 286 @code{((a) < (b) ? (a):(b))}.
 287 @end defmac
 288
 289 @deftypefun {extern inline double} GSL_MAX_DBL (double @var{a}, double @var{b})
 290 This function returns the maximum of the double precision numbers
 291 @var{a} and @var{b} using an inline function. The use of a function
 292 allows for type checking of the arguments as an extra safety feature. On
 293 platforms where inline functions are not available the macro
 294 @code{GSL_MAX} will be automatically substituted.
 295 @end deftypefun
 296
 297 @deftypefun {extern inline double} GSL_MIN_DBL (double @var{a}, double @var{b})
 298 This function returns the minimum of the double precision numbers
 299 @var{a} and @var{b} using an inline function. The use of a function
 300 allows for type checking of the arguments as an extra safety feature. On
 301 platforms where inline functions are not available the macro
 302 @code{GSL_MIN} will be automatically substituted.
 303 @end deftypefun
 304
 305 @deftypefun {extern inline int} GSL_MAX_INT (int @var{a}, int @var{b})
 306 @deftypefunx {extern inline int} GSL_MIN_INT (int @var{a}, int @var{b})
 307 These functions return the maximum or minimum of the integers @var{a}
 308 and @var{b} using an inline function.  On platforms where inline
 309 functions are not available the macros @code{GSL_MAX} or @code{GSL_MIN}
 310 will be automatically substituted.
 311 @end deftypefun
 312
 313 @deftypefun {extern inline long double} GSL_MAX_LDBL (long double @var{a}, long double @var{b})
 314 @deftypefunx {extern inline long double} GSL_MIN_LDBL (long double @var{a}, long double @var{b})
 315 These functions return the maximum or minimum of the long doubles @var{a}
 316 and @var{b} using an inline function.  On platforms where inline
 317 functions are not available the macros @code{GSL_MAX} or @code{GSL_MIN}
 318 will be automatically substituted.
 319 @end deftypefun
 320
 321 @node Approximate Comparison of Floating Point Numbers
 322 @section Approximate Comparison of Floating Point Numbers
 323
 324 It is sometimes useful to be able to compare two floating point numbers
 325 approximately, to allow for rounding and truncation errors.  The following
 326 function implements the approximate floating-point comparison algorithm
 327 proposed by D.E. Knuth in Section 4.2.2 of @cite{Seminumerical
 328 Algorithms} (3rd edition).
 329
 330 @deftypefun int gsl_fcmp (double @var{x}, double @var{y}, double @var{epsilon})
 331 @cindex approximate comparison of floating point numbers
 332 @cindex safe comparison of floating point numbers
 333 @cindex floating point numbers, approximate comparison
 334 This function determines whether @math{x} and @math{y} are approximately
 335 equal to a relative accuracy @var{epsilon}.
 336
 337 The relative accuracy is measured using an interval of size @math{2
 338 \delta}, where @math{\delta = 2^k \epsilon} and @math{k} is the
 339 maximum base-2 exponent of @math{x} and @math{y} as computed by the
 340 function @code{frexp}.
 341
 342 If @math{x} and @math{y} lie within this interval, they are considered
 343 approximately equal and the function returns 0. Otherwise if @math{x <
 344 y}, the function returns @math{-1}, or if @math{x > y}, the function returns
 345 @math{+1}.
 346
 347 Note that @math{x} and @math{y} are compared to relative accuracy, so
 348 this function is not suitable for testing whether a value is
 349 approximately zero.
 350
 351 The implementation is based on the package @code{fcmp} by T.C. Belding.
 352 @end deftypefun