Installation Guide

Installation Methods

CUDA-QX provides multiple installation methods to suit your needs:

pip install

The simplest way to install CUDA-QX is via pip. You can install individual components:

# Install QEC library
pip install cudaq-qec

# Install Solvers library
pip install cudaq-solvers

# Install both libraries
pip install cudaq-qec cudaq-solvers

Docker Container

CUDA-QX is available as a Docker container with all dependencies pre-installed:

Pull the container:

docker pull ghcr.io/nvidia/cudaqx

Run the container:

docker run --gpus all -it ghcr.io/nvidia/cudaqx

The container includes:

CUDA-Q compiler and runtime
CUDA-QX libraries (QEC and Solvers)
All required dependencies
Example notebooks and tutorials

Building from Source

Prerequisites

Before building CUDA-QX from source, ensure your system meets the following requirements:

CUDA-Q: The NVIDIA quantum-classical programming model
CMake: Version 3.28 or higher (pip install cmake>=3.28)
GCC: Version 11 or higher
Python: Version 3.10, 3.11, or 3.12
NVIDIA GPU: CUDA-capable GPU with compute capability 12.0 or higher
Git: For cloning the repository

Build Instructions

Clone the repository:

git clone https://github.com/nvidia/cudaqx
cd cudaqx

Create and enter build directory:

mkdir build && cd build

Configure with CMake:

cmake .. -G Ninja \
    -DCUDAQX_ENABLE_LIBS="all" \
    -DCUDAQX_INCLUDE_TESTS=ON \
    -DCUDAQX_BINDINGS_PYTHON=ON \
    -DCUDAQ_DIR=$HOME/.cudaq/lib/cmake/cudaq \
    -DCMAKE_CXX_FLAGS="-Wno-attributes" \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=$HOME/.cudaqx

Build and install:

ninja install

CMake Build Options

CUDAQX_ENABLE_LIBS: Specify which libraries to build (all, qec, solvers)
CUDAQX_INCLUDE_TESTS: Enable building of tests
CUDAQX_BINDINGS_PYTHON: Enable Python bindings
CUDAQ_DIR: Path to CUDA-Q installation
CMAKE_INSTALL_PREFIX: Installation directory

Verifying Installation

To verify your installation, run the following Python code:

import cudaq_qec as qec
import cudaq_solvers as solvers

Troubleshooting (Common Issues)

CMake configuration fails:
- Ensure CUDA-Q is properly installed
- Verify CMake version (cmake --version)
- Check GCC version (gcc --version)
CUDA device not found:
- Verify NVIDIA driver installation
- Check CUDA toolkit installation
- Ensure GPU compute capability is supported
Python bindings not found:
- Confirm CUDAQX_BINDINGS_PYTHON=ON during build
- Check Python environment activation
- Verify installation path is in PYTHONPATH

For additional support, please visit our GitHub Issues page.