# chandu-8/space-probe-simulator architecture

> Architecture diagram of the GitHub repository chandu-8/space-probe-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chandu-8/space-probe-simulator
- Repository: https://github.com/chandu-8/space-probe-simulator

## Overview

##### Project Type and Purpose
- This project is a physics-engine based simulation designed to model a space mission to Titan. It encompasses numerical ODE solvers (Euler, Runge-Kutta, Verlet) for trajectory simulation, closed-loop control via a PID controller for the landing phase, and a wind simulation module to mimic Titan’s actual environmental conditions.

##### Analyzing the File Structure
- The Java code is organized under the “app/src/main/java/titan” package, broken into sub-packages:
- bodies (CelestialBody): Models for celestial objects.
- controllers (FlightController, PIDController): Manage in-flight corrections and landing control.
- interfaces: Define key contracts such as ProbeSimulatorInterface, SolverInterface, etc.
- landing: Contains classes like Lander and Landing2D for modeling landing sequences.
- math: Provides mathematical utilities (Matrix, Vector3d, Vector4d) that underpin the simulation.
- pathplanner: Includes classes for trajectory optimization (GradientDescent, NewtonRaphsonSecondVersion, etc.).
- probe: Implements components such as ProbeSimulator, Rocket, and Tsiolkovsky for propulsion dynamics.
- solarsystem: Represents the solar system model.
- solver: Houses various numerical solvers – EulerSolver, RungeKuttaSolver, VerletSolver – and associated classes like Position, Rate, and State.
- windsimulation: Contains the StochasticWindModel for realistic simulation of Titan’s wind.

a. Main Components:
- Graphical User Interface (GUI): Built using JavaFX to allow user interaction with the simulation.
- Simulation Engine: The core module running the simulation loop that integrates physics calculations, invoking numerical solvers.
- Numerical Solvers: Components that include Euler, Runge-Kutta, and Verlet methods for computing probe trajectories.
- Control Systems: Consisting of both the FlightController and PIDController that maintain stable trajectories and manage descent.
- Trajectory Planning & Optimization: The pathplanner package focuses on cost calculation (CostFunction, PlanningCost) and optimization techniques (GradientDescent, NewtonRaphson) for route corrections.
- Environmental and Celestial Models: Includes the modeling of celestial bodies (in the “bodies” and “solarsystem” packages) and the simulation of environmental factors (wind simulation module).
- Domain-Specific Libraries: Utilities such as mathematical classes (matrix and vector operations) needed across modules.

b. Relationships and Interactions:
- The GUI serves as the entry point, sending user commands to the Simulation Engine.
- The Simulation Engine acts as the central coordinator, calling the appropriate numerical solver (from the solver package) to update the state of the probe and celestial bodies.
- The Control Systems continuously receive simulation state inputs to adjust trajectory and landing via the FlightController/PIDController.
- The Trajectory Planner uses algorithms from the pathplanner package to refine the flight path and ensure efficient fuel usage.
- Environmental inputs from the StochasticWindModel influence the simulation by modifying the dynamics applied within the Simulation Engine.

c. Architectural Patterns/Design Principles:
- Modular Separation: Each functional part (solvers, controllers, GUI, etc.) is split into separate packages, promoting encapsulation.
- Interface-Driven Design: Use of Java interfaces (e.g., ProbeSimulatorInterface, SolverInterface) to abstract details and allow flexibility in swapping out implementations.
- Layered Architecture: Different layers such as presentation (JavaFX GUI), business logic (simulation loop, control systems), and data/model (celestial bodies, wind model).

d. Highlighted Technologies, Frameworks, and Tools:
- Java SE 8 or higher (along with JavaFX for GUI).
- Gradle for build automation and dependency management.
- Numerical libraries and custom mathematical utilities (Matrix, Vector3d, etc.) are core to simulation accuracy.

##### Elements
- Each component should have a clear label (e.g., “Simulation Engine”, “Euler Solver”, “PID Controller”).
▪ Another for core simulation logic/engine.
▪ Yet another for external/environment modules (wind simulation, celestial modeling).
- Annotations to highlight important interactions; for example, note that the Simulation Engine integrates the outputs of multiple numerical methods together with control inputs to update probe trajectories.

