xnn.common.models.d3.DFTD3#

class xnn.common.models.d3.DFTD3(damping='bj', s6=1.0, s8=None, s9=0.0, a1=0.4145, a2=4.8593, rs6=1.287, rs8=1.0, alp=14.0, bet=0.0, cutoff_pair=31.750632654269545, cutoff_triple=21.167088436179696, cutoff_cn=21.167088436179696, switch_width_pair=0.0, switch_width_triple=0.0, trainable=False, references='2024')[source]#

Bases: Module

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

Holds the damping parameters, the model constants and the reference data and evaluates the geometry-dependent dispersion energy of one or several structures from positions, atomic numbers and a neighbor list. Positions are in Angstrom, energies in eV; coordination numbers and C6 coefficients (hartree bohr^6) are reported in atomic units.

Parameters:

  • damping (str, optional) – "bj" (rational, the 2011 default and this class’s), "zero" (the 2010 form), "mzero" or "op".

  • s6 (float, optional) – Scaling of the C6, C8 and C9 terms; by default 1, the PBE0 value of the chosen damping (1.2177 for BJ, 0.928 for zero) and 0 (no three-body term, as upstream).

  • s8 (float, optional) – Scaling of the C6, C8 and C9 terms; by default 1, the PBE0 value of the chosen damping (1.2177 for BJ, 0.928 for zero) and 0 (no three-body term, as upstream).

  • s9 (float, optional) – Scaling of the C6, C8 and C9 terms; by default 1, the PBE0 value of the chosen damping (1.2177 for BJ, 0.928 for zero) and 0 (no three-body term, as upstream).

  • a1 (float, optional) – Rational-damping radii parameters (PBE0: 0.4145, 4.8593 bohr); used by "bj" and "op".

  • a2 (float, optional) – Rational-damping radii parameters (PBE0: 0.4145, 4.8593 bohr); used by "bj" and "op".

  • rs6 (float, optional) – Zero-damping radii scalings (PBE0: 1.287, 1.0); used by "zero" and "mzero".

  • rs8 (float, optional) – Zero-damping radii scalings (PBE0: 1.287, 1.0); used by "zero" and "mzero".

  • alp (float, optional) – Zero-damping steepness alpha_6 (14; alpha_8 = alp + 2), also setting the ATM exponent.

  • bet (float, optional) – The extra parameter of "mzero" (shift) and "op" (power), 0.

  • cutoff_pair (float, optional) – Real-space cutoffs in Angstrom of the two-body sum, the three-body sum and the coordination number; by default upstream’s 60, 40 and 40 bohr.

  • cutoff_triple (float, optional) – Real-space cutoffs in Angstrom of the two-body sum, the three-body sum and the coordination number; by default upstream’s 60, 40 and 40 bohr.

  • cutoff_cn (float, optional) – Real-space cutoffs in Angstrom of the two-body sum, the three-body sum and the coordination number; by default upstream’s 60, 40 and 40 bohr.

  • switch_width_pair (float, optional) – Widths (Angstrom) of quintic switching windows at the pair / triple cutoffs, by default 0 (sharp, as upstream).

  • switch_width_triple (float, optional) – Widths (Angstrom) of quintic switching windows at the pair / triple cutoffs, by default 0 (sharp, as upstream).

  • trainable (bool, optional) – Make s6, s8, s9, a1, a2, rs6, rs8, bet learnable parameters, by default False.

  • references (str, optional) – Set of reference systems: "2024" (default, the current reference code: Fr-Pu re-parametrized with up to seven references, Am-Lr added) or "2010" (Grimme’s original references, Z <= 94, the tables of the original D3 codes and of PhysNet). Identical for Z <= 86.

Variables:

  • cutoff (float) – The largest of the cutoffs (Angstrom), the neighbor-list radius.

  • n_features (int) – Width of the per-atom descriptors evaluate reports as "node_features" (the coordination number and the homoatomic C6).

  • references (str) – The selected set of reference systems.

coordination_numbers(z, edge_index, r, n_atoms)[source]#

Exponential-count coordination numbers (2010 paper eq 15), (N,).

Uses the edges within cutoff_cn; r in bohr.

Parameters:
Return type:

Tensor

reference_weights(z, cn)[source]#

Gaussian CN weights of the reference systems (eq 16), (N, 7).

Parameters:
Return type:

Tensor

pair_c6(z, weights, species_vectors, idx_i, idx_j)[source]#

C6 of the pairs (idx_i, idx_j) (eq 16), (E,).

Parameters:
Return type:

Tensor

c6_matrix(z, weights, species_vectors)[source]#

Dense pair C6 matrix, (N, N) in hartree bohr^6.

Parameters:
Return type:

Tensor

pair_radius(zi, zj)[source]#

Critical radius R_0^AB of the two-body damping, bohr, (E,).

Rational and optimized-power damping build it from the C8/C6 ratio (2011 eq 7), zero and modified-zero damping use the tabulated pair cutoff radii (2010 sec II.D).

Parameters:
Return type:

Tensor

two_body_energy(z, edge_index, r, c6, n_atoms)[source]#

Per-atom two-body energy in hartree for the selected damping.

Every directed edge contributes half of its pair energy to its center, so the sum over atoms is the sum over unordered pairs.

Parameters:
Return type:

Tensor

evaluate(atomic_numbers, pos, edge_index, edge_vec, batch, num_graphs, cell, pbc, total_charge)[source]#

Dispersion energy and D3 properties of a batch of structures.

The TorchScript-compatible core shared by DispersionCorrection and the deploy wrappers; the signature matches evaluate() (D3 has no charge dependence, so cell, pbc and total_charge are accepted and ignored – periodicity enters through the edge list). Inputs in Angstrom; the neighbor list must reach cutoff.

Returns:

"node_energy" (N,) in eV, "energy_2body" / "energy_3body" (B,) in eV, "coordination_numbers" (N,), "c6_matrix" (N, N) in hartree bohr^6 (empty for more than 20000 atoms) and "node_features" (N, 2) (the CN and the homoatomic C6).

Return type:

dict of str to Tensor

Parameters:
forward(data)[source]#

Evaluate a (batched) AtomicGraph.

Adds "energy" (B,) to the keys of evaluate().

Return type:

Dict[str, Tensor]