ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'master' into restrain_lbound

Browse Source
This commit is contained in:
Axel Kohlmeyer
2020-04-15 14:24:47 -04:00
parent 0796a7032e 80311891f1
commit 01f97f1936
2974 changed files with 166511 additions and 137505 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/src/.gitignore vendored
View File

@ -1,3 +1 @@
/Eqs
/JPG
/false_positives.txt

14
doc/src/Build.rst
View File

@ -1,12 +1,14 @@
Build LAMMPS
************
LAMMPS can be built as an executable or library from source code via
either traditional makefiles (which may require manual editing)
for use with GNU make or gmake, or a build environment generated by CMake
(Unix Makefiles, Xcode, Visual Studio, KDevelop or more). As an
alternative you can download a package with pre-built executables
as described on the :doc:`Install <Install>` doc page.
LAMMPS is built as a library and an executable from source code using
either traditional makefiles for use with GNU make (which may require
manual editing), or using a build environment generated by CMake (Unix
Makefiles, Ninja, Xcode, Visual Studio, KDevelop, CodeBlocks and more).
As an alternative you can download a package with pre-built executables
or automated build trees as described on the :doc:`Install <Install>`
doc page.
.. toctree::
:maxdepth: 1

323
doc/src/Build_basics.rst
View File

@ -6,7 +6,8 @@ CMake and make:
* :ref:`Serial vs parallel build <serial>`
* :ref:`Choice of compiler and compile/link options <compile>`
* :ref:`Build LAMMPS as an executable or a library <exe>`
* :ref:`Build the LAMMPS executable and library <exe>`
* :ref:`Including and removing debug support <debug>`
* :ref:`Build the LAMMPS documentation <doc>`
* :ref:`Install LAMMPS after a build <install>`
@ -15,7 +16,7 @@ CMake and make:
.. _serial:
Serial vs parallel build
-------------------------------------
------------------------
LAMMPS is written to use the ubiquitous `MPI (Message Passing Interface)
<https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ library API
@ -28,8 +29,8 @@ MPI STUBS library.
Independent of the distributed memory MPI parallelization, parts of
LAMMPS are also written with support for shared memory parallelization
using the OpenMP threading standard. A more detailed discussion of that
is below.
using the `OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_ threading
standard. A more detailed discussion of that is below.
**CMake build**\ :
@ -41,7 +42,7 @@ is below.
# no default value
The executable created by CMake (after running make) is named ``lmp`` unless
the LAMMPS_MACHINE option is set. When setting ``LAMMPS_MACHINE=name``
the ``LAMMPS_MACHINE`` option is set. When setting ``LAMMPS_MACHINE=name``
the executable will be called ``lmp_name``. Using ``BUILD_MPI=no`` will
enforce building a serial executable using the MPI STUBS library.
@ -55,18 +56,20 @@ The build with traditional makefiles has to be done inside the source folder ``s
make serial # serial build, produces lmp_serial using Makefile/serial
make mybox # uses Makefile.mybox to produce lmp_mybox
Any "make machine" command will look up the make settings from a file
Makefile.machine, create a folder Obj_machine with all objects and
generated files and an executable called ``lmp_machine``\ . The standard
parallel build with ``make mpi`` assumes a standard MPI installation with
MPI compiler wrappers where all necessary compiler and linker flags to
get access and link with the suitable MPI headers and libraries are set
by the wrapper programs. For other cases or the serial build, you have
to adjust the make file variables ``MPI_INC``, ``MPI_PATH``, ``MPI_LIB``
as well as ``CC`` and ``LINK``\ . To enable OpenMP threading usually
a compiler specific flag needs to be added to the compile and link
commands. For the GNU compilers, this is ``-fopenmp``\ , which can be
added to the ``CC`` and ``LINK`` makefile variables.
Any ``make machine`` command will look up the make settings from a file
``Makefile.machine`` in the folder ``src/MAKE`` or one of its
sub-directories ``MINE``, ``MACHINES``, or ``OPTIONS``, create a folder
``Obj_machine`` with all objects and generated files and an executable
called ``lmp_machine``\ . The standard parallel build with ``make mpi``
assumes a standard MPI installation with MPI compiler wrappers where all
necessary compiler and linker flags to get access and link with the
suitable MPI headers and libraries are set by the wrapper programs. For
other cases or the serial build, you have to adjust the make file
variables ``MPI_INC``, ``MPI_PATH``, ``MPI_LIB`` as well as ``CC`` and
``LINK``\ . To enable OpenMP threading usually a compiler specific flag
needs to be added to the compile and link commands. For the GNU
compilers, this is ``-fopenmp``\ , which can be added to the ``CC`` and
``LINK`` makefile variables.
For the serial build the following make variables are set (see src/MAKE/Makefile.serial):
@ -80,18 +83,19 @@ For the serial build the following make variables are set (see src/MAKE/Makefile
You also need to build the STUBS library for your platform before making
LAMMPS itself. A ``make serial`` build does this for you automatically,
otherwise, type ``make mpi-stubs`` from the src directory, or ``make`` from
the src/STUBS dir. If the build fails, you will need to edit the
STUBS/Makefile for your platform. The stubs library does not provide
MPI/IO functions required by some LAMMPS packages, e.g. MPIIO or USER-LB,
and thus is not compatible with those packages.
otherwise, type ``make mpi-stubs`` from the src directory, or ``make``
from the ``src/STUBS`` dir. If the build fails, you may need to edit
the ``STUBS/Makefile`` for your platform. The stubs library does not
provide MPI/IO functions required by some LAMMPS packages,
e.g. ``MPIIO`` or ``USER-LB``, and thus is not compatible with those
packages.
.. note::
The file ``src/STUBS/mpi.c`` provides a CPU timer function called
MPI_Wtime() that calls gettimeofday() . If your operating system
does not support gettimeofday() , you will need to insert code to
call another timer. Note that the ANSI-standard function clock()
``MPI_Wtime()`` that calls ``gettimeofday()``. If your operating system
does not support ``gettimeofday()``, you will need to insert code to
call another timer. Note that the ANSI-standard function ``clock()``
rolls over after an hour or so, and is therefore insufficient for
timing long LAMMPS simulations.
@ -111,20 +115,22 @@ self-installed MPICH or OpenMPI, so you should study the provided
documentation to find out how to build and link with it.
The majority of OpenMP (threading) support in LAMMPS is provided by the
USER-OMP package; see the :doc:`Speed omp <Speed_omp>` doc page for
details. The USER-INTEL package also includes OpenMP threading (it is
compatible with USER-OMP) and adds vectorization support when compiled
with compatible compilers, in particular the Intel compilers on top of
OpenMP. Also, the KOKKOS package can be compiled to include OpenMP
threading.
``USER-OMP`` package; see the :doc:`Speed omp <Speed_omp>` doc page for
details. The ``USER-INTEL`` package also includes OpenMP threading (it
is compatible with ``USER-OMP`` and will usually fall back on styles
from that package, if a ``USER-INTEL`` does not exist) and adds
vectorization support when compiled with compatible compilers, in
particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS``
package can be compiled to include OpenMP threading.
In addition, there are a few commands in LAMMPS that have native OpenMP
support included as well. These are commands in the MPIIO, SNAP,
USER-DIFFRACTION, and USER-DPD packages. In addition some packages
support OpenMP threading indirectly through the libraries they interface
to: e.g. LATTE and USER-COLVARS. See the :doc:`Packages details
<Packages_details>` doc page for more info on these packages and the doc
pages for their respective commands for OpenMP threading info.
support included as well. These are commands in the ``MPIIO``,
``SNAP``, ``USER-DIFFRACTION``, and ``USER-DPD`` packages. In addition
some packages support OpenMP threading indirectly through the libraries
they interface to: e.g. ``LATTE``, ``KSPACE``, and ``USER-COLVARS``.
See the :doc:`Packages details <Packages_details>` doc page for more
info on these packages and the doc pages for their respective commands
for OpenMP threading info.
For CMake, if you use ``BUILD_OMP=yes``, you can use these packages
and turn on their native OpenMP support and turn on their native OpenMP
@ -142,14 +148,15 @@ please refer to its documentation.
**OpenMP Compiler compatibility info**\ :
Some compilers do not fully support the ``default(none)`` directive
and others (e.g. GCC version 9 and beyond) may implement OpenMP 4.0
semantics, which are incompatible with the OpenMP 3.1 semantics used
in LAMMPS (for maximal compatibility with compiler versions in use).
In those case, all ``default(none)`` directives (which aid in detecting
incorrect and unwanted sharing) can be replaced with ``default(shared)``
while dropping all ``shared()`` directives. The script
'src/USER-OMP/hack_openmp_for_pgi_gcc9.sh' can be used to automate
this conversion.
and others (e.g. GCC version 9 and beyond, Clang version 10 and later)
may implement strict OpenMP 4.0 and later semantics, which are incompatible
with the OpenMP 3.1 semantics used in LAMMPS for maximal compatibility
with compiler versions in use. If compilation with OpenMP enabled fails
because of your compiler requiring strict OpenMP 4.0 semantic, you can
change the behavior by adding ``-D LAMMPS_OMP_COMPAT=4`` to the ``LMP_INC``
variable in your makefile, or add it to the command line while configuring
with CMake. CMake will detect the suitable setting for the GNU, Clang,
and Intel compilers.
----------
@ -158,15 +165,18 @@ this conversion.
Choice of compiler and compile/link options
---------------------------------------------------------
The choice of compiler and compiler flags can be important for
The choice of compiler and compiler flags can be important for maximum
performance. Vendor provided compilers for a specific hardware can
produce faster code than open-source compilers like the GNU compilers.
On x86 hardware most popular compilers are quite similar in performance
of C/C++ code at high optimization levels. When using the USER-INTEL
package, there is a distinct advantage in using the `Intel C++ compiler
<intel_>`_ due to much improved vectorization through SSE and AVX
instructions on compatible hardware as the source code includes changes
and compiler directives to enable high degrees of vectorization.
On the most common x86 hardware most popular C++ compilers are quite
similar in performance of C/C++ code at high optimization levels. When
using the ``USER-INTEL`` package, there is a distinct advantage in using
the `Intel C++ compiler <intel_>`_ due to much improved vectorization
through SSE and AVX instructions on compatible hardware as the source
code includes changes and Intel compiler specific directives to enable
high degrees of vectorization. This may change over time as equivalent
vectorization directives are included into OpenMP standard revisions and
other compilers adopt them.
.. _intel: https://software.intel.com/en-us/intel-compilers
@ -177,17 +187,20 @@ LAMMPS.
**CMake build**\ :
By default CMake will use a compiler it finds and it will add
optimization flags appropriate to that compiler and any
:doc:`accelerator packages <Speed_packages>` you have included in the
build.
By default CMake will use a compiler it finds according to internal
preferences and it will add optimization flags appropriate to that
compiler and any :doc:`accelerator packages <Speed_packages>` you have
included in the build.
You can tell CMake to look for a specific compiler with these variable
settings. Likewise you can specify the corresponding ``CMAKE_*_FLAGS``
variables if you want to experiment with alternate optimization flags.
You should specify all 3 compilers, so that the small number of LAMMPS
source files written in C or Fortran are built with a compiler consistent
with the one used for all the C++ files:
You can tell CMake to look for a specific compiler with setting CMake
variable during configuration. For a few common choices, there are also
presets in the ``cmake/presets`` folder. For convenience, there is a
``CMAKE_TUNE_FLAGS`` variable that can be set to apply global compiler
options. More on that below, but you can also specify the corresponding
``CMAKE_*_FLAGS`` variables individually if you want to experiment with
alternate optimization flags. You should specify all 3 compilers, so
that the (few) LAMMPS source files written in C or Fortran are built
with a compiler consistent with the one used for the C++ files:
.. code-block:: bash
@ -210,16 +223,17 @@ A few example command lines are:
# Building with LLVM/Clang Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang
For compiling with the Clang/LLVM compilers a special CMake preset is
included that can be loaded with `-C ../cmake/presets/clang.cmake`.
For compiling with the Clang/LLVM compilers a CMake preset is provided that
can be loaded with `-C ../cmake/presets/clang.cmake`. Similarly,
`-C ../cmake/presets/intel.cmake` should switch the
In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add compiler
flags to tune for optimal performance on given hosts. By default these are
initialized to some compiler specific flags, where known, to optimize the
LAMMPS executable with optimizations and instructions available on the host
where LAMMPS is compiled. For example, for Intel compilers this would be
``-xHost`` and for GNU compilers this would be ``-march=native``. To turn
these flags off, set ``-D CMAKE_TUNE_FLAGS=``.
In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
compiler flags to tune for optimal performance on given hosts. By
default these are initialized to some compiler specific flags, to
optimize the LAMMPS executable with optimizations and instructions
available on the host where LAMMPS is compiled. For example, for Intel
compilers this would be ``-xHost`` and for GNU compilers this would be
``-march=native``. To turn these flags off, do ``-D CMAKE_TUNE_FLAGS=``.
.. note::
@ -235,11 +249,11 @@ these flags off, set ``-D CMAKE_TUNE_FLAGS=``.
The "compiler/linker settings" section of a Makefile.machine lists
compiler and linker settings for your C++ compiler, including
optimization flags. For a parallel build it is recommended to use
mpicxx or mpiCC, since these compiler wrappers will include a variety of
settings appropriate for your MPI installation and thus avoiding the
guesswork of finding the right flags.
``mpicxx`` or ``mpiCC``, since these compiler wrappers will include a
variety of settings appropriate for your MPI installation and thus
avoiding the guesswork of finding the right flags.
Parallel build (see src/MAKE/Makefile.mpi):
Parallel build (see ``src/MAKE/Makefile.mpi``):
.. code-block:: bash
@ -248,7 +262,7 @@ Parallel build (see src/MAKE/Makefile.mpi):
LINK = mpicxx
LINKFLAGS = -g -O
Serial build (see src/MAKE/Makefile.serial):
Serial build with GNU gcc (see ``src/MAKE/Makefile.serial``):
.. code-block:: make
@ -257,17 +271,35 @@ Serial build (see src/MAKE/Makefile.serial):
LINK = g++
LINKFLAGS = -g -O
.. note::
If you build LAMMPS with any :doc:`accelerator packages <Speed_packages>`
included, there may be specific optimization flags that are either
required or recommended to enable required features and to achieve
optimal performance. You need to include these in the CCFLAGS and
LINKFLAGS settings above. For details, see the individual package
doc pages listed on the :doc:`Speed packages <Speed_packages>` doc
page. Or examine these files in the src/MAKE/OPTIONS directory.
They correspond to each of the 5 accelerator packages and their
hardware variants:
If compilation stops with a message like the following:
.. code-block::
g++ -g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I../STUBS -c ../main.cpp
In file included from ../pointers.h:24:0,
from ../input.h:17,
from ../main.cpp:16:
../lmptype.h:34:2: error: #error LAMMPS requires a C++11 (or later) compliant compiler. Enable C++11 compatibility or upgrade the compiler.
then you have either an unsupported (old) compiler or you have to
turn on C++11 mode. The latter applies to GCC 4.8.x shipped with
RHEL 7.x and CentOS 7.x. For those compilers, you need to add the
``-std=c++11`` flag. Otherwise, you would have to install a newer
compiler that supports C++11; either as a binary package or through
compiling from source.
If you build LAMMPS with any :doc:`accelerator packages
<Speed_packages>` included, there may be specific optimization flags
that are either required or recommended to enable required features and
to achieve optimal performance. You need to include these in the
CCFLAGS and LINKFLAGS settings above. For details, see the individual
package doc pages listed on the :doc:`Speed packages <Speed_packages>`
doc page. Or examine these files in the src/MAKE/OPTIONS directory.
They correspond to each of the 5 accelerator packages and their hardware
variants:
.. code-block:: bash
@ -284,69 +316,74 @@ Serial build (see src/MAKE/Makefile.serial):
.. _exe:
Build LAMMPS as an executable or a library
----------------------------------------------------
Build the LAMMPS executable and library
---------------------------------------
LAMMPS can be built as either an executable or as a static or shared
library. The LAMMPS library can be called from another application or
a scripting language. See the :doc:`Howto couple <Howto_couple>` doc
LAMMPS is always built as a library of C++ classes plus an executable.
The executable is a simple ``main()`` function that sets up MPI and then
creates a LAMMPS class instance from the LAMMPS library, which
will then process commands provided via a file or from the console
input. The LAMMPS library can also be called from another application
or a scripting language. See the :doc:`Howto couple <Howto_couple>` doc
page for more info on coupling LAMMPS to other codes. See the
:doc:`Python <Python_head>` doc page for more info on wrapping and
running LAMMPS from Python via its library interface.
**CMake build**\ :
For CMake builds, you can select through setting CMake variables which
files the compilation produces during the configuration step. If none
are set, defaults are applied.
For CMake builds, you can select through setting CMake variables between
building a shared or a static LAMMPS library and what kind of suffix is
added to them (in case you want to concurrently install multiple variants
of binaries with different settings). If none are set, defaults are applied.
.. code-block:: bash
-D BUILD_EXE=value # yes (default) or no
-D BUILD_LIB=value # yes or no (default)
-D BUILD_SHARED_LIBS=value # yes or no (default)
-D LAMMPS_LIB_SUFFIX=name # name = mpi, serial, mybox, titan, laptop, etc
-D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc
# no default value
Setting ``BUILD_EXE=no`` will not produce an executable. Setting
``BUILD_LIB=yes`` will produce a static library named ``liblammps.a``\ .
Setting both ``BUILD_LIB=yes`` and ``BUILD_SHARED_LIBS=yes`` will produce a
shared library named ``liblammps.so`` instead. If ``LAMMPS_LIB_SUFFIX=name``
is set in addition, the name of the generated libraries will be changed to
either ``liblammps_name.a`` or ``liblammps_name.so``\ , respectively.
The compilation will always produce a LAMMPS library and an executable
linked to it. By default this will be a static library named
``liblammps.a`` and an executable named ``lmp`` Setting
``BUILD_SHARED_LIBS=yes`` will instead produce a shared library called
``liblammps.so`` (or ``liblammps.dylib`` or ``liblammps.dll`` depending
on the platform) If ``LAMMPS_MACHINE=name`` is set in addition, the name
of the generated libraries will be changed to either
``liblammps_name.a`` or ``liblammps_name.so``\ , respectively and the
executable will be called ``lmp_name``.
**Traditional make**\ :
With the traditional makefile based build process, the choice of
the generated executable or library depends on the "mode" setting.
Several options are available and ``mode=exe`` is the default.
Several options are available and ``mode=static`` is the default.
.. code-block:: bash
make machine # build LAMMPS executable lmp_machine
make mode=exe machine # same as "make machine"
make mode=lib machine # build LAMMPS static lib liblammps_machine.a
make mode=shlib machine # build LAMMPS shared lib liblammps_machine.so
make mode=shexe machine # same as "mode=exe" but uses objects from "mode=shlib"
make mode=static machine # same as "make machine"
make mode=shared machine # build LAMMPS shared lib liblammps_machine.so instead
The two "exe" builds will generate and executable ``lmp_machine``\ ,
while the two library builds will create a file ``liblammps_machine.a``
or ``liblammps_machine.so``\ . They will also create generic soft links,
named ``liblammps.a`` and ``liblammps.so``\ , which point to the specific
The "static" build will generate a static library called
``liblammps_machine.a`` and an executable named ``lmp_machine``\ , while
the "shared" build will generate a shared library
``liblammps_machine.so`` instead and ``lmp_machine`` will be linked to
it. The build step will also create generic soft links, named
``liblammps.a`` and ``liblammps.so``\ , which point to the specific
``liblammps_machine.a/so`` files.
**CMake and make info**\ :
Note that for a shared library to be usable by a calling program, all
the auxiliary libraries it depends on must also exist as shared
libraries. This will be the case for libraries included with LAMMPS,
such as the dummy MPI library in src/STUBS or any package libraries in
the lib/packages directory, since they are always built in a shared
library compatible way using the ``-fPIC`` switch. However, if a library
like MPI or FFTW does not exist as a shared library, the shared library
build may generate an error. This means you will need to install a
shared library version of the auxiliary library. The build instructions
for the library should tell you how to do this.
Note that for creating a shared library, all the libraries it depends on
must be compiled to be compatible with shared libraries. This should be
the case for libraries included with LAMMPS, such as the dummy MPI
library in ``src/STUBS`` or any package libraries in the ``lib``
directory, since they are always built in a shared library compatible
way using the ``-fPIC`` compiler switch. However, if an auxiliary
library (like MPI or FFTW) does not exist as a compatible format, the
shared library linking step may generate an error. This means you will
need to install a compatible version of the auxiliary library. The
build instructions for that library should tell you how to do this.
As an example, here is how to build and install the `MPICH library
<mpich_>`_, a popular open-source version of MPI, as a shared library
@ -360,10 +397,12 @@ in the default /usr/local/lib location:
make
make install
You may need to use ``sudo make install`` in place of the last line if you
do not have write privileges for ``/usr/local/lib``. The end result should
be the file ``/usr/local/lib/libmpich.so``. On many Linux installations the
folder ``${HOME}/.local`` is an alternative to using ``/usr/local`` and does
You may need to use ``sudo make install`` in place of the last line if
you do not have write privileges for ``/usr/local/lib`` or use the
``--prefix`` configuration option to select an installation folder,
where you do have write access. The end result should be the file
``/usr/local/lib/libmpich.so``. On many Linux installations the folder
``${HOME}/.local`` is an alternative to using ``/usr/local`` and does
not require superuser or sudo access. In that case the configuration
step becomes:
@ -371,12 +410,41 @@ step becomes:
./configure --enable-shared --prefix=${HOME}/.local
Avoiding using "sudo" for custom software installation (i.e. from source
Avoiding to use "sudo" for custom software installation (i.e. from source
and not through a package manager tool provided by the OS) is generally
recommended to ensure the integrity of the system software installation.
----------
.. _debug:
Excluding or removing debug support
-----------------------------------
By default the compilation settings will include the *-g* flag which
instructs the compiler to include debug information (e.g. which line of
source code a particular instruction correspond to). This can be
extremely useful in case LAMMPS crashes and can help to provide crucial
information in :doc:`tracking down the origin of a crash <Errors_debug>`
and help the LAMMPS developers fix bugs in the source code. However,
this increases the storage requirements for object files, libraries, and
the executable 3-5 fold.
If this is a concern, you can change the compilation settings or remove
the debug information from the LAMMPS executable:
- **Traditional make**: edit your ``Makefile.<machine>`` to remove the
*-g* flag from the ``CCFLAGS`` and ``LINKFLAGS`` definitions
- **CMake**: use ``-D CMAKE_BUILD_TYPE=Release`` or explicitly reset
the applicable compiler flags (best done using the text mode or
graphical user interface).
- **Remove debug info**: If you are only concerned about the executable
being too large, you can use the ``strip`` tool (e.g. ``strip
lmp_serial``) to remove the debug information from the executable file.
Do not strip libraries or object files, as that will render them unusable.
----------
.. _doc:
Build the LAMMPS documentation
@ -427,7 +495,8 @@ It is also possible to create the HTML version of the manual within
the :doc:`CMake build directory <Build_cmake>`. The reason for this
option is to include the installation of the HTML manual pages into
the "install" step when installing LAMMPS after the CMake build via
``make install``.
``make install``. The documentation build is included in the default
build target, but can also be requested independently with ``make doc``.
.. code-block:: bash

316
doc/src/Build_cmake.rst
View File

@ -1,205 +1,158 @@
Build LAMMPS with CMake
=======================
This page is a short summary of how to use CMake to build LAMMPS.
Details on CMake variables that enable specific LAMMPS build options
are given on the pages linked to from the :doc:`Build <Build>` doc page.
This page describes how to use `CMake <https://cmake.org>`_ in general
to build LAMMPS. Details for specific compile time settings and options
to enable and configure add-on packages are discussed with those
packages. Links to those pages on the :doc:`Build overview <Build>`
page.
Richard Berger (Temple U) has also written a `more comprehensive guide <https://github.com/lammps/lammps/blob/master/cmake/README.md>`_
for how to use CMake to build LAMMPS. If you are new to CMake it is a
good place to start.
The following text assumes some familiarity with CMake and focuses on
using the command line tool ``cmake`` and what settings are supported
for building LAMMPS. A more detailed tutorial on how to use ``cmake``
itself, the text mode or graphical user interface, change the generated
output files for different build tools and development environments is
on a :doc:`separate page <Howto_cmake>`.
----------
.. note::
LAMMPS currently requires that CMake version 3.10 or later is available;
version 3.12 or later is preferred.
.. warning::
You must not mix the :doc:`traditional make based <Build_make>`
LAMMPS build procedure with using CMake. Thus no packages may be
installed or a build been previously attempted in the LAMMPS source
directory by using ``make <machine>``. CMake will detect if this is
the case and generate an error. To remove conflicting files from the
``src`` you can use the command ``make no-all purge`` which will
un-install all packages and delete all auto-generated files.
Advantages of using CMake
^^^^^^^^^^^^^^^^^^^^^^^^^
CMake is an alternative to compiling LAMMPS in the traditional way
through :doc:`(manually customized) makefiles <Build_make>` and a recent
addition to LAMMPS thanks to the efforts of Christoph Junghans (LANL)
and Richard Berger (Temple U). Using CMake has multiple advantages that
are specifically helpful for people with limited experience in compiling
software or for people that want to modify or extend LAMMPS.
- CMake can detect available hardware, tools, features, and libraries
and adapt the LAMMPS default build configuration accordingly.
- CMake can generate files for different build tools and integrated
development environments (IDE).
- CMake supports customization of settings with a text mode or graphical
user interface. No knowledge of file formats or and complex command
line syntax required.
- All enabled components are compiled in a single build operation.
- Automated dependency tracking for all files and configuration options.
- Support for true out-of-source compilation. Multiple configurations
and settings with different choices of LAMMPS packages, settings, or
compilers can be configured and built concurrently from the same
source tree.
- Simplified packaging of LAMMPS for Linux distributions, environment
modules, or automated build tools like `Homebrew <https://brew.sh/>`_.
- Integration of automated regression testing (the LAMMPS side for that
is still under development).
.. _cmake_build:
Getting started
^^^^^^^^^^^^^^^
Building LAMMPS with CMake is a two-step process. First you use CMake
to create a build environment in a new directory. On Linux systems,
this will be by default based on Unix-style makefiles for use with make.
Then you use the *make* command to build LAMMPS, which uses the created
Makefile(s). Example:
to generate a build environment in a new directory. For that purpose
you can use either the command-line utility ``cmake`` (or ``cmake3``),
the text-mode UI utility ``ccmake`` (or ``ccmake3``) or the graphical
utility ``cmake-gui``, or use them interchangeably. The second step is
then the compilation and linking of all objects, libraries, and
executables. Here is a minimal example using the command line version of
CMake to build LAMMPS with no add-on packages enabled and no
customization:
.. code-block:: bash
cd lammps # change to the LAMMPS distribution directory
mkdir build; cd build # create a new directory (folder) for build
cmake [options ...] ../cmake # configuration with (command-line) cmake
cmake --build . # compilation (or type "make")
cd lammps # change to the LAMMPS distribution directory
mkdir build; cd build # create and use a build directory
cmake ../cmake # configuration reading CMake scripts from ../cmake
cmake --build . # compilation (or type "make")
The ``cmake`` command will detect available features, enable selected
packages and options, and will generate the build environment. By default
this build environment will be created for "Unix Makefiles" on most
platforms and particularly on Linux. However, alternate build tools
(e.g. Ninja) and project files for Integrated Development Environments
(IDEs) like Eclipse, CodeBlocks, or Kate can be generated, too. This is
selected via the ``-G`` command line flag. Further details about features
and settings for CMake are in the `CMake online documentation <cmake_doc_>`_
This will create and change into a folder called ``build``, then run the
configuration step to generate build files for the default build command
and then launch that build command to compile LAMMPS. During the
configuration step CMake will try to detect whether support for MPI,
OpenMP, FFTW, gzip, JPEG, PNG, and ffmpeg are available and enable the
corresponding configuration settings. The progress of this
configuration can be followed on the screen and a summary of selected
options and settings will be printed at the end. The ``cmake --build
.`` command will launch the compilation, which, if successful, will
ultimately produce a library ``liblammps.a`` and the LAMMPS executable
``lmp`` inside the ``build`` folder.
.. _cmake_doc: https://cmake.org/documentation/
Compilation can take a long time, since LAMMPS is a large project with
many features. If your machine has multiple CPU cores (most do these
days), you can speed this up by compiling sources in parallel with
``make -j N`` (with N being the maximum number of concurrently executed
tasks). Also installation of the `ccache <https://ccache.dev/>`_ (=
Compiler Cache) software may speed up repeated compilation even more,
e.g. during code development.
For the rest of the documentation
we will assume that the build environment is generated for "Unix Makefiles"
and thus the ``make`` command will be used to compile and link LAMMPS as
indicated above, producing (by default) an executable called ``lmp`` and
a library called ``liblammps.a`` in the ``build`` folder.
If your machine has multiple CPU cores (most do these days), you can
compile sources in parallel with a command like ``make -j N`` (with N
being the maximum number of concurrently executed tasks). Also
installation of the ``ccache`` (= Compiler Cache) software may speed
up repeated compilation, e.g. during code development, significantly.
After the initial build, whenever you edit LAMMPS source files, enable
or disable packages, change compiler flags or build options, you must
re-compile and relink the LAMMPS executable with ``cmake --build .`` (or
``make``). If the compilation fails for some reason, try running
``cmake .`` and then compile again. The included dependency tracking
should make certain that only the necessary subset of files are
re-compiled. You can also delete compiled objects, libraries and
executables with ``cmake --build . clean`` (or ``make clean``).
After compilation, you may optionally install the LAMMPS executable into
your system with:
.. code-block:: bash
make install # optional, copy LAMMPS executable & library elsewhere
make install # optional, copy compiled files into installation location
This will install the lammps executable and library (if requested), some
tools (if configured) and additional files like library API headers,
manpages, potential and force field files. The location of the installation
tree is set by the CMake variable "CMAKE_INSTALL_PREFIX" which defaults
to ${HOME}/.local
This will install the LAMMPS executable and library, some tools (if
configured) and additional files like LAMMPS API headers, manpages,
potential and force field files. The location of the installation tree
defaults to ``${HOME}/.local``.
----------
.. _cmake_options:
.. _cmake_build:
Configuration and build options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are 3 variants of the CMake command itself: a command-line version
(``cmake`` or ``cmake3``), a text mode UI version (``ccmake`` or ``ccmake3``),
and a graphical GUI version (``cmake-gui``). You can use any of them
interchangeably to configure and create the LAMMPS build environment.
On Linux all the versions produce a Makefile as their output by default.
See more details on each below.
The CMake commands have one mandatory argument: a folder containing a
file called ``CMakeLists.txt`` (for LAMMPS it is located in the
``cmake`` folder) or a build folder containing a file called
``CMakeCache.txt``, which is generated at the end of the CMake
configuration step. The cache file contains all current CMake settings.
You can specify a variety of options with any of the 3 versions, which
affect how the build is performed and what is included in the LAMMPS
executable. Links to pages explaining all the options are listed on
the :doc:`Build <Build>` doc page.
To modify settings, enable or disable features, you need to set *variables*
with either the *-D* command line flag (``-D VARIABLE1_NAME=value``) or
change them in the text mode of graphical user interface. The *-D* flag
can be used several times in one command.
You must perform the CMake build system generation and compilation in
a new directory you create. It can be anywhere on your local machine.
In these Build pages we assume that you are building in a directory
called ``lammps/build``. You can perform separate builds independently
with different options, so long as you perform each of them in a
separate directory you create. All the auxiliary files created by one
build process (executable, object files, log files, etc) are stored in
this directory or sub-directories within it that CMake creates.
For your convenience we provide :ref:`CMake presets <cmake_presets>`
that combine multiple settings to enable optional LAMMPS packages or use
a different compiler tool chain. Those are loaded with the *-C* flag
(``-C ../cmake/presets/minimal.cmake``). This step would only be needed
once, as the settings from the preset files are stored in the
``CMakeCache.txt`` file. It is also possible to customize the build
by adding one or more *-D* flags to the CMake command line.
.. note::
Generating files for alternate build tools (e.g. Ninja) and project files
for IDEs like Eclipse, CodeBlocks, or Kate can be selected using the *-G*
command line flag. A list of available generator settings for your
specific CMake version is given when running ``cmake --help``.
To perform a CMake build, no packages can be installed or a build
been previously attempted in the LAMMPS src directory by using ``make``
commands to :doc:`perform a conventional LAMMPS build <Build_make>`.
CMake detects if this is the case and generates an error, telling you
to type ``make no-all purge`` in the src directory to un-install all
packages. The purge removes all the \*.h files auto-generated by
make.
You must have CMake version 3.10 or later on your system to build
LAMMPS. Installation instructions for CMake are below.
After the initial build, if you edit LAMMPS source files, or add your
own new files to the source directory, you can just re-type make from
your build directory and it will re-compile only the files that have
changed. If you want to change CMake options you can run cmake (or
ccmake or cmake-gui) again from the same build directory and alter
various options; see details below. Or you can remove the entire build
folder, recreate the directory and start over.
----------
**Command-line version of CMake**\ :
.. code-block:: bash
cmake [options ...] /path/to/lammps/cmake # build from any dir
cmake [options ...] ../cmake # build from lammps/build
cmake3 [options ...] ../cmake # build from lammps/build
The cmake command takes one required argument, which is the LAMMPS
cmake directory which contains the CMakeLists.txt file.
The argument can be prefixed or followed by various CMake
command-line options. Several useful ones are:
.. code-block:: bash
-D CMAKE_INSTALL_PREFIX=path # where to install LAMMPS executable/lib if desired
-D CMAKE_BUILD_TYPE=type # type = RelWithDebInfo (default), Release, MinSizeRel, or Debug
-G output # style of output CMake generates (e.g. "Unix Makefiles" or "Ninja")
-D CMAKE_MAKE_PROGRAM=builder # name of the builder executable (e.g. when using "gmake" instead of "make")
-DVARIABLE=value # setting for a LAMMPS feature to enable
-D VARIABLE=value # ditto, but cannot come after CMakeLists.txt dir
-C path/to/preset/file # load some CMake settings before configuring
All the LAMMPS-specific -D variables that a LAMMPS build supports are
described on the pages linked to from the :doc:`Build <Build>` doc page.
All of these variable names are upper-case and their values are
lower-case, e.g. -D LAMMPS_SIZES=smallbig. For boolean values, any of
these forms can be used: yes/no, on/off, 1/0.
On Unix/Linux machines, CMake generates a Makefile by default to
perform the LAMMPS build. Alternate forms of build info can be
generated via the -G switch, e.g. Visual Studio on a Windows machine,
Xcode on MacOS, or KDevelop on Linux. Type ``cmake --help`` to see the
"Generator" styles of output your system supports.
.. note::
When CMake runs, it prints configuration info to the screen.
You should review this to verify all the features you requested were
enabled, including packages. You can also see what compilers and
compile options will be used for the build. Any errors in CMake
variable syntax will also be flagged, e.g. mis-typed variable names or
variable values.
CMake creates a CMakeCache.txt file when it runs. This stores all the
settings, so that when running CMake again you can use the current
folder '.' instead of the path to the LAMMPS cmake folder as the
required argument to the CMake command. Either way the existing
settings will be inherited unless the CMakeCache.txt file is removed.
If you later want to change a setting you can rerun cmake in the build
directory with different setting. Please note that some automatically
detected variables will not change their value when you rerun cmake.
In these cases it is usually better to first remove all the
files/directories in the build directory, or start with a fresh build
directory.
----------
**Curses version (terminal-style menu) of CMake**\ :
.. code-block:: bash
ccmake ../cmake
You initiate the configuration and build environment generation steps
separately. For the first you have to type **c**\ , for the second you
have to type **g**\ . You may need to type **c** multiple times, and may be
required to edit some of the entries of CMake configuration variables
in between. Please see the `ccmake manual <https://cmake.org/cmake/help/latest/manual/ccmake.1.html>`_ for
more information.
----------
**GUI version of CMake**\ :
.. code-block:: bash
cmake-gui ../cmake
You initiate the configuration and build environment generation steps
separately. For the first you have to click on the **Configure** button,
for the second you have to click on the **Generate** button. You may
need to click on **Configure** multiple times, and may be required to
edit some of the entries of CMake configuration variables in between.
Please see the `cmake-gui manual <https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html>`_
for more information.
----------
**Installing CMake**
Installing CMake
^^^^^^^^^^^^^^^^
Check if your machine already has CMake installed:
@ -216,11 +169,12 @@ software packages, do this:
module list # is a module for cmake already loaded?
module avail # is a module for cmake available?
module load cmake3 # load cmake module with appropriate name
module load cmake # load cmake module with appropriate name
Most Linux distributions offer pre-compiled cmake packages through
their package management system. If you do not have CMake or a new
enough version, you can download the latest version at
`https://cmake.org/download/ <https://cmake.org/download/>`_.
Instructions on how to install it on various platforms can be found
`on this page <https://cmake.org/install/>`_.
Most Linux distributions offer pre-compiled cmake packages through their
package management system. If you do not have CMake or a recent enough
version (Note: for CentOS 7.x you need to enable the EPEL repository),
you can download the latest version from `https://cmake.org/download/
<https://cmake.org/download/>`_. Instructions on how to install it on
various platforms can be found `on this page
<https://cmake.org/install/>`_.

38
doc/src/Build_development.rst
View File

@ -1,15 +1,15 @@
Development build options (CMake only)
======================================
The CMake build of LAMMPS has a few extra options which are useful during
development, testing or debugging.
The CMake build procedure of LAMMPS offers a few extra options which are
useful during development, testing or debugging.
----------
.. _compilation:
Verify compilation flags
------------------------------------------
------------------------
Sometimes it is necessary to verify the complete sequence of compilation flags
generated by the CMake build. To enable a more verbose output during
@ -30,7 +30,7 @@ Another way of doing this without reconfiguration is calling make with variable
.. _sanitizer:
Address, Undefined Behavior, and Thread Sanitizer Support
-------------------------------------------------------------------------
---------------------------------------------------------
Compilers such as GCC and Clang support generating instrumented binaries
which use different sanitizer libraries to detect problems in code
@ -41,10 +41,11 @@ during run-time. They can detect issues like:
- `data races <https://clang.llvm.org/docs/ThreadSanitizer.html>`_
Please note that this kind of instrumentation usually comes with a small
performance hit (much less than using tools like `Valgrind <valgrind_>`_).
The to enable these features additional compiler flags need to be added
to the compilation and linking stages. This is most easily done through
setting the ``CMAKE_TUNE_FLAGS`` variable during configuration. Examples:
performance hit (much less than using tools like `Valgrind
<https://valgrind.org>`_). The to enable these features additional
compiler flags need to be added to the compilation and linking stages.
This is most easily done through setting the ``CMAKE_TUNE_FLAGS``
variable during configuration. Examples:
.. code-block:: bash
@ -52,8 +53,6 @@ setting the ``CMAKE_TUNE_FLAGS`` variable during configuration. Examples:
-D CMAKE_TUNE_FLAGS=-fsanitize=undefined # enable undefined behavior sanitizer
-D CMAKE_TUNE_FLAGS=-fsanitize=thread # enable thread sanitizer
.. _valgrind: https://valgrind.org
----------
.. _testing:
@ -75,24 +74,26 @@ developers can run the tests directly on their workstation.
-D LAMMPS_TESTING_SOURCE_DIR=path # path to lammps-testing repository (option if in custom location)
-D LAMMPS_TESTING_GIT_TAG=value # version of lammps-testing repository that should be used, value = master (default) or custom git commit or tag
If you enable testing in the CMake build it will create an additional target called "test". You can run them with:
If you enable testing in the CMake build it will create an additional
target called "test". You can run them with:
.. code-block:: bash
make test
cmake --build . test
The test cases used come from the lammps-testing repository. They are
derivatives of the examples folder with some modifications to make the run
faster.
derivatives of the examples folder with some modifications to make the
run faster.
You can also collect code coverage metrics while running the tests by enabling
coverage support during building.
You can also collect code coverage metrics while running the tests by
enabling coverage support during building.
.. code-block:: bash
-D ENABLE_COVERAGE=value # enable coverage measurements, value = no (default) or yes
This will also add the following targets to generate coverage reports after running the LAMMPS executable:
This will also add the following targets to generate coverage reports
after running the LAMMPS executable:
.. code-block:: bash
@ -100,7 +101,8 @@ This will also add the following targets to generate coverage reports after runn
make gen_coverage_html # generate coverage report in HTML format
make gen_coverage_xml # generate coverage report in XML format
These reports require GCOVR to be installed. The easiest way to do this to install it via pip:
These reports require GCOVR to be installed. The easiest way to do this
to install it via pip:
.. code-block:: bash

290
doc/src/Build_extras.rst
View File

@ -87,27 +87,33 @@ GPU package
---------------------
To build with this package, you must choose options for precision and
which GPU hardware to build for.
which GPU hardware to build for. The GPU package currently supports
three different types of backends: OpenCL, CUDA and HIP.
**CMake build**\ :
.. code-block:: bash
-D GPU_API=value # value = opencl (default) or cuda
-D GPU_PREC=value # precision setting
# value = double or mixed (default) or single
-D OCL_TUNE=value # hardware choice for GPU_API=opencl
# generic (default) or intel (Intel CPU) or fermi, kepler, cypress (NVIDIA)
-D GPU_ARCH=value # primary GPU hardware choice for GPU_API=cuda
# value = sm_XX, see below
# default is sm_30
-D CUDPP_OPT=value # optimization setting for GPU_API=cuda
# enables CUDA Performance Primitives Optimizations
# value = yes (default) or no
-D CUDA_MPS_SUPPORT=value # enables some tweaks required to run with active nvidia-cuda-mps daemon
# value = yes or no (default)
-D GPU_API=value # value = opencl (default) or cuda or hip
-D GPU_PREC=value # precision setting
# value = double or mixed (default) or single
-D OCL_TUNE=value # hardware choice for GPU_API=opencl
# generic (default) or intel (Intel CPU) or fermi, kepler, cypress (NVIDIA)
-D GPU_ARCH=value # primary GPU hardware choice for GPU_API=cuda
# value = sm_XX, see below
# default is sm_30
-D HIP_ARCH=value # primary GPU hardware choice for GPU_API=hip
# value depends on selected HIP_PLATFORM
# default is 'gfx906' for HIP_PLATFORM=hcc and 'sm_30' for HIP_PLATFORM=nvcc
-D HIP_USE_DEVICE_SORT=value # enables GPU sorting
# value = yes (default) or no
-D CUDPP_OPT=value # optimization setting for GPU_API=cuda
# enables CUDA Performance Primitives Optimizations
# value = yes (default) or no
-D CUDA_MPS_SUPPORT=value # enables some tweaks required to run with active nvidia-cuda-mps daemon
# value = yes or no (default)
GPU_ARCH settings for different GPU hardware is as follows:
:code:`GPU_ARCH` settings for different GPU hardware is as follows:
* sm_12 or sm_13 for GT200 (supported by CUDA 3.2 until CUDA 6.5)
* sm_20 or sm_21 for Fermi (supported by CUDA 3.2 until CUDA 7.5)
@ -126,6 +132,28 @@ Thus the GPU_ARCH setting is merely an optimization, to have code for
the preferred GPU architecture directly included rather than having to wait
for the JIT compiler of the CUDA driver to translate it.
If you are compiling with HIP, note that before running CMake you will have to
set appropriate environment variables. Some variables such as
:code:`HCC_AMDGPU_TARGET` or :code:`CUDA_PATH` are necessary for :code:`hipcc`
and the linker to work correctly.
.. code:: bash
# AMDGPU target
export HIP_PLATFORM=hcc
export HCC_AMDGPU_TARGET=gfx906
cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=gfx906 -D CMAKE_CXX_COMPILER=hipcc ..
make -j 4
.. code:: bash
# CUDA target
# !!! DO NOT set CMAKE_CXX_COMPILER !!!
export HIP_PLATFORM=nvcc
export CUDA_PATH=/usr/local/cuda
cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=sm_70 ..
make -j 4
**Traditional make**\ :
Before building LAMMPS, you must build the GPU library in ``lib/gpu``\ .
@ -189,13 +217,27 @@ KIM package
---------------------
To build with this package, the KIM library with API v2 must be downloaded
and built on your system. It must include the KIM models that you want to
use with LAMMPS. If you want to use the :doc:`kim_query <kim_commands>`
and built on your system. It must include the KIM models that you want to
use with LAMMPS.
If you would like to use the :doc:`kim_query <kim_commands>`
command, you also need to have libcurl installed with the matching
development headers and the curl-config tool.
See the `Obtaining KIM Models <http://openkim.org/doc/usage/obtaining-models>`_
web page to
If you would like to use the :doc:`kim_property <kim_commands>`
command, you need to build LAMMPS with the Python 3.6 or later package
installed. See the :doc:`Python <python>` doc page for more info on building
LAMMPS with the version of Python on your system.
After successfully building LAMMPS with Python, you need to
install the kim-property Python package, which can be easily done using
*pip* as ``pip install kim-property``, or from the *conda-forge* channel as
``conda install kim-property`` if LAMMPS is built in Conda. More detailed
information is available at:
`kim-property installation <https://github.com/openkim/kim-property#installing-kim-property>`_.
In addition to installing the KIM API, it is also necessary to install the
library of KIM models (interatomic potentials).
See `Obtaining KIM Models <http://openkim.org/doc/usage/obtaining-models>`_ to
learn how to install a pre-build binary of the OpenKIM Repository of Models.
See the list of all KIM models here: https://openkim.org/browse/models
@ -265,74 +307,131 @@ using. For example:
.. _kokkos:
KOKKOS package
---------------------------
--------------
To build with this package, you must choose which hardware you want to
build for, either CPUs (multi-threading via OpenMP) or KNLs (OpenMP)
or GPUs (NVIDIA Cuda).
Using the KOKKOS package requires choosing several settings. You have
to select whether you want to compile with parallelization on the host
and whether you want to include offloading of calculations to a device
(e.g. a GPU). The default setting is to have no host parallelization
and no device offloading. In addition, you can select the hardware
architecture to select the instruction set. Since most hardware is
backward compatible, you may choose settings for an older architecture
to have an executable that will run on this and newer architectures.
For a CMake or make build, these are the possible choices for the
``KOKKOS_ARCH`` settings described below. Note that for CMake, these are
really Kokkos variables, not LAMMPS variables. Hence you must use
case-sensitive values, e.g. BDW, not bdw.
.. note::
* AMDAVX = AMD 64-bit x86 CPUs
* EPYC = AMD EPYC Zen class CPUs
* ARMv80 = ARMv8.0 Compatible CPU
* ARMv81 = ARMv8.1 Compatible CPU
* ARMv8-ThunderX = ARMv8 Cavium ThunderX CPU
* ARMv8-TX2 = ARMv8 Cavium ThunderX2 CPU
* WSM = Intel Westmere CPUs
* SNB = Intel Sandy/Ivy Bridge CPUs
* HSW = Intel Haswell CPUs
* BDW = Intel Broadwell Xeon E-class CPUs
* SKX = Intel Sky Lake Xeon E-class HPC CPUs (AVX512)
* KNC = Intel Knights Corner Xeon Phi
* KNL = Intel Knights Landing Xeon Phi
* BGQ = IBM Blue Gene/Q CPUs
* Power7 = IBM POWER8 CPUs
* Power8 = IBM POWER8 CPUs
* Power9 = IBM POWER9 CPUs
* Kepler = NVIDIA Kepler default (generation CC 3.5)
* Kepler30 = NVIDIA Kepler generation CC 3.0
* Kepler32 = NVIDIA Kepler generation CC 3.2
* Kepler35 = NVIDIA Kepler generation CC 3.5
* Kepler37 = NVIDIA Kepler generation CC 3.7
* Maxwell = NVIDIA Maxwell default (generation CC 5.0)
* Maxwell50 = NVIDIA Maxwell generation CC 5.0
* Maxwell52 = NVIDIA Maxwell generation CC 5.2
* Maxwell53 = NVIDIA Maxwell generation CC 5.3
* Pascal60 = NVIDIA Pascal generation CC 6.0
* Pascal61 = NVIDIA Pascal generation CC 6.1
* Volta70 = NVIDIA Volta generation CC 7.0
* Volta72 = NVIDIA Volta generation CC 7.2
* Turing75 = NVIDIA Turing generation CC 7.5
NVIDIA GPUs with CC 5.0 (Maxwell) and newer are not compatible with
CC 3.x (Kepler). If you run Kokkos on a newer architecture than what
LAMMPS was compiled with, there will be a significant delay during
device initialization since the just-in-time compiler has to
recompile the GPU kernel code for the new hardware.
**CMake build**\ :
The settings discussed below have been tested with LAMMPS and are
confirmed to work. Kokkos is an active project with ongoing improvements
and projects working on including support for additional architectures.
More information on Kokkos can be found on the
`Kokkos GitHub project <https://github.com/kokkos>`_.
Available Architecture settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These are the possible choices for the Kokkos architecture ID. They must
be specified in uppercase.
.. list-table::
:header-rows: 0
:widths: auto
* - **Arch-ID**
- **Description**
* - AMDAVX
- AMD 64-bit x86 CPU (AVX 1)
* - EPYC
- AMD EPYC Zen class CPU (AVX 2)
* - ARMV80
- ARMv8.0 Compatible CPU
* - ARMV81
- ARMv8.1 Compatible CPU
* - ARMV8_THUNDERX
- ARMv8 Cavium ThunderX CPU
* - ARMV8_THUNDERX2
- ARMv8 Cavium ThunderX2 CPU
* - WSM
- Intel Westmere CPU (SSE 4.2)
* - SNB
- Intel Sandy/Ivy Bridge CPU (AVX 1)
* - HSW
- Intel Haswell CPU (AVX 2)
* - BDW
- Intel Broadwell Xeon E-class CPU (AVX 2 + transactional mem)
* - SKX
- Intel Sky Lake Xeon E-class HPC CPU (AVX512 + transactional mem)
* - KNC
- Intel Knights Corner Xeon Phi
* - KNL
- Intel Knights Landing Xeon Phi
* - BGQ
- IBM Blue Gene/Q CPU
* - POWER7
- IBM POWER8 CPU
* - POWER8
- IBM POWER8 CPU
* - POWER9
- IBM POWER9 CPU
* - KEPLER30
- NVIDIA Kepler generation CC 3.0 GPU
* - KEPLER32
- NVIDIA Kepler generation CC 3.2 GPU
* - KEPLER35
- NVIDIA Kepler generation CC 3.5 GPU
* - KEPLER37
- NVIDIA Kepler generation CC 3.7 GPU
* - MAXWELL50
- NVIDIA Maxwell generation CC 5.0 GPU
* - MAXWELL52
- NVIDIA Maxwell generation CC 5.2 GPU
* - MAXWELL53
- NVIDIA Maxwell generation CC 5.3 GPU
* - PASCAL60
- NVIDIA Pascal generation CC 6.0 GPU
* - PASCAL61
- NVIDIA Pascal generation CC 6.1 GPU
* - VOLTA70
- NVIDIA Volta generation CC 7.0 GPU
* - VOLTA72
- NVIDIA Volta generation CC 7.2 GPU
* - TURING75
- NVIDIA Turing generation CC 7.5 GPU
CMake build settings:
^^^^^^^^^^^^^^^^^^^^^
For multicore CPUs using OpenMP, set these 2 variables.
.. code-block:: bash
-D KOKKOS_ARCH=archCPU # archCPU = CPU from list above
-D KOKKOS_ENABLE_OPENMP=yes
-D Kokkos_ARCH_CPUARCH=yes # CPUARCH = CPU from list above
-D Kokkos_ENABLE_OPENMP=yes
-D BUILD_OMP=yes
For Intel KNLs using OpenMP, set these 2 variables:
Please note that enabling OpenMP for KOKKOS requires that OpenMP is
also :ref:`enabled for the rest of LAMMPS <serial>`.
For Intel KNLs using OpenMP, set these variables:
.. code-block:: bash
-D KOKKOS_ARCH=KNL
-D KOKKOS_ENABLE_OPENMP=yes
-D Kokkos_ARCH_KNL=yes
-D Kokkos_ENABLE_OPENMP=yes
For NVIDIA GPUs using CUDA, set these 4 variables:
For NVIDIA GPUs using CUDA, set these variables:
.. code-block:: bash
-D KOKKOS_ARCH="archCPU;archGPU" # archCPU = CPU from list above that is hosting the GPU
# archGPU = GPU from list above
-D KOKKOS_ENABLE_CUDA=yes
-D KOKKOS_ENABLE_OPENMP=yes
-D CMAKE_CXX_COMPILER=wrapper # wrapper = full path to Cuda nvcc wrapper
-D Kokkos_ARCH_CPUARCH=yes # CPUARCH = CPU from list above
-D Kokkos_ARCH_GPUARCH=yes # GPUARCH = GPU from list above
-D Kokkos_ENABLE_CUDA=yes
-D Kokkos_ENABLE_OPENMP=yes
-D CMAKE_CXX_COMPILER=wrapper # wrapper = full path to Cuda nvcc wrapper
The wrapper value is the Cuda nvcc compiler wrapper provided in the
Kokkos library: ``lib/kokkos/bin/nvcc_wrapper``\ . The setting should
@ -340,20 +439,35 @@ include the full path name to the wrapper, e.g.
.. code-block:: bash
-D CMAKE_CXX_COMPILER=/home/username/lammps/lib/kokkos/bin/nvcc_wrapper
-D CMAKE_CXX_COMPILER=${HOME}/lammps/lib/kokkos/bin/nvcc_wrapper
**Traditional make**\ :
To simplify the compilation, three preset files are included in the
``cmake/presets`` folder, ``kokkos-serial.cmake``, ``kokkos-openmp.cmake``,
and ``kokkos-cuda.cmake``. They will enable the KOKKOS package and
enable some hardware choice. So to compile with OpenMP host parallelization,
CUDA device parallelization (for GPUs with CC 5.0 and up) with some
common packages enabled, you can do the following:
.. code-block:: bash
mkdir build-kokkos-cuda
cd build-kokkos-cuda
cmake -C ../cmake/presets/minimal.cmake -C ../cmake/presets/kokkos-cuda.cmake ../cmake
cmake --build .
Traditional make settings:
^^^^^^^^^^^^^^^^^^^^^^^^^^
Choose which hardware to support in ``Makefile.machine`` via
``KOKKOS_DEVICES`` and ``KOKKOS_ARCH`` settings. See the
``src/MAKE/OPTIONS/Makefile.kokkos\*`` files for examples.
``src/MAKE/OPTIONS/Makefile.kokkos*`` files for examples.
For multicore CPUs using OpenMP:
.. code-block:: make
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = archCPU # archCPU = CPU from list above
KOKKOS_ARCH = CPUARCH # CPUARCH = CPU from list above
For Intel KNLs using OpenMP:
@ -367,22 +481,28 @@ For NVIDIA GPUs using CUDA:
.. code-block:: make
KOKKOS_DEVICES = Cuda
KOKKOS_ARCH = archCPU,archGPU # archCPU = CPU from list above that is hosting the GPU
# archGPU = GPU from list above
FFT_INC = -DFFT_CUFFT # enable use of cuFFT (optional)
FFT_LIB = -lcufft # link to cuFFT library
KOKKOS_ARCH = CPUARCH,GPUARCH # CPUARCH = CPU from list above that is hosting the GPU
# GPUARCH = GPU from list above
FFT_INC = -DFFT_CUFFT # enable use of cuFFT (optional)
FFT_LIB = -lcufft # link to cuFFT library
For GPUs, you also need the following 2 lines in your Makefile.machine
before the CC line is defined, in this case for use with OpenMPI mpicxx.
The 2 lines define a nvcc wrapper compiler, which will use nvcc for
compiling CUDA files and use a C++ compiler for non-Kokkos, non-CUDA
files.
For GPUs, you also need the following lines in your ``Makefile.machine``
before the CC line is defined. They tell ``mpicxx`` to use an ``nvcc``
compiler wrapper, which will use ``nvcc`` for compiling CUDA files and a
C++ compiler for non-Kokkos, non-CUDA files.
.. code-block:: make
# For OpenMPI
KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd)
export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper
CC = mpicxx
CC = mpicxx
.. code-block:: make
# For MPICH and derivatives
KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd)
CC = mpicxx -cxx=$(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper
----------
@ -421,7 +541,7 @@ args:
$ make lib-latte args="-b" # download and build in lib/latte/LATTE-master
$ make lib-latte args="-p $HOME/latte" # use existing LATTE installation in $HOME/latte
$ make lib-latte args="-b -m gfortran" # download and build in lib/latte and
# copy Makefile.lammps.gfortran to Makefile.lammps
# copy Makefile.lammps.gfortran to Makefile.lammps
Note that 3 symbolic (soft) links, "includelink" and "liblink" and
"filelink.o", are created in lib/latte to point into the LATTE home

147
doc/src/Build_link.rst
View File

@ -1,33 +1,35 @@
Link LAMMPS as a library to another code
========================================
LAMMPS can be used as a library by another application, including
Python scripts. The files src/library.cpp and library.h define the
LAMMPS is designed as a library of C++ objects and can thus be
integrated into other applications including Python scripts.
The files ``src/library.cpp`` and ``src/library.h`` define a
C-style API for using LAMMPS as a library. See the :doc:`Howto
library <Howto_library>` doc page for a description of the interface
and how to extend it for your needs.
The :doc:`Build basics <Build_basics>` doc page explains how to build
LAMMPS as either a shared or static library. This results in one of
these 2 files:
.. code-block:: bash
liblammps.so # shared library
liblammps.a # static library
LAMMPS as either a shared or static library. This results in a file
in the compilation folder called ``liblammps.a`` or ``liblammps_<name>.a``
in case of building a static library. In case of a shared library
the name is the same only that the suffix is going to be either ``.so``
or ``.dylib`` or ``.dll`` instead of ``.a`` depending on the OS.
In some cases the ``.so`` file may be a symbolic link to a file with
the suffix ``.so.0`` (or some other number).
.. note::
Care should be taken to use the same MPI library for the calling
code and the LAMMPS library. The library.h file includes mpi.h and
uses definitions from it so those need to be available and
consistent. When LAMMPS is compiled with the MPI STUBS library,
then its mpi.h file needs to be included. While it is technically
possible to use a full MPI library in the calling code and link to
a serial LAMMPS library compiled with MPI STUBS, it is recommended
to use the *same* MPI library for both, and then use MPI_Comm_split()
in the calling code to pass a suitable communicator with a subset
of MPI ranks to the function creating the LAMMPS instance.
Care should be taken to use the same MPI library for the calling code
and the LAMMPS library. The ``library.h`` file includes ``mpi.h``
and uses definitions from it so those need to be available and
consistent. When LAMMPS is compiled with the included STUBS MPI
library, then its ``mpi.h`` file needs to be included. While it is
technically possible to use a full MPI library in the calling code
and link to a serial LAMMPS library compiled with MPI STUBS, it is
recommended to use the *same* MPI library for both, and then use
``MPI_Comm_split()`` in the calling code to pass a suitable
communicator with a subset of MPI ranks to the function creating the
LAMMPS instance.
----------
@ -42,11 +44,11 @@ executable code from the library is copied into the calling executable.
*CMake build*\ :
This assumes that LAMMPS has been configured with "-D BUILD_LIB=yes"
and installed with "make install" and the PKG_CONFIG_PATH environment
variable updated to include the *liblammps.pc* file installed into the
configured destination folder, if needed. The commands to compile and
link the coupled executable are then:
This assumes that LAMMPS has been configured without setting a
``LAMMPS_MACHINE`` name, installed with "make install", and the
``PKG_CONFIG_PATH`` environment variable has been updated to include the
``liblammps.pc`` file installed into the configured destination folder.
The commands to compile and link a coupled executable are then:
.. code-block:: bash
@ -56,30 +58,35 @@ link the coupled executable are then:
*Traditional make*\ :
This assumes that LAMMPS has been compiled in the folder
"${HOME}/lammps/src" with "make mode=lib mpi". The commands to compile
and link the coupled executable are then:
``${HOME}/lammps/src`` with "make mpi". The commands to compile and link
a coupled executable are then:
.. code-block:: bash
mpicc -c -O -I${HOME}/lammps/src caller.c
mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps
mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps_mpi
The *-I* argument is the path to the location of the *library.h*
The *-I* argument is the path to the location of the ``library.h``
header file containing the interface to the LAMMPS C-style library
interface. The *-L* argument is the path to where the *liblammps.a*
file is located. The *-llammps* argument is shorthand for telling the
compiler to link the file *liblammps.a*\ .
interface. The *-L* argument is the path to where the ``liblammps_mpi.a``
file is located. The *-llammps_mpi* argument is shorthand for telling the
compiler to link the file ``liblammps_mpi.a``. If LAMMPS has been
built as a shared library, then the linker will use ``liblammps_mpi.so``
instead. If both files are available, the linker will usually prefer
the shared library. In case of a shared library, you may need to update
the ``LD_LIBRARY_PATH`` environment variable or running the ``caller``
executable will fail since it cannot find the shared library at runtime.
However, it is only as simple as shown above for the case of a plain
LAMMPS library without any optional packages that depend on libraries
(bundled or external). Otherwise, you need to include all flags,
libraries, and paths for the coupled executable, that are also
required to link the LAMMPS executable.
(bundled or external) or when using a shared library. Otherwise, you
need to include all flags, libraries, and paths for the coupled
executable, that are also required to link the LAMMPS executable.
*CMake build*\ :
When using CMake, additional libraries with sources in the lib folder
are built, but not included in liblammps.a and (currently) not
are built, but not included in ``liblammps.a`` and (currently) not
installed with "make install" and not included in the *pkgconfig*
configuration file. They can be found in the top level build folder,
but you have to determine the necessary link flags manually. It is
@ -87,23 +94,26 @@ therefore recommended to either use the traditional make procedure to
build and link with a static library or build and link with a shared
library instead.
.. TODO: this needs to be updated to reflect that latest CMake changes after they are complete.
*Traditional make*\ :
After you have compiled a static LAMMPS library using the conventional
build system for example with "make mode=lib serial". And you also
have installed the POEMS package after building its bundled library in
lib/poems. Then the commands to build and link the coupled executable
build system for example with "make mode=static serial". And you also
have installed the ``POEMS`` package after building its bundled library
in ``lib/poems``. Then the commands to build and link the coupled executable
change to:
.. code-block:: bash
gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
g++ -o caller caller.o -L${HOME}/lammps/lib/poems \
-L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src -llammps -lpoems -lmpi_stubs
-L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src -llammps_serial -lpoems -lmpi_stubs
Note, that you need to link with "g++" instead of "gcc", since LAMMPS
is C++ code. You can display the currently applied settings for building
LAMMPS for the "serial" machine target by using the command:
Note, that you need to link with "g++" instead of "gcc", since the
LAMMPS library is C++ code. You can display the currently applied
settings for building LAMMPS for the "serial" machine target by using
the command:
.. code-block:: bash
@ -113,16 +123,16 @@ Which should output something like:
.. code-block:: bash
# Compiler:
# Compiler:
CXX=g++
# Linker:
# Linker:
LD=g++
# Compilation:
CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/lammps/lib/poems -I${HOME}/lammps/src/STUBS
# Linking:
# Compilation:
CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/compile/lammps/lib/poems -I${HOME}/compile/lammps/src/STUBS
# Linking:
LDFLAGS=-g -O
# Libraries:
LDLIBS=-L${HOME}/lammps/lib/poems -L${HOME}/lammps/src/STUBS -lpoems -lmpi_stubs
# Libraries:
LDLIBS=-L${HOME}/compile/lammps/src -llammps_serial -L${HOME}/compile/lammps/lib/poems -L${HOME}/compile/lammps/src/STUBS -lpoems -lmpi_stubs
From this you can gather the necessary paths and flags. With
makefiles for other *machine* configurations you need to do the
@ -133,14 +143,13 @@ of the makefile.
**Link with LAMMPS as a shared library**\ :
When linking to LAMMPS built as a shared library, the situation
becomes much simpler, as all dependent libraries and objects are
included in the shared library, which is - technically speaking -
effectively a regular LAMMPS executable that is missing the `main()`
function. Thus those libraries need not to be specified when linking
the calling executable. Only the *-I* flags are needed. So the
example case from above of the serial version static LAMMPS library
with the POEMS package installed becomes:
When linking to LAMMPS built as a shared library, the situation becomes
much simpler, as all dependent libraries and objects are either included
in the shared library or registered as a dependent library in the shared
library file. Thus those libraries need not to be specified when
linking the calling executable. Only the *-I* flags are needed. So the
example case from above of the serial version static LAMMPS library with
the POEMS package installed becomes:
*CMake build*\ :
@ -155,19 +164,19 @@ build process are the same as for the static library.
*Traditional make*\ :
The commands with a shared LAMMPS library compiled with the
traditional make build using "make mode=shlib serial" becomes:
traditional make build using "make mode=shared serial" becomes:
.. code-block:: bash
gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
g++ -o caller caller.o -L${HOME}/lammps/src -llammps
g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial
*Locating liblammps.so at runtime*\ :
However, now the `liblammps.so` file is required at runtime and needs
However, now the ``liblammps.so`` file is required at runtime and needs
to be in a folder, where the shared linker program of the operating
system can find it. This would be either a folder like "/usr/local/lib64"
or "${HOME}/.local/lib64" or a folder pointed to by the LD_LIBRARY_PATH
system can find it. This would be either a folder like ``/usr/local/lib64``
or ``${HOME}/.local/lib64`` or a folder pointed to by the ``LD_LIBRARY_PATH``
environment variable. You can type
.. code-block:: bash
@ -177,11 +186,11 @@ environment variable. You can type
to see what directories are in that list.
Or you can add the LAMMPS src directory (or the directory you performed
a CMake style build in) to your LD_LIBRARY_PATH, so that the current
a CMake style build in) to your ``LD_LIBRARY_PATH``, so that the current
version of the shared library is always available to programs that use it.
For the Bourne or Korn shells (/bin/sh, /bin/ksh, /bin/bash etc.), you
would add something like this to your ~/.profile file:
would add something like this to your ``${HOME}/.profile`` file:
.. code-block:: bash
@ -189,14 +198,14 @@ would add something like this to your ~/.profile file:
export LD_LIBRARY_PATH
For the csh or tcsh shells, you would equivalently add something like this
to your ~/.cshrc file:
to your ``${HOME}/.cshrc`` file:
.. code-block:: csh
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${HOME}/lammps/src
You can verify whether all required shared libraries are found with the
`ldd` tool. Example:
``ldd`` tool. Example:
.. code-block:: bash
@ -229,20 +238,20 @@ If a required library is missing, you would get a 'not found' entry:
Either flavor of library (static or shared) allows one or more LAMMPS
objects to be instantiated from the calling program. When used from a
C++ program, most of the symbols and functions in LAMMPS are wrapped
in a LAMMPS_NS namespace; you can safely use any of its classes and
in a ``LAMMPS_NS`` namespace; you can safely use any of its classes and
methods from within the calling code, as needed, and you will not incur
conflicts with functions and variables in your code that share the name.
This, however, does not extend to all additional libraries bundled with
LAMMPS in the lib folder and some of the low-level code of some packages.
To be compatible with C, Fortran, Python programs, the library has a simple
C-style interface, provided in src/library.cpp and src/library.h.
C-style interface, provided in ``src/library.cpp`` and ``src/library.h``.
See the :doc:`Python library <Python_library>` doc page for a
description of the Python interface to LAMMPS, which wraps the C-style
interface from a shared library through the `ctypes python module <ctypes_>`_.
See the sample codes in examples/COUPLE/simple for examples of C++ and
See the sample codes in ``examples/COUPLE/simple`` for examples of C++ and
C and Fortran codes that invoke LAMMPS through its library interface.
Other examples in the COUPLE directory use coupling ideas discussed on
the :doc:`Howto couple <Howto_couple>` doc page.

