Library

mutable struct J2OsculatingPropagator{Tepoch <: Number, T <: Number}

J2 osculating orbit propagator structure, where Tepoch is the type of the epoch and T is the type of the elements and of the internal variables. The fields are set by j2osc_init! and updated by j2osc!, and must not be modified directly by the callers, except for j2d, which must be assigned before initializing a structure created with the empty constructor.

Fields

• j2d::J2Propagator{Tepoch, T}: J2 orbit propagator that propagates the mean elements and stores the timespan from the initial elements' epoch.
• orbk::KeplerianElements{TrueAnomaly, Tepoch, T}: Current osculating orbit elements [SI units].

Extended help

Printing

show(io, pd) prints the compact form: the type with its parameters and the epoch of the initial mean elements as a Julian Day and as a date. show(io, MIME("text/plain"), pd) prints a tree with the sections holding the initial mean elements and their epoch, the secular rates, the constants, and the last propagation instant, one field per line with its unit, with the labels in bold and the units dimmed if io supports color. The body can be printed under another header with SatelliteToolboxBase.print_tree_body. An uninitialized structure prints the status not initialized instead.

mutable struct J2Propagator{Tepoch <: Number, T <: Number}

J2 orbit propagator structure, where Tepoch is the type of the epoch and T is the type of the elements and of the internal variables. The fields are set by j2_init! and updated by j2!, and must not be modified directly by the callers, except for j2c, which must be assigned before initializing a structure created with the empty constructor.

Fields

• orb₀::KeplerianElements{MeanAnomaly, Tepoch, T}: Initial mean orbit elements [SI units].
• orbk::KeplerianElements{MeanAnomaly, Tepoch, T}: Current mean orbit elements [SI units].
• j2c::J2PropagatorConstants{T}: Propagator constants.
• Δt::T: Timespan from the initial elements' epoch [s], which is NaN until the structure is initialized.
• ∂Ω::T: RAAN time derivative [rad / s].
• ∂ω::T: Argument of perigee time derivative [rad / s].
• n̄::T: Perturbed mean motion [rad / s].

Extended help

Printing

show(io, pd) prints the compact form: the type with its parameters and the epoch of the initial mean elements as a Julian Day and as a date. show(io, MIME("text/plain"), pd) prints a tree with the sections holding the initial mean elements and their epoch, the secular rates, the constants, and the last propagation instant, one field per line with its unit, with the labels in bold and the units dimmed if io supports color. The body can be printed under another header with SatelliteToolboxBase.print_tree_body. An uninitialized structure prints the status not initialized instead.

struct J2PropagatorConstants{T <: Number}

Constants for the J2 orbit propagator.

Fields

• R0::T: Earth equatorial radius [m].
• μm::T: Standard gravitational parameter normalized by the Earth equatorial radius, √(GM / R0³) [rad / s].
• J2::T: The second gravitational zonal harmonic of the Earth [-].

J2PropagatorConstants{T}(
    j2c::J2PropagatorConstants
) where {T <: Number} -> J2PropagatorConstants{T}

Create a copy of the J2 propagator constants j2c with the element type T.

mutable struct J4OsculatingPropagator{Tepoch <: Number, T <: Number}

J4 osculating orbit propagator structure, where Tepoch is the type of the epoch and T is the type of the elements and of the internal variables. The fields are set by j4osc_init! and updated by j4osc!, and must not be modified directly by the callers, except for j4d, which must be assigned before initializing a structure created with the empty constructor.

Fields

• j4d::J4Propagator{Tepoch, T}: J4 orbit propagator that propagates the mean elements and stores the timespan from the initial elements' epoch.
• orbk::KeplerianElements{TrueAnomaly, Tepoch, T}: Current osculating orbit elements [SI units].

Extended help

Printing

show(io, pd) prints the compact form: the type with its parameters and the epoch of the initial mean elements as a Julian Day and as a date. show(io, MIME("text/plain"), pd) prints a tree with the sections holding the initial mean elements and their epoch, the secular rates, the constants, and the last propagation instant, one field per line with its unit, with the labels in bold and the units dimmed if io supports color. The body can be printed under another header with SatelliteToolboxBase.print_tree_body. An uninitialized structure prints the status not initialized instead.

mutable struct J4Propagator{Tepoch <: Number, T <: Number}

J4 orbit propagator structure, where Tepoch is the type of the epoch and T is the type of the elements and of the internal variables. The fields are set by j4_init! and updated by j4!, and must not be modified directly by the callers, except for j4c, which must be assigned before initializing a structure created with the empty constructor.

Fields

• orb₀::KeplerianElements{MeanAnomaly, Tepoch, T}: Initial mean orbit elements [SI units].
• orbk::KeplerianElements{MeanAnomaly, Tepoch, T}: Current mean orbit elements [SI units].
• j4c::J4PropagatorConstants{T}: Propagator constants.
• Δt::T: Timespan from the initial elements' epoch [s], which is NaN until the structure is initialized.
• ∂Ω::T: RAAN time derivative [rad / s].
• ∂ω::T: Argument of perigee time derivative [rad / s].
• n̄::T: Perturbed mean motion [rad / s].

Extended help

Printing

show(io, pd) prints the compact form: the type with its parameters and the epoch of the initial mean elements as a Julian Day and as a date. show(io, MIME("text/plain"), pd) prints a tree with the sections holding the initial mean elements and their epoch, the secular rates, the constants, and the last propagation instant, one field per line with its unit, with the labels in bold and the units dimmed if io supports color. The body can be printed under another header with SatelliteToolboxBase.print_tree_body. An uninitialized structure prints the status not initialized instead.

struct J4PropagatorConstants{T <: Number}

Constants for the J4 orbit propagator.

Fields

• R0::T: Earth equatorial radius [m].
• μm::T: Standard gravitational parameter normalized by the Earth equatorial radius, √(GM / R0³) [rad / s].
• J2::T: The second gravitational zonal harmonic of the Earth [-].
• J4::T: The fourth gravitational zonal harmonic of the Earth [-].

J4PropagatorConstants{T}(
    j4c::J4PropagatorConstants
) where {T <: Number} -> J4PropagatorConstants{T}

Create a copy of the J4 propagator constants j4c with the element type T.

struct MeanElementsFitDivergenceError <: Exception

Exception thrown when the least-square iterations used to fit the mean elements of the analytical propagators diverge.

Fields

• iteration::Int: Iteration in which the divergence was detected.
• residue::Float64: Total RMSE of the residue in that iteration.

struct OrbitPropagatorJ2{Tepoch <: Number, T <: Number} <: OrbitPropagator{Tepoch, T}

J2 orbit propagator for the Propagators API.

Fields

• j2d::J2Propagator{Tepoch, T}: Structure that stores the J2 orbit propagator data (see J2Propagator).

Extended help

Printing

show(io, orbp) prints the compact form: the type with its parameters, the propagator name, and the epoch as a Julian Day and as a date. show(io, MIME("text/plain"), orbp) prints the same header followed by the body of the rich representation of j2d.

struct OrbitPropagatorJ2Osculating{
    Tepoch <: Number,
    T <: Number
} <: OrbitPropagator{Tepoch, T}

J2 osculating orbit propagator for the Propagators API.

Fields

• j2oscd::J2OsculatingPropagator{Tepoch, T}: Structure that stores the J2 osculating orbit propagator data (see J2OsculatingPropagator).

Extended help

Printing

show(io, orbp) prints the compact form: the type with its parameters, the propagator name, and the epoch as a Julian Day and as a date. show(io, MIME("text/plain"), orbp) prints the same header followed by the body of the rich representation of j2oscd.

struct OrbitPropagatorJ4{Tepoch <: Number, T <: Number} <: OrbitPropagator{Tepoch, T}

J4 orbit propagator for the Propagators API.

Fields

• j4d::J4Propagator{Tepoch, T}: Structure that stores the J4 orbit propagator data (see J4Propagator).

Extended help

Printing

show(io, orbp) prints the compact form: the type with its parameters, the propagator name, and the epoch as a Julian Day and as a date. show(io, MIME("text/plain"), orbp) prints the same header followed by the body of the rich representation of j4d.

struct OrbitPropagatorJ4Osculating{
    Tepoch <: Number,
    T <: Number
} <: OrbitPropagator{Tepoch, T}

J4 osculating orbit propagator for the Propagators API.

Fields

• j4oscd::J4OsculatingPropagator{Tepoch, T}: Structure that stores the J4 osculating orbit propagator data (see J4OsculatingPropagator).

Extended help

Printing

show(io, orbp) prints the compact form: the type with its parameters, the propagator name, and the epoch as a Julian Day and as a date. show(io, MIME("text/plain"), orbp) prints the same header followed by the body of the rich representation of j4oscd.

struct OrbitPropagatorSgp4{Tepoch <: Number, T <: Number} <: OrbitPropagator{Tepoch, T}

SGP4 orbit propagator for the Propagators API.

Fields

• sgp4d::Sgp4Propagator{Tepoch, T}: Structure that stores the SGP4 orbit propagator data (see Sgp4Propagator in SatelliteToolboxSgp4.jl).

Extended help

Printing

show(io, orbp) prints the compact form: the type with its parameters, the propagator name, and the epoch as a Julian Day and as a date. show(io, MIME("text/plain"), orbp) prints the same header followed by the body of the rich representation of sgp4d.

struct OrbitPropagatorTwoBody{
    Tepoch <: Number,
    T <: Number
} <: OrbitPropagator{Tepoch, T}

Two-body orbit propagator for the Propagators API.

Fields

• tbd::TwoBodyPropagator{Tepoch, T}: Structure that stores the two-body orbit propagator data (see TwoBodyPropagator).

Extended help

Printing

show(io, orbp) prints the compact form: the type with its parameters, the propagator name, and the epoch as a Julian Day and as a date. show(io, MIME("text/plain"), orbp) prints the same header followed by the body of the rich representation of tbd.

mutable struct TwoBodyPropagator{Tepoch <: Number, T <: Number}

Two-body orbit propagator structure, where Tepoch is the type of the epoch and T is the type of the elements and of the internal variables. The fields are set by twobody_init! and updated by twobody!, and must not be modified directly by the callers, except for μ, which must be assigned before initializing a structure created with the empty constructor.

Fields

• orb₀::KeplerianElements{MeanAnomaly, Tepoch, T}: Initial mean orbit elements [SI units].
• orbk::KeplerianElements{MeanAnomaly, Tepoch, T}: Current mean orbit elements [SI units].
• μ::T: Standard gravitational parameter of the central body [m³ / s²].
• Δt::T: Timespan from the initial elements' epoch [s], which is NaN until the structure is initialized.
• n₀::T: Mean motion [rad / s].

Extended help

Printing

show(io, pd) prints the compact form: the type with its parameters and the epoch of the initial mean elements as a Julian Day and as a date. show(io, MIME("text/plain"), pd) prints a tree with the sections holding the initial mean elements and their epoch, the mean motion, the constants, and the last propagation instant, one field per line with its unit, with the labels in bold and the units dimmed if io supports color. The body can be printed under another header with SatelliteToolboxBase.print_tree_body. An uninitialized structure prints the status not initialized instead.

