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