vibe-qcDocumentation

Design: GFN2-SECCM as the complete GFN2-xTB functional

Status. GFN2-SECCM is experimental. Since #1115 its default route is the complete GFN2-xTB energy functional of Bannwarth, Ehlert and Grimme (2019): H0, isotropic second order, anisotropic second order (AES and anisotropic XC), third order, repulsion and the self-consistent D4 dispersion of Caldeweyher et al. (2019). The energy is available, with its analytic fixed-topology nuclear gradient (#1120) and a finite-difference gradient as its independent reference; a stress is not implemented. The long-range closure of the monopole Coulomb term remains the subject of the long-range gamma design note.

This note states which closure every term of the functional uses on the cyclic cluster and why.

One closure per interaction class

A cyclic cluster is a finite translation group: N copies of the primitive cell with the cluster translations identified with zero. An interaction between two sites of that group has to be closed, because the two sites are connected by infinitely many images. Three closures exist, and the physics of the interaction, not convenience, selects one.

  1. Wigner-Seitz closure. Each central atom interacts with every other atom through its nearest image; images at equal distance share the pair with fractional weights that sum to one. A Wigner-Seitz cell therefore holds every other atom exactly once and never an image of the central atom itself. This is the closure of the exchange-like and short-range one-electron terms (Bredow, Geudtner and Jug (2001), Peintinger and Bredow (2014)): it keeps the cluster Hamiltonian a finite, translation-covariant matrix.

  2. Lattice sum with its own cutoff. A classical pair or triple sum whose range is a property of the interaction is summed over every real image of the cluster translations inside that range, self images included. The result does not know the cluster size.

  3. Ewald completion. A Coulomb interaction whose lattice sum converges conditionally, or not fast enough to truncate, is summed completely through the Ewald-regularized lattice potential.

The table lists the terms of the functional, the closure that runs and the key under which GFN2SECCMResult.interaction_closures records it.

Term

Long-range form

Closure

Record key

Option

Overlap, extended Hueckel H0

exponential

Wigner-Seitz

overlap_h0

fixed

Coordination numbers in H0 and the AES radii (Eq. 18, Eq. 29)

cutoff 15 bohr

lattice sum; Wigner-Seitz on request

h0_coordination_numbers

geometric_closure

Repulsion (Section 2.2.1)

exponential, cutoff 15 bohr

lattice sum; Wigner-Seitz on request

repulsion

geometric_closure

Isotropic second order, short range (Eqs. 21-22)

gamma - 1/R

Wigner-Seitz

isotropic_coulomb_short_range

fixed

Isotropic second order, 1/R tail

1/R

Ewald on request, else truncated

isotropic_coulomb_long_range

ewald_gamma, madelung

Third order (shell-wise, on-site)

on-site

none needed

third_order

fixed

AES damped kernel (Eqs. 25, 28), anisotropic XC (Eq. 31)

R^-5 and R^-7 remainders

Wigner-Seitz

aes_damped_kernel

fixed

AES bare charge-dipole

R^-2

Ewald on request

aes_charge_dipole

aes_ewald

AES bare dipole-dipole

R^-3

Ewald on request in 3-D

aes_dipole_dipole

aes_ewald

AES bare charge-quadrupole

R^-3

Ewald on request in 3-D

aes_charge_quadrupole

aes_ewald

D4 coordination numbers

erfc, cutoff 30 bohr

lattice sum

d4_coordination_numbers

d4_model

D4 two-body (Section 2.2.6)

R^-6, cutoff 50 bohr

lattice sum

d4_two_body

d4_model

D4 three-body (Eq. 32)

R^-9, cutoff 25 bohr

lattice sum

d4_three_body

d4_model

On a zero-image topology (every record is the home image at full weight) the cyclic cluster is the ordinary molecule. The adapter then delegates to the molecular driver and every entry reads molecular or molecular_limit: the free-boundary functional, D4 included.

Self-consistent D4 on the cyclic cluster

The molecular functional (python/vibeqc/semiempirical/methods/gfn2_dispersion.py) is

