Basics of Writing Basilisk Modules

Making New Modules

You should build your own Basilisk modules outside of the primary Basilisk source folder. This keeps your Basilisk source folder free of local customizations that interfere with upgrading the simulation framework. The only exception is if you are planning on pushing the module back to the primary Basilisk source itself.

Recommended: Build your module as a About Extensions — a self-contained Python wheel that compiles independently without recompiling all of Basilisk and can be shared via pip install.

The older Building Basilisk with External Modules approach is still supported for users who need modules folded directly into a from-source Basilisk build.

This chapter covers the basics of designing Basilisk modules, as well as how to write a module using C++, C, Python, or Rust. As always with code documentation, it is never complete and always work-in-progress.

For general developer support pages on coding guidelines, forking, building the Sphinx documentation system etc., see Support/Developer Information in Basics of Writing Basilisk Modules.

The following pages cover the primary tasks required to make a Basilisk module. This includes how to design the basic module function, how messages work, what methods are required for a module, etc. Note that the dynamics modules are both Basilisk modules and also a sub-class of either C++ Module: dynamicEffector (provide external forces and torques acting on the body, but doesn’t have state differential equations to integrate), or C++ Module: stateEffector (has internal state differential equations to integrate that couple with the spacecraft rigid hub).

Warning

The goal of the following content is to facilitate the process of creating new modules. However, this documentation does not avoid the need to study the Basilisk source code, including how other modules were written, to understand how to create new modules.

• Module Design Considerations
  • Message Connections
  • One Big Module or Several Small Modules
  • Variable Number of Input or Output Messages
• Creating New Message Definitions
  • Msg File Location
  • Msg Data Definition
  • Creating the Msg C/C++ Swig Interface Files
• Making C Modules
  • Simulation Time
  • Unused Lifecycle Parameters
• Making C++ Modules
  • Simulation Time
  • Unused Lifecycle Parameters
• [BETA] Making Rust Modules
  • Rust Terms Used in This Guide
  • Comparison with C and C++ Modules
  • Install and Build with Rust Support
  • Quick-Start from rustModuleTemplate
  • Module Layout
  • Configure the Module Package
  • Generate the Language Boundary
  • Register the Module in the Workspace
  • Integrated External Rust Modules
  • Write the Module
  • Configuration Getters, Setters, and Validation
  • Module Lifecycle
  • Unused Lifecycle Parameters
  • Message Ports and Values
  • Python-Visible Configuration
  • Rust-Owned Private State
  • Basilisk C Utilities
  • Linear Algebra with nalgebra
  • Simulation Time
  • Runtime Context and Logging
  • Use the Module from Python
  • Document the Module
  • Test the Module
  • Current Limitations
  • Reference
• Making Python Modules
  • Simulation Time
  • Unused Lifecycle Parameters
• Making Numba Modules
  • Defining a Numba Module
  • Parameter Naming Convention
  • What is Allowed in UpdateStateImpl
  • Re-use and Re-initialisation
  • RigidBodyKinematicsNumba
  • Continuous-Time States (StatefulNumbaModel)
  • Performance Notes
• Module RST Documentation
  • Creating the Documentation Page
  • Testing the Documentation
• Module Unit Test File
• Automation Script to Create a New Basilisk Module
  • Header File
  • C/C++ File
  • Swig File
  • RST Module Documentation
  • Unit Test File
  • User Guide
• Common Basilisk Support Files
• Advanced Topics
  • Creating DynamicObject Basilisk Modules
  • Multi-body Dynamics with MuJoCo
  • Enabling Branching of Basilisk Effectors
  • Optimizing performance when using SPICE