NAG FL Interface
s22aaf (legendre_​p)

1 Purpose

s22aaf returns a sequence of values for either the unnormalized or normalized Legendre functions of the first kind Pnmx 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 Pnmx or Pnm¯x, where x is real with -1x1, of order m and degree n=0,1,,N defined by
Pnmx = 1-x2m/2 dmdxm Pnx   if ​m0, Pnmx = n+m! n-m! Pn-mx   if ​m<0  and Pnm¯x = 2n+1 2 n-m! n+m! Pnmx  
respectively; Pnx is the (unassociated) Legendre polynomial of degree n given by
PnxPn0x=12nn! dndxn x2-1n  
(the Rodrigues formula). Note that some authors (e.g., Abramowitz and Stegun (1972)) include an additional factor of -1m (the Condon–Shortley Phase) in the definitions of Pnmx and Pnm¯x. They use the notation Pmnx-1mPnmx 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: absx1.0.
3: m Integer Input
On entry: the order m of the function.
Constraint: absm 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 - absm .
5: p0:nl Real (Kind=nag_wp) array Output
On exit: the required sequence of function values as follows:
  • if mode=1, pn contains Pnm x , for n=0,1,,N;
  • if mode=2, pn 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: m27.
On entry, x=value.
Constraint: x1.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 m0, nl0.
On entry, nl=value and m=value.
Constraint: nl+m55.
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 Pnmx,Pn+1mx,,Pn+Nmx, 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)