PMECalculator

class torchpme.PMECalculator(potential: Potential, mesh_spacing: float, interpolation_nodes: int = 4, full_neighbor_list: bool = False, prefactor: float = 1.0)

Potential using a particle mesh-based Ewald (PME).

Scaling as \(\mathcal{O}(NlogN)\) with respect to the number of particles \(N\) used as a reference to test faster implementations.

For getting reasonable values for the smaring of the potential class and the mesh_spacing based on a given accuracy for a specific structure you should use torchpme.tuning.tune_pme(). This function will also find the optimal cutoff for the neighborlist.

Hint

For a training exercise it is recommended only run a tuning procedure with torchpme.tuning.tune_pme() for the largest system in your dataset.

Parameters:

• potential (Potential) – A torchpme.potentials.Potential object that implements the evaluation of short and long-range potential terms. The smearing parameter of the potential determines the split between real and k-space regions. For a torchpme.CoulombPotential it corresponds to the smearing of the atom-centered Gaussian used to split the Coulomb potential into the short- and long-range parts. A reasonable value for most systems is to set it to 1/5 times the neighbor list cutoff.

• mesh_spacing (float) – Value that determines the umber of Fourier-space grid points that will be used along each axis. If set to None, it will automatically be set to half of smearing.

• interpolation_nodes (int) – The number n of nodes used in the interpolation per coordinate axis. The total number of interpolation nodes in 3D will be n^3. In general, for n nodes, the interpolation will be performed by piecewise polynomials of degree n - 1 (e.g. n = 4 for cubic interpolation). Only the values 3, 4, 5, 6, 7 are supported.

• full_neighbor_list (bool) – If set to True, a “full” neighbor list is expected as input. This means that each atom pair appears twice. If set to False, a “half” neighbor list is expected.

• prefactor (float) – electrostatics prefactor; see Prefactors for details and common values.

forward(charges: Tensor, cell: Tensor, positions: Tensor, neighbor_indices: Tensor, neighbor_distances: Tensor, periodic: Tensor | None = None, node_mask: Tensor | None = None, pair_mask: Tensor | None = None, kvectors: Tensor | None = None)

Compute the potential “energy”.

It is calculated as

\[V_i = \frac{1}{2} \sum_{j} q_j\,v(r_{ij})\]

where \(v(r)\) is the pair potential defined by the potential parameter and \(q_j\) are atomic “charges” (corresponding to the electrostatic charge when using a Coulomb potential).

If the smearing of the potential is not set, the calculator evaluates only the real-space part of the potential. Otherwise, provided that the calculator implements a _compute_kspace method, it will also evaluate the long-range part using a Fourier-domain method.

Parameters:

• charges (Tensor) – torch.tensor of shape (n_channels, len(positions)) containaing the atomic (pseudo-)charges. n_channels is the number of charge channels the potential should be calculated. For a standard potential n_channels = 1. If more than one “channel” is provided multiple potentials for the same position are computed depending on the charges and the potentials.

• cell (Tensor) – torch.tensor of shape (3, 3), where cell[i] is the i-th basis vector of the unit cell

• positions (Tensor) – torch.tensor of shape (N, 3) containing the Cartesian coordinates of the N particles within the supercell.

• neighbor_indices (Tensor) – torch.tensor with the i,j indices of neighbors for which the potential should be computed in real space.

• neighbor_distances (Tensor) – torch.tensor with the pair distances of the neighbors for which the potential should be computed in real space.

• periodic (Tensor | None) – optional torch.tensor of shape (3,) indicating which directions are periodic (True) and which are not (False). If not provided, full periodicity is assumed.

• node_mask (Tensor | None) – Optional torch.tensor of shape (len(positions),) that indicates which of the atoms are masked.

• pair_mask (Tensor | None) – Optional torch.tensor containing a mask to be applied to the result.

• kvectors (Tensor | None) – Optional precomputed k-vectors to be used in the Fourier space part of the calculation.