Dynamics modules

The dynamics category contains the core modules that govern spacecraft translational and rotational motion. You assemble a simulation by attaching state effectors (components with their own internal states, such as reaction wheels or fuel tanks) and dynamic effectors (components that apply forces or torques, such as thrusters or drag) to a central Spacecraft hub.

Spacecraft hub

spacecraft

The spacecraft module is the primary rigid-body hub for 6-DOF translational and rotational motion. It is an instantiation of the dynamicObject abstract class and serves as the attachment point for all state and dynamic effectors.Key parameters

Variable	Type	Description
`mHub`	`double`	Hub mass [kg]
`IHubPntBc_B`	`double[3][3]`	Hub inertia tensor about point B in body frame [kg·m²]
`r_BcB_B`	`double[3]`	Center of mass offset from point B in body frame [m]
`r_CN_NInit`	`double[3]`	Initial inertial position [m]
`v_CN_NInit`	`double[3]`	Initial inertial velocity [m/s]
`sigma_BNInit`	`double[3]`	Initial attitude as MRP
`omega_BN_BInit`	`double[3]`	Initial angular velocity in body frame [rad/s]

Messages

Message	Type	Direction	Description
`scStateOutMsg`	`SCStatesMsgPayload`	Output	Spacecraft state
`scMassStateOutMsg`	`SCMassPropsMsgPayload`	Output	Mass properties
`attRefInMsg`	`AttRefMsgPayload`	Input (optional)	Prescribed attitude
`transRefInMsg`	`TransRefMsgPayload`	Input (optional)	Prescribed translation

from Basilisk.simulation import spacecraft

scObject = spacecraft.Spacecraft()
scObject.ModelTag = "bskSat"

# Set hub mass properties
scObject.hub.mHub = 750.0  # [kg]
scObject.hub.r_BcB_B = [[0.0], [0.0], [0.0]]  # [m]
scObject.hub.IHubPntBc_B = [[900.0, 0.0, 0.0],
                             [0.0, 800.0, 0.0],
                             [0.0, 0.0, 600.0]]  # [kg*m^2]

# Set initial conditions
scObject.hub.r_CN_NInit = [[7000.0e3], [0.0], [0.0]]  # [m]
scObject.hub.v_CN_NInit = [[0.0], [7.5e3], [0.0]]      # [m/s]
scObject.hub.sigma_BNInit = [[0.0], [0.0], [0.0]]       # MRP
scObject.hub.omega_BN_BInit = [[0.0], [0.0], [0.1]]    # [rad/s]

sim.AddModelToTask(taskName, scObject)

spacecraftSystem

spacecraftSystem extends the single-spacecraft hub to support simulations with multiple connected spacecraft objects sharing a common dynamics kernel. Use this module when you need to simulate formation flying or docked assemblies as a single dynamical system.

State effectors

State effectors add internal degrees of freedom to the spacecraft. Attach them with scObject.addStateEffector(effector).

reactionWheelStateEffector

Simulates an array of reaction wheels. The module includes safety mechanisms to prevent numerical instability from excessive wheel acceleration.Key parameters

Parameter	Default	Description
`maxWheelAcceleration`	`1.0e6 rad/s²`	Maximum allowed wheel acceleration
`largeTorqueThreshold`	`10.0 N·m`	Warning threshold for large torque with unlimited torque setting

Messages

Message	Type	Direction	Description
`rwMotorCmdInMsg`	`ArrayMotorTorqueMsgPayload`	Input (optional)	Motor torque commands
`rwSpeedOutMsg`	`RWSpeedMsgPayload`	Output	Wheel speed array
`rwOutMsgs`	`RWConfigLogMsgPayload`	Output (vector)	Per-wheel log messages

from Basilisk.simulation import reactionWheelStateEffector
from Basilisk.utilities import simIncludeRW

rwFactory = simIncludeRW.rwFactory()

# Add wheels (spin axes in body frame)
rwFactory.create('Honeywell_HR16', [1, 0, 0], maxMomentum=50.0)  # [Nms]
rwFactory.create('Honeywell_HR16', [0, 1, 0], maxMomentum=50.0)
rwFactory.create('Honeywell_HR16', [0, 0, 1], maxMomentum=50.0)

rwStateEffector = reactionWheelStateEffector.ReactionWheelStateEffector()
rwFactory.addToSpacecraft(scObject.ModelTag, rwStateEffector, scObject)

# Adjust safety thresholds if needed
rwStateEffector.setMaxWheelAcceleration(2.0e6)   # [rad/s^2]
rwStateEffector.setLargeTorqueThreshold(15.0)    # [Nm]

sim.AddModelToTask(taskName, rwStateEffector)

vscmgStateEffector

Implements Variable Speed Control Moment Gyroscopes (VSCMGs) — devices that combine a spinning wheel with a gimballed mount. Each VSCMG has two torque inputs: wheel spin torque (u_s) and gimbal torque (u_g).Messages

