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

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