Merge branch 'master' into collected-small-changes

doc/src/Eqs/fix_integration_spin_stdecomposition.tex

@@ -0,0 +1,40 @@
+\documentclass[preview]{standalone}
+\usepackage{varwidth}
+\usepackage[utf8x]{inputenc}
+\usepackage{amsmath,amssymb,amsthm,bm,tikz}
+\usetikzlibrary{automata,arrows,shapes,snakes}
+\begin{document}
+\begin{varwidth}{50in}
+\begin{tikzpicture}
+
+%Global
+\node (v1) at (0,6.0) [draw,thick,minimum width=0.2cm,minimum height=0.2cm] { $\bm{v} \leftarrow \bm{v}+L_v.\Delta t/2$ };
+\node (s1) at (0,4.5) [draw,thick,minimum width=0.2cm,minimum height=0.2cm] { $\bm{s} \leftarrow \bm{s}+L_s.\Delta t/2$ };
+\node (r)  at (0,3.0) [draw,thick,minimum width=0.2cm,minimum height=0.2cm] { $\bm{r} \leftarrow \bm{r}+L_r.\Delta t$ };
+\node (s2) at (0,1.5) [draw,thick,minimum width=0.2cm,minimum height=0.2cm] { $\bm{s} \leftarrow \bm{s}+L_s.\Delta t/2$ };
+\node (v2) at (0,0.0) [draw,thick,minimum width=0.2cm,minimum height=0.2cm] { $\bm{v} \leftarrow \bm{v}+L_v.\Delta t/2$ };
+
+\draw[line width=2pt, ->] (v1) -- (s1);
+\draw[line width=2pt, ->] (s1) -- (r);
+\draw[line width=2pt, ->] (r) -- (s2);
+\draw[line width=2pt, ->] (s2) -- (v2);
+
+%Spin
+\node (s01) at (6,6.0) [draw,thick,minimum width=0.2cm,minimum height=0.2cm] {$\bm{s}_0 \leftarrow \bm{s}_0+L_{s_0}.\Delta t/4$ };
+\node (sN1) at (6,4.5) [draw,thick,minimum width=0.2cm,minimum height=0.2cm] {$\bm{s}_{\rm N-1}\leftarrow\bm{s}_{\rm N-1}+L_{s_{\rm N-1}}.\Delta t/4$};
+\node (sN)  at (6,3.0) [draw,thick,minimum width=0.2cm,minimum height=0.2cm] {$\bm{s}_{\rm N} \leftarrow \bm{s}_{\rm N}+L_{s_{\rm N}}.\Delta t/2$ };
+\node (sN2) at (6,1.5) [draw,thick,minimum width=0.2cm,minimum height=0.2cm] {$\bm{s}_{\rm N-1}\leftarrow\bm{s}_{\rm N-1}+L_{s_{\rm N-1}}.\Delta t/4$};
+\node (s02) at (6,0.0) [draw,thick,minimum width=0.2cm,minimum height=0.2cm] {$\bm{s}_0 \leftarrow \bm{s}_0+L_{s_0}.\Delta t/4$ };
+
+\draw[line width=2pt,dashed, ->] (s01) -- (sN1);
+\draw[line width=2pt, ->] (sN1) -- (sN);
+\draw[line width=2pt, ->] (sN) -- (sN2);
+\draw[line width=2pt,dashed, ->] (sN2) -- (s02);
+
+%from Global to Spin
+\draw[line width=2pt, dashed, ->] (s1) -- (s01.west);
+\draw[line width=2pt, dashed, ->] (s1) -- (s02.west);
+
+\end{tikzpicture}
+\end{varwidth}
+\end{document}

doc/src/Eqs/fix_langevin_spin_sLLG.tex

@@ -0,0 +1,14 @@
+\documentclass[preview]{standalone}
+\usepackage{varwidth}
+\usepackage[utf8x]{inputenc}
+\usepackage{amsmath, amssymb, graphics, setspace}
+
+\begin{document}
+\begin{varwidth}{50in}
+  \begin{equation}
+    \frac{d \vec{s}_{i}}{dt} = \frac{1}{\left(1+\lambda^2 \right)} \left( \left(
+    \vec{\omega}_{i} +\vec{\eta} \right) \times \vec{s}_{i} + \lambda\, \vec{s}_{i}
+  \times\left( \vec{\omega}_{i} \times\vec{s}_{i} \right) \right), \nonumber
+  \end{equation}
+\end{varwidth}
+\end{document}

doc/src/Eqs/force_spin_aniso.tex

@@ -0,0 +1,11 @@
+\documentclass[preview]{standalone}
+\usepackage{varwidth}
+\usepackage[utf8x]{inputenc}
+\usepackage{amsmath,amssymb,amsthm,bm}
+\begin{document}
+\begin{varwidth}{50in}
+  \begin{equation}
+    \bm{H}_{aniso}  = -\sum_{{ i}=1}^{N} K_{an}(\bm{r}_{i})\, \left( \vec{s}_{i} \cdot \vec{n}_{i} \right)^2, \nonumber
+  \end{equation}
+\end{varwidth}
+\end{document}

doc/src/Eqs/force_spin_zeeman.tex

@@ -0,0 +1,11 @@
+\documentclass[preview]{standalone}
+\usepackage{varwidth}
+\usepackage[utf8x]{inputenc}
+\usepackage{amsmath,amssymb,amsthm,bm}
+\begin{document}
+\begin{varwidth}{50in}
+  \begin{equation}
+    \bm{H}_{zeeman} = -\mu_{B}\mu_0\sum_{i=0}^{N}g_{i} \vec{s}_{i} \cdot \vec{H}_{ext} \nonumber 
+  \end{equation}
+\end{varwidth}
+\end{document}

