CachingSpaceWeatherProvider¶

Automatically download and cache space weather data from CelesTrak.

CachingSpaceWeatherProvider ¶

CachingSpaceWeatherProvider(max_age_seconds: int, auto_refresh: bool, extrapolate: str, cache_dir: str = None)

Caching Space Weather provider that automatically downloads updated files when stale.

This provider wraps a FileSpaceWeatherProvider and adds automatic cache management. It checks the age of the space weather file and downloads updated versions when the file exceeds the maximum age value. If the file doesn't exist, it will be downloaded on initialization from CelesTrak.

Parameters:

Name	Type	Description	Default
`max_age_seconds`	`int`	Maximum age of file in seconds before triggering a refresh	required
`auto_refresh`	`bool`	If True, automatically checks file age and refreshes on every data access	required
`extrapolate`	`str`	Behavior for dates outside data range: "Hold", "Zero", or "Error"	required
`cache_dir`	`str`	Custom cache directory. If None, uses ~/.cache/brahe/	`None`

Example

import brahe as bh

# Using default cache location (recommended)
provider = bh.CachingSpaceWeatherProvider(
    max_age_seconds=7 * 86400,  # 7 days
    auto_refresh=False,
    extrapolate="Hold"
)
bh.set_global_space_weather_provider(provider)

# Check file status
print(f"File loaded at: {provider.file_epoch()}")
print(f"File age: {provider.file_age() / 86400:.1f} days")

# Manually refresh
provider.refresh()

Initialize instance.

extrapolation `method descriptor` ¶

extrapolation() -> str

Get the extrapolation method.

Returns:

Name	Type	Description
`str`	`str`	Extrapolation method

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
print(f"Extrapolation: {provider.extrapolation()}")  # "Hold"

file_age `method descriptor` ¶

file_age() -> float

Get the age of the currently loaded file in seconds.

Returns:

Name	Type	Description
`float`	`float`	Age of the loaded file in seconds

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
age = provider.file_age()
print(f"File age: {age:.2f} seconds")

file_epoch `method descriptor` ¶

file_epoch() -> Epoch

Get the epoch when the space weather file was last loaded.

Returns:

Name	Type	Description
`Epoch`	`Epoch`	Epoch in UTC when file was loaded

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
file_epoch = provider.file_epoch()
print(f"File loaded at: {file_epoch}")

get_ap `method descriptor` ¶

get_ap(mjd: float) -> float

Get Ap index for the specified MJD.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date	required

Returns:

Name	Type	Description
`float`	`float`	Ap index

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
ap = provider.get_ap(60000.0)
print(f"Ap: {ap}")

get_ap_all `method descriptor` ¶

get_ap_all(mjd: float) -> list[float]

Get all eight 3-hourly Ap indices for the day.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date	required

Returns:

Type	Description
`list[float]`	list[float]: Array of 8 Ap indices

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
ap_all = provider.get_ap_all(60000.0)
print(f"8 Ap indices: {ap_all}")

get_ap_daily `method descriptor` ¶

get_ap_daily(mjd: float) -> float

Get daily average Ap index.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date	required

Returns:

Name	Type	Description
`float`	`float`	Daily average Ap

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
ap_daily = provider.get_ap_daily(60000.0)
print(f"Daily Ap: {ap_daily}")

get_f107_adj_avg81 `method descriptor` ¶

get_f107_adj_avg81(mjd: float) -> float

Get 81-day centered average adjusted F10.7 flux.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date	required

Returns:

Name	Type	Description
`float`	`float`	81-day average adjusted F10.7 flux in sfu

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
f107_adj_avg = provider.get_f107_adj_avg81(60000.0)
print(f"F10.7 adj 81-day avg: {f107_adj_avg} sfu")

get_f107_adjusted `method descriptor` ¶

get_f107_adjusted(mjd: float) -> float

Get adjusted F10.7 solar flux.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date	required

Returns:

Name	Type	Description
`float`	`float`	Adjusted F10.7 flux in sfu

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
f107_adj = provider.get_f107_adjusted(60000.0)
print(f"F10.7 adjusted: {f107_adj} sfu")

get_f107_obs_avg81 `method descriptor` ¶

get_f107_obs_avg81(mjd: float) -> float

Get 81-day centered average observed F10.7 flux.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date	required

Returns:

