# hustvl/diffusiondrive architecture

> Architecture diagram of the GitHub repository hustvl/diffusiondrive, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hustvl/diffusiondrive
- Repository: https://github.com/hustvl/diffusiondrive

## Overview

##### Project Type and Purpose
- DiffusionDrive is an open-source research framework for real-time end-to-end autonomous driving, built on top of the NAVSIM simulator.
- It provides data-download utilities, scenario building, planning/simulation modules, a truncated diffusion agent, training/evaluation pipelines, and visualization tools.

##### Main Architectural Components
A. Data & Environment Layer
- download/ – shell scripts to fetch NAVSIM maps, scenarios, train/test splits
- NAVSIM simulator (external dependency)
B. Scenario & Data Preparation
- navsim/planning/scenario_builder – constructs driving scenarios from map and traffic data
- navsim/common/dataloader – PyTorch Dataset + DataLoader abstractions
- navsim/planning/script/run_dataset_caching.py – caches precomputed metrics for faster iteration
C. Core Agent & Model
- navsim/agents/abstract_agent.py – base agent interface (plugin point)
- navsim/agents/diffusiondrive – truncated diffusion model implementation (backbone, scheduler, loss modules, training callbacks)
- navsim/agents/transfuser & others – reference implementations for alternative policies
D. Planning & Simulation
- navsim/planning/simulation/planner/pdm_planner – runs closed-loop planning with PDM (proposal, scoring, simulation)
- navsim/planning/training – LightningModule wrappers, feature/target builders, callbacks
- navsim/planning/utils/multithreading – optional Ray or thread-pool parallel execution of rollouts
E. Training & Evaluation Orchestration
- docs/train_eval.md – high-level instructions
- navsim/planning/script/run_training.py – config-driven training entrypoint
- navsim/planning/script/run_pdm_score.py – evaluate model in closed-loop, compute PDMS
- scripts/training & scripts/evaluation – convenience shell scripts
F. Visualization & Analysis
- navsim/visualization – BEV, camera, LiDAR renderers and plotting utilities
- tutorial/tutorial_visualization.ipynb – example notebook

##### Relationships & Data Flow
1. Download & Prepare Data →
2. Scenario Builder loads map/scene definitions →
3. DataLoader yields sensor + map + ego/human trajectories →
4. Training loop (LightningModule) invokes:
- backbone (ResNet-34/50) for perception features
- truncated diffusion denoiser for control outputs
- loss calculation, backprop, checkpointing
5. After training, run PDM scoring pipeline:
- load trained weights → simulation planner → agent takes actions in NAVSIM → metrics collected → PDMS computed
6. Visualization tools consume trajectories + sensor data for qualitative analysis

##### Architectural Patterns & Design Principles
- Plugin architecture for “Agent” abstraction (easy to swap diffusion, transfuser, constant-velocity, human, MLP)
- Config-driven design (YAML files under navsim/planning/script/config)
- Modular separation: data ingestion, model, planning, evaluation, visualization
- Use of PyTorch Lightning for standardized training loops and callbacks
- Parallel execution via Ray or thread pools for scenario rollouts and metric caching

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Data & Environment Layer"
        Download["download/"]:::data
        NAVSIM["NAVSIM Simulator"]:::external
    end

    subgraph "Scenario & Data Preparation"
        SB["Scenario Builder"]:::data
        CachingScript["run_dataset_caching.py"]:::script
        DL["DataLoader"]:::data
    end

    subgraph "Core Agent & Model"
        AgentAbstract["abstract_agent.py"]:::model
        Diffusion["diffusiondrive modules"]:::model
    end

    subgraph "Training Engine"
        TrainEngine["LightningModule & Callbacks"]:::train
    end

    subgraph "Planning & Simulation Engine"
        Planner["PDM Planner & Utils"]:::sim
        Multithread["worker_ray_no_torch.py"]:::sim
    end

    subgraph "Evaluation & Orchestration"
        EvalScripts["run_pdm_score & Scripts"]:::script
        Config["YAML Configs"]:::config
    end

    subgraph "Visualization & Analysis"
        Viz["Visualization Tools"]:::viz
    end

    Download -->|fetch maps & scenarios| SB
    SB -->|cache metrics| CachingScript
    CachingScript -->|prepare data| DL
    DL -->|provide batches| TrainEngine
    TrainEngine -->|train model| Diffusion
    TrainEngine -->|use abstract API| AgentAbstract
    TrainEngine -->|config from| Config

    TrainEngine -->|trained weights| Planner
    Config -->|settings| Planner
    Planner -->|invoke agent| AgentAbstract
    Planner -->|multithread support| Multithread
    Planner -->|produce metrics| EvalScripts

    EvalScripts -->|results| Viz
    EvalScripts -->|use configs| Config
    Viz -->|visual analysis| Config

    %% Click Events
    click Download "https://github.com/hustvl/diffusiondrive/tree/main/download/"
    click SB "https://github.com/hustvl/diffusiondrive/tree/main/navsim/planning/scenario_builder/"
    click CachingScript "https://github.com/hustvl/diffusiondrive/blob/main/navsim/planning/script/run_dataset_caching.py"
    click DL "https://github.com/hustvl/diffusiondrive/blob/main/navsim/common/dataloader.py"
    click AgentAbstract "https://github.com/hustvl/diffusiondrive/blob/main/navsim/agents/abstract_agent.py"
    click Diffusion "https://github.com/hustvl/diffusiondrive/tree/main/navsim/agents/diffusiondrive/"
    click TrainEngine "https://github.com/hustvl/diffusiondrive/blob/main/navsim/planning/training/agent_lightning_module.py"
    click Planner "https://github.com/hustvl/diffusiondrive/tree/main/navsim/planning/simulation/planner/pdm_planner/"
    click Multithread "https://github.com/hustvl/diffusiondrive/blob/main/navsim/planning/utils/multithreading/worker_ray_no_torch.py"
    click EvalScripts "https://github.com/hustvl/diffusiondrive/blob/main/navsim/planning/script/run_pdm_score.py"
    click Config "https://github.com/hustvl/diffusiondrive/tree/main/navsim/planning/script/config/"
    click Viz "https://github.com/hustvl/diffusiondrive/tree/main/navsim/visualization/"

    %% Styles
    classDef data fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef model fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef train fill:#ffe0b2,stroke:#f57c00,color:#e65100
    classDef sim fill:#e1bee7,stroke:#8e24aa,color:#4a148c
    classDef script fill:#eceff1,stroke:#90a4ae,color:#37474f
    classDef config fill:#fff9c4,stroke:#fbc02d,color:#f57f17
    classDef viz fill:#b2dfdb,stroke:#00796b,color:#004d40
    classDef external fill:#CFD8DC,stroke:#546e7a,color:#263238
```
