Spaceflight Dynamics Framework Architecture

System Overview

The Spaceflight Dynamics Framework (SDF) is structured as a modular spacecraft simulation environment with a clear separation between frontend presentation, simulation execution, interface-level data exchange, and backend simulation logic.

This overview shows the main architectural building blocks and their communication paths. More detailed subsystem diagrams are provided separately for the frontend, interface layer, backend, propulsion and physics.

The architecture supports full six-degree-of-freedom (6DoF) rigid-body spacecraft dynamics, including three-dimensional translation, rotational dynamics, angular velocity propagation, and quaternion-based attitude representation. The backend separates simulation orchestration, spacecraft state, translational and rotational physics, propulsion, numerical integration, configuration interpretation, and coordinate frame transformation into dedicated subsystems.

A dedicated Interface Layer isolates the Qt frontend from the backend simulation engine. Commands are transferred through FlightCommand DTO, telemetry is exposed through Telemetry DTO, and the TelemetryMapper translates between backend domain data and frontend-facing data structures.

Main Building Blocks

• Frontend / UI: Qt-based presentation layer for cockpit visualization, user interaction, configuration selection, and telemetry display.
• SimulationWorker: Worker-thread boundary that keeps the simulation loop separate from the UI thread and exchanges data through Qt signal-slot communication.
• Interface Layer: Stable communication boundary between frontend and backend. It contains the command and telemetry DTOs as well as the mapping logic required to keep both sides decoupled.
• Backend / Simulation Engine: Core C++ simulation layer containing the spacecraft model, simulation orchestration, physics, propulsion, configuration interpretation, and frame transformation logic.
• Spacecraft: Authoritative domain object and single source of truth for the current spacecraft state, including position, velocity, angular velocity, quaternion-based attitude, mass properties, propulsion state, and mission status.
• Simulation Models: Replaceable physics, propulsion, control, sensor, and optimization models that extend the framework without changing the overall architecture.

Frontend Architecture

The frontend has been refactored into a clearer Qt application structure. MainWindow now acts as the central application shell and frontend coordinator. It owns the persistent top navigation bar, the central page stack, the shared configuration manager, and the simulation worker thread.

Individual pages are now treated as focused UI components rather than application controllers. The landing page only presents the project entry point and emits navigation requests. The spacecraft selection page handles configuration selection. The cockpit page handles telemetry visualization and operator interaction. Additional pages such as control help and settings can now be integrated without changing the overall navigation structure.

This structure reduces coupling between pages, prevents nested page stacks, and prepares the frontend for future expansion such as settings, telemetry inspection, replay views, ROS communication monitoring, and additional research-oriented tools.

Frontend Components

• MainWindow: Central Qt application shell. It owns the top bar, page stack, core pages, configuration manager, simulation thread, and worker interface.
• TopBarWidget: Persistent navigation bar for global frontend navigation, settings access, and control help access.
• QStackedWidget: Central page container used to switch between homepage, spacecraft selection, cockpit, controls help, and settings pages.
• Homepage: Pure landing page. It displays the SDF branding, development status, and primary entry points without owning worker threads or sub-pages.
• SpacecraftSelectionPage: UI page for selecting JSON-defined spacecraft configurations through the sharedConfigManager.
• cockpitPage: Main simulation cockpit page. It displays telemetry, forwards operator commands, and owns cockpit widgets such as LandingView and inputmapper.
• ControlsHelpPage: Static control reference page showing keyboard-first control bindings and planned controller readiness.
• SettingsPage: Placeholder page for the planned v0.2 SDF Research Release settings subsystem.
• inputmapper: Converts keyboard input into structured FlightCommand data.
• LandingView: Lightweight 2.5D visualization widget for spatial landing state, trajectory history, velocity vectors, and RCS activity indication.
• UIBuilder: Shared helper for consistent frontend UI elements, buttons, labels, page titles, and telemetry detail boxes.

Frontend Design Direction

• Centralized page routing through MainWindow
• Persistent global navigation through TopBarWidget
• UI pages with focused responsibilities
• No nested application windows inside the homepage
• Simulation worker ownership located at application shell level
• Preparation for future settings, help, telemetry, and ROS tooling pages

Backend Architecture

The backend of the Spaceflight Dynamics Framework (SDF) is designed as a modular simulation engine centered around a single authoritative spacecraft representation. It separates simulation orchestration, state management, coordinate transformations, propulsion modeling, physical state propagation, telemetry generation, and future optimization components into clearly defined subsystems.

