Library

abstract type AbstractAtmosphericModelOutput end

Supertype of the structures returned by the atmospheric models that provide the number density of the species in addition to the total density.

Implementation

Every concrete subtype must define the private functions _model_name, returning the short name of the model (e.g. "JR1971"), _model_description, returning the full name of the model (e.g. "Jacchia-Roberts 1971"), and _show_fields, returning a tuple with the description of each field shown by show. Those definitions provide the shared show methods.

struct JB2008Output{T <: Number} <: AbstractAtmosphericModelOutput

Output of the atmospheric model Jacchia-Bowman 2008.

Fields

• total_density::T: Total atmospheric density [kg / m³].
• temperature::T: Temperature at the selected position [K].
• exospheric_temperature::T: Exospheric temperature [K].
• N2_number_density::T: Number density of N₂ [1 / m³].
• O2_number_density::T: Number density of O₂ [1 / m³].
• O_number_density::T: Number density of O [1 / m³].
• Ar_number_density::T: Number density of Ar [1 / m³].
• He_number_density::T: Number density of He [1 / m³].
• H_number_density::T: Number density of H [1 / m³].

struct JR1971Output{T <: Number} <: AbstractAtmosphericModelOutput

Output of the atmospheric model Jacchia-Roberts 1971.

Fields

• total_density::T: Total atmospheric density [kg / m³].
• temperature::T: Temperature at the selected position [K].
• exospheric_temperature::T: Exospheric temperature [K].
• N2_number_density::T: Number density of N₂ [1 / m³].
• O2_number_density::T: Number density of O₂ [1 / m³].
• O_number_density::T: Number density of O [1 / m³].
• Ar_number_density::T: Number density of Ar [1 / m³].
• He_number_density::T: Number density of He [1 / m³].
• H_number_density::T: Number density of H [1 / m³].

struct Jacchia1977Output{T <: Number} <: AbstractAtmosphericModelOutput

Output of the atmospheric model Jacchia 1977.

Fields

• total_density::T: Total atmospheric density [kg / m³].
• temperature::T: Local temperature at the selected position [K], computed from the temperature profile related to the local quiet exospheric temperature (phase angle of -60°, as prescribed for the actual temperature in eq. 26 of the report) increased by the geomagnetic variation.
• exospheric_temperature::T: Mean exospheric temperature T½ above the selected position [K], as defined in eq. 20 of the report.
• N2_number_density::T: Number density of N₂ [1 / m³].
• O2_number_density::T: Number density of O₂ [1 / m³].
• O_number_density::T: Number density of O [1 / m³].
• Ar_number_density::T: Number density of Ar [1 / m³].
• He_number_density::T: Number density of He [1 / m³].
• H_number_density::T: Number density of H [1 / m³]. It is 0 at altitudes up to 140 km, where the model does not include the hydrogen.

struct Nrlmsise00Flags

Flags to configure NRLMSISE-00.

Fields

• F10_Mean::Bool: F10.7 effect on mean.
• time_independent::Bool: Independent of time.
• sym_annual::Bool: Symmetrical annual.
• sym_semiannual::Bool: Symmetrical semiannual.
• asym_annual::Bool: Asymmetrical annual.
• asym_semiannual::Bool: Asymmetrical semiannual.
• diurnal::Bool: Diurnal.
• semidiurnal::Bool: Semidiurnal.
• daily_ap::Bool: Daily AP.
• all_ut_long_effects::Bool: All UT/long effects.
• longitudinal::Bool: Longitudinal.
• ut_mixed_ut_long::Bool: UT and mixed UT/long.
• mixed_ap_ut_long::Bool: Mixed AP/UT/long.
• terdiurnal::Bool: Terdiurnal.
• departures_from_eq::Bool: Departures from diffusive equilibrium.
• all_tinf_var::Bool: All TINF variations.
• all_tlb_var::Bool: All TLB variations.
• all_tn1_var::Bool: All TN1 variations.
• all_s_var::Bool: All S variations.
• all_tn2_var::Bool: All TN2 variations.
• all_nlb_var::Bool: All NLB variations.
• all_tn3_var::Bool: All TN3 variations.

