Here is the updated, streamlined version of your README with the ablation dataset references removed and the citation simplified to a clean, textual format.
IterTestQ is the first testing framework designed specifically for cross-platform interoperability testing of quantum software stacks. Instead of analyzing a compiler or optimizer in isolation, IterTestQ repeatedly transfers programs across multiple platforms using OpenQASM—exposing subtle interoperability, compiler, and transformation bugs that remain completely invisible to traditional, single-platform testing.
Its core engine is the Import–Transform–Export (ITE) loop, which iteratively imports a quantum program into a platform, applies platform-native transformations (such as optimizations or gate-set translations), and exports it back to QASM. IterTestQ groups these variants into equivalence classes and validates them using symbolic equivalence checking (via QCEC), while simultaneously monitoring all platform operations for crashes.
-
23 Real-World Bugs Uncovered across Qiskit, PennyLane, Pytket, BQSKit, and Cirq—with 17 already confirmed or fixed by platform maintainers.
-
Novel ITE Process that iteratively mutates and transfers programs across platforms to generate highly diverse test suites.
-
Dual-Oracle Design combining runtime crash detection with symbolic equivalence checking (QCEC) without requiring probabilistic state execution.
-
High Efficiency capable of processing and transforming quantum programs in just 0.00089 seconds per program.
-
Complementary Code Coverage exercising tens of thousands of lines of deep translation code that traditional single-platform fuzzers miss.
├── qite/ # Core implementation of the IterTestQ framework
├── notebooks/ # Jupyter notebooks reproducing paper evaluation and figures
├── tests/ # Unit and integration tests
├── program_bank/ # Generated test programs, experimental outputs, and reduced bugs
├── config/ # Configuration files for IterTestQ execution runs
└── docker/ # Docker environment for reproducible runs and coverage collection
You must have the following software installed on your machine to run IterTestQ:
-
Conda — Recommended for managing Python environments and dependencies.
-
Docker — For reproducible, containerized test execution and coverage profiling.
-
screen (Optional) — Recommended for running long-duration fuzzing campaigns in the background.
Supported OS: We recommend Ubuntu 22.04.5 LTS or newer. The codebase is thoroughly evaluated on Ubuntu and we cannot guarantee out-of-the-box compatibility with other operating systems.
IterTestQ supports two distinct levels of replication depending on your objective.
This option recreates all figures and tables from our pre-compiled experimental data.
-
Download and Extract Artifacts: Download the unified data artifact from DOI 10.6084/m9.figshare.33016415. Extract its contents into
program_bank/artifact/. (Note: If you unpack the files elsewhere, updateARTIFACT_BASEat the top ofnotebooks/031_RQ_Results.ipynb). -
Set Up the Environment:
conda env create -f environment.yml
conda activate crosspl
- Run the Notebook: Open and execute
notebooks/031_RQ_Results.ipynbfrom top to bottom to regenerate the paper's results and figures:
jupyter notebook notebooks/031_RQ_Results.ipynb
Choose one of the execution methods below to generate new tests and collect execution data.
This is the most reliable method for reproducing the full pipeline with isolated dependencies and coverage collection.
-
Configure your run by inspecting or modifying the template at
config/demo_itertestq.yaml. -
Build the image and launch the test suite inside a background terminal session:
# (Optional) Use screen to protect the session
screen -S itertestq
# Build and execute
docker build -t itertestq -f docker/Dockerfile .
docker run -v $(pwd)/program_bank:/app/program_bank itertestq --config config/demo_itertestq.yaml
- Outputs and logs will be written to
program_bank/demo_itertestq/<run_id>/.
To execute IterTestQ directly on your host machine:
# Ensure your Conda environment is active
conda activate crosspl
# Run the entry script with your chosen configuration
python entry.py --config config/demo_itertestq.yaml
All outputs, including any detected program inequivalences or runtime failures, will populate under program_bank/demo_itertestq/<run_id>/.
We make all experimental datasets used to evaluate IterTestQ and its comparative baselines openly accessible via a single, archive repository:
- IterTestQ & MorphQ Dataset (DOI: 10.6084/m9.figshare.33016415) — This archive contains the complete generated program banks, execution logs, and MorphQ comparative execution runs.
If you use IterTestQ or our dataset in your academic research, please cite our paper:
Paper: IterTestQ: Assembly-Level, Cross-Platform Testing of Quantum Computing Platforms
Authors: Matteo Paltenghi and Michael Pradel
Venue: Proceedings of the ACM on Software Engineering (ISSTA 2026)
DOI: 10.1145/3832211