opengnc.actuators package

Submodules

opengnc.actuators.actuator module

Abstract base class for actuator models.

class opengnc.actuators.actuator.Actuator(name: str = 'Actuator', saturation: float | tuple[float, float] | None = None, deadband: float | None = None)

Bases: ABC

Abstract base class for all actuators.

Parameters:

• name (str, optional) – Actuator name. Default is “Actuator”.

• saturation (float | tuple[float, float], optional) – Max output magnitude (scalar) or (min, max) range.

• deadband (float, optional) – Input values below this magnitude result in zero output.

apply_deadband(value: float) → float

Apply deadband to value.

Parameters:

value (float) – Commanded value.

Returns:

Value after deadband application.

Return type:

float

apply_saturation(value: ndarray | float) → ndarray | float

Apply saturation limits.

Parameters:

value (np.ndarray | float) – Signal to saturate.

Returns:

Saturated signal.

Return type:

np.ndarray | float

abstractmethod command(*args: Any, **kwargs: Any) → Any

Calculate the actuator output based on the command signal.

Parameters:

• *args (Any) – Commanded input(s) (e.g., torque, dipole, voltage).

• **kwargs (dict) – Additional state info (e.g., current speed, environment).

Returns:

The actual output applied to the system.

Return type:

Any

opengnc.actuators.allocation module

Control allocation algorithms mapping generalized forces to actuator commands.

class opengnc.actuators.allocation.ControlAllocator(actuator_matrix: ndarray)

Bases: ABC

Abstract base class for control allocation logic.

Maps desired generalized forces (force/torque) to individual actuator commands.

Parameters:

actuator_matrix (np.ndarray) – The (m x n) matrix A where Y = A * u. m = degrees of freedom (e.g., 3 for torque). n = number of actuators.

abstractmethod allocate(force_torque_cmd: ndarray) → ndarray

Allocate generalized force/torque to individual actuators.

Parameters:

force_torque_cmd (np.ndarray) – Desired 6-DOF force and torque vector.

Returns:

Individual actuator commands.

Return type:

np.ndarray

class opengnc.actuators.allocation.NullMotionManager(actuator_matrix: ndarray)

Bases: object

Manages null-motion to redistribute actuator states without affecting net output.

u_net = u_alloc + u_null u_null = (I - A+ * A) * z

Parameters:

actuator_matrix (np.ndarray) – The control effectiveness matrix.

apply_null_command(u_base: ndarray, z: ndarray, A_current: ndarray | None = None) → ndarray

Add null-motion component to base command.

Parameters:

• u_base (np.ndarray) – Base actuator commands (e.g., from pseudo-inverse).

• z (np.ndarray) – Desired secondary goal (e.g., move gimbals away from limits).

• A_current (np.ndarray, optional) – Current Jacobian.

Returns:

Combined actuator command.

Return type:

np.ndarray

get_null_projection(A_current: ndarray | None = None) → ndarray

Calculate the null-space projection matrix (I - A+ * A).

Parameters:

A_current (np.ndarray, optional) – Current Jacobian/effectiveness matrix.

Returns:

Null-space projection matrix.

Return type:

np.ndarray

class opengnc.actuators.allocation.PseudoInverseAllocator(effectiveness_matrix: ndarray)

Bases: ControlAllocator

Control allocation using the Moore-Penrose pseudo-inverse.

Suitable for over-determined systems (more actuators than DOFs). Minimizes the L2-norm of the actuator commands: u = A^# * f.

Parameters:

effectiveness_matrix (np.ndarray) – The (m x n) matrix mapping actuator outputs to forces/torques.

allocate(force_torque_cmd: ndarray) → ndarray

Perform allocation using pseudo-inverse.

Parameters:

force_torque_cmd (np.ndarray) – Desired force/torque vector.

Returns:

Actuator commands vector.

Return type:

np.ndarray

class opengnc.actuators.allocation.SingularRobustAllocator(actuator_matrix: ndarray, epsilon: float = 0.01, lambda0: float = 0.01)

Bases: ControlAllocator

Singular Robust Inverse (SR-Inverse) allocator for CMGs.

Adds a regularization term to avoid extremely high actuator rates near singularities. u = A^T * (A * A^T + lambda * I)^-1 * Y.

Parameters:

• actuator_matrix (np.ndarray) – The control effectiveness matrix.

