.. _scenarioLagrangePointOrbit:

scenarioLagrangePointOrbit
==========================

Overview
--------

This script sets up a 3-DOF spacecraft which is operating at one of five Earth-Moon Lagrange points. The purpose
is to illustrate how to use multiple gravity bodies to create interesting 3-body orbit behavior.

The script is found in the folder ``xmera/examples`` and executed by using::

    python3 scenarioLagrangePointOrbit.py

For this simulation, the Earth is assumed stationary, and the Moon's trajectory is generated using SPICE. Refer to
:ref:`scenarioOrbitMultiBody` to learn how to create multiple gravity bodies and read a SPICE trajectory.

The initial position of the spacecraft is specified using a Lagrange point index. The positioning of the Lagrange
points is illustrated `here <https://www.spaceacademy.net.au/library/notes/lagrangp.htm>`__.

For Lagrange points 1-3, the initial Earth-spacecraft distance is specified to lowest order
in :math:`\alpha = \mu_{M} / \mu_{E}`, where the subscript M is for the Moon and E is for the Earth.
These are unstable equilibrium points.

.. math::
    r_{L1} = a_{M} \left[ 1-\left(\frac{\alpha}{3}\right)^{1/3} \right]

.. math::
    r_{L2} = a_{M} \left[ 1+\left(\frac{\alpha}{3}\right)^{1/3} \right]

.. math::
    r_{L3} = a_{M} \left[ 1-\frac{7 \alpha}{12} \right]

For Lagrange points 4 and 5, the spacecraft is positioned at :math:`r_{L4} = r_{L5} = a_{M}` at +/- 60
degrees from the Earth-Moon vector. These are stable equilibrium points.

When the simulation completes, two plots are shown. The first plot shows the orbits of the Moon and spacecraft in
the Earth-centered inertial frame. The second plot shows the motion of the Moon and spacecraft in a frame rotating
with the Moon.

Illustration of Simulation Results
----------------------------------

The following images illustrate the simulation run results with the following settings:

::

    nOrbits=1, timestep=300, showPlots=True

When starting at L1, L2, or L3, the spacecraft moves away from the unstable equilibrium point.

::

    lagrangePoint=1

.. image:: /_images/Scenarios/scenarioLagrangePointOrbitL1Fig1.svg
    :align: center

.. image:: /_images/Scenarios/scenarioLagrangePointOrbitL1Fig2.svg
    :align: center

::

    lagrangePoint=2

.. image:: /_images/Scenarios/scenarioLagrangePointOrbitL2Fig1.svg
    :align: center

.. image:: /_images/Scenarios/scenarioLagrangePointOrbitL2Fig2.svg
    :align: center

::

    lagrangePoint=3

.. image:: /_images/Scenarios/scenarioLagrangePointOrbitL3Fig1.svg
    :align: center

.. image:: /_images/Scenarios/scenarioLagrangePointOrbitL3Fig2.svg
    :align: center

When starting at L4 or L5, the spacecraft remains near the stable equilibrium point.

::

    lagrangePoint=4

.. image:: /_images/Scenarios/scenarioLagrangePointOrbitL4Fig1.svg
    :align: center

.. image:: /_images/Scenarios/scenarioLagrangePointOrbitL4Fig2.svg
    :align: center


::

    lagrangePoint=5

.. image:: /_images/Scenarios/scenarioLagrangePointOrbitL5Fig1.svg
    :align: center

.. image:: /_images/Scenarios/scenarioLagrangePointOrbitL5Fig2.svg
    :align: center