This is gsl-ref.info, produced by Makeinfo version 3.12h from
gsl-ref.texi.

INFO-DIR-SECTION Scientific software
START-INFO-DIR-ENTRY
* gsl-ref: (gsl-ref).                   GNU Scientific Library - Reference
END-INFO-DIR-ENTRY

   This file documents the GNU Scientific Library.

   Copyright (C) 1996, 1997, 1998, 1999 The GSL Project.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.


File: gsl-ref.info,  Node: Exponential Integrals,  Next: Fermi-Dirac Function,  Prev: Exponential Function,  Up: Special Functions

Exponential Integrals
=====================

Exponential Integrals
---------------------

   We have  E_1(x) := Re \int_1^\infty dt \exp(-xt)/t ;  E_2(x) := Re
\int_1^\infty dt \exp(-xt)/t^2 .

 - Function: int gsl_sf_expint_E1_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_expint_E1_e (double x, gsl_sf_result * result)
     Domain: x != 0.0 Exceptional Return Values: GSL_EDOM, GSL_EOVRFLW,
     GSL_EUNDRFLW

 - Function: int gsl_sf_expint_E2_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_expint_E2_e (double x, gsl_sf_result * result)
     Domain: x != 0.0 Exceptional Return Values: GSL_EDOM, GSL_EOVRFLW,
     GSL_EUNDRFLW

Ei(x)
-----

   We have  Ei(x) := PV \int_(-x)^\infty dt \exp(-t)/t .

 - Function: int gsl_sf_expint_Ei_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_expint_Ei_e (double x, gsl_sf_result * result)
     Domain: x != 0.0 Exceptional Return Values: GSL_EDOM, GSL_EOVRFLW,
     GSL_EUNDRFLW

