estimation_analysis

This module contains the top-level functionality for performing a covariance analysis or state/parameter estimation in Tudat. The class through which these procedures are performed is the Estimator class, with dedicated classes for input and output for both a covariance analysis and estimation (CovarianceAnalysisInput, CovarianceAnalysisOutput, EstimationInput, EstimationOutput). The procedure for state estimation is described in detail on a series of user guide pages, with the final step of using the Estimator class described here.

In addition to functionality to perform and support the estimation, this module also contains functionality to propagate the covariance that is obtained at the initial epoch \(t_{0}\) to any other epoch (see tudatpy.estimation.estimation_analysis.propagate_covariance()).

Finally, this module also contains functions of convenience to perform the estimation of state and parameters based on pseudo-observations using the create_best_fit_to_ephemeris() function.

Functions

propagate_covariance(initial_covariance, ...)

Function to propagate system covariance through time.

propagate_covariance_from_analysis_objects(...)

Function to propagate system covariance through time.

propagate_formal_errors(initial_covariance, ...)

Function to propagate system formal errors through time.

estimation_convergence_checker([...])

Function for creating an EstimationConvergenceChecker object.

create_covariance_from_diagonal_entries(...)

Function to create a covariance-like matrix from per-parameter diagonal-entry vectors.

add_covariance_diagonal_entries(...[, ...])

Function to add or update diagonal entries in a covariance-like matrix.

create_best_fit_to_ephemeris(bodies, ...)

No documentation found.
propagate_covariance(initial_covariance: numpy.ndarray[numpy.float64[m, n]], state_transition_interface: tudatpy.kernel.dynamics.simulator.CombinedStateTransitionAndSensitivityMatrixInterface, output_times: list[float | SupportsIndex]) → dict[float, numpy.ndarray[numpy.float64[m, n]]]

Function to propagate system covariance through time.

Function to propagate the covariance of a given system through time. The covariance of the states and parameters at the reference epoch \(\mathbf{P}(t_{0})\) is to be provided as input by the user. The definition of the parameters provided in the entries of this covariance must be consistent with those in the associated state_transition_interface input. Splitting the covariance into dynamical parameters (initial states \(\mathbf{x_{0}}=\mathbf{x}_{0}\)) and static parameters :math:mathbf{p}`, we can write:

\[\begin{split}\mathbf{P}(t_{0}) &= \begin{pmatrix} \mathbf{P}_{x0,x0} & \mathbf{P}_{x0,p} \\ \mathbf{P}_{p,x0} & \mathbf{P}_{p,p} \end{pmatrix}\\ \boldsymbol{\Psi(t,t_{0})} &= \begin{pmatrix} \boldsymbol{\Phi}(t,t_{0}) & \mathbf{S}(t) \\ \mathbf{0} & \mathbf{1} \end{pmatrix}\end{split}\]

with \(\boldsymbol{\Phi}(t,t_{0})\) and \(\mathbf{S}(t)\) the state transition and sensitivity matrices. The covariance is then propagated to any time \(t\) using:

\[\begin{split}\mathbf{P}(t) &= \boldsymbol{\Psi(t,t_{0})} \mathbf{P}(t_{0}) \boldsymbol{\Psi(t,t_{0})}^{T} &= \begin{pmatrix} \mathbf{P}_{x,x} & \mathbf{P}_{x,p} \\ \mathbf{P}_{p,x} & \mathbf{P}_{p,p} \end{pmatrix}\end{split}\]

To automatically link the covariance computed by an Estimator object, use the propagate_covariance_from_analysis_objects() function

Parameters:

  • initial_covariance (numpy.ndarray[numpy.float64[n, n]]) – System covariance matrix (symmetric and positive semi-definite) at initial time. Dimensions have to be consistent with estimatable parameters in the system (specified by state_transition_interface)

  • state_transition_interface (CombinedStateTransitionAndSensitivityMatrixInterface) – Interface to the variational equations of the system dynamics, handling the propagation of the covariance matrix through time (typically retrieved from state_transition_interface).

  • output_times (List[ astro.time_representation.Time ]) – Times at which the propagated covariance matrix shall be reported. Note that this argument has no impact on the integration time-steps of the variational equations, which happens before the call to this function, with results stored in the state_transition_interface input. Output times which do not coincide with integration time steps are calculated via interpolation.

Returns:

Dictionary reporting the propagated covariances at each output time.

Return type:

Dict[ astro.time_representation.Time, numpy.ndarray[numpy.float64[n, n]] ]

propagate_covariance_from_analysis_objects(analysis_output: tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisOutput, state_transition_interface: tudatpy.kernel.dynamics.simulator.CombinedStateTransitionAndSensitivityMatrixInterface, output_times: list[float | SupportsIndex]) → dict[float, numpy.ndarray[numpy.float64[m, n]]]

Function to propagate system covariance through time.

Function to propagate the covariance of a given system through time. Functionality is similar as propagate_covariance() with the difference that the initial covariance is automatically extracted from the analysis_output input.

This function also automatically deals with the presence of any consider parameters \(\mathbf{p}_{c}\). If these are present (with covariance \(\mathbf{C}\), taken from consider_covariance) the system propagates the matrix \(\bar{\mathbf{P}}\) constructed from the consider-parameter-free matrix \(\mathbf{P}\) (taken from covariance) as:

\[\begin{split}\bar{\mathbf{P}}(t_{0}) &= \begin{pmatrix} \mathbf{P} + \Delta\mathbf{P}_{c} & \mathbf{0} \\ \mathbf{0} & \mathbf{C} \end{pmatrix}\end{split}\]

where \(\Delta\mathbf{P}_{c}\) (taken from consider_covariance_contribution) is the contribution of the consider parameters to the estimated parameter covariance at \(t_{0}\)

Parameters:
Returns:

Dictionary reporting the propagated covariances at each output time.

Return type:

Dict[ astro.time_representation.Time, numpy.ndarray[numpy.float64[m, n]] ]

propagate_formal_errors(initial_covariance: numpy.ndarray[numpy.float64[m, n]], state_transition_interface: tudatpy.kernel.dynamics.simulator.CombinedStateTransitionAndSensitivityMatrixInterface, output_times: list[float | SupportsIndex]) → dict[float, numpy.ndarray[numpy.float64[m, 1]]]

Function to propagate system formal errors through time.

Identical to propagate_covariance(), but returning only the formal errors :math:sigma_{i}` (from diagonal of covariance \(P_{ii}=\sigma_{i}^{2}\))