##### Putting It All Together
- Divide the engine into sub-components: Numerical Solvers (branch further into Euler, Runge-Kutta, Verlet), Control Systems, Trajectory Planning, and Environmental Models.
- Data flow and feedback loops (e.g., sensor/control data feedback between FlightController and Simulation Engine).
- That any dependencies (like the mathematical library utilities) are shown as shared components used by several modules.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        GUI["GUI (JavaFX)"]:::presentation
    end

    %% Core Simulation Engine
    subgraph "Core Simulation Engine"
        SE["Simulation Engine"]:::engine
    end

    %% Numerical Solvers
    subgraph "Numerical Solvers"
        ES["Euler Solver"]:::solver
        RKS["Runge-Kutta Solver"]:::solver
        VS["Verlet Solver"]:::solver
    end

    %% Control Systems
    subgraph "Control Systems"
        FC["Flight Controller"]:::control
        PC["PID Controller"]:::control
    end

    %% Trajectory Planning & Optimization
    subgraph "Trajectory Planning"
        GD["Gradient Descent Optimizer"]:::trajectory
        NR["Newton-Raphson Optimizer"]:::trajectory
    end

    %% Environmental Models
    subgraph "Environmental Models"
        WIND["Wind Simulation Model"]:::environmental
    end

    %% Celestial and Domain Models
    subgraph "Celestial & Domain Models"
        CB["Celestial Bodies"]:::celestial
        SS["Solar System Model"]:::celestial
    end

    %% Mathematical Libraries
    subgraph "Mathematical Libraries"
        MATH["Matrix & Vectors"]:::math
    end

    %% Data Flow Connections
    GUI -->|"sends commands"| SE
    SE -->|"computes trajectories"| ES
    SE -->|"computes trajectories"| RKS
    SE -->|"computes trajectories"| VS
    SE -->|"control feedback"| FC
    SE -->|"control feedback"| PC
    SE -->|"optimizes route"| GD
    SE -->|"optimizes route"| NR
    SE -->|"applies environment"| WIND
    SE -->|"updates models"| CB
    SE -->|"updates models"| SS
    SE -->|"uses math utils"| MATH
    
    %% Feedback loops from Control Systems to Simulation Engine
    FC -->|"feedback"| SE
    PC -->|"feedback"| SE

    %% Styles
    classDef presentation fill:#FFDDC1,stroke:#333,stroke-width:2px;
    classDef engine fill:#C1FFD7,stroke:#333,stroke-width:2px;
    classDef solver fill:#C1D4FF,stroke:#333,stroke-width:2px;
    classDef control fill:#FFD1DC,stroke:#333,stroke-width:2px;
    classDef trajectory fill:#E2C2FF,stroke:#333,stroke-width:2px;
    classDef environmental fill:#FFFACD,stroke:#333,stroke-width:2px;
    classDef celestial fill:#DCD0FF,stroke:#333,stroke-width:2px;
    classDef math fill:#D1E7DD,stroke:#333,stroke-width:2px;

    %% Click Events
    click GUI "https://github.com/chandu-8/space-probe-simulator/blob/main/app/src/main/java/App.java"
    click SE "https://github.com/chandu-8/space-probe-simulator/blob/main/app/src/main/java/titan/probe/ProbeSimulator.java"
    click ES "https://github.com/chandu-8/space-probe-simulator/blob/main/app/src/main/java/titan/solver/EulerSolver.java"
    click RKS "https://github.com/chandu-8/space-probe-simulator/blob/main/app/src/main/java/titan/solver/RungeKuttaSolver.java"
    click VS "https://github.com/chandu-8/space-probe-simulator/blob/main/app/src/main/java/titan/solver/VerletSolver.java"
    click FC "https://github.com/chandu-8/space-probe-simulator/blob/main/app/src/main/java/titan/controllers/FlightController.java"
    click PC "https://github.com/chandu-8/space-probe-simulator/blob/main/app/src/main/java/titan/controllers/PIDController.java"
    click GD "https://github.com/chandu-8/space-probe-simulator/blob/main/app/src/main/java/titan/pathplanner/GradientDescent.java"
    click NR "https://github.com/chandu-8/space-probe-simulator/blob/main/app/src/main/java/titan/pathplanner/NewtonRaphsonSecondVersion.java"
    click WIND "https://github.com/chandu-8/space-probe-simulator/blob/main/app/src/main/java/titan/windsimulation/StochasticWindModel.java"
    click CB "https://github.com/chandu-8/space-probe-simulator/blob/main/app/src/main/java/titan/bodies/CelestialBody.java"
    click SS "https://github.com/chandu-8/space-probe-simulator/blob/main/app/src/main/java/titan/solarsystem/SolarSystem.java"
    click MATH "https://github.com/chandu-8/space-probe-simulator/blob/main/app/src/main/java/titan/math/Matrix.java"
```
