.. _scenarioAlbedo:

scenarioAlbedo
==============

Overview
--------

Demonstrates how to add albedo module to coarse sun sensor. The script is found in the folder ``xmera/examples`` and
executed by using::

      python3 scenarioAlbedo.py

This script sets up a spacecraft with scenario options (1) and (2) shown in the following illustration.
In scenario (1), only earth is considered as a celestial body, and the spacecraft is orbiting around earth.
In scenario (2), there are two bodies (earth, moon) and spacecraft close to Earth increases its altitude up to moon
without considering the gravity effector. In both scenarios, rotational  motion is simulated too.

.. image:: /_images/static/test_scenarioAlbedo.svg
   :align: center

Simulation Scenario Setup Details
---------------------------------
A simulation process is created which contains both the spacecraft simulation module,
as well as one albedo module from :ref:`albedo` module using CSS configuration.
The dynamics simulation is setup using :ref:`Spacecraft`.
The CSS module is created using :ref:`coarseSunSensor`.
The input message ``sunPositionInMsg`` specifies an input message that contains the sun's position.

Albedo module calculates the albedo value for any instrument location. The instrument configuration can be set
through the variables::

   fov
   nHat_B
   r_IB_B

which specify half field of view angle of the instrument, unit normal vector, and misalignment vector in meters.
The instrument configuration is added to the albedo module through::

    albModule.addInstrumentConfig(instInMsgName, configMsg)
    albModule.addInstrumentConfig(instInMsgName, fov, nHat_B, r_IB_B)

Both method can be used for the same purpose. Note that this commands can be repeated if the albedo should be computed
for different instruments.

Every time an instrument is added to the albedo module, an automated output message is created.
For ``albModule`` is "AlbedoModule_0_data" as the modelTag string is ``AlbedoModule`` and the instrument number is 0.
This output is added to the ``albOutMsgs`` module vector within the  ``addInstrumentConfig()`` function.

Multiple planets can be added to the albedo module through::

    albModule.addPlanetandAlbedoAverageModel(SpicePlanetStateMsg)
    albModule.addPlanetandAlbedoAverageModel(SpicePlanetStateMsg, ALB_avg, numLat, numLon)
    albModule.addPlanetandAlbedoDataModel(SpicePlanetStateMsg, dataPath, fileName)

based on the albedo model to be used for the planet. Note that this commands should be repeated for adding multiple
planets. However, the albedo module gives a summed albedo value at the instrument not a vector of values corresponding
to each planet. The albedo module is created using one of the albedo models, e.g.
``ALBEDO_DATA``
which is based on the albedo coefficient data using the specified fileName and dataPath, and
``ALBEDO_AVG``
which is a model based on an average albedo value that can be specified with ``ALB_avg`` variable,
and used for any planet. If ``ALB_avg`` is not specified albedo module uses the default value defined for each planet.

An optional input is the solar eclipse case ``eclipseCase``.
If it is specified as True, then the shadow factor is calculated by the albedo module automatically.

When the simulation completes, one to three plots are shown depending on the case. First one always show the
albedo value at the instrument (instrument's signal) with or without the instrument's total signal. In case of
using albedo data file, the albedo coefficient data map of the planet is shown. And, for the multiple planets case,
the radius of the spacecraft is shown.

albedoData, multipleInstrument, multiplePlanet, useEclipse

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

::

    show_plots = True, albedoData = True, multipleInstrument = False, multiplePlanet = False, useEclipse = False

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

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

::

    show_plots = True, albedoData = False, multipleInstrument = True, multiplePlanet = False, useEclipse = False

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

::

    show_plots = True, albedoData = False, multipleInstrument = True, multiplePlanet = False, useEclipse = True

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

::

    show_plots = True, albedoData = False, multipleInstrument = True, multiplePlanet = True, useEclipse = False

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

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