{"id":8045,"library":"cuequivariance-torch","title":"CUDA Equivariance for PyTorch","description":"cuequivariance-torch provides CUDA-accelerated implementations of equivariant operations for PyTorch. It aims to efficiently handle geometric symmetries in deep learning models, particularly for 3D data, by offering modules for SO(3) rotations and SE(3) translations. The current version is 0.9.1, and it maintains an active development pace with new features and optimizations.","status":"active","version":"0.9.1","language":"en","source_language":"en","source_url":"https://github.com/lucapassalacqua/cu-equivariance","tags":["pytorch","cuda","equivariant-networks","3d-vision","deep-learning","geometric-deep-learning"],"install":[{"cmd":"pip install cuequivariance-torch","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires PyTorch 2.1 or newer with CUDA enabled for core functionality.","package":"torch>=2.1","optional":false}],"imports":[{"symbol":"SO3Linear","correct":"from cuequivariance.modules import SO3Linear"},{"note":"The top-level package for imports is `cuequivariance`, not `cuequivariance-torch` (the PyPI package name).","wrong":"from cuequivariance_torch import SO3RotMat","symbol":"SO3RotMat","correct":"from cuequivariance import SO3RotMat"}],"quickstart":{"code":"import torch\nfrom cuequivariance.modules import SO3Linear\n\n# Ensure CUDA is available\nif not torch.cuda.is_available():\n    raise RuntimeError(\"CUDA is not available. cu-equivariance-torch requires a CUDA-enabled PyTorch installation with a GPU.\")\n\n# Define device\ndevice = torch.device(\"cuda\")\n\n# Example: SO(3) Linear layer for rotation matrices\n# Input dimensions: (batch, features_in, 3, 3) where the last two dimensions represent a 3x3 matrix\nbatch_size = 4\nfeatures_in = 16\nfeatures_out = 32\n\n# Create a dummy input tensor on the CUDA device\n# For SO3Linear, the input tensor's last two dimensions are treated as matrix components.\n# The layer handles the equivariant operations.\ninput_data = torch.randn(batch_size, features_in, 3, 3, device=device)\n\n# Instantiate an SO(3) Linear layer and move it to the CUDA device\nso3_linear_layer = SO3Linear(features_in, features_out).to(device)\n\n# Pass the input through the layer\noutput_data = so3_linear_layer(input_data)\n\nprint(f\"Input shape: {input_data.shape}, device: {input_data.device}\")\nprint(f\"Output shape: {output_data.shape}, device: {output_data.device}\")\n# Expected output shape: (batch_size, features_out, 3, 3)","lang":"python","description":"This quickstart demonstrates how to initialize and use an `SO3Linear` layer, a core module for SO(3) equivariant operations, ensuring that both the input tensor and the model are correctly placed on a CUDA device."},"warnings":[{"fix":"Ensure your PyTorch installation is `torch>=2.1` and is built with CUDA support (e.g., install `torch` using a command that specifies CUDA, such as from the official PyTorch website).","message":"The library explicitly requires PyTorch 2.1 or newer. Older versions of PyTorch or PyTorch installations without CUDA will not work.","severity":"breaking","affected_versions":"<0.9.0"},{"fix":"Always use `from cuequivariance import ...` or `from cuequivariance.modules import ...` for imports, not `cuequivariance_torch`.","message":"The PyPI package name is `cuequivariance-torch`, but the Python import name is `cuequivariance`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify that `torch.cuda.is_available()` returns `True`. If not, ensure you have a CUDA-compatible GPU, the necessary drivers, and PyTorch installed with CUDA support.","message":"This library is CUDA-accelerated and strictly requires a CUDA-enabled GPU and a PyTorch installation compiled with CUDA. It will not function on CPU-only setups.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Reinstall PyTorch with CUDA support (check official PyTorch installation instructions for your CUDA version) and ensure your system has a properly configured CUDA-enabled GPU with up-to-date drivers.","cause":"PyTorch was installed without CUDA support, or there is no CUDA-enabled GPU detected on the system.","error":"RuntimeError: CUDA is not available"},{"fix":"Change your import statements from `import cuequivariance_torch` or `from cuequivariance_torch import ...` to `import cuequivariance` or `from cuequivariance import ...`.","cause":"Attempting to import the library using its PyPI package name (`cuequivariance-torch`) rather than its internal module name (`cuequivariance`).","error":"ModuleNotFoundError: No module named 'cuequivariance_torch'"},{"fix":"Ensure all tensors involved in an operation are on the same device. Move your input tensors using `.to(device)` (e.g., `input_data.to('cuda')`) and your model using `.to(device)` (e.g., `model.to('cuda')`). Define `device = torch.device('cuda')` and consistently apply it.","cause":"One or more input tensors or the neural network module itself have not been moved to the CUDA device before computation.","error":"RuntimeError: Expected all tensors to be on the same device, but found at least two devices, cuda:0 and cpu"}]}