ADCS.satellite_hardware.actuators.actuator module

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

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

ddstor_torq__dbasestatedbasestate(u, x, os)

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

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

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

State–state Hessian of storage torque.

Return type:

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

ddstor_torq__dbasestatedh(u, x, os)

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:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

State–storage Hessian of storage torque.

Return type:

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

ddstor_torq__dbiasdbasestate(u, x, os)

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:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

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)

Second derivative of storage torque with respect to actuator bias.

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

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

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)

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:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

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)

Second derivative of storage torque with respect to storage state.

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

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

Storage–storage Hessian of storage torque.

Return type:

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

ddstor_torq__dudbasestate(u, x, os)

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:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

Input–state Hessian of storage torque.

Return type:

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

ddstor_torq__dudbias(u, x, os)

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

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

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

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)

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:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

Input–storage Hessian of storage torque.

Return type:

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

ddstor_torq__dudu(u, x, os)

Second derivative of storage torque with respect to input.

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

Input–input Hessian of storage torque.

Return type:

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

ddtorq__dbasestatedbasestate(u, x, os)

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

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

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

State–state Hessian of torque.

Return type:

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

ddtorq__dbasestatedh(u, x, os)

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:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

State–storage Hessian of torque.

Return type:

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

ddtorq__dbiasdbasestate(u, x, os)

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

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

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

Bias–state Hessian of torque.

Return type:

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

ddtorq__dbiasdbias(u, x, os)

Second derivative of torque with respect to actuator bias.

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

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

Bias–bias Hessian of torque.

Return type:

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

ddtorq__dbiasdh(u, x, os)

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

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

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

Bias–storage Hessian of torque.

Return type:

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

ddtorq__dhdh(u, x, os)

Second derivative of torque with respect to storage state.

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

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

Storage–storage Hessian of torque.

Return type:

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

ddtorq__dudbasestate(u, x, os)

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:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

Input–state Hessian of torque.

Return type:

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

ddtorq__dudbias(u, x, os)

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

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

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

Input–bias Hessian of torque.

Return type:

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

ddtorq__dudh(u, x, os)

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:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

Input–storage Hessian of torque.

Return type:

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

ddtorq__dudu(u, x, os)

Second derivative of torque with respect to input.

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

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

Input–input Hessian of torque.

Return type:

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

dstor_torq__dbasestate(u, x, os)

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

\[\frac{\partial \mathbf{t}_s}{\partial \mathbf{x}}\]

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

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)

First derivative of storage torque with respect to actuator bias.

\[\frac{\partial \mathbf{t}_s}{\partial \mathbf{b}}\]

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

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)

First derivative of storage torque with respect to storage state.

\[\frac{\partial \mathbf{t}_s}{\partial \mathbf{h}}\]

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

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)

First derivative of storage torque with respect to input.

\[\frac{\partial \mathbf{t}_s}{\partial u}\]

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

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

Return type:

numpy.ndarray of shape (1, 0)

dtorq__dbasestate(u, x, os)

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:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

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

Return type:

numpy.ndarray of shape (7, 3)

dtorq__dbias(u, x, os)

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:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

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)

First derivative of torque with respect to momentum storage state.

Base class has no storage state.

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

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

Return type:

numpy.ndarray of shape (0, 3)

dtorq__du(u, x, os)

First derivative of torque with respect to input.

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

Parameters:

• u (float) – Actuator command input.

• x (numpy.ndarray of shape (7,)) – Base spacecraft state.

• os (Orbital_State) – Orbital state.

Returns:

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

Return type:

numpy.ndarray of shape (1, 3)

storage_torque(u, j2000, dmode=None)

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)

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 (numpy.ndarray of shape (7,)) – 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)

• noise (Noise)

• estimate_bias (bool)