legendre

Associated Legendre functions

Syntax

P = legendre(n,X)

P = legendre(n,X,normalization)

Description

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

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

Examples

Associated Legendre Function Values of Vector

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

$$\begin{array}{cccc}& \text{x}\text{=}\text{0}& \text{x}\text{=}\text{0.1}& \text{x}\text{=}\text{0.2}\\ \text{m}\text{=}\text{0}& P_2^0(0)& P_2^0(0.1)& P_2^0(0.2)\\ \text{m}\text{=}\text{1}& P_2^1(0)& P_2^1(0.1)& P_2^1(0.2)\\ \text{m}\text{=}\text{2}& P_2^2(0)& P_2^2(0.1)& P_2^2(0.2)\end{array}$$

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

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

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

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

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

Compare Legendre Normalizations

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

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

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

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

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

Calculate Spherical Harmonics

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(\theta ,\varphi )=\sqrt{\frac{(2l+1)(l-m)!}{4\pi (l+m)!}}{P}_l^m(\cos \theta )e^{im\varphi },-l\le m\le l.$$

First, create a grid of values to represent all combinations of $0\le \theta \le \pi$ (colatitude angle) and $0\le \varphi \le 2\pi$ (azimuthal angle). Here, the colatitude $$\theta$$ ranges from 0 at the North Pole, to $$\pi /2$$ at the Equator, and to $$\pi$$ at the South Pole.

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

Calculate ${\mathit{P}}_{\mathit{l}}^{\mathit{m}}\left(\cos \theta \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;
if l ~= 0
    Plm = reshape(Plm(m+1,:,:),size(phi));
end

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);
Ylm = C .*Plm .*exp(1i*m*phi);

Convert the spherical coordinates to Cartesian coordinates. Here, $$\pi /2-\theta$$ becomes the latitude angle that ranges from $$\pi /2$$ at the North Pole, to 0 at the Equator, and to $$-\pi /2$$ at the South Pole. Plot the spherical harmonic for ${\mathit{Y}}_3^2$ using both the positive and negative real values.

[Xm,Ym,Zm] = sph2cart(phi, pi/2-theta, abs(real(Ylm)));
surf(Xm,Ym,Zm)
title('$Y_3^2$ spherical harmonic','interpreter','latex')

Input Arguments

n — Degree of Legendre function

positive integer

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)

X — Input values

scalar | vector | matrix | multidimensional array

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(\cos \theta \right)$$.

Example: legendre(2,cos(theta))

Data Types: single | double

normalization — Normalization type

'unnorm' (default) | 'sch' | 'norm'

Normalization type, specified as one of these values.

Value	Result
'unnorm'	Associated Legendre Functions
'sch'	Schmidt Seminormalized Associated Legendre Functions
'norm'	Fully Normalized Associated Legendre Functions

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

Output Arguments

P — Associated Legendre function values

scalar | vector | matrix | multidimensional array

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.

More About

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

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).$$

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!}\frac{d^n}{d{x}^n}{\left(x^2-1\right)}^n.$$

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(3x^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

$$\begin{array}{l}{P}_n\left(x\right)\text{ for }m=0,\\ S_n^m\left(x\right)={\left(-1\right)}^m\sqrt{\frac{2\left(n-m\right)!}{\left(n+m\right)!}}{P}_n^m\left(x\right)\text{ for }m>0.\end{array}$$

Fully Normalized Associated Legendre Functions

The fully normalized associated Legendre functions are normalized such that

$${\displaystyle {\int }_{-1}^1{\left[N_n^m(x)\right]}^{2}dx}=1.$$

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).$$

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 [1] functions $$P_n^m\left(x\right)$$ by

$$P_n^m\left(x\right)=\sqrt{\frac{\left(n+m\right)!}{\left(n-m\right)!}}{Q}_n^m\left(x\right).$$

They are related to the Schmidt form by

$$\begin{array}{l}m=0:S_n^m\left(x\right)=Q_n^0\left(x\right)\\ m>0:S_n^m\left(x\right)={\left(-1\right)}^m\sqrt{2}{Q}_n^m\left(x\right).\end{array}$$

References

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

[2] Jacobs, J. A., Geomagnetism, Academic Press, 1987, Ch.4.

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The legendre function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced before R2006a