Core Concepts¶

q2m3 connects classical quantum chemistry with quantum phase-estimation circuits and explicit MM point-charge environments. The framework is small enough for H2 validation while exposing the same architectural issues that appear in larger EFTQC-oriented studies.

QM/MM Partitioning¶

QM/MM separates a system into a quantum mechanical region and a molecular mechanics environment. q2m3 currently uses PySCF for the classical quantum chemistry side and TIP3P/SPC/E-style point charges for explicit water environments. Energies are stored in Hartree internally; kcal/mol appears only after an explicit conversion.

The current embedding model is electrostatic point-charge embedding. It does not include a polarizable MM force field or advanced solvent response model.

QPE Workflow¶

QPE estimates an eigenphase of the time-evolution operator and converts that phase back into an energy. In q2m3, real PennyLane QPE paths build HF state preparation, controlled Trotter time evolution, inverse QFT, and phase decoding. A classical fallback path is still useful for testing the QM/MM data pipeline when a PennyLane Hamiltonian is not available.

        flowchart LR
    accTitle: QPE Energy Flow
    accDescr: The q2m3 QPE path prepares a reference state, applies controlled time evolution, reads out a phase, and converts the phase to an energy.

    hamiltonian["PySCF and PennyLane Hamiltonian"]
    hf_state["HF reference state"]
    qpe["QPE circuit"]
    phase["Estimated phase"]
    energy["Energy in Hartree"]

    hamiltonian --> qpe
    hf_state --> qpe
    qpe --> phase
    phase --> energy

Active Spaces¶

Active-space truncation keeps simulation sizes manageable. An active space is reported as electrons/orbitals, followed by the resulting qubit count. For Jordan-Wigner mappings, each spatial orbital contributes two spin-orbital qubits.

System	Typical active space	System qubits	Notes
H2	2 electrons, 2 orbitals	4	First-run validation path
H3O+	4 electrons, 4 orbitals	8	Optional ionic solvation diagnostics

The full H3O+ STO-3G space is larger than the default examples. The public H3O+ scripts therefore use conservative active-space and Trotter settings.

Phase Decoding And Energy Shifts¶

QPE measures a phase modulo one. Large negative molecular energies can wrap around the phase register, so q2m3 uses shifted QPE parameters to estimate a smaller energy difference relative to a Hartree-Fock reference when needed.

Two phase-extraction conventions exist in the current code:

Path	Implementation	Interpretation
Sampled QPE	`QPEEngine._extract_energy_from_samples()`	Uses the most frequent measured bitstring
Analytical solvation	`q2m3.solvation.phase_extraction`	Uses a probability-weighted expected bin

Do not compare those paths without noting the decoding convention and shot model.

RDM Measurement¶

The one-particle reduced density matrix (1-RDM) maps quantum-state information back into classical chemical analysis. q2m3 uses RDM estimation for Mulliken population analysis, charge conservation checks, and future QM/MM feedback loops.

RDM values must obey physical constraints such as Hermiticity, electron count, and non-negative occupations. Measurement noise can violate these constraints, so the estimator includes projection utilities for physically valid matrices.

Resource Estimation¶

The q2m3.core.resource_estimation API estimates EFTQC resources such as Hamiltonian 1-norm, logical qubits, Toffoli gates, system qubits, and target error. These are hardware-planning estimates; they are not the same as Catalyst compile memory or LLVM IR size.

The H2 resource example demonstrates that MM point charges mainly modify one-electron terms. For small H2/STO-3G runs, the two-electron integrals dominate the resource estimate, so vacuum and solvated estimates are close.

Fixed-MO Full-One-Electron Embedding¶

Explicit MM point charges perturb the one-electron Hamiltonian. q2m3 exposes two public resource-estimation modes for this perturbation:

Mode	Included active-space perturbation	Intended use
`diagonal`	Diagonal `Delta h_pp` terms only	Compatibility row for dynamic coefficient-update workflows
`full_oneelectron`	Full fixed-MO `Delta h_pq` matrix	Resource rows and fixed-Hamiltonian operator support

Both modes are fixed-MO models. The vacuum molecular-orbital frame is reused, the two-electron tensor is held at its vacuum value, and no orbital relaxation, polarizable MM response, or relaxed solvation energy is computed. The diagnostic delta_h_offdiag_fro reports the Frobenius norm of the off-diagonal active-space perturbation that is omitted by diagonal mode and included by full_oneelectron mode.

Catalyst Guidance¶

Catalyst is most useful when the workflow can compile once and execute many times. Single QPE executions often pay too much compile overhead. MC solvation is a better fit because each accepted solvent configuration can reuse the same compiled circuit structure when only coefficients change at runtime.

Use case	Recommended path
H2 first validation	Standard PennyLane or existing example script
MC with fixed vacuum Hamiltonian	Catalyst fixed mode with IR cache
MC with runtime MM embedding	Catalyst dynamic mode, treated as a heavier diagnostic
Fixed full-one-electron embedding	Fixed Hamiltonian/operator path only
H3O+ high precision or Trotter scans	Optional diagnostics on high-memory machines

Three Solvation Modes¶

Mode	Energy model	Purpose
`fixed`	`E_QPE(H_vac) + E_MM`	Fast compile-once baseline
`hf_corrected`	`E_HF(R) + E_MM` with interval QPE diagnostics	Intermediate mode for throughput
`dynamic`	`E_QPE(H_eff) + E_MM`	Most complete current model for MM-embedded QPE

The difference between fixed and dynamic correlation behavior is used to study delta_corr-pol, the correlation-polarization coupling term.

The current dynamic runtime coefficient path updates diagonal coefficients. It does not accept embedding_mode="full_oneelectron" because off-diagonal one-electron terms can alter the operator support that Catalyst compiled for a given circuit.