ADCS.covariance module

Covariance storage and common estimator covariance operations.

The public Covariance interface is independent of whether uncertainty is stored as a full matrix or as an upper-triangular square-root factor. This keeps representation details out of estimators and hardware models.

class ADCS.covariance.Covariance(matrix, *, form='full', coordinates='generic', psd_policy='strict')[source]

Bases: object

Own a covariance in full or upper square-root form.

For a local error \(\delta x=x\boxminus\bar x\), covariance is

\[P=\mathbb E\!\left[\delta x\,\delta x^T\right], \qquad P=P^T\succeq0.\]

form="full" stores \(P\) directly. form="sqrt" stores an upper-triangular factor \(S\) satisfying

\[P=S^T S.\]

The same public operations are available in both forms. Inputs and returned matrices are copied, so updates occur only through explicit methods such as assign(). State-space retraction remains the responsibility of State.

Parameters:

  • matrix (Any) – Symmetric positive-semidefinite covariance matrix.

  • form (str) – Internal representation, "full" or "sqrt".

  • coordinates (str) – Descriptive coordinate-space label.

  • psd_policy (str) – Handling for numerically indefinite matrices.

classmethod block_diagonal(blocks, **kwargs)[source]
Parameters:

  • blocks (Iterable[Covariance | Any])

  • kwargs (Any)

Return type:

Covariance

classmethod from_matrix(matrix, **kwargs)[source]

Construct from a covariance matrix.

Parameters:

  • matrix (Any)

  • kwargs (Any)

Return type:

Covariance

classmethod from_upper_factor(factor, *, form='sqrt', coordinates='generic', psd_policy='strict')[source]

Construct from upper \(S\) satisfying \(P=S^T S\).

Parameters:

  • factor (Any)

  • form (str)

  • coordinates (str)

  • psd_policy (str)

Return type:

Covariance

classmethod from_weighted_deviations(deviations, weights, noise=None, **kwargs)[source]

Construct a covariance from weighted local deviations.

For row deviations \(d_i\) and optional additive noise \(Q\),

\[P=\sum_i w_i d_i d_i^T+Q.\]

Non-negative weights in square-root form use a QR factorization of the stacked weighted deviations and the noise factor.

Parameters:

  • deviations (Any)

  • weights (Any)

  • noise (Covariance | Any | None)

  • kwargs (Any)

Return type:

Covariance

classmethod identity(dimension, scale=1.0, **kwargs)[source]
Parameters:

  • dimension (int)

  • scale (float)

  • kwargs (Any)

Return type:

Covariance

classmethod zeros(dimension, **kwargs)[source]
Parameters:

  • dimension (int)

  • kwargs (Any)

Return type:

Covariance

static cross_covariance(first_deviations, second_deviations, weights)[source]

Return weighted cross-covariance.

\[P_{xy}=\sum_i w_i d_i^{x}(d_i^{y})^T.\]
Parameters:

  • first_deviations (Any)

  • second_deviations (Any)

  • weights (Any)

Return type:

ndarray

static weighted_cholupdate(factor, vectors, weight)[source]

Return the upper factor after weighted rank updates/downdates.

factor is an upper-triangular \(S\) with \(P=S^T S\). Each row of vectors contributes weight * v v^T. Negative weights use the in-tree Cholesky downdate primitive.

Parameters:

  • factor (Any)

  • vectors (Any)

  • weight (float)

Return type:

ndarray

added(other)[source]
Parameters:

other (Covariance | Any)

Return type:

Covariance

as_matrix()[source]

Return an owned full covariance matrix.

Return type:

ndarray

assign(matrix)[source]

Atomically replace the covariance while retaining this object’s form.

Parameters:

matrix (Covariance | Any)

Return type:

None

assign_upper_factor(factor)[source]

Atomically replace the covariance from an upper factor.

Parameters:

factor (Any)

Return type:

None

copy(*, form=None, coordinates=None, psd_policy=None)[source]
Parameters:

  • form (str | None)

  • coordinates (str | None)

  • psd_policy (str | None)

Return type:

Covariance