93
doc/src/Build_make.rst
View File

@ -2,10 +2,14 @@ Build LAMMPS with make
======================
Building LAMMPS with traditional makefiles requires that you have a
Makefile."machine" file appropriate for your system in the src/MAKE,
src/MAKE/MACHINES, src/MAKE/OPTIONS, or src/MAKE/MINE directory (see
below). It can include various options for customizing your LAMMPS
build with a number of global compilation options and features.
``Makefile.<machine>`` file appropriate for your system in either the
``src/MAKE``, ``src/MAKE/MACHINES``, ``src/MAKE/OPTIONS``, or
``src/MAKE/MINE`` directory (see below). It can include various options
for customizing your LAMMPS build with a number of global compilation
options and features.
Requirements
^^^^^^^^^^^^
Those makefiles are written for and tested with GNU make and may not
be compatible with other make programs. In most cases, if the "make"
@ -16,44 +20,54 @@ with :doc:`CMake <Build_cmake>`. The makefiles of the traditional
make based build process and the scripts they are calling expect a few
additional tools to be available and functioning.
* a Bourne shell compatible "Unix" shell program (often this is bash)
* a few shell utilities: ls, mv, ln, rm, grep, sed, tr, cat, touch, diff, dirname
* python (optional, required for "make lib-XXX" in the src folder)
* a working C/C++ compiler toolchain supporting the C++11 standard; on
Linux these are often the GNU compilers. Some older compilers
require adding flags like ``-std=c++11`` to enable the C++11 mode.
* a Bourne shell compatible "Unix" shell program (often this is ``bash``)
* a few shell utilities: ``ls``, ``mv``, ``ln``, ``rm``, ``grep``, ``sed``, ``tr``, ``cat``, ``touch``, ``diff``, ``dirname``
* python (optional, required for ``make lib-<pkg>`` in the src folder).
python scripts are currently tested with python 2.7 and 3.6. The procedure
for :doc:`building the documentation <Manual_build>` requires python 3.
To include LAMMPS packages (i.e. optional commands and styles) you
must enable them first, as discussed on the :doc:`Build package
<Build_package>` doc page. If a packages requires (provided or
Getting started
^^^^^^^^^^^^^^^
To include LAMMPS packages (i.e. optional commands and styles) you must
enable (or "install") them first, as discussed on the :doc:`Build
package <Build_package>` doc page. If a packages requires (provided or
external) libraries, you must configure and build those libraries
**before** building LAMMPS itself and especially **before** enabling
such a package with "make yes-<package>". Building :doc:`LAMMPS
with CMake <Build_cmake>` can automate much of this for many types of
such a package with ``make yes-<package>``. Building :doc:`LAMMPS with
CMake <Build_cmake>` can automate much of this for many types of
machines, especially workstations, desktops, and laptops, so we suggest
you try it first when building LAMMPS in those cases.
The commands below perform a default LAMMPS build, producing the LAMMPS
executable lmp_serial and lmp_mpi in lammps/src:
executable ``lmp_serial`` and ``lmp_mpi`` in ``lammps/src``:
.. code-block:: bash
cd lammps/src
make serial # build a serial LAMMPS executable
cd lammps/src # change to main LAMMPS source folder
make serial # build a serial LAMMPS executable using GNU g++
make mpi # build a parallel LAMMPS executable with MPI
make # see a variety of make options
This initial compilation can take a long time, since LAMMPS is a large
project with many features. If your machine has multiple CPU cores
(most do these days), using a command like "make -jN mpi" (with N =
the number of available CPU cores) can be much faster. If you plan to
do development on LAMMPS or need to re-compile LAMMPS repeatedly, the
installation of the ccache (= Compiler Cache) software may speed up
compilation even more.
Compilation can take a long time, since LAMMPS is a large project with
many features. If your machine has multiple CPU cores (most do these
days), you can speed this up by compiling sources in parallel with
``make -j N`` (with N being the maximum number of concurrently executed
tasks). Also installation of the `ccache <https://ccache.dev/>`_ (=
Compiler Cache) software may speed up repeated compilation even more,
e.g. during code development.
After the initial build, whenever you edit LAMMPS source files, or add
or remove new files to the source directory (e.g. by installing or
uninstalling packages), you must re-compile and relink the LAMMPS
executable with the same "make" command. This makefiles dependencies
should insure that only the subset of files that need to be are
re-compiled.
executable with the same ``make <machine>`` command. The makefile's
dependency tracking should insure that only the necessary subset of
files are re-compiled. If you change settings in the makefile, you have
to recompile *everything*. To delete all objects you can use ``make
clean-<machine>``.
.. note::
@ -65,13 +79,15 @@ re-compiled.
correctly detect which parts need to be recompiled after changes
were made to the sources.
----------
Customized builds and alternate makefiles
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The lammps/src/MAKE tree contains the Makefile.machine files included
in the LAMMPS distribution. Typing "make machine" uses
*Makefile.machine*\ . Thus the "make serial" or "make mpi" lines above
use Makefile.serial and Makefile.mpi, respectively. Other makefiles
are in these directories:
The ``src/MAKE`` directory tree contains the ``Makefile.<machine>``
files included in the LAMMPS distribution. Typing ``make example`` uses
``Makefile.example`` from one of those folders, if available. Thus the
``make serial`` and ``make mpi`` lines above use
``src/MAKE/Makefile.serial`` and ``src/MAKE/Makefile.mpi``,
respectively. Other makefiles are in these directories:
.. code-block:: bash
@ -79,11 +95,16 @@ are in these directories:
MACHINES # Makefiles for specific machines
MINE # customized Makefiles you create (you may need to create this folder)
Typing "make" lists all the available Makefile.machine files. A file
with the same name can appear in multiple folders (not a good idea).
The order the directories are searched is as follows: src/MAKE/MINE,
src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives preference
to a customized file you put in src/MAKE/MINE.
Simply typing ``make`` lists all the available ``Makefile.<machine>``
files with a single line description toward the end of the output. A
file with the same name can appear in multiple folders (not a good
idea). The order the directories are searched is as follows:
``src/MAKE/MINE``, ``src/MAKE``, ``src/MAKE/OPTIONS``,
``src/MAKE/MACHINES``. This gives preference to a customized file you
put in ``src/MAKE/MINE``. If you create your own custom makefile under
a new name, please edit the first line with the description and machine
name, so you will not confuse yourself, when looking at the machine
summary.
Makefiles you may wish to try include these (some require a package
first be installed). Many of these include specific compiler flags

2
doc/src/Build_package.rst
View File

@ -130,6 +130,8 @@ src directory.
----------
.. _cmake_presets:
**CMake shortcuts for installing many packages**\ :
Instead of specifying all the CMake options via the command-line,

1
doc/src/Commands_all.rst
View File

@ -70,6 +70,7 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`kim_init <kim_commands>`
* :doc:`kim_interactions <kim_commands>`
* :doc:`kim_param <kim_commands>`
* :doc:`kim_property <kim_commands>`
* :doc:`kim_query <kim_commands>`
* :doc:`kspace_modify <kspace_modify>`
* :doc:`kspace_style <kspace_style>`

1
doc/src/Commands_pair.rst
View File

@ -131,6 +131,7 @@ OPT.
* :doc:`lj/class2/coul/cut (ko) <pair_class2>`
* :doc:`lj/class2/coul/cut/soft <pair_fep_soft>`
* :doc:`lj/class2/coul/long (gko) <pair_class2>`
* :doc:`lj/class2/coul/long/cs <pair_cs>`
* :doc:`lj/class2/coul/long/soft <pair_fep_soft>`
* :doc:`lj/class2/soft <pair_fep_soft>`
* :doc:`lj/cubic (go) <pair_lj_cubic>`

2
doc/src/Commands_removed.rst
View File

@ -48,7 +48,7 @@ The USER-CUDA package had been removed, since it had been unmaintained
for a long time and had known bugs and problems. Significant parts of
the design were transferred to the
:ref:`KOKKOS package <PKG-KOKKOS>`, which has similar
performance characteristics on Nvidia GPUs. Both, the KOKKOS
performance characteristics on NVIDIA GPUs. Both, the KOKKOS
and the :ref:`GPU package <PKG-GPU>` are maintained
and allow running LAMMPS with GPU acceleration.

1
doc/src/Errors.rst
View File

@ -12,5 +12,6 @@ additional details for many of them.
Errors_common
Errors_bugs
Errors_debug
Errors_messages
Errors_warnings

24
doc/src/Errors_bugs.rst
View File

@ -1,7 +1,8 @@
Reporting bugs
==============
If you are confident that you have found a bug in LAMMPS, please follow the steps outlined below:
If you are confident that you have found a bug in LAMMPS, please follow
the steps outlined below:
* Check the `New features and bug fixes
<https://lammps.sandia.gov/bug.html>`_ section of the `LAMMPS WWW site
@ -17,20 +18,22 @@ If you are confident that you have found a bug in LAMMPS, please follow the step
* Check the `mailing list archives <https://lammps.sandia.gov/mail.html>`_
to see if the issue has been discussed before.
If none of these steps yields any useful information, please file
a new bug report on the `GitHub Issue page <gip_>`_\ .
The website will offer you to select a suitable template with explanations
and then you should replace those explanations with the information
that you can provide to reproduce your issue.
If none of these steps yields any useful information, please file a new
bug report on the `GitHub Issue page <gip_>`_. The website will offer
you to select a suitable template with explanations and then you should
replace those explanations with the information that you can provide to
reproduce your issue.
The most useful thing you can do to help us verify and fix a bug is to
isolate the problem. Run it on the smallest number of atoms and fewest
number of processors with the simplest input script that reproduces the
bug. Try to identify what command or combination of commands is
causing the problem and upload the complete input deck as a tar or zip
archive. Please avoid using binary restart files unless the issue requires
it. In the latter case you should also include an input deck to quickly
bug. Try to identify what command or combination of commands is causing
the problem and upload the complete input deck as a tar or zip archive.
Please avoid using binary restart files unless the issue requires it.
In the latter case you should also include an input deck to quickly
generate this restart from a data file or a simple additional input.
This input deck can be used with tools like a debugger or `valgrind
<valgrind_>`_ to further :doc:`debug the crash <Errors_debug>`.
You may also send an email to the LAMMPS mailing list at
"lammps-users at lists.sourceforge.net" describing the problem with the
@ -43,3 +46,4 @@ have looked at it.
.. _lws: https://lammps.sandia.gov
.. _gip: https://github.com/lammps/issues
.. _valgrind: https://valgrind.org

237
doc/src/Errors_debug.rst Normal file
View File

@ -0,0 +1,237 @@
Debugging crashes
=================
If LAMMPS crashes with a "segmentation fault" or a "bus error" or
similar message, then you can use the following two methods to further
narrow down the origin of the issue. This will help the LAMMPS
developers (or yourself) to understand the reason for the crash and
apply a fix (either to the input script or the source code).
This requires that your LAMMPS executable includes the required
:ref:`debug information <debug>`. Otherwise it is not possible to
look up the names of functions or variables.
The following patch will introduce a bug into the code for pair style
:doc:`lj/cut <pair_lj>` when using the ``examples/melt/in.melt`` input.
We use it to show how to identify the origin of a segmentation fault.
.. code-block:: diff
--- a/src/pair_lj_cut.cpp
+++ b/src/pair_lj_cut.cpp
@@ -81,6 +81,7 @@ void PairLJCut::compute(int eflag, int vflag)
int nlocal = atom->nlocal;
double *special_lj = force->special_lj;
int newton_pair = force->newton_pair;
+ double comx = 0.0;
inum = list->inum;
ilist = list->ilist;
@@ -134,8 +135,10 @@ void PairLJCut::compute(int eflag, int vflag)
evdwl,0.0,fpair,delx,dely,delz);
}
}
- }
+ comx += atom->rmass[i]*x[i][0]; /* BUG */
+ }
+ printf("comx = %g\n",comx);
if (vflag_fdotr) virial_fdotr_compute();
}
After recompiling LAMMPS and running the input you should get something like this:
.. code-block:
$ ./lmp -in in.melt
LAMMPS (19 Mar 2020)
OMP_NUM_THREADS environment is not set. Defaulting to 1 thread. (src/comm.cpp:94)
using 1 OpenMP thread(s) per MPI task
Lattice spacing in x,y,z = 1.6796 1.6796 1.6796
Created orthogonal box = (0 0 0) to (16.796 16.796 16.796)
1 by 1 by 1 MPI processor grid
Created 4000 atoms
create_atoms CPU = 0.000432253 secs
Neighbor list info ...
update every 20 steps, delay 0 steps, check no
max neighbors/atom: 2000, page size: 100000
master list distance cutoff = 2.8
ghost atom cutoff = 2.8
binsize = 1.4, bins = 12 12 12
1 neighbor lists, perpetual/occasional/extra = 1 0 0
(1) pair lj/cut, perpetual
attributes: half, newton on
pair build: half/bin/atomonly/newton
stencil: half/bin/3d/newton
bin: standard
Setting up Verlet run ...
Unit style : lj
Current step : 0
Time step : 0.005
Segmentation fault (core dumped)
Using the GDB debugger to get a stack trace
-------------------------------------------
There are two options to use the GDB debugger for identifying the origin
of the segmentation fault or similar crash. The GDB debugger has many
more features and options, as can be seen for example its `online
documentation <http://sourceware.org/gdb/current/onlinedocs/gdb/>`_.
Run LAMMPS from within the debugger
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Running LAMMPS under the control of the debugger as shown below only
works for a single MPI rank (for debugging a program running in parallel
you usually need a parallel debugger program). A simple way to launch
GDB is to prefix the LAMMPS command line with ``gdb --args`` and then
type the command "run" at the GDB prompt. This will launch the
debugger, load the LAMMPS executable and its debug info, and then run
it. When it reaches the code causing the segmentation fault, it will
stop with a message why it stopped, print the current line of code, and
drop back to the GDB prompt.
.. code-block::
[...]
Setting up Verlet run ...
Unit style : lj
Current step : 0
Time step : 0.005
Program received signal SIGSEGV, Segmentation fault.
0x00000000006653ab in LAMMPS_NS::PairLJCut::compute (this=0x829740, eflag=1, vflag=<optimized out>) at /home/akohlmey/compile/lammps/src/pair_lj_cut.cpp:139
139 comx += atom->rmass[i]*x[i][0]; /* BUG */
(gdb)
Now typing the command "where" will show the stack of functions starting from
the current function back to "main()".
.. code-block::
(gdb) where
#0 0x00000000006653ab in LAMMPS_NS::PairLJCut::compute (this=0x829740, eflag=1, vflag=<optimized out>) at /home/akohlmey/compile/lammps/src/pair_lj_cut.cpp:139
#1 0x00000000004cf0a2 in LAMMPS_NS::Verlet::setup (this=0x7e6c90, flag=1) at /home/akohlmey/compile/lammps/src/verlet.cpp:131
#2 0x000000000049db42 in LAMMPS_NS::Run::command (this=this@entry=0x7fffffffcca0, narg=narg@entry=1, arg=arg@entry=0x7e8750)
at /home/akohlmey/compile/lammps/src/run.cpp:177
#3 0x000000000041258a in LAMMPS_NS::Input::command_creator<LAMMPS_NS::Run> (lmp=<optimized out>, narg=1, arg=0x7e8750)
at /home/akohlmey/compile/lammps/src/input.cpp:878
#4 0x0000000000410ad3 in LAMMPS_NS::Input::execute_command (this=0x7d1410) at /home/akohlmey/compile/lammps/src/input.cpp:864
#5 0x00000000004111fb in LAMMPS_NS::Input::file (this=0x7d1410) at /home/akohlmey/compile/lammps/src/input.cpp:229
#6 0x000000000040933a in main (argc=<optimized out>, argv=<optimized out>) at /home/akohlmey/compile/lammps/src/main.cpp:65
(gdb)
You can also print the value of variables and see if there is anything
unexpected. Segmentation faults, for example, commonly happen when a
pointer variable is not assigned and still initialized to NULL.
.. code-block::
(gdb) print x
$1 = (double **) 0x7ffff7ca1010
(gdb) print i
$2 = 0
(gdb) print x[0]
$3 = (double *) 0x7ffff6d80010
(gdb) print x[0][0]
$4 = 0
(gdb) print x[1][0]
$5 = 0.83979809569125363
(gdb) print atom->rmass
$6 = (double *) 0x0
(gdb)
Inspect a core dump file with the debugger
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When an executable crashes with a "core dumped" message, it creates a
file "core" or "core.<PID#>" which contains the information about the
current state. This file may be located in the folder where you ran
LAMMPS or in some hidden folder managed by the systemd daemon. In the
latter case, you need to "extract" the core file with the ``coredumpctl``
utility to the current folder. Example: ``coredumpctl -o core dump lmp``.
Now you can launch the debugger to load the executable, its debug info
and the core dump and drop you to a prompt like before.
.. code-block::
$ gdb lmp core
Reading symbols from lmp...
[New LWP 1928535]
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib64/libthread_db.so.1".
Core was generated by `./lmp -in in.melt'.
Program terminated with signal SIGSEGV, Segmentation fault.
#0 0x00000000006653ab in LAMMPS_NS::PairLJCut::compute (this=0x1b10740, eflag=1, vflag=<optimized out>)
at /home/akohlmey/compile/lammps/src/pair_lj_cut.cpp:139
139 comx += atom->rmass[i]*x[i][0]; /* BUG */
(gdb)
From here on, you use the same commands as shown before to get a stack
trace and print current values of (pointer) variables.
Using valgrind to get a stack trace
-----------------------------------
The `valgrind <https://valgrind.org>`_ suite of tools allows to closely
inspect the behavior of a compiled program by essentially emulating a
CPU and instrumenting the program while running. This slows down
execution quite significantly, but can also report issues that are not
resulting in a crash. The default valgrind tool is a memory checker and
you can use it by prefixing the normal command line with ``valgrind``.
Unlike GDB, this will also work for parallel execution, but it is
recommended to redirect the valgrind output to a file (e.g. with
``--log-file=crash-%p.txt``, the %p will be substituted with the
process ID) so that the messages of the multiple valgrind instances to
the console are not mixed.
.. code-block::
$ valgrind ./lmp -in in.melt
==1933642== Memcheck, a memory error detector
==1933642== Copyright (C) 2002-2017, and GNU GPL'd, by Julian Seward et al.
==1933642== Using Valgrind-3.15.0 and LibVEX; rerun with -h for copyright info
==1933642== Command: ./lmp -in in.melt
==1933642==
LAMMPS (19 Mar 2020)
OMP_NUM_THREADS environment is not set. Defaulting to 1 thread. (src/comm.cpp:94)
using 1 OpenMP thread(s) per MPI task
Lattice spacing in x,y,z = 1.6796 1.6796 1.6796
Created orthogonal box = (0 0 0) to (16.796 16.796 16.796)
1 by 1 by 1 MPI processor grid
Created 4000 atoms
create_atoms CPU = 0.032964 secs
Neighbor list info ...
update every 20 steps, delay 0 steps, check no
max neighbors/atom: 2000, page size: 100000
master list distance cutoff = 2.8
ghost atom cutoff = 2.8
binsize = 1.4, bins = 12 12 12
1 neighbor lists, perpetual/occasional/extra = 1 0 0
(1) pair lj/cut, perpetual
attributes: half, newton on
pair build: half/bin/atomonly/newton
stencil: half/bin/3d/newton
bin: standard
Setting up Verlet run ...
Unit style : lj
Current step : 0
Time step : 0.005
==1933642== Invalid read of size 8
==1933642== at 0x6653AB: LAMMPS_NS::PairLJCut::compute(int, int) (pair_lj_cut.cpp:139)
==1933642== by 0x4CF0A1: LAMMPS_NS::Verlet::setup(int) (verlet.cpp:131)
==1933642== by 0x49DB41: LAMMPS_NS::Run::command(int, char**) (run.cpp:177)
==1933642== by 0x412589: void LAMMPS_NS::Input::command_creator<LAMMPS_NS::Run>(LAMMPS_NS::LAMMPS*, int, char**) (input.cpp:881)
==1933642== by 0x410AD2: LAMMPS_NS::Input::execute_command() (input.cpp:864)
==1933642== by 0x4111FA: LAMMPS_NS::Input::file() (input.cpp:229)
==1933642== by 0x409339: main (main.cpp:65)
==1933642== Address 0x0 is not stack'd, malloc'd or (recently) free'd
==1933642==
As you can see, the stack trace information is similar to that obtained
from GDB. In addition you get a more specific hint about what cause the
segmentation fault, i.e. that it is a NULL pointer dereference. To find
out which pointer exactly was NULL, you need to use the debugger, though.

