ADCS.satellite_hardware.actuators.actuator module

class ADCS.satellite_hardware.actuators.actuator.Actuator(axis, u_max, bias=None, noise=None, estimate_bias=False)[source]

Bases: object

Abstract base class for all spacecraft actuators in the ADCS framework.

This class defines a common mathematical and software interface for torque–producing devices such as magnetorquers, thrusters, or reaction wheels. It provides a complete set of first- and second-order derivatives required by nonlinear estimation and control algorithms (e.g., EKF, iLQR, DDP), while leaving the physical torque model to subclasses.

Mathematical model

An actuator produces a body-frame torque

\[\boldsymbol{\tau} = \boldsymbol{\tau}\!\left( u,\, \mathbf{x},\, \mathrm{os} \right) \in \mathbb{R}^3\]

where

\[\begin{split}\mathbf{x} = \begin{bmatrix} \boldsymbol{\omega} \\ \mathbf{q} \end{bmatrix} \in \mathbb{R}^7\end{split}\]

is the base spacecraft state consisting of angular velocity \(\boldsymbol{\omega}\in\mathbb{R}^3\) and attitude quaternion \(\mathbf{q}\in\mathbb{R}^4\).

The actuator command is a scalar input

\[u \in [-u_{\max},\, u_{\max}]\]

applied along a fixed body-frame axis

\[\mathbf{a} = \frac{\texttt{axis}}{\|\texttt{axis}\|} \in \mathbb{S}^2\]

Bias and noise models are optional and are represented by Bias and Noise.

Design philosophy

  • All Jacobians are row-Jacobians (derivative of a vector w.r.t. a scalar or vector).

  • All second derivatives return rank-3 tensors with the final dimension corresponding to the torque vector.

  • Empty dimensions (size 0) are used when a state does not exist.

  • This base class returns zeros everywhere; subclasses must override the relevant methods.

See also

MTQ, RW

bias_process_covariance(dt=1.0, *, form='full')[source]

Return the actuator-bias random-walk covariance over dt seconds.

Parameters:

  • dt (float)

  • form (str)

Return type:

Covariance

control_covariance(*, form='full')[source]

Return input-noise covariance owned by this actuator.

Parameters:

form (str)

Return type:

Covariance

ddstor_torq__dbasestatedbasestate(u, x, os)[source]

Second derivative of storage torque with respect to the base spacecraft state.

\[\frac{\partial^2 \mathbf{t}_s}{\partial \mathbf{x}^2}\]
Parameters:
Returns:

State–state Hessian of storage torque.

Return type:

numpy.ndarray of shape (7, 7, 0)

ddstor_torq__dbasestatedh(u, x, os)[source]

Mixed second derivative of storage torque with respect to base state and storage state.

\[\frac{\partial^2 \mathbf{t}_s}{\partial \mathbf{x}\,\partial \mathbf{h}}\]
Parameters:
Returns:

State–storage Hessian of storage torque.

Return type:

numpy.ndarray of shape (7, 0, 0)

ddstor_torq__dbiasdbasestate(u, x, os)[source]

Mixed second derivative of storage torque with respect to bias and base state.

\[\frac{\partial^2 \mathbf{t}_s}{\partial \mathbf{b}\,\partial \mathbf{x}}\]
Parameters:
Returns:

Bias–state Hessian of storage torque.

Return type:

numpy.ndarray of shape (1, 7, 0) or (0, 7, 0)

ddstor_torq__dbiasdbias(u, x, os)[source]

Second derivative of storage torque with respect to actuator bias.

\[\frac{\partial^2 \mathbf{t}_s}{\partial \mathbf{b}^2}\]
Parameters:
Returns:

Bias–bias Hessian of storage torque.

Return type:

numpy.ndarray of shape (1, 1, 0) or (0, 0, 0)

ddstor_torq__dbiasdh(u, x, os)[source]

Mixed second derivative of storage torque with respect to bias and storage state.

\[\frac{\partial^2 \mathbf{t}_s}{\partial \mathbf{b}\,\partial \mathbf{h}}\]
Parameters:
Returns:

Bias–storage Hessian of storage torque.

Return type:

numpy.ndarray of shape (1, 0, 0) or (0, 0, 0)

ddstor_torq__dhdh(u, x, os)[source]

Second derivative of storage torque with respect to storage state.

\[\frac{\partial^2 \mathbf{t}_s}{\partial \mathbf{h}^2}\]
Parameters:
Returns:

Storage–storage Hessian of storage torque.

Return type:

numpy.ndarray of shape (0, 0, 0)

ddstor_torq__dudbasestate(u, x, os)[source]

Mixed second derivative of storage torque with respect to input and base state.

