nlist¶
Pair forces (hoomd.md.pair) use neighbor list data structures to find
neighboring particle pairs (those within a distance of \(r_\mathrm{cut}\))
efficiently. HOOMD-blue provides a several types of neighbor list construction
algorithms that you can select from: Cell, Tree, and Stencil.
Multiple pair force objects can share a single neighbor list, or use independent neighbor list objects. When neighbor lists are shared, they find neighbors within the the maximum \(r_{\mathrm{cut},i,j}\) over the associated pair potentials.
Buffer distance
Set the NeighborList.buffer distance to amortize the cost of the neighbor list
build. When buffer > 0, a neighbor list computed on one step can be reused
on subsequent steps until a particle moves a distance buffer/2. When
NeighborList.check_dist is True, NeighborList starts checking how far
particles have moved NeighborList.rebuild_check_delay time steps after the
last build and performs a rebuild when any particle has moved a distance
buffer/2. When NeighborList.check_dist is False, NeighborList always
rebuilds after NeighborList.rebuild_check_delay time steps.
Note
With the default settings (check_dist=True and
rebuild_check_delay=1), changing NeighborList.buffer only impacts
simulation performance and not correctness.
Set the buffer too small and the neighbor list will need to be updated
often, slowing simulation performance. Set the buffer too large, and
hoomd.md.pair.Pair will need to needlessly calculate many non-interacting
particle pairs and slow the simulation. There is an optimal value for
NeighborList.buffer between the two extremes that provides the best
performance.
Base distance cutoff
The NeighborList.r_cut attribute can be used to set the base cutoff distance
for neighbor list queries. The actual cutoff distance is always the maximum
\(r_{\mathrm{cut},i,j}\) of the base cutoff and associated pair potentials.
Note
This attribute is particularly useful for implementing custom pair forces in Python.
Attention
Users should only set this attribute when utilizing the accessor APIs,
pair_list,
local_pair_list,
cpu_local_nlist_arrays, or
gpu_local_nlist_arrays.
Exclusions
Neighbor lists nominally include all particles within the chosen cutoff
distances. The NeighborList.exclusions attribute defines which particles will
be excluded from the list, even if they are within the cutoff.
NeighborList.exclusions is a tuple of strings that enable one more more types
of exclusions. The valid exclusion types are:
'angle': Exclude the first and third particles in each angle.'body': Exclude particles that belong to the same rigid body.'bond': Exclude particles that are directly bonded together.'meshbond': Exclude particles that are bonded together via a mesh.'constraint': Exclude particles that have a distance constraint applied between them.'dihedral': Exclude the first and fourth particles in each dihedral.'special_pair': Exclude particles that are part of a special pair.'1-3': Exclude particles i and k whenever there is a bond (i,j) and a bond (j,k).'1-4': Exclude particles i and m whenever there are bonds (i,j), (j,k), and (k,m).
Classes