diff --git a/doc/src/Bibliography.rst b/doc/src/Bibliography.rst index 0256552332..9f3591dcde 100644 --- a/doc/src/Bibliography.rst +++ b/doc/src/Bibliography.rst @@ -1123,9 +1123,12 @@ Bibliography **(Sun)** Sun, J. Phys. Chem. B, 102, 7338-7364 (1998). -**(Surblys)** +**(Surblys2019)** Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019). +**(Surblys2021)** + Surblys, Matsubara, Kikugawa, Ohara, J Appl Phys 130, 215104 (2021). + **(Sutmann)** Sutmann, Arnold, Fahrenberger, et. al., Physical review / E 88(6), 063308 (2013) diff --git a/doc/src/compute_heat_flux.rst b/doc/src/compute_heat_flux.rst index 94d6f09700..56975adc70 100644 --- a/doc/src/compute_heat_flux.rst +++ b/doc/src/compute_heat_flux.rst @@ -89,13 +89,20 @@ included in the calculation. .. warning:: The compute *heat/flux* has been reported to produce unphysical - values for angle, dihedral and improper contributions + values for angle, dihedral, improper and constraint force contributions when used with :doc:`compute stress/atom `, - as discussed in :ref:`(Surblys) ` and :ref:`(Boone) `. - You are strongly advised to + as discussed in :ref:`(Surblys2019) `, :ref:`(Boone) ` + and :ref:`(Surblys2021) `. You are strongly advised to use :doc:`compute centroid/stress/atom `, which has been implemented specifically for such cases. +.. warning:: + + Due to an implementation detail, the :math:`y` and :math:`z` + components of heat flux from :doc:`fix rigid ` + contribution when computed via :doc:`compute stress/atom ` + are highly unphysical and should not be used. + The Green-Kubo formulas relate the ensemble average of the auto-correlation of the heat flux :math:`\mathbf{J}` to the thermal conductivity :math:`\kappa`: @@ -232,10 +239,14 @@ none ---------- -.. _Surblys2: +.. _Surblys3: -**(Surblys)** Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019). +**(Surblys2019)** Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019). .. _Boone: **(Boone)** Boone, Babaei, Wilmer, J Chem Theory Comput, 15, 5579--5587 (2019). + +.. _Surblys4: + +**(Surblys2021)** Surblys, Matsubara, Kikugawa, Ohara, J Appl Phys 130, 215104 (2021). diff --git a/doc/src/compute_stress_atom.rst b/doc/src/compute_stress_atom.rst index cdb464a9d0..2c8be0c05a 100644 --- a/doc/src/compute_stress_atom.rst +++ b/doc/src/compute_stress_atom.rst @@ -87,6 +87,10 @@ Tersoff 3-body interaction) is assigned in equal portions to each atom in the set. E.g. 1/4 of the dihedral virial to each of the 4 atoms, or 1/3 of the fix virial due to SHAKE constraints applied to atoms in a water molecule via the :doc:`fix shake ` command. +As an exception, the virial contribution from +constraint forces in :doc:`fix rigid ` on each atom +is computed from the constraint force acting on the corresponding atom +and its position, i.e. the total virial is not equally distributed. In case of compute *centroid/stress/atom*, the virial contribution is: @@ -103,13 +107,25 @@ atom :math:`I` due to the interaction and the relative position :math:`\mathbf{r}_{I0}` of the atom :math:`I` to the geometric center of the interacting atoms, i.e. centroid, is used. As the geometric center is different for each interaction, the :math:`\mathbf{r}_{I0}` -also differs. The sixth and seventh terms, Kspace and :doc:`fix -` contribution respectively, are computed identical to compute -*stress/atom*. Although the total system virial is the same as +also differs. The sixth term, Kspace contribution, +is computed identically to compute *stress/atom*. +The seventh term is handed differently depending on +if the constraint forces are due to :doc:`fix shake ` +or :doc:`fix rigid `. +In case of SHAKE constraints, each distance constraint is +handed as a pairwise interaction. +E.g. in case of a water molecule, two OH and one HH distance +constraints are treated as three pairwise interactions. +In case of :doc:`fix rigid `, +all constraint forces in the molecule are treated +as a single many-body interaction with a single centroid position. +In case of water molecule, the formula expression would become +identical to that of the three-body angle interaction. +Although the total system virial is the same as compute *stress/atom*, compute *centroid/stress/atom* is know to -result in more consistent heat flux values for angle, dihedrals and -improper contributions when computed via :doc:`compute heat/flux -`. +result in more consistent heat flux values for angle, dihedrals, +improper and constraint force contributions +when computed via :doc:`compute heat/flux `. If no extra keywords are listed, the kinetic contribution all of the virial contribution terms are included in the per-atom stress tensor. @@ -134,7 +150,8 @@ contribution for the cluster interaction is divided evenly among those atoms. Details of how compute *centroid/stress/atom* obtains the virial for -individual atoms is given in :ref:`(Surblys) `, where the +individual atoms are given in :ref:`(Surblys2019) ` and +:ref:`(Surblys2021) `, where the idea is that the virial of the atom :math:`I` is the result of only the force :math:`\mathbf{F}_I` on the atom due to the interaction and its positional vector :math:`\mathbf{r}_{I0}`, relative to the @@ -235,10 +252,10 @@ between the pair of particles. All bond styles are supported. All angle, dihedral, improper styles are supported with the exception of INTEL and KOKKOS variants of specific styles. It also does not support models with long-range Coulombic or dispersion forces, -i.e. the kspace_style command in LAMMPS. It also does not support the -following fixes which add rigid-body constraints: :doc:`fix shake -`, :doc:`fix rattle `, :doc:`fix rigid -`, :doc:`fix rigid/small `. +i.e. the kspace_style command in LAMMPS. It also does not implement the +following fixes which add rigid-body constraints: +:doc:`fix rigid/* ` and the OpenMP accelerated version of :doc:`fix rigid/small `, +while all other :doc:`fix rigid/*/small ` are implemented. LAMMPS will generate an error if one of these options is included in your model. Extension of centroid stress calculations to these force @@ -270,4 +287,8 @@ none .. _Surblys1: -**(Surblys)** Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019). +**(Surblys2019)** Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019). + +.. _Surblys2: + +**(Surblys2021)** Surblys, Matsubara, Kikugawa, Ohara, J Appl Phys 130, 215104 (2021).