orbix.kepler
============

.. py:module:: orbix.kepler

.. autoapi-nested-parse::

   Kepler equation solvers: exact core + grid/fixed-e shortcuts.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/orbix/kepler/core/index
   /autoapi/orbix/kepler/shortcuts/index


Functions
---------

.. autoapisummary::

   orbix.kepler.E_solve
   orbix.kepler.diff_solve_trig
   orbix.kepler.solve_trig
   orbix.kepler.get_grid_solver


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

.. py:function:: E_solve(M, e)

   Vectorized orvara solver for eccentric anomaly.

   :param M: Mean anomaly. Shape: (n,).
   :type M: jnp.ndarray
   :param e: Eccentricity.
   :type e: float

   :returns: Eccentric anomaly. Shape: (n,).
   :rtype: E (jnp.ndarray)

   The solver contract is 0 <= e < 1; e >= 1 or e < 0 silently produces
   NaN or garbage (unchecked to keep the hot path branch-free).


.. py:function:: diff_solve_trig(M, e)

   Solve Kepler's equation, returning (sinE, cosE) with exact gradients.

   Drop-in replacement for :func:`solve_trig` that supports reverse-mode
   autodiff (``jax.grad``, ``jax.vjp``). Gradients come from the Implicit
   Function Theorem on ``M = E - e*sin(E)``, computed from ``(sinE, cosE, e)``
   alone (no extra trig calls, no iterative re-solves).

   :param M: Mean anomaly. Shape: (n,).
   :type M: jnp.ndarray
   :param e: Eccentricity.
   :type e: float

   :returns: Sine of the eccentric anomaly. Shape: (n,).
             cosE (jnp.ndarray): Cosine of the eccentric anomaly. Shape: (n,).
   :rtype: sinE (jnp.ndarray)

   The solver contract is 0 <= e < 1; e >= 1 or e < 0 silently produces
   NaN or garbage (unchecked to keep the hot path branch-free).


.. py:function:: solve_trig(M, e)

   Wrapper around E_solve_trig that returns only (sinE, cosE).

   :param M: Mean anomaly. Shape: (n,).
   :type M: jnp.ndarray
   :param e: Eccentricity.
   :type e: float

   :returns: Sine of the eccentric anomaly. Shape: (n,).
             cosE (jnp.ndarray): Cosine of the eccentric anomaly. Shape: (n,).
   :rtype: sinE (jnp.ndarray)

   The solver contract is 0 <= e < 1; e >= 1 or e < 0 silently produces
   NaN or garbage (unchecked to keep the hot path branch-free).


.. py:function:: get_grid_solver(level='scalar', jit=False, kind='bilinear', E=True, trig=True, n_e=512, n_M=2048)

   Helper function to get a grid-based solver and cache it.

   :param level:
                 How the solver should be batching things.
                     - "scalar" means the inputs will be a single (M, e) pair and
                       the output will be a single E, sinE, cosE value.
                     - "planet" will vectorize over times first and then over
                       orbits.
                         - M: (n_orbits, n_times)
                         - e: (n_orbits,)
   :param jit: Whether to jit the solver.
   :param kind: The kind of solver to use, either "linear" or "bilinear".
   :param E: Whether to compute the eccentric anomaly.
   :param trig: Whether to compute the sine and cosine of the eccentric anomaly.
   :param n_e: The number of eccentricity steps in the grid.
   :param n_M: The number of mean anomaly steps in the grid.