---

name: simulation-wizard description: "Install and operate AlpaSim's Hydra simulation wizard: select scenes and drivers, validate configs, generate or run Docker/Slurm deployments, tune timing/topology, and inspect run telemetry and outputs." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Simulation wizard

Use this route when the task is to prepare, configure, launch, or diagnose an AlpaSim simulation run. It owns workspace extras, public prerequisites, Hydra composition, scene/cache selection, deployment choice, capacity/timing knobs, run-directory interpretation, and Prometheus setup. It does not own microservice implementation/event-loop details, model/plugin contracts, ASL evaluation, controller/physics/traffic internals, or protobuf development. Route those topics to runtime-services, drivers-and-plugins, evaluation-and-logs, control-physics-traffic, or grpc-and-developer-tools.

Operating rules

1. Work from an AlpaSim checkout and use its own uv.lock; do not assume a bare root uv sync installs packages.
2. Treat wizard.dry_run=true as command/deployment dry-run only: wizard context creation still validates catalogs, creates cache metadata, and may download missing scenes. Use a local USDZ directory or an already-populated cache for a no-network probe.
3. Never paste HF tokens into commands, generated YAML, or logs. A gated scene or model requires the user's own access and HF_TOKEN/HF_HOME setup.
4. Generate configs before launching unfamiliar or expensive deployments. Use wizard.run_method=NONE for a manual Compose/debug workflow; use wizard.dry_run=true to print deployment commands without starting them.
5. Preserve the resolved wizard.log_dir. It is the source of generated configs, service logs, rollouts, evaluation products, and telemetry.

Quick paths

• First local run: install the wizard extra, verify Docker/NVIDIA/HF/scene prerequisites, then run deploy=local topology=1gpu driver=vavam with an explicit wizard.log_dir.
• Config/catalog check: run alpasim_check_config with the same deploy, topology, driver, and scene overrides. This queries scene metadata but does not launch services.
• Compose generation only: add wizard.run_method=NONE; afterward run docker compose -f <log_dir>/docker-compose.yaml up --exit-code-from runtime-0 from the generated directory.
• Cluster: choose a site-specific deploy and an 8gpu_* topology through the site's approved sbatch wrapper. Scheduler submission is an external, credentialed action; this skill never autonomously submits it.
• Video model: use deploy=managed_flashdreams only with a locally built flashdreams-alpasim:local, or deploy=external_video_model with an externally reachable renderer address. Pair single-view driver presets with +chunking=8frame; do not add ad-hoc camera overrides.

Core workflow

1. Install and preflight. Choose uv sync --extra wizard for wizard-only work or uv sync --extra all for a full core checkout. Compile protobufs when service imports need them. Check uv, Docker Compose, NVIDIA Container Toolkit/CUDA host compatibility, cargo if building workspace utilities, and HF gated-dataset access. Run the bundled read-only prerequisite probe before changing the environment; see troubleshooting.
2. Select exactly one scene source. Use scenes.scene_ids=[...], scenes.test_suite_id=public_2601 (recommended broad NuRec suite), public_2601_video_model (single-view video-model subset), public_2604, or public_2507 for historical reproduction. For local artifacts use scenes.local_usdz_dir=<dir>; the wizard scans *.usdz, reads each metadata.yaml, creates an in-memory local suite, and uses that directory as the mounted cache. Do not set incompatible scene_ids and test_suite_id; cap with scenes.limit_to_first_n=N.
3. Compose Hydra groups. Supply deploy, topology, and driver when launching the managed driver path. Optional groups include controller, trafficsim, physics, cameras, chunking, driver_source, and experiment presets. Use + only for optional keys (for example +chunking=8frame or +runtime.renderer.video_model_config.return_hdmap_frames=true). The complete group inventory and field ownership are in the CLI reference and configuration.
4. Check before launch. Run alpasim_check_config with the intended overrides. Then use wizard.run_method=NONE for generated docker-compose.yaml, resolved YAML, network addresses, and service commands. Inspect mounts, image tags, GPU assignment, scene paths, external endpoints, and assert_zero_decision_delay before a real run.
5. Choose deployment. deploy=local uses Docker Compose and the default NuRec renderer. managed_flashdreams manages a local video-model container; external_video_model omits the renderer and adds wizard.external_services.renderer=[host:port]. Slurm and direct Enroot require a site wrapper, an active allocation (Enroot), image caches, and cluster-specific permissions. Details and safe boundaries are in deployment.
6. Tune a bounded run. Start with one scene, one rollout, and the smallest supported topology. Keep service capacities balanced. Use the timing formula in configuration, not rounded frequencies, before changing camera/control cadence. Video-model chunk timing has its own constraints.
7. Launch and observe. Use uv run alpasim_wizard ... for a managed run. For one-shot manual Compose, use --exit-code-from runtime-0; the runtime exits while backing services remain servers. For wizard.run_mode=SERVER, wait for generated-runtime-server.yaml's endpoint to accept connections before submitting client RPCs. Inspect telemetry and outputs using scenes and results and telemetry.
8. Recover deliberately. Preserve the run directory and first error. For an incomplete run, use the site's approved resume/requeue path and enable autoresume only after confirming the original resolved config and scene split. Do not delete caches or rerun a gated download blindly.

Canonical command templates

# wizard-only environment; run at checkout root
uv sync --extra wizard

# metadata/config check; no services launched
uv run alpasim_check_config deploy=local topology=1gpu driver=vavam \
  scenes.scene_ids='[clipgt-<scene-id>]' wizard.log_dir=./runs/check

# generate Compose/configs without executing services
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam \
  scenes.scene_ids='[clipgt-<scene-id>]' wizard.log_dir=./runs/generated \
  wizard.run_method=NONE

# one-shot default NuRec simulation
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam \
  scenes.scene_ids='[clipgt-<scene-id>]' wizard.log_dir=./runs/vavam

# safe command-only deployment probe (still needs local/cache-resolvable scenes)
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam \
  scenes.local_usdz_dir=./local-usdz wizard.log_dir=./runs/dry \
  wizard.dry_run=true

For exact options, output trees, deployment variants, timing math, telemetry, and recovery, follow the bundled references. They are intentionally checkout-independent and contain no private environment paths.