# dt-g7/lunar_lander_ai architecture

> Architecture diagram of the GitHub repository dt-g7/lunar_lander_ai, 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/dt-g7/lunar_lander_ai
- Repository: https://github.com/dt-g7/lunar_lander_ai

## Overview

##### Main Components
- Environment & Simulation Module:
- The core environment is implemented in src/lunar_lander/Lunar_Lander_custom_env.py.
- The physics simulation is defined in src/lunar_lander/physics.py.
- Rendering is handled in src/lunar_lander/rendering.py using Pygame.
- Training Module:
- The training script (src/lunar_lander/custom_run.py) uses Stable-Baselines3 PPO to interact with the custom environment.
- The PPO model receives state observations from the environment (6-dimensional: dx, dy, x_velocity, y_velocity, angle, angular_velocity) and sends actions (continuous thrust and torque) back.
- Model Management:
- Models are saved and stored in directories such as custom_lunar (for “best” model checkpoints) and models/PPO (with many iteration checkpoints).
- Utility scripts (load.py and load_model_not_trained.py) are provided for loading pre-trained or untrained models.
- Logging & Monitoring:
- The logs/ directory captures TensorBoard logs generated during training.

##### Relationships and Interactions
- The Training Module (custom_run.py) interacts with:
- The Environment Module (Lunar_Lander_custom_env.py, physics.py, rendering.py) to simulate each training episode.
- The PPO agent from Stable-Baselines3 which computes updates from state transitions, rewards, and actions.
- The Model Management layer:
- Saves periodic checkpoints and best models.
- Provides loading pathways (through load.py and load_model_not_trained.py).
- Logging:
- Continuously records training events and metrics; data flows to TensorBoard when executed via tensorboard --logdir logs.
- External Dependencies:
- The system relies on external libraries such as Box2D and Pygame for simulation and rendering, Gymnasium for environment interface, and Stable-Baselines3 for the learning algorithm.

##### Architectural Patterns and Design Principles
- Modularity: The project is segmented into clearly defined modules (environment, physics, rendering, training, logging, model loading) that can be diagrammed separately.
- Separation of Concerns: Core environment simulation (physics and rendering) is decoupled from the training logic, which in turn is separate from model management.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Dependencies
    subgraph "External Dependencies"
        GYM["Gymnasium"]:::external
        BOX["Box2D"]:::external
        PG["Pygame Library"]:::external
        SB3["Stable-Baselines3"]:::external
    end

    %% Environment & Simulation Module
    subgraph "Environment & Simulation Module"
        ENV["Lunar_Lander_custom_env.py"]:::internal
        PHY["Physics Simulation (physics.py)"]:::internal
        REN["Rendering (Pygame) (rendering.py)"]:::internal
    end

    %% Training Module
    subgraph "Training Module"
        TRAIN["Training Script (custom_run.py)"]:::internal
    end

    %% Model Management
    subgraph "Model Management"
        BEST["Best Model Checkpoints"]:::management
        PPO["PPO Model Checkpoints"]:::management
        UTIL1["Utility Script: load.py"]:::management
        UTIL2["Utility Script: load_model_not_trained.py"]:::management
    end

    %% Logging & Monitoring
    subgraph "Logging & Monitoring"
        LOG["TensorBoard Logs (logs)"]:::logging
    end

    %% Interactions between modules
    TRAIN -->|"ActionRequest"| ENV
    ENV -->|"StateObservation&Rewards"| TRAIN

    %% Internal environment components
    ENV -->|"usesPhysics"| PHY
    ENV -->|"usesRendering"| REN

    %% Training to model management and logging
    TRAIN -->|"SaveModel"| BEST
    TRAIN -->|"SaveCheckpoint"| PPO
    TRAIN -->|"LoadModel"| UTIL1
    TRAIN -->|"LoadModel"| UTIL2
    TRAIN -->|"LogMetrics"| LOG

    %% External dependencies integration
    GYM -->|"interface"| ENV
    BOX -->|"physicsEngine"| PHY
    PG -->|"renderingCall"| REN
    SB3 -->|"PPOAgent"| TRAIN

    %% Styling classes
    classDef internal fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef management fill:#F1F8E9,stroke:#8BC34A,stroke-width:2px;
    classDef logging fill:#FCE4EC,stroke:#F06292,stroke-width:2px;
    classDef external fill:#FFECB3,stroke:#FF9800,stroke-width:2px;

    %% Click Events
    click ENV "https://github.com/dt-g7/lunar_lander_ai/blob/main/src/lunar_lander/Lunar_Lander_custom_env.py"
    click PHY "https://github.com/dt-g7/lunar_lander_ai/blob/main/src/lunar_lander/physics.py"
    click REN "https://github.com/dt-g7/lunar_lander_ai/blob/main/src/lunar_lander/rendering.py"
    click TRAIN "https://github.com/dt-g7/lunar_lander_ai/blob/main/src/lunar_lander/custom_run.py"
    click BEST "https://github.com/dt-g7/lunar_lander_ai/tree/main/custom_lunar"
    click PPO "https://github.com/dt-g7/lunar_lander_ai/tree/main/models/PPO"
    click UTIL1 "https://github.com/dt-g7/lunar_lander_ai/blob/main/load.py"
    click UTIL2 "https://github.com/dt-g7/lunar_lander_ai/blob/main/load_model_not_trained.py"
    click LOG "https://github.com/dt-g7/lunar_lander_ai/tree/main/logs"
```
