ADCS.state module

Typed spacecraft attitude-state containers.

class ADCS.state.EstimatorState(w, q, h=(), act_bias=(), sens_bias=(), dist_param=(), cov=None, int_cov=None, *, covariance=None, process_noise=None)

Bases: State

A State with estimated parameters and uncertainty.

The augmented estimate and its reduced local error are ordered as

\[\hat x= \begin{bmatrix} \boldsymbol\omega & \mathbf q & \mathbf h & \mathbf b_a & \mathbf b_s & \mathbf d \end{bmatrix}^{T}, \qquad P=\mathbb E\!\left[\delta x\,\delta x^T\right].\]

Consequently, the default covariance has one fewer row and column than the stored state because \(\mathbf q\in\mathbb S^3\) contributes only three local degrees of freedom. Full quaternion-coordinate covariances are also accepted and can be projected using covariance_to_reduced().

covariance and process_noise are authoritative Covariance objects. The cov and int_cov properties retain the legacy full-matrix interface during estimator migration.

Parameters:

• w (ndarray)

• q (ndarray)

• h (ndarray)

• act_bias (ndarray)

• sens_bias (ndarray)

• dist_param (ndarray)

• cov (Any)

• int_cov (Any)

• covariance (Covariance | None)

• process_noise (Covariance | None)

classmethod from_dict(payload)

Parameters:

payload (Mapping[str, Any])

Return type:

EstimatorState

classmethod from_estimator_array(value, *, n_rw=0, n_act_bias=0, n_sens_bias=0, n_dist_param=0, cov=None, int_cov=None)

Parameters:

• value (Any)

• n_rw (int)

• n_act_bias (int)

• n_sens_bias (int)

• n_dist_param (int)

• cov (Any)

• int_cov (Any)

Return type:

EstimatorState

classmethod mean(states, weights=None, *, reference=None, covariance='reference', **kwargs)

Compute an augmented-state mean with an explicit covariance policy.

Parameters:

• states (Iterable[EstimatorState])

• weights (Any)

• reference (EstimatorState | None)

• covariance (Literal['reference', 'weighted'])

• kwargs (Any)

Return type:

EstimatorState

add_error(delta)

Compatibility wrapper for plus().

Parameters:

delta (ndarray)

Return type:

EstimatorState

as_estimator_array()

Return type:

ndarray

copy()

Return type:

EstimatorState

covariance_to_full(covariance=None, **tangent_kwargs)

Project reduced covariance with \(P_f=G P_r G^T\).

Here \(G\) is tangent_map().

Parameters:

• covariance (Any)

• tangent_kwargs (Any)

Return type:

ndarray

covariance_to_reduced(covariance=None, **tangent_kwargs)

Project full covariance with \(P_r=G^\dagger P_f(G^\dagger)^T\).

Here \(G^\dagger\) is tangent_pinv().

Parameters:

• covariance (Any)

• tangent_kwargs (Any)

Return type:

ndarray

interpolate(other, alpha, *, method='slerp')

Blend two estimated states; see interpolate().

Bias and disturbance blocks interpolate linearly. Covariances also blend linearly — a convex combination of PSD matrices stays PSD, but this is a convenience for plotting/resampling, not a geodesic covariance interpolation.

Parameters:

• other (State)

• alpha (float)

• method (str)

Return type:

EstimatorState

is_close(other, *, rtol=1e-05, atol=1e-08, compare_covariance=False)

Compare augmented states, optionally including covariance matrices.

Parameters:

• other (State)

• rtol (float)

• atol (float)

• compare_covariance (bool)

Return type:

bool

minus(ref, *, quaternion_mode='quaternion_vector', quaternion_order='right', shortest=True)

Return the augmented-state difference in reduced local coordinates.

Parameters:

• ref (State)

• quaternion_mode (str)

• quaternion_order (str)

• shortest (bool)

Return type:

ndarray

normalized()

Return a copy with a unit quaternion, without changing this state.

Return type:

EstimatorState

plus(delta, *, quaternion_mode='quaternion_vector', quaternion_order='right', normalize=True)

Apply a perturbation to physical and estimated parameter blocks.

Parameters:

• delta (Any)

• quaternion_mode (str)

• quaternion_order (str)

• normalize (bool)

Return type:

EstimatorState

subtract(ref)

Compatibility wrapper for minus().

Parameters:

ref (State)

Return type:

ndarray

to_dict()

Return type:

dict[str, Any]

act_bias: ndarray

property augmented_size: int

