Merge pull request #492 from lammps/pre-patch

update docs before patch release

doc/src/Section_commands.txt

@@ -618,6 +618,7 @@ USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.
 "press/berendsen"_fix_press_berendsen.html,
 "print"_fix_print.html,
 "property/atom"_fix_property_atom.html,
+"python"_fix_python.html,
 "qeq/comb (o)"_fix_qeq_comb.html,
 "qeq/dynamic"_fix_qeq.html,
 "qeq/fire"_fix_qeq.html,
@@ -984,6 +985,7 @@ KOKKOS, o = USER-OMP, t = OPT.
 "peri/pmb (o)"_pair_peri.html,
 "peri/ves"_pair_peri.html,
 "polymorphic"_pair_polymorphic.html,
+"python"_pair_python.html,
 "reax"_pair_reax.html,
 "rebo (o)"_pair_airebo.html,
 "resquared (go)"_pair_resquared.html,

doc/src/Section_python.txt

@@ -118,13 +118,21 @@ check which version of Python you have installed, by simply typing
 
 11.2 Overview of using Python from a LAMMPS script :link(py_2),h4
 
-LAMMPS has a "python"_python.html command which can be used in an
+LAMMPS has several commands which can be used to invoke Python
-input script to define and execute a Python function that you write
+code directly from an input script:
-the code for.  The Python function can also be assigned to a LAMMPS
+
-python-style variable via the "variable"_variable.html command.  Each
+"python"_python.html
-time the variable is evaluated, either in the LAMMPS input script
+"variable python"_variable.html
-itself, or by another LAMMPS command that uses the variable, this will
+"fix python"_fix_python.html
-trigger the Python function to be invoked.
+"pair_style python"_pair_python.html :ul
+
+The "python"_python.html command which can be used to define and
+execute a Python function that you write the code for.  The Python
+function can also be assigned to a LAMMPS python-style variable via
+the "variable"_variable.html command.  Each time the variable is
+evaluated, either in the LAMMPS input script itself, or by another
+LAMMPS command that uses the variable, this will trigger the Python
+function to be invoked.
 
 The Python code for the function can be included directly in the input
 script or in an auxiliary file.  The function can have arguments which
@@ -155,13 +163,18 @@ commands.
 See the "python"_python.html doc page and the "variable"_variable.html
 doc page for its python-style variables for more info, including
 examples of Python code you can write for both pure Python operations
-and callbacks to LAMMPS. See "fix python"_fix_python.html to learn about
+and callbacks to LAMMPS.
-possibilities to execute Python code during each time step.
-Through the "python pair style"_pair_python.html it is also possible
-to define potential functions as python code.
 
-To run pure Python code from LAMMPS, you only need to build LAMMPS
+The "fix python"_fix_python.html command can execute
-with the PYTHON package installed:
+Python code at selected timesteps during a simulation run.
+
+The "pair_style python"_pair_python command allows you to define
+pairwise potentials as python code which encodes a single pairwise
+interaction.  This is useful for rapid-developement and debugging of a
+new potential.
+
+To use any of these commands, you only need to build LAMMPS with the
+PYTHON package installed:
 
 make yes-python
 make machine :pre

doc/src/fix_reax_bonds.txt

@@ -34,7 +34,20 @@ written to {filename} on timesteps that are multiples of {Nevery},
 including timestep 0.  For time-averaged chemical species analysis,
 please see the "fix reaxc/c/species"_fix_reaxc_species.html command.
 
-The format of the output file should be self-explanatory.
+The format of the output file should be reasonably self-explanatory.
+The meaning of the column header abbreviations is as follows:
+
+id = atom id
+type = atom type
+nb = number of bonds
+id_1 = atom id of first bond
+id_nb = atom id of Nth bond
+mol = molecule id
+bo_1 = bond order of first bond
+bo_nb = bond order of Nth bond
+abo = atom bond order (sum of all bonds)
+nlp = number of lone pairs
+q = atomic charge :ul
 
 If the filename ends with ".gz", the output file is written in gzipped
 format.  A gzipped dump file will be about 3x smaller than the text

doc/src/pair_edip.txt

@@ -7,12 +7,13 @@
 :line
 
 pair_style edip command :h3
+pair_style edip/multi command :h3
 
 [Syntax:]
 
-pair_style edip :pre
+pair_style style :pre
-pair_style edip/omp :pre
+
-pair_style edip/multi :pre
+style = {edip} or {edip/multi} :ul
 
 [Examples:]
 
@@ -168,4 +169,4 @@ appropriate units if your simulation doesn't use "metal" units.
 :line
 
 :link(EDIP)
