improve layout and logical structure. add references

doc/src/Commands_category.rst

@@ -7,6 +7,7 @@ alphabetically.  Style options for entries like fix, compute, pair etc.
 have their own pages where they are listed alphabetically.
 
 Initialization:
+------------------------------
 
 * :doc:`newton <newton>`,
 * :doc:`package <package>`,
@@ -15,6 +16,7 @@ Initialization:
 * :doc:`units <units>`
 
 Setup simulation box:
+------------------------------
 
 * :doc:`boundary <boundary>`,
 * :doc:`box <box>`,
@@ -25,6 +27,7 @@ Setup simulation box:
 * :doc:`region <region>`
 
 Setup atoms:
+------------------------------
 
 * :doc:`atom_modify <atom_modify>`,
 * :doc:`atom_style <atom_style>`,
@@ -45,6 +48,7 @@ Setup atoms:
 * :doc:`velocity <velocity>`
 
 Force fields:
+------------------------------
 
 * :doc:`angle_coeff <angle_coeff>`,
 * :doc:`angle_style <angle_style>`,
@@ -65,6 +69,7 @@ Force fields:
 * :doc:`special_bonds <special_bonds>`
 
 Settings:
+------------------------------
 
 * :doc:`comm_modify <comm_modify>`,
 * :doc:`comm_style <comm_style>`,
@@ -80,6 +85,7 @@ Settings:
 * :doc:`timestep <timestep>`
 
 Operations within timestepping (fixes) and diagnostics (computes):
+------------------------------------------------------------------------------------------
 
 * :doc:`compute <compute>`,
 * :doc:`compute_modify <compute_modify>`,
@@ -89,6 +95,7 @@ Operations within timestepping (fixes) and diagnostics (computes):
 * :doc:`unfix <unfix>`
 
 Output:
+------------------------------
 
 * :doc:`dump image <dump_image>`,
 * :doc:`dump movie <dump_image>`,
@@ -105,6 +112,7 @@ Output:
 * :doc:`write_restart <write_restart>`
 
 Actions:
+------------------------------
 
 * :doc:`minimize <minimize>`,
 * :doc:`neb <neb>`,
@@ -116,6 +124,7 @@ Actions:
 * :doc:`temper <temper>`
 
 Input script control:
+------------------------------
 
 * :doc:`clear <clear>`,
 * :doc:`echo <echo>`,

doc/src/Commands_parse.rst

@@ -9,47 +9,58 @@ file names or user-chosen ID strings.
 Here are 6 rules for how each line in the input script is parsed by
 LAMMPS:
 
-(1) If the last printable character on the line is a "&" character,
+.. _one:
-the command is assumed to continue on the next line.  The next line is
+
+1. If the last printable character on the line is a "&" character, the
+   command is assumed to continue on the next line.  The next line is
    concatenated to the previous line by removing the "&" character and
    line break.  This allows long commands to be continued across two or
-more lines.  See the discussion of triple quotes in (6) for how to
+   more lines.  See the discussion of triple quotes in :ref:`6 <six>`
-continue a command across multiple line without using "&" characters.
+   for how to continue a command across multiple line without using "&"
+   characters.
 
-(2) All characters from the first "#" character onward are treated as
+.. _two:
-comment and discarded.  See an exception in (6).  Note that a
+
-comment after a trailing "&" character will prevent the command from
+2. All characters from the first "#" character onward are treated as
-continuing on the next line.  Also note that for multi-line commands a
+   comment and discarded.  The exception to this rule is described in
-single leading "#" will comment out the entire command.
+   :ref:`6 <six>`. Note that a comment after a trailing "&" character
+   will prevent the command from continuing on the next line.  Also note
+   that for multi-line commands a single leading "#" will comment out
+   the entire command.
 
    .. code-block:: LAMMPS
 
       # this is a comment
+      timestep  1.0   # this is also a comment
 
-(3) The line is searched repeatedly for $ characters, which indicate
+.. _three:
-variables that are replaced with a text string.  See an exception in
-(6).
 
-If the $ is followed by curly brackets, then the variable name is the
+3. The line is searched repeatedly for $ characters, which indicate
-text inside the curly brackets.  If no curly brackets follow the $,
+   variables that are replaced with a text string.  The exception to
-then the variable name is the single character immediately following
+   this rule is described in :ref:`6 <six>`.
-the $.  Thus ${myTemp} and $x refer to variable names "myTemp" and
+
-"x".
+   If the $ is followed by text in curly brackets '{}', then the
+   variable name is the text inside the curly brackets.  If no curly
+   brackets follow the $, then the variable name is the single character
+   immediately following the $.  Thus ${myTemp} and $x refer to variables
+   named "myTemp" and "x", while "$xx" will be interpreted as a variable
+   named "x" followed by an "x" character.
 
    How the variable is converted to a text string depends on what style
