qubithub.toml Reference

The qubithub.toml file is the single source of truth for every circuit on QubitHub. You write the TOML; the platform generates metadata.json from it. Never hand-author metadata.json.

Why TOML?

TOML is a configuration format designed for humans — like YAML but without implicit typing gotchas, and like JSON but with comments and less boilerplate. It’s the same format used by Rust (Cargo.toml), Python (pyproject.toml), and Julia (Project.toml).

3-Tier progressive complexity

QubitHub manifests follow a progressive model — start simple and add sections as needed.

Tier 1 — Minimal (6 required fields)

Every circuit needs at least this:

[project]
name = "bell-state"
title = "Bell State"
type = "circuit"
framework = "qiskit"
entry_point = "circuit.py"
qubits = 2

Tier 2 — Standard

Adds description, tags, gates, execution config, and educational metadata:

schema_version = "1.0.0"

[project]
name = "vqe-h2"
title = "VQE for H2 Ground State"
type = "circuit"
framework = "pennylane"
framework_version = "0.38.0"
entry_point = "circuits/main_circuit.py"
qubits = 4
depth = 24
gates = ["H", "CX", "RY", "RZ"]
category = "chemistry"
difficulty = "intermediate"
tags = ["vqe", "chemistry", "variational"]

[execution]
default_backend = "default.qubit"
default_shots = 4096
timeout_seconds = 60

[educational]
level = "intermediate"
concepts = ["variational-algorithms", "hamiltonian-simulation"]
prerequisites = ["bell-state", "single-qubit-gates"]
learning_outcomes = [
    "Understand the VQE hybrid classical-quantum loop",
    "Implement a hardware-efficient ansatz",
]
estimated_time = "45 minutes"
next_circuits = ["vqe-lih", "qaoa-maxcut"]

[expected_output]
dominant_states = ["0011", "1100"]
probability_range = [0.35, 0.65]

Tier 3 — Advanced

Adds parameters, hardware requirements, reproducibility, multi-framework implementations, and references:

schema_version = "1.0.0"

[project]
name = "qaoa-maxcut"
title = "QAOA for MaxCut"
type = "circuit"
framework = "qiskit"
framework_version = "1.3.0"
entry_point = "circuits/main_circuit.py"
qubits = 6
depth = 42
gates = ["H", "CX", "RZ", "RX"]
category = "optimization"
difficulty = "advanced"
tags = ["qaoa", "optimization", "maxcut", "combinatorial"]

[execution]
default_backend = "aer_simulator"
default_shots = 8192
timeout_seconds = 120

[hardware]
connectivity = "heavy-hex"
min_qubits = 6
required_gates = ["h", "cx", "rz", "rx"]
backend_compatibility = ["aer_simulator", "ibm_brisbane", "ibm_kyoto"]
noise_model = "ibm_brisbane_2026q1"

[parameters]
gamma = { default = 0.785, range_min = 0.0, range_max = 3.14159, description = "Problem unitary angle" }
beta = { default = 0.393, range_min = 0.0, range_max = 3.14159, description = "Mixer unitary angle" }

[reproducibility]
backend_used = "aer_simulator"
shots_used = 8192
seed = 42
transpilation_level = 3
framework_version_tested = "1.3.0"
last_verified = "2026-03-01"

[implementations]
qiskit = "circuits/qiskit/main_circuit.py"
pennylane = "circuits/pennylane/main_circuit.py"

[educational]
level = "advanced"
concepts = ["qaoa", "combinatorial-optimization", "mixer-hamiltonian"]
prerequisites = ["vqe-h2", "grover-search"]
learning_outcomes = [
    "Implement QAOA for graph optimization problems",
    "Understand the relationship between circuit depth and approximation quality",
]
estimated_time = "90 minutes"
next_circuits = ["qaoa-tsp", "qaoa-portfolio"]

[expected_output]
dominant_states = ["101010", "010101"]
probability_range = [0.25, 0.45]

[[references.papers]]
title = "A Quantum Approximate Optimization Algorithm"
authors = ["Farhi, E.", "Goldstone, J.", "Gutmann, S."]
year = 2014
arxiv = "1411.4028"

[files]
readme = "README.md"
source = "circuits/qiskit/main_circuit.py"
tests = "tests/"
results = "results/"

---

Field reference

Top-level

Field	Type	Required	Default	Description
schema_version	string	no	"1.0.0"	Manifest schema version (semver)

[project] (required)

Field	Type	Required	Default	Description
name	string	yes	—	URL slug: lowercase, hyphens, 1–100 chars
title	string	yes	—	Human-readable display name
type	string	yes	—	"circuit", "dataset", "space", or "benchmark"
framework	string	yes	—	"qiskit", "pennylane", "cirq", "braket", or "openqasm3"
entry_point	string	yes	—	Path to main file, relative to repo root
qubits	integer	yes	—	Number of qubits used
description	string	no	from README	Short description (1–2 sentences)
framework_version	string	no	—	Framework version the circuit targets
depth	integer	no	—	Circuit depth
gates	string[]	no	[]	Gate names used (e.g., ["H", "CX", "RY"])
category	string	no	—	Primary category (see below)
difficulty	string	no	"beginner"	"beginner", "intermediate", or "advanced"
tags	string[]	no	[]	Searchable tags
is_public	boolean	no	true	Public visibility