property cov: ndarray

Legacy full-matrix view of covariance.

property covariance: Covariance

State-estimation covariance in full or square-root form.

dist_param: ndarray

property full_size: int

Number of stored scalar state elements, including all four quaternion elements.

property int_cov: ndarray

Legacy full-matrix view of process_noise.

property process_noise: Covariance

Process-noise covariance associated with this estimated state.

sens_bias: ndarray

property tangent_size: int

Dimension of the local state coordinates, with three attitude elements.

property uses_reduced_quaternion_covariance: bool

class ADCS.state.State(w, q, h=<factory>)

Bases: object

Physical spacecraft state \(x=[\boldsymbol\omega,\mathbf q,\mathbf h]\).

\[x \in \mathbb R^3 \times \mathbb S^3 \times \mathbb R^{n_h}, \qquad \delta x = \begin{bmatrix} \delta\boldsymbol\omega & \delta\boldsymbol\theta & \delta\mathbf h \end{bmatrix}^{T} \in\mathbb R^{6+n_h}.\]

The unit quaternion has the double-cover equivalence \(\mathbf q\sim-\mathbf q\). Attitude differences therefore live in the three-dimensional tangent block \(\delta\boldsymbol\theta\), not in the four stored quaternion coefficients. For a relative quaternion \(\delta\mathbf q=[\eta,\boldsymbol\epsilon]\), two common coordinate maps supported by minus() are

\[\phi_{qv}(\delta\mathbf q)=2\boldsymbol\epsilon, \qquad \phi_{rv}(\delta\mathbf q)= 2\operatorname{atan2}(\lVert\boldsymbol\epsilon\rVert,\eta) \frac{\boldsymbol\epsilon}{\lVert\boldsymbol\epsilon\rVert}.\]

The class deliberately does not emulate a NumPy array. Numerical-library boundaries use as_array() explicitly. Estimated parameters and covariance are provided by EstimatorState.

Parameters:

• w (ndarray)

• q (ndarray)

• h (ndarray)

classmethod from_array(value)

Build a state from the established [w(3), q(4), h] ordering.

Parameters:

value (Any)

Return type:

State

classmethod from_dict(payload)

Parameters:

payload (Mapping[str, Any])

Return type:

State

classmethod mean(states, weights=None, *, reference=None, quaternion_mode='quaternion_vector', quaternion_order='right', tolerance=1e-12, max_iterations=50)

Compute the weighted manifold mean \(\bar x\) satisfying

\[\sum_i w_i\left(x_i\boxminus\bar x\right)=0.\]

Iteration uses minus() and plus().

Parameters:

• states (Iterable[State])

• weights (Any)

• reference (State | None)

• quaternion_mode (str)

• quaternion_order (str)

• tolerance (float)

• max_iterations (int)

Return type:

State

static quaternion_delta_from_vector(value, *, mode='quaternion_vector')

Convert three local attitude coordinates into a unit quaternion delta.

Parameters:

• value (Any)

• mode (str)

Return type:

ndarray

static quaternion_delta_to_vector(value, *, mode='quaternion_vector', shortest=True)

Convert a quaternion delta into three local attitude coordinates.

Parameters:

• value (Any)

• mode (str)

• shortest (bool)

Return type:

ndarray

static stack(states)

Parameters:

states (Iterable[State])

Return type:

ndarray

add_error(delta)

Compatibility wrapper for plus().

Parameters:

delta (ndarray)

Return type:

State

aligned_quaternion(reference)

Return this state’s unit quaternion with the sign nearest reference.

Parameters:

reference (Any)

Return type:

ndarray

as_array()

Return an owned physical-state vector in [w, q, h] ordering.

Return type:

ndarray

copy()

Return type:

State

interpolate(other, alpha, *, method='slerp')

Blend two states: linear on w/h, SLERP or NLERP on q.

Both methods are shortest-arc (sign-corrected), so antipodal quaternion representations of nearby rotations interpolate correctly. alpha is not clamped; values outside [0, 1] extrapolate.

Parameters:

• other (State)

• alpha (float)

• method (str)

Return type:

State

is_close(other, *, rtol=1e-05, atol=1e-08)

Compare physical states while treating q and -q as equivalent.

Parameters:

• other (State)

• rtol (float)

• atol (float)

Return type:

bool

local_coordinates(ref, **kwargs)

Semantic alias for minus().

Parameters:

• ref (State)

• kwargs (Any)

Return type:

ndarray

