GitHub

Library

Documentation for SatelliteToolboxGravityModels.jl.

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

Fetch a 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 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.

Examples

julia> fetch_icgem_file(:EGM96)
[ Info: Downloading the ICGEM file 'EGM96.gfc' from 'http://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"
source
SatelliteToolboxGravityModels.icgem_coefficients — Method
icgem_coefficients(model::IcgemFile{T}, degree::Int, order::Int, time::Union{Number, DateTime}) where T<:Number -> T, T

Compute the ICGEM coefficients (Clm and Slm) of the model for the specified degree and order in the instant time.

time can be expressed using a DateTime object or the number of ellapsed seconds from J2000.0 epoch (2000-01-01T12:00:00.000).

source
SatelliteToolboxGravityModels.parse_icgem — Function
parse_icgem(filename::AbstractString, T::DataType = Float64) -> IcgemFile

Parse the ICGEM file filename using the data type T.

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

Note

T is converted to float to obtain the output type.

source
SatelliteToolboxGravityModels.GravityModels.coefficient_norm — Function
coefficient_norm(model::AbstractGravityModel{T, NT}) where {T<:Number, NT<:Val} -> Symbol

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

  • :full: Use full normalization.
  • :schmidt: Use Schmidt quasi-normalization.
  • :unnormalized: Do not perform normalization.
source
SatelliteToolboxGravityModels.GravityModels.coefficients — Function
coefficients(model::AbstractGravityModel{T, NT}, degree::Int, order::Int[, time::Union{Number, DateTime}]) where {T<:Number, NT} -> 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 is used.

time can be expressed using a DateTime object or the number of ellapsed seconds from J2000.0 epoch.

source
SatelliteToolboxGravityModels.GravityModels.gravitational_acceleration — Method
gravitational_acceleration(model::AbstractGravityModel{Number, NormType}, r::AbstractVector{Number}[, time::Union{Number, DateTime}]; kwargs...) -> NTuple{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 is used (2000-01-01T12:00:00).

time can be expressed using a DateTime object or the number of ellapsed seconds from J2000.0 epoch.

Note

Gravitational acceleration is the acceleration caused by the central body mass only, i.e., without considering the centrifugal potential.

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)
Note

The matrices P and dP are lower triangular. Hence, the algorithm peformance for large models can be improved if they are created using the LowerTriangularStorage (defined in SatelliteToolboxBase.jl) with a row-major ordering. If those matrices are not provided by the user, they will be created using that type of storage.

Returns

  • RT: The derivative of the gravitational field w.r.t. the radius (∂U/∂r).
  • RT: The derivative of the gravitational field w.r.t. the geocentric latitude (∂U/∂ϕ).
  • RT: The derivative of the gravitational field w.r.t. the longitude (∂U/∂λ).
source
SatelliteToolboxGravityModels.GravityModels.gravitational_field_derivative — Method
gravitational_field_derivative(model::AbstractGravityModel{Number, NormType}, r::AbstractVector{Number}[, time::Union{Number, DateTime}]; kwargs...) -> NTuple{3, RT}

Compute the gravitational field derivative [SI] 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 is used.

time can be expressed using a DateTime object or the number of ellapsed seconds from J2000.0 epoch.

Info

In this case, ϕ is the geocentric latitude and λ is the longitude.

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)
Note

The matrices P and dP are lower triangular. Hence, the algorithm peformance for large models can be improved if they are created using the LowerTriangularStorage (defined in SatelliteToolboxBase.jl) with a row-major ordering. If those matrices are not provided by the user, they will be created using that type of storage.

Returns

  • RT: The derivative of the gravitational field w.r.t. the radius (∂U/∂r).
  • RT: The derivative of the gravitational field w.r.t. the geocentric latitude (∂U/∂ϕ).
  • RT: The derivative of the gravitational field w.r.t. the longitude (∂U/∂λ).
source
SatelliteToolboxGravityModels.GravityModels.gravitational_potential — Method
gravitational_potential(model::AbstractGravityModel{Number, NormType}, r::AbstractVector{Number}[, time::Union{Number, DateTime}]; kwargs...) -> RT

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

time can be expressed using a DateTime object or the number of ellapsed seconds from J2000.0 epoch.

Note

Gravitational potential is the potential caused by the central body mass only, i.e., without considering the centrifugal potential.

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)
Note

The matrix P is lower triangular. Hence, the algorithm peformance for large models can be improved if it is created using the LowerTriangularStorage (defined in SatelliteToolboxBase.jl) with a row-major ordering. If this matrix is not provided by the user, it will be created using that type of storage.

Returns

  • RT: The gravitational potential U.
source
SatelliteToolboxGravityModels.GravityModels.gravity_acceleration — Method
gravity_acceleration(model::AbstractGravityModel{Number, NormType}, r::AbstractVector{Number}[, time::Union{Number, DataTime}]; kwargs...) -> NTuple{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 is used.

time can be expressed using a DateTime object or the number of ellapsed seconds from J2000.0 epoch.

Note

Gravity acceleration is the compound acceleration caused by the central body mass and the centrifugal force due to the planet's rotation.

For non-Earth bodies, the body's rotation rate can be provided using the ω keyword.

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: The rotation rate of the body [rad / s]. For non-Earth bodies, provide the appropriate rotation rate for the celestial body. (Default = EARTH_ANGULAR_SPEED)
Note

The matrices P and dP are lower triangular. Hence, the algorithm peformance for large models can be improved if they are created using the LowerTriangularStorage (defined in SatelliteToolboxBase.jl) with a row-major ordering. If those matrices are not provided by the user, they will be created using that type of storage.

Returns

  • RT: The derivative of the gravitational field w.r.t. the radius (∂U/∂r).
  • RT: The derivative of the gravitational field w.r.t. the geocentric latitude (∂U/∂ϕ).
  • RT: The derivative of the gravitational field w.r.t. the longitude (∂U/∂λ).
source