[execution] (optional)

Controls how qubithub execute runs the circuit.

Field	Type	Default	Description
default_backend	string	framework-dependent	Qiskit: "aer_simulator", PennyLane: "default.qubit", Cirq: "cirq.Simulator"
default_shots	integer	1024	Measurement shots (1–100,000)
timeout_seconds	integer	30	Max execution time (1–300)

[hardware] (optional)

Quantum hardware requirements.

Field	Type	Default	Description
connectivity	string	"any"	Topology: "any", "linear", "grid", "heavy-hex", "sycamore", "all-to-all"
min_qubits	integer	project.qubits	Minimum hardware qubits
required_gates	string[]	[]	Required gate set (lowercase)
backend_compatibility	string[]	["aer_simulator"]	Compatible backends
noise_model	string	—	Noise model identifier

[parameters] (optional)

For variational circuits. Each parameter is an inline table:

[parameters]
theta = { default = 0.785, range_min = 0.0, range_max = 6.283, description = "Rotation angle" }

Fields: default (number), range_min (number), range_max (number, optional), description (string).

[reproducibility] (optional)

Execution context for reproducing results.

Field	Type	Description
backend_used	string	Backend used for reference results
shots_used	integer	Shot count for reference results
seed	integer	Random seed for reproducible simulation
transpilation_level	integer	Qiskit transpilation level (0–3)
framework_version_tested	string	Framework version used
last_verified	string	ISO date of last successful run

[implementations] (optional)

Multi-framework support. Maps framework name to entry point:

[implementations]
qiskit = "circuits/qiskit/main_circuit.py"
pennylane = "circuits/pennylane/main_circuit.py"

[educational] (optional)

Field	Type	Description
level	string	"beginner", "intermediate", or "advanced"
concepts	string[]	Quantum concepts demonstrated
prerequisites	string[]	Circuit slugs to complete first
learning_outcomes	string[]	What the learner will understand
estimated_time	string	Study time estimate (e.g., "45 minutes")
next_circuits	string[]	Suggested follow-up circuits

[expected_output] (optional)

Reference measurement results for verification.

Field	Type	Description
dominant_states	string[]	Most probable measurement outcomes
probability_range	number[]	Expected probability range [min, max]

[references] (optional)

Academic citations using TOML array-of-tables:

[[references.papers]]
title = "Paper Title"
authors = ["Author, A."]
year = 2014
arxiv = "1411.4028"
doi = "10.1038/..."

[[references.textbooks]]
title = "Textbook Title"
authors = ["Author, A."]
section = "§4.7"

[files] (optional)

Path overrides for non-standard file locations:

[files]
readme = "README.md"
source = "circuits/main_circuit.py"
params = "params.json"
tests = "tests/"
results = "results/"

---

Categories

Valid values for project.category:

Category	Description
entanglement	Bell states, GHZ, W states
algorithm	Grover’s, Shor’s, Deutsch-Jozsa
optimization	QAOA, VQE, variational methods
chemistry	Molecular simulation
machine_learning	Quantum kernels, QNNs, classifiers
error_correction	Surface codes, repetition codes
communication	Teleportation, superdense coding
cryptography	QKD, BB84, random number generation
simulation	Hamiltonian simulation, trotterization
transform	QFT, phase estimation
utility	Helper circuits, testing primitives
ansatz	Variational circuit templates
research	Paper reproductions

---

Validation rules

1. project.name must be lowercase, hyphens only, 1–100 characters
2. project.type must be a recognized type
3. project.framework must be one of: qiskit, pennylane, cirq, braket, openqasm3
4. project.entry_point must reference an existing file in the repository
5. project.qubits must be a positive integer
6. execution.default_shots must be 1–100,000
7. execution.timeout_seconds must be 1–300
8. project.difficulty must be one of: beginner, intermediate, advanced
9. schema_version, if present, must be a supported version (currently "1.0.0")
10. hardware.connectivity recommended values: any, linear, grid, heavy-hex, sycamore, all-to-all — unrecognized values produce a warning but are not rejected

---

Relationship to metadata.json

metadata.json is auto-generated by the platform from your qubithub.toml. The precedence chain:

1. qubithub.toml (source of truth — what you author)
2. Stored metadata.json (generated artifact — what API consumers read)
3. Database synthesis (fallback for legacy circuits without a manifest)

Never hand-author metadata.json. It will be overwritten on the next push.

---

CLI usage

# Scaffold a new circuit with a template manifest
qubithub circuits init my-circuit --framework qiskit

# Push validates the manifest before upload
qubithub circuits push

# View the generated metadata
qubithub circuits metadata -f json

Next steps

• CLI / SDK Quickstart — qubithub circuits init scaffolds this file
• Contributing Circuits — full publishing workflow
• FAQ — common questions