.. _scenarioFlybySpice:

scenarioFlybySpice
==================

Overview
--------

The purpose of this simulation is to illustrate how to set a spacecraft's translational motion using a custom
Spice file for planetary flybys. This allows the user to easily visualize a mission trajectory using Vizard.
Attitude pointing modes are also implemented in this script to enhance the mission simulation and illustrate
other capabilities in Xmera.

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

      python3 scenarioFlybySpice.py

Configuring Translational Motion Using Custom Spice Files
---------------------------------------------------------

This simulation script allows the user to specify a flyby of either Venus, Mars, or Earth. Note that the custom Spice
file for this scenario incorporates translational information for all three planetary flybys. Therefore, the user must
first specify the correct flyby date and time to initialize the simulation with the correct Spice information. This is
done using the ``timeIntString`` variable::

    if planetCase == "venus":
        timeInitString = "2028 August 13 0:30:30.0"
    elif planetCase == "earth":
        timeInitString = "2029 June 20 5:30:30.0"
    elif planetCase == "mars":
        timeInitString = "2031 October 3 20:00:00.0"
    else:
        print("flyby target not implemented.")
        exit(1)

Next the custom Spice file must be loaded. The ``loadSpiceKernel()`` method of class ``SpiceInterface``
is called to load the file. This method accepts the file name and the path to the desired file to load::

    spiceObject.loadSpiceKernel("max_21T01.bsp", os.path.join(path, "dataForExamples", "Spice/"))

Note that setting up the orbital elements and initial conditions using the ``orbitalMotion`` module is no longer needed.

After the Spice file is loaded, connect the configured Spice translational output message to the spacecraft object's
``transRefInMsg`` input message::

    scObject.transRefInMsg.subscribeTo(spiceObject.transRefStateOutMsgs[0])

Finally, add the Spice object to the simulation task list::

    scSim.AddModelToTask(simTaskName, spiceObject)

Implementing Attitude Pointing Modes
------------------------------------

Now that the spacecraft's translational motion is set, the user is free to implement attitude changes to enhance the
mission visualization. Three attitude pointing modes are incorporated into this script for each planetary flyby case.

First, an ``ephemerisConverter`` module must be configured to convert Spice messages of type ``plantetStateOutMsgs``
to ephemeris messages of type ``ephemOutMsgs``. This converter is required for all attitude pointing modules::

    ephemObject = ephemerisConverter.EphemerisConverter()
    ephemObject.modelTag = 'EphemData'
    ephemObject.addSpiceInputMsg(spiceObject.planetStateOutMsgs[earthIdx])
    ephemObject.addSpiceInputMsg(spiceObject.planetStateOutMsgs[sunIdx])
    ephemObject.addSpiceInputMsg(spiceObject.planetStateOutMsgs[moonIdx])
    ephemObject.addSpiceInputMsg(spiceObject.planetStateOutMsgs[venusIdx])
    ephemObject.addSpiceInputMsg(spiceObject.planetStateOutMsgs[marsIdx])
    scSim.AddModelToTask(simTaskName, ephemObject)

Next, the ``extForceTorque`` and ``simpleNav`` modules must be set configured::

    extFTObject = extForceTorque.ExtForceTorque()
    sNavObject = simpleNav.SimpleNav()

The torque module object is added to the spacecraft as a dynamics effector and the simple navigation module's spacecraft
state input message must be subscribed to the spacecraft object's state output message::

    scObject.addDynamicEffector(extFTObject)
    sNavObject.scStateInMsg.subscribeTo(scObject.scStateOutMsg)

Both modules are added to the simulation task::

    scSim.AddModelToTask(simTaskName, extFTObject)
    scSim.AddModelToTask(simTaskName, sNavObject)

Next the ``velocityPoint`` module is configured for each planet case. This module fixes the spacecraft attitude in the
orbit velocity frame. See :ref:`velocityPoint` for a more detailed description of this module. The Mars velocity-pointing case is shown below::

    velMarsGuidance = velocityPoint.VelocityPoint()
    velMarsGuidance.modelTag = "velocityPointMars"
    velMarsGuidance.mu = marsMu

The velocity pointing module has two input messages that must be connected. First, the module's
``transNavInMsg`` message is subscribed to the simple navigation module's ``transOutMsg`` message. The module's
``celBodyInMsg`` message must be connected to the flyby planet's ephemeris output message::

    velMarsGuidance.transNavInMsg.subscribeTo(sNavObject.transOutMsg)
    velMarsGuidance.celBodyInMsg.subscribeTo(ephemObject.ephemOutMsgs[marsIdx])

Finally, add the module to the simulation task list::

    scSim.AddModelToTask(simTaskName, velMarsGuidance)

