FuzzQ Artifact: Shaking Up Quantum Simulators with Fuzzing and Rigour

Overview

FuzzQ is a framework that combines formal methods with systematic differential testing to validate quantum simulators. It generates constraint-guided circuits (via Alloy), instantiates them across simulators (Qiskit, Cirq, PennyLane), and detects discrepancies via statistical oracles.

For complete instructions, figures, and troubleshooting, see the bundled README.md inside the archive (it contains much more detail than this description).

Relation to publication

• Paper: Shaking Up Quantum Simulators with Fuzzing and Rigour (DOI: 10.1145/3763100)

• This record is the final, camera-ready artifact corresponding to the accepted paper

What’s included

• Complete evaluation pipeline for claims C1–C7 (coverage is Figure 6; C1 figures are 7a, 7b, 8, 9)

• Core tool: tools/fuzzQ.py for standalone differential testing on XML circuits

• Data for full reproducibility: data/execution_logs/ and data/xml_seeds/

• Docker setup and scripts (Dockerfile, docker-compose.yml, run-all-claims.sh, quick-demo.sh)

• MIT License

How to run (Docker)

# Quick smoke test (~3 min)
docker compose up fuzzq-artifact

# Full automated evaluation (~5 min; ~45 min including review)
bash run-all-claims.sh

Outputs are written to outputs/.

Reusability

• Using FuzzQ independently: see README section “Using FuzzQ Independently”

• Adding new simulators: see README section “Supporting Additional Simulators” (adapter pattern with required interface methods)

Reproducibility

Deterministic seeds, tested on Docker 20.10+/Compose 1.29+, 8GB RAM (16GB recommended). Figures and coverage results reproducible from included data and scripts.

License

MIT (see LICENSE)