Library

abstract type SpaceIndexSet

Abstract type for all structures that represent space index sets.

_ap_to_dtc(ap::Float64) -> Float64

Compute the non-storm dTc [K] from a 3-hour ap index value using the Jacchia 1970 geomagnetic activity equation as implemented in DTCMAKEDR (lines 251–255):

if ap > 50: ap = 50    (cap per JB2008 convention)
dTc = ap + 100 × (1 − exp(−0.08 × ap))

_auto_init(::Type{T}) where T<:SpaceIndexSet -> Bool

Return whether the space index set T should be initialized automatically by the no- argument init(). Sets that return false (e.g. Dst) must be initialized explicitly via init(T).

_build_ap_baseline(vjd, ap_source) -> Union{Vector{Float64}, Nothing}

Build an hourly Jacchia 1970 dTc baseline from ap index data. Returns nothing if the required index set is not initialized (falls back to zero baseline).

For each hour, the ap value from 6.7 hours earlier is looked up and converted to a temperature increment via _ap_to_dtc (Jacchia 1970 formula with ap capped at 50).

Arguments

• vjd: Vector of Julian dates for the Dst time series.
• ap_source: :celestrak for 3-hour ap from Celestrak, or :hpo for hourly ap60 from the GFZ Hpo index.

_compute_dtc_from_dst(vdst, vbaseline) -> Vector{Float64}
_compute_dtc_from_dst(vdst)            -> Vector{Float64}

Compute the exospheric temperature change dTc [K] from an hourly Dst time series using the JB2008 storm algorithm (DTCMAKEDR). Returns a vector of dTc values the same length as vdst.

If vbaseline is provided (same length as vdst), it supplies the Jacchia 1970 ap-based temperature for each hour. This is used as:

• The dTc value during non-storm periods.
• The initial condition at storm commencement.

If omitted, the baseline is 0 everywhere (storm-only mode).

The algorithm is a two-pass procedure:

1. Detect all storm events in the Dst time series.
2. Integrate dTc through each storm using the appropriate phase equations.

When dTc goes negative during recovery or late recovery, the storm is terminated early and the ap-based baseline is restored (matching DTCMAKEDR April 2012 revision).

_detect_dst_storms(vdst) -> Vector{_DstStormEvent}

Scan the hourly Dst time series and return a vector of detected storm events.

A storm requires:

• Dst minimum < -75.0 nT
• Magnitude ΔDst (max − min) ≥ 50 nT

Based on DSTSTM / DSTBEG / DSTMAX / DSTMIN / DSTREC / DSTEND from DTCMAKEDR.

_dtc_slope(dst_min::Float64) -> Float64

Compute the storm main phase slope S as a function of the storm Dst minimum. This is Equation (10) from JB2008 / DTCMAKEDR line 376:

S = -1.5050×10⁻⁵ × DstMIN² - 1.0604×10⁻² × DstMIN - 3.20

For very large storms (DstMIN < -450 nT), S is capped at -1.40.

_find_slope_change(vdst, min_idx, end_idx, n) -> Int

After the Dst minimum, find the index where the recovery slope changes from fast (early recovery) to slow (late recovery).

Detection method (matching DSTREC from DTCMAKEDR):

• Compute centered Dst derivative: slope = (Dst[k+1] - Dst[k-1]) / (2 × Δt) [nT/day]
• Slope change detected when slope < 100 nT/day for 3 instances
• Also stops at 6 accumulated points ≥ -40 (backstop)

_find_storm_end(vdst, min_idx, dst_min, dst_max, n) -> Int

Determine the storm end point. Based on DSTEND from DTCMAKEDR.

1. Extends the minimum forward through flat bottoms (within 15 nT of minimum).
2. Computes estimated duration: 0.0075 × ΔDst days (where ΔDst = max − min).
3. Steps forward checking for:
   • 6 accumulated points with Dst > -75 nT → storm end
   • Dst drops by > 75 nT from a local max → new storm (end at local max)
   • Estimated duration reached → storm end

_find_storm_minimum(vdst, start_idx, n) -> (min_idx, dst_min)

Scan forward from the storm start to find the global Dst minimum.

Termination criteria (matching DSTMIN from DTCMAKEDR):

