libstdc++
legendre_function.tcc
1 // Special functions -*- C++ -*-
2 
3 // Copyright (C) 2006, 2007, 2008, 2009
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  * You should not attempt to use it directly.
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
51 {
52 namespace tr1
53 {
54 
55  // [5.2] Special functions
56 
57  // Implementation-space details.
58  namespace __detail
59  {
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  } // namespace std::tr1::__detail
302 }
303 }
304 
305 #endif // _GLIBCXX_TR1_LEGENDRE_FUNCTION_TCC