Skip to content

EOP

Earth Orientation Parameter types, providers, and query functions.

See the EOP User Guide for concepts and usage.

Types

Type definitions for Earth Orientation Parameters (EOP).

Provides the core data types for EOP storage and lookup:

  • :class:EOPData: Immutable container holding sorted EOP arrays for JIT-compatible interpolation via jnp.searchsorted.
  • :class:EOPExtrapolation: Controls behavior when querying outside the data range.

EOPData 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.

EOPData

Bases: NamedTuple

Earth Orientation Parameter data for JIT-compatible lookups.

Stores EOP values as sorted JAX arrays, enabling O(log n) interpolation inside jax.jit via jnp.searchsorted. Missing optional values (dX, dY, lod in prediction regions) are stored as NaN.

Attributes:

Name Type Description
mjd Array

Sorted Modified Julian Dates, shape (N,).
pm_x Array

Polar motion x-component [rad], shape (N,).
pm_y Array

Polar motion y-component [rad], shape (N,).
ut1_utc Array

UT1-UTC offset [seconds], shape (N,).
dX Array

Celestial pole offset X [rad], shape (N,). NaN where missing.
dY Array

Celestial pole offset Y [rad], shape (N,). NaN where missing.
lod Array

Length of day excess [seconds], shape (N,). NaN where missing.
mjd_min Array

Scalar, first MJD in the dataset.
mjd_max Array

Scalar, last MJD in the dataset.
mjd_last_lod Array

Scalar, last MJD with valid LOD data.
mjd_last_dxdy Array

Scalar, last MJD with valid dX/dY data.

EOPExtrapolation

Bases: Enum

Extrapolation mode for EOP queries outside the data range.

Resolved at trace time (Python string), not at runtime. This follows the same pattern as ForceModelConfig booleans.

Attributes:

Name Type Description
HOLD

Clamp to the nearest boundary value.
ZERO

Return zero for out-of-range queries.

Query Functions

JIT-compatible EOP interpolation and query 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.

The extrapolation parameter is a Python string resolved at trace time, following the same pattern as ForceModelConfig booleans.

get_dxdy(eop, mjd, extrapolation=EOPExtrapolation.HOLD)

Query celestial pole offsets at the given MJD.

Values may be NaN if the data source does not include dX/dY for the requested epoch (e.g. far-future predictions).

Parameters:

Name Type Description Default
eop EOPData

EOP dataset.

 required
mjd ArrayLike

Modified Julian Date to query.

 required
extrapolation EOPExtrapolation

Extrapolation mode for out-of-range queries.

 HOLD

Returns:

Type Description
tuple[Array, Array]

Tuple of (dX, dY) celestial pole offsets [rad].

Examples:

from astrojax.eop import zero_eop, get_dxdy
eop = zero_eop()
dx, dy = get_dxdy(eop, 59569.0)

get_eop(eop, mjd, extrapolation=EOPExtrapolation.HOLD)

Query all EOP values at the given MJD.

Convenience function that returns all six EOP parameters at once.

Parameters:

Name Type Description Default
eop EOPData

EOP dataset.

 required
mjd ArrayLike

Modified Julian Date to query.

 required
extrapolation EOPExtrapolation

Extrapolation mode for out-of-range queries.

 HOLD

Returns:

Name Type Description
Array

Tuple of (pm_x, pm_y, ut1_utc, lod, dX, dY).
Units Array

pm_x/pm_y [rad], ut1_utc [s], lod [s], dX/dY [rad].

Examples:

from astrojax.eop import zero_eop, get_eop
eop = zero_eop()
pm_x, pm_y, ut1_utc, lod, dx, dy = get_eop(eop, 59569.0)

get_lod(eop, mjd, extrapolation=EOPExtrapolation.HOLD)

Query length-of-day excess at the given MJD.

The value may be NaN if the data source does not include LOD for the requested epoch (e.g. far-future predictions).

Parameters:

Name Type Description Default
eop EOPData

EOP dataset.

 required
mjd ArrayLike

Modified Julian Date to query.

 required
extrapolation EOPExtrapolation

Extrapolation mode for out-of-range queries.

 HOLD

Returns:

Type Description
Array

Length of day excess [seconds].

Examples:

from astrojax.eop import zero_eop, get_lod
eop = zero_eop()
lod = get_lod(eop, 59569.0)

get_pm(eop, mjd, extrapolation=EOPExtrapolation.HOLD)

Query polar motion components at the given MJD.

Parameters:

Name Type Description Default
eop EOPData

EOP dataset.

 required
mjd ArrayLike

Modified Julian Date to query.

 required
extrapolation EOPExtrapolation

Extrapolation mode for out-of-range queries.

 HOLD

Returns:

Type Description
tuple[Array, Array]

