boinor.core.perturbations
=========================

.. py:module:: boinor.core.perturbations


Functions
---------

.. autoapisummary::

   boinor.core.perturbations.J2_perturbation
   boinor.core.perturbations.J3_perturbation
   boinor.core.perturbations.atmospheric_drag_exponential
   boinor.core.perturbations.atmospheric_drag
   boinor.core.perturbations.third_body
   boinor.core.perturbations.radiation_pressure


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

.. py:function:: J2_perturbation(t0, state, k, J2, R)

   Calculates J2_perturbation acceleration (km/s2).

   .. math::

       \vec{p} = \frac{3}{2}\frac{J_{2}\mu R^{2}}{r^{4}}\left [\frac{x}{r}\left ( 5\frac{z^{2}}{r^{2}}-1 \right )\vec{i} + \frac{y}{r}\left ( 5\frac{z^{2}}{r^{2}}-1 \right )\vec{j} + \frac{z}{r}\left ( 5\frac{z^{2}}{r^{2}}-3 \right )\vec{k}\right]

   .. versionadded:: 0.9.0

   :param t0: Current time (s)
   :type t0: float
   :param state: Six component state vector [x, y, z, vx, vy, vz] (km, km/s).
   :type state: numpy.ndarray
   :param k: Standard Gravitational parameter. (km^3/s^2)
   :type k: float
   :param J2: Oblateness factor
   :type J2: float
   :param R: Attractor radius
   :type R: float

   .. rubric:: Notes

   The J2 accounts for the oblateness of the attractor. The formula is given in
   Howard Curtis, (12.30)


.. py:function:: J3_perturbation(t0, state, k, J3, R)

   Calculates J3_perturbation acceleration (km/s2).

   :param t0: Current time (s)
   :type t0: float
   :param state: Six component state vector [x, y, z, vx, vy, vz] (km, km/s).
   :type state: numpy.ndarray
   :param k: Standard Gravitational parameter. (km^3/s^2)
   :type k: float
   :param J3: Oblateness factor
   :type J3: float
   :param R: Attractor radius
   :type R: float

   .. rubric:: Notes

   The J3 accounts for the oblateness of the attractor. The formula is given in
   Howard Curtis, problem 12.8
   This perturbation has not been fully validated, see https://github.com/boinor/boinor/pull/398


.. py:function:: atmospheric_drag_exponential(t0, state, k, R, C_D, A_over_m, H0, rho0)

   Calculates atmospheric drag acceleration (km/s2).

   .. math::

       \vec{p} = -\frac{1}{2}\rho v_{rel}\left ( \frac{C_{d}A}{m} \right )\vec{v_{rel}}

   .. versionadded:: 0.9.0

   :param t0: Current time (s)
   :type t0: float
   :param state: Six component state vector [x, y, z, vx, vy, vz] (km, km/s).
   :type state: numpy.ndarray
   :param k: Standard Gravitational parameter (km^3/s^2).
   :type k: float
   :param R: Radius of the attractor (km)
   :type R: float
   :param C_D: Dimensionless drag coefficient ()
   :type C_D: float
   :param A_over_m: Frontal area/mass of the spacecraft (km^2/kg)
   :type A_over_m: float
   :param H0: Atmospheric scale height, (km)
   :type H0: float
   :param rho0: Exponent density pre-factor, (kg / km^3)
   :type rho0: float

   .. rubric:: Notes

   This function provides the acceleration due to atmospheric drag
   using an overly-simplistic exponential atmosphere model. We follow
   Howard Curtis, section 12.4
   the atmospheric density model is rho(H) = rho0 x exp(-H / H0)


.. py:function:: atmospheric_drag(t0, state, k, C_D, A_over_m, rho)

   Calculates atmospheric drag acceleration (km/s2).

   .. math::

       \vec{p} = -\frac{1}{2}\rho v_{rel}\left ( \frac{C_{d}A}{m} \right )\vec{v_{rel}}

   .. versionadded:: 1.14

   :param t0: Current time (s).
   :type t0: float
   :param state: Six component state vector [x, y, z, vx, vy, vz] (km, km/s).
   :type state: numpy.ndarray
   :param k: Standard Gravitational parameter (km^3/s^2)
   :type k: float
   :param C_D: Dimensionless drag coefficient ()
   :type C_D: float
   :param A_over_m: Frontal area/mass of the spacecraft (km^2/kg)
   :type A_over_m: float
   :param rho: Air density at corresponding state (kg/km^3)
   :type rho: float

   .. rubric:: Notes

   This function provides the acceleration due to atmospheric drag, as
   computed by a model from boinor.earth.atmosphere


.. py:function:: third_body(t0, state, k, k_third, perturbation_body)

   Calculate third body acceleration (km/s2).

   .. math::

       \vec{p} = \mu_{m}\left ( \frac{\vec{r_{m/s}}}{r_{m/s}^3} - \frac{\vec{r_{m}}}{r_{m}^3} \right )

   :param t0: Current time (s).
   :type t0: float
   :param state: Six component state vector [x, y, z, vx, vy, vz] (km, km/s).
   :type state: numpy.ndarray
   :param k: Standard Gravitational parameter of the attractor (km^3/s^2).
   :type k: float
   :param k_third: Standard Gravitational parameter of the third body (km^3/s^2).
   :type k_third: float
   :param perturbation_body: A callable object returning the position of the body that causes the perturbation
                             in the attractor frame.
   :type perturbation_body: callable

   .. rubric:: Notes

   This formula is taken from Howard Curtis, section 12.10. As an example, a third body could be
   the gravity from the Moon acting on a small satellite.


.. py:function:: radiation_pressure(t0, state, k, R, C_R, A_over_m, Wdivc_s, star)

   Calculates radiation pressure acceleration (km/s2).

   .. math::

       \vec{p} = -\nu \frac{S}{c} \left ( \frac{C_{r}A}{m} \right )\frac{\vec{r}}{r}

   :param t0: Current time (s).
   :type t0: float
   :param state: Six component state vector [x, y, z, vx, vy, vz] (km, km/s).
   :type state: numpy.ndarray
   :param k: Standard Gravitational parameter (km^3/s^2).
   :type k: float
   :param R: Radius of the attractor.
   :type R: float
   :param C_R: Dimensionless radiation pressure coefficient, 1 < C_R < 2 ().
   :type C_R: float
   :param A_over_m: Effective spacecraft area/mass of the spacecraft (km^2/kg).
   :type A_over_m: float
   :param Wdivc_s: Total star emitted power divided by the speed of light (kg km/s^2).
   :type Wdivc_s: float
   :param star: A callable object returning the position of radiating star
                in the attractor frame.
   :type star: callable

   .. rubric:: Notes

   This function provides the acceleration due to star light pressure. We follow
   Howard Curtis, section 12.9