Stencil

class hoomd.md.nlist.Stencil(cell_width, buffer, exclusions=('bond',), rebuild_check_delay=1, check_dist=True, deterministic=False, mesh=None, default_r_cut=0.0)

Bases: NeighborList

Cell list based neighbor list using stencils.

Parameters:

  • cell_width (float) – The underlying stencil bin width for the cell list \([\mathrm{length}]\).

  • buffer (float) – Buffer width \([\mathrm{length}]\).

  • exclusions (tuple[str]) – Defines which particles to exclude from the neighbor list, see more details in NeighborList.

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

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

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

  • mesh (Mesh) – When a mesh object is passed, the neighbor list uses the mesh to determine the bond exclusions in addition to all other set exclusions.

Stencil finds neighboring particles using a fixed width cell list, for O(kN) construction of the neighbor list where k is the number of particles per cell. In contrast with Cell, Stencil allows the user to choose the cell width: cell_width instead of fixing it to the largest cutoff radius (P.J. in’t Veld et al. 2008):

Stenciled cell list schematic

This neighbor list style differs from Cell in how the adjacent cells are searched for particles. One stencil is computed per particle type based on the value of cell_width set by the user, which defines the bins that the particle must search in. Distances to the bins in the stencil are precomputed so that certain particles can be quickly excluded from the neighbor list, leading to improved performance compared to Cell when there is size disparity in the cutoff radius. The memory demands of Stencil can also be lower than Cell if your system is large and has many small cells in it; however, Tree is usually a better choice for these systems.

The performance of Stencil depends strongly on the choice of cell_width. The best performance is obtained when the cutoff radii are multiples of the cell_width, and when the cell_width covers the simulation box with a roughly integer number of cells.

Examples:

nl_s = nlist.Stencil(cell_width=1.5)

Important

M.P. Howard et al. 2016 describes this neighbor list implementation. Cite it if you utilize Stencil in your research.

Members inherited from AutotunedObject:

property kernel_parameters

Kernel parameters. Read more...

property is_tuning_complete

Check if kernel parameter tuning is complete. Read more...

tune_kernel_parameters()

Start tuning kernel parameters. Read more...

Members inherited from NeighborList:

buffer

Buffer width. Read more...

check_dist

Flag to enable / disable distance checking. Read more...

exclusions

Defines which particles to exclude from the neighbor list. Read more...

mesh

Associated mesh data structure. Read more...

rebuild_check_delay

How often to attempt to rebuild the neighbor list. Read more...

r_cut

Base cutoff radius for neighbor list queries. Read more...

property cpu_local_nlist_arrays

Local nlist arrays on the CPU. Read more...

property gpu_local_nlist_arrays

Local nlist arrays on the GPU. Read more...

property local_pair_list

Local pair list. Read more...

property num_builds

The number of neighbor list builds. Read more...

property pair_list

Global pair list. Read more...

property shortest_rebuild

The shortest period between neighbor list rebuilds. Read more...

Members defined in Stencil:

cell_width

The underlying stencil bin width for the cell list \([\mathrm{length}]\).

Type:

float

deterministic

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

Type:

bool