ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #2992 from lammps/molswap

Browse Source 
Add a new fix mol/swap command
This commit is contained in:
Axel Kohlmeyer
2021-10-13 21:33:52 -04:00
committed by GitHub
parent c322064ff3 c5617dc006
commit a1fb6902d5
31 changed files with 13084 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/src/Commands_fix.rst
View File

@ -104,6 +104,7 @@ OPT.
* :doc:`manifoldforce <fix_manifoldforce>`
* :doc:`mdi/engine <fix_mdi_engine>`
* :doc:`meso/move <fix_meso_move>`
* :doc:`mol/swap <fix_mol_swap>`
* :doc:`momentum (k) <fix_momentum>`
* :doc:`momentum/chunk <fix_momentum>`
* :doc:`move <fix_move>`

1
doc/src/fix.rst
View File

@ -247,6 +247,7 @@ accelerated styles exist.
* :doc:`manifoldforce <fix_manifoldforce>` - restrain atoms to a manifold during minimization
* :doc:`mdi/engine <fix_mdi_engine>` - connect LAMMPS to external programs via the MolSSI Driver Interface (MDI)
* :doc:`meso/move <fix_meso_move>` - move mesoscopic SPH/SDPD particles in a prescribed fashion
* :doc:`mol/swap <fix_mol_swap>` - Monte Carlo atom type swapping with a molecule
* :doc:`momentum <fix_momentum>` - zero the linear and/or angular momentum of a group of atoms
* :doc:`momentum/chunk <fix_momentum>` - zero the linear and/or angular momentum of a chunk of atoms
* :doc:`move <fix_move>` - move atoms in a prescribed fashion

103
doc/src/fix_atom_swap.rst
View File

