6.1.7. qmhub_at26.patch summary and AT23 comparison#

6.1.7.1. Sources reviewed#

  • AmberTools 26 patch: qmhub/patches/qmhub_at26.patch

  • AmberTools 23 reference patch: qmhub/patches/qmhub_at23.patch

6.1.7.2. High-level summary#

qmhub_at26.patch ports the QMHub Sander external-QM interface to AmberTools 26. It adds a new qm2_extern_qmhub_module.F90, wires that module into the Sander build, registers qmhub as an EXTERN backend, and exchanges QM atoms, MM point charges, unit-cell data, QM/MM energy, and QM/MM gradients with the qmhub command. The interface supports text (comm=0), binary (comm=1), and FIFO (comm=2) exchange modes through a new &qmhub namelist.

The AT26 version also contains compatibility refinements beyond the AT23 patch: QMHub-specific behavior is gated behind detection of both qm_theory='EXTERN' and an &qmhub namelist, legacy non-QMHub EXTERN charge behavior is preserved, QM/link RESP charge storage is extended, and a TorchANI charge-slicing adjustment is added for the AT26 source layout.

6.1.7.3. Patch footprint#

Patch

Files touched

Added lines

Removed lines

qmhub_at26.patch

11

791

70

qmhub_at23.patch

8

746

68

6.1.7.4. Key changes#

Name

Main files

What changes

Sander build integration

AmberTools/src/sander/CMakeLists.txt, Makefile, depend

Adds qm2_extern_qmhub_module.F90 / .o to the normal QM, QM API, and LES build lists and dependency rules.

QMHub EXTERN registration

AmberTools/src/sander/qm2_extern_module.F90

Imports get_qmhub_forces, adds qmhub to the supported EXTERN program list, dispatches extern_program='qmhub', prints QMHub citation text, skips generic constant printing for QMHub, and calls qmhub_finalize() during external-QM finalization.

QMHub communication module

AmberTools/src/sander/qm2_extern_qmhub_module.F90

Adds the core Sander-side QMHub driver. It reads &qmhub (config, basedir, comm, debug), creates exchange files/FIFOs, launches qmhub, writes Sander input data, reads energy/gradients, converts Hartree/Bohr outputs to Amber units, and closes FIFO streams at finalization.

Unit-cell exchange

qm2_extern_module.F90, qm2_extern_qmhub_module.F90, qm_mm.F90

Passes ucell from Sander QM/MM into the EXTERN layer and writes the 3x3 cell basis to QMHub in all communication modes. In AT26, text and binary modes write ucell(i,:) rows rather than the AT23 patch’s ucell(:,i) columns.

QMHub EXTERN detection and gating

AmberTools/src/sqm/qmmm_nml_module.F90, qm2_read_nm_and_alloc.F90

Adds qmmm_nml%qmhub_extern, sets it only when qm_theory='EXTERN' and an &qmhub namelist are present, broadcasts it in MPI, and prints it with other QMMM settings.

QMHub no-cutoff periodic pair list

AmberTools/src/sander/qm_mm.F90

For QMHub EXTERN periodic QM/MM cases where the QM cutoff sphere exceeds all box dimensions, builds a no-cutoff list containing all non-link MM atoms instead of distance-filtering by qmcut. Unlike the AT23 patch, AT26 limits this behavior to qmmm_nml%qmhub_extern.

Separate legacy EXTERN and QMHub RESP charges

qm2_extern_module.F90, qm_mm.F90, qm_zero_charges.F90, qmmm_struct_module.F90

Keeps the legacy EXTERN charge array separate from QMHub RESP charges, passes qmmm_struct%qm_resp_charges only to QMHub, stores link-pair RESP charges for link atoms, and allocates qm_resp_charges for nquant+nlink entries.

QMHub-only charge adjustment

AmberTools/src/sqm/qm_zero_charges.F90

Applies the QM/link charge correction added by the AT23 patch only when the QMHub EXTERN path is active, so other EXTERN backends keep their AT26-native charge handling.

AT26 compatibility fixes

