ADCS.helpers.plot.states.quaternionplot module

class ADCS.helpers.plot.states.quaternionplot.QuaternionPlot(*, sources=None, time='time_s', title='Quaternion Components', units='', colors=('tab:blue', 'tab:orange', 'tab:green', 'tab:red'))

Bases: Subplot

Multi-panel visualization of quaternion components over time.

This class displays the four quaternion components in a fixed 2x2 layout, allowing comparison between real and estimated attitude representations. The plot is intended to give a clear overview of quaternion behavior without requiring knowledge of the underlying attitude propagation.

User configuration focuses on selecting data sources, colors, units, and the time reference used for the x-axis.

Parameters:

• sources (list[str] or None) – List of quaternion sources to display. Supported values are real and estimated. If None, only the real quaternion is shown.

• time (str) – Name of the simulation attribute containing the time vector in seconds.

• title (str) – Title displayed at the top of the plot group.

• units (str) – Optional units string appended to quaternion component labels.

• colors (tuple[str, str, str, str]) – Colors used for the quaternion components q0, q1, q2, and q3.

plot(ax, sim)

Return type:

None

class ADCS.helpers.plot.states.quaternionplot.QuaternionPlotCombined(*, sources=None, time='time_s', title='Quaternion Components', units='', colors=('tab:blue', 'tab:orange', 'tab:green', 'tab:red'))

Bases: Subplot

Combined plot of all quaternion components on a single axis.

This class overlays all four quaternion components on one set of axes, optionally including both real and estimated data. It provides a compact view suitable for quick comparison of relative component behavior.

The plot emphasizes user-defined configuration of sources, colors, units, and the time reference.

Parameters:

• sources (list[str] or None) – List of quaternion sources to display. Supported values are real and estimated.

• time (str) – Name of the simulation attribute containing the time vector in seconds.

• title (str) – Title displayed at the top of the plot.

• units (str) – Optional units string appended to the y-axis label.

• colors (tuple[str, str, str, str]) – Colors used for the quaternion components q0, q1, q2, and q3.

plot(ax, sim)

Return type:

None

class ADCS.helpers.plot.states.quaternionplot.QuaternionPlotSingle(*, component, sources=None, time='time_s', title=None, units='', color=None, colors=('tab:blue', 'tab:orange', 'tab:green', 'tab:red'))

Bases: Subplot

Visualization of a single quaternion component over time.

This class plots one selected quaternion component, optionally overlaying real and estimated values. It is intended for focused inspection of a specific quaternion element.

User settings control which component is displayed, visual styling, labeling, and the time reference.

Parameters:

• component (int) – Quaternion component index to plot. Must be one of 0, 1, 2, or 3.

• sources (list[str] or None) – List of quaternion sources to display. Supported values are real and estimated.

• time (str) – Name of the simulation attribute containing the time vector in seconds.

• title (str or None) – Title of the plot. If None, a default title is used.

• units (str) – Optional units string appended to the y-axis label.

• color (str or None) – Color used for the plotted quaternion component.

• colors (tuple[str, str, str, str]) – Default colors for quaternion components q0, q1, q2, and q3.

plot(ax, sim)

Return type:

None

class ADCS.helpers.plot.states.quaternionplot.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

class ADCS.helpers.plot.states.quaternionplot.Subplot

Bases: ABC

plot(ax, sim)

Parameters:

ax (matplotlib.pyplot.Axes)

Return type:

None