estimation#

This module contains the functionality for managing the inputs and outputs of an estimation.

Functions#

simulate_observations(simulation_settings, ...)

Function to simulate observations.

compute_target_angles_and_range(bodies, ...)

Function to compute the azimuth angle, elevation angle and range at a ground station.

propagate_covariance(initial_covariance, ...)

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.
simulate_observations(simulation_settings: List[tudat::simulation_setup::ObservationSimulationSettings<double>], observation_simulators: List[tudatpy.kernel.numerical_simulation.estimation.ObservationSimulator], bodies: tudatpy.kernel.numerical_simulation.environment.SystemOfBodies) → tudat::observation_models::ObservationCollection<double, double, 0>#

Function to simulate observations.

Function to simulate observations from set observation simulators and observation simulator settings. Automatically iterates over all provided observation simulators, generating the full set of simulated observations.

Parameters

  • observation_to_simulate (List[ ObservationSimulationSettings ]) – List of settings objects, each object providing the observation time settings for simulating one type of observable and link end set.

  • observation_simulators (List[ ObservationSimulator ]) – List of ObservationSimulator objects, each object hosting the functionality for simulating one type of observable and link end set.

  • bodies (SystemOfBodies) – Object consolidating all bodies and environment models, including ground station models, that constitute the physical environment.

Returns

Object collecting all products of the observation simulation.

Return type

ObservationCollection

compute_target_angles_and_range(bodies: tudatpy.kernel.numerical_simulation.environment.SystemOfBodies, station_id: Tuple[str, str], target_body: str, observation_times: List[float], is_station_transmitting: bool) → Dict[float, numpy.ndarray[numpy.float64[m, 1]]]#

Function to compute the azimuth angle, elevation angle and range at a ground station.

Function to compute the azimuth angle, elevation angle and range at a ground station. This functions is provided as a function of convenience, to prevent users having to manually define the relevant settings for this often-needed functionality. This function takes an observing station and a target body as input, and provides the observed angles and current range (without correction for aberrations, with correction for light time) as observed at that station

Parameters

  • bodies (SystemOfBodies) – System of bodies that defines the full physical environment

  • station_id (tuple[ str, str]) – Identifier for the observing station, as a pair of strings: the body name and the station name.

  • target_body (str) – Name of body which is observed by ground station

  • observation_times (list[float]) – List of times at which the ground station observations are to be analyzed

  • is_station_transmitting (Bool) – Boolean defining whether the observation times define times at which the station is transmitting to, or receiving from, the ground station. This has an impact on the whether the light-time is computed forward or backward in time from the ground station to the target

Returns

Dictionary with the required output. Key defines the observation time, the value is an array of size three containing entry 0 - elevation angle, entry 1 - azimuth angle, entry 2 - range

Return type

dict[float,numpy.ndarray[numpy.float64[3, 1]]]

propagate_covariance(initial_covariance: numpy.ndarray[numpy.float64[m, n]], state_transition_interface: tudatpy.kernel.numerical_simulation.estimation.CombinedStateTransitionAndSensitivityMatrixInterface, output_times: List[float]) → 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 system dynamics and numerical settings of the propagation are prescribed by the state_transition_interface parameter.

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.

  • output_times (List[ float ]) – Times at which the propagated covariance matrix shall be reported. Note that this argument has no impact on the integration time-steps of the covariance propagation, which always adheres to the integrator settings that the state_transition_interface links to. 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[ float, numpy.ndarray[numpy.float64[m, n]] ]

propagate_formal_errors(initial_covariance: numpy.ndarray[numpy.float64[m, n]], state_transition_interface: tudatpy.kernel.numerical_simulation.estimation.CombinedStateTransitionAndSensitivityMatrixInterface, output_times: List[float]) → Dict[float, numpy.ndarray[numpy.float64[m, 1]]]#

Function to propagate system formal errors through time.

Function to propagate the formal errors of a given system through time. Note that in practice the entire covariance matrix is propagated, but only the formal errors (variances) are reported at the output times. The system dynamics and numerical settings of the propagation are prescribed by the state_transition_interface parameter.

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.

  • output_times (List[ float ]) – Times at which the propagated covariance matrix shall be reported. Note that this argument has no impact on the integration time-steps of the covariance propagation, which always adheres to the integrator settings that the state_transition_interface links to. 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[ float, numpy.ndarray[numpy.float64[m, 1]] ]

estimation_convergence_checker(maximum_iterations: int = 5, minimum_residual_change: float = 0.0, minimum_residual: float = 0.0, number_of_iterations_without_improvement: int = 2) → tudatpy.kernel.numerical_simulation.estimation.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

Classes#

EstimatableParameterSet

