improve layout and logical structure. add references

have their own pages where they are listed alphabetically.

Initialization:

------------------------------

* :doc:`newton <newton>`,

* :doc:`package <package>`,

* :doc:`units <units>`

Setup simulation box:

------------------------------

* :doc:`boundary <boundary>`,

* :doc:`box <box>`,

* :doc:`region <region>`

Setup atoms:

------------------------------

* :doc:`atom_modify <atom_modify>`,

* :doc:`atom_style <atom_style>`,

* :doc:`velocity <velocity>`

Force fields:

------------------------------

* :doc:`angle_coeff <angle_coeff>`,

* :doc:`angle_style <angle_style>`,

* :doc:`special_bonds <special_bonds>`

Settings:

------------------------------

* :doc:`comm_modify <comm_modify>`,

* :doc:`comm_style <comm_style>`,

* :doc:`timestep <timestep>`

Operations within timestepping (fixes) and diagnostics (computes):

------------------------------------------------------------------------------------------

* :doc:`compute <compute>`,

* :doc:`compute_modify <compute_modify>`,

* :doc:`unfix <unfix>`

Output:

------------------------------

* :doc:`dump image <dump_image>`,

* :doc:`dump movie <dump_image>`,

* :doc:`write_restart <write_restart>`

Actions:

------------------------------

* :doc:`minimize <minimize>`,

* :doc:`neb <neb>`,

* :doc:`temper <temper>`

Input script control:

------------------------------

* :doc:`clear <clear>`,

* :doc:`echo <echo>`,

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,

the command is assumed to continue on the next line.  The next line is

.. _one:

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

continue a command across multiple line without using "&" characters.

   more lines.  See the discussion of triple quotes in :ref:`6 <six>`

   for how to continue a command across multiple line without using "&"

   characters.

.. _two:

(2) All characters from the first "#" character onward are treated as

comment and discarded.  See an exception in (6).  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.

2. All characters from the first "#" character onward are treated as

   comment and discarded.  The exception to this rule is described in

   :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

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

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 variable names "myTemp" and

"x".

.. _three:

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.

It can be a variable that stores multiple text strings, and return one

of them.  The returned text string can be multiple "words" (space

separated) which will then be interpreted as multiple arguments in the

input command.  The variable can also store a numeric formula which

will be evaluated and its numeric result returned as a string.

3. The line is searched repeatedly for $ characters, which indicate

   variables that are replaced with a text string.  The exception to

   this rule is described in :ref:`6 <six>`.

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:

   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.  It can be a variable that stores multiple text strings, and

   return one of them.  The returned text string can be multiple "words"

   (space separated) which will then be interpreted as multiple

   arguments in the input command.  The variable can also store a

   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:

   .. code-block:: LAMMPS

      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

colon, followed by a C-style format string, e.g. ":%f" or ":%.10g".

   Additionally, the "immediate" variable expression may be followed by

   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

      print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom"

Note that neither the curly-bracket or immediate form of variables can

contain nested $ characters for other variables to substitute for.

Thus you cannot do this:

   Note that neither the curly-bracket or immediate form of variables

   can contain nested $ characters for other variables to substitute

   for.  Thus you may **NOT** do this:

   .. code-block:: LAMMPS

      variable        b2 equal 4

      print           "B2 = ${b$a}"

Nor can you specify this $($x-1.0) for an immediate variable, but

you could use $(v\_x-1.0), since the latter is valid syntax for an

:doc:`equal-style variable <variable>`.

   Nor can you specify an expression like "$($x-1.0)" for an immediate

   variable, but you could use $(v\_x-1.0), since the latter is valid

   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

used in input script commands.

   strings are assigned to variables and evaluated, and how they can

   be used in input script commands.

.. _four:

(4) The line is broken into "words" separated by white-space (tabs,

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

line are arguments.

.. _five:

5. The first word is the command name.  All successive words in the line

   are arguments.

(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

.. _six:

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

needed.  For example:

   can be enclosed in triple quotes, in which case "&" characters are

   not needed.  For example:

   .. code-block:: LAMMPS

   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>`,

:doc:`if <if>`, and :doc:`python <python>` commands for examples.

   See the :doc:`dump modify format <dump_modify>`, :doc:`print

   <print>`, :doc:`if <if>`, and :doc:`python <python>` commands for

   examples.

A "#" or "$" character that is between quotes will not be treated as a

comment indicator in (2) or substituted for as a variable in (3).

   A "#" or "$" character that is between quotes will not be treated as

   a comment indicator in :ref:`2 <two>` or substituted for as a

   variable in :ref:`3 <three>`.

.. note::

A LAMMPS input script typically has 4 parts:

1. Initialization

2. Atom definition

3. Settings

4. Run a simulation

1. :ref:`Initialization <init>`

2. :ref:`System definition <system>` 

3. :ref:`Settings <settings>`

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.

:doc:`angle_style <angle_style>`, :doc:`dihedral_style <dihedral_style>`,

:doc:`improper_style <improper_style>`.

(2) Atom definition

.. _system:

System definition

------------------------------

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>`.

There are 3 ways to define atoms in LAMMPS.  Read them in from a data

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.

The entire set of atoms can be duplicated to make a larger simulation

using the :doc:`replicate <replicate>` command.

(3) Settings

.. _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>`,

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

LAMMPS is a classical molecular dynamics (MD) code with these general

classes of functionality:

* :ref:`General features <general>`

* :ref:`Particle and model types <particle>`

* :ref:`Interatomic potentials (force fields) <ff>`

* :ref:`Atom creation <create>`

* :ref:`Ensembles, constraints, and boundary conditions <ensemble>`

* :ref:`Integrators <integrate>`

* :ref:`Diagnostics <diag>`

* :ref:`Output <output>`

* :ref:`Multi-replica models <replica1>`

* :ref:`Pre- and post-processing <prepost>`

* :ref:`Specialized features (beyond MD itself) <special>`

1. :ref:`General features <general>`

2. :ref:`Particle and model types <particle>`

3. :ref:`Interatomic potentials (force fields) <ff>`

4. :ref:`Atom creation <create>`

5. :ref:`Ensembles, constraints, and boundary conditions <ensemble>`

6. :ref:`Integrators <integrate>`

7. :ref:`Diagnostics <diag>`

8. :ref:`Output <output>`

9. :ref:`Multi-replica models <replica1>`

10. :ref:`Pre- and post-processing <prepost>`

11. :ref:`Specialized features (beyond MD itself) <special>`

----------