# neigh_modify command

# neigh_settings command

## Syntax

    neigh_modify keyword values ...

- one or more keyword/value pairs may be listed

    keyword = delay or every or check or once or include or exclude or page or one or binsize
      delay value = N
        N = delay building until this many steps since last build
      every value = M
        M = build neighbor list every this many steps
      check value = yes or no
        yes = only build if some atom has moved half the skin distance or more
        no = always build on 1st step that every and delay are satisfied
      once
        yes = only build neighbor list once at start of run and never rebuild
        no = rebuild neighbor list according to other settings
      include value = group-ID
        group-ID = only build pair neighbor lists for atoms in this group
      exclude values:
        type M N
          M,N = exclude if one atom in pair is type M, other is type N
        group group1-ID group2-ID
          group1-ID,group2-ID = exclude if one atom is in 1st group, other in 2nd
        molecule group-ID
          groupname = exclude if both atoms are in the same molecule and in the same group
        none
          delete all exclude settings
      page value = N
        N = number of pairs stored in a single neighbor page
      one value = N
        N = max number of neighbors of one atom
      contact_distance_factor value = N
        N = contact distance factor used to extend the range of granular neighbor lists (must be > 1).
      binsize value = size
        size = bin size for neighbor list construction (distance units)

    neigh_settings binsize_value

- binsize_value = bin size for neighbor list constrution (distance units)

## Examples

    neigh_modify every 2 delay 10 check yes page 100000
    neigh_modify exclude type 2 3
    neigh_modify exclude group frozen frozen check no
    neigh_modify exclude group residue1 chain3
    neigh_modify exclude molecule rigid
    neigh_modify delay 0 contact_distance_factor 1.5
    neigh_settings
    neigh_settings 0.1

## Description

These commands set parameters that affect the building and use of pairwise neighbor lists. The “neigh_settings” command is a wrapper of “neigh_modify” that sets delay*=0. Its only, optional, parameter will be interpreted as the *binsize value (see below).

The every, delay, check, and once options affect how often lists are built as a simulation runs. The delay setting means never build a new list until at least N steps after the previous build. The every setting means build the list every M steps (after the delay has passed). If the check setting is no, the list is built on the 1st step that satisfies the delay and every settings. If the check setting is yes, then the list is only built on a particular step if some atom has moved more than half the skin distance (specified in the neighbor command) since the last build. If the once setting is yes, then the neighbor list is only built once at the beginning of each run, and never rebuilt. This should only be done if you are certain atoms will not move far enough that the list should be rebuilt. E.g. running a simulation of a cold crystal. Note that it is not that expensive to check if neighbor lists should be rebuilt.

When the rRESPA integrator is used (see the run_style command), the every and delay parameters refer to the longest (outermost) timestep.

The contact_distance_factor setting can be used to increase the range of granular neighbor lists. When contact_distance_factor > 1.0, instead of the standard criterion ri+rj+skin < distance, LIGGGHTS(R)-PUBLIC is checking for contact_distance_factor *(ri+rj)+skin < distance to decided if a pair of granular particles goes into a neighbor list.

The include option limits the building of pairwise neighbor lists to atoms in the specified group. This can be useful for models where a large portion of the simulation is particles that do not interact with other particles or with each other via pairwise interactions. The group specified with this option must also be specified via the atom_modify first command.

The exclude option turns off pairwise interactions between certain pairs of atoms, 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 atoms to effectively create a crack.
- When a large collection of atoms is treated as frozen, interactions between those atoms 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 type option turns off the pairwise interaction if one atom is of type M and the other of type N. M can equal N. The exclude group option turns off the interaction if one atom is in the first group and the other is the second. Group1-ID can equal group2-ID. The exclude molecule option turns off the interaction if both atoms are in the specified group and in the same molecule, as determined by their molecule ID.

Each of the exclude options can be specified multiple times. The exclude type 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 options are more expensive if specified multiple times; they require one check for each time they have been specified.

Note that the exclude options only affect pairwise interactions; see the delete_bonds command for information on turning off bond interactions.

The page and one options affect how memory is allocated for the neighbor lists. For most simulations the default settings for these options are fine, but if a very large problem is being run or a very long cutoff is being used, these parameters can be tuned. The indices of neighboring atoms are stored in “pages”, which are allocated one after another as they fill up. The size of each page is set by the page value. A new page is allocated when the next atom’s neighbors could potentially overflow the list. This threshold is set by the one value which tells LIGGGHTS(R)-PUBLIC the maximum number of neighbor’s one atom can have.

Warning

LIGGGHTS(R)-PUBLIC can crash without an error message if the number of neighbors for a single particle is larger than the page setting, which means it is much, much larger than the one setting. This is because LIGGGHTS(R)-PUBLIC doesn’t error check these limits for every pairwise interaction (too costly), but only after all the particle’s neighbors have been found. This problem usually means something is very wrong with the way you’ve setup your problem (particle spacing, cutoff length, neighbor skin distance, etc). If you really expect that many neighbors per particle, then boost the one and page settings accordingly.

The binsize option allows you to specify what size of bins will be used in neighbor list construction to sort and find neighboring atoms. By default, for neighbor style bin, LIGGGHTS(R)-PUBLIC uses bins that are 1/2 the size of the maximum pair cutoff. For neighbor style multi, 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 atoms are checked. If you make it too small, the optimal number of atoms is checked, but bin overhead goes up. If you set the binsize to 0.0, LIGGGHTS(R)-PUBLIC will use the default binsize of 1/2 the cutoff.

## Restrictions

If the “delay” setting is non-zero, then it must be a multiple of the “every” setting.

The exclude molecule option can only be used with atom styles that define molecule IDs.

The value of the page setting must be at least 10x larger than the one setting. This insures neighbor pages are not mostly empty space.

## Related commands

neighbor, delete_bonds

## Default

The option defaults are delay = 10, every = 1, check = yes, once = no, include = all, exclude = none, page = 100000, one = 2000, and binsize = 0.0.