orbix.observatory.orbit

orbix.observatory.orbit#

L2 halo orbit model for space observatories.

Provides an equinox module that interpolates a pre-computed L2 halo orbit to give telescope position at any time. Based on the EXOSIMS ObservatoryL2Halo implementation.

The halo orbit data is stored as an .npz file (converted from the EXOSIMS MATLAB data by scripts/convert_halo_mat.py).

Classes#

ObservatoryL2Halo

Space telescope on an L2 halo orbit.

Functions#

_load_default_halo_data()

Load the bundled L2 halo orbit .npz data.

Module Contents#

orbix.observatory.orbit._load_default_halo_data()[source]#

Load the bundled L2 halo orbit .npz data.

Return type:

dict

class orbix.observatory.orbit.ObservatoryL2Halo[source]#

Bases: equinox.Module

Space telescope on an L2 halo orbit.

This is an equinox module that stores the halo orbit state and provides JIT-compatible methods for position and geometry queries.

The orbit is parameterized as a periodic interpolation of a ~6-month halo around the Sun-Earth L2 point.

Parameters:

  • equinox_mjd – Reference equinox epoch in MJD (default: 60575.25).

  • halo_start_day – Offset into halo orbit at mission start (days).

Example

>>> obs = ObservatoryL2Halo.from_default()
>>> pos = obs.position_ecliptic(60000.0)  # AU, shape (3,)
_interp_x: interpax.Interpolator1D#
_interp_y: interpax.Interpolator1D#
_interp_z: interpax.Interpolator1D#
_period_yr: float#
_L2_dist_AU: float#
_mu: float#
_equinox_mjd: float#
_halo_start_yr: float#
_d2yr: float = 0.0027378507871321013#
classmethod from_default(equinox_mjd=60575.25, halo_start_day=0.0)[source]#

Create from bundled L2 halo orbit data.

Parameters:

  • equinox_mjd (float) – Reference equinox epoch in MJD.

  • halo_start_day (float) – Offset into halo orbit at mission start (days).

Returns:

Configured ObservatoryL2Halo instance.

Return type:

ObservatoryL2Halo

classmethod from_npz(npz_path, equinox_mjd=60575.25, halo_start_day=0.0)[source]#

Create from a custom .npz file.

Parameters:

  • npz_path (str) – Path to .npz file with halo orbit data.

  • equinox_mjd (float) – Reference equinox epoch in MJD.

  • halo_start_day (float) – Offset into halo orbit at mission start (days).

Returns:

Configured ObservatoryL2Halo instance.

Return type:

ObservatoryL2Halo

property period_yr: float#

Halo orbital period in years.

Return type:

float

property L2_dist_AU: float#

Sun-L2 distance in AU.

Return type:

float

_halo_time(mjd)[source]#

Convert MJD to periodic halo time in years.

Parameters:

mjd (float)

Return type:

float

position_ecliptic(mjd)[source]#

Heliocentric ecliptic position of the telescope at time mjd.

Parameters:

mjd (float) – Modified Julian Date (scalar).

Returns:

Position vector in heliocentric ecliptic frame (AU), shape (3,).

Return type:

jax.numpy.ndarray

sun_angle(mjd, ra_rad, dec_rad)[source]#

Angular separation between Sun and target as seen from the telescope.

Parameters:

  • mjd (float) – Modified Julian Date.

  • ra_rad (float) – Target right ascension in radians.

  • dec_rad (float) – Target declination in radians.

Returns:

Angular separation in radians.

Return type:

float

solar_elongation_deg(mjd, ra_rad, dec_rad)[source]#

3D solar elongation in degrees.

Identical to sun_angle() converted to degrees. This is the angular distance between the Sun and target as seen from the observer, NOT the Leinert helio-ecliptic longitude difference Delta_lambda_sun. For the latter use helio_ecliptic_longitude_deg().

Parameters:

  • mjd (float) – Modified Julian Date.

  • ra_rad (float) – Target right ascension in radians.

  • dec_rad (float) – Target declination in radians.

Returns:

Solar elongation in degrees, [0, 180].

Return type:

float

helio_ecliptic_longitude_deg(mjd, ra_rad, dec_rad)[source]#

Helio-ecliptic longitude difference |lambda_target - lambda_sun|.

This is the Leinert+1998 Delta_lambda_sun coordinate used to index Table 17 (together with ecliptic latitude). It is the absolute difference between the target’s ecliptic longitude and the Sun’s apparent ecliptic longitude (as seen from the observer, which is parallax-negligible for distant targets), wrapped onto [0, 180] deg.

For ecliptic-plane targets this equals the 3D solar elongation; for high-latitude targets the two diverge – only this quantity is correct as the Leinert table lookup.

Parameters:

  • mjd (float) – Modified Julian Date.

  • ra_rad (float) – Target right ascension in radians.

  • dec_rad (float) – Target declination in radians.

Returns:

|lambda_target - lambda_sun| in degrees, [0, 180].

Return type:

float

ecliptic_latitude_deg(mjd, ra_rad, dec_rad)[source]#

Target ecliptic latitude in degrees.

Argument order matches sun_angle(), solar_elongation_deg(), and helio_ecliptic_longitude_deg() so the four geometry helpers are interchangeable at call sites.

Parameters:

  • mjd (float) – Modified Julian Date (used for obliquity at this epoch).

  • ra_rad (float) – Target right ascension in radians.

  • dec_rad (float) – Target declination in radians.

Returns:

Ecliptic latitude in degrees, [-90, 90].

Return type:

float