Library

struct IcgemFile{T <: Number, N <: Val} <: GravityModels.AbstractGravityModel{T}

Store the information of a parsed ICGEM file.

The coefficients are stored in the field data. The time-variable coefficients are stored in the field time_variable_coefficients, sorted by degree, order, and epoch, and the field time_variable_index maps the degree and order to the index of the first object in that vector related to them, or 0 if the coefficient is constant. This index is defined only up to the degree max_time_variable_degree.

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.
• angular_speed::T: Angular speed [rad/s] of the central body, used to compute the centrifugal acceleration. It is not defined in the ICGEM file and must be provided when the model is loaded.
• 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::N: Normalization of the model coefficients wrapped in a Val, as returned by GravityModels.coefficient_norm: Val(:full) for fully normalized coefficients or Val(:unnormalized) for unnormalized ones.
• data::LowerTriangularStorage{RowMajor, IcgemGfcCoefficient{T}}: Spherical harmonics coefficients of the model, in which the element [n + 1, m + 1] is the coefficient of degree n and order m. For time-variable coefficients, it contains the values at the epoch of the first validity interval.
• max_time_variable_degree::Int: Maximum degree of the time-variable coefficients, or -1 if the model has only constant coefficients.
• time_variable_index::LowerTriangularStorage{RowMajor, Int32}: Index in which the element [n + 1, m + 1] is the position of the first time-variable coefficient of degree n and order m in time_variable_coefficients, or 0 if the coefficient is constant. It is defined only up to the degree max_time_variable_degree.
• time_variable_coefficients::Vector{IcgemTimeVariableCoefficient{T}}: Time-variable coefficients of the model sorted by degree, order, and epoch.

struct IcgemGfcCoefficient{T <: Number}

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

Fields

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

struct IcgemParseError <: Exception

Exception thrown when an ICGEM file does not conform to the ICGEM format.

Fields

• message::String: Description of the problem found in the file.
• line::Int: Number of the line in which the problem was found, or 0 if the problem is not related to a specific line.

IcgemParseError(message::String) -> IcgemParseError

Create an IcgemParseError with the message that is not related to a specific line of the file.

struct IcgemPeriodicTerm{T <: Number}

Store a periodic term of a time-variable spherical harmonics coefficient of an ICGEM file. The sine (asin) and cosine (acos) terms with the same period are stored together.

Fields

• amplitude_sin_clm::T: Amplitude [-] of the sine term of Clm.
• amplitude_sin_slm::T: Amplitude [-] of the sine term of Slm.
• amplitude_cos_clm::T: Amplitude [-] of the cosine term of Clm.
• amplitude_cos_slm::T: Amplitude [-] of the cosine term of Slm.
• period::T: Period [year] of the term.

struct IcgemTimeVariableCoefficient{T <: Number}

Store a time-variable (gfct) spherical harmonics coefficient of an ICGEM file, together with its linear trend (trnd) and periodic terms (asin and acos).

The coefficient is valid in the interval [t₀, t₁). Files in the ICGEM format 1.0 do not define the end of the validity interval, in which case t₁ is Inf. Files in the ICGEM format 2.0 can define several validity intervals for the same degree and order, each one stored in a different object. The evaluation selects the last object whose epoch t₀ is not after the requested time, so t₁ is informational: times before the first epoch use the first object, and times after the last epoch or inside a gap between two intervals extrapolate the previous object.

Fields

• degree::Int: Degree of the coefficient.
• order::Int: Order of the coefficient.
• clm::T: Cosine coefficient Clm [-] at the epoch t₀.
• slm::T: Sine coefficient Slm [-] at the epoch t₀.
• t₀::T: Epoch of the coefficient, expressed as the number of elapsed seconds [s] since the J2000.0 epoch (2000-01-01T12:00:00).
• t₁::T: End of the validity interval, expressed as the number of elapsed seconds [s] since the J2000.0 epoch (2000-01-01T12:00:00), or Inf if the file does not define it.
• trend_clm::T: Linear trend of Clm [year⁻¹].
• trend_slm::T: Linear trend of Slm [year⁻¹].
• periodic_terms::Vector{IcgemPeriodicTerm{T}}: Periodic terms of the coefficient.

