orbix
=====

.. py:module:: orbix

.. autoapi-nested-parse::

   orbix: differentiable Keplerian orbit propagation in JAX.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/orbix/equations/index
   /autoapi/orbix/kepler/index
   /autoapi/orbix/observatory/index
   /autoapi/orbix/orbit/index
   /autoapi/orbix/viz/index


Classes
-------

.. autoapisummary::

   orbix.AbstractOrbit
   orbix.KeplerianOrbit


Package Contents
----------------

.. py:class:: AbstractOrbit

   Bases: :py:obj:`equinox.Module`


   Abstract orbital-motion model.

   Subclasses own whatever parameters describe "this kind of
   orbital motion" (Keplerian, TTV, interpolated ephemeris).
   Stellar context is threaded in at call time.


   .. py:method:: propagate(trig_solver=None, t_jd = None, *, Ms_kg)
      :abstractmethod:


      Propagate to times ``t_jd``.

      :param trig_solver: Scalar solver for Kepler's equation,
                          signature ``(M, e) -> (sinE, cosE)``. None selects the
                          cached default grid solver.
      :param t_jd: Times in Julian Days, shape ``(T,)``. Required; it is
                   keyword-friendly (``propagate(t_jd=..., Ms_kg=...)``) so
                   callers relying on the default solver need not pass a
                   positional None.
      :param Ms_kg: Stellar mass in kg, shape ``(K,)`` or scalar.

      :returns: Position vectors, shape ``(K, 3, T)``.
                phase_angle_rad: Phase angle beta, shape ``(K, T)``, measured
                    from the observer (+z) axis to the position vector. The
                    standard planetary star-planet-observer phase angle is
                    ``pi`` minus this; convert before any Lambert phase
                    function.
                dist_AU: Star-planet distance, shape ``(K, T)``.
      :rtype: r_AU



.. py:class:: KeplerianOrbit

   Bases: :py:obj:`AbstractOrbit`


   Seven-element Keplerian orbit.

   Owns the orbital elements only; everything derived (AB matrices,
   mean motion, period) is recomputed per call so that ``eqx.tree_at``
   updates and gradients through any element are always consistent.
   All parameter arrays share a leading axis ``(K,)``.


   .. py:attribute:: a_AU
      :type:  jaxtyping.Array


   .. py:attribute:: e
      :type:  jaxtyping.Array


   .. py:attribute:: W_rad
      :type:  jaxtyping.Array


   .. py:attribute:: i_rad
      :type:  jaxtyping.Array


   .. py:attribute:: w_rad
      :type:  jaxtyping.Array


   .. py:attribute:: M0_rad
      :type:  jaxtyping.Array


   .. py:attribute:: t0_d
      :type:  jaxtyping.Array


   .. py:method:: __check_init__()

      Validate that all seven elements share one leading (K,) shape.



   .. py:method:: from_period(T_d, e, cos_i, W_rad, cos_w, sin_w, tp_d, *, Ms_kg)
      :classmethod:


      Construct from the period parameterization used by orbit-fitting code.

      Fitting code samples ``(T, e, cos i, W, cos w, sin w, tp)`` rather
      than the seven fields this class stores, so posterior draws reach
      the class through this constructor: period converts to semi-major
      axis via Kepler's third law (which is why ``Ms_kg`` is required
      here, unlike ``__init__``), and periapsis passage maps exactly to
      ``(M0_rad=0, t0_d=tp_d)``.

      :param T_d: Orbital period in days.
      :param e: Eccentricity.
      :param cos_i: Cosine of the inclination (the fitting basis; the
                    gradient of ``arccos`` diverges at ``|cos_i| = 1``, so
                    keep exactly face-on/edge-on samples out of gradients).
      :param W_rad: Longitude of the ascending node in radians.
      :param cos_w: Cosine of the argument of periapsis.
      :param sin_w: Sine of the argument of periapsis.
      :param tp_d: Time of periapsis passage in days (JD in practice).
      :param Ms_kg: Stellar mass in kg.

      :returns: A ``KeplerianOrbit`` whose leading axis is the common
                broadcast shape of the seven inputs, so a batch of posterior
                draws becomes a ``(K,)``-batched orbit in one call.



   .. py:method:: _AB()

      Compute the AB propagation matrices from the current elements.



   .. py:method:: propagate(trig_solver=None, t_jd = None, *, Ms_kg)

      Propagate Keplerian orbit to times ``t_jd``.

      :returns: (K, 3, T) position vectors.
                phase_angle_rad: (K, T) phase angle beta = arctan2(rho, r_z),
                    rho = sqrt(r_x**2 + r_y**2); gradient-safe at conjunction.
                    Measured from the observer (+z) axis, so the standard
                    star-planet-observer phase angle (beta = 0 at full phase)
                    is pi minus this; convert before any Lambert phase
                    function.
                dist_AU: (K, T) star-planet distance.
      :rtype: r_AU



   .. py:method:: position_arcsec(trig_solver=None, t_jd = None, *, Ms_kg, dist_pc)

      On-sky (RA, Dec) in arcsec, each shape ``(K, T)``.

      Thin wrapper around ``propagate`` for callers that only
      need projected position.



   .. py:method:: separation_arcsec(trig_solver=None, t_jd = None, *, Ms_kg, dist_pc)

      Projected angular separation in arcsec, shape ``(K, T)``.



   .. py:method:: __repr__()

      Compact summary of the seven Keplerian elements.

      Angles are converted from radians to degrees for readability.
      Arrays are summarized inline; if the leading axis K > 3, only
      the first few entries are shown.