How yvanyin/goalflow works
Project type and purpose
• Type: Research‐grade, end‐to‐end autonomous driving simulation and planning framework
• Purpose: Generate, train, simulate, and evaluate multimodal vehicle trajectories guided by goal points (GoalFlow), built on top of NAVSIM and using diffusion‐based flow matching.
File structure
• Top‐level modules:
• navsim/ – core simulation, planning, evaluation, training, visualization
• vovnet/ – visual backbone library (feature extraction)
• nuplan-devkit – external dataset & evaluation
• scripts/ & download/ – data download and orchestration scripts
• setup.py, requirements.txt, docs/
• Key subdirectories in navsim/
• agents/ – vehicle behavior models (constant‐velocity, MLP, GoalFlow)
• planning/ – scenario builder, metric caching, script runners, simulation planners
• training/ – PyTorch Lightning modules, dataset definitions, callbacks
• evaluate/ – scoring metrics (PDM)
• visualization/ – BEV, camera, lidar plotting
README for additional insights
• Pipeline stages described: data download → goal‐point construction → training → validation/evaluation
• Dependencies: NAVSIM dataset, YAML configs for different agents, PyTorch, PyTorch Lightning, Hydra‐style config files
Main components & interactions
a. Components
1. Data Layer
• NAVSIM datasets (download via download/*.sh)
• navsim/common/dataloader.py
2. Scenario Builder
• navsim/planning/scenario_builder/navsim_scenario.py
3. Agent Models
• ConstantVelocityAgent, EgoStatusMLPAgent, GoalFlowAgent
• Model definitions in navsim/agents/goalflow/*, uses vovnet backbones
4. Planner & Simulator
• PDM planner (navsim/planning/simulation/planner/pdm_planner/*)
5. Metric Caching & Scoring
• navsim/planning/metric_caching/*
• PDM score (navsim/evaluate/pdm_score.py)
6. Training Pipeline
• LightningModule (navsim/planning/training/agent_lightning_module.py)
• Configs in navsim/planning/script/config/training/*.yaml
7. Evaluation & Visualization
• Scripts in navsim/planning/script/run_*.py
• Visualization (navsim/visualization/*.py)
8. Orchestration Scripts
• scripts/ folder, top‐level run_*.sh wrappers
b. Relationships & Data Flow
1. Data Download → 2. Dataloader → 3. Scenario Builder → 4. Agent Inference / Training → 5. Planner & Simulation → 6. Metric Caching → 7. Scoring → 8. Visualization / Output
9. Training Loop: scenario builder + dataloader feed LightningModule → weight checkpoint
10. Inference Loop: use trained weights in GoalFlowAgent → follow same simulation → evaluation
c. Architectural Patterns & Principles
• Modularity: clear separation between data ingestion, scenario setup, agent logic, planner, and evaluation
• Config‐driven orchestration: YAML files under navsim/planning/script/config/ control behaviors without code changes
• Plug‐and‐play agents: abstract base class in navsim/agents/abstract_agent.py → multiple agent implementations
• PyTorch Lightning for training lifecycle management
• Metric caching to avoid recomputation
d. Key Technologies & Frameworks
• Python 3.x, PyTorch, PyTorch Lightning
• NAVSIM (dataset & baseline platform)
• VovNet (vision backbone)
• Hydra‐style YAML configs
Detail without over‐splitting
• Of the seven major modules above
• Call out the navsim/agents/goalflow submodules (model, loss, features, backbone) as a grouped cluster
• Config layer as an overlay controlling the orchestration scripts