-of variable it is; see the :doc:`variable <variable>` doc page for details.
+   of variable it is; see the :doc:`variable <variable>` doc page for
-It can be a variable that stores multiple text strings, and return one
+   details.  It can be a variable that stores multiple text strings, and
-of them.  The returned text string can be multiple "words" (space
+   return one of them.  The returned text string can be multiple "words"
-separated) which will then be interpreted as multiple arguments in the
+   (space separated) which will then be interpreted as multiple
-input command.  The variable can also store a numeric formula which
+   arguments in the input command.  The variable can also store a
-will be evaluated and its numeric result returned as a string.
+   numeric formula which will be evaluated and its numeric result
-
+   returned as a string.
-As a special case, if the $ is followed by parenthesis, then the text
-inside the parenthesis is treated as an "immediate" variable and
-evaluated as an :doc:`equal-style variable <variable>`.  This is a way
-to use numeric formulas in an input script without having to assign
-them to variable names.  For example, these 3 input script lines:
 
+   As a special case, if the $ is followed by parenthesis "()", then the
+   text inside the parenthesis is treated as an "immediate" variable and
+   evaluated as an :doc:`equal-style variable <variable>`.  This is a
+   way to use numeric formulas in an input script without having to
+   assign them to variable names.  For example, these 3 input script
+   lines:
 
    .. code-block:: LAMMPS
 
@@ -57,17 +68,17 @@ them to variable names.  For example, these 3 input script lines:
       region 1 block $X 2 INF INF EDGE EDGE
       variable X delete
 
-can be replaced by
+   can be replaced by:
-
 
    .. code-block:: LAMMPS
 
       region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE
 
-so that you do not have to define (or discard) a temporary variable X.
+   so that you do not have to define (or discard) a temporary variable,
+   "X" in this case.
 
-Additionally, the "immediate" variable expression may be followed by a
+   Additionally, the "immediate" variable expression may be followed by
-colon, followed by a C-style format string, e.g. ":%f" or ":%.10g".
+   a colon, followed by a C-style format string, e.g. ":%f" or ":%.10g".
    The format string must be appropriate for a double-precision
    floating-point value.  The format string is used to output the result
    of the variable expression evaluation.  If a format string is not
@@ -80,10 +91,9 @@ This can be useful for formatting print output to a desired precision:
 
       print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom"
 
-Note that neither the curly-bracket or immediate form of variables can
+   Note that neither the curly-bracket or immediate form of variables
-contain nested $ characters for other variables to substitute for.
+   can contain nested $ characters for other variables to substitute
-Thus you cannot do this:
+   for.  Thus you may **NOT** do this:
-
 
    .. code-block:: LAMMPS
 
@@ -91,31 +101,36 @@ Thus you cannot do this:
       variable        b2 equal 4
       print           "B2 = ${b$a}"
 
-Nor can you specify this $($x-1.0) for an immediate variable, but
+   Nor can you specify an expression like "$($x-1.0)" for an immediate
-you could use $(v\_x-1.0), since the latter is valid syntax for an
+   variable, but you could use $(v\_x-1.0), since the latter is valid
-:doc:`equal-style variable <variable>`.
+   syntax for an :doc:`equal-style variable <variable>`.
 
    See the :doc:`variable <variable>` command for more details of how
-strings are assigned to variables and evaluated, and how they can be
+   strings are assigned to variables and evaluated, and how they can
-used in input script commands.
+   be used in input script commands.
 
