git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@673 f3b2605a-c512-4ea7-a41b-209d697bcdaa

doc/Manual.txt

@@ -35,6 +35,10 @@ you find errors or omissions in this manual or have suggestions for
 useful information to add, please send an email to the developers so
 we can improve the LAMMPS documentation.
 
+Once you are familiar with LAMMPS, you may want to bookmark "this
+page"_Section_commands.html#comm at Section_commands.html#comm since
+it gives quick access to documentation for all LAMMPS commands.
+
 "PDF file"_Manual.pdf of the entire manual, generated by
 "htmldoc"_http://www.easysw.com/htmldoc
 
@@ -70,7 +74,10 @@ we can improve the LAMMPS documentation.
   4.8 "TIP4P water model"_4_8 :b
   4.9 "SPC water model"_4_9 :b
   4.10 "Coupling LAMMPS to other codes"_4_10 :b
-  4.11 "Visualizing LAMMPS snapshots"_4_11 :ule,b
+  4.11 "Visualizing LAMMPS snapshots"_4_11 :b
+  4.12 "Non-orthogonal simulation boxes"_4_12 :b
+  4.13 "NEMD simulations"_4_13 :b
+  4.14 "Aspherical particles"_4_14 :ule,b
 "Example problems"_Section_example.html :l
 "Performance & scalability"_Section_perf.html :l
 "Additional tools"_Section_tools.html :l
