`Covariance Matrix`#

class CovarianceMatrix(row_list: list[list], epoch: int, frame: str = 'J2000', from_list: bool = False, corr_factors: list | None = None, extra_apriori_sigmas: dict[str, ArrayWUnits] | None = None, definition=None)#

Bases: UncertaintyQuantification

Covariance matrix for uncertainty quantification in orbit determination.

The covariance matrix \(P\) is the central object describing the uncertainty of the estimated state vector \(\mathbf{x} \in \mathbb{R}^n\). It is defined as the expected outer product of the estimation error \(\boldsymbol{\epsilon} = \mathbf{x} - \hat{\mathbf{x}}\):

\[\begin{split}P = E\!\left[\boldsymbol{\epsilon}\,\boldsymbol{\epsilon}^T\right] = \begin{bmatrix} \sigma_1^2 & P_{12} & \cdots & P_{1n} \\ P_{21} & \sigma_2^2 & \cdots & P_{2n} \\ \vdots & \vdots & \ddots & \vdots \\ P_{n1} & P_{n2} & \cdots & \sigma_n^2 \end{bmatrix}\end{split}\]

where \(\sigma_i = \sqrt{P_{ii}}\) is the standard deviation of the \(i\)-th state component and \(P_{ij}\) is the covariance between components \(i\) and \(j\).

Fundamental properties

Symmetry: \(P = P^T\), i.e. \(P_{ij} = P_{ji}\).
Positive semi-definiteness: \(\mathbf{v}^T P \mathbf{v} \geq 0\) for all \(\mathbf{v} \in \mathbb{R}^n\).
Correlation coefficient: the normalised off-diagonal element is

\[\rho_{ij} = \frac{P_{ij}}{\sigma_i \sigma_j}, \qquad \rho_{ij} \in [-1, 1]\]

Role in the OD filter

In the batch least-squares and sequential filters implemented in Scarabaeus, \(P\) is propagated and updated according to:

Propagation (time update):

\[P^- = \Phi\, P^+\, \Phi^T + Q\]

where \(\Phi\) is the state-transition matrix (STM) and \(Q\) is the process-noise covariance.
Measurement update (information filter form):

\[P^+ = \left(P^{-\,-1} + H^T R^{-1} H\right)^{-1}\]

where \(H\) is the measurement sensitivity (partial-derivative) matrix and \(R\) is the measurement noise covariance.
Batch least-squares normal equations:

\[P = \left(\Lambda_0^{-1} + \sum_k H_k^T R_k^{-1} H_k\right)^{-1}\]

where \(\Lambda_0\) is the a-priori information matrix.

Construction paths

Parameters:

row_list (list[list]) – Full matrix data (list of rows) when from_list=False, or flat list of standard deviations \([\sigma_1, \ldots, \sigma_n]\) when from_list=True.
epoch (int) – J2000 ephemeris time (ET seconds) tagging this covariance.
frame (str, optional) – Reference frame in which the position/velocity components of \(P\) are expressed. Defaults to 'J2000'.
from_list (bool, optional) – If True, build a diagonal (or correlated) covariance from row_list treated as a sigma list. Defaults to False.
corr_factors (list, optional) – Upper-triangular correlation coefficients \(\rho_{ij}\) packed row-by-row (length \(n(n-1)/2\)). Only used when from_list=True. Defaults to None (identity correlation, i.e. diagonal \(P\)).
extra_apriori_sigmas (dict[str, ArrayWUnits], optional) – Additional a-priori standard deviations for parameters that enter in multi-arc / sequence scenarios but are not part of the current arc state. Keys are parameter names. Defaults to None.
definition (optional) – State or sequence definition object. Defaults to None.

Raises:

ValueError – If any value in extra_apriori_sigmas is not an ArrayWUnits.

Attributes:

definition: The sequence or state definition.
epoch: The epoch of the uncertainty representation.
frame: The reference frame of the uncertainty representation.
matrix: The covariance matrix as a list of lists.

Methods

`covariance_matrix_from_list`(sigmas, corr_matrix)	DEPRECATED: Use _build_from_diagonal instead.
`get_standard_deviations`()	Return the 1-sigma uncertainties of each state component.
`matrix_without_units`()	Extract values from the covariance matrix without units.
`reinitialize_with_matrix`(new_matrix[, ...])	Return a new `CovarianceMatrix` with updated numerical values.
`to_array`()	Convert covariance matrix to numpy array without units.
`vector_to_correlation_matrix`(diag_cov, ...)	DEPRECATED: Use _build_correlation_matrix instead.

covariance_matrix_from_list(sigmas: list[ArrayWUnits], corr_matrix: ndarray) → None#

DEPRECATED: Use _build_from_diagonal instead.

Constructs covariance matrix from diagonal elements and correlation matrix.

get_standard_deviations() → ndarray#

Return the 1-sigma uncertainties of each state component.

The standard deviation of the \(i\)-th component is the square root of the corresponding diagonal element:

\[\sigma_i = \sqrt{P_{ii}}, \qquad i = 1, \ldots, n\]

These values are the formal uncertainties (1-sigma) reported by the filter and are commonly used for residual editing and solution assessment.

Returns:: 1-D array of length \(n\) containing \(\sigma_i\).
Return type:: np.ndarray

matrix_without_units() → ndarray#

Extract values from the covariance matrix without units.

Returns:: The covariance matrix as a numpy array without units.
Return type:: np.ndarray

reinitialize_with_matrix(new_matrix: ndarray, new_epoch: float | None = None, new_frame: str | None = None) → Self#

Return a new CovarianceMatrix with updated numerical values.

This is the standard way to create the updated covariance after a filter step. Given the current (prior) covariance \(P^-\) and the numerically computed updated array \(\tilde{P}^+\), the typical call pattern is:

P_plus = P_minus.reinitialize_with_matrix(P_plus_array, new_epoch=t_k)

The unit metadata stored in the original matrix is re-attached to the new values wherever the sizes match; elements that fall outside the old size receive None units.

Parameters:

new_matrix (np.ndarray) – Square \(n \times n\) array of updated covariance values. Must satisfy \(n > 0\) and new_matrix.shape[0] == new_matrix.shape[1].
new_epoch (float, optional) – Ephemeris time (ET seconds) of the updated covariance. If None, the current epoch is preserved.
new_frame (str, optional) – Reference frame of the updated covariance. If None, the current frame is preserved.

Returns:

A new instance carrying new_matrix with inherited units.

Return type:

CovarianceMatrix

Raises:

ValueError – If new_matrix is not a numpy.ndarray or is not square.

to_array() → ndarray#

Convert covariance matrix to numpy array without units.

Returns:: The covariance matrix as a numpy array without units.
Return type:: np.ndarray

vector_to_correlation_matrix(diag_cov: list, upper_tri_vec: list) → ndarray#

DEPRECATED: Use _build_correlation_matrix instead.

Converts vectors into a correlation matrix.

property definition#: The sequence or state definition.

property epoch: int#: The epoch of the uncertainty representation.

property frame: str#: The reference frame of the uncertainty representation.

property matrix: list[list[ArrayWUnits]]#: The covariance matrix as a list of lists.

Covariance Matrix#

`Covariance Matrix`#