Tuple of (pm_x, pm_y) polar motion components [rad].

Examples:

from astrojax.eop import zero_eop, get_pm
eop = zero_eop()
pm_x, pm_y = get_pm(eop, 59569.0)

get_ut1_utc(eop, mjd, extrapolation=EOPExtrapolation.HOLD)

Query UT1-UTC offset at the given MJD.

Parameters:

Name Type Description Default
eop EOPData

EOP dataset.

 required
mjd ArrayLike

Modified Julian Date to query.

 required
extrapolation EOPExtrapolation

Extrapolation mode for out-of-range queries.

 HOLD

Returns:

Type Description
Array

UT1-UTC offset [seconds].

Examples:

from astrojax.eop import zero_eop, get_ut1_utc
eop = zero_eop()
ut1_utc = get_ut1_utc(eop, 59569.0)

Providers

Factory functions for creating EOPData instances.

Provides convenience constructors for common EOP configurations:

  • :func:static_eop: Constant EOP values (useful for testing or when specific values are known).
  • :func:zero_eop: All-zero EOP (equivalent to ignoring Earth orientation corrections).
  • :func:load_eop_from_file: Load from IERS standard format file.
  • :func:load_eop_from_standard_file: Alias for :func:load_eop_from_file.
  • :func:load_default_eop: Load bundled finals.all.iau2000.txt data.
  • :func:load_cached_eop: Load from a local cache, downloading fresh data from IERS when stale.

load_eop_from_standard_file = load_eop_from_file module-attribute

Alias for :func:load_eop_from_file.

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

Load EOP data from a local cache, downloading fresh data 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 of finals.all.iau2000.txt is downloaded from IERS. 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 EOP file. When None (the default), uses <cache_dir>/eop/finals.all.iau2000.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
EOPData

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

the bundled default data as a fallback.

Examples:

from astrojax.eop import load_cached_eop, get_ut1_utc

# Uses default cache location and 7-day refresh
eop = load_cached_eop()
val = get_ut1_utc(eop, 59569.0)

# Custom path and 1-day refresh
eop = load_cached_eop("/tmp/eop_cache/finals.txt", max_age_days=1.0)

load_default_eop()

Load the bundled default EOP data (finals.all.iau2000.txt).

Uses importlib.resources to locate the data file bundled with the package, following the same pattern as GravityModel.from_type().

Returns:

Type Description
EOPData

EOPData loaded from the bundled finals.all.iau2000.txt.

Examples:

from astrojax.eop import load_default_eop, get_ut1_utc
eop = load_default_eop()
val = get_ut1_utc(eop, 59569.0)

load_eop_from_file(filepath)

Load EOP data from an IERS standard format file.

Parses the file, converts lists to JAX arrays, and computes metadata scalars (mjd_min, mjd_max, last valid LOD/dXdY MJDs).

Parameters:

Name Type Description Default
filepath str | Path

Path to an IERS standard format file (e.g. finals.all.iau2000.txt).

 required

Returns:

Type Description
EOPData

EOPData ready for JIT-compatible lookups.

Raises:

Type Description
FileNotFoundError

If the file does not exist.
ValueError

If no valid EOP data is found.

Examples:

from astrojax.eop import load_eop_from_file, get_ut1_utc
eop = load_eop_from_file("path/to/finals.all.iau2000.txt")
val = get_ut1_utc(eop, 59569.0)

static_eop(pm_x=0.0, pm_y=0.0, ut1_utc=0.0, dX=0.0, dY=0.0, lod=0.0, mjd_min=0.0, mjd_max=99999.0)

Create an EOPData with constant values across the full MJD range.

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

Parameters:

Name Type Description Default
pm_x float

Polar motion x-component [rad]. Default: 0.0.

 0.0
pm_y float

Polar motion y-component [rad]. Default: 0.0.

 0.0
ut1_utc float

UT1-UTC offset [seconds]. Default: 0.0.

 0.0
dX float

Celestial pole offset X [rad]. Default: 0.0.

 0.0
dY float

Celestial pole offset Y [rad]. Default: 0.0.

 0.0
lod float

Length of day excess [seconds]. Default: 0.0.

 0.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
EOPData

EOPData with constant values.

Examples:

from astrojax.eop import static_eop, get_ut1_utc
eop = static_eop(ut1_utc=0.1)
val = get_ut1_utc(eop, 59569.0)  # returns ~0.1

zero_eop()

Create an EOPData with all-zero values.

Equivalent to ignoring Earth orientation corrections entirely. This is the simplest provider for cases where EOP corrections are not needed.

Returns:

Type Description
EOPData

EOPData with all values set to zero.

Examples:

from astrojax.eop import zero_eop, get_ut1_utc
eop = zero_eop()
val = get_ut1_utc(eop, 59569.0)  # returns 0.0