### gRPC Client Usage Example

Source: https://github.com/nvlabs/alpasim/blob/main/src/grpc/README.md

Demonstrates how to establish a gRPC connection and interact with the SensorsimServiceStub. Ensure you have the necessary protobufs generated and installed.

```python
import grpc

from alpasim_grpc.v0.sensorsim_pb2 import RenderRequest, RenderReturn
from alpasim_grpc.v0.sensorsim_pb2_grpc import SensorsimServiceStub

with grpc.insecure_channel('host:port') as channel:
    service = SensorsimServiceStub(channel)
    render_request = RenderRequest(
        scene_id="scene_id",
        # ...
    )
    response: RenderReturn = service.render(render_request)
```

--------------------------------

### Creating and Installing a New Plugin

Source: https://github.com/nvlabs/alpasim/blob/main/docs/PLUGIN_SYSTEM.md

To add a new plugin, implement the required interface and register it via an entry point in your plugin's `pyproject.toml`. Install the plugin locally using `uv pip install -e` or by adding it to the `plugins/` directory and running `uv sync`.

```bash
uv pip install -e path/to/my-plugin    # or add to plugins/ and uv sync --extra all
uv run alpasim-info                    # should list your new component
```

--------------------------------

### Setup Local Environment Script

Source: https://github.com/nvlabs/alpasim/blob/main/docs/ONBOARDING.md

Executes the setup_local_env.sh script, which is recommended for local development. This script typically compiles protos and installs core dependencies along with the transfuser_driver plugin.

```bash
source setup_local_env.sh
```

--------------------------------

### Selective Package Installation with uv

Source: https://github.com/nvlabs/alpasim/blob/main/docs/ONBOARDING.md

Demonstrates selective installation of workspace packages using uv sync with extras. Use '--extra wizard' for wizard-only dependencies or '--extra all' for all core packages.

```bash
uv sync --extra wizard
```

```bash
uv sync --extra all
```

--------------------------------

### Plugin `pyproject.toml` Example

Source: https://github.com/nvlabs/alpasim/blob/main/docs/PLUGIN_SYSTEM.md

An example `pyproject.toml` for a plugin, demonstrating how to define project metadata, dependencies, and register entry points for both models and configurations.

```toml
[project]
name = "alpasim_transfuser"
dependencies = ["alpasim_plugins", "alpasim_driver", "torch", ...]

[project.entry-points."alpasim.models"]
transfuser = "alpasim_transfuser.transfuser_model:TransfuserModel"

[project.entry-points."alpasim.configs"]
transfuser = "alpasim_transfuser.configs"
```

--------------------------------

### Installing Core Packages and Plugins

Source: https://github.com/nvlabs/alpasim/blob/main/docs/PLUGIN_SYSTEM.md

Use `uv sync` with specific `--extra` flags to install the core Alpasim packages along with desired plugins. This ensures all necessary dependencies, including plugin-specific ones, are met.

```bash
uv sync --extra all --extra internal      # core + internal plugin
uv sync --extra all --extra transfuser    # core + transfuser plugin
```

--------------------------------

### Manually Start Controller with Breakpoints

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Prepare and start the controller component from its source directory, specifying the port and log directory. Ensure the port matches the one allocated in docker-compose.yaml.

```bash
cd <repo_root>/src/controller/
mkdir my_controller_log_dir
# Note: port (6003 in this case) must match the port allocated in docker-compose.yaml
uv run python -m alpasim_controller.server --port=6003 --log_dir=my_controller_log_dir --log-level=INFO
```

--------------------------------

### Start the Manual Driver

Source: https://github.com/nvlabs/alpasim/blob/main/docs/MANUAL_DRIVER.md

Execute this command from the repository root to start the manual driver. It will launch a pygame window for visualization and bind to 0.0.0.0:6789 by default.

```bash
uv run --project src/driver python -m alpasim_driver.main \
  --config-path=configs --config-name=manual
```

--------------------------------

### Start Non-Runtime Services

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

