\(\renewcommand{\AA}{\text{Å}}\)

neigh_modify command

Syntax

neigh_modify keyword values ...

• one or more keyword/value pairs may be listed

  keyword = delay or every or check or once or cluster or include or exclude or page or one or binsize or collection/type or collection/interval
    delay value = N
      N = delay building neighbor lists until this many steps since last build
    every value = M
      M = consider building neighbor lists every this many steps
    check value = yes or no
      yes = only build if at least one atom has moved half the skin distance or more
      no = always build on 1st step where every and delay are conditions are satisfied
    once value = yes or no
      yes = only build neighbor list once at start of run and never rebuild
      no = rebuild neighbor list according to other settings
    cluster value = yes or no
      yes = check bond,angle,etc neighbor list for nearby clusters
      no = do not check bond,angle,etc neighbor list for nearby clusters
    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 (M and N may be type labels)
      group group1-ID group2-ID
        group1-ID,group2-ID = exclude if one atom is in 1st group, other in 2nd
      molecule/intra group-ID
        group-ID = exclude if both atoms are in the same molecule and in group
      molecule/inter group-ID
        group-ID = exclude if both atoms are in different molecules and in 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
    binsize value = size
      size = bin size for neighbor list construction (distance units)
    collection/type values = N arg1 ... argN
      N = number of custom collections
      arg = N separate lists of types (see below)
    collection/interval values = N arg1 ... argN
      N = number of custom collections
      arg = N separate cutoffs for intervals (see below)

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/intra rigid
neigh_modify collection/type 2 1*2,5 3*4
neigh_modify collection/interval 2 1.0 10.0

Description

This command sets parameters that affect the building and use of pairwise neighbor lists. Depending on what pair interactions and other commands are defined, a simulation may require one or more neighbor lists.

The every, delay, check, and once options affect how often lists are built as a simulation runs. The delay setting means never build new lists until at least N steps after the previous build. The every setting means attempt to build lists every M steps (after the delay has passed). If the check setting is no, the lists are built on the first step that satisfies the delay and every settings. If the check setting is yes, then the every and delay settings determine when a build may possibly be performed, but an actual build only occurs if at least one atom has moved more than half the neighbor skin distance (specified in the neighbor command) since the last neighbor list build.

Impact of neighbor list settings

The choice of neighbor list settings can have a significant impact on the (parallel) performance of LAMMPS and the correctness of the simulation results. Since building the neighbor lists is time consuming, doing it less frequently can speed up a calculation. If the lists are rebuilt too infrequently, however, interacting pairs may be missing and thus the resulting pairwise interactions incorrect. The optimal settings depend on many factors like the properties of the simulated system (density, geometry, topology, temperature, pressure), the force field parameters and settings, the size of the timestep, neighbor list skin distance and more. The default settings are chosen to be very conservative to guarantee correctness of the simulation. They depend on the check flag heuristics to reduce the number of neighbor list rebuilds at a minor expense for executing the check. Determining the correctness of a specific choice of neighbor list settings is complicated by the fact that a neighbor list rebuild changes the order in which pairwise interactions are computed and thus - due to the limitations of floating-point math - the trajectory.

If the once setting is yes, then the neighbor list is only built once at the beginning of each run, and never rebuilt, except on steps when a restart file is written, or steps when a fix forces a rebuild to occur (e.g. fixes that create or delete atoms, such as fix deposit or fix evaporate). This setting should only be made if you are certain atoms will not move far enough that the neighbor 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 cluster option does a sanity test every time neighbor lists are built for bond, angle, dihedral, and improper interactions, to check that each set of 2, 3, or 4 atoms is a cluster of nearby atoms. It does this by computing the distance between pairs of atoms in the interaction and ensuring they are not further apart than half the periodic box length. If they are, an error is generated, since the interaction would be computed between far-away atoms instead of their nearby periodic images. The only way this should happen is if the pairwise cutoff is so short that atoms that are part of the same interaction are not communicated as ghost atoms. This is an unusual model (e.g. no pair interactions at all) and the problem can be fixed by use of the comm_modify cutoff command. Note that to save time, the default cluster setting is no, so that this check is not performed.

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. Note that specifying “all” as the group-ID effectively turns off the include option.

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.

Changed in version 29Aug2024: Support for type labels was added.

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/intra option turns off the interaction if both atoms are in the specified group and in the same molecule, as determined by their molecule ID. The exclude molecule/inter turns off the interaction between pairs of atoms that have different molecule IDs and are both in the specified group.

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.

Note

Excluding pairwise interactions will not work correctly when also using a long-range solver via the kspace_style command. LAMMPS will give a warning to this effect. This is because the short-range pairwise interaction needs to subtract off a term from the total energy for pairs whose short-range interaction is excluded, to compensate for how the long-range solver treats the interaction. This is done correctly for pairwise interactions that are excluded (or weighted) via the special_bonds command. But it is not done for interactions that are excluded via these neigh_modify exclude options.

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 LAMMPS the maximum number of neighbor’s one atom can have.

Note

LAMMPS 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 LAMMPS does not 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 have 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, LAMMPS 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 collection interaction cutoff. Typically these are good 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, LAMMPS will use the default binsize of 1/2 the cutoff.

The collection/type option allows you to define collections of atom types, used by the multi neighbor mode. By grouping atom types with similar physical size or interaction cutoff lengths, one may be able to improve performance by reducing overhead. You must first specify the number of collections N to be defined followed by N lists of types. Each list consists of a series of type ranges separated by commas. The range can be specified as a single numeric value, or a wildcard asterisk can be used to specify a range of values. This takes the form “*” or “*n” or “n*” or “m*n”. For example, if M = the number of atom types, then an asterisk with no numeric values means all types from 1 to M. A leading asterisk means all types from 1 to n (inclusive). A trailing asterisk means all types from n to M (inclusive). A middle asterisk means all types from m to n (inclusive). Note that all atom types must be included in exactly one of the N collections.

The collection/interval option provides a similar capability. This command allows a user to define collections by specifying a series of cutoff intervals. LAMMPS will automatically sort atoms into these intervals based on their type-dependent cutoffs or their finite size. You must first specify the number of collections N to be defined followed by N values representing the upper cutoff of each interval. This command is particularly useful for granular pair styles where the interaction distance of particles depends on their radius and may not depend on their atom type.

Restrictions

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

The molecule/intra and molecule/inter exclusion options 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 ensures neighbor pages are not mostly empty space.

The exclude group setting is currently not compatible with dynamic groups.

Related commands

neighbor, delete_bonds

Default

The option defaults are delay = 0, every = 1, check = yes, once = no, cluster = no, include = all (same as no include option defined), exclude = none, page = 100000, one = 2000, and binsize = 0.0.