The backend is implemented in modern C++ and uses the Eigen linear algebra library as its mathematical foundation. Custom vector and quaternion implementations have been replaced by Eigen's well-established vector, matrix, and quaternion types, providing improved numerical robustness, interoperability, and maintainability across the simulation framework.

At the center of the backend architecture is the Spacecraft component. It acts as the Single Source of Truth (SSOT) for the simulation state. The associated StateVector represents the dynamic state used for numerical propagation and is one of the most important runtime data structures in the simulation core.

SimControl acts as the central simulation orchestrator. It coordinates simulation execution, forwards commands, triggers subsystem updates, manages mission and frame context data, and controls the overall simulation lifecycle.

In the diagram, the orange-highlighted components represent the core simulation state path. Spacecraft and StateVector form the central runtime state authority. The pink-highlighted Thrust Optimizer represents a research-oriented extension. While the optimizer itself has already been fully implemented, its integration into the standard simulation workflow is planned for a future SDF release, where it will support optimization-based guidance, trajectory generation, and fuel-efficiency studies.

Backend Components

• SimControl: Central simulation coordinator responsible for simulation lifecycle management, command forwarding, subsystem coordination, mission context handling, frame updates, and interaction with the active spacecraft instance.
• Spacecraft: Core backend domain object and Single Source of Truth for the current simulation state. It owns vehicle configuration, runtime state, propulsion state, physical state, and mission-related data.
• StateVector: Primary dynamic state representation used by the simulation. It stores the propagated spacecraft state using Eigen mathematical types, including Eigen::Vector3d for translational quantities and Eigen::Quaterniond for spacecraft attitude, together with angular velocity, mass properties, and additional dynamic state quantities.
• JsonConfigReader: Backend-side configuration interpreter that translates external JSON spacecraft configuration files into backend domain structures used to initialize spacecraft properties, engine configurations, fuel systems, initial conditions, and mission context data.
• CoordinateTransformer: Central backend component responsible for transformations between MCI, MCMF, MSC, ENU, LVLH, and SBF reference frames.
• Physics: Backend subsystem responsible for translational and rotational rigid-body dynamics. It coordinates environmental acceleration models, rotational physics models, numerical integration, angular acceleration, angular velocity propagation, and quaternion-based attitude propagation.
• Thrust: Propulsion subsystem responsible for main engine and RCS actuator behavior, thrust allocation, fuel consumption, body-fixed force generation, torque generation from off-center thrust, and aggregation of propulsion-induced forces and torques.
• Models and Abstract Interfaces: Extension points for physics models, propulsion models, controllers, sensors, integrators, and future research models. These interfaces allow individual simulation models to be replaced independently while leveraging Eigen for efficient vector, matrix, and quaternion computations.
• Telemetry Mapping: Mapping layer responsible for translating backend simulation data into frontend-facing telemetry DTOs.
• Thrust Optimizer: Planned SDF v0.2 research extension for optimization-based thrust, trajectory, guidance, and fuel-efficiency experiments. It is intentionally separated from the real-time simulation loop.

Backend Design Direction

• SimControl orchestrates simulation flow, while Spacecraft owns the authoritative simulation state.
• Spacecraft and StateVector form the core runtime state path.
• Eigen provides the standardized mathematical foundation for vector, matrix, and quaternion computations throughout the backend.
• Coordinate transformation is treated as a dedicated backend subsystem.
• Physics and propulsion remain strictly separated: propulsion models generate and aggregate forces and torques, while the physics subsystem evaluates the resulting translational and rotational state propagation.
• Telemetry is transferred through explicit DTOs instead of exposing backend domain structures to the frontend.
• Optimization components are intentionally separated from the real-time simulation loop to support future research-oriented functionality.

Physics Architecture

The physics architecture provides the mathematical propagation layer for the complete six-degree-of-freedom spacecraft state. Translational and rotational dynamics are implemented as separate physical models while sharing a common numerical integration architecture.

Translational physics determines linear acceleration and propagates velocity and position. Rotational physics evaluates Euler's rigid-body equations from the spacecraft inertia tensor, angular velocity, and aggregated external torque. The resulting angular acceleration is integrated to obtain angular velocity, while quaternion kinematics propagate spacecraft attitude.

