How motional/nuplan-devkit works
Project Type and Purpose
• This is a full-stack autonomous-vehicle planning and simulation framework (“nuPlan”).
• Key capabilities: scenario building (from datasets or custom), planning (ML or rule-based), closed-loop simulation, metrics evaluation, visualization (NuBoard, in-process), training pipelines, database management, and submission tooling.
High-Level Architectural Components
A. Command-Line Interfaces & Entrypoints
• nuplan/cli (db_cli.py, nuplan_cli.py)
• Shell scripts: entrypoint_simulation.sh, entrypoint_result_processor.sh, entrypoint_submission.sh
• Top-level runners in nuplan/planning/script: run_simulation.py, run_nuboard.py, run_training.py, etc.
B. Scenario Layer
• nuplan/planning/scenario_builder: builds Scenario objects from nuPlan DB or cached sources
C. Planning & Prediction
• nuplan/planning/script & nuplan/planning/planning (metrics, metric_engine)
• Planner interfaces in nuplan/planning/simulation/planner & abstract_predictor
D. Simulation
• nuplan/planning/simulation:
• Controller (kinematic, perfect tracking, ILQR/LQR trackers)
• Observation (ego-centric, ML agents, IDM agents, lidar)
• Occupancy Map
• Path & Trajectory
• Runner & Callback framework for time-stepped simulation
• SimulationHistory (nuplan/planning/simulation/history/simulation_history.py, SimulationHistoryBuffer)
E. Visualization
• nuplan/planning/simulation/visualization: consumes SimulationHistory output to render states
• NuBoard (nuplan/planning/nuboard): HTML/JS dashboard for experiment monitoring
F. Data Persistence & Database
• nuplan/database: blob stores, maps_db, nuplan_db, ORM layer
G. Training Pipeline
• nuplan/planning/training and nuplan/planning/script/builders: config-driven Hydra style builders to set up data, model, objectives, metrics
H. Submission
• nuplan/submission: gRPC servicers, EvalAI interface, proto converters, container management
Key Data Flows & Interactions
1) User issues a command (e.g., run_simulation).
2) CLI loads config → ScenarioBuilder fetches scenario(s) from nuPlan DB.
3) SimulationRunner steps through each time iteration:
• At each time step:
• Observation module generates sensor/agent observations.
• Planner/predictor produces future trajectory or actions.
• Controller applies actions to ego state.
• SimulationHistory records time-stamped states of ego, agents, environment.
• Simulation callbacks log metrics, serialize states.
4) After simulation:
• SimulationHistoryBuffer (output) is passed to visualization module to render frames, plots.
• MetricEngine consumes recorded states for offline or online metric computation.
5) Visualization (static or via NuBoard) reads history object to generate graphs and interactive HTML.
SimulationHistory: Input & Output
• Input DataStructure:
• Scenario metadata (map, traffic lights, lanes)
• Time-step tuples: {timestamp, ego_state, agent_states, sensor_data_refs, control_inputs}
• Internally: SimulationHistoryBuffer accumulates these records in ordered arrays.
• Output DataStructure:
• A SimulationHistory object exposing methods:
– get_ego_trajectory() → List[TimeStampedEgoState]
– get_agent_trajectories() → Dict[AgentID, List[TimeStampedAgentState]]
– get_simulation_occupancy_maps() → occupancy snapshots per time step
• Serialized history (pickle/JSON) via callbacks or direct API.
• Visualization Relationship:
• nuplan/planning/simulation/visualization modules subscribe to SimulationHistory.
– Occupancy grid overlays
– Planned vs actual trajectories
• In NuBoard, SimulationHistory is converted to JSON and fed into browser via resource scripts for interactive plotting.
Essential Elements
• Clear component names (e.g., SimulationHistoryBuffer).