23
doc/src/Errors_messages.rst
View File

@ -2783,7 +2783,7 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
if this helps.
*Did not find all elements in MEAM library file*
The requested elements were not found in the MEAM file.
Some requested elements were not found in the MEAM file. Check spelling etc.
*Did not find fix shake partner info*
Could not find bond partners implied by fix shake command. This error
@ -3135,6 +3135,9 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
*Epsilon or sigma reference not set by pair style in ewald/n*
The pair style is not providing the needed epsilon or sigma values.
*Error in MEAM parameter file: keyword %s (further information)*
Self-explanatory. Check the parameter file.
*Error in vdw spline: inner radius > outer radius*
A pre-tabulated spline is invalid. Likely a problem with the
potential parameters.
@ -4611,7 +4614,7 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
*Incorrect format in COMB3 potential file*
Incorrect number of words per line in the potential file.
*Incorrect format in MEAM potential file*
*Incorrect format in MEAM library file*
Incorrect number of words per line in the potential file.
*Incorrect format in SNAP coefficient file*
@ -5669,6 +5672,9 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
A fix is referenced incorrectly or a fix that produces per-atom
values is used in an equal-style variable formula.
*Mismatched parameter in MEAM library file: z!=lat*
The coordination number and lattice do not match, check that consistent values are given.
*Mismatched variable in variable formula*
A variable is referenced incorrectly or an atom-style variable that
produces per-atom values is used in an equal-style variable
@ -5845,6 +5851,9 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
Cannot use the temper command with only one processor partition. Use
the -partition command-line option.
*Must not have multiple fixes change box parameter ...*
Self-explanatory.
*Must read Atoms before Angles*
The Atoms section of a data file must come before an Angles section.
@ -7764,6 +7773,9 @@ keyword to allow for additional bonds to be formed
*Too many atoms to dump sort*
Cannot sort when running with more than 2\^31 atoms.
*Too many elements extracted from MEAM library.*
Increase 'maxelt' in meam.h and recompile.
*Too many exponent bits for lookup table*
Table size specified via pair_modify command does not work with your
machine's floating point representation.
@ -7997,11 +8009,11 @@ keyword to allow for additional bonds to be formed
*Unknown unit_style*
Self-explanatory. Check the input script or data file.
*Unrecognized lattice type in MEAM file 1*
*Unrecognized lattice type in MEAM library file*
The lattice type in an entry of the MEAM library file is not
valid.
*Unrecognized lattice type in MEAM file 2*
*Unrecognized lattice type in MEAM parameter file*
The lattice type in an entry of the MEAM parameter file is not
valid.
@ -8017,6 +8029,9 @@ keyword to allow for additional bonds to be formed
*Unsupported order in kspace_style pppm/disp, pair_style %s*
Only pair styles with 1/r and 1/r\^6 dependence are currently supported.
*Unsupported parameter in MEAM library file*
Self-explanatory.
*Use cutoff keyword to set cutoff in single mode*
Mode is single so cutoff/multi keyword cannot be used.

