Python Module: jointThrAllocation

Executive Summary

This module allocates commanded translational force and body torque across thrusters mounted on articulated arms. It solves for joint angle commands and thruster force commands using the arm configuration message and spacecraft state messages.

The optimizer uses SciPy. Importing the module from Basilisk.fswAlgorithms does not require SciPy, but executing JointThrAllocation.UpdateState does.

Message Connection Descriptions

The following diagram and table list the module input and output messages.

Module I/O Messages

Msg Variable Name	Msg Type	Description
armConfigInMsg	THRArmConfigMsgPayload	Input articulated thruster-arm configuration message.
CoMStatesInMsg	SCStatesMsgPayload	Input spacecraft center-of-mass state message.
hubStatesInMsg	SCStatesMsgPayload	Input spacecraft hub state message.
transForceInMsg	CmdForceInertialMsgPayload	Input inertial-frame commanded force message.
rotTorqueInMsg	CmdTorqueBodyMsgPayload	Input body-frame commanded torque message.
thrForceOutMsg	THRArrayCmdForceMsgPayload	Output thruster force command message.
desJointAnglesOutMsg	JointArrayStateMsgPayload	Output desired joint angle command message.

Module Assumptions and Limitations

The implementation assumes serial arm chains packed in arm order, one spacecraft tree, and one thruster per arm. The thruster parent joint is assumed to be the configured joint index on that arm.

User Guide

The module is imported through the standard flight-software package:

from Basilisk.fswAlgorithms import jointThrAllocation

allocation = jointThrAllocation.JointThrAllocation()
allocation.ModelTag = "jointThrAllocation"

The thrust upper bound can be provided as either a scalar or a per-thruster vector:

allocation.setThrForceMax(2.5)

The wrench tracking weights can be provided as a scalar, a length-six vector, or a 6-by-6 matrix:

allocation.setWc(1.0)

The thrust weighting term can be provided as either a scalar or a per-thruster vector:

allocation.setWf(1.0e-6)

---

class jointThrAllocation.JointThrAllocation(*args, **kwargs)

Bases: SysModel

Allocate thruster forces and joint angles for thrusters mounted on arms.

This implementation is intentionally example-oriented with explicit assumptions:

• Arms are serial chains packed in arm order.

• Arm geometry/config comes from THRArmConfigMsgPayload.

• One spacecraft tree is supported (all arms in same kinematic tree).

• Exactly one thruster per arm (configurable check).

• Thruster parent joint is the last joint in each arm (configurable check).

jointPoseFromTheta(theta: ndarray)

Return joint frame poses in body-frame coordinates.

Parameters:

theta – Joint angle vector.

Returns:

Direction cosine matrices and joint-frame origins in body-frame coordinates.

resolveThrForceMax()

Resolve thrForceMax to a length-nThr vector after nThr is known.

resolveWf()

Resolve Wf to a length-nThr vector after nThr is known.

setThrForceMax(thrForceMaxIn)

Set thrust upper bounds.

Accepted inputs are:

• scalar: same upper bound for all thrusters

• vector length nThr: per-thruster upper bounds

setWc(wcIn)

Set wrench tracking weights for the cost function.

Accepted inputs are:

• scalar: wc * I6

• length-6 vector: diag(wc)

• 6-by-6 matrix

setWf(wfIn)

Set thrust-weight term for the cost function.

Accepted inputs are:

• scalar: applies same weight to all thrusters

• vector length nThr: per-thruster weights

jointThrAllocation.mapMatrix(rVec_B: ndarray, fHatVec_B: ndarray, r_ComB_B: ndarray) → ndarray

Build the thruster force-to-wrench map.

Parameters:

• rVec_B – Thruster locations in body-frame coordinates.

• fHatVec_B – Thruster unit force directions in body-frame coordinates.

• r_ComB_B – Center-of-mass location relative to the hub origin in body-frame coordinates.

Returns:

Matrix mapping thruster magnitudes to stacked force and torque.