~ubuntu-branches/ubuntu/dapper/gsl-ref-html/dapper : contents of gsl-ref

~ubuntu-branches/ubuntu/dapper/gsl-ref-html/dapper : (revision 4)
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.54+ (gsl)
     from /home/bjg/gsl.redhat/doc/gsl-ref.texi on 14 September 2005 -->

<TITLE>GNU Scientific Library -- Reference Manual - Mathematical Functions</TITLE>
<link href="gsl-ref_5.html" rel=Next>
<link href="gsl-ref_3.html" rel=Previous>
<link href="gsl-ref_toc.html" rel=ToC>

</HEAD>
<BODY>
<p>Go to the <A HREF="gsl-ref_1.html">first</A>, <A HREF="gsl-ref_3.html">previous</A>, <A HREF="gsl-ref_5.html">next</A>, <A HREF="gsl-ref_50.html">last</A> section, <A HREF="gsl-ref_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC32" HREF="gsl-ref_toc.html#TOC32">Mathematical Functions</A></H1>
<P>
<A NAME="IDX60"></A>
<A NAME="IDX61"></A>

</P>
<P>
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.

</P>
<P>
The functions and macros described in this chapter are defined in the
header file <TT>`gsl_math.h'</TT>.

</P>



<H2><A NAME="SEC33" HREF="gsl-ref_toc.html#TOC33">Mathematical Constants</A></H2>
<P>
<A NAME="IDX62"></A>
<A NAME="IDX63"></A>
<A NAME="IDX64"></A>
<A NAME="IDX65"></A>
The library ensures that the standard BSD mathematical constants
are defined. For reference, here is a list of the constants:

</P>
<DL COMPACT>

<DT><CODE>M_E</CODE>
<DD>
<A NAME="IDX66"></A>
The base of exponentials, e

<DT><CODE>M_LOG2E</CODE>
<DD>
The base-2 logarithm of e, \log_2 (e)

<DT><CODE>M_LOG10E</CODE>
<DD>
The base-10 logarithm of e, 
\log_10 (e)

<DT><CODE>M_SQRT2</CODE>
<DD>
The square root of two, \sqrt 2

<DT><CODE>M_SQRT1_2</CODE>
<DD>
The square root of one-half, 
\sqrt{1/2}

<DT><CODE>M_SQRT3</CODE>
<DD>
The square root of three, \sqrt 3

<DT><CODE>M_PI</CODE>
<DD>
<A NAME="IDX67"></A>
The constant pi, \pi

<DT><CODE>M_PI_2</CODE>
<DD>
Pi divided by two, \pi/2

<DT><CODE>M_PI_4</CODE>
<DD>
Pi divided by four, \pi/4

<DT><CODE>M_SQRTPI</CODE>
<DD>
The square root of pi, \sqrt\pi

<DT><CODE>M_2_SQRTPI</CODE>
<DD>
Two divided by the square root of pi, 2/\sqrt\pi

<DT><CODE>M_1_PI</CODE>
<DD>
The reciprocal of pi, 1/\pi

<DT><CODE>M_2_PI</CODE>
<DD>
Twice the reciprocal of pi, 2/\pi

<DT><CODE>M_LN10</CODE>
<DD>
The natural logarithm of ten, \ln(10)

<DT><CODE>M_LN2</CODE>
<DD>
The natural logarithm of two, \ln(2)

<DT><CODE>M_LNPI</CODE>
<DD>
The natural logarithm of pi, \ln(\pi)

<DT><CODE>M_EULER</CODE>
<DD>
<A NAME="IDX68"></A>
Euler's constant, \gamma

</DL>



<H2><A NAME="SEC34" HREF="gsl-ref_toc.html#TOC34">Infinities and Not-a-number</A></H2>

<P>
<A NAME="IDX69"></A>
<A NAME="IDX70"></A>
<A NAME="IDX71"></A>
<A NAME="IDX72"></A>
<A NAME="IDX73"></A>

</P>
<P>
<DL>
<DT><U>Macro:</U> <B>GSL_POSINF</B>
<DD><A NAME="IDX74"></A>
This macro contains the IEEE representation of positive infinity,
+\infty. It is computed from the expression <CODE>+1.0/0.0</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Macro:</U> <B>GSL_NEGINF</B>
<DD><A NAME="IDX75"></A>
This macro contains the IEEE representation of negative infinity,
-\infty. It is computed from the expression <CODE>-1.0/0.0</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Macro:</U> <B>GSL_NAN</B>
<DD><A NAME="IDX76"></A>
This macro contains the IEEE representation of the Not-a-Number symbol,
<CODE>NaN</CODE>. It is computed from the ratio <CODE>0.0/0.0</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_isnan</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX77"></A>
This function returns 1 if <VAR>x</VAR> is not-a-number.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_isinf</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX78"></A>
This function returns +1 if <VAR>x</VAR> is positive infinity,
-1 if <VAR>x</VAR> is negative infinity and 0 otherwise.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_finite</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX79"></A>
This function returns 1 if <VAR>x</VAR> is a real number, and 0 if it is
infinite or not-a-number.
</DL>

</P>



<H2><A NAME="SEC35" HREF="gsl-ref_toc.html#TOC35">Elementary Functions</A></H2>

<P>
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</CODE> to compile your
application (see section <A HREF="gsl-ref_2.html#SEC18">Portability functions</A>).

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_log1p</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX80"></A>
<A NAME="IDX81"></A>
<A NAME="IDX82"></A>
This function computes the value of \log(1+x) in a way that is
accurate for small <VAR>x</VAR>. It provides an alternative to the BSD math
function <CODE>log1p(x)</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_expm1</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX83"></A>
<A NAME="IDX84"></A>
<A NAME="IDX85"></A>
This function computes the value of \exp(x)-1 in a way that is
accurate for small <VAR>x</VAR>. It provides an alternative to the BSD math
function <CODE>expm1(x)</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_hypot</B> <I>(const double <VAR>x</VAR>, const double <VAR>y</VAR>)</I>
<DD><A NAME="IDX86"></A>
<A NAME="IDX87"></A>
<A NAME="IDX88"></A>
<A NAME="IDX89"></A>
This function computes the value of
\sqrt{x^2 + y^2} in a way that avoids overflow. It provides an
alternative to the BSD math function <CODE>hypot(x,y)</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_acosh</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX90"></A>
<A NAME="IDX91"></A>
<A NAME="IDX92"></A>
<A NAME="IDX93"></A>
This function computes the value of \arccosh(x). It provides an
alternative to the standard math function <CODE>acosh(x)</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_asinh</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX94"></A>
<A NAME="IDX95"></A>
<A NAME="IDX96"></A>
<A NAME="IDX97"></A>
This function computes the value of \arcsinh(x). It provides an
alternative to the standard math function <CODE>asinh(x)</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_atanh</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX98"></A>
<A NAME="IDX99"></A>
<A NAME="IDX100"></A>
<A NAME="IDX101"></A>
This function computes the value of \arctanh(x). It provides an
alternative to the standard math function <CODE>atanh(x)</CODE>.
</DL>

</P>

<P>
<DL>
<DT><U>Function:</U> double <B>gsl_ldexp</B> <I>(double <VAR>x</VAR>, int <VAR>e</VAR>)</I>
<DD><A NAME="IDX102"></A>
<A NAME="IDX103"></A>
This function computes the value of x * 2^e. It provides an
alternative to the standard math function <CODE>ldexp(x,e)</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_frexp</B> <I>(double <VAR>x</VAR>, int * <VAR>e</VAR>)</I>
<DD><A NAME="IDX104"></A>
<A NAME="IDX105"></A>
This function splits the number x into its normalized fraction
f and exponent e, such that x = f * 2^e and
0.5 &#60;= f &#60; 1. The function returns f and stores the
exponent in e. If x is zero, both f and e
are set to zero. This function provides an alternative to the standard
math function <CODE>frexp(x, e)</CODE>.
</DL>

</P>


<H2><A NAME="SEC36" HREF="gsl-ref_toc.html#TOC36">Small integer powers</A></H2>

<P>
A common complaint about the standard C library is its lack of a
function for calculating (small) integer powers.  GSL provides a simple
functions to fill this gap.  For reasons of efficiency, these functions
do not check for overflow or underflow conditions. 

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_pow_int</B> <I>(double <VAR>x</VAR>, int <VAR>n</VAR>)</I>
<DD><A NAME="IDX106"></A>
This routine computes the power x^n for integer <VAR>n</VAR>.  The
power is computed efficiently--for example, x^8 is computed as
((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</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_pow_2</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX107"></A>
<DT><U>Function:</U> double <B>gsl_pow_3</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX108"></A>
<DT><U>Function:</U> double <B>gsl_pow_4</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX109"></A>
<DT><U>Function:</U> double <B>gsl_pow_5</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX110"></A>
<DT><U>Function:</U> double <B>gsl_pow_6</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX111"></A>
<DT><U>Function:</U> double <B>gsl_pow_7</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX112"></A>
<DT><U>Function:</U> double <B>gsl_pow_8</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX113"></A>
<DT><U>Function:</U> double <B>gsl_pow_9</B> <I>(const double <VAR>x</VAR>)</I>
<DD><A NAME="IDX114"></A>
These functions can be used to compute small integer powers x^2,
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.
</DL>

</P>

<PRE>
#include &#60;gsl/gsl_math.h&#62;
double y = gsl_pow_4 (3.141)  /* compute 3.141**4 */
</PRE>



<H2><A NAME="SEC37" HREF="gsl-ref_toc.html#TOC37">Testing the Sign of Numbers</A></H2>

<P>
<DL>
<DT><U>Macro:</U> <B>GSL_SIGN</B> <I>(x)</I>
<DD><A NAME="IDX115"></A>
This macro returns the sign of <VAR>x</VAR>. It is defined as <CODE>((x) &#62;= 0
? 1 : -1)</CODE>. Note that with this definition the sign of zero is positive
(regardless of its IEEE sign bit).
</DL>

</P>


<H2><A NAME="SEC38" HREF="gsl-ref_toc.html#TOC38">Testing for Odd and Even Numbers</A></H2>

<P>
<DL>
<DT><U>Macro:</U> <B>GSL_IS_ODD</B> <I>(n)</I>
<DD><A NAME="IDX116"></A>
This macro evaluates to 1 if <VAR>n</VAR> is odd and 0 if <VAR>n</VAR> is
even. The argument <VAR>n</VAR> must be of integer type.
</DL>

</P>
<P>
<DL>
<DT><U>Macro:</U> <B>GSL_IS_EVEN</B> <I>(n)</I>
<DD><A NAME="IDX117"></A>
This macro is the opposite of <CODE>GSL_IS_ODD(n)</CODE>. It evaluates to 1 if
<VAR>n</VAR> is even and 0 if <VAR>n</VAR> is odd. The argument <VAR>n</VAR> must be of
integer type.
</DL>

</P>


<H2><A NAME="SEC39" HREF="gsl-ref_toc.html#TOC39">Maximum and Minimum functions</A></H2>

<P>
<DL>
<DT><U>Macro:</U> <B>GSL_MAX</B> <I>(a, b)</I>
<DD><A NAME="IDX118"></A>
<A NAME="IDX119"></A>
This macro returns the maximum of <VAR>a</VAR> and <VAR>b</VAR>. It is defined as 
<CODE>((a) &#62; (b) ? (a):(b))</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Macro:</U> <B>GSL_MIN</B> <I>(a, b)</I>
<DD><A NAME="IDX120"></A>
<A NAME="IDX121"></A>
This macro returns the minimum of <VAR>a</VAR> and <VAR>b</VAR>. It is defined as 
<CODE>((a) &#60; (b) ? (a):(b))</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> extern inline double <B>GSL_MAX_DBL</B> <I>(double <VAR>a</VAR>, double <VAR>b</VAR>)</I>
<DD><A NAME="IDX122"></A>
This function returns the maximum of the double precision numbers
<VAR>a</VAR> and <VAR>b</VAR> 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</CODE> will be automatically substituted.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> extern inline double <B>GSL_MIN_DBL</B> <I>(double <VAR>a</VAR>, double <VAR>b</VAR>)</I>
<DD><A NAME="IDX123"></A>
This function returns the minimum of the double precision numbers
<VAR>a</VAR> and <VAR>b</VAR> 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</CODE> will be automatically substituted.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> extern inline int <B>GSL_MAX_INT</B> <I>(int <VAR>a</VAR>, int <VAR>b</VAR>)</I>
<DD><A NAME="IDX124"></A>
<DT><U>Function:</U> extern inline int <B>GSL_MIN_INT</B> <I>(int <VAR>a</VAR>, int <VAR>b</VAR>)</I>
<DD><A NAME="IDX125"></A>
These functions return the maximum or minimum of the integers <VAR>a</VAR>
and <VAR>b</VAR> using an inline function.  On platforms where inline
functions are not available the macros <CODE>GSL_MAX</CODE> or <CODE>GSL_MIN</CODE>
will be automatically substituted.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> extern inline long double <B>GSL_MAX_LDBL</B> <I>(long double <VAR>a</VAR>, long double <VAR>b</VAR>)</I>
<DD><A NAME="IDX126"></A>
<DT><U>Function:</U> extern inline long double <B>GSL_MIN_LDBL</B> <I>(long double <VAR>a</VAR>, long double <VAR>b</VAR>)</I>
<DD><A NAME="IDX127"></A>
These functions return the maximum or minimum of the long doubles <VAR>a</VAR>
and <VAR>b</VAR> using an inline function.  On platforms where inline
functions are not available the macros <CODE>GSL_MAX</CODE> or <CODE>GSL_MIN</CODE>
will be automatically substituted.
</DL>

</P>


<H2><A NAME="SEC40" HREF="gsl-ref_toc.html#TOC40">Approximate Comparison of Floating Point Numbers</A></H2>

<P>
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</CITE> (3rd edition).

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_fcmp</B> <I>(double <VAR>x</VAR>, double <VAR>y</VAR>, double <VAR>epsilon</VAR>)</I>
<DD><A NAME="IDX128"></A>
<A NAME="IDX129"></A>
<A NAME="IDX130"></A>
<A NAME="IDX131"></A>
This function determines whether x and y are approximately
equal to a relative accuracy <VAR>epsilon</VAR>.

</P>
<P>
The relative accuracy is measured using an interval of size 2
\delta, where \delta = 2^k \epsilon and k is the
maximum base-2 exponent of x and y as computed by the
function <CODE>frexp()</CODE>.  

</P>
<P>
If x and y lie within this interval, they are considered
approximately equal and the function returns 0. Otherwise if x &#60;
y, the function returns -1, or if x &#62; y, the function returns
+1.

</P>
<P>
The implementation is based on the package <CODE>fcmp</CODE> by T.C. Belding.
</DL>

</P>
<P><HR><P>
<p>Go to the <A HREF="gsl-ref_1.html">first</A>, <A HREF="gsl-ref_3.html">previous</A>, <A HREF="gsl-ref_5.html">next</A>, <A HREF="gsl-ref_50.html">last</A> section, <A HREF="gsl-ref_toc.html">table of contents</A>.
</BODY>
</HTML>