Hyperbolic Integrals
--------------------

   We have  Shi(x) = \int_0^x dt \sinh(t)/t ;  Chi(x) := Re[ M_EULER +
log(x) + \int_0^x dt (Cosh[t]-1)/t .

 - Function: int gsl_sf_Shi_impl (double x, gsl_sf_result * result)
 - Function: int gsl_sf_Shi_e (double x, gsl_sf_result * result)
     Exceptional Return Values: GSL_EOVRFLW, GSL_EUNDRFLW

 - Function: int gsl_sf_Chi_impl (double x, gsl_sf_result * result)
 - Function: int gsl_sf_Chi_e (double x, gsl_sf_result * result)
     Domain: x != 0.0 Exceptional Return Values: GSL_EDOM, GSL_EOVRFLW,
     GSL_EUNDRFLW

Ei_3(x)
-------

   We have  Ei_3(x) = \int_0^x dt \exp(-t^3) .

 - Function: int gsl_sf_expint_3_impl (double x, gsl_sf_result * result)
 - Function: int gsl_sf_expint_3_e (double x, gsl_sf_result * result)
     Domain: x >= 0.0 Exceptional Return Values: GSL_EDOM

Trigonometric Integrals
-----------------------

   We have  Si(x) = \int_0^x dt \sin(t)/t ;  Ci(x) = -\int_x^\infty
\cos(t)/t .

 - Function: int gsl_sf_Si_impl (const double x, gsl_sf_result * result)
 - Function: int gsl_sf_Si_e (double x, gsl_sf_result * result)
     Exceptional Return Values: none

 - Function: int gsl_sf_Ci_impl (const double x, gsl_sf_result * result)
 - Function: int gsl_sf_Ci_e (double x, gsl_sf_result * result)
     Domain: x > 0.0 Exceptional Return Values: GSL_EDOM

Arctangent Integral
-------------------

   We have  AtanInt(x) = \int_0^x dt \arctan(t)/t .

 - Function: int gsl_sf_atanint_impl (double x, gsl_sf_result * result);
 - Function: int gsl_sf_atanint_e (double x, gsl_sf_result * result);
     Domain: Exceptional Return Values:


File: gsl-ref.info,  Node: Fermi-Dirac Function,  Next: Gamma Function,  Prev: Exponential Integrals,  Up: Special Functions

Fermi-Dirac Function
====================

Complete Fermi-Dirac Integrals
------------------------------

   F_j(x)   := 1/Gamma[j+1] Integral[ t^j /(Exp[t-x] + 1),
(t,0,Infinity)]

   /* Complete integral F_(-1)(x) = e^x / (1 + e^x)  *

 - Function: int gsl_sf_fermi_dirac_m1_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_fermi_dirac_m1_e (double x, gsl_sf_result *
          result)
     Exceptional Return Values: GSL_EUNDRFLW

   /* Complete integral F_0(x) = ln(1 + e^x)  *

 - Function: int gsl_sf_fermi_dirac_0_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_fermi_dirac_0_e (double x, gsl_sf_result *
          result)
     Exceptional Return Values: GSL_EUNDRFLW

   /* Complete integral F_1(x)  *

 - Function: int gsl_sf_fermi_dirac_1_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_fermi_dirac_1_e (double x, gsl_sf_result *
          result)
     Exceptional Return Values: GSL_EUNDRFLW, GSL_EOVRFLW

   /* Complete integral F_2(x)  *

 - Function: int gsl_sf_fermi_dirac_2_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_fermi_dirac_2_e (double x, gsl_sf_result *
          result)
     Exceptional Return Values: GSL_EUNDRFLW, GSL_EOVRFLW

   /* Complete integral F_j(x)  * for integer j  *

 - Function: int gsl_sf_fermi_dirac_int_impl (int j, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_fermi_dirac_int_e (int j, double x,
          gsl_sf_result * result)
     Exceptional Return Values: GSL_EUNDRFLW, GSL_EOVRFLW

   /* Complete integral F_(-1/2)(x)  *

 - Function: int gsl_sf_fermi_dirac_mhalf_impl (double x, gsl_sf_result
          * result)
 - Function: int gsl_sf_fermi_dirac_mhalf_e (double x, gsl_sf_result *
          result)
     Exceptional Return Values: GSL_EUNDRFLW, GSL_EOVRFLW

   /* Complete integral F_(1/2)(x)  *

 - Function: int gsl_sf_fermi_dirac_half_impl (double x, gsl_sf_result
          * result)
 - Function: int gsl_sf_fermi_dirac_half_e (double x, gsl_sf_result *
          result)
     Exceptional Return Values: GSL_EUNDRFLW, GSL_EOVRFLW

   /* Complete integral F_(3/2)(x)  *

 - Function: int gsl_sf_fermi_dirac_3half_impl (double x, gsl_sf_result
          * result)
 - Function: int gsl_sf_fermi_dirac_3half_e (double x, gsl_sf_result *
          result)
     Exceptional Return Values: GSL_EUNDRFLW, GSL_EOVRFLW

Incomplete Fermi-Dirac Integrals:
---------------------------------

   F_j(x,b) := 1/Gamma[j+1] Integral[ t^j /(Exp[t-x] + 1),
(t,b,Infinity)]

   /* Incomplete integral F_0(x,b) = ln(1 + e^(b-x)) - (b-x)  *

 - Function: int gsl_sf_fermi_dirac_inc_0_impl (double x, double b,
          gsl_sf_result * result)
 - Function: int gsl_sf_fermi_dirac_inc_0_e (double x, double b,
          gsl_sf_result * result)
     Exceptional Return Values: GSL_EUNDRFLW, GSL_EDOM


File: gsl-ref.info,  Node: Gamma Function,  Next: Gegenbauer Functions,  Prev: Fermi-Dirac Function,  Up: Special Functions

Gamma Function
==============

   /* Log[Gamma(x)], x not a negative integer  * Uses real Lanczos
method.   * Returns the real part of Log[Gamma[x]] when x < 0,  * i.e.
Log[|Gamma[x]|].   *  * exceptions: GSL_EDOM, GSL_EROUND  */ int
gsl_sf_lngamma_impl(double x, gsl_sf_result * result); int
gsl_sf_lngamma_e(double x, gsl_sf_result * result);

   /* Log[Gamma(x)], x not a negative integer  * Uses real Lanczos
method.  Determines  * the sign of Gamma[x] as well as Log[|Gamma[x]|]
for x < 0.   * So Gamma[x] = sgn * Exp[result_lg].   *  * exceptions:
GSL_EDOM, GSL_EROUND  */ int gsl_sf_lngamma_sgn_impl(double x,
gsl_sf_result * result_lg, double *sgn); int
gsl_sf_lngamma_sgn_e(double x, gsl_sf_result * result_lg, double * sgn);

   /* Gamma(x), x not a negative integer  * Uses real Lanczos method.
*  * exceptions: GSL_EDOM, GSL_EOVRFLW, GSL_EROUND  */ int
gsl_sf_gamma_impl(double x, gsl_sf_result * result); int
gsl_sf_gamma_e(double x, gsl_sf_result * result);

   /* Regulated Gamma Function, x > 0  * Gamma^*(x) =
Gamma(x)/(Sqrt[2Pi] x^(x-1/2) exp(-x))  *            = (1 + 1/(12x) +
...),  x->Inf  * A useful suggestion of Temme.   *  * exceptions:
GSL_EDOM  */ int gsl_sf_gammastar_impl(double x, gsl_sf_result *
result); int gsl_sf_gammastar_e(double x, gsl_sf_result * result);

   /* 1/Gamma(x)  * Uses real Lanczos method.   *  * exceptions:
GSL_EUNDRFLW, GSL_EROUND  */ int gsl_sf_gammainv_impl(double x,
gsl_sf_result * result); int gsl_sf_gammainv_e(double x, gsl_sf_result
* result);

   /* Log[Gamma(z)] for z complex, z not a negative integer  * Uses
complex Lanczos method.  Note that the phase part (arg)  * is not
well-determined when |z| is very large, due  * to inevitable roundoff
in restricting to (-Pi,Pi].   * This will raise the GSL_ELOSS exception
when it occurs.   * The absolute value part (lnr), however, never
suffers.   *  * Calculates:  *   lnr = log|Gamma(z)|  *   arg =
arg(Gamma(z))  in (-Pi, Pi]  *  * exceptions: GSL_EDOM, GSL_ELOSS  */
int gsl_sf_lngamma_complex_impl(double zr, double zi, gsl_sf_result *
lnr, gsl_sf_result * arg); int gsl_sf_lngamma_complex_e(double zr,
double zi, gsl_sf_result * lnr, gsl_sf_result * arg);

   /* x^n / n!   *  * x >= 0.0, n >= 0  * exceptions: GSL_EDOM,
GSL_EOVRFLW, GSL_EUNDRFLW  */ int gsl_sf_taylorcoeff_impl(int n, double
x, gsl_sf_result * result); int gsl_sf_taylorcoeff_e(int n, double x,
gsl_sf_result * result);

   /* n!   *  * exceptions: GSL_EDOM, GSL_OVRFLW  */ int
gsl_sf_fact_impl(unsigned int n, gsl_sf_result * result); int
gsl_sf_fact_e(unsigned int n, gsl_sf_result * result);

   /* n!! = n(n-2)(n-4) ...   *  * exceptions: GSL_EDOM, GSL_OVRFLW  */
int gsl_sf_doublefact_impl(unsigned int n, gsl_sf_result * result); int
gsl_sf_doublefact_e(unsigned int n, gsl_sf_result * result);

   /* log(n!)   * Faster than ln(Gamma(n+1)) for n < 170; defers for
larger n.   *  * exceptions: none  */ int gsl_sf_lnfact_impl(unsigned
int n, gsl_sf_result * result); int gsl_sf_lnfact_e(unsigned int n,
gsl_sf_result * result);

   /* log(n!!)   *  * exceptions: none  */ int
gsl_sf_lndoublefact_impl(unsigned int n, gsl_sf_result * result); int
gsl_sf_lndoublefact_e(unsigned int n, gsl_sf_result * result);

   /* log(n choose m)  *  * exceptions: GSL_EDOM  */ int
gsl_sf_lnchoose_impl(unsigned int n, unsigned int m, gsl_sf_result *
result); int gsl_sf_lnchoose_e(unsigned int n, unsigned int m,
gsl_sf_result * result);

   /* n choose m  *  * exceptions: GSL_EDOM, GSL_EOVRFLW  */ int
gsl_sf_choose_impl(unsigned int n, unsigned int m, gsl_sf_result *
result); int gsl_sf_choose_e(unsigned int n, unsigned int m,
gsl_sf_result * result);

   /* Logarithm of Pochammer (Apell) symbol  *   log( (a)_x )  *
where (a)_x := Gamma[a + x]/Gamma[a]  *  * a > 0, a+x > 0  *  *
exceptions:  GSL_EDOM  */ int gsl_sf_lnpoch_impl(double a, double x,
gsl_sf_result * result); int gsl_sf_lnpoch_e(double a, double x,
gsl_sf_result * result);

   /* Logarithm of Pochammer (Apell) symbol, with sign information.   *
 result = log( |(a)_x| )  *   sgn    = sgn( (a)_x )  *   where (a)_x
:= Gamma[a + x]/Gamma[a]  *  * a != neg integer, a+x != neg integer  *
* exceptions:  GSL_EDOM  */ int gsl_sf_lnpoch_sgn_impl(double a, double
x, gsl_sf_result * result, double * sgn); int
gsl_sf_lnpoch_sgn_e(double a, double x, gsl_sf_result * result, double
* sgn);

   /* Pochammer (Apell) symbol  *   (a)_x := Gamma[a + x]/Gamma[x]  *
* a != neg integer, a+x != neg integer  *  * exceptions:  GSL_EDOM,
GSL_EOVRFLW  */ int gsl_sf_poch_impl(double a, double x, gsl_sf_result
* result); int gsl_sf_poch_e(double a, double x, gsl_sf_result *
result);

   /* Relative Pochammer (Apell) symbol  *   ((a,x) - 1)/x  *   where
(a,x) = (a)_x := Gamma[a + x]/Gamma[a]  *  * exceptions:  GSL_EDOM  */
int gsl_sf_pochrel_impl(double a, double x, gsl_sf_result * result);
int gsl_sf_pochrel_e(double a, double x, gsl_sf_result * result);

   /* Normalized Incomplete Gamma Function  *  * Q(a,x) = 1/Gamma(a)
Integral[ t^(a-1) e^(-t), (t,x,Infinity) ]  *  * a > 0, x >= 0  *  *
exceptions: GSL_EDOM  */ int gsl_sf_gamma_inc_Q_impl(double a, double
x, gsl_sf_result * result); int gsl_sf_gamma_inc_Q_e(double a, double
x, gsl_sf_result * result);

   /* Complementary Normalized Incomplete Gamma Function  *  * P(a,x) =
1/Gamma(a) Integral[ t^(a-1) e^(-t), (t,0,x) ]  *  * a > 0, x >= 0  *
* exceptions: GSL_EDOM  */ int gsl_sf_gamma_inc_P_impl(double a, double
x, gsl_sf_result * result); int gsl_sf_gamma_inc_P_e(double a, double
x, gsl_sf_result * result);

   /* Logarithm of Beta Function  * Log[B(a,b)]  *  * a > 0, b > 0  *
exceptions: GSL_EDOM  */ int gsl_sf_lnbeta_impl(double a, double b,
gsl_sf_result * result); int gsl_sf_lnbeta_e(double a, double b,
gsl_sf_result * result);

   /* Beta Function  * B(a,b)  *  * a > 0, b > 0  * exceptions:
GSL_EDOM, GSL_EOVRFLW, GSL_EUNDRFLW  */ int gsl_sf_beta_impl(double a,
double b, gsl_sf_result * result); int gsl_sf_beta_e(double a, double
b, gsl_sf_result * result);

   /* The maximum x such that gamma(x) is not  * considered an overflow.
*/ #define GSL_SF_GAMMA_XMAX  171.0


File: gsl-ref.info,  Node: Gegenbauer Functions,  Next: Hypergeometric Functions,  Prev: Gamma Function,  Up: Special Functions

Gegenbauer Functions
====================

 - Function: int gsl_sf_gegenpoly_1_impl (double lambda, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_gegenpoly_2_impl (double lambda, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_gegenpoly_3_impl (double lambda, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_gegenpoly_1_e (double lambda, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_gegenpoly_2_e (double lambda, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_gegenpoly_3_e (double lambda, double x,
          gsl_sf_result * result)
     Evaluate Gegenbauer polynomials using explicit representations.
     Exceptional Return Values: none

 - Function: int gsl_sf_gegenpoly_n_impl (int n, double lambda, double
          x, gsl_sf_result * result)
 - Function: int gsl_sf_gegenpoly_n_e (int n, double lambda, double x,
          gsl_sf_result * result)
     Evaluate Gegenbauer polynomials.  Domain: lambda > -1/2, n >= 0
     Exceptional Return Values: GSL_EDOM

 - Function: int gsl_sf_gegenpoly_array_impl (int nmax, double lambda,
          double x, double * result_array);
 - Function: int gsl_sf_gegenpoly_array_e (int nmax, double lambda,
          double x, double * result_array);
     Calculate array of Gegenbauer polynomials.  Conditions: n = 0, 1,
     2, ... nmax Domain: lambda > -1/2, nmax >= 0 Exceptional Return
     Values: GSL_EDOM


File: gsl-ref.info,  Node: Hypergeometric Functions,  Next: Laguerre Functions,  Prev: Gegenbauer Functions,  Up: Special Functions

Hypergeometric Functions
========================

   /* Hypergeometric function related to Bessel functions  * 0F1[c,x] =
*            Gamma[c]    x^(1/2(1-c)) I_(c-1)(2 Sqrt[x])  *
Gamma[c] (-x)^(1/2(1-c)) J_(c-1)(2 Sqrt[-x])  *  * exceptions:
GSL_EOVRFLW, GSL_EUNDRFLW  */ int gsl_sf_hyperg_0F1_impl(double c,
double x, gsl_sf_result * result); int gsl_sf_hyperg_0F1_e(double c,
double x, gsl_sf_result * result);

   /* Confluent hypergeometric function  for integer parameters.   *
1F1[m,n,x] = M(m,n,x)  *  * exceptions:  */ int
gsl_sf_hyperg_1F1_int_impl(int m, int n, double x, gsl_sf_result *
result); int gsl_sf_hyperg_1F1_int_e(int m, int n, double x,
gsl_sf_result * result);

   /* Confluent hypergeometric function.   * 1F1[a,b,x] = M(a,b,x)  *
* exceptions:  */ int gsl_sf_hyperg_1F1_impl(double a, double b, double
x, gsl_sf_result * result); int gsl_sf_hyperg_1F1_e(double a, double b,
double x, gsl_sf_result * result);

   /* Confluent hypergeometric function for integer parameters.   *
U(m,n,x)  *  * exceptions:  */ int gsl_sf_hyperg_U_int_impl(int m, int
n, double x, gsl_sf_result * result); int gsl_sf_hyperg_U_int_e(int m,
int n, double x, gsl_sf_result * result);

   /* Confluent hypergeometric function for integer parameters.   *
U(m,n,x)  *  * exceptions:  */ int gsl_sf_hyperg_U_int_e10_impl(int m,
int n, double x, gsl_sf_result_e10 * result); int
gsl_sf_hyperg_U_int_e10_e(int m, int n, double x, gsl_sf_result_e10 *
result);

   /* Confluent hypergeometric function.   * U(a,b,x)  *  * exceptions:
*/ int gsl_sf_hyperg_U_impl(double a, double b, double x,
gsl_sf_result * result); int gsl_sf_hyperg_U_e(double a, double b,
double x, gsl_sf_result * result);

   /* Confluent hypergeometric function.   * U(a,b,x)  *  * exceptions:
*/ int gsl_sf_hyperg_U_e10_impl(double a, double b, double x,
gsl_sf_result_e10 * result); int gsl_sf_hyperg_U_e10_e(double a, double
b, double x, gsl_sf_result_e10 * result);

   /* Gauss hypergeometric function 2F1[a,b,c,x]  * |x| < 1  *  *
exceptions:  */ int gsl_sf_hyperg_2F1_impl(double a, double b, double
c, double x, gsl_sf_result * result); int gsl_sf_hyperg_2F1_e(double a,
double b, double c, double x, gsl_sf_result * result);

   /* Gauss hypergeometric function  * 2F1[aR + I aI, aR - I aI, c, x]
* |x| < 1  *  * exceptions:  */ int gsl_sf_hyperg_2F1_conj_impl(double
aR, double aI, double c, double x, gsl_sf_result * result); int
gsl_sf_hyperg_2F1_conj_e(double aR, double aI, double c, double x,
gsl_sf_result * result);

   /* Renormalized Gauss hypergeometric function  * 2F1[a,b,c,x] /
Gamma[c]  * |x| < 1  *  * exceptions:  */ int
gsl_sf_hyperg_2F1_renorm_impl(double a, double b, double c, double x,
gsl_sf_result * result); int gsl_sf_hyperg_2F1_renorm_e(double a,
double b, double c, double x, gsl_sf_result * result);

   /* Renormalized Gauss hypergeometric function  * 2F1[aR + I aI, aR -
I aI, c, x] / Gamma[c]  * |x| < 1  *  * exceptions:  */ int
gsl_sf_hyperg_2F1_conj_renorm_impl(double aR, double aI, double c,
double x, gsl_sf_result * result); int
gsl_sf_hyperg_2F1_conj_renorm_e(double aR, double aI, double c, double
x, gsl_sf_result * result);

   /* Mysterious hypergeometric function.  The series representation  *
is a divergent hypergeometric series.  However, for x < 0 we  * have
2F0(a,b,x) = (-1/x)^a U(a,1+a-b,-1/x)  *  * exceptions: GSL_EDOM  */
int     gsl_sf_hyperg_2F0_impl(double a, double b, double x,
gsl_sf_result * result); int     gsl_sf_hyperg_2F0_e(double a, double
b, double x, gsl_sf_result * result);


File: gsl-ref.info,  Node: Laguerre Functions,  Next: Legendre Functions and Spherical Harmonics,  Prev: Hypergeometric Functions,  Up: Special Functions

Laguerre Functions
==================

   The Laguerre polynomials are defined in terms of confluent
hypergeometric functions as  L^a_n(x) = (a+1)_n / n! 1F1(-n,a+1,x) .

 - Function: int gsl_sf_laguerre_1_impl (double a, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_laguerre_2_impl (double a, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_laguerre_3_impl (double a, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_laguerre_1_e (double a, double x, gsl_sf_result
          * result)
 - Function: int gsl_sf_laguerre_2_e (double a, double x, gsl_sf_result
          * result)
 - Function: int gsl_sf_laguerre_3_e (double a, double x, gsl_sf_result
          * result)
     Evaluate generalized Laguerre polynomials using explicit
     representations.  Exceptional Return Values: none

 - Function: int gsl_sf_laguerre_n_impl (const int n, const double a,
          const double x, gsl_sf_result * result)
 - Function: int gsl_sf_laguerre_n_e (int n, double a, double x,
          gsl_sf_result * result)
     Domain: a > -1.0, n >= 0 Evaluate generalized Laguerre polynomials.
     Exceptional Return Values: GSL_EDOM


File: gsl-ref.info,  Node: Legendre Functions and Spherical Harmonics,  Next: Logarithm and Related Functions,  Prev: Laguerre Functions,  Up: Special Functions

Legendre Functions and Spherical Harmonics
==========================================

Legendre Polynomials
--------------------

   /* P_l(x), l=1,2,3  *

 - Function: int gsl_sf_legendre_P1_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_legendre_P2_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_legendre_P3_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_legendre_P1_e (double x, gsl_sf_result * result)
 - Function: int gsl_sf_legendre_P2_e (double x, gsl_sf_result * result)
 - Function: int gsl_sf_legendre_P3_e (double x, gsl_sf_result * result)
     Exceptional Return Values: none

   /* P_l(x)   l >= 0; |x| <= 1  *

 - Function: int gsl_sf_legendre_Pl_impl (int l, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_legendre_Pl_e (int l, double x, gsl_sf_result *
          result)
     Exceptional Return Values: GSL_EDOM

   /* P_l(x) for l=0,...,lmax; |x| <= 1  *

 - Function: int gsl_sf_legendre_Pl_array_impl (int lmax, double x,
          double * result_array)
 - Function: int gsl_sf_legendre_Pl_array_e (int lmax, double x, double
          * result_array)
     Exceptional Return Values: GSL_EDOM

   /* Q_0(x), x > -1, x != 1  *

 - Function: int gsl_sf_legendre_Q0_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_legendre_Q0_e (double x, gsl_sf_result * result)
     Exceptional Return Values: GSL_EDOM

   /* Q_1(x), x > -1, x != 1  *

 - Function: int gsl_sf_legendre_Q1_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_legendre_Q1_e (double x, gsl_sf_result * result)
     Exceptional Return Values: GSL_EDOM

   /* Q_l(x), x > -1, x != 1, l >= 0  *

 - Function: int gsl_sf_legendre_Ql_impl (int l, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_legendre_Ql_e (int l, double x, gsl_sf_result *
          result)
     Exceptional Return Values: GSL_EDOM

Associated Legendre Polynomials and Spherical Harmonics
-------------------------------------------------------

   /* P_l^m(x)  m >= 0; l >= m; |x| <= 1.0  *  * Note that this
function grows combinatorially with l.   * Therefore we can easily
generate an overflow for l larger  * than about 150.   *  * There is no
trouble for small m, but when m and l are both large,  * then there
will be trouble.  Rather than allow overflows, these  * functions
refuse to calculate when they can sense that l and m are  * too big.   *
* If you really want to calculate a spherical harmonic, then DO NOT  *
use this.  Instead use legendre_sphPlm() below, which  uses a similar
* recursion, but with the normalized functions.   *

 - Function: int gsl_sf_legendre_Plm_impl (int l, int m, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_legendre_Plm_e (int l, int m, double x,
          gsl_sf_result * result)
     Exceptional Return Values: GSL_EDOM, GSL_EOVRFLW

   /* P_l^m(x)  m >= 0; l >= m; |x| <= 1.0  * l=|m|,...,lmax  *

 - Function: int gsl_sf_legendre_Plm_array_impl (int lmax, int m,
          double x, double * result_array)
 - Function: int gsl_sf_legendre_Plm_array_e (int lmax, int m, double
          x, double * result_array)
     Exceptional Return Values: GSL_EDOM, GSL_EOVRFLW

   /* P_l^m(x), normalized properly for use in spherical harmonics  * m
>= 0; l >= m; |x| <= 1.0  *  * There is no overflow problem, as there
is for the  * standard normalization of P_l^m(x).   *  * Specifically,
it returns:  *  *        sqrt((2l+1)/(4pi)) sqrt((l-m)!/(l+m)!) P_l^m(x)
*

 - Function: int gsl_sf_legendre_sphPlm_impl (int l, int m, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_legendre_sphPlm_e (int l, int m, double x,
          gsl_sf_result * result)
     Exceptional Return Values: GSL_EDOM

   /* P_l^m(x), normalized properly for use in spherical harmonics  * m
>= 0; l >= m; |x| <= 1.0  * l=|m|,...,lmax  *

 - Function: int gsl_sf_legendre_sphPlm_array_impl (int lmax, int m,
          double x, double * result_array)
 - Function: int gsl_sf_legendre_sphPlm_array_e (int lmax, int m,
          double x, double * result_array)
     Exceptional Return Values: GSL_EDOM

   /* size of result_array[] needed for the array versions of Plm  *
(lmax - m + 1)  */

 - Function: int gsl_sf_legendre_array_size (const int lmax, const int
          m)
     Exceptional Return Values: none

Conical Functions
-----------------

   /* Irregular Spherical Conical Function  * P^(1/2)_(-1/2 + I
lambda)(x)  *  * x > -1.0

 - Function: int gsl_sf_conicalP_half_impl (double lambda, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_conicalP_half_e (double lambda, double x,
          gsl_sf_result * result)
     Exceptional Return Values: GSL_EDOM

   /* Regular Spherical Conical Function  * P^(-1/2)_(-1/2 + I
lambda)(x)  *  * x > -1.0

 - Function: int gsl_sf_conicalP_mhalf_impl (double lambda, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_conicalP_mhalf_e (double lambda, double x,
          gsl_sf_result * result)
     Exceptional Return Values: GSL_EDOM

   /* Conical Function  * P^(0)_(-1/2 + I lambda)(x)  *  * x > -1.0

 - Function: int gsl_sf_conicalP_0_impl (double lambda, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_conicalP_0_e (double lambda, double x,
          gsl_sf_result * result)
     Exceptional Return Values: GSL_EDOM

   /* Conical Function  * P^(1)_(-1/2 + I lambda)(x)  *  * x > -1.0

 - Function: int gsl_sf_conicalP_1_impl (double lambda, double x,
          gsl_sf_result * result)
 - Function: int gsl_sf_conicalP_1_e (double lambda, double x,
          gsl_sf_result * result)
     Exceptional Return Values: GSL_EDOM

   /* Regular Spherical Conical Function  * P^(-1/2-l)_(-1/2 + I
lambda)(x)  *  * x > -1.0, l >= -1

 - Function: int gsl_sf_conicalP_sph_reg_impl (int l, double lambda,
          double x, gsl_sf_result * result)
 - Function: int gsl_sf_conicalP_sph_reg_e (int l, double lambda,
          double x, gsl_sf_result * result)
     Exceptional Return Values: GSL_EDOM

   /* Regular Cylindrical Conical Function  * P^(-m)_(-1/2 + I
lambda)(x)  *  * x > -1.0, m >= -1

 - Function: int gsl_sf_conicalP_cyl_reg_impl (int m, double lambda,
          double x, gsl_sf_result * result)
 - Function: int gsl_sf_conicalP_cyl_reg_e (int m, double lambda,
          double x, gsl_sf_result * result)
     Exceptional Return Values: GSL_EDOM

Radial Functions for Hyperbolic Space
-------------------------------------

   /* The following spherical functions are specializations  * of
Legendre functions which give the regular eigenfunctions  * of the
Laplacian on a 3-dimensional hyperbolic space.   * Of particular
interest is the flat limit, which is  * Flat-Lim := (lambda->Inf,
eta->0, lambda*eta fixed).   */

   /* Zeroth radial eigenfunction of the Laplacian on the  *
3-dimensional hyperbolic space.   *  * legendre_H3d_0(lambda,eta) :=
sin(lambda*eta)/(lambda*sinh(eta))  *  * Normalization:  * Flat-Lim
legendre_H3d_0(lambda,eta) = j_0(lambda*eta)  *  * eta >= 0.0

 - Function: int gsl_sf_legendre_H3d_0_impl (double lambda, double eta,
          gsl_sf_result * result)
 - Function: int gsl_sf_legendre_H3d_0_e (double lambda, double eta,
          gsl_sf_result * result)
     Exceptional Return Values: GSL_EDOM

   /* First radial eigenfunction of the Laplacian on the  *
3-dimensional hyperbolic space.   *  * legendre_H3d_1(lambda,eta) :=  *
  1/sqrt(lambda^2 + 1) sin(lam eta)/(lam sinh(eta))  *    (coth(eta) -
lambda cot(lambda*eta))  *  * Normalization:  * Flat-Lim
legendre_H3d_1(lambda,eta) = j_1(lambda*eta)  *  * eta >= 0.0

 - Function: int gsl_sf_legendre_H3d_1_impl (double lambda, double eta,
          gsl_sf_result * result)
 - Function: int gsl_sf_legendre_H3d_1_e (double lambda, double eta,
          gsl_sf_result * result)
     Exceptional Return Values: GSL_EDOM

   /* l'th radial eigenfunction of the Laplacian on the  *
3-dimensional hyperbolic space.   *  * Normalization:  * Flat-Lim
legendre_H3d_l(l,lambda,eta) = j_l(lambda*eta)  *  * eta >= 0.0, l >= 0

 - Function: int gsl_sf_legendre_H3d_impl (int l, double lambda, double
          eta, gsl_sf_result * result)
 - Function: int gsl_sf_legendre_H3d_e (int l, double lambda, double
          eta, gsl_sf_result * result)
     Exceptional Return Values: GSL_EDOM

   /* Array of H3d(ell),  0 <= ell <= lmax  */

 - Function: int gsl_sf_legendre_H3d_array_impl (int lmax, double
          lambda, double eta, double * result_array)
 - Function: int gsl_sf_legendre_H3d_array_e (int lmax, double lambda,
          double eta, double * result_array)
     Exceptional Return Values:


File: gsl-ref.info,  Node: Logarithm and Related Functions,  Next: Polynomial Manipulation,  Prev: Legendre Functions and Spherical Harmonics,  Up: Special Functions

Logarithm and Related Functions
===============================

 - Function: int gsl_sf_log_impl (double x, gsl_sf_result * result)
 - Function: int gsl_sf_log_e (double x, gsl_sf_result * result)
     Domain: x > 0.0 Exceptional Return Values: GSL_EDOM

 - Function: int gsl_sf_log_abs_impl (double x, gsl_sf_result * result)
 - Function: int gsl_sf_log_abs_e (double x, gsl_sf_result * result)
     \log(|x|) Domain: x != 0.0 Exceptional Return Values: GSL_EDOM

   /* Complex Logarithm  *   exp(lnr + I theta) = zr + I zi  * Returns
argument in [-pi,pi].   *

 - Function: int gsl_sf_complex_log_impl (double zr, double zi,
          gsl_sf_result * lnr, gsl_sf_result * theta)
 - Function: int gsl_sf_complex_log_e (double zr, double zi,
          gsl_sf_result * lnr, gsl_sf_result * theta)
     Exceptional Return Values: GSL_EDOM

 - Function: int gsl_sf_log_1plusx_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_log_1plusx_e (double x, gsl_sf_result * result)
     \log(1 + x) Domain: x > -1.0 Exceptional Return Values: GSL_EDOM

 - Function: int gsl_sf_log_1plusx_mx_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_log_1plusx_mx_e (double x, gsl_sf_result *
          result)
     \log(1 + x) - x Domain: x > -1.0 Exceptional Return Values:
     GSL_EDOM


File: gsl-ref.info,  Node: Polynomial Manipulation,  Next: Power Function,  Prev: Logarithm and Related Functions,  Up: Special Functions

Polynomial Manipulation
=======================

 - Function: double gsl_sf_poly_eval (const double c[], const int len,
          const double x)
     Evaluate a polynomial,  c[0] + c[1] x + c[2] x^2 + ... + c[len-1]
     x^(len-1) .  Exceptional Return Values: none


File: gsl-ref.info,  Node: Power Function,  Next: Psi (Digamma) Function,  Prev: Polynomial Manipulation,  Up: Special Functions

Power Function
==============

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

   int     gsl_sf_pow_int_impl(double x, int n, gsl_sf_result * result);
int     gsl_sf_pow_int_e(double x, int n, gsl_sf_result * result);

 - Function: double gsl_sf_pow_int (double x, int n)

   double gsl_sf_pow_2(const double x); double gsl_sf_pow_3(const
double x); double gsl_sf_pow_4(const double x); double
gsl_sf_pow_5(const double x); double gsl_sf_pow_6(const double x);
double gsl_sf_pow_7(const double x); double gsl_sf_pow_8(const double
x); double gsl_sf_pow_9(const double x);

     #include <gsl/gsl_sf_pow_int.h>
     double y = gsl_sf_pow_int(3.0, 12)


File: gsl-ref.info,  Node: Psi (Digamma) Function,  Next: Synchrotron Functions,  Prev: Power Function,  Up: Special Functions

Psi (Digamma) Function
======================

   The poly-gamma functions are defined by  psi(m,x) = (d/dx)^m
psi(0,x) = (d/dx)^(m+1) log(gamma(x)) , where  \psi(0,x)  is called the
di-gamma function.

Digamma Function
----------------

 - Function: int gsl_sf_psi_int_impl (int n, gsl_sf_result * result)
 - Function: int gsl_sf_psi_int_e (int n, gsl_sf_result * result)
     Domain: n integer, n > 0 Exceptional Return Values: GSL_EDOM

 - Function: int gsl_sf_psi_impl (double x, gsl_sf_result * result)
 - Function: int gsl_sf_psi_e (double x, gsl_sf_result * result)
     Domain: x != 0.0 Exceptional Return Values: GSL_EDOM, GSL_ELOSS

   /* Di-Gamma Function Re[psi(1 + I y)]  *  * exceptions: none  */

 - Function: int gsl_sf_psi_1piy_impl (double y, gsl_sf_result * result)
 - Function: int gsl_sf_psi_1piy_e (double y, gsl_sf_result * result)
     Computes  Re psi(1 + I y) .  Exceptional Return Values: none

Trigamma Function
-----------------

 - Function: int gsl_sf_psi_1_int_impl (int n, gsl_sf_result * result)
 - Function: int gsl_sf_psi_1_int_e (int n, gsl_sf_result * result)
     Domain: n integer, n > 0 Exceptional Return Values: GSL_EDOM

Polygamma Function
------------------

 - Function: int gsl_sf_psi_n_impl (int m, double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_psi_n_e (int m, double x, gsl_sf_result *
          result)
     Domain: m >= 0, x > 0.0 Exceptional Return Values: GSL_EDOM


File: gsl-ref.info,  Node: Synchrotron Functions,  Next: Transport Functions,  Prev: Psi (Digamma) Function,  Up: Special Functions

Synchrotron Functions
=====================

   The first synchrotron function is defined by the integral
representation  synchrotron_1(x) = x \int_x^\infty dt K_(5/3)(t) .

 - Function: int gsl_sf_synchrotron_1_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_synchrotron_1_e (double x, gsl_sf_result *
          result)
     Domain: x >= 0.0 Exceptional Return Values: GSL_EDOM, GSL_EUNDRFLW

   The second synchroton function is defined by  synchrotron_2(x) = x *
K_(2/3)(x) .

 - Function: int gsl_sf_synchrotron_2_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_synchrotron_2_e (double x, gsl_sf_result *
          result)
     Domain: x >= 0.0 Exceptional Return Values: GSL_EDOM, GSL_EUNDRFLW


File: gsl-ref.info,  Node: Transport Functions,  Next: Trigonometric Functions,  Prev: Synchrotron Functions,  Up: Special Functions

Transport Functions
===================

   The transport functions are defined by the integral representations
J(n,x) := \int_0^x dt t^n e^t /(e^t - 1)^2 .

 - Function: int gsl_sf_transport_2_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_transport_2_e (double x, gsl_sf_result * result)
     Calculates J(2,x).  Exceptional Return Values: GSL_EDOM

 - Function: int gsl_sf_transport_3_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_transport_3_e (double x, gsl_sf_result * result)
     Calculates J(3,x).  Exceptional Return Values: GSL_EDOM,
     GSL_EUNDRFLW

 - Function: int gsl_sf_transport_4_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_transport_4_e (double x, gsl_sf_result * result)
     Calculates J(4,x).  Exceptional Return Values: GSL_EDOM,
     GSL_EUNDRFLW

 - Function: int gsl_sf_transport_5_impl (double x, gsl_sf_result *
          result)
 - Function: int gsl_sf_transport_5_e (double x, gsl_sf_result * result)
     Calculates J(5,x).  Exceptional Return Values: GSL_EDOM,
     GSL_EUNDRFLW


File: gsl-ref.info,  Node: Trigonometric Functions,  Next: Zeta Functions,  Prev: Transport Functions,  Up: Special Functions

Trigonometric Functions
=======================

Trigonometric Functions
-----------------------

   These simple trogonometric functions are important because we want
to control the error estimate, and trying to guess the error for the
standard library implementation every time it is used would be a little
goofy.

 - Function: int gsl_sf_sin_impl (double x, gsl_sf_result * result);
 - Function: int gsl_sf_sin_e (double x, gsl_sf_result * result);
     Exceptional Return Values:

 - Function: int gsl_sf_cos_impl (double x, gsl_sf_result * result);
 - Function: int gsl_sf_cos_e (double x, gsl_sf_result * result);
     Exceptional Return Values:

 - Function: int gsl_sf_hypot_impl (double x, double y, gsl_sf_result *
          result);
 - Function: int gsl_sf_hypot_e (double x, double y, gsl_sf_result *
          result);
     Exceptional Return Values:

 - Function: int gsl_sf_complex_sin_impl (double zr, double zi,
          gsl_sf_result * szr, gsl_sf_result * szi);
 - Function: int gsl_sf_complex_sin_e (double zr, double zi,
          gsl_sf_result * szr, gsl_sf_result * szi);
     Sin(z) Exceptional Return Values: GSL_EOVRFLW

 - Function: int gsl_sf_complex_cos_impl (double zr, double zi,
          gsl_sf_result * czr, gsl_sf_result * czi);
 - Function: int gsl_sf_complex_cos_e (double zr, double zi,
          gsl_sf_result * czr, gsl_sf_result * czi);
     Cos(z) Exceptional Return Values: GSL_EOVRFLW

 - Function: int gsl_sf_complex_logsin_impl (double zr, double zi,
          gsl_sf_result * lszr, gsl_sf_result * lszi);
 - Function: int gsl_sf_complex_logsin_e (double zr, double zi,
          gsl_sf_result * lszr, gsl_sf_result * lszi);
     Log(Sin(z)) Exceptional Return Values: GSL_EDOM, GSL_ELOSS

 - Function: int gsl_sf_sinc_impl (double x, gsl_sf_result * result);
 - Function: int gsl_sf_sinc_e (double x, gsl_sf_result * result);
     Sinc(x) = sin(pi x) / (pi x) Exceptional Return Values: none

 - Function: int gsl_sf_lnsinh_impl (double x, gsl_sf_result * result);
 - Function: int gsl_sf_lnsinh_e (double x, gsl_sf_result * result);
     Log(Sinh(x)) Domain: x > 0 Exceptional Return Values: GSL_EDOM

 - Function: int gsl_sf_lncosh_impl (double x, gsl_sf_result * result);
 - Function: int gsl_sf_lncosh_e (double x, gsl_sf_result * result);
     Log(Cosh(x)) Exceptional Return Values: none

Conversion Functions
--------------------

 - Function: int gsl_sf_polar_to_rect_impl (double r, double theta,
          gsl_sf_result * x, gsl_sf_result * y);
 - Function: int gsl_sf_polar_to_rect_e (double r, double theta,
          gsl_sf_result * x, gsl_sf_result * y);
     Convert polar to rectlinear coordinates.  Exceptional Return
     Values: GSL_ELOSS

 - Function: int gsl_sf_rect_to_polar_impl (double x, double y,
          gsl_sf_result * r, gsl_sf_result * theta)
 - Function: int gsl_sf_rect_to_polar_e (double x, double y,
          gsl_sf_result * r, gsl_sf_result * theta)
     Convert rectilinear to polar coordinates.  Return argument in
     range [-pi, pi].  Exceptional Return Values: GSL_EDOM

Restriction Functions
---------------------

 - Function: int gsl_sf_angle_restrict_symm_impl (double * theta);
 - Function: int gsl_sf_angle_restrict_symm_e (double * theta);
     Force an angle to lie in the range (-pi,pi].  Exceptional Return
     Values: GSL_ELOSS

 - Function: int gsl_sf_angle_restrict_pos_impl (double * theta);
 - Function: int gsl_sf_angle_restrict_pos_e (double * theta);
     Force an angle to lie in the range [0, 2pi).  Exceptional Return
     Values: GSL_ELOSS

   Trigonometric Functions With Error Estimate

 - Function: int gsl_sf_sin_err_impl (double x, double dx,
          gsl_sf_result * result);
 - Function: int gsl_sf_sin_err_e (double x, double dx, gsl_sf_result *
          result);

 - Function: int gsl_sf_cos_err_impl (double x, double dx,
          gsl_sf_result * result);
 - Function: int gsl_sf_cos_err_e (double x, double dx, gsl_sf_result *
          result);


File: gsl-ref.info,  Node: Zeta Functions,  Prev: Trigonometric Functions,  Up: Special Functions

Zeta Functions
==============

Riemann Zeta Function
---------------------

   The Riemann zeta function is defined by

 - Function: int gsl_sf_zeta_int_impl (int n, gsl_sf_result * result)
 - Function: int gsl_sf_zeta_int_e (int n, gsl_sf_result * result)
     Domain: n integer, n != 1 Exceptional Return Values: GSL_EDOM,
     GSL_EOVRFLW

 - Function: int gsl_sf_zeta_impl (double s, gsl_sf_result * result)
 - Function: int gsl_sf_zeta_e (double s, gsl_sf_result * result)
     Domain: s != 1.0 Exceptional Return Values: GSL_EDOM, GSL_EOVRFLW

Hurwitz Zeta Function
---------------------

   The Hurwitz zeta function is defined by  zeta(s,q) = \sum_0^\infty
(k+q)^(-s) .

 - Function: int gsl_sf_hzeta_impl (double s, double q, gsl_sf_result *
          result)
 - Function: int gsl_sf_hzeta_e (double s, double q, gsl_sf_result *
          result)
     Domain: s > 1.0, q > 0.0 Exceptional Return Values: GSL_EDOM,
     GSL_EUNDRFLW, GSL_EOVRFLW

Eta Function
------------

   The eta function is defined by  \eta(s) = (1-2^(1-s)) zeta(s) .

 - Function: int gsl_sf_eta_int_impl (int n, gsl_sf_result * result)
 - Function: int gsl_sf_eta_int_e (int n, gsl_sf_result * result)
     Exceptional Return Values: GSL_EUNDRFLW, GSL_EOVRFLW

 - Function: int gsl_sf_eta_impl (double s, gsl_sf_result * result)
 - Function: int gsl_sf_eta_e (double s, gsl_sf_result * result)
     Exceptional Return Values: GSL_EUNDRFLW, GSL_EOVRFLW


File: gsl-ref.info,  Node: Roots of Polynomials,  Next: Interpolation,  Prev: Special Functions,  Up: Top

Roots of Polynomials
********************

   This chapter describes functions for solving polynomial equations.
There are routines for finding real and complex roots of quadratic and
cubic equations using analytic methods.  An iterative polynomial solver
is also available for finding the roots of general real polynomials (of
any order).  The functions are defined in the header file `gsl_poly.h'.

* Menu:

* Quadratic equations::
* Cubic equations::
* General polynomial equations::
* Roots of Polynomials Examples::
* Roots of Polynomials References and Further Reading::


File: gsl-ref.info,  Node: Quadratic equations,  Next: Cubic equations,  Up: Roots of Polynomials

Quadratic equations
===================

 - Function: int gsl_poly_solve_quadratic (double A, double B, double
          C, double *X0, double *X1)
     This function finds the real roots of the quadratic equation,

          a x^2 + b x + c = 0

     The number of real roots (either zero or two) is returned, and
     their locations are stored in X0 and X1.  If no real roots are
     found then X0 and X1 are not modified.  When two real roots are
     found they are stored in X0 and X1 in ascending order.  The case
     of coincident roots is not considered special.  For example
     (x-1)^2=0 will have two roots, which happen to have exactly equal
     values.

     The number of roots found depends on the sign of the discriminant
     b^2 - 4 a c.  This will be subject to rounding and cancellation
     errors when computed in double precision, and will also be subject
     to errors if the coefficients of the polynomial are inexact.
     These errors may cause a discrete change in the number of roots.
     However, for polynomials with small integer coefficients the
     discriminant can always be computed exactly.


 - Function: int gsl_poly_complex_solve_quadratic (double A, double B,
          double C, gsl_complex *Z0, gsl_complex *Z1)
     This function finds the complex roots of the quadratic equation,

          a z^2 + b z + c = 0

     The number of complex roots is returned (always two) and the
     locations of the roots are stored in Z0 and Z1.  The roots are
     returned in ascending order, sorted first by their real components
     and then by their imaginary components.



File: gsl-ref.info,  Node: Cubic equations,  Next: General polynomial equations,  Prev: Quadratic equations,  Up: Roots of Polynomials

Cubic equations
===============

 - Function: int gsl_poly_solve_cubic (double A, double B, double C,
          double *X0, double *X1, double *X2)
     This function finds the real roots of the cubic equation,

          x^3 + a x^2 + b x + c = 0

     with a leading coefficient of unity.  The number of real roots
     (either one or three) is returned, and their locations are stored
     in X0, X1 and X2.  If one real root is found then only X0 is
     modified.  When three real roots are found they are stored in X0,
     X1 and X2 in ascending order.  The case of coincident roots is not
     considered special.  For example, the equation (x-1)^3=0 will have
     three roots with exactly equal values.


 - Function: int gsl_poly_complex_solve_cubic (double A, double B,
          double C, gsl_complex *Z0, gsl_complex *Z1, gsl_complex *Z2)
     This function finds the complex roots of the cubic equation,

          z^3 + a z^2 + b z + c = 0

     The number of complex roots is returned (always three) and the
     locations of the roots are stored in Z0, Z1 and Z2.  The roots are
     returned in ascending order, sorted first by their real components
     and then by their imaginary components.



File: gsl-ref.info,  Node: General polynomial equations,  Next: Roots of Polynomials Examples,  Prev: Cubic equations,  Up: Roots of Polynomials

General polynomial equations
============================

   The roots of polynomial equations cannot be found analytically beyond
the special cases of the quadratic, cubic and quartic equation.  The
algorithm described in this section uses an iterative method to find the
approximate locations of roots of higher order polynomials.

 - Function: gsl_poly_complex_workspace *
gsl_poly_complex_workspace_alloc (size_t N)
     This function allocates space for a `gsl_poly_complex_workspace'
     struct and a scratch area suitable for solving a polynomial with N
     coefficients using the routine `gsl_poly_complex_solve'.

     The function returns a pointer to the newly allocated
     `gsl_poly_complex_workspace' if no errors were detected, and 0 in
     the case of error.

 - Function: void gsl_poly_complex_workspace_free
          (gsl_poly_complex_workspace * W)
     This function frees all the memory associated with the workspace W.

 - Function: int gsl_poly_complex_solve (const double * A, size_t N,
          gsl_poly_complex_workspace * W, gsl_complex_packed_ptr Z)
     This function computes the roots of the general polynomial P(x) =
     a_0 + a_1 x + a_2 x^2 + ... + a_{n-1} x^{n-1} using balanced-QR
     reduction of the companion matrix.  The parameter N specifies the
     length of the coefficient array.  The coefficient of the highest
     order term must be non-zero.  The function requires a workspace W
     of the appropriate size.  The n-1 roots are returned in the packed
     complex array Z of length 2(n-1), alternating real and imaginary
     parts.

     The functions returns `GSL_SUCCESS' if all the roots are found and
     `GSL_EFAILED' if the QR reduction does not converge.


File: gsl-ref.info,  Node: Roots of Polynomials Examples,  Next: Roots of Polynomials References and Further Reading,  Prev: General polynomial equations,  Up: Roots of Polynomials

Examples
========

   To demonstrate the use of the general polynomial solver we will take
the polynomial P(x) = x^5 - 1 which has the following roots,

     1, e^{2\pi i /5}, e^{4\pi i /5}, e^{6\pi i /5}, e^{8\pi i /5}

The following program will find these roots.

     #include <stdio.h>
     #include <gsl/gsl_poly.h>
     
     int
     main ()
     {
       int i;
       double a[6] = { -1, 0, 0, 0, 0, 1 };  /*  P(x) =  -1 + x^5  */
       double z[10];
     
       gsl_poly_complex_workspace * w = gsl_poly_complex_workspace_alloc (6) ;
     
       gsl_poly_complex_solve (a, 6, w, z) ;
     
       gsl_poly_complex_workspace_free (w) ;
     
       for (i = 0; i < 5 ; i++)
         {
           printf("z%d = %+.18f %+.18f\n", i, z[2*i], z[2*i+1]) ;
         }
     }

The results of running the program are,

     bash$ ./a.out
     z0 = -0.809016994374947451 +0.587785252292473137
     z1 = -0.809016994374947451 -0.587785252292473137
     z2 = +0.309016994374947451 +0.951056516295153642
     z3 = +0.309016994374947451 -0.951056516295153642
     z4 = +1.000000000000000000 +0.000000000000000000


File: gsl-ref.info,  Node: Roots of Polynomials References and Further Reading,  Prev: Roots of Polynomials Examples,  Up: Roots of Polynomials

References and Further Reading
==============================

The balanced-QR method and its error analysis is described in the
following papers.

     R.S. Martin, G. Peters and J.H. Wilkinson, "The QR Algorithm for
     Real Hessenberg Matrices", `Numerische Mathematik', 14 (1970),
     219-231.

     B.N. Parlett and C. Reinsch, "Balancing a Matrix for Calculation of
     Eigenvalues and Eigenvectors", `Numerische Mathematik', 13 (1969),
     293-304.

     A. Edelman and H. Murakami, "Polynomial roots from companion matrix
     eigenvalues", `Mathematics of Computation', Vol. 64 No. 210
     (1995), 763-776.

