VQCSim Experimental Artifact

This repository is now centered on the generic OpenQASM-to-Torch lowering flow, the RQ1 applicability/parity suite, and the RQ2 time/VRAM crossover suite. The legacy classifier-backed QRing/VQCSim benchmark stack has been removed.

Quick Start

From repository root:

python3 -m venv .venv313
source .venv313/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install "mqt.bench==2.1.0"

export RUN_ROOT="$PWD/results/rq1_$(date +%Y%m%d_%H%M%S)"
bash scripts/run_mqtbench_rq1_suite.sh "$RUN_ROOT"

export RUN_ROOT="$PWD/results/rq2_$(date +%Y%m%d_%H%M%S)"
bash scripts/run_mqtbench_rq2_suite.sh "$RUN_ROOT"

RQ2 full multi-backend GPU stack (Linux + NVIDIA):

# Prefer Python 3.11 for qiskit-aer GPU wheels.
python -m pip install -r requirements-full-linux-cu128.txt

On Python 3.12+, this installs CPU qiskit-aer fallback when GPU Aer wheel is unavailable. For GPU Aer, keep the pinned stack from requirements-full-linux-cu128.txt and avoid unpinned pip install qiskit (that can pull Qiskit 2.x and break Aer 0.15.x import compatibility).

Optional Qandle extension (Python 3.12+):

python3.12 -m venv .venv312-qandle
source .venv312-qandle/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-full-linux-cu128.txt
python -m pip install -r requirements-qandle-py312.txt

Use that env for exploratory RQ2 runs that add qandle. Keep it separate from the strict default RQ2 env because Qandle currently requires Python 3.12+, while GPU Qiskit Aer typically requires Python 3.11.

Primary outputs:

• $RUN_ROOT/run_summary.json
• $RUN_ROOT/records.csv
• $RUN_ROOT/tables/*.csv
• $RUN_ROOT/plots/*.png

RQ4 selector tools:

• ./vqcsim-oracle (canonical selector CLI)
• python3 code/build_vqcsim_selector_model.py
• python3 code/vqcsim_calibrate.py
• python3 code/evaluate_vqcsim_selector.py

Documentation

• Reproduction guide
• Experiment README
• Experiment design notes

Scope

The supported claims are:

• for supported static MQT Bench circuits, a generic torch-native execution path can be constructed and checked against Qiskit for semantic parity.
• for core VQC families, RQ2 reports backend time/VRAM tradeoffs and crossover boundaries across inference/training modes and batch-size sweeps.

This repository does not currently include the legacy QRing/classifier benchmark stack.