orbix.observatory.solar_system
==============================

.. py:module:: orbix.observatory.solar_system

.. autoapi-nested-parse::

   Solar system body positions using Vallado (2013) static ephemerides.

   All positions are heliocentric ecliptic, in AU.  Time inputs are MJD.

   This module is a pure-JAX port of the ``keplerplanet`` method in
   ``EXOSIMS.Prototypes.Observatory``, using orbix's own Kepler solver.

   Reference:
       Vallado, D. A. (2013). Fundamentals of Astrodynamics and Applications.
       Appendix D.4 -- Planetary ephemerides.



Attributes
----------

.. autoapisummary::

   orbix.observatory.solar_system._J2000_JD
   orbix.observatory.solar_system._J2000_MJD
   orbix.observatory.solar_system._JULIAN_CENTURY
   orbix.observatory.solar_system._NCOEFF
   orbix.observatory.solar_system._EPHEM_RAW
   orbix.observatory.solar_system._EPHEM


Functions
---------

.. autoapisummary::

   orbix.observatory.solar_system._mjd_to_julian_centuries
   orbix.observatory.solar_system.obliquity_deg
   orbix.observatory.solar_system._rot1
   orbix.observatory.solar_system._rot3
   orbix.observatory.solar_system.equat2eclip
   orbix.observatory.solar_system.eclip2equat
   orbix.observatory.solar_system._pad
   orbix.observatory.solar_system._pack_planet
   orbix.observatory.solar_system._eval_elements
   orbix.observatory.solar_system.planet_position_ecliptic
   orbix.observatory.solar_system.planet_position_equatorial
   orbix.observatory.solar_system.earth_position_ecliptic
   orbix.observatory.solar_system.earth_position_equatorial
   orbix.observatory.solar_system.radec_to_ecliptic
   orbix.observatory.solar_system.sun_target_angle
   orbix.observatory.solar_system.solar_elongation_ecliptic


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

.. py:data:: _J2000_JD
   :value: 2451545.0


.. py:data:: _J2000_MJD
   :value: 51544.5


.. py:data:: _JULIAN_CENTURY
   :value: 36525.0


.. py:function:: _mjd_to_julian_centuries(mjd)

   Convert MJD to Julian centuries since J2000.


.. py:function:: obliquity_deg(mjd)

   Obliquity of the ecliptic in degrees (Vallado polynomial).

   :param mjd: Modified Julian Date.

   :returns: Obliquity in degrees.


.. py:function:: _rot1(theta)

   Rotation matrix about axis 1 (x).


.. py:function:: _rot3(theta)

   Rotation matrix about axis 3 (z).


.. py:function:: equat2eclip(r_equat, mjd)

   Rotate heliocentric equatorial -> ecliptic.

   :param r_equat: Position vector(s) in equatorial frame, shape ``(3,)`` or ``(n, 3)``.
   :param mjd: MJD (scalar) for obliquity calculation.

   :returns: Position vector(s) in ecliptic frame, same shape as input.


.. py:function:: eclip2equat(r_eclip, mjd)

   Rotate heliocentric ecliptic -> equatorial.

   :param r_eclip: Position vector(s) in ecliptic frame, shape ``(3,)`` or ``(n, 3)``.
   :param mjd: MJD (scalar) for obliquity calculation.

   :returns: Position vector(s) in equatorial frame, same shape as input.


.. py:data:: _NCOEFF
   :value: 4


.. py:data:: _EPHEM_RAW

.. py:function:: _pad(coeffs, n = _NCOEFF)

   Pad coefficient list to length n with zeros.


.. py:function:: _pack_planet(raw)

   Pack planet ephemeris dict into a (6, NCOEFF) array.

   Row order: a, e, I, O, w, lM.


.. py:data:: _EPHEM
   :type:  dict[str, jax.numpy.ndarray]

.. py:function:: _eval_elements(coeffs, TDB)

   Evaluate all 6 orbital element polynomials at once.

   :param coeffs: Shape ``(6, NCOEFF)`` -- rows are [a, e, I, O, w, lM].
   :param TDB: Julian centuries since J2000.

   :returns: Shape ``(6,)`` -- [a, e, I_deg, O_deg, w_deg, lM_deg].


.. py:function:: planet_position_ecliptic(body, mjd)

   Heliocentric ecliptic position of a solar system body.

   Uses Vallado (2013) Algorithms 2 and 10 -- Keplerian elements propagated
   with polynomial time corrections.  All 6 orbital elements are evaluated
   in a single vectorized ``matmul``.

   :param body: Planet name (e.g. ``"Earth"``, ``"Jupiter"``).
   :param mjd: Modified Julian Date (scalar).

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


.. py:function:: planet_position_equatorial(body, mjd)

   Heliocentric equatorial position of a solar system body.

   :param body: Planet name (e.g. ``"Earth"``).
   :param mjd: Modified Julian Date (scalar).

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


.. py:function:: earth_position_ecliptic(mjd)

   Heliocentric ecliptic position of Earth (AU).


.. py:function:: earth_position_equatorial(mjd)

   Heliocentric equatorial position of Earth (AU).


.. py:function:: radec_to_ecliptic(ra_rad, dec_rad, mjd)

   Convert equatorial RA/Dec to ecliptic longitude/latitude.

   :param ra_rad: Right ascension in radians.
   :param dec_rad: Declination in radians.
   :param mjd: MJD for obliquity calculation.

   :returns: (ecliptic_lon_rad, ecliptic_lat_rad) tuple.


.. py:function:: sun_target_angle(obs_position_eclip, ra_rad, dec_rad, mjd)

   Angular separation between the Sun and a target as seen from the observatory.

   :param obs_position_eclip: Observatory position in heliocentric ecliptic (AU),
                              shape ``(3,)``.
   :param ra_rad: Target right ascension in radians.
   :param dec_rad: Target declination in radians.
   :param mjd: MJD for coordinate conversion.

   :returns: Angular separation in radians.


.. py:function:: solar_elongation_ecliptic(obs_position_eclip, ecliptic_lon_rad, ecliptic_lat_rad)

   Solar elongation (angle between Sun and target as seen from observer).

   :param obs_position_eclip: Observatory heliocentric ecliptic position (AU).
   :param ecliptic_lon_rad: Target ecliptic longitude (rad).
   :param ecliptic_lat_rad: Target ecliptic latitude (rad).

   :returns: Solar elongation in radians.