Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_specfun_legendre_p (s22aa)

## Purpose

nag_specfun_legendre_p (s22aa) returns a sequence of values for either the unnormalized or normalized Legendre functions of the first kind ${P}_{n}^{m}\left(x\right)$ or $\overline{{P}_{n}^{m}}\left(x\right)$ for real $x$ of a given order $m$ and degree $n=0,1,\dots ,N$.

## Syntax

[p, ifail] = s22aa(mode, x, m, nl)
[p, ifail] = nag_specfun_legendre_p(mode, x, m, nl)

## Description

nag_specfun_legendre_p (s22aa) evaluates a sequence of values for either the unnormalized or normalized Legendre ($m=0$) or associated Legendre ($m\ne 0$) functions of the first kind ${P}_{n}^{m}\left(x\right)$ or $\overline{{P}_{n}^{m}}\left(x\right)$, where $x$ is real with $-1\le x\le 1$, of order $m$ and degree $n=0,1,\dots ,N$ defined by
 $Pnmx = 1-x2m/2 dmdxm Pnx if ​m≥0, Pnmx = n+m! n-m! Pn-mx if ​m<0 and Pnm¯x = 2n+1 2 n-m! n+m! Pnmx$
respectively; ${P}_{n}\left(x\right)$ is the (unassociated) Legendre polynomial of degree $n$ given by
 $Pnx≡Pn0x=12nn! dndxn x2-1n$
(the Rodrigues formula). Note that some authors (e.g., Abramowitz and Stegun (1972)) include an additional factor of ${\left(-1\right)}^{m}$ (the Condon–Shortley Phase) in the definitions of ${P}_{n}^{m}\left(x\right)$ and $\overline{{P}_{n}^{m}}\left(x\right)$. They use the notation ${P}_{mn}\left(x\right)\equiv {\left(-1\right)}^{m}{P}_{n}^{m}\left(x\right)$ in order to distinguish between the two cases.
nag_specfun_legendre_p (s22aa) 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 Arguments) to zero whenever the required function is not defined for certain values of $m$ and $n$ (e.g., $m=-5$ and $n=3$).

## References

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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{mode}$int64int32nag_int scalar
Indicates whether the sequence of function values is to be returned unnormalized or normalized.
${\mathbf{mode}}=1$
The sequence of function values is returned unnormalized.
${\mathbf{mode}}=2$
The sequence of function values is returned normalized.
Constraint: ${\mathbf{mode}}=1$ or $2$.
2:     $\mathrm{x}$ – double scalar
The argument $x$ of the function.
Constraint: $\mathrm{abs}\left({\mathbf{x}}\right)\le 1.0$.
3:     $\mathrm{m}$int64int32nag_int scalar
The order $m$ of the function.
Constraint: $\mathrm{abs}\left({\mathbf{m}}\right)\le 27$.
4:     $\mathrm{nl}$int64int32nag_int scalar
The degree $N$ of the last function required in the sequence.
Constraints:
• ${\mathbf{nl}}\ge 0$;
• if ${\mathbf{m}}=0$, ${\mathbf{nl}}\le 100$;
• if ${\mathbf{m}}\ne 0$, ${\mathbf{nl}}\le 55-\mathrm{abs}\left({\mathbf{m}}\right)$.

None.

### Output Parameters

1:     $\mathrm{p}\left(0:{\mathbf{nl}}\right)$ – double array
The required sequence of function values as follows:
• if ${\mathbf{mode}}=1$, ${\mathbf{p}}\left(n+1\right)$ contains ${P}_{n}^{m}\left(x\right)$, for $\mathit{n}=0,1,\dots ,N$;
• if ${\mathbf{mode}}=2$, ${\mathbf{p}}\left(n+1\right)$ contains $\overline{{P}_{n}^{m}}\left(x\right)$, for $\mathit{n}=0,1,\dots ,N$.
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
 On entry, $\mathrm{abs}\left({\mathbf{x}}\right)>1.0$, or ${\mathbf{mode}}\ne 1$ or $2$, or ${\mathbf{nl}}<0$, or ${\mathbf{nl}}>100$ when ${\mathbf{m}}=0$, or $\mathrm{abs}\left({\mathbf{m}}\right)>27$, or ${\mathbf{nl}}+\mathrm{abs}\left({\mathbf{m}}\right)>55$ when ${\mathbf{m}}\ne 0$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## 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.

None.

## 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 ${P}_{n}^{m}\left(x\right),{P}_{n+1}^{m}\left(x\right),\dots ,{P}_{n+N}^{m}\left(x\right)$, and prints the results.
```function s22aa_example

fprintf('s22aa example results\n\n');

mode = int64(1);
x  = 0.5;
m  = int64(2);
n  = int64(3);

[p, ifail] = s22aa(mode, x, m, n);

fprintf('First %2d unnormalized associated Legendre function values ',n);
fprintf('P^%d_n(%7.4f)\n\n',m,x);
fprintf('%3s%8s\n','n','P_n');
fprintf('%3d%10.4f\n', [double([0:n]); p']);

```
```s22aa example results

First  3 unnormalized associated Legendre function values P^2_n( 0.5000)

n     P_n
0    0.0000
1    0.0000
2    2.2500
3    5.6250
```