# legendre

Associated Legendre functions

## Syntax

``P = legendre(n,X)``
``P = legendre(n,X,normalization)``

## Description

example

````P = legendre(n,X)` computes the associated Legendre functions of degree `n` and order `m = 0, 1, ..., n` evaluated for each element in `X`.```

example

````P = legendre(n,X,normalization)` computes normalized versions of the associated Legendre functions. `normalization` can be `'unnorm'` (default), `'sch'`, or `'norm'`.```

## Examples

collapse all

Use the `legendre` function to operate on a vector and then examine the format of the output.

Calculate the second-degree Legendre function values of a vector.

```deg = 2; x = 0:0.1:0.2; P = legendre(deg,x)```
```P = 3×3 -0.5000 -0.4850 -0.4400 0 -0.2985 -0.5879 3.0000 2.9700 2.8800 ```

The format of the output is such that:

• Each row contains the function value for different values of m (the order of the associated Legendre function)

• Each column contains the function value for a different value of x

The equation for the second-degree associated Legendre function ${\mathit{P}}_{2}^{\mathit{m}}$ is

`${P}_{2}^{m}\left(x\right)={\left(-1\right)}^{m}{\left(1-{x}^{2}\right)}^{m/2}\frac{{d}^{m}}{d{x}^{m}}\left[\frac{1}{2}\left(3{x}^{2}-1\right)\right].$`

Therefore, the value of ${\mathit{P}}_{2}^{0}\left(0\right)$ is

`${P}_{2}^{0}\left(0\right)=\left[\frac{1}{2}\left(3{x}^{2}-1\right)\right]{|}_{x=0}=-\frac{1}{2}.$`

This result agrees with `P(1,1) = -0.5000`.

Calculate the associated Legendre function values with several normalizations.

Calculate the first-degree, unnormalized Legendre function values ${\mathit{P}}_{1}^{\mathit{m}}$. The first row of values corresponds to $\mathit{m}=0$, and the second row to $\mathit{m}=1$.

```x = 0:0.2:1; n = 1; P_unnorm = legendre(n,x)```
```P_unnorm = 2×6 0 0.2000 0.4000 0.6000 0.8000 1.0000 -1.0000 -0.9798 -0.9165 -0.8000 -0.6000 0 ```

Next, compute the Schmidt seminormalized function values. Compared to the unnormalized values, the Schmidt form differs when $\mathit{m}>0$ by the scaling

`${\left(-1\right)}^{m}\sqrt{\frac{2\left(n-m\right)!}{\left(n+m\right)!}}.$`

For the first row, the two normalizations are the same, since $\mathit{m}=0$. For the second row, the scaling constant multiplying each value is -1.

`P_sch = legendre(n,x,'sch')`
```P_sch = 2×6 0 0.2000 0.4000 0.6000 0.8000 1.0000 1.0000 0.9798 0.9165 0.8000 0.6000 0 ```
`C1 = (-1) * sqrt(2*factorial(0)/factorial(2))`
```C1 = -1 ```

Lastly, compute the fully normalized function values. Compared to the unnormalized values, the fully normalized form differs by the scaling factor

`${\left(-1\right)}^{m}\sqrt{\frac{\left(n+\frac{1}{2}\right)\left(n-m\right)!}{\left(n+m\right)!}}.$`

This scaling factor applies for all values of $\mathit{m}$, so the first and second rows have different scaling factors.

`P_norm = legendre(n,x,'norm')`
```P_norm = 2×6 0 0.2449 0.4899 0.7348 0.9798 1.2247 0.8660 0.8485 0.7937 0.6928 0.5196 0 ```
`Cm0 = sqrt((3/2))`
```Cm0 = 1.2247 ```
`Cm1 = (-1) * sqrt((3/2)/2)`
```Cm1 = -0.8660 ```

Spherical harmonics arise in the solution to Laplace's equation and are used to represent functions defined on the surface of a sphere. Use `legendre` to compute and visualize the spherical harmonic for ${\mathit{Y}}_{3}^{2}$.

The equation for spherical harmonics includes a term for the Legendre function, as well as a complex exponential:

`${Y}_{l}^{m}\left(\theta ,\varphi \right)=\sqrt{\frac{\left(2l+1\right)\left(l-m\right)!}{4\pi \left(l+m\right)!}}{P}_{l}^{m}\left(\mathrm{cos}\theta \right){e}^{im\varphi },\phantom{\rule{2em}{0ex}}-l\le m\le l.$`

First, create a grid of values to represent all combinations of $-\frac{\pi }{2}\le \theta \le \frac{\pi }{2}\text{\hspace{0.17em}}$ (altitude angle) and $0\le \varphi \le 2\pi$ (azimuthal angle).

```dx = pi/60; alt = -pi/2:dx:pi/2; az = 0:dx:2*pi; [phi,theta] = meshgrid(az,alt);```

Calculate ${\mathit{P}}_{\mathit{l}}^{\mathit{m}}\left(\mathrm{cos}\text{\hspace{0.17em}}\theta \text{\hspace{0.17em}}\right)$ on the grid for $\mathit{l}=3$.

```l = 3; Plm = legendre(l,cos(theta));```

Since `legendre` computes the answer for all values of $\mathit{m}$, `Plm` contains some extra function values. Extract the values for $\mathit{m}=2$ and discard the rest. Use the `reshape` function to orient the results as a matrix with the same size as `phi` and `theta`.

```m = 2; P32 = reshape(Plm(m+1,:,:), size(phi));```

Calculate the spherical harmonic values for ${\mathit{Y}}_{3}^{2}$.

```a = (2*l+1)*factorial(l-m); b = 4*pi*factorial(l+m); C = sqrt(a/b); Y32 = C .* P32 .* exp(1i*m*phi);```

