QuantBlockchain/qcv-dataset

QCV-Dataset

132 Quantum Circuits · 5 Core Modalities · 792 Experiment Results · Bilingual Annotations

The first multimodal quantum circuit dataset for training and evaluating AI systems on quantum circuit understanding, code generation, and verification.

Dataset Description

• —Curated by: Dongping Liu, Aoyu Zhang, Luyao Zhang
• —Language(s): English (EN), Chinese (CN) — bilingual annotations
• —License: MIT
• —Modality: Multimodal — Images (circuit diagrams), Text (code + descriptions), Numerical (state vectors)

Dataset Summary

QCV-Dataset contains 132 quantum circuits across 13 categories, each with 5 core modalities: circuit diagram image, Amazon Braket SDK code, Qiskit code, simulation results (state vectors), and bilingual expert annotations. Additionally, 792 experimental model invocations (3 models × 2 prompting modes × 132 circuits) provide a comprehensive benchmark for evaluating visual AI agents on quantum code generation.

Dataset Structure

Config: circuits (default)

Config: experiments

Config: failures

Annotated failure cases from model evaluation with error type classification.

Config: equivalences

Circuit equivalence pairs for verification benchmarking.

Categories (13)

Dataset Creation

Data Collection

• —Circuit diagrams generated with Qiskit QuantumCircuit.draw("mpl", style="iqp") at 150 DPI with tight bounding boxes
• —Ground-truth code implemented in Amazon Braket SDK
• —All circuits verified executable on Amazon Braket LocalSimulator

Annotations

• —Bilingual descriptions (EN/CN) created by domain experts
• —Categories assigned based on algorithm type and complexity
• —Difficulty levels determined by circuit depth and gate complexity

Experiment Results

Key Findings:

• —45 circuits passed all 6 model-mode combinations
• —18 circuits failed all 6 combinations
• —Structural complexity (not qubit count) determines success
• —Chain-of-thought provides no benefit for strong models (delta = -3 to -4%) but modest improvement for weakest (delta = +5%)

Usage

Load the dataset

from datasets import load_dataset

# Load main circuits dataset
circuits = load_dataset("QuantBlockchain/qcv-dataset", "circuits", split="train")

# Load experiment results
experiments = load_dataset("QuantBlockchain/qcv-dataset", "experiments", split="train")

# Access a sample
sample = circuits[0]
print(sample["id"])              # C01_deutsch_jozsa_3
print(sample["circuit_image"])    # PIL.Image object
print(sample["braket_code"])      # Python code string
print(sample["description_en"])   # English description
print(sample["description_cn"])   # Chinese description

Filter by category

algo_circuits = circuits.filter(lambda x: x["category"] == "classical_algorithms")
small_circuits = circuits.filter(lambda x: x["qubits"] <= 3)
passing_circuits = circuits.filter(lambda x: x["all_pass"] == True)

Analyze experiment results

from collections import Counter

model_pass = {}
for exp in experiments:
    model = exp["model"]
    if model not in model_pass:
        model_pass[model] = {"total": 0, "passed": 0}
    model_pass[model]["total"] += 1
    if exp["pass"]:
        model_pass[model]["passed"] += 1

for model, stats in model_pass.items():
    rate = stats["passed"] / stats["total"] * 100
    print(f"{model}: {rate:.1f}% ({stats['passed']}/{stats['total']})")

Data Governance & Croissant

This dataset follows Croissant metadata standards for machine-readable dataset descriptions. The dataset card uses structured YAML front matter for discoverability and includes:

• —Data provenance: Synthetic generation via Qiskit + expert curation
• —Annotation methodology: Expert-generated bilingual descriptions
• —Verification protocol: Unitary matrix fidelity >= 0.99 on Braket LocalSimulator
• —Known limitations: Framework-specific (Braket SDK), simulation-only, EN/CN bilingual only
• —Bias considerations: 23.5% blockchain-relevant circuits may skew toward cryptographic applications

The dataset also includes a Croissant-RAI (croissant-rai.jsonld) extension documenting responsible AI considerations, data limitations, and recommended use cases.

Limitations and Biases

Citation

@misc{liu2026qcv,
  title={QCV: Cost-Aware Evaluation of Visual AI Agents for Quantum Code Generation},
  author={Liu, Dongping and Zhang, Aoyu and Zhang, Luyao},
  year={2026},
  url={https://github.com/QuantBlockchain/quantum-circuit-vision}
}

License

MIT — see LICENSE

Additional Documentation

• —DATASHEET.md — Full dataset documentation following Gebru et al. (2021)
• —CITATION.cff — Machine-readable citation metadata
• —CIRCUIT_CATALOG.md — Full listing of all 132 circuits