-[(EDIP)] J. F. Justo et al., Phys. Rev. B 58, 2539 (1998).
+[(EDIP)] J F Justo et al, Phys Rev B 58, 2539 (1998).

doc/src/pair_gw.txt

@@ -11,7 +11,9 @@ pair_style gw/zbl command :h3
 
 [Syntax:]
 
-pair_style gw :pre
+pair_style style :pre
+
+style = {gw} or {gw/zbl} :ul
 
 [Examples:]
 

doc/src/pair_python.txt

@@ -40,34 +40,34 @@ Only a single pair_coeff command is used with the {python} pair style
 which specifies a python class inside a python module or file that
 LAMMPS will look up in the current directory, the folder pointed to by
 the LAMMPS_POTENTIALS environment variable or somewhere in your python
-path. A single python module can hold multiple python pair class
+path.  A single python module can hold multiple python pair class
-definitions. The class definitions itself have to follow specific rules
+definitions. The class definitions itself have to follow specific
-that are explained below.
+rules that are explained below.
 
-Atom types in the python class are specified through symbolic constants,
+Atom types in the python class are specified through symbolic
-typically strings. These are mapped to LAMMPS atom types by specifying
+constants, typically strings. These are mapped to LAMMPS atom types by
-N additional arguments after the class name in the pair_coeff command,
+specifying N additional arguments after the class name in the
-where N must be the number of currently defined atom types:
+pair_coeff command, where N must be the number of currently defined
+atom types:
 
 As an example, imagine a file {py_pot.py} has a python potential class
 names {LJCutMelt} with parameters and potential functions for a two
 Lennard-Jones atom types labeled as 'LJ1' and 'LJ2'. In your LAMMPS
 input and you would have defined 3 atom types, out of which the first
-two are supposed to be using the 'LJ1' parameters and the third
+two are supposed to be using the 'LJ1' parameters and the third the
-the 'LJ2' parameters, then you would use the following pair_coeff
+'LJ2' parameters, then you would use the following pair_coeff command:
-command:
 
 pair_coeff * * py_pot.LJCutMelt LJ1 LJ1 LJ2 :pre
 
-The first two arguments [must] be * * so as to span all LAMMPS atom types.
+The first two arguments [must] be * * so as to span all LAMMPS atom
-The first two LJ1 arguments map LAMMPS atom types 1 and 2 to the LJ1
+types.  The first two LJ1 arguments map LAMMPS atom types 1 and 2 to
-atom type in the LJCutMelt class of the py_pot.py file.  The final LJ2
+the LJ1 atom type in the LJCutMelt class of the py_pot.py file.  The
-argument maps LAMMPS atom type 3 to the LJ2 atom type the python file.
+final LJ2 argument maps LAMMPS atom type 3 to the LJ2 atom type the
-If a mapping value is specified as NULL, the mapping is not performed,
+python file.  If a mapping value is specified as NULL, the mapping is
-any pair interaction with this atom type will be skipped. This can be
+not performed, any pair interaction with this atom type will be
-used when a {python} potential is used as part of the {hybrid} or
+skipped. This can be used when a {python} potential is used as part of
-{hybrid/overlay} pair style. The NULL values are then placeholders for
+the {hybrid} or {hybrid/overlay} pair style. The NULL values are then
-atom types that will be used with other potentials.
+placeholders for atom types that will be used with other potentials.
 
 :line
 
@@ -88,14 +88,18 @@ class LAMMPSPairPotential(object):
 
 Any classes with definitions of specific potentials have to be derived
 from this class and should be initialize in a similar fashion to the
-example given below. NOTE: The class constructor has to set up a data
+example given below.
-structure containing the potential parameters supported by this class.
+
-It should also define a variable {self.units} containing a string
+NOTE: The class constructor has to set up a data structure containing
-matching one of the options of LAMMPS' "units"_units.html command, which
+the potential parameters supported by this class.  It should also
-is used to verify, that the potential definition in the python class and
+define a variable {self.units} containing a string matching one of the
-in the LAMMPS input match. Example for a single type Lennard-Jones
+options of LAMMPS' "units"_units.html command, which is used to
-potential class {LJCutMelt} in reducted units, which defines an atom
+verify, that the potential definition in the python class and in the
-type {lj} for which the parameters epsilon and sigma are both 1.0:
+LAMMPS input match.
+
+Here is an example for a single type Lennard-Jones potential class
+{LJCutMelt} in reducted units, which defines an atom type {lj} for
+which the parameters epsilon and sigma are both 1.0:
 
 class LJCutMelt(LAMMPSPairPotential):
     def __init__(self):
