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
49namespace 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)
56namespace 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