Core Concepts¶

q2m3 combines quantum chemistry, quantum algorithms, and molecular mechanics. The Glossary defines the terms used below.

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. q2m3 stores energies in Hartree internally. The unit 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. The PennyLane QPE paths prepare an HF state, apply controlled Trotter time evolution and inverse QFT, and decode the phase. A classical fallback tests the QM/MM data pipeline when no PennyLane Hamiltonian is 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 reduces the simulation size. Report the active electrons, spatial orbitals, and 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
Glycine	6, 8, or 10 electrons in the same number of orbitals	12, 16, or 20	SQD scaling tutorial. Each space has its own Hamiltonian and reference

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

Sample-Based Quantum Diagonalization¶

SQD samples a CCSD-seeded LUCJ state with ffsim. It diagonalizes the Hamiltonian in the recovered determinant subspace. The result includes HF, active-space CCSD, selected-CI, random-subspace, and reference energies. All comparisons use the same Hamiltonian. See Sample-based quantum diagonalization (SQD) for the reference policy.

The signed primary error is 1000 * (E_SQD - E_reference) in mHa, so a positive value places SQD above the reference. Only a T0 exact-active-space result supports an exact-error claim. Seed spread is descriptive. It is not a confidence interval. The sampled determinant fraction also does not equal simulator-memory savings because ffsim still represents the full fixed-particle-number state.

SQD runs on a classical simulator. It does not execute on quantum hardware or demonstrate quantum advantage.

Fragment interaction energies¶

The fragment workflow computes E(AB) - E(A) - E(B) for a dimer. Counterpoise uses the dimer basis for all three calculations. AVAS selects active orbitals from explicit atomic-shell labels and a threshold. The workflow checks correspondence between the dimer and monomer active spaces.

classical_only computes HF and frozen-core MP2. full adds budgeted CCSD(T), active-space SQD, and resource estimates. Only a T0 exact-CASCI reference supplies the CASCI energy. Missing reference values remain absent with reasons. See Fragment Interaction Energy for a complete calculation.

These interaction energies describe fixed geometries. They do not represent a solvent ensemble or a solvation free energy.

Phase Decoding And Energy Shifts¶

QPE measures a phase modulo one. Large negative molecular energies can therefore produce phase wrapping. When needed, q2m3 uses shifted QPE parameters to estimate a smaller energy difference relative to a Hartree-Fock reference.

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) connects quantum states to classical observables. q2m3 estimates 1-RDMs for Mulliken populations and charge checks. Correlated RDM feedback into SQD/MM is not implemented.

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. Use these estimates to plan quantum hardware resources. They are not the same as Catalyst compile memory or LLVM IR size.

The H2 resource example demonstrates that MM point charges mainly change 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. They reuse the vacuum molecular-orbital frame and hold the two-electron tensor at its vacuum value. They compute no orbital relaxation, polarizable MM response, or relaxed solvation energy. The diagnostic delta_h_offdiag_fro reports the Frobenius norm of the off-diagonal active-space perturbation that diagonal mode omits and full_oneelectron mode includes.

Catalyst Guidance¶

Use Catalyst when repeated executions can reuse a compiled circuit. MC solvation can reuse the circuit when only Hamiltonian coefficients change. A single execution may not recover the compilation cost.

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`	Runtime diagonal MM embedding

q2m3 uses the difference between fixed and dynamic correlation behavior 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 change the operator support that Catalyst compiled for a given circuit.