E_D4(q) = 1/2 W(q)^T K W(q) + E_ATM
W_i(q)  = w_i(CN_A) zeta_i(q_A)
K_ij    = C6_ij^ref [-s6/(R^6 + R0^6) - s8 Q/(R^8 + R0^8)]

with i, j the reference systems of the atoms, w_i the Gaussian coordination-number weights, zeta the charge scaling, Q = 3 r4r2_A r4r2_B and R0 = a1 sqrt(Q) + a2. q_A are the Mulliken partial charges of the SCC, so E_D4 is a functional of the density and its charge derivative enters the Hamiltonian as -1/2 S (dE/dq_A + dE/dq_B). The three-body term uses neutral-atom C6 coefficients and does not depend on the charges.

On the cyclic cluster each ingredient is closed as follows (build_cyclic_d4_charge_functional in python/vibeqc/semiempirical/methods/periodic_gfn2_dispersion.py).

Ingredient

Closure

Cutoff

Coordination number CN_A (electronegativity-weighted erfc counting)

sum over every atom B and every image T of the cluster translations, self images included

30 bohr

Reference weights w_i(CN_A)

local function of CN_A

none

Charge scaling zeta_i(q_A)

local function of the cluster atom’s own SCC charge

none

Two-body kernel K_ij

sum of the damped pair factor over every image T, self images included, times the quintic switch

50 bohr, switch width 0.05 bohr

Three-body term

sum over image triples: anchor A in the cluster, unordered neighbour images (B,T), (C,U), one third per anchor

25 bohr on every edge, same switch

The cutoffs, the switch and the coordination-number constants are those of the Gamma-periodic route (build_periodic_d4_charge_functional), so the two routes evaluate one functional. The operands are in fact the periodic operands with the cluster as the cell; the cyclic builder differs in producing the energy and the charge potential only, in vectorizing the image sums, and in evaluating the triple sum in a native kernel.

Why Wigner-Seitz closure would be wrong here. Dispersion is a classical pair interaction with an R^-6 tail. A Wigner-Seitz cell cuts that tail at half the cluster width and removes all self images, so the dispersion energy per cell would depend on the cluster size through a term of order L^-3 in three dimensions, and a (1,1,1) cluster of a one-atom cell would have none at all.

Why the D4 energy per primitive cell does not depend on the cluster size at fixed charges. Let the geometry repeat with the primitive lattice Lambda_p and let the cluster lattice Lambda_c be a sublattice of index N. Every atom of the infinite crystal is (b, t) with b a primitive site and t in Lambda_p, and also (B, T) with B a cluster atom and T in Lambda_c; the two labellings name the same set of points. The sums above run over all (B, T) with a bound on the physical distance only, so for a cluster atom A they are sums over the same physical neighbours as for its primitive site. Hence CN_A equals the primitive value, and so do w_i. If the charges repeat with Lambda_p as well, W repeats, the row sums sum_j K_ij W_j equal their primitive values, and

E_D4(cluster) = N E_D4(primitive cell).

The same argument covers the three-body term: an anchor sees the same image triples in either labelling. The identity is exact; the only difference between two cluster sizes is the order of summation. The test test_cyclic_d4_energy_per_cell_is_independent_of_cluster_size holds it to 1e-12 Ha in one, two and three dimensions. During an SCC the charges are those of the cluster atoms; when they break the translation symmetry the functional is still the correct periodic functional of the cluster cell.

Three-body anchors. When every bound-group translation is a symmetry of the current structure, the anchors of one translation orbit have equal shares, so one anchor per orbit is evaluated and multiplied by the orbit size. The coordination numbers of an orbit are then set to one common value, which makes the operands translation covariant to the last bit. On a displaced structure (a finite-difference point) every atom is an anchor. dispersion_record["d4_atm_anchor_reduction"] records which ran.

Molecular limit. In a box wider than every cutoff no image contributes and the cyclic operands are the molecular operands (test_cyclic_d4_reaches_the_molecular_functional_in_a_wide_box, 1e-13 Ha). A zero-image topology is delegated to the molecular driver with the molecular operands, whatever the box.