Physical modeling and numerical integration are intentionally separated. This allows dynamics models and integration schemes to be exchanged independently without changing the surrounding simulation architecture.

Key Components and Relationships

• IPhysicsModel: Abstract interface for physical force or acceleration models.
• BasicMoonGravity: Current lunar central-body gravity model used to compute gravitational acceleration.
• IRotationalPhysicsModel: Abstract interface for rotational physics models. It defines the contract for computing spacecraft angular acceleration from angular velocity, inertia properties, and applied torque, independently of the numerical integration scheme.
• RigidBodyRotationalModel: Implemented rigid-body rotational dynamics model based on Euler's equations of motion. It computes spacecraft angular acceleration from the current body-fixed angular velocity, inertia tensor, and aggregated applied torque, including gyroscopic cross-axis coupling.
• IIntegrator: Abstract numerical integration interface used to propagate both translational and rotational spacecraft states. It provides first- and second-order vector integration together with quaternion-based attitude propagation.
• EulerIntegrator: Current discrete-time integration implementation. It propagates translational state, angular velocity, and spacecraft attitude using explicit Euler-based integration and normalizes propagated attitude quaternions to preserve the unit-quaternion constraint.
• Dynamics: Runtime coordination component connecting propulsion outputs, physical state derivatives, and numerical state propagation for the complete 6DoF spacecraft state.
• IController: Interface for feedback control modules.
• PD Controller: Velocity-control component used for descent control and target tracking.
• IAutopilot: Interface for automated guidance and control logic.
• Adaptive Descent Controller: Energy-based landing controller using brake-ratio-guided mode switching and adaptive gain scheduling.
• InputArbiter: Control arbitration component that separates or prioritizes manual input and automated control commands.
• ISensor / SensorModel: Sensor abstraction and implementation used to compute telemetry quantities such as g-load and provide feedback for control and visualization.

Flow Summary

• The spacecraft provides the current translational and rotational state.
• Translational physics models compute linear acceleration from the active physical environment and applied forces.
• Propulsion models generate and aggregate body-fixed forces and torques.
• The rotational physics model computes angular acceleration from applied torque, angular velocity, and spacecraft inertia.
• The numerical integrator propagates velocity, position, angular velocity, and quaternion-based attitude.
• Control and automation modules generate commands without implementing physical state propagation themselves.
• Sensor models derive telemetry and feedback quantities from the propagated spacecraft state.

Propulsion Architecture

The propulsion subsystem is built around a central Thrust Orchestrator. Instead of treating propulsion as a single scalar output, the system supports multiple engines, multiple tanks, engine-specific runtime states, RCS allocation, vectorized force generation, torque generation, and aggregation of the resulting propulsion-induced forces and moments.

The main engine and RCS thrusters are modeled separately, but expose a common interface through IThrustModel.

Key Components and Relationships

• Thrust Orchestrator: Central propulsion manager. It registers engine models, forwards commands, advances propulsion states, applies fuel consumption, and aggregates the resulting body-fixed force and torque vectors for use by the translational and rotational dynamics models.
• IThrustModel: Abstract propulsion interface shared by main engines and RCS thrusters. It defines common access to engine identity, command input, thrust output, thrust direction, generated torque, fuel consumption, and tank assignment.
• BasicMainEngineModel: Implemented main engine model. It represents the main engine as scalar thrust magnitude with response dynamics, target tracking, direction handling, and propellant consumption.
• BasicRCSModel: Implemented low-order model of one individual RCS thruster. It represents a binary valve-controlled actuator with command delay, first-order rise and decay dynamics, scalar thrust output, and propellant consumption.
• RCSControlAllocator: Allocation helper that maps axis-based RCS vector commands to individual thruster commands. The vector command determines which thruster direction is required; the individual thruster receives its local command.
• EngineConfig: Static configuration for main engines, including identity, tank assignment, thrust parameters, response parameters, direction, and mounting position.
• RCSEngineConfig: Static configuration for RCS thrusters, including identity, axis assignment, tank assignment, nominal thrust, command delay, rise and decay time constants, direction, and mounting position.
• ME_ThrustState: Runtime state of the main engine. It stores current and commanded thrust quantities together with the propulsion-induced body-fixed torque and associated engine state information.
• RCS_ThrustState: Runtime state of one individual RCS thruster. It contains metadata, current and target thrust, normalized command state, actuator state, thrust direction, and the torque generated about the spacecraft center of mass.
• FuelTank: Tank representation used to assign and track fuel resources.
• FuelState: Runtime fuel state used by engine models to compute and apply mass flow.

