Skip to main content

Spaceflight Dynamics Framework Architecture

System Overview

The Spaceflight Dynamics Framework (SDF) is organized as a modular simulation application with explicit boundaries between the Qt frontend, the simulation worker, the interface layer, and the C++ simulation backend. Within the backend, simulation orchestration, spacecraft state, coordinate transformations, physics, propulsion, control, sensors, and numerical integration are represented by dedicated components. The current control architecture additionally contains dedicated automatic rotational control for angular-rate damping and quaternion attitude hold.

This page focuses on the concrete components, where they are located in the architecture, and which neighboring components they interact with. Runtime sequencing, state ownership over time, command timing, and the detailed movement of data through those components are documented separately on the SDF Runtime Data Flow page.

SDF system overview showing frontend, simulation worker, XML export, interface layer, backend simulation engine, physics, propulsion, and coordinate transformation components

Architectural Layers

  • Frontend / Application Layer: Qt-based UI components, page navigation, configuration selection, cockpit presentation, the simulation worker, telemetry history management, and XML export control.
  • Interface Layer: DTOs and mapping components that form the stable software boundary between frontend-facing representations and backend domain types.
  • Backend / Simulation Engine: Simulation orchestration, spacecraft state, coordinate systems, physics, propulsion, controllers, sensors, configuration interpretation, and numerical integration.
  • Simulation Models: Replaceable implementations behind interfaces for physics, propulsion, control, sensing, integration, and research-oriented extensions.

Frontend and Application Architecture

The frontend is structured around MainWindow as the application shell. It owns the persistent navigation, the page stack, shared application services, and the simulation thread boundary. Individual pages remain focused UI components rather than simulation controllers.

SimulationWorker is the application-side boundary to the simulation thread. It is connected to the UI through Qt signals and slots and collaborates with the interface layer for command and telemetry translation. It also owns application-level simulation-session concerns such as telemetry history and export requests.

Scientific telemetry export is represented by the dedicatedTelemetryXmlExporter. The exporter is associated with the worker-side telemetry history and is responsible only for XML serialization. It does not belong to the physics backend and does not own simulation state.

SDF frontend architecture showing MainWindow, pages, SimulationWorker, telemetry history, XML export, and the interface boundary

Frontend and Application Components

  • MainWindow: Central Qt application shell. It connects the top bar, page stack, configuration management, simulation thread, andSimulationWorker.
  • TopBarWidget: Persistent application navigation and global controls. It is owned by MainWindow and provides access to application-wide functions including telemetry export controls.
  • QStackedWidget: Page container owned byMainWindow for switching between the application pages.
  • Homepage: Landing page and navigation entry point. It does not own simulation infrastructure.
  • SpacecraftSelectionPage: Configuration-selection UI that works with the shared ConfigManager.
  • cockpitPage: Main simulation presentation page. It is connected to SimulationWorker for telemetry and command exchange and contains cockpit-specific widgets. The cockpit exposes dedicated Kill Rotation and Stabilize controls for automatic rotational control.
  • ControlsHelpPage: Static user-facing control reference.
  • SettingsPage: Application page reserved for the settings subsystem planned for the research-oriented release line.
  • ConfigManager: Shared frontend/application service for selecting and supplying JSON spacecraft configurations.
  • inputmapper: Cockpit-side input component that creates manual translational and rotational RCS commands. Automatic attitude-mode flags remain owned by the dedicated cockpit controls and are preserved when manual axis commands are updated.
  • LandingView: Cockpit visualization component for landing geometry, trajectory, velocity, and RCS indication.
  • UIBuilder: Shared helper for consistent frontend widgets, labels, controls, and telemetry presentation elements.
  • SimulationWorker: Simulation-thread boundary and application coordinator for the active simulation session. It communicates withcockpitPage/MainWindow, the interface layer, and telemetry recording/export components.
  • TelemetryXmlExporter: XML serialization component used by the worker-side export feature. It consumes recorded telemetry snapshots and writes the scientific telemetry document without depending on backend physics classes.

Interface Layer Architecture

The interface layer is the explicit software boundary between the Qt application and the backend domain model. It prevents frontend classes from depending directly on backend spacecraft, physics, propulsion, or frame structures.

Interface Components

  • FlightCommandDTO: Frontend-facing command contract used by cockpit/input components and SimulationWorker. In addition to manual engine and RCS commands, the DTO contains explicitkillRotation and stabilize mode requests.
  • TelemetryDTO: Frontend-facing telemetry contract used by cockpit visualization, worker-side recording, and XML export. It includes the active automatic attitude-control state so verification data can be associated unambiguously with Kill Rotation or Stabilize operation.
  • TelemetryMapper: Translation component connecting DTOs with backend command and simulation-data structures. It is used bySimulationWorker on the application side and communicates withsimcontrol/simData on the backend side.

The DTOs are value-oriented contracts rather than shared backend domain objects. This boundary can later be reused or adapted for additional transports such as ROS2 without coupling cockpit widgets to simulation-core classes.

Backend Architecture

