# swc-17/sparsedrivev2 architecture

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

- Interactive diagram: https://gitdiagram.com/swc-17/sparsedrivev2
- Repository: https://github.com/swc-17/sparsedrivev2

## Overview

SparseDriveV2 is an end-to-end autonomous-driving planner evaluated on NAVSIM. Its main workflow turns sensor and scene history into model features, scores candidate trajectories, selects a plan, and evaluates driving metrics. The repository also contains NAVSIM-v1 compatibility, metric caching, traffic-agent simulation, and visualization. Edges are limited to relationships shown in the README or SOURCE INDEX; several model-internal connections are dashed because their source was not sampled.

Main entry points: [`navsim/evaluate/pdm_score.py`](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/evaluate/pdm_score.py) (PDMS evaluation), [`navsim/agents/sparsedrive/scorer/pdm_score_v2.py`](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/scorer/pdm_score_v2.py) (SparseDrive scorer), [`navsim/planning/metric_caching/metric_cache.py`](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/metric_caching/metric_cache.py) (Metric cache), [`navsim/agents/sparsedrive/sparsedrive_model.py`](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/sparsedrive_model.py) (Scoring model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Scene Data"]
  node_scene_inputs[("Sensor scenes")]
  node_scene_types["Scene dataclasses<br/>[dataclasses.py]"]
  node_scene_enums["Scene enums<br/>[enums.py]"]
  node_scenario["Scenario builder<br/>[navsim_scenario.py]"]
  node_scenario_utils["Scenario conversion"]
  node_dataloader["Scene dataloader<br/>[dataloader.py]"]
  node_v1_dataclasses["NAVSIM-v1 types<br/>[dataclasses.py]"]
  node_v1_scenario["NAVSIM-v1 scenarios<br/>[navsim_scenario.py]"]
end

subgraph group_model["Planning Model"]
  node_features["Model features"]
  node_sparsedrive_agent["SparseDrive agent"]
  node_sparsedrive_model["Scoring model"]
  node_backbone["Vision backbone"]
  node_feature_ops["Aggregation ops"]
  node_trajectory_vocabulary["Trajectory vocabulary"]
end

subgraph group_simulation["Simulation Scoring"]
  node_metric_cache[("Metric cache<br/>[metric_cache.py]")]
  node_pdm_observation["PDM observation<br/>[pdm_observation.py]"]
  node_occupancy_map["Drivable map"]
  node_simulator["Trajectory simulator<br/>[pdm_simulator.py]"]
  node_state_arrays["State representation"]
  node_pdm_enums["Planner state enums<br/>[pdm_enums.py]"]
  node_pdm_scorer["PDM scorer<br/>[pdm_scorer.py]"]
  node_traffic_policy["Traffic policies"]
  node_idm_agents["IDM agents"]
  node_v1_observation["NAVSIM-v1 observation<br/>[pdm_observation.py]"]
end

subgraph group_tools["Evaluation Tools"]
  node_v1_cache["NAVSIM-v1 cache"]
  node_cache_processor["Cache processor"]
  node_evaluation["PDMS evaluation<br/>[pdm_score.py]"]
  node_sparsedrive_score["SparseDrive scorer<br/>[pdm_score_v2.py]"]
  node_visualization["Scene visualization<br/>[bev.py]"]
end

node_researcher(("Planner user"))
node_result["Driving metrics"]

node_researcher -.->|"provides scenes"| node_scene_inputs
node_scene_inputs -.->|"loads records"| node_dataloader
node_dataloader -->|"builds inputs"| node_scene_types
node_scenario -->|"uses types"| node_scene_types
node_scenario -->|"uses conversions"| node_scenario_utils
node_scenario_utils -->|"converts records"| node_scene_types
node_features -->|"consumes types"| node_scene_types
node_features -->|"uses geometry"| node_scenario_utils
node_features -.->|"feeds model"| node_sparsedrive_model
node_sparsedrive_model -.->|"encodes images"| node_backbone
node_sparsedrive_model -.->|"aggregates features"| node_feature_ops
node_sparsedrive_model -.->|"scores candidates"| node_trajectory_vocabulary
node_trajectory_vocabulary -.->|"selects plan"| node_sparsedrive_agent
node_sparsedrive_agent -.->|"returns plan"| node_researcher
node_cache_processor -->|"uses scenarios"| node_scenario
node_cache_processor -->|"builds cache"| node_metric_cache
node_metric_cache -->|"stores observation"| node_pdm_observation
node_metric_cache -->|"stores map"| node_occupancy_map
node_simulator -->|"uses arrays"| node_state_arrays
node_evaluation -->|"reads cache"| node_metric_cache
node_evaluation -->|"simulates proposals"| node_simulator
node_evaluation -->|"scores proposals"| node_pdm_scorer
node_evaluation -->|"uses policy"| node_traffic_policy
node_sparsedrive_score -->|"reads cache"| node_metric_cache
node_sparsedrive_score -->|"simulates proposals"| node_simulator
node_sparsedrive_score -->|"scores proposals"| node_pdm_scorer
node_sparsedrive_score -->|"uses policy"| node_traffic_policy
node_pdm_scorer -->|"uses indices"| node_pdm_enums
node_idm_agents -.->|"implements policy"| node_traffic_policy
node_v1_scenario -->|"uses types"| node_v1_dataclasses
node_v1_cache -->|"uses observation"| node_v1_observation
node_v1_cache -->|"uses scenarios"| node_v1_scenario
node_evaluation -.->|"produces metrics"| node_result
node_sparsedrive_score -.->|"produces metrics"| node_result
node_visualization -->|"uses conversions"| node_scenario_utils

click node_scene_types "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/common/dataclasses.py"
click node_scene_enums "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/common/enums.py"
click node_scenario "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/scenario_builder/navsim_scenario.py"
click node_scenario_utils "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/scenario_builder/navsim_scenario_utils.py"
click node_dataloader "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/common/dataloader.py"
click node_features "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/sparsedrive_features.py"
click node_sparsedrive_agent "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/sparsedrive_agent.py"
click node_sparsedrive_model "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/sparsedrive_model.py"
click node_backbone "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/sparsedrive_backbone.py"
click node_feature_ops "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/ops/deformable_aggregation.py"
click node_trajectory_vocabulary "https://github.com/swc-17/sparsedrivev2/tree/main/navsim/agents/sparsedrive"
click node_metric_cache "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/metric_caching/metric_cache.py"
click node_pdm_observation "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/planner/pdm_planner/observation/pdm_observation.py"
click node_occupancy_map "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/planner/pdm_planner/observation/pdm_occupancy_map.py"
click node_simulator "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/planner/pdm_planner/simulation/pdm_simulator.py"
click node_state_arrays "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/planner/pdm_planner/utils/pdm_array_representation.py"
click node_pdm_enums "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/planner/pdm_planner/utils/pdm_enums.py"
click node_pdm_scorer "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/planner/pdm_planner/scoring/pdm_scorer.py"
click node_traffic_policy "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/traffic_agents_policies/abstract_traffic_agents_policy.py"
click node_idm_agents "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/observation/navsim_idm/navsim_idm_agent_manager.py"
click node_v1_dataclasses "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/navsim_v1/common/dataclasses.py"
click node_v1_scenario "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/navsim_v1/planning/scenario_builder/navsim_scenario.py"
click node_v1_observation "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/navsim_v1/planning/simulation/planner/pdm_planner/observation/pdm_observation.py"
click node_v1_cache "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/navsim_v1/planning/metric_caching/metric_cache_processor.py"
click node_cache_processor "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/metric_caching/metric_cache_processor.py"
click node_evaluation "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/evaluate/pdm_score.py"
click node_sparsedrive_score "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/scorer/pdm_score_v2.py"
click node_visualization "https://github.com/swc-17/sparsedrivev2/blob/main/navsim/visualization/bev.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scene_inputs,node_scene_types,node_scene_enums,node_scenario,node_scenario_utils,node_dataloader,node_v1_dataclasses,node_v1_scenario,node_researcher toneBlue
class node_features,node_sparsedrive_agent,node_sparsedrive_model,node_backbone,node_feature_ops,node_trajectory_vocabulary toneAmber
class node_metric_cache,node_pdm_observation,node_occupancy_map,node_simulator,node_state_arrays,node_pdm_enums,node_pdm_scorer,node_traffic_policy,node_idm_agents,node_v1_observation toneMint
class node_v1_cache,node_cache_processor,node_evaluation,node_sparsedrive_score,node_visualization toneRose
class node_result toneIndigo
```

## Components

### Scene Data

- **Sensor scenes**
- [Scene dataclasses](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/common/dataclasses.py): `navsim/common/dataclasses.py`
- [Scene enums](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/common/enums.py): `navsim/common/enums.py`
- [Scenario builder](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/scenario_builder/navsim_scenario.py): `navsim/planning/scenario_builder/navsim_scenario.py`
- [Scenario conversion](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/scenario_builder/navsim_scenario_utils.py): `navsim/planning/scenario_builder/navsim_scenario_utils.py`
- [Scene dataloader](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/common/dataloader.py): `navsim/common/dataloader.py`
- [NAVSIM-v1 types](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/navsim_v1/common/dataclasses.py): `navsim/navsim_v1/common/dataclasses.py`
- [NAVSIM-v1 scenarios](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/navsim_v1/planning/scenario_builder/navsim_scenario.py): `navsim/navsim_v1/planning/scenario_builder/navsim_scenario.py`

### Planning Model

- [Model features](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/sparsedrive_features.py): `navsim/agents/sparsedrive/sparsedrive_features.py`
- [SparseDrive agent](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/sparsedrive_agent.py): `navsim/agents/sparsedrive/sparsedrive_agent.py`
- [Scoring model](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/sparsedrive_model.py): `navsim/agents/sparsedrive/sparsedrive_model.py`
- [Vision backbone](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/sparsedrive_backbone.py): `navsim/agents/sparsedrive/sparsedrive_backbone.py`
- [Aggregation ops](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/ops/deformable_aggregation.py): `navsim/agents/sparsedrive/ops/deformable_aggregation.py`
- [Trajectory vocabulary](https://github.com/swc-17/sparsedrivev2/tree/main/navsim/agents/sparsedrive): `navsim/agents/sparsedrive`

### Simulation Scoring

- [Metric cache](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/metric_caching/metric_cache.py): `navsim/planning/metric_caching/metric_cache.py`
- [PDM observation](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/planner/pdm_planner/observation/pdm_observation.py): `navsim/planning/simulation/planner/pdm_planner/observation/pdm_observation.py`
- [Drivable map](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/planner/pdm_planner/observation/pdm_occupancy_map.py): `navsim/planning/simulation/planner/pdm_planner/observation/pdm_occupancy_map.py`
- [Trajectory simulator](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/planner/pdm_planner/simulation/pdm_simulator.py): `navsim/planning/simulation/planner/pdm_planner/simulation/pdm_simulator.py`
- [State representation](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/planner/pdm_planner/utils/pdm_array_representation.py): `navsim/planning/simulation/planner/pdm_planner/utils/pdm_array_representation.py`
- [Planner state enums](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/planner/pdm_planner/utils/pdm_enums.py): `navsim/planning/simulation/planner/pdm_planner/utils/pdm_enums.py`
- [PDM scorer](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/planner/pdm_planner/scoring/pdm_scorer.py): `navsim/planning/simulation/planner/pdm_planner/scoring/pdm_scorer.py`
- [Traffic policies](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/traffic_agents_policies/abstract_traffic_agents_policy.py): `navsim/traffic_agents_policies/abstract_traffic_agents_policy.py`
- [IDM agents](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/simulation/observation/navsim_idm/navsim_idm_agent_manager.py): `navsim/planning/simulation/observation/navsim_idm/navsim_idm_agent_manager.py`
- [NAVSIM-v1 observation](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/navsim_v1/planning/simulation/planner/pdm_planner/observation/pdm_observation.py): `navsim/navsim_v1/planning/simulation/planner/pdm_planner/observation/pdm_observation.py`

### Evaluation Tools

- [NAVSIM-v1 cache](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/navsim_v1/planning/metric_caching/metric_cache_processor.py): `navsim/navsim_v1/planning/metric_caching/metric_cache_processor.py`
- [Cache processor](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/planning/metric_caching/metric_cache_processor.py): `navsim/planning/metric_caching/metric_cache_processor.py`
- [PDMS evaluation](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/evaluate/pdm_score.py): `navsim/evaluate/pdm_score.py`
- [SparseDrive scorer](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/agents/sparsedrive/scorer/pdm_score_v2.py): `navsim/agents/sparsedrive/scorer/pdm_score_v2.py`
- [Scene visualization](https://github.com/swc-17/sparsedrivev2/blob/main/navsim/visualization/bev.py): `navsim/visualization/bev.py`

### Other components

- **Planner user**
- **Driving metrics**

## Connections

- Planner user → Sensor scenes: provides scenes
- Sensor scenes → Scene dataloader: loads records
- Scene dataloader → Scene dataclasses: builds inputs (evidence: `navsim/common/dataloader.py`)
- Scenario builder → Scene dataclasses: uses types (evidence: `navsim/planning/scenario_builder/navsim_scenario.py`)
- Scenario builder → Scenario conversion: uses conversions (evidence: `navsim/planning/scenario_builder/navsim_scenario.py`)
- Scenario conversion → Scene dataclasses: converts records (evidence: `navsim/planning/scenario_builder/navsim_scenario_utils.py`)
- Model features → Scene dataclasses: consumes types (evidence: `navsim/agents/sparsedrive/sparsedrive_features.py`)
- Model features → Scenario conversion: uses geometry (evidence: `navsim/agents/sparsedrive/sparsedrive_features.py`)
- Model features → Scoring model: feeds model
- Scoring model → Vision backbone: encodes images
- Scoring model → Aggregation ops: aggregates features
- Scoring model → Trajectory vocabulary: scores candidates
- Trajectory vocabulary → SparseDrive agent: selects plan
- SparseDrive agent → Planner user: returns plan
- Cache processor → Scenario builder: uses scenarios (evidence: `navsim/planning/metric_caching/metric_cache_processor.py`)
- Cache processor → Metric cache: builds cache (evidence: `navsim/planning/metric_caching/metric_cache_processor.py`)
- Metric cache → PDM observation: stores observation (evidence: `navsim/planning/metric_caching/metric_cache.py`)
- Metric cache → Drivable map: stores map (evidence: `navsim/planning/metric_caching/metric_cache.py`)
- Trajectory simulator → State representation: uses arrays (evidence: `navsim/planning/simulation/planner/pdm_planner/simulation/pdm_simulator.py`)
- PDMS evaluation → Metric cache: reads cache (evidence: `navsim/evaluate/pdm_score.py`)
- PDMS evaluation → Trajectory simulator: simulates proposals (evidence: `navsim/evaluate/pdm_score.py`)
- PDMS evaluation → PDM scorer: scores proposals (evidence: `navsim/evaluate/pdm_score.py`)
- PDMS evaluation → Traffic policies: uses policy (evidence: `navsim/evaluate/pdm_score.py`)
- SparseDrive scorer → Metric cache: reads cache (evidence: `navsim/agents/sparsedrive/scorer/pdm_score_v2.py`)
- SparseDrive scorer → Trajectory simulator: simulates proposals (evidence: `navsim/agents/sparsedrive/scorer/pdm_score_v2.py`)
- SparseDrive scorer → PDM scorer: scores proposals (evidence: `navsim/agents/sparsedrive/scorer/pdm_score_v2.py`)
- SparseDrive scorer → Traffic policies: uses policy (evidence: `navsim/agents/sparsedrive/scorer/pdm_score_v2.py`)
- PDM scorer → Planner state enums: uses indices (evidence: `navsim/planning/simulation/planner/pdm_planner/scoring/pdm_scorer.py`)
- IDM agents → Traffic policies: implements policy
- NAVSIM-v1 scenarios → NAVSIM-v1 types: uses types (evidence: `navsim/navsim_v1/planning/scenario_builder/navsim_scenario.py`)
- NAVSIM-v1 cache → NAVSIM-v1 observation: uses observation (evidence: `navsim/navsim_v1/planning/metric_caching/metric_cache_processor.py`)
- NAVSIM-v1 cache → NAVSIM-v1 scenarios: uses scenarios (evidence: `navsim/navsim_v1/planning/metric_caching/metric_cache_processor.py`)
- PDMS evaluation → Driving metrics: produces metrics
- SparseDrive scorer → Driving metrics: produces metrics
- Scene visualization → Scenario conversion: uses conversions (evidence: `navsim/visualization/bev.py`)