Enabling Branching of Basilisk Effectors

Back-substitution is the default method that manages the dynamics under the hood of Basilisk. The backsubstitution formulation assumes that all dynamical modules, a.k.a. “effectors”, influencing the dynamics of the spacecraft are attached directly to its central hub in parallel. These effectors are sub-classed as either Module: dynamicEffector (provide external forces and torques acting on the body, but doesn’t have state differential equations to integrate) or Module: stateEffector (has internal state differential equations to integrate that couple with the spacecraft rigid hub).

This parallel coupling assumption can be relaxed to allow select configurations of effectors to be attached in series to each other as opposed to being attached directly to the hub. See Advanced: Effector Module Branching for a description on using this added functionality.

State Effector Augmentation

For a state effector, three changes must be made.

  1. Connect the state effector’s properties to the Module: dynParamManager

    • Ensure the effector’s inertial properties are of an appropriate data type to be accepted by the parameter manager (ex. pointer to Eigen::MatrixXd). These properties should already be computed at each timestep by a method named something like compute<EffectorName>InertialStates()

    • Define names for these inertial properties to be registered with in the parameter manager

    • Define an assignStateParamNames() method to hand these property names to the dependent effector

    • Override the registerProperties() method of the state effector base class, and inside it register the properties and call the corresponding linkInProperties() method of dependent effectors

  2. Add a way to attach dynamic effectors to the state effector

    • Add a variable to the effector’s class to store a list of its dependent effectors

    • Override the addDynamicEffector() method of the state effector base class, and inside it call assignStateParamNames() on the new dependent effector, and add it to the list

  3. Augment the equations of motion to apply forces and torques of dependent effectors

    • Inside of updateContributions(), loop over the list of dependent effectors, calling their computeForceTorque() methods, and collecting forceExternal_B and torqueExternalPntB_B

    • Insert this force and torque into the effector equation of motion, ensuring to transform it into the appropriate frame

    • Insert the force and torque into the vecTrans and vecRot contributions, ensuring to transform it into the appropriate frame

Dynamic Effector Augmentation

For a dynamic effector, three changes must also be made.

  1. Connect the dynamic effector to its parents properties

    • Override the linkInProperties() method of the base class, and inside it collect the relevant properties from the parameter manager. Different effectors require various combinations of position, velocity, attitude, and angular velocity of their parent, including requiring none.

    • In places where hub states are used, add a conditional to use effector properties instead if the parent is a state effector instead of the hub.

  2. If the dynamic effector has a setup factory, such as the thruster’s simIncludeThruster or the reaction wheel’s simIncludeRW, define a method there for adding to a state effector instead of the hub.

  3. Set dynamic effector base class variable isAttachableToStateEffector to True in the constructor.

Additional Resources

Important

The force and torque ouput by dependent effectors as variables forceExternal_B and torqueExternalPntB_B is computed relative to its parent frame, not the body frame as they are labeled. For example if attached to a Module: spinningBodyOneDOFStateEffector, torqueExternalPntB_B is actually the torque about point S expressed in the S frame (torqueExternalPntS_S) as its parent frame is the spinning body’s frame.

This also requires that the state effector output inertial properties to this frame origin (r_SN_N) as opposed to outputting inertial properties to its center of mass (r_ScN_N). This is important because dynamic effectors handle converting their applied forces to torques with respect to their parent frame origin. If the state effector passes it’s center of mass position, this torque computed by the attached dynamic effector would need to be corrected, but the state effector does not get knowledge of where dynamic effectors are attached to make such a correction.

A more complete description of back-substitution, Module: stateEffector, and Module: dynamicEffector can be found in Module: spacecraft and its linked PDF description, particularly the Equations of Motion section. Specifics on setting up the corresponding integrated tests for any newly enabled branching effectors can be found in test_effectorBranching_integrated. A more detailed description of this augmentation of the back-substitution method can be found in the following conference paper.

Note

A. Morell and H. Schaub, ““Expanded Back-Substitution Dynamics Modeling For Branched Force And Torque Based Spacecraft Components”, AAS Spaceflight Mechanics Meeting, Kauai, HI, Jan. 19-23, 2025