# kgolemo/f1-racing-line-optimization architecture

> Architecture diagram of the GitHub repository kgolemo/f1-racing-line-optimization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kgolemo/f1-racing-line-optimization
- Repository: https://github.com/kgolemo/f1-racing-line-optimization

## Overview

##### Project type and purpose
- This is an open-source reinforcement-learning (RL) application whose goal is to optimize the racing line of an F1 car.
- Key indicators: Python scripts for environment (car.py, track.py), RL training (ray_training.py), rollouts (ray_rollout.py), evaluation/rendering (render_agents.py, race.py), and saved states (exported_states/*.npy).

##### File structure
- Core environment modules:
– car.py: vehicle dynamics, state transitions
– track.py: circuit geometry
– utils.py: shared helpers (e.g., state preprocessing)
- Training pipeline:
– ray_training.py: orchestrates RLlib training, defines policy, hyperparameters
– exported_states/: stores checkpoints and rollouts in NumPy format
- Rollout & evaluation:
– ray_rollout.py: uses trained policy to generate trajectories
– render_agents.py, race.py, manual_mode.py, use_agent.py: interactive and batch–mode evaluation and visualization
- Assets & media:
– imgs/, media/: animations and GIFs for README
- Configuration & dependencies:
– No Docker or CI scripts found; Python requirements inferred via imports (NumPy, Ray RLlib, Gym-style interfaces).

##### README for additional insights
- Confirms RL application for game-style simulation based on a Toward Data Science article.

a. Main components:
1. Environment Layer
– Car Dynamics (car.py)
– Track Geometry (track.py)
– Utilities (utils.py)
2. RL Training Layer
– Ray RLlib Trainer (ray_training.py)
– Hyperparameter Config
3. Data Storage
– Checkpoint Store (exported_states/*.npy)
4. Rollout & Evaluation Layer
– Rollout Engine (ray_rollout.py)
– Interactive/Evaluation Scripts (race.py, manual_mode.py, use_agent.py)
5. Visualization Layer
– Renderer (render_agents.py)
– Media Assets (imgs/, media/)
6. External Services
– Ray Cluster / Local Ray instance

b. Relationships & interactions:
- Trainer ↔ Environment: Trainer samples episodes via Gym-style interaction with car/track modules.
- Trainer → Data Storage: Periodically writes checkpoints (.npy).
- Rollout Engine → Data Storage: Reads checkpoints to generate trajectories.
- Rollout Engine → Visualization: Feeds trajectories to render_agents or race for playback.
- Interactive Scripts → Environment: manual_mode & use_agent hook into the same environment for testing.

c. Architectural patterns & design principles:
- Modular separation: environment, training, rollout/eval, rendering
- External orchestration via Ray: supports distributed training and rollout

d. Key technologies & frameworks:
- Python 3.x
- NumPy for state storage
- Ray RLlib for distributed RL training
- Gym-style environment interfaces
- Matplotlib / custom rendering in render_agents.py

##### Essential elements
- Don’t omit any script that plays a role in the RL loop.
- Every directory of assets or data storage.
- Both automated (ray_training, ray_rollout) and interactive (manual_mode, use_agent) paths.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment Layer
    subgraph "Environment Layer"
        direction TB
        Car["Car Dynamics"]:::env
        Track["Track Geometry"]:::env
        Utils["Shared Utilities"]:::env
    end

    %% RL Training Layer
    subgraph "RL Training Layer"
        direction TB
        Trainer["RL Trainer"]:::proc
    end

    %% Data Storage
    subgraph "Data Storage"
        direction TB
        Storage(("Checkpoint Store")):::storage
    end

    %% Rollout & Evaluation Layer
    subgraph "Rollout & Evaluation Layer"
        direction TB
        Rollout["Rollout Engine"]:::proc
        Race["Batch Evaluation (race.py)"]:::proc
        Manual["Interactive Manual Mode"]:::proc
        UseAgent["Agent-Based Testing"]:::proc
    end

    %% Visualization Layer
    subgraph "Visualization Layer"
        direction TB
        Renderer["Renderer & Plotting"]:::viz
        Imgs["Static Media Assets"]:::viz
        Media["Animations & GIFs"]:::viz
    end

    %% External Service
    RayCluster["Ray Cluster / Local Ray"]:::external

    %% Connections
    Car -->|"state/action"| Trainer
    Track -->|"state"| Trainer
    Utils -->|"helpers"| Trainer
    RayCluster -.->|"orchestrates"| Trainer
    Trainer -.->|"checkpoint save"| Storage
    Storage -->|"load states"| Rollout
    RayCluster -.->|"distribution"| Rollout
    Rollout -->|"trajectories"| Race
    Rollout -->|"trajectories"| Renderer
    Race -->|"playback data"| Renderer
    Manual -->|"env interaction"| Car
    UseAgent -->|"env interaction"| Car
    Race -->|"optional feedback"| Trainer
    Renderer -->|"renders to"| Imgs
    Renderer -->|"renders to"| Media

    %% Click Events
    click Car "https://github.com/kgolemo/f1-racing-line-optimization/blob/main/car.py"
    click Track "https://github.com/kgolemo/f1-racing-line-optimization/blob/main/track.py"
    click Utils "https://github.com/kgolemo/f1-racing-line-optimization/blob/main/utils.py"
    click Trainer "https://github.com/kgolemo/f1-racing-line-optimization/blob/main/ray_training.py"
    click Storage "https://github.com/kgolemo/f1-racing-line-optimization/tree/main/exported_states/"
    click Rollout "https://github.com/kgolemo/f1-racing-line-optimization/blob/main/ray_rollout.py"
    click Race "https://github.com/kgolemo/f1-racing-line-optimization/blob/main/race.py"
    click Manual "https://github.com/kgolemo/f1-racing-line-optimization/blob/main/manual_mode.py"
    click UseAgent "https://github.com/kgolemo/f1-racing-line-optimization/blob/main/use_agent.py"
    click Renderer "https://github.com/kgolemo/f1-racing-line-optimization/blob/main/render_agents.py"
    click Imgs "https://github.com/kgolemo/f1-racing-line-optimization/tree/main/imgs/"
    click Media "https://github.com/kgolemo/f1-racing-line-optimization/tree/main/media/"

    %% Styles
    classDef env fill:#9BC1F3,stroke:#333,stroke-width:1px
    classDef proc fill:#C6E5B5,stroke:#333,stroke-width:1px,rx:5,ry:5
    classDef storage fill:#F6E58D,stroke:#333,stroke-width:1px
    classDef viz fill:#F9E79F,stroke:#333,stroke-width:1px,shape:ellipse
    classDef external fill:#F5B7B1,stroke:#333,stroke-width:1px,shape:hexagon
```
