doc/src/bond_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 bond_style table command :h3
  10 bond_style table/omp command :h3
  11
  12 [Syntax:]
  13
  14 bond_style table style N :pre
  15
  16 style = {linear} or {spline} = method of interpolation
  17 N = use N values in table :ul
  18
  19 [Examples:]
  20
  21 bond_style table linear 1000
  22 bond_coeff 1 file.table ENTRY1 :pre
  23
  24 [Description:]
  25
  26 Style {table} creates interpolation tables of length {N} from bond
  27 potential and force values listed in a file(s) as a function of bond
  28 length.  The files are read by the "bond_coeff"_bond_coeff.html
  29 command.
  30
  31 The interpolation tables are created by fitting cubic splines to the
  32 file values and interpolating energy and force values at each of {N}
  33 distances.  During a simulation, these tables are used to interpolate
  34 energy and force values as needed.  The interpolation is done in one
  35 of 2 styles: {linear} or {spline}.
  36
  37 For the {linear} style, the bond length is used to find 2 surrounding
  38 table values from which an energy or force is computed by linear
  39 interpolation.
  40
  41 For the {spline} style, a cubic spline coefficients are computed and
  42 stored at each of the {N} values in the table.  The bond length is
  43 used to find the appropriate set of coefficients which are used to
  44 evaluate a cubic polynomial which computes the energy or force.
  45
  46 The following coefficients must be defined for each bond type via the
  47 "bond_coeff"_bond_coeff.html command as in the example above.
  48
  49 filename
  50 keyword :ul
  51
  52 The filename specifies a file containing tabulated energy and force
  53 values.  The keyword specifies a section of the file.  The format of
  54 this file is described below.
  55
  56 :line
  57
  58 The format of a tabulated file is as follows (without the
  59 parenthesized comments):
  60
  61 # Bond potential for harmonic (one or more comment or blank lines) :pre
  62
  63 HAM                           (keyword is the first text on line)
  64 N 101 FP 0 0 EQ 0.5           (N, FP, EQ  parameters)
  65                               (blank line)
  66 1 0.00 338.0000 1352.0000     (index, bond-length, energy, force)
  67 2 0.01 324.6152 1324.9600
  68 ...
  69 101 1.00 338.0000 -1352.0000 :pre
  70
  71 A section begins with a non-blank line whose 1st character is not a
  72 "#"; blank lines or lines starting with "#" can be used as comments
  73 between sections.  The first line begins with a keyword which
  74 identifies the section.  The line can contain additional text, but the
  75 initial text must match the argument specified in the
  76 "bond_coeff"_bond_coeff.html command.  The next line lists (in any
  77 order) one or more parameters for the table.  Each parameter is a
  78 keyword followed by one or more numeric values.
  79
  80 The parameter "N" is required and its value is the number of table
  81 entries that follow.  Note that this may be different than the {N}
  82 specified in the "bond_style table"_bond_style.html command.  Let
  83 Ntable = {N} in the bond_style command, and Nfile = "N" in the
  84 tabulated file.  What LAMMPS does is a preliminary interpolation by
  85 creating splines using the Nfile tabulated values as nodal points.  It
  86 uses these to interpolate as needed to generate energy and force
  87 values at Ntable different points.  The resulting tables of length
  88 Ntable are then used as described above, when computing energy and
  89 force for individual bond lengths.  This means that if you want the
  90 interpolation tables of length Ntable to match exactly what is in the
  91 tabulated file (with effectively no preliminary interpolation), you
  92 should set Ntable = Nfile.
  93
  94 The "FP" parameter is optional.  If used, it is followed by two values
  95 fplo and fphi, which are the derivatives of the force at the innermost
  96 and outermost bond lengths.  These values are needed by the spline
  97 construction routines.  If not specified by the "FP" parameter, they
  98 are estimated (less accurately) by the first two and last two force
  99 values in the table.
 100
 101 The "EQ" parameter is also optional.  If used, it is followed by a the
 102 equilibrium bond length, which is used, for example, by the "fix
 103 shake"_fix_shake.html command.  If not used, the equilibrium bond
 104 length is to the distance in the table with the lowest potential energy.
 105
 106 Following a blank line, the next N lines list the tabulated values.
 107 On each line, the 1st value is the index from 1 to N, the 2nd value is
 108 the bond length r (in distance units), the 3rd value is the energy (in
 109 energy units), and the 4th is the force (in force units).  The bond
 110 lengths must range from a LO value to a HI value, and increase from
 111 one line to the next.  If the actual bond length is ever smaller than
 112 the LO value or larger than the HI value, then the bond energy and
 113 force is evaluated as if the bond were the LO or HI length.
 114
 115 Note that one file can contain many sections, each with a tabulated
 116 potential.  LAMMPS reads the file section by section until it finds
 117 one that matches the specified keyword.
 118
 119 :line
 120
 121 Styles with a {gpu}, {intel}, {kk}, {omp}, or {opt} suffix are
 122 functionally the same as the corresponding style without the suffix.
 123 They have been optimized to run faster, depending on your available
 124 hardware, as discussed in "Section 5"_Section_accelerate.html
 125 of the manual.  The accelerated styles take the same arguments and
 126 should produce the same results, except for round-off and precision
 127 issues.
 128
 129 These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
 130 USER-OMP and OPT packages, respectively.  They are only enabled if
 131 LAMMPS was built with those packages.  See the "Making
 132 LAMMPS"_Section_start.html#start_3 section for more info.
 133
 134 You can specify the accelerated styles explicitly in your input script
 135 by including their suffix, or you can use the "-suffix command-line
 136 switch"_Section_start.html#start_7 when you invoke LAMMPS, or you can
 137 use the "suffix"_suffix.html command in your input script.
 138
 139 See "Section 5"_Section_accelerate.html of the manual for
 140 more instructions on how to use the accelerated styles effectively.
 141
 142 :line
 143
 144 [Restrictions:]
 145
 146 This bond style can only be used if LAMMPS was built with the
 147 MOLECULE package.  See the "Making
 148 LAMMPS"_Section_start.html#start_3 section for more info on packages.
 149
 150 [Related commands:]
 151
 152 "bond_coeff"_bond_coeff.html, "delete_bonds"_delete_bonds.html
 153
 154 [Default:] none