Merge branch 'master' into reset-invalid-image-flags

doc/src/Build_development.rst

@@ -111,8 +111,10 @@ error margin).  The status of this automated testing can be viewed on
 The unit testing facility is integrated into the CMake build process
 of the LAMMPS source code distribution itself.  It can be enabled by
 setting ``-D ENABLE_TESTING=on`` during the CMake configuration step.
-It requires the `PyYAML <http://pyyaml.org/>`_ library and development
-headers to compile and will download and compile a recent version of the
+It requires the `YAML <http://pyyaml.org/>`_ library and development
+headers (if not found locally a recent version will be downloaded
+and compiled transparently) to compile and will download and compile
+a specific recent version of the
 `Googletest <https://github.com/google/googletest/>`_ C++ test framework
 for implementing the tests.
 

doc/src/Commands_pair.rst

@@ -241,6 +241,7 @@ OPT.
    * :doc:`spin/dipole/long <pair_spin_dipole>`
    * :doc:`spin/dmi <pair_spin_dmi>`
    * :doc:`spin/exchange <pair_spin_exchange>`
+   * :doc:`spin/exchange/biquadratic <pair_spin_exchange>`
    * :doc:`spin/magelec <pair_spin_magelec>`
    * :doc:`spin/neel <pair_spin_neel>`
    * :doc:`srp <pair_srp>`

doc/src/Errors_warnings.rst

@@ -119,7 +119,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
    :doc:`pair style zero <pair_zero>` with a suitable cutoff or use :doc:`comm_modify cutoff <comm_modify>`.
 
 *Communication cutoff is shorter than a bond length based estimate. This may lead to errors.*
-
    Since LAMMPS stores topology data with individual atoms, all atoms
    comprising a bond, angle, dihedral or improper must be present on any
    sub-domain that "owns" the atom with the information, either as a

doc/src/Howto_github.rst

