Library

abstract type AbstractIcgemCoefficient{T<:Number}

Abstract type of all spherical harmonics coefficients stored in an ICGEM file.

struct IcgemFile{T<:Number, NT<:Val, Coeff<:AbstractIcgemCoefficient{T}} <: GravityModels.AbstractGravityModel{T, NT}

Store the information of a parsed ICGEM file.

Fields

• product_type::Symbol: Product type of the model.
• model_name::String: Name of the gravity model.
• gravity_constant::T: Gravity constant [m³/s²] of the central body.
• radius::T: Reference radius [m] of the model.
• max_degree::Int: Maximum degree available in the model.
• errors::Symbol: Type of the errors described in the file (:no, :calibrated, :calibrated_and_formal, or :formal).
• tide_system::Symbol: Tide system of the model, or :unknown if the file does not specify it.
• norm::NT: Normalization of the model coefficients wrapped in a Val.
• data::LowerTriangularStorage{RowMajor, Coeff}: Spherical harmonics coefficients of the model, in which the element [n + 1, m + 1] is the coefficient of degree n and order m.

struct IcgemGfcCoefficient{T<:Number} <: AbstractIcgemCoefficient{T}

Store a constant (gfc) spherical harmonics coefficient of an ICGEM file.

Fields

• clm::T: Cosine coefficient Clm [-].
• slm::T: Sine coefficient Slm [-].

struct IcgemGfctCoefficient{T<:Number} <: AbstractIcgemCoefficient{T}

Store a time-variable (gfct) spherical harmonics coefficient of an ICGEM file.

Fields

• clm::T: Cosine coefficient Clm [-] at the epoch time.
• slm::T: Sine coefficient Slm [-] at the epoch time.
• time::T: Epoch of the coefficients, expressed as the number of elapsed seconds [s] since the J2000.0 epoch (2000-01-01T12:00:00).
• is_time_varying::Bool: Indicate whether the coefficient is time-varying. If false, the other time-related fields are ignored and the coefficient is treated as a regular IcgemGfcCoefficient. This is useful to avoid unnecessary computations, leading to a huge performance boost.
• has_trend::Bool: Indicate whether the coefficient has a linear trend.
• trend_clm::T: Linear trend of Clm [year⁻¹].
• trend_slm::T: Linear trend of Slm [year⁻¹].
• asin_coefficients::Vector{NTuple{3, T}}: Sine periodic terms, in which each element contains the amplitude for Clm [-], the amplitude for Slm [-], and the period [year].
• acos_coefficients::Vector{NTuple{3, T}}: Cosine periodic terms, in which each element contains the amplitude for Clm [-], the amplitude for Slm [-], and the period [year].

IcgemGfctCoefficient(c::IcgemGfcCoefficient{T}) -> IcgemGfctCoefficient{T}

Create an IcgemGfctCoefficient from the constant coefficient c, keeping Clm and Slm and marking the result as not time-varying.

GravityModels.load(::Type{IcgemFile}, filename::AbstractString, T::Type = Float64) -> IcgemFile

Load the ICGEM file filename and return an IcgemFile object with its parsed data. T is converted to float to obtain the type of the model coefficients. The function throws an ErrorException if the file does not conform to the ICGEM format.

See also: parse_icgem, fetch_icgem_file

_compute_icgem_coefficient(coefficient::IcgemGfcCoefficient{T}, t::Number) -> T, T

Return the constant coefficients Clm [-] and Slm [-] stored in coefficient. The time t [s] is unused since the coefficient is constant.

_compute_icgem_coefficient(coefficient::IcgemGfctCoefficient{T}, t::Number) -> RT, RT

Compute the coefficients Clm [-] and Slm [-] of the time-variable coefficient at the instant t, expressed as the number of elapsed seconds [s] from the J2000.0 epoch (2000-01-01T12:00:00).

The coefficients are obtained by adding the linear trend and the sine and cosine periodic terms to the values at the coefficient epoch, as described in the ICGEM format documentation [1]. The elapsed time from the epoch is converted to Julian years (365.25 days).

