diff options
Diffstat (limited to 'gsl-1.9/doc/math.texi')
| -rw-r--r-- | gsl-1.9/doc/math.texi | 339 |
1 files changed, 339 insertions, 0 deletions
diff --git a/gsl-1.9/doc/math.texi b/gsl-1.9/doc/math.texi new file mode 100644 index 0000000..5f28d71 --- /dev/null +++ b/gsl-1.9/doc/math.texi @@ -0,0 +1,339 @@ +@cindex elementary functions +@cindex mathematical functions, elementary + +This chapter describes basic mathematical functions. Some of these +functions are present in system libraries, but the alternative versions +given here can be used as a substitute when the system functions are not +available. + +The functions and macros described in this chapter are defined in the +header file @file{gsl_math.h}. + +@menu +* Mathematical Constants:: +* Infinities and Not-a-number:: +* Elementary Functions:: +* Small integer powers:: +* Testing the Sign of Numbers:: +* Testing for Odd and Even Numbers:: +* Maximum and Minimum functions:: +* Approximate Comparison of Floating Point Numbers:: +@end menu + +@node Mathematical Constants +@section Mathematical Constants +@cindex mathematical constants, defined as macros +@cindex numerical constants, defined as macros +@cindex constants, mathematical---defined as macros +@cindex macros for mathematical constants +The library ensures that the standard @sc{bsd} mathematical constants +are defined. For reference, here is a list of the constants: + +@table @code +@item M_E +@cindex e, defined as a macro +The base of exponentials, @math{e} + +@item M_LOG2E +The base-2 logarithm of @math{e}, @math{\log_2 (e)} + +@item M_LOG10E +The base-10 logarithm of @math{e}, @c{$\log_{10}(e)$} +@math{\log_10 (e)} + +@item M_SQRT2 +The square root of two, @math{\sqrt 2} + +@item M_SQRT1_2 +The square root of one-half, @c{$\sqrt{1/2}$} +@math{\sqrt@{1/2@}} + +@item M_SQRT3 +The square root of three, @math{\sqrt 3} + +@item M_PI +@cindex pi, defined as a macro +The constant pi, @math{\pi} + +@item M_PI_2 +Pi divided by two, @math{\pi/2} + +@item M_PI_4 +Pi divided by four, @math{\pi/4} + +@item M_SQRTPI +The square root of pi, @math{\sqrt\pi} + +@item M_2_SQRTPI +Two divided by the square root of pi, @math{2/\sqrt\pi} + +@item M_1_PI +The reciprocal of pi, @math{1/\pi} + +@item M_2_PI +Twice the reciprocal of pi, @math{2/\pi} + +@item M_LN10 +The natural logarithm of ten, @math{\ln(10)} + +@item M_LN2 +The natural logarithm of two, @math{\ln(2)} + +@item M_LNPI +The natural logarithm of pi, @math{\ln(\pi)} + +@item M_EULER +@cindex Euler's constant, defined as a macro +Euler's constant, @math{\gamma} + +@end table + +@node Infinities and Not-a-number +@section Infinities and Not-a-number + +@cindex infinity, defined as a macro +@cindex IEEE infinity, defined as a macro +@cindex NaN, defined as a macro +@cindex Not-a-number, defined as a macro +@cindex IEEE NaN, defined as a macro + +@defmac GSL_POSINF +This macro contains the IEEE representation of positive infinity, +@math{+\infty}. It is computed from the expression @code{+1.0/0.0}. +@end defmac + +@defmac GSL_NEGINF +This macro contains the IEEE representation of negative infinity, +@math{-\infty}. It is computed from the expression @code{-1.0/0.0}. +@end defmac + +@defmac GSL_NAN +This macro contains the IEEE representation of the Not-a-Number symbol, +@code{NaN}. It is computed from the ratio @code{0.0/0.0}. +@end defmac + +@deftypefun int gsl_isnan (const double @var{x}) +This function returns 1 if @var{x} is not-a-number. +@end deftypefun + +@deftypefun int gsl_isinf (const double @var{x}) +This function returns @math{+1} if @var{x} is positive infinity, +@math{-1} if @var{x} is negative infinity and 0 otherwise. +@end deftypefun + +@deftypefun int gsl_finite (const double @var{x}) +This function returns 1 if @var{x} is a real number, and 0 if it is +infinite or not-a-number. +@end deftypefun + + +@node Elementary Functions +@section Elementary Functions + +The following routines provide portable implementations of functions +found in the BSD math library. When native versions are not available +the functions described here can be used instead. The substitution can +be made automatically if you use @code{autoconf} to compile your +application (@pxref{Portability functions}). + +@deftypefun double gsl_log1p (const double @var{x}) +@cindex log1p +@cindex logarithm, computed accurately near 1 +This function computes the value of @math{\log(1+x)} in a way that is +accurate for small @var{x}. It provides an alternative to the BSD math +function @code{log1p(x)}. +@end deftypefun + +@deftypefun double gsl_expm1 (const double @var{x}) +@cindex expm1 +@cindex exponential, difference from 1 computed accurately +This function computes the value of @math{\exp(x)-1} in a way that is +accurate for small @var{x}. It provides an alternative to the BSD math +function @code{expm1(x)}. +@end deftypefun + +@deftypefun double gsl_hypot (const double @var{x}, const double @var{y}) +@cindex hypot +@cindex euclidean distance function, hypot +@cindex length, computed accurately using hypot +This function computes the value of +@c{$\sqrt{x^2 + y^2}$} +@math{\sqrt@{x^2 + y^2@}} in a way that avoids overflow. It provides an +alternative to the BSD math function @code{hypot(x,y)}. +@end deftypefun + +@deftypefun double gsl_acosh (const double @var{x}) +@cindex acosh +@cindex hyperbolic cosine, inverse +@cindex inverse hyperbolic cosine +This function computes the value of @math{\arccosh(x)}. It provides an +alternative to the standard math function @code{acosh(x)}. +@end deftypefun + +@deftypefun double gsl_asinh (const double @var{x}) +@cindex asinh +@cindex hyperbolic sine, inverse +@cindex inverse hyperbolic sine +This function computes the value of @math{\arcsinh(x)}. It provides an +alternative to the standard math function @code{asinh(x)}. +@end deftypefun + +@deftypefun double gsl_atanh (const double @var{x}) +@cindex atanh +@cindex hyperbolic tangent, inverse +@cindex inverse hyperbolic tangent +This function computes the value of @math{\arctanh(x)}. It provides an +alternative to the standard math function @code{atanh(x)}. +@end deftypefun + + +@deftypefun double gsl_ldexp (double @var{x}, int @var{e}) +@cindex ldexp +This function computes the value of @math{x * 2^e}. It provides an +alternative to the standard math function @code{ldexp(x,e)}. +@end deftypefun + +@deftypefun double gsl_frexp (double @var{x}, int * @var{e}) +@cindex frexp +This function splits the number @math{x} into its normalized fraction +@math{f} and exponent @math{e}, such that @math{x = f * 2^e} and +@c{$0.5 \le f < 1$} +@math{0.5 <= f < 1}. The function returns @math{f} and stores the +exponent in @math{e}. If @math{x} is zero, both @math{f} and @math{e} +are set to zero. This function provides an alternative to the standard +math function @code{frexp(x, e)}. +@end deftypefun + +@node Small integer powers +@section Small integer powers + +A common complaint about the standard C library is its lack of a +function for calculating (small) integer powers. GSL provides some simple +functions to fill this gap. For reasons of efficiency, these functions +do not check for overflow or underflow conditions. + +@deftypefun double gsl_pow_int (double @var{x}, int @var{n}) +This routine computes the power @math{x^n} for integer @var{n}. The +power is computed efficiently---for example, @math{x^8} is computed as +@math{((x^2)^2)^2}, requiring only 3 multiplications. A version of this +function which also computes the numerical error in the result is +available as @code{gsl_sf_pow_int_e}. +@end deftypefun + +@deftypefun double gsl_pow_2 (const double @var{x}) +@deftypefunx double gsl_pow_3 (const double @var{x}) +@deftypefunx double gsl_pow_4 (const double @var{x}) +@deftypefunx double gsl_pow_5 (const double @var{x}) +@deftypefunx double gsl_pow_6 (const double @var{x}) +@deftypefunx double gsl_pow_7 (const double @var{x}) +@deftypefunx double gsl_pow_8 (const double @var{x}) +@deftypefunx double gsl_pow_9 (const double @var{x}) +These functions can be used to compute small integer powers @math{x^2}, +@math{x^3}, etc. efficiently. The functions will be inlined when +possible so that use of these functions should be as efficient as +explicitly writing the corresponding product expression. +@end deftypefun + +@example +#include <gsl/gsl_math.h> +double y = gsl_pow_4 (3.141) /* compute 3.141**4 */ +@end example + +@node Testing the Sign of Numbers +@section Testing the Sign of Numbers + +@defmac GSL_SIGN (x) +This macro returns the sign of @var{x}. It is defined as @code{((x) >= 0 +? 1 : -1)}. Note that with this definition the sign of zero is positive +(regardless of its @sc{ieee} sign bit). +@end defmac + +@node Testing for Odd and Even Numbers +@section Testing for Odd and Even Numbers + +@defmac GSL_IS_ODD (n) +This macro evaluates to 1 if @var{n} is odd and 0 if @var{n} is +even. The argument @var{n} must be of integer type. +@end defmac + +@defmac GSL_IS_EVEN (n) +This macro is the opposite of @code{GSL_IS_ODD(n)}. It evaluates to 1 if +@var{n} is even and 0 if @var{n} is odd. The argument @var{n} must be of +integer type. +@end defmac + +@node Maximum and Minimum functions +@section Maximum and Minimum functions + +@defmac GSL_MAX (a, b) +@cindex maximum of two numbers +This macro returns the maximum of @var{a} and @var{b}. It is defined as +@code{((a) > (b) ? (a):(b))}. +@end defmac + +@defmac GSL_MIN (a, b) +@cindex minimum of two numbers +This macro returns the minimum of @var{a} and @var{b}. It is defined as +@code{((a) < (b) ? (a):(b))}. +@end defmac + +@deftypefun {extern inline double} GSL_MAX_DBL (double @var{a}, double @var{b}) +This function returns the maximum of the double precision numbers +@var{a} and @var{b} using an inline function. The use of a function +allows for type checking of the arguments as an extra safety feature. On +platforms where inline functions are not available the macro +@code{GSL_MAX} will be automatically substituted. +@end deftypefun + +@deftypefun {extern inline double} GSL_MIN_DBL (double @var{a}, double @var{b}) +This function returns the minimum of the double precision numbers +@var{a} and @var{b} using an inline function. The use of a function +allows for type checking of the arguments as an extra safety feature. On +platforms where inline functions are not available the macro +@code{GSL_MIN} will be automatically substituted. +@end deftypefun + +@deftypefun {extern inline int} GSL_MAX_INT (int @var{a}, int @var{b}) +@deftypefunx {extern inline int} GSL_MIN_INT (int @var{a}, int @var{b}) +These functions return the maximum or minimum of the integers @var{a} +and @var{b} using an inline function. On platforms where inline +functions are not available the macros @code{GSL_MAX} or @code{GSL_MIN} +will be automatically substituted. +@end deftypefun + +@deftypefun {extern inline long double} GSL_MAX_LDBL (long double @var{a}, long double @var{b}) +@deftypefunx {extern inline long double} GSL_MIN_LDBL (long double @var{a}, long double @var{b}) +These functions return the maximum or minimum of the long doubles @var{a} +and @var{b} using an inline function. On platforms where inline +functions are not available the macros @code{GSL_MAX} or @code{GSL_MIN} +will be automatically substituted. +@end deftypefun + +@node Approximate Comparison of Floating Point Numbers +@section Approximate Comparison of Floating Point Numbers + +It is sometimes useful to be able to compare two floating point numbers +approximately, to allow for rounding and truncation errors. The following +function implements the approximate floating-point comparison algorithm +proposed by D.E. Knuth in Section 4.2.2 of @cite{Seminumerical +Algorithms} (3rd edition). + +@deftypefun int gsl_fcmp (double @var{x}, double @var{y}, double @var{epsilon}) +@cindex approximate comparison of floating point numbers +@cindex safe comparison of floating point numbers +@cindex floating point numbers, approximate comparison +This function determines whether @math{x} and @math{y} are approximately +equal to a relative accuracy @var{epsilon}. + +The relative accuracy is measured using an interval of size @math{2 +\delta}, where @math{\delta = 2^k \epsilon} and @math{k} is the +maximum base-2 exponent of @math{x} and @math{y} as computed by the +function @code{frexp}. + +If @math{x} and @math{y} lie within this interval, they are considered +approximately equal and the function returns 0. Otherwise if @math{x < +y}, the function returns @math{-1}, or if @math{x > y}, the function returns +@math{+1}. + +The implementation is based on the package @code{fcmp} by T.C. Belding. +@end deftypefun |