qf++

qf++ is a grammar-driven fuzzing 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.

Contents

Doc	What it covers
Ethos	Why the project exists and its design philosophy
Architecture	How the C++ fuzzer, Python tester, and CI pipeline fit together
Grammar System	Full reference for the .qf grammar language
Writing a Grammar	Step-by-step guide to adding a new quantum framework
MAP-Elites	How diversity-driven generation works and where to take it next
Differential Testing	How circuits are validated and bugs are classified
Dev	Notes for dev environment

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

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_py.qf	CUDA-Q	KS test (WIP)

Bugs found

QSS	Bug in	Status
Pytket	tket compiler	fixed
Pytket	tket2 compiler	ack

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