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 intoYYYY-MM-DDusing theen-CAlocale.sortSubmissions<T>(arr: T[]): A generic sorter that organizes submissions bycreatedAtin 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,
// ...
};