GFN2 dispersion integration

vibeqc.semiempirical.methods.gfn2_dispersion provides internal energy, charge-potential and geometry-derivative operands. An immutable native snapshot participates in molecular SCC. The default faithful molecular GFN2Model uses this coupled path with pinned published references. The explicit legacy_eeq control retains its documented post-SCF correction.

For references indexed by i and j, the symmetric matrix K contains reference C6 coefficients times negative Becke-Johnson damping, with zero same-atom blocks. The reference weights W_i(q_A) combine normalized CN interpolation and charge scaling. Then

E2(q) = 1/2 W(q)^T K W(q)
dE2/dq_A = sum_{i on A} (dW_i/dq_A) (K W)_i

The factor 1/2 counts each atom pair once. For positive Mulliken partial charges q_A = Zval_A - population_A, the corresponding AO Hamiltonian term is -1/2 S_mu,nu (dE/dq_A + dE/dq_B). Using the opposite sign or dropping the pair factor breaks the density derivative. The ATM contribution uses neutral-charge C6 coefficients and therefore contributes no charge potential. This follows Bannwarth, Ehlert and Grimme, JCTC 15, 1652 (2019), doi:10.1021/acs.jctc.8b01176, and the D4 interpolation of Caldeweyher et al., JCP 150, 154122 (2019), doi:10.1063/1.5090222.

Construction freezes the reference data, CN weights and geometric matrix. Evaluation accepts explicit partial charges and performs no EEQ charge solve. It returns energy in Hartree and the charge derivative in Hartree per electron. energy_potential_gradient also returns the explicit gradient in Hartree per bohr at fixed partial charges, including CN response and neutral ATM. The builder accepts explicit reference data and CN operands. The faithful public molecular route supplies the published GFN2 references and CN convention. Independently generated references remain a separate control; changing the charge model alone does not establish reference parity.

tests/test_gfn2_dispersion_functional.py compares matrix energies with an independent pair sum, charge potentials with two finite-difference steps, and the AO term with electron-number-preserving density perturbations. It also checks neutral ATM, atom permutations, immutable operands, the isolated-atom limit and rejection of malformed or missing reference data. Native integration checks compare full coupled SCC free-energy derivatives at two displacement sizes, including fractional occupations and empty valence spaces.

The internal native call accepts kernel.to_native() as its fourth argument. It requires faithful AES and exactly matching elements and coordinates. The kernel is included in every Fock build, the final stationarity check, and each automatic retry. Its energy is counted once in the reported internal and free energies. The analytic gradient combines its explicit geometry derivative with the Mulliken-overlap term and the energy-weighted density of the coupled Fock. Do not add a post-SCF D4 correction to this result.

The native result reports e_dispersion and dispersion_sha256. The latter is a canonical hash of all consumed kernel and derivative operands, computed in the native constructor from detached copies. It is retained even on a failed attempt. It identifies operands, not an independently validated published reference dataset.

Periodic operands

periodic_gfn2_dispersion.build_periodic_d4_charge_functional is an internal fixed-geometry implementation. It includes periodic CN response, charge-coupled two-body D4 and neutral ATM. Image bounds use the inverse lattice, so skew cells and atoms translated outside the home cell retain their physical neighbors. Nonzero self images contribute to energy, charge potential and strain. Unordered ATM neighbor pairs are divided by their three home-cell anchors, including triplets with repeated atom indices in distinct cells.

The CN, two-body and ATM cutoffs default to 30, 50 and 25 bohr. Dispersion edges use a quintic switch over the final 0.05 bohr, matching the tblite 0.7.0 configuration with the dftd4 4.2.0 switch. The product of all three edge switches multiplies ATM. Both energy and derivatives include these switches. An explicit zero width selects hard cutoffs; derivatives then apply away from image crossings. CN retains its hard cutoff, where the counting function must be negligible for a well-converged calculation. Cutoff convergence remains the caller’s responsibility.

energy_potential_gradient_strain returns energy, charge potential, nuclear gradient and the derivative with respect to all nine components of homogeneous strain. Coordinates and lattice transform together by I + strain. This last quantity is in Hartree, without a pressure sign or volume division. The derivatives hold charges fixed and include the geometry response of CN. An SCC driver must also include the charge potential’s overlap response.

Focused checks cover two-step charge, nuclear and all-nine strain derivatives, switch boundaries, cell replication in one to three dimensions, atom image translations and permutations, and the molecular limit. A primitive NaCl neutral ATM reference checks the smoothing convention independently of SCF. The internal native Gamma driver accepts functional.to_native() as its fifth argument, after the electronic image cutoff. Its D4 potential enters every Fock build and bounded retry. The returned e_dispersion is already included in energy, e_electronic and free_energy; do not add it again. The explicit nuclear/strain terms and the charge-potential overlap response are included in the native derivative routines. Failed SCC results retain the operand identity and cannot supply derivatives. Empty-electron cells still have the derivatives of their non-electronic terms.

The immutable snapshot’s hash binds dimension, lattice, cutoff convention and all derivative operands. Molecular and periodic snapshots cannot be interchanged; changed coordinates or lattice require rebuilding the operands. The molecular snapshot format and its hash remain unchanged.

The public Gamma single-point route, periodic energy closure and analytic energy/gradient facade supply these operands by default. Parameters and the published reference dataset are pinned for an energy closure; each trial geometry rebuilds its CN, image kernels and derivative operands. Missing or invalid offline references refuse the calculation, with no dispersion-free fallback. The low-level native call without operands remains a bare control.

The public single-point result forwards native attributes and exposes native_result for low-level derivative calls and an immutable dispersion_record. The .out, .system and QVF job options record dispersion_model=self_consistent_d4, the operand and reference hashes, reference revision, damping parameters, cutoffs and smoothing width. e_dispersion_hartree is an included diagnostic channel, not an extra correction. Failed SCF attempts retain provenance and are not marked complete. The energy/gradient facade also honors explicit SCC budgets and tolerances.

External periodic energy/derivative acceptance remains open. This integration does not resolve the difference between the lattice-summed gamma kernel and a reference’s nearest-image convention; output retains shell_gamma_image_convention=lattice_sum. Full-k remains unsupported.