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

  {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

[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

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

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):

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

fix 1 statted_grp_REACT nvt temp 300 300 100

# optionally, you can customize behavior of reacting atoms,

# by using the internally-created 'bond_react_MASTER_group', like so:

fix 4 bond_react_MASTER_group temp/rescale 1 300 300 10 1

thermo_style custom step temp press density f_myrxns[1] f_myrxns[2]

# two monomer nylon example

# reaction produces a condensed water molecule

units real

boundary p p p

atom_style full

kspace_style pppm 1.0e-4

pair_style lj/class2/coul/long 8.5

angle_style class2

bond_style class2

dihedral_style class2

improper_style class2

read_data tiny_nylon.data

velocity all create 300.0 4928459 dist gaussian

molecule mol1 rxn1_stp1_unreacted.data_template

molecule mol2 rxn1_stp1_reacted.data_template

molecule mol3 rxn1_stp2_unreacted.data_template

molecule mol4 rxn1_stp2_reacted.data_template

thermo 50

# dump 1 all xyz 1 test_vis.xyz

fix myrxns all bond/react stabilization no &

  react rxn1 all 1 0.0 2.9 mol1 mol2 rxn1_stp1_map &

  react rxn2 all 1 0.0 5.0 mol3 mol4 rxn1_stp2_map

fix 1 all nve/limit .03

thermo_style custom step temp press density f_myrxns[1] f_myrxns[2]

# restart 100 restart1 restart2

run 1000

# write_restart restart_longrun

# write_data restart_longrun.data