From 9897ee73bf9d53baae9b26de162b87b05a915185 Mon Sep 17 00:00:00 2001 From: sjplimp Date: Thu, 21 Aug 2008 13:53:06 +0000 Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@2089 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/communicate.html | 49 +++++++++++++++++++++++++++++++++++++++---- doc/communicate.txt | 49 +++++++++++++++++++++++++++++++++++++++---- doc/delete_atoms.html | 6 +++++- doc/delete_atoms.txt | 6 +++++- doc/neigh_modify.html | 5 +++-- doc/neigh_modify.txt | 5 +++-- doc/neighbor.html | 42 ++++++++++++++++--------------------- doc/neighbor.txt | 40 +++++++++++++++-------------------- doc/timestep.html | 7 ++++--- doc/timestep.txt | 10 ++++----- 10 files changed, 149 insertions(+), 70 deletions(-) diff --git a/doc/communicate.html b/doc/communicate.html index 6668dbc272..7e161bc7f6 100644 --- a/doc/communicate.html +++ b/doc/communicate.html @@ -19,16 +19,18 @@
  • zero or more keyword/value pairs may be appended -
  • keyword = group +
  • keyword = group or cutoff -
      group value = group-ID = only communicate atoms in the group 
+
      group value = group-ID = only communicate atoms in the group
+  cutoff value = Rcut (distance units) = communicate atoms from this far away 
 
    
 
 
 
    Examples:
 
    
 
    communicate multi
-communicate multi group solvent 
+communicate multi group solvent
+communicate single cutoff 5.0 
 
    
 
    Description:
 
    
@@ -57,6 +59,45 @@ specified group) will still migrate to new processors as they move.
 The group specified with this option must also be specified via the
 atom_modify first command.
 
    
+
    The cutoff option allows you to set a ghost cutoff distance which is
+the distance from the borders of a processor's sub-domain at which
+ghost atoms are acquired from other processors.  By default the ghost
+cutoff = the neighbor cutoff = the pairwise force cutoff + the
+neighbor skin.  See the neighbor command for more
+information about the skin distance.  If the specified Rcut is greater
+than the neighbor cutoff, then extra ghost atoms will be acquired.  If
+it is smaller, the ghost cutoff is set to the neighbor cutoff.
+
    
+
    These are simulation scenarios in which it may be useful to set a
+ghost cutoff > neighbor cutoff:
+
    
+
    • a single polymer chain with bond interactions, but no pairwise interactions
+
    • bonded interactions (e.g. dihedrals) extend further than the pairwise cutoff
+
    • ghost atoms beyond the pairwise cutoff are needed for some computation 
+
    
+
    In the first scenario, a pairwise potential may not be defined.  Thus
+the pairwise neighbor cutoff will be 0.0.  But ghost atoms are still
+needed for computing bond, angle, etc interactions between atoms on
+different processors.  The appropriate ghost cutoff depends on the
+newton bond setting.  For newton bond off, the
+distance needs to be the furthest distance between any two atoms in
+the bond, angle, etc.  E.g. the distance between 1-4 atoms in a
+dihedral.  For newton bond on, the distance between the central atom
+in the bond, angle, etc and any other atom is sufficient.  E.g. the
+distance between 2-4 atoms in a dihedral.
+
    
+
    In the second scenario, a pairwise potential is defined, but its
+neighbor cutoff is not sufficiently long enough to enable bond, angle,
+etc terms to be computed.  As in the previous scenario, an appropriate
+ghost cutoff should be set.
+
    
+
    In the last scenario, a fix or compute or
+pairwise potential needs to calculate with ghost
+atoms beyond the normal pairwise cutoff for some computation it
+performs (e.g. locate neighbors of ghost atoms in a multibody pair
+potential).  Setting the ghost cutoff appropriately can insure it will
+find the needed atoms.
+
    
 
    Restrictions: none
 
    
 
    Related commands:
@@ -65,6 +106,6 @@ The group specified with this option must also be specified via the
 
    
 
    Default:
 
    
-
    The default settings are style = single and group = all.
+
    The default settings are style = single, group = all, cutoff = 0.0.
 
    
 
diff --git a/doc/communicate.txt b/doc/communicate.txt
index 84002fd934..3e73375daf 100644
--- a/doc/communicate.txt
+++ b/doc/communicate.txt
@@ -14,14 +14,16 @@ communicate style keyword value ... :pre
 
 style = {single} or {multi} :ulb,l
 zero or more keyword/value pairs may be appended :l
