Problem Instance Schema

Data Schema Overview

The Quantum Advantage Tracker (QAT) uses standardized JSON schemas to define the problem instances used across its three pathways. These schemas serve as the "source of truth" for the website, allowing the platform to dynamically generate tracking tables and provide links to raw experiment files.

If you are contributing a new circuit model or Hamiltonian, your metadata must adhere to the structures defined below.

Circuit Model Schema

Used by the Observable Estimations and Classically Verifiable Problems pathways, this schema categorizes quantum circuits by their model type (e.g., "Random Circuit Sampling") and lists specific experimental instances.

JSON Structure

The schema is a dictionary where each key represents a Circuit Model Type. Each type contains an array of instances.

{
  "Model Type Name": {
    "instances": [
      {
        "id": "unique-instance-id",
        "path": "filename.extension",
        "qubits": 50,
        "gates": 1000
      }
    ]
  }
}

Property Definitions

| Property | Type | Description | | :--- | :--- | :--- | | Model Type | string | The category of the circuit (e.g., "Time Evolution", "Sycamore"). | | id | string | A unique identifier for the specific instance (e.g., n53-d20-i0). | | path | string | The relative filename within the model's directory (e.g., circuit_1.qasm). | | qubits | number | The total number of qubits required for the circuit. | | gates | number | The total gate count (complexity) of the circuit. |

Hamiltonian Schema

Used by the Variational Problems pathway, this schema tracks the physical systems and mathematical operators used for variational algorithms.

JSON Structure

Similar to circuit models, Hamiltonians are grouped by system type (e.g., "Fermi-Hubbard", "Ising Model").

{
  "System Type": {
    "instances": [
      {
        "id": "system-identifier",
        "path": "hamiltonian-data.json",
        "qubits": 12,
        "gates": 0
      }
    ]
  }
}

Property Definitions

| Property | Type | Description | | :--- | :--- | :--- | | System Type | string | The class of the Hamiltonian system. | | id | string | Unique identifier for the Hamiltonian instance. | | path | string | Relative path to the operator definition file (typically JSON or HDF5). | | qubits | number | The number of spins or orbitals represented in the system. | | gates | number | Usually set to 0 for raw Hamiltonians, or used to represent decomposition complexity if applicable. |

Directory & File Conventions

To ensure the tracker correctly resolves links to your files, you must place your data files and the corresponding JSON metadata in specific locations within the repository:

File Resolution Logic

The QAT website automatically constructs GitHub URLs based on the type and path provided in your JSON.

• For Circuits: data/[pathway]/circuit-models/[type]/[path]
• For Hamiltonians: data/variational-problems/hamiltonians/[type]/[path]

Example Contribution Directory

If you are adding a "Heisenberg" model instance to Variational Problems:

1. Place your raw data file at: data/variational-problems/hamiltonians/Heisenberg/instance_1.json
2. Update the hamiltonians.json metadata at: data/variational-problems/hamiltonians.json

   {
     "Heisenberg": {
       "instances": [
         {
           "id": "Heis-1D-12",
           "path": "instance_1.json",
           "qubits": 12,
           "gates": 0
         }
       ]
     }
   }
   

Technical Types (TypeScript)

If you are developing components for the tracker, you can import the following type definitions:

export type CircuitInstance = {
  id: string;
  path: string;
  qubits: number;
  gates: number;
};

export type CircuitModels = {
  [modelType: string]: {
    instances: CircuitInstance[];
  };
};