Propagators.fit_mean_elements!(
    orbp::OrbitPropagatorJ2,
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Tepoch, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J2 orbit propagator orbp using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

The keywords are the same as in fit_j2_mean_elements, except for j2c, since the constants are those in orbp.

Returns

• KeplerianElements{MeanAnomaly, Tepoch, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

Propagators.fit_mean_elements!(
    orbp::OrbitPropagatorJ2Osculating,
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Tepoch, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J2 osculating orbit propagator orbp using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

The keywords are the same as in fit_j2osc_mean_elements, except for j2c, since the constants are those in orbp.

Returns

• KeplerianElements{MeanAnomaly, Tepoch, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

Propagators.fit_mean_elements!(
    orbp::OrbitPropagatorJ4,
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Tepoch, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J4 orbit propagator orbp using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

The keywords are the same as in fit_j4_mean_elements, except for j4c, since the constants are those in orbp.

Returns

• KeplerianElements{MeanAnomaly, Tepoch, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

Propagators.fit_mean_elements!(
    orbp::OrbitPropagatorJ4Osculating,
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Tepoch, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J4 osculating orbit propagator orbp using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

The keywords are the same as in fit_j4osc_mean_elements, except for j4c, since the constants are those in orbp.

Returns

• KeplerianElements{MeanAnomaly, Tepoch, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

Propagators.fit_mean_elements!(
    orbp::OrbitPropagatorSgp4{Tepoch, T},
    vjd::AbstractVector{Tjd},
    vr_teme::AbstractVector{Tv},
    vv_teme::AbstractVector{Tv}[, sink::Type];
    kwargs...
) where {
    Tepoch <: Number,
    T <: Number,
    Tjd <: Number,
    Tv <: AbstractVector
} -> sink, SMatrix{7, 7, T}, NamedTuple

Fit a set of SGP4 mean elements for the orbit propagator orbp using the osculating elements represented by a set of position vectors vr_teme [m] and a set of velocity vectors vv_teme [m / s] represented in the True-Equator, Mean-Equinox reference frame (TEME) at instants in the array vjd [Julian Day, UTC]. The mean elements are returned as an object of type sink, which can be TLE or OrbitMeanElementsMessage. If it is omitted, an OrbitMeanElementsMessage is returned. The fitting can fail if the least-square iterations diverge.

This algorithm was based on [1].

Keywords

The keywords are the same as in Propagators.fit_mean_elements for the SGP4 orbit propagator.

Returns

• sink: The fitted mean elements.

• SMatrix{7, 7, T}: Final covariance matrix of the least-square algorithm, whose state is the mean position [km], the mean velocity [km / s], and the drag term B* [1 / er].

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration, scaled to SI units.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned. The RMSE values are computed by SatelliteToolboxSgp4.jl in kilometers and converted here to SI units.

References

• [1] Vallado, D. A., Crawford, P (2008). SGP4 Orbit Determination. American Institute of Aeronautics and Astronautics.

Extended help

Throws

• ArgumentError: If vjd, vr_teme, and vv_teme do not have the same length, if weight_vector does not have six elements, if max_iterations is lower than 1, or if a NamedTuple template contains a field set by the fit.
• Sgp4FitDivergenceError: If the least-square iterations diverge.

Propagators.fit_mean_elements!(
    orbp::OrbitPropagatorTwoBody,
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Tepoch, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the two-body orbit propagator orbp using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

The keywords are the same as in fit_twobody_mean_elements, except for m0, since the gravitational parameter is that in orbp.

Returns

• KeplerianElements{MeanAnomaly, Tepoch, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

Propagators.fit_mean_elements(
    ::Val{:J2osc},
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) -> KeplerianElements{MeanAnomaly, Float64, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J2 osculating orbit propagator using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

• j2c::J2PropagatorConstants{T}: J2 orbit propagator constants (see J2PropagatorConstants), whose number type T is used in the fitting. (Default: J2C_EGM2008)

The other keywords are the same as in fit_j2osc_mean_elements.

Returns

• KeplerianElements{MeanAnomaly, Float64, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

Propagators.fit_mean_elements(
    ::Val{:J2},
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) -> KeplerianElements{MeanAnomaly, Float64, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J2 orbit propagator using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

• j2c::J2PropagatorConstants{T}: J2 orbit propagator constants (see J2PropagatorConstants), whose number type T is used in the fitting. (Default: J2C_EGM2008)

The other keywords are the same as in fit_j2_mean_elements.

Returns

• KeplerianElements{MeanAnomaly, Float64, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

Propagators.fit_mean_elements(
    ::Val{:J4osc},
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) -> KeplerianElements{MeanAnomaly, Float64, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J4 osculating orbit propagator using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

• j4c::J4PropagatorConstants{T}: J4 orbit propagator constants (see J4PropagatorConstants), whose number type T is used in the fitting. (Default: J4C_EGM2008)

The other keywords are the same as in fit_j4osc_mean_elements.

Returns

• KeplerianElements{MeanAnomaly, Float64, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

Propagators.fit_mean_elements(
    ::Val{:J4},
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) -> KeplerianElements{MeanAnomaly, Float64, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J4 orbit propagator using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

• j4c::J4PropagatorConstants{T}: J4 orbit propagator constants (see J4PropagatorConstants), whose number type T is used in the fitting. (Default: J4C_EGM2008)

The other keywords are the same as in fit_j4_mean_elements.

Returns

• KeplerianElements{MeanAnomaly, Float64, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

Propagators.fit_mean_elements(
    [sink::Type, ]::Val{:SGP4},
    vjd::AbstractVector{Tjd},
    vr_teme::AbstractVector{Tv},
    vv_teme::AbstractVector{Tv};
    kwargs...
) where {Tjd <: Number, Tv <: AbstractVector} -> sink, SMatrix{7, 7, T}, NamedTuple

Fit a set of SGP4 mean elements using the osculating elements represented by a set of position vectors vr_teme [m] and a set of velocity vectors vv_teme [m / s] represented in the True-Equator, Mean-Equinox reference frame (TEME) at instants in the array vjd [Julian Day, UTC]. The mean elements are returned as an object of type sink, which can be TLE or OrbitMeanElementsMessage. If it is omitted, an OrbitMeanElementsMessage is returned. The fitting can fail if the least-square iterations diverge.

This algorithm was based on [1].

Keywords

• sgp4c::Sgp4Constants: SGP4 orbit propagator constants (see Sgp4Constants), whose number type T is used in the fitting. (Default: SGP4C_WGS84)
• atol::Number: Tolerance for the residual absolute value. If the residual is lower than atol at any iteration, the computation loop stops. (Default: 2e-4)
• rtol::Number: Tolerance for the relative difference between the residuals. If the relative difference between the residuals in two consecutive iterations is lower than rtol, the computation loop stops. (Default: 2e-4)
• estimate_bstar::Bool: If true, the algorithm will try to estimate the B* parameter. Otherwise, it will be set to 0 or to the value in the initial guess (see section Initial Guess). (Default: true)
• include_covariance::Bool: If true, the covariance of the mean position and velocity obtained by the least-square algorithm is stored in the covariance matrix section of the output, represented in the TEME reference frame. It is only used when sink is OrbitMeanElementsMessage. (Default: true)
• initial_guess::Union{Nothing, AbstractVector, TLE, OrbitMeanElementsMessage}: Initial guess for the fitting process. If it is nothing, the algorithm will obtain an initial estimate from the osculating elements in vr_teme and vv_teme. For more information, see the section Initial Guess. (Default: nothing)
• jacobian_method::AbstractJacobianMethod: Method used to compute the Jacobian matrix. It can be FiniteDiffJacobian() for finite differences or ForwardDiffJacobian() for ForwardDiff.jl automatic differentiation. (Default: FiniteDiffJacobian())
• jacobian_perturbation::Number: Initial state perturbation to compute the finite-difference when calculating the Jacobian matrix. Only used with FiniteDiffJacobian(). (Default: 1e-3)
• jacobian_perturbation_tol::Number: Tolerance to accept the perturbation when calculating the Jacobian matrix. If the computed perturbation is lower than jacobian_perturbation_tol, we increase it until its absolute value is higher than jacobian_perturbation_tol. Only used with FiniteDiffJacobian(). (Default: 1e-7)
• max_iterations::Int: Maximum number of iterations allowed for the least-square fitting. (Default: 50)
• mean_elements_epoch::Union{Number, DateTime}: Epoch of the fitted mean elements, represented by a Julian Day [UTC] or a DateTime [UTC]. (Default: vjd[end])
• template::Union{Nothing, sink, NamedTuple}: Source of the metadata of the output. If it is an object of type sink, its metadata is copied, e.g. the satellite name and number of a TLE or the header, the metadata, and the TLE-related parameters of an OrbitMeanElementsMessage. If it is a NamedTuple, its entries are passed as keywords to the constructor of sink on top of the default metadata, e.g. (; name = "AMAZONIA 1", satellite_number = 47699) for a TLE or (; object_name = "AMAZONIA 1", object_id = "2021-015A", norad_cat_id = 47699) for an OrbitMeanElementsMessage. In both cases, only the mean elements, the epoch, the drag term, and the covariance matrix are set by the fitted values, and a NamedTuple must not contain them. If it is nothing, the metadata is filled with default values. (Default: nothing)
• verbose::Bool: If true, the algorithm prints debugging information to stdout. (Default: true)
• weight_vector::AbstractVector: Vector with the measurements weights for the least-square algorithm. We assemble the weight matrix W as a diagonal matrix with the elements in weight_vector at its diagonal. (Default: @SVector(ones(Bool, 6)))

Returns

• sink: The fitted mean elements.

• SMatrix{7, 7, T}: Final covariance matrix of the least-square algorithm, whose state is the mean position [km], the mean velocity [km / s], and the drag term B* [1 / er].

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration, scaled to SI units.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned. The RMSE values are computed by SatelliteToolboxSgp4.jl in kilometers and converted here to SI units.

Initial Guess

This algorithm uses a least-square algorithm to fit a set of mean elements based on a set of osculating state vectors. Since the system is chaotic, a good initial guess is paramount for algorithm convergence. We can provide an initial guess using the keyword initial_guess.

If initial_guess is a TLE or an OrbitMeanElementsMessage, we update its epoch to the desired one in mean_elements_epoch. Afterward, we use these mean elements as the initial guess.

If initial_guess is an AbstractVector, we use this vector as the initial mean state vector for the algorithm. It must contain 7 elements as follows:

┌                                    ┐
│ IDs 1 to 3: Mean position [km]     │
│ IDs 4 to 6: Mean velocity [km / s] │
│ ID  7:      Bstar         [1 / er] │
└                                    ┘

If initial_guess is nothing, the algorithm takes the closest osculating state vector to the mean_elements_epoch and uses it as the initial mean state vector. In this case, the epoch is set to the same epoch of the osculating data in vjd. When the fitted mean elements are obtained, the algorithm updates their epoch to mean_elements_epoch.

References

• [1] Vallado, D. A., Crawford, P (2008). SGP4 Orbit Determination. American Institute of Aeronautics and Astronautics.

Extended help

Throws

• ArgumentError: If vjd, vr_teme, and vv_teme do not have the same length, if weight_vector does not have six elements, if max_iterations is lower than 1, or if a NamedTuple template contains a field set by the fit.
• Sgp4FitDivergenceError: If the least-square iterations diverge.

Propagators.fit_mean_elements(
    ::Val{:TwoBody},
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Float64, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the two-body orbit propagator using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

• m0::T: Standard gravitational parameter of the central body [m³ / s²], whose number type T is used in the fitting. (Default: TBC_M0)

The other keywords are the same as in fit_twobody_mean_elements.

Returns

• KeplerianElements{MeanAnomaly, Float64, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

Propagators.init!(orbp::OrbitPropagatorJ2, orb₀::KeplerianElements) -> Nothing

Initialize the J2 orbit propagator structure orbp using the mean Keplerian elements orb₀ [SI units].

Propagators.init!(orbp::OrbitPropagatorJ2Osculating, orb₀::KeplerianElements) -> Nothing

Initialize the J2 osculating orbit propagator structure orbp using the mean Keplerian elements orb₀ [SI units].

Propagators.init!(orbp::OrbitPropagatorJ4, orb₀::KeplerianElements) -> Nothing

Initialize the J4 orbit propagator structure orbp using the mean Keplerian elements orb₀ [SI units].

Propagators.init!(orbp::OrbitPropagatorJ4Osculating, orb₀::KeplerianElements) -> Nothing

Initialize the J4 osculating orbit propagator structure orbp using the mean Keplerian elements orb₀ [SI units].

Propagators.init!(
    orbp::OrbitPropagatorSgp4,
    epoch::Number,
    n₀::Number,
    e₀::Number,
    i₀::Number,
    Ω₀::Number,
    ω₀::Number,
    M₀::Number,
    bstar::Number;
    kwargs...
) -> Nothing

Propagators.init!(
    orbp::OrbitPropagatorSgp4,
    tle::TLE;
    kwargs...
) -> Nothing

Propagators.init!(
    orbp::OrbitPropagatorSgp4,
    omm::OrbitMeanElementsMessage;
    kwargs...
) -> Nothing

Initialize the SGP4 orbit propagator structure orbp using the initial orbit specified by the arguments. The initialization from an Orbit Mean-Elements Message (OMM) can fail if the message does not describe an SGP4 orbit.

Arguments

• epoch::Number: Epoch of the orbital elements [Julian Day].
• n₀::Number: SGP type "mean" mean motion at epoch [rad/s].
• e₀::Number: "Mean" eccentricity at epoch.
• i₀::Number: "Mean" inclination at epoch [rad].
• Ω₀::Number: "Mean" longitude of the ascending node at epoch [rad].
• ω₀::Number: "Mean" argument of perigee at epoch [rad].
• M₀::Number: "Mean" mean anomaly at epoch [rad].
• bstar::Number: Drag parameter (B*).
• tle::TLE: Two-line elements used for the initialization.
• omm::OrbitMeanElementsMessage: Orbit Mean-Elements Message used for the initialization. Its mean element theory must be "SGP4", and it must provide the mean motion or the semi-major axis together with the gravitational coefficient. The drag term is set to 0 if it is absent. See sgp4_init! in SatelliteToolboxSgp4.jl for the details.

Extended help

Throws

• ArgumentError: If the mean element theory of omm is not "SGP4", or if omm provides neither the mean motion nor the semi-major axis together with the gravitational coefficient.

Propagators.init!(orbp::OrbitPropagatorTwoBody, orb₀::KeplerianElements) -> Nothing

Initialize the two-body orbit propagator structure orbp using the mean Keplerian elements orb₀ [SI units].

Arguments

• orb₀::KeplerianElements: Initial mean Keplerian elements [SI units].

Propagators.init(
    Val(:J2osc),
    orb₀::KeplerianElements;
    kwargs...
) -> OrbitPropagatorJ2Osculating

Create and initialize the J2 osculating orbit propagator structure using the mean Keplerian elements orb₀ [SI units].

Keywords

• j2c::J2PropagatorConstants: J2 orbit propagator constants (see J2PropagatorConstants). (Default: J2C_EGM2008)

Propagators.init(Val(:J2), orb₀::KeplerianElements; kwargs...) -> OrbitPropagatorJ2

Create and initialize the J2 orbit propagator structure using the mean Keplerian elements orb₀ [SI units].

Keywords

• j2c::J2PropagatorConstants: J2 orbit propagator constants (see J2PropagatorConstants). (Default: J2C_EGM2008)

Propagators.init(
    Val(:J4osc),
    orb₀::KeplerianElements;
    kwargs...
) -> OrbitPropagatorJ4Osculating

Create and initialize the J4 osculating orbit propagator structure using the mean Keplerian elements orb₀ [SI units].

Keywords

• j4c::J4PropagatorConstants: J4 orbit propagator constants (see J4PropagatorConstants). (Default: J4C_EGM2008)

Propagators.init(Val(:J4), orb₀::KeplerianElements; kwargs...) -> OrbitPropagatorJ4

Create and initialize the J4 orbit propagator structure using the mean Keplerian elements orb₀ [SI units].

Keywords

• j4c::J4PropagatorConstants: J4 orbit propagator constants (see J4PropagatorConstants). (Default: J4C_EGM2008)

Propagators.init(
    Val(:SGP4),
    epoch::Number,
    n₀::Number,
    e₀::Number,
    i₀::Number,
    Ω₀::Number,
    ω₀::Number,
    M₀::Number,
    bstar::Number;
    kwargs...
) -> OrbitPropagatorSgp4

Propagators.init(Val(:SGP4), tle::TLE; kwargs...) -> OrbitPropagatorSgp4

Propagators.init(
    Val(:SGP4),
    omm::OrbitMeanElementsMessage;
    kwargs...
) -> OrbitPropagatorSgp4

Create and initialize the SGP4 orbit propagator structure using the initial orbit specified by the arguments. The initialization from an Orbit Mean-Elements Message (OMM) can fail if the message does not describe an SGP4 orbit.

Arguments

• epoch::Number: Epoch of the orbital elements [Julian Day].
• n₀::Number: SGP type "mean" mean motion at epoch [rad/s].
• e₀::Number: "Mean" eccentricity at epoch.
• i₀::Number: "Mean" inclination at epoch [rad].
• Ω₀::Number: "Mean" longitude of the ascending node at epoch [rad].
• ω₀::Number: "Mean" argument of perigee at epoch [rad].
• M₀::Number: "Mean" mean anomaly at epoch [rad].
• bstar::Number: Drag parameter (B*).
• tle::TLE: Two-line elements used for the initialization.
• omm::OrbitMeanElementsMessage: Orbit Mean-Elements Message used for the initialization. Its mean element theory must be "SGP4", and it must provide the mean motion or the semi-major axis together with the gravitational coefficient. The drag term is set to 0 if it is absent. See sgp4_init in SatelliteToolboxSgp4.jl for the details.

Keywords

• sgp4c::Sgp4Constants: SGP4 orbit propagator constants (see Sgp4Constants). The constants in another number type can be obtained with the converting constructor, e.g. Sgp4Constants{Float32}(SGP4C_WGS84). (Default: SGP4C_WGS84)

Extended help

Throws

• ArgumentError: If the mean element theory of omm is not "SGP4", or if omm provides neither the mean motion nor the semi-major axis together with the gravitational coefficient.

Propagators.init(
    Val(:TwoBody),
    orb₀::KeplerianElements;
    kwargs...
) -> OrbitPropagatorTwoBody

Create and initialize the two-body orbit propagator structure using the mean Keplerian elements orb₀ [SI units].

Keywords

• m0::T: Standard gravitational parameter of the central body [m³ / s²]. (Default: TBC_M0)

Propagators.mean_elements(
    orbp::OrbitPropagatorSgp4{Tepoch, T}
) where {Tepoch <: Number, T <: Number} -> KeplerianElements{MeanAnomaly, Tepoch, T}

Return the mean Keplerian elements [SI units] of the SGP4 orbit propagator orbp at the last propagation instant. The initial mean elements are assembled into an Orbit Mean-Elements Message (OMM) whose epoch is updated to that instant with update_sgp4_mean_elements_epoch! of SatelliteToolboxSgp4.jl, which fits a new set of mean elements using a copy of the propagator. The epoch stored in the message is truncated to milliseconds.

Propagators.propagate!(
    orbp::OrbitPropagatorJ2{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

Propagate the orbit of the J2 orbit propagator orbp to Δt [s] after the epoch of the initial mean elements, updating the internal state of orbp.

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.

Remarks

The output is represented in the inertial reference frame of the input elements. The perturbation theory requires an inertial frame with true equator.

Propagators.propagate!(
    orbp::OrbitPropagatorJ2Osculating{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

Propagate the orbit of the J2 osculating orbit propagator orbp to Δt [s] after the epoch of the initial mean elements, updating the internal state of orbp.

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.

Remarks

The output is represented in the inertial reference frame of the input elements. The perturbation theory requires an inertial frame with true equator.

Propagators.propagate!(
    orbp::OrbitPropagatorJ4{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

Propagate the orbit of the J4 orbit propagator orbp to Δt [s] after the epoch of the initial mean elements, updating the internal state of orbp.

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.

Remarks

The output is represented in the inertial reference frame of the input elements. The perturbation theory requires an inertial frame with true equator.

Propagators.propagate!(
    orbp::OrbitPropagatorJ4Osculating{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

Propagate the orbit of the J4 osculating orbit propagator orbp to Δt [s] after the epoch of the initial mean elements, updating the internal state of orbp.

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.

Remarks

The output is represented in the inertial reference frame of the input elements. The perturbation theory requires an inertial frame with true equator.

Propagators.propagate!(
    orbp::OrbitPropagatorSgp4{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

Propagate the orbit of the SGP4 orbit propagator orbp to Δt [s] after the epoch of the TLE, updating the internal state of orbp. The SGP4 kernel works in minutes and kilometers, so the instant and the output are converted to SI units here.

Returns

• SVector{3, T}: Position vector [m] represented in the TEME frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the TEME frame at propagation instant.

Propagators.propagate!(
    orbp::OrbitPropagatorTwoBody{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

Propagate the orbit of the two-body orbit propagator orbp to Δt [s] after the epoch of the initial mean elements, updating the internal state of orbp.

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.

Remarks

The output is represented in the inertial reference frame of the input elements.

_constants(
    pd::PropagatorData
) -> Union{J2PropagatorConstants, J4PropagatorConstants, Number}

Return the constants of the initialized propagator structure pd: the structure with the gravitational constants of the J2 and J4 propagators, or the standard gravitational parameter [m³ / s²] of the two-body propagator.

_constants_fields(constants) -> Vector{PrintedField}

Return the fields that print the propagator constants, which are a J2PropagatorConstants, a J4PropagatorConstants, or the standard gravitational parameter [m³ / s²] of the two-body propagator. The equatorial radius is printed in kilometers.

_copy_field(x) -> typeof(x)

Return the value stored in a propagator field when copying the structure. Nested propagator structures are copied, whereas every other field is immutable and is returned as is.

_create_ad_propagator(
    pd::AbstractMeanElementsPropagator{Tepoch, T}
) where {Tepoch <: Number, T <: Number} -> AbstractMeanElementsPropagator{Tepoch, D}

Create an uninitialized propagator with the same constants as pd but with the element type D = _dual_type(T), which the ForwardDiff Jacobian uses to propagate dual numbers.

_create_fd_propagator(
    pd::AbstractMeanElementsPropagator{Tepoch, T}
) where {Tepoch <: Number, T <: Number} -> typeof(pd)

Create an uninitialized propagator with the same constants as pd that the finite-difference Jacobian uses as scratch space, so it does not clobber the propagator kept initialized by the fitting loop.

_dual_type(::Type{T}) where {T <: Number} -> Type

Return the ForwardDiff.Dual type with six partial derivatives used to differentiate a propagation with element type T with respect to the six components of the state vector.

_fit_decorated(versions::Tuple{String, String}, has_color::Bool) -> String

Return the colored version of a string printed by the fitting algorithm, stored as the second element of versions, if has_color is true. Otherwise, return the plain version stored as its first element.

_fit_mean_elements!(
    pd::AbstractMeanElementsPropagator{Tepoch, T},
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    Tepoch <: Number,
    T <: Number,
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Tepoch, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the propagator pd using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day]. The algorithm is an iterative weighted least-square that propagates the current estimate of the mean state vector to every measurement instant and corrects it using the Jacobian of the propagation. pd is left initialized with the fitted elements. The fitting fails if the residual diverges.

Keywords

• atol::Number: Tolerance for the residual absolute value that stops the iterations. (Default: 2e-4)
• rtol::Number: Tolerance for the relative residual variation that stops the iterations. (Default: 2e-4)
• initial_guess::Union{Nothing, KeplerianElements}: Initial guess for the mean elements. If it is nothing, the closest measurement to mean_elements_epoch is used. (Default: nothing)
• jacobian_method::AbstractJacobianMethod: Method used to compute the Jacobian matrix. (Default: FiniteDiffJacobian())
• jacobian_perturbation::Number: Initial relative state perturbation of the finite-difference Jacobian. (Default: 1e-3)
• jacobian_perturbation_tol::Number: Minimum absolute perturbation of the finite-difference Jacobian. (Default: 1e-7)
• max_iterations::Int: Maximum number of iterations. (Default: 50)
• mean_elements_epoch::Union{Number, DateTime}: Epoch of the fitted mean elements, represented by a Julian Day [UTC] or a DateTime [UTC]. (Default: vjd[end])
• verbose::Bool: If true, the algorithm prints its progress to stdout. (Default: true)
• weight_vector::AbstractVector: Diagonal of the weight matrix of the least-square algorithm, with six elements. (Default: @SVector(ones(Bool, 6)))

Returns

• KeplerianElements{MeanAnomaly, Tepoch, T}: Fitted mean Keplerian elements [SI units].

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the residual increases for three consecutive iterations and exceeds 5e11, indicating that the iterations diverged.

_initial_elements(pd::PropagatorData) -> KeplerianElements{MeanAnomaly}

Return the initial mean elements stored in the initialized propagator structure pd. The osculating propagators return the elements of the propagator they wrap.

_initial_epoch(pd::PropagatorData) -> Number

Return the epoch [Julian Day] of the initial mean elements stored in the initialized propagator structure pd.

_is_initialized(pd::PropagatorData) -> Bool
_is_initialized(sgp4d::Sgp4Propagator) -> Bool

Return whether the propagator structure has been initialized, which is marked by a NaN last propagation instant (see _last_instant) in the structures defined in this package, whereas the SGP4 propagator provides its own predicate.

_j2_mean_elements!(
    j2d::J2Propagator{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> KeplerianElements{MeanAnomaly, Tepoch, T}

Propagate the mean elements of j2d to the instant Δt [s] measured from the epoch of the initial elements, update the propagator structure, and return the mean elements [SI units]. The osculating propagator uses this function directly to avoid computing a state vector from the mean elements that it would discard.

_j2osc_init!(j2oscd::J2OsculatingPropagator, orb₀::KeplerianElements) -> Nothing

Initialize the J2 osculating orbit propagator j2oscd with the mean Keplerian elements orb₀ [SI units] without computing the osculating elements at the initial instant. The callers that propagate the orbit right afterwards use this function, since the osculating elements would be overwritten anyway.

_j4_mean_elements!(
    j4d::J4Propagator{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> KeplerianElements{MeanAnomaly, Tepoch, T}

Propagate the mean elements of j4d to the instant Δt [s] measured from the epoch of the initial elements, update the propagator structure, and return the mean elements [SI units]. The osculating propagator uses this function directly to avoid computing a state vector from the mean elements that it would discard.

_j4osc_init!(j4oscd::J4OsculatingPropagator, orb₀::KeplerianElements) -> Nothing

Initialize the J4 osculating orbit propagator j4oscd with the mean Keplerian elements orb₀ [SI units] without computing the osculating elements at the initial instant. The callers that propagate the orbit right afterwards use this function, since the osculating elements would be overwritten anyway.

_julian_day(epoch::Union{Number, DateTime}) -> Number

Return the epoch as a Julian Day, converting it if it is a DateTime [UTC].

_last_instant(pd::PropagatorData{Tepoch, T}) where {Tepoch <: Number, T <: Number} -> T

Return the last propagation instant [s] measured from the initial elements' epoch stored in the propagator structure pd, which is NaN until the structure is initialized. The osculating propagators read it from the propagator of mean elements they wrap, which is undefined until assigned.

_mean_elements_epoch(
    pd::AbstractMeanElementsPropagator{Tepoch, T}
) where {Tepoch <: Number, T <: Number} -> Tepoch

Return the epoch [Julian Day] of the initial mean elements stored in pd.

_mean_elements_fields(orb₀::KeplerianElements{MeanAnomaly}) -> Vector{PrintedField}

Return the fields that print the initial mean elements orb₀ and their epoch in the rich representation of a propagator structure. The semi-major axis is printed in kilometers and the angles in degrees.

_mean_elements_init!(
    pd::AbstractMeanElementsPropagator,
    orb::KeplerianElements
) -> Nothing

Initialize the propagator pd with the mean elements orb [SI units]. The osculating propagators use the internal initialization, which skips the propagation to the initial instant, because the algorithm always propagates right afterwards.

_mean_elements_jacobian(
    ::FiniteDiffJacobian,
    pd::AbstractMeanElementsPropagator{Tepoch, T},
    Δt::Number,
    x₁::SVector{6, T},
    y₁::SVector{6, T};
    kwargs...
) where {Tepoch <: Number, T <: Number} -> SMatrix{6, 6, T}

_mean_elements_jacobian(
    ::ForwardDiffJacobian,
    pd::AbstractMeanElementsPropagator{Tepoch, T},
    Δt::Number,
    x₁::SVector{6, T},
    y₁::SVector{6, T};
    kwargs...
) where {Tepoch <: Number, T <: Number} -> SMatrix{6, 6, T}

Compute the Jacobian of the state vector y₁ [m; m / s] propagated by Δt [s] with the propagator pd with respect to the initial state vector x₁ [m; m / s] at the epoch of the initial mean elements in pd. The first argument selects the method: finite differences, which perturbs each component of x₁ and propagates the orbit again, or forward-mode automatic differentiation with ForwardDiff.jl, which propagates dual numbers once.

Keywords

• perturbation::Number: Initial relative state perturbation to compute the finite differences. Only used with FiniteDiffJacobian. (Default: T(1e-3))
• perturbation_tol::Number: Tolerance to accept the perturbation. If the computed perturbation is lower than perturbation_tol, we increase it until its absolute value is higher than perturbation_tol. Only used with FiniteDiffJacobian. (Default: T(1e-7))
• pd_ad::Union{Nothing, AbstractMeanElementsPropagator}: Propagator with the dual element type used by the ForwardDiff method, as created by _create_ad_propagator. If it is nothing, a new one is allocated. (Default: nothing)
• pd_fd::Union{Nothing, AbstractMeanElementsPropagator}: Scratch propagator overwritten by the finite-difference method, as created by _create_fd_propagator. If it is nothing, pd itself is used and left initialized with the last perturbed state. (Default: nothing)

_mean_elements_propagate!(
    pd::AbstractMeanElementsPropagator{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

Propagate the orbit using pd to Δt [s] after the epoch of its initial mean elements, returning the position [m] and the velocity [m / s] vectors in the inertial frame.

_mean_elements_propagator(
    pd::AbstractMeanElementsPropagator
) -> Union{J2Propagator, J4Propagator, TwoBodyPropagator}

Return the structure inside pd that stores the initial (orb₀) and the current (orbk) mean elements, which is pd itself for the propagators of mean elements.

_osculating_elements(
    mean_orbk::KeplerianElements{MeanAnomaly, Tepoch, T},
    R₀::Number,
    μm::Number,
    J₂::Number
) where {Tepoch <: Number, T <: Number} -> KeplerianElements{TrueAnomaly, Tepoch, T}

Compute the osculating Keplerian elements [SI units] at the epoch of the mean elements mean_orbk [SI units] by adding the short-period perturbations of the J2 gravitational term described in [1], p. 708-710. The propagator constants are the equatorial radius R₀ [m], the normalized gravitational parameter μm = √(GM / R₀³) [rad / s], and the zonal harmonic J₂ [-]. The returned RAAN, argument of periapsis, and true anomaly are wrapped to the interval [0, 2π).

References

• [1] Vallado, D. A (2013). Fundamentals of Astrodynamics and Applications. 4th ed. Microcosm Press, Hawthorn, CA, USA.

_propagation_fields(Δt::Number) -> Vector{PrintedField}

Return the fields of the section that prints the last propagation instant Δt [s], measured from the epoch of the initial mean elements.

_propagator_eltype(
    ::Type{Tconstants},
    ::Type{Tkepler}
) where {Tconstants <: Number, Tkepler <: Number} -> Type

Return the element type used by a propagator initialized with constants of type Tconstants and Keplerian elements of type Tkepler. If Tkepler is an AbstractFloat, the constants type is used, so that, e.g., Float32 constants select a Float32 propagation regardless of the elements type. Otherwise, the types are promoted, which keeps the propagation differentiable when the elements are ForwardDiff.Dual numbers.

_propagator_name(pd::AbstractMeanElementsPropagator) -> String

Return the name of the propagator pd used in the messages of the fitting algorithm.

_sections(pd::PropagatorData) -> Vector{PrintedSection}

Return the sections of the rich representation of the initialized propagator structure pd: the initial mean elements with their epoch, the secular rates, and the constants. The last propagation instant is appended by the caller. The osculating propagators print the sections of the propagator they wrap, since the short-period corrections do not add any parameter.

_secular_rates_fields(n̄::Number[, ∂Ω::Number, ∂ω::Number]) -> Vector{PrintedField}

Return the fields that print the perturbed mean motion n̄ [rad / s] and, if provided, the RAAN rate ∂Ω [rad / s] and the argument of periapsis rate ∂ω [rad / s] in the rich representation of a propagator structure. The mean motion is printed in revolutions per day and the rates in degrees per day.

_similar_propagator(
    j2oscd::J2OsculatingPropagator{Tepoch},
    ::Type{T}
) where {Tepoch <: Number, T <: Number} -> J2OsculatingPropagator{Tepoch, T}

Create an uninitialized J2 osculating propagator with the same constants as j2oscd converted to the element type T.

_similar_propagator(
    j2d::J2Propagator{Tepoch},
    ::Type{T}
) where {Tepoch <: Number, T <: Number} -> J2Propagator{Tepoch, T}

Create an uninitialized J2 propagator with the same constants as j2d converted to the element type T.

_similar_propagator(
    j4oscd::J4OsculatingPropagator{Tepoch},
    ::Type{T}
) where {Tepoch <: Number, T <: Number} -> J4OsculatingPropagator{Tepoch, T}

Create an uninitialized J4 osculating propagator with the same constants as j4oscd converted to the element type T.

_similar_propagator(
    j4d::J4Propagator{Tepoch},
    ::Type{T}
) where {Tepoch <: Number, T <: Number} -> J4Propagator{Tepoch, T}

Create an uninitialized J4 propagator with the same constants as j4d converted to the element type T.

_similar_propagator(
    tbd::TwoBodyPropagator{Tepoch},
    ::Type{T}
) where {Tepoch <: Number, T <: Number} -> TwoBodyPropagator{Tepoch, T}

Create an uninitialized two-body propagator with the same gravitational parameter as tbd converted to the element type T.

_stats_to_si(stats::NamedTuple) -> NamedTuple

Convert the statistics stats returned by the SGP4 fitting functions of SatelliteToolboxSgp4.jl, whose RMSE values are in kilometers and kilometers per second, to SI units.

_uninitialized_instant(::Type{T}) where {T <: Number} -> T

Return the propagation instant stored in the field Δt by the empty constructors of the propagators of mean elements, NaN converted to T, which marks a structure as not initialized until an initialization function assigns its fields. Hence, T must be able to represent NaN, as every floating-point type and the dual numbers do.

_update_mean_elements_epoch!(
    pd::AbstractMeanElementsPropagator{Tepoch, T},
    orb::KeplerianElements,
    new_epoch::Number
) where {Tepoch <: Number, T <: Number} -> KeplerianElements{MeanAnomaly, Tepoch, T}

Update the epoch of the mean elements orb [SI units] to new_epoch [Julian Day] by propagating them with pd, and initialize pd with the returned elements. The osculating propagators are initialized without computing the osculating elements at the new epoch; the public functions update_*_mean_elements_epoch! complete that step.

fit_j2_mean_elements!(
    j2d::J2Propagator{Tepoch, T},
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    T <: Number,
    Tepoch <: Number,
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Tepoch, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J2 orbit propagator j2d using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

The keywords are the same as in fit_j2_mean_elements, except for j2c, since the constants are those in j2d.

Returns

• KeplerianElements{MeanAnomaly, Tepoch, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Examples

# Allocate a new J2 orbit propagator using a dummy set of Keplerian elements.
julia> j2d = j2_init(KeplerianElements(0.0, 7000e3, 0, 0, 0, 0, 0));

julia> vr_i = [
           [-6792.402703741442, 2192.6458461287293, 0.18851758695295118]  .* 1000,
           [-1781.214419290065, 1619.7795321872854, 6707.771633846665]    .* 1000,
           [ 5693.643675547716, -1192.342828671633, 4123.976025977494]    .* 1000,
           [ 5291.613719530499, -2354.5417593130833, -4175.561367156414]  .* 1000,
           [-2416.3705905186903, -268.74923235392623, -6715.411357310478] .* 1000,
           [-6795.043410709359, 2184.4414321930635, -0.4327055325971031]  .* 1000,
       ];

julia> vv_i = [
           [0.3445760107690598, 1.0395135806993514, 7.393686131436984]    .* 1000,
           [6.875680282038698, -1.864319399615942, 2.270603214569518]     .* 1000,
           [3.8964090757666496, -2.1887896252945875, -5.9960180359219075] .* 1000,
           [-4.470258022565413, 0.5119576359985208, -5.9608372367141635]  .* 1000,
           [-6.647358060413909, 2.495415251255861, 2.292118747543002]     .* 1000,
           [0.3427096905434428, 1.040125572862349, 7.3936887585116855]    .* 1000,
       ];

julia> vjd = [
           2.46002818657856e6
           2.460028200467449e6
           2.460028214356338e6
           2.4600282282452267e6
           2.4600282421341157e6
           2.4600282560230047e6
       ];

julia> orb, P, stats = fit_j2_mean_elements!(j2d, vjd, vr_i, vv_i);
ACTION:   Fitting the mean elements for the J2 propagator.
           Iteration        Position RMSE        Velocity RMSE           Total RMSE       RMSE Variation
                                     [km]             [km / s]                  [ ]
PROGRESS:          4               4.3413           0.00540076              4341.31          0.000476014 %

julia> orb
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.46003e6 (2023-03-24T18:08:40.388)
  Semi-Major Axis   : 7131.634013 km
  Eccentricity      : 0.001142993013
  Inclination       : 98.43659393°
  RA of Asc. Node   : 162.1773906°
  Arg. of Periapsis : 101.2857729°
  Mean Anomaly      : 258.8172342°

julia> stats
(converged = true, iterations = 4, position_rmse = 4341.303234165598, velocity_rmse = 5.400761345997574, total_rmse = 4341.306593549895)

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

fit_j2_mean_elements(
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Float64, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J2 orbit propagator using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

• j2c::J2PropagatorConstants{T}: J2 orbit propagator constants (see J2PropagatorConstants), whose number type T is used in the fitting. (Default: J2C_EGM2008)
• atol::Number: Tolerance for the residual absolute value. If the residual is lower than atol at any iteration, the computation loop stops. (Default: 2e-4)
• rtol::Number: Tolerance for the relative difference between the residuals. If the relative difference between the residuals in two consecutive iterations is lower than rtol, the computation loop stops. (Default: 2e-4)
• initial_guess::Union{Nothing, KeplerianElements}: Initial guess for the mean elements fitting process. If it is nothing, the algorithm will obtain an initial estimate from the osculating elements in vr_i and vv_i. (Default: nothing)
• jacobian_method::AbstractJacobianMethod: Method used to compute the Jacobian matrix. It can be FiniteDiffJacobian() for finite differences or ForwardDiffJacobian() for ForwardDiff.jl automatic differentiation. (Default: FiniteDiffJacobian())
• jacobian_perturbation::Number: Initial state perturbation to compute the finite-difference when calculating the Jacobian matrix. Only used with FiniteDiffJacobian(). (Default: 1e-3)
• jacobian_perturbation_tol::Number: Tolerance to accept the perturbation when calculating the Jacobian matrix. If the computed perturbation is lower than jacobian_perturbation_tol, we increase it until its absolute value is higher than jacobian_perturbation_tol. Only used with FiniteDiffJacobian(). (Default: 1e-7)
• max_iterations::Int: Maximum number of iterations allowed for the least-square fitting. (Default: 50)
• mean_elements_epoch::Union{Number, DateTime}: Epoch of the fitted mean elements, represented by a Julian Day [UTC] or a DateTime [UTC]. (Default: vjd[end])
• verbose::Bool: If true, the algorithm prints debugging information to stdout. (Default: true)
• weight_vector::AbstractVector: Vector with the measurements weights for the least-square algorithm. We assemble the weight matrix W as a diagonal matrix with the elements in weight_vector at its diagonal. (Default: @SVector(ones(Bool, 6)))

Returns

• KeplerianElements{MeanAnomaly, Float64, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Examples

julia> vr_i = [
           [-6792.402703741442, 2192.6458461287293, 0.18851758695295118]  .* 1000,
           [-1781.214419290065, 1619.7795321872854, 6707.771633846665]    .* 1000,
           [ 5693.643675547716, -1192.342828671633, 4123.976025977494]    .* 1000,
           [ 5291.613719530499, -2354.5417593130833, -4175.561367156414]  .* 1000,
           [-2416.3705905186903, -268.74923235392623, -6715.411357310478] .* 1000,
           [-6795.043410709359, 2184.4414321930635, -0.4327055325971031]  .* 1000,
       ];

julia> vv_i = [
           [0.3445760107690598, 1.0395135806993514, 7.393686131436984]    .* 1000,
           [6.875680282038698, -1.864319399615942, 2.270603214569518]     .* 1000,
           [3.8964090757666496, -2.1887896252945875, -5.9960180359219075] .* 1000,
           [-4.470258022565413, 0.5119576359985208, -5.9608372367141635]  .* 1000,
           [-6.647358060413909, 2.495415251255861, 2.292118747543002]     .* 1000,
           [0.3427096905434428, 1.040125572862349, 7.3936887585116855]    .* 1000,
       ];

julia> vjd = [
           2.46002818657856e6
           2.460028200467449e6
           2.460028214356338e6
           2.4600282282452267e6
           2.4600282421341157e6
           2.4600282560230047e6
       ];

julia> orb, P, stats = fit_j2_mean_elements(vjd, vr_i, vv_i);
ACTION:   Fitting the mean elements for the J2 propagator.
           Iteration        Position RMSE        Velocity RMSE           Total RMSE       RMSE Variation
                                     [km]             [km / s]                  [ ]
PROGRESS:          4               4.3413           0.00540076              4341.31          0.000476014 %

julia> orb
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.46003e6 (2023-03-24T18:08:40.388)
  Semi-Major Axis   : 7131.634013 km
  Eccentricity      : 0.001142993013
  Inclination       : 98.43659393°
  RA of Asc. Node   : 162.1773906°
  Arg. of Periapsis : 101.2857729°
  Mean Anomaly      : 258.8172342°

julia> stats
(converged = true, iterations = 4, position_rmse = 4341.303234165598, velocity_rmse = 5.400761345997574, total_rmse = 4341.306593549895)

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

fit_j2osc_mean_elements!(
    j2oscd::J2OsculatingPropagator{Tepoch, T},
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    T <: Number,
    Tepoch <: Number,
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Tepoch, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J2 osculating orbit propagator j2oscd using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

The keywords are the same as in fit_j2osc_mean_elements, except for j2c, since the constants are those in j2oscd.

Returns

• KeplerianElements{MeanAnomaly, Tepoch, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Examples

# Allocate a new J2 osculating orbit propagator using a dummy set of Keplerian elements.
julia> j2oscd = j2osc_init(KeplerianElements(0.0, 7000e3, 0, 0, 0, 0, 0));

julia> vr_i = [
           [-6792.402703741442, 2192.6458461287293, 0.18851758695295118] .* 1000,
           [-6357.88873265975, 2391.9476768911686, 2181.838771262736] .* 1000
       ];

julia> vv_i = [
           [0.3445760107690598, 1.0395135806993514, 7.393686131436984] .* 1000,
           [2.5285015912807003, 0.27812476784300005, 7.030323100703928] .* 1000
       ];

julia> vjd = [
           2.46002818657856e6,
           2.460028190050782e6
       ];

julia> orb, P, stats = fit_j2osc_mean_elements!(j2oscd, vjd, vr_i, vv_i);
ACTION:   Fitting the mean elements for the J2 osculating propagator.
           Iteration        Position RMSE        Velocity RMSE           Total RMSE       RMSE Variation
                                     [km]             [km / s]                  [ ]
PROGRESS:          4          1.69072e-05           0.00260088              2.60093         -2.38817e-10 %

julia> orb
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.46003e6 (2023-03-24T16:33:40.388)
  Semi-Major Axis   : 7135.801151 km
  Eccentricity      : 0.001353825508
  Inclination       : 98.43042292°
  RA of Asc. Node   : 162.1131669°
  Arg. of Periapsis : 64.92555131°
  Mean Anomaly      : 313.1984092°

julia> stats
(converged = true, iterations = 4, position_rmse = 0.01690717402027459, velocity_rmse = 2.6008770843982476, total_rmse = 2.6009320369208573)

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

fit_j2osc_mean_elements(
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Float64, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J2 osculating orbit propagator using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

• j2c::J2PropagatorConstants{T}: J2 orbit propagator constants (see J2PropagatorConstants), whose number type T is used in the fitting. (Default: J2C_EGM2008)
• atol::Number: Tolerance for the residual absolute value. If the residual is lower than atol at any iteration, the computation loop stops. (Default: 2e-4)
• rtol::Number: Tolerance for the relative difference between the residuals. If the relative difference between the residuals in two consecutive iterations is lower than rtol, the computation loop stops. (Default: 2e-4)
• initial_guess::Union{Nothing, KeplerianElements}: Initial guess for the mean elements fitting process. If it is nothing, the algorithm will obtain an initial estimate from the osculating elements in vr_i and vv_i. (Default: nothing)
• jacobian_method::AbstractJacobianMethod: Method used to compute the Jacobian matrix. It can be FiniteDiffJacobian() for finite differences or ForwardDiffJacobian() for ForwardDiff.jl automatic differentiation. (Default: FiniteDiffJacobian())
• jacobian_perturbation::Number: Initial state perturbation to compute the finite-difference when calculating the Jacobian matrix. Only used with FiniteDiffJacobian(). (Default: 1e-3)
• jacobian_perturbation_tol::Number: Tolerance to accept the perturbation when calculating the Jacobian matrix. If the computed perturbation is lower than jacobian_perturbation_tol, we increase it until its absolute value is higher than jacobian_perturbation_tol. Only used with FiniteDiffJacobian(). (Default: 1e-7)
• max_iterations::Int: Maximum number of iterations allowed for the least-square fitting. (Default: 50)
• mean_elements_epoch::Union{Number, DateTime}: Epoch of the fitted mean elements, represented by a Julian Day [UTC] or a DateTime [UTC]. (Default: vjd[end])
• verbose::Bool: If true, the algorithm prints debugging information to stdout. (Default: true)
• weight_vector::AbstractVector: Vector with the measurements weights for the least-square algorithm. We assemble the weight matrix W as a diagonal matrix with the elements in weight_vector at its diagonal. (Default: @SVector(ones(Bool, 6)))

Returns

• KeplerianElements{MeanAnomaly, Float64, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Examples

julia> vr_i = [
           [-6792.402703741442, 2192.6458461287293, 0.18851758695295118] .* 1000,
           [-6357.88873265975, 2391.9476768911686, 2181.838771262736] .* 1000
       ];

julia> vv_i = [
           [0.3445760107690598, 1.0395135806993514, 7.393686131436984] .* 1000,
           [2.5285015912807003, 0.27812476784300005, 7.030323100703928] .* 1000
       ];

julia> vjd = [
           2.46002818657856e6,
           2.460028190050782e6
       ];

julia> orb, P, stats = fit_j2osc_mean_elements(vjd, vr_i, vv_i);
ACTION:   Fitting the mean elements for the J2 osculating propagator.
           Iteration        Position RMSE        Velocity RMSE           Total RMSE       RMSE Variation
                                     [km]             [km / s]                  [ ]
PROGRESS:          4          1.69072e-05           0.00260088              2.60093         -2.38817e-10 %

julia> orb
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.46003e6 (2023-03-24T16:33:40.388)
  Semi-Major Axis   : 7135.801151 km
  Eccentricity      : 0.001353825508
  Inclination       : 98.43042292°
  RA of Asc. Node   : 162.1131669°
  Arg. of Periapsis : 64.92555131°
  Mean Anomaly      : 313.1984092°

julia> stats
(converged = true, iterations = 4, position_rmse = 0.01690717402027459, velocity_rmse = 2.6008770843982476, total_rmse = 2.6009320369208573)

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

fit_j4_mean_elements!(
    j4d::J4Propagator{Tepoch, T},
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    T <: Number,
    Tepoch <: Number,
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Tepoch, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J4 orbit propagator j4d using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

The keywords are the same as in fit_j4_mean_elements, except for j4c, since the constants are those in j4d.

Returns

• KeplerianElements{MeanAnomaly, Tepoch, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Examples

# Allocate a new J4 orbit propagator using a dummy set of Keplerian elements.
julia> j4d = j4_init(KeplerianElements(0.0, 7000e3, 0, 0, 0, 0, 0));

julia> vr_i = [
           [-6792.402703741442, 2192.6458461287293, 0.18851758695295118]  .* 1000,
           [-1781.214419290065, 1619.7795321872854, 6707.771633846665]    .* 1000,
           [ 5693.643675547716, -1192.342828671633, 4123.976025977494]    .* 1000,
           [ 5291.613719530499, -2354.5417593130833, -4175.561367156414]  .* 1000,
           [-2416.3705905186903, -268.74923235392623, -6715.411357310478] .* 1000,
           [-6795.043410709359, 2184.4414321930635, -0.4327055325971031]  .* 1000,
       ];

julia> vv_i = [
           [0.3445760107690598, 1.0395135806993514, 7.393686131436984]    .* 1000,
           [6.875680282038698, -1.864319399615942, 2.270603214569518]     .* 1000,
           [3.8964090757666496, -2.1887896252945875, -5.9960180359219075] .* 1000,
           [-4.470258022565413, 0.5119576359985208, -5.9608372367141635]  .* 1000,
           [-6.647358060413909, 2.495415251255861, 2.292118747543002]     .* 1000,
           [0.3427096905434428, 1.040125572862349, 7.3936887585116855]    .* 1000,
       ];

julia> vjd = [
           2.46002818657856e6
           2.460028200467449e6
           2.460028214356338e6
           2.4600282282452267e6
           2.4600282421341157e6
           2.4600282560230047e6
       ];

julia> orb, P, stats = fit_j4_mean_elements!(j4d, vjd, vr_i, vv_i);
ACTION:   Fitting the mean elements for the J4 propagator.
           Iteration        Position RMSE        Velocity RMSE           Total RMSE       RMSE Variation
                                     [km]             [km / s]                  [ ]
PROGRESS:          4              4.33863           0.00539961              4338.63          0.000476165 %

julia> orb
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.46003e6 (2023-03-24T18:08:40.388)
  Semi-Major Axis   : 7131.636674 km
  Eccentricity      : 0.001142978092
  Inclination       : 98.43659578°
  RA of Asc. Node   : 162.1773538°
  Arg. of Periapsis : 101.2819928°
  Mean Anomaly      : 258.8210223°

julia> stats
(converged = true, iterations = 4, position_rmse = 4338.627383014923, velocity_rmse = 5.399612174061325, total_rmse = 4338.630743040775)

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

fit_j4_mean_elements(
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Float64, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J4 orbit propagator using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

• j4c::J4PropagatorConstants{T}: J4 orbit propagator constants (see J4PropagatorConstants), whose number type T is used in the fitting. (Default: J4C_EGM2008)
• atol::Number: Tolerance for the residual absolute value. If the residual is lower than atol at any iteration, the computation loop stops. (Default: 2e-4)
• rtol::Number: Tolerance for the relative difference between the residuals. If the relative difference between the residuals in two consecutive iterations is lower than rtol, the computation loop stops. (Default: 2e-4)
• initial_guess::Union{Nothing, KeplerianElements}: Initial guess for the mean elements fitting process. If it is nothing, the algorithm will obtain an initial estimate from the osculating elements in vr_i and vv_i. (Default: nothing)
• jacobian_method::AbstractJacobianMethod: Method used to compute the Jacobian matrix. It can be FiniteDiffJacobian() for finite differences or ForwardDiffJacobian() for ForwardDiff.jl automatic differentiation. (Default: FiniteDiffJacobian())
• jacobian_perturbation::Number: Initial state perturbation to compute the finite-difference when calculating the Jacobian matrix. Only used with FiniteDiffJacobian(). (Default: 1e-3)
• jacobian_perturbation_tol::Number: Tolerance to accept the perturbation when calculating the Jacobian matrix. If the computed perturbation is lower than jacobian_perturbation_tol, we increase it until its absolute value is higher than jacobian_perturbation_tol. Only used with FiniteDiffJacobian(). (Default: 1e-7)
• max_iterations::Int: Maximum number of iterations allowed for the least-square fitting. (Default: 50)
• mean_elements_epoch::Union{Number, DateTime}: Epoch of the fitted mean elements, represented by a Julian Day [UTC] or a DateTime [UTC]. (Default: vjd[end])
• verbose::Bool: If true, the algorithm prints debugging information to stdout. (Default: true)
• weight_vector::AbstractVector: Vector with the measurements weights for the least-square algorithm. We assemble the weight matrix W as a diagonal matrix with the elements in weight_vector at its diagonal. (Default: @SVector(ones(Bool, 6)))

Returns

• KeplerianElements{MeanAnomaly, Float64, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Examples

julia> vr_i = [
           [-6792.402703741442, 2192.6458461287293, 0.18851758695295118]  .* 1000,
           [-1781.214419290065, 1619.7795321872854, 6707.771633846665]    .* 1000,
           [ 5693.643675547716, -1192.342828671633, 4123.976025977494]    .* 1000,
           [ 5291.613719530499, -2354.5417593130833, -4175.561367156414]  .* 1000,
           [-2416.3705905186903, -268.74923235392623, -6715.411357310478] .* 1000,
           [-6795.043410709359, 2184.4414321930635, -0.4327055325971031]  .* 1000,
       ];

julia> vv_i = [
           [0.3445760107690598, 1.0395135806993514, 7.393686131436984]    .* 1000,
           [6.875680282038698, -1.864319399615942, 2.270603214569518]     .* 1000,
           [3.8964090757666496, -2.1887896252945875, -5.9960180359219075] .* 1000,
           [-4.470258022565413, 0.5119576359985208, -5.9608372367141635]  .* 1000,
           [-6.647358060413909, 2.495415251255861, 2.292118747543002]     .* 1000,
           [0.3427096905434428, 1.040125572862349, 7.3936887585116855]    .* 1000,
       ];

julia> vjd = [
           2.46002818657856e6
           2.460028200467449e6
           2.460028214356338e6
           2.4600282282452267e6
           2.4600282421341157e6
           2.4600282560230047e6
       ];

julia> orb, P, stats = fit_j4_mean_elements(vjd, vr_i, vv_i);
ACTION:   Fitting the mean elements for the J4 propagator.
           Iteration        Position RMSE        Velocity RMSE           Total RMSE       RMSE Variation
                                     [km]             [km / s]                  [ ]
PROGRESS:          4              4.33863           0.00539961              4338.63          0.000476165 %

julia> orb
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.46003e6 (2023-03-24T18:08:40.388)
  Semi-Major Axis   : 7131.636674 km
  Eccentricity      : 0.001142978092
  Inclination       : 98.43659578°
  RA of Asc. Node   : 162.1773538°
  Arg. of Periapsis : 101.2819928°
  Mean Anomaly      : 258.8210223°

julia> stats
(converged = true, iterations = 4, position_rmse = 4338.627383014923, velocity_rmse = 5.399612174061325, total_rmse = 4338.630743040775)

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

fit_j4osc_mean_elements!(
    j4oscd::J4OsculatingPropagator{Tepoch, T},
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    T <: Number,
    Tepoch <: Number,
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Tepoch, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J4 osculating orbit propagator j4oscd using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

The keywords are the same as in fit_j4osc_mean_elements, except for j4c, since the constants are those in j4oscd.

Returns

• KeplerianElements{MeanAnomaly, Tepoch, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Examples

# Allocate a new J4 osculating orbit propagator using a dummy set of Keplerian elements.
julia> j4oscd = j4osc_init(KeplerianElements(0.0, 7000e3, 0, 0, 0, 0, 0));

julia> vr_i = [
           [-6792.402703741442, 2192.6458461287293, 0.18851758695295118] .* 1000,
           [-6357.88873265975, 2391.9476768911686, 2181.838771262736] .* 1000
       ];

julia> vv_i = [
           [0.3445760107690598, 1.0395135806993514, 7.393686131436984] .* 1000,
           [2.5285015912807003, 0.27812476784300005, 7.030323100703928] .* 1000
       ];

julia> vjd = [
           2.46002818657856e6,
           2.460028190050782e6
       ];

julia> orb, P, stats = fit_j4osc_mean_elements!(j4oscd, vjd, vr_i, vv_i);
ACTION:   Fitting the mean elements for the J4 osculating propagator.
           Iteration        Position RMSE        Velocity RMSE           Total RMSE       RMSE Variation
                                     [km]             [km / s]                  [ ]
PROGRESS:          4          1.68763e-05           0.00259611              2.59616          1.08586e-09 %

julia> orb
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.46003e6 (2023-03-24T16:33:40.388)
  Semi-Major Axis   : 7135.792461 km
  Eccentricity      : 0.001353135365
  Inclination       : 98.4304116°
  RA of Asc. Node   : 162.1131631°
  Arg. of Periapsis : 64.96868276°
  Mean Anomaly      : 313.1552992°

julia> stats
(converged = true, iterations = 4, position_rmse = 0.016876290513770688, velocity_rmse = 2.596109924485644, total_rmse = 2.596164776972825)

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

fit_j4osc_mean_elements(
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Float64, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the J4 osculating orbit propagator using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

• j4c::J4PropagatorConstants{T}: J4 orbit propagator constants (see J4PropagatorConstants), whose number type T is used in the fitting. (Default: J4C_EGM2008)
• atol::Number: Tolerance for the residual absolute value. If the residual is lower than atol at any iteration, the computation loop stops. (Default: 2e-4)
• rtol::Number: Tolerance for the relative difference between the residuals. If the relative difference between the residuals in two consecutive iterations is lower than rtol, the computation loop stops. (Default: 2e-4)
• initial_guess::Union{Nothing, KeplerianElements}: Initial guess for the mean elements fitting process. If it is nothing, the algorithm will obtain an initial estimate from the osculating elements in vr_i and vv_i. (Default: nothing)
• jacobian_method::AbstractJacobianMethod: Method used to compute the Jacobian matrix. It can be FiniteDiffJacobian() for finite differences or ForwardDiffJacobian() for ForwardDiff.jl automatic differentiation. (Default: FiniteDiffJacobian())
• jacobian_perturbation::Number: Initial state perturbation to compute the finite-difference when calculating the Jacobian matrix. Only used with FiniteDiffJacobian(). (Default: 1e-3)
• jacobian_perturbation_tol::Number: Tolerance to accept the perturbation when calculating the Jacobian matrix. If the computed perturbation is lower than jacobian_perturbation_tol, we increase it until its absolute value is higher than jacobian_perturbation_tol. Only used with FiniteDiffJacobian(). (Default: 1e-7)
• max_iterations::Int: Maximum number of iterations allowed for the least-square fitting. (Default: 50)
• mean_elements_epoch::Union{Number, DateTime}: Epoch of the fitted mean elements, represented by a Julian Day [UTC] or a DateTime [UTC]. (Default: vjd[end])
• verbose::Bool: If true, the algorithm prints debugging information to stdout. (Default: true)
• weight_vector::AbstractVector: Vector with the measurements weights for the least-square algorithm. We assemble the weight matrix W as a diagonal matrix with the elements in weight_vector at its diagonal. (Default: @SVector(ones(Bool, 6)))

Returns

• KeplerianElements{MeanAnomaly, Float64, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Examples

julia> vr_i = [
           [-6792.402703741442, 2192.6458461287293, 0.18851758695295118] .* 1000,
           [-6357.88873265975, 2391.9476768911686, 2181.838771262736] .* 1000
       ];

julia> vv_i = [
           [0.3445760107690598, 1.0395135806993514, 7.393686131436984] .* 1000,
           [2.5285015912807003, 0.27812476784300005, 7.030323100703928] .* 1000
       ];

julia> vjd = [
           2.46002818657856e6,
           2.460028190050782e6
       ];

julia> orb, P, stats = fit_j4osc_mean_elements(vjd, vr_i, vv_i);
ACTION:   Fitting the mean elements for the J4 osculating propagator.
           Iteration        Position RMSE        Velocity RMSE           Total RMSE       RMSE Variation
                                     [km]             [km / s]                  [ ]
PROGRESS:          4          1.68763e-05           0.00259611              2.59616          1.08586e-09 %

julia> orb
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.46003e6 (2023-03-24T16:33:40.388)
  Semi-Major Axis   : 7135.792461 km
  Eccentricity      : 0.001353135365
  Inclination       : 98.4304116°
  RA of Asc. Node   : 162.1131631°
  Arg. of Periapsis : 64.96868276°
  Mean Anomaly      : 313.1552992°

julia> stats
(converged = true, iterations = 4, position_rmse = 0.016876290513770688, velocity_rmse = 2.596109924485644, total_rmse = 2.596164776972825)

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

fit_twobody_mean_elements!(
    tbd::TwoBodyPropagator{Tepoch, T},
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    Tepoch <: Number,
    T <: Number,
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Tepoch, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the two-body orbit propagator tbd using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

The keywords are the same as in fit_twobody_mean_elements, except for m0, since the gravitational parameter is that in tbd.

Returns

• KeplerianElements{MeanAnomaly, Tepoch, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Examples

# Allocate a new two-body orbit propagator using a dummy set of Keplerian elements.
julia> tbd = twobody_init(KeplerianElements(0.0, 7000e3, 0, 0, 0, 0, 0));

julia> vr_i = [
           [-6792.402703741442, 2192.6458461287293, 0.18851758695295118] .* 1000,
           [-6357.88873265975, 2391.9476768911686, 2181.838771262736] .* 1000
       ];

julia> vv_i = [
           [0.3445760107690598, 1.0395135806993514, 7.393686131436984] .* 1000,
           [2.5285015912807003, 0.27812476784300005, 7.030323100703928] .* 1000
       ];

julia> vjd = [
           2.46002818657856e6,
           2.460028190050782e6
       ];

julia> orb, P, stats = fit_twobody_mean_elements!(tbd, vjd, vr_i, vv_i);
ACTION:   Fitting the mean elements for the two-body propagator.
           Iteration        Position RMSE        Velocity RMSE           Total RMSE       RMSE Variation
                                     [km]             [km / s]                  [ ]
PROGRESS:          3          1.67397e-06           0.00142531              1.42531         -4.87682e-05 %

julia> orb
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.46003e6 (2023-03-24T16:33:40.388)
  Semi-Major Axis   : 7139.282635 km
  Eccentricity      : 0.001327104531
  Inclination       : 98.42538016°
  RA of Asc. Node   : 162.1096997°
  Arg. of Periapsis : 79.45743611°
  Mean Anomaly      : 298.683562°

julia> stats
(converged = true, iterations = 3, position_rmse = 0.0016739746758051223, velocity_rmse = 1.4253086768036645, total_rmse = 1.425309659815378)

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

fit_twobody_mean_elements(
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {
    Tjd <: Number,
    Tv <: AbstractVector
} -> KeplerianElements{MeanAnomaly, Float64, T}, SMatrix{6, 6, T}, NamedTuple

Fit a set of mean Keplerian elements for the two-body orbit propagator using the osculating elements represented by a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] represented in an inertial reference frame at instants in the array vjd [Julian Day].

Keywords

• m0::T: Standard gravitational parameter of the central body [m³ / s²], whose number type T is used in the fitting. (Default: TBC_M0)
• atol::Number: Tolerance for the residual absolute value. If the residual is lower than atol at any iteration, the computation loop stops. (Default: 2e-4)
• rtol::Number: Tolerance for the relative difference between the residuals. If the relative difference between the residuals in two consecutive iterations is lower than rtol, the computation loop stops. (Default: 2e-4)
• initial_guess::Union{Nothing, KeplerianElements}: Initial guess for the mean elements fitting process. If it is nothing, the algorithm will obtain an initial estimate from the osculating elements in vr_i and vv_i. (Default: nothing)
• jacobian_method::AbstractJacobianMethod: Method used to compute the Jacobian matrix. It can be FiniteDiffJacobian() for finite differences or ForwardDiffJacobian() for ForwardDiff.jl automatic differentiation. (Default: FiniteDiffJacobian())
• jacobian_perturbation::Number: Initial state perturbation to compute the finite-difference when calculating the Jacobian matrix. Only used with FiniteDiffJacobian(). (Default: 1e-3)
• jacobian_perturbation_tol::Number: Tolerance to accept the perturbation when calculating the Jacobian matrix. If the computed perturbation is lower than jacobian_perturbation_tol, we increase it until its absolute value is higher than jacobian_perturbation_tol. Only used with FiniteDiffJacobian(). (Default: 1e-7)
• max_iterations::Int: Maximum number of iterations allowed for the least-square fitting. (Default: 50)
• mean_elements_epoch::Union{Number, DateTime}: Epoch of the fitted mean elements, represented by a Julian Day [UTC] or a DateTime [UTC]. (Default: vjd[end])
• verbose::Bool: If true, the algorithm prints debugging information to stdout. (Default: true)
• weight_vector::AbstractVector: Vector with the measurements weights for the least-square algorithm. We assemble the weight matrix W as a diagonal matrix with the elements in weight_vector at its diagonal. (Default: @SVector(ones(Bool, 6)))

Returns

• KeplerianElements{MeanAnomaly, Float64, T}: Fitted Keplerian elements.

• SMatrix{6, 6, T}: Final covariance matrix of the least-square algorithm.

• NamedTuple: Statistics of the least-square algorithm with the following fields:

  • converged::Bool: true if the iterations stopped because the residue was lower than atol or its relative variation was lower than rtol, or false if they stopped by reaching max_iterations.
  • iterations::Int: Number of iterations performed.
  • position_rmse::T: RMSE of the position residue in the last iteration [m].
  • velocity_rmse::T: RMSE of the velocity residue in the last iteration [m / s].
  • total_rmse::T: Weighted RMSE of the residue in the last iteration.

  The statistics refer to the fitting of the mean elements. If their epoch is updated afterward to match mean_elements_epoch, the statistics of that update are not returned.

Examples

julia> vr_i = [
           [-6792.402703741442, 2192.6458461287293, 0.18851758695295118] .* 1000,
           [-6357.88873265975, 2391.9476768911686, 2181.838771262736] .* 1000
       ];

julia> vv_i = [
           [0.3445760107690598, 1.0395135806993514, 7.393686131436984] .* 1000,
           [2.5285015912807003, 0.27812476784300005, 7.030323100703928] .* 1000
       ];

julia> vjd = [
           2.46002818657856e6,
           2.460028190050782e6
       ];

julia> orb, P, stats = fit_twobody_mean_elements(vjd, vr_i, vv_i);
ACTION:   Fitting the mean elements for the two-body propagator.
           Iteration        Position RMSE        Velocity RMSE           Total RMSE       RMSE Variation
                                     [km]             [km / s]                  [ ]
PROGRESS:          3          1.67397e-06           0.00142531              1.42531         -4.87682e-05 %

julia> orb
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.46003e6 (2023-03-24T16:33:40.388)
  Semi-Major Axis   : 7139.282635 km
  Eccentricity      : 0.001327104531
  Inclination       : 98.42538016°
  RA of Asc. Node   : 162.1096997°
  Arg. of Periapsis : 79.45743611°
  Mean Anomaly      : 298.683562°

julia> stats
(converged = true, iterations = 3, position_rmse = 0.0016739746758051223, velocity_rmse = 1.4253086768036645, total_rmse = 1.425309659815378)

Extended help

Throws

• ArgumentError: If vjd, vr_i, and vv_i do not have the same length, if weight_vector does not have six elements, or if max_iterations is lower than 1.
• MeanElementsFitDivergenceError: If the least-square iterations diverge.

j2!(
    j2d::J2Propagator{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

Propagate the orbit defined in j2d (see J2Propagator) to Δt [s] after the epoch of the input mean elements in j2d.

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.

Remarks

The inertial frame in which the output is represented depends on which frame was used to generate the orbit parameters. Notice that the perturbation theory requires an inertial frame with true equator.

j2(
    Δt::Number,
    orb₀::KeplerianElements;
    kwargs...
) -> SVector{3, T}, SVector{3, T}, J2Propagator

Initialize the J2 propagator structure using the input elements orb₀ [SI units] and propagate the orbit until the time Δt [s].

Keywords

• j2c::J2PropagatorConstants: J2 orbit propagator constants (see J2PropagatorConstants). (Default: J2C_EGM2008)

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.
• J2Propagator: Structure with the initialized propagator.

Remarks

The inertial frame in which the output is represented depends on which frame was used to generate the orbit parameters. Notice that the perturbation theory requires an inertial frame with true equator.

j2_init!(j2d::J2Propagator, orb₀::KeplerianElements) -> Nothing

Initialize the J2 orbit propagator structure j2d using the mean Keplerian elements orb₀ [SI units].

j2_init(orb₀::KeplerianElements; kwargs...) -> J2Propagator

Create and initialize the J2 orbit propagator structure using the mean Keplerian elements orb₀ [SI units].

Keywords

• j2c::J2PropagatorConstants: J2 orbit propagator constants (see J2PropagatorConstants). (Default: J2C_EGM2008)

j2osc!(
    j2oscd::J2OsculatingPropagator{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

Propagate the orbit defined in j2oscd (see J2OsculatingPropagator) to Δt [s] after the epoch of the input mean elements in j2oscd.

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.

Remarks

The inertial frame in which the output is represented depends on which frame was used to generate the orbit parameters. Notice that the perturbation theory requires an inertial frame with true equator.

j2osc(
    Δt::Number,
    orb₀::KeplerianElements;
    kwargs...
) -> SVector{3, T}, SVector{3, T}, J2OsculatingPropagator

Initialize the J2 osculating propagator structure using the input elements orb₀ [SI units] and propagate the orbit until the time Δt [s].

Keywords

• j2c::J2PropagatorConstants{T}: J2 orbit propagator constants (see J2PropagatorConstants). (Default: J2C_EGM2008)

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.
• J2OsculatingPropagator: Structure with the initialized propagator.

Remarks

The inertial frame in which the output is represented depends on which frame was used to generate the orbit parameters. Notice that the perturbation theory requires an inertial frame with true equator.

j2osc_init!(j2oscd::J2OsculatingPropagator, orb₀::KeplerianElements) -> Nothing

Initialize the J2 osculating orbit propagator structure j2oscd using the mean Keplerian elements orb₀ [SI units].

j2osc_init(orb₀::KeplerianElements; kwargs...) -> J2OsculatingPropagator

Create and initialize the J2 osculating orbit propagator structure using the mean Keplerian elements orb₀ [SI units].

Keywords

• j2c::J2PropagatorConstants: J2 orbit propagator constants (see J2PropagatorConstants). (Default: J2C_EGM2008)

j4!(
    j4d::J4Propagator{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

Propagate the orbit defined in j4d (see J4Propagator) to Δt [s] after the epoch of the input mean elements in j4d.

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.

Remarks

The inertial frame in which the output is represented depends on which frame was used to generate the orbit parameters. Notice that the perturbation theory requires an inertial frame with true equator.

j4(
    Δt::Number,
    orb₀::KeplerianElements;
    kwargs...
) -> SVector{3, T}, SVector{3, T}, J4Propagator

Initialize the J4 propagator structure using the input elements orb₀ and propagate the orbit until the time Δt [s].

Keywords

• j4c::J4PropagatorConstants: J4 orbit propagator constants (see J4PropagatorConstants). (Default: J4C_EGM2008)

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.
• J4Propagator: Structure with the initialized propagator.

Remarks

The inertial frame in which the output is represented depends on which frame was used to generate the orbit parameters. Notice that the perturbation theory requires an inertial frame with true equator.

j4_init!(j4d::J4Propagator, orb₀::KeplerianElements) -> Nothing

Initialize the J4 orbit propagator structure j4d using the mean Keplerian elements orb₀ [SI units].

j4_init(orb₀::KeplerianElements; kwargs...) -> J4Propagator

Create and initialize the J4 orbit propagator structure using the mean Keplerian elements orb₀ [SI units].

Keywords

• j4c::J4PropagatorConstants: J4 orbit propagator constants (see J4PropagatorConstants). (Default: J4C_EGM2008)

j4osc!(
    j4oscd::J4OsculatingPropagator{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

Propagate the orbit defined in j4oscd (see J4OsculatingPropagator) to Δt [s] after the epoch of the input mean elements in j4oscd.

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.

Remarks

The inertial frame in which the output is represented depends on which frame was used to generate the orbit parameters. Notice that the perturbation theory requires an inertial frame with true equator.

j4osc(
    Δt::Number,
    orb₀::KeplerianElements;
    kwargs...
) -> SVector{3, T}, SVector{3, T}, J4OsculatingPropagator

Initialize the J4 osculating propagator structure using the input elements orb₀ and propagate the orbit until the time Δt [s].

Keywords

• j4c::J4PropagatorConstants{T}: J4 orbit propagator constants (see J4PropagatorConstants). (Default: J4C_EGM2008)

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.
• J4OsculatingPropagator: Structure with the initialized propagator.

Remarks

The inertial frame in which the output is represented depends on which frame was used to generate the orbit parameters. Notice that the perturbation theory requires an inertial frame with true equator.

j4osc_init!(j4oscd::J4OsculatingPropagator, orb₀::KeplerianElements) -> Nothing

Initialize the J4 osculating orbit propagator structure j4oscd using the mean Keplerian elements orb₀ [SI units].

j4osc_init(orb₀::KeplerianElements; kwargs...) -> J4OsculatingPropagator

Create and initialize the J4 osculating orbit propagator structure using the mean Keplerian elements orb₀ [SI units].

Keywords

• j4c::J4PropagatorConstants: J4 orbit propagator constants (see J4PropagatorConstants). (Default: J4C_EGM2008)

twobody!(
    tbd::TwoBodyPropagator{Tepoch, T},
    Δt::Number
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

Propagate the orbit defined in tbd (see TwoBodyPropagator) to Δt [s] after the epoch of the input mean elements in tbd.

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.

Remarks

The inertial frame in which the output is represented depends on which frame was used to generate the orbit parameters.

twobody(
    Δt::Number,
    orb₀::KeplerianElements;
    kwargs...
) -> SVector{3, T}, SVector{3, T}, TwoBodyPropagator

Initialize the two-body propagator structure using the input elements orb₀ and propagate the orbit until the time Δt [s].

Keywords

• m0::T: Standard gravitational parameter of the central body [m³ / s²]. (Default: TBC_M0)

Returns

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.
• TwoBodyPropagator: Structure with the initialized propagator.

Remarks

The inertial frame in which the output is represented depends on which frame was used to generate the orbit parameters.

twobody_init!(tbd::TwoBodyPropagator, orb₀::KeplerianElements) -> Nothing

Initialize the two-body propagator structure tbd using the mean Keplerian elements orb₀ [SI units].

twobody_init(orb₀::KeplerianElements; kwargs...) -> TwoBodyPropagator

Create and initialize the two-body propagator structure using the mean Keplerian elements orb₀ [SI units].

Keywords

• m0::T: Standard gravitational parameter of the central body [m³ / s²]. (Default: TBC_M0)

update_j2_mean_elements_epoch!(
    j2d::J2Propagator,
    orb::KeplerianElements,
    new_epoch::Union{Number, DateTime}
) -> KeplerianElements{MeanAnomaly}

Update the epoch of the mean elements orb using the propagator j2d to new_epoch, which can be represented by a Julian Day or a DateTime.

Examples

julia> orb = KeplerianElements(
           DateTime("2023-01-01") |> datetime2julian,
           7190.982e3,
           0.001111,
           98.405 |> deg2rad,
           90     |> deg2rad,
           200    |> deg2rad,
           45     |> deg2rad
       )
KeplerianElements{TrueAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-01T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.0°
  Arg. of Periapsis : 200.0°
  True Anomaly      : 45.0°

# Allocate a new J2 orbit propagator using the created Keplerian elements. Notice that any
# set of Keplerian elements can be used here.
julia> j2d = j2_init(orb);

julia> update_j2_mean_elements_epoch!(j2d, orb, DateTime("2023-01-02"))
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-02T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.95653689°
  Arg. of Periapsis : 197.0775252°
  Mean Anomaly      : 127.189209°

update_j2_mean_elements_epoch(
    orb::KeplerianElements,
    new_epoch::Union{Number, DateTime};
    kwargs...
) -> KeplerianElements{MeanAnomaly}

Update the epoch of the mean elements orb using a J2 orbit propagator to new_epoch, which can be represented by a Julian Day or a DateTime.

Keywords

• j2c::J2PropagatorConstants: J2 orbit propagator constants (see J2PropagatorConstants), converted to the element type of orb. (Default: J2C_EGM2008)

Examples

julia> orb = KeplerianElements(
           DateTime("2023-01-01") |> datetime2julian,
           7190.982e3,
           0.001111,
           98.405 |> deg2rad,
           90     |> deg2rad,
           200    |> deg2rad,
           45     |> deg2rad
       )
KeplerianElements{TrueAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-01T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.0°
  Arg. of Periapsis : 200.0°
  True Anomaly      : 45.0°

julia> update_j2_mean_elements_epoch(orb, DateTime("2023-01-02"))
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-02T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.95653689°
  Arg. of Periapsis : 197.0775252°
  Mean Anomaly      : 127.189209°

update_j2osc_mean_elements_epoch!(
    j2oscd::J2OsculatingPropagator,
    orb::KeplerianElements,
    new_epoch::Union{Number, DateTime}
) -> KeplerianElements{MeanAnomaly}

Update the epoch of the mean elements orb using the propagator j2oscd to new_epoch, which can be represented by a Julian Day or a DateTime.

Examples

julia> orb = KeplerianElements(
           DateTime("2023-01-01") |> datetime2julian,
           7190.982e3,
           0.001111,
           98.405 |> deg2rad,
           90     |> deg2rad,
           200    |> deg2rad,
           45     |> deg2rad
       )
KeplerianElements{TrueAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-01T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.0°
  Arg. of Periapsis : 200.0°
  True Anomaly      : 45.0°

# Allocate a new J2 osculating orbit propagator using the created Keplerian elements. Notice
# that any set of Keplerian elements can be used here.
julia> j2oscd = j2osc_init(orb);

julia> update_j2osc_mean_elements_epoch!(j2oscd, orb, DateTime("2023-01-02"))
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-02T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.95653689°
  Arg. of Periapsis : 197.0775252°
  Mean Anomaly      : 127.189209°

update_j2osc_mean_elements_epoch(
    orb::KeplerianElements,
    new_epoch::Union{Number, DateTime};
    kwargs...
) -> KeplerianElements{MeanAnomaly}

Update the epoch of the mean elements orb using a J2 osculating orbit propagator to new_epoch, which can be represented by a Julian Day or a DateTime.

Keywords

• j2c::J2PropagatorConstants: J2 orbit propagator constants (see J2PropagatorConstants), converted to the element type of orb. (Default: J2C_EGM2008)

Examples

julia> orb = KeplerianElements(
           DateTime("2023-01-01") |> datetime2julian,
           7190.982e3,
           0.001111,
           98.405 |> deg2rad,
           90     |> deg2rad,
           200    |> deg2rad,
           45     |> deg2rad
       )
KeplerianElements{TrueAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-01T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.0°
  Arg. of Periapsis : 200.0°
  True Anomaly      : 45.0°

julia> update_j2osc_mean_elements_epoch(orb, DateTime("2023-01-02"))
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-02T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.95653689°
  Arg. of Periapsis : 197.0775252°
  Mean Anomaly      : 127.189209°

update_j4_mean_elements_epoch!(
    j4d::J4Propagator,
    orb::KeplerianElements,
    new_epoch::Union{Number, DateTime}
) -> KeplerianElements{MeanAnomaly}

Update the epoch of the mean elements orb using the propagator j4d to new_epoch, which can be represented by a Julian Day or a DateTime.

Examples

julia> orb = KeplerianElements(
           DateTime("2023-01-01") |> datetime2julian,
           7190.982e3,
           0.001111,
           98.405 |> deg2rad,
           90     |> deg2rad,
           200    |> deg2rad,
           45     |> deg2rad
       )
KeplerianElements{TrueAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-01T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.0°
  Arg. of Periapsis : 200.0°
  True Anomaly      : 45.0°

# Allocate a new J4 orbit propagator using the created Keplerian elements. Notice that any
# set of Keplerian elements can be used here.
julia> j4d = j4_init(orb);

julia> update_j4_mean_elements_epoch!(j4d, orb, DateTime("2023-01-02"))
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-02T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.95551368°
  Arg. of Periapsis : 197.0785362°
  Mean Anomaly      : 127.191195°

update_j4_mean_elements_epoch(
    orb::KeplerianElements,
    new_epoch::Union{Number, DateTime};
    kwargs...
) -> KeplerianElements{MeanAnomaly}

Update the epoch of the mean elements orb using a J4 orbit propagator to new_epoch, which can be represented by a Julian Day or a DateTime.

Keywords

• j4c::J4PropagatorConstants: J4 orbit propagator constants (see J4PropagatorConstants), converted to the element type of orb. (Default: J4C_EGM2008)

Examples

julia> orb = KeplerianElements(
           DateTime("2023-01-01") |> datetime2julian,
           7190.982e3,
           0.001111,
           98.405 |> deg2rad,
           90     |> deg2rad,
           200    |> deg2rad,
           45     |> deg2rad
       )
KeplerianElements{TrueAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-01T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.0°
  Arg. of Periapsis : 200.0°
  True Anomaly      : 45.0°

julia> update_j4_mean_elements_epoch(orb, DateTime("2023-01-02"))
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-02T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.95551368°
  Arg. of Periapsis : 197.0785362°
  Mean Anomaly      : 127.191195°

update_j4osc_mean_elements_epoch!(
    j4oscd::J4OsculatingPropagator,
    orb::KeplerianElements,
    new_epoch::Union{Number, DateTime}
) -> KeplerianElements{MeanAnomaly}

Update the epoch of the mean elements orb using the propagator j4oscd to new_epoch, which can be represented by a Julian Day or a DateTime.

Examples

julia> orb = KeplerianElements(
           DateTime("2023-01-01") |> datetime2julian,
           7190.982e3,
           0.001111,
           98.405 |> deg2rad,
           90     |> deg2rad,
           200    |> deg2rad,
           45     |> deg2rad
       )
KeplerianElements{TrueAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-01T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.0°
  Arg. of Periapsis : 200.0°
  True Anomaly      : 45.0°

# Allocate a new J4 osculating orbit propagator using the created Keplerian elements. Notice
# that any set of Keplerian elements can be used here.
julia> j4oscd = j4osc_init(orb);

julia> update_j4osc_mean_elements_epoch!(j4oscd, orb, DateTime("2023-01-02"))
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-02T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.95551368°
  Arg. of Periapsis : 197.0785362°
  Mean Anomaly      : 127.191195°

update_j4osc_mean_elements_epoch(
    orb::KeplerianElements,
    new_epoch::Union{Number, DateTime};
    kwargs...
) -> KeplerianElements{MeanAnomaly}

Update the epoch of the mean elements orb using a J4 osculating orbit propagator to new_epoch, which can be represented by a Julian Day or a DateTime.

Keywords

• j4c::J4PropagatorConstants: J4 orbit propagator constants (see J4PropagatorConstants), converted to the element type of orb. (Default: J4C_EGM2008)

Examples

julia> orb = KeplerianElements(
           DateTime("2023-01-01") |> datetime2julian,
           7190.982e3,
           0.001111,
           98.405 |> deg2rad,
           90     |> deg2rad,
           200    |> deg2rad,
           45     |> deg2rad
       )
KeplerianElements{TrueAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-01T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.0°
  Arg. of Periapsis : 200.0°
  True Anomaly      : 45.0°

julia> update_j4osc_mean_elements_epoch(orb, DateTime("2023-01-02"))
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-02T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.95551368°
  Arg. of Periapsis : 197.0785362°
  Mean Anomaly      : 127.191195°

update_twobody_mean_elements_epoch!(
    tbd::TwoBodyPropagator,
    orb::KeplerianElements,
    new_epoch::Union{Number, DateTime}
) -> KeplerianElements{MeanAnomaly}

Update the epoch of the mean elements orb using the propagator tbd to new_epoch, which can be represented by a Julian Day or a DateTime.

Examples

julia> orb = KeplerianElements(
           DateTime("2023-01-01") |> datetime2julian,
           7190.982e3,
           0.001111,
           98.405 |> deg2rad,
           90     |> deg2rad,
           200    |> deg2rad,
           45     |> deg2rad
       )
KeplerianElements{TrueAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-01T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.0°
  Arg. of Periapsis : 200.0°
  True Anomaly      : 45.0°

# Allocate a new two-body orbit propagator using the created Keplerian elements. Notice that
# any set of Keplerian elements can be used here.
julia> tbd = twobody_init(orb);

julia> update_twobody_mean_elements_epoch!(tbd, orb, DateTime("2023-01-02"))
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-02T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.0°
  Arg. of Periapsis : 200.0°
  Mean Anomaly      : 130.2533301°

update_twobody_mean_elements_epoch(
    orb::KeplerianElements,
    new_epoch::Union{Number, DateTime};
    kwargs...
) -> KeplerianElements{MeanAnomaly}

Update the epoch of the mean elements orb using a two-body orbit propagator to new_epoch, which can be represented by a Julian Day or a DateTime.

Keywords

• m0::Number: Standard gravitational parameter of the central body [m³ / s²], converted to the element type of orb. (Default: TBC_M0)

Examples

julia> orb = KeplerianElements(
           DateTime("2023-01-01") |> datetime2julian,
           7190.982e3,
           0.001111,
           98.405 |> deg2rad,
           90     |> deg2rad,
           200    |> deg2rad,
           45     |> deg2rad
       )
KeplerianElements{TrueAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-01T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.0°
  Arg. of Periapsis : 200.0°
  True Anomaly      : 45.0°

julia> update_twobody_mean_elements_epoch(orb, DateTime("2023-01-02"))
KeplerianElements{MeanAnomaly, Float64, Float64}:
  Epoch             : 2.45995e6 (2023-01-02T00:00:00)
  Semi-Major Axis   : 7190.982 km
  Eccentricity      : 0.001111
  Inclination       : 98.405°
  RA of Asc. Node   : 90.0°
  Arg. of Periapsis : 200.0°
  Mean Anomaly      : 130.2533301°

abstract type OrbitPropagator{Tepoch <: Number, T <: Number}

Abstract type for the orbit propagators, where Tepoch is the type used to represent the epoch of the input elements and T is the type used for the internal variables.

_append_propagator(result, orbp::OrbitPropagator) -> Tuple

Append the propagator orbp to the result of a propagation so that the functions that initialize and propagate the orbit at once return the initialized propagator as their last element. A result that is a tuple is splatted, whereas any other object becomes the first element of the returned tuple.

_epoch_to_seconds(orbp::OrbitPropagator, epoch::Union{Number, DateTime}) -> Number

Convert epoch, which is either a Julian Day [UTC] or a DateTime [UTC], to the elapsed time [s] from the initial elements' epoch of orbp.

_header(orbp::OrbitPropagator) -> String

Return the header of the printed representations of orbp: its type with the parameters, followed by the propagator name in parentheses if the propagator defines one.

_propagate_vector!(
    to_Δt,
    orbp::OrbitPropagator{Tepoch, T},
    vt::AbstractVector,
    ntasks::Integer
) where {Tepoch <: Number, T <: Number} -> Vector{SVector{3, T}}, Vector{SVector{3, T}}

Propagate the orbit using orbp for every element of vt, which the function to_Δt converts to an elapsed time [s] from the initial elements' epoch. The first and the last elements are propagated with orbp itself, so that it is left at the last instant, whereas the remaining ones are partitioned among ntasks parallel tasks, each one propagating a copy of orbp. If ntasks is lower than 1, the propagation is sequential.

Returns

• Vector{SVector{3, T}}: Array with the position vectors [m] in the inertial frame at each instant defined in vt.
• Vector{SVector{3, T}}: Array with the velocity vectors [m / s] in the inertial frame at each instant defined in vt.

_to_julian_day(epoch::Number) -> Number
_to_julian_day(epoch::DateTime) -> Float64

Convert epoch, which is either a Julian Day [UTC] or a DateTime [UTC], to a Julian Day [UTC].

_to_seconds(t::Number) -> Number
_to_seconds(t::Union{Dates.Period, Dates.CompoundPeriod}) -> Float64

Convert t, which is either a number [s] or a period defined using Dates.jl, to seconds.

Dates.toms is type unstable for compound periods (see https://github.com/JuliaLang/julia/pull/54995), so the conversion is implemented here.

_to_state_vectors(
    to_epoch,
    vt::AbstractVector,
    vr_i::AbstractVector,
    vv_i::AbstractVector
) -> Vector{OrbitStateVector}

Pack the position vectors vr_i [m] and the velocity vectors vv_i [m / s] into orbit state vectors whose epochs [Julian Day] are obtained by applying the function to_epoch to the elements of vt. The vectors vr_i and vv_i are 1-based, whereas vt can have any axes.

epoch(orbp::OrbitPropagator{Tepoch, T}) where {Tepoch <: Number, T <: Number} -> Tepoch

Return the initial elements' epoch of the propagator orbp [Julian Day, UTC].

fit_mean_elements(
    [sink::Type, ]::Val{:propagator},
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv};
    kwargs...
) where {Tjd <: Number, Tv <: AbstractVector} -> <Mean elements>, <Covariance>, <Statistics>

fit_mean_elements(
    [sink::Type, ]::Val{:propagator},
    vsv::AbstractVector{OrbitStateVector{Tepoch, T}};
    kwargs...
) where {Tepoch <: Number, T <: Number} -> <Mean elements>, <Covariance>, <Statistics>

Fit a set of mean elements for the propagator using the osculating state vector represented in an inertial reference frame. The state vector can be represented using a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] obtained at the instants in the array vjd [Julian Day], or an array of OrbitStateVector vsv [SI], containing the same information. The keywords kwargs depend on the propagator type.

The optional parameter sink selects the representation of the mean elements for the propagators that support more than one. SGP4 accepts TLE and OrbitMeanElementsMessage, defaulting to the latter.

Returns

• <Mean elements>: Set of mean elements used to initialize the propagator. The concrete type depends on the propagator, and it is KeplerianElements{MeanAnomaly} for every propagator except SGP4, which returns an OrbitMeanElementsMessage or a TLE selected by sink.
• <Covariance>: Final covariance matrix of the least-square algorithm. It is a SMatrix{6, 6} for every propagator except SGP4, which returns a SMatrix{7, 7} because it also fits the B* parameter.
• <Statistics>: NamedTuple with the statistics of the least-square algorithm, with the fields converged::Bool, iterations::Int, position_rmse [m], velocity_rmse [m / s], and total_rmse. The propagators share the meaning of those fields, described in the fitting functions of each propagator.

fit_mean_elements!(
    orbp::OrbitPropagator,
    vjd::AbstractVector{Tjd},
    vr_i::AbstractVector{Tv},
    vv_i::AbstractVector{Tv}[, sink::Type];
    kwargs...
) where {Tjd <: Number, Tv <: AbstractVector} -> <Mean elements>, <Covariance>, <Statistics>

fit_mean_elements!(
    orbp::OrbitPropagator,
    vsv::AbstractVector{OrbitStateVector{Tepoch, T}}[, sink::Type];
    kwargs...
) where {Tepoch <: Number, T <: Number} -> <Mean elements>, <Covariance>, <Statistics>

Fit a set of mean elements for the propagator orbp using the osculating state vector represented in an inertial reference frame. The state vector can be represented using a set of position vectors vr_i [m] and a set of velocity vectors vv_i [m / s] obtained at the instants in the array vjd [Julian Day], or an array of OrbitStateVector vsv [SI], containing the same information. The keywords kwargs depend on the propagator type.

The optional parameter sink selects the representation of the mean elements for the propagators that support more than one. SGP4 accepts TLE and OrbitMeanElementsMessage, defaulting to the latter.

This function also initializes orbp with the fitted mean elements.

Returns

• <Mean elements>: Set of mean elements used to initialize orbp. The concrete type depends on the propagator, and it is KeplerianElements{MeanAnomaly} for every propagator except SGP4, which returns an OrbitMeanElementsMessage or a TLE selected by sink.
• <Covariance>: Final covariance matrix of the least-square algorithm. It is a SMatrix{6, 6} for every propagator except SGP4, which returns a SMatrix{7, 7} because it also fits the B* parameter.
• <Statistics>: NamedTuple with the statistics of the least-square algorithm, with the fields converged::Bool, iterations::Int, position_rmse [m], velocity_rmse [m / s], and total_rmse. The propagators share the meaning of those fields, described in the fitting functions of each propagator.

init(::Val{:propagator}, args...; kwargs...) -> OrbitPropagator

Create and initialize the orbit propagator. The arguments args and keywords kwargs depend on the propagator type.

init!(orbp::OrbitPropagator, args...; kwargs...) -> Nothing

Initialize the orbit propagator orbp. The arguments args and keywords kwargs depend on the propagator type.

is_initialized(orbp::OrbitPropagator) -> Bool

Return whether the orbit propagator orbp has been initialized and can be propagated. This is an optional function in the API, used to print a propagator created without initial elements without accessing its undefined fields. It returns true if the propagator does not overload it.

last_instant(
    orbp::OrbitPropagator{Tepoch, T}
) where {Tepoch <: Number, T <: Number} -> T

Return the last propagation instant [s] measured from the epoch.

mean_elements(orbp::OrbitPropagator) -> Union{Nothing, KeplerianElements{MeanAnomaly}}

Return the mean elements using the structure KeplerianElements{MeanAnomaly} of the latest propagation performed by orbp. This is an optional function in the API. It will return nothing if the propagator does not support it.

name(orbp::OrbitPropagator) -> String

Return the name of the orbit propagator orbp. If this function is not defined, the structure name is used: typeof(orbp) |> string.

propagate!(
    orbp::OrbitPropagator{Tepoch, T},
    t::Union{Number, Dates.Period, Dates.CompoundPeriod}[, sink::Type]
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

propagate!(
    orbp::OrbitPropagator{Tepoch, T},
    t::Union{Number, Dates.Period, Dates.CompoundPeriod},
    ::Type{OrbitStateVector}
) where {Tepoch <: Number, T <: Number} -> OrbitStateVector{Tepoch, T}

Propagate the orbit using orbp by t from the initial orbit epoch, where t is either a number [s] or a period defined using Dates.jl. The output type depends on the parameter sink. If it is omitted, it defaults to Tuple and the output is a tuple with the position and velocity vectors.

Returns

If sink is Tuple:

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.

If sink is OrbitStateVector:

• OrbitStateVector{Tepoch, T}: Structure with the orbit state vector [SI] at the propagation instant.

propagate!(
    orbp::OrbitPropagator{Tepoch, T},
    vt::AbstractVector[, sink::Type];
    kwargs...
) where {Tepoch <: Number, T <: Number} -> Vector{SVector{3, T}}, Vector{SVector{3, T}}

propagate!(
    orbp::OrbitPropagator{Tepoch, T},
    vt::AbstractVector,
    ::Type{OrbitStateVector};
    kwargs...
) where {Tepoch <: Number, T <: Number} -> Vector{OrbitStateVector{Tepoch, T}}

Propagate the orbit using orbp for every instant defined in vt from the initial orbit epoch, where the elements of vt are either numbers [s] or periods defined using Dates.jl. The output type depends on the parameter sink. If it is omitted, it defaults to Tuple, and the output is a tuple with the arrays containing the position and velocity vectors.

The instants are partitioned among parallel tasks, each one propagating a copy of orbp. After the call, orbp is left at the last instant in vt.

Keywords

• ntasks::Integer: Number of parallel tasks to propagate the orbit. If it is set to a number equal or lower than 1, the function will propagate the orbit sequentially. The number of tasks is also limited to the number of propagation instants that are actually partitioned among them. (Default: Threads.nthreads())

Returns

If sink is Tuple:

• Vector{SVector{3, T}}: Array with the position vectors [m] in the inertial frame at each propagation instant defined in vt.
• Vector{SVector{3, T}}: Array with the velocity vectors [m / s] in the inertial frame at each propagation instant defined in vt.

If sink is OrbitStateVector:

• Vector{OrbitStateVector{Tepoch, T}}: Array with the orbit state vectors [SI] at each propagation instant defined in vt.

propagate(
    [sink::Type, ]::Val{:propagator},
    vt::AbstractVector,
    args...;
    kwargs...
) -> Vector{SVector{3, T}}, Vector{SVector{3, T}}, OrbitPropagator{Tepoch, T}

propagate(
    ::Type{OrbitStateVector},
    ::Val{:propagator},
    vt::AbstractVector,
    args...;
    kwargs...
) -> Vector{OrbitStateVector{Tepoch, T}}, OrbitPropagator{Tepoch, T}

Initialize the orbit propagator and propagate the orbit for every instant defined in vt from the initial orbit epoch, where the elements of vt are either numbers [s] or periods defined using Dates.jl. The initialization arguments args... and kwargs... are the same as in the initialization function Propagators.init. The output type depends on the parameter sink. If it is omitted, it defaults to Tuple, and the output is a tuple with the arrays containing the position and velocity vectors.

Keywords

• ntasks::Integer: Number of parallel tasks to propagate the orbit. If it is set to a number equal or lower than 1, the function will propagate the orbit sequentially. The number of tasks is also limited to the number of propagation instants that are actually partitioned among them. (Default: Threads.nthreads())

Returns

If sink is Tuple:

• Vector{SVector{3, T}}: Array with the position vectors [m] in the inertial frame at each propagation instant defined in vt.
• Vector{SVector{3, T}}: Array with the velocity vectors [m / s] in the inertial frame at each propagation instant defined in vt.
• OrbitPropagator{Tepoch, T}: Structure with the initialized propagator.

If sink is OrbitStateVector:

• Vector{OrbitStateVector{Tepoch, T}}: Array with the orbit state vectors [SI] at each propagation instant defined in vt.
• OrbitPropagator{Tepoch, T}: Structure with the initialized propagator.

propagate(
    [sink::Type, ]::Val{:propagator},
    t::Union{Number, Dates.Period, Dates.CompoundPeriod},
    args...;
    kwargs...
) -> SVector{3, T}, SVector{3, T}, OrbitPropagator{Tepoch, T}

propagate(
    ::Type{OrbitStateVector},
    ::Val{:propagator},
    t::Union{Number, Dates.Period, Dates.CompoundPeriod},
    args...;
    kwargs...
) -> OrbitStateVector{Tepoch, T}, OrbitPropagator{Tepoch, T}

Initialize the orbit propagator and propagate the orbit by t from the initial orbit epoch, where t is either a number [s] or a period defined using Dates.jl. The initialization arguments args... and kwargs... are the same as in the initialization function Propagators.init. The output type depends on the parameter sink. If it is omitted, it defaults to Tuple and the output is a tuple with the position and velocity vectors.

Returns

If sink is Tuple:

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.
• OrbitPropagator{Tepoch, T}: Structure with the initialized propagator.

If sink is OrbitStateVector:

• OrbitStateVector{Tepoch, T}: Structure with the orbit state vector [SI] at the propagation instant.
• OrbitPropagator{Tepoch, T}: Structure with the initialized propagator.

propagate_to_epoch!(
    orbp::OrbitPropagator{Tepoch, T},
    epoch::Union{Number, DateTime}[, sink::Type]
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

propagate_to_epoch!(
    orbp::OrbitPropagator{Tepoch, T},
    epoch::Union{Number, DateTime},
    ::Type{OrbitStateVector}
) where {Tepoch <: Number, T <: Number} -> OrbitStateVector{Tepoch, T}

Propagate the orbit using orbp until epoch, which is either a Julian Day [UTC] or a DateTime [UTC]. The output type depends on the parameter sink. If it is omitted, it defaults to Tuple and the output is a tuple with the position and velocity vectors.

Returns

If sink is Tuple:

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.

If sink is OrbitStateVector:

• OrbitStateVector{Tepoch, T}: Structure with the orbit state vector [SI] at the propagation instant.

propagate_to_epoch!(
    orbp::OrbitPropagator{Tepoch, T},
    vepoch::AbstractVector[, sink::Type];
    kwargs...
) where {Tepoch <: Number, T <: Number} -> Vector{SVector{3, T}}, Vector{SVector{3, T}}

propagate_to_epoch!(
    orbp::OrbitPropagator{Tepoch, T},
    vepoch::AbstractVector,
    ::Type{OrbitStateVector};
    kwargs...
) where {Tepoch <: Number, T <: Number} -> Vector{OrbitStateVector{Tepoch, T}}

Propagate the orbit using orbp for every epoch defined in vepoch, whose elements are either Julian Days [UTC] or DateTime objects [UTC]. The output type depends on the parameter sink. If it is omitted, it defaults to Tuple, and the output is a tuple with the arrays containing the position and velocity vectors.

The epochs are partitioned among parallel tasks, each one propagating a copy of orbp. After the call, orbp is left at the last epoch in vepoch.

Keywords

• ntasks::Integer: Number of parallel tasks to propagate the orbit. If it is set to a number equal or lower than 1, the function will propagate the orbit sequentially. The number of tasks is also limited to the number of propagation instants that are actually partitioned among them. (Default: Threads.nthreads())

Returns

If sink is Tuple:

• Vector{SVector{3, T}}: Array with the position vectors [m] in the inertial frame at each epoch defined in vepoch.
• Vector{SVector{3, T}}: Array with the velocity vectors [m / s] in the inertial frame at each epoch defined in vepoch.

If sink is OrbitStateVector:

• Vector{OrbitStateVector{Tepoch, T}}: Array with the orbit state vectors [SI] at each epoch defined in vepoch.

propagate_to_epoch(
    [sink::Type, ]::Val{:propagator},
    vepoch::AbstractVector,
    args...;
    kwargs...
) -> Vector{SVector{3, T}}, Vector{SVector{3, T}}, OrbitPropagator{Tepoch, T}

propagate_to_epoch(
    ::Type{OrbitStateVector},
    ::Val{:propagator},
    vepoch::AbstractVector,
    args...;
    kwargs...
) -> Vector{OrbitStateVector{Tepoch, T}}, OrbitPropagator{Tepoch, T}

Initialize the orbit propagator and propagate the orbit for every epoch defined in vepoch, whose elements are either Julian Days [UTC] or DateTime objects [UTC]. The initialization arguments args... and kwargs... are the same as in the initialization function Propagators.init. The output type depends on the parameter sink. If it is omitted, it defaults to Tuple, and the output is a tuple with the arrays containing the position and velocity vectors.

Keywords

• ntasks::Integer: Number of parallel tasks to propagate the orbit. If it is set to a number equal or lower than 1, the function will propagate the orbit sequentially. The number of tasks is also limited to the number of propagation instants that are actually partitioned among them. (Default: Threads.nthreads())

Returns

If sink is Tuple:

• Vector{SVector{3, T}}: Array with the position vectors [m] in the inertial frame at each epoch defined in vepoch.
• Vector{SVector{3, T}}: Array with the velocity vectors [m / s] in the inertial frame at each epoch defined in vepoch.
• OrbitPropagator{Tepoch, T}: Structure with the initialized propagator.

If sink is OrbitStateVector:

• Vector{OrbitStateVector{Tepoch, T}}: Array with the orbit state vectors [SI] at each epoch defined in vepoch.
• OrbitPropagator{Tepoch, T}: Structure with the initialized propagator.

propagate_to_epoch(
    [sink::Type, ]::Val{:propagator},
    epoch::Union{Number, DateTime},
    args...;
    kwargs...
) -> SVector{3, T}, SVector{3, T}, OrbitPropagator{Tepoch, T}

propagate_to_epoch(
    ::Type{OrbitStateVector},
    ::Val{:propagator},
    epoch::Union{Number, DateTime},
    args...;
    kwargs...
) -> OrbitStateVector{Tepoch, T}, OrbitPropagator{Tepoch, T}

Initialize the orbit propagator and propagate the orbit until epoch, which is either a Julian Day [UTC] or a DateTime [UTC]. The initialization arguments args... and kwargs... are the same as in the initialization function Propagators.init. The output type depends on the parameter sink. If it is omitted, it defaults to Tuple and the output is a tuple with the position and velocity vectors.

Returns

If sink is Tuple:

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.
• OrbitPropagator{Tepoch, T}: Structure with the initialized propagator.

If sink is OrbitStateVector:

• OrbitStateVector{Tepoch, T}: Structure with the orbit state vector [SI] at the propagation instant.
• OrbitPropagator{Tepoch, T}: Structure with the initialized propagator.

propagator_data(orbp::OrbitPropagator) -> Any

Return the structure that stores the data of the propagation theory wrapped by the orbit propagator orbp. This is an optional function in the API, used to print the rich representation of that structure after the header of orbp. It returns nothing if the propagator does not overload it, in which case only the epoch and the last propagation instant are printed.

step!(
    orbp::OrbitPropagator{Tepoch, T},
    Δt::Union{Number, Dates.Period, Dates.CompoundPeriod}[, sink::Type]
) where {Tepoch <: Number, T <: Number} -> SVector{3, T}, SVector{3, T}

step!(
    orbp::OrbitPropagator{Tepoch, T},
    Δt::Union{Number, Dates.Period, Dates.CompoundPeriod},
    ::Type{OrbitStateVector}
) where {Tepoch <: Number, T <: Number} -> OrbitStateVector{Tepoch, T}

Propagate the orbit using orbp by Δt from the last propagation instant, where Δt is either a number [s] or a period defined using Dates.jl. The output type depends on the parameter sink. If it is omitted, it defaults to Tuple and the output is a tuple with the position and velocity vectors.

Returns

If sink is Tuple:

• SVector{3, T}: Position vector [m] represented in the inertial frame at propagation instant.
• SVector{3, T}: Velocity vector [m / s] represented in the inertial frame at propagation instant.

If sink is OrbitStateVector:

• OrbitStateVector{Tepoch, T}: Structure with the orbit state vector [SI] at the propagation instant.