libstdc++-v3/include/tr1/legendre_function.tcc

   1 // Special functions -*- C++ -*-
   2
   3 // Copyright (C) 2006, 2007, 2008, 2009, 2010
   4 // Free Software Foundation, Inc.
   5 //
   6 // This file is part of the GNU ISO C++ Library.  This library is free
   7 // software; you can redistribute it and/or modify it under the
   8 // terms of the GNU General Public License as published by the
   9 // Free Software Foundation; either version 3, or (at your option)
  10 // any later version.
  11 //
  12 // This library is distributed in the hope that it will be useful,
  13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 // GNU General Public License for more details.
  16 //
  17 // Under Section 7 of GPL version 3, you are granted additional
  18 // permissions described in the GCC Runtime Library Exception, version
  19 // 3.1, as published by the Free Software Foundation.
  20
  21 // You should have received a copy of the GNU General Public License and
  22 // a copy of the GCC Runtime Library Exception along with this program;
  23 // see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
  24 // <http://www.gnu.org/licenses/>.
  25
  26 /** @file tr1/legendre_function.tcc
  27  *  This is an internal header file, included by other library headers.
  28  *  Do not attempt to use it directly. @headername{tr1/cmath}
  29  */
  30
  31 //
  32 // ISO C++ 14882 TR1: 5.2  Special functions
  33 //
  34
  35 // Written by Edward Smith-Rowland based on:
  36 //   (1) Handbook of Mathematical Functions,
  37 //       ed. Milton Abramowitz and Irene A. Stegun,
  38 //       Dover Publications,
  39 //       Section 8, pp. 331-341
  40 //   (2) The Gnu Scientific Library, http://www.gnu.org/software/gsl
  41 //   (3) Numerical Recipes in C, by W. H. Press, S. A. Teukolsky,
  42 //       W. T. Vetterling, B. P. Flannery, Cambridge University Press (1992),
  43 //       2nd ed, pp. 252-254
  44
  45 #ifndef _GLIBCXX_TR1_LEGENDRE_FUNCTION_TCC
  46 #define _GLIBCXX_TR1_LEGENDRE_FUNCTION_TCC 1
  47
  48 #include "special_function_util.h"
  49
  50 namespace std _GLIBCXX_VISIBILITY(default)
  51 {
  52 namespace tr1
  53 {
  54   // [5.2] Special functions
  55
  56   // Implementation-space details.
  57   namespace __detail
  58   {
  59   _GLIBCXX_BEGIN_NAMESPACE_VERSION
  60
  61     /**
  62      *   @brief  Return the Legendre polynomial by recursion on order
  63      *           @f$ l @f$.
  64      *
  65      *   The Legendre function of @f$ l @f$ and @f$ x @f$,
  66      *   @f$ P_l(x) @f$, is defined by:
  67      *   @f[
  68      *     P_l(x) = \frac{1}{2^l l!}\frac{d^l}{dx^l}(x^2 - 1)^{l}
  69      *   @f]
  70      *
  71      *   @param  l  The order of the Legendre polynomial.  @f$l >= 0@f$.
  72      *   @param  x  The argument of the Legendre polynomial.  @f$|x| <= 1@f$.
  73      */
  74     template<typename _Tp>
  75     _Tp
  76     __poly_legendre_p(const unsigned int __l, const _Tp __x)
  77     {
  78
  79       if ((__x < _Tp(-1)) || (__x > _Tp(+1)))
  80         std::__throw_domain_error(__N("Argument out of range"
  81                                       " in __poly_legendre_p."));
  82       else if (__isnan(__x))
  83         return std::numeric_limits<_Tp>::quiet_NaN();
  84       else if (__x == +_Tp(1))
  85         return +_Tp(1);
  86       else if (__x == -_Tp(1))
  87         return (__l % 2 == 1 ? -_Tp(1) : +_Tp(1));
  88       else
  89         {
  90           _Tp __p_lm2 = _Tp(1);
  91           if (__l == 0)
  92             return __p_lm2;
  93
  94           _Tp __p_lm1 = __x;
  95           if (__l == 1)
  96             return __p_lm1;
  97
  98           _Tp __p_l = 0;
  99           for (unsigned int __ll = 2; __ll <= __l; ++__ll)
 100             {
 101               //  This arrangement is supposed to be better for roundoff
 102               //  protection, Arfken, 2nd Ed, Eq 12.17a.
 103               __p_l = _Tp(2) * __x * __p_lm1 - __p_lm2
 104                     - (__x * __p_lm1 - __p_lm2) / _Tp(__ll);
 105               __p_lm2 = __p_lm1;
 106               __p_lm1 = __p_l;
 107             }
 108
 109           return __p_l;
 110         }
 111     }
 112
 113
 114     /**
 115      *   @brief  Return the associated Legendre function by recursion
 116      *           on @f$ l @f$.
 117      *
 118      *   The associated Legendre function is derived from the Legendre function
 119      *   @f$ P_l(x) @f$ by the Rodrigues formula:
 120      *   @f[
 121      *     P_l^m(x) = (1 - x^2)^{m/2}\frac{d^m}{dx^m}P_l(x)
 122      *   @f]
 123      *
 124      *   @param  l  The order of the associated Legendre function.
 125      *              @f$ l >= 0 @f$.
 126      *   @param  m  The order of the associated Legendre function.
 127      *              @f$ m <= l @f$.
 128      *   @param  x  The argument of the associated Legendre function.
 129      *              @f$ |x| <= 1 @f$.
 130      */
 131     template<typename _Tp>
 132     _Tp
 133     __assoc_legendre_p(const unsigned int __l, const unsigned int __m,
 134                        const _Tp __x)
 135     {
 136
 137       if (__x < _Tp(-1) || __x > _Tp(+1))
 138         std::__throw_domain_error(__N("Argument out of range"
 139                                       " in __assoc_legendre_p."));
 140       else if (__m > __l)
 141         std::__throw_domain_error(__N("Degree out of range"
 142                                       " in __assoc_legendre_p."));
 143       else if (__isnan(__x))
 144         return std::numeric_limits<_Tp>::quiet_NaN();
 145       else if (__m == 0)
 146         return __poly_legendre_p(__l, __x);
 147       else
 148         {
 149           _Tp __p_mm = _Tp(1);
 150           if (__m > 0)
 151             {
 152               //  Two square roots seem more accurate more of the time
 153               //  than just one.
 154               _Tp __root = std::sqrt(_Tp(1) - __x) * std::sqrt(_Tp(1) + __x);
 155               _Tp __fact = _Tp(1);
 156               for (unsigned int __i = 1; __i <= __m; ++__i)
 157                 {
 158                   __p_mm *= -__fact * __root;
 159                   __fact += _Tp(2);
 160                 }
 161             }
 162           if (__l == __m)
 163             return __p_mm;
 164
 165           _Tp __p_mp1m = _Tp(2 * __m + 1) * __x * __p_mm;
 166           if (__l == __m + 1)
 167             return __p_mp1m;
 168
 169           _Tp __p_lm2m = __p_mm;
 170           _Tp __P_lm1m = __p_mp1m;
 171           _Tp __p_lm = _Tp(0);
 172           for (unsigned int __j = __m + 2; __j <= __l; ++__j)
 173             {
 174               __p_lm = (_Tp(2 * __j - 1) * __x * __P_lm1m
 175                       - _Tp(__j + __m - 1) * __p_lm2m) / _Tp(__j - __m);
 176               __p_lm2m = __P_lm1m;
 177               __P_lm1m = __p_lm;
 178             }
 179
 180           return __p_lm;
 181         }
 182     }
 183
 184
 185     /**
 186      *   @brief  Return the spherical associated Legendre function.
 187      *
 188      *   The spherical associated Legendre function of @f$ l @f$, @f$ m @f$,
 189      *   and @f$ \theta @f$ is defined as @f$ Y_l^m(\theta,0) @f$ where
 190      *   @f[
 191      *      Y_l^m(\theta,\phi) = (-1)^m[\frac{(2l+1)}{4\pi}
 192      *                                  \frac{(l-m)!}{(l+m)!}]
 193      *                     P_l^m(\cos\theta) \exp^{im\phi}
 194      *   @f]
 195      *   is the spherical harmonic function and @f$ P_l^m(x) @f$ is the
 196      *   associated Legendre function.
 197      *
 198      *   This function differs from the associated Legendre function by
 199      *   argument (@f$x = \cos(\theta)@f$) and by a normalization factor
 200      *   but this factor is rather large for large @f$ l @f$ and @f$ m @f$
 201      *   and so this function is stable for larger differences of @f$ l @f$
 202      *   and @f$ m @f$.
 203      *
 204      *   @param  l  The order of the spherical associated Legendre function.
 205      *              @f$ l >= 0 @f$.
 206      *   @param  m  The order of the spherical associated Legendre function.
 207      *              @f$ m <= l @f$.
 208      *   @param  theta  The radian angle argument of the spherical associated
 209      *                  Legendre function.
 210      */
 211     template <typename _Tp>
 212     _Tp
 213     __sph_legendre(const unsigned int __l, const unsigned int __m,
 214                    const _Tp __theta)
 215     {
 216       if (__isnan(__theta))
 217         return std::numeric_limits<_Tp>::quiet_NaN();
 218
 219       const _Tp __x = std::cos(__theta);
 220
 221       if (__l < __m)
 222         {
 223           std::__throw_domain_error(__N("Bad argument "
 224                                         "in __sph_legendre."));
 225         }
 226       else if (__m == 0)
 227         {
 228           _Tp __P = __poly_legendre_p(__l, __x);
 229           _Tp __fact = std::sqrt(_Tp(2 * __l + 1)
 230                      / (_Tp(4) * __numeric_constants<_Tp>::__pi()));
 231           __P *= __fact;
 232           return __P;
 233         }
 234       else if (__x == _Tp(1) || __x == -_Tp(1))
 235         {
 236           //  m > 0 here
 237           return _Tp(0);
 238         }
 239       else
 240         {
 241           // m > 0 and |x| < 1 here
 242
 243           // Starting value for recursion.
 244           // Y_m^m(x) = sqrt( (2m+1)/(4pi m) gamma(m+1/2)/gamma(m) )
 245           //             (-1)^m (1-x^2)^(m/2) / pi^(1/4)
 246           const _Tp __sgn = ( __m % 2 == 1 ? -_Tp(1) : _Tp(1));
 247           const _Tp __y_mp1m_factor = __x * std::sqrt(_Tp(2 * __m + 3));
 248 #if _GLIBCXX_USE_C99_MATH_TR1
 249           const _Tp __lncirc = std::tr1::log1p(-__x * __x);
 250 #else
 251           const _Tp __lncirc = std::log(_Tp(1) - __x * __x);
 252 #endif
 253           //  Gamma(m+1/2) / Gamma(m)
 254 #if _GLIBCXX_USE_C99_MATH_TR1
 255           const _Tp __lnpoch = std::tr1::lgamma(_Tp(__m + _Tp(0.5L)))
 256                              - std::tr1::lgamma(_Tp(__m));
 257 #else
 258           const _Tp __lnpoch = __log_gamma(_Tp(__m + _Tp(0.5L)))
 259                              - __log_gamma(_Tp(__m));
 260 #endif
 261           const _Tp __lnpre_val =
 262                     -_Tp(0.25L) * __numeric_constants<_Tp>::__lnpi()
 263                     + _Tp(0.5L) * (__lnpoch + __m * __lncirc);
 264           _Tp __sr = std::sqrt((_Tp(2) + _Tp(1) / __m)
 265                    / (_Tp(4) * __numeric_constants<_Tp>::__pi()));
 266           _Tp __y_mm = __sgn * __sr * std::exp(__lnpre_val);
 267           _Tp __y_mp1m = __y_mp1m_factor * __y_mm;
 268
 269           if (__l == __m)
 270             {
 271               return __y_mm;
 272             }
 273           else if (__l == __m + 1)
 274             {
 275               return __y_mp1m;
 276             }
 277           else
 278             {
 279               _Tp __y_lm = _Tp(0);
 280
 281               // Compute Y_l^m, l > m+1, upward recursion on l.
 282               for ( int __ll = __m + 2; __ll <= __l; ++__ll)
 283                 {
 284                   const _Tp __rat1 = _Tp(__ll - __m) / _Tp(__ll + __m);
 285                   const _Tp __rat2 = _Tp(__ll - __m - 1) / _Tp(__ll + __m - 1);
 286                   const _Tp __fact1 = std::sqrt(__rat1 * _Tp(2 * __ll + 1)
 287                                                        * _Tp(2 * __ll - 1));
 288                   const _Tp __fact2 = std::sqrt(__rat1 * __rat2 * _Tp(2 * __ll + 1)
 289                                                                 / _Tp(2 * __ll - 3));
 290                   __y_lm = (__x * __y_mp1m * __fact1
 291                          - (__ll + __m - 1) * __y_mm * __fact2) / _Tp(__ll - __m);
 292                   __y_mm = __y_mp1m;
 293                   __y_mp1m = __y_lm;
 294                 }
 295
 296               return __y_lm;
 297             }
 298         }
 299     }
 300
 301   _GLIBCXX_END_NAMESPACE_VERSION
 302   } // namespace std::tr1::__detail
 303 }
 304 }
 305
 306 #endif // _GLIBCXX_TR1_LEGENDRE_FUNCTION_TCC