PartQMMM

QM/MM subsystem construction for quantum reference data used in environment-aware ML interatomic-potential workflows (for example AIMNet2/MLMM).

The current V1 workflow writes two files per selected MD frame:

• frame_XXXXXX_qm.xyz — physical QM atoms plus link H atoms;
• frame_XXXXXX_mm.pc — electrostatic embedding sites as q x y z.

No quantum-engine input is generated by V1.

QM/MM boundary-charge schemes and references

When a covalent bond crosses the QM/MM boundary, PartQMMM uses a link-H atom to cap the QM fragment and modifies the electrostatic embedding near the cut bond to avoid exposing the QM density and link atom to the unmodified partial charge of the nearby MM boundary atom.

PartQMMM currently provides two boundary-charge treatments:

shift — charge redistribution

For each Cα-Cβ QM/MM cut, the MM boundary atom (M1; Cα) charge is set to zero and its original charge is redistributed equally among the adjacent MM M2 atoms (N, C, and HA in the present protein implementation).

This is a simple charge-redistribution (RC-like) treatment. It conserves the total boundary charge but does not explicitly enforce conservation of the original M1-M2 bond dipoles.

Relevant references:

1. Walker, R. C.; Crowley, M. F.; Case, D. A. "The Implementation of a Fast and Accurate QM/MM Potential Method in Amber." J. Comput. Chem. 2008, 29, 1019-1031. DOI: 10.1002/jcc.20857

2. Brunken, C.; Reiher, M. "Automated Construction of Quantum-Classical Hybrid Models." J. Chem. Theory Comput. 2021, 17, 3797-3813. DOI: 10.1021/acs.jctc.1c00178

A related charge-smearing treatment was previously used and benchmarked in:

3. Bose, S.; Chakrabarty, S.; Ghosh, D. "Effect of Solvation on Electron Detachment and Excitation Energies of a Green Fluorescent Protein Chromophore Variant." J. Phys. Chem. B 2016, 120, 4410-4420. DOI: 10.1021/acs.jpcb.6b03723

rcd — Redistributed Charge and Dipole

The Redistributed Charge and Dipole (RCD) scheme is based on the method of Lin and Truhlar. The M1/Cα charge is removed, the neighboring M2 charges are adjusted, and auxiliary point charges are placed at the midpoints of the M1-M2 bonds. The construction conserves the redistributed charge while also preserving the local M1-M2 bond dipoles.

In PartQMMM these auxiliary sites are electrostatic-embedding sites only: they are written to the MM point-charge field and are not included as physical atoms in the QM XYZ or MLIP atom list. Midpoint placement is performed using the minimum-image geometry under periodic boundary conditions.

Primary reference:

4. Lin, H.; Truhlar, D. G. "Redistributed Charge and Dipole Schemes for Combined Quantum Mechanical and Molecular Mechanical Calculations." J. Phys. Chem. A 2005, 109, 3991-4004. DOI: 10.1021/jp0446332

Further development of the RCD boundary treatment:

5. Zhang, Y.; Lin, H.; Truhlar, D. G. "Self-Consistent Polarization of the Boundary in the Redistributed Charge and Dipole Scheme for Combined Quantum-Mechanical and Molecular-Mechanical Calculations." J. Chem. Theory Comput. 2007, 3, 1378-1398. DOI: 10.1021/ct7000107

QM-region model

Fixed chemical core

• minimal: Zn + AZM + His94, His96, His119, Thr199 sidechains; formal QM charge +1.
• larger: adds His64 and deprotonated Glu106; formal QM charge 0.

Sidechains are cut at C-alpha--C-beta. C-beta and the selected sidechain are QM; C-alpha and the peptide backbone remain MM. A 1.09 A link H caps C-beta.

Adaptive waters: H-bond OR Zn coordination

There is no fixed number of QM waters. A complete water is promoted to QM when either condition is satisfied:

1. it forms a direct H bond to a donor/acceptor N, O, or S site in the fixed QM core; or
2. its water oxygen directly coordinates QM Zn, by default Zn-O <= 2.6 A.

Default H-bond geometry is donor--acceptor distance <= 3.5 A and D-H...A angle >= 140 deg.

The Zn criterion is configurable:

--zn-water-cutoff 2.6

Set --zn-water-cutoff 0 only for a controlled comparison that disables direct Zn-water selection.

All geometry tests are triclinic-PBC aware. If a water satisfies both H-bond and Zn-coordination criteria it is included only once, while both selection reasons are recorded.

For OPC/four-site water, the complete topology residue including the virtual charge site is removed from MM, while only real O/H/H atoms enter the QM XYZ. Adaptive waters must be neutral; therefore adding any number of waters does not change the configured formal QM charge.

PBC

Distances, H-bond angles, Zn--water coordination, link geometry, ion guards, and RCD virtual-site placement use a triclinic minimum-image convention. The implementation explicitly checks neighboring lattice translations to select the shortest Cartesian image.

Covalent boundary electrostatics

Choose:

--boundary-charge-method shift

or:

--boundary-charge-method rcd

shift zeroes the MM C-alpha charge and distributes it equally over its M2 N/C/HA atoms.

rcd uses a PBC-aware Redistributed Charge and Dipole representation: C-alpha is zeroed, M2 charges are modified, and virtual embedding charges are placed at minimum-image C-alpha--M2 midpoints. RCD virtual sites exist only in the MM point-charge field; they never enter the QM XYZ or MLIP atom count.

The formal-QM-charge correction remains separate from local boundary treatment. Every frame verifies

Q_QM(formal) + Q_MM(embedding) = Q_system(force field)

within numerical tolerance.

Free-ion guard

Positive and negative free ions are detected to prevent silent double counting or pathological close point charges. By default a non-QM free ion inside the guard radius causes a fail-fast error; V1 does not silently delete or promote ions.

No outer MM electrostatic cutoff is used in V1.

Files

qmmm_partition.py      engine-agnostic partition library
generate_partitions.py CLI writer for QM XYZ + MM point-charge files
test_partition.py      PBC/RCD/adaptive-water/charge regression tests
analysis/               MD-ensemble diagnostic suite

Generate partitions

python generate_partitions.py \
  --top system_1264.parm7 \
  --traj run1.dcd \
  --output-dir partitions_run1_rcd \
  --region larger \
  --boundary-charge-method rcd \
  --zn-water-cutoff 2.6

Useful options:

--frames START:STOP:STRIDE
--hbond-distance 3.5
--hbond-angle 140
--zn-water-cutoff 2.6
--boundary-charge-method shift|rcd
--ion-guard 4.0
--allow-close-ions
--resnum-offset -4

The JSON diagnostic printed per frame reports total selected waters plus separate H-bond and Zn-coordinated water counts/identities, formal charge, MM embedding charge, charge error, boundary method, and number of RCD virtual sites.

Tests

python test_partition.py

With the supplied-style real system:

python test_partition.py system_1264.parm7 hca2_azm_withwater_run5_combined.pdb

The tests also synthesize a 2.1 A Zn--water contact and verify that the complete neutral water is moved to QM without changing formal charge or being double counted in MM.

Ensemble analysis

See analysis/README.md. The analysis package imports this root qmmm_partition.py directly, so the production partition and ensemble diagnostics always use the same H-bond, Zn-water, PBC, charge, and boundary definitions.