Add LAMMPSLexer for LAMMPS code-blocks in docs
This commit is contained in:
Richard Berger
@ -17,7 +17,7 @@ one line at a time and each command takes effect when it is read.
|
||||
Thus this sequence of commands:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
timestep 0.5
|
||||
run 100
|
||||
@ -26,7 +26,7 @@ Thus this sequence of commands:
|
||||
does something different than this sequence:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
run 100
|
||||
timestep 0.5
|
||||
|
||||
@ -22,6 +22,10 @@ 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
|
||||
|
||||
(3) The line is searched repeatedly for $ characters, which indicate
|
||||
variables that are replaced with a text string. See an exception in
|
||||
(6).
|
||||
@ -47,7 +51,7 @@ to use numeric formulas in an input script without having to assign
|
||||
them to variable names. For example, these 3 input script lines:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
variable X equal (xlo+xhi)/2+sqrt(v_area)
|
||||
region 1 block $X 2 INF INF EDGE EDGE
|
||||
@ -56,7 +60,7 @@ them to variable names. For example, these 3 input script lines:
|
||||
can be replaced by
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE
|
||||
|
||||
@ -72,7 +76,7 @@ specified a high-precision "%.20g" is used as the default.
|
||||
This can be useful for formatting print output to a desired precision:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom"
|
||||
|
||||
@ -81,7 +85,7 @@ contain nested $ characters for other variables to substitute for.
|
||||
Thus you cannot do this:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
variable a equal 2
|
||||
variable b2 equal 4
|
||||
@ -113,7 +117,7 @@ can be enclosed in triple quotes, in which case "&" characters are not
|
||||
needed. For example:
|
||||
|
||||
|
||||
.. parsed-literal::
|
||||
.. code-block:: LAMMPS
|
||||
|
||||
print "Volume = $v"
|
||||
print 'Volume = $v'
|
||||
|
||||
@ -1,60 +0,0 @@
|
||||
"Higher level section"_Commands.html - "LAMMPS WWW Site"_lws - "LAMMPS
|
||||
Documentation"_ld - "LAMMPS Commands"_lc :c
|
||||
|
||||
:link(lws,http://lammps.sandia.gov)
|
||||
:link(ld,Manual.html)
|
||||
:link(lc,Commands_all.html)
|
||||
|
||||
:line
|
||||
|
||||
LAMMPS input scripts :h3
|
||||
|
||||
LAMMPS executes by reading commands from a input script (text file),
|
||||
one line at a time. When the input script ends, LAMMPS exits. Each
|
||||
command causes LAMMPS to take some action. It may set an internal
|
||||
variable, read in a file, or run a simulation. Most commands have
|
||||
default settings, which means you only need to use the command if you
|
||||
wish to change the default.
|
||||
|
||||
In many cases, the ordering of commands in an input script is not
|
||||
important. However the following rules apply:
|
||||
|
||||
(1) LAMMPS does not read your entire input script and then perform a
|
||||
simulation with all the settings. Rather, the input script is read
|
||||
one line at a time and each command takes effect when it is read.
|
||||
Thus this sequence of commands:
|
||||
|
||||
timestep 0.5
|
||||
run 100
|
||||
run 100 :pre
|
||||
|
||||
does something different than this sequence:
|
||||
|
||||
run 100
|
||||
timestep 0.5
|
||||
run 100 :pre
|
||||
|
||||
In the first case, the specified timestep (0.5 fs) is used for two
|
||||
simulations of 100 timesteps each. In the 2nd case, the default
|
||||
timestep (1.0 fs) is used for the 1st 100 step simulation and a 0.5 fs
|
||||
timestep is used for the 2nd one.
|
||||
|
||||
(2) Some commands are only valid when they follow other commands. For
|
||||
example you cannot set the temperature of a group of atoms until atoms
|
||||
have been defined and a group command is used to define which atoms
|
||||
belong to the group.
|
||||
|
||||
(3) Sometimes command B will use values that can be set by command A.
|
||||
This means command A must precede command B in the input script if it
|
||||
is to have the desired effect. For example, the
|
||||
"read_data"_read_data.html command initializes the system by setting
|
||||
up the simulation box and assigning atoms to processors. If default
|
||||
values are not desired, the "processors"_processors.html and
|
||||
"boundary"_boundary.html commands need to be used before read_data to
|
||||
tell LAMMPS how to map processors to the simulation box.
|
||||
|
||||
Many input script errors are detected by LAMMPS and an ERROR or
|
||||
WARNING message is printed. The "Errors"_Errors.html doc page gives
|
||||
more information on what errors mean. The documentation for each
|
||||
command lists restrictions on how the command can be used.
|
||||
|
||||
@ -1,136 +0,0 @@
|
||||
"Higher level section"_Commands.html - "LAMMPS WWW Site"_lws - "LAMMPS
|
||||
Documentation"_ld - "LAMMPS Commands"_lc :c
|
||||
|
||||
:link(lws,http://lammps.sandia.gov)
|
||||
:link(ld,Manual.html)
|
||||
:link(lc,Commands_all.html)
|
||||
|
||||
:line
|
||||
|
||||
Parsing rules for input scripts :h3
|
||||
|
||||
Each non-blank line in the input script is treated as a command.
|
||||
LAMMPS commands are case sensitive. Command names are lower-case, as
|
||||
are specified command arguments. Upper case letters may be used in
|
||||
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.
|
||||
|
||||
(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.
|
||||
|
||||
(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".
|
||||
|
||||
How the variable is converted to a text string depends on what style
|
||||
of variable it is; see the "variable"_variable.html 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 "equal-style variable"_variable.html. 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:
|
||||
|
||||
variable X equal (xlo+xhi)/2+sqrt(v_area)
|
||||
region 1 block $X 2 INF INF EDGE EDGE
|
||||
variable X delete :pre
|
||||
|
||||
can be replaced by
|
||||
|
||||
region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE :pre
|
||||
|
||||
so that you do not have to define (or discard) a temporary variable X.
|
||||
|
||||
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:
|
||||
|
||||
print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom" :pre
|
||||
|
||||
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:
|
||||
|
||||
variable a equal 2
|
||||
variable b2 equal 4
|
||||
print "B2 = $\{b$a\}" :pre
|
||||
|
||||
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
|
||||
"equal-style variable"_variable.html.
|
||||
|
||||
See the "variable"_variable.html 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:
|
||||
|
||||
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
|
||||
""" :pre
|
||||
|
||||
In each case, the single, double, or triple quotes are removed when
|
||||
the single argument they enclose is stored internally.
|
||||
|
||||
See the "dump modify format"_dump_modify.html, "print"_print.html,
|
||||
"if"_if.html, and "python"_python.html 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).
|
||||
|
||||
NOTE: If the argument is itself a command that requires a quoted
|
||||
argument (e.g. using a "print"_print.html command as part of an
|
||||
"if"_if.html or "run every"_run.html command), then single, double, or
|
||||
triple quotes can be nested in the usual manner. See the doc pages
|
||||
for those commands for examples. Only one of level of nesting is
|
||||
allowed, but that should be sufficient for most use cases.
|
||||
|
||||
57
doc/utils/sphinx-config/LAMMPSLexer.py
Normal file
57
doc/utils/sphinx-config/LAMMPSLexer.py
Normal file
@ -0,0 +1,57 @@
|
||||
from pygments.lexer import RegexLexer, words
|
||||
from pygments.token import *
|
||||
|
||||
LAMMPS_COMMANDS = ("angle_coeff", "angle_style", "atom_modify", "atom_style",
|
||||
"balance", "bond_coeff", "bond_style", "bond_write", "boundary", "box",
|
||||
"change_box", "clear", "comm_modify", "comm_style", "compute",
|
||||
"compute_modify", "create_atoms", "create_bonds", "create_box", "delete_atoms",
|
||||
"delete_bonds", "dielectric", "dihedral_coeff", "dihedral_style", "dimension",
|
||||
"displace_atoms", "dump", "dump_modify", "dynamical_matrix", "echo", "fix",
|
||||
"fix_modify", "group", "group2ndx", "hyper", "if", "improper_coeff",
|
||||
"improper_style", "include", "info", "jump", "kim_init", "kim_interactions",
|
||||
"kim_param", "kim_query", "kspace_modify", "kspace_style", "label", "lattice",
|
||||
"log", "mass", "message", "minimize", "min_modify", "min_style", "molecule",
|
||||
"ndx2group", "neb", "neb/spin", "neighbor", "neigh_modify", "newton", "next",
|
||||
"package", "pair_coeff", "pair_modify", "pair_style", "pair_write",
|
||||
"partition", "prd", "print", "processors", "python", "quit", "read_data",
|
||||
"read_dump", "read_restart", "region", "replicate", "rerun", "reset_ids",
|
||||
"reset_timestep", "restart", "run", "run_style", "server", "set", "shell",
|
||||
"special_bonds", "suffix", "tad", "temper", "temper/grem", "temper/npt",
|
||||
"thermo", "thermo_modify", "thermo_style", "then", "third_order", "timer", "timestep",
|
||||
"uncompute", "undump", "unfix", "units", "variable", "velocity", "write_coeff",
|
||||
"write_data", "write_dump", "write_restart")
|
||||
|
||||
class LAMMPSLexer(RegexLexer):
|
||||
name = 'LAMMPS'
|
||||
tokens = {
|
||||
'root': [
|
||||
(words(LAMMPS_COMMANDS, suffix=r'\b', prefix=r'^'), Keyword),
|
||||
(r'#.*?\n', Comment),
|
||||
('"', String, 'string'),
|
||||
('\'', String, 'single_quote_string'),
|
||||
(r'[0-9]+(\.[0-9]+)?([eE]\-?[0-9]+)?', Number),
|
||||
('\$?\(', Name.Variable, 'expression'),
|
||||
('\$\{', Name.Variable, 'variable'),
|
||||
(r'[\w_\.\[\]]+', Name),
|
||||
(r'\$[\w_]+', Name.Variable),
|
||||
(r'\s+', Whitespace),
|
||||
(r'[\+\-\*\/&=<>]', Operator),
|
||||
],
|
||||
'variable' : [
|
||||
('[^\}]+', Name.Variable),
|
||||
('\}', Name.Variable, '#pop'),
|
||||
],
|
||||
'string' : [
|
||||
('[^"]+', String),
|
||||
('"', String, '#pop'),
|
||||
],
|
||||
'single_quote_string' : [
|
||||
('[^\']+', String),
|
||||
('\'', String, '#pop'),
|
||||
],
|
||||
'expression' : [
|
||||
('[^\(\)]+', Name.Variable),
|
||||
('\(', Name.Variable, 'expression'),
|
||||
('\)', Name.Variable, '#pop'),
|
||||
]
|
||||
}
|
||||
@ -317,3 +317,9 @@ if spelling_spec:
|
||||
|
||||
spelling_lang='en_US'
|
||||
spelling_word_list_filename='false_positives.txt'
|
||||
|
||||
sys.path.append(os.path.join(os.path.dirname(__file__), '.'))
|
||||
import LAMMPSLexer
|
||||
from sphinx.highlighting import lexers
|
||||
|
||||
lexers['LAMMPS'] = LAMMPSLexer.LAMMPSLexer(startinline=True)
|
||||
|
||||
Reference in New Issue
Block a user