From 57711f0dcba834d620ece3126ee830ebc97c4bbe Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sat, 22 Feb 2020 10:39:15 -0500 Subject: [PATCH] improve layout and logical structure. add references --- doc/src/Commands_category.rst | 9 ++ doc/src/Commands_parse.rst | 221 ++++++++++++++++++--------------- doc/src/Commands_structure.rst | 52 +++++--- doc/src/Intro_features.rst | 22 ++-- 4 files changed, 173 insertions(+), 131 deletions(-) diff --git a/doc/src/Commands_category.rst b/doc/src/Commands_category.rst index 6476c73bbb..00d06fed47 100644 --- a/doc/src/Commands_category.rst +++ b/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 `, * :doc:`package `, @@ -15,6 +16,7 @@ Initialization: * :doc:`units ` Setup simulation box: +------------------------------ * :doc:`boundary `, * :doc:`box `, @@ -25,6 +27,7 @@ Setup simulation box: * :doc:`region ` Setup atoms: +------------------------------ * :doc:`atom_modify `, * :doc:`atom_style `, @@ -45,6 +48,7 @@ Setup atoms: * :doc:`velocity ` Force fields: +------------------------------ * :doc:`angle_coeff `, * :doc:`angle_style `, @@ -65,6 +69,7 @@ Force fields: * :doc:`special_bonds ` Settings: +------------------------------ * :doc:`comm_modify `, * :doc:`comm_style `, @@ -80,6 +85,7 @@ Settings: * :doc:`timestep ` Operations within timestepping (fixes) and diagnostics (computes): +------------------------------------------------------------------------------------------ * :doc:`compute `, * :doc:`compute_modify `, @@ -89,6 +95,7 @@ Operations within timestepping (fixes) and diagnostics (computes): * :doc:`unfix ` Output: +------------------------------ * :doc:`dump image `, * :doc:`dump movie `, @@ -105,6 +112,7 @@ Output: * :doc:`write_restart ` Actions: +------------------------------ * :doc:`minimize `, * :doc:`neb `, @@ -116,6 +124,7 @@ Actions: * :doc:`temper ` Input script control: +------------------------------ * :doc:`clear `, * :doc:`echo `, diff --git a/doc/src/Commands_parse.rst b/doc/src/Commands_parse.rst index ec1c8c1e46..83e7d439ef 100644 --- a/doc/src/Commands_parse.rst +++ b/doc/src/Commands_parse.rst @@ -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 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 -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. +.. _one: -(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. +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 :ref:`6 ` + 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 `. 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 -variables that are replaced with a text string. See an exception in -(6). + .. code-block:: LAMMPS -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". + # this is a comment + timestep 1.0 # this is also a comment -How the variable is converted to a text string depends on what style -of variable it is; see the :doc:`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. +.. _three: -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 `. 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: +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 `. + + 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 ` 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 `. 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) - region 1 block $X 2 INF INF EDGE EDGE - variable X delete + print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom" -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 `. -so that you do not have to define (or discard) a temporary variable X. + See the :doc:`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 -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. +.. _four: -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 -contain nested $ characters for other variables to substitute for. -Thus you cannot do this: + .. code-block:: LAMMPS - -.. code-block:: LAMMPS - - variable a equal 2 - 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 `. - -See the :doc:`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 & + print "Volume = $v" + print 'Volume = $v' + if "${steps} > 1000" then quit + variable a string "red green blue & purple orange cyan" - print """ - System volume = $v - System temperature = $t - """ + print """ + System volume = $v + System temperature = $t + """ -In each case, the single, double, or triple quotes are removed when -the single argument they enclose is stored internally. + 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 `, :doc:`print `, -:doc:`if `, and :doc:`python ` commands for examples. + See the :doc:`dump modify format `, :doc:`print + `, :doc:`if `, and :doc:`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 ` or substituted for as a + variable in :ref:`3 `. .. note:: diff --git a/doc/src/Commands_structure.rst b/doc/src/Commands_structure.rst index cd96007bf2..4ffd95e6fc 100644 --- a/doc/src/Commands_structure.rst +++ b/doc/src/Commands_structure.rst @@ -8,17 +8,20 @@ page. A LAMMPS input script typically has 4 parts: -1. Initialization -2. Atom definition -3. Settings -4. Run a simulation +1. :ref:`Initialization ` +2. :ref:`System definition ` +3. :ref:`Settings ` +4. :ref:`Run a simulation ` 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 `, :doc:`dihedral_style `, :doc:`improper_style `. -(2) Atom definition +.. _system: -There are 3 ways to define atoms in LAMMPS. Read them in from a data -or restart file via the :doc:`read_data ` or -:doc:`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 `, -:doc:`region `, :doc:`create_box `, -:doc:`create_atoms `. The entire set of atoms can be -duplicated to make a larger simulation using the -:doc:`replicate ` command. +System definition +------------------------------ -(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 +` or :doc:`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 `, :doc:`region `, :doc:`create_box +`, :doc:`create_atoms ` or +:doc:`read_dump `. + +The entire set of atoms can be duplicated to make a larger simulation +using the :doc:`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 `, @@ -77,7 +90,10 @@ commands. Output options are set by the :doc:`thermo `, :doc:`dump `, and :doc:`restart ` commands. -(4) Run a simulation +.. _run: + +Run a simulation +------------------------------ A molecular dynamics simulation is run using the :doc:`run ` command. Energy minimization (molecular statics) is performed using diff --git a/doc/src/Intro_features.rst b/doc/src/Intro_features.rst index 3c3419ce05..7c25a6f09b 100644 --- a/doc/src/Intro_features.rst +++ b/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 ` -* :ref:`Particle and model types ` -* :ref:`Interatomic potentials (force fields) ` -* :ref:`Atom creation ` -* :ref:`Ensembles, constraints, and boundary conditions ` -* :ref:`Integrators ` -* :ref:`Diagnostics ` -* :ref:`Output ` -* :ref:`Multi-replica models ` -* :ref:`Pre- and post-processing ` -* :ref:`Specialized features (beyond MD itself) ` +1. :ref:`General features ` +2. :ref:`Particle and model types ` +3. :ref:`Interatomic potentials (force fields) ` +4. :ref:`Atom creation ` +5. :ref:`Ensembles, constraints, and boundary conditions ` +6. :ref:`Integrators ` +7. :ref:`Diagnostics ` +8. :ref:`Output ` +9. :ref:`Multi-replica models ` +10. :ref:`Pre- and post-processing ` +11. :ref:`Specialized features (beyond MD itself) ` ----------