API Reference

p = legendre(norm::AbstractLegendreNorm, l::DimOrInd, m::DimOrInd, x)

Computes the associated Legendre polynomials $N_ℓ^m P_ℓ^m(x)$ of degree(s) l and order(s) m at x for the normalization scheme norm.

• If l and m are integers, returns a single value.
• If l is a range 0:lmax and m an integer, returns the vector of values for order m and all degrees 0 ≤ l ≤ lmax.
• If l is a range 0:lmax and m is a range 0:mmax, returns the matrix of values for all degrees 0 ≤ l ≤ lmax and orders 0 ≤ m ≤ mmax.

Note that in both the second and third cases, the ranges must have a first index of 0.

legendre!(norm::AbstractLegendreNorm, Λ, l::Integer, m::Integer, x)

Fills the array Λ with the Legendre polynomial values $N_ℓ^m P_ℓ^m(x)$ up to/of degree(s) l and order(s) m for the normalization scheme norm. Λ must be an array with between 0 and 2 more dimensions than x, with the leading dimensions having the same shape as x.

• If ndims(Λ) == ndims(x), then Λ is filled with the polynomial values at x for degree l and order m.
• If ndims(Λ) == ndims(x) + 1, then l is interpreted as lmax, and Λ filled with polynomial values for all degrees 0 ≤ l ≤ lmax of order m.
• If ndims(Λ) == ndims(x) + 2, then l is interpreted as lmax and m as mmax, and Λ is filled with polynomial values for all degrees 0 ≤ l ≤ lmax and orders 0 ≤ m ≤ min(mmax, l).

N = Nlm([T=Float64], l, m)

Computes the normalization constant

\[ N_\ell^m \equiv \sqrt{\frac{2\ell+1}{4\pi} \frac{(\ell-m)!}{(\ell+m)!}}\]

which defines the Spherical Harmonic normalized functions $\lambda_\ell^m(x)$ in terms of the standard unit normalized $P_\ell^m(x)$

\[ \lambda_\ell^m(x) \equiv N_\ell^m P_\ell^m(x)\]

using numbers of type T.

See also Plm and λlm.

abstract type AbstractLegendreNorm end

Abstract trait supertype for normalization conditions of the associated Legendre functions.

struct LegendreUnitNorm <: AbstractLegendreNorm end

Trait type denoting the unnormalized associated Legendre functions $P_\ell^m(x)$ which solve the colatitude $\theta$ part of Laplace's equation in spherical coordinates where $x=\cos(\theta)$. The degree $\ell=0$, order $m=0$ constant function is normalized to be unity:

\[ P_0^0(x) = 1\]

struct LegendreFourPiNorm <: AbstractLegendreNorm end

Trait type denoting the $4\pi$ (geodesy) normalization of the associated Legendre functions $F_\ell^m(x)$. The orthonormal normalization is defined such that

\[ \int_{-1}^{1} \left[ F_\ell^m(x) \right]^2 \,dx = 2\]

The normalization factor with respect to the standard (unnormalized) Legendre functions $P_\ell^m(x)$ (LegendreUnitNorm) is given by

\[ F_\ell^m(x) \equiv \sqrt{2\pi(2\ell+1) \frac{(\ell-m)!}{(\ell+m)!}} P_\ell^m(x)\]

struct LegendreOrthoNorm <: AbstractLegendreNorm end

Trait type denoting the orthonormal (full) normalization of the associated Legendre functions $O_\ell^m(x)$. The orthonormal normalization is defined such that

\[ \int_{-1}^{1} \left[ O_\ell^m(x) \right]^2 \,dx = 1\]

The normalization factor with respect to the standard (unnormalized) Legendre functions $P_\ell^m(x)$ (LegendreUnitNorm) is given by

\[ O_\ell^m(x) \equiv \sqrt{\frac{2\ell+1}{2} \frac{(\ell-m)!}{(\ell+m)!}} P_\ell^m(x)\]

struct LegendreSphereNorm <: AbstractLegendreNorm end

Trait type denoting the spherical-harmonic normalization of the associated Legendre functions $\lambda_\ell^m(x)$. The spherical-harmonic normalization is defined such that

\[ \int_{-1}^{1} \left[ \lambda_\ell^m(x) \right]^2 \,dx = \frac{1}{2\pi}\]

The normalization factor with respect to the standard (unnormalized) Legendre functions $P_\ell^m(x)$ (LegendreUnitNorm) is given by

\[ \lambda_\ell^m(x) \equiv \sqrt{\frac{2\ell+1}{4\pi} \frac{(\ell-m)!}{(\ell+m)!}} P_\ell^m(x)\]

