special_observatories
Resolve space-based (“special case”) MPC observatory codes via JPL Horizons.
A handful of MPC observatory codes denote spacecraft rather than fixed ground stations (issue #55). They have no parallax constants, so layup cannot compute their position geometrically, and – unlike a roving ground observer – the user usually does not carry an explicit per-observation position for them. For these codes we query the JPL Horizons vector API for the spacecraft’s geocentric state at each observation epoch and feed it into the same moving-observer path that an ADES-supplied position uses (issue #147).
The obscode -> NAIF-id map is ported from the Rust spacerocks project
(~/Dropbox/roman-footprint/spacerocks). Spacecraft carry negative NAIF ids
by JPL convention.
This is intentionally a live HTTP lookup (the case is rare); a user-supplied ADES position always takes priority, so fits never depend on Horizons being reachable when a position is provided.
Attributes
Functions
|
SPICE ephemeris time (seconds past J2000 TDB) -> Julian Date (TDB). |
|
Whether |
|
Geocentric ICRF state of a spacecraft at the given epochs, via JPL Horizons. |
|
The raw chunked Horizons query, with no disk cache (one network round-trip |
|
Resolve the persistent-cache root directory, or |
|
|
|
|
|
Best-effort atomic write of one (pos, vel) state. Distinct epochs are |
|
|
|
Parse the CSV vector table between the |
Module Contents
- query_horizons_geocentric(naif_id, jd_tdb_list, timeout=30, cache_dir=None)[source]
Geocentric ICRF state of a spacecraft at the given epochs, via JPL Horizons.
- Parameters:
naif_id (str) – JPL/NAIF id of the spacecraft (e.g.
"-48"for Hubble).jd_tdb_list (sequence of float) – Observation epochs as Julian Date (TDB).
timeout (float, optional) – Per-request HTTP timeout in seconds.
cache_dir (str or path or None or False, optional) – Location of the persistent
(naif_id, jd) -> statedisk cache. The states are geometric (VEC_CORR='NONE') and therefore deterministic and safe to cache across objects, processes, and runs – one Horizons call per (spacecraft, epoch), ever, instead of once per object per process (which rate-limits to HTTP 503 at catalog scale). Precedence: an explicitcache_dir(uses ahorizons/subdir under it) > theLAYUP_HORIZONS_CACHEenv var > the default layup pooch cache. Passcache_dir=False(orLAYUP_HORIZONS_CACHE=0) to disable.
- Returns:
{jd_tdb: (pos_km, vel_km_s)}; each value is a length-3numpyarray. Positions are geocentric (center = Earth body center), ICRF / equatorial-J2000, in km, and velocities in km/s. No light-time or aberration correction is applied (VEC_CORR='NONE'): the geometric state at the requested TDB epoch is returned, matching how layup supplies every other observer position (light time is handled later, in the integrator).- Return type:
dict
Notes
We deliberately query the geocentric spacecraft state (center = Earth’s body center) rather than the barycentric one, so this plugs into the same “geocentric observer offset + Earth’s barycentric state” path the ground stations use:
_barycentric_moving_observatoryadds Earth’s barycentric state (from layup’s own SPICE kernel) to this offset. Referencing the offset against a physical body (Earth) is more reproducible than referencing against the solar-system barycenter, whose definition shifts between ephemeris versions.Caveat for high-precision work: Earth’s geocenter as realized by layup’s SPICE kernel may differ slightly from the geocenter implied by the spacecraft’s Horizons reference ephemeris. The geocentric offset cancels Earth’s own position to first order, but a small residual inconsistency (~meters) can remain. That is negligible for normal astrometry, but could matter for very high precision applications such as space-based stellar occultations – flagged here as a known limitation (see PR #377 discussion).
- _query_horizons_uncached(naif_id, jd_list, timeout)[source]
The raw chunked Horizons query, with no disk cache (one network round-trip per
_TLIST_CHUNKepochs).
- _horizons_cache_root(cache_dir)[source]
Resolve the persistent-cache root directory, or
Noneto disable caching.See
query_horizons_geocentricfor the precedence. Returns aPathwhose per-spacecraft subdirectories hold one<jd>.npzper cached epoch.
- _cache_store(cdir, jd, state)[source]
Best-effort atomic write of one (pos, vel) state. Distinct epochs are distinct files, so this is lock-free and safe on a shared/parallel filesystem; a temp-file-plus-rename keeps a concurrent reader from seeing a partial file. A cache write must never break a fit, so failures are swallowed.