# wayveai/mile architecture

> Architecture diagram of the GitHub repository wayveai/mile, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wayveai/mile
- Repository: https://github.com/wayveai/mile

## Overview

##### Project Type and Purpose
- The project is a research implementation in the field of model-based imitation learning for urban driving. It integrates data collection, training, and evaluation components with simulation (using CARLA) to train a driving policy that operates “in imagination.”
- The README, together with the file tree, indicates that the system is designed to interact with the CARLA simulator, process sensor and map data (e.g., bird's-eye view, RGB camera inputs), and drive using both RL-based and imitation learning approaches.

##### Main Components

a. Simulation & Environment Interface (carla_gym)
- The “carla_gym” package encapsulates the environment interface and simulation specifics:
- The “core” folder includes various observation managers that handle input data (birdview, camera, navigation, etc.), object detection (object_finder), and task-related components.
- “envs” which describe different simulation scenarios and test cases (e.g., LeaderBoard scenarios with various Town configurations).
- “utils” to support key functionalities such as map transformations and weather simulation.
- This part as the simulation/environment wrapper that interfaces directly with the external CARLA simulator.

b. Training, Inference & Model Components (mile)
- The “mile” directory holds the core learning components:
- “agents” that include both the imitation-based “mile_agent” and the RL-based “rl_birdview_agent.”
- “models” representing the neural network architectures (e.g., world model, policy network, auxiliary processing layers).
- “trainer.py” and other utilities (e.g., losses, preprocessing, data handling) for training the driving policy.
- “configs” containing YAML configuration files to set up experiments (debug, one_frame, mile, etc.).
- This section should be illustrated as the “brain” of the system with flows for training input, forward passes through models, and feedback from loss calculations and policy evaluations.

c. Data Collection & Evaluation Pipeline
- Scripts and configurations for:
- Data collection (e.g., run/data_collect.sh, config/data_collect.yaml) that collect simulation data from CARLA.
- Evaluation (e.g., run/evaluate.sh) which runs the pre-trained model and evaluates it in the simulation environment.
- These components are critical for the full lifecycle: they provide the data that feeds into training and assess the performance of the model in simulated environments.

d. Configuration and Utility Layers
- “config” directory: Contains configuration files for agents, training, and test suites.
- “utils”: Common utilities such as saving checkpoints, managing network-related tasks, and server utilities.
- That these utilities support and glue the main components together.

e. External Dependencies
- PyTorch: Indicate that the training/inference backend is implemented using PyTorch.
- Any other relevant libraries (e.g., conda for environment management, YAML for configuration, etc.).

##### Relationships and Interactions

- Data Flow:
- The output of the model (driving policy) then influences vehicle simulation within the CARLA environment.
- Training loop feedback should be shown from the trainer and loss components back onto model parameters.

- Dependency Links:
- Configuration files (from the config folder) to both the simulation environment (which they help parameterize) and the training pipeline.
- Role of utility functions in each subsystem, acting as common services for processing data, transforming coordinates, managing weather, etc.

##### Architectural Patterns and Design Principles

- Modularity: The separation between carla_gym (simulation interfacing) and mile (model training and inference) indicates a modular design where changes in simulation or modeling can be developed separately.
- Configuration-Driven Design: With several configuration files driving agent parameters, observation setups, and test suites, note how every component is highly configurable.
- Layered Architecture: From low-level sensor data processing in the observation manager to high-level learning and policy evaluation, the design follows a layered approach.

##### Final Steps

- Reference the test suites and scenario descriptions as input sources/configurations for simulation runs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    External1["CARLA Simulator"]:::external
    External2["PyTorch"]:::external

    %% Configuration & Utility Layers
    subgraph "Configuration & Utility Layers"
        Config["Experiment Configurations (config/)"]:::utility
        CommonUtil["Common Utilities (utils/)"]:::utility
        CarlaUtil["CARLA Utils in Training (mile/utils/carla_utils.py)"]:::utility
        NetUtil["Network Utilities (mile/utils/network_utils.py)"]:::utility
    end

    %% Simulation & Environment Interface (carla_gym)
    subgraph "Simulation & Environment Interface (carla_gym)"
        ObsMgr["Observation Managers (carla_gym/core/obs_manager/)"]:::simulation
        Scenarios["Simulation Scenarios (carla_gym/envs/)"]:::simulation
        SimUtils["Simulation Utilities (carla_gym/utils/)"]:::simulation
    end

    %% Training, Inference & Model Components (mile)
    subgraph "Training, Inference & Model Components (mile)"
        Agents["Agents (mile/agents/)"]:::training
        Models["Model Architectures (mile/models/)"]:::training
        Layers["Auxiliary Layers (mile/layers/)"]:::training
        Trainer["Training Script (mile/trainer.py)"]:::training
        TrainConfig["Training Configurations (mile/configs/)"]:::training
        DataProc["Data Processing (mile/data/)"]:::training
        Loss["Loss Functions (mile/losses.py)"]:::training
        ModelUtil["Model Utilities (mile/utils/)"]:::training
    end

    %% Data Collection & Evaluation Pipeline
    subgraph "Data Collection & Evaluation Pipeline"
        DataCollect["Data Collection Pipeline (run/data_collect.sh)"]:::utility
        Evaluate["Evaluation Pipeline (run/evaluate.sh)"]:::utility
    end

    %% Data Flow Connections
    External1 -->|"sensors/data"| ObsMgr
    External1 -->|"scenario setup"| Scenarios

    ObsMgr -->|"sensor data"| Agents
    Scenarios -->|"environment info"| Agents
    SimUtils -->|"sim data"| Agents

    Agents -->|"decision-making"| Trainer
    DataProc -->|"training data"| Trainer
    Trainer -->|"model inference"| Models
    Layers -->|"supports"| Models
    Trainer -->|"loss computation"| Loss
    ModelUtil -->|"utility functions"| Trainer

    Trainer -->|"control commands"| External1

    Evaluate -->|"evaluation feedback"| Trainer
    Evaluate -->|"driving commands"| External1
    DataCollect -->|"collected data"| ObsMgr
    DataCollect -->|"training data"| Trainer

    %% Configuration & Utilities Support
    Config --- ObsMgr
    Config --- Trainer
    CommonUtil --- ObsMgr
    CommonUtil --- Trainer
    CarlaUtil --- Trainer
    NetUtil --- Trainer

    %% External Dependency to Training Module
    External2 --- Trainer

    %% Click Events for Component Mapping
    click ObsMgr "https://github.com/wayveai/mile/tree/main/carla_gym/core/obs_manager/"
    click Scenarios "https://github.com/wayveai/mile/tree/main/carla_gym/envs/"
    click SimUtils "https://github.com/wayveai/mile/tree/main/carla_gym/utils/"
    click Agents "https://github.com/wayveai/mile/tree/main/mile/agents/"
    click Models "https://github.com/wayveai/mile/tree/main/mile/models/"
    click Layers "https://github.com/wayveai/mile/tree/main/mile/layers/"
    click Trainer "https://github.com/wayveai/mile/blob/main/mile/trainer.py"
    click TrainConfig "https://github.com/wayveai/mile/tree/main/mile/configs/"
    click DataProc "https://github.com/wayveai/mile/tree/main/mile/data/"
    click Loss "https://github.com/wayveai/mile/blob/main/mile/losses.py"
    click ModelUtil "https://github.com/wayveai/mile/tree/main/mile/utils/"
    click Config "https://github.com/wayveai/mile/tree/main/config/"
    click CommonUtil "https://github.com/wayveai/mile/tree/main/utils/"
    click CarlaUtil "https://github.com/wayveai/mile/blob/main/mile/utils/carla_utils.py"
    click NetUtil "https://github.com/wayveai/mile/blob/main/mile/utils/network_utils.py"
    click DataCollect "https://github.com/wayveai/mile/blob/main/run/data_collect.sh"
    click Evaluate "https://github.com/wayveai/mile/blob/main/run/evaluate.sh"

    %% Styles
    classDef external fill:#f9c74f,stroke:#333,stroke-width:2px,color:#000;
    classDef simulation fill:#90be6d,stroke:#333,stroke-width:2px,color:#fff;
    classDef training fill:#577590,stroke:#333,stroke-width:2px,color:#fff;
    classDef utility fill:#f94144,stroke:#333,stroke-width:2px,color:#fff;
```