Parameters:

  • initial_covariance (numpy.ndarray[numpy.float64[m, n]]) – System covariance matrix (symmetric and positive semi-definite) at initial time. Dimensions have to be consistent with estimatable parameters in the system (specified by state_transition_interface)

  • state_transition_interface (CombinedStateTransitionAndSensitivityMatrixInterface) – Interface to the variational equations of the system dynamics, handling the propagation of the covariance matrix through time (typically retrieved from state_transition_interface).

  • output_times (List[ astro.time_representation.Time ]) – Times at which the propagated covariance matrix shall be reported. Note that this argument has no impact on the integration time-steps of the variational equations, which happens before the call to this function, with results stored in the state_transition_interface input. Output times which do not coincide with integration time steps are calculated via interpolation.

Returns:

Dictionary reporting the propagated formal errors at each output time.

Return type:

Dict[ astro.time_representation.Time, numpy.ndarray[numpy.float64[m, 1]] ]

estimation_convergence_checker(maximum_iterations: int | SupportsIndex = 5, minimum_residual_change: float | SupportsIndex = 0.0, minimum_residual: float | SupportsIndex = 0.0, number_of_iterations_without_improvement: int | SupportsIndex = 2) → tudatpy.kernel.estimation.estimation_analysis.EstimationConvergenceChecker

Function for creating an EstimationConvergenceChecker object.

Function for creating an EstimationConvergenceChecker object, which is required for defining the convergence criteria of an estimation.

Parameters:

  • maximum_iterations (int, default = 5) – Maximum number of allowed iterations for estimation.

  • minimum_residual_change (float, default = 0.0) – Minimum required change in residual between two iterations.

  • minimum_residual (float, default = 0.0) – Minimum value of observation residual below which estimation is converged.

  • number_of_iterations_without_improvement (int, default = 2) – Number of iterations without reduction of residual.

Returns:

Instance of the EstimationConvergenceChecker class, defining the convergence criteria for an estimation.

Return type:

EstimationConvergenceChecker

create_covariance_from_diagonal_entries(parameter_set: tudatpy.kernel.dynamics.parameters.EstimatableParameterSet, covariance_diagonal_entries_per_parameter: list[tuple[tuple[tudatpy.kernel.dynamics.parameters_setup.EstimatableParameterTypes, tuple[str, str]], numpy.ndarray[numpy.float64[m, 1]]]], require_all_entries_to_match: bool = True) → numpy.ndarray[numpy.float64[m, n]]

Function to create a covariance-like matrix from per-parameter diagonal-entry vectors.

Function that creates a full covariance-like matrix for the estimated parameters in parameter_set. The matrix is initialized as all zeros and only diagonal entries for specified parameters are set. This function is representation-agnostic and can be used for covariance matrices, inverse covariance matrices, consider covariance matrices, or any parameter-aligned diagonal matrix.

