lammps/doc/src/Run_options.rst

Command-line options
====================

At run time, LAMMPS recognizes several optional command-line switches
which may be used in any order.  Either the full word or a one or two
letter abbreviation can be used:

* :ref:`-e or -echo <echo>`
* :ref:`-h or -help <help>`
* :ref:`-i or -in <file>`
* :ref:`-k or -kokkos <run-kokkos>`
* :ref:`-l or -log <log>`
* :ref:`-mdi <mdi_flags>`
* :ref:`-m or -mpicolor <mpicolor>`
* :ref:`-c or -cite <cite>`
* :ref:`-nc or -nocite <nocite>`
* :ref:`-nb or -nonbuf <nonbuf>`
* :ref:`-pk or -package <package>`
* :ref:`-p or -partition <partition>`
* :ref:`-pl or -plog <plog>`
* :ref:`-ps or -pscreen <pscreen>`
* :ref:`-ro or -reorder <reorder>`
* :ref:`-r2data or -restart2data <restart2data>`
* :ref:`-r2dump or -restart2dump <restart2dump>`
* :ref:`-r2info or -restart2info <restart2info>`
* :ref:`-sc or -screen <screen>`
* :ref:`-sr or skiprun <skiprun>`
* :ref:`-sf or -suffix <suffix>`
* :ref:`-v or -var <var>`

For example, the lmp_mpi executable might be launched as follows:

.. code-block:: bash

   mpirun -np 16 lmp_mpi -v f tmp.out -l my.log -sc none -i in.alloy
   mpirun -np 16 lmp_mpi -var f tmp.out -log my.log -screen none -in in.alloy

----------

.. _echo:

**-echo style**

Set the style of command echoing.  The style can be *none* or *screen*
or *log* or *both*\ .  Depending on the style, each command read from
the input script will be echoed to the screen and/or logfile.  This
can be useful to figure out which line of your script is causing an
input error.  The default value is *log*\ .  The echo style can also be
set by using the :doc:`echo <echo>` command in the input script itself.

----------

.. _help:

**-help**

Print a brief help summary and a list of options compiled into this
executable for each LAMMPS style (atom_style, fix, compute,
pair_style, bond_style, etc).  This can tell you if the command you
want to use was included via the appropriate package at compile time.
LAMMPS will print the info and immediately exit if this switch is
used.

----------

.. _file:

**-in file**

Specify a file to use as an input script.  This is an optional but
recommended switch when running LAMMPS in one-partition mode.  If it
is not specified, LAMMPS reads its script from standard input, typically
from a script via I/O redirection; e.g. lmp_linux < in.run.
With many MPI implementations I/O redirection also works in parallel,
but using the -in flag will always work.

Note that this is a required switch when running LAMMPS in
multi-partition mode, since multiple processors cannot all read from
stdin concurrently.  The file name may be "none" for starting
multi-partition calculations without reading an initial input file
from the library interface.

----------

.. _run-kokkos:

**-kokkos on/off keyword/value ...**

Explicitly enable or disable KOKKOS support, as provided by the KOKKOS
package.  Even if LAMMPS is built with this package, as described
in the :doc:`the KOKKOS package page <Speed_kokkos>`, this switch must be set to enable
running with KOKKOS-enabled styles the package provides.  If the
switch is not set (the default), LAMMPS will operate as if the KOKKOS
package were not installed; i.e. you can run standard LAMMPS or with
the GPU or OPENMP packages, for testing or benchmarking purposes.

Additional optional keyword/value pairs can be specified which determine
how Kokkos will use the underlying hardware on your platform.  These
settings apply to each MPI task you launch via the ``mpirun`` or
``mpiexec`` command.  You may choose to run one or more MPI tasks per
physical node.  Note that if you are running on a desktop machine, you
typically have one physical node.  On a cluster or supercomputer there
may be dozens or 1000s of physical nodes.

