# legendre_function.tcc

Go to the documentation of this file.

    00001 // Special functions -*- C++ -*-
    00002
    00003 // Copyright (C) 2006, 2007, 2008
    00004 // Free Software Foundation, Inc.
    00005 //
    00006 // This file is part of the GNU ISO C++ Library.  This library is free
    00007 // software; you can redistribute it and/or modify it under the
    00008 // terms of the GNU General Public License as published by the
    00009 // Free Software Foundation; either version 2, or (at your option)
    00010 // any later version.
    00011 //
    00012 // This library is distributed in the hope that it will be useful,
    00013 // but WITHOUT ANY WARRANTY; without even the implied warranty of
    00014 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    00015 // GNU General Public License for more details.
    00016 //
    00017 // You should have received a copy of the GNU General Public License along
    00018 // with this library; see the file COPYING.  If not, write to the Free
    00019 // Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
    00020 // USA.
    00021 //
    00022 // As a special exception, you may use this file as part of a free software
    00023 // library without restriction.  Specifically, if other files instantiate
    00024 // templates or use macros or inline functions from this file, or you compile
    00025 // this file and link it with other files to produce an executable, this
    00026 // file does not by itself cause the resulting executable to be covered by
    00027 // the GNU General Public License.  This exception does not however
    00028 // invalidate any other reasons why the executable file might be covered by
    00029 // the GNU General Public License.
    00030
    00031 /** @file tr1/legendre_function.tcc
    00032  *  This is an internal header file, included by other library headers.
    00033  *  You should not attempt to use it directly.
    00034  */
    00035
    00036 //
    00037 // ISO C++ 14882 TR1: 5.2  Special functions
    00038 //
    00039
    00040 // Written by Edward Smith-Rowland based on:
    00041 //   (1) Handbook of Mathematical Functions,
    00042 //       ed. Milton Abramowitz and Irene A. Stegun,
    00043 //       Dover Publications,
    00044 //       Section 8, pp. 331-341
    00045 //   (2) The Gnu Scientific Library, http://www.gnu.org/software/gsl
    00046 //   (3) Numerical Recipes in C, by W. H. Press, S. A. Teukolsky,
    00047 //       W. T. Vetterling, B. P. Flannery, Cambridge University Press (1992),
    00048 //       2nd ed, pp. 252-254
    00049
    00050 #ifndef _GLIBCXX_TR1_LEGENDRE_FUNCTION_TCC
    00051 #define _GLIBCXX_TR1_LEGENDRE_FUNCTION_TCC 1
    00052
    00053 #include "special_function_util.h"
    00054
    00055 namespace std
    00056 {
    00057 namespace tr1
    00058 {
    00059
    00060   // [5.2] Special functions
    00061
    00062   // Implementation-space details.
    00063   namespace __detail
    00064   {
    00065
    00066     /**
    00067      *   @brief  Return the Legendre polynomial by recursion on order
    00068      *           @f$ l @f$.
    00069      *
    00070      *   The Legendre function of @f$ l @f$ and @f$ x @f$,
    00071      *   @f$ P_l(x) @f$, is defined by:
    00072      *   @f[
    00073      *     P_l(x) = \frac{1}{2^l l!}\frac{d^l}{dx^l}(x^2 - 1)^{l}
    00074      *   @f]
    00075      *
    00076      *   @param  l  The order of the Legendre polynomial.  @f$l >= 0@f$.
    00077      *   @param  x  The argument of the Legendre polynomial.  @f$|x| <= 1@f$.
    00078      */
    00079     template<typename _Tp>
    00080     _Tp
    00081     __poly_legendre_p(const unsigned int __l, const _Tp __x)
    00082     {
    00083
    00084       if ((__x < _Tp(-1)) || (__x > _Tp(+1)))
    00085         std::__throw_domain_error(__N("Argument out of range"
    00086                                       " in __poly_legendre_p."));
    00087       else if (__isnan(__x))
    00088         return std::numeric_limits<_Tp>::quiet_NaN();
    00089       else if (__x == +_Tp(1))
    00090         return +_Tp(1);
    00091       else if (__x == -_Tp(1))
    00092         return (__l % 2 == 1 ? -_Tp(1) : +_Tp(1));
    00093       else
    00094         {
    00095           _Tp __p_lm2 = _Tp(1);
    00096           if (__l == 0)
    00097             return __p_lm2;
    00098
    00099           _Tp __p_lm1 = __x;
    00100           if (__l == 1)
    00101             return __p_lm1;
    00102
    00103           _Tp __p_l = 0;
    00104           for (unsigned int __ll = 2; __ll <= __l; ++__ll)
    00105             {
    00106               //  This arrangement is supposed to be better for roundoff
    00107               //  protection, Arfken, 2nd Ed, Eq 12.17a.
    00108               __p_l = _Tp(2) * __x * __p_lm1 - __p_lm2
    00109                     - (__x * __p_lm1 - __p_lm2) / _Tp(__ll);
    00110               __p_lm2 = __p_lm1;
    00111               __p_lm1 = __p_l;
    00112             }
    00113
    00114           return __p_l;
    00115         }
    00116     }
    00117
    00118
    00119     /**
    00120      *   @brief  Return the associated Legendre function by recursion
    00121      *           on @f$ l @f$.
    00122      *
    00123      *   The associated Legendre function is derived from the Legendre function
    00124      *   @f$ P_l(x) @f$ by the Rodrigues formula:
    00125      *   @f[
    00126      *     P_l^m(x) = (1 - x^2)^{m/2}\frac{d^m}{dx^m}P_l(x)
    00127      *   @f]
    00128      *
    00129      *   @param  l  The order of the associated Legendre function.
    00130      *              @f$ l >= 0 @f$.
    00131      *   @param  m  The order of the associated Legendre function.
    00132      *              @f$ m <= l @f$.
    00133      *   @param  x  The argument of the associated Legendre function.
    00134      *              @f$ |x| <= 1 @f$.
    00135      */
    00136     template<typename _Tp>
    00137     _Tp
    00138     __assoc_legendre_p(const unsigned int __l, const unsigned int __m,
    00139                        const _Tp __x)
    00140     {
    00141
    00142       if (__x < _Tp(-1) || __x > _Tp(+1))
    00143         std::__throw_domain_error(__N("Argument out of range"
    00144                                       " in __assoc_legendre_p."));
    00145       else if (__m > __l)
    00146         std::__throw_domain_error(__N("Degree out of range"
    00147                                       " in __assoc_legendre_p."));
    00148       else if (__isnan(__x))
    00149         return std::numeric_limits<_Tp>::quiet_NaN();
    00150       else if (__m == 0)
    00151         return __poly_legendre_p(__l, __x);
    00152       else
    00153         {
    00154           _Tp __p_mm = _Tp(1);
    00155           if (__m > 0)
    00156             {
    00157               //  Two square roots seem more accurate more of the time
    00158               //  than just one.
    00159               _Tp __root = std::sqrt(_Tp(1) - __x) * std::sqrt(_Tp(1) + __x);
    00160               _Tp __fact = _Tp(1);
    00161               for (unsigned int __i = 1; __i <= __m; ++__i)
    00162                 {
    00163                   __p_mm *= -__fact * __root;
    00164                   __fact += _Tp(2);
    00165                 }
    00166             }
    00167           if (__l == __m)
    00168             return __p_mm;
    00169
    00170           _Tp __p_mp1m = _Tp(2 * __m + 1) * __x * __p_mm;
    00171           if (__l == __m + 1)
    00172             return __p_mp1m;
    00173
    00174           _Tp __p_lm2m = __p_mm;
    00175           _Tp __P_lm1m = __p_mp1m;
    00176           _Tp __p_lm = _Tp(0);
    00177           for (unsigned int __j = __m + 2; __j <= __l; ++__j)
    00178             {
    00179               __p_lm = (_Tp(2 * __j - 1) * __x * __P_lm1m
    00180                       - _Tp(__j + __m - 1) * __p_lm2m) / _Tp(__j - __m);
    00181               __p_lm2m = __P_lm1m;
    00182               __P_lm1m = __p_lm;
    00183             }
    00184
    00185           return __p_lm;
    00186         }
    00187     }
    00188
    00189
    00190     /**
    00191      *   @brief  Return the spherical associated Legendre function.
    00192      *
    00193      *   The spherical associated Legendre function of @f$ l @f$, @f$ m @f$,
    00194      *   and @f$ \theta @f$ is defined as @f$ Y_l^m(\theta,0) @f$ where
    00195      *   @f[
    00196      *      Y_l^m(\theta,\phi) = (-1)^m[\frac{(2l+1)}{4\pi}
    00197      *                                  \frac{(l-m)!}{(l+m)!}]
    00198      *                     P_l^m(\cos\theta) \exp^{im\phi}
    00199      *   @f]
    00200      *   is the spherical harmonic function and @f$ P_l^m(x) @f$ is the
    00201      *   associated Legendre function.
    00202      *
    00203      *   This function differs from the associated Legendre function by
    00204      *   argument (@f$x = \cos(\theta)@f$) and by a normalization factor
    00205      *   but this factor is rather large for large @f$ l @f$ and @f$ m @f$
    00206      *   and so this function is stable for larger differences of @f$ l @f$
    00207      *   and @f$ m @f$.
    00208      *
    00209      *   @param  l  The order of the spherical associated Legendre function.
    00210      *              @f$ l >= 0 @f$.
    00211      *   @param  m  The order of the spherical associated Legendre function.
    00212      *              @f$ m <= l @f$.
    00213      *   @param  theta  The radian angle argument of the spherical associated
    00214      *                  Legendre function.
    00215      */
    00216     template <typename _Tp>
    00217     _Tp
    00218     __sph_legendre(const unsigned int __l, const unsigned int __m,
    00219                    const _Tp __theta)
    00220     {
    00221       if (__isnan(__theta))
    00222         return std::numeric_limits<_Tp>::quiet_NaN();
    00223
    00224       const _Tp __x = std::cos(__theta);
    00225
    00226       if (__l < __m)
    00227         {
    00228           std::__throw_domain_error(__N("Bad argument "
    00229                                         "in __sph_legendre."));
    00230         }
    00231       else if (__m == 0)
    00232         {
    00233           _Tp __P = __poly_legendre_p(__l, __x);
    00234           _Tp __fact = std::sqrt(_Tp(2 * __l + 1)
    00235                      / (_Tp(4) * __numeric_constants<_Tp>::__pi()));
    00236           __P *= __fact;
    00237           return __P;
    00238         }
    00239       else if (__x == _Tp(1) || __x == -_Tp(1))
    00240         {
    00241           //  m > 0 here
    00242           return _Tp(0);
    00243         }
    00244       else
    00245         {
    00246           // m > 0 and |x| < 1 here
    00247
    00248           // Starting value for recursion.
    00249           // Y_m^m(x) = sqrt( (2m+1)/(4pi m) gamma(m+1/2)/gamma(m) )
    00250           //             (-1)^m (1-x^2)^(m/2) / pi^(1/4)
    00251           const _Tp __sgn = ( __m % 2 == 1 ? -_Tp(1) : _Tp(1));
    00252           const _Tp __y_mp1m_factor = __x * std::sqrt(_Tp(2 * __m + 3));
    00253 #if _GLIBCXX_USE_C99_MATH_TR1
    00254           const _Tp __lncirc = std::tr1::log1p(-__x * __x);
    00255 #else
    00256           const _Tp __lncirc = std::log(_Tp(1) - __x * __x);
    00257 #endif
    00258           //  Gamma(m+1/2) / Gamma(m)
    00259 #if _GLIBCXX_USE_C99_MATH_TR1
    00260           const _Tp __lnpoch = std::tr1::lgamma(_Tp(__m + _Tp(0.5L)))
    00261                              - std::tr1::lgamma(_Tp(__m));
    00262 #else
    00263           const _Tp __lnpoch = __log_gamma(_Tp(__m + _Tp(0.5L)))
    00264                              - __log_gamma(_Tp(__m));
    00265 #endif
    00266           const _Tp __lnpre_val =
    00267                     -_Tp(0.25L) * __numeric_constants<_Tp>::__lnpi()
    00268                     + _Tp(0.5L) * (__lnpoch + __m * __lncirc);
    00269           _Tp __sr = std::sqrt((_Tp(2) + _Tp(1) / __m)
    00270                    / (_Tp(4) * __numeric_constants<_Tp>::__pi()));
    00271           _Tp __y_mm = __sgn * __sr * std::exp(__lnpre_val);
    00272           _Tp __y_mp1m = __y_mp1m_factor * __y_mm;
    00273
    00274           if (__l == __m)
    00275             {
    00276               return __y_mm;
    00277             }
    00278           else if (__l == __m + 1)
    00279             {
    00280               return __y_mp1m;
    00281             }
    00282           else
    00283             {
    00284               _Tp __y_lm = _Tp(0);
    00285
    00286               // Compute Y_l^m, l > m+1, upward recursion on l.
    00287               for ( int __ll = __m + 2; __ll <= __l; ++__ll)
    00288                 {
    00289                   const _Tp __rat1 = _Tp(__ll - __m) / _Tp(__ll + __m);
    00290                   const _Tp __rat2 = _Tp(__ll - __m - 1) / _Tp(__ll + __m - 1);
    00291                   const _Tp __fact1 = std::sqrt(__rat1 * _Tp(2 * __ll + 1)
    00292                                                        * _Tp(2 * __ll - 1));
    00293                   const _Tp __fact2 = std::sqrt(__rat1 * __rat2 * _Tp(2 * __ll + 1)
    00294                                                                 / _Tp(2 * __ll - 3));
    00295                   __y_lm = (__x * __y_mp1m * __fact1
    00296                          - (__ll + __m - 1) * __y_mm * __fact2) / _Tp(__ll - __m);
    00297                   __y_mm = __y_mp1m;
    00298                   __y_mp1m = __y_lm;
    00299                 }
    00300
    00301               return __y_lm;
    00302             }
    00303         }
    00304     }
    00305
    00306   } // namespace std::tr1::__detail
    00307 }
    00308 }
    00309
    00310 #endif // _GLIBCXX_TR1_LEGENDRE_FUNCTION_TCC