# valeoai/v-max architecture

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

- Interactive diagram: https://gitdiagram.com/valeoai/v-max
- Repository: https://github.com/valeoai/v-max

## Overview

V-Max extends Waymax for autonomous-driving motion-planning research. The principal workflow is to load scenarios, construct a wrapped simulation environment, run a learned or rule-based planner, and train or evaluate it using driving metrics. Its major branches include RL/IL algorithms, configurable neural encoders, rule-based policies, ScenarioMax SDC-path support, and visualization. The graph reflects documented capabilities and indexed imports; several implementation details, particularly unsampled trainer and dataset internals, remain unverified.

Main entry points: [`vmax/scripts/evaluate/utils.py`](https://github.com/valeoai/v-max/blob/main/vmax/scripts/evaluate/utils.py) (Evaluation utilities), [`vmax/agents/pipeline/inference.py`](https://github.com/valeoai/v-max/blob/main/vmax/agents/pipeline/inference.py) (Policy inference), [`vmax/agents/pipeline/training.py`](https://github.com/valeoai/v-max/blob/main/vmax/agents/pipeline/training.py) (Training pipeline), [`vmax/simulator/sim_factory.py`](https://github.com/valeoai/v-max/blob/main/vmax/simulator/sim_factory.py) (Environment factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Training and evaluation"]
  node_train_cli["Training entry<br/>[train.py]"]
  node_eval_cli["Evaluation entry<br/>[evaluate.py]"]
  node_train_config["Training utilities<br/>[train_utils.py]"]
  node_eval_utils["Evaluation utilities<br/>[utils.py]"]
end

subgraph group_agents["Planner agents"]
  node_transitions["Agent transitions<br/>[datatypes.py]"]
  node_bc["Behavior cloning<br/>[bc_factory.py]"]
  node_sac["SAC learner<br/>[sac_factory.py]"]
  node_ppo["PPO learner<br/>[ppo_factory.py]"]
  node_hybrid["BC-SAC learner<br/>[bc_sac_factory.py]"]
  node_networks["Network factory<br/>[network_factory.py]"]
  node_wayformer["Wayformer encoder<br/>[wayformer.py]"]
  node_inference["Policy inference<br/>[inference.py]"]
  node_training_pipeline["Training pipeline<br/>[training.py]"]
  node_idm["IDM policy<br/>[idm.py]"]
  node_pdm["PDM planner<br/>[pdm.py]"]
end

subgraph group_simulation["Simulation and data"]
  node_datasets["Scenario datasets<br/>[datasets.py]"]
  node_sim_factory["Environment factory<br/>[sim_factory.py]"]
  node_wrappers["Environment wrappers<br/>[base.py]"]
  node_sdc_paths["SDC path support<br/>[sdc_path.py]"]
  node_features["Feature extraction<br/>[vec_extractor.py]"]
  node_overrides["Waymax overrides<br/>[observation.py]"]
  node_operations["Simulation operations<br/>[operations.py]"]
end

subgraph group_assessment["Metrics and visualization"]
  node_metrics["Driving metrics<br/>[collector.py]"]
  node_visualization["Visualization<br/>[viz.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"starts training"| node_train_cli
node_researcher -->|"runs evaluation"| node_eval_cli
node_train_config -->|"loads scenarios"| node_datasets
node_eval_cli -->|"uses utilities"| node_eval_utils
node_eval_utils -->|"loads scenarios"| node_datasets
node_eval_utils -->|"collects metrics"| node_metrics
node_eval_utils -->|"renders results"| node_visualization
node_eval_utils -->|"selects algorithm"| node_bc
node_eval_utils -->|"selects algorithm"| node_sac
node_eval_utils -->|"selects algorithm"| node_ppo
node_eval_utils -->|"selects algorithm"| node_hybrid
node_sim_factory -->|"registers metrics"| node_metrics
node_sim_factory -->|"configures environment"| node_wrappers
node_sim_factory -->|"adds path wrapper"| node_sdc_paths
node_train_config -->|"configures data"| node_datasets
node_networks -->|"builds encoders"| node_wayformer
node_inference -->|"creates transitions"| node_transitions
node_inference -->|"steps environment"| node_wrappers
node_inference -->|"selects SDC"| node_operations
node_inference -->|"dispatches policy"| node_idm
node_inference -->|"dispatches policy"| node_pdm
node_pdm -->|"uses policy logic"| node_idm
node_wrappers -->|"computes rewards"| node_metrics
node_wrappers -->|"uses operations"| node_operations
node_features -->|"uses operations"| node_operations
node_train_cli -.->|"constructs simulation"| node_sim_factory
node_train_cli -.->|"runs learning"| node_training_pipeline
node_training_pipeline -.->|"trains policy"| node_bc
node_training_pipeline -.->|"trains policy"| node_sac
node_training_pipeline -.->|"trains policy"| node_ppo
node_training_pipeline -.->|"trains policy"| node_hybrid
node_sdc_paths -.->|"uses enriched data"| node_datasets
node_overrides -->|"extends visualization"| node_visualization

click node_train_cli "https://github.com/valeoai/v-max/blob/main/vmax/scripts/training/train.py"
click node_eval_cli "https://github.com/valeoai/v-max/blob/main/vmax/scripts/evaluate/evaluate.py"
click node_train_config "https://github.com/valeoai/v-max/blob/main/vmax/scripts/training/train_utils.py"
click node_eval_utils "https://github.com/valeoai/v-max/blob/main/vmax/scripts/evaluate/utils.py"
click node_datasets "https://github.com/valeoai/v-max/blob/main/vmax/simulator/datasets.py"
click node_sim_factory "https://github.com/valeoai/v-max/blob/main/vmax/simulator/sim_factory.py"
click node_wrappers "https://github.com/valeoai/v-max/blob/main/vmax/simulator/wrappers/base.py"
click node_sdc_paths "https://github.com/valeoai/v-max/blob/main/vmax/simulator/wrappers/sdc_path.py"
click node_features "https://github.com/valeoai/v-max/blob/main/vmax/simulator/features/extractor/vec_extractor.py"
click node_overrides "https://github.com/valeoai/v-max/blob/main/vmax/simulator/overrides/datatypes/observation.py"
click node_transitions "https://github.com/valeoai/v-max/blob/main/vmax/agents/datatypes.py"
click node_bc "https://github.com/valeoai/v-max/blob/main/vmax/agents/learning/imitation/bc/bc_factory.py"
click node_sac "https://github.com/valeoai/v-max/blob/main/vmax/agents/learning/reinforcement/sac/sac_factory.py"
click node_ppo "https://github.com/valeoai/v-max/blob/main/vmax/agents/learning/reinforcement/ppo/ppo_factory.py"
click node_hybrid "https://github.com/valeoai/v-max/blob/main/vmax/agents/learning/hybrid/bc_sac/bc_sac_factory.py"
click node_networks "https://github.com/valeoai/v-max/blob/main/vmax/agents/networks/network_factory.py"
click node_wayformer "https://github.com/valeoai/v-max/blob/main/vmax/agents/networks/encoders/wayformer.py"
click node_inference "https://github.com/valeoai/v-max/blob/main/vmax/agents/pipeline/inference.py"
click node_training_pipeline "https://github.com/valeoai/v-max/blob/main/vmax/agents/pipeline/training.py"
click node_idm "https://github.com/valeoai/v-max/blob/main/vmax/agents/rule_based/idm.py"
click node_pdm "https://github.com/valeoai/v-max/blob/main/vmax/agents/rule_based/pdm.py"
click node_metrics "https://github.com/valeoai/v-max/blob/main/vmax/simulator/metrics/collector.py"
click node_operations "https://github.com/valeoai/v-max/blob/main/vmax/simulator/operations.py"
click node_visualization "https://github.com/valeoai/v-max/blob/main/vmax/simulator/overrides/visualization/viz.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_train_cli,node_eval_cli,node_train_config,node_eval_utils toneBlue
class node_transitions,node_bc,node_sac,node_ppo,node_hybrid,node_networks,node_wayformer,node_inference,node_training_pipeline,node_idm,node_pdm toneAmber
class node_datasets,node_sim_factory,node_wrappers,node_sdc_paths,node_features,node_overrides,node_operations toneMint
class node_metrics,node_visualization toneRose
class node_researcher toneIndigo
```

## Components

### Training and evaluation

- [Training entry](https://github.com/valeoai/v-max/blob/main/vmax/scripts/training/train.py): `vmax/scripts/training/train.py`
- [Evaluation entry](https://github.com/valeoai/v-max/blob/main/vmax/scripts/evaluate/evaluate.py): `vmax/scripts/evaluate/evaluate.py`
- [Training utilities](https://github.com/valeoai/v-max/blob/main/vmax/scripts/training/train_utils.py): `vmax/scripts/training/train_utils.py`
- [Evaluation utilities](https://github.com/valeoai/v-max/blob/main/vmax/scripts/evaluate/utils.py): `vmax/scripts/evaluate/utils.py`

### Planner agents

- [Agent transitions](https://github.com/valeoai/v-max/blob/main/vmax/agents/datatypes.py): `vmax/agents/datatypes.py`
- [Behavior cloning](https://github.com/valeoai/v-max/blob/main/vmax/agents/learning/imitation/bc/bc_factory.py): `vmax/agents/learning/imitation/bc/bc_factory.py`
- [SAC learner](https://github.com/valeoai/v-max/blob/main/vmax/agents/learning/reinforcement/sac/sac_factory.py): `vmax/agents/learning/reinforcement/sac/sac_factory.py`
- [PPO learner](https://github.com/valeoai/v-max/blob/main/vmax/agents/learning/reinforcement/ppo/ppo_factory.py): `vmax/agents/learning/reinforcement/ppo/ppo_factory.py`
- [BC-SAC learner](https://github.com/valeoai/v-max/blob/main/vmax/agents/learning/hybrid/bc_sac/bc_sac_factory.py): `vmax/agents/learning/hybrid/bc_sac/bc_sac_factory.py`
- [Network factory](https://github.com/valeoai/v-max/blob/main/vmax/agents/networks/network_factory.py): `vmax/agents/networks/network_factory.py`
- [Wayformer encoder](https://github.com/valeoai/v-max/blob/main/vmax/agents/networks/encoders/wayformer.py): `vmax/agents/networks/encoders/wayformer.py`
- [Policy inference](https://github.com/valeoai/v-max/blob/main/vmax/agents/pipeline/inference.py): `vmax/agents/pipeline/inference.py`
- [Training pipeline](https://github.com/valeoai/v-max/blob/main/vmax/agents/pipeline/training.py): `vmax/agents/pipeline/training.py`
- [IDM policy](https://github.com/valeoai/v-max/blob/main/vmax/agents/rule_based/idm.py): `vmax/agents/rule_based/idm.py`
- [PDM planner](https://github.com/valeoai/v-max/blob/main/vmax/agents/rule_based/pdm.py): `vmax/agents/rule_based/pdm.py`

### Simulation and data

- [Scenario datasets](https://github.com/valeoai/v-max/blob/main/vmax/simulator/datasets.py): `vmax/simulator/datasets.py`
- [Environment factory](https://github.com/valeoai/v-max/blob/main/vmax/simulator/sim_factory.py): `vmax/simulator/sim_factory.py`
- [Environment wrappers](https://github.com/valeoai/v-max/blob/main/vmax/simulator/wrappers/base.py): `vmax/simulator/wrappers/base.py`
- [SDC path support](https://github.com/valeoai/v-max/blob/main/vmax/simulator/wrappers/sdc_path.py): `vmax/simulator/wrappers/sdc_path.py`
- [Feature extraction](https://github.com/valeoai/v-max/blob/main/vmax/simulator/features/extractor/vec_extractor.py): `vmax/simulator/features/extractor/vec_extractor.py`
- [Waymax overrides](https://github.com/valeoai/v-max/blob/main/vmax/simulator/overrides/datatypes/observation.py): `vmax/simulator/overrides/datatypes/observation.py`
- [Simulation operations](https://github.com/valeoai/v-max/blob/main/vmax/simulator/operations.py): `vmax/simulator/operations.py`

### Metrics and visualization

- [Driving metrics](https://github.com/valeoai/v-max/blob/main/vmax/simulator/metrics/collector.py): `vmax/simulator/metrics/collector.py`
- [Visualization](https://github.com/valeoai/v-max/blob/main/vmax/simulator/overrides/visualization/viz.py): `vmax/simulator/overrides/visualization/viz.py`

### Other components

- **Researcher**

## Connections

- Researcher → Training entry: starts training (evidence: `README.md`)
- Researcher → Evaluation entry: runs evaluation (evidence: `README.md`)
- Training utilities → Scenario datasets: loads scenarios (evidence: `vmax/scripts/training/train_utils.py`)
- Evaluation entry → Evaluation utilities: uses utilities (evidence: `vmax/scripts/evaluate/evaluate.py`)
- Evaluation utilities → Scenario datasets: loads scenarios (evidence: `vmax/scripts/evaluate/evaluate.py`)
- Evaluation utilities → Driving metrics: collects metrics (evidence: `vmax/scripts/evaluate/utils.py`)
- Evaluation utilities → Visualization: renders results (evidence: `vmax/scripts/evaluate/utils.py`)
- Evaluation utilities → Behavior cloning: selects algorithm (evidence: `vmax/scripts/evaluate/utils.py`)
- Evaluation utilities → SAC learner: selects algorithm (evidence: `vmax/scripts/evaluate/utils.py`)
- Evaluation utilities → PPO learner: selects algorithm (evidence: `vmax/scripts/evaluate/utils.py`)
- Evaluation utilities → BC-SAC learner: selects algorithm (evidence: `vmax/scripts/evaluate/utils.py`)
- Environment factory → Driving metrics: registers metrics (evidence: `vmax/simulator/sim_factory.py`)
- Environment factory → Environment wrappers: configures environment (evidence: `vmax/simulator/sim_factory.py`)
- Environment factory → SDC path support: adds path wrapper (evidence: `vmax/simulator/sim_factory.py`)
- Training utilities → Scenario datasets: configures data (evidence: `vmax/scripts/training/train_utils.py`)
- Network factory → Wayformer encoder: builds encoders (evidence: `vmax/agents/networks/network_factory.py`)
- Policy inference → Agent transitions: creates transitions (evidence: `vmax/agents/pipeline/inference.py`)
- Policy inference → Environment wrappers: steps environment (evidence: `vmax/agents/pipeline/inference.py`)
- Policy inference → Simulation operations: selects SDC (evidence: `vmax/agents/pipeline/inference.py`)
- Policy inference → IDM policy: dispatches policy (evidence: `vmax/agents/pipeline/inference.py`)
- Policy inference → PDM planner: dispatches policy (evidence: `vmax/agents/pipeline/inference.py`)
- PDM planner → IDM policy: uses policy logic (evidence: `vmax/agents/rule_based/pdm.py`)
- Environment wrappers → Driving metrics: computes rewards
- Environment wrappers → Simulation operations: uses operations (evidence: `vmax/simulator/wrappers/reward.py`)
- Feature extraction → Simulation operations: uses operations (evidence: `vmax/simulator/features/extractor/vec_extractor.py`)
- Training entry → Environment factory: constructs simulation
- Training entry → Training pipeline: runs learning
- Training pipeline → Behavior cloning: trains policy
- Training pipeline → SAC learner: trains policy
- Training pipeline → PPO learner: trains policy
- Training pipeline → BC-SAC learner: trains policy
- SDC path support → Scenario datasets: uses enriched data
- Waymax overrides → Visualization: extends visualization (evidence: `vmax/simulator/overrides/__init__.py`)