The covariance_diagonal_entries_per_parameter input is a list where each entry is:

  • a tuple (parameter_identifier, covariance_diagonal_entries_vector)

with:

  • parameter_identifier = (EstimatableParameterTypes, (body_name, secondary_name))

  • covariance_diagonal_entries_vector = 1D vector of diagonal values. The vector is interpreted per matched parameter block: - length 1: the scalar is broadcast to all components of the matched parameter block - length = parameter block size: each vector element is used for the corresponding block component

If both strings in parameter_identifier are empty, parameter matching is performed by enum only. In case of multiple matching parameters, the same a priori constraint is applied to each match.

For each matched parameter block, the values from covariance_diagonal_entries_vector are written directly to the corresponding diagonal entries of the output matrix.

Parameters:

  • parameter_set (EstimatableParameterSet) – Consolidated set of estimated parameters.

  • covariance_diagonal_entries_per_parameter (list) – List of (parameter_identifier, covariance_diagonal_entries_vector) entries.

  • require_all_entries_to_match (bool, default = True) – If True, each parameter_identifier must match at least one parameter block, otherwise a runtime error is raised. If False, non-matching identifiers are ignored.

Returns:

Covariance-like matrix with specified diagonal entries.

Return type:

numpy.ndarray[numpy.float64[m, m]]

add_covariance_diagonal_entries(covariance_matrix: numpy.ndarray[numpy.float64[m, n]], parameter_set: tudatpy.kernel.dynamics.parameters.EstimatableParameterSet, covariance_diagonal_entries_per_parameter: list[tuple[tuple[tudatpy.kernel.dynamics.parameters_setup.EstimatableParameterTypes, tuple[str, str]], numpy.ndarray[numpy.float64[m, 1]]]], require_all_entries_to_match: bool = True) → numpy.ndarray[numpy.float64[m, n]]

Function to add or update diagonal entries in a covariance-like matrix.

Function that takes an existing covariance-like matrix and sets diagonal entries from the provided per-parameter diagonal-entry vectors. Existing matrix entries are preserved, except for constrained diagonal entries which are overwritten. This function is representation-agnostic and can be used for covariance matrices, inverse covariance matrices, consider covariance matrices, or any parameter-aligned diagonal matrix.

If covariance_matrix is provided as a 0x0 matrix, a zero matrix with the correct parameter dimension is created before applying entries.

The format and interpretation of covariance_diagonal_entries_per_parameter is identical to create_covariance_from_diagonal_entries().

Parameters:

  • covariance_matrix (numpy.ndarray[numpy.float64[m, m]]) – Existing covariance-like matrix (or a 0x0 matrix).

  • parameter_set (EstimatableParameterSet) – Consolidated set of estimated parameters.

  • covariance_diagonal_entries_per_parameter (list) – List of (parameter_identifier, covariance_diagonal_entries_vector) entries.

  • require_all_entries_to_match (bool, default = True) – If True, each parameter_identifier must match at least one parameter block, otherwise a runtime error is raised. If False, non-matching identifiers are ignored.

Returns:

Updated covariance-like matrix.

Return type:

numpy.ndarray[numpy.float64[m, m]]

create_best_fit_to_ephemeris(bodies: tudatpy.kernel.dynamics.environment.SystemOfBodies, acceleration_models: dict[str, dict[str, list[tudatpy.kernel.dynamics.propagation.AccelerationModel]]], observed_bodies: list[str], central_bodies: list[str], integrator_settings: tudatpy.kernel.dynamics.propagation_setup.integrator.IntegratorSettings, initial_time: tudatpy.kernel.astro.time_representation.Time, final_time: tudatpy.kernel.astro.time_representation.Time, data_point_interval: tudatpy.kernel.astro.time_representation.Time, additional_parameter_names: list[tudatpy.kernel.dynamics.parameters_setup.EstimatableParameterSettings] = [], number_of_iterations: int | SupportsIndex = 3, reintegrate_variational_equations: bool = True, results_print_frequency: float | SupportsIndex = 0.0) → tudat::simulation_setup::EstimationOutput<double, tudat::Time>

No documentation found.

Classes

CovarianceAnalysisInput

Class for defining all inputs to a covariance analysis.

EstimationInput

Class for defining all inputs to the estimation.

CovarianceAnalysisOutput

Class collecting all outputs from the covariance analysis process (which takes a CovarianceAnalysisInput as input)

EstimationOutput

Class collecting all outputs from the iterative estimation process.

Estimator

Class for consolidating all estimation functionality.

EstimationConvergenceChecker

Class defining the convergence criteria for an estimation.
class CovarianceAnalysisInput

Bases: pybind11_object