1
doc/src/Howto.rst
View File

@ -16,6 +16,7 @@ Tutorials howto
:name: tutorials
:maxdepth: 1
Howto_cmake
Howto_github
Howto_pylammps
Howto_bash

6
doc/src/Howto_bash.rst
View File

@ -12,6 +12,10 @@ via apt-get and all files are accessible in both the Windows Explorer and your
Linux shell (bash). This avoids switching to a different operating system or
installing a virtual machine. Everything runs on Windows.
.. seealso::
You can find more detailed information at the `Windows Subsystem for Linux Installation Guide for Windows 10 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_.
Installing Bash on Windows
--------------------------
@ -103,7 +107,7 @@ needed for various LAMMPS features:
.. code-block:: bash
sudo apt install -y build-essential ccache gfortran openmpi-bin libopenmpi-dev libfftw3-dev libjpeg-dev libpng12-dev python-dev python-virtualenv libblas-dev liblapack-dev libhdf5-serial-dev hdf5-tools
sudo apt install -y build-essential ccache gfortran openmpi-bin libopenmpi-dev libfftw3-dev libjpeg-dev libpng-dev python-dev python-virtualenv libblas-dev liblapack-dev libhdf5-serial-dev hdf5-tools
Files in Ubuntu on Windows
^^^^^^^^^^^^^^^^^^^^^^^^^^

483
doc/src/Howto_cmake.rst Normal file
View File

@ -0,0 +1,483 @@
Using CMake with LAMMPS tutorial
================================
The support for building LAMMPS with CMake is a recent addition to
LAMMPS thanks to the efforts of Christoph Junghans (LANL) and Richard
Berger (Temple U). One of the key strengths of CMake is that it is not
tied to a specific platform or build system and thus generate the files
necessary to build and develop for different build systems and on
different platforms. Note, that this applies to the build system itself
not the LAMMPS code. In other words, without additional porting effort,
it is not possible - for example - to compile LAMMPS with Visual C++ on
Windows. The build system output can also include support files
necessary to program LAMMPS as a project in integrated development
environments (IDE) like Eclipse, Visual Studio, QtCreator, Xcode,
CodeBlocks, Kate and others.
A second important feature of CMake is, that it can detect and validate
available libraries, optimal settings, available support tools and so
on, so that by default LAMMPS will take advantage of available tools
without requiring to provide the details about how to enable/integrate
them.
The downside of this approach is, that there is some complexity
associated with running CMake itself and how to customize the building
of LAMMPS. This tutorial will show how to manage this through some
selected examples. Please see the chapter about :doc:`building LAMMPS
<Build>` for descriptions of specific flags and options for LAMMPS in
general and for specific packages.
CMake can be used through either the command-line interface (CLI)
program ``cmake`` (or ``cmake3``), a text mode interactive user
interface (TUI) program ``ccmake`` (or ``ccmake3``), or a graphical user
interface (GUI) program ``cmake-gui``. All of them are portable
software available on all supported platforms and can be used
interchangeably. The minimum supported CMake version is 3.10 (3.12 or
later is recommended).
All details about features and settings for CMake are in the `CMake
online documentation <https://cmake.org/documentation/>`_. We focus
below on the most important aspects with respect to compiling LAMMPS.
Prerequisites
-------------
This tutorial assumes that you are operating in a command-line environment
using a shell like Bash.
- Linux: any Terminal window will work
- MacOS X: launch the Terminal application.
- Windows 10: install and run the :doc:`Windows subsystem for Linux <Howto_bash>`
We also assume that you have downloaded and unpacked a recent LAMMPS source code package
or used Git to create a clone of the LAMMPS sources on your compilation machine.
You should change into the top level directory of the LAMMPS source tree all
paths mentioned in the tutorial are relative to that. Immediately after downloading
it should look like this:
.. code-block:: bash
$ ls
bench doc lib potentials README tools
cmake examples LICENSE python src
Build versus source directory
-----------------------------
When using CMake the build procedure is separated into multiple distinct phases:
#. **Configuration:** detect or define which features and settings
should be enable and used and how LAMMPS should be compiled
#. **Compilation:** generate and compile all necessary source files
and build libraries and executables.
#. **Installation:** copy selected files from the compilation into
your file system, so they can be used without having to keep the
source and build tree around.
The configuration and compilation of LAMMPS has to happen in a dedicated
*build directory* which must be different from the source directory.
Also the source directory (``src``) must remain pristine, so it is not
allowed to "install" packages using the traditional make process and
after an compilation attempt all created source files must be removed.
This can be achieved with ``make no-all purge``.
You can pick **any** folder outside the source tree. We recommend to
create a folder ``build`` in the top-level directory, or multiple
folders in case you want to have separate builds of LAMMPS with
different options (``build-parallel``, ``build-serial``) or with
different compilers (``build-gnu``, ``build-clang``, ``build-intel``)
and so on. All the auxiliary files created by one build process
(executable, object files, log files, etc) are stored in this directory
or sub-directories within it that CMake creates.
Running CMake
-------------
CLI version
^^^^^^^^^^^
In the (empty) ``build`` directory, we now run the command ``cmake
../cmake``, which will start the configuration phase and you will see
the progress of the configuration printed to the screen followed by a
summary of the enabled features, options and compiler settings. A typical
summary screen will look like this:
.. code-block::
$ cmake ../cmake/
-- The CXX compiler identification is GNU 8.2.0
-- Check for working CXX compiler: /opt/tools/gcc-8.2.0/bin/c++
-- Check for working CXX compiler: /opt/tools/gcc-8.2.0/bin/c++ - works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Found Git: /usr/bin/git (found version "2.25.2")
-- Running check for auto-generated files from make-based build system
-- Found MPI_CXX: /usr/lib64/mpich/lib/libmpicxx.so (found version "3.1")
-- Found MPI: TRUE (found version "3.1")
-- Looking for C++ include omp.h
-- Looking for C++ include omp.h - found
-- Found OpenMP_CXX: -fopenmp (found version "4.5")
-- Found OpenMP: TRUE (found version "4.5")
-- Found JPEG: /usr/lib64/libjpeg.so (found version "62")
-- Found PNG: /usr/lib64/libpng.so (found version "1.6.37")
-- Found ZLIB: /usr/lib64/libz.so (found version "1.2.11")
-- Found GZIP: /usr/bin/gzip
-- Found FFMPEG: /usr/bin/ffmpeg
-- Performing Test COMPILER_SUPPORTS-ffast-math
-- Performing Test COMPILER_SUPPORTS-ffast-math - Success
-- Performing Test COMPILER_SUPPORTS-march=native
-- Performing Test COMPILER_SUPPORTS-march=native - Success
-- Looking for C++ include cmath
-- Looking for C++ include cmath - found
-- Generating style_angle.h...
[...]
-- Generating lmpinstalledpkgs.h...
-- The following tools and libraries have been found and configured:
* Git
* MPI
* OpenMP
* JPEG
* PNG
* ZLIB
-- <<< Build configuration >>>
Build type: RelWithDebInfo
Install path: /home/akohlmey/.local
Generator: Unix Makefiles using /usr/bin/gmake
-- <<< Compilers and Flags: >>>
-- C++ Compiler: /opt/tools/gcc-8.2.0/bin/c++
Type: GNU
Version: 8.2.0
C++ Flags: -O2 -g -DNDEBUG
Defines: LAMMPS_SMALLBIG;LAMMPS_MEMALIGN=64;LAMMPS_JPEG;LAMMPS_PNG;LAMMPS_GZIP;LAMMPS_FFMPEG
Options: -ffast-math;-march=native
-- <<< Linker flags: >>>
-- Executable name: lmp
-- Static library flags:
-- <<< MPI flags >>>
-- MPI includes: /usr/include/mpich-x86_64
-- MPI libraries: /usr/lib64/mpich/lib/libmpicxx.so;/usr/lib64/mpich/lib/libmpi.so;
-- Configuring done
-- Generating done
-- Build files have been written to: /home/akohlmey/compile/lammps/build
The ``cmake`` command has one mandatory argument, and that is a folder
with either the file ``CMakeLists.txt`` or ``CMakeCache.txt``. The
``CMakeCache.txt`` file is created during the CMake configuration run
and contains all active settings, thus after a first run of CMake
all future runs in the build folder can use the folder ``.`` and CMake
will know where to find the CMake scripts and reload the settings
from the previous step. This means, that one can modify an existing
configuration by re-running CMake, but only needs to provide flags
indicating the desired change, everything else will be retained. One
can also mix compilation and configuration, i.e. start with a minimal
configuration and then, if needed, enable additional features and
recompile.
The steps above **will NOT compile the code**\ . The compilation can be
started in a portable fashion with ``cmake --build .``, or you use the
selected built tool, e.g. ``make``.
TUI version
^^^^^^^^^^^
For the text mode UI CMake program the basic principle is the same.
You start the command ``ccmake ../cmake`` in the ``build`` folder.
.. list-table::
* - .. figure:: JPG/ccmake-initial.png
:target: JPG/ccmake-initial.png
:align: center
Initial ``ccmake`` screen
- .. figure:: JPG/ccmake-config.png
:target: JPG/ccmake-config.png
:align: center
Configure output of ``ccmake``
- .. figure:: JPG/ccmake-options.png
:target: JPG/ccmake-options.png
:align: center
Options screen of ``ccmake``
This will show you the initial screen (left image) with the empty
configuration cache. Now you type the 'c' key to run the configuration
step. That will do a first configuration run and show the summary
(center image). You exit the summary screen with 'e' and see now the
main screen with detected options and settings. You can now make changes
by moving and down with the arrow keys of the keyboard and modify
entries. For on/off settings, the enter key will toggle the state.
For others, hitting enter will allow you to modify the value and
you commit the change by hitting the enter key again or cancel using
the escape key. All "new" settings will be marked with a star '\*'
and for as long as one setting is marked like this, you have to
re-run the configuration by hitting the 'c' key again, sometimes
multiple times unless the TUI shows the word "generate" next to the
letter 'g' and by hitting the 'g' key the build files will be written
to the folder and the TUI exits. You can quit without generating
build files by hitting 'q'.
GUI version
^^^^^^^^^^^
For the graphical CMake program the steps are similar to the TUI
version. You can type the command ``cmake-gui ../cmake`` in the
``build`` folder. In this case the path to the CMake script folder is
not required, it can also be entered from the GUI.
.. list-table::
* - .. figure:: JPG/cmake-gui-initial.png
:target: JPG/cmake-gui-initial.png
:align: center
Initial ``cmake-gui`` screen
- .. figure:: JPG/cmake-gui-popup.png
:target: JPG/cmake-gui-popup.png
:align: center
Generator selection in ``cmake-gui``
- .. figure:: JPG/cmake-gui-options.png
:target: JPG/cmake-gui-options.png
:align: center
Options screen of ``cmake-gui``
Again, you start with an empty configuration cache (left image) and need
to start the configuration step. For the very first configuration in a
folder, you will have a pop-up dialog (center image) asking to select
the desired build tool and some configuration settings (stick with the
default) and then you get the option screen with all new settings
highlighted in red. You can modify them (or not) and click on the
"configure" button again until satisfied and click on the "generate"
button to write out the build files. You can exit the GUI from the
"File" menu or hit "ctrl-q".
Setting options
---------------
Options that enable, disable or modify settings are modified by setting
the value of CMake variables. This is done on the command line with the
*-D* flag in the format ``-D VARIABLE=value``, e.g. ``-D
CMAKE_BUILD_TYPE=Release`` or ``-D BUILD_MPI=on``. There is one quirk:
when used before the CMake directory, there may be a space between the
*-D* flag and the variable, after it must not be. Such CMake variables
can have boolean values (on/off, yes/no, or 1/0 are all valid) or are
strings representing a choice, or a path, or are free format. If the
string would contain whitespace, it must be put in quotes, for example
``-D CMAKE_TUNE_FLAGS="-ftree-vectorize -ffast-math"``.
CMake variables fall into two categories: 1) common CMake variables that
are used by default for any CMake configuration setup and 2) project
specific variables, i.e. settings that are specific for LAMMPS.
Also CMake variables can be flagged as *advanced*, which means they are
not shown in the text mode or graphical CMake program in the overview
of all settings by default, but only when explicitly requested (by hitting
the 't' key or clicking on the 'Advanced' check-box).
Some common CMake variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Variable
- Description
* - ``CMAKE_INSTALL_PREFIX``
- root directory of install location for ``make install`` (default: ``$HOME/.local``)
* - ``CMAKE_BUILD_TYPE``
- controls compilation options:
one of ``RelWithDebInfo`` (default), ``Release``, ``Debug``, ``MinSizeRel``
* - ``BUILD_SHARED_LIBS``
- if set to ``on`` build the LAMMPS library as shared library (default: ``off``)
* - ``CMAKE_MAKE_PROGRAM``
- name/path of the compilation command (default depends on *-G* option, usually ``make``)
* - ``CMAKE_VERBOSE_MAKEFILE``
- if set to ``on`` echo commands while executing during build (default: ``off``)
* - ``CMAKE_C_COMPILER``
- C compiler to be used for compilation (default: system specific, ``gcc`` on Linux)
* - ``CMAKE_CXX_COMPILER``
- C++ compiler to be used for compilation (default: system specific, ``g++`` on Linux)
* - ``CMAKE_Fortran_COMPILER``
- Fortran compiler to be used for compilation (default: system specific, ``gfortran`` on Linux)
* - ``CXX_COMPILER_LAUNCHER``
- tool to launch the C++ compiler, e.g. ``ccache`` or ``distcc`` for faster compilation (default: empty)
Some common LAMMPS specific variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
* - Variable
- Description
* - ``BUILD_MPI``
- build LAMMPS with MPI support (default: ``on`` if a working MPI available, else ``off``)
* - ``BUILD_OMP``
- build LAMMPS with OpenMP support (default: ``on`` if compiler supports OpenMP fully, else ``off``)
* - ``BUILD_TOOLS``
- compile some additional executables from the ``tools`` folder (default: ``off``)
* - ``BUILD_DOC``
- include building the HTML format documentation for packaging/installing (default: ``off``)
* - ``CMAKE_TUNE_FLAGS``
- common compiler flags, for optimization or instrumentation (default: compiler specific)
* - ``LAMMPS_MACHINE``
- when set to ``name`` the LAMMPS executable and library will be called ``lmp_name`` and ``liblammps_name.a``
* - ``LAMMPS_EXCEPTIONS``
- when set to ``on`` errors will throw a C++ exception instead of aborting (default: ``off``)
* - ``FFT``
- select which FFT library to use: ``FFTW3``, ``MKL``, ``KISS`` (default, unless FFTW3 is found)
* - ``FFT_SINGLE``
- select whether to use single precision FFTs (default: ``off``)
* - ``WITH_JPEG``
- whether to support JPEG format in :doc:`dump image <dump_image>` (default: ``on`` if found)
* - ``WITH_PNG``
- whether to support PNG format in :doc:`dump image <dump_image>` (default: ``on`` if found)
* - ``WITH_GZIP``
- whether to support reading and writing compressed files (default: ``on`` if found)
* - ``WITH_FFMPEG``
- whether to support generating movies with :doc:`dump movie <dump_image>` (default: ``on`` if found)
Enabling or disabling LAMMPS packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The LAMMPS software is organized into a common core that is always
included and a large number of :doc:`add-on packages <Packages>` that
have to be enabled to be included into a LAMMPS executable. Packages
are enabled through setting variables of the kind ``PKG_<NAME>`` to
``on`` and disabled by setting them to ``off`` (or using ``yes``,
``no``, ``1``, ``0`` correspondingly). ``<NAME>`` has to be replaced by
the name of the package, e.g. ``MOLECULE`` or ``USER-MISC``.
Using presets
-------------
Since LAMMPS has a lot of optional features and packages, specifying
them all on the command line can be tedious. Or when selecting a
different compiler toolchain, multiple options have to be changed
consistently and that is rather error prone. Or when enabling certain
packages, they require consistent settings to be operated in a
particular mode. For this purpose, we are providing a selection of
"preset files" for CMake in the folder ``cmake/presets``. They
represent a way to pre-load or override the CMake configuration cache by
setting or changing CMake variables. Preset files are loaded using the
*-C* command line flag. You can combine loading multiple preset files or
change some variables later with additional *-D* flags. A few examples:
.. code-block:: bash
cmake -C ../cmake/preset/minimal.cmake -D PKG_MISC=on ../cmake
cmake -C ../cmake/preset/clang.cmake -C ../cmake/preset/most.cmake ../cmake
cmake -C ../cmake/preset/minimal.cmake -D BUILD_MPI=off ../cmake
The first command will install the packages ``KSPACE``, ``MANYBODY``,
``MOLECULE``, ``RIGID`` and ``MISC``; the first four from the preset
file and the fifth from the explicit variable definition. The second
command will first switch the compiler toolchain to use the Clang
compilers and install a large number of packages that are not depending
on any special external libraries or tools and are not very unusual.
The third command will enable the first four packages like above and
then enforce compiling LAMMPS as a serial program (using the MPI STUBS
library).
It is also possible to do this incrementally.
.. code-block:: bash
cmake -C ../cmake/preset/minimal.cmake ../cmake
cmake -D PKG_MISC=on .
will achieve the same configuration like in the first example above. In
this scenario it is particularly convenient to do the second
configuration step using either the text mode or graphical user
interface (``ccmake`` or ``cmake-gui``).
Compilation and build targets
-----------------------------
The actual compilation will be started by running the selected build
command (on Linux this is by default ``make``, see below how to select
alternatives). You can also use the portable command ``cmake --build .``
which will adapt to whatever the selected build command is.
This is particularly convenient, if you have set a custom build command
via the ``CMAKE_MAKE_PROGRAM`` variable.
When calling the build program, you can also select which "target" is to
be build through appending the name of the target to the build command.
Example: ``cmake --build . all``. The following abstract targets are available:
.. list-table::
:header-rows: 1
* - Target
- Description
* - ``all``
- build "everything" (default)
* - ``lammps``
- build the LAMMPS library and executable
* - ``doc``
- build the HTML documentation (if configured)
* - ``install``
- install all target files into folders in ``CMAKE_INSTALL_PREFIX``
* - ``test``
- run some simple tests (if configured with ``-D ENABLE_TESTING=on``)
* - ``clean``
- remove all generated files
Choosing generators
-------------------
While CMake usually defaults to creating makefiles to compile software
with the ``make`` program, it supports multiple alternate build tools
(e.g. ``ninja-build`` which tends to be faster and more efficient in
parallelizing builds than ``make``) and can generate project files for
integrated development environments (IDEs) like VisualStudio, Eclipse or
CodeBlocks. This is specific to how the local CMake version was
configured and compiled. The list of available options can be seen at
the end of the output of ``cmake --help``. Example on Fedora 31 this is:
.. code-block::
Generators
The following generators are available on this platform (* marks default):
* Unix Makefiles = Generates standard UNIX makefiles.
Green Hills MULTI = Generates Green Hills MULTI files
(experimental, work-in-progress).
Ninja = Generates build.ninja files.
Ninja Multi-Config = Generates build-<Config>.ninja files.
Watcom WMake = Generates Watcom WMake makefiles.
CodeBlocks - Ninja = Generates CodeBlocks project files.
CodeBlocks - Unix Makefiles = Generates CodeBlocks project files.
CodeLite - Ninja = Generates CodeLite project files.
CodeLite - Unix Makefiles = Generates CodeLite project files.
Sublime Text 2 - Ninja = Generates Sublime Text 2 project files.
Sublime Text 2 - Unix Makefiles
= Generates Sublime Text 2 project files.
Kate - Ninja = Generates Kate project files.
Kate - Unix Makefiles = Generates Kate project files.
Eclipse CDT4 - Ninja = Generates Eclipse CDT 4.0 project files.
Eclipse CDT4 - Unix Makefiles= Generates Eclipse CDT 4.0 project files.
Below is a screenshot of using the CodeBlocks IDE with the ninja build tool
after running CMake as follows:
.. code-block:: bash
cmake -G 'CodeBlocks - Ninja' ../cmake/presets/most.cmake ../cmake/
.. image:: JPG/cmake-codeblocks.png
:align: center

