This package is part of the SatelliteToolbox.jl ecosystem.
SatelliteToolboxLegendre.jl
This package contains function to compute the Legendre associated functions and its derivatives for the models in the SatelliteToolbox.jl ecosystem.
Installation
julia> using Pkg
julia> Pkg.add("SatelliteToolboxLegendre")
Usage
Legendre Associated Functions
This package exports two methods to compute the Legendre associated functions: legendre
and legendre!
.
legendre(N, ϕ::T, n_max::Integer, m_max::Integer = -1; ph_term::Bool = false) where T<:Number -> Matrix{float(T)}
Compute the associated Legendre function n_max
and the maximum order is m_max
. Notice that if
m_max
is higher than n_max
or negative (default), it is set to n_max
.
The parameter N
selects the normalization. The following values are valid:
Val(:full)
: Compute the fully normalized associated Legendre function.Val(:schmidt)
: Compute the Schmidt quasi-normalized associated Legendre function.Val(:unnormalized)
: Compute the unnormalized associated Legendre function.
This function has the following keywords:
-
ph_term::Bool
: Iftrue
, the Condon-Shortley phase term$(-1)^m$ will be included. (Default =false
)
It returns a Matrix{float(T)}
with the Legendre associated functions
julia> legendre(Val(:unnormalized), 0.45, 4)
5×5 Matrix{Float64}:
1.0 0.0 0.0 0.0 0.0
0.900447 0.434966 0.0 0.0 0.0
0.716207 1.17499 0.567585 0.0 0.0
0.474547 1.99259 2.5554 1.2344 0.0
0.210627 2.61987 6.63455 7.78058 3.75845
julia> legendre(Val(:schmidt), 0.45, 4, 3; ph_term = true)
5×4 Matrix{Float64}:
1.0 0.0 0.0 0.0
0.900447 -0.434966 0.0 0.0
0.716207 -0.678381 0.163848 0.0
0.474547 -0.813473 0.329901 -0.0650586
0.210627 -0.828476 0.49451 -0.154993
julia> legendre(Val(:full), 0.45, 4, 1)
5×2 Matrix{Float64}:
1.0 0.0
1.55962 0.753382
1.60149 1.51691
1.25553 2.15225
0.631881 2.48543
legendre!(N, P::AbstractMatrix, ϕ::Number, n_max::Integer = -1, m_max::Integer = -1; kwargs...) -> Nothing
Compute the associated Legendre function n_max
and m_max
. If
they are negative (default), the dimensions of matrix P
will be used:
maximum degree -> number of rows - 1
maximum order -> number of columns - 1
The result will be stored at matrix P
. Hence, this function can be used to reduce
allocations.
The parameter N
selects the normalization. The following values are valid:
Val(:full)
: Compute the fully normalized associated Legendre function.Val(:schmidt)
: Compute the Schmidt quasi-normalized associated Legendre function.Val(:unnormalized)
: Compute the unnormalized associated Legendre function.
This function has the following keywords:
-
ph_term::Bool
: Iftrue
, the Condon-Shortley phase term$(-1)^m$ will be included. (Default =false
)
Derivative of the Legendre Associated Functions
This package exports two methods to compute the derivative of the Legendre associated
functions: dlegendre
and dlegendre!
.
dlegendre(N, ϕ::T, n_max::Integer, m_max::Integer = -1; kwargs...) where T<:Number -> Matrix{float(T)}, Matrix{float(T)}
Compute the first-order derivative of the associated Legendre function
The maximum degree that will be computed is n_max
and the maximum order is m_max
. Notice
that if m_max
is higher than n_max
or negative (default), it is set to n_max
.
The parameter N
selects the normalization. The following values are valid:
Val(:full)
: Compute the fully normalized associated Legendre function.Val(:schmidt)
: Compute the Schmidt quasi-normalized associated Legendre function.Val(:unnormalized)
: Compute the unnormalized associated Legendre function.
This function has the following keywords:
-
ph_term::Bool
: Iftrue
, the Condon-Shortley phase term$(-1)^m$ will be included. (Default =false
)
It returns the following objects:
-
Matrix{float(T)}
: A matrix with the first-order derivative of the Legendre associated functions$P_{n,m}\left[\cos(\phi)\right]$ . -
Matrix{float(T)}
: A matrix with the Legendre associated functions$P_{n,m}\left[\cos(\phi)\right]$ `.
julia> dP, P = dlegendre(Val(:unnormalized), 0.45, 4)
julia> dP
5×5 Matrix{Float64}:
0.0 0.0 0.0 0.0 0.0
-0.434966 0.900447 0.0 0.0 0.0
-1.17499 1.86483 2.34998 0.0 0.0
-1.99259 1.56958 9.34577 7.6662 0.0
-2.61987 -1.21101 19.6885 44.5626 31.1223
julia> P
5×5 Matrix{Float64}:
1.0 0.0 0.0 0.0 0.0
0.900447 0.434966 0.0 0.0 0.0
0.716207 1.17499 0.567585 0.0 0.0
0.474547 1.99259 2.5554 1.2344 0.0
0.210627 2.61987 6.63455 7.78058 3.75845
julia> dP, P = dlegendre(Val(:schmidt), 0.45, 4, 3; ph_term = true)
julia> dP
5×4 Matrix{Float64}:
0.0 0.0 0.0 0.0
-0.434966 -0.900447 0.0 0.0
-1.17499 -1.07666 0.678381 0.0
-1.99259 -0.640778 1.20653 -0.404044
-2.61987 0.382954 1.4675 -0.887709
julia> P
5×5 Matrix{Float64}:
1.0 0.0 0.0 0.0 0.0
0.900447 -0.434966 0.0 0.0 0.0
0.716207 -0.678381 0.163848 0.0 0.0
0.474547 -0.813473 0.329901 -0.0650586 0.0
0.210627 -0.828476 0.49451 -0.154993 0.0264706
julia> dP, P = dlegendre(Val(:full), 0.45, 4, 1)
julia> dP
5×2 Matrix{Float64}:
0.0 0.0
-0.753382 1.55962
-2.62736 2.40749
-5.27191 1.69534
-7.85961 -1.14886
julia> P
5×3 Matrix{Float64}:
1.0 0.0 0.0
1.55962 0.753382 0.0
1.60149 1.51691 0.366375
1.25553 2.15225 0.872836
0.631881 2.48543 1.48353
dlegendre!(dP::AbstractMatrix, ϕ::Number, P::AbstractMatrix, n_max::Integer = -1, m_max::Integer = -1; kwargs...) -> Nothing
Compute the first-order derivative of the associated Legendre function
The maximum degree and order that will be computed are given by the parameters n_max
and
m_max
. If they are negative (default), the dimensions of matrix dP
will be used:
maximum degree -> number of rows - 1
maximum order -> number of columns - 1
The derivatives will be stored in the matrix dP
. Hence, this function can be used to reduce
allocations.
The parameter N
selects the normalization. The following values are valid:
Val(:full)
: Compute the fully normalized associated Legendre function.Val(:schmidt)
: Compute the Schmidt quasi-normalized associated Legendre function.Val(:unnormalized)
: Compute the unnormalized associated Legendre function.
This algorithm needs the matrix P
with the values of the associated Legendre function
using the same normalization N
, which can be computed using the function legendre
.
Warning The user is responsible to pass a matrix
P
with the correct values. For example, ifph_term
istrue
,P
must also be computed withph_term
set totrue
.
This function has the following keywords:
-
ph_term::Bool
: Iftrue
, the Condon-Shortley phase term$(-1)^m$ will be included. (Default =false
)
Normalizations
Full normalization
This algorithm was based on [1]. Our definition of fully normalized associated Legendre function can be seen in [2, p. 546]. The conversion is obtained by:
where
where
Schmidt quasi-normalization
This algorithm was based on [3, 4]. The conversion is obtained by:
where
where
References
-
[1] Holmes, S. A. and W. E. Featherstone, 2002. A unified approach to the Clenshaw summation and the recursive computation of very high degree and order normalised associated Legendre functions. Journal of Geodesy, 76(5), pp. 279-299. For more info.: http://mitgcm.org/~mlosch/geoidcookbook/node11.html
-
[2] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. Microcosm Press, Hawthorn, CA, USA.
-
[3] Schmidt, A (1917). Erdmagnetismus, Enzykl. Math. Wiss., 6, pp. 265–396.
-
[4] Winch, D. E., Ivers, D. J., Turner, J. P. R., Stening R. J (2005). Geomagnetism and Schmidt quasi-normalization. Geophysical Journal International, 160(2), pp. 487-504.