doc/src/Eqs/pair_spin_dmi_interaction.tex

@@ -0,0 +1,16 @@
+\documentclass[preview]{standalone}
+\usepackage{varwidth}
+\usepackage[utf8x]{inputenc}
+\usepackage{amsmath,amssymb,amsthm,bm}
+\begin{document}
+\begin{varwidth}{50in}
+  \begin{equation}
+    \bm{H}_{dm} = -\sum_{{ i,j}=1,i\neq j}^{N} 
+    \left( \vec{e}_{ij} \times \vec{D} \right)
+    \cdot\left(\vec{s}_{i}\times \vec{s}_{j}\right), 
+    \nonumber
+  \end{equation}
+\end{varwidth}
+\end{document}
+    \vec{D}\left(r_{ij}\right) 
+    {\rm ~and~}  \vec{D}\left(r_{ij}\right) = \vec{e}_{ij} \times \vec{D}  

doc/src/Eqs/pair_spin_exchange_forces.tex

@@ -0,0 +1,14 @@
+\documentclass[preview]{standalone}
+\usepackage{varwidth}
+\usepackage[utf8x]{inputenc}
+\usepackage{amsmath,amssymb,amsthm,bm}
+\begin{document}
+\begin{varwidth}{50in}
+  \begin{equation}
+    \vec{F}^{i} = \sum_{j}^{Neighbor} \frac{\partial {J} \left(r_{ij} \right)}{
+    \partial r_{ij}} \left( \vec{s}_{i}\cdot \vec{s}_{j} \right) \vec{r}_{ij}  
+    ~~{\rm and}~~ \vec{\omega}^{i} = \frac{1}{\hbar} \sum_{j}^{Neighbor} {J} 
+    \left(r_{ij} \right)\,\vec{s}_{j} \nonumber
+  \end{equation}
+\end{varwidth}
+\end{document}

doc/src/Eqs/pair_spin_exchange_function.tex

@@ -0,0 +1,13 @@
+\documentclass[preview]{standalone}
+\usepackage{varwidth}
+\usepackage[utf8x]{inputenc}
+\usepackage{amsmath, amssymb, graphics, setspace}
+
+\begin{document}
+\begin{varwidth}{50in}
+  \begin{equation}
+    {J}\left( r_{ij} \right) = 4 a \left( \frac{r_{ij}}{d}  \right)^2 \left( 1 - b \left( \frac{r_{ij}}{d}  \right)^2 \right) e^{-\left( \frac{r_{ij}}{d}  
+    \right)^2 }\Theta (R_c - r_{ij}) \nonumber
+  \end{equation}
+\end{varwidth}
+\end{document}

doc/src/Eqs/pair_spin_exchange_interaction.tex

@@ -0,0 +1,11 @@
+\documentclass[preview]{standalone}
+\usepackage{varwidth}
+\usepackage[utf8x]{inputenc}
+\usepackage{amsmath,amssymb,amsthm,bm}
+\begin{document}
+\begin{varwidth}{50in}
+  \begin{equation}
+    \bm{H}_{exchange} ~=~ -\sum_{i,j,i\neq j}^{N} {J} \left(r_{ij} \right)\, \vec{s}_{i}\cdot \vec{s}_{j} \nonumber
+  \end{equation}
+\end{varwidth}
+\end{document}

doc/src/Eqs/pair_spin_me_forces.tex

@@ -0,0 +1,13 @@
+\documentclass[preview]{standalone}
+\usepackage{varwidth}
+\usepackage[utf8x]{inputenc}
+\usepackage{amsmath,amssymb,amsthm,bm}
+\begin{document}
+\begin{varwidth}{50in}
+  \begin{equation}
+    \vec{F}^{i} = -\sum_{j}^{Neighbor} \left( \vec{s}_{i}\times \vec{s}_{j} \right)
+    \times \vec{E} ~~{\rm and}~~ \vec{\omega}^{i} = -\frac{1}{\hbar} 
+    \sum_{j}^{Neighbor} \vec{s}_j \times \left(\vec{E}\times r_{ij} \right),\nonumber
+  \end{equation}
+\end{varwidth}
+\end{document}

doc/src/Eqs/pair_spin_me_interaction.tex

@@ -0,0 +1,12 @@
+\documentclass[preview]{standalone}
+\usepackage{varwidth}
+\usepackage[utf8x]{inputenc}
+\usepackage{amsmath,amssymb,amsthm,bm}
+\begin{document}
+\begin{varwidth}{50in}
+  \begin{equation}
+    \vec{\omega}_i = -\frac{1}{\hbar} \sum_{j}^{Neighb} \vec{s}_{j}\times\vec{D}(r_{ij}) ~~{\rm and}~~
+    \vec{F}_i = -\sum_{j}^{Neighb} \frac{\partial D(r_{ij})}{\partial r_{ij}} \left(\vec{s}_{i}\times \vec{s}_{j} \right) \cdot \vec{r}_{ij}, \nonumber
+  \end{equation}
+\end{varwidth}
+\end{document}

doc/src/Eqs/pair_spin_neel_functions.tex

