mlipops.Pairwise#

class mlipops.Pairwise(computation: Callable, cutoff: float | None, exclusions: Tensor | None = None)#

Computes pairwise interactions between particles.

This class can be used to implement arbitrary interactions of the form

\[E = \sum_{i,j} f(r_{ij}, P_ij)\]

where f is a function you provide, \(r_{ij}\) is the vector between particles i and j, and \(P_ij\) is an arbitrary set of parameters that may depend on i and j. To use it, first define a function to compute the interaction. For example,

>>> def coulomb(pairs, r, delta, params):
>>>     return params[pairs[:,0]]*params[pairs[:,1]]/r

The function should take four arguments. pairs is a Tensor of shape (n_pairs, 2), with each row containing the indices of two interacting particles. Typically it is computed by a NeighborList. r is a Tensor of shape (n_pairs,) containing the distance between each pair of interacting particles. deltas is a Tensor of shape (npairs, 3) containing the displacement vector from the first to the second particle in each pair. params is an arbitrary object containing additional parameters on which the interaction can depend. In the above example, it should be a Tensor of shape (n_particles,) containing the charge on each particle.

Next create a Pairwise object, passing your function to the constructor.

>>> pairwise = Pairwise(coulomb)

And finally evaluate it, passing in the particle positions, parameters, pairs, and periodic box vectors.

>>> energy = pairwise(positions, params, pairs, box_vectors)

When creating a Pairwise object, you can optionally specify a cutoff distance. Pairs of particles that are further apart than the cutoff are ignored. This is useful when using a NeighborList with padding, so some of the returned pairs are beyond the cutoff. You also can specify a list of specific particle pairs whose interaction should always be excluded, regardless of their distance.

__init__(computation: Callable, cutoff: float | None, exclusions: Tensor | None = None)#

Create an object for computing pairwise interactions.

Parameters:

  • computation (Callable) – a callable object that defines how the interaction is computed

  • cutoff (float | None) – if specified, any pair whose distance is greater than the cutoff will be omitted

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

forward(positions: Tensor, parameters: Any, pairs: Tensor, box_vectors: 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

  • parameters (Any) – an arbitrary object containing parameter values. It is passed to the computation function.

  • pairs (torch.Tensor) – a Tensor of shape (n_pairs, 2). Each row contains the indices of two particles that interact. Typically it is created by a NeighborList.

  • 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