@@ -72,7 +72,7 @@ explained in more detail here: `feature branch workflow <https://www.atlassian.c
 
 **Feature branches**
 
-First of all, create a clone of your version on github on your local
+First of all, create a clone of your version on GitHub on your local
 machine via HTTPS:
 
 .. code-block:: bash
@@ -155,7 +155,7 @@ useful message that explains the change.
 
 .. code-block:: bash
 
-     $ git commit -m 'Finally updated the github tutorial'
+     $ git commit -m 'Finally updated the GitHub tutorial'
 
 After the commit, the changes can be pushed to the same branch on GitHub:
 

doc/src/Howto_walls.rst

@@ -67,5 +67,5 @@ rotate.
 
 The only frictional idealized walls currently in LAMMPS are flat or
 curved surfaces specified by the :doc:`fix wall/gran <fix_wall_gran>`
-command.  At some point we plan to allow regoin surfaces to be used as
+command.  At some point we plan to allow region surfaces to be used as
 frictional walls, as well as triangulated surfaces.

doc/src/Packages_details.rst

@@ -1036,9 +1036,11 @@ the usual manner via MD.  Various pair, fix, and compute styles.
 * :doc:`pair_style spin/dipole/long <pair_spin_dipole>`
 * :doc:`pair_style spin/dmi <pair_spin_dmi>`
 * :doc:`pair_style spin/exchange <pair_spin_exchange>`
+* :doc:`pair_style spin/exchange/biquadratic <pair_spin_exchange>`
 * :doc:`pair_style spin/magelec <pair_spin_magelec>`
 * :doc:`pair_style spin/neel <pair_spin_neel>`
 * :doc:`fix nve/spin <fix_nve_spin>`
+* :doc:`fix langevin/spin <fix_langevin_spin>`
 * :doc:`fix precession/spin <fix_precession_spin>`
 * :doc:`compute spin <compute_spin>`
 * :doc:`neb/spin <neb_spin>`

doc/src/atc_output.rst

@@ -14,7 +14,7 @@ Syntax
 * AtC fixID = ID of :doc:`fix atc <fix_atc>` instance
 * *output* or *output index* = name of the AtC sub-command
 * filename_prefix = prefix for data files (for *output*)
-* frequency = frequency of output in time-steps (for *output*)
+* frequency = frequency of output in timesteps (for *output*)
 * optional keywords for *output*:
 
   - text = creates text output of index, step and nodal variable values for unique nodes

doc/src/fix_filter_corotate.rst

@@ -56,7 +56,7 @@ is slightly modified only for the computation of long-range forces. A
 good cluster decomposition constitutes in building clusters which
 contain the fastest covalent bonds inside clusters.
 
-If the clusters are chosen suitably, the :doc:`run_style respa <run_style>` is stable for outer time-steps of at least 8fs.
+If the clusters are chosen suitably, the :doc:`run_style respa <run_style>` is stable for outer timesteps of at least 8fs.
 
 ----------
 

doc/src/fix_precession_spin.rst

@@ -62,7 +62,7 @@ with:
 
 The field value in Tesla is multiplied by the gyromagnetic
 ratio, :math:`g \cdot \mu_B/\hbar`, converting it into a precession frequency in
-rad.THz (in metal units and with :math:`\mu_B = 5.788 eV/T`).
+rad.THz (in metal units and with :math:`\mu_B = 5.788\cdot 10^{-5}` eV/T).
 
 As a comparison, the figure below displays the simulation of a
 single spin (of norm :math:`\mu_i = 1.0`) submitted to an external

doc/src/fix_rx.rst

@@ -90,10 +90,10 @@ accepted, *h* is increased by a proportional amount, and the next ODE step is be
 Otherwise, *h* is shrunk and the ODE step is repeated.
 
 Run-time diagnostics are available for the rkf45 ODE solver. The frequency
-(in time-steps) that diagnostics are reported is controlled by the last (optional)
+(in timesteps) that diagnostics are reported is controlled by the last (optional)
 12th argument. A negative frequency means that diagnostics are reported once at the
 end of each run. A positive value N means that the diagnostics are reported once
-per N time-steps.
+per N timesteps.
 
 The diagnostics report the average # of integrator steps and RHS function evaluations
 and run-time per ODE as well as the average/RMS/min/max per process. If the

doc/src/pair_spin_exchange.rst

@@ -1,14 +1,19 @@
 .. index:: pair_style spin/exchange
+.. index:: pair_style spin/exchange/biquadratic
 
 pair_style spin/exchange command
 ================================
 
+pair_style spin/exchange/biquadratic command
+============================================
+
 Syntax
 """"""
 
 .. code-block:: LAMMPS
 
    pair_style spin/exchange cutoff
+   pair_style spin/exchange/biquadratic cutoff
 
 * cutoff = global cutoff pair (distance in metal units)
 
@@ -19,7 +24,11 @@ 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
+   pair_coeff 1 2 exchange 6.0 -0.01575 0.0 1.965 offset yes
+
+   pair_style spin/exchange/biquadratic 4.0
+   pair_coeff * * biquadratic 4.0 0.05 0.03 1.48 0.05 0.03 1.48 offset no
+   pair_coeff 1 2 biquadratic 6.0 -0.01 0.0 1.9 0.0 0.1 19
 
 Description
 """""""""""
@@ -31,69 +40,163 @@ pairs of magnetic spins:
 
    H_{ex} = -\sum_{i,j}^N J_{ij} (r_{ij}) \,\vec{s}_i \cdot \vec{s}_j
 
-where :math:`\vec{s}_i` and :math:`\vec{s}_j` are two neighboring magnetic spins of two particles,
-:math:`r_{ij} = \vert \vec{r}_i - \vec{r}_j \vert` is the inter-atomic distance between the two
-particles. The summation is over pairs of nearest neighbors.
-:math:`J(r_{ij})` is a function defining the intensity and the sign of the exchange
-interaction for different neighboring shells. This function is defined as:
+where :math:`\vec{s}_i` and :math:`\vec{s}_j` are two unit vectors representing
+the magnetic spins of two particles (usually atoms), and
+:math:`r_{ij} = \vert \vec{r}_i - \vec{r}_j \vert` is the inter-atomic distance
+between those two particles. The summation is over pairs of nearest neighbors.
+:math:`J(r_{ij})` is a function defining the intensity and the sign of the
+exchange interaction for different neighboring shells.
+
+Style *spin/exchange/biquadratic* computes a biquadratic exchange interaction
+between pairs of magnetic spins:
 
 .. math::
 
-    {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})
+   H_{bi} = -\sum_{i, j}^{N} {J}_{ij} \left(r_{ij} \right)\,
+                      \vec{s}_{i}\cdot \vec{s}_{j}
+                      -\sum_{i, j}^{N} {K}_{ij} \left(r_{ij} \right)\,
+                      \left(\vec{s}_{i}\cdot
+                      \vec{s}_{j}\right)^2
 
-where :math:`a`, :math:`b` and :math:`d` are the three constant coefficients defined in the associated
-"pair_coeff" command, and :math:`R_c` is the radius cutoff associated to
-the pair interaction (see below for more explanations).
+where :math:`\vec{s}_i`,  :math:`\vec{s}_j`,  :math:`r_{ij}` and
+:math:`J(r_{ij})` have the same definitions as above, and :math:`K(r_{ij})` is
+a second function, defining the intensity and the sign of the biquadratic term.
 
-The coefficients :math:`a`, :math:`b`, and :math:`d` need to be fitted so that the function above matches with
-the value of the exchange interaction for the :math:`N` neighbor shells taken into account.
-Examples and more explanations about this function and its parameterization are reported
-in :ref:`(Tranchida) <Tranchida3>`.
+The interatomic dependence of :math:`J(r_{ij})` and :math:`K(r_{ij})` in both
+interactions above is defined by the following function:
+
+.. math::
+
+    {f}\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})
+
+where :math:`a`, :math:`b` and :math:`d` are the three constant coefficients
+defined in the associated "pair_coeff" command, and :math:`R_c` is the radius
+cutoff associated to the pair interaction (see below for more explanations).
+
+The coefficients :math:`a`, :math:`b`, and :math:`d` need to be fitted so that
+the function above matches with the value of the exchange interaction for the
+:math:`N` neighbor shells taken into account.
+Examples and more explanations about this function and its parameterization
+are reported in :ref:`(Tranchida) <Tranchida3>`.
+
+When a *spin/exchange/biquadratic* pair style is defined, six coefficients
+(three for :math:`J(r_{ij})`, and three for :math:`K(r_{ij})`) have to be
+fitted.
 
 From this exchange interaction, each spin :math:`i` will be submitted
-to a magnetic torque :math:`\vec{\omega}`, and its associated atom can be submitted to a
-force :math:`\vec{F}` for spin-lattice calculations (see :doc:`fix nve/spin <fix_nve_spin>`),
-such as:
+to a magnetic torque :math:`\vec{\omega}_{i}`, and its associated atom can be
+submitted to a force :math:`\vec{F}_{i}` for spin-lattice calculations (see
+:doc:`fix nve/spin <fix_nve_spin>`), such as:
 
 .. math::
 
    \vec{\omega}_{i} = \frac{1}{\hbar} \sum_{j}^{Neighb} {J}
    \left(r_{ij} \right)\,\vec{s}_{j}
    ~~{\rm and}~~
-   \vec{F}_{i} = \sum_{j}^{Neighb} \frac{\partial {J} \left(r_{ij} \right)}{ \partial r_{ij}} \left( \vec{s}_{i}\cdot \vec{s}_{j} \right) \vec{e}_{ij}
+   \vec{F}_{i} = \sum_{j}^{Neighb} \frac{\partial {J} \left(r_{ij} \right)}{
+   \partial r_{ij}} \left( \vec{s}_{i}\cdot \vec{s}_{j} \right) \vec{e}_{ij}
 
-with :math:`\hbar` the Planck constant (in metal units), and :math:`\vec{e}_{ij} = \frac{\vec{r}_i - \vec{r}_j}{\vert \vec{r}_i-\vec{r}_j \vert}` the unit
+with :math:`\hbar` the Planck constant (in metal units), and :math:`\vec{e}_{ij}
+= \frac{\vec{r}_i - \vec{r}_j}{\vert \vec{r}_i-\vec{r}_j \vert}` the unit
 vector between sites :math:`i` and :math:`j`.
+Equivalent forces and magnetic torques are generated for the biquadratic term
+when a *spin/exchange/biquadratic* pair style is defined.
 
 More details about the derivation of these torques/forces are reported in
 :ref:`(Tranchida) <Tranchida3>`.
 
-For the *spin/exchange* pair style, the following coefficients must be defined
-for each pair of atoms types via the :doc:`pair_coeff <pair_coeff>` command as in
-the examples above, or in the data file or restart files read by the
-:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>` commands, and
-set in the following order:
+For the *spin/exchange* and *spin/exchange/biquadratic* pair styles, the
+following coefficients must be defined for each pair of atoms types via the
+:doc:`pair_coeff <pair_coeff>` command as in the examples above, or in the data
+file or restart files read by the :doc:`read_data <read_data>` or
+:doc:`read_restart <read_restart>` commands, and set in the following order:
 
 * :math:`R_c` (distance units)
 * :math:`a`  (energy units)
 * :math:`b`  (adim parameter)
 * :math:`d`  (distance units)
 
