legendre_function.tcc revision 1.10 
1// Special functions -*- C++ -*-
2
3// Copyright (C) 2006-2019 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 <tr1/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 degree
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 degree 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 (__isnan(__x))
86        return std::numeric_limits<_Tp>::quiet_NaN();
87      else if (__x == +_Tp(1))
88        return +_Tp(1);
89      else if (__x == -_Tp(1))
90        return (__l % 2 == 1 ? -_Tp(1) : +_Tp(1));
91      else
92        {
93          _Tp __p_lm2 = _Tp(1);
94          if (__l == 0)
95            return __p_lm2;
96
97          _Tp __p_lm1 = __x;
98          if (__l == 1)
99            return __p_lm1;
100
101          _Tp __p_l = 0;
102          for (unsigned int __ll = 2; __ll <= __l; ++__ll)
103            {
104              //  This arrangement is supposed to be better for roundoff
105              //  protection, Arfken, 2nd Ed, Eq 12.17a.
106              __p_l = _Tp(2) * __x * __p_lm1 - __p_lm2
107                    - (__x * __p_lm1 - __p_lm2) / _Tp(__ll);
108              __p_lm2 = __p_lm1;
109              __p_lm1 = __p_l;
110            }
111
112          return __p_l;
113        }
114    }
115
116
117    /**
118     *   @brief  Return the associated Legendre function by recursion
119     *           on @f$ l @f$.
120     * 
121     *   The associated Legendre function is derived from the Legendre function
122     *   @f$ P_l(x) @f$ by the Rodrigues formula:
123     *   @f[
124     *     P_l^m(x) = (1 - x^2)^{m/2}\frac{d^m}{dx^m}P_l(x)
125     *   @f]
126     *   @note @f$ P_l^m(x) = 0 @f$ if @f$ m > l @f$.
127     * 
128     *   @param  l  The degree of the associated Legendre function.
129     *              @f$ l >= 0 @f$.
130     *   @param  m  The order of the associated Legendre function.
131     *   @param  x  The argument of the associated Legendre function.
132     *              @f$ |x| <= 1 @f$.
133     *   @param  phase  The phase of the associated Legendre function.
134     *                  Use -1 for the Condon-Shortley phase convention.
135     */
136    template<typename _Tp>
137    _Tp
138    __assoc_legendre_p(unsigned int __l, unsigned int __m, _Tp __x,
139		       _Tp __phase = _Tp(+1))
140    {
141
142      if (__m > __l)
143        return _Tp(0);
144      else if (__isnan(__x))
145        return std::numeric_limits<_Tp>::quiet_NaN();
146      else if (__m == 0)
147        return __poly_legendre_p(__l, __x);
148      else
149        {
150          _Tp __p_mm = _Tp(1);
151          if (__m > 0)
152            {
153              //  Two square roots seem more accurate more of the time
154              //  than just one.
155              _Tp __root = std::sqrt(_Tp(1) - __x) * std::sqrt(_Tp(1) + __x);
156              _Tp __fact = _Tp(1);
157              for (unsigned int __i = 1; __i <= __m; ++__i)
158                {
159                  __p_mm *= __phase * __fact * __root;
160                  __fact += _Tp(2);
161                }
162            }
163          if (__l == __m)
164            return __p_mm;
165
166          _Tp __p_mp1m = _Tp(2 * __m + 1) * __x * __p_mm;
167          if (__l == __m + 1)
168            return __p_mp1m;
169
170          _Tp __p_lm2m = __p_mm;
171          _Tp __P_lm1m = __p_mp1m;
172          _Tp __p_lm = _Tp(0);
173          for (unsigned int __j = __m + 2; __j <= __l; ++__j)
174            {
175              __p_lm = (_Tp(2 * __j - 1) * __x * __P_lm1m
176                      - _Tp(__j + __m - 1) * __p_lm2m) / _Tp(__j - __m);
177              __p_lm2m = __P_lm1m;
178              __P_lm1m = __p_lm;
179            }
180
181          return __p_lm;
182        }
183    }
184
185
186    /**
187     *   @brief  Return the spherical associated Legendre function.
188     * 
189     *   The spherical associated Legendre function of @f$ l @f$, @f$ m @f$,
190     *   and @f$ \theta @f$ is defined as @f$ Y_l^m(\theta,0) @f$ where
191     *   @f[
192     *      Y_l^m(\theta,\phi) = (-1)^m[\frac{(2l+1)}{4\pi}
193     *                                  \frac{(l-m)!}{(l+m)!}]
194     *                     P_l^m(\cos\theta) \exp^{im\phi}
195     *   @f]
196     *   is the spherical harmonic function and @f$ P_l^m(x) @f$ is the
197     *   associated Legendre function.
198     * 
199     *   This function differs from the associated Legendre function by
200     *   argument (@f$x = \cos(\theta)@f$) and by a normalization factor
201     *   but this factor is rather large for large @f$ l @f$ and @f$ m @f$
202     *   and so this function is stable for larger differences of @f$ l @f$
203     *   and @f$ m @f$.
204     *   @note Unlike the case for __assoc_legendre_p the Condon-Shortley
205     *         phase factor @f$ (-1)^m @f$ is present here.
206     *   @note @f$ Y_l^m(\theta) = 0 @f$ if @f$ m > l @f$.
207     * 
208     *   @param  l  The degree of the spherical associated Legendre function.
209     *              @f$ l >= 0 @f$.
210     *   @param  m  The order of the spherical associated Legendre function.
211     *   @param  theta  The radian angle argument of the spherical associated
212     *                  Legendre function.
213     */
214    template <typename _Tp>
215    _Tp
216    __sph_legendre(unsigned int __l, unsigned int __m, _Tp __theta)
217    {
218      if (__isnan(__theta))
219        return std::numeric_limits<_Tp>::quiet_NaN();
220
221      const _Tp __x = std::cos(__theta);
222
223      if (__m > __l)
224        return _Tp(0);
225      else if (__m == 0)
226        {
227          _Tp __P = __poly_legendre_p(__l, __x);
228          _Tp __fact = std::sqrt(_Tp(2 * __l + 1)
229                     / (_Tp(4) * __numeric_constants<_Tp>::__pi()));
230          __P *= __fact;
231          return __P;
232        }
233      else if (__x == _Tp(1) || __x == -_Tp(1))
234        {
235          //  m > 0 here
236          return _Tp(0);
237        }
238      else
239        {
240          // m > 0 and |x| < 1 here
241
242          // Starting value for recursion.
243          // Y_m^m(x) = sqrt( (2m+1)/(4pi m) gamma(m+1/2)/gamma(m) )
244          //             (-1)^m (1-x^2)^(m/2) / pi^(1/4)
245          const _Tp __sgn = ( __m % 2 == 1 ? -_Tp(1) : _Tp(1));
246          const _Tp __y_mp1m_factor = __x * std::sqrt(_Tp(2 * __m + 3));
247#if _GLIBCXX_USE_C99_MATH_TR1
248          const _Tp __lncirc = _GLIBCXX_MATH_NS::log1p(-__x * __x);
249#else
250          const _Tp __lncirc = std::log(_Tp(1) - __x * __x);
251#endif
252          //  Gamma(m+1/2) / Gamma(m)
253#if _GLIBCXX_USE_C99_MATH_TR1
254          const _Tp __lnpoch = _GLIBCXX_MATH_NS::lgamma(_Tp(__m + _Tp(0.5L)))
255                             - _GLIBCXX_MATH_NS::lgamma(_Tp(__m));
256#else
257          const _Tp __lnpoch = __log_gamma(_Tp(__m + _Tp(0.5L)))
258                             - __log_gamma(_Tp(__m));
259#endif
260          const _Tp __lnpre_val =
261                    -_Tp(0.25L) * __numeric_constants<_Tp>::__lnpi()
262                    + _Tp(0.5L) * (__lnpoch + __m * __lncirc);
263          const _Tp __sr = std::sqrt((_Tp(2) + _Tp(1) / __m)
264                         / (_Tp(4) * __numeric_constants<_Tp>::__pi()));
265          _Tp __y_mm = __sgn * __sr * std::exp(__lnpre_val);
266          _Tp __y_mp1m = __y_mp1m_factor * __y_mm;
267
268          if (__l == __m)
269            return __y_mm;
270          else if (__l == __m + 1)
271            return __y_mp1m;
272          else
273            {
274              _Tp __y_lm = _Tp(0);
275
276              // Compute Y_l^m, l > m+1, upward recursion on l.
277              for (int __ll = __m + 2; __ll <= __l; ++__ll)
278                {
279                  const _Tp __rat1 = _Tp(__ll - __m) / _Tp(__ll + __m);
280                  const _Tp __rat2 = _Tp(__ll - __m - 1) / _Tp(__ll + __m - 1);
281                  const _Tp __fact1 = std::sqrt(__rat1 * _Tp(2 * __ll + 1)
282                                                       * _Tp(2 * __ll - 1));
283                  const _Tp __fact2 = std::sqrt(__rat1 * __rat2 * _Tp(2 * __ll + 1)
284                                                                / _Tp(2 * __ll - 3));
285                  __y_lm = (__x * __y_mp1m * __fact1
286                         - (__ll + __m - 1) * __y_mm * __fact2) / _Tp(__ll - __m);
287                  __y_mm = __y_mp1m;
288                  __y_mp1m = __y_lm;
289                }
290
291              return __y_lm;
292            }
293        }
294    }
295  } // namespace __detail
296#undef _GLIBCXX_MATH_NS
297#if ! _GLIBCXX_USE_STD_SPEC_FUNCS && defined(_GLIBCXX_TR1_CMATH)
298} // namespace tr1
299#endif
300
301_GLIBCXX_END_NAMESPACE_VERSION
302}
303
304#endif // _GLIBCXX_TR1_LEGENDRE_FUNCTION_TCC
305