AmberTools/src/sander/qm2_extern_torchani_module.F90, qm2_extern_module.F90

Slices qmmm_struct%qm_resp_charges(1:nqmatoms) for TorchANI because the array can now include link atoms, and adapts the EXTERN program table to AT26’s existing entries such as ANI.

6.1.7.5. Notable differences from qmhub_at23.patch#

  • More files are touched in AT26. AT26 adds changes to qmmm_nml_module.F90, qm2_read_nm_and_alloc.F90, qmmm_struct_module.F90, and qm2_extern_torchani_module.F90; AT23 does not touch these files.

  • QMHub behavior is explicitly gated in AT26. AT23 applies the no-cutoff periodic pair-list behavior and QM/link charge redistribution broadly once the patched logic is reached. AT26 introduces qmmm_nml%qmhub_extern so those behaviors activate only for EXTERN calculations with an &qmhub namelist.

  • Charge plumbing is more conservative in AT26. AT23 routes EXTERN calls through qmmm_struct%qm_resp_charges; AT26 passes both scf_mchg for legacy EXTERN backends and qmmm_struct%qm_resp_charges for QMHub, avoiding unintended changes to other external engines.

  • Link-atom RESP storage is extended in AT26. AT26 updates qmmm_struct_module.F90 so qm_resp_charges can hold QM atoms plus link atoms (nquant+nlink). This supports the QMHub link-charge additions made in qm_zero_charges.F90.

  • Unit-cell text/binary orientation differs. AT23 writes ucell(:,i) for comm=0 and comm=1; AT26 writes ucell(i,:). FIFO mode writes row slices in both patches. Current QMHub readers load the exchange matrix as a 3x3 array, so the AT26 row-wise output preserves Amber’s ucell matrix orientation for those readers.

  • FIFO startup is hardened in AT26. AT23 creates only the input FIFO before launching QMHub. AT26 creates both input and output FIFO paths up front to avoid a first-step race where Sander writes before QMHub creates the output FIFO.

  • The AT23 sander.F90 message-format tweak is not carried into AT26. AT26’s QMHub patch does not touch AmberTools/src/sander/sander.F90.

  • AT26 preserves newer AmberTools behavior. The patch accounts for AT26’s existing TorchANI/ANI external-QM code and avoids broad changes that would affect other EXTERN backends.

6.1.7.6. Changed files in qmhub_at26.patch#

File

Purpose

AmberTools/src/sander/CMakeLists.txt

Adds QMHub module to Sander CMake source lists.

AmberTools/src/sander/Makefile

Adds QMHub object to traditional Makefile object lists.

AmberTools/src/sander/depend

Adds dependencies and compile rule for qm2_extern_qmhub_module.o.

AmberTools/src/sander/qm2_extern_module.F90

Registers and dispatches the QMHub EXTERN backend.

AmberTools/src/sander/qm2_extern_qmhub_module.F90

New QMHub Sander interface implementation.

AmberTools/src/sander/qm2_extern_torchani_module.F90

Restricts TorchANI RESP-charge copy to real QM atoms.

AmberTools/src/sander/qm_mm.F90

Passes unit-cell/charge data into EXTERN and adds QMHub-gated no-cutoff pair-list logic.

AmberTools/src/sqm/qmmm_nml_module.F90

Adds and broadcasts/prints qmhub_extern.

AmberTools/src/sqm/qm2_read_nm_and_alloc.F90

Detects the &qmhub namelist and sets qmhub_extern.

AmberTools/src/sqm/qm_zero_charges.F90

Adds QMHub link-charge storage and QMHub-only charge redistribution.

AmberTools/src/sqm/qmmm_struct_module.F90

Allocates qm_resp_charges for QM plus link atoms.

6.1.7.7. Usage implication#

For AmberTools 26, this patch expects QMHub runs to use qm_theory='EXTERN' in &qmmm together with an &qmhub namelist. The presence of &qmhub selects the QMHub-specific path; other EXTERN backends should continue using the AT26-native charge and cutoff behavior.