commit JT 020818

- documentation v1.0
- reorg. of examples

doc/src/atom_style.txt

@@ -15,7 +15,7 @@ atom_style style args :pre
 style = {angle} or {atomic} or {body} or {bond} or {charge} or {dipole} or \
         {dpd} or {edpd} or {mdpd} or {tdpd} or {electron} or {ellipsoid} or \
         {full} or {line} or {meso} or {molecular} or {peri} or {smd} or \
-        {sphere} or {tri} or {template} or {hybrid} :ulb,l
+        {sphere} or {tri} or {template} or {hybrid} or {spin} :ulb,l
   args = none for any style except the following
     {body} args = bstyle bstyle-args
       bstyle = style of body particles
@@ -38,6 +38,7 @@ atom_style full
 atom_style body nparticle 2 10
 atom_style hybrid charge bond
 atom_style hybrid charge body nparticle 2 5
+atom_style spin
 atom_style template myMols 
 atom_style tdpd 2 :pre
 
@@ -89,6 +90,7 @@ quantities.
 {peri} | mass, volume | mesocopic Peridynamic models |
 {smd} | volume, kernel diameter, contact radius, mass | solid and fluid SPH particles |
 {sphere} | diameter, mass, angular velocity | granular models |
+{spin} | magnetic moment | system with magnetic particles |
 {template} | template index, template atom | small molecules with fixed topology |
 {tri} | corner points, angular momentum | rigid bodies |
 {wavepacket} | charge, spin, eradius, etag, cs_re, cs_im | AWPMD :tb(c=3,s=|)
@@ -175,6 +177,9 @@ used for calculating the field variables (e.g. stress and deformation)
 and a contact radius for calculating repulsive forces which prevent
 individual physical bodies from penetrating each other.
 
+For the {spin} style, a magnetic spin is associated to each atom.
+Those spins have a norm (their magnetic moment) and a direction.
+
 The {wavepacket} style is similar to {electron}, but the electrons may
 consist of several Gaussian wave packets, summed up with coefficients
 cs= (cs_re,cs_im).  Each of the wave packets is treated as a separate
@@ -312,6 +317,8 @@ The {meso} style is part of the USER-SPH package for smoothed particle
 hydrodynamics (SPH).  See "this PDF
 guide"_USER/sph/SPH_LAMMPS_userguide.pdf to using SPH in LAMMPS.
 
+The {spin} style is part of the SPIN package.
+
 The {wavepacket} style is part of the USER-AWPMD package for the
 "antisymmetrized wave packet MD method"_pair_awpmd.html.
 

doc/src/fix_force_spin.txt

@@ -36,7 +36,7 @@ Style {zeeman} is used for the simulation of the interaction
 between the magnetic spins in the defined group and an external 
 magnetic field:
 
-:c,image(Eqs/force_spin_zeeman.pdf)
+:c,image(Eqs/force_spin_zeeman.jpg)
 
 with mu0 the vacuum permeability, muB the Bohr magneton (muB = 5.788 eV/T 
 in metal units), 
@@ -44,7 +44,7 @@ in metal units),
 Style {aniso} is used to simulate an easy axis or an easy plane 
 for the magnetic spins in the defined group: 
 
-:c,image(Eqs/force_spin_aniso.pdf)
+:c,image(Eqs/force_spin_aniso.jpg)
 
 with n defining the direction of the anisotropy, and K (in eV) its intensity. 
 If K>0, an easy axis is defined, and if K<0, an easy plane is defined.

doc/src/fix_integration_spin.txt

@@ -10,33 +10,38 @@ fix integration/spin command :h3
 
 [Syntax:]
 
-fix ID group-ID integration/spin style :pre
+fix ID group-ID integration/spin keyword values :pre
 
 ID, group-ID are documented in "fix"_fix.html command :ulb,l
 integration/spin = style name of this fix command :l
-style = {serial} or {mpi} :l
-  {serial} value = factor
-    factor = do thermostat rotational degrees of freedom via the angular momentum and apply numeric scale factor as discussed below :pre
-  {mpi} 
+keyword = {lattice} :l
+  {lattice} value = {no} or {yes} :pre
 :ule
 
 [Examples:]
 