\[\frac{\partial^2 \mathbf{t}_s}{\partial u\,\partial \mathbf{x}}\]
Parameters:
Returns:

Input–state Hessian of storage torque.

Return type:

numpy.ndarray of shape (1, 7, 0)

ddstor_torq__dudbias(u, x, os)[source]

Mixed second derivative of storage torque with respect to input and bias.

\[\frac{\partial^2 \mathbf{t}_s}{\partial u\,\partial \mathbf{b}}\]
Parameters:
Returns:

Input–bias Hessian of storage torque.

Return type:

numpy.ndarray of shape (1, 1, 0) or (1, 0, 0)

ddstor_torq__dudh(u, x, os)[source]

Mixed second derivative of storage torque with respect to input and storage state.

\[\frac{\partial^2 \mathbf{t}_s}{\partial u\,\partial \mathbf{h}}\]
Parameters:
Returns:

Input–storage Hessian of storage torque.

Return type:

numpy.ndarray of shape (1, 0, 0)

ddstor_torq__dudu(u, x, os)[source]

Second derivative of storage torque with respect to input.

Parameters:
Returns:

Input–input Hessian of storage torque.

Return type:

numpy.ndarray of shape (1, 1, 0)

ddtorq__dbasestatedbasestate(u, x, os)[source]

Second derivative of torque with respect to the base spacecraft state.

\[\frac{\partial^2 \boldsymbol{\tau}}{\partial \mathbf{x}^2}\]
Parameters:
Returns:

State–state Hessian of torque.

Return type:

numpy.ndarray of shape (7, 7, 3)

ddtorq__dbasestatedh(u, x, os)[source]

Mixed second derivative of torque with respect to base state and storage state.

\[\frac{\partial^2 \boldsymbol{\tau}}{\partial \mathbf{x}\,\partial \mathbf{h}}\]
Parameters:
Returns:

State–storage Hessian of torque.

Return type:

numpy.ndarray of shape (7, 0, 3)

ddtorq__dbiasdbasestate(u, x, os)[source]

Mixed second derivative of torque with respect to bias and base state.

\[\frac{\partial^2 \boldsymbol{\tau}}{\partial \mathbf{b}\,\partial \mathbf{x}}\]
Parameters:
Returns:

Bias–state Hessian of torque.

Return type:

numpy.ndarray of shape (1, 7, 3) or (0, 7, 3)

ddtorq__dbiasdbias(u, x, os)[source]

Second derivative of torque with respect to actuator bias.

\[\frac{\partial^2 \boldsymbol{\tau}}{\partial \mathbf{b}^2}\]
Parameters:
Returns:

Bias–bias Hessian of torque.

Return type:

numpy.ndarray of shape (1, 1, 3) or (0, 0, 3)

ddtorq__dbiasdh(u, x, os)[source]

Mixed second derivative of torque with respect to bias and storage state.

\[\frac{\partial^2 \boldsymbol{\tau}}{\partial \mathbf{b}\,\partial \mathbf{h}}\]
Parameters:
Returns:

Bias–storage Hessian of torque.

Return type:

numpy.ndarray of shape (1, 0, 3) or (0, 0, 3)

ddtorq__dhdh(u, x, os)[source]

Second derivative of torque with respect to storage state.

\[\frac{\partial^2 \boldsymbol{\tau}}{\partial \mathbf{h}^2}\]
Parameters:
Returns:

Storage–storage Hessian of torque.

Return type:

numpy.ndarray of shape (0, 0, 3)

ddtorq__dudbasestate(u, x, os)[source]

Mixed second derivative of torque with respect to input and base state.

\[\begin{split}\frac{\partial^2 \boldsymbol{\tau}}{\partial u\,\partial \mathbf{x}} = \begin{bmatrix} \frac{\partial^2 \boldsymbol{\tau}}{\partial u\,\partial \boldsymbol{\omega}} \\ \frac{\partial^2 \boldsymbol{\tau}}{\partial u\,\partial \mathbf{q}} \end{bmatrix}\end{split}\]
Parameters:
Returns:

Input–state Hessian of torque.

Return type:

numpy.ndarray of shape (1, 7, 3)

ddtorq__dudbias(u, x, os)[source]

Mixed second derivative of torque with respect to input and bias.

\[\frac{\partial^2 \boldsymbol{\tau}}{\partial u\,\partial \mathbf{b}}\]
Parameters:
Returns:

Input–bias Hessian of torque.

Return type:

numpy.ndarray of shape (1, 1, 3) or (1, 0, 3)

ddtorq__dudh(u, x, os)[source]

Mixed second derivative of torque with respect to input and storage state.

\[\frac{\partial^2 \boldsymbol{\tau}}{\partial u\,\partial \mathbf{h}}\]

