QuAIRKit Paper Experiment Code

This repository contains the scripts used to regenerate the numerical data and figure panels for the paper A Parallel Simulation Protocol for Structures in Quantum Circuit Design.

The table below maps each paper result to the script that regenerates its numerical data.

Paper result	Script to regenerate data	Data artifact	External requirement
Figure 3: compiled kernels vs. JIT for batched PQC training	python benchmark/execute.py --device-target cpu and python benchmark/execute.py --device-target gpu	plot/data/benchmark_cpu.json, plot/data/benchmark_gpu.json	GPU for the GPU run
Figure 4(b): QPE verification and resource inset	python application/execute.py --experiment qpe --profile paper --device-target cpu	plot/data/figure4_1.json	None
Figure 5(b): qutrit unitary inversion fidelity and resource band	python application/execute.py --experiment inversion --profile paper --device-target gpu	plot/data/figure4_2.json	GPU; MATLAB environment
Figure 6(b): Bell-state distillation fidelity and resource band	python application/execute.py --experiment distillation --profile paper --device-target cpu	plot/data/figure4_3.json	MATLAB environment

The circuit panels in Figures 4(a), 5(a), and 6(a) are static figure assets in the paper source. This repository regenerates the numerical data and plotted experiment panels listed above.

Environment Setup

Prepare the following before running the paper-scale scripts:

Requirement	Used for
Conda environment	Running the main scripts and creating separate environments for each package
GPU driver and CUDA runtime	Figure 3 GPU data and Figure 5(b) QuAIRKit training
MATLAB environment	Figure 5(b) and Figure 6(b) SDP baselines

The command-line tool is conda; this README uses Conda for the environment manager name. The included result JSON files were generated with an NVIDIA GeForce RTX 4090 Laptop GPU.

We recommend Python 3.10 for the main environment:

conda create -n quairkit-experiments python=3.10 -y
conda activate quairkit-experiments
pip install numpy scipy matplotlib psutil

The experiment runners create or reuse separate Conda environments for the packages being compared. Conda must therefore be available in PATH.

This repository provides local wheels under:

package/
├── quairkit/
├── pennylane/
├── tensorcircuit-ng/
└── matlab/

The runners select wheels from these directories to reproduce the paper results. To try different package versions, replace the corresponding wheels or adjust the runner install steps. The included result JSON files used QuAIRKit 0.5.1, PennyLane 0.44.1, TensorCircuit-NG 1.5.0, JAX/JAXLib 0.6.2, CUDA extra cuda12, and pennylane-lightning-gpu 0.44.0.

The Figure 5 and Figure 6 SDP baselines require a MATLAB environment with QETLAB and CVX configured. This repository includes MATLAB package assets under package/matlab/; alternatively, follow the QETLAB installation guide and the CVX instructions to configure the MATLAB environment. The runner installs matlabengine for the detected MATLAB release when the release is supported.

Repository Structure

.
├── README.md                         # This reproduction guide
├── plot.sh                           # Generate all plotted experiment panels from result JSON files
├── benchmark/
│   ├── execute.py                    # Regenerate Figure 3 data
│   ├── quairkit.py                   # QuAIRKit adapter for Figure 3
│   ├── pennylane.py                  # PennyLane adapter for Figure 3
│   ├── tensorcircuit_ng.py           # TensorCircuit-NG adapter for Figure 3
│   └── data/                         # Generated Figure 3 caches and logs
├── application/
│   ├── execute.py                    # Regenerate Figure 4(b), Figure 5(b), and Figure 6(b) data
│   ├── phase_estimation/             # Figure 4(b) QPE verification adapters
│   ├── unitary_inversion/            # Figure 5(b) qutrit unitary inversion adapters
│   ├── entanglement_distillation/    # Figure 6(b) Bell-state distillation adapters
│   └── data/                         # Generated application input caches
├── plot/
│   ├── figure3.py                    # Plot Figure 3
│   ├── figure4_1.py                  # Plot Figure 4(b)
│   ├── figure4_2.py                  # Plot Figure 5(b)
│   ├── figure4_3.py                  # Plot Figure 6(b)
│   └── data/                         # Included result JSON files
├── package/                          # Local wheels and MATLAB package assets used for reproduction
└── figs/                             # Generated PDFs

