tx258/lammps-gran-kokkos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update fix_bond_react.rst

Browse Source 
manual rebase
This commit is contained in:
Jacob Gissinger
2021-02-04 13:41:58 -05:00
parent 0927e52dea
commit de5ba601f2
1 changed files with 106 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

170
doc/src/fix_bond_react.rst
View File

@ -35,13 +35,13 @@ Syntax
* react-ID = user-assigned name for the reaction
* react-group-ID = only atoms in this group are considered for the reaction
* Nevery = attempt reaction every this many steps
* Rmin = bonding pair atoms must be separated by more than Rmin to initiate reaction (distance units)
* Rmax = bonding pair atoms must be separated by less than Rmax to initiate reaction (distance units)
* Rmin = initiator atoms must be separated by more than Rmin to initiate reaction (distance units)
* Rmax = initiator atoms must be separated by less than Rmax to initiate reaction (distance units)
* template-ID(pre-reacted) = ID of a molecule template containing pre-reaction topology
* template-ID(post-reacted) = ID of a molecule template containing post-reaction topology
* map_file = name of file specifying corresponding atom-IDs in the pre- and post-reacted templates
* zero or more individual keyword/value pairs may be appended to each react argument
* individual_keyword = *prob* or *max_rxn* or *stabilize_steps* or *custom_charges* or *modify_create*
* individual_keyword = *prob* or *max_rxn* or *stabilize_steps* or *custom_charges* or *molecule* or *modify_create*
.. parsed-literal::
@ -55,6 +55,10 @@ Syntax
*custom_charges* value = *no* or *fragmentID*
no = update all atomic charges (default)
fragmentID = ID of molecule fragment whose charges are updated
*molecule* value = *off* or *inter* or *intra*
off = allow both inter- and intramolecular reactions (default)
inter = search for reactions between molecules with different IDs
intra = search for reactions within the same molecule
*modify_create* keyword values
*fit* value = *all* or *fragmentID*
all = use all eligible atoms for create-atoms fit (default)
@ -180,17 +184,19 @@ timesteps. *Nevery* can be specified with an equal-style
integer.
Three physical conditions must be met for a reaction to occur. First,
a bonding atom pair must be identified within the reaction distance
cutoffs. Second, the topology surrounding the bonding atom pair must
match the topology of the pre-reaction template. Finally, any reaction
constraints listed in the map file (see below) must be satisfied. If
all of these conditions are met, the reaction site is eligible to be
modified to match the post-reaction template.
an initiator atom pair must be identified within the reaction distance
cutoffs. Second, the topology surrounding the initiator atom pair must
match the topology of the pre-reaction template. Only atom types and
bond connectivity are used to identify a valid reaction site (not bond
types, etc.). Finally, any reaction constraints listed in the map file
(see below) must be satisfied. If all of these conditions are met, the
reaction site is eligible to be modified to match the post-reaction
template.
A bonding atom pair will be identified if several conditions are met.
First, a pair of atoms I,J within the specified react-group-ID of type
itype and jtype must be separated by a distance between *Rmin* and
*Rmax*\ . *Rmin* and *Rmax* can be specified with equal-style
An initiator atom pair will be identified if several conditions are
met. First, a pair of atoms I,J within the specified react-group-ID of
type itype and jtype must be separated by a distance between *Rmin*
and *Rmax*\ . *Rmin* and *Rmax* can be specified with equal-style
:doc:`variables <variable>`. For example, these reaction cutoffs can
be a function of the reaction conversion using the following commands:
@ -200,23 +206,30 @@ be a function of the reaction conversion using the following commands:
fix myrxn all bond/react react myrxn1 all 1 0 v_rmax mol1 mol2 map_file.txt
variable rmax equal 3+f_myrxn[1]/100 # arbitrary function of reaction count
It is possible that multiple bonding atom pairs are identified: if the
bonding atoms in the pre-reacted template are 1-2 neighbors, i.e.
directly bonded, the farthest bonding atom partner is set as its
bonding partner; otherwise, the closest potential partner is chosen.
Then, if both an atom I and atom J have each other as their 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 following criteria are used if multiple candidate initiator atom
pairs are identified within the cutoff distance: 1) If the initiator
atoms in the pre-reaction template are not 1-2 neighbors (i.e. not
directly bonded) the closest potential partner is chosen. 2)
Otherwise, if the initiator atoms in the pre-reaction template are 1-2
neighbors (i.e. directly bonded) the farthest potential partner is
chosen. 3) Then, if both an atom I and atom J have each other as their
initiator partners, these two atoms are identified as the initiator
atom pair of the reaction site. Note that it can be helpful to select
unique atom types for the initiator atoms: if an initiator atom pair
is identified, as described in the previous steps, but does not
correspond to the same pair specified in the pre-reaction template, an
otherwise eligible reaction could be prevented from occurring. Once
this unique initiator atom pair is identified for each reaction, there
could be two or more reactions that involve the same 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
involving the overlapping atom. 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
surrounding topology. As described below, the bonding atom pairs of
surrounding topology. As described below, the initiator atom pairs of
the pre-reacted template are specified by atom ID in the map file. The
pre-reacted molecule template should contain as few atoms as possible
while still completely describing the topology of all atoms affected
@ -230,18 +243,18 @@ missing topology with respect to the simulation. For example, the
pre-reacted template may contain an atom that, in the simulation, is
currently connected to the rest of a long polymer chain. These are
referred to as edge atoms, and are also specified in the map file. All
pre-reaction template atoms should be linked to a bonding atom, via at
least one path that does not involve edge atoms. When the pre-reaction
template contains edge atoms, not all atoms, bonds, charges, etc.
specified in the reaction templates will be updated. Specifically,
topology that involves only atoms that are 'too near' to template
edges will not be updated. The definition of 'too near the edge'
depends on which interactions are defined in the simulation. If the
simulation has defined dihedrals, atoms within two bonds of edge atoms
are considered 'too near the edge.' If the simulation defines angles,
but not dihedrals, atoms within one bond of edge atoms are considered
'too near the edge.' If just bonds are defined, only edge atoms are
considered 'too near the edge.'
pre-reaction template atoms should be linked to an initiator atom, via
at least one path that does not involve edge atoms. When the
pre-reaction template contains edge atoms, not all atoms, bonds,
charges, etc. specified in the reaction templates will be updated.
Specifically, topology that involves only atoms that are 'too near' to
template edges will not be updated. The definition of 'too near the
edge' depends on which interactions are defined in the simulation. If
the simulation has defined dihedrals, atoms within two bonds of edge
atoms are considered 'too near the edge.' If the simulation defines
angles, but not dihedrals, atoms within one bond of edge atoms are
considered 'too near the edge.' If just bonds are defined, only edge
atoms are considered 'too near the edge.'
.. note::
@ -298,25 +311,25 @@ The optional keywords are 'edgeIDs', 'deleteIDs', 'chiralIDs' and
The body of the map file contains two mandatory sections and five
optional sections. 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 first optional section begins with the keyword
'EdgeIDs' and lists the atom IDs of edge atoms in the pre-reacted
molecule template. The second optional section begins with the keyword
'DeleteIDs' and lists the atom IDs of pre-reaction template atoms to
delete. The third optional section begins with the keyword 'CreateIDs'
and lists the atom IDs of the post-reaction template atoms to create.
The fourth optional section begins with the keyword 'ChiralIDs' lists
the atom IDs of chiral atoms whose handedness should be enforced. The
fifth optional section begins with the keyword 'Constraints' and lists
additional criteria that must be satisfied in order for the reaction
to occur. Currently, there are five types of constraints available, as
discussed below: 'distance', 'angle', 'dihedral', 'arrhenius', and
'rmsd'.
'InitiatorIDs' and lists the two atom IDs of the initiator 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 first optional section begins with
the keyword 'EdgeIDs' and lists the atom IDs of edge atoms in the
pre-reacted molecule template. The second optional section begins with
the keyword 'DeleteIDs' and lists the atom IDs of pre-reaction
template atoms to delete. The third optional section begins with the
keyword 'CreateIDs' and lists the atom IDs of the post-reaction
template atoms to create. The fourth optional section begins with the
keyword 'ChiralIDs' lists the atom IDs of chiral atoms whose
handedness should be enforced. The fifth optional section begins with
the keyword 'Constraints' and lists additional criteria that must be
satisfied in order for the reaction to occur. Currently, there are
five types of constraints available, as discussed below: 'distance',
'angle', 'dihedral', 'arrhenius', and 'rmsd'.
A sample map file is given below:
@ -329,7 +342,7 @@ A sample map file is given below:
7 equivalences
2 edgeIDs
BondingIDs
InitiatorIDs
3
5
@ -487,6 +500,23 @@ example, the molecule fragment could consist of only the backbone
atoms of a polymer chain. This constraint can be used to enforce a
specific relative position and orientation between reacting molecules.
By default, all constraints must be satisfied for the reaction to
occur. In other words, constraints are evaluated as a series of
logical values using the logical AND operator "&&". More complex logic
can be achieved by explicitly adding the logical AND operator "&&" or
the logical OR operator "||" after a given constraint command. If a
logical operator is specified after a constraint, it must be placed
after all constraint parameters, on the same line as the constraint
(one per line). Similarly, parentheses can be used to group
constraints. The expression that results from concatenating all
constraints should be a valid logical expression that can be read by
the :doc:`variable <variable>` command after converting each
constraint to a logical value. Because exactly one constraint is
allowed per line, having a valid logical expression implies that left
parentheses "(" should only appear before a constraint, and right
parentheses ")" should only appear after a constraint and before any
logical operator.
Once a reaction site has been successfully identified, data structures
within LAMMPS that store bond topology are updated to reflect the
post-reacted molecule template. All force fields with fixed bonds,
@ -496,7 +526,7 @@ 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
between the bonding atom pairs specified in the pre-reacted molecule
between the initiator atoms 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
can allow for the possibility of one or more reverse reactions.
@ -525,12 +555,20 @@ situations, decreasing rather than increasing this parameter will
result in an increase in stability.
The *custom_charges* keyword can be used to specify which atoms'
atomic charges are updated. When the value is set to 'no,' all atomic
atomic charges are updated. When the value is set to 'no', all atomic
charges are updated to those specified by the post-reaction template
(default). Otherwise, the value should be the name of a molecule
fragment defined in the pre-reaction molecule template. In this case,
only the atomic charges of atoms in the molecule fragment are updated.
The *molecule* keyword can be used to force the reaction to be
intermolecular, intramolecular or either. When the value is set to
'off', molecule IDs are not considered when searching for reactions
(default). When the value is set to 'inter', the initiator atoms must
have different molecule IDs in order to be considered for the
reaction. When the value is set to 'intra', only initiator atoms with
the same molecule ID are considered for the reaction.
A few other considerations:
Optionally, you can enforce additional behaviors on reacting atoms.
@ -583,7 +621,7 @@ These is 1 quantity for each react argument:
No parameter of this fix can be used with the *start/stop* keywords
of the :doc:`run <run>` command. This fix is not invoked during :doc:`energy minimization <minimize>`.
When fix bond/react is 'unfixed,' all internally-created groups are
When fix bond/react is 'unfixed', all internally-created groups are
deleted. Therefore, fix bond/react can only be unfixed after unfixing
all other fixes that use any group created by fix bond/react.
@ -606,10 +644,14 @@ Default
"""""""
The option defaults are stabilization = no, prob = 1.0, stabilize_steps = 60,
reset_mol_ids = yes, custom_charges = no, modify_create = no
reset_mol_ids = yes, custom_charges = no, molecule = off, modify_create = no
----------
.. _Gissinger:
**(Gissinger)** Gissinger, Jensen and Wise, Polymer, 128, 211 (2017).
**(Gissinger)** Gissinger, Jensen and Wise, Polymer, 128, 211-217 (2017).
.. _Gissinger2020:
**(Gissinger)** Gissinger, Jensen and Wise, Macromolecules, 53, 22, 9953-9961 (2020).