Flow Summary

• The JSON spacecraft configuration defines tanks, main engines, RCS thrusters, thrust directions, and actuator mounting positions.
• The Thrust Orchestrator initializes one propulsion model per configured engine.
• Main engine commands are forwarded directly to the associated engine model.
• RCS vector commands are mapped by the RCSControlAllocator to individual RCS thruster commands.
• Each propulsion model updates its actuator state, thrust output, torque output, and fuel consumption.
• Engine thrust magnitudes and directions are combined into body-fixed force vectors.
• Off-center forces generate body-fixed torques about the spacecraft center of mass.
• The Thrust Orchestrator aggregates all propulsion-induced forces and torques.
• The resulting force and torque vectors are provided to the translational and rotational dynamics pipeline.

Command and Input Flow

Manual control input is processed separately from physical engine behavior. The frontend does not directly apply forces. Instead, operator input is converted into a command object, routed through the simulation control path, mapped to engine commands, and only then translated into physical thrust by propulsion models.

Current Command Path

• Keyboard input is captured by the cockpit frontend.
• The InputMapper converts key states into a FlightCommand.
• The command is forwarded through the current Qt signal-slot interface.
• SimControl and Spacecraft forward propulsion-relevant commands to the Thrust Orchestrator.
• The Thrust Orchestrator separates main engine and RCS commands.
• RCS commands are allocated to individual thrusters by the RCSControlAllocator.
• Engine models update actuator state, thrust output, and fuel consumption.
• The resulting propulsion forces and torques are used by the translational and rotational dynamics models during the next simulation step.

Telemetry and Frontend Data Boundary

The frontend and backend are separated by an explicit telemetry boundary. Backend domain objects remain internal to the simulation engine, while frontend-facing state is transferred through dedicated telemetry DTOs.

The TelemetryMapper translates the authoritative backend spacecraft state into TelemetryDTO structures. This prevents cockpit components from depending directly on backend domain models and establishes a stable communication contract for future frontend and ROS integrations.

Current Architecture

• Backend domain state: Internal spacecraft, propulsion, physics, fuel, and simulation state remains owned by the backend.
• TelemetryDTO: Explicit frontend-facing representation of simulation telemetry.
• TelemetryMapper: Implemented mapping layer translating backend domain state into telemetry DTOs.

Design Direction

• The frontend shall not depend on backend domain structures.
• The backend shall remain independent of Qt frontend classes.
• Telemetry contracts shall remain explicit and transport-independent.
• The cockpit frontend shall be replaceable without changing simulation logic.
• ROS2 integration can later reuse the established interface boundary.

Optimization Components

The backend contains experimental optimization components based on NLopt. These components are currently used for thrust optimization experiments and are separated from the real-time control and propulsion path.

• OptimizationModelParams: Parameter container for optimization runs.
• OptimizationStruct: Data structure for optimization state and results.
• ThrustOptimizationProblem: Problem formulation for thrust optimization.
• ThrustOptimizer: Optimization driver using NLopt.

Architectural Design Principles

• Separation of Concerns: Input handling, command routing, control, propulsion, physics, telemetry, and visualization are separated into distinct components.
• Interface-Based Extensibility: Physics, sensors, controllers, autopilots, integrators, and thrust models are exposed through interfaces where appropriate.
• Configuration-Driven Setup: Spacecraft engines, tanks, mass properties, and initial conditions are loaded from external configuration.
• Explicit Runtime State: Engine states, spacecraft states, telemetry states, and fuel states are modeled explicitly.
• 6DoF Rigid-Body Dynamics: Translational and rotational spacecraft motion are represented explicitly using Eigen vectors, matrices, and quaternions. Force and torque propagation, inertia-based rotational dynamics, angular velocity, and quaternion attitude together form the complete six-degree-of-freedom state.
• Frontend/Backend Decoupling: Direct dependency of the frontend on backend domain structs is temporary and will be replaced by DTO and ROS-based communication layers.
• Research Orientation: The system is designed for reproducible simulation runs, telemetry export, model validation, and future autonomous landing research campaigns.
• Open Engineering Philosophy: The project is developed as an open-source framework with emphasis on transparent architecture, modularity, reproducibility, and contribution-friendly evolution.