-fix 3 all integration/spin serial
-fix 1 all integration/spin mpi
+fix 3 all integration/spin lattice yes
+fix 1 all integration/spin lattice no :pre
 
 [Description:]
 
-A Suzuki-Trotter decomposition is applied to the integration of the 
-spin-lattice system. 
+Perform a symplectic integration for the spin or spin-lattice system.
 
-:line
+The {lattice} keyword defines if the spins are integrated on a lattice 
+of fixed atoms (lattice = no), or if atoms are moving (lattice = yes).
 
-The {style} value defines if a serial of a parallel 
-algorithm has to be used for the integration. 
+By default (lattice = yes), a spin-lattice integration is performed.
 
-The parallel algorithm uses a sectoring method as 
-described in .
+The {integration/spin} fix applies a Suzuki-Trotter decomposition to 
+the equations of motion of the spin lattice system, following the scheme:
+
+:c,image(Eqs/fix_integration_spin_stdecomposition.jpg)
+
+according to the implementation reported in "(Omelyan)"_#Omelyan1.
+
+A sectoring enables this scheme for parallel calculations. 
+The implementation of this sectoring algorithm is reported in
+"(Tranchida)"_#Tranchida1. 
 
 :line
 
@@ -49,17 +54,16 @@ section for more info on packages.
 
 [Related commands:]
 
-"fix nve"_fix_nve.html, "pair spin"_pair_spin.html, 
-"compute spin"_compute_spin.html, "fix langevin spin"_fix_langevin_spin.html, 
-
+"atom_style spin"_atom_style.html, "fix nve"_fix_nve.html
 
 [Default:] none
 
 :line
 
-:link(Davidchack2)
-[(Davidchack)] R.L Davidchack, T.E. Ouldridge, M.V. Tretyakov. J. Chem. Phys. 142, 144114 (2015).
-:link(Miller2)
-[(Miller)] T. F. Miller III, M. Eleftheriou, P. Pattnaik, A. Ndirango, G. J. Martyna, J. Chem. Phys., 116, 8649-8659 (2002).
-:link(Dunweg3)
-[(Dunweg)] B. Dunweg, W. Paul, Int. J. Mod. Phys. C, 2, 817-27 (1991).
+:link(Omelyan1)
+[(Omelyan)] I.P. Omelyan, I.M. Mryglod, R. Folk. Phys. Rev. Lett. 
+86(5), 898. (2001)
+
+:link(Tranchida1)
+[(Tranchida)] J. Tranchida, S.J. Plimpton, P. Thibaudeau, A.P. Thompson. 
+arXiv preprint arXiv:1801.10233. (2018)

doc/src/fix_langevin_spin.txt

@@ -26,16 +26,22 @@ fix 2 all langevin/spin 300.0 0.01 0.0 21 :pre
 
 [Description:]
 
-Apply a Langevin thermostat as described in "(Mayergoyz)"_#Mayergoyz1
-to the magnetic spins associated to the atoms. 
-Used with "fix integration spin"_fix_integration_spin.html, this 
-command performs Brownian dynamics (BD), apply a random torque 
-and a transverse dissipation to each spin: 
+Apply a Langevin thermostat as described in "(Mayergoyz)"_#Mayergoyz1 to the 
+magnetic spins associated to the atoms. 
+Used with "fix integration spin"_fix_integration_spin.html, this command performs 
+Brownian dynamics (BD). 
+A random torque and a transverse dissipation are applied to each spin i according to
+the following stochastic differential equation:
 
-Rand torque = 
-Transverse dmping = 
-D is proportional to sqrt(Kb T m / (hbar dt damp)) :pre
+:c,image(Eqs/fix_langevin_spin_sLLG.jpg)
 
+with lambda the transverse damping, and eta a random verctor.
+
+The components of eta are drawn from a Gaussian probability law. Their amplitude 
+is defined as a proportion of the temperature of the external thermostat T (in K 
+in metal units).
+
+More details about this implementation are reported in "(Tranchida)"_#Tranchida1.
 
 Note: The random # {seed} must be a positive integer.  A Marsaglia random
 number generator is used.  Each processor uses the input seed to
