mlipops.CoulombEwald#

class mlipops.CoulombEwald(neighbor_list: NeighborList, exclusions: Tensor, kmaxx: int, kmaxy: int, kmaxz: int, alpha: float, prefactor: float, cutoff: float | None = None, max_multipole='charge')#

Compute Coulomb interactions using Ewald summation.

This class computes the energy of an infinite set of multipoles repeating periodically through space. The interaction is divided into a short range part, which is computed in direct space, and a long range part, which is computed in reciprocal space. The division between the two is set by a parameter alpha, which can be adjusted to minimize the total cost of computing both parts.

By default, the multipoles are simply point charges. You can also include dipoles by passing max_multipole=’dipole’ to the constructor. In that case, you must provide dipole moments along with charges when invoking the module.

You can optionally specify that certain interactions should be omitted when computing the energy. This is typically used for nearby atoms within the same molecule. When two atoms are listed as an exclusion, only the interaction of each with the same periodic copy of the other (that is, not applying periodic boundary conditions) is excluded. Each atom still interacts with all the periodic copies of the other.

Due to the way the reciprocal space term is calculated, it is impossible to prevent it from including excluded interactions. The direct space term therefore compensates for it, subtracting off the energy that was incorrectly included in reciprocal space. The sum of the two terms thus yields the correct energy with the interaction fully excluded.

In addition to calculating energy and forces, this class can compute the electric field at arbitrary points in space. To do this, call compute_field().

When you create an instance of this class, you must specify the value of Coulomb’s constant 1/(4*pi*eps0). Its value depends on the units used for energy and distance. The value you specify thus sets the unit system. See the User Guide for the values in common unit systems.

__init__(neighbor_list: NeighborList, exclusions: Tensor, kmaxx: int, kmaxy: int, kmaxz: int, alpha: float, prefactor: float, cutoff: float | None = None, max_multipole='charge')#

Create on object for computing Coulomb interactions.

Parameters:

  • neighbor_list (NeighborList) – the NeighborList used to identify direct space interactions. It determines the direct space cutoff distance, the device to run on, and whether padding is used to enable caching of neighbors.

  • exclusions (torch.Tensor) – a tensor of shape (n_exclusions, 2). Each row contains the indices of two particles whose interaction should be omitted.

  • kmaxx (int) – the index of the maximum wave vector in the x direction. All vectors between -kmaxx and kmaxx are included.

  • kmaxy (int) – the index of the maximum wave vector in the y direction. All vectors between -kmaxy and kmaxy are included.

  • kmaxz (int) – the index of the maximum wave vector in the z direction. All vectors between -kmaxz and kmaxz are included.

  • alpha (float) – the coefficient of the erf() function used to separate the energy into direct and reciprocal space terms

  • prefactor (float) – Coulomb’s constant 1/(4*pi*eps0). This sets the unit system.

  • cutoff (float | None) – the cutoff distance used when computing direct space interactions. If None, the NeighborList’s cutoff is used. This argument is useful when a single NeighborList is shared by multiple interactions that use different cutoffs. The value may never be greater than the NeighborList’s cutoff.

  • max_multipole (str) – the maximum multipole order for each particle. Allowed options are ‘charge’ (point charges only) and ‘dipole’ (charges and dipoles).

forward(positions: Tensor, charges: Tensor, box_vectors: Tensor, include_direct: bool = True, include_reciprocal: bool = True, dipoles: Tensor | None = None, batch: Tensor | None = None) → Tensor#

Compute the interaction.

Parameters:

  • positions (torch.Tensor) – a Tensor of shape (n_particles, 3) containing the Cartesian coordinates of each particle

  • charges – a Tensor of shape (n_particles,) containing the charge of each particle

  • box_vectors (torch.Tensor | None) – if batch is None, a Tensor of shape (3, 3) containing box vectors defining the periodic box. If batch is not None, a Tensor of shape (n_systems, 3, 3) containing the box vectors for each system. If None, periodic boundary conditions are not used.

  • include_direct (bool) – specifies whether the direct space term should be included in the result

  • include_reciprocal (bool) – specifies whether the reciprocal space term should be included in the result

  • dipoles (torch.Tensor | None) – a Tensor of shape (n_particles, 3) containing the dipole moment of each particle. If max_multipole is ‘charge’, this is ignored.

  • batch (torch.Tensor | None) – a Tensor of shape (n_particles,) containing the index of the system each particle belongs to. This must be sorted in ascending order, and every system must contain at least one particle. If None, the interaction is computed for a single system instead of a batch of systems.

Returns:

a torch.Tensor containing the energy of the interaction. If batch is None, this is a scalar containing the total energy. Otherwise, it has shape (n_systems,) containing the energy of each system in the batch.

Return type:

torch.Tensor

compute_field(field_positions: Tensor, positions: Tensor, charges: Tensor, box_vectors: Tensor, include_direct: bool = True, include_reciprocal: bool = True, dipoles: Tensor | None = None) → Tensor#

Compute the electric field produced by the particles at a set of points.

Parameters:

  • field_positions (torch.Tensor) – a Tensor of shape (n_points, 3) containing the positions at which to compute the field

  • positions (torch.Tensor) – a Tensor of shape (n_particles, 3) containing the Cartesian coordinates of each particle

  • charges – a Tensor of shape (n_particles,) containing the charge of each particle

  • box_vectors (torch.Tensor) – a Tensor of shape (3, 3) containing box vectors defining the periodic box.

  • include_direct (bool) – specifies whether the direct space term should be included in the result

  • include_reciprocal (bool) – specifies whether the reciprocal space term should be included in the result

  • dipoles (torch.Tensor | None) – a Tensor of shape (n_particles, 3) containing the dipole moment of each particle. If max_multipole is ‘charge’, this is ignored.

Returns:

a Tensor of shape (n_points, 3) containing the electric field at each of the points

Return type:

torch.Tensor