@@ -0,0 +1,13 @@
+\documentclass[preview]{standalone}
+\usepackage{varwidth}
+\usepackage[utf8x]{inputenc}
+\usepackage{amsmath,amssymb,amsthm,bm}
+\begin{document}
+\begin{varwidth}{50in}
+  \begin{eqnarray}
+    g_1(r_{ij}) &=& g(r_{ij}) + \frac{12}{35} q(r_{ij}) \nonumber \\
+    q_1(r_{ij}) &=& \frac{9}{5} q(r_{ij}) \nonumber \\
+    q_2(r_{ij}) &=& - \frac{2}{5} q(r_{ij}) \nonumber
+  \end{eqnarray}
+\end{varwidth}
+\end{document}

doc/src/Eqs/pair_spin_neel_interaction.tex

@@ -0,0 +1,16 @@
+\documentclass[preview]{standalone}
+\usepackage{varwidth}
+\usepackage[utf8x]{inputenc}
+\usepackage{amsmath,amssymb,amsthm,bm}
+\begin{document}
+\begin{varwidth}{50in}
+  \begin{equation}
+    \mathcal{H}_{N\acute{e}el}=-\sum_{{ i,j=1,i\neq j}}^N g_1(r_{ij})\left(({\bm e}_{ij}\cdot {\bm s}_{i})({\bm e}_{ij}
+    \cdot {\bm s}_{j})-\frac{{\bm s}_{i}\cdot{\bm s}_{j}}{3} \right)
+    +q_1(r_{ij})\left( ({\bm e}_{ij}\cdot {\bm s}_{i})^2 -\frac{{\bm s}_{i}\cdot{\bm s}_{j}}{3}\right)
+    \left( ({\bm e}_{ij}\cdot {\bm s}_{i})^2 -\frac{{\bm s}_{i}\cdot{\bm s}_{j}}{3} \right)
+    + q_2(r_{ij}) \Big( ({\bm e}_{ij}\cdot {\bm s}_{i}) ({\bm e}_{ij}\cdot {\bm s}_{j})^3 + ({\bm e}_{ij}\cdot
+    {\bm s}_{j}) ({\bm e}_{ij}\cdot {\bm s}_{i})^3\Big) \nonumber
+  \end{equation}
+\end{varwidth}
+\end{document}

doc/src/Section_commands.txt

@@ -594,6 +594,7 @@ USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.
 "indent"_fix_indent.html,
 "latte"_fix_latte.html,
 "langevin (k)"_fix_langevin.html,
+"langevin/spin"_fix_langevin_spin.hmtl,
 "lineforce"_fix_lineforce.html,
 "momentum (k)"_fix_momentum.html,
 "move"_fix_move.html,
@@ -617,6 +618,7 @@ USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.
 "nve/line"_fix_nve_line.html,
 "nve/noforce"_fix_nve_noforce.html,
 "nve/sphere (o)"_fix_nve_sphere.html,
+"nve/spin"_fix_nve_spin.html,
 "nve/tri"_fix_nve_tri.html,
 "nvt (iko)"_fix_nh.html,
 "nvt/asphere (o)"_fix_nvt_asphere.html,
@@ -629,6 +631,7 @@ USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.
 "planeforce"_fix_planeforce.html,
 "poems"_fix_poems.html,
 "pour"_fix_pour.html,
+"precession/spin"_fix_precession_spin.html,
 "press/berendsen"_fix_press_berendsen.html,
 "print"_fix_print.html,
 "property/atom (k)"_fix_property_atom.html,
@@ -835,6 +838,7 @@ KOKKOS, o = USER-OMP, t = OPT.
 "sna/atom"_compute_sna_atom.html,
 "snad/atom"_compute_sna_atom.html,
 "snav/atom"_compute_sna_atom.html,
+"spin"_compute_spin.html,
 "stress/atom"_compute_stress_atom.html,
 "temp (k)"_compute_temp.html,
 "temp/asphere"_compute_temp_asphere.html,
@@ -1029,6 +1033,10 @@ KOKKOS, o = USER-OMP, t = OPT.
 "snap (k)"_pair_snap.html,
 "soft (go)"_pair_soft.html,
 "sw (giko)"_pair_sw.html,
+"spin/dmi"_pair_spin_dmi.html,
+"spin/exchange"_pair_spin_exchange.html,
+"spin/magelec"_pair_spin_magelec.html,
+"spin/neel"_pair_spin_neel.html,
 "table (gko)"_pair_table.html,
 "tersoff (giko)"_pair_tersoff.html,
 "tersoff/mod (gko)"_pair_tersoff_mod.html,

doc/src/Section_howto.txt

@@ -36,7 +36,8 @@ This section describes how to perform common tasks using LAMMPS.
 6.24 "Setting parameters for the kspace_style pppm/disp command"_#howto_24
 6.25 "Polarizable models"_#howto_25
 6.26 "Adiabatic core/shell model"_#howto_26
-6.27 "Drude induced dipoles"_#howto_27 :all(b)
+6.27 "Drude induced dipoles"_#howto_27
+6.28 "Magnetic spins"_#howto_28 :all(b)
 
 The example input scripts included in the LAMMPS distribution and
 highlighted in "Section 7"_Section_example.html also show how to
@@ -2906,6 +2907,53 @@ with a Coulomb pair style. It may be useful to use {coul/long/cs} or
 similar from the CORESHELL package if the core and Drude particle come
 too close, which can cause numerical issues.
 