Class containing a consolidated set of estimatable parameters.

ObservationViabilityCalculator

Template class for observation viability calculators.

ObservationSimulator

Class hosting the functionality for simulating observations.

ObservationCollection

Class collecting all products of the observation simulation.

CombinedStateTransitionAndSensitivityMatrixInterface

Class establishing an interface with the simulation's State Transition and Sensitivity Matrices.

EstimationConvergenceChecker

Class defining the convergence criteria for an estimation.

PodInput

Class for consolidating all inputs to the estimation.

PodOutput

Class collecting all outputs from the estimation process.
class EstimatableParameterSet#

Class containing a consolidated set of estimatable parameters.

Class containing a consolidated set of estimatable parameters, linked to the environment and acceleration settings of the simulation. The user typically creates instances of this class via the create_parameters_to_estimate() factory function.

indices_for_parameter_type(self: tudatpy.kernel.numerical_simulation.estimation.EstimatableParameterSet, parameter_type: Tuple[tudat::estimatable_parameters::EstimatebleParametersEnum, Tuple[str, str]]) → List[Tuple[int, int]]#

Function to retrieve the indices of a given type of parameter.

Function to retrieve the index of all parameters of a given type from the parameter set. This function can be very useful, since the order of parameters within the parameter set does not necessarily correspond to the order in which the elements were added to the set.

Parameters

parameter_type (Tuple[ EstimatableParameterTypes, Tuple[str, str] ]) – help

Returns

help

Return type

List[ Tuple[int, int] ]

property constraints_size#

read-only

Total size of linear constraint that is to be applied during estimation.

Type

int

property initial_multi_arc_states_size#

read-only

Amount of initial state parameters in the set, which are treated in a multi-arc fashion.

Type

int

property initial_single_arc_states_size#

read-only

Amount of initial state parameters in the set, which are treated in a single-arc fashion.

Type

int

property initial_states_size#

read-only

Amount of initial state parameters contained in the set.

Type

int

property parameter_set_size#

read-only

Size of the parameter set, i.e. amount of estimatable parameters contained in the set.

Type

int

property parameter_vector#

Vector containing the parameter values of all parameters in the set.

Type

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

class ObservationViabilityCalculator#

Template class for observation viability calculators.

Template class for classes which conducts viability calculations on simulated observations. Instances of the applicable ObservationViabilityCalculators are automatically created from the given ObservationSimulationSettings objects during the simulation of observations (simulate_observations()). The user typically does not interact directly with this class.

is_observation_viable(self: tudatpy.kernel.numerical_simulation.estimation.ObservationViabilityCalculator, link_end_states: List[numpy.ndarray[numpy.float64[6, 1]]], link_end_times: List[float]) → bool#

Function to check whether an observation is viable.

Function to check whether an observation is viable. The calculation is performed based on the given times and link end states. Note, that this function is called automatically during the simulation of observations. Direct calls to this function are generally not required.

Parameters

  • link_end_states (List[ numpy.ndarray[numpy.float64[6, 1]] ]) – Vector of states of the link ends involved in the observation.

  • link_end_times (List[float]) – Vector of times at the link ends involved in the observation.

Returns

True if observation is viable, false if not.

Return type

bool

class ObservationSimulator#

Class hosting the functionality for simulating observations.

Class hosting the functionality for simulating a given observable over a defined link geometry. Instances of this class are automatically created from the given ObservationSettings objects upon instantiation of the Estimator class.

class ObservationCollection#

Class collecting all products of the observation simulation.

Class containing all products of the observation simulation. This class is instantiated via a call to the simulate_observations() function.

property concatenated_observations#

read-only

Vector containing concatenated observation times. Concatenation takes place over the observations of all observables.

Type

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

property concatenated_times#

read-only

Vector containing concatenated observation times. Concatenation takes place over the observation times of all observables.

Type

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

class CombinedStateTransitionAndSensitivityMatrixInterface#

Class establishing an interface with the simulation’s State Transition and Sensitivity Matrices.

Class establishing an interface to the State Transition and Sensitivity Matrices. Instances of this class are instantiated automatically upon creation of Estimator objects, using the simulation information in the observation, propagation and integration settings that the Estimator instance is linked to.

full_state_transition_sensitivity_at_epoch(self: tudatpy.kernel.numerical_simulation.estimation.CombinedStateTransitionAndSensitivityMatrixInterface, time: float) → numpy.ndarray[numpy.float64[m, n]]#
Parameters

time (float) – Time at which full concatenated state transition and sensitivity matrix are to be retrieved.

Returns

Full concatenated state transition and sensitivity matrix at a given time.

Return type

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

