Commit1 JT 070918

- created README in examples/SPIN
- modified doc/src/set.txt to define 'spin' and 'spin/random' keywords

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

examples/SPIN/README

@@ -0,0 +1,20 @@
+This directory contains examples and applications of the SPIN package
+=====================================================================
+
+- the iron, cobalt_hcp, cobalt_fcc and nickel directories provide 
+examples of spin-lattice calculations.
+
+- the bfo repository provides an example of spin dynamics calculation
+performed on a fixed lattice, and applied to the multiferroic 
+material bismuth-oxide. 
+
+- the read_restart directory provides examples allowing to write or 
+read data files, and restart magneto-mechanical simulations.  
+
+- vizualization of the dump files can be achieved using Ovito or 
+VMD. See the vmd repository for help vizualizing results with VMD. 
+
+** Note, the aim of this repository is mainly to provide users with
+examples. Better values and tuning of the magnetic and mechanical 
+interactions can be achieved for more accurate materials 
+simulations. **