Environment:Haosulab ManiSkill GPU CUDA Simulation

Knowledge Sources	ManiSkill SAPIEN PhysX GPU
Domains	Infrastructure, GPU_Simulation
Last Updated	2026-02-15 08:00 GMT

Overview

NVIDIA GPU environment with CUDA support, PyTorch CUDA backend, and SAPIEN PhysX GPU simulation for parallelized multi-environment rollouts.

Description

This environment provides GPU-accelerated physics simulation through SAPIEN's PhysX CUDA backend. It enables running hundreds to thousands of parallel environments on a single GPU, which is essential for efficient RL training. The GPU simulation backend (`physx_cuda`) handles physics stepping, while the SAPIEN CUDA renderer handles visual observations. PyTorch CUDA tensors are used for all data transfer between the simulation and the learning algorithm, keeping data on the GPU to avoid costly CPU-GPU transfers.

Usage

Use this environment for any workflow requiring multi-environment parallelism (num_envs > 1). This includes RL training with PPO/SAC, large-scale trajectory generation, and any task that benefits from GPU-batched simulation. When `num_envs > 1`, ManiSkill automatically selects the `physx_cuda` backend.

System Requirements

Category	Requirement	Notes
OS	Linux (Ubuntu 20.04+)	Primary platform for GPU simulation
Hardware	NVIDIA GPU with CUDA support	Minimum 8GB VRAM recommended; 24GB+ for visual observations
Driver	NVIDIA Driver compatible with CUDA toolkit	Check nvidia-smi for driver version
CUDA	CUDA toolkit (version depends on PyTorch build)	Must match PyTorch CUDA version
RAM	16GB+ system RAM	For large parallel environments and data loading

Dependencies

System Packages

NVIDIA GPU driver (compatible with installed CUDA)
CUDA toolkit (matching PyTorch build)

Python Packages

`torch` (with CUDA support)
`sapien` >= 3.0.0 (Linux)
`nvidia-ml-py` (GPU monitoring)
All packages from Environment:Haosulab_ManiSkill_Python_SAPIEN_Core

Credentials

No additional credentials required beyond the core environment. The `CUDA_VISIBLE_DEVICES` environment variable can be used to select specific GPUs.

Quick Install

# Install PyTorch with CUDA support (example for CUDA 12.1)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# Install ManiSkill
pip install mani_skill

# Verify GPU availability
python -c "import torch; print(torch.cuda.is_available())"

Code Evidence

Automatic GPU backend selection from `mani_skill/envs/sapien_env.py:233-237`:

if sim_backend is None:
    if num_envs == 1:
        sim_backend = "cpu"
    else:
        sim_backend = "gpu"

PhysX GPU enablement from `mani_skill/envs/sapien_env.py:243-245`:

if self.device.type == "cuda":
    if not physx.is_gpu_enabled():
        physx.enable_gpu()

GPU memory configuration from `mani_skill/envs/sapien_env.py:271-275`:

try:
    physx.set_gpu_memory_config(**gpu_mem_config)
except TypeError:
    gpu_mem_config.pop("collision_stack_size")
    physx.set_gpu_memory_config(**gpu_mem_config)

CPU simulation restriction from `mani_skill/envs/sapien_env.py:248-251`:

if self.backend.sim_backend in CPU_SIM_BACKENDS and num_envs > 1:
    raise RuntimeError(
        """Cannot set the sim backend to 'cpu' and have multiple environments."""
    )

Backend device mapping from `mani_skill/envs/utils/system/backend.py:30-43`:

sim_backend_name_mapping = {
    "cpu": "physx_cpu", "cuda": "physx_cuda", "gpu": "physx_cuda",
}
render_backend_name_mapping = {
    "cpu": "sapien_cpu", "cuda": "sapien_cuda", "gpu": "sapien_cuda",
}

macOS forced CPU rendering fallback from `mani_skill/envs/utils/system/backend.py:73-78`:

if platform.system() == "Darwin":
    render_device = sapien.Device("cpu")
    render_backend = "sapien_cpu"
    logger.warning(
        "Detected MacOS system, forcing render backend to be sapien_cpu..."
    )

Common Errors

Error Message	Cause	Solution
`Cannot set the sim backend to 'cpu' and have multiple environments`	Trying num_envs > 1 with CPU backend	Use `sim_backend="gpu"` or reduce num_envs to 1
`failed to find device "cuda"`	No CUDA GPU available	Install NVIDIA drivers or use CPU backend
`PxgPinnedHostLinearMemoryAllocator: overflowing initial allocation size`	GPU temp buffer too small	Increase `gpu_memory_config.temp_buffer_capacity`
`Contact buffer overflow detected`	Too many rigid contacts	Increase `gpu_memory_config.max_rigid_contact_count`
`Patch buffer overflow detected`	Too many contact patches	Increase `gpu_memory_config.max_rigid_patch_count`
`Collision stack overflow detected`	Collision stack too small	Increase `gpu_memory_config.collision_stack_size`
Ray-tracing with num_envs > 1	RT shaders incompatible with multi-env	Use num_envs=1 for ray-tracing or switch to "default" shader

Compatibility Notes

macOS: GPU simulation is not supported. macOS forces CPU rendering backend regardless of user settings.
Windows: GPU simulation available but `collision_stack_size` parameter may not be supported in the SAPIEN beta build. A try/except fallback handles this gracefully.
AMD GPUs: For AMD GPUs, the render_backend must use a `pci:...` device string instead of `cuda`. Special handling exists in the backend parser.
Multi-GPU: Use `CUDA_VISIBLE_DEVICES` or `sim_backend="cuda:N"` to select specific GPU. Device ID is parsed from the backend string.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment