ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

improve layout and logical structure. add references

Browse Source
This commit is contained in:
Axel Kohlmeyer
2020-02-22 10:39:15 -05:00
parent 44a54324c1
commit 57711f0dcb
4 changed files with 173 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
doc/src/Commands_category.rst
View File

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

221
doc/src/Commands_parse.rst
View File

@ -9,134 +9,151 @@ file names or user-chosen ID strings.
Here are 6 rules for how each line in the input script is parsed by Here are 6 rules for how each line in the input script is parsed by
LAMMPS: 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
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.
(2) All characters from the first "#" character onward are treated as 1. If the last printable character on the line is a "&" character, the
comment and discarded. See an exception in (6). Note that a command is assumed to continue on the next line. The next line is
comment after a trailing "&" character will prevent the command from concatenated to the previous line by removing the "&" character and
continuing on the next line. Also note that for multi-line commands a line break. This allows long commands to be continued across two or
single leading "#" will comment out the entire command. more lines. See the discussion of triple quotes in :ref:`6 <six>`
for how to continue a command across multiple line without using "&"
characters.
.. code-block:: LAMMPS .. _two:
# this is a comment 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.
(3) The line is searched repeatedly for $ characters, which indicate .. code-block:: LAMMPS
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 # this is a comment
text inside the curly brackets. If no curly brackets follow the $, timestep 1.0 # this is also a comment
then the variable name is the single character immediately following
the $. Thus ${myTemp} and $x refer to variable names "myTemp" and
"x".
How the variable is converted to a text string depends on what style .. _three:
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 3. The line is searched repeatedly for $ characters, which indicate
inside the parenthesis is treated as an "immediate" variable and variables that are replaced with a text string. The exception to
evaluated as an :doc:`equal-style variable <variable>`. This is a way this rule is described in :ref:`6 <six>`.
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
variable X equal (xlo+xhi)/2+sqrt(v_area)
region 1 block $X 2 INF INF EDGE EDGE
variable X delete
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" 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".
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
specified a high-precision "%.20g" is used as the default.
This can be useful for formatting print output to a desired precision:
.. code-block:: LAMMPS .. code-block:: LAMMPS
variable X equal (xlo+xhi)/2+sqrt(v_area) print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom"
region 1 block $X 2 INF INF EDGE EDGE
variable X delete
can be replaced by 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
.. code-block:: LAMMPS variable a equal 2
variable b2 equal 4
print "B2 = ${b$a}"
region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE 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>`.
so that you do not have to define (or discard) a temporary variable X. 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.
Additionally, the "immediate" variable expression may be followed by a .. _four:
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
specified a high-precision "%.20g" is used as the default.
This can be useful for formatting print output to a desired precision: 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.
.. _five:
5. The first word is the command name. All successive words in the line
are arguments.
.. code-block:: LAMMPS .. _six:
print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom" 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:
Note that neither the curly-bracket or immediate form of variables can .. code-block:: LAMMPS
contain nested $ characters for other variables to substitute for.
Thus you cannot do this:
print "Volume = $v"
.. code-block:: LAMMPS print 'Volume = $v'
if "${steps} > 1000" then quit
variable a equal 2 variable a string "red green blue &
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>`.
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.
(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.
(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:
.. code-block:: LAMMPS
print "Volume = $v"
print 'Volume = $v'
if "${steps} > 1000" then quit
variable a string "red green blue &
purple orange cyan" purple orange cyan"
print """ print """
System volume = $v System volume = $v
System temperature = $t System temperature = $t
""" """
In each case, the single, double, or triple quotes are removed when In each case, the single, double, or triple quotes are removed when
the single argument they enclose is stored internally. 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:: .. note::

52
doc/src/Commands_structure.rst
View File

@ -8,17 +8,20 @@ page.
A LAMMPS input script typically has 4 parts: 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 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 simulation, change some settings, run some more, etc. Each of the 4
parts is now described in more detail. Remember that almost all parts is now described in more detail. Remember that almost all
commands need only be used if a non-default value is desired. 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 Set parameters that need to be defined before atoms are created or
read-in from a file. 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:`angle_style <angle_style>`, :doc:`dihedral_style <dihedral_style>`,
:doc:`improper_style <improper_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 Once atoms and molecular topology are defined, a variety of settings
can be specified: force field coefficients, simulation parameters, 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 Force field coefficients are set by these commands (they can also be
set in the read-in files): :doc:`pair_coeff <pair_coeff>`, 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>`, Output options are set by the :doc:`thermo <thermo>`, :doc:`dump <dump>`,
and :doc:`restart <restart>` commands. and :doc:`restart <restart>` commands.
(4) Run a simulation .. _run:
Run a simulation
------------------------------
A molecular dynamics simulation is run using the :doc:`run <run>` A molecular dynamics simulation is run using the :doc:`run <run>`
command. Energy minimization (molecular statics) is performed using command. Energy minimization (molecular statics) is performed using

22
doc/src/Intro_features.rst
View File

@ -4,17 +4,17 @@ LAMMPS features
LAMMPS is a classical molecular dynamics (MD) code with these general LAMMPS is a classical molecular dynamics (MD) code with these general
classes of functionality: 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>`
---------- ----------