The return type RT is float(promote_type(T, typeof(t))).

References

• [1] Barthelmes, F., Förste, C (2011). The ICGEM-format. GFZ Potsdam, Department 1 "Geodesy and Remote Sensing".

_parse_asin_acos_data_line(Tf, tokens, current_line) -> Union{Nothing, Tuple}

Parse the asin or acos data line in tokens using the type Tf for the floating point fields. If any field cannot be parsed, log a warning with the current_line number and return nothing.

Arguments

• Tf::Type: Type used to parse the floating point fields.
• tokens::AbstractVector{<:AbstractString}: Tokens of the data line.
• current_line::Int: Number of the line being parsed, used in the warning messages.

Returns

• Int: Degree.
• Int: Order.
• Tf: Amplitude of the periodic term for Clm [-].
• Tf: Amplitude of the periodic term for Slm [-].
• Tf: Period of the term [year].

_parse_degree_and_order(tokens, current_line) -> Union{Nothing, Tuple{Int, Int}}

Parse the degree in tokens[2] and the order in tokens[3]. If any of them cannot be parsed, log a warning with the current_line number and return nothing.

Arguments

• tokens::AbstractVector{<:AbstractString}: Tokens of the data line.
• current_line::Int: Number of the line being parsed, used in the warning messages.

Returns

• Int: Degree.
• Int: Order.

_parse_gfc_data_line(Tf, tokens, current_line) -> Union{Nothing, Tuple}

Parse the gfc data line in tokens using the type Tf for the floating point fields. If any field cannot be parsed, log a warning with the current_line number and return nothing.

Arguments

• Tf::Type: Type used to parse the floating point fields.
• tokens::AbstractVector{<:AbstractString}: Tokens of the data line.
• current_line::Int: Number of the line being parsed, used in the warning messages.

Returns

• Int: Degree.
• Int: Order.
• Tf: Coefficient Clm [-].
• Tf: Coefficient Slm [-].

_parse_gfct_data_line(Tf, tokens, current_line) -> Union{Nothing, Tuple}

Parse the gfct data line in tokens using the type Tf for the floating point fields. If any field cannot be parsed, log a warning with the current_line number and return nothing. The function throws an ArgumentError if the epoch in the last token is not a valid date in the yyyymmdd format.

Arguments

• Tf::Type: Type used to parse the floating point fields.
• tokens::AbstractVector{<:AbstractString}: Tokens of the data line.
• current_line::Int: Number of the line being parsed, used in the warning messages.

Returns

• Int: Degree.
• Int: Order.
• Tf: Coefficient Clm [-] at the epoch.
• Tf: Coefficient Slm [-] at the epoch.
• Float64: Epoch (t₀) of the coefficients, expressed as the number of elapsed seconds [s] since the J2000.0 epoch (2000-01-01T12:00:00).

_parse_icgem_float(::Type{T}, input::AbstractString) -> Union{Nothing, T}

Parse the input to the float type T, substituting all Ds and ds by e so that numbers in FORTRAN format can be converted. If input cannot be parsed to T, return nothing.

_parse_trnd_data_line(Tf, tokens, current_line) -> Union{Nothing, Tuple}

Parse the trnd data line in tokens using the type Tf for the floating point fields. If any field cannot be parsed, log a warning with the current_line number and return nothing.

Arguments

• Tf::Type: Type used to parse the floating point fields.
• tokens::AbstractVector{<:AbstractString}: Tokens of the data line.
• current_line::Int: Number of the line being parsed, used in the warning messages.

Returns

• Int: Degree.
• Int: Order.
• Tf: Linear trend of Clm [year⁻¹].
• Tf: Linear trend of Slm [year⁻¹].

_print_asin_acos_vectors(io::IO, v::Vector{NTuple{3, T}}) -> Nothing

Print to io the periodic terms in v, in which each element contains the amplitude for Clm [-], the amplitude for Slm [-], and the period [year].

