Add LAMMPSLexer for LAMMPS code-blocks in docs

Thus this sequence of commands:

.. parsed-literal::

.. code-block:: LAMMPS

   timestep 0.5

   run      100

does something different than this sequence:

.. parsed-literal::

.. code-block:: LAMMPS

   run      100

   timestep 0.5

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

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

can be replaced by

.. parsed-literal::

.. code-block:: LAMMPS

   region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE

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"

Thus you cannot do this:

.. parsed-literal::

.. code-block:: LAMMPS

   variable        a equal 2

   variable        b2 equal 4

needed.  For example:

.. parsed-literal::

.. code-block:: LAMMPS

   print "Volume = $v"

   print 'Volume = $v'

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

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

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'),

        ]

    }