Skip to content

Space Weather

Space weather types, providers, and query functions.

See the Space Weather User Guide for concepts and usage.

Types

Type definitions for Space Weather data.

Provides the core data type for space weather storage and lookup:

  • :class:SpaceWeatherData: Immutable container holding sorted space weather arrays for JIT-compatible lookup via jnp.searchsorted.

SpaceWeatherData is a :class:~typing.NamedTuple, which JAX treats as a pytree automatically. This means it works seamlessly with jax.jit, jax.vmap, and jax.lax control flow primitives.

SpaceWeatherData

Bases: NamedTuple

Space weather data for JIT-compatible lookups.

Stores space weather values as sorted JAX arrays, enabling O(log n) lookup inside jax.jit via jnp.searchsorted. Missing values (e.g. Kp/Ap in monthly-predicted regions) are stored as NaN.

Attributes:

Name Type Description
mjd Array

Sorted Modified Julian Dates (one per day), shape (N,).
kp Array

3-hourly Kp indices (0.0-9.0 scale), shape (N, 8).
ap Array

3-hourly Ap indices, shape (N, 8).
ap_daily Array

Daily average Ap index, shape (N,).
f107_obs Array

Observed 10.7 cm solar radio flux [sfu], shape (N,).
f107_adj Array

Adjusted 10.7 cm solar radio flux [sfu], shape (N,).
f107_obs_ctr81 Array

81-day centered average observed F10.7, shape (N,).
f107_obs_lst81 Array

81-day last average observed F10.7, shape (N,).
f107_adj_ctr81 Array

81-day centered average adjusted F10.7, shape (N,).
f107_adj_lst81 Array

81-day last average adjusted F10.7, shape (N,).
mjd_min Array

Scalar, first MJD in the dataset.
mjd_max Array

Scalar, last MJD in the dataset.

Query Functions

JIT-compatible space weather lookup functions.

All functions use only JAX primitives (jnp.searchsorted, array indexing, jnp.where) and are fully compatible with jax.jit, jax.vmap, and jax.grad.

get_sw_ap(sw, mjd)

Query 3-hourly Ap index at the given MJD.

Parameters:

Name Type Description Default
sw SpaceWeatherData

Space weather dataset.

 required
mjd ArrayLike

Modified Julian Date to query.

 required

Returns:

Type Description
Array

Ap index for the 3-hour interval containing the MJD.

get_sw_ap_array(sw, mjd)

Build the 7-element NRLMSISE-00 AP array.

Constructs the magnetic activity array required by the NRLMSISE-00 model:

  • [0]: Daily Ap
  • [1]: Current 3-hour Ap
  • [2]: 3-hour Ap at -3h
  • [3]: 3-hour Ap at -6h
  • [4]: 3-hour Ap at -9h
  • [5]: Average of eight 3-hour Ap from 12-33h prior
  • [6]: Average of eight 3-hour Ap from 36-57h prior

All lookups use compile-time known offsets (unrolled at trace time).

Parameters:

Name Type Description Default
sw SpaceWeatherData

Space weather dataset.

 required
mjd ArrayLike

Modified Julian Date to query.

 required

Returns:

Type Description
Array

Array of shape (7,) with the NRLMSISE-00 AP array.

get_sw_ap_daily(sw, mjd)

Query daily average Ap index at the given MJD.

Parameters:

Name Type Description Default
sw SpaceWeatherData

Space weather dataset.

 required
mjd ArrayLike

Modified Julian Date to query.

 required

Returns:

Type Description
Array

Daily average Ap index.

get_sw_f107_adj(sw, mjd)

Query adjusted F10.7 solar flux at the given MJD.

Parameters:

Name Type Description Default
sw SpaceWeatherData

Space weather dataset.

 required
mjd ArrayLike

Modified Julian Date to query.

 required

Returns:

Type Description
Array

Adjusted F10.7 flux [sfu].

get_sw_f107_obs(sw, mjd)

Query observed F10.7 solar flux at the given MJD.

Parameters:

Name Type Description Default
sw SpaceWeatherData

Space weather dataset.

 required
mjd ArrayLike

Modified Julian Date to query.

 required

Returns:

Type Description
Array

Observed F10.7 flux [sfu].

get_sw_f107_obs_ctr81(sw, mjd)

Query 81-day centered average observed F10.7 at the given MJD.

Parameters:

Name Type Description Default
sw SpaceWeatherData

Space weather dataset.

 required
mjd ArrayLike

Modified Julian Date to query.

 required

Returns:

Type Description
Array

81-day centered average observed F10.7 flux [sfu].

get_sw_f107_obs_lst81(sw, mjd)

Query 81-day last average observed F10.7 at the given MJD.

Parameters:

Name Type Description Default
sw SpaceWeatherData