• epsilon (float, optional) – Threshold for manipulability measure. Default is 0.01.

• lambda0 (float, optional) – Maximum regularization weight. Default is 0.01.

allocate(desired_output: ndarray, A_current: ndarray | None = None) → ndarray

Perform SR-Inverse allocation.

Parameters:

• desired_output (np.ndarray) – Desired torque or force.

• A_current (np.ndarray, optional) – Current Jacobian matrix if time-varying. Defaults to self.A.

Returns:

Actuator rate commands.

Return type:

np.ndarray

opengnc.actuators.cmg module

Control Moment Gyro (CMG) actuator model.

class opengnc.actuators.cmg.ControlMomentGyro(wheel_momentum: float, gimbal_axis: ndarray, spin_axis_init: ndarray, name: str = 'CMG', max_gimbal_rate: float | None = None)

Bases: Actuator

Control Moment Gyro (CMG) Actuator.

Models torque produced by changing the orientation of a constant-speed momentum wheel. Torque = gimbal_rate x momentum.

Parameters:

• wheel_momentum (float) – Angular momentum magnitude (Nms).

• gimbal_axis (np.ndarray) – Unit vector of the gimbal axis (3,).

• spin_axis_init (np.ndarray) – Unit vector of the initial spin axis (3,).

• name (str, optional) – Actuator name. Default is “CMG”.

• max_gimbal_rate (float, optional) – Maximum gimbal angular velocity (rad/s).

command(gimbal_rate_cmd: Any = None, dt: float | None = None, *args: Any, **kwargs: Any) → ndarray

Calculate torque produced by gimbal rate.

Parameters:

• gimbal_rate_cmd (float) – Commanded gimbal rate (rad/s).

• dt (float, optional) – Time step (s) to update gimbal angle.

• **kwargs (dict) – Additional parameters (unused).

Returns:

Torque vector (Nm) (3,).

Return type:

np.ndarray

get_axes(angle: float | None = None) → tuple[ndarray, ndarray]

Get the current spin and transverse axes for a given gimbal angle.

Parameters:

angle (float, optional) – Gimbal angle (rad). If None, uses current self.gimbal_angle.

Returns:

(spin_axis, transverse_axis).

Return type:

tuple[np.ndarray, np.ndarray]

get_torque_jacobian(angle: float | None = None) → ndarray

Returns the Jacobian mapping gimbal rate to torque: T = A * g_rate.

Parameters:

angle (float, optional) – Angle to evaluate at (rad).

Returns:

(3, 1) mapping matrix.

Return type:

np.ndarray

opengnc.actuators.magnetorquer module

Magnetorquer actuator model.

class opengnc.actuators.magnetorquer.Magnetorquer(max_dipole: float | None = None, name: str = 'MTQ')

Bases: Actuator

Magnetorquer Actuator Model.

Parameters:

• max_dipole (float | None, optional) – Maximum dipole moment (Am^2). Default None (no saturation).

• name (str, optional) – Actuator name. Default “MTQ”.

command(dipole_cmd: float | None = None, *args: Any, **kwargs: Any) → float

Calculate delivered dipole moment.

Parameters:

• dipole_cmd (float) – Commanded dipole moment (Am^2).

• **kwargs (Any) – Additional parameters.

Returns:

Delivered dipole moment (Am^2).

Return type:

float

opengnc.actuators.reaction_wheel module

Reaction Wheel (RW) actuator model with friction and momentum limits.

class opengnc.actuators.reaction_wheel.ReactionWheel(max_torque: float | None = None, max_momentum: float | None = None, inertia: float | None = None, name: str = 'RW', static_friction: float = 0.0, viscous_friction: float = 0.0, coulomb_friction: float = 0.0)

Bases: Actuator

Reaction Wheel Actuator.

Models torque generation with saturation, max speed limits, and friction.

Parameters:

• max_torque (float, optional) – Maximum torque (Nm). Default is None (no saturation).

• max_momentum (float, optional) – Maximum angular momentum (Nms).

• inertia (float, optional) – Moment of inertia about spin axis (kg*m^2).

• name (str, optional) – Actuator name. Default is “RW”.

• static_friction (float, optional) – Static friction torque (Nm). Default is 0.0.

• viscous_friction (float, optional) – Viscous friction coefficient (Nm/(rad/s)). Default is 0.0.

• coulomb_friction (float, optional) – Coulomb friction torque (Nm). Default is 0.0.

