Getting Started

Installation

CuQuantum.jl requires a CUDA-capable GPU and the NVIDIA cuQuantum SDK (provided automatically via cuQuantum_jll).

using Pkg
Pkg.add(url="https://github.com/harmoniqs/CuQuantum.jl")

GPU Required

CuQuantum.jl requires a CUDA-capable GPU at runtime. The package will load without a GPU, but all computation functions require one. Supported architectures: Turing (T4), Ampere (A100), Ada (L4/L40), Hopper (H100), Blackwell (B200).

Dependencies

CuQuantum.jl depends on:

CUDA.jl — Julia GPU computing
cuQuantum_jll — prebuilt cuQuantum SDK binaries
CEnum.jl — C enum support

All dependencies are installed automatically.

Verify Installation

using CuQuantum
using CuQuantum.CuDensityMat

# Check the cuDensityMat library version
v = CuDensityMat.version()
println("cuDensityMat version: $v")

# Create and close a workspace (verifies GPU + library connectivity)
ws = WorkStream()
close(ws)
println("CuQuantum.jl is working!")

Basic Workflow

Every CuQuantum.jl simulation follows this pattern:

Create a WorkStream — manages the GPU handle, workspace memory, and CUDA stream
Define elementary operators — single-mode operators (annihilation, number, Pauli) uploaded to GPU
Build operator terms — tensor products of elementary operators acting on specific modes
Assemble the composite operator — sum of terms with coefficients and duality flags
Prepare the action — one-time workspace allocation and contraction planning
Compute — evaluate $L[\rho]$ at a given time, as many times as needed
Clean up — close(ws)

See the Concepts section for details on each step.