• Recovery of 125 nT from minimum
• Recovery of 75 nT AND current Dst > -75
• 2 accumulated points ≥ -40 (after a valid minimum < -75 is found)

_find_storm_start(vdst, trigger_idx) -> (start_idx, dst_max)

Scan backward from the storm trigger (first Dst < -75) to find the Dst maximum (storm commencement point). Based on DSTMAX from DTCMAKEDR.

Stops when 6 consecutive points ≥ -40 nT are found (quiet pre-storm period).

_integrate_storm_dtc!(vdtc, vdst, vbaseline, storm, initial_dtc) -> Nothing

Integrate the exospheric temperature change through a single storm event, writing the results into vdtc. Matches the DSTDTC subroutine from DTCMAKEDR.

• Main phase (start → min+lag): Equation (8) with slope S from Equation (10). Dst values are clamped to ≤ 0 to guard against SSC positive spikes. When Dst increases (substorms), Equation (11) is used instead. No dTc floor is applied during the main phase (per Fortran reference).
• Recovery (min+lag → slope_change+lag): Equation (12)
• Late recovery (slope_change+lag → end): Equation (13). When Dst dips (ΔDst < 0), the main phase slope S is used instead of -2.5.

In recovery and late recovery, if dTc goes negative the storm is terminated early and the ap-based baseline is restored (DTCMAKEDR April 2012 revision, lines 407–414, 436–443).

The Fortran DTCMAKEDR applies a DELAY as a pure output time shift (lines 345–348, 457–458, 468–477): the integration runs at "integration time" TSTEP with Dst accessed at TSTEP (no lag), and the output is mapped to time TSTEP + DELAY. This means:

• Output at time T uses Dst from time T − DELAY (uniform lag on ALL phases)
• Phase boundaries in the output domain are shifted by +DELAY

To match this, the lag is applied uniformly to ALL Dst accesses (not just main phase), and the phase boundaries are shifted by +lag:

• 0 hours for large storms (DstMIN < -350 nT)
• 1 hour for moderate storms (-350 ≤ DstMIN < -250 nT)
• 2 hours for minor storms (DstMIN ≥ -250 nT)

_lookup_3h_ap(ap_jd, ap_tuples, jd) -> Float64

Look up the 3-hour ap value for a given Julian date from the Celestrak daily ap data. ap_jd contains Julian dates at the start of each day, and ap_tuples contains 8 three-hourly ap values per day.

_lookup_hourly_ap(ap_jd, ap_tuples, jd) -> Float64

Look up the hourly ap60 value for a given Julian date from the Hpo daily ap data. ap_jd contains Julian dates at the start of each day, and ap_tuples contains 24 hourly ap values per day.

_round_Kp(x::Float64)

Celestrak mulitples Kp by 10 and rounds to the nearest integer this puts it back.

constant_interpolation(knots::AbstractVector, values::AbstractVector, x) -> eltype(values)

Perform a constant interpolation at x of values evaluated at knots. The interpolation returns value(knots[k-1]) in which knots[k-1] <= x < knots[k].

destroy() -> Nothing

Destroy the objects of all space index sets that were initialized.

expiry_periods(::Type{T}) where T<:SpaceIndexSet -> Vector{DatePeriod}

Return the expiry periods for the remote files associated with the space index set T. If a time interval greater than this period has elapsed since the last download, the remote files will be downloaded again.

filenames(::Type{T}) where T<:SpaceIndexSet -> Vector{String}

Return the filenames for the remote files associated with the space index set T. If this function is not defined for T, the filenames will be obtained based on the URLs.

init(::Type{Dst}; ap_source::Symbol = :celestrak, kwargs...) -> Nothing

Initialize the Dst space index set.

Dst is not included in the default init() call because it downloads many monthly files and depends on an ap data source being initialized first.

Keywords

• ap_source::Symbol: The source of ap data for the non-storm dTc baseline.
  • :celestrak — Use 3-hour ap from Celestrak (default). Matches JB2008 DTCFILE.TXT convention.
  • :hpo — Use hourly ap60 from the GFZ Hpo index. Provides higher temporal resolution.
  The corresponding index set (Celestrak or Hpo) must already be initialized. (Default = :celestrak)
• filepaths::Union{Nothing, Vector{String}}: If nothing, download from Kyoto WDC. (Default = nothing)
• force_download::Bool: If true, re-download regardless of timestamps. (Default = false)

