How nsarrazin/odessa works
1. What ODESSA is
ODESSA is a Python ODE simulation framework built around a modular right-hand-side pipeline. It uses SciPy’s ODE solvers for integration and Numba jitclasses to keep modules and core state structured and fast enough for repeated RHS evaluations.
2. Top-level runtime flow
The central flow is:
JSON config / scripted setup → Simulation → one or more Phases → ordered module execution on a shared Core → SciPy integrator → solution outputs.
The solver repeatedly calls an RHS function that populates the Core, runs each module in order, and returns Core.dy.
3. Simulation orchestration boundary
odessa/simulation.py is the main orchestration layer. It constructs simulations from JSON, owns the list of phases, and drives the integration run. This is the primary boundary between user-facing configuration and the internal numerical model.
4. Phase model
odessa/phase.py represents a simulation segment. A phase contains:
- a set of modules to execute in a fixed order,
- a set of events that can terminate or switch behavior.
Multiple phases allow a run to change physics mid-flight, such as powered ascent followed by ballistic flight or deployment logic.
5. Shared state through the Core
The Core classes are the shared data bus for the simulation. They hold:
- state variables like position and velocity,
- derived quantities like force, acceleration, density, speed of sound, mass, inertia.
Modules do not communicate directly with each other; they read and write through Core. This is the key architectural boundary that keeps the model modular.
6. Module system
Modules live under odessa/modules/ and are grouped by degree-of-freedom:
- 3DoF: simpler translational flight dynamics
- 6DoF: full translational + rotational dynamics
Each module exposes an id, a type, and an rhs(Core) method. The order in the config matters, because later modules depend on values written by earlier ones.
7. Physics subsystems
The main physics families are:
- Atmos: atmospheric properties
- Mass: mass and inertia evolution
- Gravity: gravity models, including J2 and other approximations
- Aero: drag and aerodynamic force/moment models
- Thrust: engine force models driven by tables
- Tower: launch-rail or rigid constraint behavior in 6DoF
- Dynamics: final equations-of-motion assembly that turns accumulated forces/moments into derivatives
These are the main diagram boxes for the simulation’s physical pipeline.
8. 3DoF vs 6DoF architecture
The repository contains two parallel simulation stacks:
- **odessa/modules/3dof/*** for trajectory-style motion with fewer state variables
- **odessa/modules/6dof/*** for full rigid-body flight dynamics
They share concepts and some helper patterns, but the 6DoF stack adds orientation, moments, and rotational dynamics, plus more detailed aero/gravity/tower behavior.
9. Events as termination or phase-control logic
Event modules live under odessa/events/ and are evaluated during integration to detect conditions such as:
- ground contact
- fixed simulation time
- altitude thresholds
- apogee or distance-based conditions
These are used both to stop a phase early and to trigger phase transitions.
10. Helpers and numerical utilities
odessa/helpers/ contains cross-cutting utilities rather than physics modules:
- coordinate/frame transformations
- rotation math
- atmospheric helper functions
- interpolation utilities for tables and grids
- JSON/Numpy encoding support
These support the module layer and are critical for data-driven models like drag tables, engine tables, and wind profiles.
11. Configuration and data-driven inputs
Most repository examples are driven by JSON files in scripts/configs/ and test configs under test/. Tables and CSVs provide real inputs such as:
- aero coefficients
- wind profiles
- mass and inertia histories
- engine/thrust curves
This means the architecture is strongly data-driven: the same module code is reused with different parameter tables.
12. Examples, demos, and benchmarks
The scripts/ folder contains runnable demos and benchmarks that show how the framework is assembled in practice. These scripts are not a separate runtime subsystem, but they are important because they demonstrate:
- composing phases and modules,
- modifying a running simulation,
- logging and plotting outputs,
- performance comparisons for 6DoF runs.
13. Testing and validation
The test/ tree contains scenario-based regression tests for both 3DoF and 6DoF, including NASA-style atmosphere/orbit cases and a two-stage rocket scenario with external CSV fixtures. The tests validate the numerical pipeline against known outputs, which is important because architecture correctness depends on module ordering, table interpolation, and solver/event behavior.
14. External dependencies that shape the architecture
The main external technologies are Numba and SciPy. Numba influences the design toward statically described module classes and jitclass specs; SciPy supplies the numerical integration engine. The architecture is therefore optimized for repeated numeric evaluation rather than request/response workloads.
Main entry points: 6dof 6DoF modules · 3dof 3DoF modules · simulation.py Simulation · phase.py Phase
Components 21
Runtime
Simulation orchestration and shared execution flow.
- Simulation · Top-level simulation boundary that builds runs, owns phases, and drives execution.
odessa/simulation.py - Phase · A simulation segment with ordered modules and event conditions.
odessa/phase.py - RHS loop · Repeated solver callback that populates shared state, runs modules, and returns derivatives.
- Events · Event modules that stop phases or trigger transitions during integration.
odessa/events - SciPy solver · Numerical integration engine repeatedly invoking the RHS callback.
Physics
Core model subsystems for flight dynamics.
- Core 3DoF · 3DoF shared state bus for forces, mass, and derivatives.
odessa/modules/3dof/core/Core3DoF.py - Core 6DoF · 6DoF shared state bus including translational and rotational quantities.
odessa/modules/6dof/core/Core6DoF.py - 3DoF modules · Translational flight-dynamics modules executed in fixed order.
odessa/modules/3dof - 6DoF modules · Rigid-body flight-dynamics modules with orientation, moments, and constraints.
odessa/modules/6dof - Atmos · Atmospheric property models shared by both dynamics stacks.
odessa/modules/6dof/atmos/Atmos.py - Mass · Mass and inertia evolution from tables or scripted logic.
odessa/modules/6dof/mass/Mass.py - Gravity · Gravity models including J2 and simpler approximations.
odessa/modules/6dof/gravity/GravityJ2.py - Aero · Aerodynamic force and moment models driven by tables or analytic forms.
odessa/modules/6dof/aero/AeroBallistic6DoF.py - Thrust · Engine and thrust-table models that feed force accumulation.
odessa/modules/6dof/thrust/Thrust.py - Tower · Launch-rail or rigid constraint behavior used in 6DoF scenarios.
odessa/modules/6dof/tower/Tower.py - Dynamics · Final equations-of-motion assembly that converts accumulated loads into derivatives.
odessa/modules/6dof/dynamics/DynamicsSpherical.py
Support
Helpers and data-driven inputs used by the model.
- Helpers · Cross-cutting math, frames, interpolation, and encoding utilities.
odessa/helpers - Numba JIT · JIT-compiled structured state and modules for repeated numeric evaluation.
Delivery
Scripts and regression coverage that exercise the framework.
Connections 33
- Config → Simulation: defines run · Configuration and scripted setup are consumed to build simulations.
- Simulation → Phase: owns · A simulation is composed of one or more phases.
- Simulation → Events: loads · Simulation setup wires in phase-control events.
- Simulation → SciPy solver: drives · Simulation hands the phase runtime to the numerical integrator.
- SciPy solver → RHS loop: calls · The integrator repeatedly evaluates the RHS callback.
- RHS loop → Phase: executes · Each RHS evaluation runs the active phase logic.
- RHS loop → Core 3DoF: writes · 3DoF modules accumulate state and derivatives on shared core state.
- RHS loop → Core 6DoF: writes · 6DoF modules accumulate state and derivatives on shared core state.
- Phase → 3DoF modules: orders · A phase configures the ordered 3DoF module chain.
- Phase → 6DoF modules: orders · A phase configures the ordered 6DoF module chain.
- 3DoF modules → Atmos: uses · 3DoF model family includes atmospheric state preparation.
- 3DoF modules → Gravity: uses · 3DoF model family includes gravity contributions.
- 3DoF modules → Mass: uses · 3DoF model family includes mass evolution.
- 3DoF modules → Thrust: uses · 3DoF model family includes propulsion forcing.
- 3DoF modules → Dynamics: finishes · 3DoF dynamics assembly produces derivatives.
- 6DoF modules → Atmos: uses · 6DoF model family includes atmospheric state preparation.
- 6DoF modules → Gravity: uses · 6DoF model family includes gravity contributions.
- 6DoF modules → Mass: uses · 6DoF model family includes mass and inertia evolution.
- 6DoF modules → Aero: uses · 6DoF model family includes aerodynamic forces and moments.
- 6DoF modules → Thrust: uses · 6DoF model family includes propulsion forcing.
- 6DoF modules → Tower: uses · 6DoF model family includes launch-constraint behavior.
- 6DoF modules → Dynamics: finishes · 6DoF dynamics assembly produces derivatives.
- Events → Phase: controls · Events can terminate a phase or trigger transition behavior.
- Helpers → 3DoF modules: supports · Helper math and interpolation utilities underpin model modules.
- Helpers → 6DoF modules: supports · Helper math and interpolation utilities underpin model modules.
- Helpers → Simulation: supports · Encoding and transformation helpers support orchestration and data handling.
- Numba JIT → Core 3DoF: structures · Numba shapes the 3DoF core as structured numeric state.
- Numba JIT → Core 6DoF: structures · Numba shapes the 6DoF core as structured numeric state.
- Numba JIT → 3DoF modules: compiles · Numba accelerates module evaluation in the 3DoF stack.
- Numba JIT → 6DoF modules: compiles · Numba accelerates module evaluation in the 6DoF stack.
- Scripts → Simulation: demonstrates · Example scripts show how to compose and run simulations.
- Tests → Simulation: validates · Regression tests exercise simulation assembly and outputs.
- Tests → Helpers: validates · Helper tests cover interpolation and numeric utilities.