Potential¶

class torchpme.potentials.Potential(smearing: float | None = None, exclusion_radius: float | None = None, dtype: dtype | None = None, device: device | None = None)[source]¶

Base class defining the interface for a pair potential energy function

The class provides the interface to compute a short-range and long-range functions in real space (such that \(V(r)=V_{\mathrm{SR}}(r)+V_{\mathrm{LR}}(r)\) ), as well as a reciprocal-space version of the long-range component \(\hat{V}_{\mathrm{LR}}(k))\) ).

Derived classes can decide to implement a subset of these functionalities (e.g. providing only the real-space potential \(V(r)\)). Internal state variables and parameters in derived classes should be defined in the __init__ method.

This base class also provides parameters to set the length scale associated with the range separation (smearing), and a cutoff function that can be optionally set to zero out the potential inside a short-range exclusion_radius. This is often useful when combining torch-pme-based ML models with local models that are better suited to describe the structure within a local cutoff.

Note that a Potential class can also be used inside a KSpaceFilter, see Potential.kernel_from_k_sq().

Parameters:

smearing (float | None) – The length scale associated with the switching between \(V_{\mathrm{SR}}(r)\) and \(V_{\mathrm{LR}}(r)\)
exclusion_radius (float | None) – A length scale that defines a local environment within which the potential should be smoothly zeroed out, as it will be described by a separate model.
dtype (dtype | None) – type used for the internal buffers and parameters
device (device | None) – device used for the internal buffers and parameters

f_cutoff(dist: Tensor) → Tensor[source]¶

Default cutoff function defining the local region that should be excluded from the computation of a long-range model. Defaults to a shifted cosine \((1+\cos \pi r/r_\mathrm{cut})/2\).

Parameters:: dist (Tensor) – a torc.Tensor containing the interatomic distances over which the cutoff function should be computed.
Return type:: Tensor

from_dist(dist: Tensor) → Tensor[source]¶

Computes a pair potential given a tensor of interatomic distances.

Parameters:: dist (Tensor) – torch.Tensor containing the distances at which the potential is to be evaluated.
Return type:: Tensor

sr_from_dist(dist: Tensor) → Tensor[source]¶

Short-range part of the pair potential in real space.

Even though one can provide a custom version, this is usually evaluated as \(V_{\mathrm{SR}}(r)=V(r)-V_{\mathrm{LR}}(r)\), based on the full and long-range parts of the potential. If the parameter exclusion_radius is defined, it computes this part as \(V_{\mathrm{SR}}(r)=-V_{\mathrm{LR}}(r)*f_\mathrm{cut}(r)\) so that, when added to the part of the potential computed in the Fourier domain, the potential within the local region goes smoothly to zero.

Parameters:: dist (Tensor) – torch.tensor containing the distances at which the potential is to be evaluated.
Return type:: Tensor

lr_from_dist(dist: Tensor) → Tensor[source]¶

Computes the long-range part of the pair potential \(V_\mathrm{LR}(r)\). in real space, given a tensor of interatomic distances.

Parameters:: dist (Tensor) – torch.tensor containing the distances at which the potential is to be evaluated.
Return type:: Tensor

lr_from_k_sq(k_sq: Tensor) → Tensor[source]¶

Computes the Fourier-domain version of the long-range part of the pair potential \(\hat{V}_\mathrm{LR}(k)\). The function is expressed in terms of \(k^2\), as that avoids, in several important cases, an unnecessary square root operation. :param k_sq: torch.tensor containing the squared norm of the Fourier domain vectors at which \(\hat{V}_\mathrm{LR}\) must be evaluated.

Parameters:: k_sq (Tensor)
Return type:: Tensor

kernel_from_k_sq(k_sq: Tensor) → Tensor[source]¶

Compatibility function with the interface of KSpaceKernel, so that potentials can be used as kernels for KSpaceFilter.

Parameters:: k_sq (Tensor)
Return type:: Tensor

self_contribution() → Tensor[source]¶

A correction that depends exclusively on the “charge” on every particle and on the range splitting parameter. Foe example, in the case of a Coulomb potential, this is the potential generated at the origin by the fictituous Gaussian charge density in order to split the potential into a SR and LR part.

Return type:: Tensor

background_correction() → Tensor[source]¶

A correction designed to compensate for the presence of divergent terms. For instance, the energy of a periodic electrostatic system is infinite when the cell is not charge-neutral. This term then implicitly assumes that a homogeneous background charge of the opposite sign is present to make the cell neutral.