4
doc/src/Install_mac.rst
View File

@ -34,9 +34,9 @@ install the `openkim-models` package
% brew install openkim-models
If you have problems with the installation you can post issues to
`this link <homebrew_>`_.
`this link <https://github.com/Homebrew/homebrew-core/issues>`_.
.. _homebrew: https://github.com/Homebrew/homebrew-core/issues
.. _homebrew: https://brew.sh
Thanks to Derek Thomas (derekt at cello.t.u-tokyo.ac.jp) for setting
up the Homebrew capability.

0
doc/src/JPG/bow_tutorial_01.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 32 KiB

After

Width:  |  Height:  |  Size: 32 KiB

0
doc/src/JPG/bow_tutorial_01_small.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 15 KiB

0
doc/src/JPG/bow_tutorial_02.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 41 KiB

After

Width:  |  Height:  |  Size: 41 KiB

0
doc/src/JPG/bow_tutorial_02_small.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

0
doc/src/JPG/bow_tutorial_03.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 42 KiB

After

Width:  |  Height:  |  Size: 42 KiB

0
doc/src/JPG/bow_tutorial_03_small.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 20 KiB

0
doc/src/JPG/bow_tutorial_04.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 54 KiB

After

Width:  |  Height:  |  Size: 54 KiB

0
doc/src/JPG/bow_tutorial_04_small.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 21 KiB

0
doc/src/JPG/bow_tutorial_05.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

0
doc/src/JPG/bow_tutorial_06.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

0
doc/src/JPG/bow_tutorial_07.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.7 KiB

After

Width:  |  Height:  |  Size: 9.7 KiB

0
doc/src/JPG/bow_tutorial_08.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 24 KiB

After

Width:  |  Height:  |  Size: 24 KiB

0
doc/src/JPG/bow_tutorial_09.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 18 KiB

0
doc/src/JPG/bow_tutorial_10.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.6 KiB

After

Width:  |  Height:  |  Size: 7.6 KiB

BIN
doc/src/JPG/ccmake-config.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
doc/src/JPG/ccmake-initial.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
doc/src/JPG/ccmake-options.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
doc/src/JPG/cmake-codeblocks.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 129 KiB

BIN
doc/src/JPG/cmake-gui-initial.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 64 KiB

BIN
doc/src/JPG/cmake-gui-options.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 136 KiB

BIN
doc/src/JPG/cmake-gui-popup.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

0
doc/src/JPG/offload_knc.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

0
doc/src/JPG/rhodo_staggered.jpg Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 41 KiB

After

Width:  |  Height:  |  Size: 41 KiB

0
doc/src/JPG/saed_ewald_intersect.jpg Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 110 KiB

After

Width:  |  Height:  |  Size: 110 KiB

0
doc/src/JPG/saed_ewald_intersect_small.jpg Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 40 KiB

0
doc/src/JPG/saed_mesh.jpg Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 108 KiB

After

Width:  |  Height:  |  Size: 108 KiB

0
doc/src/JPG/saed_mesh_small.jpg Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 42 KiB

After

Width:  |  Height:  |  Size: 42 KiB

0
doc/src/JPG/user_intel.png Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 19 KiB

0
doc/src/JPG/xrd_mesh.jpg Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 118 KiB

After

Width:  |  Height:  |  Size: 118 KiB

0
doc/src/JPG/xrd_mesh_small.jpg Executable file → Normal file
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 45 KiB

After

Width:  |  Height:  |  Size: 45 KiB

28
doc/src/Packages_details.rst
View File

