diff --git a/doc/fix_atom_swap.html b/doc/fix_atom_swap.html index 2a1d517a43..6ad468a649 100644 --- a/doc/fix_atom_swap.html +++ b/doc/fix_atom_swap.html @@ -9,153 +9,137 @@
-

fix atom/swap command +

fix atom_swap command

Syntax:

-
fix ID group-ID atom/swap N X type_1 type_2 seed T keyword values ... 
+
fix ID group-ID atom_swap N X seed T keyword values ... 
 

 
 
Examples:
 

-
fix 2 all atom/swap 1 1 1 2 29494 300.0 ke no
-fix atom_swap_fix all atom/swap 100 1 5 6 12345 298.0 region my_swap_region 
+
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 
 

 
Description:
 

-
This fix performs Monte Carlo swaps of atoms of one type with atoms of
-a second type.  The specified temperature T is used to scale the
-energy in the criterion for accepting or rejecting each swap.  The fix
-is invoked once every N steps.  Each time the fix is invoked X
-swap attempts are made, one after the other, bewteen pairs of randomly
-selected atoms.  Two attributes of the atoms in the pair are swapped:
-the atom type and the atom charge (if defined).  Each attempted swap
-is accepted or rejected based on the Metropolis criterion using the
-Boltzmann factor exp(-Edelta / kT), where Edelta is the change in the
-system potential energy due to the swap, k is the Boltzmann constant,
-and T is the specified temperature.
+
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. 
 

-
In addition to the MC swaps, atoms in the simulation domain will move
-via normal dynamic timestepping if a time integration fix is defined,
-e.g. fix_nvt, which will result in a hybrid MC+MD
-simulation.  If a swap produces a poorly equilibrated system, a
-smaller-than-usual timestep size may be needed when running such a
-simulation.
+
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.
 

-
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.
+
All atoms in the simulation domain can be moved using regular time 
+integration displacements, e.g. via fix_nvt, 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, meaning 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 type_1 with an atom of type_2.
-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. Particles of type_1 can independently be converted
-to type_2, and particles of type_2 can independently be converted to type_1.
-Swaps in each direction are attempted half of the time.
+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.
 

-
If the region keyword is not used, all atoms of type_1 and
-type_2 which are in the specified group are candidates for swapping.
-If the region keyword is used, swappable atoms must also be in the
-specified region.  Each time a swap is performed one random atom is
-chosen from the list of candidate type_1 atoms, and one random atom
-from the list of candidate type_2 atoms.  A pair of swapped atoms
-can thus be far apart geometrically.  If multiple swaps are attempted
-in the same timestep, an individual atom may be swapped multiple
-times.
+
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.
 

-
An additional requirement for charged systems is that all swappable
-atoms of type_1 must have the same charge, and likewise for type_2.
-Atoms of type_1 need not have the same charge as atoms of type_2.
+
This command may optionally use the region keyword to define
+swap volume.  The specified region must have been 
+previously defined with a 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.
 

-
Note that this fix computes total potential energies before and after
-attempted swaps, so even systems with complicated potential energy
-calculations can be used, including the following:
+
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.
 

-