AlpaSim

AlpaSim is a modular, data-driven autonomous-driving simulator. It orchestrates renderer, driver, controller, physics, traffic, runtime, and evaluation services through gRPC. Use this root as a router; read only the focused sub-skill needed for the task.

Route by intent

• Prepare or run a simulation, compose Hydra overrides, select scenes, Docker/Slurm deployment, tune GPUs/timing, or inspect telemetry: read simulation-wizard.
• Understand the event loop, service lifecycle, addresses, daemon mode, replay, timing validation, renderer caches, or video-model chunking: read runtime-services.
• Select or adapt an ego policy, manual/external driver, model input/output, camera rectification, or plugin entry points/config discovery: read drivers-and-plugins.
• Inspect ASL logs, extract frames, evaluate/aggregate/re-evaluate runs, interpret metrics/videos, or use trajectory/geometry utilities: read evaluation-and-logs.
• Choose MPC, inspect vehicle state, run ground physics, understand CATK traffic sessions/handover, or classify CUDA/PyG/Warp requirements: read control-physics-traffic.
• Change protobufs, compile generated stubs, use gRPC clients, inspect package entry points, or review safe developer/tool workflows: read grpc-and-developer-tools.

Cross-cutting details are in troubleshooting, package and backend notes, and coordinate frames. Run the read-only environment checker before optional backend work; the structured routing metadata is consumed by the specialized repo-skill importer. Check repository provenance before treating this graph as current for another checkout.

Installation orientation

AlpaSim is a uv workspace. The root project intentionally has no default runtime dependencies; install only the workspace extra for the chosen workflow:

uv sync --extra wizard                 # wizard and its transitive core
uv sync --extra all                    # all core packages, no optional plugin
uv sync --extra all --extra transfuser # core plus the public Transfuser plugin

Use Python 3.11 for the core packages. alpasim_driver currently requires Python 3.12, so use a compatible environment for driver/model inspection. A full simulation additionally requires Docker Compose, NVIDIA Container Toolkit/CUDA, scene artifacts, and often Hugging Face access; a package import is not proof that those services or assets work.

After changing .proto definitions, compile stubs from the gRPC package with uv run compile-protos; use the developer-tools route for the safe bundled compiler and clean/build distinctions. Verify a selected environment with:

python -c "import alpasim_grpc, alpasim_utils, alpasim_runtime, alpasim_wizard"
python -c "from alpasim_grpc.v0 import runtime_pb2, runtime_pb2_grpc"

Operating boundaries

• Keep HF_TOKEN, external endpoints, private paths, model weights, scene caches, and scheduler credentials out of prompts, generated YAML, logs, and skill content. Treat gated scene/model downloads as user-authorized actions.
• Start with config generation and a one-scene/one-rollout plan. Prefer wizard.run_method=NONE or a read-only checker before containers, network services, GPU inference, or scheduler submission.
• Preserve resolved run files and the first causal service error. A rollout is successful only when its _complete marker and expected evaluation outputs exist; an ASL file alone is not completion.
• Do not use CPU imports to claim CUDA renderer, Warp, CATK/PyG, or model inference coverage. The optional backend notes preserve those limits.
• Keep coordinate-frame names explicit: local, rig, aabb, ecef, and the estimated/noised frame are not interchangeable. Read the coordinate reference before changing transforms or service messages.

Verification entry points

The generated graph is intended to support focused, reproducible checks rather than a default full simulation. Use the verification artifacts outside this runtime tree when reviewing coverage. Safe native candidates include wizard config/dispatch, runtime validation/replay, controller, evaluation/ASL, utilities, plugin registry, and protobuf compilation tests. Full Docker, NuRec/FlashDreams, gated HF assets, model inference, CATK compiled extensions, Slurm submission, and large benchmarks remain explicitly conditional.