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 307