Either the full word or an abbreviation can be used for the keywords.
Note that the keywords do not use a leading minus sign.  I.e. the
keyword is "t", not "-t".  Also note that each of the keywords has a
default setting.  Examples of when to use these options and what
settings to use on different platforms is given on the :doc:`KOKKOS
package <Speed_kokkos>` doc page.

* d or device
* g or gpus
* t or threads

.. parsed-literal::

   device Nd

This option is only relevant if you built LAMMPS with CUDA=yes, you
have more than one GPU per node, and if you are running with only one
MPI task per node.  The Nd setting is the ID of the GPU on the node to
run on.  By default Nd = 0.  If you have multiple GPUs per node, they
have consecutive IDs numbered as 0,1,2,etc.  This setting allows you
to launch multiple independent jobs on the node, each with a single
MPI task per node, and assign each job to run on a different GPU.

.. parsed-literal::

   gpus Ng Ns

This option is only relevant if you built LAMMPS with CUDA=yes, you
have more than one GPU per node, and you are running with multiple MPI
tasks per node (up to one per GPU).  The Ng setting is how many GPUs
you will use.  The Ns setting is optional.  If set, it is the ID of a
GPU to skip when assigning MPI tasks to GPUs.  This may be useful if
your desktop system reserves one GPU to drive the screen and the rest
are intended for computational work like running LAMMPS.  By default
Ng = 1 and Ns is not set.

Depending on which flavor of MPI you are running, LAMMPS will look for
one of these 4 environment variables

.. parsed-literal::

   SLURM_LOCALID (various MPI variants compiled with SLURM support)
   MPT_LRANK (HPE MPI)
   MV2_COMM_WORLD_LOCAL_RANK (Mvapich)
   OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI)

which are initialized by the ``srun``, ``mpirun``, or ``mpiexec``
commands.  The environment variable setting for each MPI rank is used to
assign a unique GPU ID to the MPI task.

.. parsed-literal::

   threads Nt

This option assigns Nt number of threads to each MPI task for
performing work when Kokkos is executing in OpenMP or pthreads mode.
The default is Nt = 1, which essentially runs in MPI-only mode.  If
there are Np MPI tasks per physical node, you generally want Np\*Nt =
the number of physical cores per node, to use your available hardware
optimally.  This also sets the number of threads used by the host when
LAMMPS is compiled with CUDA=yes.

.. deprecated:: 22Dec2022

Support for the "numa" or "n" option was removed as its functionality
was ignored in Kokkos for some time already.

----------

.. _log:

**-log file**

Specify a log file for LAMMPS to write status information to.  In
one-partition mode, if the switch is not used, LAMMPS writes to the
file log.lammps.  If this switch is used, LAMMPS writes to the
specified file.  In multi-partition mode, if the switch is not used, a
log.lammps file is created with high-level status information.  Each
partition also writes to a log.lammps.N file where N is the partition
ID.  If the switch is specified in multi-partition mode, the high-level
logfile is named "file" and each partition also logs information to a
file.N.  For both one-partition and multi-partition mode, if the
specified file is "none", then no log files are created.  Using a
:doc:`log <log>` command in the input script will override this setting.
Option -plog will override the name of the partition log files file.N.

----------

.. _mdi_flags:

**-mdi 'multiple flags'**

This flag is only recognized and used when LAMMPS has support for the MolSSI
Driver Interface (MDI) included as part of the :ref:`MDI <PKG-MDI>`
package.  This flag is specific to the MDI library and controls how LAMMPS
interacts with MDI.  There are usually multiple flags that have to follow it
and those have to be placed in quotation marks.  For more information about
how to launch LAMMPS in MDI client/server mode please refer to the
:doc:`MDI Howto <Howto_mdi>`.

----------

.. _mpicolor:

**-mpicolor color**

If used, this must be the first command-line argument after the LAMMPS
executable name.  It is only used when LAMMPS is launched by an mpirun
command which also launches another executable(s) at the same time.
(The other executable could be LAMMPS as well.)  The color is an
integer value which should be different for each executable (another
application may set this value in a different way).  LAMMPS and the
other executable(s) perform an MPI_Comm_split() with their own colors
to shrink the MPI_COMM_WORLD communication to be the subset of
processors they are actually running on.

----------

.. _cite:

**-cite style** or **file name**

Select how and where to output a reminder about citing contributions
to the LAMMPS code that were used during the run. Available keywords
for styles are "both", "none", "screen", or "log".  Any other keyword
will be considered a file name to write the detailed citation info to
instead of logfile or screen.  Default is the "log" style where there
is a short summary in the screen output and detailed citations
in BibTeX format in the logfile.  The option "both" selects the detailed
output for both, "none", the short output for both, and "screen" will
write the detailed info to the screen and the short version to the log
file.  If a dedicated citation info file is requested, the screen and
log file output will be in the short format (same as with "none").

See the :doc:`citation page <Intro_citing>` for more details on
how to correctly reference and cite LAMMPS.

----------

.. _nocite:

**-nocite**

Disable generating a citation reminder (see above) at all.

----------

.. _nonbuf:

**-nonbuf**

.. versionadded:: 15Sep2022

Turn off buffering for screen and logfile output.  For performance
reasons, output to the screen and logfile is usually buffered, i.e.
output is only written to a file if its buffer - typically 4096 bytes -
has been filled.  When LAMMPS crashes for some reason, however, that can
mean that there is important output missing.  With this flag the
buffering can be turned off (only for screen and logfile output) and any
output will be committed immediately.  Note that when running in
parallel with MPI, the screen output may still be buffered by the MPI
library and this cannot be changed by LAMMPS.  This flag should only be
used for debugging and not for production simulations as the performance
impact can be significant, especially for large parallel runs.

----------

.. _package:

**-package style args ....**

Invoke the :doc:`package <package>` command with style and args.  The
syntax is the same as if the command appeared at the top of the input
script.  For example ``-package gpu 2`` or ``-pk gpu 2`` is the same as
:doc:`package gpu 2 <package>` in the input script.  The possible styles
and args are documented on the :doc:`package <package>` doc page.  This
switch can be used multiple times, e.g. to set options for the
INTEL and OPENMP packages which can be used together.

Along with the ``-suffix`` command-line switch, this is a convenient
mechanism for invoking accelerator packages and their options without
having to edit an input script.

----------

.. _partition:

**-partition 8x2 4 5 ...**

Invoke LAMMPS in multi-partition mode.  When LAMMPS is run on P
processors and this switch is not used, LAMMPS runs in one partition,
i.e. all P processors run a single simulation.  If this switch is
used, the P processors are split into separate partitions and each
partition runs its own simulation.  The arguments to the switch
specify the number of processors in each partition.  Arguments of the
form MxN mean M partitions, each with N processors.  Arguments of the
form N mean a single partition with N processors.  The sum of
processors in all partitions must equal P.  Thus the command
``-partition 8x2 4 5`` has 10 partitions and runs on a total of 25
processors.

Running with multiple partitions can be useful for running
:doc:`multi-replica simulations <Howto_replica>`, where each replica
runs on one or a few processors.  Note that with MPI installed on a
machine (e.g. your desktop), you can run on more (virtual) processors
than you have physical processors.

To run multiple independent simulations from one input script, using
multiple partitions, see the :doc:`Howto multiple <Howto_multiple>`
page.  World- and universe-style :doc:`variables <variable>` are useful
in this context.

----------

.. _plog:

**-plog file**

Specify the base name for the partition log files, so partition N
writes log information to file.N. If file is none, then no partition
log files are created.  This overrides the filename specified in the
-log command-line option.  This option is useful when working with
large numbers of partitions, allowing the partition log files to be
suppressed (-plog none) or placed in a subdirectory (-plog
replica_files/log.lammps) If this option is not used the log file for
partition N is log.lammps.N or whatever is specified by the -log
command-line option.

----------

.. _pscreen:

**-pscreen file**

