QMatBridge by q-matsuite
Open-source research software · early stage

Materials databases to first-quantized Hamiltonians.

QMatBridge is a Python library that turns classical materials-database records into a neutral, provenance-rich description of the Hamiltonian, so fault-tolerant quantum-simulation benchmarks can be compared and reproduced.

Explore examples Install Read the docs

Sources

  • Materials Project available
  • OQMD stub
  • OPTIMADE planned

Neutral representation

QMatEntry

Provenance · structure · basis · oracle cost · canonical hash

Exporters

  • OpenFermion planned
  • qualtran / pyLIQTR planned
  • Qiskit planned
Examples

Three materials, one representation

A textbook semiconductor, a wide-gap III–V, and a Li-ion battery cathode, each fetched from the Materials Project and stored as a QMatEntry. Drag the crystal to rotate it.

The problem

Two groups, one “silicon”, no way to check

Research groups developing block-encodings, qubitization variants and truncated Dyson series methods need realistic electronic-structure Hamiltonians. The usual route is a one-off script that pulls DFT data, reformats it and feeds it to a compiler.

Those scripts are rarely shared, rarely work with more than one framework, and often drop the provenance needed to reproduce a result. When two groups report T-gate counts for “silicon”, nothing says they used the same Hamiltonian. QMatBridge records what was used, and hashes it.

What an entry records

Everything needed to reproduce the Hamiltonian

  • provenanceWhere it came from. Database and identifier, functional, pseudopotential family, DFT code and version, retrieval time.
  • structureWhat it is. Reduced and unit-cell formula, species per site, lattice parameters, space group.
  • basisHow it is discretised. Plane-wave cutoff and the resulting number of plane waves.
  • oracleWhat access costs. LCU 1-norm, per-term breakdown, SELECT/PREPARE parameters and complexity annotations.
  • exportsWhere it went. Downstream framework, format, status and artifact path.
  • hashA stable fingerprint. canonical_hash() is a SHA-256 over the physically meaningful fields, so a result can be traced to one Hamiltonian.
Schema

The core dataclasses

Dependency-free, JSON-serialisable, versioned. Changes to the schema go through public discussion and a minor-version bump.

ClassRoleKey fields
QMatEntryTop-level recordreference, hamiltonian, exports, tags, schema_version
MaterialReferenceProvenance plus structureprovenance, structure
SourceProvenanceUpstream source and DFT settingsprimary, functional, pseudopotential, code, retrieved_at
StructureMetadataChemistry and geometryformula_reduced, formula_unit_cell, species, lattice
HamiltonianMetadataElectrons, basis, terms, oraclenum_electrons, spin_polarized, basis, terms, oracle
BasisMetadataBasis-set specificationtype, cutoff_energy_ev, num_plane_waves
OracleMetadataBlock-encoding oracle descriptionoracle type, index encoding, complexity annotations
ExportMetadataDownstream export recordtarget, format, status, artifact path
Install

From source, in a minute

Not yet on PyPI. Python 3.10+; the core schema has no required dependencies. Fetching from the Materials Project needs the mp extra and a free API key.

Install
git clone https://github.com/q-matsuite/qmatbridge.git
cd qmatbridge
pip install -e ".[mp]"
Fetch an entry
export MP_API_KEY=...   # your own key
python -c "from qmatbridge.adapters.materials_project import fetch_entry_from_mp as f; print(f('mp-149').canonical_hash())"
Who it is for

Narrow on purpose: a bridge, not a database

Use it if you are

  • an algorithm researcher who needs real materials Hamiltonians for block-encoding or qubitization work;
  • a research software engineer who wants a citable format between the DFT and circuit worlds;
  • a resource-estimation group running T-count and qubit studies across many materials.

Look elsewhere if you want

  • a general materials-informatics toolkit — use pymatgen or ASE;
  • molecular, Gaussian-basis or excited-state Hamiltonians — out of scope for now.
Roadmap

Where the project is

  1. v0.1 done

    Schema, JSON I/O, canonical hash, adapter stubs, CI.

  2. v0.2 in progress

    Materials Project adapter, plane-wave utility, benchmark fixtures, documentation site.

  3. v0.3 planned

    OPTIMADE, OQMD and Alexandria adapters; cross-database deduplication.

  4. v0.4 planned

    Exporters: OpenFermion, raw plane-wave arrays, LCU coefficients for qualtran / pyLIQTR.

  5. v0.5 planned

    T-count, Toffoli and qubit estimation hooks.

Community

Built in the open

DiscussionsQuestions and design proposals IssuesBugs and feature requests ContributingHow to propose changes GovernanceRoles and decisions
Cite

Using QMatBridge in a paper?

There is no formal publication yet. Please cite the repository.

BibTeX
@software{qmatbridge,
  author = {Reis, Roberto},
  title  = {{QMatBridge}: A bridge from classical materials
            databases to first-quantized Hamiltonians for
            quantum simulation},
  url    = {https://github.com/q-matsuite/qmatbridge},
  version = {0.1.0},
  year   = {2026},
}