Coupling. The native supercell engine receives the operands (GFN2SECCMDispersion), deposits -dE_D4/dq_A in the shell potential on every charge-map evaluation and adds E_D4 at the density’s own Mulliken charges, exactly as the molecular and Gamma-periodic drivers do. The fixed point is a stationary point of the reported energy (test_complete_functional_is_stationary_at_the_scc_fixed_point). As in the molecular driver, the coupled term is refused with the ad-hoc AES, whose Fock matrix is not the derivative of its energy.

Records. dispersion_included, e_dispersion (per primitive cell), cyclic_dispersion_energy, d4_model, dispersion_closure and dispersion_record (operand digest, reference-data revision and digests, damping parameters, cutoffs). d4_model="none" runs the dispersion-free functional and records dispersion_included=False.

Departure from the reference programs. The D4 lattice sums follow the cutoff convention of the Gamma-periodic route (tblite 0.7.0 switching width). The quadratic charge-kernel spectrum of #137 does not include the D4 term, which is not quadratic in the charges.

Coordination numbers and repulsion

The Eq. 18 coordination number enters the H0 self-energies and the multipole radii of Eq. 29; the classical repulsion is a pair energy. Both are classical, charge-independent pair sums with a short range: the coordination count has a 15 bohr cutoff and the repulsion decays as exp(-sqrt(a_A a_B) R^k_f).

Before #1115 both were summed over the Wigner-Seitz records. That is exact once the cluster is wider than twice the range, and truncated below it: a record set holds each other atom once and no self image. On the (1,1,1) cluster of the two-atom diamond cell the Wigner-Seitz coordination number counts one neighbour (four tied images of weight 1/4) instead of four nearest neighbours and the next shells, and the repulsion holds one bond per cell instead of four.

geometric_closure="lattice_sum" (the default) closes both as lattice sums over the cluster translations: gfn2_h0_periodic_coordination_numbers on the cluster cell, and the pair-complete repulsion sum of the Gamma-periodic driver with its 15 bohr pair cutoff. They are the Gamma-periodic route’s values for the same cell (test_small_cluster_coordination_numbers_and_repulsion_match_gamma_route) and do not depend on the cluster size (test_lattice_sum_closure_is_independent_of_cluster_size). geometric_closure="wigner_seitz" restores the former sums. The two agree only when no image outside the Wigner-Seitz cell lies inside the cutoff; on a 16 bohr wire of water molecules they already differ, through an H…O image at 9.8 bohr.

The H0 hopping and the overlap stay on the Wigner-Seitz records. A lattice-summed coordination number with a Wigner-Seitz hopping is not an inconsistency: the coordination number is an environment descriptor of the atom, and the environment of an atom in the crystal is the same in every cluster.

Anisotropic electrostatics at long range

The legacy ad-hoc model

aes_faithful=False selects the shell-resolved gamma^3/gamma^5 multipole kernel on moment integrals of the home-cell molecule. On a topology with periodic images that operator depends on which lattice copy of an atom was typed. It is not translation covariant: translation-orbit charge spreads of 1.8e-3 e (LiH chain) and 3.8e-3 e (HF chain) that do not shrink with the SCC tolerance, and a 1.6e-4 Ha dependence on the typed representative, against 1e-14 e and exact invariance for the faithful model. It is therefore refused on a cyclic topology with periodic images unless allow_legacy_adhoc_aes=True is passed, which emits GFN2SECCMLegacyAESWarning; its energy carries no D4. The zero-image molecular limit has no images and is not affected.

Limiting forms and convergence

The faithful model is Eq. 25 of the GFN2 paper on cumulative atomic multipole moments. With the pair vector R and the damping of Eq. 28,

f_n(R) = 1 / (R^n [1 + 6 (R0_AB / R)^a_n]),    a_3 = 3, a_5 = 4,

the three pair terms are

charge-dipole       f_3(R) q mu . R                              -> R^-2
charge-quadrupole   f_5(R) q R^T Theta R                         -> R^-3
dipole-dipole       f_5(R) [(mu_A . mu_B) R^2 - 3 (mu_A . R)(mu_B . R)] -> R^-3

