Merge pull request #1583 from evoyiatzis/gyration_shape

computing the eigenvalues of gyration tensor & shape parameters

doc/src/Commands_compute.txt

@@ -66,6 +66,7 @@ KOKKOS, o = USER-OMP, t = OPT.
 "group/group"_compute_group_group.html,
 "gyration"_compute_gyration.html,
 "gyration/chunk"_compute_gyration_chunk.html,
+"gyration/shape"_compute_gyration_shape.html,
 "heat/flux"_compute_heat_flux.html,
 "heat/flux/tally"_compute_tally.html,
 "hexorder/atom"_compute_hexorder_atom.html,

doc/src/Eqs/compute_shape_parameters.tex

@@ -0,0 +1,13 @@
+\documentclass[12pt]{article}
+
+\pagestyle{empty}
+\begin{document}
+
+\begin{eqnarray*}
+ c = l_z - 0.5(l_y+l_x) \\
+ b = l_y - l_x \\
+ k = \frac{3}{2} \frac{l_x^2+l_y^2+l_z^2}{(l_x+l_y+l_z)^2} - \frac{1}{2} 
+\end{eqnarray*}
+
+\end{document}
+

doc/src/Errors_messages.txt

@@ -2438,6 +2438,14 @@ Self-explanatory. :dd
 
 Self-explanatory. :dd
 
+{Compute gyration ID does not exist for compute gyration/shape} :dt
+
+Self-explanatory. Provide a valid compute ID. :dd
+
+{Compute gyration/shape compute ID does not point to a gyration compute} :dt
+
+Self-explanatory. Provide and ID of a compute gyration command. :dd
+
 {Compute ID for compute reduce does not exist} :dt
 
 Self-explanatory. :dd

doc/src/compute.txt

@@ -213,6 +213,7 @@ compute"_Commands_compute.html doc page are followed by one or more of
 "group/group"_compute_group_group.html - energy/force between two groups of atoms
 "gyration"_compute_gyration.html - radius of gyration of group of atoms
 "gyration/chunk"_compute_gyration_chunk.html - radius of gyration for each chunk
+"gyration/shape"_compute_gyration_shape.html - compute shape parameters from radius of gyration tensor
 "heat/flux"_compute_heat_flux.html - heat flux through a group of atoms
 "heat/flux/tally"_compute_tally.html -
 "hexorder/atom"_compute_hexorder_atom.html - bond orientational order parameter q6

doc/src/compute_gyration.txt

@@ -67,6 +67,7 @@ distance^2 "units"_units.html respectively.
 
 [Related commands:]
 
-"compute gyration/chunk"_compute_gyration_chunk.html
+"compute gyration/chunk"_compute_gyration_chunk.html,
+"compute gyration/shape"_compute_gyration_shape.html
 
 [Default:] none

doc/src/compute_gyration_shape.txt

@@ -0,0 +1,86 @@
+"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
+
+:link(lws,http://lammps.sandia.gov)
+:link(ld,Manual.html)
+:link(lc,Commands_all.html)
+
+:line
+
+compute gyration/shape command :h3
+
+[Syntax:]
+
+compute ID group-ID gyration compute-ID :pre
+
+ID, group-ID are documented in "compute"_compute.html command
+gyration/shape = style name of this compute command
+compute-ID = ID of "compute gyration"_compute_gyration.html command :ul
+
+[Examples:]
+
+compute 1 molecule gyration/shape pe :pre
+
+[Description:]
+
+Define a computation that calculates the eigenvalues of the gyration tensor of a
+group of atoms and three shape parameters. The computation includes all effects
+due to atoms passing thru periodic boundaries.
+
+The three computed shape parameters are the asphericity, b, the acylindricity, c,
+and the relative shape anisotropy, k:
+
+:c,image(Eqs/compute_shape_parameters.jpg)
+
+where lx <= ly <= lz are the three eigenvalues of the gyration tensor.
+The asphericity  is always non-negative and zero only when the three principal
+moments are equal. This zero condition is met when the distribution of particles
+is spherically symmetric (hence the name asphericity) but also whenever the particle
+distribution is symmetric with respect to the three coordinate axes, e.g.,
+when the particles are distributed uniformly on a cube, tetrahedron or other Platonic
+solid. The acylindricity is always non-negative and zero only when the two principal
+moments are equal. This zero condition is met when the distribution of particles is
+cylindrically symmetric (hence the name, acylindricity), but also whenever the particle
+distribution is symmetric with respect to the two coordinate axes, e.g., when the
+particles are distributed uniformly on a regular prism. the relative shape anisotropy
+is bounded between zero (if all points are spherically symmetric) and one
+(if all points lie on a line).
+
+NOTE: The coordinates of an atom contribute to the gyration tensor in
+"unwrapped" form, by using the image flags associated with each atom.
+See the "dump custom"_dump.html command for a discussion of "unwrapped"
+coordinates. See the Atoms section of the "read_data"_read_data.html
+command for a discussion of image flags and how they are set for each
+atom.  You can reset the image flags (e.g. to 0) before invoking this
+compute by using the "set image"_set.html command.
+
+[Output info:]
+
+This compute calculates a global vector of
+length 6, which can be accessed by indices 1-6. The first three values are the
+eigenvalues of the gyration tensor followed by the asphericity, the acylindricity
+and the relative shape anisotropy.  The computed values can be used by any command
+that uses global  vector values from a compute as input.  See the "Howto
+output"_Howto_output.html doc page for an overview of LAMMPS output
+options.
+
+The vector values calculated by this compute are
+"intensive".  The first five vector values will be in
+distance^2 "units"_units.html while the sixth one is dimensionless.
+
+[Restrictions:]
+
+This compute is part of the USER-MISC package.  It is only enabled if
+LAMMPS was built with that package.  See the "Build
+package"_Build_package.html doc page for more info.
+
+[Related commands:]
+
+"compute gyration"_compute_gyration.html
+
+[Default:] none
+
+:line
+
+:link(Theodorou)
+[(Theodorou)] Theodorou, Suter, Macromolecules, 18, 1206 (1985).
+

doc/src/computes.txt

@@ -44,6 +44,7 @@ Computes :h1
    compute_group_group
    compute_gyration
    compute_gyration_chunk
+   compute_gyration_shape
    compute_heat_flux
    compute_hexorder_atom
    compute_improper

doc/src/lammps.book

@@ -455,6 +455,7 @@ compute_global_atom.html
 compute_group_group.html
 compute_gyration.html
 compute_gyration_chunk.html
+compute_gyration_shape.html
 compute_heat_flux.html
 compute_hexorder_atom.html
 compute_improper.html