The backend is a modular C++ simulation engine centered aroundspacecraft and its associated runtime state. The backend separates orchestration, configuration interpretation, coordinate handling, physical models, propulsion, integration, control, and sensing into distinct responsibilities.

Eigen provides the common mathematical foundation for vectors, matrices, and quaternions across the simulation core. Coordinate-system concerns are kept in dedicated context and transformation components rather than embedded in the UI or configuration layer.

SDF backend architecture showing SimControl, spacecraft, state and frame contexts, coordinate transformation, physics, propulsion, configuration, and research components

Backend Core Components

  • simcontrol: Backend orchestration component. It connects the interface boundary with the active spacecraft instance and coordinates backend subsystem participation in a simulation session.
  • spacecraft: Central backend domain object. It owns the authoritative StateVector and collaborates with propulsion, physics, mission/frame contexts, coordinate transformation, sensors, and configuration-derived vehicle data.
  • StateVector: Dynamic spacecraft-state container owned byspacecraft. It provides the state consumed by physics, frame derivation, control, sensing, and telemetry aggregation.
  • MissionContext: Mission-reference component associated withspacecraft. It contains persistent mission references such as the configured landing-site definition and the corresponding reference-frame representations.
  • SimulationFrameContext: Runtime frame-view component associated with spacecraft. It groups the spacecraft state as represented in MCI, MCMF, MSC, ENU, LVLH, and SBF-related forms for consumers that require those representations.
  • CoordinateTransformer: Stateless/compute-oriented coordinate subsystem used by spacecraft and frame-context construction for transformations between MCI, MCMF, MSC, ENU, LVLH, and SBF representations.
  • jsonConfigReader: Backend configuration interpreter. It creates backend configuration structures from external JSON and supplies spacecraft, propulsion, fuel, initial-state, and mission-reference data.
  • customSpacecraft: Configuration-side spacecraft data model populated by jsonConfigReader and consumed during spacecraft construction/initialization.
  • simData: Backend-facing aggregate representation used at the interface boundary. It references state, frame, mission, propulsion, fuel, sensor, integrity, console, automatic attitude-control mode, and simulation-time information without exposing the completespacecraft object to the frontend.

Backend Structural Relationships

  • simcontrol is the backend entry point used by the interface layer.
  • simcontrol owns or manages the active spacecraft instance.
  • spacecraft is the hub connecting state, propulsion, physics, frames, and sensing.
  • StateVector, MissionContext, and SimulationFrameContext remain distinct domain structures with different responsibilities.
  • CoordinateTransformer is shared by frame-related backend components rather than duplicated across subsystems.
  • simData forms the backend side of the telemetry/interface boundary.

Physics Architecture

The physics subsystem contains the components responsible for translational and rotational rigid-body dynamics and the numerical integration interfaces used by the spacecraft model. Physical models, integration algorithms, and feedback-control components are intentionally represented by separate abstractions. Automatic attitude control remains outside the rigid-body equations and influences spacecraft motion only through the normal RCS actuation path.

SDF physics architecture showing translational and rotational models, integration interfaces, dynamics coordination, controllers, and sensors

Physics and Control Components

  • IPhysicsModel: Abstract interface for translational environmental/acceleration models used by the physics subsystem.
  • BasicMoonGravityModel: Current lunar gravity-model implementation behind the translational physics interface.
  • IRotationalPhysicsModel: Interface for rotational rigid-body models.
  • RigidBodyRotationalModel: Euler-equation-based rotational dynamics implementation used with spacecraft inertia and body angular state.
  • IIntegrator: Numerical integration abstraction shared by translational, rotational, and quaternion state updates.
  • EulerIntegrator: Current concrete implementation ofIIntegrator.
  • Dynamics: Coordination component connecting spacecraft state, physical models, applied loads, and the selected integrator.
  • IController: Generic feedback-controller interface. In addition to scalar control operations, it exposes a quaternion-based three-axis control function used by the attitude-control subsystem.
  • PD Controller: Concrete feedback-controller implementation used by both the descent-control architecture and the quaternion attitude controller. For attitude control, it combines quaternion-error feedback with body angular-rate damping.
  • IAttitudeControl: Dedicated interface for automatic rotational-control modes. It separates the attitude-control contract from both simulation orchestration and the physical rigid-body model.
  • AttitudeController: Concrete implementation ofIAttitudeControl. It provides Kill Rotationfor angular-rate damping and Stabilize for quaternion attitude hold. Stabilize captures the current orientation as its reference attitude and applies a hysteresis band around the settled state to reduce repeated RCS switching.
  • IAutopilot: Interface for automated guidance/control logic.
  • Adaptive Descent Controller: Current automated descent controller connected to the main-engine control subsystem.
  • InputArbiter: Control-authority component positioned between manual and automated command producers and the backend actuation path. Main engine, translational RCS, and rotational RCS authority can be resolved independently so automatic attitude control does not replace unrelated manual channels.
  • ISensor / SensorModel: Sensor abstraction and concrete sensor components attached to the simulation state for telemetry and feedback consumers.

