Updated documentation and source

doc/src/angle_dipole.txt

@@ -96,16 +96,17 @@ USER-MISC package.  See the "Making LAMMPS"_Section_start.html#start_2_3
 section for more info on packages.
 
 NOTE: In the "Angles" section of the data file, the atom ID 'j'
-corresponding to the dipole to restrain must come before the atom ID
-of the reference atom 'i'. A third atom ID 'k' must also be provided,
-although 'k' is just a 'dummy' atom which can be any atom; it may be
-useful to choose a convention (e.g., 'k'='i') and adhere to it.  For
-example, if ID=1 for the dipolar atom to restrain, and ID=2 for the
-reference atom, the corresponding line in the "Angles" section of the
-data file would read: X X 1 2 2
+defining the direction of the dipole vector to restrain must come
+before the atom ID of the reference atom 'i'. A third atom ID 'k' must
+also be provided to comply with the requirement of a valid angle
+definition. This atom ID k should be chosen to be that of an atom
+bonded to atom 'i' to avoid errors with "lost angle atoms" when running
+in parallel. Since the LAMMPS code checks for valid angle definitions,
+cannot use the same atom ID of either 'i' or 'j' (this was allowed
+and recommended with older LAMMPS versions).
 
 The "newton" command for intramolecular interactions must be "on"
-(which is the default).
+(which is the default except when using some accelerator packages).
 
 This angle style should not be used with SHAKE.
 

doc/src/fix_langevin_spin.txt

@@ -98,5 +98,5 @@ integration fix (e.g. {fix nve/spin}).
 [(Mayergoyz)] I.D. Mayergoyz, G. Bertotti, C. Serpico (2009). Elsevier (2009)
 
 :link(Tranchida2)
-[(Tranchida)] Tranchida, Plimpton, Thibaudeau and Thompson, 
-arXiv preprint arXiv:1801.10233, (2018).
+[(Tranchida)] Tranchida, Plimpton, Thibaudeau and Thompson,
+Journal of Computational Physics, (2018).

doc/src/fix_nve_spin.txt

@@ -73,4 +73,4 @@ instead of "array" is also valid.
 
 :link(Tranchida1)
 [(Tranchida)] Tranchida, Plimpton, Thibaudeau and Thompson,
-arXiv preprint arXiv:1801.10233, (2018).
+Journal of Computational Physics, (2018).

doc/src/pair_atm.txt

@@ -10,16 +10,21 @@ pair_style atm command :h3
 
 [Syntax:]
 
-pair_style atm args = cutoff :pre
+pair_style atm cutoff :pre
+
+cutoff = global cutoff for 3-body interactions (distance units) :ul
 
 [Examples:]
 
 pair_style 2.5
 pair_coeff * * * 0.072 :pre
 
-pair_style	hybrid/overlay lj/cut 6.5 atm 2.5
-pair_coeff	* * lj/cut 1.0 1.0
-pair_coeff	* * atm * 0.072 :pre
+pair_style hybrid/overlay lj/cut 6.5 atm 2.5
+pair_coeff * * lj/cut 1.0 1.0
+pair_coeff 1 1 atm 1 0.064
+pair_coeff 1 1 atm 2 0.080
+pair_coeff 1 2 atm 2 0.100
+pair_coeff 2 2 atm 2 0.125 :pre
 
 [Description:]
 
@@ -28,36 +33,104 @@ potential for the energy E of a system of atoms as
 
 :c,image(Eqs/pair_atm.jpg)
 
-where r12, r23 and r31 are the distances between the atoms,
-gamma1 is included by the sides r12 and r31
-with similar definitions for gamma2 and gamma3,
-nu is the three-body interaction strength (energy times distance^9 units).
+where nu is the three-body interaction strength,
+and the distances between pairs of atoms r12, r23 and r31
+and the angles gamma1, gamma2 and gamma3
+are shown at the diagram:
 
-The {atm} is typically used in compination with some two-body potential
-using "hybrid/overlay"_pair_hybrid.html style as in an example above.
+:c,image(JPG/pair_atm_dia.jpg)
 
-The calculations are not undertaken if the distances between atoms satisfy
-r12 r23 r31 > curoff^3. Virtual cutoff distance based on a user defined
-tolerance tol is not used.
+There is no \"central\" atom, the interaction is symmetric with respect
+to permutation of atom types.
 
-The Axilrod-Teller-Muto potential file must contain entries for all the
-elements listed in the pair_coeff command.  It can also contain
-entries for additional elements not being used in a particular
-simulation; LAMMPS ignores those entries.
+The {atm} potential is typically used in combination with a two-body
+potential using the "pair_style hybrid/overlay"_pair_hybrid.html
+command as in the example above.
 