state_transition_sensitivity_at_epoch(self: tudatpy.kernel.numerical_simulation.estimation.CombinedStateTransitionAndSensitivityMatrixInterface, time: float) → numpy.ndarray[numpy.float64[m, n]]#

Function to get the concatenated state transition and sensitivity matrix at a given time.

Function to get the concatenated state transition and sensitivity matrix at a given time. Entries corresponding to parameters which are not active at the current arc are omitted.

Parameters

time (float) – Time at which concatenated state transition and sensitivity matrix are to be retrieved.

Returns

Concatenated state transition and sensitivity matrix at a given time.

Return type

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

property full_parameter_size#

read-only

Full amount of parameters w.r.t. which partials have been set up via State Transition and Sensitivity Matrices.

Type

int

property sensitivity_size#

read-only

Number of columns in the sensitivity matrix.

Type

int

property state_transition_size#

read-only

Size of the (square) state transition matrix.

Type

int

class EstimationConvergenceChecker#

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() factory function.

class PodInput#

Class for consolidating all inputs to the estimation.

__init__(self: tudatpy.kernel.numerical_simulation.estimation.PodInput, observations_and_times: tudatpy.kernel.numerical_simulation.estimation.ObservationCollection, parameter_size: int, inverse_apriori_covariance: numpy.ndarray[numpy.float64[m, n]] = array([], shape=(0, 0), dtype=float64), apriori_parameter_correction: numpy.ndarray[numpy.float64[m, 1]] = array([], dtype=float64)) → 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.

  • parameter_size (int) – Size of vector of estimated parameters.

  • inverse_apriori_covariance (numpy.ndarray[numpy.float64[m, n]], default = [ ]) – A priori covariance matrix (unnormalized) of estimated parameters.

  • apriori_parameter_correction (numpy.ndarray[numpy.float64[m, 1]], default = [ ]) – Correction to estimated parameter vector to be applied on first iteration.

Returns

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

Return type

PodInput

define_estimation_settings(self: tudatpy.kernel.numerical_simulation.estimation.PodInput, 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) → None#

Function to define specific settings for estimation process

Function to define specific settings for estimation process

Parameters

  • reintegrate_equations_on_first_iteration (bool, default = True) – Boolean denoting whether the dynamics and variational equations are to be reintegrated on first iteration, 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.

  • save_design_matrix (bool, default = True) – Boolean denoting whether to save the partials matrix in the output.

  • print_output_to_terminal (bool, default = True) – Boolean denoting whether to print output to th 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 is to be saved on each iteration.

Returns

Function modifies the object in-place.

Return type

None

set_constant_weight(self: tudatpy.kernel.numerical_simulation.estimation.PodInput, weight: float) → None#

Function to set a constant weight matrix for all observables.

Function to set a constant weight matrix for all observables. The weights are applied to all observations managed by the given PodInput object.

Parameters

constant_weight (float) – Constant weight factor that is to be applied to all observations.

Returns

Function modifies the object in-place.

Return type

None

set_constant_weight_per_observable(self: tudatpy.kernel.numerical_simulation.estimation.PodInput, weight_per_observable: Dict[tudat::observation_models::ObservableType, float]) → None#

Function to set a constant weight matrix for a given type of observable.

Function to set a constant weight matrix for a given type of observable. The weights are applied to all observations of the observable type specified by the weight_per_observable parameter.

Parameters

constant_weight (Dict[ ObservableType, float ]) – Constant weight factor that is to be applied to all observations.

Returns

Function modifies the object in-place.

Return type

None

class PodOutput#

Class collecting all outputs from the estimation process.

property correlations#

read-only

Correlation matrix of the estimation result.

Type

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

property covariance#

read-only

(Unnormalized) estimation covariance matrix.

Type

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

property design_matrix#

read-only

Matrix of unnormalized partial derivatives.

Type

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

property final_residuals#

read-only

Vector of post-fit observation residuals.

Type

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

property formal_errors#

read-only

Formal error vector of the estimation result. Correlation matrix of the estimation result.

Type

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

property inverse_covariance#

read-only

(Unnormalized) inverse estimation covariance matrix.

Type

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

property normalization_terms#

No documentation found.

property normalized_design_matrix#

read-only

Matrix of partial derivatives.

Type

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

property parameter_history#

read-only

Parameter vectors, concatenated per iteration into a matrix. Column 0 contains pre-estimation values.

Type

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

property residual_history#

read-only

Residual vectors, concatenated per iteration into a matrix.

Type

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

property weighted_design_matrix#

read-only

Matrix of weighted partial derivatives.

Type

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

property weighted_normalized_design_matrix#

read-only

Matrix of weighted, normalized partial derivatives.

Type

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