Specify the base name for the partition screen file, so partition N
writes screen information to file.N. If file is "none", then no
partition screen files are created.  This overrides the filename
specified in the -screen command-line option.  This option is useful
when working with large numbers of partitions, allowing the partition
screen files to be suppressed (-pscreen none) or placed in a
subdirectory (-pscreen replica_files/screen).  If this option is not
used the screen file for partition N is screen.N or whatever is
specified by the -screen command-line option.

----------

.. _reorder:

**-reorder**

This option has 2 forms:

.. parsed-literal::

   -reorder nth N
   -reorder custom filename

Reorder the processors in the MPI communicator used to instantiate
LAMMPS, in one of several ways.  The original MPI communicator ranks
all P processors from 0 to P-1.  The mapping of these ranks to
physical processors is done by MPI before LAMMPS begins.  It may be
useful in some cases to alter the rank order.  E.g. to ensure that
cores within each node are ranked in a desired order.  Or when using
the :doc:`run_style verlet/split <run_style>` command with 2 partitions
to ensure that a specific Kspace processor (in the second partition) is
matched up with a specific set of processors in the first partition.
See the :doc:`General tips <Speed_tips>` page for more details.

If the keyword *nth* is used with a setting *N*, then it means every
Nth processor will be moved to the end of the ranking.  This is useful
when using the :doc:`run_style verlet/split <run_style>` command with 2
partitions via the -partition command-line switch.  The first set of
processors will be in the first partition, the second set in the second
partition.  The -reorder command-line switch can alter this so that
the first N procs in the first partition and one proc in the second partition
will be ordered consecutively, e.g. as the cores on one physical node.
This can boost performance.  For example, if you use ``-reorder nth 4``
and ``-partition 9 3`` and you are running on 12 processors, the
processors will be reordered from

.. parsed-literal::

   0 1 2 3 4 5 6 7 8 9 10 11

to

.. parsed-literal::

   0 1 2 4 5 6 8 9 10 3 7 11

so that the processors in each partition will be

.. parsed-literal::

   0 1 2 4 5 6 8 9 10
   3 7 11

See the "processors" command for how to ensure processors from each
partition could then be grouped optimally for quad-core nodes.

If the keyword is *custom*, then a file that specifies a permutation
of the processor ranks is also specified.  The format of the reorder
file is as follows.  Any number of initial blank or comment lines
(starting with a "#" character) can be present.  These should be
followed by P lines of the form:

.. parsed-literal::

   I J

where P is the number of processors LAMMPS was launched with.  Note
that if running in multi-partition mode (see the -partition switch
above) P is the total number of processors in all partitions.  The I
and J values describe a permutation of the P processors.  Every I and
J should be values from 0 to P-1 inclusive.  In the set of P I values,
every proc ID should appear exactly once.  Ditto for the set of P J
values.  A single I,J pairing means that the physical processor with
rank I in the original MPI communicator will have rank J in the
reordered communicator.

Note that rank ordering can also be specified by many MPI
implementations, either by environment variables that specify how to
order physical processors, or by config files that specify what
physical processors to assign to each MPI rank.  The -reorder switch
simply gives you a portable way to do this without relying on MPI
itself.  See the :doc:`processors file <processors>` command for how
to output info on the final assignment of physical processors to
the LAMMPS simulation domain.

----------

.. _restart2data:

**-restart2data restartfile datafile keyword value ...**

Convert the restart file into a data file and immediately exit.  This
is the same operation as if the following 2-line input script were
run:

.. code-block:: LAMMPS

   read_restart restartfile
   write_data datafile keyword value ...