Base class has no storage state.

Parameters:
Returns:

Input–storage Hessian of torque.

Return type:

numpy.ndarray of shape (1, 0, 3)

ddtorq__dudu(u, x, os)[source]

Second derivative of torque with respect to input.

\[\frac{\partial^2 \boldsymbol{\tau}}{\partial u^2}\]
Parameters:
Returns:

Input–input Hessian of torque.

Return type:

numpy.ndarray of shape (1, 1, 3)

dstor_torq__dbasestate(u, x, os)[source]

First derivative of storage torque with respect to the base spacecraft state.

\[\frac{\partial \mathbf{t}_s}{\partial \mathbf{x}}\]
Parameters:
Returns:

Row-Jacobian of storage torque w.r.t. base state.

Return type:

numpy.ndarray of shape (7, 0)

dstor_torq__dbias(u, x, os)[source]

First derivative of storage torque with respect to actuator bias.

\[\frac{\partial \mathbf{t}_s}{\partial \mathbf{b}}\]
Parameters:
Returns:

Row-Jacobian of storage torque w.r.t. bias.

Return type:

numpy.ndarray of shape (1, 0) or (0, 0)

dstor_torq__dh(u, x, os)[source]

First derivative of storage torque with respect to storage state.

\[\frac{\partial \mathbf{t}_s}{\partial \mathbf{h}}\]
Parameters:
Returns:

Row-Jacobian of storage torque w.r.t. storage state.

Return type:

numpy.ndarray of shape (0, 0)

dstor_torq__du(u, x, os)[source]

First derivative of storage torque with respect to input.

\[\frac{\partial \mathbf{t}_s}{\partial u}\]
Parameters:
Returns:

Row-Jacobian of storage torque w.r.t. input.

Return type:

numpy.ndarray of shape (1, 0)

dtorq__dbasestate(u, x, os)[source]

First derivative of torque with respect to the base spacecraft state.

\[\begin{split}\frac{\partial \boldsymbol{\tau}}{\partial \mathbf{x}} = \begin{bmatrix} \frac{\partial}{\partial \boldsymbol{\omega}} \\ \frac{\partial}{\partial \mathbf{q}} \end{bmatrix}\end{split}\]
Parameters:
Returns:

Row-Jacobian of torque w.r.t. base state.

Return type:

numpy.ndarray of shape (7, 3)

dtorq__dbias(u, x, os)[source]

First derivative of torque with respect to actuator bias.

If a bias model exists, this mirrors dtorq__du().

\[\frac{\partial \boldsymbol{\tau}}{\partial \mathbf{b}}\]
Parameters:
Returns:

Row-Jacobian of torque w.r.t. bias.

Return type:

numpy.ndarray of shape (1, 3) or (0, 3)

dtorq__dh(u, x, os)[source]

First derivative of torque with respect to momentum storage state.

Base class has no storage state.

Parameters:
Returns:

Row-Jacobian of torque w.r.t. storage state.

Return type:

numpy.ndarray of shape (0, 3)

dtorq__du(u, x, os)[source]

First derivative of torque with respect to input.

\[\frac{\partial \boldsymbol{\tau}}{\partial u} \in \mathbb{R}^{1\times 3}\]
Parameters:
Returns:

Row-Jacobian of torque w.r.t. input.

Return type:

numpy.ndarray of shape (1, 3)

storage_torque(u, j2000, dmode=None)[source]

Compute the torque contribution associated with momentum storage states.

This is relevant for actuators such as reaction wheels that exchange angular momentum with an internal state.

Base class has no storage degrees of freedom.

Parameters:

  • u (float) – Actuator command input.

  • j2000 (float) – Absolute time in seconds since J2000 epoch.

  • dmode (ErrorMode or None) – Optional disturbance configuration.

Returns:

Storage torque vector.

Return type:

numpy.ndarray of shape (0,)

torque(u, x, os, dmode=None)[source]

Compute the body-frame torque produced by the actuator.

\[\boldsymbol{\tau} = \boldsymbol{\tau}(u, \mathbf{x}, \mathrm{os})\]

This base implementation returns zero torque.

Parameters:

  • u (float) – Actuator command input.

  • x (ADCS.state.State) – Base spacecraft state \([\boldsymbol{\omega};\mathbf{q}]\).

  • os (Orbital_State) – Orbital state providing environmental context.

  • dmode (ErrorMode or None) – Optional disturbance configuration.

Returns:

Body-frame torque vector.

Return type:

numpy.ndarray of shape (3,)

Parameters:

  • axis (ndarray)

  • u_max (float)

  • bias (Bias | None)

  • noise (Noise | None)

  • estimate_bias (bool)