command(torque_cmd: float | None = None, current_speed: float = 0.0, *args: Any, **kwargs: Any) → float

Calculate delivered motor torque.

Friction Model: $tau_f = f_v omega + f_c text{sgn}(omega)$

Parameters:

• torque_cmd (float) – Commanded motor torque (Nm).

• current_speed (float, optional) – Current wheel spin rate (rad/s). Default 0.0.

Returns:

Actual torque delivered to the spacecraft (Nm).

Return type:

float

opengnc.actuators.solar_sail module

Solar Sail force model based on Solar Radiation Pressure (SRP).

class opengnc.actuators.solar_sail.SolarSail(area: float, reflectivity: float = 0.9, specular_reflect_coeff: float = 0.9, name: str = 'SolarSail')

Bases: Actuator

Solar Sail Actuator model.

Models the force produced by Solar Radiation Pressure (SRP) on a flat sail surface.

Parameters:

• area (float) – Surface area of the sail (m^2).

• reflectivity (float, optional) – Total reflectivity coefficient [0 to 1]. Default is 0.9.

• specular_reflect_coeff (float, optional) – Fraction of reflection that is specular [0 to 1]. Default is 0.9.

• name (str, optional) – Actuator name. Default is “SolarSail”.

calculate_force(sun_unit_vec: ndarray, normal_unit_vec: ndarray, distance_au: float = 1.0) → ndarray

Calculate SRP force vector on the flat sail surface.

Parameters:

• sun_unit_vec (np.ndarray) – Unit vector from sail towards the Sun.

• normal_unit_vec (np.ndarray) – Unit vector normal to the sail surface.

• distance_au (float, optional) – Distance from the Sun in Astronomical Units (AU). Default is 1.0.

Returns:

SRP force vector (N) in the same frame as input vectors.

Return type:

np.ndarray

command(normal_cmd: ndarray | None = None, *args: Any, **kwargs: Any) → ndarray

Calculate force based on commanded normal vector and current environment.

Parameters:

• normal_cmd (np.ndarray) – Commanded normal vector for the sail.

• **kwargs (dict) –

  • sun_vecnp.ndarray

    Unit vector towards the Sun. Required.

  • distance_aufloat, optional

    Distance from Sun (AU). Default is 1.0.

Returns:

Force vector (N).

Return type:

np.ndarray

opengnc.actuators.thruster module

Thruster models including Chemical, Electric, and Multi-thruster clusters.

class opengnc.actuators.thruster.ChemicalThruster(max_thrust: float = 10.0, isp: float = 300.0, min_on_time: float = 0.01, name: str = 'ChemThruster')

Bases: Thruster

Chemical Thruster model.

Models On/Off behavior or PWM-averaged thrust with minimum on-time constraints.

Parameters:

• max_thrust (float, optional) – Maximum thrust (N). Default is 10.0.

• isp (float, optional) – Specific impulse (s). Default is 300.0.

• min_on_time (float, optional) – Minimum valve open time (s). Default is 0.010.

• name (str, optional) – Actuator name. Default is “ChemThruster”.

command(thrust_cmd: float | None = None, dt: float | None = None, *args: Any, **kwargs: Any) → float

Considers PWM constraints for chemical valve.

If the commanded thrust implies an on-time < min_on_time, it is zeroed.

Parameters:

• thrust_cmd (float) – Commanded thrust (N).

• dt (float, optional) – Control period (s).

• **kwargs (dict) – Additional parameters.

Returns:

Delivered thrust (N).

Return type:

float

class opengnc.actuators.thruster.ElectricThruster(max_thrust: float = 0.1, isp: float = 1500.0, power_efficiency: float = 0.6, name: str = 'ElecThruster')

Bases: Thruster

Electric Thruster model (e.g., Hall Effect, Ion).

Power-limited thrust generation.

Parameters:

• max_thrust (float, optional) – Maximum thrust (N). Default is 0.1.

• isp (float, optional) – Specific impulse (s). Default is 1500.0.

• power_efficiency (float, optional) – Electrical to Jet power efficiency (eta). Default is 0.6.

• name (str, optional) – Actuator name. Default is “ElecThruster”.

get_power_consumption(thrust: float) → float

Calculate electrical power requirement.

Equation: $P_{in} = frac{T I_{sp} g_0}{2 eta}$

Parameters:

thrust (float) – Produced thrust (N).

