Merge pull request #1548 from jrgissing/bond/react-clarify-how-stabilization-works

Bond/react clarify how stabilization works

doc/src/fix_bond_react.txt

@@ -24,7 +24,7 @@ common_keyword = {stabilization} :l
   {stabilization} values = {no} or {yes} {group-ID} {xmax}
     {no} = no reaction site stabilization
     {yes} = perform reaction site stabilization
-      {group-ID} = user-assigned prefix for the dynamic group of non-reacting atoms
+      {group-ID} = user-assigned prefix for the dynamic group of atoms not currently involved in a reaction
       {xmax} = xmax value that is used by an internally-created "nve/limit"_fix_nve_limit.html integrator :pre
 react = mandatory argument indicating new reaction specification :l
   react-ID = user-assigned name for the reaction :l
@@ -52,6 +52,8 @@ react = mandatory argument indicating new reaction specification :l
 
 [Examples:]
 
+For unabridged example scripts and files, see examples/USER/misc/bond_react.
+
 molecule mol1 pre_reacted_topology.txt
 molecule mol2 post_reacted_topology.txt
 fix 5 all bond/react react myrxn1 all 1 0 3.25 mol1 mol2 map_file.txt :pre
@@ -106,6 +108,20 @@ involved in any new reactions. The {xmax} value keyword should
 typically be set to the maximum distance that non-reacting atoms move
 during the simulation.
 
+Fix bond/react creates and maintains two important dynamic groups of
+atoms when using the {stabilization} keyword. The first group contains
+all atoms currently involved in a reaction; this group is
+automatically thermostatted by an internally-created
+"nve/limit"_fix_nve_limit.html integrator. The second group contains
+all atoms currently not involved in a reaction. This group should be
+used by a thermostat in order to time integrate the system. The name
+of this group of non-reacting atoms is created by appending '_REACT'
+to the group-ID argument of the {stabilization} keyword, as shown in
+the second example above.
+
+NOTE: When using reaction stabilization, you should generally not have
+a separate thermostat which acts on the 'all' group.
+
 The group-ID set using the {stabilization} keyword can be an existing
 static group or a previously-unused group-ID. It cannot be specified
 as 'all'. If the group-ID is previously unused, the fix bond/react
@@ -116,20 +132,17 @@ internally-created dynamic group. In both cases, this new dynamic
 group is named by appending '_REACT' to the group-ID, e.g.
 nvt_grp_REACT. By specifying an existing group, you may thermostat
 constant-topology parts of your system separately. The dynamic group
-contains only non-reacting atoms at a given timestep, and therefore
-should be used by a subsequent system-wide time integrator such as
-nvt, npt, or nve, as shown in the second example above. The time
-integration command should be placed after the fix bond/react command
-due to the internal dynamic grouping performed by fix bond/react.
+contains only atoms not involved in a reaction at a given timestep,
+and therefore should be used by a subsequent system-wide time
+integrator such as nvt, npt, or nve, as shown in the second example
+above (full examples can be found at examples/USER/misc/bond_react).
+The time integration command should be placed after the fix bond/react
+command due to the internal dynamic grouping performed by fix
+bond/react.
 
 NOTE: If the group-ID is an existing static group, react-group-IDs
 should also be specified as this static group, or a subset.
 
-NOTE: If the group-ID is previously unused, the internally-created
-group applies to all atoms in the system, i.e. you should generally
-not have a separate thermostat which acts on the 'all' group, or any
-other group.
-
 The following comments pertain to each {react} argument (in other
 words, can be customized for each reaction, or reaction step):
 
@@ -352,12 +365,13 @@ an atom that is not deleted. In addition to deleting unwanted reaction
 by-products, this feature can be used to remove specific topologies,
 such as small rings, that may be otherwise indistinguishable.
 
-Also, it may be beneficial to ensure reacting atoms are at a certain
-temperature before being released to the overall thermostat. For this,
-you can use the internally-created dynamic group named
-"bond_react_MASTER_group." For example, adding the following command
-would thermostat the group of all atoms currently involved in a
-reaction:
+Optionally, you can enforce additional behaviors on reacting atoms.
+For example, it may be beneficial to force reacting atoms to remain at
+a certain temperature. For this, you can use the internally-created
+dynamic group named "bond_react_MASTER_group", which consists of all
+atoms currently involved in a reaction. For example, adding the
+following command would add an additional thermostat to the group of
+all currently-reacting atoms:
 
 fix 1 bond_react_MASTER_group temp/rescale 1 300 300 10 1 :pre