Merge pull request #913 from jrgissing/bond/react-doc-reformat

Bond/react doc reformat

doc/src/fix_bond_react.txt

@@ -20,14 +20,15 @@ ID, group-ID are documented in "fix"_fix.html command. Group-ID is ignored. :ulb
 bond/react = style name of this fix command :l
 zero or more common keyword/value pairs may be appended directly after 'bond/react' :l
 these apply to all reaction specifications (below) :l
-common_keyword = {stabilization}
-  {stabilization} values = group-ID xmax
-    group-ID = user-assigned ID of an internally-created dynamic group that excludes reacting atoms, and can be used by a subsequent time integration fix such as nvt, npt, or nve (cannot be 'all')
-  {xmax} value = distance
-    distance = xmax value that is used by an internally created "nve/limit"_fix_nve_limit.html integrator
-react = mandatory argument indicating new reaction specification
-  react-ID = user-assigned name for the reaction
-  react-group-ID = only atoms in this group are available for the reaction
+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 ID for all non-reacting atoms (group created internally)
+      {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
+  react-group-ID = only atoms in this group are available for the reaction :l
   Nevery = attempt reaction every this many steps :l
   Rmin = bonding pair atoms must be separated by more than Rmin to initiate reaction (distance units) :l
   Rmax = bonding pair atoms must be separated by less than Rmax to initiate reaction (distance units) :l
@@ -47,7 +48,7 @@ react = mandatory argument indicating new reaction specification
 
 molecule mol1 pre_reacted_topology.txt
 molecule mol2 post_reacted_topology.txt
-fix 5 all bond/react stabilization no react myrxn1 all 1 0 3.25 mol1 mol2 map_file.txt
+fix 5 all bond/react stabilization no react myrxn1 all 1 0 3.25 mol1 mol2 map_file.txt :pre
 
 molecule mol1 pre_reacted_rxn1.txt
 molecule mol2 post_reacted_rxn1.txt
@@ -56,12 +57,12 @@ molecule mol4 post_reacted_rxn2.txt
 fix 5 all bond/react stabilization yes nvt_grp .03 &
   react myrxn1 all 1 0 3.25 mol1 mol2 map_file_rxn1.txt prob 0.50 12345 &
   react myrxn2 all 1 0 2.75 mol3 mol4 map_file_rxn2.txt prob 0.25 12345
-fix 6 nvt_grp nvt temp 300 300 100 # system-wide thermostat must be defined after bond/react :pre
+fix 6 nvt_grp nvt temp 300 300 100 # set thermostat after bond/react :pre
 
 [Description:]
 
 Initiate complex covalent bonding (topology) changes. These topology
-changes will be referred to as "reactions" throughout this
+changes will be referred to as 'reactions' throughout this
 documentation. Topology changes are defined in pre- and post-reaction
 molecule templates and can include creation and deletion of bonds,
 angles, dihedrals, impropers, bond-types, angle-types, dihedral-types,
@@ -81,10 +82,10 @@ occurred 3) build a molecule template of the reaction site after the
 reaction has occurred 4) create a map that relates the
 template-atom-IDs of each atom between pre- and post-reaction molecule
 templates 5) fill a simulation box with molecules and run a simulation
-with fix/bond react.
+with fix bond/react.
 
 Only one 'fix bond/react' command can be used at a time. Multiple
-reactions can be simultaneously applied by specifying multiple 'react'
+reactions can be simultaneously applied by specifying multiple {react}
 arguments to a single 'fix bond/react' command. This syntax is
 necessary because the 'common keywords' are applied to all reactions.
 
@@ -99,10 +100,11 @@ typically be set to the maximum distance that non-reacting atoms move
 during the simulation.
 
 The group-ID set using the {stabilization} keyword should be a
-previously unused group-ID. The fix bond/react command creates a
-"dynamic group"_group.html of this name that excludes reacting atoms.
-This dynamic group-ID should then be used by a subsequent system-wide
-time integrator, as shown in the second example above. It is currently
+previously unused group-ID. It cannot be specified as 'all'. The fix
+bond/react command creates a "dynamic group"_group.html of this name
+that includes all non-reacting atoms. This dynamic group-ID should
+then be used by a subsequent system-wide time integrator such as nvt,
+npt, or nve, as shown in the second example above. It is currently
 necessary to place the time integration command after the fix
 bond/react command due to the internal dynamic grouping performed by
 fix bond/react.