After generating configuration files, navigate to the generated directory and start the non-runtime services using Docker Compose. Ensure the specified services are listed.

```bash
docker compose -f docker-compose.yaml --profile sim up \
  driver-0 controller-0 physics-0 renderer-0
```

--------------------------------

### Install All Packages from Subdirectory with uv

Source: https://github.com/nvlabs/alpasim/blob/main/docs/ONBOARDING.md

Installs all dependencies for a single package from its subdirectory using uv sync. This is useful for working on individual plugins or components.

```bash
cd src/wizard && uv sync
```

--------------------------------

### Install Rust Manually

Source: https://github.com/nvlabs/alpasim/blob/main/docs/ONBOARDING.md

If `setup_local_env.sh` fails silently in non-interactive environments, manually install Rust using this command. The script only installs Rust when a TTY is detected.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
```

--------------------------------

### Start Alpasim Runtime as a Server

Source: https://github.com/nvlabs/alpasim/blob/main/docs/OPERATIONS.md

Use `wizard.run_mode=SERVER` to start the runtime as a gRPC daemon. The resolved client endpoint is written to `generated-runtime-server.yaml`. Clients should poll the gRPC port until it accepts connections.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam \
    wizard.run_mode=SERVER \
    wizard.log_dir=runs/{DATETIME}
```

--------------------------------

### Service Configuration Example

Source: https://github.com/nvlabs/alpasim/blob/main/docs/OPERATIONS.md

This YAML snippet shows how to configure replica counts and GPU assignments for Alpasim services. Ensure total capacity across services is balanced to avoid bottlenecks.

```yaml
services:
  renderer:
    replicas_per_container: 4
    gpus: [0, 1, 2, 3]

```

```yaml
services:
  renderer:
    replicas_per_container: 1
    gpus: [0, 1]

  driver:
    replicas_per_container: 8
    gpus: [2, 3]

  controller:
    replicas_per_container: 16
    gpus: null

runtime:
  endpoints:
    renderer:
      n_concurrent_rollouts: 4

    driver:
      n_concurrent_rollouts: 2

    controller:
      n_concurrent_rollouts: 2

```

--------------------------------

### Install Core and Transfuser Driver with uv

Source: https://github.com/nvlabs/alpasim/blob/main/docs/ONBOARDING.md

Installs all core packages and the transfuser_driver plugin using uv sync. This command ensures that both the main AlpaSim components and a specific plugin are available in the environment.

```bash
uv sync --extra all --extra transfuser_driver
```

--------------------------------

### Install Dev Dependencies with uv

Source: https://github.com/nvlabs/alpasim/blob/main/src/runtime/tests/README.md

Installs development dependencies, including pytest, using uv. Ensure you are in the `src/runtime` directory before running.

```bash
cd src/runtime
uv sync --all-extras
```

--------------------------------

### Install uv with curl

Source: https://github.com/nvlabs/alpasim/blob/main/src/eval/README.md

Installs the uv package manager using a curl command. This is a prerequisite for running the evaluation workflow locally.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Launch Alpasim Runtime for Debugging

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Navigate to the runtime source directory and execute this command to start the Alpasim runtime. This command uses the generated configuration files and sets the log level to INFO. Ensure the user configuration includes data_source settings.

```bash
cd <repo_root>/src/runtime/
# Following command is based on the docker-compose.yaml generated by the wizard
# Ensure the user config contains the data_source configuration
uv run python -m alpasim_runtime.simulate \
  --user-config=../../tutorial_dbg_runtime/generated-user-config-0.yaml \
  --network-config=../../tutorial_dbg_runtime/generated-network-config.yaml \
  --log-dir=../../tutorial_dbg_runtime \
  --eval-config=../../tutorial_dbg_runtime/eval-config.yaml \
  --log-level=INFO
```

--------------------------------

### Start Simulation with Docker Compose

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Initiate the rest of the simulation using Docker Compose with the generated configuration. The `--exit-code-from runtime-0` flag is crucial for manual runs including the runtime.