struct Nrlmsise00Output{T <: Number} <: AbstractAtmosphericModelOutput

Output structure for NRLMSISE00 model.

Fields

• total_density::T: Total mass density [kg / m³].
• temperature: Temperature at the selected altitude [K].
• exospheric_temperature: Exospheric temperature [K].
• N_number_density: Nitrogen number density [1 / m³].
• N2_number_density: N₂ number density [1 / m³].
• O_number_density: Oxygen number density [1 / m³].
• aO_number_density: Anomalous Oxygen number density [1 / m³].
• O2_number_density: O₂ number density [1 / m³].
• H_number_density: Hydrogen number density [1 / m³].
• He_number_density: Helium number density [1 / m³].
• Ar_number_density: Argon number density [1 / m³].

Remarks

Anomalous oxygen is defined as hot atomic oxygen or ionized oxygen that can become appreciable at high altitudes (> 500 km) for some ranges of inputs, thereby affecting drag on satellites and debris. We group these species under the term Anomalous Oxygen, since their individual variations are not presently separable with the drag data used to define this model component.

exponential(h::Number) -> Number

Compute the atmospheric density [kg / m³] at the altitude h [m] above the ellipsoid using the exponential atmospheric model, returning a value with the floating-point type of h:

                ┌            ┐
                │    h - h₀  │
ρ(h) = ρ₀ . exp │ - ──────── │ ,
                │      H     │
                └            ┘

in which ρ₀, h₀, and H are parameters obtained from tables that depend only on h.

The function throws an ArgumentError if the altitude h is negative. Above 1000 km, the parameters of the last layer of the table are used.

harrispriester(
    instant::DateTime,
    ϕ_gd::Number,
    λ::Number,
    h::Number;
    kwargs...
) -> Number
harrispriester(jd::Number, ϕ_gd::Number, λ::Number, h::Number; kwargs...) -> Number

Compute the atmospheric density [kg / m³] using the Harris-Priester model [1] with the diurnal bulge modeling and the density profile for the mean solar activity of [2, 3].

The angle between the diurnal bulge apex and the position is computed using the geodetic latitude ϕ_gd in place of the geocentric declination, as in [2]. The difference is lower than 0.2° and its effect on the density is negligible for the accuracy of the model.

The model is valid only inside the altitude range of the density profile alt_ρ (100 km to 1000 km for the default profile). The function throws an ArgumentError if the altitude h is outside this range or if the profile has less than two rows, less than three columns, or altitudes that are not sorted in ascending order.

Arguments

• instant::DateTime: Instant to compute the model represented using DateTime.
• jd::Number: Julian day to compute the model.
• ϕ_gd::Number: Geodetic latitude [rad].
• λ::Number: Geodetic longitude [rad].
• h::Number: Geodetic altitude [m].

Keywords

• n::Number: Cosine exponent in the diurnal bulge modeling (2 <= n <= 7). If n is 2, it models a smooth transition, whereas if n is 6, it models a sharp transition. The function throws an ArgumentError if n is outside this range. (Default: 4)
• alt_ρ::AbstractMatrix: Matrix containing the minimum and maximum density profiles, where the columns are the altitude [m], the minimum density [kg / m³], and the maximum density [kg / m³], respectively. (Default: _HARRIS_PRIESTER_ALT_RHO, related to the mean solar activity)

Returns

• Number: Atmospheric density [kg / m³]. The type is the promotion of the types of the numeric inputs.

References

• [1] Harris, I., Priester, W (1962). Time-dependent structure of the upper atmosphere. Journal of the Atmospheric Sciences, 19(4), pp. 286-301.
• [2] Montenbruck, O., Gill, E (2000). Satellite Orbits: Models, Methods and Applications. Springer-Verlag, Berlin, Germany, Section 3.5.1.
• [3] Long, A. C., Cappellari Jr., J. O., Velez, C. E., Fuchs, A. J (editors) (1989). Goddard Trajectory Determination System (GTDS) Mathematical Theory (Revision 1). FDD/552-89/0001 and CSC/TR-89/6001, Section 4.4.