GravityModels.load(::Type{IcgemFile}, filename::AbstractString, T::Type = Float64; kwargs...) -> 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 IcgemParseError if the file does not conform to the ICGEM format.

See also: parse_icgem, fetch_icgem_file

Keywords

• angular_speed::Number: Angular speed [rad/s] of the central body, which is not defined in the ICGEM file and is used to compute the centrifugal acceleration. It must be provided for models of bodies other than Earth. (Default: EARTH_ANGULAR_SPEED)

_add_periodic_term!(
    periodic_terms::Vector{IcgemPeriodicTerm{T}},
    is_sine::Bool,
    amplitude_clm::T,
    amplitude_slm::T,
    period::T
) -> Nothing

Add to periodic_terms the sine (is_sine = true) or cosine (is_sine = false) term with the amplitudes amplitude_clm [-] and amplitude_slm [-] and the period [year]. If periodic_terms already has a term with the same period, its amplitudes are updated. Otherwise, a new term is pushed to the vector, which is modified in place.

_compute_icgem_time_variable_coefficient(coefficients::Vector{IcgemTimeVariableCoefficient{T}}, k::Int, t::Number, ::Type{RT}) -> 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), using the element type RT.

k must be the index in coefficients of the first object related to the desired degree and order. The function selects the last object whose epoch t₀ is not after t, assuming that the objects related to the same degree and order are stored consecutively and sorted by epoch. Hence, the end t₁ of the validity intervals is not used: if t is before the first epoch, the first object is used, and if t is after the last epoch or inside a gap between two intervals, the previous object is extrapolated.

The coefficients are obtained by adding the linear trend and the 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).

References

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

_is_degree_and_order_valid(degree::Int, order::Int, max_degree::Int, current_line::Int) -> Bool

Check if degree and order of a data line are valid, i.e. if degree is not higher than max_degree and order is not higher than degree. If they are invalid, log a warning with the current_line number and return false.

_parse_asin_acos_data_line(Tf::Type, tokens::AbstractVector{<:AbstractString}, current_line::Int) -> 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::AbstractVector{<:AbstractString}, current_line::Int) -> 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::Type, tokens::AbstractVector{<:AbstractString}, current_line::Int) -> 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::Type, tokens::AbstractVector{<:AbstractString}, current_line::Int, is_format_2::Bool) -> 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.

In the ICGEM format 1.0 (is_format_2 = false), the last token is the epoch t₀ of the coefficients. In the ICGEM format 2.0 (is_format_2 = true), the last two tokens are the epoch t₀ and the end t₁ of the validity interval.

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.
• is_format_2::Bool: true if the file uses the ICGEM format 2.0, false otherwise.

Returns

• Int: Degree.
• Int: Order.
• Tf: Coefficient Clm [-] at the epoch.
• Tf: Coefficient Slm [-] at the epoch.
• Tf: Epoch (t₀) of the coefficients, expressed as the number of elapsed seconds [s] since the J2000.0 epoch (2000-01-01T12:00:00).
• Tf: End (t₁) of the validity interval, expressed as the number of elapsed seconds [s] since the J2000.0 epoch (2000-01-01T12:00:00), or Inf in the ICGEM format 1.0.

_parse_icgem_epoch(input::AbstractString) -> Union{Nothing, Float64}

Parse the epoch input, written as yyyymmdd or yyyymmdd.hhmm, and return it as the number of elapsed seconds [s] since the J2000.0 epoch (2000-01-01T12:00:00). If input cannot be parsed, return nothing.

Some published files round the minutes without carrying them into the hours, e.g. 20041226.0060 for 01:00 in EIGEN-GRGS.RL04.MEAN-FIELD. Hence, the hours are accepted up to 24 and the minutes up to 60, and the overflow is carried to the next hour or day.

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

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