+:line
+
+6.28 Magnetic spins :link(howto_28),h4
+
+The magnetic spin simualtions are enabled by the SPIN package, whose
+implementation is detailed in "Tranchida"_#Tranchida7.
+
+The model representents the simulation of atomic magnetic spins coupled 
+to lattice vibrations. The dynamics of those magnetic spins can be used 
+to simulate a broad range a phenomena related to magneto-elasticity, or 
+or to study the influence of defects on the magnetic properties of 
+materials. 
+
+The magnetic spins are interacting with each others and with the 
+lattice via pair interactions. Typically, the magnetic exchange 
+interaction can be defined using the 
+"pair/spin/exchange"_pair_spin_exchange.html command. This exchange
+applies a magnetic torque to a given spin, considering the orientation
+of its neighboring spins and their relative distances. 
+It also applies a force on the atoms as a function of the spin 
+orientations and their associated inter-atomic distances. 
+ 
+The command "fix precession/spin"_fix_precession_spin.html allows to
+apply a constant magnetic torque on all the spins in the system. This
+torque can be an external magnetic field (Zeeman interaction), or an
+uniaxial magnetic anisotropy. 
+
+A Langevin thermostat can be applied to those magnetic spins using 
+"fix langevin/spin"_fix_langevin_spin.html. Typically, this thermostat 
+can be coupled to another Langevin thermostat applied to the atoms 
+using "fix langevin"_fix_langevin.html in order to simulate 
+thermostated spin-lattice system. 
+
+The magnetic Gilbert damping can also be applied using "fix 
+langevin/spin"_fix_langevin_spin.html. It allows to either dissipate 
+the thermal energy of the Langevin thermostat, or to perform a 
+relaxation of the magnetic configuration toward an equilibrium state.
+
+All the computed magnetic properties can be outputed by two main 
+commands. The first one is "compute spin"_compute_spin.html, that 
+enables to evaluate magnetic averaged quantities, such as the total 
+magnetization of the system along x, y, or z, the spin temperature, or
+the magnetic energy. The second command is "compute 
+property/atom"_compute_property_atom.html. It enables to output all the
+per atom magnetic quantities. Typically, the orientation of a given 
+magnetic spin, or the magnetic force acting on this spin.
+
 :line
 :line
 
@@ -2957,3 +3005,7 @@ Phys, 79, 926 (1983).
 
 :link(howto-Lamoureux)
 [(Lamoureux and Roux)] G. Lamoureux, B. Roux, J. Chem. Phys 119, 3025 (2003)
+
+:link(Tranchida7)
+[(Tranchida)] Tranchida, Plimpton, Thibaudeau and Thompson, 
+arXiv preprint arXiv:1801.10233, (2018).

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 {spin} or {tri} or {template} or {hybrid} :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/compute_property_atom.txt

@@ -19,6 +19,7 @@ input = one or more atom attributes :l
                         x, y, z, xs, ys, zs, xu, yu, zu, ix, iy, iz,
                         vx, vy, vz, fx, fy, fz,
                         q, mux, muy, muz, mu,
+			sp, spx, spy, spz, fmx, fmy, fmz,
                         radius, diameter, omegax, omegay, omegaz,
                         angmomx, angmomy, angmomz,
                         shapex,shapey, shapez,
@@ -46,6 +47,9 @@ input = one or more atom attributes :l
       q = atom charge
       mux,muy,muz = orientation of dipole moment of atom
       mu = magnitude of dipole moment of atom
+      sp = atomic magnetic spin moment
+      spx, spy, spz = direction of the atomic magnetic spin
+      fmx, fmy, fmz = magnetic force
       radius,diameter = radius,diameter of spherical particle
       omegax,omegay,omegaz = angular velocity of spherical particle
       angmomx,angmomy,angmomz = angular momentum of aspherical particle
@@ -82,7 +86,8 @@ input = one or more atom attributes :l
 
 compute 1 all property/atom xs vx fx mux
 compute 2 all property/atom type
-compute 1 all property/atom ix iy iz :pre
+compute 1 all property/atom ix iy iz 
+compute 3 all property/atom sp spx spy spz :pre
 
 [Description:]
 
@@ -152,6 +157,10 @@ The vector or array values will be in whatever "units"_units.html the
 corresponding attribute is in, e.g. velocity units for vx, charge
 units for q, etc.
 
+For the spin quantities, sp is in the units of the Bohr magneton, spx,
+spy, and spz are adimentional quantities, and fmx, fmy and fmz are 
+given in rad.THz. 
+
 [Restrictions:] none
 
 [Related commands:]

doc/src/compute_spin.txt