harrispriester_modified(
    instant::DateTime,
    ϕ_gd::Number,
    λ::Number,
    h::Number[, F10ₐ::Number];
    kwargs...
) -> Number
harrispriester_modified(
    jd::Number,
    ϕ_gd::Number,
    λ::Number,
    h::Number[, F10ₐ::Number];
    kwargs...
) -> Number

Compute the atmospheric density [kg / m³] using the modified Harris-Priester model.

This model is a Julia translation of the Fortran code harris_priester_mod_dist.f90 developed by Noble Hatten and Ryan P. Russell [1]. It ensures continuous first derivatives, eliminates singularities, and uses a cubic dependency on the 81-day centered average of the F10.7 solar flux index (F10ₐ) to model density variations.

If F10ₐ is not provided, it will be automatically fetched using the SpaceIndices package. In this case, the initialization of the space indices package with SpaceIndices.init() is required.

The model is valid only between 100 km and 1000 km. The function throws an ArgumentError if the altitude h is outside this range.

Arguments

• instant::DateTime: Instant to compute the model represented using DateTime.
• jd::Number: Julian day to compute the model.
• ϕ_gd::Number: Geodetic latitude [rad].
• λ::Number: Geodetic longitude [rad].
• h::Number: Geodetic altitude [m].
• F10ₐ::Number: 81-day centered average of the F10.7 solar flux index [sfu].

Keywords

• n::Number: Cosine exponent in the diurnal bulge modeling (2 <= n <= 7). The original Fortran implementation computes n from the orbital inclination as n = 2.001 + 4 sin²(inclination). Hence, use n = 2.001 for equatorial orbits, n = 6.001 for polar orbits, and interpolate for intermediate inclinations. If the orbital inclination is unknown, the default provides a reasonable approximation. This functionality was purposefully removed here to avoid needing an additional dependency. The function throws an ArgumentError if n is outside this range. (Default: 4)

Returns

• Number: Atmospheric density [kg / m³]. The type is the promotion of the types of the numeric inputs.

References

• [1] Hatten, N., & Russell, R. P. (2017). A smooth and robust Harris-Priester atmospheric density model for low Earth orbit applications. Advances in Space Research, 59(2), 571-586.

jacchia1977(
    instant::DateTime,
    ϕ_gd::Number,
    λ::Number,
    h::Number[, F10::Number, F10ₐ::Number, Kp::Number];
    kwargs...
) -> Jacchia1977Output
jacchia1977(
    jd::Number,
    ϕ_gd::Number,
    λ::Number,
    h::Number[, F10::Number, F10ₐ::Number, Kp::Number];
    kwargs...
) -> Jacchia1977Output

Compute the atmospheric density using the Jacchia 1977 model.

Unlike the Jacchia-Roberts 1971 model, the Jacchia 1977 model does not have a closed-form solution. Hence, the barometric and diffusion equations are numerically integrated here, making this model considerably slower than jr1971.

The keyword variant selects how the dynamic model is assembled. The default, Val(:sr375), follows the report [1]: each species is evaluated at its own pseudo exospheric temperature, and the geomagnetic, seasonal-latitudinal, and semiannual variations are applied to the number densities. The alternative, Val(:stela), follows the simplified assembly used by the CNES tools STELA and PATRIUS [3]: the static model is evaluated at a single local exospheric temperature computed with the hydrogen phase angle (-60°) and a fixed diurnal exponent of 3, the geomagnetic variation of the exospheric temperature is weighted by the altitude profile of eq. 32 of [1] and added to that temperature, and only the semiannual variation is applied to the number densities. The reference implementation [3] also swaps the daily and averaged fluxes in eq. 20 of [1], computing the exospheric temperature with 5.48 F10^0.8 + 101.8 F10ₐ^0.4, and we replicate this behavior to match its output. The STELA variant produces total densities a few percent higher on average than the report formulation, and it is provided to reproduce decay analyses performed with those tools.