Class for defining all inputs to a covariance analysis.

__init__(self: tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisInput, observations_and_times: tudatpy.kernel.estimation.observations.ObservationCollection, inverse_apriori_covariance: numpy.ndarray[numpy.float64[m, n]] = array([], shape=(0, 0), dtype=float64), consider_covariance: numpy.ndarray[numpy.float64[m, n]] = array([], shape=(0, 0), dtype=float64)) → None

Class constructor.

Constructor through which the user can create instances of this class. Note that the weight are all initiated as 1.0, and the default settings of define_covariance_settings are used.

Parameters:

  • observations_and_times (ObservationCollection) – Total data structure of observations and associated times/link ends/type/etc.

  • inverse_apriori_covariance (numpy.ndarray[numpy.float64[m, n]], default = [ ]) – A priori covariance matrix (unnormalized) of estimated parameters. This should be either a size 0x0 matrix (no a priori information), or a square matrix with the same size as the number of parameters that are considered

Returns:

Instance of the CovarianceAnalysisInput class, defining the data and other settings to be used for the covariance analysis.

Return type:

CovarianceAnalysisInput

define_covariance_settings(self: tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisInput, reintegrate_equations_on_first_iteration: bool = True, reintegrate_variational_equations: bool = True, save_design_matrix: bool = True, print_output_to_terminal: bool = True, limit_condition_number_for_warning: float | SupportsIndex = 100000000.0) → None

Function to define specific settings for covariance analysis process

Function to define specific settings for covariance analysis process

Parameters:

  • reintegrate_equations (bool, default = True) – Boolean denoting whether the dynamics and variational equations are to be reintegrated or if existing values are to be used to perform first iteration.

  • reintegrate_variational_equations (bool, default = True) – Boolean denoting whether the variational equations are to be reintegrated during estimation (if this is set to False, and reintegrate_equations to true, only the dynamics are re-integrated)

  • save_design_matrix (bool, default = True) – Boolean denoting whether to save the partials matrix (also called design matrix) \(\mathbf{H}\) in the output. Setting this to false makes the \(\mathbf{H}\) matrix unavailable to the user, with the advantage of lower RAM usage.

  • print_output_to_terminal (bool, default = True) – Boolean denoting whether to print covariance-analysis-specific output to the terminal when running the estimation.

Returns:

Function modifies the object in-place.

Return type:

None

Function is deprecated, weights should be set in the ObservationCollection object containing the data, see user guide description

Function is deprecated, weights should be set in the ObservationCollection object containing the data, see user guide description

set_constant_single_observable_vector_weight(self: tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisInput, observable_type: tudatpy.kernel.estimation.observable_models_setup.model_settings.ObservableType, weight: numpy.ndarray[numpy.float64[m, 1]]) → None

Function is deprecated, weights should be set in the ObservationCollection object containing the data, see user guide description

set_constant_single_observable_weight(self: tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisInput, observable_type: tudatpy.kernel.estimation.observable_models_setup.model_settings.ObservableType, weight: float | SupportsIndex) → None

Function is deprecated, weights should be set in the ObservationCollection object containing the data, see user guide description

set_constant_vector_weight_per_observable(self: tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisInput, weight_per_observable: dict[tudatpy.kernel.estimation.observable_models_setup.model_settings.ObservableType, numpy.ndarray[numpy.float64[m, 1]]]) → None

Function is deprecated, weights should be set in the ObservationCollection object containing the data, see user guide description

set_constant_weight(self: tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisInput, weight: float | SupportsIndex) → None

Function is deprecated, weights should be set in the ObservationCollection object containing the data, see user guide description

set_constant_weight_per_observable(self: tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisInput, weight_per_observable: dict[tudatpy.kernel.estimation.observable_models_setup.model_settings.ObservableType, float | SupportsIndex]) → None

Function is deprecated, weights should be set in the ObservationCollection object containing the data, see user guide description

Function is deprecated, weights should be set in the ObservationCollection object containing the data, see user guide description

set_weights_from_observation_collection(self: tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisInput) → None

Function is deprecated, weights should be set in the ObservationCollection object containing the data, see user guide description

property consider_covariance

read-only

A-priori covariance matrix of the considered parameters.

Type:

numpy.ndarray[numpy.float64[n, n]]

property inverse_apriori_covariance

read-only

Inverse a-priori covariance matrix of the estimated parameters.

Type:

numpy.ndarray[numpy.float64[n, n]]

property weight_matrix_diagonal

read-only

Complete diagonal of the weights matrix that is to be used

Type:

numpy.ndarray[numpy.float64[n, 1]]

class EstimationInput

Bases: CovarianceAnalysisInput