@@ -0,0 +1,78 @@
+"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
+
+compute spin command :h3
+
+[Syntax:]
+
+compute ID group-ID compute/spin :pre
+
+ID, group-ID are documented in "compute"_compute.html command
+compute/spin = style name of this compute command :ul
+
+[Examples:]
+
+compute out_mag all compute/spin :pre
+
+[Description:]
+
+Define a computation that calculates magnetic quantities for a system 
+of atoms having spins.
+
+This compute calculates 6 magnetic quantities.
+
+The three first quantities are the x,y and z coordinates of the total magnetization.
+
+The fourth quantity is the norm of the total magnetization.
+
+The fifth quantity is the magnetic energy. 
+
+The sixth one is referred to as the spin temperature, according
+to the work of "(Nurdin)"_#Nurdin1. 
+  
+The simplest way to output the results of the compute spin calculation
+is to define some of the quantities as variables, and to use the thermo and
+thermo_style commands, for example:
+
+compute out_mag		all compute/spin :pre
+
+variable mag_z      	equal c_out_mag\[3\]
+variable mag_norm	equal c_out_mag\[4\]
+variable temp_mag      	equal c_out_mag\[6\] :pre
+
+thermo          	10
+thermo_style    	custom step v_mag_z v_mag_norm v_temp_mag :pre
+
+This serie of commands evaluates the total magnetization along z, the norm of 
+the total magnetization, and the magnetic temperature. Three variables are 
+assigned to those quantities. The thermo and thermo_style commands print them 
+every 10 timesteps.
+
+
+[Output info:]
+
+The array values are "intensive".  The array values will be in
+metal units ("units"_units.html).
+
+[Restrictions:] 
+
+The {spin} compute is part of the SPIN package.
+This compute is only enabled if LAMMPS was built with this package.
+See the "Making LAMMPS"_Section_start.html#start_3 section for more info.
+The atom_style has to be "spin" for this compute to be valid.
+
+[Related commands:] none
+
+
+[Default:] none
+
+:line
+
+:link(Nurdin1)
+[(Nurdin)] Nurdin and Schotte Phys Rev E, 61(4), 3579 (2000)
+

doc/src/computes.txt

@@ -96,6 +96,7 @@ Computes :h1
    compute_smd_ulsph_stress
    compute_smd_vol
    compute_sna_atom
+   compute_spin
    compute_stress_atom
    compute_tally
    compute_tdpd_cc_atom

doc/src/fix_langevin_spin.txt

@@ -0,0 +1,102 @@
+"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 langevin/spin command :h3
+
+[Syntax:]
+
+fix ID group-ID langevin/spin T Tdamp seed :pre
+
+ID, group-ID are documented in "fix"_fix.html command :ulb,l
+langevin/spin = style name of this fix command :l
+T = desired temperature of the bath (temperature units, K in metal units) :l
+Tdamp = transverse magnetic damping parameter (adim) :l
+seed = random number seed to use for white noise (positive integer) :l
+:ule
+
+[Examples:]
+
+fix 2 all langevin/spin 300.0 0.01 21 :pre
+
+[Description:]
+
+Apply a Langevin thermostat as described in "(Mayergoyz)"_#Mayergoyz1 to the 
+magnetic spins associated to the atoms. 
+Used with "fix nve/spin"_fix_nve_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:
+
+:c,image(Eqs/fix_langevin_spin_sLLG.jpg)
+
+with lambda the transverse damping, and eta a random verctor.
+This equation is referred to as the stochastic Landau-Lifshitz-Gilbert (sLLG) 
+equation.
+
+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)"_#Tranchida2.
+
+Note: due to the form of the sLLG equation, this fix has to be defined just
+before the nve/spin fix (and after all other magnetic fixes). 
+As an example:
+
+fix 1 all precession/spin zeeman 0.01 0.0 0.0 1.0
+fix 2 all langevin/spin 300.0 0.01 21 
+fix 3 all nve/spin lattice yes :pre
+
+is correct, but defining a force/spin command after the langevin/spin command
+would give an error message. 
+
+Note: The random # {seed} must be a positive integer.  A Marsaglia random
+number generator is used.  Each processor uses the input seed to
+generate its own unique seed and its own stream of random numbers.
+Thus the dynamics of the system will not be identical on two runs on
+different numbers of processors.
+
+:line
+
+[Restart, fix_modify, output, run start/stop, minimize info:]
+
+No information about this fix is written to "binary restart
+files"_restart.html.  Because the state of the random number generator
+is not saved in restart files, this means you cannot do "exact"
+restarts with this fix, where the simulation continues on the same as
+if no restart had taken place.  However, in a statistical sense, a
+restarted simulation should produce the same behavior.
+
+This fix is not invoked during "energy minimization"_minimize.html.
+
+[Restrictions:]
+
+The {langevin/spin} fix is part of the SPIN 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 nve/spin}
+when {fix langevin/spin} is enabled. 
+
+This fix has to be the last defined magnetic fix before the time
+integration fix (e.g. {fix nve/spin}). 
+
+[Related commands:]
+
+"fix nve/spin"_fix_nve_spin.html, "fix precession/spin"_fix_precession_spin.html
+
+[Default:] none
+
+:line
+
+:link(Mayergoyz1)
+[(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).

doc/src/fix_nve_spin.txt

@@ -0,0 +1,76 @@
+"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 nve/spin command :h3
+
+[Syntax:]
+
+fix ID group-ID nve/spin keyword values :pre
+
+ID, group-ID are documented in "fix"_fix.html command :ulb,l
+nve/spin = style name of this fix command :l
+keyword = {lattice} :l
+  {lattice} value = {no} or {yes} :pre
+:ule
+
+[Examples:]
+
+fix 3 all nve/spin lattice yes
+fix 1 all nve/spin lattice no :pre
+
+[Description:]
+
+Perform a symplectic integration for the spin or spin-lattice system.
+
+The {lattice} keyword defines if the spins are integrated on a lattice 
+of fixed atoms (lattice = no), or if atoms are moving (lattice = yes).
+
+By default (lattice = yes), a spin-lattice integration is performed.
+
+The {nve/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 method enables this scheme for parallel calculations. 
+The implementation of this sectoring algorithm is reported 
+in "(Tranchida)"_#Tranchida1.
+
+:line
+
+[Restrictions:]
+
+This fix style can only be used if LAMMPS was built with the
+SPIN package. See the "Making LAMMPS"_Section_start.html#start_3
+section for more info on packages.
+
+To use the spin algorithm, it is necessary to define a map with 
+the atom_modify command. Typically, by adding the command:
+
+atom_modify map array :pre
+
+before you create the simulation box. Note that the keyword "hash"
+instead of "array" is also valid.
+
+[Related commands:]
+
+"atom_style spin"_atom_style.html, "fix nve"_fix_nve.html
+
+[Default:] none
+
+:line
+
+:link(Omelyan1)
+[(Omelyan)] Omelyan, Mryglod, and Folk. Phys. Rev. Lett. 
+86(5), 898. (2001).
+
+:link(Tranchida1)
+[(Tranchida)] Tranchida, Plimpton, Thibaudeau and Thompson,
+arXiv preprint arXiv:1801.10233, (2018).

doc/src/fix_precession_spin.txt

@@ -0,0 +1,87 @@
+"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 precession/spin command :h3
+
+[Syntax:]
+
+fix ID group precession/spin style args :pre
+
+ID, group are documented in "fix"_fix.html command :ulb,l
+precession/spin = style name of this fix command :l
+style = {zeeman} or {anisotropy} :l
+  {zeeman} args = H x y z 
+    H = intensity of the magnetic field (in Tesla)
+    x y z = vector direction of the field
+  {anisotropy} args = K x y z
+    K = intensity of the magnetic anisotropy (in eV)
+    x y z = vector direction of the anisotropy :pre
+:ule
+
+[Examples:]
+
+fix 1 all precession/spin zeeman 0.1 0.0 0.0 1.0
+fix 1 all precession/spin anisotropy 0.001 0.0 0.0 1.0 
+fix 1 all precession/spin zeeman 0.1 0.0 0.0 1.0 anisotropy 0.001 0.0 0.0 1.0 :pre
+
+[Description:]
+
+Impose a force torque to each magnetic spin in the group.
+
+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.jpg)
+
+with mu0 the vacuum permeability, muB the Bohr magneton (muB = 5.788 eV/T 
+in metal units). 
+
+Style {anisotropy} 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.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.
+
+In both cases, the choice of (x y z) imposes the vector direction for the force. 
+Only the direction of the vector is important; it's length is ignored.  
+
+Both styles can be combined within one single command line. 
+
+:line
+
+[Restart, fix_modify, output, run start/stop, minimize info:]
+
+By default, the energy associated to this fix is not added to the potential 
+energy of the system. 
+The "fix_modify"_fix_modify.html {energy} option is supported by this fix 
+to add this magnetic potential energy to the potential energy of the system, 
+
+fix             1 all precession/spin zeeman 1.0 0.0 0.0 1.0
+fix_modify      1 energy yes :pre
+
+This fix computes a global scalar which can be accessed by various 
+"output commands"_Section_howto.html#howto_15. 
+
+No information about this fix is written to "binary restart
+files"_restart.html.
+
+[Restrictions:]
+
+The {precession/spin} style is part of the SPIN package. 
+This style is only enabled if LAMMPS was built with this package, and
+if the atom_style "spin" was declared. 
+See the "Making LAMMPS"_Section_start.html#start_3 section for more info.
+
+[Related commands:]
+
+"atom_style spin"_atom_style.html
+
+[Default:] none

doc/src/fix_rigid.txt

@@ -241,19 +241,17 @@ molecule ID = 0) surrounding rigid bodies, this may not be what you
 want.  Thus you should be careful to use a fix group that only
 includes atoms you want to be part of rigid bodies.
 
