qf++

qf++ is a framework for quantum compilers. It generates structurally valid quantum programs across multiple quantum software stacks, then differentially tests them by comparing circuit simulation outputs across compiler optimisation levels.

Quick start

# 1. Setup
python3 -m scripts.setup

# 2. Run CI pipeline (10 circuits per grammar)
uv run -m scripts.run --num-tests 10

# 3. Run nightly (1200 circuits, saves interesting ones)
uv run -m scripts.run --nightly --num-tests 1200 --grammars pytket qiskit

# 4. Use the interactive fuzzer REPL directly
./build/qf
> pytket program   # set grammar + entry point
> 5               # generate 5 circuits
> quit

To run inside a separate environment, pull the docker image using

docker pull ghcr.io/ilaniwumbwe/qutefuzz-env:latest

If you prefer to build the image from sratch, run

./scripts/docker/build.sh

then

./scripts/docker/run.sh

to create a docker container and start a shell inside it. From there, run setup commands as normal.

Install external libs

To install external repos

python3 -m scripts.setup --libs {EXTERNAL LIBS}

To clone and build cuda-quantum from source without coverage collection enabled

python3 -m scripts.setup --libs cuda-quantum

To clone and build from source with coverage collection enabled

python3 -m scripts.setup --cov

Note:

• Run script is not set up to run fuzzing campaigns on instrumented compilers, due to the large volumes of data that would be dumped, and is not collected and deleted in batches. The coverage flag is more for development testing to see how well the test cases stress test the compiler. Currently, only CUDAQ compiler can be instrumented.

• If conan command fails, this is because the run needs to happen within the virtual env. Source first with

  source .venv/bin./activate

  then re-run setup command.

• Make sure that any time you use uv run, it is with the --no-sync flag, or use python3 directly. This is because the setup script in dev mode "tampers with" the .venv, uv sees that and tries to sync everything to match the lockfile. As a result, it reinstalls the release, uninstrumented pytket version from PyPI.

Supported quantum frameworks

Grammar file	Framework	Test method
pytket.qf	Pytket (TKET compiler)	KS test across optimisation levels 0–3
qiskit.qf	Qiskit + Aer	KS test across optimisation levels 0–3
cirq.qf	Cirq	KS test across 3 custom transpile levels
pennylane.qf	PennyLane Lightning	KS test across 4 transform pipelines
cudaq.qf	CUDA-Q	KS test across optimisation levels 0-3

Bugs found

QSS	Bug in	Status
Pytket	optimiser	fixed
Pytket	optimiser	ack
CUDA-Q	parser	ack
CUDA-Q	parser
Qiskit	basis translator	ack, duplicate
Pytket	parser
Pytket	routing pass

Acknowledgements

• Linenoise library for nicities in REPL loop like command history and tab completion.

Note

• Only GCC/clang compilers due to some use of GCC pragmas
• >= C++20 required