@ -73,51 +73,51 @@ is the same after the swap as it was before the swap, even though the
atom masses have changed.
The *semi-grand* keyword can be set to *yes* to switch to the
semi-grand canonical ensemble as discussed in :ref:`(Sadigh) <Sadigh>`. This
means that the total number of each particle type does not need to be
conserved. The default is *no*, which means that the only kind of swap
allowed exchanges an atom of one type with an atom of a different
given type. In other words, the relative mole fractions of the swapped
atoms remains constant. Whereas in the semi-grand canonical ensemble,
the composition of the system can change. Note that when using
*semi-grand*, atoms in the fix group whose type is not listed
in the *types* keyword are ineligible for attempted
conversion. An attempt is made to switch
the selected atom (if eligible) to one of the other listed types
with equal probability. Acceptance of each attempt depends upon the Metropolis criterion.
semi-grand canonical ensemble as discussed in :ref:`(Sadigh)
<Sadigh>`. This means that the total number of each particle type does
not need to be conserved. The default is *no*, which means that the
only kind of swap allowed exchanges an atom of one type with an atom
of a different given type. In other words, the relative mole fractions
of the swapped atoms remains constant. Whereas in the semi-grand
canonical ensemble, the composition of the system can change. Note
that when using *semi-grand*, atoms in the fix group whose type is not
listed in the *types* keyword are ineligible for attempted
conversion. An attempt is made to switch the selected atom (if
eligible) to one of the other listed types with equal
probability. Acceptance of each attempt depends upon the Metropolis
criterion.
The *mu* keyword allows users to specify chemical
potentials. This is required and allowed only when using *semi-grand*\ .
All chemical potentials are absolute, so there is one for
each swap type listed following the *types* keyword.
In semi-grand canonical ensemble simulations the chemical composition
of the system is controlled by the difference in these values. So
shifting all values by a constant amount will have no effect
on the simulation.
The *mu* keyword allows users to specify chemical potentials. This is
required and allowed only when using *semi-grand*\ . All chemical
potentials are absolute, so there is one for each swap type listed
following the *types* keyword. In semi-grand canonical ensemble
simulations the chemical composition of the system is controlled by
the difference in these values. So shifting all values by a constant
amount will have no effect on the simulation.
This command may optionally use the *region* keyword to define swap
volume. The specified region must have been previously defined with a
:doc:`region <region>` command. It must be defined with side = *in*\ .
Swap attempts occur only between atoms that are both within the
:doc:`region <region>` command. It must be defined with side = *in*\
. Swap attempts occur only between atoms that are both within the
specified region. Swaps are not otherwise attempted.
You should ensure you do not swap atoms belonging to a molecule, or
LAMMPS will soon generate an error when it tries to find those atoms.
LAMMPS will warn you if any of the atoms eligible for swapping have a
non-zero molecule ID, but does not check for this at the time of
LAMMPS will eventually generate an error when it tries to find those
atoms. LAMMPS will warn you if any of the atoms eligible for swapping
have a non-zero molecule ID, but does not check for this at the time of
swapping.
If not using *semi-grand* this fix checks to ensure all atoms of the
given types have the same atomic charge. LAMMPS does not enforce this
in general, but it is needed for this fix to simplify the
swapping procedure. Successful swaps will swap the atom type and charge
of the swapped atoms. Conversely, when using *semi-grand*, it is assumed that all the atom
types involved in switches have the same charge. Otherwise, charge
would not be conserved. As a consequence, no checks on atomic charges are
performed, and successful switches update the atom type but not the
atom charge. While it is possible to use *semi-grand* with groups of
atoms that have different charges, these charges will not be changed when the
atom types change.
in general, but it is needed for this fix to simplify the swapping
procedure. Successful swaps will swap the atom type and charge of the
swapped atoms. Conversely, when using *semi-grand*, it is assumed that
all the atom types involved in switches have the same
charge. Otherwise, charge would not be conserved. As a consequence, no
checks on atomic charges are performed, and successful switches update
the atom type but not the atom charge. While it is possible to use
*semi-grand* with groups of atoms that have different charges, these
charges will not be changed when the atom types change.
Since this fix computes total potential energies before and after
proposed swaps, so even complicated potential energy calculations are
@ -133,23 +133,24 @@ OK, including the following:
Some fixes have an associated potential energy. Examples of such fixes
include: :doc:`efield <fix_efield>`, :doc:`gravity <fix_gravity>`,
:doc:`addforce <fix_addforce>`, :doc:`langevin <fix_langevin>`,
:doc:`restrain <fix_restrain>`, :doc:`temp/berendsen <fix_temp_berendsen>`,
:doc:`temp/rescale <fix_temp_rescale>`, and :doc:`wall fixes <fix_wall>`.
For that energy to be included in the total potential energy of the
system (the quantity used when performing GCMC moves),
you MUST enable the :doc:`fix_modify <fix_modify>` *energy* option for
that fix. The doc pages for individual :doc:`fix <fix>` commands
specify if this should be done.
:doc:`restrain <fix_restrain>`, :doc:`temp/berendsen
<fix_temp_berendsen>`, :doc:`temp/rescale <fix_temp_rescale>`, and
:doc:`wall fixes <fix_wall>`. For that energy to be included in the
total potential energy of the system (the quantity used when
performing GCMC moves), you MUST enable the :doc:`fix_modify
<fix_modify>` *energy* option for that fix. The doc pages for
individual :doc:`fix <fix>` commands specify if this should be done.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This fix writes the state of the fix to :doc:`binary restart files <restart>`. This includes information about the random
number generator seed, the next timestep for MC exchanges, the number
of exchange attempts and successes etc. See
the :doc:`read_restart <read_restart>` command for info on how to
re-specify a fix in an input script that reads a restart file, so that
the operation of the fix continues in an uninterrupted fashion.
This fix writes the state of the fix to :doc:`binary restart files
<restart>`. This includes information about the random number
generator seed, the next timestep for MC exchanges, the number of
exchange attempts and successes etc. See the :doc:`read_restart
<read_restart>` command for info on how to re-specify a fix in an
input script that reads a restart file, so that the operation of the
fix continues in an uninterrupted fashion.
.. note::
@ -165,12 +166,13 @@ by various :doc:`output commands <Howto_output>`. The vector values are
the following global cumulative quantities:
* 1 = swap attempts
* 2 = swap successes
* 2 = swap accepts
The vector values calculated by this fix are "extensive".
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>`.
the :doc:`run <run>` command. This fix is not invoked during
:doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
@ -184,7 +186,8 @@ Related commands
:doc:`fix nvt <fix_nh>`, :doc:`neighbor <neighbor>`,
:doc:`fix deposit <fix_deposit>`, :doc:`fix evaporate <fix_evaporate>`,
:doc:`delete_atoms <delete_atoms>`, :doc:`fix gcmc <fix_gcmc>`
:doc:`delete_atoms <delete_atoms>`, :doc:`fix gcmc <fix_gcmc>`,
:doc:`fix mol/swap <fix_mol_swap>`
Default
"""""""

170
doc/src/fix_mol_swap.rst Normal file
View File

@ -0,0 +1,170 @@
.. index:: fix mol/swap
fix mol/swap command
=====================
Syntax
""""""
.. parsed-literal::
fix ID group-ID mol/swap N X itype jtype seed T keyword value ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* atom/swap = style name of this fix command
* N = invoke this fix every N steps
* X = number of swaps to attempt every N steps
* itype,jtype = two atom types to swap with each other
* seed = random # seed (positive integer)
* T = scaling temperature of the MC swaps (temperature units)
* zero or more keyword/value pairs may be appended to args
* keyword = *ke*
.. parsed-literal::
*ke* value = *no* or *yes*
*no* = no conservation of kinetic energy after atom swaps
*yes* = kinetic energy is conserved after atom swaps
Examples
""""""""
.. code-block:: LAMMPS
fix 2 all mol/swap 100 1 2 3 29494 300.0 ke no
fix mySwap fluid mol/swap 500 10 1 2 482798 1.0
Description
"""""""""""
This fix performs Monte Carlo swaps of two specified atom types within
a randomly selected molecule. Two possible use cases are as follows.
First, consider a mixture of some molecules with atoms of itype and
other molecules with atoms of jtype. The fix will select a random
molecule and attempt to swap all the itype atoms to jtype for the
first kind of molecule, or all the jtype atoms to itype for the second
kind. Because the swap will only take place if it is energetically
favorable, the fix can be used to determine the miscibility of 2
different kinds of molecules much more quickly than just dynamics
would do it.
Second, consider diblock co-polymers with two types of monomers itype
and jtype. The fix will select a random molecule and attempt to do a
itype <--> jtype swap of all those monomers within the molecule. Thus
the fix can be used to find the energetically favorable fractions of
two flavors of diblock co-polymers.
Intra-molecular swaps of atom types are attempted every N timesteps. On
that timestep, X swaps are attempted. For each attempt a single
molecule ID is randomly selected. The range of possible molecule IDs
from loID to hiID is pre-computed before each run begins. The
loID/hiID is set for the molecule with the smallest/largest ID which
has any itype or jtype atoms in it. Note that if you define a system
with many molecule IDs between loID and hiID which have no itype or
jtype atoms, then the fix will be inefficient at performing swaps.
Also note that if atoms with molecule ID = 0 exist, they are not
considered molecules by this fix; they are assumed to be solvent atoms
or molecules.
Candidate atoms for swapping must also be in the fix group. Atoms
within the selected molecule which are not itype or jtype are ignored.
When an atom is swapped from itype to jtype (or vice versa), if
charges are defined, the charge values for itype versus jtype atoms
are also swapped. This requires that all itype atoms in the system
have the same charge value. Likewise all jtype atoms in the system
must have the same charge value. If this is not the case, LAMMPS
issues a warning that it cannot swap charge values.
If the *ke* keyword is set to yes, which is the default, and the
masses of itype and jtype atoms are different, then when a swap
occurs, the velocity of the swapped atom is rescaled by the sqrt of
the mass ratio, so as to conserve the kinetic energy of the atom.
----------
The potential energy of the entire system is computed before and after
each swap is performed within a single molecule. The specified
temperature T is used in the Metropolis criterion to accept or reject
the attempted swap. If the swap is rejected all swapped values are
reversed.
The potential energy calculations can include systems and models with
the following features:
* manybody pair styles, including EAM
* hybrid pair styles
* long-range electrostatics (kspace)
* triclinic systems
* potential energy contributions from other fixes
For the last bullet point, fixes can have an associated potential
energy. Examples of such fixes include: :doc:`efield <fix_efield>`,
:doc:`gravity <fix_gravity>`, :doc:`addforce <fix_addforce>`,
:doc:`langevin <fix_langevin>`, :doc:`restrain <fix_restrain>`,
:doc:`temp/berendsen <fix_temp_berendsen>`, :doc:`temp/rescale
<fix_temp_rescale>`, and :doc:`wall fixes <fix_wall>`. For that
energy to be included in the total potential energy of the system (the
quantity used for the swap accept/reject decision), you MUST enable
the :doc:`fix_modify <fix_modify>` *energy* option for that fix. The
doc pages for individual :doc:`fix <fix>` commands specify if this
should be done.
.. note::
One comment on computational efficiency. If the cutoff lengths
defined for the pair style are different for itype versus jtype
atoms (for any of their interactions with any other atom type), then
a new neighbor list needs to be generated for every attempted swap.
This is potentially expensive if N is small or X is large.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This fix writes the state of the fix to :doc:`binary restart files
<restart>`. This includes information about the random number
generator seed, the next timestep for MC exchanges, the number of
exchange attempts and successes etc. See the :doc:`read_restart
<read_restart>` command for info on how to re-specify a fix in an
input script that reads a restart file, so that the operation of the
fix continues in an uninterrupted fashion.
.. note::
For this to work correctly, the timestep must **not** be changed
after reading the restart with :doc:`reset_timestep <reset_timestep>`.
The fix will try to detect it and stop with an error.
None of the :doc:`fix_modify <fix_modify>` options are relevant to this
fix.
This fix computes a global vector of length 2, which can be accessed
by various :doc:`output commands <Howto_output>`. The vector values are
the following global cumulative quantities:
* 1 = swap attempts
* 2 = swap accepts
The vector values calculated by this fix are "extensive".
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>`.
Restrictions
""""""""""""
This fix is part of the MC package. It is only enabled if LAMMPS was
built with that package. See the :doc:`Build package <Build_package>`
doc page for more info.
Related commands
""""""""""""""""
:doc:`fix atom/swap <fix_atom_swap>`, :doc:`fix gcmc <fix_gcmc>`
Default
"""""""
The option default is ke = yes.