_parse_trnd_data_line(Tf::Type, tokens::AbstractVector{<:AbstractString}, current_line::Int) -> 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⁻¹].

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)

Extended help

The files are stored in the scratch space of the package, managed by Scratch.jl. The first call downloads the file and logs a message, whereas the next calls return the cached file path.

Examples

julia> fetch_icgem_file(:EGM96)
[ Info: Downloading the ICGEM file 'EGM96.gfc' from 'https://icgem.gfz-potsdam.de/getmodel/gfc/971b0a3b49a497910aad23cd85e066d4cd9af0aeafe7ce6301a696bed8570be3/EGM96.gfc'...
"<scratch space>/icgem/EGM96.gfc"

julia> fetch_icgem_file(:EGM96)
"<scratch space>/icgem/EGM96.gfc"

icgem_coefficients(model::IcgemFile, degree::Int, order::Int, time::Number) -> RT, RT
icgem_coefficients(model::IcgemFile, degree::Int, order::Int, time::DateTime) -> 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.

The return type RT is float(promote_type(T, typeof(time))), where T is the type of the model coefficients.

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 [-].

parse_icgem(filename::AbstractString, T::Type = Float64; kwargs...) -> IcgemFile
parse_icgem(io::IO, T::Type = Float64; kwargs...) -> IcgemFile

Parse the ICGEM file filename, or the ICGEM data read from the stream io, using the data type T and return an IcgemFile object with the parsed data. The file filename is closed after parsing, whereas the stream io is left open.

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). Both the ICGEM formats 1.0 and 2.0 are supported, including the time-variable coefficients with validity intervals of the latter.

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

Keywords

• angular_speed::Number: Angular speed [rad/s] of the central body, which is not defined in the ICGEM file and is used to compute the centrifugal acceleration. It must be provided for models of bodies other than Earth. (Default: EARTH_ANGULAR_SPEED)

References

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

abstract type AbstractGravityModel{T <: Number}

Abstract data type of all gravity models, in which T is the type of the coefficients.

struct Workspace{N, T <: AbstractFloat}

Store the buffers and the precomputed coefficients used to evaluate a gravity model, avoiding allocations and the evaluation of square roots at every call. It must be created with Workspace(model::AbstractGravityModel; kwargs...) and passed to the evaluation functions using the keyword workspace.

The workspace supports computations up to the degree max_degree and order max_order with element type T, which must be the type obtained by promoting the type of the model coefficients, the element type of the position, and the type of the time. N is the Symbol with the normalization of the model coefficients (:full, :schmidt, or :unnormalized).

Fields

• coefficients::LegendreCoefficients{N, T}: Precomputed recursion coefficients of the associated Legendre functions.
• P::LowerTriangularStorage{RowMajor, T}: Buffer to store the associated Legendre functions. It is overwritten at every evaluation and must not be modified directly.
• dP::LowerTriangularStorage{RowMajor, T}: Buffer to store the derivatives of the associated Legendre functions. It is overwritten at every evaluation and must not be modified directly.
• max_degree::Int: Maximum degree supported by the workspace.
• max_order::Int: Maximum order supported by the workspace.

Workspace(model::AbstractGravityModel{Tm}; kwargs...) -> Workspace

Create a Workspace to evaluate the gravity model up to the degree max_degree and order max_order using the element type T.

Keywords

• max_degree::Int: Maximum degree supported by the workspace. If it is higher than the maximum degree of model, it will be clamped. If it is lower than 0, it will be set to the maximum degree of model. (Default: -1)
• max_order::Int: Maximum order supported by the workspace. 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)
• T::Type{<:AbstractFloat}: Element type of the workspace, which must be the type obtained by promoting the type of the model coefficients, the element type of the position, and the type of the time used in the evaluations. (Default: float(Tm))

_check_workspace(workspace::Workspace, ::Type{RT}, n_max::Int, m_max::Int) -> Nothing

