# neigh_modify command ## Syntax ``` LAMMPS 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 *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 ``` LAMMPS 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](neighbor) command) since the last neighbor list build. ::: {.admonition .note} 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](fix_deposit) or [fix evaporate](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](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](comm_modify) 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](atom_modify) 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](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](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/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](delete_bonds) command for information on turning off bond interactions. :::: note ::: title Note ::: Excluding pairwise interactions will not work correctly when also using a long-range solver via the [kspace_style](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](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 ::: title 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](neighbor), LAMMPS uses bins that are 1/2 the size of the maximum pair cutoff. For [neighbor style multi](neighbor), 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. ## Related commands [neighbor](neighbor), [delete_bonds](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.