```bash
docker compose -f docker-compose.yaml --profile sim up \
  --exit-code-from runtime-0 \
  runtime-0 driver-0 physics-0 renderer-0
```

--------------------------------

### Full Command for High-Rate Camera/Lower Inference

Source: https://github.com/nvlabs/alpasim/blob/main/docs/OPERATIONS.md

Example command for running Alpasim with 30Hz cameras and 10Hz inference, including frame subsampling. Assumes a 2-camera configuration.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam \
    wizard.log_dir=runs/{DATETIME} \
    runtime.simulation_config.control_timestep_us=100002 \
    runtime.simulation_config.cameras.0.frame_interval_us=33334 \
    ++driver.inference.Cframes_subsample=3
```

--------------------------------

### Full Command for 5Hz Inference

Source: https://github.com/nvlabs/alpasim/blob/main/docs/OPERATIONS.md

Example of a complete command to run Alpasim with 5Hz inference and matching camera frame rates. Assumes a 2-camera configuration.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam \
    wizard.log_dir=runs/{DATETIME} \
    runtime.simulation_config.control_timestep_us=200000 \
    runtime.simulation_config.cameras.0.frame_interval_us=200000
```

--------------------------------

### Minimal Custom Controller Config

Source: https://github.com/nvlabs/alpasim/blob/main/src/controller/benchmark/README.md

A minimal example of a controller configuration override in YAML format.

```yaml
mpc_implementation: nonlinear
n_horizon: 15
```

--------------------------------

### Add Alpasim gRPC to Project

Source: https://github.com/nvlabs/alpasim/blob/main/src/grpc/README.md

Install the Alpasim gRPC library into your project using uv. This command adds the library from a Git repository, ensuring generated protobuf artifacts are included.

```bash
uv add "git+ssh://git@<host>/<org>/alpasim.git#subdirectory=src/grpc"
```

--------------------------------

### Render Specific Video Layouts with Hydra

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Generate reasoning-overlay videos by setting the eval.video.video_layouts parameter. This example sets the log directory and specifies the REASONING_OVERLAY layout.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=alpamayo1 wizard.log_dir=$PWD/tutorial eval.video.video_layouts=[REASONING_OVERLAY]
```

--------------------------------

### Use Public Scene Suite

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Utilize pre-validated collections of scenes for testing by specifying a `scenes.test_suite_id`. This example uses the 'public_2601' suite, which will download all 916 validated scenes from the 26.01 release dataset.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam scenes.test_suite_id=public_2601 wizard.log_dir=$PWD/tutorial_suite
```

--------------------------------

### Start External FlashDreams OmniDreams gRPC Server

Source: https://github.com/nvlabs/alpasim/blob/main/docs/VIDEO_MODEL.md

Manually start the OmniDreams gRPC server from a FlashDreams checkout. This is useful for running the video model on a separate machine. Ensure the correct pipeline configuration and network settings are used.

```bash
cd path/to/flashdreams
uv run --package flashdreams-omnidreams torchrun \
  --standalone \
  --nnodes=1 \
  --nproc_per_node=1 \
  -m omnidreams.grpc.server \
  --pipeline_config_name omnidrereams-sv-2steps-chunk2-loc6-lightvae-lighttae-perf \
  --host 0.0.0.0 \
  --port 50051 \
  --output_format jpeg \
  --jpeg_quality 90
```

--------------------------------

### Upgrade uv Package Manager

Source: https://github.com/nvlabs/alpasim/blob/main/docs/ONBOARDING.md

If 'uv' is already installed, use this command to upgrade it to the latest version.

```bash
uv self update
```

--------------------------------

### Interpreting Driving Quality Metrics in Text Format

Source: https://github.com/nvlabs/alpasim/blob/main/docs/OPERATIONS.md

This example shows how to interpret aggregated driving quality metrics from the metrics_results.txt file. It provides a summary of common metrics and their typical values.

```text
collision_at_fault: mean=0.05 → 5% of rollouts had at-fault collisions
dist_to_gt_trajectory: mean=2.3 → Average 2.3m deviation from GT path
duration_frac_20s: mean=0.95 → Average 95% of 20s completed
```

