diff --git a/doc/src/neighbor.rst b/doc/src/neighbor.rst index 0cfedfc090..663170ef47 100644 --- a/doc/src/neighbor.rst +++ b/doc/src/neighbor.rst @@ -49,29 +49,27 @@ sometimes be faster. Either style should give the same answers. The *multi* style 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 granular pair styles, cutoffs are set to the -sum of the maximum atomic radii for each atom type. -For the *bin* style, the bin size is set to 1/2 of -the largest cutoff distance between any pair of atom types and a -single set of bins is defined to search over for all atom types. This -can be inefficient if one pair of types has a very long cutoff, but -other type pairs have a much shorter cutoff. The *multi* style uses -different sized bins for collections of different sized particles, where -"size" may mean the physical size of the particle or its cutoff -distance for interacting with other particles. Different +size particles. For granular pair styles, cutoffs are set to the sum of +the maximum atomic radii for each atom type. For the *bin* style, the +bin size is set to 1/2 of the largest cutoff distance between any pair +of atom types and a single set of bins is defined to search over for all +atom types. This can be inefficient if one pair of types has a very +long cutoff, but other type pairs have a much shorter cutoff. The +*multi* style uses different sized bins for collections of different +sized particles, where "size" may mean the physical size of the particle +or its cutoff distance for interacting with other particles. Different sets of bins are then used to construct the neighbor lists as as further described by Shire, Hanley, and Stratford :ref:`(Shire) `. -This imposes some extra setup overhead, but the searches themselves -may be much faster. By default, each atom type defines a separate -collection of particles. For systems where two or more atom types -have the same size (either physical size or cutoff distance), the -definition of collections can be customized, which can result in less -overhead and faster performance. See the :doc:`neigh_modify ` -command for how to define custom collections. Whether the collection -definition is customized or not, also see the -:doc:`comm_modify mode multi ` command for communication -options that further improve performance in a manner consistent with -neighbor style multi. +This imposes some extra setup overhead, but the searches themselves may +be much faster. By default, each atom type defines a separate collection +of particles. For systems where two or more atom types have the same +size (either physical size or cutoff distance), the definition of +collections can be customized, which can result in less overhead and +faster performance. See the :doc:`neigh_modify ` command +for how to define custom collections. Whether the collection definition +is customized or not, also see the :doc:`comm_modify mode multi +` command for communication options that further improve +performance in a manner consistent with neighbor style multi. An alternate style, *multi/old*, sets the bin size to 1/2 of the shortest cutoff distance and multiple sets of bins are defined to search over for @@ -80,6 +78,16 @@ algorithm in LAMMPS but was found to be significantly slower than the new approach. For now we are keeping the old option in case there are use cases where multi/old outperforms the new multi style. +.. note:: + + If there are multiple sub-styles in a :doc:`hybrid/overlay pair style + ` that cover the same atom types, but have significantly + different cutoffs, the *multi* style does not apply. Instead, the + :doc:`pair_modify neigh/trim ` setting applies (which is + *yes* by default). Please check the neighbor list summary printed at + the beginning of a calculation to verify that the desired set of + neighbor list builds is performed. + The :doc:`neigh_modify ` command has additional options that control how often neighbor lists are built and which pairs are diff --git a/doc/src/pair_modify.rst b/doc/src/pair_modify.rst index 70e0e6c870..6d4171fbc9 100644 --- a/doc/src/pair_modify.rst +++ b/doc/src/pair_modify.rst @@ -284,29 +284,30 @@ the *pair* keyword. Use *no* to disable, or *yes* to enable. The "pair_modify pair compute/tally" command must be issued **before** the corresponding compute style is defined. -The *neigh/trim* keyword controls whether an explicit cutoff is set -for each neighbor list requested by the individual pair sub-styles -when using :doc:`pair hybrid\*/overlay `. When -this keyword is set to *no*, then the cutoff of each pair sub-style -neighbor list will be set equal to the largest cutoff, even if a -shorter cutoff is specified for a particular sub-style. If possible -the neighbor list will be copied directly from another list. When this -keyword is set to *yes* then the cutoff of the neighbor list will be -explicitly set to the value requested by the pair sub-style, and if -possible the list will be created by trimming from another list with a -longer cutoff, otherwise a new neighbor list will be created with the -specified cutoff. The *yes* option can be faster when there are -multiple pair styles with different cutoffs since the number of -pair-wise distance checks between neighbors is reduced (but the time -required to build the neighbor lists is increased). The *no* option -could be faster when two or more neighbor lists have similar (but not -exactly the same) cutoffs. +The *neigh/trim* keyword controls whether an explicit cutoff is set for +each neighbor list request issued by individual pair sub-styles when +using :doc:`pair hybrid/overlay `. When this keyword is +set to *no*, then the cutoff of each pair sub-style neighbor list will +be set equal to the largest cutoff, even if a shorter cutoff is +specified for a particular sub-style. If possible the neighbor list +will be copied directly from another list. When this keyword is set to +*yes* then the cutoff of the neighbor list will be explicitly set to the +value requested by the pair sub-style, and if possible the list will be +created by trimming neighbors from another list with a longer cutoff, +otherwise a new neighbor list will be created with the specified cutoff. +The *yes* option can be faster when there are multiple pair styles with +different cutoffs since the number of pair-wise distance checks between +neighbors is reduced (but the time required to build the neighbor lists +is increased). The *no* option could be faster when two or more neighbor +lists have similar (but not exactly the same) cutoffs. .. note:: - The "pair_modify neigh/trim" command only applies when there are - multiple pair sub-styles with different cutoffs, i.e. when using - pair hybrid/overlay + The "pair_modify neigh/trim" command *only* applies when there are + multiple pair sub-styles for the same atoms with different cutoffs, + i.e. when using pair style hybrid/overlay. If you have different + cutoffs for different pairs for atoms type, the :doc:`neighbor style + multi ` should be used to create optimized neighbor lists. ---------- @@ -323,7 +324,7 @@ Related commands :doc:`pair_style `, :doc:`pair_style hybrid `, :doc:`pair_coeff `, :doc:`thermo_style `, -:doc:`compute \*/tally ` +:doc:`compute \*/tally `, :doc:`neighbor multi ` Default """"""" diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 77a1da6643..e5edbc61ea 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -3191,6 +3191,7 @@ Souza sp spacings Spearot +specieslist specular spellcheck Spellmeyer