Data Architecture

The Quantum Advantage Tracker (QAT) uses a transparent, file-based data architecture. All information—from circuit definitions to experimental results—is stored as static JSON files and raw data formats within the /data directory. This allows for version-controlled submissions and enables the community to audit or reuse the data easily.

Directory Structure

The repository organizes data by the three primary pathways to quantum advantage. Each pathway contains a registry of problem instances and a registry of verified submissions.

data/
├── classically-verifiable-problems/
│   ├── circuit-models/         # Source files for circuits
│   ├── circuit-models.json     # Metadata for available models
│   └── submissions.json        # Registry of experimental results
├── observable-estimations/
│   ├── circuit-models/
│   ├── circuit-models.json
│   └── submissions.json
└── variational-problems/
    ├── hamiltonians/           # Source files for Hamiltonians
    ├── hamiltonians.json       # Metadata for available Hamiltonians
    └── submissions.json        # Registry of experimental results

Problem Instance Registries

Before a result can be submitted, it must reference a specific problem instance (a Circuit Model or a Hamiltonian). These are defined in metadata JSON files.

Circuit Models

Used in Observable Estimations and Classically Verifiable Problems. Each entry tracks the complexity of the quantum circuit.

{
  "model-category-name": {
    "instances": [
      {
        "id": "instance-unique-id",
        "path": "relative/path/to/circuit.qasm",
        "qubits": 40,
        "gates": 1200
      }
    ]
  }
}

Hamiltonians

Used in Variational Problems. These files define the physical systems being simulated.

{
  "system-type": {
    "instances": [
      {
        "id": "hamiltonian-id",
        "path": "relative/path/to/hamiltonian.json",
        "qubits": 20
      }
    ]
  }
}

Submissions Registry

The submissions.json file in each pathway folder acts as the "ledger" for the tracker. When a researcher submits a candidate via a GitHub Issue, the verified data is appended here.

Schema Overview

While schemas vary slightly by pathway, a standard submission includes:

Example Entry (Observable Estimations)

{
  "id": "sub-123",
  "instanceId": "heisenberg-model-v1",
  "createdAt": "2025-01-20T10:00:00Z",
  "institutions": "University of Quantum, Q-Corp",
  "value": "0.456",
  "errorBar": "0.001",
  "link": "https://arxiv.org/abs/..."
}

Data Access & Utility Functions

For developers or researchers programmatically interacting with the tracker, the following utility patterns are used to resolve data locations:

Resolving File Paths

To find the raw circuit or Hamiltonian file on GitHub, use the path resolution logic found in src/utils.ts.

// Example: Constructing a URL for a circuit model
const url = getCircuitInstanceUrl('observable-estimations', {
  type: 'heisenberg',
  path: 'model_40q.qasm'
});
// Returns: https://github.com/.../data/observable-estimations/circuit-models/heisenberg/model_40q.qasm

Aggregating Data

The frontend aggregates data across all pathways for features like the contributor marquee. Researchers can perform similar aggregations by importing the JSON files directly:

import submissionsCVP from './data/classically-verifiable-problems/submissions.json';
import submissionsOE from './data/observable-estimations/submissions.json';
import submissionsVP from './data/variational-problems/submissions.json';

const allSubmissions = [...submissionsCVP, ...submissionsOE, ...submissionsVP];

How to Contribute Data

Select an Instance: Browse the /data/*/circuit-models/ or /hamiltonians/ directories to find a problem instance to benchmark.
Submit Results: Use the provided GitHub Issue templates. Once verified, your results will be added to the relevant submissions.json.
Propose New Models: If you wish to track a new type of problem, submit a Pull Request adding the raw circuit/Hamiltonian files and updating the corresponding circuit-models.json or hamiltonians.json.