ParticleSystem interface

The mapped function

The purpose of CellListMap is to compute a pairwise-dependent function for all pairs of particles that are closer to each other than a defined cutoff. This pairwise function must be implemented by the user and adhere to the following interface:

function f(pair, output)
    (; i, j, x, y, d2, d) = pair
    # update output variable using above pair data
    return output
end

where pair is a NeighborPair object, containing fields i, j, x, y, d2 and d, which here we extract from the object using destructuring syntax.

x and y are the positions of the particles, already wrapped relative to each other according to the periodic boundary conditions (a minimum-image set of positions), i and j are the indexes of the particles in the arrays of coordinates, d2 is the squared distance between the particles, d is the distance, and output is the variable to be computed.

Basic examples

For example, computing the energy, as the sum of the inverse of the distance between particles, can be done with a function like:

function energy(pair, u)
    u += 1 / pair.d
    return u
end

and this function is passed directly to pairwise!:

u = pairwise!(energy, system)

(what system is will be explained in the examples below). Note that the energy function only uses pair.d (the distance), but all other fields (pair.x, pair.y, pair.i, pair.j, pair.d2) are available.

Alternatively, the function might require additional parameters, such as the masses of the particles. In this case, we can use a closure to provide such data:

function energy(pair, u, masses)
    (; i, j, d)  = pair 
    u += masses[i]*masses[j] / d
    return u
end
const masses = # ... some masses
u = pairwise!((pair, u) -> energy(pair, u, masses), system)

Here we reinforce the fact that the energy functions defined above compute the contribution to the energy of the interaction of a single pair of particles. This function will be called for every pair of particles within the cutoff, automatically, in the pairwise! call.

The ParticleSystem constructor

The ParticleSystem constructor receives the properties of the system and sets up automatically the most commonly used data structures necessary.

The ParticleSystemPositions type

The positions stored in a ParticleSystem (accessible via system.xpositions and, for two-set systems, system.ypositions) are of type ParticleSystemPositions{N,T}. This is a wrapper around a Vector{SVector{N,T}} that carries an internal updated flag. When coordinates are mutated through the supported interface, the flag is set automatically, so that cell lists are recomputed on the next call to pairwise!.

A ParticleSystemPositions can be constructed from a vector of vectors (e.g. Vector{Vector{Float64}}), but typically this construction occurs only internal on the call to ParticleSystem. The mutation interface is important when the user wants to vary the coordinates of the system. Mutation must strictly follow the available API methods, otherwise subsequent computations might be wrong because they can be based on outdated cell lists.

Mutating interface

The following functions mutate the positions and flag the array as updated, triggering recomputation of the cell lists on the next pairwise! call:

Read-only interface