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.

full_state_continuity(bodies, epochs, ...[, ...])

Build full translational-state continuity settings.

position_only_continuity(bodies, epochs, ...)

Build position-only continuity settings.

velocity_only_continuity(bodies, epochs, ...)

Build velocity-only continuity settings.

general_continuity(bodies, epochs, ...[, ...])

Build continuity settings from general Cartesian-state weight matrices.
propagate_covariance(initial_covariance: numpy.ndarray[numpy.float64[m, n]], state_transition_interface: tudatpy.kernel.dynamics.simulator.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 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[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 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[float, 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]) → 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:

  • analysis_output (CovarianceAnalysisOutput) – Object storing all results of a covariance analysis (using compute_covariance()) or estimation (using perform_estimation())

  • 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[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.dynamics.simulator.CombinedStateTransitionAndSensitivityMatrixInterface, output_times: list[float]) → 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[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 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[float, numpy.ndarray[numpy.float64[m, 1]]]

estimation_convergence_checker(maximum_iterations: int = 5, minimum_residual_change: float = 0.0, minimum_residual: float = 1e-20, number_of_iterations_without_improvement: int = 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 = 1.0e-20) – 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[tuple[tuple[EstimatableParameterTypes, tuple[str, str]], numpy.ndarray]]) – 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[tuple[tuple[EstimatableParameterTypes, tuple[str, str]], numpy.ndarray]]) – 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 = 3, reintegrate_variational_equations: bool = True, results_print_frequency: float = 0.0) → tudatpy.kernel.estimation.estimation_analysis.EstimationOutput

No documentation found.

full_state_continuity(bodies: list[str], epochs: dict[str, list[float]], position_weights: dict[str, float | numpy.ndarray[numpy.float64[m, 1]]], velocity_weights: dict[str, float | numpy.ndarray[numpy.float64[m, 1]]], constraint_scaling_factor: float = 1.0, arc_pairs: dict[str, list[tuple[int, int]]] = {}) → tudatpy.kernel.estimation.estimation_analysis.InterArcStateContinuityConstraintSettings

Build full translational-state continuity settings.

The position and velocity entries form the diagonal blocks of \(\mathbf{C}_{bk}\) defined by InterArcStateContinuityConstraintSettings. One matrix is broadcast to every connection epoch of a body.

Parameters:

  • bodies (list[str]) – Bodies whose position and velocity jumps are constrained.

  • epochs (dict[str, list[float]]) – Connection epochs \(t_{c,bk}\) for each body, in seconds since J2000.

  • position_weights (dict[str, float | numpy.ndarray]) – Isotropic scalar or three Cartesian diagonal position weights for each body.

  • velocity_weights (dict[str, float | numpy.ndarray]) – Isotropic scalar or three Cartesian diagonal velocity weights for each body.

  • constraint_scaling_factor (float, default = 1.0) – Positive factor \(\mu_s\); larger values weaken the constraint.

  • arc_pairs (dict[str, list[tuple[int, int]]], optional) – Zero-based consecutive arc pairs. If omitted, epoch entry \(k\) connects arcs \(k\) and \(k+1\).

Returns:

Settings containing the resulting full-state weight matrices.

Return type:

InterArcStateContinuityConstraintSettings

position_only_continuity(bodies: list[str], epochs: dict[str, list[float]], position_weights: dict[str, float | numpy.ndarray[numpy.float64[m, 1]]], constraint_scaling_factor: float = 1.0, arc_pairs: dict[str, list[tuple[int, int]]] = {}) → tudatpy.kernel.estimation.estimation_analysis.InterArcStateContinuityConstraintSettings

Build position-only continuity settings.

This constructs \(\mathbf{C}_{bk}\) with the velocity block set to zero, leaving inter-arc velocity jumps unconstrained. See InterArcStateContinuityConstraintSettings for the mathematical model.

Parameters:

  • bodies (list[str]) – Bodies whose position jumps are constrained.

  • epochs (dict[str, list[float]]) – Connection epochs \(t_{c,bk}\) for each body, in seconds since J2000.

  • position_weights (dict[str, float | numpy.ndarray]) – Isotropic scalar or three Cartesian diagonal position weights for each body.

  • constraint_scaling_factor (float, default = 1.0) – Positive factor \(\mu_s\); larger values weaken the constraint.

  • arc_pairs (dict[str, list[tuple[int, int]]], optional) – Zero-based consecutive arc pairs; inferred from epoch order when omitted.

Returns:

Settings containing position-only weight matrices.

Return type:

InterArcStateContinuityConstraintSettings

