lammps/doc/fix_atom_swap.txt

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line

fix atom_swap command :h3

[Syntax:]

fix ID group-ID atom_swap N X seed T keyword values ... :pre

ID, group-ID are documented in "fix"_fix.html command :ulb,l
atom_swap = style name of this fix command :l
N = invoke this fix every N steps :l
X = number of swaps to attempt every N steps :l
seed = random # seed (positive integer) :l
T = scaling temperature of the MC swaps (temperature units) :l
one or more keyword/value pairs may be appended to args :l
keyword = {types} or {delta_mu} or {ke} or {semi-grand} or {region} :l
  {types} values = two or more atom types
  {delta_mu} values = number_of_types-1 relative chemical potentials (energy units)
  {ke} value = {no} or {yes}
    {no} = no conservation of kinetic energy after atom swaps
    {yes} = kinetic energy is conserved after atom swaps
  {semi-grand} value = {no} or {yes}
    {no} = particle type counts and fractions conserved
    {yes} = semi-grand canonical ensemble, particle fractions not conserved
  {region} value = region-ID
    region-ID = ID of region to use as an exchange/move volume :pre
:ule

[Examples:]

fix 2 all atom/swap 1 1 29494 300.0 ke no types 1 2
fix atom_swap_fix all atom/swap 100 1 12345 298.0 region my_swap_region types 5 6 
fix SGMC all atom/swap 1 100 345 1.0 semi-grand yes types 1 2 3 delta_mu 4.3 -5.0 :pre

[Description:]

This fix performs Monte Carlo swaps of atoms of one given atom type with atoms
of the other given atom types. The specified T is used in the Metropolis criterion
dictating swap probabilities. 

Perform X swaps of atoms of one type with atoms of another type according to a
Monte Carlo probability. Swap candidates must be in the fix group, must be in
the region (if specified), and must be of one of the listed types. Swaps are
attempted between candidates that are chosen randomly with equal probability 
among the candidate atoms. Swaps are not attempted between atoms of the same 
type since nothing would happen.

All atoms in the simulation domain can be moved using regular time 
integration displacements, e.g. via "fix_nvt"_fix_nvt.html, resulting
in a hybrid MC+MD simulation. A smaller-than-usual timestep size 
may be needed when running such a hybrid simulation, especially if 
the swapped atoms are not well equilibrated.

The {types} keyword is required. At least two atom types must be specified.

The {ke} keyword can be set to {no} to turn off kinetic energy conservation 
for swaps. The default is {yes}, which means that swapped atoms have their 
velocities scaled by the ratio of the masses of the swapped atom types. This
ensures that the kinetic energy of each atom 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 "(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}, all atoms in the fix group are eligible for 
attempted conversion to one of the given types, even if its current type is 
not one of the given types. An attempt is made to switch the selected atom to
one of the listed {types} with equal probability. Acceptance of each attempt 
depends upon the Metropolis criterion.

The {delta_mu} keyword allows users to specify non-zero chemical potentials
for each of the atom types. All chemical potentials are relative to the first
atom type, so no value is given for the first atom type. These parameters are
useful for semi-grand canonical ensemble simulations where it may be 
desirable to actively control the composition of the system. When given,
there must be ntypes-1 values given, where ntypes is the number of atom
types in the simulated system. Note that a value for delta_mu is required for
all atom types when using {semi-grand}, even for atom types not listed 
following the {types} keyword. This is because when using {semi-grand}, it is
possible that any of the atom types in the system could be part of the fix
group and therefore are eligible for swapping to one of the listed atom types.

This command may optionally use the {region} keyword to define
swap volume.  The specified region must have been 
previously defined with a "region"_region.html 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
swapping.

This fix checks to ensure all atoms of the given types have the same
atomic charge. LAMMPS doesn't 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.

Since this fix computes total potential energies before and after
proposed swaps, so even complicated potential energy calculations are 
OK, including the following:

  long-range electrostatics (kspace)
  many body pair styles
  hybrid pair styles
  eam pair styles
  triclinic systems 
  need to include potential energy contributions from other fixes :ul

Some fixes have an associated potential energy. Examples of such fixes
include: "efield"_fix_efield.html, "gravity"_fix_gravity.html, 
"addforce"_fix_addforce.html, "langevin"_fix_langevin.html, 
"restrain"_fix_restrain.html, "temp/berendsen"_fix_temp_berendsen.html, 
"temp/rescale"_fix_temp_rescale.html, and "wall fixes"_fix_wall.html. 
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 "fix_modify"_fix_modify.html {energy} option for
that fix.  The doc pages for individual "fix"_fix.html 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 "binary restart
files"_restart.html.  This includes information about the random
number generator seed, the next timestep for MC exchanges, etc.  See
the "read_restart"_read_restart.html 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.

None of the "fix_modify"_fix_modify.html options are relevant to this
fix.

This fix computes a global vector of length 2, which can be accessed
by various "output commands"_Section_howto.html#howto_15.  The vector
values are the following global cumulative quantities:

1 = swap attempts
2 = swap successes :ul

The vector values calculated by this fix are "extensive".

No parameter of this fix can be used with the {start/stop} keywords of
the "run"_run.html command.  This fix is not invoked during "energy
minimization"_minimize.html.

[Restrictions:]

This fix is part of the MC package.  It is only enabled if LAMMPS was
built with that package.  See the "Making
LAMMPS"_Section_start.html#start_3 section for more info.

[Related commands:]

"fix_nvt"_fix_nvt.html, "neighbor"_neighbor.html, 
"fix_deposit"_fix_deposit.html, "fix_evaporate"_fix_evaporate.html,
"delete_atoms"_delete_atoms.html, "fix_gcmc"_fix_gcmc.html

[Default:]

The option defaults are ke = yes, semi-grand = no, delta_mu = 0.0 for 
all atom types.

:line

:link(Sadigh)
[(Sadigh)] B Sadigh, P Erhart, A Stukowski, A Caro, E Martinez, and 
L Zepeda-Ruiz, Phys. Rev. B, 85, 184203 (2012).