Name	Type	Description
`float`	`float`	81-day average F10.7 flux in sfu

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
f107_avg = provider.get_f107_obs_avg81(60000.0)
print(f"F10.7 81-day avg: {f107_avg} sfu")

get_f107_observed `method descriptor` ¶

get_f107_observed(mjd: float) -> float

Get observed F10.7 solar flux.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date	required

Returns:

Name	Type	Description
`float`	`float`	F10.7 flux in sfu

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
f107 = provider.get_f107_observed(60000.0)
print(f"F10.7: {f107} sfu")

get_kp `method descriptor` ¶

get_kp(mjd: float) -> float

Get Kp index for the specified MJD.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date	required

Returns:

Name	Type	Description
`float`	`float`	Kp index (0.0-9.0)

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
kp = provider.get_kp(60000.0)
print(f"Kp: {kp}")

get_kp_all `method descriptor` ¶

get_kp_all(mjd: float) -> list[float]

Get all eight 3-hourly Kp indices for the day.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date	required

Returns:

Type	Description
`list[float]`	list[float]: Array of 8 Kp indices

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
kp_all = provider.get_kp_all(60000.0)
print(f"8 Kp indices: {kp_all}")

get_kp_daily `method descriptor` ¶

get_kp_daily(mjd: float) -> float

Get daily average Kp index.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date	required

Returns:

Name	Type	Description
`float`	`float`	Daily average Kp

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
kp_daily = provider.get_kp_daily(60000.0)
print(f"Daily Kp: {kp_daily}")

get_last_ap `method descriptor` ¶

get_last_ap(mjd: float, n: int) -> list[float]

Get the last N 3-hourly Ap values.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date (end point)	required
`n`	`int`	Number of 3-hourly values to return	required

Returns:

Type	Description
`list[float]`	list[float]: List of Ap indices (oldest first)

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
ap_last = provider.get_last_ap(60000.0, 8)
print(f"Last 8 Ap values: {ap_last}")

get_last_daily_ap `method descriptor` ¶

get_last_daily_ap(mjd: float, n: int) -> list[float]

Get the last N daily average Ap values.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date (end point)	required
`n`	`int`	Number of daily values to return	required

Returns:

Type	Description
`list[float]`	list[float]: List of daily average Ap indices (oldest first)

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
ap_daily_last = provider.get_last_daily_ap(60000.0, 7)
print(f"Last 7 daily Ap: {ap_daily_last}")

get_last_daily_epochs `method descriptor` ¶

get_last_daily_epochs(mjd: float, n: int) -> list[Epoch]

Get epochs for the last N daily values.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date (end point)	required
`n`	`int`	Number of epochs to return	required

Returns:

Type	Description
`list[Epoch]`	list[Epoch]: Epoch objects, oldest first

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
epochs = provider.get_last_daily_epochs(60000.0, 7)
for epoch in epochs:
    print(f"Epoch: {epoch}")

get_last_daily_kp `method descriptor` ¶

get_last_daily_kp(mjd: float, n: int) -> list[float]

Get the last N daily average Kp values.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date (end point)	required
`n`	`int`	Number of daily values to return	required

Returns:

Type	Description
`list[float]`	list[float]: List of daily average Kp indices (oldest first)

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
kp_daily_last = provider.get_last_daily_kp(60000.0, 7)
print(f"Last 7 daily Kp: {kp_daily_last}")

get_last_f107 `method descriptor` ¶

get_last_f107(mjd: float, n: int) -> list[float]

Get the last N daily observed F10.7 values.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date (end point)	required
`n`	`int`	Number of daily values to return	required

Returns:

Type	Description
`list[float]`	list[float]: List of F10.7 values in sfu (oldest first)

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
f107_last = provider.get_last_f107(60000.0, 7)
print(f"Last 7 F10.7 values: {f107_last}")

get_last_kp `method descriptor` ¶

get_last_kp(mjd: float, n: int) -> list[float]

Get the last N 3-hourly Kp values.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date (end point)	required
`n`	`int`	Number of 3-hourly values to return	required

Returns:

Type	Description
`list[float]`	list[float]: List of Kp indices (oldest first)

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
kp_last = provider.get_last_kp(60000.0, 8)
print(f"Last 8 Kp values: {kp_last}")

get_last_kpap_epochs `method descriptor` ¶

get_last_kpap_epochs(mjd: float, n: int) -> list[Epoch]

