qmatbridge 0.1.0__tar.gz

qmatbridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roberto Reis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qmatbridge-0.1.0/PKG-INFO

@@ -0,0 +1,388 @@
+Metadata-Version: 2.4
+Name: qmatbridge
+Version: 0.1.0
+Summary: Bridge from classical materials databases to first-quantized Hamiltonians for quantum simulation
+Author-email: Roberto Reis <robertomsreis@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Roberto Reis
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/rmsreis/qmatbridge
+Project-URL: Repository, https://github.com/rmsreis/qmatbridge
+Project-URL: Issues, https://github.com/rmsreis/qmatbridge/issues
+Keywords: quantum computing,quantum simulation,materials science,Hamiltonian simulation,block encoding,fault tolerant,resource estimation
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Provides-Extra: mp
+Requires-Dist: mp-api>=0.41; extra == "mp"
+Requires-Dist: pymatgen>=2024.1; extra == "mp"
+Provides-Extra: ase
+Requires-Dist: ase>=3.22; extra == "ase"
+Provides-Extra: oqmd
+Requires-Dist: qmpy-rester>=0.3; extra == "oqmd"
+Provides-Extra: openfermion
+Requires-Dist: openfermion>=1.6; extra == "openfermion"
+Dynamic: license-file
+
+# QMatBridge
+
+**A Python library for bridging classical materials databases to first-quantized
+Hamiltonians for fault-tolerant quantum simulation.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![CI](https://github.com/rmsreis/qmatbridge/actions/workflows/python-package.yml/badge.svg)](https://github.com/rmsreis/qmatbridge/actions)
+[![PyPI](https://img.shields.io/badge/PyPI-not%20yet%20published-lightgrey.svg)](#installation)
+[![Docs](https://img.shields.io/badge/docs-in%20progress-lightgrey.svg)](docs/)
+
+> **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](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.
+
+---
+
+## Core idea
+
+```text
+  Materials Project  ──┐
+  OQMD               ──┤  adapters  ──▶  QMatEntry (NIR)  ──▶  exporters  ──▶  OpenFermion
+  OPTIMADE sources   ──┤                                                   ──▶  qualtran
+  Alexandria         ──┘                                                   ──▶  pyLIQTR
+                                                                           ──▶  Qiskit
+```
+
+A `QMatEntry` records:
+
+- **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 its physically
+meaningful fields so that benchmark results can be traced to a specific
+Hamiltonian without re-deriving it.
+
+---
+
+## 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](https://pymatgen.org) or [ASE](https://wiki.fysik.dtu.dk/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)
+- LCU / qubitization oracle metadata
+- JSON serialization with canonical entry hashes
+- Adapter stubs for Materials Project and OQMD
+- 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
+- Live API calls (adapters are stubs until v0.2)
+- Exporter implementations (planned v0.4)
+
+---
+
+## 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](GOVERNANCE.md); design discussions happen in GitHub
+Discussions before any code is written.
+
+---
+
+## Getting started
+
+### Installation
+
+```bash
+# from source (recommended until PyPI publication)
+git clone https://github.com/rmsreis/qmatbridge.git
+cd qmatbridge
+pip install -e ".[dev]"
+```
+
+Optional extras:
+
+```bash
+pip install -e ".[mp]"        # Materials Project adapter (mp-api, pymatgen)
+pip install -e ".[oqmd]"      # OQMD adapter (qmpy-rester)
+pip install -e ".[openfermion]"  # OpenFermion exporter
+```
+
+### Minimal example
+
+```python
+from qmatbridge.schema import (
+    ExternalIdentifier, SourceProvenance,
+    LatticeMetadata, StructureMetadata,
+    BasisMetadata, HamiltonianMetadata,
+    MaterialReference, QMatEntry,
+)
+from qmatbridge.io import write_entry_json
+
+provenance = SourceProvenance(
+    primary=ExternalIdentifier(
+        source="materials_project", identifier="mp-149"
+    ),
+    functional="PBE",
+    pseudopotential="PAW_PBE",
+    code="VASP",
+)
+
+structure = StructureMetadata(
+    formula_reduced="Si",
+    formula_unit_cell="Si2",
+    num_sites=2,
+    species=["Si", "Si"],
+    lattice=LatticeMetadata(
+        a=3.867, b=3.867, c=3.867,
+        alpha=60.0, beta=60.0, gamma=60.0,
+        spacegroup_number=227, spacegroup_symbol="Fd-3m",
+    ),
+)
+
+hamiltonian = HamiltonianMetadata(
+    num_electrons=8,
+    spin_polarized=False,
+    basis=BasisMetadata(type="plane_wave", cutoff_energy_ev=520.0),
+    num_bands=16,
+)
+
+entry = QMatEntry(
+    reference=MaterialReference(provenance=provenance, structure=structure),
+    hamiltonian=hamiltonian,
+    tags=["silicon", "benchmark"],
+)
+
+print(entry)                      # QMatEntry(formula='Si', source='materials_project', ...)
+print(entry.canonical_hash())     # deterministic SHA-256
+
+write_entry_json(entry, "silicon.json")   # full nested JSON, 2-space indent
+```
+
+See [`examples/minimal_entry.py`](examples/minimal_entry.py) for a fully
+populated silicon entry including oracle metadata and term breakdown.
+
+---
+
+## Repository layout
+
+```text
+qmatbridge/
+├── qmatbridge/
+│   ├── schema.py                  # Neutral intermediate representation (NIR)
+│   ├── io.py                      # JSON serialization utilities
+│   └── adapters/
+│       ├── materials_project.py   # Materials Project adapter stub (v0.2 target)
+│       └── oqmd.py                # OQMD adapter stub (v0.3 target)
+├── docs/
+│   ├── vision.md                  # Design rationale and architectural constraints
+│   ├── adapters.md                # Upstream adapter documentation
+│   └── oracle-model.md            # Oracle abstraction and export model
+├── examples/
+│   └── minimal_entry.py           # Silicon QMatEntry with full oracle metadata
+├── benchmarks/
+│   └── README.md                  # Benchmark methodology and Tier-1 material plan
+├── planning/
+│   └── initial_issues.md          # Scoped GitHub issue set for v0.1–v0.4
+└── .github/workflows/
+    └── python-package.yml         # CI: lint (ruff + mypy) + tests on 3.10–3.12
+```
+
+---
+
+## Roadmap
+
+### v0.1 — Schema and scaffold *(current)*
+
+- [x] Core dataclasses: `MaterialReference`, `HamiltonianMetadata`, `QMatEntry`
+- [x] Oracle and term metadata: `OracleMetadata`, `TermMetadata`, `ExportMetadata`
+- [x] JSON serialization via `qmatbridge.io`
+- [x] Canonical entry hash (`QMatEntry.canonical_hash()`)
+- [x] Adapter stubs: Materials Project, OQMD
+- [x] CI: ruff, mypy, pytest on Python 3.10–3.12
+- [ ] JSON round-trip regression fixtures
+- [ ] Oracle convention vocabulary (`oracle_type`, `index_encoding`)
+
+### v0.2 — Materials Project live integration
+
+- [ ] `fetch_structure_metadata_from_mp` and `fetch_hamiltonian_metadata_from_mp`
+- [ ] Plane-wave count utility (`num_plane_waves_from_ecut`)
+- [ ] Tier-1 benchmark material fixtures (Si, LiH, Fe, MgO, TiO₂)
+- [ ] MkDocs documentation site on GitHub Pages
+
+### v0.3 — OPTIMADE, OQMD, and Alexandria adapters
+
+- [ ] Generic OPTIMADE adapter (AFLOW, JARVIS, NOMAD, MC3D)
+- [ ] OQMD live fetch
+- [ ] Alexandria adapter (PBEsol / HSE06 / r²SCAN, ~4.5 M structures)
+- [ ] Cross-database deduplication via shared ICSD numbers
+
+### v0.4 — Hamiltonian exporters
+
+- [ ] OpenFermion `InteractionOperator` exporter
+- [ ] First-quantized plane-wave Hamiltonian (raw NumPy arrays)
+- [ ] LCU coefficient export for `qualtran` / `pyLIQTR`
+
+### v0.5 — Resource estimation hooks
+
+- [ ] T-count and Toffoli estimation interface
+- [ ] Qubit footprint estimator
+- [ ] Direct integration with `qualtran` / `pyLIQTR` resource analysis
+
+### Beyond v0.5
+
+- Gaussian and real-space basis support
+- Defect and surface slab geometries
+- Community adapter registry (entry-point group)
+
+---
+
+## Community
+
+| Document | Purpose |
+| --- | --- |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | How to open issues, propose schema changes, and submit pull requests |
+| [GOVERNANCE.md](GOVERNANCE.md) | Roles, decision process, and release policy |
+| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community standards and enforcement |
+| [SECURITY.md](SECURITY.md) | Private vulnerability reporting |
+| [SUPPORT.md](SUPPORT.md) | Where to ask questions vs. file bugs |
+| [GitHub Discussions](https://github.com/rmsreis/qmatbridge/discussions) | 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](CONTRIBUTING.md) and the [project vision](docs/vision.md)
+before opening a large pull request.
+
+---
+
+## Citation
+
+QMatBridge does not yet have a formal publication.  If you use it in
+academic work, please cite the repository directly:
+
+```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/rmsreis/qmatbridge},
+    version = {0.1.0},
+  year    = {2026},
+}
+```
+
+A citable release and, if the project grows, a JOSS submission are planned
+once the v0.2 Materials Project adapter is complete and the API is stable.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).