xnn.common.models.electrostatics

Point-charge electrostatics shared by the charge-predicting models.

Per-atom Coulomb energies of partial charges, in eV for charges in units of e and distances in Angstrom, in the forms the models need:

• coulomb_direct(): the plain 1/r sum over every pair of a molecular structure (no cutoff; the pairs come from all_pairs());

• coulomb_dsf(): the damped shifted-force truncation of Fennell and Gezelter (J. Chem. Phys. 124, 234104, 2006) over a neighbor list, which gives a continuous energy and force at a finite cutoff and so serves periodic structures (images in the neighbor list) and large molecules;

• coulomb_ewald(): the Ewald sum of a periodic structure, the erfc-screened real-space part over the neighbor list plus the reciprocal sum over the lattice vectors within a spherical cutoff (reciprocal_lattice()), with the self and neutralizing-background corrections;

• coulomb_pme(): the same with the reciprocal part on a charge mesh (smooth particle-mesh Ewald, pme).

The Ewald parameters come from ewald_parameters(): for a real-space cutoff r_c and a target relative accuracy eps the splitting parameter is alpha = sqrt(-ln eps) / r_c (the screened pair term is eps of its bare value at the cutoff) and the reciprocal cutoff k_c = 2 alpha sqrt(-ln eps) (the Gaussian factor of the reciprocal sum is eps at k_c), the balance of Kolafa and Perram that the reference AIMNet2 calculator and nvalchemiops use as well; xnn fixes r_c to the model’s neighbor-list radius instead of choosing it per structure, so the graph the data pipeline builds is the one the sum needs.

Every function returns the energy as a per-atom share (half of every pair term on each of its atoms, the reciprocal energy as q_i phi_i / 2) so the callers’ node_energy stays additive, and accumulates the pair and reciprocal sums in float64 whatever the dtype of the charges. Used by AIMNet2; the all-pairs enumeration also by BAMBOO, the reciprocal lattice also by the periodic EEQ charges of D4 (eeq).

Module Attributes

COULOMB_CONSTANT	Coulomb constant k_e e^2 in eV Angstrom (one hartree times one bohr).
RECIPROCAL_BUDGET	Largest (N, N_k) phase table of the reciprocal sum formed at once (float64: 1.6 GB); longer lattice sums run in blocks of vectors.

Functions

all_pairs(batch)	All ordered intra-structure atom pairs (i, j), i != j.
coulomb_direct(charges, pos, batch[, k_e])	Per-atom share of the all-pairs Coulomb energy of molecular structures.
coulomb_dsf(charges, edge_index, r, alpha, ...)	Per-atom share of the damped shifted-force Coulomb energy over a neighbor list.
coulomb_ewald(charges, pos, cell, ...[, k_e])	Per-atom Ewald Coulomb energies of one periodic structure, in eV.
coulomb_pme(charges, pos, cell, edge_index, ...)	Per-atom particle-mesh Ewald Coulomb energies of one periodic structure, in eV.
ewald_corrections(charges, alpha, volume)	Self and neutralizing-background terms per atom, float64.
ewald_mesh_sizes(cell, alpha, accuracy)	The PME mesh coulomb_pme() uses for a cell (for reporting and tests).
ewald_parameters(cutoff, accuracy)	Splitting parameter and reciprocal cutoff for a real-space cutoff and an accuracy.
ewald_real(charges, edge_index, r, alpha, cutoff)	Per-atom share of the screened real-space sum sum q_i q_j erfc(alpha r) / r.
ewald_reciprocal(charges, pos, cell, alpha, ...)	Per-atom reciprocal-space energies q_i phi_i / 2 of one periodic structure.
reciprocal_lattice(cell, k_cutoff)	The reciprocal lattice vectors k != 0 with |k| <= k_cutoff.