5.2. Parsing rules for input scripts

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.

  1. All characters from the first “#” character onward are treated as comment and discarded. The exception to this rule is described 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.

    # this is a comment
timestep  1.0   # this is also a comment

  1. 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 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 variable 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. 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

    can be replaced by:

    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:

    print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom"

    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:

    variable        a equal 2
variable        b2 equal 4
print           "B2 = ${b$a}"

    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 equal-style variable.

    See the variable command for more details of how strings are assigned to variables and evaluated, and how they can be used in input script commands.

  1. The line is broken into “words” separated by white-space (tabs, spaces). Note that words can thus contain letters, digits, underscores, or punctuation characters.

  1. The first word is the command name. All successive words in the line are arguments.

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

    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, print, if, and 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.

Note

If the argument is itself a command that requires a quoted argument (e.g. using a print command as part of an if or run every 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.

ASCII versus UTF-8

LAMMPS expects and processes 7-bit ASCII format text internally. Many modern environments use UTF-8 encoding, which is a superset of the 7-bit ASCII character table and thus mostly compatible. However, there are several non-ASCII characters that can look very similar to their ASCII equivalents or are invisible (so they look like a blank), but are encoded differently. Web browsers, PDF viewers, document editors are known to sometimes replace one with the other for a better looking output. However, that can lead to problems, for instance, when using cut-n-paste of input file examples from web pages, or when using a document editor (not a dedicated plain text editor) for writing LAMMPS inputs. LAMMPS will try to detect this and substitute the non-ASCII characters with their ASCII equivalents where known. There also is going to be a warning printed, if this occurs. It is recommended to avoid such characters altogether in LAMMPS input, data and potential files. The replacement tables are likely incomplete and dependent on users reporting problems processing correctly looking input containing UTF-8 encoded non-ASCII characters.