-For a single-element simulation, only a single entry is required
-(e.g. 1 1 1).  For a two-element simulation, the file must contain 4
-entries (eg. 1 1 1, 1 1 2, 1 2 2, 2 2 2), that
-specify ATM parameters for all combinations of the two elements
-interacting in three-body configurations.  Thus for 3 elements, 10
-entries would be required, etc.
+The potential is calculated if all three atoms are in the
+"neighbor list"_neighbor.html
+and the distances between atoms satisfy r12 r23 r31 > cutoff^3.
+
+The following coefficients must be defined for each pair of atoms
+types via the "pair_coeff"_pair_coeff.html command as in the examples
+above, or in the restart files read by the
+"read_restart"_read_restart.html commands:
+
+K - the type of the third atom
+nu (energy/distance^9 units) :ul
+
+For a single-atom type simulation, only a single entry is required, eg
+
+pair_coeff 1 1 1 nu :pre
+
+where all three atoms are of type 1.
+For a two-atom type simulation, more pair_coeff commands can be used.
+ATM interaction is symmetric with respect to permutation of atoms,
+it is necessary to provide pair_coeff command for one permutation.
+For example, the command
+
+pair_coeff 1 1 2 nu :pre
+
+also implies
+
+pair_coeff 1 2 1 nu
+pair_coeff 2 1 1 nu :pre
+
+Thus, to specify all ATM interactions between two atom types (eg 1 and 2)
+it is sufficient to provide four pair_coeff commands, eg:
+
+pair_coeff 1 1 1 nu1
+pair_coeff 1 1 2 nu2
+pair_coeff 1 2 2 nu3
+pair_coeff 2 2 2 nu4 :pre
+
+For 3 atom types, 10 pair_coeff commands
+(eg 111, 112, 113, 122, 123, 133, 222, 223, 233, 333)
+will describe all possible ATM interactions, etc.
+It is not necessary to provide the pair_coeff commands for interactions
+of all combinations of atom types: if some combination is not defined then
+there is no ATM interaction for this combination and all its permutations.
+
+--------------------
+
+[Steve:]
+
+I think a better syntax for the pair coeff command might be this:
+
+pair_coeff I J v1 v2 ... vN
+
+when 1,2,...N are the number of atom types defined.
+Then there be one pair_coeff command for each type pair,
+the same syntax as all other potentials in LAMMPS use.
+
+[Sergey:]
+
+The reason for my original pair_coeff command syntax is that
+I would like to reserve further arguments for possible extension of
+ATM potential in LAMMPS to further terms in the multipole expansion of
+many-body dispersion interaction.
+For example, the next term would be dipole-dipole-quadrupole, it may be
+activated if the next argument of pair_coeff is present
+without breaking backward compatibility.
+
+Also, the command you propose
+(i) will not account that the value of nu for different permutations
+of atom types is the same, and
+(ii) will make the numbering of atom types messy since there is
+no requirement to supply the values of nu for all triplets.
+
+--------------------
 
 :line
 
-[Shift, table, tail correction, rRESPA info]:
+[Mixing, shift, table, tail correction, restart, rRESPA info]:
 
-This pair style does not support the "pair_modify"_pair_modify.html
-shift, table, and tail options.
+This pair styles do not support the "pair_modify"_pair_modify.html
+mix, shift, table, and tail options.
+
+This pair style writes its information to "binary restart
+files"_restart.html, so pair_style and pair_coeff commands do not need
+to be specified in an input script that reads a restart file.
 
 This pair style can only be used via the {pair} keyword of the
 "run_style respa"_run_style.html command.  It does not support the
@@ -68,8 +141,8 @@ This pair style can only be used via the {pair} keyword of the
 [Restrictions:]
 
 This pair style is part of the MANYBODY 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.
+if LAMMPS was built with that package.  See the "Making
+LAMMPS"_Section_start.html#start_3 section for more info.
 
 [Related commands:]
 
@@ -82,4 +155,4 @@ the "Making LAMMPS"_Section_start.html#start_3 section for more info.
 :link(Axilrod)
 [(Axilrod)]
 Axilrod and Teller, J Chem Phys, 11, 299 (1943);
-Muto, Nippon Sugaku Butsuri Gakkwaishi 17, 629 (1943).
+Muto, Nippon Sugaku-Buturigakkwaishi 17, 629 (1943).

doc/src/pair_spin_dmi.txt