and the arrow gives the long-range form, since f_n -> R^-n. Expanding the damping, f_n = R^-n [1 - 6 (R0/R)^a_n + ...], splits each term into its bare multipole interaction and a remainder that decays as R^-5 (charge-dipole) or R^-7 (the two R^-3 terms). The on-site anisotropic XC energy of Eq. 31 has no pair sum.

A lattice sum of a term of order R^-n over a d-dimensional lattice has R^(d-1) dR sites per shell, so it converges absolutely exactly when n > d. For n <= d the sum over a neutral cell with traceless tensors converges only conditionally: its value depends on the order of summation.

Interaction

n

1-D

2-D

3-D

remainders (damped minus bare)

5, 7

absolute

absolute

absolute

bare charge-dipole

2

absolute

conditional

conditional

bare dipole-dipole

3

absolute

absolute

conditional

bare charge-quadrupole

3

absolute

absolute

conditional

Consequences for the closure:

  • The remainders may be closed by the Wigner-Seitz records in every dimension. Their truncation error decays at least as L^(d-5) with the cluster width L.

  • An absolutely convergent bare term may also be closed by the Wigner-Seitz records; the truncation error vanishes with the cluster size, as L^(d-n): 1/L for the charge-dipole term in one dimension and for the R^-3 terms in two, 1/L^2 for the R^-3 terms in one.

  • A conditionally convergent bare term must not be truncated: the Wigner-Seitz sum has no cluster-size limit that is independent of the shape of the cell. It needs Ewald completion.

Ewald completion

The bare interactions are spatial derivatives of 1/r: charge-dipole is -grad(1/r), dipole-dipole -Hess(1/r) and charge-traceless-quadrupole Hess(1/r)/3. Replacing 1/r by the Ewald lattice potential Phi of the cluster translations gives the complete bare lattice sum. The damped kernel over the Wigner-Seitz records already holds the bare sum over those records, so only the difference is added:

E_tail = 1/2 sum_ab [ -(q_a mu_b - q_b mu_a) . G_ab
                      - mu_a . H_ab mu_b
                      + (q_a Theta_b + q_b Theta_a) : H_ab / 3 ]
G_ab = grad Phi(R_a - R_b) + sum_{WS records} w d / |d|^3
H_ab = Hess Phi(R_a - R_b) - sum_{WS records} w (3 d d^T / |d|^2 - 1) / |d|^3

with d the record pair vector and w its weight. For a = b the lattice self potential is used (no zero-distance term) and there are no records. This is the construction of the Gamma-periodic driver’s nearest-image convention (methods/xtb/periodic_gfn2.cpp), driven by the Wigner-Seitz records with their fractional weights. The potentials added to the Fock matrix are the exact derivatives of E_tail with respect to the charges, dipoles and (through the traceless-to-raw chain) quadrupoles, so the SCC stays variational.

aes_ewald=True enables it:

  • G, the charge-dipole term, in one, two and three dimensions, from EwaldCoulombKernel::gradient: the three-dimensional Ewald sum with the conducting (tin-foil) boundary, the two-dimensional Parry sum including the field of the charged sheet, and the one-dimensional wire sum.

  • H, the dipole-dipole and charge-quadrupole terms, in three dimensions, from EwaldCoulombKernel::hessian_3d, again with the conducting boundary.

  • In one and two dimensions H stays zero. Those sums converge absolutely, so the Wigner-Seitz closure is correct in the large-cluster limit, with the algebraic error stated above. The shared kernel has an analytic off-site one- and two-dimensional Hessian (EwaldCoulombKernel::hessian, added for the gradient) but no same-site one, which the a = b terms would need; a finite-difference Hessian of the gradient was rejected because the lattice self term has a 1/r^2 singularity that the kernel’s self convention removes only exactly at zero displacement.

The result records the closure of each of the three terms: ewald_completed, ws_truncated_absolutely_convergent, ws_truncated_conditionally_convergent, molecular_limit, ws_truncated_home_cell_moments (the legacy model) or none. The option is off by default, like the monopole closures: without it a three-dimensional run reports all three terms, and a two-dimensional run the charge-dipole term, as conditionally convergent and truncated.