The other attitude guidance modules used in this simulation are implemented in similar manner. The ``locationPointing``
module points a body-fixed spacecraft axis towards a particular location of interest. Modes for Earth- and Sun-pointing
are implemented by subscribing the module's ``celBodyInMsg`` input message to the desired planet's ephemeris output
message. The module's ``pHat_B`` vector is set according to which body-fixed vector should point towards the location
of interest. See :ref:`locationPointing` for a more detailed description of this module.
The Earth-pointing guidance module setup is shown below::

    earthPointGuidance = locationPointing.LocationPointing()
    earthPointGuidance.modelTag = "antennaEarthPoint"
    earthPointGuidance.scTransInMsg.subscribeTo(sNavObject.transOutMsg)
    earthPointGuidance.celBodyInMsg.subscribeTo(ephemObject.ephemOutMsgs[earthIdx])
    earthPointGuidance.scTransInMsg.subscribeTo(sNavObject.transOutMsg)
    earthPointGuidance.scAttInMsg.subscribeTo(sNavObject.attOutMsg)
    earthPointGuidance.pHat_B = [0.0, 0.0, 1.0]
    earthPointGuidance.useBoresightRateDamping = 1
    scSim.AddModelToTask(simTaskName, earthPointGuidance)

Next, a science-pointing mode is implemented using the ``hillPoint`` module. This module points a body-fixed location
on the spacecraft designated as a camera towards the flyby planet of interest. See :ref:`hillPoint` for a more
detailed description of this module::

    cameraLocation = [0.0, 1.5, 0.0]
    sciencePointGuidance = hillPoint.HillPoint()
    sciencePointGuidance.modelTag = "sciencePointAsteroid"
    sciencePointGuidance.transNavInMsg.subscribeTo(sNavObject.transOutMsg)
    sciencePointGuidance.celBodyInMsg.subscribeTo(ephemObject.ephemOutMsgs[planetIdx])
    scSim.AddModelToTask(simTaskName, sciencePointGuidance)

Next, the attitude tracking error module must be configured with the initial flight mode::

    attError = attTrackingError.AttTrackingError()
    attError.modelTag = "attErrorInertial3D"
    scSim.AddModelToTask(simTaskName, attError)
    attError.attRefInMsg.subscribeTo(velEarthGuidance.attRefOutMsg)  # initial flight mode
    attError.attNavInMsg.subscribeTo(sNavObject.attOutMsg)

Then, the flight software vehicle configuration message is configured::

    vehicleConfigOut = messaging.VehicleConfigMsgPayload()
    vehicleConfigOut.ISCPntB_B = I  # use the same inertia in the FSW algorithm as in the simulation
    vcMsg = messaging.VehicleConfigMsg().write(vehicleConfigOut)

The MRP Feedback control module is configured next for attitude control::

    mrpControl = mrpFeedback.MrpFeedback()
    mrpControl.modelTag = "mrpFeedback"
    scSim.AddModelToTask(simTaskName, mrpControl)
    mrpControl.guidInMsg.subscribeTo(attError.attGuidOutMsg)
    mrpControl.vehConfigInMsg.subscribeTo(vcMsg)
    mrpControl.setK(3.5)
    mrpControl.setKi(-1.0)  # make value negative to turn off integral feedback
    mrpControl.setP(30.0)
    mrpControl.setIntegralLimit(2. / mrpControl.getKi() * 0.1)

To complete the feedback loop, the MRP feedback module's ``cmdTorqueOutMsg`` output message is connected to the
external torque module's ``cmdTorqueInMsg``::

    extFTObject.cmdTorqueInMsg.subscribeTo(mrpControl.cmdTorqueOutMsg)

Additional Visualization Features
------------------------------------

To add a visualization of antenna transmission back to Earth during the Earth-pointing mode, a transceiver is created
through the ``vizInterface``::

    transceiverHUD = vizInterface.Transceiver()
    transceiverHUD.r_SB_B = [0.23, 0., 1.38]
    transceiverHUD.fieldOfView = 40.0 * macros.D2R
    transceiverHUD.normalVector = [0.0, 0., 1.0]
    transceiverHUD.color = vizInterface.IntVector(vizSupport.toRGBA255("cyan"))
    transceiverHUD.label = "antenna"
    transceiverHUD.animationSpeed = 1

To add a camera to the science-pointing mode, the ``createStandardCamera`` method is used::

    vizSupport.createStandardCamera(viz, setMode=1, spacecraftName=scObject.modelTag,
                                    fieldOfView=10 * macros.D2R,
                                    pointingVector_B=[0,1,0], position_B=cameraLocation)

After the simulation is initialized, functions are created for each attitude flight mode. Each function accepts the
desired simulation time and executes the simulation after setting additional flight mode parameters. Note that because
the velocity pointing mode depends on which planet is specified, this function is generalized to also accept the
desired guidance configuration module::

    def runVelocityPointing(simTime, planetMsg):
        nonlocal simulationTime
        attError.attRefInMsg.subscribeTo(planetMsg)
        transceiverHUD.transceiverState = 0  # antenna off
        attError.setSigma_R0R([np.tan(90.*macros.D2R/4), 0, 0])
        simulationTime += macros.sec2nano(simTime)
        scSim.ConfigureStopTime(simulationTime)
        scSim.ExecuteSimulation()

To execute the desired attitude-pointing mode, the ``run`` function must be called with the desired simulation time::

    runVelocityPointing(4*hour, velPlant.attRefOutMsg)

Ensure to unload the Spice kernel at the end of each simulation::

    spiceObject.unloadSpiceKernel("max_21T01.bsp", os.path.join(path, "Data", "Spice/"))


Simulation Visualization In Vizard
----------------------------------

The following image illustrates the expected visualization of this simulation script for a flyby of Mars.

.. image:: /_images/static/scenarioFlybySpice.jpg
   :align: center