init(; blocklist::Vector = []) -> Nothing

Initialize all the registered space index sets.

This function will download the remote files associated to the space index sets if they do not exist or if the expiry period has been elapsed. Afterward, it will parse the files and populate the objects to be accessed by the function space_index.

Space index sets where _auto_init(T) returns false (e.g. Dst) are always skipped and must be initialized explicitly via init(T).

If the user does not want to initialize some additional sets, they can pass them in the keyword blocklist.

init(::Type{T}; kwargs...) where T<:SpaceIndexSet -> Nothing

Initialize the space index set T.

This function will download the remote files associated with the space index set T if they do not exist or if their expiry period has been elapsed. Aftward, it will parse the files and populate the object to be accessed by the function space_index.

Keywords

• force_download::Bool: If true, the remote files will be downloaded regardless of their timestamps. (Default = false)
• filepaths::Union{Nothing, Vector{String}}: If it is nothing, the function will download the space index files from the locations specified in the urls API function. However, the user can pass a vector with the file locations, which will be used instead of downloading the data. In this case, the user must provide all the files in the space index set T. (Default = nothing)

linear_interpolation(knots::AbstractVector, values::AbstractVector, x)

Perform a linear interpolation at x of values evaluated at knots.

parse_files(::Type{T}, filepaths::Vector{String}) where T<:SpaceIndexSet -> T

Parse the files associated with the space index set T using the files in filepaths. It must return an object of type T with the parsed data.

space_index(::Val{:index}, jd::Number; kwargs...) -> Number
space_index(::Val{:index}, date::DateTime; kwargs...) -> Number

Get the space index for the Julian day jd or the instant. The latter must be an object of type DateTime. kwargs... can be used to pass additional configuration for the space index.

space_index(::Val{:Ap30}, jd::Number) -> NTuple{48, Float64}

Return the Ap30 index for the day at Julian Day jd.

The Ap30 index is the linear equivalent of Hp30 geomagnetic activity. This function returns all 48 values for the day containing the given Julian Day.

space_index(::Val{:Ap60}, jd::Number) -> NTuple{24, Float64}

Return the ap60 index for the day at Julian Day jd.

The ap60 index is the linear equivalent of Hp60 geomagnetic activity. This function returns all 24 values for the day containing the given Julian Day.

space_index(::Val{:Ap_daily}, jd::Number) -> Int64

Get the daily Ap index for the day at instant.

space_index(::Val{:Ap}, jd::Number) -> NTuple{8, Float64}

Get the Ap index for the day at instant compute every three hours.

space_index(::Val{:BSRN}, jd::Number) -> Int64

Get the BSRN index for the day at instant

space_index(::Val{:C9}, jd::Number) -> Float64

Get the C9 index for the day at instant

space_index(::Val{:Cp}, jd::Number) -> Float64

Get the Cp index for the day at instant

space_index(::Val{:DTC_Dst}, jd::Number) -> Float64

Get the exospheric temperature variation [K] caused by geomagnetic activity at Julian Day jd, computed from the Dst index using the JB2008 storm algorithm.

This provides a real-time alternative to the pre-computed DTC values from DTCFILE.TXT (available via Val(:DTC) from the JB2008 index set), which have a ~45 day publication lag.

During geomagnetic storms (Dst < -75 nT, ΔDst ≥ 50 nT), the temperature change is integrated using the differential equations from Burke et al. as extended by Bowman et al. (2008), matching the DTCMAKEDR Fortran reference implementation:

• Main phase: Eq. (8)/(10) with storm-magnitude-dependent slope S; Dst clamped to ≤ 0, no dTc floor.
• Recovery: Eq. (12) with S=0.13; storm terminates if dTc < 0.
• Late recovery: Eq. (13) with S=-2.5 (uses main-phase S when Dst dips).

During non-storm periods, dTc is the Jacchia 1970 ap-based temperature (ap capped at 50) if Celestrak is initialized, or 0 otherwise.

For times beyond the last available Dst observation, the Dst series is extended with quiet-time values (0 nT) so that any in-progress storm recovery completes naturally through the integral. In quiet extended regions the dTc converges to the ap baseline.

Reference

Bowman, B.R., et al., "A New Empirical Thermospheric Density Model JB2008 Using New Solar and Geomagnetic Indices," AIAA 2008-6438, 2008.

