.. _BskSim_scenarios_scenario_LambertGuidance:

scenario_LambertGuidance
========================

Overview
--------

This BSK Sim scenario demonstrates how to use the Lambert solver module package, consisting of
``lambertPlanner()``, ``lambertSolver()`` and ``lambertValidator()``, as well as the modules that can be used for the
second maneuver of the Lambert transfer arc, ``lambertSurfaceRelativeVelocity()`` and ``lambertSecondDV()``. In this
scenario, the goal is to reach a target position and velocity at final time tf (equal to time of the second
maneuver tm2) by performing two maneuvers.

The first maneuver at time tm1 is done by solving Lambert's problem. The
Lambert problem is set up using :ref:`lambertPlanner`, which provides the information in the form of
:ref:`lambertProblemMsgPayload` to :ref:`lambertSolver`. Lambert's problem is solved within
:ref:`lambertSolver`, which writes the :ref:`lambertSolutionMsgPayload` and :ref:`lambertPerformanceMsgPayload` output
messages. Finally, :ref:`lambertValidator` processes the content of those messages, computes the required Delta-V, and
only writes a non-zero Delta-V message within :ref:`dvBurnCmdMsgPayload` if no constraints are violated
(minimum orbit radius and final distance from targeted location) and the Delta-V solution has converged.

The second maneuver at time tm2 is performed at the end of the Lambert transfer arc to match a desired velocity at that
point. In the case of this scenario, the desired velocity is obtained from the ``lambertSurfaceRelativeVelocity()``
module to such that the relative velocity to the central body surface is zero.

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

      python3 scenario_LambertGuidance.py

The simulation is a more complex simulation than the earlier tutorial for the Lambert solver modules in
:ref:`scenarioLambertSolver`.


Custom Dynamics Configurations Instructions
-------------------------------------------

The modules required for this scenario are identical to those used in :ref:`scenario_BasicOrbit`.


Custom FSW Configurations Instructions
--------------------------------------

The five Lambert modules were added to the :ref:`BSK_FSW` framework.

The first maneuver event is triggered when a user calls `self.masterSim.modeRequest = 'lambertFirstDV'` in any
current or future :ref:`Folder_BskSim` file, and the second maneuver using
`self.masterSim.modeRequest = 'lambertSecondDV'`

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

::

    showPlots = True

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

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

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

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