mlipops.CoulombRF#

class mlipops.CoulombRF(neighbor_list: NeighborList, exclusions: Tensor, prefactor: float, dielectric: float = 78.3, cutoff: float | None = None)#

Compute Coulomb interactions using the reaction field approximation.

This class computes the energy of a set of charges, either with or without periodic boundary conditions. Interactions beyond a cutoff distance are ignored, and the form of the potential is modified based on two assumptions: first, that everything beyond the cutoff is filled with bulk solvent, and second, that bulk solvent can be modeled as a uniform dielectric.

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.

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, prefactor: float, dielectric: float = 78.3, cutoff: float | None = None)#

Create on object for computing Coulomb interactions.

Parameters:

  • neighbor_list (NeighborList) – the NeighborList used to identify interactions. It determines the 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.

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

  • dielectric (float) – the dielectric constant to use for the solvent. The default value corresponds to water.

  • cutoff (float | None) – the cutoff distance used when computing 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.

forward(positions: Tensor, charges: Tensor, box_vectors: Tensor, 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.

  • 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) → 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. If None, periodic boundary conditions are not used.

Returns:

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

Return type:

torch.Tensor