minus(ref, *, quaternion_mode='quaternion_vector', quaternion_order='right', shortest=True)

Return \(x\boxminus x_{\mathrm{ref}}\) in local coordinates.

For right errors,

\[\delta\mathbf q = \mathbf q_{\mathrm{ref}}^{-1}\otimes\mathbf q, \qquad \delta x = [\Delta\boldsymbol\omega, \phi(\delta\mathbf q),\Delta\mathbf h].\]

Left errors reverse the quaternion product. See plus() for the inverse operation.

Parameters:

• ref (State)

• quaternion_mode (str)

• quaternion_order (str)

• shortest (bool)

Return type:

ndarray

normalization_jacobian()

Return the full-state quaternion-normalization Jacobian.

\[N_q=\frac{1}{\lVert\mathbf q\rVert} \left(I_4-\frac{\mathbf q\mathbf q^T}{\lVert\mathbf q\rVert^2}\right).\]

Return type:

ndarray

normalized()

Return a copy with a unit quaternion, without changing this state.

Return type:

State

plus(delta, *, quaternion_mode='quaternion_vector', quaternion_order='right', normalize=True)

Return \(x\boxplus\delta x\).

For the default right-error convention,

\[x\boxplus\delta x = [\boldsymbol\omega+\delta\boldsymbol\omega, \mathbf q\otimes\phi^{-1}(\delta\boldsymbol\theta), \mathbf h+\delta\mathbf h].\]

full_quaternion uses additive four-element quaternion coordinates followed by normalization. Other modes use three attitude coordinates. This is the inverse of minus() locally.

Parameters:

• delta (Any)

• quaternion_mode (str)

• quaternion_order (str)

• normalize (bool)

Return type:

State

retract(delta, **kwargs)

Semantic alias for plus().

Parameters:

• delta (Any)

• kwargs (Any)

Return type:

State

subtract(ref)

Compatibility wrapper for minus().

Parameters:

ref (State)

Return type:

ndarray

tangent_map(*, quaternion_mode='quaternion_vector', quaternion_order='right')

Return the local-to-full differential map \(G(x)\).

\[\begin{split}G(x)=\operatorname{diag}(I_3,sW_{\pm}(\mathbf q),I_{n_h}), \qquad W_{\pm}(\mathbf q)= \begin{bmatrix}-\mathbf q_v^T\\q_0I_3\pm[\mathbf q_v]_\times\end{bmatrix}.\end{split}\]

Thus a local perturbation and its first-order full-state displacement are related by

\[(x\boxplus\delta x)-x = G(x)\,\delta x +\mathcal O(\lVert\delta x\rVert^2).\]

The sign is positive for right errors and negative for left errors.

Parameters:

• quaternion_mode (str)

• quaternion_order (str)

Return type:

ndarray

tangent_pinv(*, quaternion_mode='quaternion_vector', quaternion_order='right')

Return \(G(x)^\dagger\), the analytical pseudoinverse of tangent_map().

For reduced attitude coordinates the quaternion block satisfies

\[(sW_\pm)^\dagger=\frac{1}{s}W_\pm^T, \qquad G^\dagger G=I, \qquad GG^\dagger=\Pi_{T_x\mathcal M},\]

where \(\Pi_{T_x\mathcal M}\) projects a full quaternion displacement onto the unit-quaternion tangent space.

Parameters:

• quaternion_mode (str)

• quaternion_order (str)

Return type:

ndarray

to_dict()

Return type:

dict[str, Any]

with_quaternion_delta(delta_q, *, order='right', normalize=True)

Compose a unit delta quaternion on the right or left.

\[\mathbf q^+ = \mathbf q\otimes\delta\mathbf q \quad\text{or}\quad \mathbf q^+ = \delta\mathbf q\otimes\mathbf q\]

The Hamilton product matches quat_mult().

Parameters:

• delta_q (Any)

• order (str)

• normalize (bool)

Return type:

State

DEFAULT_QUATERNION_MODE: ClassVar[Literal['quaternion_vector', 'rotation_vector', 'mrp', 'two_mrp', 'cayley', 'full_quaternion']] = 'quaternion_vector'

DEFAULT_QUATERNION_ORDER: ClassVar[Literal['right', 'left']] = 'right'

property error_size: int

Alias for tangent_size.

property full_size: int

Number of stored scalar state elements, including all four quaternion elements.

h: ndarray

q: ndarray

property tangent_size: int

Dimension of the local state coordinates, with three attitude elements.

w: ndarray