.. _scenarioVariableTimeStepIntegrators:

scenarioVariableTimeStepIntegrators
===================================

Overview
--------

This script illustrates how to setup different variable time step integration methods for a basic 3-DOF orbit scenario.
Both a fourth-order (RKF45) and a seventh-order (RKF78) integrators are used. For comparison, an RK4 integrator is also
used.

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

      python3 scenarioVariableTimeStepIntegrators.py

For more information on how to setup different integrators, see :ref:`scenarioIntegrators`. When the simulation
completes, a plot is shown for illustrating both the true and the numerically evaluated orbit.

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

::

    show_plots = True, integratorCase = {'rk4', 'rkf45', 'rkf78'}

The following figure illustrates the resulting trajectories relative to the true trajectory using a very coarse
integration time step of 2 hours. The variable time step integrators still approximates the true orbit well, while
the RK4 method is starting to show some visible errors, illustrating that much smaller time steps must be used with
this method in this scenario.

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


Creating New Integrator Modules
-------------------------------

New integration modules can be readily created for Xmera.  They are all stored in the folder
``Xmera/src/simulation/dynamics/Integrators/``.

The integrators must be created to function on a general state vector and be independent of the particular
dynamics being integrated.  Note that the default integrator is placed inside the ``_GeneralModulesFiles``
folder within the ``dynamics`` folder.