@@ -111,9 +113,9 @@ NOTE: The internally created group currently applies to all atoms in
 the system, i.e. you should generally not have a separate thermostat
 which acts on the 'all' group.
 
-The following comments pertain to each 'react' argument:
+The following comments pertain to each {react} argument:
 
-A check for possible new reaction sites is performed every Nevery
+A check for possible new reaction sites is performed every {Nevery}
 timesteps.
 
 Two conditions must be met for a reaction to occur. First a bonding
@@ -124,20 +126,20 @@ modified to match the post-reaction template.
 
 A bonding atom pair will be identified if several conditions are met.
 First, a pair of atoms within the specified react-group-ID of type
-typei and typej must separated by a distance between Rmin and Rmax. It
-is possible that multiple bonding atom pairs are identified: if the
-bonding atoms in the pre-reacted template are not 1-2, 1-3, or 1-4
-neighbors, the closest bonding atom partner is set as its bonding
-partner; otherwise, the farthest potential partner is chosen. Then, if
-both an atomi and atomj have each other as their nearest bonding
-partners, these two atoms are identified as the bonding atom pair of
-the reaction site. Once this unique bonding atom pair is identified
-for each reaction, there could two or more reactions that involve a
-given atom on the same timestep. If this is the case, only one such
-reaction is permitted to occur. This reaction is chosen randomly from
-all potential reactions. This capability allows e.g. for different
-reaction pathways to proceed from identical reaction sites with
-user-specified probabilities.
+typei and typej must separated by a distance between {Rmin} and
+{Rmax}. It is possible that multiple bonding atom pairs are
+identified: if the bonding atoms in the pre-reacted template are not
+1-2, 1-3, or 1-4 neighbors, the closest bonding atom partner is set as
+its bonding partner; otherwise, the farthest potential partner is
+chosen. Then, if both an atomi and atomj have each other as their
+nearest bonding partners, these two atoms are identified as the
+bonding atom pair of the reaction site. Once this unique bonding atom
+pair is identified for each reaction, there could two or more
+reactions that involve a given atom on the same timestep. If this is
+the case, only one such reaction is permitted to occur. This reaction
+is chosen randomly from all potential reactions. This capability
+allows e.g. for different reaction pathways to proceed from identical
+reaction sites with user-specified probabilities.
 
 The pre-reacted molecule template is specified by a molecule command.
 This molecule template file contains a sample reaction site and its
@@ -175,77 +177,43 @@ A discussion of correctly handling this is also provided on the
 
 The map file is a text document with the following format:
 
-Format of the map file
-
-A map file has a header and a body. The header appears first. The
-first line of the header is always skipped; it typically contains a
-description of the file.  Lines can have a trailing comment starting
-with '#' that is ignored. If the line is blank (only whitespace after
-comment is deleted), it is skipped. If the line contains a header
-keyword, the corresponding value(s) is read from the line. If it
-doesn't contain a header keyword, the line begins the body of the
-file.
-
-The header contains one mandatory keyword and one optional keyword.
-The mandatory keyword is 'equivalences' and the optional keyword is
-'edgeIDs.' These specify the number of atoms in the pre- and
-post-reacted templates and the number of edge atoms in pre-reacted
-template, respectively.
-
-The body contains two mandatory sections and one optional section. The
-first section begins with the keyword 'BondingIDs' and lists the atom
-IDs of the bonding atom pair in the pre-reacted molecule template. The
-second mandatory section begins with the keyword 'Equivalences' and
-lists a one-to-one correspondence between atom IDs of the pre- and
-post-reacted templates. The optional section begins with the keyword
-'EdgeIDs' and list the atom IDs of edge atoms in the pre-reacted
+A map file has a header and a body. The header of map file the
+contains one mandatory keyword and one optional keyword. The mandatory
+keyword is 'equivalences' and the optional keyword is 'edgeIDs':
+
+N {equivalences} = # of atoms N in the reaction molecule templates
+N {edgeIDs} = # of edge atoms N in the pre-reacted molecule template :pre
+
+The body of the map file contains two mandatory sections and one
+optional section. The first mandatory section begins with the keyword
+'BondingIDs' and lists the atom IDs of the bonding atom pair in the
+pre-reacted molecule template. The second mandatory section begins
+with the keyword 'Equivalences' and lists a one-to-one correspondence
+between atom IDs of the pre- and post-reacted templates. The first
+column is an atom ID of the pre-reacted molecule template, and the
+second column is the corresponding atom ID of the post-reacted
+molecule template. The optional section begins with the keyword
+'EdgeIDs' and lists the atom IDs of edge atoms in the pre-reacted
 molecule template.
 