-Note that :math:`R_c` is the radius cutoff of the considered exchange interaction,
-and :math:`a`, :math:`b` and :math:`d` are the three coefficients performing the parameterization
-of the function :math:`J(r_{ij})` defined above.
+for the *spin/exchange* pair style, and:
+
+* :math:`R_c` (distance units)
+* :math:`a_j`  (energy units)
+* :math:`b_j`  (adim parameter)
+* :math:`d_j`  (distance units)
+* :math:`a_k`  (energy units)
+* :math:`b_k`  (adim parameter)
+* :math:`d_k`  (distance units)
+
+for the *spin/exchange/biquadratic* pair style.
+
+Note that :math:`R_c` is the radius cutoff of the considered exchange
+interaction, and :math:`a`, :math:`b` and :math:`d` are the three coefficients
+performing the parameterization of the function :math:`J(r_{ij})` defined
+above (in the *biquadratic* style, :math:`a_j`, :math:`b_j`, :math:`d_j` and
+:math:`a_k`, :math:`b_k`, :math:`d_k` are the coefficients of :math:`J(r_{ij})`
+and :math:`K(r_{ij})` respectively).
+
 
 None of those coefficients is optional. If not specified, the
 *spin/exchange* pair style cannot be used.
 
 ----------
 
+**Offsetting magnetic forces and energies**\ :
+
+For spin-lattice simulation, it can be useful to offset the
+mechanical forces and energies generated by the exchange
+interaction.
+The *offset* keyword allows to apply this offset.
+By setting *offset* to *yes*, the energy definitions above are
+replaced by:
+
+.. math::
+
+   H_{ex} = -\sum_{i,j}^N J_{ij} (r_{ij}) \,[ \vec{s}_i \cdot \vec{s}_j-1 ]
+
+for the *spin/exchange* pair style, and:
+
+.. math::
+
+   H_{bi} = -\sum_{i, j}^{N} {J}_{ij} \left(r_{ij} \right)\,
+                      [ \vec{s}_{i}\cdot \vec{s}_{j} -1 ]
+                      -\sum_{i, j}^{N} {K}_{ij} \left(r_{ij} \right)\,
+                      [ \left(\vec{s}_{i}\cdot
+                      \vec{s}_{j}\right)^2 -1]
+
+for the *spin/exchange/biquadratic* pair style.
+
+Note that this offset only affects the calculation of the energy
+and mechanical forces. It does not modify the calculation of the
+precession vectors (and thus does no impact the purely magnetic
+properties).
+This ensures that when all spins are aligned, the magnetic energy
+and the associated mechanical forces (and thus the pressure
+generated by the magnetic potential) are null.
+
+.. note::
+  This offset term can be very important when calculations such as
+  equations of state (energy vs volume, or energy vs pressure) are
+  being performed. Indeed, setting the *offset* term ensures that
+  at the ground state of the crystal and at the equilibrium magnetic
+  configuration (typically ferromagnetic), the pressure is null,
+  as expected.
+  Otherwise, magnetic forces could generate a residual pressure.
+
+When the *offset* option is set to *no*, no offset is applied
+(also corresponding to the default option).
+
+----------
+
 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 :doc:`Build package <Build_package>` doc page for more info.
+atom_style "spin" was declared.
+See the :doc:`Build package <Build_package>` doc page for more info.
 
 Related commands
 """"""""""""""""
@@ -105,7 +208,7 @@ Default
 """""""
 
 
-none
+The default *offset* keyword value is *no*.
 
 ----------
 

doc/src/pair_style.rst

@@ -305,6 +305,7 @@ accelerated styles exist.
 * :doc:`spin/dipole/long <pair_spin_dipole>` -
 * :doc:`spin/dmi <pair_spin_dmi>` -
 * :doc:`spin/exchange <pair_spin_exchange>` -
+* :doc:`spin/exchange/biquadratic <pair_spin_exchange>` -
 * :doc:`spin/magelec <pair_spin_magelec>` -
 * :doc:`spin/neel <pair_spin_neel>` -
 * :doc:`srp <pair_srp>` -