fetch_icgem_file(url::AbstractString; kwargs...) -> String
fetch_icgem_file(model::Symbol; kwargs...) -> String

Fetch an ICGEM file from the url and return its file path to be parsed with the function GravityModels.load. If the file already exists, it will not be re-downloaded unless the keyword force = true is passed.

A symbol can be passed instead of the URL to fetch pre-configured gravity field models. The supported values are:

• :EGM96: Earth Gravitational Model from 1996.
• :EGM2008: Earth Gravitational Model from 2008.
• :JGM2: Joint Gravity Model 2.
• :JGM3: Joint Gravity Model 3.

The function throws an ArgumentError if model is not one of the supported symbols or if the file name cannot be obtained from the url.

Keywords

• force::Bool: If true, the file is downloaded again even if it already exists in the local cache. (Default: false)

Examples

julia> fetch_icgem_file(:EGM96)
[ Info: Downloading the ICGEM file 'EGM96.gfc' from 'https://icgem.gfz-potsdam.de/getmodel/gfc/971b0a3b49a497910aad23cd85e066d4cd9af0aeafe7ce6301a696bed8570be3/EGM96.gfc'...
"/Users/ronan.arraes/.julia/scratchspaces/bd9e9728-6f7b-4d28-9e50-c765cb1b7c8c/icgem/EGM96.gfc"

julia> fetch_icgem_file(:EGM96)
"/Users/ronan.arraes/.julia/scratchspaces/bd9e9728-6f7b-4d28-9e50-c765cb1b7c8c/icgem/EGM96.gfc"

icgem_coefficients(model::IcgemFile, degree::Int, order::Int, time) -> RT, RT

Compute the coefficients Clm and Slm [-] of the ICGEM model for the specified degree and order at the instant time, expressed as a DateTime object or the number of elapsed seconds [s] from the J2000.0 epoch (2000-01-01T12:00:00).

The function throws an ArgumentError if order is higher than degree or if degree is higher than the maximum degree available in model.

Arguments

• model::IcgemFile{T}: ICGEM model.
• degree::Int: Degree of the coefficients.
• order::Int: Order of the coefficients.
• time::Union{Number, DateTime}: Time at which the coefficients are computed, expressed as a DateTime object or the number of elapsed seconds [s] from the J2000.0 epoch.

Returns

• RT: Coefficient Clm [-].
• RT: Coefficient Slm [-].

The return type RT is T for models with only constant coefficients, or float(promote_type(T, typeof(time))) for models with time-variable coefficients.

parse_icgem(filename::AbstractString, T::Type = Float64) -> IcgemFile

Parse the ICGEM file filename using the data type T and return an IcgemFile object with the parsed data.

This function supports ICGEM gravity model files for Earth and other celestial bodies (Moon, planets, etc.). The parser automatically detects whether the file uses earth_gravity_constant (for Earth models) or gravity_constant (for non-Earth models).

The function throws an ErrorException if the file does not conform to the ICGEM format, and logs a warning for each invalid data line, which is skipped.

References

• [1] Barthelmes, F., Förste, C (2011). The ICGEM-format. GFZ Potsdam, Department 1 "Geodesy and Remote Sensing".

abstract type AbstractGravityModel{T<:Number, NT<:Val}

Abstract data type of all gravity models.

_gravitational_field_derivative_kernel(
    model::AbstractGravityModel,
    r::AbstractVector,
    time::Number,
    n_max::Int,
    m_max::Int,
    n_max_P::Int,
    m_max_P::Int,
    n_max_dP::Int,
    m_max_dP::Int,
    P::AbstractMatrix,
    dP::AbstractMatrix
) -> NTuple{3, RT}

Compute the derivative of the gravitational field of model with respect to the spherical coordinates at the position r [m], represented in the body-fixed frame (ITRF for Earth), and instant time, expressed as the number of elapsed seconds [s] from the J2000.0 epoch (2000-01-01T12:00:00), using the spherical harmonics up to degree n_max and order m_max.

This function is the kernel of gravitational_field_derivative, called through a function barrier so the hot loop is compiled with concrete types for P and dP. It assumes all inputs were already processed: n_max and m_max must be valid for model, and P and dP must have at least n_max_P + 1 × m_max_P + 1 and n_max_dP + 1 × m_max_dP + 1 elements, respectively, which are overwritten with the associated Legendre function values and their derivatives.

Returns

• RT: Derivative of the gravitational field w.r.t. the radius (∂U/∂r) [m/s²].
• RT: Derivative of the gravitational field w.r.t. the geocentric latitude (∂U/∂ϕ) [m²/s²].
• RT: Derivative of the gravitational field w.r.t. the longitude (∂U/∂λ) [m²/s²].

_gravitational_potential_kernel(
    model::AbstractGravityModel,
    r::AbstractVector,
    time::Number,
    n_max::Int,
    m_max::Int,
    P::AbstractMatrix
) -> RT

Compute the gravitational potential [m²/s²] of model at the position r [m], represented in the body-fixed frame (ITRF for Earth), and instant time, expressed as the number of elapsed seconds [s] from the J2000.0 epoch (2000-01-01T12:00:00), using the spherical harmonics up to degree n_max and order m_max.

This function is the kernel of gravitational_potential, called through a function barrier so the hot loop is compiled with a concrete type for P. It assumes all inputs were already processed: n_max and m_max must be valid for model, and P must have at least n_max + 1 × m_max + 1 elements, which are overwritten with the associated Legendre function values.

coefficient_norm(model::AbstractGravityModel) -> Symbol

Return the normalization we must use in the spherical harmonics when computing the Legendre associated functions for the gravity model. The accepted values are:

• :full: Use full normalization.
• :schmidt: Use Schmidt quasi-normalization.
• :unnormalized: Do not perform normalization.

coefficients(model::AbstractGravityModel, degree::Int, order::Int[, time]) -> T, T

Return the Clm and Slm coefficients [-] of the gravity model for the specified degree, order, and time. If the latter argument is omitted, the J2000.0 epoch (2000-01-01T12:00:00) is used.

Arguments

• model::AbstractGravityModel{T, NT}: Gravity model.
• degree::Int: Degree of the coefficients.
• order::Int: Order of the coefficients.
• time::Union{Number, DateTime}: Time at which the coefficients are computed, expressed as a DateTime object or the number of elapsed seconds [s] from the J2000.0 epoch. (Default: J2000.0 epoch)

Returns

• T: Coefficient Clm [-] for the specified degree, order, and time.
• T: Coefficient Slm [-] for the specified degree, order, and time.

gravitational_acceleration(model::AbstractGravityModel, r::AbstractVector[, time]; kwargs...) -> SVector{3, RT}

Compute the gravitational acceleration [m/s²] represented in the body-fixed frame (ITRF for Earth) using the model in the position r [m], also represented in the body-fixed frame, at instant time. If the latter argument is omitted, the J2000.0 epoch (2000-01-01T12:00:00) is used.

The return element type RT is obtained by promoting the type of the model coefficients, the element type of r, and the type of time.

See also: gravity_acceleration

Arguments

• model::AbstractGravityModel{T, NT}: Gravity model.
• r::AbstractVector: Position [m] in the body-fixed frame (ITRF for Earth) at which the acceleration is computed.
• time::Union{Number, DateTime}: Time at which the acceleration is computed, expressed as a DateTime object or the number of elapsed seconds [s] from the J2000.0 epoch. (Default: J2000.0 epoch)

Keywords

• max_degree::Int: Maximum degree used in the spherical harmonics when computing the gravitational field derivative. If it is higher than the available number of coefficients in the model, it will be clamped. If it is lower than 0, it will be set to the maximum degree available. (Default: -1)
• max_order::Int: Maximum order used in the spherical harmonics when computing the gravitational field derivative. If it is higher than max_degree, it will be clamped. If it is lower than 0, it will be set to the same value as max_degree. (Default: -1)
• P::Union{Nothing, AbstractMatrix}: An optional matrix that must contain at least max_degree + 1 × max_degree + 1 real numbers that will be used to store the Legendre coefficients, reducing the allocations. If it is nothing, the matrix will be created when calling the function. (Default: nothing)
• dP::Union{Nothing, AbstractMatrix}: An optional matrix that must contain at least max_degree + 1 × max_degree + 1 real numbers that will be used to store the Legendre derivative coefficients, reducing the allocations. If it is nothing, the matrix will be created when calling the function. (Default: nothing)

Returns

• SVector{3, RT}: Gravitational acceleration [m/s²] represented in the body-fixed frame (ITRF for Earth).

References

• [1] Barthelmes, F (2013). Definition of Functions of the Geopotential and Their Calculation from Spherical Harmonic Models. Scientific Technical Report STR09/02. GeoForschungsZentrum (GFZ), p. 22.

gravitational_field_derivative(model::AbstractGravityModel, r::AbstractVector[, time]; kwargs...) -> NTuple{3, RT}

Compute the gravitational field derivative with respect to the spherical coordinates (∂U/∂r, ∂U/∂ϕ, ∂U/∂λ) using the model in the position r [m], represented in the body-fixed frame (ITRF for Earth), at instant time. If the latter argument is omitted, the J2000.0 epoch (2000-01-01T12:00:00) is used.

The return element type RT is obtained by promoting the type of the model coefficients, the element type of r, and the type of time.

Arguments

• model::AbstractGravityModel{T, NT}: Gravity model.
• r::AbstractVector: Position [m] in the body-fixed frame (ITRF for Earth) at which the derivative is computed.
• time::Union{Number, DateTime}: Time at which the derivative is computed, expressed as a DateTime object or the number of elapsed seconds [s] from the J2000.0 epoch. (Default: J2000.0 epoch)

Keywords

• max_degree::Int: Maximum degree used in the spherical harmonics when computing the gravitational field derivative. If it is higher than the available number of coefficients in the model, it will be clamped. If it is lower than 0, it will be set to the maximum degree available. (Default: -1)
• max_order::Int: Maximum order used in the spherical harmonics when computing the gravitational field derivative. If it is higher than max_degree, it will be clamped. If it is lower than 0, it will be set to the same value as max_degree. (Default: -1)
• P::Union{Nothing, AbstractMatrix}: An optional matrix that must contain at least max_degree + 1 × max_degree + 1 real numbers that will be used to store the Legendre coefficients, reducing the allocations. If it is nothing, the matrix will be created when calling the function. (Default: nothing)
• dP::Union{Nothing, AbstractMatrix}: An optional matrix that must contain at least max_degree + 1 × max_degree + 1 real numbers that will be used to store the Legendre derivative coefficients, reducing the allocations. If it is nothing, the matrix will be created when calling the function. (Default: nothing)

Returns

• RT: Derivative of the gravitational field w.r.t. the radius (∂U/∂r) [m/s²].
• RT: Derivative of the gravitational field w.r.t. the geocentric latitude (∂U/∂ϕ) [m²/s²].
• RT: Derivative of the gravitational field w.r.t. the longitude (∂U/∂λ) [m²/s²].

gravitational_potential(model::AbstractGravityModel, r::AbstractVector[, time]; kwargs...) -> RT

Compute the gravitational potential U [m²/s²] using the model in the position r [m], represented in the body-fixed frame (ITRF for Earth), at instant time. If the latter argument is omitted, the J2000.0 epoch (2000-01-01T12:00:00) is used.

The return type RT is obtained by promoting the type of the model coefficients, the element type of r, and the type of time.

Arguments

• model::AbstractGravityModel{T, NT}: Gravity model.
• r::AbstractVector: Position [m] in the body-fixed frame (ITRF for Earth) at which the potential is computed.
• time::Union{Number, DateTime}: Time at which the potential is computed, expressed as a DateTime object or the number of elapsed seconds [s] from the J2000.0 epoch. (Default: J2000.0 epoch)

Keywords

• max_degree::Int: Maximum degree used in the spherical harmonics when computing the gravitational potential. If it is higher than the available number of coefficients in the model, it will be clamped. If it is lower than 0, it will be set to the maximum degree available. (Default: -1)
• max_order::Int: Maximum order used in the spherical harmonics when computing the gravitational potential. If it is higher than max_degree, it will be clamped. If it is lower than 0, it will be set to the same value as max_degree. (Default: -1)
• P::Union{Nothing, AbstractMatrix}: An optional matrix that must contain at least max_degree + 1 × max_degree + 1 real numbers that will be used to store the Legendre coefficients, reducing the allocations. If it is nothing, the matrix will be created when calling the function. (Default: nothing)

References

• [1] Barthelmes, F (2013). Definition of Functions of the Geopotential and Their Calculation from Spherical Harmonic Models. Scientific Technical Report STR09/02. GeoForschungsZentrum (GFZ), p. 19.

gravity_acceleration(model::AbstractGravityModel, r::AbstractVector[, time]; kwargs...) -> SVector{3, RT}

Compute the gravity acceleration [m/s²] represented in the body-fixed frame (ITRF for Earth) using the model in the position r [m], also represented in the body-fixed frame, at instant time. If the latter argument is omitted, the J2000.0 epoch (2000-01-01T12:00:00) is used.

The return element type RT is obtained by promoting the type of the model coefficients, the element type of r, and the type of time.

See also: gravitational_acceleration

Arguments

• model::AbstractGravityModel{T, NT}: Gravity model.
• r::AbstractVector: Position [m] in the body-fixed frame (ITRF for Earth) at which the acceleration is computed.
• time::Union{Number, DateTime}: Time at which the acceleration is computed, expressed as a DateTime object or the number of elapsed seconds [s] from the J2000.0 epoch. (Default: J2000.0 epoch)

Keywords

• max_degree::Int: Maximum degree used in the spherical harmonics when computing the gravitational field derivative. If it is higher than the available number of coefficients in the model, it will be clamped. If it is lower than 0, it will be set to the maximum degree available. (Default: -1)
• max_order::Int: Maximum order used in the spherical harmonics when computing the gravitational field derivative. If it is higher than max_degree, it will be clamped. If it is lower than 0, it will be set to the same value as max_degree. (Default: -1)
• P::Union{Nothing, AbstractMatrix}: An optional matrix that must contain at least max_degree + 1 × max_degree + 1 real numbers that will be used to store the Legendre coefficients, reducing the allocations. If it is nothing, the matrix will be created when calling the function. (Default: nothing)
• dP::Union{Nothing, AbstractMatrix}: An optional matrix that must contain at least max_degree + 1 × max_degree + 1 real numbers that will be used to store the Legendre derivative coefficients, reducing the allocations. If it is nothing, the matrix will be created when calling the function. (Default: nothing)
• ω::Number: Rotation rate of the body [rad/s]. For non-Earth bodies, provide the appropriate rotation rate for the celestial body. (Default: EARTH_ANGULAR_SPEED)

Returns

• SVector{3, RT}: Gravity acceleration [m/s²] represented in the body-fixed frame (ITRF for Earth).

References

• [1] Barthelmes, F (2013). Definition of Functions of the Geopotential and Their Calculation from Spherical Harmonic Models. Scientific Technical Report STR09/02. GeoForschungsZentrum (GFZ), pp. 22-23.

gravity_constant(model::AbstractGravityModel{T, NT}) -> T

Return the gravity constant [m³/s²] of the gravity model.

load(::Type{T}, args...; kwargs...) -> T

Load a gravity model of type T using the arguments args... and keywords kwargs....

maximum_degree(model::AbstractGravityModel) -> Int

Return the maximum degree of the gravity model.

radius(model::AbstractGravityModel{T, NT}) -> T

Return the reference radius [m] of the gravity model.