README.md 43.6 KB
Newer Older
1
# Building LAMMPS using CMake
Christoph Junghans's avatar
Christoph Junghans committed
2

3
LAMMPS recently acquired support for building with CMake thanks to the efforts
Richard Berger's avatar
Richard Berger committed
4
of Christoph Junghans (LANL) and Richard Berger (Temple U). One of the key
5
6
7
8
9
10
11
12
13
14
15
16
17
18
strengths of CMake is that it can generate the necessary build system files of
your own personal preference. It also enables using common development IDEs such
as Eclipse, Visual Studio, QtCreator, Xcode and many more for LAMMPS
development.

CMake can both be used as a command-line (CLI) utility `cmake` or through one of
its GUIs. `ccmake` is a text-based ui to configure and build CMake projects.
`cmake-gui` is a graphical frontend for running CMake operations that works on
Linux desktop environments, Windows and MacOS X.

The following is a tutorial-style introduction in using the CMake system. It
should give you the necessary foundation to understand how to do the most common
tasks, act as a reference and provide examples of typical use cases.

Richard Berger's avatar
Richard Berger committed
19
20
21
22
23
24
## Table of Contents

   * [Quick Start for the Impatient](#quick-start-for-the-impatient)
   * [Building LAMMPS using cmake](#building-lammps-using-cmake-1)
      * [Prerequisites](#prerequisites)
      * [Build directory vs. Source Directory](#build-directory-vs-source-directory)
Richard Berger's avatar
Richard Berger committed
25
   * [Defining and using presets](#defining-and-using-presets)
Richard Berger's avatar
Richard Berger committed
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
   * [Reference](#reference)
      * [Common CMAKE Configuration Options](#common-cmake-configuration-options)
      * [LAMMPS Configuration Options](#lammps-configuration-options)
      * [Parallelization and Accelerator Packages](#parallelization-and-accelerator-packages)
      * [Default Packages](#default-packages)
      * [Other Packages](#other-packages)
      * [User Packages](#user-packages)
      * [Package-Specific Configuration Options](#package-specific-configuration-options)
         * [KSPACE Package](#kspace-package)
         * [MKL](#mkl)
         * [FFTW2](#fftw2)
         * [FFTW3](#fftw3)
         * [LAPACK](#lapack)
         * [PYTHON Package](#python-package)
         * [GPU Package](#gpu-package)
         * [VORONOI Package](#voronoi-package)
         * [USER-SMD Package](#user-smd-package)
      * [Optional Features](#optional-features)
         * [zlib support](#zlib-support)
         * [JPEG support](#jpeg-support)
         * [PNG support](#png-support)
         * [GZIP support](#gzip-support)
         * [FFMPEG support](#ffmpeg-support)
      * [Compilers](#compilers)
         * [Building with GNU Compilers](#building-with-gnu-compilers)
         * [Building with Intel Compilers](#building-with-intel-compilers)
         * [Building with LLVM/Clang Compilers](#building-with-llvmclang-compilers)
      * [Examples](#examples)


56
57
58
59
60
61
62
63
64
## Quick Start for the Impatient
If you want to skip ahead and just run the compilation using `cmake`, please
find a minimal example below. Together with the options reference below, this
should get you started.

```bash
git clone https://github.com/lammps/lammps.git
mkdir lammps/build
cd lammps/build
Richard Berger's avatar
Richard Berger committed
65
cmake [-D OPTION_A=VALUE_A -D OPTION_B=VALUE_B ...] ../cmake
66
67
68
69
70
71
72
73
74
75
76
77
78
79
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
make
```

# Building LAMMPS using `cmake`

## Prerequisites
This tutorial assumes you are running in a command-line environment using a
shell like Bash.

* Linux: any terminal window will work
* MacOS X: launch the Terminal app
* Windows 10: install and run "Bash on Windows" (aka Ubuntu on Windows)

Before we start, please download the latest and greatest version of LAMMPS from
GitHub. You can either download it as a tarball or ZIP file, or via git. When
you start with a fresh lammps directory, the contents should look like this:

```bash
$ ls
bench  doc       lib      potentials  README  tools
cmake  examples  LICENSE  python      src
```

## Build directory vs. Source Directory

By using CMake we separate building LAMMPS into multiple phases:

1. **Configuration**: define which features we want to enable/disable and how it should be compiled
2. **Compilation**: compile each source file and generate binaries and libraries based on the configuration
3. **Installation** (Optional): finally we can install the generated binaries on our system

In the GNU Make based build system of LAMMPS, configuration occurs by running
special make targets like `make yes-MOLECULAR`. These targets modify the
**source directory** (`src/`) directory by copying package files and patching
Makefile. In some cases you are force to manually edit Makefiles to add compiler
options and/or correct include directory and library paths.

These edits and copy operations are no longer necessary when compiling with
CMake. The source directory stays untouched, so you compile LAMMPS in many
different variants using the same source code checkout. It enables true
**out-of-source** builds.

When using Cmake, you can compile in **any** folder outside of the source
Richard Berger's avatar
Richard Berger committed
109
directory. Any working directory you choose becomes a so-called **build
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
directory**. All configuration files and compilation results are stored in this
folder. We recommend calling it something like `build/`.

Let's have a look a quick example, where we get the greatest and latest version
of LAMMPS from GitHub via git:
```bash
git clone https://github.com/lammps/lammps.git
```

We then create a new `build` folder and make it our current working directory:
```
mkdir lammps/build
cd lammps/build
```

To configure LAMMPS we run `cmake` inside of this folder. However it requires at
least one argument. `cmake` needs to read the LAMMPS `CMakeLists.txt` file to
know what to do.  This file is located in the `cmake/` subdirectory of the
lammps checkout. To run `cmake` add the relative or absolute path to the `cmake/`
directory  as first argument.

E.g., if the current working directory is `lammps/build` you can specify the
relative path to `lammps/cmake` as follows:
Christoph Junghans's avatar
Christoph Junghans committed
133
```
134
cmake ../cmake
Christoph Junghans's avatar
Christoph Junghans committed
135
136
```

137
You could also specify the absolute path:
Christoph Junghans's avatar
Christoph Junghans committed
138
```
139
cmake /path/to/my/lammps/folder/cmake
Christoph Junghans's avatar
Christoph Junghans committed
140
141
```

142
143
144
145
146
147
148
149
150
Please note: **This does NOT compile the code!** Running cmake only configures
the next build. It generates the necessary files to compile the code. On
Unix/Linux it defaults to generating Makefiles. You can also choose other output
formats to generate files for Eclipse, Xcode or Visual Studio which are
supported on other platorms.

To compile LAMMPS once the Makefiles are generated, simply type `make` in the
build directory.

Christoph Junghans's avatar
Christoph Junghans committed
151
```
152
make
Christoph Junghans's avatar
Christoph Junghans committed
153
```
Richard Berger's avatar
Richard Berger committed
154
155
156
157
158
159
160
161
162
163
164
# Defining and using presets

The CMake build exposes a lot of different options. In the old build system
some of the package selections were possible by using special make target like
`make yes-std` or `make no-lib`. Achieving the same result with cmake requires
specifying all options manually. This can quickly become a very long command
line that is hard to handle.  While these could be stored in a simple script
file, there is another way of defining "presets" to compile LAMMPS in a certain
way.

A preset is a regular CMake script file that can use constructs such as
Richard Berger's avatar
Richard Berger committed
165
166
167
168
variables, lists and for-loops to manipulate configuration options and create
an [*initial cache*](https://cmake.org/cmake/help/v3.12/manual/cmake.1.html).
Options must be set with the `CACHE` and `FORCE` flag to ensure they are
considered even during a second cmake run.
Richard Berger's avatar
Richard Berger committed
169

Richard Berger's avatar
Richard Berger committed
170
171
Such a file can then be passed to cmake via the `-C` flag. Several examples of
presets can be found in the `cmake/presets` folder.
Richard Berger's avatar
Richard Berger committed
172
173
174
175
176

```bash
# build LAMMPS with all "standard" packages which don't use libraries and enable GPU package
mkdir build
cd build
Richard Berger's avatar
Richard Berger committed
177
cmake -C ../cmake/presets/std_nolib.cmake -D PKG_GPU=on ../cmake
Richard Berger's avatar
Richard Berger committed
178
```
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194

# Reference

## Common CMAKE Configuration Options


<table>
<thead>
<tr>
  <th>Option</th>
  <th>Description</th>
  <th>Values</th>
</tr>
</thead>
<tbody>
<tr>
Richard Berger's avatar
Richard Berger committed
195
  <td><code>CMAKE_INSTALL_PREFIX</code></td>
196
197
198
199
200
  <td>Install location where LAMMPS files will be copied to. In the Unix/Linux case with Makefiles this controls what `make install` will do.</td>
  <td>
  </td>
</tr>
<tr>
Richard Berger's avatar
Richard Berger committed
201
  <td><code>CMAKE_BUILD_TYPE</code></td>
202
203
204
  <td>Controls if debugging symbols are added to the generated binaries</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
205
206
  <dt><code>Release</code> (default)</dt>
  <dt><code>Debug</code></dt>
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
  </dl>
  </td>
</tr>
</tbody>
</table>


## LAMMPS Configuration Options

<table>
<thead>
<tr>
  <th>Option</th>
  <th>Description</th>
  <th>Values</th>
</tr>
</thead>
<tbody>
<tr>
Richard Berger's avatar
Richard Berger committed
226
  <td><code>LAMMPS_SIZE_LIMIT</code></td>
227
228
229
  <td>Controls the integer sizes used by LAMMPS internally</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
230
    <dt><code>LAMMPS_SMALLBIG</code> (default)</dt>
231
    <dd>32bit , 64bit</dd>
Richard Berger's avatar
Richard Berger committed
232
    <dt><code>LAMMPS_SMALLSMALL</code></dt>
233
    <dd>32bit , 32bit</dd>
Richard Berger's avatar
Richard Berger committed
234
    <dt><code>LAMMPS_BIGBIG</code></dt>
235
236
237
238
239
    <dd>64bit , 64bit</dd>
  </dl>
  </td>
</tr>
<tr>
Richard Berger's avatar
Richard Berger committed
240
  <td><code>LAMMPS_MEMALIGN</code></td>
241
242
243
  <td>controls the alignment of blocks of memory allocated by LAMMPS</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
244
    <dt><code>64</code> (default)</dt>
245
246
247
248
  </dl>
  </td>
</tr>
<tr>
Richard Berger's avatar
Richard Berger committed
249
250
  <td><code>LAMMPS_EXCEPTIONS</code></td>
  <td>controls whether LAMMPS dies after an error or throws a C++ exception. This is particularly useful when running through the C library interface, since an error
251
252
253
  in LAMMPS then doesn't kill the parent process</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
254
255
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
256
257
258
259
  </dl>
  </td>
</tr>
<tr>
Richard Berger's avatar
Richard Berger committed
260
  <td><code>LAMMPS_MACHINE</code></td>
261
262
263
264
265
266
267
  <td>allows appending a machine suffix to the generate LAMMPS binary</td>
  <td>
  <dl>
    <dt>*none*  (default)</dt>
  </dl>
  </td>
</tr>
Richard Berger's avatar
Richard Berger committed
268
269
270
271
272
273
274
275
276
277
<tr>
  <td><code>BUILD_LIB</code></td>
  <td>control whether to build LAMMPS as a library</td>
  <td>
  <dl>
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
  </dl>
  </td>
</tr>
278
279
280
281
282
283
284
285
286
287
<tr>
  <td><code>BUILD_EXE</code></td>
  <td>control whether to build LAMMPS executable</td>
  <td>
  <dl>
    <dt><code>on</code> (default)</dt>
    <dt><code>off</code></dt>
  </dl>
  </td>
</tr>
288
<tr>
Richard Berger's avatar
Richard Berger committed
289
  <td><code>BUILD_SHARED_LIBS</code></td>
290
291
292
  <td>control whether to build LAMMPS as a shared-library</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
293
294
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
295
296
297
  </dl>
  </td>
</tr>
298
299
300
301
302
303
304
305
306
307
<tr>
  <td><code>BUILD_DOC</code></td>
  <td>control whether to build LAMMPS documentation</td>
  <td>
  <dl>
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
  </dl>
  </td>
</tr>
308
<tr>
Richard Berger's avatar
Richard Berger committed
309
310
  <td><code>LAMMPS_LONGLONG_TO_LONG</code></td>
  <td>Workaround if your system or MPI version does not recognize <code>long long</code> data types</td>
311
312
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
313
314
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
  </dl>
  </td>
</tr>
</tbody>
</table>

## Parallelization and Accelerator Packages

<table>
<thead>
<tr>
  <th>Option</th>
  <th>Description</th>
  <th>Values</th>
</tr>
</thead>
<tbody>
<tr>
333
  <td><code>BUILD_MPI</code></td>
334
335
336
337
  <td>control whether to build LAMMPS with MPI support. This will look for
  `mpicxx` in your path and use this MPI implementation.</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
338
339
    <dt><code>on</code> (default, if found)</dt>
    <dt><code>off</code></dt>
340
341
342
  </dl>
  </td>
</tr>
343
344
345
346
347
<tr>
  <td><code>BUILD_OMP</code></td>
  <td>control whether to build LAMMPS with OpenMP support.</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
348
349
    <dt><code>on</code> (default, if found)</dt>
    <dt><code>off</code></dt>
350
351
352
  </dl>
  </td>
</tr>
353
<tr>
354
  <td><code>PKG_OPT</code></td>
355
356
357
358
359
360
  <td>
  A handful of pair styles which are optimized for improved CPU performance on
  single or multiple cores. These include EAM, LJ, CHARMM, and Morse potentials.
  </td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
361
362
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
363
364
365
366
  </dl>
  </td>
</tr>
<tr>
367
  <td><code>PKG_USER-OMP</code></td>
368
369
370
371
372
373
374
  <td>
  Hundreds of pair, fix, compute, bond, angle, dihedral, improper, and kspace
  styles which are altered to enable threading on many-core CPUs via OpenMP
  directives.
  </td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
375
376
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
377
378
379
380
  </dl>
  </td>
</tr>
<tr>
381
  <td><code>PKG_USER-INTEL</code></td>
382
383
384
385
386
387
  <td>
  Dozens of pair, fix, bond, angle, dihedral, improper, and kspace styles which
  are optimized for Intel CPUs and KNLs (Knights Landing).
  </td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
388
389
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
390
391
392
393
  </dl>
  </td>
</tr>
<tr>
394
  <td><code>PKG_GPU</code></td>
395
396
397
398
399
400
401
402
403
  <td>
  Dozens of pair styles and a version of the PPPM long-range Coulombic solver
  optimized for GPUs. All such styles have a “gpu” as a suffix in their style
  name. The GPU code can be compiled with either CUDA or OpenCL, however the
  OpenCL variants are no longer actively maintained and only the CUDA versions
  are regularly tested.
  </td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
404
405
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
406
407
408
409
  </dl>
  </td>
</tr>
<tr>
410
  <td><code>PKG_KOKKOS</code></td>
411
412
413
  <td>Dozens of atom, pair, bond, angle, dihedral, improper, fix, compute styles adapted to compile using the Kokkos library which can convert them to OpenMP or CUDA code so that they run efficiently on multicore CPUs, KNLs, or GPUs.</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
414
415
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
  </dl>
  </td>
</tr>
</tbody>
</table>

## Default Packages

<table>
<thead>
<tr>
  <th>Option</th>
  <th>Description</th>
  <th>Values</th>
</tr>
</thead>
<tbody>
<tr>
434
  <td><code>PKG_ASPHERE</code></td>
435
436
437
  <td>Computes, time-integration fixes, and pair styles for aspherical particle models including ellipsoids, 2d lines, and 3d triangles.</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
438
439
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
440
441
442
443
  </dl>
  </td>
</tr>
<tr>
444
  <td><code>PKG_BODY</code></td>
445
446
447
  <td>Body-style particles with internal structure. Computes, time-integration fixes, pair styles, as well as the body styles themselves.</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
448
449
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
450
451
452
453
  </dl>
  </td>
</tr>
<tr>
454
  <td><code>PKG_CLASS2</code></td>
455
456
457
  <td>Bond, angle, dihedral, improper, and pair styles for the COMPASS CLASS2 molecular force field.</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
458
459
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
460
461
462
463
  </dl>
  </td>
</tr>
<tr>
464
  <td><code>PKG_COLLOID</code></td>
465
466
467
  <td>Coarse-grained finite-size colloidal particles. Pair styles and fix wall styles for colloidal interactions. Includes the Fast Lubrication Dynamics (FLD) method for hydrodynamic interactions, which is a simplified approximation to Stokesian dynamics.</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
468
469
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
470
471
472
473
  </dl>
  </td>
</tr>
<tr>
474
  <td><code>PKG_COMPRESS</code></td>
475
476
477
  <td>Compressed output of dump files via the zlib compression library, using dump styles with a “gz” in their style name.</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
478
479
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
480
481
482
483
  </dl>
  </td>
</tr>
<tr>
484
  <td><code>PKG_CORESHELL</code></td>
485
486
487
  <td>Compute and pair styles that implement the adiabatic core/shell model for polarizability. The pair styles augment Born, Buckingham, and Lennard-Jones styles with core/shell capabilities. The compute temp/cs command calculates the temperature of a system with core/shell particles.</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
488
489
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
490
491
492
493
  </dl>
  </td>
</tr>
<tr>
494
  <td><code>PKG_DIPOLE</code></td>
495
496
497
  <td>An atom style and several pair styles for point dipole models with short-range or long-range interactions.</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
498
499
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
500
501
502
503
  </dl>
  </td>
</tr>
<tr>
504
  <td><code>PKG_GRANULAR</code></td>
505
506
507
  <td>Pair styles and fixes for finite-size granular particles, which interact with each other and boundaries via frictional and dissipative potentials.</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
508
509
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
510
511
512
513
  </dl>
  </td>
</tr>
<tr>
514
  <td><code>PKG_KSPACE</code></td>
515
516
517
  <td>A variety of long-range Coulombic solvers, as well as pair styles which compute the corresponding short-range pairwise Coulombic interactions. These include Ewald, particle-particle particle-mesh (PPPM), and multilevel summation method (MSM) solvers.</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
518
519
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
520
521
522
523
  </dl>
  </td>
</tr>
<tr>
524
  <td><code>PKG_MANYBODY</code></td>
525
526
527
528
529
530
  <td>
  A variety of manybody and bond-order potentials. These include (AI)REBO, BOP,
  EAM, EIM, Stillinger-Weber, and Tersoff potentials.
  </td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
531
532
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
533
534
535
536
  </dl>
  </td>
</tr>
<tr>
537
  <td><code>PKG_MC</code></td>
538
539
540
541
542
543
544
545
  <td>
  Several fixes and a pair style that have Monte Carlo (MC) or MC-like
  attributes. These include fixes for creating, breaking, and swapping bonds,
  for performing atomic swaps, and performing grand-canonical MC (GCMC) in
  conjuction with dynamics.
  </td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
546
547
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
548
549
550
551
  </dl>
  </td>
</tr>
<tr>
552
  <td><code>PKG_MEAM</code></td>
553
554
555
556
557
558
559
560
561
562
  <td>
<p>A pair style for the modified embedded atom (MEAM) potential.</p>

<p><strong>Please note that the MEAM package has been superseded by the USER-MEAMC package,
which is a direct translation of the MEAM package to C++. USER-MEAMC contains
additional optimizations making it run faster than MEAM on most machines, while
providing the identical features and USER interface.</strong></p>
  </td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
563
564
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
565
566
567
568
  </dl>
  </td>
</tr>
<tr>
569
  <td><code>PKG_MISC</code></td>
570
571
572
573
574
575
  <td>
  A variety of compute, fix, pair, dump styles with specialized capabilities that
  don’t align with other packages.
  </td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
576
577
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
578
579
580
581
  </dl>
  </td>
</tr>
<tr>
582
  <td><code>PKG_MOLECULE</code></td>
Richard Berger's avatar
Richard Berger committed
583
584
585
586
587
588
  <td>
  A large number of atom, pair, bond, angle, dihedral, improper styles that are
  used to model molecular systems with fixed covalent bonds. The pair styles
  include the Dreiding (hydrogen-bonding) and CHARMM force fields, and a TIP4P
  water model.
  </td>
589
590
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
591
592
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
593
594
595
596
  </dl>
  </td>
</tr>
<tr>
597
  <td><code>PKG_PERI</code></td>
Richard Berger's avatar
Richard Berger committed
598
599
600
601
602
  <td>
  An atom style, several pair styles which implement different Peridynamics
  materials models, and several computes which calculate diagnostics.
  Peridynamics is a a particle-based meshless continuum model.
  </td>
603
604
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
605
606
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
607
608
609
610
  </dl>
  </td>
</tr>
<tr>
611
  <td><code>PKG_QEQ</code></td>
Richard Berger's avatar
Richard Berger committed
612
613
614
615
616
  <td>
  Several fixes for performing charge equilibration (QEq) via different
  algorithms. These can be used with pair styles that perform QEq as part of
  their formulation.
  </td>
617
618
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
619
620
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
621
622
623
624
  </dl>
  </td>
</tr>
<tr>
625
  <td><code>PKG_REAX</code></td>
Richard Berger's avatar
Richard Berger committed
626
627
628
629
630
631
  <td>
  A pair style which wraps a Fortran library which implements the ReaxFF
  potential, which is a universal reactive force field. See the USER-REAXC
  package for an alternate implementation in C/C++. Also a fix reax/bonds
  command for monitoring molecules as bonds are created and destroyed.
  </td>
632
633
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
634
635
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
636
637
638
639
  </dl>
  </td>
</tr>
<tr>
640
  <td><code>PKG_REPLICA</code></td>
Richard Berger's avatar
Richard Berger committed
641
642
643
644
645
646
647
648
649
  <td>
  A collection of multi-replica methods which can be used when running multiple
  LAMMPS simulations (replicas). See Section 6.5 for an overview of how to run
  multi-replica simulations in LAMMPS. Methods in the package include nudged
  elastic band (NEB), parallel replica dynamics (PRD), temperature accelerated
  dynamics (TAD), parallel tempering, and a verlet/split algorithm for
  performing long-range Coulombics on one set of processors, and the remainder
  of the force field calcalation on another set.
  </td>
650
651
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
652
653
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
654
655
656
657
  </dl>
  </td>
</tr>
<tr>
658
  <td><code>PKG_RIGID</code></td>
Richard Berger's avatar
Richard Berger committed
659
660
661
662
663
664
  <td>
  Fixes which enforce rigid constraints on collections of atoms or particles.
  This includes SHAKE and RATTLE, as well as varous rigid-body integrators for a
  few large bodies or many small bodies. Also several computes which calculate
  properties of rigid bodies.
  </td>
665
666
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
667
668
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
669
670
671
672
  </dl>
  </td>
</tr>
<tr>
673
  <td><code>PKG_SHOCK</code></td>
Richard Berger's avatar
Richard Berger committed
674
675
676
677
  <td>
  Fixes for running impact simulations where a shock-wave passes through a
  material.
  </td>
678
679
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
680
681
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
682
683
684
685
  </dl>
  </td>
</tr>
<tr>
686
  <td><code>PKG_SNAP</code></td>
Richard Berger's avatar
Richard Berger committed
687
688
689
690
691
692
  <td>
  A pair style for the spectral neighbor analysis potential (SNAP). SNAP is
  methodology for deriving a highly accurate classical potential fit to a large
  archive of quantum mechanical (DFT) data. Also several computes which analyze
  attributes of the potential.
  </td>
693
694
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
695
696
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
697
698
699
700
  </dl>
  </td>
</tr>
<tr>
701
  <td><code>PKG_SRD</code></td>
Richard Berger's avatar
Richard Berger committed
702
703
704
705
  <td>
  A pair of fixes which implement the Stochastic Rotation Dynamics (SRD) method
  for coarse-graining of a solvent, typically around large colloidal particles.
  </td>
706
707
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
708
709
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
  </dl>
  </td>
</tr>
</tbody>
</table>

## Other Packages

<table>
<thead>
<tr>
  <th>Option</th>
  <th>Description</th>
  <th>Values</th>
</tr>
</thead>
<tbody>
<tr>
728
  <td><code>PKG_KIM</code></td>
729
730
731
  <td>A <code>pair_style kim</code> command which is a wrapper on the Knowledge Base for Interatomic Models (KIM) repository of interatomic potentials, enabling any of them to be used in LAMMPS simulations.</td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
732
733
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
734
735
736
737
  </dl>
  </td>
</tr>
<tr>
738
  <td><code>PKG_PYTHON</code></td>
Richard Berger's avatar
Richard Berger committed
739
  <td>Enable support for Python scripting inside of LAMMPS.</td>
740
741
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
742
743
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
744
745
746
747
  </dl>
  </td>
</tr>
<tr>
748
  <td><code>PKG_MSCG</code></td>
Richard Berger's avatar
Richard Berger committed
749
750
751
752
  <td>
  A fix mscg command which can parameterize a Multi-Scale Coarse-Graining (MSCG)
  model using the open-source MS-CG library.
  </td>
753
754
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
755
756
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
757
758
759
760
  </dl>
  </td>
</tr>
<tr>
761
  <td><code>PKG_MPIIO</code></td>
Richard Berger's avatar
Richard Berger committed
762
763
764
  <td>
  Support for parallel output/input of dump and restart files via the MPIIO library.
  </td>
765
766
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
767
768
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
769
770
771
772
  </dl>
  </td>
</tr>
<tr>
773
  <td><code>PKG_POEMS</code></td>
Richard Berger's avatar
Richard Berger committed
774
775
776
777
778
779
  <td>
  A fix that wraps the Parallelizable Open source Efficient Multibody Software
  (POEMS) library, which is able to simulate the dynamics of articulated body
  systems. These are systems with multiple rigid bodies (collections of
  particles) whose motion is coupled by connections at hinge points.
  </td>
780
781
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
782
783
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
784
785
786
787
  </dl>
  </td>
</tr>
<tr>
788
  <td><code>PKG_LATTE</code></td>
Richard Berger's avatar
Richard Berger committed
789
790
791
792
793
  <td>
  A fix command which wraps the LATTE DFTB code, so that molecular dynamics can
  be run with LAMMPS using density-functional tight-binding quantum forces
  calculated by LATTE.
  </td>
794
795
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
796
797
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
  </dl>
  </td>
</tr>
</tbody>
</table>

## User Packages

<table>
<thead>
<tr>
  <th>Option</th>
  <th>Description</th>
  <th>Values</th>
</tr>
</thead>
<tbody>
<tr>
816
  <td><code>PKG_USER-ATC</code></td>
Richard Berger's avatar
Richard Berger committed
817
818
819
820
821
  <td>
  ATC stands for atoms-to-continuum. This package implements a fix atc command
  to either couple molecular dynamics with continuum finite element equations or
  perform on-the-fly conversion of atomic information to continuum fields.
  </td>
822
823
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
824
825
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
826
827
828
829
  </dl>
  </td>
</tr>
<tr>
830
  <td><code>PKG_USER-AWPMD</code></td>
Richard Berger's avatar
Richard Berger committed
831
832
833
834
835
  <td>
  AWPMD stands for Antisymmetrized Wave Packet Molecular Dynamics. This package
  implements an atom, pair, and fix style which allows electrons to be treated
  as explicit particles in a classical molecular dynamics model.
  </td>
836
837
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
838
839
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
840
841
842
843
  </dl>
  </td>
</tr>
<tr>
844
  <td><code>PKG_USER-CGDNA</code></td>
845
  <td>
Richard Berger's avatar
Richard Berger committed
846
847
848
849
  Several pair styles, a bond style, and integration fixes for coarse-grained
  models of single- and double-stranded DNA based on the oxDNA model of Doye,
  Louis and Ouldridge at the University of Oxford. This includes Langevin-type
  rigid-body integrators with improved stability.
850
851
852
  </td>
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
853
854
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
855
856
857
858
  </dl>
  </td>
</tr>
<tr>
859
  <td><code>PKG_USER-CGSDK</code></td>
Richard Berger's avatar
Richard Berger committed
860
861
862
863
864
  <td>
  Several pair styles and an angle style which implement the coarse-grained SDK
  model of Shinoda, DeVane, and Klein which enables simulation of ionic liquids,
  electrolytes, lipids and charged amino acids.
  </td>
865
866
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
867
868
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
869
870
871
872
  </dl>
  </td>
</tr>
<tr>
873
  <td><code>PKG_USER-COLVARS</code></td>
Richard Berger's avatar
Richard Berger committed
874
875
876
877
878
879
880
  <td>
  COLVARS stands for collective variables, which can be used to implement
  various enhanced sampling methods, including Adaptive Biasing Force,
  Metadynamics, Steered MD, Umbrella Sampling and Restraints. A fix colvars
  command is implemented which wraps a COLVARS library, which implements these
  methods. simulations.
  </td>
881
882
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
883
884
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
885
886
887
888
  </dl>
  </td>
</tr>
<tr>
889
  <td><code>PKG_USER-DIFFRACTION</code></td>
Richard Berger's avatar
Richard Berger committed
890
891
892
893
  <td>
  Two computes and a fix for calculating x-ray and electron diffraction
  intensities based on kinematic diffraction theory.
  </td>
894
895
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
896
897
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
898
899
900
901
  </dl>
  </td>
</tr>
<tr>
902
  <td><code>PKG_USER-DPD</code></td>
Richard Berger's avatar
Richard Berger committed
903
904
905
906
907
908
909
910
911
912
  <td>
  DPD stands for dissipative particle dynamics. This package implements
  coarse-grained DPD-based models for energetic, reactive molecular crystalline
  materials. It includes many pair styles specific to these systems, including
  for reactive DPD, where each particle has internal state for multiple species
  and a coupled set of chemical reaction ODEs are integrated each timestep.
  Highly accurate time integrators for isothermal, isoenergetic, isobaric and
  isenthalpic conditions are included. These enable long timesteps via the
  Shardlow splitting algorithm.
  </td>
913
914
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
915
916
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
917
918
919
920
  </dl>
  </td>
</tr>
<tr>
921
  <td><code>PKG_USER-DRUDE</code></td>
Richard Berger's avatar
Richard Berger committed
922
923
924
925
  <td>
  Fixes, pair styles, and a compute to simulate thermalized Drude oscillators as
  a model of polarization.
  </td>
926
927
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
928
929
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
930
931
932
933
  </dl>
  </td>
</tr>
<tr>
934
  <td><code>PKG_USER-EFF</code></td>
Richard Berger's avatar
Richard Berger committed
935
936
937
938
939
940
941
  <td>
  EFF stands for electron force field which allows a classical MD code to model
  electrons as particles of variable radius. This package contains atom, pair,
  fix and compute styles which implement the eFF as described in A.
  Jaramillo-Botero, J. Su, Q. An, and W.A. Goddard III, JCC, 2010. The eFF
  potential was first introduced by Su and Goddard, in 2007.
  </td>
942
943
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
944
945
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
946
947
948
949
  </dl>
  </td>
</tr>
<tr>
950
  <td><code>PKG_USER-FEP</code></td>
Richard Berger's avatar
Richard Berger committed
951
952
953
954
955
  <td>
  FEP stands for free energy perturbation. This package provides methods for
  performing FEP simulations by using a fix adapt/fep command with soft-core
  pair potentials, which have a “soft” in their style name.
  </td>
956
957
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
958
959
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
960
961
962
963
  </dl>
  </td>
</tr>
<tr>
964
  <td><code>PKG_USER-H5MD</code></td>
Richard Berger's avatar
Richard Berger committed
965
966
967
968
969
970
  <td>
  H5MD stands for HDF5 for MD. HDF5 is a portable, binary, self-describing file
  format, used by many scientific simulations. H5MD is a format for molecular
  simulations, built on top of HDF5. This package implements a dump h5md command
  to output LAMMPS snapshots in this format.
  </td>
971
972
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
973
974
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
975
976
977
978
  </dl>
  </td>
</tr>
<tr>
979
  <td><code>PKG_USER-LB</code></td>
Richard Berger's avatar
Richard Berger committed
980
981
982
983
  <td>
  Fixes which implement a background Lattice-Boltzmann (LB) fluid, which can be
  used to model MD particles influenced by hydrodynamic forces.
  </td>
984
985
  <td>
  <dl>
Richard Berger's avatar
Richard Berger committed
986
987
    <dt><code>off</code> (default)</dt>
    <dt><code>on</code></dt>
988
989
990
991
  </dl>
  </td>
</tr>
<tr>
992
  <td><code>PKG_USER-MANIFOLD</code></td>
Richard Berger's avatar
Richard Berger committed
993
994
995
996
997
998
999
  <td>
  Several fixes and a “manifold” class which enable simulations of particles
  constrained to a manifold (a 2D surface within the 3D simulation box). This is
  done by applying the RATTLE constraint algorithm to formulate single-particle
  constraint functions g(xi,yi,zi) = 0 and their derivative (i.e. the normal of
  the manifold) n = grad(g).
  </td>
1000
  <td>
For faster browsing, not all history is shown. View entire blame