From e076d08ee9c5e113464fa4f1668a19cbe488c107 Mon Sep 17 00:00:00 2001 From: jrgissing Date: Sat, 12 May 2018 14:17:29 -0600 Subject: [PATCH] correctly render doc page --- doc/src/fix_bond_react.txt | 145 ++++++++++++++----------------------- 1 file changed, 56 insertions(+), 89 deletions(-) diff --git a/doc/src/fix_bond_react.txt b/doc/src/fix_bond_react.txt index 4a7c2428c1..c19123c58b 100644 --- a/doc/src/fix_bond_react.txt +++ b/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 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} = 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. @@ -111,9 +112,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 +125,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 +176,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 of map file the +contains one mandatory keyword and one optional keyword. The mandatory +keyword is 'equivalences' and the optional keyword is 'edgeIDs': -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. +N {equivalences} = # of atoms N in the reaction molecule templates +N {edgeIDs} = # of edge atoms N in the pre-reacted molecule template :pre -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 +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 +231,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 @@ -327,7 +294,7 @@ 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. -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 +326,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).