struct LegendreNormCoeff{N<:AbstractLegendreNorm,T<:Real} <: AbstractLegendreNorm

Precomputed recursion relation coefficients for the normalization N and value type T.

Example

julia> LegendreNormCoeff{LegendreSphereNorm,Float64}(1)
LegendreNormCoeff{LegendreSphereNorm,Float64} for lmax = 1, mmax = 1 with coefficients:
    μ: [0.0, 1.22474]
    ν: [1.73205, 2.23607]
    α: [0.0 0.0; 1.73205 0.0]
    β: [0.0 0.0; -0.0 0.0]

p = Plm(l, m, x)

Computes the associated Legendre polynomials using unit normalization; equivalent to p = legendre(LegendreUnitNorm(), l, m, x).

λ = λlm(l, m, x)

Computes the associated Legendre polynomials using spherical-harmonic normalization; equivalent to λ = legendre(LegendreSphereNorm(), l, m, x).

Plm!(P, l, m, x)

Fills the array P with the unit-normalized associated Legendre polynomial values $P_ℓ^m(x)$; equivalent to legendre!(LegendreUnitNorm(), P, l, m, x).

λlm!(Λ, l, m, x)

Fills the array Λ with the spherical-harmonic normalized associated Legendre polynomial values $λ_ℓ^m(x)$; equivalent to legendre!(LegendreSphereNorm(), P, l, m, x).

LegendreUnitCoeff{T}

Precomputed recursion relation coefficients for the standard unit normalization. Alias for LegendreNormCoeff{LegendreUnitNorm,T}.

LegendreFourPiCoeff{T}

Table type of precomputed recursion relation coefficients for the $4\pi$ spherical harmonic normalization. Alias for LegendreNormCoeff{LegendreFourPiNorm,T}.

LegendreOrthoCoeff{T}

Table type of precomputed recursion relation coefficients for the orthonormal normalization. Alias for LegendreNormCoeff{LegendreOrthoNorm,T}.

LegendreSphereCoeff{T}

Table type of precomputed recursion relation coefficients for the spherical harmonic normalization. Alias for LegendreNormCoeff{LegendreSphereNorm,T}.

initcond(::N, ::Type{T}) where {N<:AbstractLegendreNorm, T}

Returns the initial condition $P_0^0(x)$ for the associated Legendre recursions based on the normalization choice N for numeric type T.

coeff_μ(norm::N, ::Type{T}, l::Integer) where {N<:AbstractLegendreNorm, T}

Returns the coefficient $\mu_\ell$ for the single-term recursion relation

\[ P_\ell^\ell(x) = -\mu_\ell \sqrt{1-x^2} P_{\ell-1}^{\ell-1}(x)\]

where $\mu_\ell$ is appropriate for the choice of normalization N.

coeff_ν(norm::N, ::Type{T}, l::Integer) where {N<:AbstractLegendreNorm, T}

Returns the coefficient $\nu_\ell$ for the single-term recursion relation

\[ P_\ell^{\ell-1}(x) = \nu_\ell x P_{\ell-1}^{\ell-1}(x)\]

where $\nu_\ell$ is appropriate for the choice of normalization N.

coeff_α(norm::N, ::Type{T}, l::Integer, m::Integer) where {N<:AbstractLegendreNorm, T}

Returns the coefficient $\alpha_\ell^m$ for the two-term recursion relation

\[ P_\ell^m(x) = \alpha_\ell^m x P_{\ell-1}^m(x) - \beta_\ell^m P_{\ell-2}^m(x)\]

where $\alpha_\ell^m$ is appropriate for the choice of normalization N.

coeff_β(norm::N, ::Type{T}, l::Integer, m::Integer) where {N<:AbstractLegendreNorm, T}

Returns the coefficient $\beta_\ell^m$ for the two-term recursion relation

\[ P_\ell^m(x) = \alpha_\ell^m x P_{\ell-1}^m(x) - \beta_\ell^m P_{\ell-2}^m(x)\]

where $\beta_\ell^m$ is appropriate for the choice of normalization N.

boundscheck_hook(norm::AbstractLegendreNorm, lmax, mmax)

A bounds-checking hook executed at the beginning of each legendre! call to permit a normalization norm to validate that the given maximum $(\ell,m)$ will be within the ability to satisfy. The default case always returns nothing. A custom normalization should throw an error if lmax or mmax is out of bounds or return nothing otherwise.

For example, the precomputed coefficients of LegendreNormCoeff are limited to a given domain at time of construction and cannot be used to calculate terms to arbitrary orders/degrees.