Verification without a reference program:

  • tail + (bare sum over the Wigner-Seitz records) is the complete bare lattice energy, which per primitive cell cannot depend on the cluster. It agrees between the (1,1,1) and the (2,1,1) cluster to 1e-9 Ha in every dimensionality (two different Ewald widths).

  • In one dimension the charge-dipole tail equals a direct sum over 40001 images, independent of any Ewald code.

  • The fixed point of an SCC with the tail is stationary under occupied-virtual rotations, on a 1-D wire (gradient potentials) and in a 3-D cell (Hessian potentials).

A complete electrostatic closure combines aes_ewald=True with a monopole closure (ewald_gamma=True, with gamma_form="elstner" in three dimensions). The two are independent options because the monopole closure of the published Klopman-Ohno kernel has no three-dimensional thermodynamic limit, which is a separate decision.

State policy for scans

A lowest-state policy can switch solutions between neighbouring points of a lattice scan. The route never selects a state silently; it records which start produced the returned state and lets a scan follow one state.

  • initial_shell_charges seeds the primary SCC attempt. The seed carries the shell charges; on the faithful AES the atomic multipoles start from zero and converge with the charges.

  • result.shell_charges is the vector to pass on. continue_gfn2_seccm_state(previous, molecule, topology, ...) does so.

  • result.scc_seed (neutral or supplied), scc_seed_sha256 and selected_seed (the start of the attempt that produced the state) record the seed. They differ when the stabilisation ladder converged a neutral restart after the seeded attempt failed.

  • seed_policy="strict" (the default of the continuation helper) raises GFN2SECCMStateSeedError in that case instead of returning the other state. seed_policy="allow_neutral_restart" returns it, recorded.

  • The existing audit (audit_states) still runs one alternative neutral-start solve and reports a different free energy as GFN2SECCMStateAmbiguityWarning; it never replaces the selected state. compare_gfn2_seccm_states reports the changes between two points and now compares the dispersion model and the closures as part of the Hamiltonian identity.

Gradient

gfn2_seccm_gradient_fd is a central difference of the reported energy:

  • the Wigner-Seitz topology is fixed and only the record displacements follow the atoms; the lattice sums are rebuilt at every point;

  • a reference SCC runs first, with strict_temperature=True;

  • every displaced SCC is seeded with the reference shell charges under seed_policy="strict", at the reference temperature requested explicitly;

  • a displaced SCC that fails raises GFN2SECCMGradientError;

  • state continuity is judged on rotation-invariant quantities: the shell charges (bound 1e-2 + 25 h electrons) and the symmetric second difference of the cyclic energy (bound max(1e-4, 25 h^2) Ha), plus equality of the Hamiltonian identity, the dispersion model and the closures;

  • gradient is the derivative of the energy per primitive cell with respect to one cluster atom; cyclic_gradient = N gradient is the derivative of the total cyclic energy, which at a translation-covariant geometry is the primitive-cell gradient of that atom’s sublattice;

  • one representative per translation orbit is differentiated only when every bound-group translation is a symmetry of the reference structure and the reference charges respect it.

Analytic gradient

run_gfn2_seccm(compute_gradient=True) and gfn2_seccm_gradient return the analytic derivative of the same energy at the same fixed topology (cpp/src/semiempirical/seccm/gfn2_gradient.cpp), as the same GFN2SECCMGradient object (gradient_method="analytic"), so the two are interchangeable. Every atom is differentiated at once; no translation-orbit reduction is applied.

Why no response term. The SCC Fock is the derivative of the reported energy with respect to the density: the shell potential of the isotropic, third-order, Madelung and D4 terms enters through the S-weighted Mulliken deposit, and the faithful AES Fock is dE_AES/dD (Bannwarth 2019, Eqs. 39-44), Ewald tail included. The occupations are Aufbau or Fermi-Dirac at the SCC temperature, for which the Mermin free energy is stationary. The energy is therefore stationary in the orbitals and the occupations, and the gradient is the Hellmann-Feynman/Pulay form. For D4 in particular: E_D4 depends on the density only through the Mulliken charges q_A(D, S), and its charge derivative is part of the Fock, so the charge response cancels with the other orbital responses; what remains is its dependence through S (contracted with dS like every other Mulliken term) and its explicit fixed-charge geometry derivative.

