md.nlist

Overview

md.nlist.NList

Base class neighbor list.

md.nlist.Cell

Cell list based neighbor list

Details

Neighbor list acceleration structures.

Pair forces (hoomd.md.pair) use neighbor list data structures to perform efficient calculations. HOOMD-blue provides a several types of neighbor list construction algorithms that you can select from. Multiple pair force objects can share a 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.

class hoomd.md.nlist.Cell(buffer=0.4, exclusions='bond', rebuild_check_delay=1, diameter_shift=False, check_dist=True, max_diameter=1.0, deterministic=False)

Cell list based neighbor list

Parameters
  • buffer (float) – Buffer width.

  • check_dist (bool) – Flag to enable / disable distance checking.

  • deterministic (bool) – When True, sort neighbors to help provide deterministic simulation runs.

  • diameter_shift (bool) – Flag to enable / disable diameter shifting.

  • exclusions (tuple[str]) – Excludes pairs from the neighbor list, which excludes them from the pair potential calculation.

  • max_diameter (float) – The maximum diameter a particle will achieve.

  • rebuild_check_delay (int) – How often to attempt to rebuild the neighbor list.

Cell finds neighboring particles using a fixed width cell list, allowing for O(kN) construction of the neighbor list where k is the number of particles per cell. Cells are sized to the largest \(r_\mathrm{cut}\). This method is very efficient for systems with nearly monodisperse cutoffs, but performance degrades for large cutoff radius asymmetries due to the significantly increased number of particles per cell.

Examples:

cell = nlist.Cell()
lj = md.pair.LJ(nlist=cell)
deterministic

When True, sort neighbors to help provide deterministic simulation runs.

Type

bool

class hoomd.md.nlist.NList(buffer, exclusions, rebuild_check_delay, diameter_shift, check_dist, max_diameter)

Base class neighbor list.

Methods and attributes provided by this base class are available to all subclasses.

Attention

Users should instantiate the subclasses, using NList directly will result in an error.

Buffer distance

Set the 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 check_dist is True, NList starts checking how far particles have moved rebuild_check_delay time steps after the last build and performs a rebuild when any particle has moved a distance buffer/2. When check_dist is False, NList always rebuilds after rebuild_check_delay time steps.

Exclusions

Neighbor lists nominally include all particles within the specified cutoff distances. The exclusions attribute defines which particles will be excluded from the list, even if they are within the cutoff. exclusions is a tuple of strings that enable one more more types of exclusions. The valid exclusion types are:

  • bond: Exclude particles that are directly bonded together.

  • angle: Exclude the first and third particles in each angle.

  • 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.

  • body: Exclude particles that belong to the same rigid body.

  • 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).

Diameter shifting

Set diameter_shift to True when using hoomd.md.pair.SLJ or hoomd.md.pair.DLVO so that the neighbor list includes all particles that interact under the modified \(r_\mathrm{cut}\) conditions in those potentials. When diameter_shift is True, set max_diameter to the largest value that any particle’s diameter will achieve (where diameter is the per particle quantity stored in the hoomd.State).

buffer

Buffer width.

Type

float

check_dist

Flag to enable / disable distance checking.

Type

bool

diameter_shift

Flag to enable / disable diameter shifting.

Type

bool

exclusions

Excludes pairs from the neighbor list, which excludes them from the pair potential calculation.

Type

tuple[str]

max_diameter

The maximum diameter a particle will achieve.

Type

float

rebuild_check_delay

How often to attempt to rebuild the neighbor list.

Type

int

property shortest_rebuild

The shortest period between neighbor list rebuilds.

shortest_rebuild is the smallest number of time steps between neighbor list rebuilds during the previous Simulation.run.

Type

int