.. _scenarioMomentumDumpingZeroNetForce:

scenarioMomentumDumpingZeroNetForce
===================================

Overview
--------

This script is similar to :ref:`scenarioMomentumDumping`, but ensures that the net force on the spacecraft is zero
during momentum dumping. This is done by using the module :ref:`forceTorqueThrForceMapping` instead of the module
:ref:`thrForceMapping`. As opposed to :ref:`thrForceMapping`, the module :ref:`forceTorqueThrForceMapping` also
considers a desired force on the spacecraft instead of only a desired torque. For momentum dumping, the desired force
is zero, so no force message needs to be connected.

The script shows how to perform momentum dumping when the momentum accumulated on the reaction wheels
is above a user-defined threshold. In this case, such threshold is set at 80 Nms. The dumping is performed
by a set of 8 thrusters that can provide control about the three principal axes of the spacecraft.
To perform the momentum dumping, three concatenated modules are used:

- :ref:`thrMomentumManagement`: computes the amount of momentum to be dumped, based on current stored momentum
  and the user-defined threshold. It is important to notice that, for the three concatenated modules to work
  correctly, this first module cannot be run at simulation time :math:`t = 0`. In this script, the method
  ``Reset`` is called on :ref:`thrMomentumManagement` at :math:`t = 10` s, which coincides to the time at which
  the first desaturating impulse is fired.
- :ref:`forceTorqueThrForceMapping`: maps the amount of momentum to be dumped into impulses that must be delivered by
  each thruster, while ensuring that no net force is exerted on the spacecraft. This module is originally implemented
  to map a requested torque (and force) into forces imparted by the thrusters, but it can be applied in this case as
  well to map a requested angular momentum (and impulse) into impulses imparted by the thrusters, because the math is
  the same.
- :ref:`thrMomentumDumping`: computes the thruster on-times required to deliver the desired impulse. A
  ``maxCounterValue`` of 100 is used in this example to allow the spacecraft to maneuver back to the desired attitude
  after each time the thrusters fire.

For this script to work as intended, it is necessary to run the flight software and the dynamics at two different
frequencies. In this example, the simulation time step for the flight software is 1 second, whereas for the dynamics
it is 0.1 seconds. This is necessary because the :ref:`thrMomentumDumping` automatically uses the task time step as
control period for the firing. However, if the dynamics is integrated at the same frequency, this does not give
enough time resolution to appreciate the variation in the momentum.

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

      python3 scenarioMomentumDumpingZeroNetForce.py

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

In this examples, the spacecraft is already at the desired attitude, but the four reaction wheels are saturated
(the total angular momentum exceeds the threshold). The desaturation happens at :math:`t = 10` when the
:ref:`thrMomentumManagement` is reset. Three firings are sufficient to dump the momentum below the set threshold.
The following figures illustrate the change in momentum for the four wheels :math:`H_i` for :math:`i = 1,...,4` and the
total angular momentum :math:`\|H\|`, and the attitude errors, as functions of time, with respect to the desired
target attitude.

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

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

The plots show that the momentum is dumped below the threshold. Also, the desired attitude is recovered after the
firings.

The next two plots show the amount of impulse [Ns] requested for each thruster, and the times during which each
thruster is operational. As expected, 100 control periods pass between each firing: because the control period
coincides with the flight software simulation time step of 1 s, this means that firings are 100 seconds apart.

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

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

The last plot shows the net force exerted on the spacecraft, which is zero for the entire duration of the simulation.

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