Skip to content

ONBOARDING.md

Latest commit

 

History

History
120 lines (95 loc) · 6.56 KB

ONBOARDING.md

File metadata and controls

120 lines (95 loc) · 6.56 KB
Raw

Onboarding

Alpasim depends on access to the following:

  • Hugging Face access
    • Used for downloading simulation artifacts
    • Data is here
    • See info on data here for more information on the contents of artifacts used to define scenes
    • You will need to create a free Hugging Face account if you do not already have one and create an access token with read access. See access tokens.
    • You must also request access to the gated dataset at nvidia/PhysicalAI-Autonomous-Vehicles-NuRec. Without this, scene downloads will fail with a GatedRepoError.
    • Once you have the token, set it as an environment variable: export HF_TOKEN=<token>
  • uv version 0.9.17 or newer installed (see here)
    • Example installation command for Ubuntu: curl -LsSf https://astral.sh/uv/install.sh | sh.
    • If uv is already installed, you can upgrade it with uv self update.
  • Rust toolchain (cargo) for building utils_rs, a compiled extension that accelerates trajectory transformations and interpolations in the runtime. Install via rustup or interactively let setup_local_env.sh install it for you.
  • Docker installed (see setup instructions)
  • Docker compose installed (see setup instructions)
    • The wizard needs docker, docker-compose-plugin, and docker-buildx-plugin
    • Docker needs to be able to run without sudo. If you see a permission error when running docker commands, add yourself to the docker group: sudo usermod -aG docker $USER
  • CUDA 12.8 or greater installed (see here for instructions)
    • The NRE container uses CUDA 12.8, so your host NVIDIA driver must support it (driver version >= 570.x).
  • Install the NVIDIA Container Toolkit (see here)

Optional: OmniDreams video-model renderer

The default AlpaSim tutorial uses NuRec. To use OmniDreams as the renderer backend, follow the Video Model Renderer guide after completing the base setup above.

Additional requirements for this path:

  • A FlashDreams checkout and a locally built flashdreams-alpasim:local image for deploy=managed_flashdreams, or access to an external OmniDreams gRPC server for deploy=external_video_model.
  • Hugging Face authentication for any gated OmniDreams, FlashDreams, driver, or scene assets needed by the selected run.
  • Enough GPU memory for both the renderer and the selected driver. The managed FlashDreams preset currently requires about 48 GB VRAM with the lightweight public single-view driver preset and about 96 GB VRAM with the Alpamayo1.5 single-camera preset.

Dependency management

The repo is a uv workspace. All packages under src/ and plugins/ are workspace members sharing a single lockfile (uv.lock). The root pyproject.toml has empty dependencies, so a bare uv sync installs nothing -- this is intentional to avoid pulling heavy dependencies (torch, warp-lang) by default.

Each workspace member is exposed as a named optional dependency extra, enabling composable installs from the repo root:

# Recommended for local development (compiles protos, installs all core + transfuser_driver plugin)
source setup_local_env.sh

# Or install selectively:
uv sync --extra wizard                           # wizard + transitive deps only
uv sync --extra all                              # all core packages
uv sync --extra all --extra transfuser_driver    # core + transfuser_driver plugin

# Single-package install from a subdirectory also works:
cd src/wizard && uv sync

Use uv run to execute commands in the workspace environment:

uv run pytest                                # run tests
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam ...  # run the wizard
uv run --project src/runtime python -c "..." # run in a sub-project context

All members share one dependency resolution; there is no per-member version isolation. See Plugin System for how plugins integrate with the workspace.

Troubleshooting

CUDA_ERROR_UNSUPPORTED_PTX_VERSION during NRE warmup Your NVIDIA driver is too old for the CUDA version in the NRE container. Upgrade to driver >= 570.x (CUDA 12.8 support). Check your current version with nvidia-smi.

GatedRepoError when downloading scenes You need to request access to the gated HuggingFace dataset. Visit nvidia/PhysicalAI-Autonomous-Vehicles-NuRec and request access.

HF_TOKEN not set / authentication failures Set your HuggingFace token: export HF_TOKEN=<your-token>. You can create a token at huggingface.co/settings/tokens.

gRPC connectivity errors between services Ensure Docker networking is working and all containers are on the same network. Check docker compose logs for port binding conflicts. If using debug_flags.use_localhost: true, ensure no other process is using the assigned ports.

setup_local_env.sh fails silently in non-interactive environments The script only installs Rust when a TTY is detected. To install Rust manually, use: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

uv parse error on exclude-newer = "3 days" Your uv is older than 0.9.17 and can't parse the relative cooldown in the root pyproject.toml. Don't delete the line (it's an intentional supply-chain safeguard); upgrade instead with uv self update.

ModuleNotFoundError (e.g. alpasim_grpc.v0.*_pb2) in the service containers The git-ignored gRPC stubs are missing on the host, and the volume-mounted source tree shadows the stubs baked into the images. Run source setup_local_env.sh (or cd src/grpc && uv run compile-protos) to generate them.

Next steps

Once you have access to the above, please follow instructions in the tutorial to get started running Alpasim.