The specified restartfile and/or datafile name may contain the wild-card
character "\*".  The restartfile name may also contain the wild-card
character "%".  The meaning of these characters is explained on the
:doc:`read_restart <read_restart>` and :doc:`write_data <write_data>` doc
pages.  The use of "%" means that a parallel restart file can be read.
Note that a filename such as file.\* may need to be enclosed in quotes or
the "\*" character prefixed with a backslash ("\") to avoid shell
expansion of the "\*" character.

The syntax following restartfile, namely

.. parsed-literal::

   datafile keyword value ...

is identical to the arguments of the :doc:`write_data <write_data>`
command.  See its documentation page for details.  This includes its
optional keyword/value settings.

----------

.. _restart2dump:

**-restart2dump restartfile group-ID dumpstyle dumpfile arg1 arg2 ...**

Convert the restart file into a dump file and immediately exit.  This
is the same operation as if the following 2-line input script were
run:

.. code-block:: LAMMPS

   read_restart restartfile
   write_dump group-ID dumpstyle dumpfile arg1 arg2 ...

Note that the specified restartfile and dumpfile names may contain
wild-card characters ("\*" or "%") as explained on the
:doc:`read_restart <read_restart>` and :doc:`write_dump <write_dump>` doc
pages.  The use of "%" means that a parallel restart file and/or
parallel dump file can be read and/or written.  Note that a filename
such as file.\* may need to be enclosed in quotes or the "\*" character
prefixed with a backslash ("\") to avoid shell expansion of the "\*"
character.

The syntax following restartfile, namely

.. code-block:: LAMMPS

   group-ID dumpstyle dumpfile arg1 arg2 ...

is identical to the arguments of the :doc:`write_dump <write_dump>`
command.  See its documentation page for details.  This includes what
per-atom fields are written to the dump file and optional dump_modify
settings, including ones that affect how parallel dump files are written,
e.g. the *nfile* and *fileper* keywords.  See the
:doc:`dump_modify <dump_modify>` page for details.

----------

.. _restart2info:

**-restart2info restartfile keyword ...**

.. versionadded:: TBD

Write out some info about the restart file and and immediately exit.
This is the same operation as if the following 2-line input script were
run:

.. code-block:: LAMMPS

   read_restart restartfile
   info system group computes fixes

The specified restartfile name may contain the wild-card character "\*".
The restartfile name may also contain the wild-card character "%".  The
meaning of these characters is explained on the :doc:`read_restart
<read_restart>` documentation.  The use of "%" means that a parallel
restart file can be read.  Note that a filename such as file.\* may need
to be enclosed in quotes or the "\*" character prefixed with a backslash
("\") to avoid shell expansion of the "\*" character.

Optional keywords may follow the restartfile argument.  These must be
valid keywords for the :doc:`info command <info>`.  The most useful
ones - *system*, *group*, *computes*, and *fixes* - are already applied.
Appending keywords like *coeffs* or *communication* may provide
additional useful information stored in the restart file.

----------

.. _screen:

**-screen file**

Specify a file for LAMMPS to write its screen information to.  In
one-partition mode, if the switch is not used, LAMMPS writes to the
screen.  If this switch is used, LAMMPS writes to the specified file
instead and you will see no screen output.  In multi-partition mode,
if the switch is not used, high-level status information is written to
the screen.  Each partition also writes to a screen.N file where N is
the partition ID.  If the switch is specified in multi-partition mode,
the high-level screen dump is named "file" and each partition also
writes screen information to a file.N.  For both one-partition and
multi-partition mode, if the specified file is "none", then no screen
output is performed. Option -pscreen will override the name of the
partition screen files file.N.

----------

.. _skiprun:

**-skiprun**

Insert the command :doc:`timer timeout 0 every 1 <timer>` at the
beginning of an input file or after a :doc:`clear <clear>` command.
This has the effect that the entire LAMMPS input script is processed
without executing actual :doc:`run <run>` or :doc:`minimize <minimize>`
and similar commands (their main loops are skipped).  This can be
helpful and convenient to test input scripts of long running
calculations for correctness to avoid having them crash after a
long time due to a typo or syntax error in the middle or at the end.

----------

.. _suffix:

**-suffix style args**

Use variants of various styles if they exist.  The specified style can
be *gpu*, *intel*, *kk*, *omp*, *opt*, or *hybrid*\ .  These
refer to optional packages that LAMMPS can be built with, as described
in :doc:`Accelerate performance <Speed>`.  The "gpu" style corresponds to the
GPU package, the "intel" style to the INTEL package, the "kk"
style to the KOKKOS package, the "opt" style to the OPT package, and
the "omp" style to the OPENMP package. The hybrid style is the only
style that accepts arguments. It allows for two packages to be
specified. The first package specified is the default and will be used
if it is available. If no style is available for the first package,
the style for the second package will be used if available. For
example, ``-suffix hybrid intel omp`` will use styles from the
INTEL package if they are installed and available, but styles for
the OPENMP package otherwise.

Along with the ``-package`` command-line switch, this is a convenient
mechanism for invoking accelerator packages and their options without
having to edit an input script.

As an example, all of the packages provide a :doc:`pair_style lj/cut <pair_lj>` variant, with style names lj/cut/gpu,
lj/cut/intel, lj/cut/kk, lj/cut/omp, and lj/cut/opt.  A variant style
can be specified explicitly in your input script, e.g. pair_style
lj/cut/gpu.  If the -suffix switch is used the specified suffix
(gpu,intel,kk,omp,opt) is automatically appended whenever your input
script command creates a new :doc:`atom style <atom_style>`,
:doc:`pair style <pair_style>`, :doc:`fix <fix>`,
:doc:`compute <compute>`, or :doc:`run style <run_style>`.  If the
variant version does not exist, the standard version is created.

For the GPU package, using this command-line switch also invokes the
default GPU settings, as if the command "package gpu 1" were used at
the top of your input script.  These settings can be changed by using
the ``-package gpu`` command-line switch or the :doc:`package gpu <package>` command in your script.

For the INTEL package, using this command-line switch also
invokes the default INTEL settings, as if the command "package
intel 1" were used at the top of your input script.  These settings
can be changed by using the ``-package intel`` command-line switch or
the :doc:`package intel <package>` command in your script. If the
OPENMP package is also installed, the hybrid style with "intel omp"
arguments can be used to make the omp suffix a second choice, if a
requested style is not available in the INTEL package.  It will
also invoke the default OPENMP settings, as if the command "package
omp 0" were used at the top of your input script.  These settings can
be changed by using the ``-package omp`` command-line switch or the
:doc:`package omp <package>` command in your script.

For the KOKKOS package, using this command-line switch also invokes
the default KOKKOS settings, as if the command "package kokkos" were
used at the top of your input script.  These settings can be changed
by using the ``-package kokkos`` command-line switch or the :doc:`package kokkos <package>` command in your script.

For the OMP package, using this command-line switch also invokes the
default OMP settings, as if the command "package omp 0" were used at
the top of your input script.  These settings can be changed by using
the ``-package omp`` command-line switch or the :doc:`package omp <package>` command in your script.

The :doc:`suffix <suffix>` command can also be used within an input
script to set a suffix, or to turn off or back on any suffix setting
made via the command line.

----------

.. _var:

**-var name value1 value2 ...**

Specify a variable that will be defined for substitution purposes when
the input script is read.  This switch can be used multiple times to
define multiple variables.  "Name" is the variable name which can be a
single character (referenced as $x in the input script) or a full
string (referenced as ${abc}).  An :doc:`index-style variable <variable>` will be created and populated with the
subsequent values, e.g. a set of filenames.  Using this command-line
option is equivalent to putting the line "variable name index value1
value2 ..."  at the beginning of the input script.  Defining an index
variable as a command-line argument overrides any setting for the same
index variable in the input script, since index variables cannot be
re-defined.

See the :doc:`variable <variable>` command for more info on defining
index and other kinds of variables and the :doc:`Parsing rules <Commands_parse>`
page for more info on using variables in input scripts.

.. note::

   Currently, the command-line parser looks for arguments that
   start with "-" to indicate new switches.  Thus you cannot specify
   multiple variable values if any of them start with a "-", e.g. a
   negative numeric value.  It is OK if the first value1 starts with a
   "-", since it is automatically skipped.