-keyword = {group} :l
-  {group} value = group-ID = only communicate atoms in the group :pre
+keyword = {group} or {cutoff} :l
+  {group} value = group-ID = only communicate atoms in the group
+  {cutoff} value = Rcut (distance units) = communicate atoms from this far away :pre
 :ule
 
 [Examples:]
 
 communicate multi
-communicate multi group solvent :pre
+communicate multi group solvent
+communicate single cutoff 5.0 :pre
 
 [Description:]
 
@@ -50,6 +52,45 @@ specified group) will still migrate to new processors as they move.
 The group specified with this option must also be specified via the
 "atom_modify first"_atom_modify.html command.
 
+The {cutoff} option allows you to set a ghost cutoff distance which is
+the distance from the borders of a processor's sub-domain at which
+ghost atoms are acquired from other processors.  By default the ghost
+cutoff = the neighbor cutoff = the pairwise force cutoff + the
+neighbor skin.  See the "neighbor"_neighbor.html command for more
+information about the skin distance.  If the specified Rcut is greater
+than the neighbor cutoff, then extra ghost atoms will be acquired.  If
+it is smaller, the ghost cutoff is set to the neighbor cutoff.
+
+These are simulation scenarios in which it may be useful to set a
+ghost cutoff > neighbor cutoff:
+
+a single polymer chain with bond interactions, but no pairwise interactions
+bonded interactions (e.g. dihedrals) extend further than the pairwise cutoff
+ghost atoms beyond the pairwise cutoff are needed for some computation :ul
+
+In the first scenario, a pairwise potential may not be defined.  Thus
+the pairwise neighbor cutoff will be 0.0.  But ghost atoms are still
+needed for computing bond, angle, etc interactions between atoms on
+different processors.  The appropriate ghost cutoff depends on the
+"newton bond"_newton.html setting.  For newton bond {off}, the
+distance needs to be the furthest distance between any two atoms in
+the bond, angle, etc.  E.g. the distance between 1-4 atoms in a
+dihedral.  For newton bond {on}, the distance between the central atom
+in the bond, angle, etc and any other atom is sufficient.  E.g. the
+distance between 2-4 atoms in a dihedral.
+
+In the second scenario, a pairwise potential is defined, but its
+neighbor cutoff is not sufficiently long enough to enable bond, angle,
+etc terms to be computed.  As in the previous scenario, an appropriate
+ghost cutoff should be set.
+
+In the last scenario, a "fix"_fix.html or "compute"_compute.html or
+"pairwise potential"_pair_style.html needs to calculate with ghost
+atoms beyond the normal pairwise cutoff for some computation it
+performs (e.g. locate neighbors of ghost atoms in a multibody pair
+potential).  Setting the ghost cutoff appropriately can insure it will
+find the needed atoms.
+
 [Restrictions:] none
 
 [Related commands:]
@@ -58,4 +99,4 @@ The group specified with this option must also be specified via the
 
 [Default:]
 
-The default settings are style = single and group = all.
+The default settings are style = single, group = all, cutoff = 0.0.
diff --git a/doc/delete_atoms.html b/doc/delete_atoms.html
index d252dbf8df..1658779cd2 100644
--- a/doc/delete_atoms.html
+++ b/doc/delete_atoms.html
@@ -71,7 +71,11 @@ would foul up the bond connectivity that has already been assigned.
 
    The overlap styles requires inter-processor communication to acquire
 ghost atoms and build a neighbor list.  This means that your system
 must be ready to perform a simulation before using this command (force
-fields setup, atom masses set, etc).
+fields setup, atom masses set, etc).  Since a neighbor list is used to
+find overlapping atom pairs, it also means that you must define a
+pair style with force cutoffs greater than or equal
+to the desired overlap cutoff between pairs of relevant atom types,
+even though the pair potential will not be evaluated.
 
    
 
    If the special_bonds command is used with a
 setting of 0, then a pair of bonded atoms (1-2, 1-3, or 1-4) will not
diff --git a/doc/delete_atoms.txt b/doc/delete_atoms.txt
index a02e3fc942..add63b0b3a 100644
--- a/doc/delete_atoms.txt
+++ b/doc/delete_atoms.txt
@@ -66,7 +66,11 @@ would foul up the bond connectivity that has already been assigned.
 The {overlap} styles requires inter-processor communication to acquire
 ghost atoms and build a neighbor list.  This means that your system
 must be ready to perform a simulation before using this command (force
-fields setup, atom masses set, etc).
+fields setup, atom masses set, etc).  Since a neighbor list is used to
+find overlapping atom pairs, it also means that you must define a
+"pair style"_pair_style.html with force cutoffs greater than or equal
+to the desired overlap cutoff between pairs of relevant atom types,
+even though the pair potential will not be evaluated.
 
 If the "special_bonds"_special_bonds.html command is used with a
 setting of 0, then a pair of bonded atoms (1-2, 1-3, or 1-4) will not