-Bodystyle {custom} is similar to bodystyle {molecule}, however some
-custom properties are used to group atoms into rigid bodies. The
-special case for molecule/body ID = 0 is not available. Possible
-custom properties are an integer property associated with atoms through
-"fix property/atom"_fix_property_atom.html or an atom style variable
-or an atomfile style variable. For the latter two, the variable value
-will be rounded to an integer and then rigid bodies defined from
-those values.
-
-For bodystyle {group}, each of the listed groups is treated as a
-separate rigid body.  Only atoms that are also in the fix group are
-included in each rigid body.  This option is only allowed for the
-{rigid} styles.
+Bodystyle {custom} is similar to bodystyle {molecule} except that it
+is more flexible in using other per-atom properties to define the sets
+of atoms that form rigid bodies.  An integer vector defined by the
+"fix property/atom"_fix_property_atom.txt command can be used.  Or an
+"atom-style or atomfile-style variable"_variable.html can be used; the
+floating-point value produced by the variable is rounded to an
+integer.  As with bondstyle {molecule}, each set of atoms in the fix
+groups with the same integer value is treated as a different rigid
+body.  Since fix property/atom vectors and atom-style variables
+produce values for all atoms, you should be careful to use a fix group
+that only includes atoms you want to be part of rigid bodies.
 
 NOTE: To compute the initial center-of-mass position and other
 properties of each rigid body, the image flags for each atom in the

doc/src/fixes.txt

@@ -61,6 +61,7 @@ Fixes :h1
    fix_langevin
    fix_langevin_drude
    fix_langevin_eff
+   fix_langevin_spin
    fix_latte
    fix_lb_fluid
    fix_lb_momentum
@@ -99,6 +100,7 @@ Fixes :h1
    fix_nve_manifold_rattle
    fix_nve_noforce
    fix_nve_sphere
+   fix_nve_spin
    fix_nve_tri
    fix_nvk
    fix_nvt_asphere
