q2m3: A Hybrid Quantum-Classical QM/MM Simulation Framework

q2m3 is a research framework for hybrid quantum-classical QM/MM (quantum mechanics / molecular mechanics). It connects PySCF molecular integrals and Hartree–Fock references to PennyLane Quantum Phase Estimation (QPE) circuits. It also supports explicit MM point charges, Monte Carlo (MC) solvation, and sample-based quantum diagonalization (SQD).

Use q2m3 to explore small-molecule QPE workflows and early fault-tolerant quantum computing (EFTQC) resource estimates. The project is an alpha proof of concept. Its approximations and small-system checks do not establish production chemistry accuracy.

Install

q2m3 requires Python 3.11+. Install from PyPI to use the library. Use a source checkout to run the example scripts and the development tools.

From PyPI

In a virtual environment (POSIX shell):

python -m venv .venv
source .venv/bin/activate
python -m pip install q2m3

The package is available as q2m3 on PyPI.

From source

With uv installed:

git clone https://github.com/yjmaxpayne/q2m3.git
cd q2m3
uv sync

The core install supports the three H₂ starter scripts in the example guide. Select optional extras by purpose:

For example, run uv sync --extra solvation in a source checkout. In a library environment, run python -m pip install "q2m3[solvation]".

Minimal Python API

This snippet estimates resources for H₂/STO-3G. The active space has two electrons in two spatial orbitals, which gives four Jordan–Wigner system qubits. Coordinates are in Å. The target energy error is in Hartree. Run the snippet with python in the PyPI environment, or with uv run python in the source checkout.

import numpy as np

from q2m3.core import estimate_resources

resources = estimate_resources(
    symbols=["H", "H"],
    coords=np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 0.74]]),
    basis="sto-3g",
    active_electrons=2,
    active_orbitals=2,
    target_error=0.0016,
)
print("System qubits:", resources.n_system_qubits)
print("Logical qubits:", resources.logical_qubits)
print("Toffoli gates:", resources.toffoli_gates)

estimate_resources returns an EFTQCResources object. The logical-qubit and Toffoli-gate counts come from an algorithmic cost model. They do not predict local simulator runtime or Catalyst compilation memory.

SQD workflows

To install the SQD dependencies in a source checkout, run uv sync --frozen --extra sqd. SQD does not require Catalyst. The public supervisor requires Linux x86_64 and serial native threads. The unified lock also moves the core-only PySCF version to 2.14.0. The calibrated resource profile uses Python 3.12.3.

SQD has two entry points:

• from q2m3 import run_sqd starts from a molecular geometry.
• from q2m3.sqd import run_sqd_from_integrals starts from an authenticated integral Hamiltonian and a same-frame CCSD seed.

Both functions require an explicit closed-shell active space. Both return the complete SQDResult. The SQD guide gives runnable examples for both. It also covers fixed-frame MM semantics, reference tiers, installation boundaries, and resource caps. The SQD API reference lists the public contracts, the authenticated integral producers, and the resource-policy functions.

Current evidence supports the default benchmark scope of two repetitions and 100000 shots. H₂ and H₃O⁺ are full-space regressions. Glycine is worse than CCSD for all five seeds. N₂ is worse than both CCSD and matched-size SCI. The original orbital-basis (E1) and connectivity (E6) studies remain inconclusive. Historical four-repetition runs remain outside the certified resource domain. These results do not establish SQD superiority or quantum hardware readiness.

Examples and documentation

Start with the example guide. It gives runnable H₂ commands and the complete script index. It also separates MC workflows from larger diagnostics.

q2m3 computes energies in Hartree and converts them explicitly for kcal/mol reports. QPE–HF differences contain numerical errors as well as correlation contributions. Fixed-MO MM embedding keeps the vacuum orbital frame and the two-electron tensor fixed. Runtime MC coefficient updates are diagonal-only. Read the example boundaries before you interpret energies physically.

Runnable capability map

SQD tutorials save complete results, CSV files, and PNG/SVG figures to a unique run directory under data/output/examples/. The default glycine scan runs 15 actual points in sequence, each in a fresh process. Local development tools are not part of the installed package and are not required in a fresh clone. Use q2m3.profiling.measure_command for complete-process monitoring. The SQD tutorial documents its result contract, units, environment defaults, and sampling limits. Historical benchmark and calibration records describe their original inputs and versions. Shared CI does not promise to regenerate those studies.

Development, citation, and license

See the development guide for test, lint, and build commands. See AGENTS.md for contribution conventions. Do not commit generated coverage files, caches, or benchmark outputs.

For research use, cite the release that produced your results. Use CITATION.cff for the citation metadata. q2m3 uses the MIT License.