Regenerate Numerical Data

Use the commands in the Code-Paper Correspondence table to reproduce the paper-scale JSON files. These commands can create Conda environments, reinstall wheels, write cache files, and run for hours.

Generate Figures

After the JSON files are present, generate all plotted panels with:

bash plot.sh

This writes:

• figs/3_benchmark.pdf
• figs/4_qpe_exp.pdf
• figs/4_uinv_exp.pdf
• figs/4_dist_exp.pdf

plot.sh only generates figures from existing JSON files. It does not regenerate experiment data.

Figure 3 Details

Item	Setting
Paper result	Figure 3: performance of compiled kernels vs. JIT for batched PQC training
Compared packages	QuAIRKit, TensorCircuit-NG, PennyLane
Case (a)	Pure-state batched training with 8 qubits, depth 10, batch sizes 1, 10, 100, 1000
Case (b)	Batched noisy training with depth 10, amplitude-damping noise gamma=0.01, qubit counts 2 through 8
Shared optimizer settings	Adam, learning rate 0.01, 100 steps
dtype and seed	complex64, seed 2026
Resource guards	Host memory 20480 MB, GPU memory 14336 MB, timeout 3600 s

Figure 4(b) Details

Item	Setting
Paper result	Figure 4(b): QPE success probability across random input unitaries
Command	python application/execute.py --experiment qpe --profile paper --device-target cpu
Inputs	10000 random unitaries U = exp(iH)
Circuit size	6 ancilla qubits and system dimension 32
Compared backends	QuAIRKit and PennyLane
Resource guards	Host memory 30720 MB, timeout 3600 s

Figure 5(b) Details

Item	Setting
Paper result	Figure 5(b): qutrit unitary inversion fidelity and resource cost
Command	python application/execute.py --experiment inversion --profile paper --device-target gpu
Training and test sets	3000 train unitaries and 6000 test unitaries
Circuit setting	3 ancillary qutrits, query counts 1 through 10
QuAIRKit training	2000 fixed iterations per query count, scheduler enabled, parameter seeds 2026 + 100K + 27
Compared methods	QuAIRKit training and MATLAB SDP upper bounds
Resource guards	Host memory 30720 MB, timeout 3600 s

Figure 6(b) Details

Item	Setting
Paper result	Figure 6(b): Bell-state distillation fidelity and resource cost
Command	python application/execute.py --experiment distillation --profile paper --device-target cpu
Input copies	2, 3, 4, and 5 noisy Bell pairs
Noise model	Single-qubit depolarizing noise with gamma1=0.1 and gamma2=0.2
Compared methods	QuAIRKit learned protocols and MATLAB SDP upper bounds
Resource guards	Host memory 30720 MB, timeout 3600 s

Failure and Resource Records

The runners write JSON records during package install, experiment runs, skipped runs, and failures. A nonzero exit code means that at least one package install failed, one run failed, or the number of recorded runs was not the expected number.

Each run record stores time, memory, resource_cost = runtime_seconds * peak_memory_total_mb where available, and a failure type. Memory failures can create skip records for larger settings. Timeout records keep both the time limit and the observed wall time. MATLAB SDP failures are kept in the JSON output because they show where the SDP baseline runs out of memory or otherwise fails.

Hardware Used for the Included Results

The included result JSON files record runs on Linux with:

• Python 3.10.18 for the main environment.
• About 31.9 GB host memory.
• NVIDIA GeForce RTX 4090 Laptop GPU with about 16.4 GB memory.
• MATLAB R2023a with matlabengine 9.14.7 for the MATLAB-based application baselines.

Different hardware can change runtime, memory use, timeout behavior, and the exact point where OOM failures occur.