Check if workspace has the element type RT and supports the degree n_max and the order m_max, throwing an ArgumentError otherwise.

_dlegendre!(
    N::Val,
    dP::AbstractMatrix,
    θ::Number,
    P::AbstractMatrix,
    n_max::Int,
    m_max::Int
) -> Nothing
_dlegendre!(
    coefficients::LegendreCoefficients,
    dP::AbstractMatrix,
    θ::Number,
    P::AbstractMatrix,
    n_max::Int,
    m_max::Int
) -> Nothing

Compute in dP the first-order derivatives of the associated Legendre functions P_n,m[cos(θ)] with respect to θ [rad] up to the degree n_max and order m_max without the Condon-Shortley phase term, using either the normalization N or the precomputed coefficients. The matrix P must contain the associated Legendre functions computed with _legendre!.

_from_j2000_seconds(time::Number) -> DateTime

Convert time, expressed as the number of elapsed seconds [s] from the J2000.0 epoch (2000-01-01T12:00:00), to a DateTime object with millisecond resolution.

_gravitational_field_derivative_kernel(
    model::AbstractGravityModel,
    sc::NamedTuple,
    time::Number,
    legendre::Union{Val, LegendreCoefficients},
    n_max::Int,
    m_max::Int,
    n_max_P::Int,
    m_max_P::Int,
    P::AbstractMatrix,
    dP::AbstractMatrix
) -> NTuple{4, RT}

Compute the derivative of the gravitational field of model with respect to the spherical coordinates at the position whose geocentric spherical coordinates sc were computed with _spherical_coordinates using the element type RT, 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 legendre, P, and dP. It assumes all inputs were already processed: n_max and m_max must be valid for model, legendre must be either the normalization of the model coefficients wrapped in a Val or a LegendreCoefficients object supporting n_max and m_max, and P and dP must have at least n_max_P + 1 × m_max_P + 1 and n_max + 1 × m_max + 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²].
• RT: Limit of (∂U/∂λ) / cos(ϕ) [m²/s²] at the poles, which is required to compute the east component of the acceleration on the polar axis, where both ∂U/∂λ and cos(ϕ) are 0. This value is meaningful only if the position lies on the polar axis.

_gravitational_potential_kernel(
    model::AbstractGravityModel,
    sc::NamedTuple,
    time::Number,
    legendre::Union{Val, LegendreCoefficients},
    n_max::Int,
    m_max::Int,
    P::AbstractMatrix
) -> RT

Compute the gravitational potential [m²/s²] of model at the position whose geocentric spherical coordinates sc were computed with _spherical_coordinates using the element type RT, 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 concrete types for legendre and P. It assumes all inputs were already processed: n_max and m_max must be valid for model, legendre must be either the normalization of the model coefficients wrapped in a Val or a LegendreCoefficients object supporting n_max and m_max, and P must have at least n_max + 1 × m_max + 1 elements, which are overwritten with the associated Legendre function values.

_legendre!(N::Val, P::AbstractMatrix, θ::Number, n_max::Int, m_max::Int) -> Nothing
_legendre!(
    coefficients::LegendreCoefficients,
    P::AbstractMatrix,
    θ::Number,
    n_max::Int,
    m_max::Int
) -> Nothing

Compute in P the associated Legendre functions P_n,m[cos(θ)] up to the degree n_max and order m_max without the Condon-Shortley phase term, using either the normalization N or the precomputed coefficients.

_prepare_field_derivative_inputs(model::AbstractGravityModel, ::Type{RT}, max_degree::Int, max_order::Int, workspace::Union{Nothing, Workspace}) -> Int, Int, Int, Int, Union{Val, LegendreCoefficients}, AbstractMatrix, AbstractMatrix

Process the inputs of the gravitational field derivative computation of model with element type RT, returning the degrees and orders used in the computation, the object that selects how the associated Legendre functions are computed, and the matrices to store them and their derivatives.

