CachingEOPProvider¶

CachingEOPProvider ¶

CachingEOPProvider(eop_type: str, max_age_seconds: int, auto_refresh: bool, interpolate: bool, extrapolate: str, filepath: str = ...)

Caching EOP provider that automatically downloads updated files when stale.

This provider wraps a FileEOPProvider and adds automatic cache management. It checks the age of the EOP file and downloads updated versions when the file exceeds the maximum age threshold. If the file doesn't exist, it will be downloaded on initialization.

Parameters:

Name	Type	Description	Default
`eop_type`	`str`	Type of EOP file - "C04" for IERS C04 format or "StandardBulletinA" for IERS finals2000A.all format	required
`max_age_seconds`	`int`	Maximum age of file in seconds before triggering a refresh. Common values: 86400 (1 day), 604800 (7 days)	required
`auto_refresh`	`bool`	If True, automatically checks file age and refreshes on every data access. If False, only checks on initialization and manual refresh() calls	required
`interpolate`	`bool`	Enable linear interpolation between tabulated EOP values. Recommended: True for smoother data	required
`extrapolate`	`str`	Behavior for dates outside EOP data range: "Hold" (use last known value), "Zero" (return 0.0), or "Error" (raise exception)	required
`filepath`	`str`	Path to the EOP file (will be created if it doesn't exist). If None, uses default cache location: - StandardBulletinA: ~/.cache/brahe/finals.all.iau2000.txt - C04: ~/.cache/brahe/EOP_20_C04_one_file_1962-now.txt	`...`

Raises:

Type	Description
`RuntimeError`	If file download fails or file is invalid

Example

import brahe as bh

# Using default cache location (recommended)
provider = bh.CachingEOPProvider(
    eop_type="StandardBulletinA",
    max_age_seconds=7 * 86400,  # 7 days
    auto_refresh=False,
    interpolate=True,
    extrapolate="Hold"
)
bh.set_global_eop_provider_from_caching_provider(provider)

# Check and refresh as needed
provider.refresh()

# With explicit filepath
provider = bh.CachingEOPProvider(
    eop_type="StandardBulletinA",
    max_age_seconds=7 * 86400,
    auto_refresh=False,
    interpolate=True,
    extrapolate="Hold",
    filepath="./eop_data/finals.all.iau2000.txt"
)

# Auto-refresh mode (convenience)
auto_provider = bh.CachingEOPProvider(
    eop_type="StandardBulletinA",
    max_age_seconds=24 * 3600,  # 24 hours
    auto_refresh=True,  # Checks on every access
    interpolate=True,
    extrapolate="Hold"
)

Initialize instance.

doc `class-attribute` ¶

__doc__ = 'Caching EOP provider that automatically downloads updated files when stale.\n\nThis provider wraps a FileEOPProvider and adds automatic cache management.\nIt checks the age of the EOP file and downloads updated versions when the file\nexceeds the maximum age threshold. If the file doesn\'t exist, it will be\ndownloaded on initialization.\n\nArgs:\n    eop_type (str): Type of EOP file - "C04" for IERS C04 format or\n        "StandardBulletinA" for IERS finals2000A.all format\n    max_age_seconds (int): Maximum age of file in seconds before triggering\n        a refresh. Common values: 86400 (1 day), 604800 (7 days)\n    auto_refresh (bool): If True, automatically checks file age and refreshes\n        on every data access. If False, only checks on initialization and\n        manual refresh() calls\n    interpolate (bool): Enable linear interpolation between tabulated EOP\n        values. Recommended: True for smoother data\n    extrapolate (str): Behavior for dates outside EOP data range:\n        "Hold" (use last known value), "Zero" (return 0.0), or "Error" (raise exception)\n    filepath (str, optional): Path to the EOP file (will be created if it doesn\'t exist).\n        If None, uses default cache location:\n        - StandardBulletinA: ~/.cache/brahe/finals.all.iau2000.txt\n        - C04: ~/.cache/brahe/EOP_20_C04_one_file_1962-now.txt\n\nRaises:\n    RuntimeError: If file download fails or file is invalid\n\nExample:\n    ```python\n    import brahe as bh\n\n    # Using default cache location (recommended)\n    provider = bh.CachingEOPProvider(\n        eop_type="StandardBulletinA",\n        max_age_seconds=7 * 86400,  # 7 days\n        auto_refresh=False,\n        interpolate=True,\n        extrapolate="Hold"\n    )\n    bh.set_global_eop_provider_from_caching_provider(provider)\n\n    # Check and refresh as needed\n    provider.refresh()\n\n    # With explicit filepath\n    provider = bh.CachingEOPProvider(\n        eop_type="StandardBulletinA",\n        max_age_seconds=7 * 86400,\n        auto_refresh=False,\n        interpolate=True,\n        extrapolate="Hold",\n        filepath="./eop_data/finals.all.iau2000.txt"\n    )\n\n    # Auto-refresh mode (convenience)\n    auto_provider = bh.CachingEOPProvider(\n        eop_type="StandardBulletinA",\n        max_age_seconds=24 * 3600,  # 24 hours\n        auto_refresh=True,  # Checks on every access\n        interpolate=True,\n        extrapolate="Hold"\n    )\n    ```'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

module `class-attribute` ¶

__module__ = 'brahe._brahe'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

new `builtin` ¶

__new__(*args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

repr `method descriptor` ¶

__repr__() -> str

Return repr(self).

str `method descriptor` ¶

__str__() -> str

Return str(self).

eop_type `method descriptor` ¶

eop_type() -> str

Get the EOP file type.

Returns:

Name	Type	Description
`str`	`str`	EOP type ("C04", "StandardBulletinA", etc.)

extrapolation `method descriptor` ¶

extrapolation() -> str

Get the extrapolation method.

Returns:

Name	Type	Description
`str`	`str`	Extrapolation method ("Hold", "Zero", or "Error")

file_age `method descriptor` ¶

file_age() -> float

Get the age of the currently loaded EOP file in seconds.

Returns:

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

Example

import brahe as bh

provider = bh.CachingEOPProvider(
    eop_type="StandardBulletinA",
    max_age_seconds=7 * 86400,
    auto_refresh=False,
    interpolate=True,
    extrapolate="Hold"
)

age = provider.file_age()
print(f"EOP file age: {age:.2f} seconds")

file_epoch `method descriptor` ¶

file_epoch() -> Epoch

Get the epoch when the EOP file was last loaded.

Returns:

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

Example

import brahe as bh

provider = bh.CachingEOPProvider(
    eop_type="StandardBulletinA",
    max_age_seconds=7 * 86400,
    auto_refresh=False,
    interpolate=True,
    extrapolate="Hold"
)

file_epoch = provider.file_epoch()
print(f"EOP file loaded at: {file_epoch}")

get_dxdy `method descriptor` ¶

get_dxdy(mjd: float) -> tuple[float, float]

Get celestial pole offsets for a given MJD.

Parameters:

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

Returns:

Type	Description
`tuple[float, float]`	tuple[float, float]: Celestial pole offsets dx and dy in radians

get_eop `method descriptor` ¶

get_eop(mjd: float) -> Tuple

Get all EOP parameters for a given MJD.

Parameters:

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

Returns:

Name	Type	Description
`tuple`	`Tuple`	(pm_x, pm_y, ut1_utc, dx, dy, lod)

get_lod `method descriptor` ¶

get_lod(mjd: float) -> float

Get length of day offset for a given MJD.

Parameters:

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

Returns:

Name	Type	Description
`float`	`float`	Length of day offset in seconds

get_pm `method descriptor` ¶

get_pm(mjd: float) -> tuple[float, float]

Get polar motion components for a given MJD.

Parameters:

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

Returns:

Type	Description
`tuple[float, float]`	tuple[float, float]: Polar motion x and y components in radians

get_ut1_utc `method descriptor` ¶

get_ut1_utc(mjd: float) -> float

Get UT1-UTC time difference for a given MJD.

Parameters:

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

Returns:

Name	Type	Description
`float`	`float`	UT1-UTC time difference in seconds

interpolation `method descriptor` ¶

interpolation() -> bool

Check if interpolation is enabled.

Returns:

Name	Type	Description
`bool`	`bool`	True if interpolation is enabled

is_initialized `method descriptor` ¶

is_initialized() -> bool

Check if the provider is initialized.

Returns:

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

len `method descriptor` ¶

len() -> int

Get the number of EOP data points.

Returns:

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

mjd_last_dxdy `method descriptor` ¶

mjd_last_dxdy() -> float

Get the last MJD with valid celestial pole offset data.

Returns:

Name	Type	Description
`float`	`float`	Last MJD with dX/dY data

mjd_last_lod `method descriptor` ¶

mjd_last_lod() -> float

Get the last MJD with valid LOD data.

Returns:

Name	Type	Description
`float`	`float`	Last MJD with length of day data

mjd_max `method descriptor` ¶

mjd_max() -> float

Get the maximum MJD in the dataset.

Returns:

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

mjd_min `method descriptor` ¶

mjd_min() -> float

Get the minimum MJD in the dataset.

Returns:

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

refresh `method descriptor` ¶

refresh() -> Any

Manually refresh the cached EOP data.

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

Example

import brahe as bh

provider = bh.CachingEOPProvider(
    eop_type="StandardBulletinA",
    max_age_seconds=7 * 86400,
    auto_refresh=False,
    interpolate=True,
    extrapolate="Hold"
)

# Later, manually force a refresh check
provider.refresh()

CachingEOPProvider¶