Message	Type	Direction	Description
`cmdsInMsg`	`VSCMGArrayTorqueMsgPayload`	Input	Wheel and gimbal torque commands
`speedOutMsg`	`VSCMGSpeedMsgPayload`	Output	VSCMG speed states
`vscmgOutMsgs`	`VSCMGConfigMsgPayload`	Output (vector)	Per-device config log

from Basilisk.simulation import vscmgStateEffector
from Basilisk.architecture import messaging

vscmgEffector = vscmgStateEffector.VSCMGStateEffector()

vscmg = messaging.VSCMGConfigMsgPayload()
vscmg.gsHat0_B = [[1.0], [0.0], [0.0]]   # spin axis
vscmg.ggHat_B  = [[0.0], [0.0], [1.0]]   # gimbal axis
vscmg.Omega    = 2000.0 * macros.RPM      # initial wheel speed
vscmg.massW    = 6.0                       # [kg]
vscmgEffector.AddVSCMG(vscmg)

scObject.addStateEffector(vscmgEffector)
sim.AddModelToTask(taskName, vscmgEffector)

hingedRigidBodyStateEffector

Models a flexible appendage (e.g., a solar panel) as a rigid body attached to the hub by a single-DOF torsional hinge with a linear spring and optional damping term. Each panel has two states: hinge angle theta and angular rate thetaDot.Messages

Message	Type	Direction	Description
`hingedRigidBodyRefMsg`	`HingedRigidBodyMsgPayload`	Input (optional)	Reference angle and rate
`motorTorqueInMsg`	`ArrayMotorTorqueMsgPayload`	Input (optional)	Hinge motor torque
`hingedRigidBodyOutMsg`	`HingedRigidBodyMsgPayload`	Output	Panel hinge angle and rate
`hingedRigidBodyConfigLogOutMsg`	`SCStatesMsgPayload`	Output	Panel inertial position and attitude

from Basilisk.simulation import hingedRigidBodyStateEffector
import numpy as np

panel1 = hingedRigidBodyStateEffector.HingedRigidBodyStateEffector()
panel1.IPntS_S = [[100.0, 0.0, 0.0],
                  [0.0, 50.0, 0.0],
                  [0.0, 0.0, 50.0]]  # [kg*m^2]
panel1.thetaInit = 5.0 * np.pi / 180.0  # [rad]
panel1.thetaDotInit = 0.0               # [rad/s]
panel1.nameOfThetaState = "panelTheta1"
panel1.nameOfThetaDotState = "panelThetaDot1"

scObject.addStateEffector(panel1)
sim.AddModelToTask(taskName, panel1)

fuelTank

Tracks fuel mass as a state variable and provides its contribution to the spacecraft mass properties. A FuelTank must be assigned a tank model (e.g., FuelTankModelConstantVolume) and can be linked to one or more thruster effectors for automatic mass depletion.Messages

Message	Type	Direction	Description
`fuelTankOutMsg`	`FuelTankMsgPayload`	Output	Tank mass and properties

from Basilisk.simulation import fuelTank

tankEffector = fuelTank.FuelTank()
tankModel = fuelTank.FuelTankModelConstantVolume()
tankEffector.setTankModel(tankModel)

# Link a thruster set to deplete tank fuel
tankEffector.addThrusterSet(thrustersEffector)

scObject.addStateEffector(tankEffector)

Other state effectors

Module	Description
`dualHingedRigidBodies`	Two-panel articulated solar array with two hinge DOFs
`NHingedRigidBodies`	Arbitrarily long chain of N hinged rigid body segments
`spinningBodies`	Constant-rate spinning body attached to the hub
`linearTranslationalBodies`	Body that translates linearly relative to the hub
`prescribedMotion`	Body whose motion is fully prescribed via an input message
`LinearSpringMassDamper`	Linear spring-mass-damper fuel slosh model
`sphericalPendulum`	Spherical pendulum fuel slosh model
`meanRevertingNoiseStateEffector`	Scalar mean-reverting noise state (e.g., density correction)

Dynamic effectors

Dynamic effectors apply forces or torques to the hub without maintaining internal states. Attach them with scObject.addDynamicEffector(effector).

thrusterDynamicEffector / thrusterStateEffector

Simulates a set of thrusters. thrusterDynamicEffector applies impulsive or continuous thrust; thrusterStateEffector models propellant-fed thrusters with a state-based mass flow rate.Use simIncludeThruster.thrusterFactory() to configure thruster arrays and attach them to both the spacecraft and a fuelTank effector.

dragDynamicEffector

Computes aerodynamic drag using a cannonball model (attitude-independent) or flat-plate model. Supports an optional density correction state and atmosphere-relative velocity computation for low Earth orbit.Messages

Message	Type	Direction	Description
`atmoDensInMsg`	`AtmoPropsMsgPayload`	Input	Atmospheric density from an atmosphere module

from Basilisk.simulation import dragDynamicEffector

drag = dragDynamicEffector.DragDynamicEffector()
drag.coreParams.dragCoeff = 2.2
drag.coreParams.projectedArea = 10.0  # [m^2]
drag.atmoDensInMsg.subscribeTo(atmo.envOutMsgs[0])