@@ -116,6 +123,9 @@ we can improve the LAMMPS documentation.
 :link(4_9,Section_howto.html#4_9)
 :link(4_10,Section_howto.html#4_10)
 :link(4_11,Section_howto.html#4_11)
+:link(4_12,Section_howto.html#4_12)
+:link(4_13,Section_howto.html#4_13)
+:link(4_14,Section_howto.html#4_14)
 
 :link(9_1,Section_errors.html#9_1)
 :link(9_2,Section_errors.html#9_2)

doc/Section_commands.txt

@@ -459,6 +459,7 @@ full description:
 
 "none"_pair_none.html,
 "hybrid"_pair_hybrid.html,
+"airebo"_pair_airebo.html,
 "buck"_pair_buck.html,
 "buck/coul/cut"_pair_buck.html,
 "buck/coul/long"_pair_buck.html,

doc/Section_howto.txt

@@ -21,7 +21,10 @@ certain kinds of LAMMPS simulations.
 4.8 "TIP4P water model"_#4_8
 4.9 "SPC water model"_#4_9
 4.10 "Coupling LAMMPS to other codes"_#4_10
-4.11 "Visualizing LAMMPS snapshots"_#4_11 :all(b)
+4.11 "Visualizing LAMMPS snapshots"_#4_11
+4.12 "Non-orthogonal simulation boxes"_#4_12
+4.13 "NEMD simulations"_#4_13
+4.14 "Aspherical particles"_#4_14 :all(b)
 
 The example input scripts included in the LAMMPS distribution and
 highlighted in "this section"_Section_example.html also show how to
@@ -642,6 +645,145 @@ See the "dump"_dump.html command for more information on XTC files.
 
 :line
 
+4.12 Non-orthogonal simulation boxes :link(4_12),h4
+
+By default, LAMMPS uses an orthogonal simulation box to encompass the
+particles.  The "boundary"_boundary.html command sets the boundary
+conditions of the box (periodic, non-periodic, etc).  If the box size
+is xprd by yprd by zprd then the 3 mutually orthogonal edge vectors of
+an orthogonal simulation box are a = (xprd,0,0), b = (0,yprd,0), and c
+= (0,0,zprd).
+
+LAMMPS also allows non-orthogonal simulation boxes (triclinic
+symmetry) to be defined with 3 additional "tilt" parameters which
+change the edge vectors of the simulation box to be a = (xprd,0,0), b
+= (xy,yprd,0), and c = (xz,yz,zprd).  The xy, xz, and yz parameters
+can be positive or negative.  The simulation box must be periodic in
+both dimensions associated with a tilt factor.  For example, if xz !=
+0.0, then the x and z dimensions must be periodic.
+
+To avoid extremely tilted boxes (which would be computationally
+inefficient), no tilt factor can skew the box more than half the
+distance of the parallel box length, which is the 1st dimension in the
+tilt factor (x for xz).  For example, if xlo = 2 and xhi = 12, then
+the x box length is 10 and the xy tilt factor must be between -5 and
+5.  Similarly, both xz and yz must be between -(xhi-xlo)/2 and
++(yhi-ylo)/2.  Note that this is not a limitation, since if the
+maximum tilt factor is 5 (as in this example), then configurations
+with tilt = ..., -15, -5, 5, 15, 25, ... are all equivalent.
+
+You tell LAMMPS to use a non-orthogonal box when the simulation box is
+defined.  This happens in one of 3 ways.  If the
+"create_box"_create_box.html command is used with a region of style
+{prism}, then a non-orthogonal domain is setup.  See the
+"region"_region.html command for details.  If the
+"read_data"_read_data.html command is used to define the simulation
+box, and the header of the data file contains a line with the "xy xz
+yz" keyword, then a non-orthogonal domain is setup.  See the
+"read_data"_read_data.html command for details.  Finally, if the
+"read_restart"_read_restart.html command reads a restart file which
+was written from a simulation using a triclinic box, then a
+non-orthogonal box will be enabled for the restarted simulation.
+
+Note that you can define a non-orthogonal box with all 3 tilt factors
+= 0.0, so that it is initially orthogonal.  This is necessary if the
+box will ever become non-orthogonal.
+
+One use of non-orthogonal boxes is to model solid-state crystals with
+triclinic symmetry.  The "lattice"_lattice.html command can be used
+with non-orthogonal basis vectors to define a lattice that will tile a
+non-orthogonal simulation box via the "create_atoms"_create_atoms.html
+command.  Note that while the box edge vectors a,b,c cannot be
+arbitrary vectors (e.g. a must be aligned with the x axis), it is
+possible to rotate any crystal's basis vectors so that they meet these
+restrictions.
+
+A second use of non-orthogonal boxes is to shear a bulk solid to study
+the response of the material.  The "fix deform"_fix_deform.html
+command can be used for this purpose.  It allows dynamic control of
+the xy, xz, and yz tilt factors as a simulation runs.
+
+Another use of non-orthogonal boxes is to perform non-equilibrium MD
+(NEMD) simulations, as discussed in the next section.
+
+:line
+
+4.13 NEMD simulations :link(4_13),h4
+
+Non-equilibrium molecular dynamics or NEMD simulations are typically
+used to measure a fluid's rheological properties such as viscosity.
+In LAMMPS, such simulations can be performed by first setting up a
+non-orthogonal simulation box (see the preceeding Howto section).
+
+A shear strain can be applied to the simualation box at a desired
+strain rate by using the "fix deform"_fix_deform.html command.  The
+"fix nvt/sllod"_fix_nvt_sllod.html command can be used to thermostat
+the sheared fluid and integrate the SLLOD equations of motion for the
+system.  Fix nvt/sllod uses "compute
+temp/deform"_compute_temp_deform.html to compute a thermal temperature
+by subtracting out the streaming velocity of the shearing atoms.  The
+velocity profile or other properties of the fluid can be monitored via
+the "fix ave/spatial"_fix_ave_spatial.html command.
+
+As discussed in the previous section on non-orthogonal simulation
+boxes, the amount of tilt or skew that can be applied is limited by
+LAMMPS for computation efficiency to be 1/2 of the paralell box
+length.  However, "fix deform"_fix_deform.html can be used to
+continuously strain a box by an arbitrary amount.  As discussed in the
+"fix deform"_fix_deform.html command, when the tilt reaches a limit,
+the box is re-shaped to the opposite limit which is an equivalent
+tiling of the periodic plane.  The strain rate can then continue to
+change as before.  In a long NEMD simulation these box re-shaping may
+occur any number of times.
+
+In a NEMD simulation, the "remap" option of "fix
+deform"_fix_deform.html should be set to "remap v", since that is what
+"fix nvt/sllod"_fix_nvt_sllod.html assumes to generate a velocity
+profile consistent with the applied shear strain rate.
+
+:line
+
+4.14 Aspherical particles :link(4_14),h4
+
+LAMMPS supports ellipsoidal particles via the "atom_style
+ellipsoid"_atom_style.html and "shape"_shape.html commands.  The
+latter defines the 3 axes (diamaters) of a general ellipsoid.  The
+"pair_style gayberne"_pair_gayberne.html command can be used to define
+a Gay-Berne (GB) potential for how such particles interact with each
+other and with spherical particles.  The GB potential is like a
+Lennard-Jones (LJ) potential generalized for ellipsoids interacting in
+an orientiation-dependent manner.
+
+The orientation of ellipsoidal particles is stored as a quaternion.
+See the "set"_set.html command for a brief explanation of quaternions
+and how the orientation of such particles can be initialized.  The
+data file read by the "read_data"_read_data.html command also contains
+quaternions for each atom in the Atoms section if "atom_style
+ellipsoid"_atom_style.html is being used.  The "compute
+temp/asphere"_compute_temp_asphere.html command can be used to
+calculate the temperature of a group of ellipsoidal particles, taking
+account of rotational degrees of freedom.  The motion of the particles
+can be integrated via the "fix nve/asphere"_fix_nve_asphere.html, "fix
+nvt/asphere"_fix_nvt_asphere.html, or "fix
+npt/asphere"_fix_npt_asphere.html commands.  All of these commands are
+part of the ASPHERE package in LAMMPS.
+
+Computationally, the cost for two ellipsoidal particles to interact is
+30x or more expensive than for 2 LJ particles.  Thus if you are
+modeling a system with many spherical particles (e.g. as the solvent),
+then you should insure sphere-sphere interactions are computed with
+the a cheaper potential than GB.  This can be done by setting the
+particle's 3 shape parameters to all be equal (a sphere).
+Additionally, the corresponding GB potential coefficients can be set
+so the GB potential will treat the pair of particles as LJ spheres.
+Details are given in the doc page for the "pair_style
+gayberne"_pair_gayberne.html.  Alternatively, the "pair_style
+hybrid"_pair_hybrid.html potential can be used, with the sphere-sphere
+interactions computed by another pair potential, such as "pair_style
+lj/cut"_pair_lj.html.
+
+:line
+
 :link(Cornell)
 [(Cornell)] Cornell, Cieplak, Bayly, Gould, Merz, Ferguson,
 Spellmeyer, Fox, Caldwell, Kollman, JACS 117, 5179-5197 (1995).

doc/Section_intro.txt

@@ -129,7 +129,7 @@ commands)
     class 2 (COMPASS), OPLS
   improper potentials: harmonic, cvff, class 2 (COMPASS)
   hybrid potentials: multiple pair, bond, angle, dihedral, improper \
-    potentials can be used
+    potentials can be used in one simlulation
   polymer potentials: all-atom, united-atom, bead-spring, breakable
   water potentials: TIP3P, TIP4P, SPC
   long-range Coulombics: Ewald, PPPM (similar to particle-mesh Ewald)

doc/angle_charmm.txt

@@ -43,7 +43,11 @@ r_ub (distance) :ul
 Theta0 is specified in degrees, but LAMMPS converts it to radians
 internally; hence the units of K are in energy/radian^2.
 
-[Restrictions:] none
+[Restrictions:]
+
+This angle style can only be used if LAMMPS was built with the
+"molecular" package (which it is by default).  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.
 
 [Related commands:]
 

doc/angle_class2.txt

@@ -29,8 +29,8 @@ the equilibrium bond lengths.
 
 See "(Sun)"_#Sun for a description of the COMPASS class2 force field.
 
-For this style, only coefficients for the Ea formula can be specified
-in the input script.  These are the 4 coefficients:
+For this style, coefficients for the Ea formula can be specified in
+the input script or data file.  These are the 4 coefficients:
 
 theta0 (degrees)
 K2 (energy/radian^2)
@@ -40,7 +40,7 @@ K4 (energy/radian^2) :ul
 Theta0 is specified in degrees, but LAMMPS converts it to radians
 internally; hence the units of K are in energy/radian^2.
 
-Coefficients for the Ebb and Eba formulas must be specified in the
+Coefficients for the Ebb and Eba formulas can only be specified in the
 data file.
 
 For the Ebb formula, the coefficients are listed under a "BondBond
@@ -63,9 +63,9 @@ same value from the Ea formula.
 
 [Restrictions:]
 
-This angle style is part of the "class2" package.  It is only enabled
-if LAMMPS was built with that package.  See the "Making
-LAMMPS"_Section_start.html#2_2 section for more info.
+This angle style can only be used if LAMMPS was built with the
+"class2" package.  See the "Making LAMMPS"_Section_start.html#2_3
+section for more info on packages.
 
 [Related commands:]
 

doc/angle_cosine.txt

@@ -32,7 +32,11 @@ or "read_restart"_read_restart.html commands:
 
 K (energy) :ul
 
-[Restrictions:] none
+[Restrictions:]
+
+This angle style can only be used if LAMMPS was built with the
+"molecular" package (which it is by default).  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.
 
 [Related commands:]
 

doc/angle_cosine_squared.txt

@@ -37,7 +37,11 @@ theta0 (degrees) :ul
 Theta0 is specified in degrees, but LAMMPS converts it to radians
 internally.
 
-[Restrictions:] none
+[Restrictions:]
+
+This angle style can only be used if LAMMPS was built with the
+"molecular" package (which it is by default).  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.
 
 [Related commands:]
 

doc/angle_harmonic.txt

@@ -39,6 +39,10 @@ internally; hence the units of K are in energy/radian^2.
 
 [Restrictions:] none
 
+This angle style can only be used if LAMMPS was built with the
+"molecular" package (which it is by default).  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.
+
 [Related commands:]
 
 "angle_coeff"_angle_coeff.html

doc/angle_hybrid.txt

@@ -49,7 +49,11 @@ An angle style of {none} can be specified as an argument to
 angle_style hybrid and the corresponding angle_coeff commands, if you
 desire to turn off certain angle types.
 
-[Restrictions:] none
+[Restrictions:]
+
+This angle style can only be used if LAMMPS was built with the
+"molecular" package (which it is by default).  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.
 
 [Related commands:]
 

doc/angle_style.txt

@@ -35,14 +35,22 @@ potentials can be setup using the {hybrid} angle style.
 The coefficients associated with a angle style can be specified in a
 data or restart file or via the "angle_coeff"_angle_coeff.html command.
 
+All angle potentials store their coefficient data in binary restart
+files which means angle_style and "angle_coeff"_angle_coeff.html
+commands do not need to be re-specified in an input script that
+restarts a simulation.  See the "read_restart"_read_restart.html
+command for details on how to do this.  The one exception is that
+angle_style {hybrid} only stores the list of sub-styles in the restart
+file; angle coefficients need to be re-specified.
+
+IMPORTANT NOTE: When both an angle and pair style is defined, the
+"special_bonds"_special_bonds.html command often needs to be used to
+turn off (or weight) the pairwise interaction that would otherwise
+exist between 3 bonded atoms.
+
 In the formulas listed for each angle style, {theta} is the angle
 between the 3 atoms in the angle.
 
-Note that when both an angle and pair style is defined, the
-"special_bond"_special_bond.html command often needs to be used to
-turn off (or weight) the pairwise interactions that would otherwise
-exist between the 3 bonded atoms.
-
 :line
 
 Here is an alphabetic list of angle styles defined in LAMMPS.  Click on
@@ -65,10 +73,11 @@ specified by the associated "angle_coeff"_angle_coeff.html command:
 Angle styles can only be set for atom_styles that allow angles to be
 defined.
 
-Angle styles are part of the "molecular" package or other packages as
-noted in their documentation.  They are only enabled if LAMMPS was
-built with that package.  See the "Making
-LAMMPS"_Section_start.html#2_2 section for more info.
+Most angle styles are part of the "molecular" package.  They are only
+enabled if LAMMPS was built with that package.  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.  The
+doc pages for individual bond potentials tell if it is part of a
+package.
 
 [Related commands:]
 

doc/bond_class2.txt

@@ -39,9 +39,9 @@ K4 (energy/distance^2) :ul
 
 [Restrictions:]
 
-This bond style is part of the "class2" package.  It is only enabled
-if LAMMPS was built with that package.  See the "Making
-LAMMPS"_Section_start.html#2_2 section for more info.
+This bond style can only be used if LAMMPS was built with the "class2"
+package.  See the "Making LAMMPS"_Section_start.html#2_3 section for
+more info on packages.
 
 [Related commands:]
 

doc/bond_fene.txt

@@ -39,7 +39,11 @@ R0 (distance)
 epsilon (energy)
 sigma (distance) :ul
 
-[Restrictions:] none
+[Restrictions:]
+
+This bond style can only be used if LAMMPS was built with the
+"molecular" package (which it is by default).  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.
 
 [Related commands:]
 

doc/bond_fene_expand.txt

@@ -44,7 +44,11 @@ epsilon (energy)
 sigma (distance)
 delta (distance) :ul
 
-[Restrictions:] none
+[Restrictions:]
+
+This bond style can only be used if LAMMPS was built with the
+"molecular" package (which it is by default).  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.
 
 [Related commands:]
 

doc/bond_harmonic.txt

@@ -34,7 +34,11 @@ or "read_restart"_read_restart.html commands:
 K (energy/distance^2)
 r0 (distance) :ul
 
-[Restrictions:] none
+[Restrictions:]
+
+This bond style can only be used if LAMMPS was built with the
+"molecular" package (which it is by default).  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.
 
 [Related commands:]
 

doc/bond_hybrid.txt

@@ -42,7 +42,11 @@ A bond style of {none} can be specified as an argument to bond_style
 hybrid and the corresponding bond_coeff commands, if you desire to
 turn off certain bond types.
 
-[Restrictions:] none
+[Restrictions:]
+
+This bond style can only be used if LAMMPS was built with the
+"molecular" package (which it is by default).  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.
 
 [Related commands:]
 

doc/bond_morse.txt

@@ -35,7 +35,11 @@ D (energy)
 alpha (inverse distance)
 r0 (distance) :ul
 
-[Restrictions:] none
+[Restrictions:]
+
+This bond style can only be used if LAMMPS was built with the
+"molecular" package (which it is by default).  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.
 
 [Related commands:]
 

doc/bond_nonlinear.txt

@@ -35,7 +35,11 @@ epsilon (energy)
 r0 (distance)
 lamda (distance) :ul
 
-[Restrictions:] none
+[Restrictions:]
+
+This bond style can only be used if LAMMPS was built with the
+"molecular" package (which it is by default).  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.
 
 [Related commands:]
 

doc/bond_quartic.txt

@@ -72,6 +72,10 @@ delete_bonds all bond 0 remove :pre
 
 [Restrictions:]
 
+This bond style can only be used if LAMMPS was built with the
+"molecular" package (which it is by default).  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.
+
 The {quartic} style requires that "special_bonds"_special_bonds.html
 parameters be set to 1,1,1.  Three- and four-body interactions (angle,
 dihedral, etc) cannot be used with {quartic} bonds.

doc/bond_style.txt

@@ -33,9 +33,9 @@ remain in force for the duration of the simulation (unless the bond
 breaks which is possible in some bond potentials).  The list of bonded
 atoms is read in by a "read_data"_read_data.html or
 "read_restart"_read_restart.html command from a data or restart file.
-By contrast, pair potentials are defined between pairs of atoms that
-are within a cutoff distance and the set of active interactions
-typically changes over time.
+By contrast, pair potentials are typically defined between all pairs
+of atoms within a cutoff distance and the set of active interactions
+changes over time.
 
 Hybrid models where bonds are computed using different bond potentials
 can be setup using the {hybrid} bond style.
@@ -43,14 +43,22 @@ can be setup using the {hybrid} bond style.
 The coefficients associated with a bond style can be specified in a
 data or restart file or via the "bond_coeff"_bond_coeff.html command.
 
-In the formulas listed for each bond style, {r} is the distance
-between the 2 atoms in the bond.
+All bond potentials store their coefficient data in binary restart
+files which means bond_style and "bond_coeff"_bond_coeff.html commands
+do not need to be re-specified in an input script that restarts a
+simulation.  See the "read_restart"_read_restart.html command for
+details on how to do this.  The one exception is that bond_style
+{hybrid} only stores the list of sub-styles in the restart file; bond
+coefficients need to be re-specified.
 
-Note that when both a bond and pair style is defined, the
+IMPORTANT NOTE: When both a bond and pair style is defined, the
 "special_bonds"_special_bonds.html command often needs to be used to
 turn off (or weight) the pairwise interaction that would otherwise
 exist between 2 bonded atoms.
 
+In the formulas listed for each bond style, {r} is the distance
+between the 2 atoms in the bond.
+
 :line
 
 Here is an alphabetic list of bond styles defined in LAMMPS.  Click on
@@ -75,10 +83,11 @@ specified by the associated "bond_coeff"_bond_coeff.html command:
 Bond styles can only be set for atom styles that allow bonds to be
 defined.
 
-Bond styles are part of the "molecular" package or other packages as
-noted in their documentation.  They are only enabled if LAMMPS was
-built with that package.  See the "Making
-LAMMPS"_Section_start.html#2_2 section for more info.
+Most bond styles are part of the "molecular" package.  They are only
+enabled if LAMMPS was built with that package.  See the "Making
+LAMMPS"_Section_start.html#2_3 section for more info on packages.  The
+doc pages for individual bond potentials tell if it is part of a
+package.
 
 [Related commands:]