Class for defining all inputs to the estimation.

__init__(self: tudatpy.kernel.estimation.estimation_analysis.EstimationInput, observations_and_times: tudatpy.kernel.estimation.observations.ObservationCollection, inverse_apriori_covariance: numpy.ndarray[numpy.float64[m, n]]=array([], shape=(0, 0), dtype=float64), convergence_checker: tudatpy.kernel.estimation.estimation_analysis.EstimationConvergenceChecker = <tudatpy.kernel.estimation.estimation_analysis.EstimationConvergenceChecker object at 0x7fa5e93ee570>, consider_covariance: numpy.ndarray[numpy.float64[m, n]]=array([], shape=(0, 0), dtype=float64), consider_parameters_deviations: numpy.ndarray[numpy.float64[m, 1]]=array([], dtype=float64), apply_final_parameter_correction: bool = True) → None

Class constructor.

Constructor through which the user can create instances of this class.

Parameters:

  • observations_and_times (ObservationCollection) – Total data structure of observations and associated times/link ends/type/etc.

  • inverse_apriori_covariance (numpy.ndarray[numpy.float64[m, n]], default = [ ]) – A priori covariance matrix (unnormalized) of estimated parameters. This should be either a size 0x0 matrix (no a priori information), or a square matrix with the same size as the number of parameters that are considered

  • convergence_checker (EstimationConvergenceChecker, default = estimation_convergence_checker()) – Object defining when the estimation is converged.

Returns:

Instance of the EstimationInput class, defining the data and other settings to be used for the estimation.

Return type:

EstimationInput

define_estimation_settings(self: tudatpy.kernel.estimation.estimation_analysis.EstimationInput, reintegrate_equations_on_first_iteration: bool = True, reintegrate_variational_equations: bool = True, save_design_matrix: bool = True, print_output_to_terminal: bool = True, save_residuals_and_parameters_per_iteration: bool = True, save_state_history_per_iteration: bool = False, limit_condition_number_for_warning: float | SupportsIndex = 100000000.0, condition_number_warning_each_iteration: bool = True) → None

Function to define specific settings for the estimation process

Function to define specific settings for covariance analysis process

Parameters:

  • reintegrate_equations_on_first_iteration (bool, default = True) – Boolean denoting whether the dynamics and variational equations are to be reintegrated or if existing values are to be used to perform first iteration.

  • reintegrate_variational_equations (bool, default = True) – Boolean denoting whether the variational equations are to be reintegrated during estimation (if this is set to False, and reintegrate_equations_on_first_iteration to true, only the dynamics are re-integrated)

  • save_design_matrix (bool, default = True) – Boolean denoting whether to save the partials matrix (also called design matrix) \(\mathbf{H}\) in the output. Setting this to false makes the \(\mathbf{H}\) matrix unavailable to the user, with the advantage of lower RAM usage.

  • print_output_to_terminal (bool, default = True) – Boolean denoting whether to print covariance-analysis-specific output to the terminal when running the estimation.

  • save_residuals_and_parameters_per_iteration (bool, default = True) – Boolean denoting whether the residuals and parameters from the each iteration are to be saved.

  • save_state_history_per_iteration (bool, default = False) – Boolean denoting whether the state history and dependent variables are to be saved on each iteration.

Returns:

Function modifies the object in-place.

Return type:

None

class CovarianceAnalysisOutput

Bases: pybind11_object

Class collecting all outputs from the covariance analysis process (which takes a CovarianceAnalysisInput as input)

This object is typically created by the compute_covariance or perform_estimation function of the Estimator class. The primary inputs used to create this object are (see user guide for underlying models)

  • The partials matrix \(\mathbf{H}=\frac{\partial\mathbf{h}}{\partial\mathbf{p}}\) of the observations w.r.t. the estimated parameters

  • The inverse covariance matrix \(\mathbf{P}^{-1}\) of the estimated parameters (without influence of consider parameters). The inverse covariance is provided as input for situations where the inverse is unstable

  • The consider partials matrix \(\mathbf{H}_{c}=\frac{\partial\mathbf{h}}{\partial\mathbf{p}_{c}}\) of the observations w.r.t. the consider parameters (if any)

  • The contribution \(\Delta \mathbf{P}_{c}\) of the consider parameters to the estimated parameter covariance