If we omit all space indices, the system tries to obtain them automatically for the selected day jd or instant using the prescriptions in the report [1]: the daily flux is evaluated with a lag that depends on the solar hour angle, the averaged flux is a Gaussian-weighted mean with a standard width of 71 days centered on the input time, and the Kp is delayed by an interval that depends on the geomagnetic latitude. However, the indices must be already initialized using the function SpaceIndices.init(). Notice that the Gaussian-weighted mean uses a window of ±213 days (three standard widths) truncated at the available data span, renormalizing the weights accordingly.

The function throws an ArgumentError if the altitude h is outside the interval [90, 2000] km.

Arguments

• jd::Number: Julian day to compute the model.
• instant::DateTime: Instant to compute the model represented using DateTime.
• ϕ_gd::Number: Geodetic latitude [rad].
• λ::Number: Longitude [rad].
• h::Number: Altitude [m].
• F10::Number: 10.7-cm solar flux adjusted to 1 AU [sfu] (as used to fit the Jacchia models), evaluated with the lag prescribed in [1] (from 0.9 day to 1.6 days, depending on the local solar time).
• F10ₐ::Number: 10.7-cm averaged solar flux adjusted to 1 AU, Gaussian-weighted mean centered on the input time with a standard width of 71 days [sfu]. In the Val(:stela) variant, the automatic fetching centers the mean on the lagged instant instead, as in the reference implementation [3].
• Kp::Number: Kp geomagnetic index, delayed by 0.1 day to 0.3 day depending on the geomagnetic latitude, as prescribed in [1].

Keywords

• geomagnetic_profile::Val: Profile of the geomagnetic variation of the temperature, only available in the Val(:sr375) variant. If it is Val(:constant), the entire temperature profile used to compute the geomagnetic variation of the number densities is increased by the geomagnetic variation of the exospheric temperature, as in the reference implementation [2] and in the numerical example of [1]. If it is Val(:tanh), the increase is weighted by the altitude-dependent profile of eq. 32 of [1], which vanishes at 90 km and tends to the full variation at high altitudes. The report states that neglecting eq. 32 is not justified at lower heights. (Default: Val(:constant))
• variant::Val: Assembly of the dynamic model. If it is Val(:sr375), the model follows the report [1]. If it is Val(:stela), the model follows the simplified assembly of the CNES tools STELA and PATRIUS [3] (see the description above). The function throws an ArgumentError for other values and when geomagnetic_profile is set to Val(:tanh) together with Val(:stela). (Default: Val(:sr375))

Returns

• Jacchia1977Output: Structure containing the results obtained from the model. Its element type is the promotion of the types of the numeric inputs. In the Val(:stela) variant, the field exospheric_temperature holds the local exospheric temperature used to evaluate the static model, including the diurnal and geomagnetic variations, instead of the mean exospheric temperature T½ of eq. 20 of [1].

References

• [1] Jacchia, L. G (1977). Thermospheric temperature, density and composition: New models. SAO Special Report #375.
• [2] de Matos, B. S., Carrara, V (1985-1987). Fortran implementation of the Jacchia 1977 model. INPE, São José dos Campos, BR.
• [3] CNES (2025). Java implementation of the Jacchia 1977 model used by the tools STELA and PATRIUS (class fr.cnes.sirius.patrius.stela.forces.atmospheres.Jacchia77, PATRIUS 4.16). Available in https://github.com/CNES/patrius.