Convert to Cartesian coordinates and plot the spherical harmonic for ${\mathit{Y}}_{3}^{2}$ using only the real values.

```[Xm,Ym,Zm] = sph2cart(phi, theta, real(Y32)); surf(Xm,Ym,Zm) title('\$Y_3^2\$ spherical harmonic','interpreter','latex')``` ## Input Arguments

collapse all

Degree of Legendre function, specified as a positive integer. For a specified degree, `legendre` computes ${P}_{n}^{m}\left(x\right)$ for all orders m from m = 0 to m = n.

Example: `legendre(2,X)`

Input values, specified as a scalar, vector, matrix, or multidimensional array of real values in the range `[-1,1]`. For example, with spherical harmonics it is common to use `X = cos(theta)` as the input values to compute ${P}_{n}^{m}\left(\mathrm{cos}\theta \right)$.

Example: `legendre(2,cos(theta))`

Data Types: `single` | `double`

Normalization type, specified as one of these values.

Example: `legendre(n,X,'sch')`

## Output Arguments

collapse all

Associated Legendre function values, returned as a scalar, vector, matrix, or multidimensional array. The normalization of `P` depends on the value of `normalization`.

The size of `P` depends on the size of `X`:

• If `X` is a vector, then `P` is a matrix of size `(n+1)`-by-`length(X)`. The `P(m+1,i)` entry is the associated Legendre function of degree `n` and order `m` evaluated at `X(i)`.

• In general, `P` has one more dimension than `X` and each element `P(m+1,i,j,k,...)` contains the associated Legendre function of degree `n` and order `m` evaluated at `X(i,j,k,...)`.

## Limitations

The values of the unnormalized associated Legendre function overflow the range of double-precision numbers for `n > 150` and the range of single-precision numbers for `n > 28`. This overflow results in `Inf` and `NaN` values. For orders larger than these thresholds, consider using the `'sch'` or `'norm'` normalizations instead.

collapse all

### Associated Legendre Functions

The associated Legendre functions $y={P}_{n}^{m}\left(x\right)$ are solutions to the general Legendre differential equation

`$\left(1-{x}^{2}\right)\frac{{d}^{2}y}{d{x}^{2}}-2x\frac{dy}{dx}+\left[n\left(n+1\right)-\frac{{m}^{2}}{1-{x}^{2}}\right]y=0\text{\hspace{0.17em}}.$`

n is the integer degree and m is the integer order of the associated Legendre function, such that $0\le m\le n$.

The associated Legendre functions ${P}_{n}^{m}\left(x\right)$ are the most general solutions to this equation given by

`${P}_{n}^{m}\left(x\right)={\left(-1\right)}^{m}{\left(1-{x}^{2}\right)}^{m/2}\frac{{d}^{m}}{d{x}^{m}}{P}_{n}\left(x\right)\text{\hspace{0.17em}}.$`

They are defined in terms of derivatives of the Legendre polynomials ${P}_{n}\left(x\right)$, which are a subset of the solutions given by

`${P}_{n}\left(x\right)=\frac{1}{{2}^{n}n!}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\frac{{d}^{n}}{d{x}^{n}}{\left({x}^{2}-1\right)}^{n}\text{\hspace{0.17em}}.$`

The first few Legendre polynomials are

Value of `n`${P}_{n}\left(x\right)$
`0`${P}_{0}\left(x\right)=1$
`1`${P}_{1}\left(x\right)=x$
`2`${P}_{2}\left(x\right)=\frac{1}{2}\left(3{x}^{2}-1\right)$

### Schmidt Seminormalized Associated Legendre Functions

The Schmidt seminormalized associated Legendre functions are related to the unnormalized associated Legendre functions ${P}_{n}^{m}\left(x\right)$ by

### Fully Normalized Associated Legendre Functions

The fully normalized associated Legendre functions are normalized such that

`${\int }_{-1}^{1}{\left[{N}_{n}^{m}\left(x\right)\right]}^{\text{\hspace{0.17em}}2}dx=1\text{\hspace{0.17em}}.$`

The normalized functions are related to the unnormalized associated Legendre functions ${P}_{n}^{m}\left(x\right)$ by

`${N}_{n}^{m}\left(x\right)={\left(-1\right)}^{m}\sqrt{\frac{\left(n+\frac{1}{2}\right)\left(n-m\right)!}{\left(n+m\right)!}}{P}_{n}^{m}\left(x\right)\text{\hspace{0.17em}}.$`

## Algorithms

`legendre` uses a three-term backward recursion relationship in `m`. This recursion is on a version of the Schmidt seminormalized associated Legendre functions ${Q}_{n}^{m}\left(x\right)$, which are complex spherical harmonics. These functions are related to the standard Abramowitz and Stegun  functions ${P}_{n}^{m}\left(x\right)$ by

`${P}_{n}^{m}\left(x\right)=\sqrt{\frac{\left(n+m\right)!}{\left(n-m\right)!}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}{Q}_{n}^{m}\left(x\right)\text{\hspace{0.17em}}.$`

They are related to the Schmidt form by

`$\begin{array}{l}m=0:\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}{S}_{n}^{m}\left(x\right)={Q}_{n}^{0}\left(x\right)\\ m>0:\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}{S}_{n}^{m}\left(x\right)={\left(-1\right)}^{m}\sqrt{2}\text{\hspace{0.17em}}\text{\hspace{0.17em}}{Q}_{n}^{m}\left(x\right)\text{\hspace{0.17em}}.\end{array}$`

 Abramowitz, M. and I. A. Stegun, Handbook of Mathematical Functions, Dover Publications, 1965, Ch.8.

 Jacobs, J. A., Geomagnetism, Academic Press, 1987, Ch.4.