The requested max_degree and max_order are clamped as described in _process_degree_and_order. If workspace is nothing, the matrices are allocated and the Legendre functions are computed using the normalization of model. Otherwise, the buffers and the precomputed coefficients of workspace are used, and the function throws an ArgumentError if the workspace is not compatible with the computation.

Returns

• Int: Maximum degree n_max used in the computation.
• Int: Maximum order m_max used in the computation.
• Int: Maximum degree computed in P.
• Int: Maximum order computed in P, which is m_max + 1 if m_max < n_max because the derivative computation requires one additional order.
• Union{Val, LegendreCoefficients}: Normalization or precomputed coefficients used to compute the associated Legendre functions.
• AbstractMatrix: Matrix P to store the associated Legendre functions.
• AbstractMatrix: Matrix dP to store the derivatives of the associated Legendre functions.

_prepare_potential_inputs(model::AbstractGravityModel, ::Type{RT}, max_degree::Int, max_order::Int, workspace::Union{Nothing, Workspace}) -> Int, Int, Union{Val, LegendreCoefficients}, AbstractMatrix

Process the inputs of the gravitational potential computation of model with element type RT, returning the degree and order used in the computation, the object that selects how the associated Legendre functions are computed, and the matrix to store them.

The requested max_degree and max_order are clamped as described in _process_degree_and_order. If workspace is nothing, the matrix is allocated and the Legendre functions are computed using the normalization of model. Otherwise, the buffer and the precomputed coefficients of workspace are used, and the function throws an ArgumentError if the workspace is not compatible with the computation.

Returns

• Int: Maximum degree n_max used in the computation.
• Int: Maximum order m_max used in the computation.
• Union{Val, LegendreCoefficients}: Normalization or precomputed coefficients used to compute the associated Legendre functions.
• AbstractMatrix: Matrix P to store the associated Legendre functions.

_process_degree_and_order(model::AbstractGravityModel, max_degree::Int, max_order::Int) -> Int, Int

Return the maximum degree and order used in the spherical harmonics computation of model given the requested max_degree and max_order. If max_degree is negative or higher than the maximum degree of model, it is clamped to the latter. If max_order is negative or higher than the selected degree, it is set to the selected degree.

Returns

• Int: Maximum degree used in the computation.
• Int: Maximum order used in the computation.

_spherical_coordinates(r::AbstractVector, ::Type{RT}) -> NamedTuple

Compute the geocentric spherical coordinates of the position r [m] using the element type RT. The components of r are converted to RT before any operation. Hence, the precision of the result is not limited by the element type of r when it is narrower than RT.

The sine and cosine of the longitude are obtained directly from the coordinates, avoiding trigonometric functions. On the polar axis, where the longitude is undefined, the longitude is defined as 0.

The returned angle is the geocentric colatitude folded to the northern hemisphere, i.e. the angle between the position and the polar axis in the interval [0, π / 2]. The last returned value indicates whether the position lies in the southern hemisphere, in which case the geocentric colatitude is π minus the returned angle. The angle is computed directly from the coordinates instead of subtracting the latitude from π / 2, avoiding the catastrophic cancellation near the poles, where the latitude rounds to π / 2. The folding is required because the floating-point numbers near π cannot represent the colatitude near the south pole as accurately as those near 0 represent it near the north pole.

Returns

• NamedTuple: Spherical coordinates with the fields:
  • r_gc::RT: Distance from the origin [m].
  • ρ_gc::RT: Distance from the polar axis [m].
  • z::RT: Component of the position along the polar axis [m].
  • θ::RT: Geocentric colatitude folded to the northern hemisphere [rad] in the interval [0, π / 2].
  • sin_λ::RT: Sine of the longitude [-].
  • cos_λ::RT: Cosine of the longitude [-].
  • south::Bool: true if the position lies in the southern hemisphere, false otherwise.

_to_j2000_seconds(time::Number) -> Number
_to_j2000_seconds(time::DateTime) -> Float64