@@ -59,7 +65,7 @@ This fix is not invoked during "energy minimization"_minimize.html.
 [Restrictions:]
 
 The {langevin/spin} fix is part of the SPIN package.
-These styles are only enabled if LAMMPS was built with this package.
+This style is only enabled if LAMMPS was built with this package.
 See the "Making LAMMPS"_Section_start.html#start_3 section for more info.
 
 The numerical integration has to be performed with {fix/integration/spin} 
@@ -70,22 +76,13 @@ when {langevin/spin} is enabled.
 "fix integration spin"_fix_integration_spin.html, 
 "pair spin"_pair_spin.html
 
-[Default:]
-
-The option defaults are angmom = no, omega = no, scale = 1.0 for all
-types, tally = no, zero = no, gjf = no.
+[Default:] none
 
 :line
 
 :link(Mayergoyz1)
-Mayergoyz, Bertotti, and Serpico (2009). Elsevier (2009)
+[(Mayergoyz)] I.D. Mayergoyz, G. Bertotti, C. Serpico (2009). Elsevier (2009)
 
-
-
-:link(Schneider1)
-[(Schneider)] Schneider and Stoll, Phys Rev B, 17, 1302 (1978).
-
-:link(Gronbech-Jensen)
-[(Gronbech-Jensen)] Gronbech-Jensen and Farago, Mol Phys, 111, 983
-(2013); Gronbech-Jensen, Hayre, and Farago, Comp Phys Comm,
-185, 524 (2014)
+:link(Tranchida1)
+[(Tranchida)] J. Tranchida, S.J. Plimpton, P. Thibaudeau, A.P. Thompson. 
+arXiv preprint arXiv:1801.10233. (2018)

doc/src/pair_spin_exchange.txt

@@ -27,7 +27,7 @@ pair_coeff 1 2 exchange 6.0 -0.01575 0.0 1.965 :pre
 Style {pair/spin/exchange} computes the exchange interaction between 
 pairs of magnetic spins: 
 
-:c,image(Eqs/pair_spin_exchange_interaction.pdf)
+:c,image(Eqs/pair_spin_exchange_interaction.jpg)
 
 where si and sj are two neighboring magnetic spins of two particles, 
 rij = ri - rj is the inter-atomic distance between the two particles,
@@ -36,7 +36,7 @@ interaction.
 
 This function is defined as:
 
-:c,image(Eqs/pair_spin_exchange_function.pdf)
+:c,image(Eqs/pair_spin_exchange_function.jpg)
 
 where a, b and d are the three constant coefficients defined in the associated 
 "pair_coeff" command.   
@@ -44,9 +44,19 @@ where a, b and d are the three constant coefficients defined in the associated
 The coefficients a, b, and c need to be fitted so that the function above matches with 
 the value of the exchange interaction for the N neighbor shells taken into account.
 
-Examles and more explanations about this function and its parametrization are reported 
+Examples and more explanations about this function and its parametrization are reported 
 in "(Tranchida)"_#Tranchida1.
 
+From this exchange interaction, each spin i will be submitted to a magnetic torque
+omega and its associated atom to a force F, such as: 
+
+:c,image(Eqs/pair_spin_exchange_forces.jpg)
+
+with h the Planck constant (in metal units).
+
+More details about the derivation of these torques/forces are reported in
+"(Tranchida)"_#Tranchida1.
+
 :line
 
 [Restrictions:]

src/SPIN/fix_integration_spin.cpp

@@ -98,7 +98,7 @@ FixIntegrationSpin::FixIntegrationSpin(LAMMPS *lmp, int narg, char **arg) :
   if (extra == SPIN && !atom->mumag_flag)
     error->all(FLERR,"Fix integration/spin requires spin attribute mumag");
 
-  if (mpi_flag == 0 && nprocs_tmp == 1)
+  if (mpi_flag == 0 && nprocs_tmp > 1)
     error->all(FLERR,"Illegal fix/integration/spin command");
 
   magpair_flag = 0;