predicted_linear(transition, noise)[source]

Return the linear prediction covariance.

\[P_{k+1}^{-}=F_kP_k^{+}F_k^T+Q_k.\]

In square-root form, \(S_{k+1}^{-}\) is the triangular factor from

\[\begin{split}\begin{bmatrix}S_kF_k^T\\S_Q\end{bmatrix} =\mathcal Q S_{k+1}^{-}, \qquad Q_k=S_Q^TS_Q,\end{split}\]

avoiding explicit construction of \(F_kP_kF_k^T\).

Parameters:
Return type:

Covariance

predicted_unscented(deviations, weights, noise)[source]

Return the unscented prediction covariance.

For propagated sigma points \(x_i^-\) and their manifold mean \(\bar x^-\), callers supply

\[d_i=x_i^-\boxminus\bar x^-, \qquad P^-=\sum_i w_i^{(c)}d_i d_i^T+Q.\]
Parameters:

  • deviations (Any)

  • weights (Any)

  • noise (Covariance | Any)

Return type:

Covariance

rank_updated(vectors, weight=1.0)[source]
Parameters:

  • vectors (Any)

  • weight (float)

Return type:

Covariance

replace_block(indices, block)[source]
Parameters:
Return type:

None

scaled(scale)[source]
Parameters:

scale (float)

Return type:

Covariance

sigma_offsets(scale=1.0)[source]

Return paired positive and negative sigma-point offsets as rows.

With \(P=S^T S\) and scale \(\gamma\), row \(i\) produces

\[\Delta_i^+=\gamma S_{i,:},\qquad \Delta_i^-=-\gamma S_{i,:},\qquad \chi_i^\pm=\bar x\boxplus\Delta_i^\pm.\]

The final retraction is performed by retract(); this method returns only the Euclidean tangent offsets.

Parameters:

scale (float)

Return type:

ndarray

solve(rhs)[source]

Solve \(P X=B\) without exposing the stored representation.

Parameters:

rhs (Any)

Return type:

ndarray

subset(indices, *, coordinates=None)[source]
Parameters:

  • indices (Any)

  • coordinates (str | None)

Return type:

Covariance

transformed(jacobian, *, coordinates=None)[source]

Return \(J P J^T\).

Parameters:

  • jacobian (Any)

  • coordinates (str | None)

Return type:

Covariance

updated_linear(measurement_jacobian, measurement_noise, *, joseph=True)[source]

Return Kalman gain and posterior covariance for a linear update.

With measurement Jacobian \(H\) and noise covariance \(R\),

\[\Sigma=HP^-H^T+R,\qquad K=P^-H^T\Sigma^{-1}.\]

The default Joseph update preserves symmetry and positive semidefiniteness more reliably than direct subtraction:

\[P^+=(I-KH)P^-(I-KH)^T+KRK^T.\]
Parameters:

  • measurement_jacobian (Any)

  • measurement_noise (Covariance | Any)

  • joseph (bool)

Return type:

tuple[ndarray, Covariance]

updated_unscented(state_deviations, measurement_deviations, weights, measurement_noise)[source]

Return gain and posterior from weighted sigma deviations.

\[P_{yy}=\sum_i w_i d_i^y(d_i^y)^T+R,\qquad K=P_{xy}P_{yy}^{-1},\qquad P^+=P^- - KP_{yy}K^T.\]

State and measurement deviations must already be expressed relative to their respective means.

Parameters:

  • state_deviations (Any)

  • measurement_deviations (Any)

  • weights (Any)

  • measurement_noise (Covariance | Any)

Return type:

tuple[ndarray, Covariance]

upper_factor()[source]

Return an owned upper factor \(S\), where \(P=S^T S\).

Return type:

ndarray

zero_cross(first, second)[source]

Set covariance cross terms between two index selections to zero.

Parameters:

  • first (Any)

  • second (Any)

Return type:

None

property coordinates: str
property dimension: int
property form: Literal['full', 'sqrt']
property psd_policy: Literal['strict', 'project', 'jitter', 'allow_indefinite']
property shape: tuple[int, int]