NAG FL Interface
s22aaf (legendre_​p)

Settings help

FL Name Style:


FL Specification Language:


1 Purpose

s22aaf returns a sequence of values for either the unnormalized or normalized Legendre functions of the first kind Pnm(x) or Pnm¯(x) for real x of a given order m and degree n=0,1,,N.

2 Specification

Fortran Interface
Subroutine s22aaf ( mode, x, m, nl, p, ifail)
Integer, Intent (In) :: mode, m, nl
Integer, Intent (Inout) :: ifail
Real (Kind=nag_wp), Intent (In) :: x
Real (Kind=nag_wp), Intent (Out) :: p(0:nl)
C Header Interface
#include <nag.h>
void  s22aaf_ (const Integer *mode, const double *x, const Integer *m, const Integer *nl, double p[], Integer *ifail)
The routine may be called by the names s22aaf or nagf_specfun_legendre_p.

3 Description

s22aaf evaluates a sequence of values for either the unnormalized or normalized Legendre (m=0) or associated Legendre (m0) functions of the first kind Pnm(x) or Pnm¯(x), where x is real with -1x1, of order m and degree n=0,1,,N defined by
Pnm(x) = (1-x2)m/2 dmdxm Pn(x)   if ​m0, Pnm(x) = (n+m)! (n-m)! Pn-m(x)   if ​m<0  and Pnm¯(x) = (2n+1) 2 (n-m)! (n+m)! Pnm(x)  
respectively; Pn(x) is the (unassociated) Legendre polynomial of degree n given by
Pn(x)Pn0(x)=12nn! dndxn (x2-1)n  
(the Rodrigues formula). Note that some authors (e.g., Abramowitz and Stegun (1972)) include an additional factor of (-1)m (the Condon–Shortley Phase) in the definitions of Pnm(x) and Pnm¯(x). They use the notation Pmn(x)(-1)mPnm(x) in order to distinguish between the two cases.
s22aaf is based on a standard recurrence relation described in Section 8.5.3 of Abramowitz and Stegun (1972). Constraints are placed on the values of m and n in order to avoid the possibility of machine overflow. It also sets the appropriate elements of the array p (see Section 5) to zero whenever the required function is not defined for certain values of m and n (e.g., m=-5 and n=3).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1: mode Integer Input
On entry: indicates whether the sequence of function values is to be returned unnormalized or normalized.
mode=1
The sequence of function values is returned unnormalized.
mode=2
The sequence of function values is returned normalized.
Constraint: mode=1 or 2.
2: x Real (Kind=nag_wp) Input
On entry: the argument x of the function.
Constraint: abs(x)1.0.
3: m Integer Input
On entry: the order m of the function.
Constraint: abs(m) 27 .
4: nl Integer Input
On entry: the degree N of the last function required in the sequence.
Constraints:
  • nl0;
  • if m=0, nl100;
  • if m0, nl 55 - abs(m) .
5: p(0:nl) Real (Kind=nag_wp) array Output
On exit: the required sequence of function values as follows:
  • if mode=1, p(n) contains Pnm (x) , for n=0,1,,N;
  • if mode=2, p(n) contains Pnm ¯ (x) , for n=0,1,,N.
6: ifail Integer Input/Output
On entry: ifail must be set to 0, −1 or 1 to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of 0 causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of −1 means that an error message is printed while a value of 1 means that it is not.
If halting is not appropriate, the value −1 or 1 is recommended. If message printing is undesirable, then the value 1 is recommended. Otherwise, the value 0 is recommended. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry ifail=0 or −1, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
ifail=1
On entry, |m|=value.
Constraint: |m|27.
On entry, |x|=value.
Constraint: |x|1.0.
On entry, mode=value.
Constraint: mode2.
On entry, mode=value.
Constraint: mode1.
On entry, nl=value.
Constraint: nl100 when m=0.
On entry, nl=value.
Constraint: nl0.
On entry, nl=value.
Constraint: when |m|0, nl0.
On entry, nl=value and |m|=value.
Constraint: nl+|m|55.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

The computed function values should be accurate to within a small multiple of the machine precision except when underflow (or overflow) occurs, in which case the true function values are within a small multiple of the underflow (or overflow) threshold of the machine.

8 Parallelism and Performance

s22aaf is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads the values of the arguments x, m and N from a file, calculates the sequence of unnormalized associated Legendre function values Pnm(x),Pn+1m(x),,Pn+Nm(x), and prints the results.

10.1 Program Text

Program Text (s22aafe.f90)

10.2 Program Data

Program Data (s22aafe.d)

10.3 Program Results

Program Results (s22aafe.r)