@@ -63,4 +63,4 @@ See the "Making LAMMPS"_Section_start.html#start_3 section for more info.
 
 :link(Tranchida5)
 [(Tranchida)] Tranchida, Plimpton, Thibaudeau and Thompson,
-arXiv preprint arXiv:1801.10233, (2018).
+Journal of Computational Physics, (2018).

doc/src/pair_spin_exchange.txt

@@ -79,4 +79,4 @@ See the "Making LAMMPS"_Section_start.html#start_3 section for more info.
 
 :link(Tranchida3)
 [(Tranchida)] Tranchida, Plimpton, Thibaudeau and Thompson,
-arXiv preprint arXiv:1801.10233, (2018).
+Journal of Computational Physics, (2018).

doc/src/pair_spin_magelec.txt

@@ -70,4 +70,4 @@ See the "Making LAMMPS"_Section_start.html#start_3 section for more info.
 
 :link(Tranchida4)
 [(Tranchida)] Tranchida, Plimpton, Thibaudeau, and Thompson, 
-arXiv preprint arXiv:1801.10233, (2018).
+Journal of Computational Physics, (2018).

doc/src/pair_spin_neel.txt

@@ -78,4 +78,4 @@ See the "Making LAMMPS"_Section_start.html#start_3 section for more info.
 
 :link(Tranchida6)
 [(Tranchida)] Tranchida, Plimpton, Thibaudeau and Thompson,
-arXiv preprint arXiv:1801.10233, (2018).
+Journal of Computational Physics, (2018).

doc/src/run_style.txt

@@ -138,13 +138,19 @@ iterations of level 1 for a single iteration of level 2, N2 is the
 iterations of level 2 per iteration of level 3, etc.  N-1 looping
 parameters must be specified.
 
-The "timestep"_timestep.html command sets the timestep for the
-outermost rRESPA level.  Thus if the example command above for a
-4-level rRESPA had an outer timestep of 4.0 fmsec, the inner timestep
-would be 8x smaller or 0.5 fmsec.  All other LAMMPS commands that
-specify number of timesteps (e.g. "neigh_modify"_neigh_modify.html
-parameters, "dump"_dump.html every N timesteps, etc) refer to the
-outermost timesteps.
+Thus with a 4-level respa setting of "2 2 2" for the 3 loop factors,
+you could choose to have bond interactions computed 8x per large
+timestep, angle interactions computed 4x, pair interactions computed
+2x, and long-range interactions once per large timestep.
+
+The "timestep"_timestep.html command sets the large timestep for the
+outermost rRESPA level.  Thus if the 3 loop factors are "2 2 2" for
+4-level rRESPA, and the outer timestep is set to 4.0 fmsec, then the
+inner timestep would be 8x smaller or 0.5 fmsec.  All other LAMMPS
+commands that specify number of timesteps (e.g. "thermo"_thermo.html
+for thermo output every N steps, "neigh_modify
+delay/every"_neigh_modify.html parameters, "dump"_dump.html every N
+steps, etc) refer to the outermost timesteps.
 
 The rRESPA keywords enable you to specify at what level of the
 hierarchy various forces will be computed.  If not specified, the
@@ -167,11 +173,17 @@ have their force go ramped to 0.0 so the overlap with the next regime
 compute forces for all pairs from 5.0 outward, with those from 5.0 to
 6.0 having their value ramped in an inverse manner.
 
-Only some pair potentials support the use of the {inner} and {middle}
-and {outer} keywords.  If not, only the {pair} keyword can be used
-with that pair style, meaning all pairwise forces are computed at the
-same rRESPA level.  See the doc pages for individual pair styles for
-details.i
+Note that you can use {inner} and {outer} without using {middle} to
+split the pairwise computations into two portions instead of three.
+Unless you are using a very long pairwise cutoff, a 2-way split is
+often faster than a 3-way split, since it avoids too much duplicate
+computation of pairwise interactions near the intermediate cutoffs.
+
+Also note that only a few pair potentials support the use of the
+{inner} and {middle} and {outer} keywords.  If not, only the {pair}
+keyword can be used with that pair style, meaning all pairwise forces
+are computed at the same rRESPA level.  See the doc pages for
+individual pair styles for details.
 
 Another option for using pair potentials with rRESPA is with the
 {hybrid} keyword, which requires the use of the "pair_style hybrid or
@@ -238,12 +250,24 @@ roughly a 1.5 fold speedup over the {verlet} style with SHAKE and a
 
 For non-biomolecular simulations, the {respa} style can be
 advantageous if there is a clear separation of time scales - fast and
