xnn.common.models.d3#

Grimme DFT-D3 London dispersion: a geometry-dependent correction for any xnn model.

Implements the D3 model of Grimme, Antony, Ehrlich & Krieg, J. Chem. Phys. 132, 154104 (2010) with the damping functions of that paper (zero damping) and of Grimme, Ehrlich & Goerigk, J. Comput. Chem. 32, 1456 (2011) (rational Becke-Johnson damping), in pure PyTorch, as an additive energy term that combines with every xnn model family and deploys through every channel (PyTorch, TorchScript, ASE, LAMMPS) – the same way d4 does for the charge-dependent successor D4.

The model, equation by equation (atomic units; 2010 paper numbering)#

  • Coordination number (eq 15): CN_A = sum_B 1 / (1 + exp(-k1 (k2 (R_A,cov + R_B,cov) / R_AB - 1))) with k1 = 16 and the 4/3-scaled Pyykko covalent radii, no electronegativity factor.

  • CN-dependent C6 (eq 16): a Gaussian-weighted average over the TD-DFT reference pairs, C6^AB = sum_ij C6,ref^AB(CN_i, CN_j) L_ij / sum_ij L_ij with L_ij = exp(-k3 [(CN_A - CN_i)^2 + (CN_B - CN_j)^2]), k3 = 4; here written as a product of per-atom weights.

  • C8 (eqs 6, 9): C8 = 3 C6 sqrt(Q_A Q_B) with the tabulated sqrt(0.5 sqrt(Z) <r^4>/<r^2>) factors.

  • Two-body energy (eqs 3-4): E = -sum_AB sum_n=6,8 s_n C_n / R^n f_n with the damping function selected by damping:

    • "zero" (2010 eq 4, Chai & Head-Gordon): f_n = 1 / (1 + 6 (R / (sr_n R_0^AB))^-alp_n), alp_6 = alp, alp_8 = alp + 2, with the tabulated pair cutoff radii R_0^AB of sec II.D;

    • "bj" (2011 eqs 5-7, rational): E = -sum_AB sum_n s_n C_n / (R^n + (a1 R_0 + a2)^n) with R_0 = sqrt(C8/C6);

    • "mzero" (Smith et al. 2016): zero damping with the shifted argument R / (sr_n R_0) + bet R_0;

    • "op" (Witte et al. 2017, optimized power): E = -sum s_n C_n R^bet / (R^(n+bet) + (a1 R_0 + a2)^(n+bet)).

  • Three-body ATM energy (eqs 11-14): E = s9 sum_ABC C9 (3 cos cos cos + 1) / (R_AB R_BC R_CA)^3 f_d,3 with C9 = sqrt(C6 C6 C6) and zero damping built on the 4/3-scaled pair cutoff radii and exponent alp + 2 (off by default, as recommended in the paper and as in the reference code).

Fidelity#

An independent implementation, written from the two papers and the observed behavior of the reference code simple-dftd3 (not copied, and never imported here). The conventions the papers leave to the code are reproduced so that energies, gradients and virials match s-dftd3 to floating-point precision for every damping function, molecular and periodic (tests/test_d3.py and examples/fidelity_checks/d3_verification.ipynb): the exponential counting function and its 40 bohr cutoff, the highest-CN fallback of the Gaussian weights, the 60 / 40 bohr pair / triple cutoffs with optional quintic switching windows, and the triple_scale bookkeeping of the ATM term.

One reference-data file ships next to this module, d3_reference.npz, extracted from the reference code by tools/build_d3_reference.py. It holds two sets of reference systems, selected with references:

  • "2010" – Grimme’s original reference systems (Z <= 94, up to five per element), the tables of the original D3 codes and of the PhysNet TensorFlow code. Default of the legacy functional API below (edisp(), _ncoord(), _getc6()), which PhysNet and BAMBOO’s D3(CSO) use, so their upstream parity holds for every element;

  • "2024" – the current reference code (simple-dftd3 >= 1.1.0), which re-parametrized Fr-Pu with up to seven references and added Am-Lr. Default of DFTD3, verified against s-dftd3.

The two sets are identical for Z <= 86 and stored once; the original Fr-Pu references are kept as patches. The 95-entry radius tables of the PhysNet code (rcov, r2r4) are single-precision values that the reference-code radii do not reproduce (seventh digit), so the legacy API keeps them verbatim as literals.

Units and cutoffs#

Public interfaces take Angstrom and return eV; internally atomic units with the CODATA-2018 factors of dispersion. The D3 cutoffs (default: the upstream 60 / 40 / 40 bohr for pairs / triples / CN) set the neighbor-list radius of D3Dispersion; for condensed-phase MLIP training shorter cutoffs with a switching window are the sensible choice, the defaults reproduce s-dftd3 exactly.

Module Attributes

REFERENCE_SETS

"2010" (Grimme's original, Z <= 94, PhysNet / original D3 codes) and "2024" (current reference code, simple-dftd3 >= 1.1.0, actinides re-parametrized and extended to Lr).

d3_c6ab

Grimme's original C6 reference systems (PhysNet layout), (Zi, Zj, ref_i, ref_j) -> (C6, CN_i, CN_j), shape (95, 95, 5, 5, 3)

d3_rcov

covalent radii in bohr, pre-scaled for coordination counting

d3_r2r4

element factors sqrt(Q) entering C8 = 3 C6 Q_i Q_j

PBE0_D3BJ

rational damping (2011, table 2) and zero damping (2010, table IV).

Functions

d3_options_from_extra(extra)

Pick the DFTD3 keyword arguments out of a config extra dict.

edisp(Z, r, idx_i, idx_j[, cutoff, s6, s8, ...])

Per-atom D3(BJ) dispersion energy, PhysNet's force-shifted variant.

legacy_c6_table([references, max_z])

C6 reference systems in the layout of the PhysNet TensorFlow code.

reference_tables([references])

Reference-system tables of one reference set (fresh copies).

Classes

D3Dispersion([model])

DFT-D3 dispersion as an xnn potential, standalone or wrapped around a model.

DFTD3([damping, s6, s8, s9, a1, a2, rs6, ...])

The D3 dispersion model as a TorchScript-compatible energy evaluator.