@ -365,12 +365,17 @@ KIM package
This package contains a set of commands that serve as a wrapper on the
`Open Knowledgebase of Interatomic Models (OpenKIM) <https://openkim.org>`_
repository of interatomic models (IMs)
enabling compatible ones to be used in LAMMPS simulations.
This includes :doc:`kim_init and kim_interactions <kim_commands>`
commands to select, initialize and instantiate the IM, and a
:doc:`kim_query <kim_commands>` command to perform web queries
for material property predictions of OpenKIM IMs.
repository of interatomic models (IMs) enabling compatible ones to be used in
LAMMPS simulations.
This includes :doc:`kim_init <kim_commands>`, and
:doc:`kim_interactions <kim_commands>` commands to select, initialize and
instantiate the IM, a :doc:`kim_query <kim_commands>` command to perform web
queries for material property predictions of OpenKIM IMs, a
:doc:`kim_param <kim_commands>` command to access KIM Model Parameters from
LAMMPS, and a :doc:`kim_property <kim_commands>` command to write material
properties computed in LAMMPS to standard KIM property instance format.
Support for KIM IMs that conform to the
`KIM Application Programming Interface (API) <https://openkim.org/kim-api/>`_
is provided by the :doc:`pair_style kim <pair_kim>` command.
@ -392,13 +397,16 @@ The KIM project is led by Ellad Tadmor and Ryan Elliott (U Minnesota)
and is funded by the `National Science Foundation <https://www.nsf.gov/>`_.
**Authors:** Ryan Elliott (U Minnesota) is the main developer for the KIM
API and the *pair_style kim* command. Axel Kohlmeyer (Temple U) and
Ellad Tadmor (U Minnesota) contributed to the :doc:`kim_commands <kim_commands>`
interface in close collaboration with Ryan Elliott.
API and the *pair_style kim* command. Yaser Afshar (U Minnesota),
Axel Kohlmeyer (Temple U), Ellad Tadmor (U Minnesota), and
Daniel Karls (U Minnesota) contributed to the
:doc:`kim_commands <kim_commands>` interface in close collaboration with
Ryan Elliott.
**Install:**
This package has :ref:`specific installation instructions <kim>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <kim>` on the
:doc:`Build extras <Build_extras>` doc page.
**Supporting info:**

7
doc/src/Python_shlib.rst
View File

@ -1,6 +1,8 @@
Build LAMMPS as a shared library
================================
.. TODO this is mostly redundant and should be addressed in the 'progguide' branch if it has not already
Build LAMMPS as a shared library using make
-------------------------------------------
@ -14,7 +16,7 @@ From the src directory, type
.. code-block:: bash
make foo mode=shlib
make foo mode=shared
where foo is the machine target name, such as mpi or serial.
This should create the file liblammps_foo.so in the src directory, as
@ -39,7 +41,6 @@ shared library:
.. code-block:: bash
-D BUILD_LIB=on # enable building LAMMPS as a library
-D BUILD_SHARED_LIBS=on # enable building of LAMMPS shared library (both options are needed!)
What this does is create a liblammps.so which contains the majority of LAMMPS
@ -59,7 +60,7 @@ CMAKE_INSTALL_PREFIX.
# build library
mkdir build
cd build
cmake -D PKG_PYTHON=on -D BUILD_LIB=on -D BUILD_SHARED_LIBS=on -D CMAKE_INSTALL_PREFIX=$VIRTUAL_ENV ../cmake
cmake -D PKG_PYTHON=on -D BUILD_SHARED_LIBS=on -D CMAKE_INSTALL_PREFIX=$VIRTUAL_ENV ../cmake
make -j 4
# install into prefix

2
doc/src/Speed_compare.rst
View File

@ -87,7 +87,7 @@ section below for examples where this has been done.
* The GPU package requires neighbor lists to be built on the CPU when using
exclusion lists, or a triclinic simulation box.
* The GPU package can be compiled for CUDA or OpenCL and thus supports
both, Nvidia and AMD GPUs well. On Nvidia hardware, using CUDA is typically
both, NVIDIA and AMD GPUs well. On NVIDIA hardware, using CUDA is typically
resulting in equal or better performance over OpenCL.
* OpenCL in the GPU package does theoretically also support Intel CPUs or
Intel Xeon Phi, but the native support for those in KOKKOS (or USER-INTEL)

2
doc/src/Speed_kokkos.rst
View File

@ -38,7 +38,7 @@ compatible with specific hardware.
.. note::
To build with Kokkos support for NVIDIA GPUs, NVIDIA CUDA
software version 7.5 or later must be installed on your system. See
software version 9.0 or later must be installed on your system. See
the discussion for the :doc:`GPU package <Speed_gpu>` for details of how
to check and do this.

2
doc/src/Speed_packages.rst
View File

@ -20,7 +20,7 @@ standard or user packages:
+-----------------------------------------+-------------------------------------------------------+
| :doc:`USER-INTEL Package <Speed_intel>` | for Intel CPUs and Intel Xeon Phi |
+-----------------------------------------+-------------------------------------------------------+
| :doc:`KOKKOS Package <Speed_kokkos>` | for Nvidia GPUs, Intel Xeon Phi, and OpenMP threading |
| :doc:`KOKKOS Package <Speed_kokkos>` | for NVIDIA GPUs, Intel Xeon Phi, and OpenMP threading |
+-----------------------------------------+-------------------------------------------------------+
| :doc:`USER-OMP Package <Speed_omp>` | for OpenMP threading and generic CPU optimizations |
+-----------------------------------------+-------------------------------------------------------+

34
doc/src/balance.rst
View File

@ -175,23 +175,27 @@ a logical 3d grid of processors. They operate by changing the cutting
planes (or lines) between processors in 3d (or 2d), to adjust the
volume (area in 2d) assigned to each processor, as in the following 2d
diagram where processor sub-domains are shown and particles are
colored by the processor that owns them. The leftmost diagram is the
default partitioning of the simulation box across processors (one
sub-box for each of 16 processors); the middle diagram is after a
"grid" method has been applied.
colored by the processor that owns them.
.. image:: JPG/balance_uniform_small.jpg
:target: JPG/balance_uniform.jpg
.. image:: JPG/balance_nonuniform_small.jpg
:target: JPG/balance_nonuniform.jpg
.. image:: JPG/balance_rcb_small.jpg
:target: JPG/balance_rcb.jpg
.. list-table::
The *rcb* style is a "tiling" method which does not produce a logical
3d grid of processors. Rather it tiles the simulation domain with
rectangular sub-boxes of varying size and shape in an irregular
fashion so as to have equal numbers of particles (or weight) in each
sub-box, as in the rightmost diagram above.
* - .. figure:: JPG/balance_uniform_small.jpg
:target: JPG/balance_uniform.jpg
- .. figure:: JPG/balance_nonuniform_small.jpg
:target: JPG/balance_nonuniform.jpg
- .. figure:: JPG/balance_rcb_small.jpg
:target: JPG/balance_rcb.jpg
The leftmost diagram is the default partitioning of the simulation box
across processors (one sub-box for each of 16 processors); the middle
diagram is after a "grid" method has been applied. The *rcb* style is a
"tiling" method which does not produce a logical 3d grid of processors.
Rather it tiles the simulation domain with rectangular sub-boxes of
varying size and shape in an irregular fashion so as to have equal
numbers of particles (or weight) in each sub-box, as in the rightmost
diagram above.
The "grid" methods can be used with either of the
:doc:`comm_style <comm_style>` command options, *brick* or *tiled*\ . The

2
doc/src/bond_oxdna.rst
View File

@ -32,7 +32,7 @@ Examples
bond_coeff * 2.0 0.25 0.7564
bond_style oxrna2/fene
bond_coeff \* 2.0 0.25 0.76107
bond_coeff * 2.0 0.25 0.76107
Description
"""""""""""

43
doc/src/fix_adapt.rst
View File

@ -14,7 +14,7 @@ Syntax
* adapt = style name of this fix command
* N = adapt simulation settings every this many timesteps
* one or more attribute/arg pairs may be appended
* attribute = *pair* or *kspace* or *atom*
* attribute = *pair* or *bond* or *kspace* or *atom*
.. parsed-literal::
@ -86,8 +86,8 @@ the end of a simulation. Even if *reset* is specified as *yes*\ , a
restart file written during a simulation will contain the modified
settings.
If the *scale* keyword is set to *no*\ , then the value the parameter is
set to will be whatever the variable generates. If the *scale*
If the *scale* keyword is set to *no*\ , then the value of the altered
parameter will be whatever the variable generates. If the *scale*
keyword is set to *yes*\ , then the value of the altered parameter will
be the initial value of that parameter multiplied by whatever the
variable generates. I.e. the variable is now a "scale factor" applied
@ -288,11 +288,19 @@ Currently *bond* does not support bond_style hybrid nor bond_style
hybrid/overlay as bond styles. The only bonds that currently are
working with fix_adapt are
+---------------------------------+-------+------------+
| :doc:`gromos <bond_gromos>` | k, r0 | type bonds |
+---------------------------------+-------+------------+
| :doc:`harmonic <bond_harmonic>` | k,r0 | type bonds |
+---------------------------------+-------+------------+
+------------------------------------+-------+------------+
| :doc:`class2 <bond_class2>` | r0 | type bonds |
+------------------------------------+-------+------------+
| :doc:`fene <bond_fene>` | k, r0 | type bonds |
+------------------------------------+-------+------------+
| :doc:`gromos <bond_gromos>` | k, r0 | type bonds |
+------------------------------------+-------+------------+
| :doc:`harmonic <bond_harmonic>` | k,r0 | type bonds |
+------------------------------------+-------+------------+
| :doc:`morse <bond_morse>` | r0 | type bonds |
+------------------------------------+-------+------------+
| :doc:`nonlinear <bond_nonlinear>` | r0 | type bonds |
+------------------------------------+-------+------------+
----------
@ -311,26 +319,23 @@ The *atom* keyword enables various atom properties to be changed. The
current list of atom parameters that can be varied by this fix:
* charge = charge on particle
* diameter = diameter of particle
* diameter, or, diameter/disc = diameter of particle
The *v_name* argument of the *atom* keyword is the name of an
:doc:`equal-style variable <variable>` which will be evaluated each time
this fix is invoked to set the parameter to a new value. It should be
specified as v_name, where name is the variable name. See the
this fix is invoked to set, or scale the parameter to a new value.
It should be specified as v_name, where name is the variable name. See the
discussion above describing the formulas associated with equal-style
variables. The new value is assigned to the corresponding attribute
for all atoms in the fix group.
.. note::
The *atom* keyword works this way whether the *scale* keyword is
set to *no* or *yes*\ . I.e. the use of scale yes is not yet supported
by the *atom* keyword.
If the atom parameter is *diameter* and per-atom density and per-atom
mass are defined for particles (e.g. :doc:`atom_style granular <atom_style>`), then the mass of each particle is also
changed when the diameter changes (density is assumed to stay
constant).
changed when the diameter changes. The mass is set from the particle volume
for 3d systems (density is assumed to stay constant). For 2d, the default is
for LAMMPS to model particles with a radius attribute as spheres.
However, if the atom parameter is *diameter/disc*, then the mass is
set from the particle area (the density is assumed to be in mass/distance^2 units).
For example, these commands would shrink the diameter of all granular
particles in the "center" group from 1.0 to 0.1 in a linear fashion

37
doc/src/fix_balance.rst
View File

@ -154,28 +154,27 @@ of processors. It operates by changing the cutting planes (or lines)
between processors in 3d (or 2d), to adjust the volume (area in 2d)
assigned to each processor, as in the following 2d diagram where
processor sub-domains are shown and atoms are colored by the processor
that owns them. The leftmost diagram is the default partitioning of
the simulation box across processors (one sub-box for each of 16
processors); the middle diagram is after a "grid" method has been
applied.
that owns them.
.. |bal_uni| image:: JPG/balance_uniform_small.jpg
:target: JPG/balance_uniform.jpg
:width: 31%
.. |bal_non| image:: JPG/balance_nonuniform_small.jpg
:target: JPG/balance_nonuniform.jpg
:width: 31%
.. |bal_rcb| image:: JPG/balance_rcb_small.jpg
:target: JPG/balance_rcb.jpg
:width: 31%
.. list-table::
|bal_uni| |bal_non| |bal_rcb|
* - .. figure:: JPG/balance_uniform_small.jpg
:target: JPG/balance_uniform.jpg
The *rcb* style is a "tiling" method which does not produce a logical
3d grid of processors. Rather it tiles the simulation domain with
rectangular sub-boxes of varying size and shape in an irregular
fashion so as to have equal numbers of particles (or weight) in each
sub-box, as in the rightmost diagram above.
- .. figure:: JPG/balance_nonuniform_small.jpg
:target: JPG/balance_nonuniform.jpg
- .. figure:: JPG/balance_rcb_small.jpg
:target: JPG/balance_rcb.jpg
The leftmost diagram is the default partitioning of the simulation box
across processors (one sub-box for each of 16 processors); the middle
diagram is after a "grid" method has been applied. The *rcb* style is a
"tiling" method which does not produce a logical 3d grid of processors.
Rather it tiles the simulation domain with rectangular sub-boxes of
varying size and shape in an irregular fashion so as to have equal
numbers of particles (or weight) in each sub-box, as in the rightmost
diagram above.
The "grid" methods can be used with either of the
:doc:`comm_style <comm_style>` command options, *brick* or *tiled*\ . The

6
doc/src/fix_precession_spin.rst
View File

@ -76,6 +76,7 @@ function for the same parameters.
.. image:: JPG/zeeman_langevin.jpg
:align: center
:width: 600
The temperature effects are accounted for by connecting the spin
:math:`i` to a thermal bath using a Langevin thermostat (see
@ -154,6 +155,11 @@ The *precession/spin* style is part of the SPIN package. This style
is only enabled if LAMMPS was built with this package, and if the
atom_style "spin" was declared. See the :doc:`Build package <Build_package>` doc page for more info.
The *precession/spin* style can only be declared once. If more
than one precession type (for example combining an anisotropy and a Zeeman interactions)
has to be declared, they have to be chained in the same command
line (as shown in the examples above).
Related commands
""""""""""""""""

548
doc/src/kim_commands.rst
View File