@@ -114,6 +116,7 @@ Fixes :h1
    fix_planeforce
    fix_poems
    fix_pour
+   fix_precession_spin
    fix_press_berendsen
    fix_print
    fix_property_atom

doc/src/lammps.book

@@ -176,6 +176,7 @@ fix_ipi.html
 fix_langevin.html
 fix_langevin_drude.html
 fix_langevin_eff.html
+fix_langevin_spin.html
 fix_latte.html
 fix_lb_fluid.html
 fix_lb_momentum.html
@@ -213,6 +214,7 @@ fix_nve_line.html
 fix_nve_manifold_rattle.html
 fix_nve_noforce.html
 fix_nve_sphere.html
+fix_nve_spin.html
 fix_nve_tri.html
 fix_nvk.html
 fix_nvt_asphere.html
@@ -229,6 +231,7 @@ fix_pimd.html
 fix_planeforce.html
 fix_poems.html
 fix_pour.html
+fix_precession_spin.html
 fix_press_berendsen.html
 fix_print.html
 fix_property_atom.html
@@ -382,6 +385,7 @@ compute_smd_ulsph_strain_rate.html
 compute_smd_ulsph_stress.html
 compute_smd_vol.html
 compute_sna_atom.html
+compute_spin.html
 compute_stress_atom.html
 compute_tally.html
 compute_tdpd_cc_atom.html
@@ -507,6 +511,10 @@ pair_sph_lj.html
 pair_sph_rhosum.html
 pair_sph_taitwater.html
 pair_sph_taitwater_morris.html
+pair_spin_dmi.html
+pair_spin_exchange.html
+pair_spin_magelec.html
+pair_spin_neel.html
 pair_srp.html
 pair_sw.html
 pair_table.html

doc/src/pair_spin_dmi.txt

@@ -0,0 +1,66 @@
+"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
+
+pair_style spin/dmi command :h3
+
+[Syntax:]
+
+pair_style spin/dmi cutoff :pre
+
+cutoff = global cutoff pair (distance in metal units) :ulb,l
+
+:ule
+	
+[Examples:]
+
+pair_style spin/dmi 4.0
+pair_coeff * * dmi 2.6 0.001 1.0 0.0 0.0	
+pair_coeff 1 2 dmi 4.0 0.00109 0.0 0.0 1.0 :pre
+
+[Description:]
+
+Style {spin/dmi} computes the Dzyaloshinskii-Moriya (DM) interaction
+between pairs of magnetic spins: 
+
+:c,image(Eqs/pair_spin_dmi_interaction.jpg)
+
+where si and sj are two neighboring magnetic spins of two particles, 
+eij = (ri - rj)/|ri-rj| is the normalized separation vector between the 
+two particles, and D is the DM vector defining the intensity and the 
+sign of the interaction.
+
+Examples and more explanations about this interaction and its parametrization are 
+reported in "(Tranchida)"_#Tranchida5.
+
+From this DM interaction, each spin i will be submitted to a magnetic torque
+omega and its associated atom to a force F (for spin-lattice calculations only). 
+
+More details about the derivation of these torques/forces are reported in
+"(Tranchida)"_#Tranchida5.
+
+:line
+
+[Restrictions:]
+
+All the {pair/spin} styles are part of the SPIN package. 
+These styles are only enabled if LAMMPS was built with this package, and
+if the atom_style "spin" was declared. 
+See the "Making LAMMPS"_Section_start.html#start_3 section for more info.
+
+[Related commands:]
+
+"atom_style spin"_atom_style.html, "pair_coeff"_pair_coeff.html, 
+"pair_eam"_pair_eam.html,
+
+[Default:] none
+
+:line
+
+:link(Tranchida5)
+[(Tranchida)] Tranchida, Plimpton, Thibaudeau and Thompson,
+arXiv preprint arXiv:1801.10233, (2018).

doc/src/pair_spin_exchange.txt

@@ -0,0 +1,82 @@
+"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
+
+pair_style spin/exchange command :h3
+
+[Syntax:]
+
+pair_style spin/exchange cutoff :pre
+
+cutoff = global cutoff pair (distance in metal units) :ulb,l
+
+:ule
+
+[Examples:]
+
+pair_style spin/exchange 4.0
+pair_coeff * * exchange 4.0 0.0446928 0.003496 1.4885
+pair_coeff 1 2 exchange 6.0 -0.01575 0.0 1.965 :pre
+
+[Description:]
+
+Style {spin/exchange} computes the exchange interaction between 
+pairs of magnetic spins:
+
+: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,
+and J(rij) is a function defining the intensity and the sign of the exchange 
+interaction.
+
+This function is defined as:
+
+: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.
+
+The coefficients a, b, and d 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.
+
+Examples and more explanations about this function and its parametrization are reported
+in "(Tranchida)"_#Tranchida3.
+
+From this exchange interaction, each spin i will be submitted 
+to a magnetic torque omega, and its associated atom can be submitted to a
+force F for spin-lattice calculations (see "fix_nve_spin"_fix_nve_spin.html),
+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)"_#Tranchida3.
+
+:line
+
+[Restrictions:]
+
+All the {pair/spin} styles are part of the SPIN package. 
+These styles are only enabled if LAMMPS was built with this package, and
+if the atom_style "spin" was declared. 
+See the "Making LAMMPS"_Section_start.html#start_3 section for more info.
+
+[Related commands:]
+
+"atom_style spin"_atom_style.html, "pair_coeff"_pair_coeff.html, 
+"pair_eam"_pair_eam.html,
+
+[Default:] none
+
+:line
+
+:link(Tranchida3)
+[(Tranchida)] Tranchida, Plimpton, Thibaudeau and Thompson,
+arXiv preprint arXiv:1801.10233, (2018).

