TypeScript Type System

The Quantum Advantage Tracker (QAT) uses a strictly typed system to manage quantum circuit definitions, Hamiltonian specifications, and community submissions. This ensures that data remains consistent across the three primary evaluation pathways.

Core Domain Types

The domain types are structured to support platform-agnostic benchmarking. You can find these definitions primarily within the src/types directory and used throughout the application data loaders.

Circuit Models

Circuit-based pathways (Observable Estimations and Classically Verifiable Problems) utilize the CircuitModels type to organize problem instances by category.

export type CircuitModels = {
  [key: string]: {
    instances: {
      id: string;      // Unique identifier for the instance
      path: string;    // Relative path to the circuit file in the repository
      qubits: number;  // Number of qubits required
      gates: number;   // Total gate count or depth
    }[];
  };
};

Usage Example: When fetching circuit data for the trackers, the data is typically flattened for display in tables:

import { flattenInstances } from '@/utils';

// Returns an array of instances with an additional 'type' property
const allInstances = flattenInstances(circuitModelsData);

Submissions

Submissions represent the experimental results contributed by the community. While the specific metrics vary by pathway, the base structure remains consistent to support the global contributors list and filtering.

export type Submission = {
  id: string;
  createdAt: string;   // ISO 8601 date string
  institutions: string; // Comma-separated list of participating organizations
  pathway: 'observable-estimations' | 'variational-problems' | 'classically-verifiable-problems';
  // ... pathway-specific result data
};

Pathway Data Structures

The project categorizes data into three distinct schemas based on the verification method:

1. Observable Estimations 📊

Focuses on expectation values. The types enforce the presence of mathematically grounded error bars and confidence intervals.

2. Variational Problems 🌀

Uses Hamiltonian-based definitions. Unlike circuit models, these focus on energy bounds and the variational principle.

// Used by getHamiltonianUrl helper
type HamiltonianInstance = {
  type: string; // The category of the Hamiltonian (e.g., "Ising", "Hubbard")
  path: string; // Filesystem path to the Hamiltonian specification
};

3. Classically Verifiable Problems 🗝️

Leverages the same CircuitModels structure but requires additional metadata for "witnesses" or known answers used for scoring.

Type-Safe Utilities

QAT provides several utility functions to interact with these types safely, particularly for generating links to the raw data hosted on GitHub.

URL Generators

To ensure internal links to data files are always correct, use the provided URL helpers:

| Function | Input | Description | | :--- | :--- | :--- | | getCircuitInstanceUrl | path: string, instance: { type, path } | Generates a GitHub URL for circuit model files. | | getHamiltonianUrl | instance: { type, path } | Generates a GitHub URL for Hamiltonian definitions. |

Example:

const url = getHamiltonianUrl({ 
  type: 'molecular-hydrogen', 
  path: 'h2_sto3g.json' 
});

Formatting and Sorting

Standardized helpers exist for handling common data operations across the UI:

• formatDate(dateString: string): Formats ISO strings into YYYY-MM-DD using the en-CA locale.
• sortSubmissions<T>(arr: T[]): A generic sorter that organizes submissions by createdAt in descending order (newest first).

Configuration and Routing

The project leverages Next.js Typed Routes. This ensures that all internal links (e.g., <Link href="/trackers/variational-problems">) are validated at compile time against the actual file structure in src/app.

To maintain type safety when adding new routes or data categories, ensure the next.config.ts includes:

const nextConfig: NextConfig = {
  typedRoutes: true,
  // ...
};