Quick start

Run your first AlpaSim simulation in minutes

This guide will walk you through running your first simulation with the VaVAM driver policy, interpreting the results, and understanding the output structure.

Prerequisites

Before starting, ensure you have completed the onboarding setup with all dependencies installed.

Run your first simulation

1. Set up your environment

   Run the setup script to compile protos, download an example driver model, and install the alpasim_wizard command line tool:

   source setup_local_env.sh
   

   This will ensure you have a valid Hugging Face token and prepare your environment.

2. Run the wizard

   Execute the wizard to create necessary config files, download the scene (if necessary), and run a simulation:

   alpasim_wizard +deploy=local wizard.log_dir=$PWD/tutorial
   

   This creates a tutorial/ directory with all necessary config files and runs the simulation.

   The wizard uses VaVAM as the default driver policy. The first run will download the required scene from Hugging Face.

3. View the results

   Once the simulation completes, find the visualization video in the created tutorial directory:

   tutorial/aggregate/videos/all/clipgt-026d..._0.mp4
   

   Open this MP4 file to see a visualization of your simulation results.

Understanding the results

The simulation creates a comprehensive output structure in the tutorial/ directory:

Key directories

rollouts/

Contains logs of simulation behavior for each rollout, used to analyze AV behavior and calculate metrics. Organized as rollouts/{scene_id}/{batch_uuid}/.

Key files:

• rollout.asl: Messages exchanged within the simulation (useful for debugging)
• metrics.parquet: Per-rollout evaluation metrics
• {clipgt_id}_{batch_id}_{rollout_id}.mp4: Evaluation videos
• _complete: Marker file indicating successful rollout completion

aggregate/

Contains aggregated results across all rollouts:

• metrics_results.txt: Formatted table of driving scores (mean, std, quantiles)
• metrics_results.png: Visual summary of driving quality metrics
• metrics_unprocessed.parquet: Combined metrics from all rollouts
• videos/: Videos organized by violation type (collision, offroad, etc.)

Configuration files

Various YAML files provide insight into the simulation configuration:

• wizard-config.yaml: Config used by the wizard after applying Hydra inheritance
• generated-user-config-{ARRAY_ID}.yaml: Expanded simulation config
• trafficsim-config.yaml: Traffic simulation configuration
• generated-network-config.yaml: Service port mappings

Example directory structure

tutorial/
├── aggregate/
│   ├── metrics_results.png
│   ├── metrics_results.txt
│   ├── metrics_unprocessed.parquet
│   └── videos/
│       ├── all/
│       │   └── clipgt-026d..._0.mp4
│       └── violations/
│           ├── collision_at_fault/
│           ├── collision_rear/
│           ├── dist_to_gt_trajectory/
│           └── offroad/
├── rollouts/
│   └── clipgt-f7020b3e.../
│       └── 86513b18-96c5.../
│           ├── rollout.asl
│           ├── rollout.rclog
│           ├── metrics.parquet
│           └── _complete
├── driver-config.yaml
├── eval-config.yaml
├── wizard-config.yaml
└── run.sh

Basic debugging

This section covers debugging the simulator configuration itself, not vehicle behavior within the simulation.

The console contains logs from all microservices and is the first place to look when something goes wrong.

If the rollouts directory does not appear or other errors occur:

1. Check the console logs to identify where the first errors occurred
2. Review the wizard-config.yaml for configuration issues
3. Ensure all services started successfully

Try a different driver policy

Once you’ve successfully run your first simulation, try running with the Alpamayo-R1 model:

Download model weights

huggingface-cli download nvidia/Alpamayo-R1-10B

The Alpamayo-R1 model is large (10B parameters). Ensure your GPU has sufficient capacity to run it.

Next steps

Customize simulations

Learn how to configure scenes, driver policies, and runtime parameters

Operations guide

Performance tuning, troubleshooting, and advanced usage