--------------------------------

### VSCode Debugger Configuration for Alpasim Runtime

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Add this configuration to your `.vscode/launch.json` file to enable debugging the Alpasim runtime directly within VSCode. This setup specifies the module to run, command-line arguments, and necessary environment variables for the Python path.

```json
{
  "name": "Debug Runtime (Level 3 Tutorial)",
  "type": "debugpy",
  "request": "launch",
  "module": "alpasim_runtime.simulate",
  "justMyCode": false,
  "cwd": "${workspaceFolder}/src/runtime",
  "args": [
    "--user-config=../../tutorial_dbg_runtime/generated-user-config-0.yaml",
    "--network-config=../../tutorial_dbg_runtime/generated-network-config.yaml",
    "--eval-config=../../tutorial_dbg_runtime/eval-config.yaml",
    "--log-dir=../../tutorial_dbg_runtime",
    "--log-level=INFO"
  ],
  "console": "integratedTerminal",
  "env": {
    "PYTHONPATH": "${workspaceFolder}/src/grpc:${workspaceFolder}/src/eval/src:${workspaceFolder}/src/utils:${workspaceFolder}/src/runtime:${env:PYTHONPATH}"
  }
}
```

--------------------------------

### Run Alpamayo 1.5 with Classifier-Free Guidance

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Enable classifier-free guidance navigation for Alpamayo 1.5. This requires approximately 60 GB of VRAM.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=alpamayo1_5 wizard.log_dir=$PWD/tutorial_alpamayo driver.model.use_classifier_free_guidance_nav=true
```

--------------------------------

### Run Alpamayo 1.5 Driver

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Execute the wizard with the Alpamayo 1.5 driver. Ensure model weights are downloaded.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=alpamayo1_5 wizard.log_dir=$PWD/tutorial_alpamayo
```

--------------------------------

### Launch Simulator with Local Static External Driver

Source: https://github.com/nvlabs/alpasim/blob/main/docs/MANUAL_DRIVER.md

Run the Alpasim wizard with the local deploy target and specify the driver source as an external static driver. This command connects the runtime to the driver at localhost:6789.

```bash
uv run --project src/wizard alpasim_wizard \
  deploy=local \
  driver=manual \
  driver_source=external_static \
  topology=1gpu \
  wizard.log_dir=$PWD/manual_run \
  scenes.scene_ids='["your-scene-id"]'
```

--------------------------------

### Benchmark Run Command Options

Source: https://github.com/nvlabs/alpasim/blob/main/src/controller/benchmark/README.md

Lists the available options for the `run` command in the benchmark suite.

```bash
uv run python -m benchmark run [OPTIONS]
```

--------------------------------

### Run Quick Benchmark

Source: https://github.com/nvlabs/alpasim/blob/main/src/controller/benchmark/README.md

Executes a quick benchmark run with default configurations and saves results to a JSON file.

```bash
uv run python -m benchmark run --quick -o results/baseline.json -d "Baseline MPC"
```

--------------------------------

### Discovering and Accessing Models

Source: https://github.com/nvlabs/alpasim/blob/main/docs/PLUGIN_SYSTEM.md

Use the `models` module to get a list of available model names or retrieve a specific model class by its registered name.

```python
from alpasim_plugins import models

models.get_names()                  # → ['alpamayo1', 'alpamayo1_5', 'manual', 'transfuser', 'vam']
models.get("transfuser")            # → <class TransfuserModel>
```

--------------------------------

### Build utils_rs Python Extension

Source: https://github.com/nvlabs/alpasim/blob/main/src/utils_rs/README.md

Installs the Rust-based Python extension in editable mode using maturin and pip. This command recompiles the Rust code after changes.

```bash
uv pip install -e src/utils_rs --force-reinstall
```

--------------------------------