@@ -136,32 +140,32 @@ the {LJCutMelt} example, here are the two functions:
         lj4 = coeff\[3\]
         return (r6inv * (lj3*r6inv - lj4)) :pre
 
-IMPORTANT NOTE: for consistency with the C++ pair styles in LAMMPS,
+NOTE: for consistency with the C++ pair styles in LAMMPS, the
-the {compute_force} function follows the conventions of the Pair::single()
+{compute_force} function follows the conventions of the Pair::single()
 methods and does not return the full force, but the force scaled by
 the distance between the two atoms, so this value only needs to be
-multiplied by delta x, delta y, and delta z to conveniently obtain
+multiplied by delta x, delta y, and delta z to conveniently obtain the
-the three components of the force vector between these two atoms.
+three components of the force vector between these two atoms.
 
 :line
 
-IMPORTANT NOTE: The evaluation of scripted python code will slow down
+NOTE: The evaluation of scripted python code will slow down the
-the computation pair-wise interactions quite significantly. However,
+computation pair-wise interactions quite significantly. However, this
-this can be largely worked around through using the python pair style
+can be largely worked around through using the python pair style not
-not for the actual simulation, but to generate tabulated potentials
+for the actual simulation, but to generate tabulated potentials on the
-on the fly using the "pair_write"_pair_write.html command. Please
+fly using the "pair_write"_pair_write.html command. Please see below
-see below for an example LAMMPS input of how to build a table file:
+for an example LAMMPS input of how to build a table file:
 
 pair_style python 2.5
 pair_coeff * * py_pot.LJCutMelt lj
 shell rm -f melt.table
 pair_write  1 1 2000 rsq 0.01 2.5 lj1_lj2.table lj :pre
 
-Note, that it is strong recommended to try to [delete] the potential
+Note that it is strongly recommended to try to [delete] the potential
 table file before generating it. Since the {pair_write} command will
-always append to a table file, which pair style table will use the first
+always append to a table file, which pair style table will use the
-match. Thus when changing the potential function in the python class,
+first match. Thus when changing the potential function in the python
-the table pair style will still read the old variant.
+class, the table pair style will still read the old variant.
 
 After switching the pair style to {table}, the potential tables need
 to be assigned to the LAMMPS atom types like this:
@@ -169,7 +173,7 @@ to be assigned to the LAMMPS atom types like this:
 pair_style      table linear 2000
 pair_coeff      1  1  melt.table lj :pre
 
-This can also be done for more complex systems. Please see the
+This can also be done for more complex systems.  Please see the
 {examples/python} folders for a few more examples.
 
 :line
@@ -198,9 +202,9 @@ This pair style can only be used via the {pair} keyword of the
 
 [Restrictions:]
 
-This pair style is part of the PYTHON package.  It is only enabled
+This pair style is part of the PYTHON package.  It is only enabled if
-if LAMMPS was built with that package.  See
+LAMMPS was built with that package.  See the "Making
-the "Making LAMMPS"_Section_start.html#start_3 section for more info.
+LAMMPS"_Section_start.html#start_3 section for more info.
 
 [Related commands:]
 

doc/src/pair_tersoff.txt

@@ -18,7 +18,7 @@ pair_style tersoff/table/omp command :h3
 
 pair_style style :pre
 
-style = {tersoff} or {tersoff/table} or {tersoff/gpu} or {tersoff/omp} or {tersoff/table/omp}
+style = {tersoff} or {tersoff/table} or {tersoff/gpu} or {tersoff/omp} or {tersoff/table/omp} :ul
 
 [Examples:]
 

src/USER-MISC/README

@@ -60,8 +60,6 @@ pair_style dipole/sf, Mario Orsi, orsimario at gmail.com, 8 Aug 11
 pair_style edip, Luca Ferraro, luca.ferraro at caspur.it, 15 Sep 11
 pair_style eam/cd, Alexander Stukowski, stukowski at mm.tu-darmstadt.de, 7 Nov 09
 pair_style gauss/cut, Axel Kohlmeyer, akohlmey at gmail.com, 1 Dec 11
-pair_style gw, German Samolyuk, samolyuk at gmail.com, 17 May 17
-pair_style gw/zbl, German Samolyuk, samolyuk at gmail.com, 17 May 17
 pair_style lennard/mdf, Paolo Raiteri, p.raiteri at curtin.edu.au, 2 Dec 15
 pair_style list, Axel Kohlmeyer (Temple U), akohlmey at gmail.com, 1 Jun 13
 pair_style lj/mdf, Paolo Raiteri, p.raiteri at curtin.edu.au, 2 Dec 15