space_index(::Val{:DTC}, date::Number) -> Float64

Get the exospheric temperature variation [K] caused by the Dst index at instant (UTC).

space_index(::Val{:Dst}, jd::Number) -> Float64

Get the Dst (Disturbance Storm Time) index [nT] at the Julian Day jd.

The Dst index measures the intensity of the globally symmetric part of the equatorial ring current. Negative values indicate geomagnetic storms. Values are linearly interpolated between hourly observations.

For times beyond the last available observation, the Dst series is extended with quiet-time values (0 nT) so that any in-progress storm recovery completes naturally through the dTc integral.

Source

WDC for Geomagnetism, Kyoto University. https://wdc.kugi.kyoto-u.ac.jp/dstdir/

space_index(::Val{:F10adj_avg_center81}, jd::Number) -> Float64

Get the adjusted F10.7 index (10.7-cm solar flux) [10⁻²² W / (M² ⋅ Hz)] averaged over 81 days centered for the instant (UTC).

space_index(::Val{:F10adj_avg_last81}, jd::Number) -> Float64

Get the adjusted F10.7 index (10.7-cm solar flux) [10⁻²² W / (M² ⋅ Hz)] averaged over the last 81 days from the instant (UTC).

space_index(::Val{:F10adj}, jd::Number) -> Float64

Get the adjusted F10.7 index (10.7-cm solar flux) [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:F10obs_avg_center81}, jd::Number) -> Float64

Get the observed F10.7 index (10.7-cm solar flux) [10⁻²² W / (M² ⋅ Hz)] averaged over 81 days centered for the instant (UTC).

space_index(::Val{:F10obs_avg_last81}, jd::Number) -> Float64

Get the observed F10.7 index (10.7-cm solar flux) [10⁻²² W / (M² ⋅ Hz)] averaged over the last 81 days from the instant (UTC).

space_index(::Val{:F10obs}, jd::Number) -> Float64

Get the observed F10.7 index (10.7-cm solar flux) [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:Hp30}, jd::Number) -> NTuple{48, Float64}

Return the Hp30 index for the day at Julian Day jd.

The Hp30 index represents geomagnetic activity with 30-minute resolution. This function returns all 48 values for the day containing the given Julian Day.

space_index(::Val{:Hp60}, jd::Number) -> NTuple{24, Float64}

Return the Hp60 index for the day at Julian Day jd.

The Hp60 index represents geomagnetic activity with 60-minute (hourly) resolution. This function returns all 24 values for the day containing the given Julian Day.

space_index(::Val{:ISN}, jd::Number) -> Int64

Get the ISN index for the day at instant

space_index(::Val{:Kp_daily}, jd::Number) -> Float64

Get the daily Kp index for the day at instant.

space_index(::Val{:Kp}, jd::Number) -> NTuple{8, Float64}

Get the Kp index for the day at instant compute every three hours.

get_space_index(::Val{:M10}, date::Number) -> Float64

Get the MG2 index scaled to F10.7 [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:M81a}, date::Number) -> Float64

Get the 81-day averaged MG2 index scaled to F10.7 [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:ND}, jd::Number) -> Int64

Get the ND index for the day at instant

space_index(::Val{:S10}, date::Number) -> Float64

Get the EUV index (26-34 nm) scaled to F10.7 [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:S81a}, date::Number) -> Float64

Get the 81-day averaged EUV index (26-34 nm) scaled to F10.7 [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:Y10}, date::Number) -> Float64

Get the solar X-ray & Lya index scaled to F10.7 [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

space_index(::Val{:Y81a}, date::Number) -> Float64

Get the 81-day averaged solar X-ray & Lya index scaled to F10.7 [10⁻²² W / (M² ⋅ Hz)] for the instant (UTC).

urls(::Type{T}) where T<:SpaceIndexSet -> Vector{String}

Return the URLs to fetch the remote files associated with the space index set T.

@data_handler(T)

Return the optional data handler associated with space index set T. This variable stores an instance of T if the set was already initialized.

@object(T)

Return the object associated with the space index set T.

Throws

• Error: If the space index T was not initialized.

@register(T)

Register the the space index set T. This macro push the data into the global vector of space files and also creates the optional data handler for the processed structure.