### Run Alpamayo 1 Driver

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Execute the wizard with the Alpamayo 1 driver. Ensure model weights are downloaded.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=alpamayo1 wizard.log_dir=$PWD/tutorial_alpamayo
```

--------------------------------

### Run AlpaSim wizard for deployment

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

This command initiates the AlpaSim wizard to deploy a local simulation. It configures the topology, specifies the driver, and sets the log directory, creating necessary config files and running the simulation.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam wizard.log_dir=$PWD/tutorial
```

--------------------------------

### Run Controller Benchmarks

Source: https://github.com/nvlabs/alpasim/blob/main/src/controller/README.md

Compare controller performance using uv and the benchmark module. Benchmarks can be run with default or custom configurations.

```bash
# Run benchmark with default ControllerConfig (linear MPC)
uv run -m benchmark run --output results/linear.json
```

```bash
# Run benchmark with a custom config (write a small YAML that sets ControllerConfig fields; see benchmark/README.md)
uv run -m benchmark run --output results/nonlinear.json --config path/to/controller.yaml
```

```bash
# Compare results
uv run -m benchmark compare results/nonlinear.json results/linear.json
```

--------------------------------

### Run Full Benchmark

Source: https://github.com/nvlabs/alpasim/blob/main/src/controller/benchmark/README.md

Executes a full benchmark run with default configurations and saves results to a JSON file.

```bash
uv run python -m benchmark run -o results/baseline.json -d "Baseline MPC"
```

--------------------------------

### Configure Hugging Face token and download assets

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

These commands are necessary for downloading assets and models, particularly the VaVAM assets required by the default driver. Ensure you have a valid Hugging Face token.

```bash
# 1) Ensure HF env is present (needed for scene/model downloads)
export HF_TOKEN="<your_hf_token>"
# 2) Download VaVAM assets required by default driver
bash data/download_vavam_assets.sh --model vavam-b
```

--------------------------------

### Benchmark Compare Command Arguments and Options

Source: https://github.com/nvlabs/alpasim/blob/main/src/controller/benchmark/README.md

Details the arguments and options for the `compare` command used to compare benchmark results.

```bash
uv run python -m benchmark compare BASELINE COMPARISON [OPTIONS]
```

--------------------------------

### Deploy VaVAM Driver

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Use this command to deploy the VaVAM driver. Ensure the wizard is set up correctly.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam wizard.log_dir=$PWD/tutorial_alpamayo
```

--------------------------------

### Run Transfuser Driver

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Execute the wizard with the Transfuser driver. Ensure model weights are downloaded to the specified path.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=transfuser wizard.log_dir=$PWD/tutorial_transfuser
```

--------------------------------

### Read Alpasim .asl Logs Asynchronously

Source: https://github.com/nvlabs/alpasim/blob/main/docs/DATA_PIPELINE.md

Use this function to read .asl logs as a stream of messages. It requires an async runtime or execution within a Jupyter notebook. The example shows how to print the first 20 log entries.

```python
from alpasim_grpc.utils.logs import async_read_pb_log

i = 0
async for log_entry in async_read_pb_log("<path_to_log>.asl"):
    print(log_entry)
    i += 1
    if i == 20:
        break
```

--------------------------------

### Combining Conventions for Positions and Poses in Python

Source: https://github.com/nvlabs/alpasim/blob/main/CONTRIBUTING.md

Demonstrates the application of naming conventions for positions and poses, including vector addition and pose composition.

```python
# Positions
rig_to_aabb_in_local = np.array(...)
position_rig_local = np.array(...)
position_aabb_local = position_rig_local + rig_to_aabb_in_local

# Poses
pose_ego_rig_to_aabb = QVec(vec3=..., quat=...)
pose_local_to_ego_rig = QVec(vec3=..., quat=...)

position_ego_aabb_local = (pose_local_to_ego_rig @ pose_ego_rig_to_aabb).vec3
```

--------------------------------

### Generate Replay Files

Source: https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/replay_services/README.md

Use this command to generate ASL log, network-config, and user-config files for replaying simulation data. Ensure the RUN_DIR is set correctly.

