.. _scenarioMagneticFieldCenteredDipole:

scenarioMagneticFieldCenteredDipole
===================================

Overview
--------

This script sets up a 3-DOF spacecraft which is orbiting a planet that
has a magnetic field.  The purpose
is to illustrate how to create and setup the centered dipole
magnetic field, as well as determine the
magnetic field at a spacecraft location.  The orbit setup is similar to that used in
:ref:`scenarioBasicOrbit`.

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

    python3 scenarioMagneticFieldCenteredDipole.py

Simulation Scenario Setup Details
---------------------------------

The simulation layout is shown in the following illustration.
A single simulation process is created
which contains the spacecraft object.  The spacecraft state message
is connected to the magnetic field
module which outputs the local magnetic field in inertial frame components.

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

When the simulation completes 2 plots are shown for each case.  One plot always shows
the inertial position vector components, while the second plot shows the local magnetic field
vector components with respect to the inertial frame.

Note that the magnetic field module are zeroed, and appropriate
parameters must be specified for the planet.  The
following code illustrates setting the Earth dipole parameters::

    magModule.g10 = -30926.00 / 1e9 * 0.5  # Tesla
    magModule.g11 =  -2318.00 / 1e9 * 0.5  # Tesla
    magModule.h11 =   5817.00 / 1e9 * 0.5  # Tesla
    magModule.planetRadius = 6371.2 * 1000  # meters

The python support file ``simSetPlanetEnvironment.py`` provides helper
functions to use magnetic field
environments including the centered dipole models for Mercury,
Earth, Jupiter, Saturn, Uranus and Neptune.

The default
planet's position vector is assumed to be the inertial frame origin
and an identity orientation matrix.
If a different planet state message is required this can be specified
through the optional input message ``planetPosInMsgName``.

The magnetic field module can produce the magnetic field for a vector of
spacecraft locations, not just for a
single spacecraft.  Let ``scObject`` be an instance of :ref:`Spacecraft`,
then the spacecraft state output message
is added to the magnetic field module through::

    magModule.addSpacecraftToModel(scObject.scStateOutMsg)

Note that this command can be repeated if the magnetic field should be
evaluated for different spacecraft.

Every time a spacecraft is added to the magnetic field module,
an automated output message name is created.
For `magModule` is "CenteredDipole_0_data" as the modelTag string is
``CenteredDipole`` and the spacecraft number is 0.
This output name is created in the  ``addSpacecraftToModel()`` function.
However, if the default output name is used for the second planetary
magnetic field model, then both module share
the same output name and one will overwrite the others output.
To ensure the second magnetic field has a unique
output name, the default name is replaced with a unique message.

The reach of the magnetic field model is specified through the module
variables ``envMinReach`` and ``envMaxReach``.
Their default values are -1 which turns off this feature, giving the
magnetic field evaluation infinite reach.
As the elliptical Earth scenario uses 2 Earth-fixed magnetic fields,
we want ``magModule2`` to only evaluate a
magnetic field if the orbit radius is less than ``req*1.3``.  Similarly,
for radii above ``req*1.3`` we want the first
magnetic field model to be used.

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

The following images illustrate the expected simulation run returns for a range of script configurations.

::

    show_plots = True, orbitCase='circular', planetCase='Earth'

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

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

::

   show_plots = True, orbitCase='elliptical', planetCase='Earth'

This case illustrates an elliptical Earth orbit inclination where 2 dipole magnetic
fields are attached. One model acts above 1.3 Earth radius, and the other below that region.

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

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

::

    show_plots = True, orbitCase='elliptical', planetCase='Jupiter'

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

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