diff --git a/doc/neigh_modify.html b/doc/neigh_modify.html
index f81b4f6150..c36fcb4ff9 100644
--- a/doc/neigh_modify.html
+++ b/doc/neigh_modify.html
@@ -56,9 +56,10 @@ neigh_modify exclude molecule rigid

    Description:

    -

    This command sets parameters that affect the pairwise neighbor list. +

    This command sets parameters that affect the building and use of +pairwise neighbor lists.

    -

    The every, delay, and check options affect how often the list is +

    The every, delay, and check 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 diff --git a/doc/neigh_modify.txt b/doc/neigh_modify.txt index 21b7e2ad4d..5607dd2c6e 100644 --- a/doc/neigh_modify.txt +++ b/doc/neigh_modify.txt @@ -50,9 +50,10 @@ neigh_modify exclude molecule rigid :pre [Description:] -This command sets parameters that affect the pairwise neighbor list. +This command sets parameters that affect the building and use of +pairwise neighbor lists. -The {every}, {delay}, and {check} options affect how often the list is +The {every}, {delay}, and {check} 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 diff --git a/doc/neighbor.html b/doc/neighbor.html index 8b24a4929d..135a53fba6 100644 --- a/doc/neighbor.html +++ b/doc/neighbor.html @@ -25,13 +25,22 @@ neighbor 2.0 nsq

    Description:

    -

    This command sets parameters that affect the building of the pairwise -neighbor list. All atom pairs within a cutoff distance equal to the +

    This command sets parameters that affect the building of pairwise +neighbor lists. All atom pairs within a cutoff distance equal to the their force cutoff plus the skin distance are stored in the list. Typically, the larger the skin distance, the less often neighbor lists need to be built, but more pairs must be checked for possible force interactions every timestep. The default value for skin depends on -the choice of units for the simulation (see below). +the choice of units for the simulation; see the default values below. +

    +

    Even if pairwise neighbor lists are not used in a simulation (e.g. a +pair potential is not defined), the skin distance may still determine +how often atoms migrate to new processors due to atom motion and +should thus be set appropriately. This is because atoms migrate on +the same timestep that neighbor lists are built. See the various +settings of the neigh_modify command which control when +neighbor lists are built, based on atom movement via the "check yes" +option.

    The style value selects what algorithm is used to build the list. The bin style creates the list by binning which is an operation that @@ -64,24 +73,7 @@ the pairwise list and the number of times neighbor lists were built are printed to the screen and log file. See this section for details.

    -

    Restrictions: -

    -

    For simulations without pairwise interactions (see "pair_style none" -command), but that include bonded interactions, you still need to set -the neighbor skin distance. Pairwise neighbor lists will not be -formed, but the pair cutoff (0.0 in this case) plus the skin distance -is the range at which atoms are communicated from nearby processors. -This needs to be large enough that atoms in the same bond, angle, etc -as an atom owned by a processor are acquired. What distance is -appropriate depends on the newton bond setting. For -newton bond off, the distance needs to be the furthest distance -between any two atoms in the bond, angle, etc. E.g. the distance -between the 1-4 atoms in a dihedral. For newton bond on, the distance -is between the central atom in the bond, angle, etc and any other -atom. E.g. the distance between the 2-4 atoms in a dihedral. -

    -

    The same logic applies to systems that include bonded interactions and -a pairwise cutoff shorter than the distances just described. +

    Restrictions: none

    Related commands:

    @@ -90,7 +82,9 @@ a pairwise cutoff shorter than the distances just described.

    Default:

    -
    0.3 bin      for lj units (0.3 sigma)