Returns:

Electrical power consumption (W).

Return type:

float

class opengnc.actuators.thruster.Thruster(max_thrust: float = 1.0, min_impulse_bit: float = 0.0, isp: float | None = None, name: str = 'Thruster')

Bases: Actuator

Base Thruster model.

Produces thrust force and consumes mass based on Isp.

Parameters:

• max_thrust (float, optional) – Maximum thrust (N). Default is 1.0.

• min_impulse_bit (float, optional) – Minimum impulse bit (Ns). Default is 0.0.

• isp (float, optional) – Specific Impulse (s). Default is None.

• name (str, optional) – Actuator name. Default is “Thruster”.

command(thrust_cmd: float | None = None, dt: float | None = None, *args: Any, **kwargs: Any) → float

Calculate delivered thrust.

Parameters:

• thrust_cmd (float) – Commanded thrust (N).

• dt (float, optional) – Time step duration (s). Required for MIB checks.

• **kwargs (dict) – Additional parameters.

Returns:

Delivered thrust (N).

Return type:

float

get_mass_flow(thrust: float) → float

Calculate mass flow rate.

Equation: $dot{m} = frac{T}{I_{sp} g_0}$

Parameters:

thrust (float) – Actual thrust produced (N).

Returns:

Mass flow rate (kg/s).

Return type:

float

class opengnc.actuators.thruster.ThrusterCluster(thrusters: list[Thruster], positions: ndarray, directions: ndarray)

Bases: object

A collection of thrusters with defined allocation logic.

Maps generalized 6-DOF force/torque commands to individual thruster outputs.

Parameters:

• thrusters (list[Thruster]) – List of thruster objects.

• positions (np.ndarray) – (N, 3) positions of thrusters in body frame (m).

• directions (np.ndarray) – (N, 3) thrust unit vectors in body frame.

command(force_torque_cmd: ndarray | None = None, dt: float | None = None, *args: Any) → ndarray

Distribute 6-DOF force/torque command to individual thrusters.

Parameters:

• force_torque_cmd (np.ndarray) – Desired [Fx, Fy, Fz, Tx, Ty, Tz] in body frame (N, Nm).

• dt (float, optional) – Time step for MIB and duty cycle checks (s).

Returns:

Delivered thrusts for each thruster in the cluster (N).

Return type:

np.ndarray

opengnc.actuators.vscmg module

Variable Speed Control Moment Gyro (VSCMG) actuator model.

class opengnc.actuators.vscmg.VariableSpeedCMG(wheel_inertia: float, gimbal_axis: ndarray, spin_axis_init: ndarray, name: str = 'VSCMG', max_gimbal_rate: float | None = None, max_wheel_torque: float | None = None)

Bases: ControlMomentGyro

Variable Speed Control Moment Gyro (VSCMG).

Allows wheel speed to change (Reaction Wheel effect) while gimbaling (CMG effect). Torque = I_w * alpha * s + gimbal_rate * h * t.

Parameters:

• wheel_inertia (float) – Moment of inertia of the wheel (kg*m^2).

• gimbal_axis (np.ndarray) – Gimbal axis vector (3,).

• spin_axis_init (np.ndarray) – Initial spin axis vector (3,).

• name (str, optional) – Actuator name. Default is “VSCMG”.

• max_gimbal_rate (float, optional) – Maximum gimbal angular velocity (rad/s).

• max_wheel_torque (float, optional) – Maximum torque for wheel acceleration (Nm).

command(gimbal_rate_cmd: Any = None, dt: float | None = None, *args: Any, **kwargs: Any) → ndarray

Calculate combined torque from gimbaling and wheel acceleration.

Parameters:

• cmd_vec (tuple[float, float] | list[float]) – (gimbal_rate_cmd, wheel_torque_cmd). - gimbal_rate_cmd : Commanded gimbal rate (rad/s). - wheel_torque_cmd : Commanded wheel torque (Nm).

• dt (float, optional) – Time step (s) for state integration.

Returns:

Net torque vector (Nm) (3,).

Return type:

np.ndarray

get_jacobian(angle: float | None = None) → ndarray

Returns full Jacobian matrix mapping [g_rate, w_torque]^T to torque vector.

Parameters:

angle (float, optional) – Gimbal angle to evaluate at (rad).

Returns:

(3, 2) Jacobian matrix.

Return type:

np.ndarray

Module contents