jb2008(instant::DateTime, ϕ_gd::Number, λ::Number, h::Number) -> JB2008Output
jb2008(
    instant::DateTime,
    ϕ_gd::Number,
    λ::Number,
    h::Number,
    F10::Number,
    F10ₐ::Number,
    S10::Number,
    S10ₐ::Number,
    M10::Number,
    M10ₐ::Number,
    Y10::Number,
    Y10ₐ::Number,
    DstΔTc::Number,
) -> JB2008Output
jb2008(jd::Number, ϕ_gd::Number, λ::Number, h::Number) -> JB2008Output
jb2008(
    jd::Number,
    ϕ_gd::Number,
    λ::Number,
    h::Number,
    F10::Number,
    F10ₐ::Number,
    S10::Number,
    S10ₐ::Number,
    M10::Number,
    M10ₐ::Number,
    Y10::Number,
    Y10ₐ::Number,
    DstΔTc::Number,
) -> JB2008Output

Compute the atmospheric density using the Jacchia-Bowman 2008 (JB2008) model.

This model is a product of the Space Environment Technologies, please, refer to the following website for more information:

https://spacewx.com/JB2008/

If we omit all space indices, the system tries to obtain them automatically for the selected day jd or instant. However, the indices must be already initialized using the function SpaceIndices.init().

The function throws an ArgumentError if the altitude h is outside the interval [90, 3000] km.

Arguments

• jd::Number: Julian day to compute the model.
• instant::DateTime: Instant to compute the model represented using DateTime.
• ϕ_gd: Geodetic latitude [rad].
• λ: Longitude [rad].
• h: Altitude [m].
• F10: 10.7-cm solar flux [sfu] obtained 1 day before jd.
• F10ₐ: 10.7-cm averaged solar flux using a 81-day window centered on input time obtained 1 day before jd.
• S10: EUV index (26-34 nm) scaled to F10.7 obtained 1 day before jd.
• S10ₐ: EUV 81-day averaged centered index obtained 1 day before jd.
• M10: MG2 index scaled to F10.7 obtained 2 days before jd.
• M10ₐ: MG2 81-day averaged centered index obtained 2 days before jd.
• Y10: Solar X-ray & Ly-α index scaled to F10.7 obtained 5 days before jd.
• Y10ₐ: Solar X-ray & Ly-α 81-day averaged centered index obtained 5 days before jd.
• DstΔTc: Temperature variation related to the Dst.

Returns

• JB2008Output: Structure containing the results obtained from the model. Its element type is the promotion of the types of the numeric inputs.

jr1971(instant::DateTime, ϕ_gd::Number, λ::Number, h::Number) -> JR1971Output
jr1971(
    instant::DateTime,
    ϕ_gd::Number,
    λ::Number,
    h::Number,
    F10::Number,
    F10ₐ::Number,
    Kp::Number,
) -> JR1971Output
jr1971(jd::Number, ϕ_gd::Number, λ::Number, h::Number) -> JR1971Output
jr1971(
    jd::Number,
    ϕ_gd::Number,
    λ::Number,
    h::Number,
    F10::Number,
    F10ₐ::Number,
    Kp::Number,
) -> JR1971Output

Compute the atmospheric density using the Jacchia-Roberts 1971 model.

If we omit all space indices, the system tries to obtain them automatically for the selected day jd or instant. However, the indices must be already initialized using the function SpaceIndices.init().

The function throws an ArgumentError if the altitude h is outside the interval [90, 3000] km.

Arguments

• jd::Number: Julian day to compute the model.
• instant::DateTime: Instant to compute the model represented using DateTime.
• ϕ_gd::Number: Geodetic latitude [rad].
• λ::Number: Longitude [rad].
• h::Number: Altitude [m].
• F10::Number: 10.7-cm solar flux adjusted to 1 AU [sfu], as used to fit the Jacchia models.
• F10ₐ::Number: 10.7-cm averaged solar flux adjusted to 1 AU, 81-day centered on input time [sfu].
• Kp::Number: Kp geomagnetic index with a delay of 3 hours.

Returns

• JR1971Output: Structure containing the results obtained from the model. Its element type is the promotion of the types of the numeric inputs.

