doc/src/dihedral_table.txt

   1 "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
   2
   3 :link(lws,http://lammps.sandia.gov)
   4 :link(ld,Manual.html)
   5 :link(lc,Section_commands.html#comm)
   6
   7 :line
   8
   9 dihedral_style table command :h3
  10 dihedral_style table/omp command :h3
  11
  12 [Syntax:]
  13
  14 dihedral_style table style Ntable :pre
  15
  16 style = {linear} or {spline} = method of interpolation
  17 Ntable = size of the internal lookup table :ul
  18
  19 [Examples:]
  20
  21 dihedral_style table spline 400
  22 dihedral_style table linear 1000
  23 dihedral_coeff 1 file.table DIH_TABLE1
  24 dihedral_coeff 2 file.table DIH_TABLE2 :pre
  25
  26 [Description:]
  27
  28 The {table} dihedral style creates interpolation tables of length
  29 {Ntable} from dihedral potential and derivative values listed in a
  30 file(s) as a function of the dihedral angle "phi".  The files are read
  31 by the "dihedral_coeff"_dihedral_coeff.html command.
  32
  33 The interpolation tables are created by fitting cubic splines to the
  34 file values and interpolating energy and derivative values at each of
  35 {Ntable} dihedral angles. During a simulation, these tables are used
  36 to interpolate energy and force values on individual atoms as
  37 needed. The interpolation is done in one of 2 styles: {linear} or
  38 {spline}.
  39
  40 For the {linear} style, the dihedral angle (phi) is used to find 2
  41 surrounding table values from which an energy or its derivative is
  42 computed by linear interpolation.
  43
  44 For the {spline} style, cubic spline coefficients are computed and
  45 stored at each of the {Ntable} evenly-spaced values in the
  46 interpolated table.  For a given dihedral angle (phi), the appropriate
  47 coefficients are chosen from this list, and a cubic polynomial is used
  48 to compute the energy and the derivative at this angle.
  49
  50 The following coefficients must be defined for each dihedral type via
  51 the "dihedral_coeff"_dihedral_coeff.html command as in the example
  52 above.
  53
  54 filename
  55 keyword :ul
  56
  57 The filename specifies a file containing tabulated energy and
  58 derivative values. The keyword specifies a section of the file.  The
  59 format of this file is described below.
  60
  61 :line
  62
  63 The format of a tabulated file is as follows (without the
  64 parenthesized comments).  It can begin with one or more comment
  65 or blank lines.
  66
  67 # Table of the potential and its negative derivative  :pre
  68
  69 DIH_TABLE1                   (keyword is the first text on line)
  70 N 30 DEGREES                 (N, NOF, DEGREES, RADIANS, CHECKU/F)
  71                              (blank line)
  72 1 -168.0 -1.40351172223 0.0423346818422
  73 2 -156.0 -1.70447981034 0.00811786522531
  74 3 -144.0 -1.62956100432 -0.0184129719987
  75 ...
  76 30 180.0 -0.707106781187 0.0719306095245 :pre
  77
  78 # Example 2: table of the potential. Forces omitted :pre
  79
  80 DIH_TABLE2
  81 N 30 NOF CHECKU testU.dat CHECKF testF.dat :pre
  82
  83 1 -168.0 -1.40351172223
  84 2 -156.0 -1.70447981034
  85 3 -144.0 -1.62956100432
  86 ...
  87 30 180.0 -0.707106781187 :pre
  88
  89 A section begins with a non-blank line whose 1st character is not a
  90 "#"; blank lines or lines starting with "#" can be used as comments
  91 between sections. The first line begins with a keyword which
  92 identifies the section. The line can contain additional text, but the
  93 initial text must match the argument specified in the
  94 "dihedral_coeff"_dihedral_coeff.html command. The next line lists (in
  95 any order) one or more parameters for the table. Each parameter is a
  96 keyword followed by one or more numeric values.
  97
  98 Following a blank line, the next N lines list the tabulated values. On
  99 each line, the 1st value is the index from 1 to N, the 2nd value is
 100 the angle value, the 3rd value is the energy (in energy units), and
 101 the 4th is -dE/d(phi) also in energy units). The 3rd term is the
 102 energy of the 4-atom configuration for the specified angle.  The 4th
 103 term (when present) is the negative derivative of the energy with
 104 respect to the angle (in degrees, or radians depending on whether the
 105 user selected DEGREES or RADIANS).  Thus the units of the last term
 106 are still energy, not force. The dihedral angle values must increase
 107 from one line to the next.
 108
 109 Dihedral table splines are cyclic.  There is no discontinuity at 180
 110 degrees (or at any other angle).  Although in the examples above, the
 111 angles range from -180 to 180 degrees, in general, the first angle in
 112 the list can have any value (positive, zero, or negative).  However
 113 the {range} of angles represented in the table must be {strictly} less
 114 than 360 degrees (2pi radians) to avoid angle overlap.  (You may not
 115 supply entries in the table for both 180 and -180, for example.)  If
 116 the user's table covers only a narrow range of dihedral angles,
 117 strange numerical behavior can occur in the large remaining gap.
 118
 119 [Parameters:]
 120
 121 The parameter "N" is required and its value is the number of table
 122 entries that follow. Note that this may be different than the N
 123 specified in the "dihedral_style table"_dihedral_style.html command.
 124 Let {Ntable} is the number of table entries requested dihedral_style
 125 command, and let {Nfile} be the parameter following "N" in the
 126 tabulated file ("30" in the sparse example above).  What LAMMPS does
 127 is a preliminary interpolation by creating splines using the {Nfile}
 128 tabulated values as nodal points.  It uses these to interpolate as
 129 needed to generate energy and derivative values at {Ntable} different
 130 points (which are evenly spaced over a 360 degree range, even if the
 131 angles in the file are not).  The resulting tables of length {Ntable}
 132 are then used as described above, when computing energy and force for
 133 individual dihedral angles and their atoms.  This means that if you
 134 want the interpolation tables of length {Ntable} to match exactly what
 135 is in the tabulated file (with effectively nopreliminary
 136 interpolation), you should set {Ntable} = {Nfile}.  To insure the
 137 nodal points in the user's file are aligned with the interpolated
 138 table entries, the angles in the table should be integer multiples of
 139 360/{Ntable} degrees, or 2*PI/{Ntable} radians (depending on your
 140 choice of angle units).
 141
 142 The optional "NOF" keyword allows the user to omit the forces
 143 (negative energy derivatives) from the table file (normally located in
 144 the 4th column).  In their place, forces will be calculated
 145 automatically by differentiating the potential energy function
 146 indicated by the 3rd column of the table (using either linear or
 147 spline interpolation).
 148
 149 The optional "DEGREES" keyword allows the user to specify angles in
 150 degrees instead of radians (default).
 151
 152 The optional "RADIANS" keyword allows the user to specify angles in
 153 radians instead of degrees.  (Note: This changes the way the forces
 154 are scaled in the 4th column of the data file.)
 155
 156 The optional "CHECKU" keyword is followed by a filename.  This allows
 157 the user to save all of the {Ntable} different entries in the
 158 interpolated energy table to a file to make sure that the interpolated
 159 function agrees with the user's expectations.  (Note: You can
 160 temporarily increase the {Ntable} parameter to a high value for this
 161 purpose.  "{Ntable}" is explained above.)
 162
 163 The optional "CHECKF" keyword is analogous to the "CHECKU" keyword.
 164 It is followed by a filename, and it allows the user to check the
 165 interpolated force table.  This option is available even if the user
 166 selected the "NOF" option.
 167
 168 Note that one file can contain many sections, each with a tabulated
 169 potential. LAMMPS reads the file section by section until it finds one
 170 that matches the specified keyword.
 171
 172 :line
 173
 174 Styles with a {gpu}, {intel}, {kk}, {omp}, or {opt} suffix are
 175 functionally the same as the corresponding style without the suffix.
 176 They have been optimized to run faster, depending on your available
 177 hardware, as discussed in "Section 5"_Section_accelerate.html
 178 of the manual.  The accelerated styles take the same arguments and
 179 should produce the same results, except for round-off and precision
 180 issues.
 181
 182 These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
 183 USER-OMP and OPT packages, respectively.  They are only enabled if
 184 LAMMPS was built with those packages.  See the "Making
 185 LAMMPS"_Section_start.html#start_3 section for more info.
 186
 187 You can specify the accelerated styles explicitly in your input script
 188 by including their suffix, or you can use the "-suffix command-line
 189 switch"_Section_start.html#start_6 when you invoke LAMMPS, or you can
 190 use the "suffix"_suffix.html command in your input script.
 191
 192 See "Section 5"_Section_accelerate.html of the manual for
 193 more instructions on how to use the accelerated styles effectively.
 194
 195 [Restrictions:]
 196
 197 This dihedral style can only be used if LAMMPS was built with the
 198 USER-MISC package.  See the "Making LAMMPS"_Section_start.html#start_3
 199 section for more info on packages.
 200
 201 [Related commands:]
 202
 203 "dihedral_coeff"_dihedral_coeff.html
 204
 205 [Default:] none