DynQ is a topology-agnostic quantum virtual machine (QVM) hypervisor for multiprogramming on Qiskit-compatible backends. It discovers high-quality, non-overlapping qubit regions from backend topology and calibration data, then packs multiple quantum circuits into one backend submission.

The implementation supports IBM Quantum backends through Qiskit Runtime and AWS Braket devices through qiskit-braket-provider.

dynQ/
  api/          Public QVM and hypervisor interfaces
  compiler/     Circuit combining and backend execution helpers
  graph/        Hardware graph construction from backend topology data
  offline/      Atomic-unit discovery, scoring, and set packing
  online/       Allocation state and online placement strategies
  benchmarks/   Benchmark runners and fidelity analysis tools
  examples/     Usage examples and provider-specific reproductions
  tests/        Pytest suite
benchmark_results/
cache/           Cached backend data and compilation state for reproducibility
docs/            Algorithm and implementation notes

The checked-in .pkl, JSON, log, and report files under cache/, and benchmark_results/ are retained as reproducibility artifacts. Do not delete them when packaging a reproduction run.

python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate

pip install -r requirements.txt

Optional provider packages:

pip install qiskit-ibm-runtime

# Use the bundled provider copy when reproducing Braket runs from this folder.
pip install -e ./qiskit-braket-provider

Keep credentials in environment variables or a local .env file. .env is ignored and should not be committed.

from qiskit import QuantumCircuit
from qiskit_ibm_runtime import QiskitRuntimeService
from dynQ import DynQHypervisor

service = QiskitRuntimeService(token="<token>")
backend = service.backend("ibm_kingston")
hypervisor = DynQHypervisor(backend)

qc = QuantumCircuit(3, 3)
qc.h(0)
qc.cx(0, 1)
qc.cx(1, 2)
qc.measure_all()

job = hypervisor.run([qc], shots=1024)
print(job.result()[0])

import os
from qiskit import QuantumCircuit
from qiskit_braket_provider import BraketProvider
from dynQ import DynQHypervisor

os.environ["AWS_PROFILE"] = "your-aws-profile"
os.environ["AWS_DEFAULT_REGION"] = "us-west-1"

backend = BraketProvider().get_backend("Ankaa-3")
hypervisor = DynQHypervisor(backend)

qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

job = hypervisor.run([qc], shots=100)
print(job.result()[0])

Generate ideal noiseless reference probabilities:

python dynQ/benchmarks/generate_ideal.py \
  small \
  ./benchmark_results/ideal_results.json \
  --gpu

Run DynQ on an IBM noise simulator:

python dynQ/benchmarks/dynq_runner.py \
  --category small \
  --output-dir ./benchmark_results/kingston/dynq/small \
  --workload-id 1 \
  --backend ibm_kingston \
  --max-batch-size 10 \
  --gpu

Run DynQ on AWS Braket:

aws sso login --profile your-aws-profile

python dynQ/benchmarks/dynq_runner.py \
  --category small \
  --output-dir ./benchmark_results/ankaa3/dynq/small \
  --workload-id 1 \
  --backend Ankaa-3 \
  --shots 1024 \
  --max-batch-size 10 \
  --profile your-aws-profile \
  --region us-west-1

Run the one-circuit baseline:

python dynQ/benchmarks/run_baseline.py \
  --category small \
  --output-dir ./benchmark_results/kingston/baseline_noise/small \
  --backend ibm_kingston \
  --gpu

Analyze fidelity:

python dynQ/benchmarks/analyze_fidelity.py analyze \
  ./benchmark_results/kingston/dynq/small/benchmark_results_1.json \
  ./benchmark_results/ideal_results.json \
  --output-dir ./benchmark_results/kingston/dynq/small/fidelity_reports/

For asynchronous hardware jobs, rerun the same benchmark with --fetchresult after the provider reports completion. Existing result files are updated in place.

pytest -v

Common subsets:

pytest -v -m "not braket_remote and not qpu"
pytest dynQ/tests/test_braket_sanity.py -v -m braket_local
pytest -v --braket-backend sv1 --aws-profile your-aws-profile
pytest -v --braket-backend ankaa-3 --aws-profile your-aws-profile --aws-region us-west-1

See dynQ/tests/README.md for the test tiers and Braket-specific options.

• docs/ALGORITHM.md describes the hardware graph, atomic-unit discovery, allocation, circuit combining, and fidelity workflow.
• dynQ/examples/ankaa3_github_issue.md documents a provider-specific Ankaa-3 qubit-label mismatch reproduction.

Tracked source files, tests, benchmark artifacts, cached .pkl state, and reference results are intended to be included for reproducibility. Local credentials, virtual environments, pytest caches, build outputs, and editor metadata are ignored.

This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0).

You may use, modify, and distribute this software under the terms of the LGPL-3.0 license. However, any modifications to the core library itself must be released under the same license.

For full details, see the LICENSE file in this repository or visit: https://www.gnu.org/licenses/lgpl-3.0.html

Maintainer: Shusen Liu
Affiliation: CSIRO / Pawsey Supercomputing Research Centre
Email: shusen.liu@csiro.au