.. _estimationExecution:
Parameter Estimation
=========================
.. _estimationObjectCreation:
Creating the estimation object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The estimation of orbits and physical parameters in Tudat is done through the use of an :class:`OrbitDeterminationManager` object. This object is created once for a given set of estimated parameters, and may be (re-)used to reset and/or estimate parameters from a given set of data.
.. class:: OrbitDeterminationManager
Creating an object of this type automatically propagates both the equations of motion and variational equations using the input to its constructor. Additionally, a set of :class:`ObservationSimulatorBase` objects is created, as well as all required objects to compute the partial derivatives of the observations.
An object is created as follows:
.. code-block:: cpp
OrbitDeterminationManager orbitDeterminationManager =
std::make_shared< ObservationViabilitySettings >(
OrbitDeterminationManager( bodyMap, parametersToEstimate, observationSettingsMap, integratorSettings, propagatorSettings );
The input is:
- :literal:`bodyMap`
A :literal:`NamedBodyMap` variable which contains all information on the physical environment
- :literal:`parametersToEstimate`
A :literal:`std::shared_ptr< EstimatableParameterSet< ObservationScalarType > >` variable which contains the full list of parameters that are to be estimated.
- :literal:`observationSettingsMap`
A list of :class:`ObservationSettings` that may be provided as either :literal:`std::multimap< LinkEnds, std::shared_ptr< ObservationSettings > >` or a :literal:`std::map< ObservableType, std::map< LinkEnds, std::shared_ptr< ObservationSettings > >`. In the former case, the list is sorter by :literal:`LinkEnds` only, in the latter by both :literal:`ObservableType` and :literal:`LinkEnds`
- :literal:`integratorSettings`
A :literal:`std::shared_ptr< IntegratorSettings< TimeType > >` object which contains all settings for the numerical integrator, used to numerically calcualte the dynamics and variational equations.
- :literal:`propagatorSettings`
A :literal:`std::shared_ptr< PropagatorSettings< ObservationScalarType > >` object which contains all propagation settings.
.. warning::
The settings in :class:`PropagatorSettings` and :class:`EstimatableParameterSet` must be consistently defined: any initial state that is propagated *must* also be estimated, there is as yet no possibility to only estimate some of the propagates states.
After the creation of the :class:`OrbitDeterminationManager` object, a number of objects are created internally that can be used for various purposes:
* An object with base class :class:`VariationalEquationsSolver`, which contains the numerically propagated variational equations and dynamics, can be retrieved using the :literal:`getVariationalEquationsSolver` member function.
* A list of objects with base class :class:`ObservationSimulatorBase` (one per observable type) to simulate observations, discussed in more detail on the page on :ref:`creatingObservationSimulators`
* A list of objects with base class :class:`ObservationManagerBase` (one per observable type) to simulate observations and the associated partial derivatives. These objects are not directly accesed by users. Their output (partial derivatives of observables) are provided *a posterior* through an object of type :class:`PodOutput`, discussed on the page on :ref:`estimationOutput`.
.. _estimationInput:
Defining estimation input
~~~~~~~~~~~~~~~~~~~~~~~~~
The input to the estimation consists of several parts. Firstly, the input data, weights, *etc.* need to be defined, which is done through the :literal:`PodInput` class.
.. class:: PodInput
This class is templated by both :literal:`ObservationScalarType` and :literal:`TimeType`. An object of :class:`PodInput` is created as follows:
.. code-block:: cpp
std::shared_ptr< PodInput< ObservationScalarType, TimeType > > podInput =
std::make_shared< PodInput< ObservationScalarType, TimeType > >(
observationsAndTimes, numberOfEstimatedParameters, inverseOfAprioriCovariance );
The input is:
- :literal:`observationsAndTimes` A container of type :literal:`std::map< ObservableType, std::map< LinkEnds, std::pair< Eigen::Matrix< ObservationScalarType, Eigen::Dynamic, 1 >, std::pair< std::vector< TimeType >, LinkEndType > > > >` (the structure of which is described in more detail on the page :ref:`generatingObservations`). This container has both the observables to be used in the estimation, and the assictaed times and link end types.
- :literal:`numberOfEstimatedParameters` An :literal:`int` denoting the length of the vector of estimated paramaters, discussed in more detail on the page :ref:`parameterSettingCreation`.
- :literal:`inverseOfAprioriCovariance` An :literal:`Eigen::MatrixXd` with the inverse of the *a priori* covariance matrix. This input type may be left empty, in which case no *a priori* covariance is used.
.. note::
Currently, Tudat only supports diagonal weight matrices, implicitly assuming independent observation noise in the inversion.
.. _estimationOutput:
Estimation output
~~~~~~~~~~~~~~~~~
When performing the estimation, the code rescales the values of all parameters :math:`p`, where we denote the scaled parameters as :math:`\tilde{h}`, so that all partials :math:`\partial h/\partial\tilde{p}` w.r.t. lie in the range :math:`[-1,1]`. To provide transparency, it is the covariance and partial derivative matrix of these scaled parameters that is saved to the :literal:`PodOutput` object. However, the following functions allow you to retrieve the information w.r.t. the *unscaled* parameters:
* Inverse covariance, obtained using the :literal:`getUnnormalizedInverseCovarianceMatrix` function.
* Covariance, obtained using the :literal:`getUnnormalizedCovarianceMatrix` function. Note that this only produces valid results if the problem is not ill-posed.
* Formal error vector, obtained using the :literal:`getFormalErrorVector` function. Note that this only produces valid results if the problem is not ill-posed.
* Correlation matrix, obtained using the :literal:`getCorrelationMatrix` function. Note that this only produces valid results if the problem is not ill-posed.