@ -1,16 +1,19 @@
.. index:: kim_init, kim_interactions, kim_query, kim_param
.. index:: kim_init, kim_interactions, kim_query, kim_param, kim_property
kim_init command
=================
:ref:`kim_init<kim_init command>` command
=========================================
kim_interactions command
=========================
:ref:`kim_interactions<kim_interactions command>` command
=========================================================
kim_query command
==================
:ref:`kim_query<kim_query command>` command
===========================================
kim_param command
==================
:ref:`kim_param<kim_param command>` command
===========================================
:ref:`kim_property<kim_property command>` command
=================================================
Syntax
""""""
@ -22,6 +25,11 @@ Syntax
kim_query variable formatarg query_function queryargs
kim_param get param_name index_range variables formatarg
kim_param set param_name index_range values
kim_property create instance_id property_id
kim_property modify instance_id key key_name key_name_key key_name_value
kim_property remove instance_id key key_name
kim_property destroy instance_id
kim_property dump file
.. _formatarg_options:
@ -48,6 +56,12 @@ Syntax
* param_name = name of a KIM portable model parameter
* index_range = KIM portable model parameter index range (an integer for a single element, or pair of integers separated by a colon for a range of elements)
* values = new value(s) to replace the current value(s) of a KIM portable model parameter
* instance_id = a positive integer identifying the KIM property instance
* property_id = identifier of a `KIM Property Definition <https://openkim.org/properties>`_, which can be (1) a property short name, (2) the full unique ID of the property (including the contributor and date), (3) a file name corresponding to a local property definition file
* key_name = one of the keys belonging to the specified KIM property definition
* key_name_key = a key belonging to a key-value pair (standardized in the `KIM Properties Framework <https://openkim.org/doc/schema/properties-framework>`__)
* key_name_value = value to be associated with a key_name_key in a key-value pair
* file = name of a file to write the currently defined set of KIM property instances to
Examples
""""""""
@ -64,6 +78,15 @@ Examples
kim_query a0 get_lattice_constant_cubic crystal=["fcc"] species=["Al"] units=["angstrom"]
kim_param get gamma 1 varGamma
kim_param set gamma 1 3.0
kim_property create 1 atomic-mass
kim_property modify 1 key mass source-value 26.98154
kim_property modify 1 key species source-value Al
kim_property remove 1 key species
kim_property destroy 1
kim_property dump results.edn
.. _kim_description:
Description
"""""""""""
@ -157,11 +180,10 @@ See the `current list of KIM PMs and SMs archived in OpenKIM <https://openkim.or
This list is sorted by species and can be filtered to display only
IMs for certain species combinations.
See `Obtaining KIM Models <http://openkim.org/doc/usage/obtaining-models>`_ to
learn how to install a pre-build binary of the OpenKIM Repository of Models.
See `Obtaining KIM Models <https://openkim.org/doc/usage/obtaining-models>`_ to
learn how to install a pre-built binary of the OpenKIM Repository of Models.
.. note::
It is also possible to locally install IMs not archived in OpenKIM,
in which case their names do not have to conform to the KIM ID format.
@ -169,15 +191,17 @@ Using OpenKIM IMs with LAMMPS
-----------------------------
Two commands are employed when using OpenKIM IMs, one to select the
IM and perform necessary initialization (*kim_init*), and the second
IM and perform necessary initialization (\ *kim_init*\ ), and the second
to set up the IM for use by executing any necessary LAMMPS commands
(*kim_interactions*). Both are required.
(\ *kim_interactions*\ ). Both are required.
See the *examples/kim* directory for example input scripts that use KIM PMs
and KIM SMs.
.. _kim_init command:
OpenKIM IM Initialization (*kim_init*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The *kim_init* mode command must be issued **before**
the simulation box is created (normally at the top of the file).
@ -219,7 +243,7 @@ either match the required units of the IM or the IM must be able
to adjust its units to match. (The latter is only possible with some KIM PMs;
SMs can never adjust their units.) If a match is possible, the LAMMPS
:doc:`units <units>` command is called to set the units to
*user_units*. If the match fails, the simulation is terminated with
*user_units*\ . If the match fails, the simulation is terminated with
an error.
Here is an example of a LAMMPS script to compute the cohesive energy
@ -324,8 +348,10 @@ be done to convert the box and all atomic positions to the correct units:
all appropriate places in the input script. It is up to the user to do this
correctly.
.. _kim_interactions command:
OpenKIM IM Execution (*kim_interactions*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The second and final step in using an OpenKIM IM is to execute the
*kim_interactions* command. This command must be preceded by a *kim_init*
@ -399,12 +425,17 @@ the *kim_interactions* command executes the following LAMMPS input commands:
pair_coeff * * ffield.reax.rdx C H N O
fix reaxqeq all qeq/reax 1 0.0 10.0 1.0e-6 param.qeq
Note that the files *lmp_control*, *ffield.reax.rdx* and *param.qeq*
are specific to the Strachan et al. (2003) ReaxFF parameterization
and are archived as part of the SM package in OpenKIM.
Note also that parameters like cutoff radii and charge tolerances,
which have an effect on IM predictions, are also included in the
SM definition ensuring reproducibility.
.. note::
The files *lmp_control*, *ffield.reax.rdx* and *param.qeq*
are specific to the Strachan et al. (2003) ReaxFF parameterization
and are archived as part of the SM package in OpenKIM.
.. note::
Parameters like cutoff radii and charge tolerances,
which have an effect on IM predictions, are also included in the
SM definition ensuring reproducibility.
.. note::
@ -414,8 +445,10 @@ SM definition ensuring reproducibility.
bond_coeff, fixes related to charge equilibration, etc.) should normally
not appear in the input script.
.. _kim_query command:
Using OpenKIM Web Queries in LAMMPS (*kim_query*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The *kim_query* command performs a web query to retrieve the predictions
of an IM set by *kim_init* for material properties archived in
@ -427,6 +460,7 @@ of an IM set by *kim_init* for material properties archived in
The syntax for the *kim_query* command is as follows:
.. code-block:: LAMMPS
kim_query variable formatarg query_function queryargs
@ -442,7 +476,7 @@ individual variables of the form *prefix_I*, where *prefix* is set to the
*kim_query* *variable* argument and *I* ranges from 1 to the number of
returned values. The number and order of the returned values is determined
by the type of query performed. (Note that the "explicit" setting of
*formatarg* is not supported by *kim_query*.)
*formatarg* is not supported by *kim_query*\ .)
.. note::
@ -452,7 +486,7 @@ by the type of query performed. (Note that the "explicit" setting of
cases will generate an error.
The second required argument *query_function* is the name of the
query function to be called (e.g. *get_lattice_constant_cubic*).
query function to be called (e.g. *get_lattice_constant_cubic*\ ).
All following :doc:`arguments <Commands_parse>` are parameters handed over to
the web query in the format *keyword=value*\ , where *value* is always
an array of one or more comma-separated items in brackets.
@ -466,7 +500,7 @@ is available on the OpenKIM webpage at
All query functions require the *model* keyword, which identifies
the IM whose predictions are being queried. This keyword is automatically
generated by *kim_query* based on the IM set in *kim_init* and must not
be specified as an argument to *kim_query*.
be specified as an argument to *kim_query*\ .
.. note::
@ -475,11 +509,11 @@ is available on the OpenKIM webpage at
used to compute this property. In cases where there are multiple
methods in OpenKIM for computing a property, a *method* keyword can
be provided to select the method of choice. See the
`query documentation <https://openkim.org/doc/repository/kim-query>`_
to see which methods are available for a given *query function*\ .
`query documentation <https://openkim.org/doc/usage/kim-query>`_
to see which methods are available for a given *query_function*\ .
*kim_query* Usage Examples and Further Clarifications
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The data obtained by *kim_query* commands can be used as part of the setup
or analysis phases of LAMMPS simulations. Some examples are given below.
@ -502,10 +536,12 @@ crystal. By using *kim_query*, the user is saved the trouble and possible
error of tracking this value down, or of having to perform an energy
minimization to find the equilibrium lattice constant.
Note that in *unit_conversion_mode* the results obtained from a
*kim_query* would need to be converted to the appropriate units system.
For example, in the above script, the lattice command would need to be
changed to: "lattice fcc ${a0}\*${_u_distance}".
.. note::
In *unit_conversion_mode* the results obtained from a
*kim_query* would need to be converted to the appropriate units system.
For example, in the above script, the lattice command would need to be
changed to: "lattice fcc ${a0}*${_u_distance}".
**Define an equilibrium hcp crystal**
@ -524,7 +560,7 @@ changed to: "lattice fcc ${a0}\*${_u_distance}".
In this case the *kim_query* returns two arguments (since the hexagonal
close packed (hcp) structure has two independent lattice constants).
The *formatarg* keyword "split" places the two values into
the variables *latconst_1* and *latconst_2*. (These variables are
the variables *latconst_1* and *latconst_2*\ . (These variables are
created if they do not already exist.) For convenience the variables
*a0* and *c0* are created in order to make the remainder of the
input script more readable.
@ -555,9 +591,9 @@ potential.
If no tolerance is passed a default value is used. If multiple results
are returned (indicating that the tolerance is too large), *kim_query*
will return an error. See the
`query documentation <https://openkim.org/doc/repository/kim-query>`_
`query documentation <https://openkim.org/doc/usage/kim-query>`_
to see which numerical arguments and tolerances are available for a
given *query function*\ .
given *query_function*\ .
**Compute defect formation energy**
@ -586,8 +622,10 @@ ideal fcc cohesive energy of the atoms in the system obtained from
from these programs are queried is tracked. No other information about
the nature of the query or its source is recorded.
.. _kim_param command:
Accessing KIM Model Parameters from LAMMPS (*kim_param*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All IMs are functional forms containing a set of
parameters. The values of these parameters are typically
@ -620,7 +658,7 @@ for details).
.. note::
The *kim_param get/set* commands must be preceded by *kim_init*.
The *kim_param get/set* commands must be preceded by *kim_init*\ .
The *kim_param set* command must additionally be preceded by a
*kim_interactions* command (or alternatively by a *pair_style kim*
and *pair_coeff* commands). The *kim_param set* command may be used wherever a *pair_coeff* command may occur.
@ -674,13 +712,13 @@ Multiple parameters can be retrieved with a single call to *kim_param get*
by repeating the argument list following *get*\ .
For a *set* operation, the *values* argument contains the new value(s)
for the element(s) of the parameter specified by *index_range*. For the case
for the element(s) of the parameter specified by *index_range*\ . For the case
where multiple values are being set, *values* contains a set of values
separated by spaces. Multiple parameters can be set with a single call to
*kim_param set* by repeating the argument list following *set*\ .
*kim_param* Usage Examples and Further Clarifications
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Examples of getting and setting KIM PM parameters with further
clarifications are provided below.
@ -722,7 +760,7 @@ determined by the *formatarg* argument.
In this case, *formatarg* is not specified and therefore the default
"explicit" mode is used. (The behavior would be the same if the word
*explicit* were added after *LAM_TeSe*.) Elements 7, 8 and 9 of parameter
*explicit* were added after *LAM_TeSe*\ .) Elements 7, 8 and 9 of parameter
lambda retrieved by the *get* operation are placed in the LAMMPS variables
*LAM_TeTe*, *LAM_TeZn* and *LAM_TeSe*, respectively.
@ -765,7 +803,7 @@ contains the current value of lambda.
In this case, the "split" mode of *formatarg* is used.
The three values retrieved by the *get* operation are stored in
the three LAMMPS variables *LAM_15*, *LAM_16* and *LAM_17*.
the three LAMMPS variables *LAM_15*, *LAM_16* and *LAM_17*\ .
The provided name "LAM" is used as prefix and the location in
the lambda array is appended to create the variable names.
@ -797,7 +835,7 @@ potential, while *NEW_GAMMA* will contain the value 2.6.
**Setting multiple scalar parameters with a single call**
.. parsed-literal::
.. code-block:: LAMMPS
kim_init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal
...
@ -824,6 +862,421 @@ In this case, elements 2 through 6 of the parameter *sigma*
are set to the values 2.35214, 2.23869, 2.04516, 2.43269 and 1.80415 in
order.
.. _kim_property command:
Writing material properties computed in LAMMPS to standard KIM property instance format (*kim_property*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As explained :ref:`above<kim_description>`,
The OpenKIM system includes a collection of Tests (material property calculation codes),
Models (interatomic potentials), Predictions, and Reference Data (DFT or experiments).
Specifically, a KIM Test is a computation that when coupled with a KIM Model generates
the prediction of that model for a specific material property rigorously defined
by a KIM Property Definition (see the
`KIM Properties Framework <https://openkim.org/doc/schema/properties-framework/>`__
for further details). A prediction of a material property for a given model is a specific
numerical realization of a property definition, referred to as a "Property
Instance." The objective of the *kim_property* command is to make it easy to
output material properties in a standardized, machine readable, format that can be easily
ingested by other programs.
Additionally, it aims to make it as easy as possible to convert a LAMMPS script that computes a
material property into a KIM Test that can then be uploaded to `openkim.org <https://openkim.org>`_
A developer interested in creating a KIM Test using a LAMMPS script should
first determine whether a property definition that applies to their calculation
already exists in OpenKIM by searching the `properties page
<https://openkim.org/properties>`_. If none exists, it is possible to use a
locally defined property definition contained in a file until it can be
uploaded to the official repository (see below). Once one or more applicable
property definitions have been identified, the *kim_property create*,
*kim_property modify*, *kim_property remove*, and *kim_property destroy*,
commands provide an interface to create, set, modify, remove, and destroy
instances of them within a LAMMPS script. Their general syntax is as follows:
.. code-block:: LAMMPS
kim_property create instance_id property_id
kim_property modify instance_id key key_name key_name_key key_name_value
kim_property remove instance_id key key_name
kim_property destroy instance_id
kim_property dump file
Here, *instance_id* is a positive integer used to uniquely identify each
property instance; (note that the results file can contain multiple property
instances). A property_id is an identifier of a
`KIM Property Definition <https://openkim.org/properties>`_,
which can be (1) a property short name, (2) the full unique ID of the property
(including the contributor and date), (3) a file name corresponding to a local
property definition file. Examples of each of these cases are shown below:
.. code-block:: LAMMPS
kim_property create 1 atomic-mass
kim_property create 2 cohesive-energy-relation-cubic-crystal
.. code-block:: LAMMPS
kim_property create 1 tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass
kim_property create 2 tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal
.. code-block:: LAMMPS
kim_property create 1 new-property.edn
kim_property create 2 /home/mary/marys-kim-properties/dissociation-energy.edn
In the last example, "new-property.edn" and "/home/mary/marys-kim-properties/dissociation-energy.edn" are the
names of files that contain user-defined (local) property definitions.
A KIM property instance takes the form of a "map," i.e. a set of key-value
pairs akin to Perl's hash, Python's dictionary, or Java's Hashtable. It
consists of a set of property key names, each of which is referred to here by
the *key_name* argument, that are defined as part of the relevant KIM Property
Definition and include only lowercase alphanumeric characters and dashes. The
value paired with each property key is itself a map whose possible keys are
defined as part of the `KIM Properties Framework
<https://openkim.org/doc/schema/properties-framework>`__; these keys are
referred to by the *key_name_key* argument and their associated values by the
*key_name_value* argument. These values may either be scalars or arrays,
as stipulated in the property definition.
.. note::
Each map assigned to a *key_name* must contain the *key_name_key*
"source-value" and an associated *key_name_value* of the appropriate
type (as defined in the relevant KIM Property Definition). For keys that are
defined as having physical units, the
"source-unit" *key_name_key* must also be given a string value recognized
by `GNU units <https://www.gnu.org/software/units/>`_.
Once a *kim_property create* command has been given to instantiate a property
instance, maps associated with the property's keys can be edited using the
*kim_property modify* command. In using this command, the special keyword
"key" should be given, followed by the property key name and the key-value pair
in the map associated with the key that is to be set. For example, the
`atomic-mass <https://openkim.org/properties/show/2016-05-11/brunnels@noreply.openkim.org/atomic-mass>`_
property definition consists of two property keys named "mass" and "species."
An instance of this property could be created like so:
.. code-block:: LAMMPS
kim_property create 1 atomic-mass
kim_property modify 1 key species source-value Al
kim_property modify 1 key mass source-value 26.98154
kim_property modify 1 key mass source-unit amu
or, equivalently,
.. code-block:: LAMMPS
kim_property create 1 atomic-mass
kim_property modify 1 key species source-value Al &
key mass source-value 26.98154 &
source-unit amu
*kim_property* Usage Examples and Further Clarifications
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
**Create**
.. code-block:: LAMMPS
kim_property create instance_id property_id
The *kim_property create* command takes as input a property instance ID and the
property definition name, and creates an initial empty property instance data
structure. For example,
.. code-block:: LAMMPS
kim_property create 1 atomic-mass
kim_property create 2 cohesive-energy-relation-cubic-crystal
creates an empty property instance of the "atomic-mass" property definition
with instance ID 1 and an empty instance of the
"cohesive-energy-relation-cubic-crystal" property with ID 2. A list of
published property definitions in OpenKIM can be found on the `properties page
<https://openkim.org/properties>`_.
One can also provide the name of a file in the current working directory or the
path of a file containing a valid property definition. For example,
.. code-block:: LAMMPS
kim_property create 1 new-property.edn
where "new-property.edn" refers to a file name containing a new property
definition that does not exist in OpenKIM.
If the *property_id* given cannot be found in OpenKIM and no file of this name
containing a valid property definition can be found, this command will produce
an error with an appropriate message. Calling *kim_property create* with the
same instance ID multiple times will also produce an error.
**Modify**
.. code-block:: LAMMPS
kim_property modify instance_id key key_name key_name_key key_name_value
The *kim_property modify* command incrementally builds the property instance
by receiving property definition keys along with associated arguments. Each
*key_name* is associated with a map containing one or more key-value pairs (in
the form of *key_name_key*-*key_name_value* pairs). For example,
.. code-block:: LAMMPS
kim_property modify 1 key species source-value Al
kim_property modify 1 key mass source-value 26.98154
kim_property modify 1 key mass source-unit amu
where the special keyword "key" is followed by a *key_name* ("species" or
"mass" in the above) and one or more key-value pairs. These key-value pairs
may continue until either another "key" keyword is given or the end of the
command line is reached. Thus, the above could equivalently be written as
.. code-block:: LAMMPS
kim_property modify 1 key species source-value Al &
key mass source-value 26.98154 &
key mass source-unit amu
As an example of modifying multiple key-value pairs belonging to the map of a
single property key, the following command modifies the map of the
"cohesive-potential-energy" property key to contain the key "source-unit" which
is assigned a value of "eV" and the key "digits" which is assigned a value of
5:
.. code-block:: LAMMPS
kim_property modify 2 key cohesive-potential-energy source-unit eV digits 5
.. note::
The relevant data types of the values in the map are handled
automatically based on the specification of the key in the
KIM Property Definition. In the example above,
this means that the value "eV" will automatically be interpreted as a string
while the value 5 will be interpreted as an integer.
The values contained in maps can either be scalars, as in all of the examples
above, or arrays depending on which is stipulated in the corresponding Property
Definition. For one-dimensional arrays, a single one-based index must be
supplied that indicates which element of the array is to be modified. For
multidimensional arrays, multiple indices must be given depending on the
dimensionality of the array.
.. note::
All array indexing used by *kim_property modify* is one-based, i.e. the
indices are enumerated 1, 2, 3, ...
.. note::
The dimensionality of arrays are defined in the the corresponding Property
Definition. The extent of each dimension of an array can either be a
specific finite number or indefinite and determined at run time. If
an array has a fixed extent, attempting to modify an out-of-range index will
fail with an error message.
For example, the "species" property key of the
`cohesive-energy-relation-cubic-crystal
<https://openkim.org/properties/show/2014-04-15/staff@noreply.openkim.org/cohesive-energy-relation-cubic-crystal>`_
property is a one-dimensional array that can contain any number of entries
based on the number of atoms in the unit cell of a given cubic crystal. To
assign an array containing the string "Al" four times to the "source-value" key
of the "species" property key, we can do so by issuing:
.. code-block:: LAMMPS
kim_property modify 2 key species source-value 1 Al
kim_property modify 2 key species source-value 2 Al
kim_property modify 2 key species source-value 3 Al
kim_property modify 2 key species source-value 4 Al
.. note::
No declaration of the number of elements in this array was given;
*kim_property modify* will automatically handle memory management to allow
an arbitrary number of elements to be added to the array.
.. note::
In the event that *kim_property modify* is used to set the value of an
array index without having set the values of all lesser indices, they will
be assigned default values based on the data type associated with the key in
the map:
.. table_from_list::
:columns: 2
* Data type
* Default value
* int
* 0
* float
* 0.0
* string
* \"\"
* file
* \"\"
For example, doing the following:
.. code-block:: LAMMPS
kim_property create 2 cohesive-energy-relation-cubic-crystal
kim_property modify 2 key species source-value 4 Al
will result in the "source-value" key in the map for the property key
"species" being assigned the array ["", "", "", "Al"].
For convenience, the index argument provided may refer to an inclusive range of
indices by specifying two integers separated by a colon (the first integer must
be less than or equal to the second integer, and no whitespace should be
included). Thus, the snippet above could equivalently be written:
.. code-block:: LAMMPS
kim_property modify 2 key species source-value 1:4 Al Al Al Al
Calling this command with a non-positive index, e.g.
``kim_property modify 2 key species source-value 0 Al``, or an incorrect
number of input arguments, e.g.
``kim_property modify 2 key species source-value 1:4 Al Al``, will result in an
error.
As an example of modifying multidimensional arrays, consider the "basis-atoms"
key in the `cohesive-energy-relation-cubic-crystal
<https://openkim.org/properties/show/2014-04-15/staff@noreply.openkim.org/cohesive-energy-relation-cubic-crystal>`_
property definition. This is a two-dimensional array containing the fractional
coordinates of atoms in the unit cell of the cubic crystal. In the case of,
e.g. a conventional fcc unit cell, the "source-value" key in the map associated
with this key should be assigned the following value:
.. code-block:: LAMMPS
[[0.0, 0.0, 0.0],
[0.5, 0.5, 0.0],
[0.5, 0.0, 0.5],
[0.0, 0.5, 0.5]]
While each of the twelve components could be set individually, we can instead set
each row at a time using colon notation:
.. code-block:: LAMMPS
kim_property modify 2 key basis-atom-coordinates source-value 1 1:3 0.0 0.0 0.0
kim_property modify 2 key basis-atom-coordinates source-value 2 1:3 0.5 0.5 0.0
kim_property modify 2 key basis-atom-coordinates source-value 3 1:3 0.5 0.0 0.5
kim_property modify 2 key basis-atom-coordinates source-value 4 1:3 0.0 0.5 0.5
Where the first index given refers to a row and the second index refers to a
column. We could, instead, choose to set each column at a time like so:
.. code-block:: LAMMPS
kim_property modify 2 key basis-atom-coordinates source-value 1:4 1 0.0 0.5 0.5 0.0 &
key basis-atom-coordinates source-value 1:4 2 0.0 0.5 0.0 0.5 &
key basis-atom-coordinates source-value 1:4 3 0.0 0.0 0.5 0.5
.. note::
Multiple calls of *kim_property modify* made for the same instance ID
can be combined into a single invocation, meaning the following are
both valid:
.. code-block:: LAMMPS
kim_property modify 2 key basis-atom-coordinates source-value 1 1:3 0.0 0.0 0.0 &
key basis-atom-coordinates source-value 2 1:3 0.5 0.5 0.0 &
key basis-atom-coordinates source-value 3 1:3 0.5 0.0 0.5 &
key basis-atom-coordinates source-value 4 1:3 0.0 0.5 0.5
.. code-block:: LAMMPS
kim_property modify 2 key short-name source-value 1 fcc &
key species source-value 1:4 Al Al Al Al &
key a source-value 1:5 3.9149 4.0000 4.032 4.0817 4.1602 &
source-unit angstrom &
digits 5 &
key basis-atom-coordinates source-value 1 1:3 0.0 0.0 0.0 &
key basis-atom-coordinates source-value 2 1:3 0.5 0.5 0.0 &
key basis-atom-coordinates source-value 3 1:3 0.5 0.0 0.5 &
key basis-atom-coordinates source-value 4 1:3 0.0 0.5 0.5
.. note::
For multidimensional arrays, only one colon-separated range is allowed
in the index listing. Therefore,
.. code-block:: LAMMPS
kim_property modify 2 key basis-atom-coordinates 1 1:3 0.0 0.0 0.0
is valid but
.. code-block:: LAMMPS
kim_property modify 2 key basis-atom-coordinates 1:2 1:3 0.0 0.0 0.0 0.0 0.0 0.0
is not.
.. note::
After one sets a value in a map with the *kim_property modify* command,
additional calls will overwrite the previous value.
**Remove**
.. code-block:: LAMMPS
kim_property remove instance_id key key_name
The *kim_property remove* command can be used to remove a property key from a
property instance. For example,
.. code-block:: LAMMPS
kim_property remove 2 key basis-atom-coordinates
**Destroy**
.. code-block:: LAMMPS
kim_property destroy instance_id
The *kim_property destroy* command deletes a previously created property
instance ID. For example,
.. code-block:: LAMMPS
kim_property destroy 2
.. note::
If this command is called with an instance ID that does not exist, no
error is raised.
**Dump**
The *kim_property dump* command can be used to write the content of all
currently defined property instances to a file:
.. code-block:: LAMMPS
kim_property dump file
For example,
.. code-block:: LAMMPS
kim_property dump results.edn
.. note::
Issuing the *kim_property dump* command clears all existing property
instances from memory.
Citation of OpenKIM IMs
-----------------------
@ -847,8 +1300,11 @@ LAMMPS is built with that package. A requirement for the KIM package,
is the KIM API library that must be downloaded from the
`OpenKIM website <https://openkim.org/kim-api/>`_ and installed before
LAMMPS is compiled. When installing LAMMPS from binary, the kim-api package
is a dependency that is automatically downloaded and installed. See the KIM
section of the :doc:`Packages details <Packages_details>` for details.
is a dependency that is automatically downloaded and installed. The *kim_query*
command requires the *libcurl* library to be installed. The *kim_property*
command requires *Python* 3.6 or later and the *kim-property* python package to
be installed. See the KIM section of the :doc:`Packages details <Packages_details>`
for details.
Furthermore, when using *kim_commands* to run KIM SMs, any packages required
by the native potential being used or other commands or fixes that it invokes

3
doc/src/min_modify.rst
View File

@ -87,8 +87,7 @@ The choice of a norm can be modified for the min styles *cg*\ , *sd*\
the 2-norm (Euclidean length) of the global force vector:
.. math::
|| \vec{F} ||_{2} = \sqrt{\vec{F}_1+ \cdots + \vec{F}_N}
|| \vec{F} ||_{2} = \sqrt{\vec{F}_1^2+ \cdots + \vec{F}_N^2}
The *max* norm computes the length of the 3-vector force
for each atom (2-norm), and takes the maximum value of those across

2
doc/src/minimize.rst
View File

@ -64,7 +64,7 @@ performed using a line search algorithm. The line search typically
evaluates forces and energies several times to set new coordinates.
Currently, a backtracking algorithm is used which may not be optimal
in terms of the number of force evaluations performed, but appears to
be more robust than previous line searches we've tried. The
be more robust than previous line searches we have tried. The
backtracking method is described in Nocedal and Wright's Numerical
Optimization (Procedure 3.1 on p 41).

6
doc/src/pair_adp.rst
View File

@ -56,8 +56,10 @@ command to specify them.
* The NIST WWW site at http://www.ctcms.nist.gov/potentials.
Note that ADP potentials obtained from NIST must be converted
into the extended DYNAMO *setfl* format discussed below.
* The OpenKIM Project at https://openkim.org/browse/models/by-type provides
ADP potentials that can be used directly in LAMMPS with the :doc:`kim_commands interface <kim_commands>`.
* The OpenKIM Project at
`https://openkim.org/browse/models/by-type <https://openkim.org/browse/models/by-type>`_
provides ADP potentials that can be used directly in LAMMPS with the
:doc:`kim_commands <kim_commands>` interface.
----------

4
doc/src/pair_bop.rst
View File

@ -132,9 +132,9 @@ and Te. If your LAMMPS simulation has 4 atoms types and you want the
1st 3 to be Cd, and the 4th to be Te, you would use the following
pair_coeff command:
.. parsed-literal::
.. code-block:: LAMMPS
pair_coeff \* \* CdTe Cd Cd Cd Te
pair_coeff * * CdTe Cd Cd Cd Te
The 1st 2 arguments must be \* \* so as to span all LAMMPS atom types.
The first three Cd arguments map LAMMPS atom types 1,2,3 to the Cd

8
doc/src/pair_class2.rst
View File

@ -60,18 +60,18 @@ Examples
.. code-block:: LAMMPS
pair_style lj/class2 10.0
pair_coeff \* \* 100.0 2.5
pair_coeff 1 2\* 100.0 2.5 9.0
pair_coeff * * 100.0 2.5
pair_coeff 1 2* 100.0 2.5 9.0
pair_style lj/class2/coul/cut 10.0
pair_style lj/class2/coul/cut 10.0 8.0
pair_coeff \* \* 100.0 3.0
pair_coeff * * 100.0 3.0
pair_coeff 1 1 100.0 3.5 9.0
pair_coeff 1 1 100.0 3.5 9.0 9.0
pair_style lj/class2/coul/long 10.0
pair_style lj/class2/coul/long 10.0 8.0
pair_coeff \* \* 100.0 3.0
pair_coeff * * 100.0 3.0
pair_coeff 1 1 100.0 3.5 9.0
Description

12
doc/src/pair_coeff.rst
View File

@ -19,11 +19,11 @@ Examples
.. code-block:: LAMMPS
pair_coeff 1 2 1.0 1.0 2.5
pair_coeff 2 \* 1.0 1.0
pair_coeff 3\* 1\*2 1.0 1.0 2.5
pair_coeff \* \* 1.0 1.0
pair_coeff \* \* nialhjea 1 1 2
pair_coeff \* 3 morse.table ENTRY1
pair_coeff 2 * 1.0 1.0
pair_coeff 3* 1*2 1.0 1.0 2.5
pair_coeff * * 1.0 1.0
pair_coeff * * nialhjea 1 1 2
pair_coeff * 3 morse.table ENTRY1
pair_coeff 1 2 lj/cut 1.0 1.0 2.5 (for pair_style hybrid)
Description
@ -55,7 +55,7 @@ pairs, then overwrite the coeffs for just the I,J = 2,3 pair:
.. code-block:: LAMMPS
pair_coeff \* \* 1.0 1.0 2.5
pair_coeff * * 1.0 1.0 2.5
pair_coeff 2 3 2.0 1.0 1.12
A line in a data file that specifies pair coefficients uses the exact

4
doc/src/pair_cosine_squared.rst
View File

@ -31,7 +31,7 @@ Examples
.. code-block:: LAMMPS
pair_style cosine/squared 3.0
pair_coeff \* \* 1.0 1.3
pair_coeff * * 1.0 1.3
pair_coeff 1 3 1.0 1.3 2.0
pair_coeff 1 3 1.0 1.3 wca
pair_coeff 1 3 1.0 1.3 2.0 wca
@ -46,7 +46,7 @@ Style *cosine/squared* computes a potential of the form
E =
\begin{cases}
-\epsilon& \quad r < \sigma \\
-\epsilon\cos\left(\frac{\pi\left(r - \sigma\right)}{2\left(r_c - \sigma\right)}\right)&\quad \sigma \leq r < r_c \\
-\epsilon\cos\left(\frac{\pi\left(r - \sigma\right)}{2\left(r_c - \sigma\right)}\right)^2&\quad \sigma \leq r < r_c \\
0& \quad r \geq r_c
\end{cases}

9
doc/src/pair_cs.rst
View File

@ -30,6 +30,9 @@ pair_style coul/wolf/cs command
pair_style lj/cut/coul/long/cs command
=======================================
pair_style lj/class2/coul/long/cs command
==========================================
Syntax
""""""
@ -37,7 +40,7 @@ Syntax
pair_style style args
* style = *born/coul/dsf/cs* or *born/coul/long/cs* or *born/coul/wolf/cs* or *buck/coul/long/cs* or *coul/long/cs* or *coul/wolf/cs* or *lj/cut/coul/long/cs*
* style = *born/coul/dsf/cs* or *born/coul/long/cs* or *born/coul/wolf/cs* or *buck/coul/long/cs* or *coul/long/cs* or *coul/wolf/cs* or *lj/cut/coul/long/cs* or *lj/class2/coul/long/cs*
* args = list of arguments for a particular style
.. parsed-literal::
@ -64,6 +67,9 @@ Syntax
*lj/cut/coul/long/cs* args = cutoff (cutoff2)
cutoff = global cutoff for LJ (and Coulombic if only 1 arg) (distance units)
cutoff2 = global cutoff for Coulombic (optional) (distance units)
*lj/class2/coul/long/cs* args = cutoff (cutoff2)
cutoff = global cutoff for LJ (and Coulombic if only 1 arg) (distance units)
cutoff2 = global cutoff for Coulombic (optional) (distance units)
Examples
""""""""
@ -115,6 +121,7 @@ the "/cs" in the name:
* :doc:`pair_style coul/long <pair_coul>`
* :doc:`pair_style coul/wolf <pair_coul>`
* :doc:`pair_style lj/cut/coul/long <pair_lj>`
* :doc:`pair_style lj/class2/coul/long <pair_class2>`
except that they correctly treat the special case where the distance
between two charged core and shell atoms in the same core/shell pair

6
doc/src/pair_eam.rst
View File

@ -149,6 +149,7 @@ potentials stored in DYNAMO or other formats:
http://www.ctcms.nist.gov/potentials
http://cst-www.nrl.navy.mil/ccm6/ap
http://enpub.fulton.asu.edu/cms/potentials/main/main.htm
https://openkim.org
These potentials should be usable with LAMMPS, though the alternate
formats would need to be converted to the DYNAMO format used by LAMMPS
@ -156,6 +157,11 @@ and described on this page. The NIST site is maintained by Chandler
Becker (cbecker at nist.gov) who is good resource for info on
interatomic potentials and file formats.
The OpenKIM Project at
`https://openkim.org/browse/models/by-type <https://openkim.org/browse/models/by-type>`_
provides EAM potentials that can be used directly in LAMMPS with the
:doc:`kim_commands <kim_commands>` interface.
----------
For style *eam*\ , potential values are read from a file that is in the

4
doc/src/pair_meam_sw_spline.rst
View File

@ -75,7 +75,9 @@ If your LAMMPS simulation has 3 atoms types and they are all to be
treated with this potential, you would use the following pair_coeff
command:
pair_coeff \* \* Ti.meam.sw.spline Ti Ti Ti
.. code-block:: LAMMPS
pair_coeff * * Ti.meam.sw.spline Ti Ti Ti
The 1st 2 arguments must be \* \* so as to span all LAMMPS atom types.
The three Ti arguments map LAMMPS atom types 1,2,3 to the Ti element

22
doc/src/pair_meamc.rst
View File

@ -93,12 +93,13 @@ and the 4th to be C, you would use the following pair_coeff command:
pair_coeff * * library.meam Si C sic.meam Si Si Si C
The 1st 2 arguments must be \* \* so as to span all LAMMPS atom types.
The two filenames are for the library and parameter file respectively.
The Si and C arguments (between the file names) are the two elements
for which info will be extracted from the library file. The first
three trailing Si arguments map LAMMPS atom types 1,2,3 to the MEAM Si
element. The final C argument maps LAMMPS atom type 4 to the MEAM C
element.
The first filename is the element library file. The list of elements following
it extracts lines from the library file and assigns numeric indices to these
elements. The second filename is the alloy parameter file, which refers to
elements using the numeric indices assigned before.
The arguments after the parameter file map LAMMPS atom types to elements, i.e.
LAMMPS atom types 1,2,3 to the MEAM Si element. The final C argument maps
LAMMPS atom type 4 to the MEAM C element.
If the 2nd filename is specified as NULL, no parameter file is read,
which simply means the generic parameters in the library file are
@ -140,7 +141,7 @@ not required. The other numeric parameters match values in the
formulas above. The value of the "elt" string is what is used in the
pair_coeff command to identify which settings from the library file
you wish to read in. There can be multiple entries in the library
file with the same "elt" value; LAMMPS reads the 1st matching entry it
file with the same "elt" value; LAMMPS reads the first matching entry it
finds and ignores the rest.
Other parameters in the MEAM library file correspond to single-element
@ -192,7 +193,7 @@ trailing comment (starting with #) which is ignored.
The indices I, J, K correspond to the elements selected from the
MEAM library file numbered in the order of how those elements were
selected starting from 1. Thus for the example given below
selected starting from 1. Thus for the example given before
.. code-block:: LAMMPS
@ -202,11 +203,6 @@ an index of 1 would refer to Si and an index of 2 to C.
The recognized keywords for the parameter file are as follows:
Ec, alpha, rho0, delta, lattce, attrac, repuls, nn2, Cmin, Cmax, rc, delr,
augt1, gsmooth_factor, re
where
.. parsed-literal::
rc = cutoff radius for cutoff function; default = 4.0

4
doc/src/pair_nb3b_harmonic.rst
View File

@ -64,7 +64,9 @@ NULL values are placeholders for atom types that will be used with
other potentials. An example of a pair_coeff command for use with the
*hybrid* pair style is:
pair_coeff \* \* nb3b/harmonic MgOH.nb3b.harmonic Mg O H
.. code-block:: LAMMPS
pair_coeff * * nb3b/harmonic MgOH.nb3b.harmonic Mg O H
Three-body non-bonded harmonic files in the *potentials* directory of
the LAMMPS distribution have a ".nb3b.harmonic" suffix. Lines that

4
doc/src/pair_polymorphic.rst
View File

@ -180,9 +180,9 @@ functions for Si-C tersoff potential. If your LAMMPS simulation has 4
atoms types and you want the 1st 3 to be Si, and the 4th to be C, you
would use the following pair_coeff command:
.. parsed-literal::
.. code-block:: LAMMPS
pair_coeff \* \* SiC_tersoff.poly Si Si Si C
pair_coeff * * SiC_tersoff.poly Si Si Si C
The 1st 2 arguments must be \* \* so as to span all LAMMPS atom
types. The first three Si arguments map LAMMPS atom types 1,2,3 to the

12
doc/src/pair_python.rst
View File

@ -113,8 +113,8 @@ which the parameters epsilon and sigma are both 1.0:
class LJCutMelt(LAMMPSPairPotential):
def __init__(self):
super(LJCutMelt,self).__init__()
# set coeffs: 48\*eps\*sig\*\*12, 24\*eps\*sig\*\*6,
# 4\*eps\*sig\*\*12, 4\*eps\*sig\*\*6
# set coeffs: 48*eps*sig**12, 24*eps*sig**6,
# 4*eps*sig**12, 4*eps*sig**6
self.units = 'lj'
self.coeff = {'lj' : {'lj' : (48.0,24.0,4.0,4.0)}}
@ -137,18 +137,18 @@ the *LJCutMelt* example, here are the two functions:
def compute_force(self,rsq,itype,jtype):
coeff = self.coeff[self.pmap[itype]][self.pmap[jtype]]
r2inv = 1.0/rsq
r6inv = r2inv\*r2inv\*r2inv
r6inv = r2inv*r2inv*r2inv
lj1 = coeff[0]
lj2 = coeff[1]
return (r6inv \* (lj1\*r6inv - lj2))\*r2inv
return (r6inv * (lj1*r6inv - lj2))*r2inv
def compute_energy(self,rsq,itype,jtype):
coeff = self.coeff[self.pmap[itype]][self.pmap[jtype]]
r2inv = 1.0/rsq
r6inv = r2inv\*r2inv\*r2inv
r6inv = r2inv*r2inv*r2inv
lj3 = coeff[2]
lj4 = coeff[3]
return (r6inv \* (lj3\*r6inv - lj4))
return (r6inv * (lj3*r6inv - lj4))
.. note::

2
doc/src/pair_spin_magelec.rst
View File

@ -18,7 +18,7 @@ Examples
.. code-block:: LAMMPS
pair_style spin/magelec 4.5
pair_coeff \* \* magelec 4.5 0.00109 1.0 1.0 1.0
pair_coeff * * magelec 4.5 0.00109 1.0 1.0 1.0
Description
"""""""""""