Terms. With D_L and w_L o X the supercell matrices scattered into the blocks of image label L with the ownership weights of the overlap assembly, v the total shell potential, W the energy-weighted density and P the moving-retained-subspace response of a screened overlap:

Term

Derivative

Code

Overlap, H0 shape factor, Mulliken potentials

sum_L tr[M_L dS_L], M_L = D_L o (F_L + (v_mu + v_nu)/2) - w_L o (W - P)

overlap_lattice_gradient_contribution per label, gfn2_h0_image_derivative_terms

H0 distance polynomial (Eq. 19)

D_L : dH0_L/dR at fixed S, CN

gfn2_h0_image_derivative_terms

Coordination numbers (H0 self-energies, AES radii)

dE/dCN dCN/dR in the executed closure

gfn2_periodic_cn_chain_derivatives on the cluster cell; record loop with gfn2_h0_coordination_pair_derivative

Isotropic second order

1/2 dq . dGamma/dR . dq

record loop (Wigner-Seitz Klopman-Ohno); periodic_shell_gamma_gradient (Ewald, Klopman-Ohno or Elstner)

Madelung embedding

1/2 q . dM_eff/dR . q

wire_kernel_gradient (1-D), indo::_add_madelung_gradient (2-D)

Third order

through the charges only (in v)

none

Faithful AES

integral derivatives, CAMM origins, damped kernel, Eq. 29 radii

contract_gfn2_multipole_lattice_derivatives with the record pair weight, gfn2_aes_origin_derivatives, gfn2_aes_kernel_derivatives

AES Ewald tail

dG/dR = Hess Phi, dH/dR = third derivatives of Phi, record terms analytic

EwaldCoulombKernel::hessian (1-D, 2-D, 3-D), third_derivative_3d

Screened overlap

moving retained subspace

screened_overlap_projector_response

Repulsion

pair derivative in the executed closure

lattice sum over the cluster cell; record loop

D4, charge response

-dE_D4/dq in v

native

D4, explicit

pair kernel, CN weights, three-body

build_periodic_d4_charge_functional on the cluster cell (Python), checked against the cyclic operands to 1e-7

Refusals. Before the SCC: the legacy ad-hoc AES and the legacy diagonal Madelung deposit, whose Fock is not the derivative of the energy. After it, GFN2SECCMGradientError: an unconverged or unphysical state, or one that converged only on an elevated-temperature stabilisation rung (pass an explicit temperature to differentiate a smeared state). A state at which the derivative does not exist (an overlap eigenvalue on the screening threshold) is reported with its reason. A zero-image delegation returns the molecular analytic GFN2 gradient (gradient_method="analytic_molecular").

Pair virials. Every term that is a sum over record or image pair vectors v is accumulated through dE/dv, and its pair-vector virial sum (dE/dv) (x) v is returned (gradient_pair_virials): the H0 polynomial, the coordination-number chain, the Wigner-Seitz Coulomb kernel, the AES kernel and the record part of the AES tail, and the repulsion.

Verification. tests/test_gfn2_seccm_gradient.py compares the analytic gradient with gfn2_seccm_gradient_fd and with central differences at fixed topology in one, two and three dimensions, for each closure, with and without D4, with the AES tail, at finite temperature and with a screened overlap; it checks the translational sum rule, rotational covariance, the molecular limit and every refusal.

Strain derivative

run_gfn2_seccm(compute_stress=True), and the front-door route option compute_stress, return strain_derivative[a, b] = dE/d eps_ab of the energy per primitive cell under x -> (1 + eps) x of the atoms and the cyclic translations together, at fixed Wigner-Seitz topology, unsymmetrized (the contract of the SECCM stress design; Doll, Mol. Phys. 108, 223 (2010), Eq. 1). Stress, periodic stress, pressure and cell gradient are derived centrally by seccm_stress_from_strain_derivative; optimize_seccm_cell uses the analytic derivative.

