From 0f925f7a39ea4fccd20e5bd35cf81dc56dd00296 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Jun 2023 04:33:08 -0400 Subject: [PATCH] reformat, add versionadded marker --- doc/src/compute_stress_mop.rst | 123 ++++++++++++++++++--------------- 1 file changed, 69 insertions(+), 54 deletions(-) diff --git a/doc/src/compute_stress_mop.rst b/doc/src/compute_stress_mop.rst index 7ab8c58a76..5662fc76d4 100644 --- a/doc/src/compute_stress_mop.rst +++ b/doc/src/compute_stress_mop.rst @@ -45,92 +45,107 @@ Examples Description """"""""""" -Compute *stress/mop* and compute *stress/mop/profile* define computations that -calculate components of the local stress tensor using the method of -planes :ref:`(Todd) `. Specifically in compute *stress/mop* calculates 3 -components are computed in directions *dir*,\ *x*\ ; *dir*,\ *y*\ ; and -*dir*,\ *z*\ ; where *dir* is the direction normal to the plane, while -in compute *stress/mop/profile* the profile of the stress is computed. +Compute *stress/mop* and compute *stress/mop/profile* define +computations that calculate components of the local stress tensor using +the method of planes :ref:`(Todd) `. Specifically in compute +*stress/mop* calculates 3 components are computed in directions *dir*,\ +*x*\ ; *dir*,\ *y*\ ; and *dir*,\ *z*\ ; where *dir* is the direction +normal to the plane, while in compute *stress/mop/profile* the profile +of the stress is computed. Contrary to methods based on histograms of atomic stress (i.e., using -:doc:`compute stress/atom `), the method of planes is -compatible with mechanical balance in heterogeneous systems and at +:doc:`compute stress/atom `), the method of planes +is compatible with mechanical balance in heterogeneous systems and at interfaces :ref:`(Todd) `. The stress tensor is the sum of a kinetic term and a configurational term, which are given respectively by Eq. (21) and Eq. (16) in -:ref:`(Todd) `. For the kinetic part, the algorithm considers that -atoms have crossed the plane if their positions at times :math:`t-\Delta t` -and :math:`t` are one on either side of the plane, and uses the velocity at -time :math:`t-\Delta t/2` given by the velocity Verlet algorithm. +:ref:`(Todd) `. For the kinetic part, the algorithm considers +that atoms have crossed the plane if their positions at times +:math:`t-\Delta t` and :math:`t` are one on either side of the plane, +and uses the velocity at time :math:`t-\Delta t/2` given by the velocity +Verlet algorithm. -Between one and six keywords can be used to indicate which -contributions to the stress must be computed: total stress (total), kinetic stress (kin), -configurational stress (conf), stress due to bond stretching (bond), -stress due to angle bending (angle) and/or due to pairwise non-bonded interactions (pair). -The angle keyword is currently available only for the stress/mop command and not the stress/mop/profile. +.. versionadded:: TBD -NOTE 1: The configurational stress is computed considering all pairs of atoms where at least one atom belongs to group group-ID. + contributions from bond and angle potentials + +Between one and six keywords can be used to indicate which contributions +to the stress must be computed: total stress (total), kinetic stress +(kin), configurational stress (conf), stress due to bond stretching +(bond), stress due to angle bending (angle) and/or due to pairwise +non-bonded interactions (pair). The angle keyword is currently +available only for the *stress/mop* command and **not** the +*stress/mop/profile* command. + +NOTE 1: The configurational stress is computed considering all pairs of +atoms where at least one atom belongs to group group-ID. NOTE 2: The local stress does not include any Lennard-Jones tail -corrections to the stress added by the :doc:`pair_modify tail yes ` -command, since those are contributions to the global system pressure. +corrections to the stress added by the :doc:`pair_modify tail yes +` command, since those are contributions to the global +system pressure. -NOTE 3: The local stress profile generated by compute *stress/mop/profile* -is similar to that obtained by compute -:doc:`stress/cartesian `. -A key difference is that compute *stress/mop/profile* considers particles -crossing a set of planes, while compute *stress/cartesian* computes averages -for a set of small volumes. More information -on the similarities and differences can be found in -:ref:`(Ikeshoji)`. +NOTE 3: The local stress profile generated by compute +*stress/mop/profile* is similar to that obtained by compute +:doc:`stress/cartesian `. A key difference is +that compute *stress/mop/profile* considers particles crossing a set of +planes, while compute *stress/cartesian* computes averages for a set of +small volumes. More information on the similarities and differences can +be found in :ref:`(Ikeshoji)`. Output info """"""""""" -Compute *stress/mop* calculates a global vector (indices starting at 1), with 3 -values for each declared keyword (in the order the keywords have been -declared). For each keyword, the stress tensor components are ordered as -follows: stress_dir,x, stress_dir,y, and stress_dir,z. +Compute *stress/mop* calculates a global vector (indices starting at 1), +with 3 values for each declared keyword (in the order the keywords have +been declared). For each keyword, the stress tensor components are +ordered as follows: stress_dir,x, stress_dir,y, and stress_dir,z. -Compute *stress/mop/profile* instead calculates a global array, with 1 column -giving the position of the planes where the stress tensor was computed, -and with 3 columns of values for each declared keyword (in the order the -keywords have been declared). For each keyword, the profiles of stress -tensor components are ordered as follows: stress_dir,x; stress_dir,y; -and stress_dir,z. +Compute *stress/mop/profile* instead calculates a global array, with 1 +column giving the position of the planes where the stress tensor was +computed, and with 3 columns of values for each declared keyword (in the +order the keywords have been declared). For each keyword, the profiles +of stress tensor components are ordered as follows: stress_dir,x; +stress_dir,y; and stress_dir,z. The values are in pressure :doc:`units `. -The values produced by this compute can be accessed by various :doc:`output commands `. -For instance, the results can be written to a file using the -:doc:`fix ave/time ` command. Please see the example -in the examples/PACKAGES/mop folder. +The values produced by this compute can be accessed by various +:doc:`output commands `. For instance, the results can be +written to a file using the :doc:`fix ave/time ` +command. Please see the example in the examples/PACKAGES/mop folder. Restrictions """""""""""" -These styles are part of the EXTRA-COMPUTE package. They are only enabled if -LAMMPS is built with that package. See the :doc:`Build package ` -doc page on for more info. +These styles are part of the EXTRA-COMPUTE package. They are only +enabled if LAMMPS is built with that package. See the :doc:`Build +package ` doc page on for more info. The method is only implemented for 3d orthogonal simulation boxes whose size does not change in time, and axis-aligned planes. The method only works with two-body pair interactions, because it -requires the class method pair->single() to be implemented. In -particular, compute *stress/mop/profile* does not work with more than -two-body pair interactions, long range (kspace) interactions and angle/dihedral/improper -intramolecular interactions. Similarly, compute *stress/mop* does not work with more than -two-body pair interactions, long range (kspace) interactions and dihedral/improper -intramolecular interactions but works with all bond interactions with the class method -single() implemented and all angle interactions with the class method born_matrix() -implemented. +requires the class method ``Pair::single()`` to be implemented, which is +not possible for manybody potentials. In particular, compute +*stress/mop/profile* does not work with more than two-body pair +interactions, long range (kspace) interactions and +angle/dihedral/improper intramolecular interactions. Similarly, compute +*stress/mop* does not work with more than two-body pair interactions, +long range (kspace) interactions and dihedral/improper intramolecular +interactions but works with all bond interactions with the class method +single() implemented and all angle interactions with the class method +born_matrix() implemented. Related commands """""""""""""""" -:doc:`compute stress/atom `, :doc:`compute pressure `, :doc:`compute stress/cartesian `, :doc:`compute stress/cylinder `, :doc:`compute stress/spherical ` +:doc:`compute stress/atom `, +:doc:`compute pressure `, +:doc:`compute stress/cartesian `, +:doc:`compute stress/cylinder `, +:doc:`compute stress/spherical ` Default """""""