```bash
RUN_DIR=/home/migl/workspace/alpasim/.wizard \
uv run python -m alpasim_wizard \
    wizard.log_dir=${RUN_DIR} \
    deploy=local topology=1gpu driver=vavam \
    runtime.endpoints.trafficsim.skip=False \
    scenes.scene_ids="[clipgt-c14c031a-8c17-4d08-aa4d-23c020a6871e]" \
    runtime.simulation_config.n_sim_steps=60
```

--------------------------------

### Download Transfuser Model Weights

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Download the Transfuser model weights and configuration from HuggingFace. Specify the local directory for storage.

```bash
huggingface-cli download longpollehn/tfv6_navsim model_0060.pth --local-dir=data/drivers/transfuser/
huggingface-cli download longpollehn/tfv6_navsim config.json --local-dir=data/drivers/transfuser/
```

--------------------------------

### Run Benchmark with Custom Controller Config

Source: https://github.com/nvlabs/alpasim/blob/main/src/controller/benchmark/README.md

Executes a quick benchmark run using a custom controller configuration specified in a YAML file.

```bash
uv run python -m benchmark run --quick --config path/to/controller.yaml \
    -o results/optimized.json -d "Custom MPC"
```

--------------------------------

### Configure Video Model Driver and Chunking

Source: https://github.com/nvlabs/alpasim/blob/main/docs/VIDEO_MODEL.md

Use specific driver presets that match the video-model view count and the desired chunking for frame processing. Ensure the driver configuration aligns with the model's input cadence requirements.

```bash
driver=vavam_video_model +chunking=8frame
```

```bash
driver=alpamayo1_5_1cam +chunking=8frame
```

--------------------------------

### Registering a Config Directory Entry Point

Source: https://github.com/nvlabs/alpasim/blob/main/docs/PLUGIN_SYSTEM.md

Register a directory containing Hydra configuration files in `pyproject.toml` under the `alpasim.configs` entry point group. This allows Alpasim to automatically discover and include these configurations.

```toml
[project.entry-points."alpasim.configs"]
transfuser = "alpasim_transfuser.configs"
```

--------------------------------

### Benchmark List Command

Source: https://github.com/nvlabs/alpasim/blob/main/src/controller/benchmark/README.md

Lists the available trajectories for benchmarking.

```bash
uv run python -m benchmark list [--quick]
```

--------------------------------

### Download Alpamayo 1.5 Model Weights

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Download the Alpamayo 1.5 model weights and its VLM backbone. Ensure you accept license agreements and authenticate with HuggingFace CLI.

```bash
# Alpamayo 1.5 — both the model and its VLM backbone are gated;
# accept the license agreements first, then authenticate:
#   https://huggingface.co/nvidia/Alpamayo-1.5-10B
#   https://huggingface.co/nvidia/Cosmos-Reason2-8B
huggingface-cli login            # paste your HF token when prompted
huggingface-cli download nvidia/Alpamayo-1.5-10B
huggingface-cli download nvidia/Cosmos-Reason2-8B
```

--------------------------------

### Run Alpasim with External Video Model Deployment

Source: https://github.com/nvlabs/alpasim/blob/main/docs/VIDEO_MODEL.md

Configure Alpasim to use an external video model deploy preset by specifying the FlashDreams server IP and port. This allows the video model to run on a cloud/cluster machine while Alpasim runs locally.

```bash
cd path/to/alpasim
uv run --project src/wizard alpasim_wizard \
  deploy=external_video_model \
  topology=1gpu \
  driver=alpamayo1_5_1cam \
  +chunking=8frame \
  'wizard.external_services.renderer=["<flashdreams-ip>:50051"]' \
  wizard.log_dir=$PWD/outputs/video-model-run
```

--------------------------------

### Deploy Managed FlashDreams with VAVAM Video Model

Source: https://github.com/nvlabs/alpasim/blob/main/docs/VIDEO_MODEL.md

Deploys Alpasim with the managed FlashDreams preset for the default VAVAM video model. This requires 48GB of VRAM. The initial run downloads model checkpoints, consider increasing startup timeout.