The variational argument of the gradient carries over unchanged: at fixed weights the energy is stationary in the density, the occupations (Mermin at finite temperature) and the CAMM, so W is the explicit derivative of each term at fixed D and charges. It is computed in the same pass as the gradient (gfn2_gradient.cpp, in.compute_strain): every per-record derivative is contracted once with the atoms and once with the record vector. Term by term (cyclic, then divided by the group order):

Term

Strain derivative

Code

Overlap, H0 shape factor, Mulliken potentials, screened subspace

sum_L M_L : (dS_L/dd)_a d_b, d = R_nu + T(L) - R_mu, the M_L blocks of the gradient

overlap_record_strain_contribution per label

H0 distance polynomial

pair virial over R = R_a - R_b - T(L)

gfn2_h0_image_derivative_terms (strain_poly)

Coordination numbers

pair virial of the Eq. 18 sum in the executed closure; the lattice sum includes the image vectors of the cluster translations

gfn2_periodic_cn_chain_derivatives (strain_derivative); record loop

Isotropic second order, Wigner-Seitz

record pair virial

record loop

Isotropic second order, Ewald

remainder pair virial plus 1/2 sum_ab dq_a dq_b dPhi/d eps (R_b - R_a), same-site pairs included; ewald_gamma_molecular_onsite subtracts 1/2 sum_A Q_A^2 dPhi_self/d eps

ewald_gamma_strain_derivative, EwaldStrainKernel::strain

Madelung embedding

1/2 sum w q_I q_J [dPhi/d eps(-d) + d d^T/d^3], own images included; madelung_no_self subtracts the strain derivative of the madkonst diagonal

seccm_madelung_strain_derivative; madelung_self_strain_derivative

AES multipole integrals and CAMM origins

sum_A g_A (x) R_A + sum_g f_ket(g) (x) g: global-origin integrals and the origins R_A, R_B + g depend on absolute positions and on the image vectors

contract_gfn2_multipole_lattice_derivatives and gfn2_aes_origin_derivatives (image_virial), as in the periodic GFN2 stress

AES damped kernel, Eq. 29 radii

record pair virial; radii through the CN chain

gfn2_aes_kernel_derivatives (strain)

AES Ewald tail, records

record pair virial

record loop

AES Ewald tail, lattice

1/2 sum_ab [u_ab . dG/d eps + M_ab : dH/d eps] at fixed moments, G = grad Phi (one to three dimensions), H = Hess Phi (three), the same-site Hessian included

EwaldFieldStrainKernel (gfn2_aes_tail_strain.h)

Repulsion

pair virial in the executed closure

lattice sum; record loop

Third order

through the charges only

none

D4, charge response

-dE_D4/dq in the M_L blocks

native

D4, explicit

CN, two-body and three-body strain at fixed charges

PeriodicD4ChargeFunctional.energy_potential_gradient_strain on the cluster cell (Python), checked against the cyclic operands to 1e-7

The Ewald parameter is held fixed in every lattice derivative: the converged sums do not depend on it (Nielsen and Martin, Phys. Rev. B 32, 3780 (1985)); the kernels were evaluated at two values of alpha and agree to 1.5e-12.

Strain derivatives of the field and field gradient. With Phi_eps((1 + eps) v) = Phi(v) + eps : S(v) for every v (S the strain derivative of the potential, EwaldStrainKernel), differentiating in v gives

dG_i/d eps_cd  = d_i S_cd - delta_id G_c,
dH_ij/d eps_cd = d_i d_j S_cd - delta_id H_cj - delta_jd H_ic.

Real space: every image strains with the lattice, so it contributes (d_c d_i g)(r) r_d and (d_c d_i d_j g)(r) r_d with g = erfc(alpha r)/r. Three dimensions: dg_i/d eps_cd = -delta_id g_c, dw_g/d eps_cd = w_g m_cd, m_cd = 2 g_c g_d (1/g^2 + 1/(4 alpha^2)) - delta_cd, and the phase is invariant. Two dimensions: the v-gradient of the Parry strain derivative term by term in the phase and the height, with dF/dz = K G, dG/dz = K F - (4 alpha/sqrt(pi)) E and d[(dF/dK)/K - F/K^2]/dz = z F (Parry, Surf. Sci. 49, 433 (1975); de Leeuw and Perram, Mol. Phys. 37, 1313 (1979)). One dimension: the v-gradient of the Euler form of the wire strain derivative, from the kernel’s value, gradient and Hessian. The same-site field and its strain derivative vanish by inversion symmetry; the same-site Hessian is the lattice self term, whose regular part -erf(alpha r)/r is a fixed function of v and contributes nothing.