87
doc/src/pair_style.rst
View File

@ -111,41 +111,41 @@ accelerated styles exist.
* :doc:`born <pair_born>` - Born-Mayer-Huggins potential
* :doc:`born/coul/dsf <pair_born>` - Born with damped-shifted-force model
* :doc:`born/coul/dsf/cs <pair_cs>` - Born with damped-shifted-force and core/shell model
* :doc:`born/coul/long <pair_born>` - Born with long-range Coulombics
* :doc:`born/coul/long/cs <pair_cs>` - Born with long-range Coulombics and core/shell
* :doc:`born/coul/msm <pair_born>` - Born with long-range MSM Coulombics
* :doc:`born/coul/wolf <pair_born>` - Born with Wolf potential for Coulombics
* :doc:`born/coul/wolf/cs <pair_cs>` - Born with Wolf potential for Coulombics and core/shell model
* :doc:`born/coul/long <pair_born>` - Born with long-range Coulomb
* :doc:`born/coul/long/cs <pair_cs>` - Born with long-range Coulomb and core/shell
* :doc:`born/coul/msm <pair_born>` - Born with long-range MSM Coulomb
* :doc:`born/coul/wolf <pair_born>` - Born with Wolf potential for Coulomb
* :doc:`born/coul/wolf/cs <pair_cs>` - Born with Wolf potential for Coulomb and core/shell model
* :doc:`brownian <pair_brownian>` - Brownian potential for Fast Lubrication Dynamics
* :doc:`brownian/poly <pair_brownian>` - Brownian potential for Fast Lubrication Dynamics with polydispersity
* :doc:`buck <pair_buck>` - Buckingham potential
* :doc:`buck/coul/cut <pair_buck>` - Buckingham with cutoff Coulomb
* :doc:`buck/coul/long <pair_buck>` - Buckingham with long-range Coulombics
* :doc:`buck/coul/long/cs <pair_cs>` - Buckingham with long-range Coulombics and core/shell
* :doc:`buck/coul/msm <pair_buck>` - Buckingham with long-range MSM Coulombics
* :doc:`buck/long/coul/long <pair_buck_long>` - long-range Buckingham with long-range Coulombics
* :doc:`buck/coul/long <pair_buck>` - Buckingham with long-range Coulomb
* :doc:`buck/coul/long/cs <pair_cs>` - Buckingham with long-range Coulomb and core/shell
* :doc:`buck/coul/msm <pair_buck>` - Buckingham with long-range MSM Coulomb
* :doc:`buck/long/coul/long <pair_buck_long>` - long-range Buckingham with long-range Coulomb
* :doc:`buck/mdf <pair_mdf>` - Buckingham with a taper function
* :doc:`buck6d/coul/gauss/dsf <pair_buck6d_coul_gauss>` - dispersion-damped Buckingham with damped-shift-force model
* :doc:`buck6d/coul/gauss/long <pair_buck6d_coul_gauss>` - dispersion-damped Buckingham with long-range Coulombics
* :doc:`buck6d/coul/gauss/long <pair_buck6d_coul_gauss>` - dispersion-damped Buckingham with long-range Coulomb
* :doc:`colloid <pair_colloid>` - integrated colloidal potential
* :doc:`comb <pair_comb>` - charge-optimized many-body (COMB) potential
* :doc:`comb3 <pair_comb>` - charge-optimized many-body (COMB3) potential
* :doc:`cosine/squared <pair_cosine_squared>` - Cooke-Kremer-Deserno membrane model potential
* :doc:`coul/cut <pair_coul>` - cutoff Coulombic potential
* :doc:`coul/cut/soft <pair_fep_soft>` - Coulombic potential with a soft core
* :doc:`coul/debye <pair_coul>` - cutoff Coulombic potential with Debye screening
* :doc:`coul/cut <pair_coul>` - cutoff Coulomb potential
* :doc:`coul/cut/soft <pair_fep_soft>` - Coulomb potential with a soft core
* :doc:`coul/debye <pair_coul>` - cutoff Coulomb potential with Debye screening
* :doc:`coul/diel <pair_coul_diel>` - Coulomb potential with dielectric permittivity
* :doc:`coul/dsf <pair_coul>` - Coulombics with damped-shifted-force model
* :doc:`coul/long <pair_coul>` - long-range Coulombic potential
* :doc:`coul/long/cs <pair_cs>` - long-range Coulombic potential and core/shell
* :doc:`coul/long/soft <pair_fep_soft>` - long-range Coulombic potential with a soft core
* :doc:`coul/msm <pair_coul>` - long-range MSM Coulombics
* :doc:`coul/slater/cut <pair_coul>` - smeared out Coulombics
* :doc:`coul/slater/long <pair_coul>` - long-range smeared out Coulombics
* :doc:`coul/shield <pair_coul_shield>` - Coulombics for boron nitride for use with :doc:`ilp/graphene/hbn <pair_ilp_graphene_hbn>` potential
* :doc:`coul/streitz <pair_coul>` - Coulombics via Streitz/Mintmire Slater orbitals
* :doc:`coul/wolf <pair_coul>` - Coulombics via Wolf potential
* :doc:`coul/wolf/cs <pair_cs>` - ditto with core/shell adjustments
* :doc:`coul/dsf <pair_coul>` - Coulomb with damped-shifted-force model
* :doc:`coul/long <pair_coul>` - long-range Coulomb potential
* :doc:`coul/long/cs <pair_cs>` - long-range Coulomb potential and core/shell
* :doc:`coul/long/soft <pair_fep_soft>` - long-range Coulomb potential with a soft core
* :doc:`coul/msm <pair_coul>` - long-range MSM Coulomb
* :doc:`coul/slater/cut <pair_coul>` - smeared out Coulomb
* :doc:`coul/slater/long <pair_coul>` - long-range smeared out Coulomb
* :doc:`coul/shield <pair_coul_shield>` - Coulomb for boron nitride for use with :doc:`ilp/graphene/hbn <pair_ilp_graphene_hbn>` potential
* :doc:`coul/streitz <pair_coul>` - Coulomb via Streitz/Mintmire Slater orbitals
* :doc:`coul/wolf <pair_coul>` - Coulomb via Wolf potential
* :doc:`coul/wolf/cs <pair_cs>` - Coulomb via Wolf potential with core/shell adjustments
* :doc:`dpd <pair_dpd>` - dissipative particle dynamics (DPD)
* :doc:`dpd/fdt <pair_dpd_fdt>` - DPD for constant temperature and pressure
* :doc:`dpd/fdt/energy <pair_dpd_fdt>` - DPD for constant energy and enthalpy
@ -189,44 +189,45 @@ accelerated styles exist.
* :doc:`lj/charmm/coul/charmm/implicit <pair_charmm>` - CHARMM for implicit solvent
* :doc:`lj/charmm/coul/long <pair_charmm>` - CHARMM with long-range Coulomb
* :doc:`lj/charmm/coul/long/soft <pair_fep_soft>` - CHARMM with long-range Coulomb and a soft core
* :doc:`lj/charmm/coul/msm <pair_charmm>` - CHARMM with long-range MSM Coulombics
* :doc:`lj/charmm/coul/msm <pair_charmm>` - CHARMM with long-range MSM Coulomb
* :doc:`lj/charmmfsw/coul/charmmfsh <pair_charmm>` - CHARMM with force switching and shifting
* :doc:`lj/charmmfsw/coul/long <pair_charmm>` - CHARMM with force switching and long-rnage Coulombics
* :doc:`lj/class2 <pair_class2>` - COMPASS (class 2) force field with no Coulomb
* :doc:`lj/charmmfsw/coul/long <pair_charmm>` - CHARMM with force switching and long-rnage Coulomb
* :doc:`lj/class2 <pair_class2>` - COMPASS (class 2) force field without Coulomb
* :doc:`lj/class2/coul/cut <pair_class2>` - COMPASS with cutoff Coulomb
* :doc:`lj/class2/coul/cut/soft <pair_fep_soft>` - COMPASS with cutoff Coulomb with a soft core
* :doc:`lj/class2/coul/long <pair_class2>` - COMPASS with long-range Coulomb
* :doc:`lj/class2/coul/long/cs <pair_cs>` - COMPASS with long-range Coulomb with core/shell adjustments
* :doc:`lj/class2/coul/long/soft <pair_fep_soft>` - COMPASS with long-range Coulomb with a soft core
* :doc:`lj/class2/soft <pair_fep_soft>` - COMPASS (class 2) force field with no Coulomb with a soft core
* :doc:`lj/cubic <pair_lj_cubic>` - LJ with cubic after inflection point
* :doc:`lj/cut <pair_lj>` - cutoff Lennard-Jones potential with no Coulomb
* :doc:`lj/cut <pair_lj>` - cutoff Lennard-Jones potential without Coulomb
* :doc:`lj/cut/coul/cut <pair_lj>` - LJ with cutoff Coulomb
* :doc:`lj/cut/coul/cut/soft <pair_fep_soft>` - LJ with cutoff Coulomb with a soft core
* :doc:`lj/cut/coul/debye <pair_lj>` - LJ with Debye screening added to Coulomb
* :doc:`lj/cut/coul/dsf <pair_lj>` - LJ with Coulombics via damped shifted forces
* :doc:`lj/cut/coul/long <pair_lj>` - LJ with long-range Coulombics
* :doc:`lj/cut/coul/long/cs <pair_cs>` - ditto with core/shell adjustments
* :doc:`lj/cut/coul/long/soft <pair_fep_soft>` - LJ with long-range Coulombics with a soft core
* :doc:`lj/cut/coul/msm <pair_lj>` - LJ with long-range MSM Coulombics
* :doc:`lj/cut/coul/wolf <pair_lj>` - LJ with Coulombics via Wolf potential
* :doc:`lj/cut/coul/dsf <pair_lj>` - LJ with Coulomb via damped shifted forces
* :doc:`lj/cut/coul/long <pair_lj>` - LJ with long-range Coulomb
* :doc:`lj/cut/coul/long/cs <pair_cs>` - LJ with long-range Coulomb with core/shell adjustments
* :doc:`lj/cut/coul/long/soft <pair_fep_soft>` - LJ with long-range Coulomb with a soft core
* :doc:`lj/cut/coul/msm <pair_lj>` - LJ with long-range MSM Coulomb
* :doc:`lj/cut/coul/wolf <pair_lj>` - LJ with Coulomb via Wolf potential
* :doc:`lj/cut/dipole/cut <pair_dipole>` - point dipoles with cutoff
* :doc:`lj/cut/dipole/long <pair_dipole>` - point dipoles with long-range Ewald
* :doc:`lj/cut/soft <pair_fep_soft>` - LJ with a soft core
* :doc:`lj/cut/thole/long <pair_thole>` - LJ with Coulombics with thole damping
* :doc:`lj/cut/thole/long <pair_thole>` - LJ with Coulomb with thole damping
* :doc:`lj/cut/tip4p/cut <pair_lj>` - LJ with cutoff Coulomb for TIP4P water
* :doc:`lj/cut/tip4p/long <pair_lj>` - LJ with long-range Coulomb for TIP4P water
* :doc:`lj/cut/tip4p/long/soft <pair_fep_soft>` - LJ with cutoff Coulomb for TIP4P water with a soft core
* :doc:`lj/expand <pair_lj_expand>` - Lennard-Jones for variable size particles
* :doc:`lj/expand/coul/long <pair_lj_expand>` - Lennard-Jones for variable size particles with long-range Coulombics
* :doc:`lj/expand/coul/long <pair_lj_expand>` - Lennard-Jones for variable size particles with long-range Coulomb
* :doc:`lj/gromacs <pair_gromacs>` - GROMACS-style Lennard-Jones potential
* :doc:`lj/gromacs/coul/gromacs <pair_gromacs>` - GROMACS-style LJ and Coulombic potential
* :doc:`lj/long/coul/long <pair_lj_long>` - long-range LJ and long-range Coulombics
* :doc:`lj/gromacs/coul/gromacs <pair_gromacs>` - GROMACS-style LJ and Coulomb potential
* :doc:`lj/long/coul/long <pair_lj_long>` - long-range LJ and long-range Coulomb
* :doc:`lj/long/dipole/long <pair_dipole>` - long-range LJ and long-range point dipoles
* :doc:`lj/long/tip4p/long <pair_lj_long>` - long-range LJ and long-range Coulombics for TIP4P water
* :doc:`lj/long/tip4p/long <pair_lj_long>` - long-range LJ and long-range Coulomb for TIP4P water
* :doc:`lj/mdf <pair_mdf>` - LJ potential with a taper function
* :doc:`lj/sdk <pair_sdk>` - LJ for SDK coarse-graining
* :doc:`lj/sdk/coul/long <pair_sdk>` - LJ for SDK coarse-graining with long-range Coulombics
* :doc:`lj/sdk/coul/msm <pair_sdk>` - LJ for SDK coarse-graining with long-range Coulombics via MSM
* :doc:`lj/sdk/coul/long <pair_sdk>` - LJ for SDK coarse-graining with long-range Coulomb
* :doc:`lj/sdk/coul/msm <pair_sdk>` - LJ for SDK coarse-graining with long-range Coulomb via MSM
* :doc:`lj/sf/dipole/sf <pair_dipole>` - LJ with dipole interaction with shifted forces
* :doc:`lj/smooth <pair_lj_smooth>` - smoothed Lennard-Jones potential
* :doc:`lj/smooth/linear <pair_lj_smooth_linear>` - linear smoothed LJ potential
@ -255,7 +256,7 @@ accelerated styles exist.
* :doc:`nb3b/harmonic <pair_nb3b_harmonic>` - non-bonded 3-body harmonic potential
* :doc:`nm/cut <pair_nm>` - N-M potential
* :doc:`nm/cut/coul/cut <pair_nm>` - N-M potential with cutoff Coulomb
* :doc:`nm/cut/coul/long <pair_nm>` - N-M potential with long-range Coulombics
* :doc:`nm/cut/coul/long <pair_nm>` - N-M potential with long-range Coulomb
* :doc:`oxdna/coaxstk <pair_oxdna>` -
* :doc:`oxdna/excv <pair_oxdna>` -
* :doc:`oxdna/hbond <pair_oxdna>` -
@ -315,7 +316,7 @@ accelerated styles exist.
* :doc:`tersoff/zbl <pair_tersoff_zbl>` - Tersoff/ZBL 3-body potential
* :doc:`thole <pair_thole>` - Coulomb interactions with thole damping
* :doc:`tip4p/cut <pair_coul>` - Coulomb for TIP4P water w/out LJ
* :doc:`tip4p/long <pair_coul>` - long-range Coulombics for TIP4P water w/out LJ
* :doc:`tip4p/long <pair_coul>` - long-range Coulomb for TIP4P water w/out LJ
* :doc:`tip4p/long/soft <pair_fep_soft>` -
* :doc:`tri/lj <pair_tri_lj>` - LJ potential between triangles
* :doc:`ufm <pair_ufm>` -