.. _scenarioCSSFilters: scenarioCSSFilters ================== Overview -------- This script sets up a 6-DOF spacecraft in deep space without any gravitational bodies. Only rotational motion is simulated. The script illustrates how to setup attitude filters that use measurements from the Coarse Sun Sensors (CSS). The script is found in the folder ``xmera/examples`` and executed by using:: python3 scenarioCSSFilters.py When the simulation completes several plots are written summarizing the filter performances. The simulation reads the Sun's position from :ref:`SpiceInterface`. By creating this spice object and adding it to the task, the spice object automatically writes out the ephemeris messages. The dynamics simulation is setup using a :ref:`Spacecraft` module where a specific spacecraft location is specified. Note that both the rotational and translational degrees of freedom of the spacecraft hub are turned on here to get a 6-DOF simulation. The position vector is required when computing the relative heading between the sun and the spacecraft locations. The spacecraft position is held fixed, while the orientation rotates constantly about the 3rd body axis. The CSS modules must first be individual created and configured. This simulation uses 8 sun sensors, in 2 pyramids of 4 units. The code that sets up a constellation displays another method that is used in :ref:`scenarioCSS`. In this case instead of creating a list of CSS and adding the list to the constellation, the ``appendCSS`` command is used. The constellation characteristics are summarized in the following table. This table shows the individual unit vectors for each sensor, named ``nHat_B`` in the code. ======== ============================ CSS normal vector ======== ============================ 1 [:math:`\sqrt{2}`/2, -0.5, 0.5] 2 [:math:`\sqrt{2}`/2, -0.5, -0.5] 3 [:math:`\sqrt{2}`/2, 0.5, -0.5] 4 [:math:`\sqrt{2}`/2, 0.5, 0.5] 5 [-:math:`\sqrt{2}`/2, 0, :math:`\sqrt{2}`/2] 6 [-:math:`\sqrt{2}`/2, :math:`\sqrt{2}`/2, 0] 7 [-:math:`\sqrt{2}`/2, 0, -:math:`\sqrt{2}`/2] 8 [-:math:`\sqrt{2}`/2, -:math:`\sqrt{2}`/2, 0] ======== ============================ An additional message must be written for the configuration of the CSS for the Flight Software modules. This is done with ``vehicleConfigData``, a message that is read once at the start of a simulation. This message also allows the user to set different values between the simulation and the flight software parameters, which could corrupt the simulation, and reproduce an imperfect spacecraft construction process. The filters can now be initialized. These are configured very similarly, but the nature of the filters lead to slight differences. All of the filters output a Navigation message which outputs the sun heading for other modules to use, but they also output a filtering message (:ref:`sunlineFilterMsgPayload`), containing observations, post-fit residuals, covariances, and full states. This allows users to check in on filter performances efficiently, and is used in this tutorial. This first allows us to see when observations occur throughout the scenario over which we are comparing performance: .. image:: /_images/Scenarios/scenario_Filters_ObsOEKF.svg :align: center Setup 1 - ukF ------------- In the first run, we use an square root unscented Kalman Filter (:ref:`sunlineUKF`). This filter has the following states: ================ ============= States notation ================ ============= Sunheading ``d`` Sunheading Rate| ``d_dot`` ================ ============= This filter estimates sunheading, and the sunheading's rate of change. As a unscented filter, it also has the the following parameters: ============= ============= Name Value ============= ============= ``alpha`` 0.02 ``beta`` 2 ``kappa`` 0 ============= ============= The covariance is then set, as well as the measurement noise: ============================================= ================== Parameter Value ============================================= ================== covariance on heading vector components 0.2 covariance on heading rate components 0.02 noise on heading measurements 0.017 ** 2 noise on heading measurements 0.0017 ** 2 ============================================= ================== The resulting plots of the states, their covariance envelopes, as compared to the true state are plotted. Further documentation can be found in :ref:`sunlineUKF`. .. image:: /_images/Scenarios/scenario_Filters_StatesPlotuKF.svg :align: center .. image:: /_images/Scenarios/scenario_Filters_StatesExpecteduKF.svg :align: center These plots show good state estimation throughout the simulation. The mean stays close to the truth, the states do appear slightly noisy at times. The post fit residuals, show a fully functional filter, with no issues of observability: .. image:: /_images/Scenarios/scenario_Filters_PostFituKF.svg :align: center Setup 2 - EKF ------------- The following filter tested is an Extended Kalman filter (:ref:`sunlineEKF`). This filter uses all the same values for initialization as the uKF (aside from the uKF specific alpha, beta, kappa variables). A couple variables are added: =============== =============== Name Value =============== =============== Process noise 0.001**2 CKF switch 5 =============== =============== The process noise is the noise added on the dynamics. This allows to account for dynamical uncertainties, and avoid filter saturation. The CKF switch is the number of measurements that are processed using a classical, linear Kalman filter when the filter is first run. This allows for the covariance to shrink before employing the EKF, increasing the robustness. The states vs expected states are plotted, as well as the state error plots along with the covariance envelopes. Further documentation can be found in :ref:`sunlineEKF` .. image:: /_images/Scenarios/scenario_Filters_StatesPlotEKF.svg :align: center .. image:: /_images/Scenarios/scenario_Filters_StatesExpectedEKF.svg :align: center These plots show good state estimation throughout the simulation and despite the patches of time with fewer measurements. The covariance stays close to the mean, without exesive noise. The post fit residuals, give further confirmation of a working filter: .. image:: /_images/Scenarios/scenario_Filters_PostFitEKF.svg :align: center Setup 3 - OEKF -------------- The 3rd scenario uses a second type of Extended Kalman Filter (:ref:`okeefeEKF`). This filter takes in fewer states as it only estimates the sun heading. In order to propagate it, it estimates the omega vector from the two last measurements. The set up is nearly identical to the EKF, with the exception of the size of the vectors and matrices (only 3 states are estimated now). Furthermore, the rotation rate of the spacecraft, omega, is initialized. More in-depth documentation on the filter specifics are found in :ref:`okeefeEKF`. .. image:: /_images/Scenarios/scenario_Filters_StatesPlotOEKF.svg :align: center .. image:: /_images/Scenarios/scenario_Filters_StatesExpectedOEKF.svg :align: center These plots show poorer state estimation throughout the simulation. As measurements stop, the filter doesn't propagate the states sufficiently well. This is due to the absence of rate in the states, and the compensation with the computation of omega can lead to noisy estimates. The post fit residuals, do show that the filter is working, just with difficulties when measurements become sparse: .. image:: /_images/Scenarios/scenario_Filters_PostFitOEKF.svg :align: center Setup 4 -Switch-EKF ------------------- The 4th scenario uses a Switch formulation to extract the observable rates as well as estimate the sun heading (:ref:`sunlineSEKF`). .. image:: /_images/Scenarios/scenario_Filters_StatesPlotSEKF.svg :align: center .. image:: /_images/Scenarios/scenario_Filters_StatesExpectedSEKF.svg :align: center These plots show poorer state estimation throughout the simulation. The post fit residuals show that the filter is working, just with difficulties when measurements become sparse. .. image:: /_images/Scenarios/scenario_Filters_PostFitSEKF.svg :align: center Setup 5 -Switch-uKF ------------------- The 5th scenario uses the same Switch formulation but in a square-root uKF (:ref:`sunlineSuKF`). This one has an additional state: the sun intensity (equal to 1 at 1AU). This state has low process noise and low initial covariance given it's well determined nature generally. .. image:: /_images/Scenarios/scenario_Filters_StatesPlotSuKF.svg :align: center .. image:: /_images/Scenarios/scenario_Filters_StatesExpectedSuKF.svg :align: center These plots show good state estimation throughout the simulation. The mean stays close to the truth. The post fit residuals, show a fully functional filter, with no issues of observabilty: .. image:: /_images/Scenarios/scenario_Filters_PostFitSuKF.svg :align: center