A Python library for bridging classical materials databases to first-quantized
Hamiltonians for fault-tolerant quantum simulation.
Status: early-stage, active development — schema is stabilizing, adapters
are stubs, exporters are planned. The core NIR and I/O layer are functional.
Breaking changes to QMatEntry before v1.0 will be announced in
CHANGELOG.md and accompanied by migration notes.
Why QMatBridge exists
Research groups developing fault-tolerant Hamiltonian-simulation algorithms —
block-encodings, qubitization variants, truncated Dyson series methods — need
realistic electronic-structure Hamiltonians to test and benchmark their
primitives. The standard path is to write one-off scripts that pull DFT data
from the Materials Project or similar databases, reformat it, and feed it into
a quantum compiler.
These scripts are rarely shared, almost never interoperable with more than one
quantum framework, and often omit the provenance information needed to reproduce
or compare results. When two groups report T-gate counts for "silicon", there
is no standard way to verify they used the same Hamiltonian.
QMatBridge addresses this by providing a neutral intermediate representation
(NIR) that any upstream database adapter can write to and any downstream
quantum compiler or resource estimator can read from, with full provenance
baked in.
where the material came from (SourceProvenance — database, functional,
pseudopotential, code version, retrieval timestamp)
what it looks like (StructureMetadata — formula, lattice, spacegroup)
how the Hamiltonian is constructed (BasisMetadata — plane-wave cutoff,
basis size)
what the oracle costs (OracleMetadata — LCU 1-norm λ, term breakdown,
SELECT/PREPARE circuit parameters, complexity annotations)
where it has been exported (ExportMetadata — framework, format, status,
artifact path)
Every entry carries a deterministic canonical_hash() over eleven setup fields
(source record, functional, electrons, basis cutoff and a few more), plus the lattice and
atomic positions when the entry records them, so that benchmark results can be traced to a
specific recorded calculation. See
what the hash covers.
Who it is for
QMatBridge is written for:
Algorithm researchers implementing block-encodings, qubitization circuits,
LCU decompositions, and related fault-tolerant primitives who need real
materials data without building a database-integration layer themselves.
Research software engineers building quantum-chemistry / quantum-computing
pipelines who need a stable, citable intermediate format between the DFT world
and the circuit world.
Resource estimation groups running systematic T-count and qubit studies
across a library of materials, who need reproducible, provenance-rich
Hamiltonian records.
If you are looking for a general materials informatics library, use
pymatgen or ASE.
QMatBridge is intentionally narrow: it is a bridge, not a database.
Current scope
In scope (v0.1):
Periodic bulk materials in a plane-wave basis
First-quantized Hamiltonian representation (T + U + V in reciprocal space)
Raw plane-wave NumPy exporter; OpenFermion InteractionOperator and Pauli-LCU exporters (a small point-ion plane-wave model); cross-database deduplication
Zero required dependencies in the core schema
Out of scope (for now):
Gaussian / LCAO / real-space basis sets
Molecular (non-periodic) systems
Excited-state or TDDFT Hamiltonians
Alexandria HSE06 / r²SCAN adapter (planned v0.4)
qualtran / pyLIQTR exporters (planned v0.5)
Design principles
Provenance-first. Every QMatEntry records the exact upstream source,
DFT functional, pseudopotential family, and retrieval timestamp. The
canonical_hash() method produces a stable SHA-256 digest over the physically
meaningful fields so that published results can be precisely reproduced.
Open and interoperable. The core schema has zero required dependencies.
Adapters for upstream databases and exporters for downstream frameworks are
optional extras — install only what you need. The NIR is designed to be
targeted by any adapter or consumed by any exporter without coupling the two.
Benchmark-oriented. Field names, norm conventions, and oracle metadata
types are chosen to align with the quantities reported in fault-tolerant
resource-estimation literature (LCU 1-norm λ, plane-wave count N,
rotation-precision bits b_r). The library should make it easy to reproduce
or extend a published benchmark, not just run a new one.
Representation-aware.OracleMetadata distinguishes between LCU,
qubitization, sparse-access, and tensor-hypercontraction decompositions.
TermMetadata stores per-physical-term norms so that methods that weight
T, U, and V differently can extract exactly the quantities they need.
Community-driven. The schema is a shared contract. Changes to
QMatEntry, MaterialReference, or HamiltonianMetadata require a public
discussion period and a minor-version bump. The governance model is documented
in GOVERNANCE.md; design discussions happen in GitHub
Discussions before any code is written.
Getting started
Installation
pip install qmatbridge # from PyPI; the core has no required dependencies
pip install "qmatbridge[mp]" # + Materials Project adapter (mp-api, pymatgen); use Python 3.11+
To work on QMatBridge itself, install from source:
git clone https://github.com/q-matsuite/qmatbridge.git
cd qmatbridge
pip install -e ".[dev]"
API keys
QMatBridge ships no credentials. To fetch from the Materials Project you need your
own free API key (export MP_API_KEY=...); reading entries and the committed
benchmark fixtures needs none. See docs/api-keys.md for which
sources need a key, how to keep it out of git, and data-licence/attribution notes.
A curated, peer-reviewed library of qubit Hamiltonians (2 to 1000 qubits: molecular electronic structure, Fermi-Hubbard, Heisenberg and other models, combinatorial problems) for benchmarking algorithms and hardware
Complementary, and not something we beat. HamLib is a dataset of finished, validated Hamiltonians at a scale QMatBridge does not approach. QMatBridge works one step earlier: it keeps the representation before a qubit mapping, records which database record and calculation a Hamiltonian came from, and builds entries on demand from materials databases. The instance families HamLib lists (molecules, lattice models, combinatorial problems) do not include records from crystal databases such as the Materials Project; that gap is what QMatBridge fills.
Where HamLib is ahead: scale, curation, peer review, a fixed file format with benchmark
instances anyone can cite, and Hamiltonians that come from real computed models. Where
QMatBridge differs: provenance from a materials database, a canonical hash that makes
"the same Hamiltonian" checkable, plane-wave and oracle metadata, cross-database
deduplication. Where QMatBridge is limited: the Hamiltonians it exports are a small
point-ion plane-wave model, not the DFT Hamiltonian of the source calculation, and only
small bases are practical. A HamLib-format (HDF5) exporter would be a natural addition.
Q&A, design proposals, and architecture discussions
Contributions are welcome at any level — bug reports, adapter implementations,
documentation improvements, and benchmark additions. Please read
CONTRIBUTING.md and the project vision
before opening a large pull request.
Citation
QMatBridge does not yet have a journal publication. Each release is archived on
Zenodo (concept DOI 10.5281/zenodo.23192772,
which always resolves to the latest version), so the software itself is citable.
If you use it in academic work, please cite it:
@software{qmatbridge,
author = {{dos Reis}, Roberto},
organization = {q-matsuite},
title = {{QMatBridge}: A bridge from classical materials databases to
first-quantized Hamiltonians for quantum simulation},
url = {https://github.com/q-matsuite/qmatbridge},
version = {0.6.0},
doi = {10.5281/zenodo.23192772},
year = {2026},
}
A JOSS submission is planned once the API has settled and the
project has research uses to point to; a draft paper, including the comparison with HamLib
and related tools, is in joss/. It has not been submitted.
Author
Created and maintained by Roberto dos Reis, Department of Materials Science and Engineering, Northwestern University (@rmsreis).
