2 // (C) Copyright John Maddock 2006.
3 // Use, modification and distribution are subject to the
4 // Boost Software License, Version 1.0. (See accompanying file
5 // LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7 #ifndef BOOST_MATH_SPECIAL_LEGENDRE_HPP
8 #define BOOST_MATH_SPECIAL_LEGENDRE_HPP
16 #include <boost/math/special_functions/math_fwd.hpp>
17 #include <boost/math/special_functions/factorials.hpp>
18 #include <boost/math/tools/roots.hpp>
19 #include <boost/math/tools/config.hpp>
24 // Recurrance relation for legendre P and Q polynomials:
25 template <class T1, class T2, class T3>
26 inline typename tools::promote_args<T1, T2, T3>::type
27 legendre_next(unsigned l, T1 x, T2 Pl, T3 Plm1)
29 typedef typename tools::promote_args<T1, T2, T3>::type result_type;
30 return ((2 * l + 1) * result_type(x) * result_type(Pl) - l * result_type(Plm1)) / (l + 1);
35 // Implement Legendre P and Q polynomials via recurrance:
36 template <class T, class Policy>
37 T legendre_imp(unsigned l, T x, const Policy& pol, bool second = false)
39 static const char* function = "boost::math::legrendre_p<%1%>(unsigned, %1%)";
41 if((x < -1) || (x > 1))
42 return policies::raise_domain_error<T>(
44 "The Legendre Polynomial is defined for"
45 " -1 <= x <= 1, but got x = %1%.", x, pol);
50 // A solution of the second kind (Q):
51 p0 = (boost::math::log1p(x, pol) - boost::math::log1p(-x, pol)) / 2;
56 // A solution of the first kind (P):
68 p1 = boost::math::legendre_next(n, x, p0, p1);
74 template <class T, class Policy>
75 T legendre_p_prime_imp(unsigned l, T x, const Policy& pol, T* Pn
76 #ifdef BOOST_NO_CXX11_NULLPTR
83 static const char* function = "boost::math::legrendre_p_prime<%1%>(unsigned, %1%)";
85 if ((x < -1) || (x > 1))
86 return policies::raise_domain_error<T>(
88 "The Legendre Polynomial is defined for"
89 " -1 <= x <= 1, but got x = %1%.", x, pol);
103 // If the order is odd, we sum all the even polynomials:
108 else // Otherwise we sum the odd polynomials * (2n+1)
117 p1 = boost::math::legendre_next(n, x, p0, p1);
121 p_prime += (2*n+1)*p1;
129 // This allows us to evaluate the derivative and the function for the same cost.
133 *Pn = boost::math::legendre_next(n, x, p0, p1);
138 template <class T, class Policy>
139 struct legendre_p_zero_func
144 legendre_p_zero_func(int n_, const Policy& p) : n(n_), pol(p) {}
146 std::pair<T, T> operator()(T x) const
149 T Pn_prime = detail::legendre_p_prime_imp(n, x, pol, &Pn);
150 return std::pair<T, T>(Pn, Pn_prime);
154 template <class T, class Policy>
155 std::vector<T> legendre_p_zeros_imp(int n, const Policy& pol)
161 using boost::math::constants::pi;
162 using boost::math::constants::half;
163 using boost::math::tools::newton_raphson_iterate;
165 BOOST_ASSERT(n >= 0);
166 std::vector<T> zeros;
169 // There are no zeros of P_0(x) = 1.
175 zeros.resize((n-1)/2 + 1, std::numeric_limits<T>::quiet_NaN());
181 zeros.resize(n/2, std::numeric_limits<T>::quiet_NaN());
184 T half_n = ceil(n*half<T>());
186 while (k < (int)zeros.size())
188 // Bracket the root: Szego:
189 // Gabriel Szego, Inequalities for the Zeros of Legendre Polynomials and Related Functions, Transactions of the American Mathematical Society, Vol. 39, No. 1 (1936)
190 T theta_nk = ((half_n - half<T>()*half<T>() - static_cast<T>(k))*pi<T>())/(static_cast<T>(n)+half<T>());
191 T lower_bound = cos( (half_n - static_cast<T>(k))*pi<T>()/static_cast<T>(n + 1));
192 T cos_nk = cos(theta_nk);
193 T upper_bound = cos_nk;
194 // First guess follows from:
195 // F. G. Tricomi, Sugli zeri dei polinomi sferici ed ultrasferici, Ann. Mat. Pura Appl., 31 (1950), pp. 93-97;
196 T inv_n_sq = 1/static_cast<T>(n*n);
197 T sin_nk = sin(theta_nk);
198 T x_nk_guess = (1 - inv_n_sq/static_cast<T>(8) + inv_n_sq /static_cast<T>(8*n) - (inv_n_sq*inv_n_sq/384)*(39 - 28 / (sin_nk*sin_nk) ) )*cos_nk;
200 boost::uintmax_t number_of_iterations = policies::get_max_root_iterations<Policy>();
202 legendre_p_zero_func<T, Policy> f(n, pol);
204 const T x_nk = newton_raphson_iterate(f, x_nk_guess,
205 lower_bound, upper_bound,
206 policies::digits<T, Policy>(),
207 number_of_iterations);
209 BOOST_ASSERT(lower_bound < x_nk);
210 BOOST_ASSERT(upper_bound > x_nk);
217 } // namespace detail
219 template <class T, class Policy>
220 inline typename boost::enable_if_c<policies::is_policy<Policy>::value, typename tools::promote_args<T>::type>::type
221 legendre_p(int l, T x, const Policy& pol)
223 typedef typename tools::promote_args<T>::type result_type;
224 typedef typename policies::evaluation<result_type, Policy>::type value_type;
225 static const char* function = "boost::math::legendre_p<%1%>(unsigned, %1%)";
227 return policies::checked_narrowing_cast<result_type, Policy>(detail::legendre_imp(-l-1, static_cast<value_type>(x), pol, false), function);
228 return policies::checked_narrowing_cast<result_type, Policy>(detail::legendre_imp(l, static_cast<value_type>(x), pol, false), function);
232 template <class T, class Policy>
233 inline typename boost::enable_if_c<policies::is_policy<Policy>::value, typename tools::promote_args<T>::type>::type
234 legendre_p_prime(int l, T x, const Policy& pol)
236 typedef typename tools::promote_args<T>::type result_type;
237 typedef typename policies::evaluation<result_type, Policy>::type value_type;
238 static const char* function = "boost::math::legendre_p_prime<%1%>(unsigned, %1%)";
240 return policies::checked_narrowing_cast<result_type, Policy>(detail::legendre_p_prime_imp(-l-1, static_cast<value_type>(x), pol), function);
241 return policies::checked_narrowing_cast<result_type, Policy>(detail::legendre_p_prime_imp(l, static_cast<value_type>(x), pol), function);
245 inline typename tools::promote_args<T>::type
246 legendre_p(int l, T x)
248 return boost::math::legendre_p(l, x, policies::policy<>());
252 inline typename tools::promote_args<T>::type
253 legendre_p_prime(int l, T x)
255 return boost::math::legendre_p_prime(l, x, policies::policy<>());
258 template <class T, class Policy>
259 inline std::vector<T> legendre_p_zeros(int l, const Policy& pol)
262 return detail::legendre_p_zeros_imp<T>(-l-1, pol);
264 return detail::legendre_p_zeros_imp<T>(l, pol);
269 inline std::vector<T> legendre_p_zeros(int l)
271 return boost::math::legendre_p_zeros<T>(l, policies::policy<>());
274 template <class T, class Policy>
275 inline typename boost::enable_if_c<policies::is_policy<Policy>::value, typename tools::promote_args<T>::type>::type
276 legendre_q(unsigned l, T x, const Policy& pol)
278 typedef typename tools::promote_args<T>::type result_type;
279 typedef typename policies::evaluation<result_type, Policy>::type value_type;
280 return policies::checked_narrowing_cast<result_type, Policy>(detail::legendre_imp(l, static_cast<value_type>(x), pol, true), "boost::math::legendre_q<%1%>(unsigned, %1%)");
284 inline typename tools::promote_args<T>::type
285 legendre_q(unsigned l, T x)
287 return boost::math::legendre_q(l, x, policies::policy<>());
290 // Recurrence for associated polynomials:
291 template <class T1, class T2, class T3>
292 inline typename tools::promote_args<T1, T2, T3>::type
293 legendre_next(unsigned l, unsigned m, T1 x, T2 Pl, T3 Plm1)
295 typedef typename tools::promote_args<T1, T2, T3>::type result_type;
296 return ((2 * l + 1) * result_type(x) * result_type(Pl) - (l + m) * result_type(Plm1)) / (l + 1 - m);
300 // Legendre P associated polynomial:
301 template <class T, class Policy>
302 T legendre_p_imp(int l, int m, T x, T sin_theta_power, const Policy& pol)
305 if((x < -1) || (x > 1))
306 return policies::raise_domain_error<T>(
307 "boost::math::legendre_p<%1%>(int, int, %1%)",
308 "The associated Legendre Polynomial is defined for"
309 " -1 <= x <= 1, but got x = %1%.", x, pol);
310 // Handle negative arguments first:
312 return legendre_p_imp(-l-1, m, x, sin_theta_power, pol);
315 int sign = (m&1) ? -1 : 1;
316 return sign * boost::math::tgamma_ratio(static_cast<T>(l+m+1), static_cast<T>(l+1-m), pol) * legendre_p_imp(l, -m, x, sin_theta_power, pol);
322 return boost::math::legendre_p(l, x, pol);
324 T p0 = boost::math::double_factorial<T>(2 * m - 1, pol) * sin_theta_power;
331 T p1 = x * (2 * m + 1) * p0;
338 p1 = boost::math::legendre_next(n, m, x, p0, p1);
344 template <class T, class Policy>
345 inline T legendre_p_imp(int l, int m, T x, const Policy& pol)
348 // TODO: we really could use that mythical "pow1p" function here:
349 return legendre_p_imp(l, m, x, static_cast<T>(pow(1 - x*x, T(abs(m))/2)), pol);
354 template <class T, class Policy>
355 inline typename tools::promote_args<T>::type
356 legendre_p(int l, int m, T x, const Policy& pol)
358 typedef typename tools::promote_args<T>::type result_type;
359 typedef typename policies::evaluation<result_type, Policy>::type value_type;
360 return policies::checked_narrowing_cast<result_type, Policy>(detail::legendre_p_imp(l, m, static_cast<value_type>(x), pol), "bost::math::legendre_p<%1%>(int, int, %1%)");
364 inline typename tools::promote_args<T>::type
365 legendre_p(int l, int m, T x)
367 return boost::math::legendre_p(l, m, x, policies::policy<>());
373 #endif // BOOST_MATH_SPECIAL_LEGENDRE_HPP