In the computation of the covariance (see TODO), the columns of the \(H\) matrices are normalized to reduce numerical instability that can result from the partials w.r.t. different parameters being of a very different order of magnitude. The normalization is achieved by computing a vector \(\mathbf{N}\) (of the same size as the parameter vector \(\mathbf{p}\), such that for each column of the matrix \(\mathbf{H}\), we have:

\[\max_{i}\left| \frac{H_{ij}}{N_{j}}\right|=1\]

That is, the entries of \(\mathbf{N}\) are chosen such that they normalize the corresponding column of \(\mathbf{H}\) to be in the range \([-1,1]\). We denote the normalized quantities with a tilde, so that:

\[\begin{split}\tilde{H}_{ij}=\frac{H_{ij}}{N{j}}\\ \tilde{P}_{ij}=P_{ij}N_{i}N_{j}\end{split}\]

When wanting to recreate the internal workings of the analysis, use the normalized quantities, when interested in the actual covariances, sensitivities, etc of the observations/parameters, use the unnormalized quantities.

property consider_covariance

read-only

Covariance \(\mathbf{C}\) of consider parameters used in calculations

Type:

numpy.ndarray[numpy.float64[m, m]]

property consider_covariance_contribution

read-only

Contribution of the consider parameters to the estimated parameter covariance matrix, equal to \((\mathbf{P} \mathbf{H}^{T} \mathbf{W}) (\mathbf{H}_c \mathbf{C} \mathbf{H}^{T}_c) (\mathbf{P} \mathbf{H}^{T} \mathbf{W})^{T}\)

Type:

numpy.ndarray[numpy.float64[m, n]]

property consider_normalization_terms

read-only

Vector of consider parameter normalization terms \(\mathbf{N}_{c}\)

Type:

numpy.ndarray[numpy.float64[m, 1]]

property correlations

read-only

Correlation matrix of the estimation result. Entry \(i,j\) is equal to \(P_{i,j}/(\sigma_{i}\sigma_{j})\)

Type:

numpy.ndarray[numpy.float64[m, m]]

property covariance

read-only

(Unnormalized) estimation covariance matrix \(\mathbf{P}\). Note: if the any consider parameters are included in the analysis, this attribute does not include their contribution. The contribution of the consider parameters to the covariance can be retrieved from the consider_covariance_contribution attribute

Type:

numpy.ndarray[numpy.float64[m, m]]

property covariance_with_consider_parameters

read-only

Covariance matrix of the estimated parameters that includes the contribution of the consider parameters, equal to the sum of the covariance matrix and the consider_covariance_contribution matrix.

Type:

numpy.ndarray[numpy.float64[m, n]]

property design_matrix

read-only

Matrix of partial derivatives \(\mathbf{H}=\frac{\partial\mathbf{h}}{\partial\mathbf{p}}\).

Type:

numpy.ndarray[numpy.float64[m, n]]

property design_matrix_consider_parameters

read-only

Matrix of partial derivatives of observations w.r.t. consider parameters \(\mathbf{H}_c=\frac{\partial\mathbf{h}}{\partial\mathbf{c}}\).

Type:

numpy.ndarray[numpy.float64[m, n]]

property formal_errors

read-only

Formal error vector \(\boldsymbol{\sigma}\) of the estimation result (e.g. square root of diagonal entries of covariance \(\mathbf{P}\))

Type:

numpy.ndarray[numpy.float64[m, 1]]s

property inverse_covariance

read-only

(Unnormalized) inverse estimation covariance matrix \(\mathbf{P}^{-1}\). Note: if the any consider parameters are included in the analysis, this attribute does not include their contribution. The contribution of the consider parameters to the covariance can be retrieved from the consider_covariance_contribution attribute

Type:

numpy.ndarray[numpy.float64[m, m]]

property inverse_normalized_covariance

read-only

Normalized version of inverse_covariance

Type:

numpy.ndarray[numpy.float64[m, m]]

property normalization_terms

read-only

Vector of estimated parameter normalization terms \(\math{N}\)

Type:

numpy.ndarray[numpy.float64[m, 1]]

property normalized_covariance

read-only

Normalized version of covariance

Type:

numpy.ndarray[numpy.float64[m, m]]

property normalized_covariance_with_consider_parameters

read-only

Normalized version of covariance_with_consider_parameters

Type:

numpy.ndarray[numpy.float64[m, n]]

property normalized_design_matrix

read-only

Normalized version of design_matrix

Type:

numpy.ndarray[numpy.float64[m, n]]

property normalized_design_matrix_consider_parameters

read-only

Normalized version of design_matrix_consider_parameters

Type:

numpy.ndarray[numpy.float64[m, n]]

property weighted_design_matrix

read-only

Matrix of weighted partial derivatives, equal to \(\mathbf{W}^{1/2}{\mathbf{H}}\)

Type:

numpy.ndarray[numpy.float64[m, n]]

property weighted_normalized_design_matrix

read-only

Normalized version of weighted_design_matrix

Type:

numpy.ndarray[numpy.float64[m, n]]

class EstimationOutput

Bases: CovarianceAnalysisOutput

Class collecting all outputs from the iterative estimation process.

property best_iteration

No documentation found.

property exception_during_inversion

No documentation found.

property exception_during_propagation

No documentation found.

property final_parameters

No documentation found.

property final_residuals

read-only

Vector of post-fit observation residuals, for the iteration with the lowest rms residuals.

Type:

numpy.ndarray[numpy.float64[m, 1]]

property parameter_history

read-only

Parameter vectors, concatenated per iteration into a matrix. Column 0 contains pre-estimation values. The \((i+1)^{th}\) column has the residuals from the \(i^{th}\) iteration.

Type:

numpy.ndarray[numpy.float64[m, n]]

property residual_history

read-only

Residual vectors, concatenated per iteration into a matrix; the \(i^{th}\) column has the residuals from the \(i^{th}\) iteration.

Type:

numpy.ndarray[numpy.float64[m, n]]

property simulation_results_per_iteration

read-only

List of complete numerical propagation results, with the \(i^{th}\) entry of thee list thee results of the \(i^{th}\) propagation

Type:

list[SimulationResults]

class Estimator

Bases: pybind11_object

Class for consolidating all estimation functionality.

Class for consolidating all functionality required to perform an estimation.

__init__(self: tudatpy.kernel.estimation.estimation_analysis.Estimator, bodies: tudatpy.kernel.dynamics.environment.SystemOfBodies, estimated_parameters: tudatpy.kernel.dynamics.parameters.EstimatableParameterSet, observation_settings: list[tudatpy.kernel.estimation.observable_models_setup.model_settings.ObservationModelSettings], propagator_settings: tudatpy.kernel.dynamics.propagation_setup.propagator.PropagatorSettings, integrate_on_creation: bool = True) → None

Class constructor.

Constructor through which the user can create instances of this class. Defines environment, propagation and integrations models, as well as a number of settings related to the estimatable parameters and observation settings.

Note

When using default settings, creating an object of this type automatically triggers the propagation

Parameters:

  • bodies (SystemOfBodies) – Object defining the physical environment, with all properties of artificial and natural bodies.

  • estimated_parameters (EstimatableParameterSet) – Object defining a consolidated set of estimatable parameters, linked to the environment and acceleration settings of the simulation.

  • observation_settings (ObservationModelSettings) – List of settings objects, each object defining the observation model settings for one combination of observable and link geometry that is to be simulated.

  • integrator_settings (IntegratorSettings) – Settings to create the numerical integrator that is to be used for the integration of the equations of motion

  • propagator_settings (PropagatorSettings) – Settings to create the propagator that is to be used for the propagation of dynamics

  • integrate_on_creation (bool, default = True) – Boolean defining whether the propagation should be performed immediately (default), or at a later time (when calling the perform_estimation() member function.

compute_covariance(self: tudatpy.kernel.estimation.estimation_analysis.Estimator, covariance_analysis_input: tudat::simulation_setup::CovarianceAnalysisInput<double, tudat: :Time>) → tudat::simulation_setup::CovarianceAnalysisOutput<double, tudat::Time>

Function to perform a covariance analysis for the given observations and parameters

Function to perform a covariance analysis for the given observations and parameters. The observations (which include weights, see TODO) are provided through the covariance_analysis_input input and inverse a priori covariance \((\mathbf{P}_{0})^{-1}\). Calling this function uses the environment and propagator settings provided to the constructor of this class to simulate the dynamics of any relevant bodies for the observations (and associated variational equations for the estimated parameters and states \(\mathbf{p}\)). The observations :math:mathbf{h}` are then computed using the observation models created by the settings provided to the constructor of this Estimator class, as is the associated design matrix \(\mathbf{H}(=\frac{\partial\mathbf{h}}{\mathbf{p}})\). This function then produces the covariance \(\mathbf{P}\) (internally using the normalized partials and covariance for stability, see CovarianceAnalysisOutput for details)

\[\mathbf{P}=\left(\mathbf{H}^{T}\mathbf{W}\mathbf{H}+(\mathbf{P}_{0})^{-1}\right)^{-1}\]

In the presence of consider parameters, an additional term \(\Delta\mathbf{P}_{c}\) is computed that denotes the contribution of the consider covariance to the parameter uncertainties, which is computed from the above as:

\[\Delta \mathbf{P}^{c} = \left(\mathbf{P}\mathbf{H}^{T}\mathbf{W}\right)\left(\mathbf{H}_{c}\mathbf{C}\mathbf{H}_{c}^{T}\right)\left(\mathbf{P}\mathbf{H}^{T}\mathbf{W}\right)^{T} \mathbf{P}^{c}=\mathbf{P}+ \Delta \mathbf{P}^{c}\]

where \(\mathbf{H}_{c}\) is the design matrix for the consider parameters.

Note that, although the actual observations are formally not required for a covariance analysis, all additional data (e.g. observation time, type, link ends, etc.) are. And, as such, the covariance_analysis_input does require the full set of observations and associated information, for consistency purposes (e.g., same input as perform_estimation function) .

To propagate the covariance of the initial states obtained from this function to other epochs, use the propagate_covariance() function

Parameters:

covariance_analysis_input (CovarianceAnalysisInput) – Object consolidating all relevant settings for the covariance analysis This includes foremost the simulated observations, as well as a priori information about the estimatable parameters

Returns:

Object containing all outputs from the estimation process.

Return type:

CovarianceAnalysisOutput

perform_estimation(self: tudatpy.kernel.estimation.estimation_analysis.Estimator, estimation_input: tudat::simulation_setup::EstimationInput<double, tudat: :Time>) → tudat::simulation_setup::EstimationOutput<double, tudat::Time>

Function to trigger the parameter estimation.

Function to trigger the parameter estimation. Part the process and requirements are similar to those described in the compute_covariance function.

The estimation performs an iterative differential correction of the estimated parameters, where for iteration \(i\) a correction to the parameter vector \(\mathbf{p}\) is computed according to:

\[\begin{split}\Delta\mathbf{p}_{i}&=\mathbf{P}_{i}\left(\mathbf{H}_{i}\mathbf{W}\Delta\mathbf{z}_{i}\right)\\ \mathbf{p}_{i+1}&=\mathbf{p}_{i}+\Delta\mathbf{p}_{i}\end{split}\]

where \(\mathbf{P}\) is the covariance (see previous section; where using consider parameters, we have \(\mathbf{P}\rightarrow\mathbf{P}^{c}\) in the above), and \(\Delta\mathbf{z}_{i}\) is the observation residual at iteration \(i\), computed from:

\[\Delta\mathbf{z}_{i} = \mathbf{z} - \mathbf{h}(\mathbf{p}_{i})\]

with \(\mathbf{z}\) the vector of all observations provided as input to the data (observed data) and \(\mathbf{h}(\mathbf{p}_{i})\) the vector of all observations, as computed from the current estimate of the parameters (computed data). The above procedure is performed iteratively, until convergence has been reached.

The results of the estimation are stored in an EstimationOutput object (which by default contains the results from the iteration where the residual was lowest), with two key quantities being:

  • The residual vector of the iteration that had the lowest residual, from the final_residuals attribute of the EstimationOutput class

  • The values of the parameters at the iteration that had the lowest residual, from the final_parameters attribute of the EstimationOutput class

After the estimation is finished, the properties of both the environment (in the bodies) and the estimated parameters (in the parameters_to_estimate) are modified as follows:

  • The ephemerides of all propagated/estimated bodies will be set to the propagation results of the last iteration in the estimation. For instance, when estimating the state of body “Delfi-C3”, the (tabulated) ephemeris of this body will be set to contain the numerical results of the last iteration of the estimation

  • The values of the parameter values in the parameters_to_estimate object are those of the last iteration of the estimation. Note that, if the apply_final_parameter_correction parameter to the EstimationInput is set to True, the parameter correction computed at the end of the last iteration (for which the performance has not been computed) has been used to update the parameters vector

Parameters:

estimation_input (EstimationInput) – Object consolidating all relevant settings for the estimation This includes foremost the simulated observations, as well as a priori information about the estimatable parameters and convergence criteria for the least squares estimation.

Returns:

Object containing all outputs from the estimation process.

Return type:

EstimationOutput

property observation_managers

read-only

Observation managers contained in the Estimator object. A single observation manager can simulate observations and calculate observation partials for all link ends involved in the given observable type.

Type:

dict[ ObservableType, ObservationManager ]

property observation_simulators

read-only

Observation simulators contained in the Estimator object. A single observation simulator hosts the functionality for simulating a given observable over the defined link geometry.

Type:

list[ ObservationSimulator ]

property state_transition_interface

read-only

State transition and sensitivity matrix interface, in which the numerical solution of the variational equations is stored/updated

Type:

CombinedStateTransitionAndSensitivityMatrixInterface

property variational_solver

read-only

Variational equations solver, which is used to manage and execute the numerical integration of equations of motion and variational equations/dynamics in the Estimator object.

Type:

SingleArcVariationalSimulator

class EstimationConvergenceChecker

Bases: pybind11_object

Class defining the convergence criteria for an estimation.

Class defining the convergence criteria for an estimation. The user typically creates instances of this class via the estimation_convergence_checker() function.