# Use velocity relative to rotating atmosphere (recommended for LEO)
drag.setUseAtmosphereRelativeVelocity(True)
drag.setPlanetOmega_N([0.0, 0.0, 7.2921159e-5])  # [rad/s] Earth rotation

scObject.addDynamicEffector(drag)

radiationPressure

Computes solar radiation pressure (SRP) force and torque on the spacecraft. Supports cannonball models and lookup-table-based models for complex shapes.Messages

Message	Type	Direction	Description
`sunEphmInMsg`	`SpicePlanetStateMsgPayload`	Input	Sun state
`sunEclipseInMsg`	`EclipseMsgPayload`	Input (optional)	Eclipse factor

extForceTorque

Applies a user-specified external force and/or torque directly to the spacecraft hub. Useful for modelling outgassing, disturbance forces, or directly injecting control inputs for testing.Messages

Message	Type	Direction	Description
`cmdTorqueInMsg`	`CmdTorqueBodyMsgPayload`	Input	Commanded body torque
`cmdForceBodyInMsg`	`CmdForceBodyMsgPayload`	Input	Commanded force in body frame
`cmdForceInertialInMsg`	`CmdForceInertialMsgPayload`	Input	Commanded force in inertial frame

constraintDynamicEffector

Enforces a physical connection between two separate spacecraft using Baumgarte stabilization. You specify the connection point on each spacecraft in its body frame and tune stiffness (alpha) and damping (beta) gains.

from Basilisk.simulation import constraintDynamicEffector

constraint = constraintDynamicEffector.ConstraintDynamicEffector()
constraint.setR_P1B1_B1(r_P1B1_B1)       # connection point on sc1 [m]
constraint.setR_P2B2_B2(r_P2B2_B2)       # connection point on sc2 [m]
constraint.setR_P2P1_B1Init(r_P2P1_B1Init)  # initial relative vector [m]
constraint.setAlpha(1e2)                  # stiffness gain
constraint.setBeta(1e3)                   # damping gain

scObject1.addDynamicEffector(constraint)
scObject2.addDynamicEffector(constraint)

# Sync integrators — use a variable-step integrator for best results
scObject1.syncDynamicsIntegration(scObject2)

The task must execute spacecraft 1 before spacecraft 2. Set ModelPriority or add them to the task in order.

Other dynamic effectors

Module	Description
`GravityGradientEffector`	Gravity gradient torque on an extended body
`MtbEffector`	Magnetic torque bar (magnetorquer) actuator
`facetDragEffector`	Faceted aerodynamic drag model
`facetSRPDynamicEffector`	Faceted solar radiation pressure model
`msmForceTorque`	Multi-sphere model electrostatic force and torque
`hingedRigidBodyMotor`	Actuator for driving a hinged rigid body hinge
`ExtPulsedTorque`	Time-series of pulsed torque inputs

Gravity models

gravityEffector — spherical harmonics

The default gravity model uses a spherical harmonics expansion. Configure it through simIncludeGravBody.gravBodyFactory(), which handles loading SPICE-compatible gravity coefficient files.

from Basilisk.utilities import simIncludeGravBody

gravFactory = simIncludeGravBody.gravBodyFactory()
earth = gravFactory.createEarth()
earth.isCentralBody = True

scObject.gravField.gravBodies = spacecraft.GravBodyVector(
    list(gravFactory.gravBodies.values())
)

polyhedralGravityModel

Computes gravitational acceleration from an arbitrarily shaped body modelled as a constant-density polyhedron, following Werner and Scheeres (1996). Suitable for small-body proximity operations around asteroids or comets.

mu = 4.46275472004e5  # [m^3/s^2] Eros standard gravity parameter
file_poly = 'eros007790.tab'

gravFactory = simIncludeGravBody.gravBodyFactory()
erosBody = gravFactory.createCustomGravObject('eros_poly', mu=mu)
erosBody.isCentralBody = True
erosBody.usePolyhedralGravityModel(file_poly)

scObject.gravField.gravBodies = spacecraft.GravBodyVector(
    list(gravFactory.gravBodies.values())
)

Supported shape file formats: .tab, .obj, and .txt. Vertex coordinates must be in kilometers.

Integrators

The Integrators sub-folder provides numerical integration schemes that you assign to a spacecraft object. Available integrators include RK4, RKF45 (variable step), and Euler. Assign one with:

from Basilisk.simulation import svIntegrators

integrator = svIntegrators.svIntegratorRKF45(scObject)
scObject.setIntegrator(integrator)

Get Started

Core Concepts

Building from Source

Simulation Modules

FSW Algorithms

Tutorials & Examples

Creating Modules

Vizard Visualization

Support

Spacecraft hub

State effectors

Dynamic effectors

Gravity models

Integrators

Build docs developers (and LLMs) love

Get Started

Core Concepts

Building from Source

Simulation Modules

FSW Algorithms

Tutorials & Examples

Creating Modules

Vizard Visualization

Support

​Spacecraft hub

​State effectors

​Dynamic effectors

​Gravity models

​Integrators

Build docs developers (and LLMs) love

Spacecraft hub

State effectors

Dynamic effectors

Gravity models

Integrators