Magic#

class Magic : public Actuator#
#include <Magic.h>

“Magic” (direct body-torque) actuator class.

Represents an idealised actuator that applies a body-frame torque directly along a fixed body axis, with no environmental dependence and no momentum-storage state. The torque model is

\[ \boldsymbol{\tau} = u \cdot \mathbf{a}, \]
where \(\mathbf{a}\) is the unit body axis and \(u\) is the commanded torque magnitude.

Unlike MTQs (whose torque depends on the geomagnetic field through \(\boldsymbol{\tau} = -\mathbf{B}_b \times \mathbf{a} \cdot u\)) and RWs (which carry their own angular-momentum state and exchange momentum via Newton’s third law), magic actuators are dynamically trivial:

  • No state dependence ( \(\partial \boldsymbol{\tau}/\partial \mathbf{x} = 0\)).

  • No environment dependence (no B-field, sun, or orbit needed).

  • Constant Jacobian ( \(\partial \boldsymbol{\tau}/\partial u = \mathbf{a}\)).

Use cases: modelling thrusters with a fixed thrust direction, or as a “clean” body-torque commander in tests where the MTQ rank-deficiency and RW back-reaction would otherwise obscure the property under test.

See also

Actuator for the base class interface.

Public Types

using Vec3 = Actuator::Vec3#
using BaseState = Actuator::BaseState#
using Mat13 = Actuator::Mat13#
using Mat73 = Actuator::Mat73#
using T113 = Actuator::T113#
using T173 = Actuator::T173#
using T773 = Actuator::T773#

Public Functions

Magic(const Vec3 &axis, double max_torque)#

Construct a magic actuator with specified parameters.

Parameters:

  • axis – Unit vector specifying the torque direction in body frame.

  • max_torque – Maximum torque magnitude (N*m).

virtual Vec3 torque(double u, const BaseState &x) const override#

Compute the body-frame torque produced by this magic actuator.

Returns \(u \cdot \mathbf{a}\) &#8212; the torque is exactly linear in the control input, with no state or environment dependence.

Parameters:

  • u – Control input (torque magnitude, N*m).

  • x – Base state (unused; included for interface consistency).

Returns:

3D torque vector in body frame (N*m).

virtual Mat13 dtorq_du(double u, const BaseState &x) const override#

Jacobian of torque with respect to the control input.

Constant for a magic actuator: \(\partial \boldsymbol{\tau} / \partial u = \mathbf{a}^\top\) (returned as a 1x3 row).

Parameters:

  • u – Control input (unused).

  • x – Base state (unused).

Returns:

1x3 Jacobian.

virtual Mat73 dtorq_dbasestate(double u, const BaseState &x) const override#

Jacobian of torque with respect to the base state.

Zero &#8212; the magic torque is independent of \(\boldsymbol{\omega}\) and \(\mathbf{q}\).

Parameters:

  • u – Control input (unused).

  • x – Base state (unused).

Returns:

7x3 zero matrix.

virtual T113 ddtorq_dudu(double u, const BaseState &x) const override#

Second derivative of torque with respect to the control input.

Zero &#8212; torque is affine in \(u\).

virtual T173 ddtorq_dudbasestate(double u, const BaseState &x) const override#

Mixed second derivative \(\partial^2 \boldsymbol{\tau}/(\partial u \, \partial \mathbf{x})\).

Zero &#8212; torque doesn’t depend on the base state.

virtual T773 ddtorq_dbasestatedbasestate(double u, const BaseState &x) const override#

Second derivative of torque with respect to the base state.

Zero &#8212; torque doesn’t depend on the base state.

virtual Vec3 torque(double u, const BaseState &x) const

Compute the torque vector produced by this actuator.

Returns the torque vector as a function of control input and spacecraft state.

Parameters:

  • u – Control input (typically in [-u_max, u_max]).

  • x – Base state vector (7D: [av; q; …]).

Returns:

3D torque vector in body frame (Newton-meters).

virtual Mat13 dtorq_du(double u, const BaseState &x) const

Jacobian of torque with respect to control input.

Returns \(\frac{\partial \boldsymbol{\tau}}{\partial u}\) as a 1×3 row vector.

Parameters:

  • u – Control input.

  • x – Base state.

Returns:

1×3 Jacobian matrix.

virtual Mat73 dtorq_dbasestate(double u, const BaseState &x) const

Jacobian of torque with respect to base state.

Returns \(\frac{\partial \boldsymbol{\tau}}{\partial \mathbf{x}}\) as a 7×3 matrix.

Parameters:

  • u – Control input.

  • x – Base state (7D).

Returns:

7×3 Jacobian matrix.

virtual T113 ddtorq_dudu(double u, const BaseState &x) const

Hessian of torque with respect to control input (second derivatives).

Returns a 3-slice tensor of \(\frac{\partial^2 \tau_i}{\partial u^2}\).

Parameters:

  • u – Control input.

  • x – Base state.

Returns:

Tensor3 with 3 slices of 1×1 matrices (one per torque component).

virtual T173 ddtorq_dudbasestate(double u, const BaseState &x) const

Hessian of torque with respect to control input and base state.

Returns mixed partial derivatives \(\frac{\partial^2 \tau_i}{\partial u \partial x_j}\).

Parameters:

  • u – Control input.

  • x – Base state.

Returns:

Tensor3 with 3 slices of 1×7 matrices.

virtual T773 ddtorq_dbasestatedbasestate(double u, const BaseState &x) const

Hessian of torque with respect to base state (full second derivatives).

Returns \(\frac{\partial^2 \tau_i}{\partial x_j \partial x_k}\) for each component i.

Parameters:

  • u – Control input.

  • x – Base state.

Returns:

Tensor3 with 3 slices of 7×7 matrices.