-2.0 bin      for real or metal units (2.0 Angstroms) 
-
    +0.3 bin for units = lj, skin = 0.3 sigma
    +2.0 bin for units = real or metal, skin = 2.0 Angstroms
    +0.001 bin for units = si, skin = 0.001 meters = 1.0 mm
    +0.1 bin for units = cgs, skin = 0.1 cm = 1.0 mm
    + diff --git a/doc/neighbor.txt b/doc/neighbor.txt index 9a04488d4c..9d3532dee2 100644 --- a/doc/neighbor.txt +++ b/doc/neighbor.txt @@ -22,13 +22,22 @@ neighbor 2.0 nsq :pre [Description:] -This command sets parameters that affect the building of the pairwise -neighbor list. All atom pairs within a cutoff distance equal to the +This command sets parameters that affect the building of pairwise +neighbor lists. All atom pairs within a cutoff distance equal to the their force cutoff plus the {skin} distance are stored in the list. Typically, the larger the skin distance, the less often neighbor lists need to be built, but more pairs must be checked for possible force interactions every timestep. The default value for {skin} depends on -the choice of units for the simulation (see below). +the choice of units for the simulation; see the default values below. + +Even if pairwise neighbor lists are not used in a simulation (e.g. a +pair potential is not defined), the skin distance may still determine +how often atoms migrate to new processors due to atom motion and +should thus be set appropriately. This is because atoms migrate on +the same timestep that neighbor lists are built. See the various +settings of the "neigh_modify"_neigh_modify command which control when +neighbor lists are built, based on atom movement via the "check yes" +option. The {style} value selects what algorithm is used to build the list. The {bin} style creates the list by binning which is an operation that @@ -61,24 +70,7 @@ the pairwise list and the number of times neighbor lists were built are printed to the screen and log file. See "this section"_Section_start.html#2_7 for details. -[Restrictions:] - -For simulations without pairwise interactions (see "pair_style none" -command), but that include bonded interactions, you still need to set -the neighbor skin distance. Pairwise neighbor lists will not be -formed, but the pair cutoff (0.0 in this case) plus the skin distance -is the range at which atoms are communicated from nearby processors. -This needs to be large enough that atoms in the same bond, angle, etc -as an atom owned by a processor are acquired. What distance is -appropriate depends on the "newton bond"_newton.html setting. For -newton bond off, the distance needs to be the furthest distance -between any two atoms in the bond, angle, etc. E.g. the distance -between the 1-4 atoms in a dihedral. For newton bond on, the distance -is between the central atom in the bond, angle, etc and any other -atom. E.g. the distance between the 2-4 atoms in a dihedral. - -The same logic applies to systems that include bonded interactions and -a pairwise cutoff shorter than the distances just described. +[Restrictions:] none [Related commands:] @@ -87,5 +79,7 @@ a pairwise cutoff shorter than the distances just described. [Default:] -0.3 bin for lj units (0.3 sigma) -2.0 bin for real or metal units (2.0 Angstroms) :pre +0.3 bin for units = lj, skin = 0.3 sigma +2.0 bin for units = real or metal, skin = 2.0 Angstroms +0.001 bin for units = si, skin = 0.001 meters = 1.0 mm +0.1 bin for units = cgs, skin = 0.1 cm = 1.0 mm :all(b) diff --git a/doc/timestep.html b/doc/timestep.html index 4d6eca3bc9..b12cc15c9c 100644 --- a/doc/timestep.html +++ b/doc/timestep.html @@ -26,8 +26,8 @@ timestep 0.003

    Set the timestep size for subsequent molecular dynamics simulations. See the units command for a discussion of time units. -Note that using the units command also sets the timestep to its -default value in the chosen units. +The default value for the timestep also depends on the choice of units +for the simulation; see the default values below.

    When the run style is respa, dt is the timestep for the outer loop (largest) timestep. @@ -43,6 +43,7 @@ the outer loop (largest) timestep.

    timestep = 0.005 tau for units = lj
    timestep = 1.0 fmsec for units = real
    -timestep = 0.001 psec for units = metal
    +timestep = 0.001 psec for units = metal
    +timestep = 1.0e-8 sec (10 nsec) for units = si or cgs
    diff --git a/doc/timestep.txt b/doc/timestep.txt index a08f7b483c..95c73930e0 100644 --- a/doc/timestep.txt +++ b/doc/timestep.txt @@ -23,8 +23,8 @@ timestep 0.003 :pre Set the timestep size for subsequent molecular dynamics simulations. See the "units"_units.html command for a discussion of time units. -Note that using the units command also sets the timestep to its -default value in the chosen units. +The default value for the timestep also depends on the choice of units +for the simulation; see the default values below. When the "run style"_run_style.html is {respa}, dt is the timestep for the outer loop (largest) timestep. @@ -40,7 +40,5 @@ the outer loop (largest) timestep. timestep = 0.005 tau for units = lj timestep = 1.0 fmsec for units = real -timestep = 0.001 psec for units = metal :all(b) - - - +timestep = 0.001 psec for units = metal +timestep = 1.0e-8 sec (10 nsec) for units = si or cgs :all(b)