boinor.core.iod
===============

.. py:module:: boinor.core.iod


Functions
---------

.. autoapisummary::

   boinor.core.iod.vallado
   boinor.core.iod.izzo


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

.. py:function:: vallado(k, r0, r, tof, M, prograde, lowpath, numiter, rtol)

   Solves the Lambert's problem.

   The algorithm returns the initial velocity vector and the final one, these are
   computed by the following expresions:

   .. math::

       \vec{v_{o}} &= \frac{1}{g}(\vec{r} - f\vec{r_{0}}) \\
       \vec{v} &= \frac{1}{g}(\dot{g}\vec{r} - \vec{r_{0}})

   Therefore, the lagrange coefficients need to be computed. For the case of
   Lamber's problem, they can be expressed by terms of the initial and final vector:

   .. math::

       \begin{aligned}
           f = 1 -\frac{y}{r_{o}} \\
           g = A\sqrt{\frac{y}{\mu}} \\
           \dot{g} = 1 - \frac{y}{r} \\
       \end{aligned}

   Where y(z) is a function that depends on the :py:mod:`boinor.core.stumpff` coefficients:

   .. math::

       y = r_{o} + r + A\frac{zS(z)-1}{\sqrt{C(z)}} \\
       A = \sin{(\Delta \nu)}\sqrt{\frac{rr_{o}}{1 - \cos{(\Delta \nu)}}}

   The value of z to evaluate the stump functions is solved by applying a Numerical method to
   the following equation:

   .. math::

       z_{i+1} = z_{i} - \frac{F(z_{i})}{F{}'(z_{i})}

   Function F(z)  to the expression:

   .. math::

       F(z) = \left [\frac{y(z)}{C(z)}  \right ]^{\frac{3}{2}}S(z) + A\sqrt{y(z)} - \sqrt{\mu}\Delta t

   :param k: Gravitational Parameter
   :type k: float
   :param r0: Initial position vector
   :type r0: numpy.ndarray
   :param r: Final position vector
   :type r: numpy.ndarray
   :param tof: Time of flight
   :type tof: float
   :param M: Number of revolutions
   :type M: int
   :param prograde: Controls the desired inclination of the transfer orbit.
   :type prograde: boolean
   :param lowpath: If `True` or `False`, gets the transfer orbit whose vacant focus is
                   below or above the chord line, respectively.
   :type lowpath: boolean
   :param numiter: Number of iterations to
   :type numiter: int
   :param rtol: Number of revolutions
   :type rtol: int

   :returns: * **v0** (*numpy.ndarray*) -- Initial velocity vector
             * **v** (*numpy.ndarray*) -- Final velocity vector

   .. rubric:: Examples

   >>> from boinor.core.iod import vallado
   >>> from astropy import units as u
   >>> import numpy as np
   >>> from boinor.bodies import Earth
   >>> k = Earth.k.to(u.km ** 3 / u.s ** 2)
   >>> r1 = np.array([5000, 10000, 2100]) * u.km # Initial position vector
   >>> r2 = np.array([-14600, 2500, 7000]) * u.km # Final position vector
   >>> tof = 3600 * u.s # Time of flight
   >>> v1, v2 = vallado(k.value, r1.value, r2.value, tof.value, M=0, prograde=True, lowpath=True, numiter=35, rtol=1e-8)
   >>> v1 = v1 * u.km / u.s
   >>> v2 = v2 * u.km / u.s
   >>> print(v1, v2)
   [-5.99249503  1.92536671  3.24563805] km / s [-3.31245851 -4.19661901 -0.38528906] km / s

   .. rubric:: Notes

   This procedure can be found in section 5.3 of :cite:t:`Curtis2013`, with all the
   theoretical description of the problem. Analytical example can be found
   in the same book under name Example 5.2.


.. py:function:: izzo(k, r1, r2, tof, M, prograde, lowpath, numiter, rtol)

   Aplies izzo algorithm to solve Lambert's problem.

   :param k: Gravitational Constant
   :type k: float
   :param r1: Initial position vector
   :type r1: numpy.ndarray
   :param r2: Final position vector
   :type r2: numpy.ndarray
   :param tof: Time of flight between both positions
   :type tof: float
   :param M: Number of revolutions
   :type M: int
   :param prograde: Controls the desired inclination of the transfer orbit.
   :type prograde: boolean
   :param lowpath: If `True` or `False`, gets the transfer orbit whose vacant focus is
                   below or above the chord line, respectively.
   :type lowpath: boolean
   :param numiter: Number of iterations
   :type numiter: int
   :param rtol: Error tolerance
   :type rtol: float

   :returns: * **v1** (*numpy.ndarray*) -- Initial velocity vector
             * **v2** (*numpy.ndarray*) -- Final velocity vector