-Format of the header of the map file
-
-These are the recognized header keywords. Header lines can come in any
-order. The value(s) are read from the beginning of the line. Thus the
-keyword 'equivalences' should be in a line like "25 equivalences."
-
-equivalences = # of atoms in the pre- and post-reacted molecule
-templates edgeIDs = # of edge atoms in the pre-reacted molecule template :pre
-
-The edgeIDs keyword is optional.
-
-Format of the body of the map file
-
-These are the section keywords for the body of the file.
-
-BondingIDs, EdgeIDs = list of atom IDs of bonding and edge atoms in
-the pre-reacted molecule template
-
-Equivalences = a two column list where the first column is an atom ID
-of the pre-reacted molecule template, and the second column is the
-corresponding atom ID of the post-reacted molecule template
-
-The bondingIDs section will always contain two atom IDs, corresponding
-to the bonding atom pairs of the pre-reacted map file. The
-Equivalences section will contain as many rows as there are atoms in
-the pre- and post-reacted molecule templates. The edgeIDs section is
-optional, but would contain an atom ID for each edge atom in the
-pre-reacted molecule template.
-
 A sample map file is given below:
 
 :line
 
-# This is a map file :pre
+# this is a map file :pre
 
 2 edgeIDs
 7 equivalences :pre
 
 BondingIDs :pre
 
-3 5 :pre
+3
+5 :pre
 
 EdgeIDs :pre
 
-1 7 :pre
+1
+7 :pre
 
 Equivalences :pre
 
@@ -264,13 +232,13 @@ within LAMMPS that store bond topology are updated to reflect the
 post-reacted molecule template. All force fields with fixed bonds,
 angles, dihedrals or impropers are supported.
 
-A few capabilities to note: 1) You may specify as many 'react'
+A few capabilities to note: 1) You may specify as many {react}
 arguments as desired. For example, you could break down a complicated
 reaction mechanism into several reaction steps, each defined by its
-own 'react' argument. 2) While typically a bond is formed or removed
+own {react} argument. 2) While typically a bond is formed or removed
 between the bonding atom pairs specified in the pre-reacted molecule
 template, this is not required. 3) By reversing the order of the pre-
-and post- reacted molecule templates in another 'react' argument, you
+and post- reacted molecule templates in another {react} argument, you
 can allow for the possibility of one or more reverse reactions.
 
 The optional keywords deal with the probability of a given reaction
@@ -304,7 +272,7 @@ you can use the internally-created dynamic group named
 would thermostat the group of all atoms currently involved in a
 reaction:
 
-fix 1 bond_react_MASTER_group temp/rescale 1 300 300 10 1
+fix 1 bond_react_MASTER_group temp/rescale 1 300 300 10 1 :pre
 
 NOTE: This command must be added after the fix bond/react command, and
 will apply to all reactions.
@@ -324,10 +292,11 @@ local command.
 [Restart, fix_modify, output, run start/stop, minimize info:]
 
 No information about this fix is written to "binary restart
-files"_restart.html.  None of the "fix_modify"_fix_modify.html options
-are relevant to this fix.
+files"_restart.html, aside from internally-created per-atom
+properties. None of the "fix_modify"_fix_modify.html options are
+relevant to this fix.
 
-This fix computes one statistic for each 'react' argument that it
+This fix computes one statistic for each {react} argument that it
 stores in a global vector, of length 'number of react arguments', that
 can be accessed by various "output
 commands"_Section_howto.html#howto_15. The vector values calculated by
@@ -359,5 +328,5 @@ The option defaults are stabilization = no, stabilize_steps = 60
 
 :line
 
-:link(Gissinger) [(Gissinger)] Gissinger, Jensen and Wise, Polymer,
-128, 211 (2017).
+:link(Gissinger)
+[(Gissinger)] Gissinger, Jensen and Wise, Polymer, 128, 211 (2017).