-slow modes in the simulation.  Even a LJ system can benefit from
-rRESPA if the interactions are divided by the inner, middle and outer
-keywords.  A 2-fold or more speedup can be obtained while maintaining
-good energy conservation.  In real units, for a pure LJ fluid at
-liquid density, with a sigma of 3.0 angstroms, and epsilon of 0.1
-Kcal/mol, the following settings seem to work well:
+slow modes in the simulation.  For example, a system of slowly-moving
+charged polymer chains could be setup as follows:
+
+timestep 4.0
+run_style respa 2 8 :pre
+
+This is two-level rRESPA with an 8x difference between the short and
+long timesteps.  The bonds, angles, dihedrals will be computed every
+0.5 fs (assuming real units), while the pair and kspace interactions
+will be computed once every 4 fs.  These are the default settings for
+each kind of interaction, so no additional keywords are necessary.
+
+Even a LJ system can benefit from rRESPA if the interactions are
+divided by the inner, middle and outer keywords.  A 2-fold or more
+speedup can be obtained while maintaining good energy conservation.
+In real units, for a pure LJ fluid at liquid density, with a sigma of
+3.0 angstroms, and epsilon of 0.1 Kcal/mol, the following settings
+seem to work well:
 
 timestep  36.0
 run_style respa 3 3 4 inner 1 3.0 4.0 middle 2 6.0 7.0 outer 3 :pre
@@ -271,9 +295,9 @@ more instructions on how to use the accelerated styles effectively.
 [Restrictions:]
 
 The {verlet/split} style can only be used if LAMMPS was built with the
-REPLICA package. Correspondingly the {respa/omp} style is available only
-if the USER-OMP package was included. See the "Making LAMMPS"_Section_start.html#start_3
-section for more info on packages.
+REPLICA package. Correspondingly the {respa/omp} style is available
+only if the USER-OMP package was included. See the "Making
+LAMMPS"_Section_start.html#start_3 section for more info on packages.
 
 Whenever using rRESPA, the user should experiment with trade-offs in
 speed and accuracy for their system, and verify that they are
@@ -287,6 +311,17 @@ conserving energy to adequate precision.
 
 run_style verlet :pre
 
+For run_style respa, the default assignment of interactions
+to rRESPA levels is as follows:
+
+bond forces = level 1 (innermost loop)
+angle forces = same level as bond forces
+dihedral forces = same level as angle forces
+improper forces = same level as dihedral forces
+pair forces = leven N (outermost level)
+kspace forces = same level as pair forces
+inner, middle, outer forces = no default :ul
+
 :line
 
 :link(Tuckerman3)

doc/src/set.txt

@@ -17,6 +17,7 @@ ID = atom ID range or type range or mol ID range or group ID or region ID :l
 one or more keyword/value pairs may be appended :l
 keyword = {type} or {type/fraction} or {mol} or {x} or {y} or {z} or \
           {charge} or {dipole} or {dipole/random} or {quat} or \
+          {spin} or {spin/random} or {quat} or \
           {quat/random} or {diameter} or {shape} or \
           {length} or {tri} or {theta} or {theta/random} or \
           {angmom} or {omega} or \
@@ -43,6 +44,13 @@ keyword = {type} or {type/fraction} or {mol} or {x} or {y} or {z} or \
   {dipole/random} value = seed Dlen
     seed = random # seed (positive integer) for dipole moment orientations
     Dlen = magnitude of dipole moment (dipole units)
+  {spin} values = g x y z
+    g = magnitude of magnetic spin vector (in Bohr magneton's unit)
+    x,y,z = orientation of magnetic spin vector
+    any of x,y,z can be an atom-style variable (see below)
+  {spin/random} value = seed Dlen
+    seed = random # seed (positive integer) for magnetic spin orientations
+    Dlen = magnitude of magnetic spin vector (in Bohr magneton's unit)
   {quat} values = a b c theta
     a,b,c = unit vector to rotate particle around via right-hand rule
     theta = rotation angle (degrees)
@@ -232,6 +240,15 @@ the orientation of a particular atom is the same, regardless of how
 many processors are being used.  This keyword does not allow use of an
 atom-style variable.
 
+Keyword {spin} uses the specified g value to set the magnitude of the
+magnetic spin vectors, and the x,y,z values as components of a vector 
+to set as the orientation of the magnetic spin vectors of the selected 
+atoms.  
+
+Keyword {spin/random} randomizes the orientation of the magnetic spin
+vectors for the selected atoms and sets the magnitude of each to the 
+specified {Dlen} value.  
+
 Keyword {quat} uses the specified values to create a quaternion
 (4-vector) that represents the orientation of the selected atoms.  The
 particles must define a quaternion for their orientation