neighbor_list command

Purpose

Command for modifying the options of the neighbor list build algorithm.

Note

This command is supported by Aspherix GPU.

Warning

GPU support for this command has not been tested and may not work as expected.

Syntax

neighbor_list keyword values ...

arg = skin distance (bin units)
one or more keyword/value pairs may be listed

keyword = skin_size or type or bin_size or stencil_check or exclude or neighbor_optimization or skin_limit_factor or log_skin_and_binsize
 skin_size value = size
   size = skin distance
  type value = monodisperse_binning or polydisperse_binning
    monodisperse_binning = binning algorithm for monodisperse packings or packings with a narrow particle distribution
    polydisperse_binning = modified binning algorithm for systems with a wide range of cutoff distances
  bin_size value = size
    size = bin size for neighbor list construction (distance units)
  neighbor_optimization value = yes or no
    yes = automatically optimize bin_size and skin_size during the simulation
    no = disable automatic optimization (default)
  skin_limit_factor = factor
    factor = factor used to limit the skin_size during automatic optimization [default: 20]
  log_skin_and_binsize value = yes or no
    yes = write result of parameter optimization to log file
    no = disable log file writing (default)
  stencil_check value = yes or no
    yes = warning if more than 10 particles are in a stencil, error if there are more than 100 particles in a stencil
    no = disable this warning/error
  exclude values:
    material {material1, material2}
      material1, material2 = exclude if one particle is of 1st material, other of 2nd
    group {group1-ID, group2-ID}
      group1-ID, group2-ID = exclude if one particle is in 1st group, other in 2nd

Examples

neighbor_list skin_size 0.3
neighbor_list skin_size 1e-4 stencil_check no exclude material {filter_material, filter_material}
neighbor_list skin_size 1e-3 type polydisperse_binning
neighbor_list skin_size 1e-3 bin_size 1e-2
neighbor_list neighbor_optimization yes log_skin_and_binsize yes

Description

This command allows to set certain parameters of the neighbor list.

The skin_size parameter defines the skin distance, which is a parameter affecting the building of pairwise neighbor lists. All particle pairs within a neighbor cutoff distance equal to the their force cutoff plus the skin distance are stored in the list. Typically, the larger the skin distance, the less often neighbor lists need to be built, but more pairs must be checked for possible force interactions every timestep. The skin distance is also used to determine how often particles migrate to new processors if the check option of the neigh_modify command is set to yes. Particles are migrated (communicated) to new processors on the same timestep that neighbor lists are re-built. The user-specified skin value is scaled by the current coarsegraining factor (skin -> cg_factor*skin), cf. coarsegraining.

The type value selects what algorithm is used to build the list. The monodisperse_binning type creates the list by binning which is an operation that scales linearly with N/P, the number of particles per processor where N = total number of particles and P = number of processors.

The polydisperse_binning type is a modified binning algorithm that is useful for systems with a wide range of cutoff distances, e.g. due to different size particles. For the monodisperse_binning type, the bin size is set to 1/2 of the largest cutoff distance between any pair of particle types and a single set of bins is defined to search over for all particle types. This can be inefficient if one pair of types has a very long cutoff, but other type pairs have a much shorter cutoff. For type polydisperse_binning the bin size is set to 1/2 of the shortest cutoff distance and multiple sets of bins are defined to search over for different particle types. This imposes some extra setup overhead, but the searches themselves may be much faster for the short-cutoff cases. See the communicate multi command for a communication option option that may also be beneficial for simulations of this kind.

The binsize option allows you to specify what size of bins will be used in neighbor list construction to sort and find neighboring particles. By default, for type monodisperse_binning, Aspherix® uses bins that are 1/2 the size of the maximum pair cutoff. For type polydisperse_binning, the bins are 1/2 the size of the minimum pair cutoff. Typically these are good values values for minimizing the time for neighbor list construction. This setting overrides the default. If you make it too big, there is little overhead due to looping over bins, but more particles are checked. If you make it too small, the optimal number of particles is checked, but bin overhead goes up. If you set the binsize to 0.0, Aspherix® will use the default binsize of 1/2 the cutoff.

In order to avoid erroneous user inputs a check is performed whether stencils contain less than 10 particles. If stencils contain more particles significant performance losses can be expected, in this case a warning will be thrown once. In case over 100 particles are in a stencil an error is thrown. For expert users it is possible to circumvent these checks by using the keyword stencil_checks with a no value.

The exclude option turns off pairwise interactions between certain pairs of particles, by not including them in the neighbor list. These are sample scenarios where this is useful:

In crack simulations, pairwise interactions can be shut off between 2 slabs of particles to effectively create a crack.
When a large collection of particles is treated as frozen, interactions between those particles can be turned off to save needless computation. E.g. Using the fix setforce command to freeze a wall or portion of a bio-molecule.
When one or more rigid bodies are specified, interactions within each body can be turned off to save needless computation. See the fix rigid command for more details.

The exclude material option turns off the pairwise interaction if one particle is of material M and the other of material N. M can equal N. The exclude group option turns off the interaction if one particle is in the first group and the other is the second. Group1-ID can equal group2-ID.

Each of the exclude options can be specified multiple times. The exclude material option is the most efficient option to use; it requires only a single check, no matter how many times it has been specified. The other exclude option is more expensive if specified multiple times; it requires one check for each time it has been specified.

If neighbor_optimization is turned on the values for skin_size and bin_size are varied during the simulation to optimize the simulation for a lower run time. Note, if you specify either skin_size or bin_size the corresponding parameter will not be optimized, regardless of the value set for neighbor_optimization. The skin_limit_factor can be used to limit the automatically computed minimum and maximum allowed skin size values (to prevent divergence of this value which could cause very slow simulations). It will limit the skin size value within skin_init / skin_limit_factor and skin_init * skin_limit_factor, where skin_init is the value after the initial automatic skin size calculation. If one of theses thresholds is reached, a warning will be shown (added to the warnings_aspherix.txt output file).

If active, the neighbor_optimization will update bin and skin size (if these parameters are free) every ten neighbor list builds. Moreover, the paramter update will only be invoked, if the relative pair time exceeds 5% of the entire computional effort.

Note

This feature has been released in May 2021 and might not be fully optimized for all possible use cases. If you have one that does not optimize well, please inform the developers (support@dcs-computing.com).

If you wish to monitor the values chosen by the optimizer you can set log_skin_and_binsize to yes and the corresponding output will be written to the log file along with some further debug information for the developers.

Additional information

The neighbor list is created by binning, which is an operation that scales linearly with the number of particles per processor, $N/P$ , where $N$ is the total number of particles and $P$ is the number of processors. The neigh_modify command has additional options that control how often neighbor lists are built and which pairs are stored in the list. When a run is finished, counts of the number of neighbors stored in the pairwise list and the number of times the neighbor lists were built are printed to the screen and log file, see Interpret Aspherix® screen output for details.

Restrictions

none

Default

skin_size = chosen based on particle size, bin_size = chosen based on contact models and particle size, type = monodisperse_binning, neighbor_optimization = no, log_skin_and_binsize = no, stencil_check = yes, skin_limit_factor = 20