{"id":9631,"library":"cuequivariance","title":"CUDA Equivariant Operations for PyTorch","description":"cuequivariance (version 0.9.1) provides efficient and flexible CUDA kernels for equivariant operations on 3D data, specifically designed for use with PyTorch. It aims to accelerate computations for deep learning models that require rotational, translational, or other forms of equivariance, often found in point cloud processing and molecular modeling. The library is actively developed and part of the vLLM project.","status":"active","version":"0.9.1","language":"en","source_language":"en","source_url":"https://github.com/vllm-project/cuequivariance","tags":["cuda","equivariant","pytorch","3d","point-cloud","machine-learning","gpu","vllm"],"install":[{"cmd":"pip install cuequivariance","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for tensor operations and deep learning framework integration (version >= 2.0.0).","package":"torch","optional":false},{"reason":"System-level dependency required for CUDA compilation and runtime execution on a GPU.","package":"CUDA Toolkit","optional":false}],"imports":[{"note":"Most core modules, including PointCloudTransformer, are nested under the 'modules' submodule.","wrong":"from cuequivariance import PointCloudTransformer","symbol":"PointCloudTransformer","correct":"from cuequivariance.modules import PointCloudTransformer"},{"note":"Most core modules, including EquivariantLinear, are nested under the 'modules' submodule.","wrong":"from cuequivariance import EquivariantLinear","symbol":"EquivariantLinear","correct":"from cuequivariance.modules import EquivariantLinear"}],"quickstart":{"code":"import torch\nfrom cuequivariance.modules import PointCloudTransformer\n\n# --- Runtime CUDA Check ---\n# cuequivariance requires a CUDA-enabled GPU and PyTorch compiled with CUDA support.\nif not torch.cuda.is_available():\n    raise RuntimeError(\n        \"CUDA is not available. cuequivariance requires a CUDA-enabled GPU and PyTorch \"\n        \"compiled with CUDA support. Please check your PyTorch installation and CUDA setup.\"\n    )\n\n# Ensure PyTorch device is set to CUDA\ndevice = torch.device(\"cuda\")\n\n# --- Example Data Generation ---\nbatch_size = 1\nnum_points = 100\ninput_feature_dim = 64\noutput_feature_dim = 128\n\n# Input points (batch_size, num_points, 3) - Represents 3D coordinates\npoints = torch.randn(batch_size, num_points, 3, device=device)\n# Input features (batch_size, num_points, input_feature_dim) - Features associated with each point\nfeatures = torch.randn(batch_size, num_points, input_feature_dim, device=device)\n\n# --- Initialize and Use a cuequivariance Module ---\n# PointCloudTransformer is an example module demonstrating 3D equivariant operations.\ntransformer = PointCloudTransformer(input_feature_dim, output_feature_dim).to(device)\n\n# Perform the forward pass\noutput_features = transformer(points, features)\n\n# --- Verify Output ---\nprint(f\"Input points shape: {points.shape}\")\nprint(f\"Input features shape: {features.shape}\")\nprint(f\"Output features shape: {output_features.shape}\")\n\nassert output_features.shape == (batch_size, num_points, output_feature_dim)\nprint(\"cuequivariance quickstart example ran successfully!\")","lang":"python","description":"This quickstart demonstrates how to use the PointCloudTransformer module from cuequivariance. It initializes a batch of 3D points and associated features, then processes them through the transformer on a CUDA-enabled GPU. This highlights the library's core functionality for equivariant operations on point cloud data and includes essential runtime CUDA checks."},"warnings":[{"fix":"Ensure you have a compatible CUDA-enabled GPU. Install the NVIDIA CUDA Toolkit (matching your PyTorch CUDA version if possible) and corresponding GPU drivers. Verify your PyTorch installation is compiled with CUDA support (e.g., `torch.cuda.is_available()` should be `True`).","message":"cuequivariance is a CUDA-dependent library. It requires a CUDA-enabled GPU, NVIDIA drivers, and the CUDA Toolkit installed on your system for both compilation during `pip install` and for runtime execution. Without a proper CUDA setup, the library will not function and installation may fail.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your PyTorch installation to version 2.0.0 or newer (e.g., `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118` for CUDA 11.8).","message":"The library explicitly requires PyTorch version 2.0.0 or newer. Using older PyTorch versions (e.g., < 2.0) will lead to API incompatibilities, compilation failures, or runtime errors.","severity":"gotcha","affected_versions":"All cuequivariance versions (requires PyTorch >= 2.0.0)"},{"fix":"Always refer to the latest official documentation or release notes when upgrading to new minor versions. Pin your `cuequivariance` version in `requirements.txt` to mitigate unexpected breaking changes in production environments (e.g., `cuequivariance==0.9.1`).","message":"As the library is currently in version 0.9.x (pre-1.0.0), its API is subject to change without strict backward compatibility guarantees between minor releases. Future updates may introduce breaking changes to module names, class signatures, or function parameters.","severity":"breaking","affected_versions":"All versions prior to 1.0.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure you have a CUDA-enabled GPU with up-to-date drivers. Install PyTorch with CUDA support (e.g., `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118` for CUDA 11.8). Verify `torch.cuda.is_available()` returns `True` before running any code using cuequivariance.","cause":"PyTorch is installed without CUDA support, CUDA drivers are not installed, or no CUDA-enabled GPU is detected on your system.","error":"RuntimeError: CUDA is not available"},{"fix":"Install the NVIDIA CUDA Toolkit relevant to your system and ensure its `bin` directory (containing `nvcc`) and `lib64` directory (containing CUDA libraries) are added to your system's PATH and `LD_LIBRARY_PATH` environment variables respectively.","cause":"Compilation error during `pip install` because the NVIDIA CUDA Toolkit is not correctly installed, or its `nvcc` compiler and CUDA libraries (`libcua.so`) are not in the system PATH and `LD_LIBRARY_PATH` (or equivalent environment variables).","error":"ninja: build stopped: subcommand failed. /usr/bin/ld: cannot find -lcuda"},{"fix":"Import specific modules from their correct submodule path. For example, use `from cuequivariance.modules import PointCloudTransformer` instead of `from cuequivariance import PointCloudTransformer`.","cause":"Attempting to import modules directly from the top-level `cuequivariance` package when they are nested within its submodules (e.g., `modules`).","error":"AttributeError: module 'cuequivariance' has no attribute 'PointCloudTransformer'"}]}