velocity_only_continuity(bodies: list[str], epochs: dict[str, list[float]], velocity_weights: dict[str, float | numpy.ndarray[numpy.float64[m, 1]]], constraint_scaling_factor: float = 1.0, arc_pairs: dict[str, list[tuple[int, int]]] = {}) → tudatpy.kernel.estimation.estimation_analysis.InterArcStateContinuityConstraintSettings

Build velocity-only continuity settings.

This constructs \(\mathbf{C}_{bk}\) with the position block set to zero, leaving inter-arc position jumps unconstrained. See InterArcStateContinuityConstraintSettings for the mathematical model.

Parameters:

  • bodies (list[str]) – Bodies whose velocity jumps are constrained.

  • epochs (dict[str, list[float]]) – Connection epochs \(t_{c,bk}\) for each body, in seconds since J2000.

  • velocity_weights (dict[str, float | numpy.ndarray]) – Isotropic scalar or three Cartesian diagonal velocity weights for each body.

  • constraint_scaling_factor (float, default = 1.0) – Positive factor \(\mu_s\); larger values weaken the constraint.

  • arc_pairs (dict[str, list[tuple[int, int]]], optional) – Zero-based consecutive arc pairs; inferred from epoch order when omitted.

Returns:

Settings containing velocity-only weight matrices.

Return type:

InterArcStateContinuityConstraintSettings

general_continuity(bodies: list[str], epochs: dict[str, list[float]], weight_matrices: dict[str, numpy.ndarray[numpy.float64[m, n]] | list[numpy.ndarray[numpy.float64[m, n]]]], constraint_scaling_factor: float = 1.0, arc_pairs: dict[str, list[tuple[int, int]]] = {}) → tudatpy.kernel.estimation.estimation_analysis.InterArcStateContinuityConstraintSettings

Build continuity settings from general Cartesian-state weight matrices.

See InterArcStateContinuityConstraintSettings for the definition of \(\mathbf{C}_{bk}\) and the complete mathematical model.

Parameters:

  • bodies (list[str]) – Bodies whose Cartesian-state jumps are constrained.

  • epochs (dict[str, list[float]]) – Connection epochs \(t_{c,bk}\) for each body, in seconds since J2000.

  • weight_matrices (dict[str, numpy.ndarray[float, 6, 6] | list[numpy.ndarray[float, 6, 6]]]) – Symmetric positive semi-definite matrices \(\mathbf{C}_{bk}\). One matrix is broadcast to all epochs of its body; otherwise supply one matrix per epoch.

  • constraint_scaling_factor (float, default = 1.0) – Positive factor \(\mu_s\); larger values weaken the constraint.

  • arc_pairs (dict[str, list[tuple[int, int]]], optional) – Zero-based consecutive arc pairs; inferred from epoch order when omitted.

Returns:

Settings containing the supplied general weight matrices.

Return type:

InterArcStateContinuityConstraintSettings

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.

InterArcStateContinuityConstraintSettings

Soft inter-arc translational state continuity-prior settings for one or more multi-arc bodies.
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 = 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) → 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) → 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]) → None

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

set_inter_arc_continuity_constraints(self: tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisInput, constraints: list[tudat::simulation_setup::InterArcStateContinuityConstraintSettings]) → None

Attach soft inter-arc translational state continuity priors.

The inputs map directly to the discrepancy, weight, cost, and normal-equation model documented by InterArcStateContinuityConstraintSettings. Constraints are currently supported only for pure multi-arc translational estimators. Pass an empty list to disable the feature.

Parameters:

constraints (list[InterArcStateContinuityConstraintSettings]) – Settings defining all constrained bodies, arc pairs, connection epochs, weights, and scaling factors.

Returns:

Modifies this input object in place.

Return type:

None

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 inter_arc_continuity_constraints

read-only

List of currently attached soft inter-arc continuity-prior settings.

Type:

list[InterArcStateContinuityConstraintSettings]

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

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.

This class contains the observations, a-priori information, convergence settings, optional consider parameter information, and optional soft inter-arc continuity constraints used by perform_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.estimation.estimation_analysis.estimation_convergence_checker(), 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.

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

  • consider_parameters_deviations (numpy.ndarray[numpy.float64[n]], default = [ ]) – Deviations of the consider parameters from their nominal values. This should be either a size 0 vector (no consider-parameter deviations), or a vector with the same size as the number of consider parameters.

  • apply_final_parameter_correction (bool, default = True) – Whether to apply the final estimated parameter correction to the simulation models after convergence.

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 = 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

set_inter_arc_continuity_constraints(self: tudatpy.kernel.estimation.estimation_analysis.EstimationInput, constraints: list[tudat::simulation_setup::InterArcStateContinuityConstraintSettings]) → None

Attach soft inter-arc translational state continuity constraints to the estimation input.

The inputs map directly to the discrepancy, weight, cost, and normal-equation model documented by InterArcStateContinuityConstraintSettings. A settings object may constrain one or more bodies. Pass an empty list to disable the feature.

Parameters:

constraints (list[InterArcStateContinuityConstraintSettings]) – Settings defining all constrained bodies, arc pairs, connection epochs, weights, and scaling factors.

Returns:

Modifies this input object in place.

Return type:

None

property inter_arc_continuity_constraints

read-only

List of currently attached inter-arc continuity constraint settings.

Type:

list[InterArcStateContinuityConstraintSettings]

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

  • Optional soft inter-arc continuity-prior diagnostics, when such priors are attached to the input

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.

static load_from_binary(path: str) → tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisOutput

Deserialize this object from binary. Python pickle uses the same serialization schema. Compatibility with other builds is not guaranteed. Only load trusted files.

save_to_binary(self: tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisOutput, path: str) → None

Serialize this object in binary form. Python pickle uses the same serialization schema. Compatibility with other builds is not guaranteed.

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 inter_arc_continuity_cost

read-only

Soft inter-arc continuity cost \(J_d\) at the covariance-analysis linearization point. See InterArcStateContinuityConstraintSettings for its definition and input mapping. This value is zero when no inter-arc continuity constraints were attached.

Type:

float

property inter_arc_continuity_discrepancies

read-only

State discrepancy vectors \(\mathbf{d}_{bk}\) used to assemble the continuity terms in covariance analysis. See InterArcStateContinuityConstraintSettings for their definition and ordering inputs.

Type:

list[numpy.ndarray[numpy.float64[6, 1]]]

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.

static load_from_binary(path: str) → tudatpy.kernel.estimation.estimation_analysis.EstimationOutput

Deserialize this object from binary. Python pickle uses the same serialization schema. Compatibility with other builds is not guaranteed. Only load trusted files.

save_to_binary(self: tudatpy.kernel.estimation.estimation_analysis.EstimationOutput, path: str) → None

Serialize this object in binary form. Python pickle uses the same serialization schema. Compatibility with other builds is not guaranteed.

property best_iteration

read-only

No documentation found.

property exception_during_inversion

read-only

No documentation found.

property exception_during_propagation

read-only

No documentation found.

property final_parameters

read-only

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 inter_arc_continuity_cost_history

read-only

Per-iteration continuity cost \(J_d\). See InterArcStateContinuityConstraintSettings for the mathematical definition. Empty if no continuity constraints were attached to the input.

Type:

list[float]

property inter_arc_continuity_discrepancy_history

read-only

Per-iteration list of state discrepancies at every constrained boundary, computed as the right-arc state minus the left-arc state at the connection epoch. Outer index is iteration, inner index is pair in the order produced by the attached settings. For the current translational-state continuity settings, each discrepancy has six entries.

Type:

list[list[numpy.ndarray[numpy.float64[6, 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 (list[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.

  • 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: tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisInput) → tudatpy.kernel.estimation.estimation_analysis.CovarianceAnalysisOutput

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}\]

If soft inter-arc continuity constraints have been attached to the covariance_analysis_input through set_inter_arc_continuity_constraints(), the covariance is computed from the augmented normalized normal matrix defined by InterArcStateContinuityConstraintSettings. Equivalently, the unnormalized covariance expression includes the sum of continuity information terms:

\[\mathbf{P}=\left(\mathbf{H}^{T}\mathbf{W}\mathbf{H}+(\mathbf{P}_{0})^{-1} +\sum_{b,k}\mathbf{D}_{bk}^{T}\mathbf{W}_{d,bk}\mathbf{D}_{bk}\right)^{-1}.\]

The implementation forms the normalized equivalent of this equation. If no continuity constraints are attached, the added sum is zero.

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: tudatpy.kernel.estimation.estimation_analysis.EstimationInput) → tudatpy.kernel.estimation.estimation_analysis.EstimationOutput

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.

If soft inter-arc continuity constraints have been attached to the estimation_input through set_inter_arc_continuity_constraints(), the least-squares solve uses the augmented normalized normal matrix and right-hand side defined by InterArcStateContinuityConstraintSettings. The iteration selected as best minimizes the implemented total cost

\[J_i=\frac{1}{2}\Delta\mathbf{z}_i^T\mathbf{W}\Delta\mathbf{z}_i+J_{d,i},\]

where \(J_{d,i}\) is the continuity cost defined by that settings class. Observation residual RMS remains observation-only. If no continuity constraints are attached, \(J_{d,i}=0\) and the normal equation is unchanged.

The results of the estimation are stored in an EstimationOutput object (which contains the results from the iteration with the lowest cost defined above), with two key quantities being:

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.

class InterArcStateContinuityConstraintSettings

Bases: pybind11_object

Soft inter-arc translational state continuity-prior settings for one or more multi-arc bodies.

Created via the factory functions full_state_continuity(), position_only_continuity(), velocity_only_continuity(), or general_continuity(). Pass a list of these objects to CovarianceAnalysisInput.set_inter_arc_continuity_constraints() or the inherited EstimationInput.set_inter_arc_continuity_constraints() to attach the feature. The feature is currently supported for pure multi-arc translational estimators only.

For body \(b\) and constrained arc pair \(k=(\ell,r)\) at connection epoch \(t_{c,bk}\), the state discrepancy and its parameter partials are

\[\begin{split}\mathbf{d}_{bk} &= \mathbf{x}_{r,b}(t_{c,bk})-\mathbf{x}_{\ell,b}(t_{c,bk}),\\ \mathbf{D}_{bk} &= \frac{\partial\mathbf{d}_{bk}}{\partial\mathbf{p}} =\mathbf{M}_{r,b}(t_{c,bk})-\mathbf{M}_{\ell,b}(t_{c,bk}),\end{split}\]

where \(\mathbf{M}\) contains the applicable rows of the full state-transition and sensitivity matrix. Let \(\mathbf{C}_{bk}\) be the user-supplied positive semi-definite weight matrix and \(\overline{\mathbf{C}}_{bk}=\tfrac{1}{2}(\mathbf{C}_{bk}+\mathbf{C}_{bk}^{T})\) its symmetric part. This distinction only affects matrices whose asymmetry is within the numerical validation tolerance. With scaling factor \(\mu_s\) for settings object \(s\), \(m\) scalar observations, and

\[m_d=\sum_{b,k}\operatorname{rank}(\overline{\mathbf{C}}_{bk}),\qquad \mathbf{W}_{d,bk}=\frac{m}{\mu_s m_d}\overline{\mathbf{C}}_{bk},\]

the implemented continuity cost is

\[J_d=\frac{1}{2}\sum_{b,k}\mathbf{d}_{bk}^{T}\mathbf{W}_{d,bk}\mathbf{d}_{bk}.\]

This is Eqs. (4) and (28) of Lari et al. (2021), after multiplying the averaged total objective by \(m/2\) to match Tudat’s \(\frac{1}{2}\mathbf{r}^{T}\mathbf{W}\mathbf{r}\) convention. The rank sum generalizes Lari et al.’s \(m_d=6(n-1)\) to component masks and general rank-deficient weights. If \(\mathbf{N}\) contains the observation-design-matrix column normalization factors, \(\widetilde{\mathbf{D}}_{bk}=\mathbf{D}_{bk}\operatorname{diag}(\mathbf{N})^{-1}\). The normal matrix and estimation right-hand side receive

\[\begin{split}\Delta\widetilde{\mathbf{P}}^{-1} &= \sum_{b,k}\widetilde{\mathbf{D}}_{bk}^{T}\mathbf{W}_{d,bk}\widetilde{\mathbf{D}}_{bk},\\ \Delta\widetilde{\mathbf{g}} &=- \sum_{b,k}\widetilde{\mathbf{D}}_{bk}^{T}\mathbf{W}_{d,bk}\mathbf{d}_{bk}.\end{split}\]

bodies selects \(b\); connection_epochs supplies \(t_{c,bk}\); arc_pairs supplies \((\ell,r)\) (or consecutive pairs are inferred); the factory weight arguments construct \(\mathbf{C}_{bk}\); and constraint_scaling_factor is \(\mu_s\). Larger values of \(\mu_s\) weaken the constraint.

bodies

Bodies whose multi-arc translational states are constrained.

Type:

list[str]

connection_epochs

Body-specific connection epochs \(t_{c,bk}\), in seconds since J2000.

Type:

dict[str, list[float]]

constraint_scaling_factor

Positive penalty scaling factor \(\mu_s\).

Type:

float

arc_pairs

Optional body-specific zero-based (left_arc, right_arc) pairs.

Type:

dict[str, list[tuple[int, int]]]