1 /* specfunc/legendre_poly.c
3 * Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002 Gerard Jungman
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 3 of the License, or (at
8 * your option) any later version.
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
20 /* Author: G. Jungman */
23 #include <gsl/gsl_math.h>
24 #include <gsl/gsl_errno.h>
25 #include <gsl/gsl_sf_bessel.h>
26 #include <gsl/gsl_sf_exp.h>
27 #include <gsl/gsl_sf_gamma.h>
28 #include <gsl/gsl_sf_log.h>
29 #include <gsl/gsl_sf_pow_int.h>
30 #include <gsl/gsl_sf_legendre.h>
36 /* Calculate P_m^m(x) from the analytic result:
37 * P_m^m(x) = (-1)^m (2m-1)!! (1-x^2)^(m/2) , m > 0
40 static double legendre_Pmm(int m, double x)
49 double root_factor = sqrt(1.0-x)*sqrt(1.0+x);
50 double fact_coeff = 1.0;
54 p_mm *= -fact_coeff * root_factor;
63 /*-*-*-*-*-*-*-*-*-*-*-* Functions with Error Codes *-*-*-*-*-*-*-*-*-*-*-*/
66 gsl_sf_legendre_P1_e(double x, gsl_sf_result * result)
68 /* CHECK_POINTER(result) */
78 gsl_sf_legendre_P2_e(double x, gsl_sf_result * result)
80 /* CHECK_POINTER(result) */
83 result->val = 0.5*(3.0*x*x - 1.0);
84 result->err = GSL_DBL_EPSILON * (fabs(3.0*x*x) + 1.0);
90 gsl_sf_legendre_P3_e(double x, gsl_sf_result * result)
92 /* CHECK_POINTER(result) */
95 result->val = 0.5*x*(5.0*x*x - 3.0);
96 result->err = GSL_DBL_EPSILON * (fabs(result->val) + 0.5 * fabs(x) * (fabs(5.0*x*x) + 3.0));
103 gsl_sf_legendre_Pl_e(const int l, const double x, gsl_sf_result * result)
105 /* CHECK_POINTER(result) */
107 if(l < 0 || x < -1.0 || x > 1.0) {
108 DOMAIN_ERROR(result);
121 result->val = 0.5 * (3.0*x*x - 1.0);
122 result->err = GSL_DBL_EPSILON * (fabs(3.0*x*x) + 1.0);
123 /*result->err = 3.0 * GSL_DBL_EPSILON * fabs(result->val);
124 removed this old bogus estimate [GJ]
134 result->val = ( GSL_IS_ODD(l) ? -1.0 : 1.0 );
138 else if(l < 100000) {
139 /* upward recurrence: l P_l = (2l-1) z P_{l-1} - (l-1) P_{l-2} */
141 double p_ellm2 = 1.0; /* P_0(x) */
142 double p_ellm1 = x; /* P_1(x) */
143 double p_ell = p_ellm1;
145 double e_ellm2 = GSL_DBL_EPSILON;
146 double e_ellm1 = fabs(x)*GSL_DBL_EPSILON;
147 double e_ell = e_ellm1;
151 for(ell=2; ell <= l; ell++){
152 p_ell = (x*(2*ell-1)*p_ellm1 - (ell-1)*p_ellm2) / ell;
156 e_ell = 0.5*(fabs(x)*(2*ell-1.0) * e_ellm1 + (ell-1.0)*e_ellm2)/ell;
162 result->err = e_ell + l*fabs(p_ell)*GSL_DBL_EPSILON;
166 /* Asymptotic expansion.
173 int stat_J0 = gsl_sf_bessel_J0_e(u*th, &J0);
174 int stat_Jm1 = gsl_sf_bessel_Jn_e(-1, u*th, &Jm1);
179 /* B00 = 1/8 (1 - th cot(th) / th^2
180 * pre = sqrt(th/sin(th))
182 if(th < GSL_ROOT4_DBL_EPSILON) {
183 B00 = (1.0 + th*th/15.0)/24.0;
184 pre = 1.0 + th*th/12.0;
187 double sin_th = sqrt(1.0 - x*x);
188 double cot_th = x / sin_th;
189 B00 = 1.0/8.0 * (1.0 - th * cot_th) / (th*th);
190 pre = sqrt(th/sin_th);
195 result->val = pre * (J0.val + c1 * Jm1.val);
196 result->err = pre * (J0.err + fabs(c1) * Jm1.err);
197 result->err += GSL_SQRT_DBL_EPSILON * fabs(result->val);
199 return GSL_ERROR_SELECT_2(stat_J0, stat_Jm1);
205 gsl_sf_legendre_Pl_array(const int lmax, const double x, double * result_array)
207 /* CHECK_POINTER(result_array) */
209 if(lmax < 0 || x < -1.0 || x > 1.0) {
210 GSL_ERROR ("domain error", GSL_EDOM);
213 result_array[0] = 1.0;
217 result_array[0] = 1.0;
222 /* upward recurrence: l P_l = (2l-1) z P_{l-1} - (l-1) P_{l-2} */
224 double p_ellm2 = 1.0; /* P_0(x) */
225 double p_ellm1 = x; /* P_1(x) */
226 double p_ell = p_ellm1;
229 result_array[0] = 1.0;
232 for(ell=2; ell <= lmax; ell++){
233 p_ell = (x*(2*ell-1)*p_ellm1 - (ell-1)*p_ellm2) / ell;
236 result_array[ell] = p_ell;
245 gsl_sf_legendre_Pl_deriv_array(const int lmax, const double x, double * result_array, double * result_deriv_array)
247 int stat_array = gsl_sf_legendre_Pl_array(lmax, x, result_array);
249 if(lmax >= 0) result_deriv_array[0] = 0.0;
250 if(lmax >= 1) result_deriv_array[1] = 1.0;
252 if(stat_array == GSL_SUCCESS)
256 if(fabs(x - 1.0)*(lmax+1.0)*(lmax+1.0) < GSL_SQRT_DBL_EPSILON)
259 for(ell = 2; ell <= lmax; ell++)
261 const double pre = 0.5 * ell * (ell+1.0);
262 result_deriv_array[ell] = pre * (1.0 - 0.25 * (1.0-x) * (ell+2.0)*(ell-1.0));
265 else if(fabs(x + 1.0)*(lmax+1.0)*(lmax+1.0) < GSL_SQRT_DBL_EPSILON)
268 for(ell = 2; ell <= lmax; ell++)
270 const double sgn = ( GSL_IS_ODD(ell) ? 1.0 : -1.0 ); /* derivative is odd in x for even ell */
271 const double pre = sgn * 0.5 * ell * (ell+1.0);
272 result_deriv_array[ell] = pre * (1.0 - 0.25 * (1.0+x) * (ell+2.0)*(ell-1.0));
277 const double diff_a = 1.0 + x;
278 const double diff_b = 1.0 - x;
279 for(ell = 2; ell <= lmax; ell++)
281 result_deriv_array[ell] = - ell * (x * result_array[ell] - result_array[ell-1]) / (diff_a * diff_b);
295 gsl_sf_legendre_Plm_e(const int l, const int m, const double x, gsl_sf_result * result)
297 /* If l is large and m is large, then we have to worry
298 * about overflow. Calculate an approximate exponent which
299 * measures the normalization of this thing.
301 const double dif = l-m;
302 const double sum = l+m;
303 const double t_d = ( dif == 0.0 ? 0.0 : 0.5 * dif * (log(dif)-1.0) );
304 const double t_s = ( dif == 0.0 ? 0.0 : 0.5 * sum * (log(sum)-1.0) );
305 const double exp_check = 0.5 * log(2.0*l+1.0) + t_d - t_s;
307 /* CHECK_POINTER(result) */
309 if(m < 0 || l < m || x < -1.0 || x > 1.0) {
310 DOMAIN_ERROR(result);
312 else if(exp_check < GSL_LOG_DBL_MIN + 10.0){
314 OVERFLOW_ERROR(result);
317 /* Account for the error due to the
318 * representation of 1-x.
320 const double err_amp = 1.0 / (GSL_DBL_EPSILON + fabs(1.0-fabs(x)));
322 /* P_m^m(x) and P_{m+1}^m(x) */
323 double p_mm = legendre_Pmm(m, x);
324 double p_mmp1 = x * (2*m + 1) * p_mm;
328 result->err = err_amp * 2.0 * GSL_DBL_EPSILON * fabs(p_mm);
331 else if(l == m + 1) {
332 result->val = p_mmp1;
333 result->err = err_amp * 2.0 * GSL_DBL_EPSILON * fabs(p_mmp1);
337 /* upward recurrence: (l-m) P(l,m) = (2l-1) z P(l-1,m) - (l+m-1) P(l-2,m)
338 * start at P(m,m), P(m+1,m)
341 double p_ellm2 = p_mm;
342 double p_ellm1 = p_mmp1;
346 for(ell=m+2; ell <= l; ell++){
347 p_ell = (x*(2*ell-1)*p_ellm1 - (ell+m-1)*p_ellm2) / (ell-m);
353 result->err = err_amp * (0.5*(l-m) + 1.0) * GSL_DBL_EPSILON * fabs(p_ell);
362 gsl_sf_legendre_Plm_array(const int lmax, const int m, const double x, double * result_array)
364 /* If l is large and m is large, then we have to worry
365 * about overflow. Calculate an approximate exponent which
366 * measures the normalization of this thing.
368 const double dif = lmax-m;
369 const double sum = lmax+m;
370 const double t_d = ( dif == 0.0 ? 0.0 : 0.5 * dif * (log(dif)-1.0) );
371 const double t_s = ( dif == 0.0 ? 0.0 : 0.5 * sum * (log(sum)-1.0) );
372 const double exp_check = 0.5 * log(2.0*lmax+1.0) + t_d - t_s;
374 /* CHECK_POINTER(result_array) */
376 if(m < 0 || lmax < m || x < -1.0 || x > 1.0) {
377 GSL_ERROR ("domain error", GSL_EDOM);
379 else if(m > 0 && (x == 1.0 || x == -1.0)) {
381 for(ell=m; ell<=lmax; ell++) result_array[ell-m] = 0.0;
384 else if(exp_check < GSL_LOG_DBL_MIN + 10.0){
386 GSL_ERROR ("overflow", GSL_EOVRFLW);
389 double p_mm = legendre_Pmm(m, x);
390 double p_mmp1 = x * (2.0*m + 1.0) * p_mm;
393 result_array[0] = p_mm;
396 else if(lmax == m + 1) {
397 result_array[0] = p_mm;
398 result_array[1] = p_mmp1;
402 double p_ellm2 = p_mm;
403 double p_ellm1 = p_mmp1;
407 result_array[0] = p_mm;
408 result_array[1] = p_mmp1;
410 for(ell=m+2; ell <= lmax; ell++){
411 p_ell = (x*(2.0*ell-1.0)*p_ellm1 - (ell+m-1)*p_ellm2) / (ell-m);
414 result_array[ell-m] = p_ell;
424 gsl_sf_legendre_Plm_deriv_array(
425 const int lmax, const int m, const double x,
426 double * result_array,
427 double * result_deriv_array)
429 if(m < 0 || m > lmax)
431 GSL_ERROR("m < 0 or m > lmax", GSL_EDOM);
435 /* It is better to do m=0 this way, so we can more easily
436 * trap the divergent case which can occur when m == 1.
438 return gsl_sf_legendre_Pl_deriv_array(lmax, x, result_array, result_deriv_array);
442 int stat_array = gsl_sf_legendre_Plm_array(lmax, m, x, result_array);
444 if(stat_array == GSL_SUCCESS)
448 if(m == 1 && (1.0 - fabs(x) < GSL_DBL_EPSILON))
450 /* This divergence is real and comes from the cusp-like
451 * behaviour for m = 1. For example, P[1,1] = - Sqrt[1-x^2].
453 GSL_ERROR("divergence near |x| = 1.0 since m = 1", GSL_EOVRFLW);
455 else if(m == 2 && (1.0 - fabs(x) < GSL_DBL_EPSILON))
457 /* m = 2 gives a finite nonzero result for |x| near 1 */
458 if(fabs(x - 1.0) < GSL_DBL_EPSILON)
460 for(ell = m; ell <= lmax; ell++) result_deriv_array[ell-m] = -0.25 * x * (ell - 1.0)*ell*(ell+1.0)*(ell+2.0);
462 else if(fabs(x + 1.0) < GSL_DBL_EPSILON)
464 for(ell = m; ell <= lmax; ell++)
466 const double sgn = ( GSL_IS_ODD(ell) ? 1.0 : -1.0 );
467 result_deriv_array[ell-m] = -0.25 * sgn * x * (ell - 1.0)*ell*(ell+1.0)*(ell+2.0);
474 /* m > 2 is easier to deal with since the endpoints always vanish */
475 if(1.0 - fabs(x) < GSL_DBL_EPSILON)
477 for(ell = m; ell <= lmax; ell++) result_deriv_array[ell-m] = 0.0;
482 const double diff_a = 1.0 + x;
483 const double diff_b = 1.0 - x;
484 result_deriv_array[0] = - m * x / (diff_a * diff_b) * result_array[0];
485 if(lmax-m >= 1) result_deriv_array[1] = (2.0 * m + 1.0) * (x * result_deriv_array[0] + result_array[0]);
486 for(ell = m+2; ell <= lmax; ell++)
488 result_deriv_array[ell-m] = - (ell * x * result_array[ell-m] - (ell+m) * result_array[ell-1-m]) / (diff_a * diff_b);
503 gsl_sf_legendre_sphPlm_e(const int l, int m, const double x, gsl_sf_result * result)
505 /* CHECK_POINTER(result) */
507 if(m < 0 || l < m || x < -1.0 || x > 1.0) {
508 DOMAIN_ERROR(result);
512 int stat_P = gsl_sf_legendre_Pl_e(l, x, &P);
513 double pre = sqrt((2.0*l + 1.0)/(4.0*M_PI));
514 result->val = pre * P.val;
515 result->err = pre * P.err;
516 result->err += 2.0 * GSL_DBL_EPSILON * fabs(result->val);
519 else if(x == 1.0 || x == -1.0) {
526 /* m > 0 and |x| < 1 here */
528 /* Starting value for recursion.
529 * Y_m^m(x) = sqrt( (2m+1)/(4pi m) gamma(m+1/2)/gamma(m) ) (-1)^m (1-x^2)^(m/2) / pi^(1/4)
531 gsl_sf_result lncirc;
532 gsl_sf_result lnpoch;
535 gsl_sf_result ex_pre;
537 const double sgn = ( GSL_IS_ODD(m) ? -1.0 : 1.0);
538 const double y_mmp1_factor = x * sqrt(2.0*m + 3.0);
539 double y_mm, y_mm_err;
540 double y_mmp1, y_mmp1_err;
541 gsl_sf_log_1plusx_e(-x*x, &lncirc);
542 gsl_sf_lnpoch_e(m, 0.5, &lnpoch); /* Gamma(m+1/2)/Gamma(m) */
543 lnpre_val = -0.25*M_LNPI + 0.5 * (lnpoch.val + m*lncirc.val);
544 lnpre_err = 0.25*M_LNPI*GSL_DBL_EPSILON + 0.5 * (lnpoch.err + fabs(m)*lncirc.err);
545 /* Compute exp(ln_pre) with error term, avoiding call to gsl_sf_exp_err BJG */
546 ex_pre.val = exp(lnpre_val);
547 ex_pre.err = 2.0*(sinh(lnpre_err) + GSL_DBL_EPSILON)*ex_pre.val;
548 sr = sqrt((2.0+1.0/m)/(4.0*M_PI));
549 y_mm = sgn * sr * ex_pre.val;
550 y_mm_err = 2.0 * GSL_DBL_EPSILON * fabs(y_mm) + sr * ex_pre.err;
551 y_mm_err *= 1.0 + 1.0/(GSL_DBL_EPSILON + fabs(1.0-x));
552 y_mmp1 = y_mmp1_factor * y_mm;
553 y_mmp1_err=fabs(y_mmp1_factor) * y_mm_err;
557 result->err = y_mm_err;
558 result->err += 2.0 * GSL_DBL_EPSILON * fabs(y_mm);
561 else if(l == m + 1) {
562 result->val = y_mmp1;
563 result->err = y_mmp1_err;
564 result->err += 2.0 * GSL_DBL_EPSILON * fabs(y_mmp1);
572 /* Compute Y_l^m, l > m+1, upward recursion on l. */
573 for(ell=m+2; ell <= l; ell++){
574 const double rat1 = (double)(ell-m)/(double)(ell+m);
575 const double rat2 = (ell-m-1.0)/(ell+m-1.0);
576 const double factor1 = sqrt(rat1*(2.0*ell+1.0)*(2.0*ell-1.0));
577 const double factor2 = sqrt(rat1*rat2*(2.0*ell+1.0)/(2.0*ell-3.0));
578 y_ell = (x*y_mmp1*factor1 - (ell+m-1.0)*y_mm*factor2) / (ell-m);
582 y_ell_err = 0.5*(fabs(x*factor1)*y_mmp1_err + fabs((ell+m-1.0)*factor2)*y_mm_err) / fabs(ell-m);
583 y_mm_err = y_mmp1_err;
584 y_mmp1_err = y_ell_err;
588 result->err = y_ell_err + (0.5*(l-m) + 1.0) * GSL_DBL_EPSILON * fabs(y_ell);
597 gsl_sf_legendre_sphPlm_array(const int lmax, int m, const double x, double * result_array)
599 /* CHECK_POINTER(result_array) */
601 if(m < 0 || lmax < m || x < -1.0 || x > 1.0) {
602 GSL_ERROR ("error", GSL_EDOM);
604 else if(m > 0 && (x == 1.0 || x == -1.0)) {
606 for(ell=m; ell<=lmax; ell++) result_array[ell-m] = 0.0;
614 y_mm = 0.5/M_SQRTPI; /* Y00 = 1/sqrt(4pi) */
615 y_mmp1 = x * M_SQRT3 * y_mm;
620 gsl_sf_result lncirc;
621 gsl_sf_result lnpoch;
623 const double sgn = ( GSL_IS_ODD(m) ? -1.0 : 1.0);
624 gsl_sf_log_1plusx_e(-x*x, &lncirc);
625 gsl_sf_lnpoch_e(m, 0.5, &lnpoch); /* Gamma(m+1/2)/Gamma(m) */
626 lnpre = -0.25*M_LNPI + 0.5 * (lnpoch.val + m*lncirc.val);
627 y_mm = sqrt((2.0+1.0/m)/(4.0*M_PI)) * sgn * exp(lnpre);
628 y_mmp1 = x * sqrt(2.0*m + 3.0) * y_mm;
632 result_array[0] = y_mm;
635 else if(lmax == m + 1) {
636 result_array[0] = y_mm;
637 result_array[1] = y_mmp1;
644 result_array[0] = y_mm;
645 result_array[1] = y_mmp1;
647 /* Compute Y_l^m, l > m+1, upward recursion on l. */
648 for(ell=m+2; ell <= lmax; ell++){
649 const double rat1 = (double)(ell-m)/(double)(ell+m);
650 const double rat2 = (ell-m-1.0)/(ell+m-1.0);
651 const double factor1 = sqrt(rat1*(2*ell+1)*(2*ell-1));
652 const double factor2 = sqrt(rat1*rat2*(2*ell+1)/(2*ell-3));
653 y_ell = (x*y_mmp1*factor1 - (ell+m-1)*y_mm*factor2) / (ell-m);
656 result_array[ell-m] = y_ell;
666 gsl_sf_legendre_sphPlm_deriv_array(
667 const int lmax, const int m, const double x,
668 double * result_array,
669 double * result_deriv_array)
671 if(m < 0 || lmax < m || x < -1.0 || x > 1.0)
673 GSL_ERROR ("domain", GSL_EDOM);
677 /* m = 0 is easy to trap */
678 const int stat_array = gsl_sf_legendre_Pl_deriv_array(lmax, x, result_array, result_deriv_array);
680 for(ell = 0; ell <= lmax; ell++)
682 const double prefactor = sqrt((2.0 * ell + 1.0)/(4.0*M_PI));
683 result_array[ell] *= prefactor;
684 result_deriv_array[ell] *= prefactor;
690 /* Trapping m = 1 is necessary because of the possible divergence.
691 * Recall that this divergence is handled properly in ..._Plm_deriv_array(),
692 * and the scaling factor is not large for small m, so we just scale.
694 const int stat_array = gsl_sf_legendre_Plm_deriv_array(lmax, m, x, result_array, result_deriv_array);
696 for(ell = 1; ell <= lmax; ell++)
698 const double prefactor = sqrt((2.0 * ell + 1.0)/(ell + 1.0) / (4.0*M_PI*ell));
699 result_array[ell-1] *= prefactor;
700 result_deriv_array[ell-1] *= prefactor;
706 /* as for the derivative of P_lm, everything is regular for m >= 2 */
708 int stat_array = gsl_sf_legendre_sphPlm_array(lmax, m, x, result_array);
710 if(stat_array == GSL_SUCCESS)
714 if(1.0 - fabs(x) < GSL_DBL_EPSILON)
716 for(ell = m; ell <= lmax; ell++) result_deriv_array[ell-m] = 0.0;
721 const double diff_a = 1.0 + x;
722 const double diff_b = 1.0 - x;
723 result_deriv_array[0] = - m * x / (diff_a * diff_b) * result_array[0];
724 if(lmax-m >= 1) result_deriv_array[1] = sqrt(2.0 * m + 3.0) * (x * result_deriv_array[0] + result_array[0]);
725 for(ell = m+2; ell <= lmax; ell++)
727 const double c1 = sqrt(((2.0*ell+1.0)/(2.0*ell-1.0)) * ((double)(ell-m)/(double)(ell+m)));
728 result_deriv_array[ell-m] = - (ell * x * result_array[ell-m] - c1 * (ell+m) * result_array[ell-1-m]) / (diff_a * diff_b);
741 #ifndef HIDE_INLINE_STATIC
743 gsl_sf_legendre_array_size(const int lmax, const int m)
750 /*-*-*-*-*-*-*-*-*-* Functions w/ Natural Prototypes *-*-*-*-*-*-*-*-*-*-*/
754 double gsl_sf_legendre_P1(const double x)
756 EVAL_RESULT(gsl_sf_legendre_P1_e(x, &result));
759 double gsl_sf_legendre_P2(const double x)
761 EVAL_RESULT(gsl_sf_legendre_P2_e(x, &result));
764 double gsl_sf_legendre_P3(const double x)
766 EVAL_RESULT(gsl_sf_legendre_P3_e(x, &result));
769 double gsl_sf_legendre_Pl(const int l, const double x)
771 EVAL_RESULT(gsl_sf_legendre_Pl_e(l, x, &result));
774 double gsl_sf_legendre_Plm(const int l, const int m, const double x)
776 EVAL_RESULT(gsl_sf_legendre_Plm_e(l, m, x, &result));
779 double gsl_sf_legendre_sphPlm(const int l, const int m, const double x)
781 EVAL_RESULT(gsl_sf_legendre_sphPlm_e(l, m, x, &result));