doc/src/pair_spin_magelec.txt

@@ -0,0 +1,73 @@
+"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
+
+pair_style spin/me command :h3
+
+[Syntax:]
+
+pair_style spin/me cutoff :pre
+
+cutoff = global cutoff pair (distance in metal units) :ulb,l
+
+:ule
+
+[Examples:]
+
+pair_style spin/me 4.5
+pair_coeff * * me 4.5 0.00109 1.0 1.0 1.0 :pre
+
+[Description:]
+
+Style {spin/me} computes a magneto-electric interaction between
+pairs of magnetic spins. According to the derivation reported in
+"(Katsura)"_#Katsura1, this interaction is defined as: 
+
+:c,image(Eqs/pair_spin_me_interaction.jpg)
+
+where si and sj are neighboring magnetic spins of two particles,
+eij = (ri - rj)/|ri-rj| is the normalized separation vector between the
+two particles, and E is an electric polarization vector.
+The norm and direction of E are giving the intensity and the
+direction of a screened dielectric atomic polarization (in eV).
+
+From this magneto-electric interaction, each spin i will be submitted
+to a magnetic torque omega, and its associated atom can be submitted to a
+force F for spin-lattice calculations (see "fix_nve_spin"_fix_nve_spin.html),
+such as:
+
+:c,image(Eqs/pair_spin_me_forces.jpg)
+
+with h the Planck constant (in metal units).
+
+More details about the derivation of these torques/forces are reported in
+"(Tranchida)"_#Tranchida4.
+
+:line
+
+[Restrictions:]
+
+All the {pair/spin} styles are part of the SPIN package.
+These styles are only enabled if LAMMPS was built with this package, and
+if the atom_style "spin" was declared.
+See the "Making LAMMPS"_Section_start.html#start_3 section for more info.
+
+[Related commands:]
+
+"atom_style spin"_atom_style.html, "pair_coeff"_pair_coeff.html,
+"pair_spin_exchange"_pair_spin_exchange.html, "pair_eam"_pair_eam.html,
+
+[Default:] none
+
+:line
+
+:link(Katsura1)
+[(Katsura)] H. Katsura, N. Nagaosa, A.V. Balatsky. Phys. Rev. Lett., 95(5), 057205. (2005)
+
+:link(Tranchida4)
+[(Tranchida)] Tranchida, Plimpton, Thibaudeau, and Thompson, 
+arXiv preprint arXiv:1801.10233, (2018).

doc/src/pair_spin_neel.txt

@@ -0,0 +1,81 @@
+"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
+
+pair_style spin/neel command :h3
+
+[Syntax:]
+
+pair_style spin/neel cutoff :pre
+
+cutoff = global cutoff pair (distance in metal units) :ulb,l
+
+:ule
+	
+[Examples:]
+
+pair_style spin/neel 4.0
+pair_coeff * * neel 4.0 0.0048 0.234 1.168 2.6905 0.705 0.652
+pair_coeff 1 2 neel 4.0 0.0048 0.234 1.168 0.0 0.0 1.0 :pre
+
+[Description:]
+
+Style {spin/neel} computes the Neel pair anisotropy model 
+between pairs of magnetic spins: 
+
+:c,image(Eqs/pair_spin_neel_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,
+eij = (ri - rj)/|ri-rj| is their normalized separation vector 
+and g1, q1 and q2 are three functions defining the intensity of the
+dipolar and quadrupolar contributions, with:
+
+:c,image(Eqs/pair_spin_neel_functions.jpg)
+
+With the functions g(rij) and q(rij) defined and fitted according to the same
+Bethe-Slater function used to fit the exchange interaction: 
+
+: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.   
+
+The coefficients a, b, and d need to be fitted so that the function above matches with 
+the values of the magneto-elastic constant of the materials at stake. 
+
+Examples and more explanations about this function and its parametrization are reported 
+in "(Tranchida)"_#Tranchida6. More examples of parametrization will be provided in 
+future work.
+
+From this DM interaction, each spin i will be submitted to a magnetic torque
+omega and its associated atom to a force F (for spin-lattice calculations only). 
+
+More details about the derivation of these torques/forces are reported in
+"(Tranchida)"_#Tranchida6.
+
+:line
+
+[Restrictions:]
+
+All the {pair/spin} styles are part of the SPIN package. 
+These styles are only enabled if LAMMPS was built with this package, and
+if the atom_style "spin" was declared. 
+See the "Making LAMMPS"_Section_start.html#start_3 section for more info.
+
+[Related commands:]
+
+"atom_style spin"_atom_style.html, "pair_coeff"_pair_coeff.html, 
+"pair_eam"_pair_eam.html,
+
+[Default:] none
+
+:line
+
+:link(Tranchida6)
+[(Tranchida)] Tranchida, Plimpton, Thibaudeau and Thompson,
+arXiv preprint arXiv:1801.10233, (2018).

doc/src/pairs.txt

@@ -97,6 +97,10 @@ Pair Styles :h1
    pair_sph_rhosum
    pair_sph_taitwater
    pair_sph_taitwater_morris
+   pair_spin_dmi
+   pair_spin_exchange
+   pair_spin_magelec
+   pair_spin_neel
    pair_srp
    pair_sw
    pair_table