Getting Started

CUDA-Q Algorithms is a primitive-first library of fault-tolerant quantum algorithms built on CUDA-Q. It is pure Python: quantum primitives are @cudaq.kernel device functions, and the classical preprocessing is NumPy/SciPy.

What’s in the library

The library is a small set of layers that feed each other:

  • Chemistry preprocessing (classical) turns a molecule — via PySCF, Psi4, or an FCIDUMP file — into integral tensors and a qubit Hamiltonian, and can compress that Hamiltonian by double factorization before anything quantum happens.

  • Block encodings embed a Hamiltonian into a unitary circuit so that quantum algorithms can consume it. PauliLCU ships with the library, and a structural protocol lets you plug in an encoding of your own.

  • Algorithm primitives build circuits from those inputs: qubitization walks (Walk), the quantum singular value transformation (QSVT), and Suzuki–Trotter product formulas (Trotter).

  • State preparation produces the initial states those circuits act on: Hartree–Fock references, unitary-coupled-cluster ansätze, and Givens-rotation Slater determinants.

The goal is to provide the fault-tolerant era’s standard circuit building blocks as small, hardware-shaped, independently validated kernels that compose — with each other and with your own kernels — rather than as end-to-end application workflows. A typical path through the library reads left to right: molecule → qubit Hamiltonian → block encoding → walk/QSVT circuit → expectation values or spectra.

Installation

The package is a single, CUDA-agnostic py3-none-any wheel that depends on the cudaq metapackage (which selects the matching cuda-quantum-cuNN for your platform):

$ pip install cudaq-algorithms

Note

Until the first PyPI release, install from a release wheel with pip install cudaq-algorithms --find-links <wheel directory> or build from source (below).

Building from source

The library needs no compilation — it is pure Python. Point PYTHONPATH at the python/ directory of a checkout (with cudaq importable) and run the tests:

$ PYTHONPATH=python python3 -m pytest tests/python -q

The dense-reference tolerances require an fp64 simulator; conftest.py selects qpp-cpu by default (override with CUDAQ_DEFAULT_SIMULATOR).

The primitive-first philosophy

Every algorithm is exposed as a factory that emits a CUDA-Q kernel — a quantum device function, compiled and run by CUDA-Q (see the CUDA-Q kernel basics if the term is new). The constructor holds the problem, and a method call holds the choices.

from cudaq_algorithms import PauliLCU, Walk, QSVT, Trotter

encoding = PauliLCU(hamiltonian)      # block-encode H / alpha
walk = Walk(encoding).kernel(power=3) # qubitization walk W^3
evolve = QSVT(encoding).kernel(phases)
trotter = Trotter(hamiltonian).kernel(time=1.0, steps=10, order=2)

Consumers such as Walk and QSVT are generic over the structural BlockEncoding protocol (cudaq_algorithms.block_encoding) — implement the documented factory surface and any encoding plugs in, no inheritance required. See Block encodings for the protocol and a “bring your own encoding” walkthrough.

Where to go next