Examples and documentation

doc/src/comm_modify.rst

@@ -66,9 +66,10 @@ For many systems this is an efficient algorithm, but for systems with
 widely varying cutoffs for different type pairs, the *multi* mode can
 be faster.  In this case, each atom type is assigned its own distance
 cutoff for communication purposes, and fewer atoms will be
-communicated.  See the :doc:`neighbor multi <neighbor>` command for a
+communicated. See the :doc:`neighbor multi <neighbor>` command for a
 neighbor list construction option that may also be beneficial for
-simulations of this kind.
+simulations of this kind. The *multi* mode is compatable with both the
+*multi* and *multi/old* neighbor styles.
 
 The *cutoff* keyword allows you to extend the ghost cutoff distance
 for communication mode *single*\ , which is the distance from the borders
@@ -95,11 +96,12 @@ using the usual asterisk notation can be given. For granular pair styles,
 the default cutoff is set to the sum of the current maximum atomic radii
 for each type.
 
-The *cutoff/bytype* option applies to *multi* and automtically sets communication 
-cutoffs for each particle type based on the largest interaction distance
-between two particles of the same type. This method is only compatible 
-with Newton on and the *bytype* neighbor style. See the :doc:`neighbor bytype <neighbor>` 
-command for more information.
+The *multi/reduce* option applies to *multi* and automatically sets communication 
+cutoffs for different sized particles based on the largest interaction distance 
+between two particles in the same multi grouping. This reduces the number of
+ghost that need to be communicated This method is only compatible with the 
+*multi* neighbor style and requires only half neighbor lists and Newton on. 
+See the :doc:`neighbor multi <neighbor>` command for more information.
 
 These are simulation scenarios in which it may be useful or even
 necessary to set a ghost cutoff > neighbor cutoff:

doc/src/neigh_modify.rst

@@ -14,7 +14,7 @@ Syntax
 
   .. parsed-literal::
 
-     keyword = *delay* or *every* or *check* or *once* or *cluster* or *include* or *exclude* or *page* or *one* or *binsize*
+     keyword = *delay* or *every* or *check* or *once* or *cluster* or *include* or *exclude* or *page* or *one* or *binsize* or *multi/custom*
        *delay* value = N
          N = delay building until this many steps since last build
        *every* value = M
@@ -47,6 +47,9 @@ Syntax
          N = max number of neighbors of one atom
        *binsize* value = size
          size = bin size for neighbor list construction (distance units)
+       *multi/custom* values = N types
+         N = number of custom groups
+         types = N separate types or groups of types (see below)
 
 Examples
 """"""""
@@ -58,6 +61,7 @@ Examples
    neigh_modify exclude group frozen frozen check no
    neigh_modify exclude group residue1 chain3
    neigh_modify exclude molecule/intra rigid
+   neigh_modify multi/custom 2 1*2 3*4
 
 Description
 """""""""""
@@ -197,6 +201,20 @@ 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 *multi/custom* option allows you to define custom groups of atom 
+types for the *multi* neighbor mode. By grouping atom types with 
+similar cutoffs, one may be able to improve performance by reducing
+overhead. You must first specify the number of custom groups N to be
+defined followed by N ranges of types. 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 N = the number of atom types, then an asterisk with no numeric 
+values means all types from 1 to N.  A leading asterisk means all types 
+from 1 to n (inclusive).  A trailing asterisk means all types from n to N 
+(inclusive).  A middle asterisk means all types from m to n (inclusive). 
+Note that any atom types not included in a custom group will be automatically
+placed within a new, separate group.
+
 Restrictions
 """"""""""""
 

doc/src/neighbor.rst

@@ -11,7 +11,7 @@ Syntax
    neighbor skin style
 
 * skin = extra distance beyond force cutoff (distance units)
-* style = *bin* or *nsq* or *multi* or *bytype*
+* style = *bin* or *nsq* or *multi* or *multi/old*
 
 Examples
 """"""""
@@ -55,22 +55,24 @@ 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.  For style *multi* 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 atom types.
+other type pairs have a much shorter cutoff. The *multi* style uses
+different sized bins for groups of different sized particles. Different
+sets of bins are then used to construct the neighbor lists as as further 
+described by Shire, Hanley, and Stratford :ref:`(Shire) <bytype-Shire>`. 
 This imposes some extra setup overhead, but the searches themselves
-may be much faster for the short-cutoff cases.
-See the :doc:`comm_modify mode multi <comm_modify>` command for a
-communication option that may also be beneficial for simulations of
-this kind.
+may be much faster. By default, separate groups of particles are defined 
+for each atom type. For systems with two or more types with similar 
+cutoffs, one can reduce the extra overhead by defining custom groupings 
+using the :doc:`neigh_modify <neigh_modify>` command. See the 
+:doc:`comm_modify mode bytype <comm_modify>` command for compatible 
+communication options that may be beneficial for simulations of this kind.
 
-The *bytype* style is an extension of the *multi* style that was 
-presented by Shire, Hanley, and Stratford :ref:`(Shire) <bytype-Shire>`. 
-For style *bytype*, different bin lists are created for each different 
-type and separate bin sizes are generated. Whether *bytype* or *multi* 
-is faster may depend on the specifics of your system. See the 
-:doc:`comm_modify mode bytype <comm_modify>` command for a compatible 
-communication option.
+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 
+different atom types. This algorithm used to be the default *multi* 
+algorithm in LAMMPS but was found to be significantly slower than the new
+approach. Although, there may be instances where the *multi/old* style 
+could outperform the new style. 
 
 The :doc:`neigh_modify <neigh_modify>` command has additional options
 that control how often neighbor lists are built and which pairs are