nrlmsise00(
    instant::DateTime,
    h::Number,
    ϕ_gd::Number,
    λ::Number;
    kwargs...
) -> Nrlmsise00Output
nrlmsise00(
    instant::DateTime,
    h::Number,
    ϕ_gd::Number,
    λ::Number,
    F10ₐ::Number,
    F10::Number,
    ap::Union{Number, AbstractVector};
    kwargs...
) -> Nrlmsise00Output
nrlmsise00(
    jd::Number,
    h::Number,
    ϕ_gd::Number,
    λ::Number;
    kwargs...
) -> Nrlmsise00Output
nrlmsise00(
    jd::Number,
    h::Number,
    ϕ_gd::Number,
    λ::Number,
    F10ₐ::Number,
    F10::Number,
    ap::Union{Number, AbstractVector};
    kwargs...
) -> Nrlmsise00Output

Compute the atmospheric density using the NRLMSISE-00 model.

If we omit all space indices, the system tries to obtain them automatically for the selected day jd or instant. However, the indices must be already initialized using the function SpaceIndices.init().

The function throws an ArgumentError if the altitude h is negative.

Arguments

• instant::DateTime: Instant to compute the model represented using DateTime.
• jd::Number: Julian day to compute the model.
• h::Number: Altitude [m].
• ϕ_gd::Number: Geodetic latitude [rad].
• λ::Number: Longitude [rad].
• F10ₐ::Number: 10.7-cm averaged solar flux, 81-day centered on input time [sfu].
• F10::Number: 10.7-cm solar flux [sfu].
• ap::Union{Number, AbstractVector}: Magnetic index, see the section AP for more information.

Keywords

• flags::Nrlmsise00Flags: A list of flags to configure the model. For more information, see Nrlmsise00Flags. (Default: Nrlmsise00Flags())
• include_anomalous_oxygen::Bool: If true, the anomalous oxygen density will be included in the total density computation. (Default: true)
• P::Union{Nothing, AbstractMatrix}: If the user passes a matrix with dimensions equal to or greater than 8 × 4, it will be used when computing the Legendre associated functions, reducing allocations and improving the performance. Its element type must be the floating-point promotion of the types of the numeric inputs (e.g. Float64), otherwise an ArgumentError is thrown. If it is nothing, the matrix is allocated inside the function. (Default: nothing)

Returns

• Nrlmsise00Output: Structure containing the results obtained from the model. Its element type is the promotion of the types of the numeric inputs.

AP

The input variable ap contains the magnetic index. It can be a Number or an AbstractVector.

If ap is a number, it must contain the daily magnetic index.

If ap is an AbstractVector, it must be a vector with 7 elements as described below, otherwise the function throws an ArgumentError:

Extended help

1. The densities of O, H, N, and anomalous O are set to 0 below 72.5 km.
2. The exospheric temperature is set to global average for altitudes below 120 km. The 120 km gradient is left at global average value for altitudes below 72.5 km.
3. Anomalous oxygen is defined as hot atomic oxygen or ionized oxygen that can become appreciable at high altitudes (> 500 km) for some ranges of inputs, thereby affecting drag on satellites and debris. We group these species under the term Anomalous Oxygen, since their individual variations are not presently separable with the drag data used to define this model component.

Notes on Input Variables

F10 and F10ₐ values used to generate the model correspond to the 10.7 cm radio flux at the actual distance of the Earth from the Sun rather than the radio flux at 1 AU. The following site provides both classes of values:

ftp://ftp.ngdc.noaa.gov/STP/SOLAR_DATA/SOLAR_RADIO/FLUX/

F10, F10ₐ, and ap effects are neither large nor well established below 80 km and these parameters should be set to 150, 150, and 4 respectively.

If include_anomalous_oxygen is false, the total_density field in the output is the sum of the mass densities of the species He, O, N₂, O₂, Ar, H, and N, but does not include anomalous oxygen.

If include_anomalous_oxygen is true, the total_density field in the output is the effective total mass density for drag and is the sum of the mass densities of all species in this model including the anomalous oxygen.