Merge pull request #1690 from charlessievers/third_order

Added third order, added documentation, took out extraneous lines, ad…

doc/src/Commands_all.txt

@@ -124,6 +124,7 @@ An alphabetic list of all general LAMMPS commands.
 "thermo"_thermo.html,
 "thermo_modify"_thermo_modify.html,
 "thermo_style"_thermo_style.html,
+"third_order"_third_order.html,
 "timer"_timer.html,
 "timestep"_timestep.html,
 "uncompute"_uncompute.html,

doc/src/Packages_details.txt

@@ -1746,11 +1746,12 @@ USER-PHONON package :link(PKG-USER-PHONON),h4
 A "fix phonon"_fix_phonon.html command that calculates dynamical
 matrices, which can then be used to compute phonon dispersion
 relations, directly from molecular dynamics simulations.
-And a "dynamical_matrix" command to compute the dynamical matrix
-from finite differences.
+And a "dynamical_matrix"_dynamical_matrix.html as well as a
+"third_order"_third_order.html command to compute the dynamical matrix
+and third order tensor from finite differences.
 
 [Authors:] Ling-Ti Kong (Shanghai Jiao Tong University) for "fix phonon"
-and Charlie Sievers (UC Davis) for "dynamical_matrix"
+and Charlie Sievers (UC Davis) for "dynamical_matrix" and "third_order"
 
 
 [Supporting info:]
@@ -1759,6 +1760,7 @@ src/USER-PHONON: filenames -> commands
 src/USER-PHONON/README
 "fix phonon"_fix_phonon.html
 "dynamical_matrix"_dynamical_matrix.html
+"third_order"_third_order.html
 examples/USER/phonon :ul
 
 :line

doc/src/commands_list.txt

@@ -108,6 +108,7 @@ Commands :h1
    thermo
    thermo_modify
    thermo_style
+   third_order
    timer
    timestep
    uncompute

doc/src/dynamical_matrix.txt

@@ -30,14 +30,29 @@ dynamical_matrix 5 eskm 0.00000001 file dynamical.dat binary yes :pre
 
 [Description:]
 
-Calculate the dynamical matrix of the selected group.
+Calculate the dynamical matrix by finite difference of the selected group,
+
+:c,image(JPG/dynamical_matrix_dynmat.jpg)
+
+where D is the dynamical matrix and Phi is the force constant matrix defined by
+
+:c,image(JPG/dynamical_matrix_force_constant.jpg).
+
+The output for the dynamical matrix is printed three elements at a time. The
+three elements are the three beta elements for a respective i/alpha/j combination. 
+Each line is printed in order of j increasing first, alpha second, and i last.
+
+If the style eskm is selected, the dynamical matrix will be in units of inverse squared
+femtoseconds. These units will then conveniently leave frequencies in THz, where
+frequencies, represented as omega, can be calculated from
+
+:c, image(Eqs/dynamical_matrix_phonons.jpg)
 
 [Restrictions:]
 
-The command collects the entire dynamical matrix a single MPI rank,
-so the memory requirements can be very significant for large systems.
-
-This command assumes a periodic system.
+The command collects an array of nine times the number of atoms in a group
+on every single MPI rank, so the memory requirements can be very significant
+for large systems.
 
 This command is part of the USER-PHONON package.  It is only enabled if
 LAMMPS was built with that package.  See the "Build

doc/src/lammps.book

@@ -217,6 +217,7 @@ temper_npt.html
 thermo.html
 thermo_modify.html
 thermo_style.html
+third_order.html
 timer.html
 timestep.html
 uncompute.html

doc/src/third_order.txt

@@ -0,0 +1,62 @@
+"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
+
+third_order command :h3
+
+[Syntax:]
+
+third_order group-ID style delta args keyword value ... :pre
+
+group-ID = ID of group of atoms to displace :ulb,l
+style = {regular} or {eskm} :l
+delta = finite different displacement length (distance units) :l
+one or more keyword/arg pairs may be appended :l
+  keyword = {file} or {binary}
+    {file} name = name of output file for the third order tensor
+    {binary} arg = {yes} or {no} or {gzip} :pre
+:ule
+
+[Examples:]
+
+third_order 1 regular 0.000001
+third_order 1 eskm 0.000001
+third_order 3 regular 0.00004 file third_order.dat
+third_order 5 eskm 0.00000001 file third_order.dat binary yes :pre
+
+[Description:]
+
+Calculate the third order force constant tensor by finite difference of the selected group,
+
+:c,image(JPG/third_order_force_constant.png))
+
+where Phi is the third order force constant tensor.
+
+The output of the command is the tensor, three elements at a time. The
+three elements correspond to the three gamma elements for a specific i/alpha/j/beta/k.
+The initial five numbers are i, alpha, j, beta, and k respectively.
+
+If the style eskm is selected, the tensor will be using energy units of 10 J/mol.
+These units conform to eskm style from the dynamical_matrix command, which
+will simplify operations using dynamical matrices with third order tensors.
+
+[Restrictions:]
+
+The command collects a 9 times the number of atoms in the group on every single MPI rank,
+so the memory requirements can be very significant for large systems.
+
+This command is part of the USER-PHONON 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:]
+
+"fix phonon"_fix_phonon.html "dynamical_matrix"_dynamical_matrix.html
+
+[Default:]
+
+The default settings are file = "third_order.dat", binary = no