-(4) The line is broken into "words" separated by white-space (tabs,
+.. _four:
+
+4. The line is broken into "words" separated by white-space (tabs,
    spaces).  Note that words can thus contain letters, digits,
    underscores, or punctuation characters.
 
-(5) The first word is the command name.  All successive words in the
+.. _five:
-line are arguments.
    
-(6) If you want text with spaces to be treated as a single argument,
+5. The first word is the command name.  All successive words in the line
-it can be enclosed in either single or double or triple quotes.  A
+   are arguments.
-long single argument enclosed in single or double quotes can span
+
-multiple lines if the "&" character is used, as described above.  When
+.. _six:
-the lines are concatenated together (and the "&" characters and line
+
+6. If you want text with spaces to be treated as a single argument, it
+   can be enclosed in either single or double or triple quotes.  A long
+   single argument enclosed in single or double quotes can span multiple
+   lines if the "&" character is used, as described above.  When the
+   lines are concatenated together (and the "&" characters and line
    breaks removed), the text will become a single line.  If you want
    multiple lines of an argument to retain their line breaks, the text
-can be enclosed in triple quotes, in which case "&" characters are not
+   can be enclosed in triple quotes, in which case "&" characters are
-needed.  For example:
+   not needed.  For example:
-
 
    .. code-block:: LAMMPS
 
@@ -132,11 +147,13 @@ needed.  For example:
    In each case, the single, double, or triple quotes are removed when
    the single argument they enclose is stored internally.
 
-See the :doc:`dump modify format <dump_modify>`, :doc:`print <print>`,
+   See the :doc:`dump modify format <dump_modify>`, :doc:`print
-:doc:`if <if>`, and :doc:`python <python>` commands for examples.
+   <print>`, :doc:`if <if>`, and :doc:`python <python>` commands for
+   examples.
 
-A "#" or "$" character that is between quotes will not be treated as a
+   A "#" or "$" character that is between quotes will not be treated as
-comment indicator in (2) or substituted for as a variable in (3).
+   a comment indicator in :ref:`2 <two>` or substituted for as a
+   variable in :ref:`3 <three>`.
 
 .. note::
 

doc/src/Commands_structure.rst

@@ -8,17 +8,20 @@ page.
 
 A LAMMPS input script typically has 4 parts:
 
-1. Initialization
+1. :ref:`Initialization <init>`
-2. Atom definition
+2. :ref:`System definition <system>` 
-3. Settings
+3. :ref:`Settings <settings>`
-4. Run a simulation
+4. :ref:`Run a simulation <run>`
 
 The last 2 parts can be repeated as many times as desired.  I.e. run a
 simulation, change some settings, run some more, etc.  Each of the 4
 parts is now described in more detail.  Remember that almost all
 commands need only be used if a non-default value is desired.
 
-(1) Initialization
+.. _init:
+
+Initialization
+------------------------------
 
 Set parameters that need to be defined before atoms are created or
 read-in from a file.
@@ -34,23 +37,33 @@ commands tell LAMMPS what kinds of force fields are being used:
 :doc:`angle_style <angle_style>`, :doc:`dihedral_style <dihedral_style>`,
 :doc:`improper_style <improper_style>`.
 
-(2) Atom definition
+.. _system:
 
-There are 3 ways to define atoms in LAMMPS.  Read them in from a data
+System definition
-or restart file via the :doc:`read_data <read_data>` or
+------------------------------
-:doc:`read_restart <read_restart>` commands.  These files can contain
-molecular topology information.  Or create atoms on a lattice (with no
-molecular topology), using these commands: :doc:`lattice <lattice>`,
-:doc:`region <region>`, :doc:`create_box <create_box>`,
-:doc:`create_atoms <create_atoms>`.  The entire set of atoms can be
-duplicated to make a larger simulation using the
-:doc:`replicate <replicate>` command.
 
-(3) Settings
+There are 3 ways to define the simulation cell and reserve space for
+force field info and fill it with atoms in LAMMPS.  Read them in from
+(1) a data file or (2) a restart file via the :doc:`read_data
+<read_data>` or :doc:`read_restart <read_restart>` commands,
+respectively.  These files can also contain molecular topology
+information.  Or (3) create a simulation cell and fill it with atoms on
+a lattice (with no molecular topology), using these commands:
+:doc:`lattice <lattice>`, :doc:`region <region>`, :doc:`create_box
+<create_box>`, :doc:`create_atoms <create_atoms>` or
+:doc:`read_dump <read_dump>`.
+
+The entire set of atoms can be duplicated to make a larger simulation
+using the :doc:`replicate <replicate>` command.
+
+.. _settings:
+
+Settings
+------------------------------
 
 Once atoms and molecular topology are defined, a variety of settings
 can be specified: force field coefficients, simulation parameters,
-output options, etc.
+output options, and more.
 
 Force field coefficients are set by these commands (they can also be
 set in the read-in files): :doc:`pair_coeff <pair_coeff>`,
@@ -77,7 +90,10 @@ commands.
 Output options are set by the :doc:`thermo <thermo>`, :doc:`dump <dump>`,
 and :doc:`restart <restart>` commands.
 
-(4) Run a simulation
+.. _run:
+
+Run a simulation
+------------------------------
 
 A molecular dynamics simulation is run using the :doc:`run <run>`
 command.  Energy minimization (molecular statics) is performed using

doc/src/Intro_features.rst

@@ -4,17 +4,17 @@ LAMMPS features
 LAMMPS is a classical molecular dynamics (MD) code with these general
 classes of functionality:
 
-* :ref:`General features <general>`
+1. :ref:`General features <general>`
-* :ref:`Particle and model types <particle>`
+2. :ref:`Particle and model types <particle>`
-* :ref:`Interatomic potentials (force fields) <ff>`
+3. :ref:`Interatomic potentials (force fields) <ff>`
-* :ref:`Atom creation <create>`
+4. :ref:`Atom creation <create>`
-* :ref:`Ensembles, constraints, and boundary conditions <ensemble>`
+5. :ref:`Ensembles, constraints, and boundary conditions <ensemble>`
-* :ref:`Integrators <integrate>`
+6. :ref:`Integrators <integrate>`
-* :ref:`Diagnostics <diag>`
+7. :ref:`Diagnostics <diag>`
-* :ref:`Output <output>`
+8. :ref:`Output <output>`
-* :ref:`Multi-replica models <replica1>`
+9. :ref:`Multi-replica models <replica1>`
-* :ref:`Pre- and post-processing <prepost>`
+10. :ref:`Pre- and post-processing <prepost>`
-* :ref:`Specialized features (beyond MD itself) <special>`
+11. :ref:`Specialized features (beyond MD itself) <special>`
 
 
 ----------