Onboarding

Initial setup and dependencies for AlpaSim

Before running AlpaSim, you need to set up your environment with the required dependencies and access credentials.

System requirements

AlpaSim requires a system with:

• NVIDIA GPU with CUDA 12.6 or greater
• Docker and Docker Compose
• Python environment (managed via uv)
• Hugging Face account for data access

Dependencies

1. Install uv

   Install uv, a fast Python package installer and resolver:

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

   For more installation options, see the uv documentation.

2. Install Docker

   Install Docker and required plugins:

   Ubuntu

   Follow the Docker installation guide for Ubuntu.

   Install required plugins:

   sudo apt-get install docker-ce docker-ce-cli containerd.io \
     docker-buildx-plugin docker-compose-plugin
   

   Other platforms

   Visit the Docker installation documentation for your platform.

   Docker needs to run without sudo. If you see permission errors, add yourself to the docker group:

   sudo usermod -aG docker $USER
   

   Log out and log back in for the changes to take effect.

3. Install CUDA

   Install CUDA 12.6 or greater:

   # Visit NVIDIA CUDA downloads for your platform-specific installation
   

   Download from NVIDIA CUDA Downloads and follow the instructions for your platform.

4. Install NVIDIA Container Toolkit

   Install the NVIDIA Container Toolkit to enable GPU support in Docker containers:

   # Follow the installation guide for your platform
   

   See the NVIDIA Container Toolkit installation guide for detailed instructions.

Hugging Face access

AlpaSim downloads simulation artifacts from Hugging Face. You need to set up access:

1. Create a Hugging Face account

   If you don’t already have one, create a free account at huggingface.co.

2. Generate an access token

   Create an access token with read access:

   1. Go to Hugging Face settings
   2. Click “New token”
   3. Select “Read” access
   4. Generate and copy the token
3. Set the environment variable

   Export the token as an environment variable:

   export HF_TOKEN=<your-token-here>
   

   Add this to your ~/.bashrc or ~/.zshrc to make it permanent:

   echo 'export HF_TOKEN=<your-token-here>' >> ~/.bashrc
   source ~/.bashrc
   

Dataset information

AlpaSim uses the PhysicalAI Autonomous Vehicles NuRec dataset:

• Dataset location: Hugging Face dataset
• Format details: See the dataset README for information on the contents of artifacts used to define scenes

Scenes will be automatically downloaded to data/nre-artifacts/all-usdzs when you run simulations that require them.

Verify installation

To verify your setup is complete:

Check uv

uv --version

If all commands return version information without errors, your environment is ready.

Next steps

Quick start

Now that your environment is set up, run your first simulation