Run_options.txt 20.1 KB
Newer Older
Richard Berger's avatar
Richard Berger committed
1
"Higher level section"_Run_head.html - "LAMMPS WWW Site"_lws - "LAMMPS
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Commands_all.html)

:line

Command-line options :h3

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:

"-e or -echo"_#echo
"-h or -help"_#help
18
19
"-i or -in"_#file
"-k or -kokkos"_#run-kokkos
20
21
22
23
"-l or -log"_#log
"-nc or -nocite"_#nocite
"-pk or -package"_#package
"-p or -partition"_#partition
24
"-pl or -plog"_#plog
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
"-ps or -pscreen"_#pscreen
"-r or -restart"_#restart
"-ro or -reorder"_#reorder
"-sc or -screen"_#screen
"-sf or -suffix"_#suffix
"-v or -var"_#var :ul

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

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 :pre

:line

[-echo style] :link(echo)

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 "echo"_echo.html command in the input script itself.

:line

[-help] :link(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.

:line

[-in file] :link(file)

Specify a file to use as an input script.  This is an optional 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.  I/O redirection should
also work in parallel, but if it does not (in the unlikely case that
an MPI implementation does not support it), then use the -in flag.
Note that this is a required switch when running LAMMPS in
multi-partition mode, since multiple processors cannot all read from
stdin.

:line

75
[-kokkos on/off keyword/value ...] :link(run-kokkos)
76
77
78

Explicitly enable or disable KOKKOS support, as provided by the KOKKOS
package.  Even if LAMMPS is built with this package, as described
79
in "Speed kokkos"_Speed_kokkos.html, this switch must be set to enable
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
running with the 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 USER-OMP 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 "Speed
kokkos"_Speed_kokkos.html doc page.

d or device
g or gpus
t or threads
n or numa :ul

device Nd :pre

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.

gpus Ng Ns :pre

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 3 environment variables

SLURM_LOCALID (various MPI variants compiled with SLURM support)
MV2_COMM_WORLD_LOCAL_RANK (Mvapich)
OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI) :pre

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.

threads Nt :pre

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.

numa Nm :pre

This option is only relevant when using pthreads with hwloc support.
In this case Nm defines the number of NUMA regions (typically sockets)
on a node which will be utilized by a single MPI rank.  By default Nm
= 1.  If this option is used the total number of worker-threads per
MPI rank is threads*numa.  Currently it is always almost better to
assign at least one MPI rank per NUMA region, and leave numa set to
its default value of 1. This is because letting a single process span
multiple NUMA regions induces a significant amount of cross NUMA data
traffic which is slow.

:line

[-log file] :link(log)

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 hi-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 hi-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
"log"_log.html command in the input script will override this setting.
Option -plog will override the name of the partition log files file.N.

:line

[-nocite] :link(nocite)

Disable writing the log.cite file which is normally written to list
references for specific cite-able features used during a LAMMPS run.
See the "citation page"_http://lammps.sandia.gov/cite.html for more
details.

:line

[-package style args ....] :link(package)

Invoke the "package"_package.html 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
"package gpu 2"_package.html in the input script.  The possible styles
and args are documented on the "package"_package.html doc page.  This
switch can be used multiple times, e.g. to set options for the
USER-INTEL and USER-OMP 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.

:line

[-partition 8x2 4 5 ...] :link(partition)

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
"multi-replica simulations"_Howto_replica.html, where each replica
runs on 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 "Howto multiple"_Howto_multiple.html doc
page.  World- and universe-style "variables"_variable.html are useful
in this context.

:line

[-plog file] :link(plog)

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 sub-directory (-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.

:line

[-pscreen file] :link(pscreen)

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
sub-directory (-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.

:line

[-restart restartfile {remap} datafile keyword value ...] :link(restart)

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:

read_restart restartfile {remap}
write_data datafile keyword value ... :pre

Note that the specified restartfile and datafile can have wild-card
characters ("*",%") as described by the
"read_restart"_read_restart.html and "write_data"_write_data.html
commands.  But a filename such as file.* will need to be enclosed in
quotes to avoid shell expansion of the "*" character.

Note that following restartfile, the optional flag {remap} can be
used.  This has the same effect as adding it to the
"read_restart"_read_restart.html command, as explained on its doc
page.  This is only useful if the reading of the restart file triggers
an error that atoms have been lost.  In that case, use of the remap
flag should allow the data file to still be produced.

Also note that following datafile, the same optional keyword/value
pairs can be listed as used by the "write_data"_write_data.html
command.

:line

[-reorder] :link(reorder)

This option has 2 forms:

-reorder nth N
-reorder custom filename :pre

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 insure that
cores within each node are ranked in a desired order.  Or when using
the "run_style verlet/split"_run_style.html command with 2 partitions
to insure that a specific Kspace processor (in the 2nd partition) is
matched up with a specific set of processors in the 1st partition.
See the "Speed tips"_Speed_tips.html doc 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 "run_style verlet/split"_run_style.html command with 2
partitions via the -partition command-line switch.  The first set of
processors will be in the first partition, the 2nd set in the 2nd
partition.  The -reorder command-line switch can alter this so that
the 1st N procs in the 1st partition and one proc in the 2nd 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

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

to

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

so that the processors in each partition will be

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

See the "processors" command for how to insure 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:

I J :pre

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 "processors out"_processors.html command for how
to output info on the final assignment of physical processors to
the LAMMPS simulation domain.

:line

[-screen file] :link(screen)

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, hi-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 hi-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.

:line

[-suffix style args] :link(suffix)

Use variants of various styles if they exist.  The specified style can
be {cuda}, {gpu}, {intel}, {kk}, {omp}, {opt}, or {hybrid}.  These
refer to optional packages that LAMMPS can be built with, as described
381
in "Accelerate performance"_Speed.html.  The "gpu" style corresponds to the
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
GPU package, the "intel" style to the USER-INTEL package, the "kk"
style to the KOKKOS package, the "opt" style to the OPT package, and
the "omp" style to the USER-OMP 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
USER-INTEL package if they are installed and available, but styles for
the USER-OMP 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 "pair_style
lj/cut"_pair_lj.html 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 "atom"_atom_style.html,
"pair"_pair_style.html, "fix"_fix.html, "compute"_compute.html, or
"run"_run_style.html 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 "package
gpu"_package.html command in your script.

For the USER-INTEL package, using this command-line switch also
invokes the default USER-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 "package intel"_package.html command in your script. If the
USER-OMP 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 USER-INTEL package.  It will
also invoke the default USER-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
"package omp"_package.html 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 "package
kokkos"_package.html 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 "package
omp"_package.html command in your script.

The "suffix"_suffix.html 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.

:line

[-var name value1 value2 ...] :link(var)

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 "index-style
variable"_variable.html 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 "variable"_variable.html command for more info on defining
index and other kinds of variables and the "Commands
parse"_Commands_parse.html 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.