Space weather dataset.

 required
mjd ArrayLike

Modified Julian Date to query.

 required

Returns:

Type Description
Array

81-day last average observed F10.7 flux [sfu].

get_sw_kp(sw, mjd)

Query 3-hourly Kp index at the given MJD.

Parameters:

Name Type Description Default
sw SpaceWeatherData

Space weather dataset.

 required
mjd ArrayLike

Modified Julian Date to query.

 required

Returns:

Type Description
Array

Kp index (0.0-9.0) for the 3-hour interval containing the MJD.

Providers

Factory functions for creating SpaceWeatherData instances.

Provides convenience constructors for common space weather configurations:

  • :func:static_space_weather: Constant space weather values (useful for testing or when specific values are known).
  • :func:zero_space_weather: All-zero space weather.
  • :func:load_sw_from_file: Load from CSSI format file.
  • :func:load_default_sw: Load bundled sw19571001.txt data.
  • :func:load_cached_sw: Load from a local cache, downloading fresh data from CelesTrak when stale.

load_cached_sw(filepath=None, *, max_age_days=_DEFAULT_MAX_AGE_DAYS)

Load space weather data from a local cache, downloading when stale.

Checks whether the cached file at filepath exists and is younger than max_age_days. If the file is missing or stale, a fresh copy is downloaded from CelesTrak. If the download fails or the file cannot be parsed, the bundled default data is returned so this function never raises on network issues.

Parameters:

Name Type Description Default
filepath str | Path | None

Path to the cached SW file. When None (the default), uses <cache_dir>/space_weather/sw19571001.txt.

 None
max_age_days float

Maximum acceptable age of the cached file in days. Defaults to 7.

 _DEFAULT_MAX_AGE_DAYS

Returns:

Type Description
SpaceWeatherData

SpaceWeatherData loaded from the cached (or freshly downloaded) file,
SpaceWeatherData

or the bundled default data as a fallback.

Examples:

from astrojax.space_weather import load_cached_sw, get_sw_f107_obs
sw = load_cached_sw()
val = get_sw_f107_obs(sw, 59569.0)

load_default_sw()

Load the bundled default space weather data (sw19571001.txt).

Uses importlib.resources to locate the data file bundled with the package.

Returns:

Type Description
SpaceWeatherData

SpaceWeatherData loaded from the bundled sw19571001.txt.

Examples:

from astrojax.space_weather import load_default_sw, get_sw_f107_obs
sw = load_default_sw()
val = get_sw_f107_obs(sw, 59569.0)

load_sw_from_file(filepath)

Load space weather data from a CSSI format file.

Parses the file, converts lists to JAX arrays, and computes metadata scalars (mjd_min, mjd_max).

Parameters:

Name Type Description Default
filepath str | Path

Path to a CSSI space weather file (e.g. sw19571001.txt).

 required

Returns:

Type Description
SpaceWeatherData

SpaceWeatherData ready for JIT-compatible lookups.

Raises:

Type Description
FileNotFoundError

If the file does not exist.
ValueError

If no valid data is found.

Examples:

from astrojax.space_weather import load_sw_from_file, get_sw_f107_obs
sw = load_sw_from_file("path/to/sw19571001.txt")
val = get_sw_f107_obs(sw, 59569.0)

static_space_weather(ap=4.0, f107=150.0, f107a=150.0, kp=1.0, mjd_min=0.0, mjd_max=99999.0)

Create a SpaceWeatherData with constant values.

Useful for testing or when specific constant space weather values are known. The resulting dataset contains two points (at mjd_min and mjd_max) with identical values, so lookups return the constant everywhere.

Parameters:

Name Type Description Default
ap float

Constant Ap index. Default: 4.0.

 4.0
f107 float

Constant F10.7 flux [sfu]. Default: 150.0.

 150.0
f107a float

Constant 81-day average F10.7 flux [sfu]. Default: 150.0.

 150.0
kp float

Constant Kp index. Default: 1.0.

 1.0
mjd_min float

Start of the valid MJD range. Default: 0.0.

 0.0
mjd_max float

End of the valid MJD range. Default: 99999.0.

 99999.0

Returns:

Type Description
SpaceWeatherData

SpaceWeatherData with constant values.

Examples:

from astrojax.space_weather import static_space_weather, get_sw_f107_obs
sw = static_space_weather(f107=200.0)
val = get_sw_f107_obs(sw, 59569.0)  # returns ~200.0

zero_space_weather()

Create a SpaceWeatherData with all-zero values.

Returns:

Type Description
SpaceWeatherData

SpaceWeatherData with all values set to zero.

Examples:

from astrojax.space_weather import zero_space_weather, get_sw_f107_obs
sw = zero_space_weather()
val = get_sw_f107_obs(sw, 59569.0)  # returns 0.0