```bash
cd ../alpasim
uv run --project src/wizard alpasim_wizard \
  deploy=managed_flashdreams \
  topology=1gpu \
  driver=vavam_video_model \
  +chunking=8frame \
  wizard.log_dir=$PWD/outputs/managed-flashdreams-vavam-run

```

--------------------------------

### Download Alpamayo 1 Model Weights

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Download the Alpamayo 1 model weights from HuggingFace. This is required before running the model.

```bash
# Alpamayo 1
huggingface-cli download nvidia/Alpamayo-R1-10B
```

--------------------------------

### Registering a Model Entry Point

Source: https://github.com/nvlabs/alpasim/blob/main/docs/PLUGIN_SYSTEM.md

Declare a model component in `pyproject.toml` under the `alpasim.models` entry point group. This makes the model discoverable by Alpasim.

```toml
[project.entry-points."alpasim.models"]
transfuser = "alpasim_transfuser.transfuser_model:TransfuserModel"
```

--------------------------------

### Generate Config Files with Alpasim Wizard

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Use this command to generate configuration files without initiating the simulation. Specify deployment, topology, driver, and logging options.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam wizard.log_dir=$PWD/tutorial_dbg wizard.run_method=NONE  wizard.debug_flags.use_localhost=True
```

--------------------------------

### Deploy Local Alpasim with Custom Vavam Driver Path

Source: https://github.com/nvlabs/alpasim/blob/main/docs/OPERATIONS.md

Use this command to deploy Alpasim locally with a custom Vavam driver model located at a specified path. The wizard mounts this path into the container.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam \
    wizard.log_dir=runs/{DATETIME} \
    defines.vavam_driver=/path/to/custom/vavam-driver

```

--------------------------------

### Configure Log Replay Driver

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Set specific runtime configurations to force the ego vehicle to follow its recorded trajectory using the log replay driver.

```bash
runtime.endpoints.{physics,trafficsim,controller}.skip: true
runtime.simulation_config.physics_update_mode: NONE
runtime.simulation_config.force_gt_duration_us: 20000000
```

--------------------------------

### Build Alpasim-Ready FlashDreams Docker Image

Source: https://github.com/nvlabs/alpasim/blob/main/docs/VIDEO_MODEL.md

Builds the Alpasim-ready FlashDreams Docker image, baking in workspace source and OmniDreams package. Use the same Docker context that will run Alpasim.

```bash
docker build -t flashdreams-alpasim:local -f docker/Dockerfile.alpasim .

```

--------------------------------

### Import Core Alpasim Utils

Source: https://github.com/nvlabs/alpasim/blob/main/src/utils/README.md

Import essential classes and functions for geometry, artifacts, and asynchronous log reading from the alpasim_utils library.

```python
from alpasim_utils.geometry import Pose, Trajectory, pose_from_grpc
from alpasim_utils.artifact import Artifact
from alpasim_utils.logs import async_read_pb_log
```

--------------------------------

### Run AlpaSim Wizard and Generate ASL Files

Source: https://github.com/nvlabs/alpasim/blob/main/src/eval/README.md

Executes the AlpaSim wizard to generate ASL files for evaluation. This command requires specifying deployment, topology, driver, and a log directory.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam wizard.log_dir=<log_dir>
```

--------------------------------

### Docker Compose for One-Shot Simulations

Source: https://github.com/nvlabs/alpasim/blob/main/docs/OPERATIONS.md

When running a generated `docker-compose.yaml` manually for one-shot simulations, use `--exit-code-from runtime-0` to ensure Docker Compose waits for the runtime container to exit.

```bash
docker compose -f docker-compose.yaml up --exit-code-from runtime-0
```

--------------------------------

### Launch Simulator with External Driver on Different Machine

Source: https://github.com/nvlabs/alpasim/blob/main/docs/MANUAL_DRIVER.md

When the driver is running on a different host or port, override the default address using `wizard.external_services.driver`. Replace '192.168.1.100:6789' with the actual external IP and port of your driver.

```bash
uv run --project src/wizard alpasim_wizard \
  deploy=local \
  driver=manual \
  driver_source=external_static \
  topology=1gpu \
  wizard.log_dir=$PWD/manual_run \
  scenes.scene_ids='["your-scene-id"]' \
  wizard.external_services.driver='["192.168.1.100:6789"]'
