ADCS.estimators.covariance module

Backward-compatible import for ADCS.covariance.

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

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)

Parameters:

• blocks (Iterable[Covariance | Any])

• kwargs (Any)

Return type:

Covariance

classmethod from_matrix(matrix, **kwargs)

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')

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)

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)

Parameters:

• dimension (int)

• scale (float)

• kwargs (Any)

Return type:

Covariance

classmethod zeros(dimension, **kwargs)

Parameters:

• dimension (int)

• kwargs (Any)

Return type:

Covariance

static cross_covariance(first_deviations, second_deviations, weights)

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)

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)

Parameters:

other (Covariance | Any)

Return type:

Covariance

as_matrix()

Return an owned full covariance matrix.

Return type:

ndarray

assign(matrix)

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

Parameters:

matrix (Covariance | Any)

Return type:

None

assign_upper_factor(factor)

Atomically replace the covariance from an upper factor.

Parameters:

factor (Any)

Return type:

None

copy(*, form=None, coordinates=None, psd_policy=None)

Parameters:

• form (str | None)

• coordinates (str | None)

• psd_policy (str | None)

Return type:

Covariance

predicted_linear(transition, noise)

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:

• transition (Any)

• noise (Covariance | Any)

Return type:

Covariance

predicted_unscented(deviations, weights, noise)

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)

Parameters:

• vectors (Any)

• weight (float)

Return type:

Covariance

replace_block(indices, block)

Parameters:

• indices (Any)

• block (Covariance | Any)

Return type:

None

scaled(scale)

Parameters:

scale (float)

Return type:

Covariance

sigma_offsets(scale=1.0)

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)

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

Parameters:

rhs (Any)

Return type:

ndarray

subset(indices, *, coordinates=None)

Parameters:

• indices (Any)

• coordinates (str | None)

Return type:

Covariance

transformed(jacobian, *, coordinates=None)

Return \(J P J^T\).

Parameters:

• jacobian (Any)

• coordinates (str | None)

Return type:

Covariance

updated_linear(measurement_jacobian, measurement_noise, *, joseph=True)

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)

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()

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

Return type:

ndarray

zero_cross(first, second)

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]