# autonomousvision/navsim architecture

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

- Interactive diagram: https://gitdiagram.com/autonomousvision/navsim
- Repository: https://github.com/autonomousvision/navsim

## Overview

Based on our review of both the file tree and the README, NAVSIM is a data‐driven simulation and benchmarking tool for autonomous vehicles. Its purpose is to simulate simplified bird’s eye view scenes to compute meaningful evaluation metrics (like progress and time to collision) under a “non-reactive” or open-loop simulation setup. This system helps to benchmark end-to-end autonomous driving policies while keeping the simulation efficient and closely aligned with closed-loop conditions.

##### Major Components
- Agents and Policies:
– Represented by the “navsim/agents” and “navsim/traffic_agents_policies” directories.
– Include various agent implementations (e.g., ConstantVelocity, EgoStatusMLP, Human, Transfuser variants).
– Indicate how agent selection and behavior configurations are handled through YAML files in the configuration directories.
- Planning Engine:
– Found under “navsim/planning”. This component includes several submodules for scenario building, simulation, metric caching, training, and even a dedicated “pdm_planner” that handles scoring and simulation proposals.
– Highlight the “scenario_builder”, “simulation”, “training”, “metric_caching”, and “pdm_scoring” parts.
- Data and Common Utilities:
– The “navsim/common” folder encapsulates shared dataclasses, dataloader utilities, and enumerations.
– This component underpins configuration management (via “navsim/planning/script/config”) and helps interconnect many parts of the system.
- Evaluation and Benchmarking:
– Modules inside “navsim/evaluate” (like pdm_score) work on gathering metrics.
– Scripts in “scripts/evaluation” and “scripts/submission” orchestrate evaluation workflows and leaderboard submissions.
- Visualization:
– Managed under “navsim/visualization”, which includes modules to display BEV (bird’s eye view), camera views, LiDAR, and plotting functions.
- External/Operational Scripts and Deployment:
– The “scripts”, “download”, and configuration files (e.g., environment.yml, setup.py, GitHub workflows) support installation, data acquisition, and CI/CD.
– They represent the “glue” that enables the simulation, training, and evaluation to run in real-world scenarios.

##### Relationships and Interactions
- Data Flow – Illustrate how raw input data (from sensor logs or pre-downloaded datasets) enters the system via the dataloader (common utilities) and is preprocessed before being fed to the agent modules.
- Simulation-to-Evaluation – After simulating an episode, outputs (such as vehicle states, progress metrics, or collision indicators) are passed to the metric caching and evaluation modules for scoring (e.g., via PDM Score).
- Feedback for Training – For training purposes, there is a pipeline where simulation data is leveraged to train or validate models. This is defined through scripts and configurations under “navsim/planning/training” and related YAML files.
- Visualization Overlays – The visualization components take simulation outputs to render BEV images, camera views, or other plots that help interpret system behavior.

##### Architectural Patterns and Design Principles
- Modular Design – The system is clearly engineered to separate concerns: different modules for agents, planning, evaluation, and visualization.
- Configuration-Driven Architecture – With extensive use of YAML configuration files in “navsim/planning/script/config”, the system is highly flexible for parameter tuning and support of different simulation scenarios.
- Script-Oriented Orchestration – External scripts (in the “scripts” directory) are used to build, run, and deploy the pipelines. This reflects a design that supports both development and production environments.
- Extensibility – Each module (agent, planning, evaluation) is designed in a pluggable manner, which is evident by the abstract classes and multiple implementations found within the code structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data and Utilities
    subgraph "Data & Common Utilities"
        CU("Common Utilities"):::utils
        CM("Config Management"):::utils
    end

    %% Agents and Policies
    subgraph "Agents & Policies"
        A("Agents"):::agents
        TAP("Traffic Agents Policies"):::agents
    end

    %% Planning Engine
    subgraph "Planning Engine"
        PSB("Scenario Builder"):::planning
        SIM("Simulation & PDM Planner"):::planning
        MC("Metric Caching"):::planning
        TN("Training"):::planning
    end

    %% Evaluation and Benchmarking
    subgraph "Evaluation & Benchmarking"
        EM("Evaluation Module"):::evaluation
        ES("Evaluation Scripts"):::evaluation
        SS("Submission Scripts"):::evaluation
    end

    %% Visualization
    subgraph "Visualization"
        VIS("Visualization"):::visualization
    end

    %% External and Deployment
    subgraph "External & Deployment"
        EXS("External Scripts"):::external
        DD("Download"):::external
        PS("Project Setup"):::external
        CI("CI/CD"):::external
        EC("Environment Config"):::external
    end

    %% Connections from Data & Utilities to Agents
    CU -->|"load_data"| A
    CU -->|"load_data"| TAP
    CM -->|"config"| A
    CM -->|"config"| PSB
    CM -->|"config"| TN

    %% Agents feeding into Planning Engine
    A -->|"agent_input"| PSB
    TAP -->|"policy_input"| PSB

    %% Planning Engine internal flow
    PSB -->|"build_scenario"| SIM
    SIM -->|"cache_metrics"| MC
    SIM -->|"train_data"| TN
    SIM -->|"sim_output"| EM
    SIM -->|"viz_data"| VIS

    %% Evaluation flow
    EM -->|"orchestrate_eval"| ES
    ES -->|"submission"| SS

    %% External orchestration
    EXS -->|"trigger_training"| TN
    EXS -->|"trigger_evaluation"| ES
    EXS -->|"download"| DD
    EXS -->|"ci_cd"| CI
    EXS -->|"project_setup"| PS
    EXS -->|"env_config"| EC

    %% Class Definitions for color coding
    classDef agents fill:#f6d186,stroke:#333,stroke-width:2px;
    classDef planning fill:#a2d5f2,stroke:#333,stroke-width:2px;
    classDef utils fill:#d5e1df,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#c1e1c1,stroke:#333,stroke-width:2px;
    classDef visualization fill:#fde2e4,stroke:#333,stroke-width:2px;
    classDef external fill:#e2eafc,stroke:#333,stroke-width:2px;

    %% Click Events
    click A "https://github.com/autonomousvision/navsim/tree/main/navsim/agents"
    click TAP "https://github.com/autonomousvision/navsim/tree/main/navsim/traffic_agents_policies"
    click PSB "https://github.com/autonomousvision/navsim/tree/main/navsim/planning/scenario_builder"
    click SIM "https://github.com/autonomousvision/navsim/tree/main/navsim/planning/simulation/planner/pdm_planner"
    click MC "https://github.com/autonomousvision/navsim/tree/main/navsim/planning/metric_caching"
    click TN "https://github.com/autonomousvision/navsim/tree/main/navsim/planning/training"
    click CU "https://github.com/autonomousvision/navsim/tree/main/navsim/common"
    click CM "https://github.com/autonomousvision/navsim/tree/main/navsim/planning/script/config"
    click EM "https://github.com/autonomousvision/navsim/tree/main/navsim/evaluate"
    click ES "https://github.com/autonomousvision/navsim/tree/main/scripts/evaluation"
    click SS "https://github.com/autonomousvision/navsim/tree/main/scripts/submission"
    click VIS "https://github.com/autonomousvision/navsim/tree/main/navsim/visualization"
    click EXS "https://github.com/autonomousvision/navsim/tree/main/scripts"
    click DD "https://github.com/autonomousvision/navsim/tree/main/download"
    click PS "https://github.com/autonomousvision/navsim/blob/main/setup.py"
    click CI "https://github.com/autonomousvision/navsim/tree/main/.github/workflows"
    click EC "https://github.com/autonomousvision/navsim/blob/main/environment.yml"
```