```

--------------------------------

### Deploy Managed FlashDreams with Alpamayo1.5

Source: https://github.com/nvlabs/alpasim/blob/main/docs/VIDEO_MODEL.md

Deploys Alpasim with the managed FlashDreams preset for the Alpamayo1.5 model. This requires 96GB of VRAM. This configuration uses a local image tag and never pulls from a registry.

```bash
cd ../alpasim
uv run --project src/wizard alpasim_wizard \
  deploy=managed_flashdreams \
  topology=1gpu \
  driver=alpamayo_1_5_1cam \
  +chunking=8frame \
  wizard.log_dir=$PWD/outputs/managed-flashdreams-run

```

--------------------------------

### Deploy Local Alpasim with Custom Driver Image

Source: https://github.com/nvlabs/alpasim/blob/main/docs/OPERATIONS.md

Deploy Alpasim locally using a custom driver container image. Ensure your custom image exposes a gRPC endpoint compatible with the driver service interface.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam \
    wizard.log_dir=runs/{DATETIME} \
    services.driver.image=<your-registry>/<your-driver-image>:<tag>

```

--------------------------------

### Compile Protobufs Locally

Source: https://github.com/nvlabs/alpasim/blob/main/src/grpc/README.md

Compile protobuf definitions in-place for local development using uv. This command is useful after changing the definitions and also serves to re-compile them.

```python
uv run compile-protos
```

--------------------------------

### Visualize Chain-of-Causation Reasoning

Source: https://github.com/nvlabs/alpasim/blob/main/docs/TUTORIAL.md

Modify the video layout to visualize the predicted chain-of-causation reasoning when using the Alpamayo driver.

```bash
uv run alpasim_wizard deploy=local topology=1gpu driver=alpamayo1 wizard.log_dir=$PWD/tutorial_alpamayo eval.video.video_layouts=[REASONING_OVERLAY]
```

--------------------------------

### Benchmark Output JSON Structure

Source: https://github.com/nvlabs/alpasim/blob/main/src/controller/benchmark/README.md

Illustrates the JSON structure for benchmark results, including summary statistics and simulation details.

```json
{
  "timestamp": "2025-01-15T10:30:00",
  "description": "Baseline MPC",
  "summary": {
    "n_simulations": 100,
    "total_iterations": 10000,
    "total_time_s": 1234.5,
    "solve_time_mean_ms": 45.2,
    "solve_time_median_ms": 42.1,
    "solve_time_min_ms": 30.5,
    "solve_time_max_ms": 120.3
  },
  "simulations": [
    {
      "trajectory_name": "straight_v10_0",
      "trajectory_description": "Straight at 10 m/s",
      "total_time_ms": 12345.6,
      "iterations": [
        {
          "timestamp_us": 0,
          "solve_time_ms": 45.2,
          "x": 0.0,
          "y": 0.0,
          "yaw": 0.0,
          "ref_x": 0.0,
          "ref_y": 0.0,
          "ref_yaw": 0.0
        }
      ]
    }
  ]
}
```

--------------------------------

### Build FlashDreams Base Docker Image

Source: https://github.com/nvlabs/alpasim/blob/main/docs/VIDEO_MODEL.md

Builds the base Docker image for FlashDreams from its source checkout. Ensure you are in the FlashDreams directory.

```bash
cd ../flashdreams
docker build -t flashdreams-base:local -f docker/Dockerfile .

```

--------------------------------

### Compare Two Benchmark Runs

Source: https://github.com/nvlabs/alpasim/blob/main/src/controller/benchmark/README.md

Compares two benchmark result files and generates a comparison report.

```bash
uv run python -m benchmark compare results/baseline.json results/optimized.json \
    -o comparison_report/
```