orbix.observatory.orbit
=======================

.. py:module:: orbix.observatory.orbit

.. autoapi-nested-parse::

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

.. autoapisummary::

   orbix.observatory.orbit.ObservatoryL2Halo


Functions
---------

.. autoapisummary::

   orbix.observatory.orbit._load_default_halo_data


Module Contents
---------------

.. py:function:: _load_default_halo_data()

   Load the bundled L2 halo orbit .npz data.


.. py:class:: ObservatoryL2Halo

   Bases: :py:obj:`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.

   :param equinox_mjd: Reference equinox epoch in MJD (default: 60575.25).
   :param halo_start_day: Offset into halo orbit at mission start (days).

   .. rubric:: Example

   >>> obs = ObservatoryL2Halo.from_default()
   >>> pos = obs.position_ecliptic(60000.0)  # AU, shape (3,)


   .. py:attribute:: _interp_x
      :type:  interpax.Interpolator1D


   .. py:attribute:: _interp_y
      :type:  interpax.Interpolator1D


   .. py:attribute:: _interp_z
      :type:  interpax.Interpolator1D


   .. py:attribute:: _period_yr
      :type:  float


   .. py:attribute:: _L2_dist_AU
      :type:  float


   .. py:attribute:: _mu
      :type:  float


   .. py:attribute:: _equinox_mjd
      :type:  float


   .. py:attribute:: _halo_start_yr
      :type:  float


   .. py:attribute:: _d2yr
      :type:  float
      :value: 0.0027378507871321013



   .. py:method:: from_default(equinox_mjd = 60575.25, halo_start_day = 0.0)
      :classmethod:


      Create from bundled L2 halo orbit data.

      :param equinox_mjd: Reference equinox epoch in MJD.
      :param halo_start_day: Offset into halo orbit at mission start (days).

      :returns: Configured ObservatoryL2Halo instance.



   .. py:method:: from_npz(npz_path, equinox_mjd = 60575.25, halo_start_day = 0.0)
      :classmethod:


      Create from a custom .npz file.

      :param npz_path: Path to .npz file with halo orbit data.
      :param equinox_mjd: Reference equinox epoch in MJD.
      :param halo_start_day: Offset into halo orbit at mission start (days).

      :returns: Configured ObservatoryL2Halo instance.



   .. py:property:: period_yr
      :type: float


      Halo orbital period in years.


   .. py:property:: L2_dist_AU
      :type: float


      Sun-L2 distance in AU.


   .. py:method:: _halo_time(mjd)

      Convert MJD to periodic halo time in years.



   .. py:method:: position_ecliptic(mjd)

      Heliocentric ecliptic position of the telescope at time ``mjd``.

      :param mjd: Modified Julian Date (scalar).

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



   .. py:method:: sun_angle(mjd, ra_rad, dec_rad)

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

      :param mjd: Modified Julian Date.
      :param ra_rad: Target right ascension in radians.
      :param dec_rad: Target declination in radians.

      :returns: Angular separation in radians.



   .. py:method:: solar_elongation_deg(mjd, ra_rad, dec_rad)

      3D solar elongation in degrees.

      Identical to :meth:`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
      :meth:`helio_ecliptic_longitude_deg`.

      :param mjd: Modified Julian Date.
      :param ra_rad: Target right ascension in radians.
      :param dec_rad: Target declination in radians.

      :returns: Solar elongation in degrees, [0, 180].



   .. py:method:: helio_ecliptic_longitude_deg(mjd, ra_rad, dec_rad)

      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.

      :param mjd: Modified Julian Date.
      :param ra_rad: Target right ascension in radians.
      :param dec_rad: Target declination in radians.

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



   .. py:method:: ecliptic_latitude_deg(mjd, ra_rad, dec_rad)

      Target ecliptic latitude in degrees.

      Argument order matches :meth:`sun_angle`, :meth:`solar_elongation_deg`,
      and :meth:`helio_ecliptic_longitude_deg` so the four geometry
      helpers are interchangeable at call sites.

      :param mjd: Modified Julian Date (used for obliquity at this epoch).
      :param ra_rad: Target right ascension in radians.
      :param dec_rad: Target declination in radians.

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