Structural Relationships

  • spacecraft uses the physics/dynamics subsystem for state propagation.
  • Dynamics connects physics-model and integrator abstractions.
  • Propulsion supplies the loads consumed by the dynamics subsystem.
  • Controllers and autopilot components are separated from the physical models and connect through the control architecture.
  • AttitudeController consumes spacecraft attitude and angular velocity but does not directly modify the StateVector.
  • Automatic rotational commands are resolved by InputArbiter before reaching the RCS actuation subsystem.
  • Sensor components observe simulation state without becoming state owners.

Propulsion Architecture

The propulsion subsystem models main engines, RCS thrusters, fuel assignment, actuator state, and propulsion-induced loads behind a common orchestration layer. Main-engine and RCS models are separate concrete implementations but share the IThrustModel abstraction where appropriate.

SDF propulsion architecture showing Thrust orchestrator, main-engine and RCS models, allocator, configuration, runtime states, and fuel components

Propulsion Components

  • Thrust Orchestrator: Central propulsion component owned or used by spacecraft. It manages engine-model instances and forms the connection between spacecraft control requests, propulsion models, fuel, and the dynamics subsystem.
  • IThrustModel: Common engine-model interface exposing engine identity, command/state access, thrust, direction, torque, fuel consumption, and tank assignment.
  • BasicMainEngineModel: Concrete main-engine model implementing the main propulsion actuator behavior.
  • BasicRCSModel: Concrete model for an individual RCS thruster.
  • RCSControlAllocator: RCS allocation component positioned between spacecraft control requests and individual RCS engine models. It is also the actuator-side consumer of automatic rotational commands generated by Kill Rotation or Stabilize.
  • EngineConfig / RCSEngineConfig: Static configuration objects supplied from spacecraft configuration and associated with the corresponding engine-model instances.
  • ME_ThrustState / RCS_ThrustState: Runtime propulsion-state structures associated with main-engine and RCS models and exposed to telemetry consumers.
  • FuelTank / FuelState: Propellant-resource components shared by the configured propulsion models and spacecraft mass/fuel accounting.

Structural Relationships

  • spacecraft connects the control side, Thrust, and the dynamics subsystem.
  • Thrust owns/manages the concrete main-engine and RCS model instances.
  • RCSControlAllocator is specific to the RCS branch of the propulsion architecture.
  • Engine configurations are static inputs; thrust-state structures represent the corresponding runtime actuator state.
  • Fuel components are referenced by propulsion models and spacecraft-level resource accounting.

Telemetry, Recording, and Export Architecture

Telemetry spans three architectural areas: backend aggregation, interface-layer translation, and frontend/application consumption. The components are deliberately separated so cockpit presentation and scientific export can use the same frontend-facing telemetry contract without depending directly on backend domain classes.

Telemetry Components and Connections

  • simData: Backend aggregate attached tospacecraft/simcontrol and consumed by the interface layer.
  • TelemetryMapper: Interface-layer component connecting backend simData with the frontend-facingTelemetryDTO representation.
  • TelemetryDTO: Shared application-facing value contract used by cockpitPage, SimulationWorker telemetry history, and the export subsystem. The DTO contains explicit automation-state fields for killRotationActive and stabilizeActive.
  • SimulationWorker: Application-side owner of telemetry history and the connection point between simulation-thread telemetry, frontend presentation, and export requests.
  • TelemetryXmlExporter: Dedicated serializer connected to the recorded telemetry history. It produces XML output while remaining separate from backend simulation and physics components.
  • cockpitPage / LandingView: UI consumers connected to the worker-provided telemetry representation.

For snapshot timing, recording semantics, history handling, lifecycle behavior, and the detailed relationship between cockpit output and XML export, see Runtime Data Flow.

Optimization Components

The backend contains experimental optimization components based on NLopt. They are structurally separated from the real-time simulation loop and remain research-oriented extensions rather than dependencies of the core simulation architecture.

  • OptimizationModelParams: Parameter container for optimization runs.
  • OptimizationStruct: Data structure for optimization state and results.
  • ThrustOptimizationProblem: Optimization problem formulation.
  • ThrustOptimizer: NLopt-based optimization driver.

Architectural Design Principles

  • Separation of Concerns: UI, application/session management, interface translation, backend orchestration, physics, propulsion, control, sensing, and export are represented by distinct components.
  • Explicit Boundaries: DTOs and TelemetryMapperisolate frontend/application code from backend domain structures.
  • Centralized Spacecraft Domain: spacecraft is the backend hub for state and vehicle-specific subsystem composition, while supporting contexts remain separate domain structures.
  • Interface-Based Extensibility: Physics, rotational models, integrators, propulsion models, generic controllers, attitude-control implementations, autopilots, and sensors expose replaceable interfaces where appropriate.
  • Configuration-Driven Composition: Spacecraft, mission, propulsion, fuel, and initial-state configuration are supplied externally and interpreted by dedicated configuration components.
  • Dedicated Coordinate Subsystem: Frame transformations and mission/runtime frame representations remain explicit backend components.
  • Reusable Telemetry Contract: Cockpit visualization, recording, and XML export share the same application-facing telemetry representation rather than creating independent simulation interfaces.
  • Research Orientation: Optimization and future communication extensions can be attached without collapsing the existing subsystem boundaries.