Because the moments are space-fixed while the lattice kernels rotate, the tail, kernel, integral and origin terms each have antisymmetric parts of up to 0.5 Hartree; only their sum is symmetric, which makes the antisymmetric part of W a sharp consistency check.

Molecular limit. A zero-image delegation (every record in the home cell) does not depend on the translations; W is the atomic virial sum_A g_A (x) R_A of the molecular analytic gradient.

Refusals. Exactly the gradient’s: the legacy ad-hoc AES and the legacy diagonal Madelung deposit before the SCC, and after it an unconverged, unphysical or elevated-temperature state (GFN2SECCMGradientError with strain_refusal). Every other option combination of the supercell engine is covered in one to three dimensions.

Verification. A standalone native harness of gfn2.cpp and gfn2_gradient.cpp compared W with fourth-order central differences of the fixed-topology energy per cell (h = 1e-3, all nine components, SCC charges to 1e-11) for the polar HF cell: 1-D with the Wigner-Seitz and lattice-sum closures, Ewald Klopman-Ohno (with ewald_gamma_molecular_onsite), Ewald Elstner with the AES tail, Madelung (with madelung_no_self), T = 0.01 Ha, the AES off and synthetic D4 operands; 2-D Ewald Elstner with the tail, Madelung, madelung_no_self, ewald_gamma_molecular_onsite, Ewald Klopman-Ohno; 3-D Ewald Elstner with the tail and with the Wigner-Seitz closure at T = 0.02 Ha. All agree to 2.8e-11..3.7e-11 Hartree with |W| of order 1e-2; a tied H4 ring at T = 0.01 Ha to 9.0e-12, a screened H2 chain (one negative overlap mode, |W| = 1.5 Ha) to 6.8e-12, the molecular limit to 2.4e-11. The antisymmetric part is below 2.2e-13, a rotation of the 3-D cell maps W to Q W Q^T to 5e-15, and the field and field-gradient kernels agree with strained-lattice differences to 1e-12 (1-D), 6e-12 (2-D) and 2e-11 (3-D) for values of order one. tests/test_gfn2_seccm_stress.py repeats the comparisons through the front door against seccm_strain_derivative_fd, with the explicit D4 strain, and adds the trace against a rebuilt-topology scaling scan, front-door units and the record, and the cell optimiser.

Memory

assemble_gfn2_supercell used to hold the overlap and H0 image block of every image label at once, two n_basis^2 matrices per label (54 in three dimensions). The blocks are now streamed: one label is computed, scattered into the supercell matrices and released. The assembly performs the same operations in the same order as before; a pair that owns several tied images keeps its summation in record order by setting its sub-blocks aside until the last label. Peak storage is the two supercell matrices, two image blocks and the sub-blocks of the tied pairs (none for odd replica counts). The multipole lattice sums of the faithful AES are built by the shared routine and are not changed here.

What remains

  • Stress: a comparison of the GFN2-SECCM stress of a converged cluster with a periodic Gamma-supercell GFN2 stress of the same cell (compute_periodic_gfn2_stress) is a calculation for the validator.

  • Ewald completion of the R^-3 AES terms in one and two dimensions, to remove their algebraic cluster-size error.

  • The three-dimensional monopole closure of the published Klopman-Ohno kernel (former-tracker issue 444) is unchanged: it still fails closed.

  • A deterministic test of the seed_policy="strict" refusal needs a system whose seeded attempt fails and whose neutral restart converges.

  • Block-sparse multipole lattice sums.

  • The reference comparisons of #1115 (a Gamma-supercell tblite or xtb energy for diamond, Si and MgO; dftd4 on the same periodic cells) are calculations for the validator and are not part of this change.