Get epochs for the last N 3-hourly Kp/Ap intervals.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date (end point)	required
`n`	`int`	Number of epochs to return	required

Returns:

Type	Description
`list[Epoch]`	list[Epoch]: Epoch objects, oldest first

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
epochs = provider.get_last_kpap_epochs(60000.0, 8)
for epoch in epochs:
    print(f"Epoch: {epoch}")

get_sunspot_number `method descriptor` ¶

get_sunspot_number(mjd: float) -> int

Get International Sunspot Number.

Parameters:

Name	Type	Description	Default
`mjd`	`float`	Modified Julian Date	required

Returns:

Name	Type	Description
`int`	`int`	Sunspot number

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
ssn = provider.get_sunspot_number(60000.0)
print(f"Sunspot number: {ssn}")

is_initialized `method descriptor` ¶

is_initialized() -> bool

Check if the provider is initialized.

Returns:

Name	Type	Description
`bool`	`bool`	True if initialized

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
print(f"Initialized: {provider.is_initialized()}")  # True

len `method descriptor` ¶

len() -> int

Get the number of space weather data points.

Returns:

Name	Type	Description
`int`	`int`	Number of data points

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
print(f"Data points: {provider.len()}")

mjd_last_daily_predicted `method descriptor` ¶

mjd_last_daily_predicted() -> float

Get the last MJD with daily predicted data.

Returns:

Name	Type	Description
`float`	`float`	Last MJD with daily predicted data

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
print(f"Last daily predicted MJD: {provider.mjd_last_daily_predicted()}")

mjd_last_monthly_predicted `method descriptor` ¶

mjd_last_monthly_predicted() -> float

Get the last MJD with monthly predicted data.

Returns:

Name	Type	Description
`float`	`float`	Last MJD with monthly predicted data

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
print(f"Last monthly predicted MJD: {provider.mjd_last_monthly_predicted()}")

mjd_last_observed `method descriptor` ¶

mjd_last_observed() -> float

Get the last MJD with observed data.

Returns:

Name	Type	Description
`float`	`float`	Last MJD with observed data

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
print(f"Last observed MJD: {provider.mjd_last_observed()}")

mjd_max `method descriptor` ¶

mjd_max() -> float

Get the maximum MJD in the dataset.

Returns:

Name	Type	Description
`float`	`float`	Maximum Modified Julian Date

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
print(f"Max MJD: {provider.mjd_max()}")

mjd_min `method descriptor` ¶

mjd_min() -> float

Get the minimum MJD in the dataset.

Returns:

Name	Type	Description
`float`	`float`	Minimum Modified Julian Date

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
print(f"Min MJD: {provider.mjd_min()}")

refresh `method descriptor` ¶

refresh() -> Any

Manually refresh the cached space weather data.

Checks if the file needs updating and downloads a new version if necessary.

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
provider.refresh()

sw_type `method descriptor` ¶

sw_type() -> str

Get the space weather data type.

Returns:

Name	Type	Description
`str`	`str`	Space weather type

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider(7 * 86400, False, "Hold")
print(f"Type: {provider.sw_type()}")  # "CssiSpaceWeather"

with_url `builtin` ¶

with_url(url: str, max_age_seconds: int, auto_refresh: bool, extrapolate: str, cache_dir: str = None) -> CachingSpaceWeatherProvider

Create a caching provider with a custom URL for downloading space weather data.

Parameters:

Name	Type	Description	Default
`url`	`str`	URL to download space weather data from	required
`max_age_seconds`	`int`	Maximum age of file in seconds before triggering a refresh	required
`auto_refresh`	`bool`	If True, automatically checks file age and refreshes on every access	required
`extrapolate`	`str`	Behavior for dates outside data range: "Hold", "Zero", or "Error"	required
`cache_dir`	`str`	Custom cache directory. If None, uses ~/.cache/brahe/	`None`

Returns:

Name	Type	Description
`CachingSpaceWeatherProvider`	`CachingSpaceWeatherProvider`	Provider with automatic cache management from custom URL

Example

import brahe as bh

provider = bh.CachingSpaceWeatherProvider.with_url(
    url="https://example.com/sw19571001.txt",
    max_age_seconds=7 * 86400,  # 7 days
    auto_refresh=False,
    extrapolate="Hold"
)
bh.set_global_space_weather_provider(provider)

CachingSpaceWeatherProvider¶