From eaef8089a1f3b714dca4d46513446f5ac9af2079 Mon Sep 17 00:00:00 2001 From: Richard Berger Date: Wed, 6 Nov 2019 16:53:43 -0500 Subject: [PATCH] Add LAMMPSLexer for LAMMPS code-blocks in docs --- doc/src/Commands_input.rst | 4 +- doc/src/Commands_parse.rst | 14 ++- doc/txt/Commands_input.txt | 60 ----------- doc/txt/Commands_parse.txt | 136 ------------------------- doc/utils/sphinx-config/LAMMPSLexer.py | 57 +++++++++++ doc/utils/sphinx-config/conf.py | 6 ++ 6 files changed, 74 insertions(+), 203 deletions(-) delete mode 100644 doc/txt/Commands_input.txt delete mode 100644 doc/txt/Commands_parse.txt create mode 100644 doc/utils/sphinx-config/LAMMPSLexer.py diff --git a/doc/src/Commands_input.rst b/doc/src/Commands_input.rst index 39b11d2639..ce93f65d81 100644 --- a/doc/src/Commands_input.rst +++ b/doc/src/Commands_input.rst @@ -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 diff --git a/doc/src/Commands_parse.rst b/doc/src/Commands_parse.rst index c79dcab4e1..91a11089a8 100644 --- a/doc/src/Commands_parse.rst +++ b/doc/src/Commands_parse.rst @@ -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' diff --git a/doc/txt/Commands_input.txt b/doc/txt/Commands_input.txt deleted file mode 100644 index 8b3dda741b..0000000000 --- a/doc/txt/Commands_input.txt +++ /dev/null @@ -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. - diff --git a/doc/txt/Commands_parse.txt b/doc/txt/Commands_parse.txt deleted file mode 100644 index 13a4c2699d..0000000000 --- a/doc/txt/Commands_parse.txt +++ /dev/null @@ -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. - diff --git a/doc/utils/sphinx-config/LAMMPSLexer.py b/doc/utils/sphinx-config/LAMMPSLexer.py new file mode 100644 index 0000000000..6436be410d --- /dev/null +++ b/doc/utils/sphinx-config/LAMMPSLexer.py @@ -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'), + ] + } diff --git a/doc/utils/sphinx-config/conf.py b/doc/utils/sphinx-config/conf.py index 727a5f7612..70a96e1614 100644 --- a/doc/utils/sphinx-config/conf.py +++ b/doc/utils/sphinx-config/conf.py @@ -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)