Convert time to the number of elapsed seconds [s] from the J2000.0 epoch (2000-01-01T12:00:00). If time is a number, it is assumed to be already expressed in this representation and it is returned unchanged.

angular_speed(model::AbstractGravityModel{T}) -> T

Return the angular speed [rad/s] of the central body of the gravity model, which is used to compute the centrifugal acceleration in gravity_acceleration.

coefficient_norm(model::AbstractGravityModel) -> Val

Return the normalization we must use in the spherical harmonics when computing the Legendre associated functions for the gravity model, wrapped in a Val so that the Legendre functions can be dispatched on it. The accepted values are:

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

coefficients(model::AbstractGravityModel, degree::Int, order::Int, time::Number) -> RT, RT
coefficients(model::AbstractGravityModel, degree::Int, order::Int, time::DateTime) -> RT, RT
coefficients(model::AbstractGravityModel, degree::Int, order::Int) -> RT, RT

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.

The models must implement only the method that receives time as a Number. The other methods convert the time and call it.

Arguments

• model::AbstractGravityModel{T}: 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

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

The return type RT is the promotion of the type T of the model coefficients with the type of time. Models with constant coefficients may return T instead.

gravitational_acceleration(model::AbstractGravityModel, r::AbstractVector, time::Number = 0; kwargs...) -> SVector{3, RT}
gravitational_acceleration(model::AbstractGravityModel, r::AbstractVector, time::DateTime; 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}: 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 acceleration. 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 acceleration. 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)
• workspace::Union{Nothing, Workspace}: Workspace created with Workspace for the model, holding the buffers and the precomputed coefficients used in the computation, which avoids allocations and improves the performance. Its element type must be RT and it must support the selected degree and order. Otherwise, the function throws an ArgumentError. If it is nothing, the buffers are allocated at every call. (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::Number = 0; kwargs...) -> RT, RT, RT
gravitational_field_derivative(model::AbstractGravityModel, r::AbstractVector, time::DateTime; kwargs...) -> RT, RT, 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}: 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)
• workspace::Union{Nothing, Workspace}: Workspace created with Workspace for the model, holding the buffers and the precomputed coefficients used in the computation, which avoids allocations and improves the performance. Its element type must be RT and it must support the selected degree and order. Otherwise, the function throws an ArgumentError. If it is nothing, the buffers are allocated at every call. (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::Number = 0; kwargs...) -> RT
gravitational_potential(model::AbstractGravityModel, r::AbstractVector, time::DateTime; 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}: 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)
• workspace::Union{Nothing, Workspace}: Workspace created with Workspace for the model, holding the buffers and the precomputed coefficients used in the computation, which avoids allocations and improves the performance. Its element type must be RT and it must support the selected degree and order. Otherwise, the function throws an ArgumentError. If it is nothing, the buffers are allocated at every call. (Default: nothing)

Returns

• RT: Gravitational potential U [m²/s²] at the position r.

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::Number = 0; kwargs...) -> SVector{3, RT}
gravity_acceleration(model::AbstractGravityModel, r::AbstractVector, time::DateTime; 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, the type of time, and the type of the angular speed ω.

See also: gravitational_acceleration

Arguments

• model::AbstractGravityModel{T}: 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 acceleration. 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 acceleration. 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)
• workspace::Union{Nothing, Workspace}: Workspace created with Workspace for the model, holding the buffers and the precomputed coefficients used in the computation, which avoids allocations and improves the performance. Its element type must be RT and it must support the selected degree and order. Otherwise, the function throws an ArgumentError. If it is nothing, the buffers are allocated at every call. (Default: nothing)
• ω::Number: Angular speed of the body [rad/s], which defaults to the value stored in the model (see angular_speed). (Default: angular_speed(model))

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}) -> 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..., which are defined by each model type. For example, IcgemFile requires the file name and accepts the coefficient type and the angular speed of the body.

maximum_degree(model::AbstractGravityModel) -> Int

Return the maximum degree of the gravity model.

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

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