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

Merge branch 'master' into feature-cnt

Browse Source
This commit is contained in:
iafoss
2020-05-18 18:23:16 -04:00
parent e26be18b1e 48fa824a32
commit ed43c1e22b
3490 changed files with 279208 additions and 173596 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

382
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,95 +307,209 @@ 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
If you run Kokkos on a different GPU architecture than what LAMMPS
was compiled with, there will be a delay during device initialization
while the just-in-time compiler is recompiling all GPU kernels for
the new hardware. This is, however, only supported for GPUs of the
**same** major hardware version and different minor hardware versions,
e.g. 5.0 and 5.2 but not 5.2 and 6.0. LAMMPS will abort with an
error message indicating a mismatch, if that happens.
**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**
- **HOST or GPU**
- **Description**
* - AMDAVX
- HOST
- AMD 64-bit x86 CPU (AVX 1)
* - EPYC
- HOST
- AMD EPYC Zen class CPU (AVX 2)
* - ARMV80
- HOST
- ARMv8.0 Compatible CPU
* - ARMV81
- HOST
- ARMv8.1 Compatible CPU
* - ARMV8_THUNDERX
- HOST
- ARMv8 Cavium ThunderX CPU
* - ARMV8_THUNDERX2
- HOST
- ARMv8 Cavium ThunderX2 CPU
* - WSM
- HOST
- Intel Westmere CPU (SSE 4.2)
* - SNB
- HOST
- Intel Sandy/Ivy Bridge CPU (AVX 1)
* - HSW
- HOST
- Intel Haswell CPU (AVX 2)
* - BDW
- HOST
- Intel Broadwell Xeon E-class CPU (AVX 2 + transactional mem)
* - SKX
- HOST
- Intel Sky Lake Xeon E-class HPC CPU (AVX512 + transactional mem)
* - KNC
- HOST
- Intel Knights Corner Xeon Phi
* - KNL
- HOST
- Intel Knights Landing Xeon Phi
* - BGQ
- HOST
- IBM Blue Gene/Q CPU
* - POWER7
- HOST
- IBM POWER7 CPU
* - POWER8
- HOST
- IBM POWER8 CPU
* - POWER9
- HOST
- IBM POWER9 CPU
* - KEPLER30
- GPU
- NVIDIA Kepler generation CC 3.0 GPU
* - KEPLER32
- GPU
- NVIDIA Kepler generation CC 3.2 GPU
* - KEPLER35
- GPU
- NVIDIA Kepler generation CC 3.5 GPU
* - KEPLER37
- GPU
- NVIDIA Kepler generation CC 3.7 GPU
* - MAXWELL50
- GPU
- NVIDIA Maxwell generation CC 5.0 GPU
* - MAXWELL52
- GPU
- NVIDIA Maxwell generation CC 5.2 GPU
* - MAXWELL53
- GPU
- NVIDIA Maxwell generation CC 5.3 GPU
* - PASCAL60
- GPU
- NVIDIA Pascal generation CC 6.0 GPU
* - PASCAL61
- GPU
- NVIDIA Pascal generation CC 6.1 GPU
* - VOLTA70
- GPU
- NVIDIA Volta generation CC 7.0 GPU
* - VOLTA72
- GPU
- NVIDIA Volta generation CC 7.2 GPU
* - TURING75
- GPU
- NVIDIA Turing generation CC 7.5 GPU
* - VEGA900
- GPU
- AMD GPU MI25 GFX900
* - VEGA906
- GPU
- AMD GPU MI50/MI60 GFX906
Basic 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_HOSTARCH=yes # HOSTARCH = HOST 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_HOSTARCH=yes # HOSTARCH = HOST 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
include the full path name to the wrapper, e.g.
This will also enable executing FFTs on the GPU, either via the internal
KISSFFT library, or - by preference - with the cuFFT library bundled
with the CUDA toolkit, depending on whether CMake can identify its
location. The *wrapper* value for ``CMAKE_CXX_COMPILER`` variable is
the path to the CUDA nvcc compiler wrapper provided in the Kokkos
library: ``lib/kokkos/bin/nvcc_wrapper``\ . The setting should 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 .
Basic 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 = HOSTARCH # HOSTARCH = HOST from list above
For Intel KNLs using OpenMP:
@ -367,22 +523,72 @@ 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 = HOSTARCH,GPUARCH # HOSTARCH = HOST from list above that is hosting the GPU
KOKKOS_CUDA_OPTIONS = "enable_lambda"
# 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
Advanced KOKKOS compilation settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are other allowed options when building with the KOKKOS package
that can improve performance or assist in debugging or profiling. Below
are some examples that may be useful in combination with LAMMPS. For
the full list (which keeps changing as the Kokkos package itself evolves),
please consult the Kokkos library documentation.
As alternative to using multi-threading via OpenMP
(``-DKokkos_ENABLE_OPENMP=on`` or ``KOKKOS_DEVICES=OpenMP``) it is also
possible to use Posix threads directly (``-DKokkos_ENABLE_PTHREAD=on``
or ``KOKKOS_DEVICES=Pthread``). While binding of threads to individual
or groups of CPU cores is managed in OpenMP with environment variables,
you need assistance from either the "hwloc" or "libnuma" library for the
Pthread thread parallelization option. To enable use with CMake:
``-DKokkos_ENABLE_HWLOC=on`` or ``-DKokkos_ENABLE_LIBNUMA=on``; and with
conventional make: ``KOKKOS_USE_TPLS=hwloc`` or
``KOKKOS_USE_TPLS=libnuma``.
The CMake option ``-DKokkos_ENABLE_LIBRT=on`` or the makefile setting
``KOKKOS_USE_TPLS=librt`` enables the use of a more accurate timer
mechanism on many Unix-like platforms for internal profiling.
The CMake option ``-DKokkos_ENABLE_DEBUG=on`` or the makefile setting
``KOKKOS_DEBUG=yes`` enables printing of run-time
debugging information that can be useful. It also enables runtime
bounds checking on Kokkos data structures. As to be expected, enabling
this option will negatively impact the performance and thus is only
recommended when developing a Kokkos-enabled style in LAMMPS.
The CMake option ``-DKokkos_ENABLE_CUDA_UVM=on`` or the makefile
setting ``KOKKOS_CUDA_OPTIONS=enable_lambda,force_uvm`` enables the
use of CUDA "Unified Virtual Memory" (UVM) in Kokkos. UVM allows to
transparently use RAM on the host to supplement the memory used on the
GPU (with some performance penalty) and thus enables running larger
problems that would otherwise not fit into the RAM on the GPU.
Please note, that the LAMMPS KOKKOS package must **always** be compiled
with the *enable_lambda* option when using GPUs. The CMake configuration
will thus always enable it.
----------
@ -421,7 +627,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>`

11
doc/src/Commands_compute.rst
View File

@ -42,7 +42,7 @@ KOKKOS, o = USER-OMP, t = OPT.
* :doc:`com <compute_com>`
* :doc:`com/chunk <compute_com_chunk>`
* :doc:`contact/atom <compute_contact_atom>`
* :doc:`coord/atom <compute_coord_atom>`
* :doc:`coord/atom (k) <compute_coord_atom>`
* :doc:`damage/atom <compute_damage_atom>`
* :doc:`dihedral <compute_dihedral>`
* :doc:`dihedral/local <compute_dihedral_local>`
@ -79,16 +79,13 @@ KOKKOS, o = USER-OMP, t = OPT.
* :doc:`ke/atom/eff <compute_ke_atom_eff>`
* :doc:`ke/eff <compute_ke_eff>`
* :doc:`ke/rigid <compute_ke_rigid>`
* :doc:`meso/e/atom <compute_meso_e_atom>`
* :doc:`meso/rho/atom <compute_meso_rho_atom>`
* :doc:`meso/t/atom <compute_meso_t_atom>`
* :doc:`mesont <compute_mesont>`
* :doc:`momentum <compute_momentum>`
* :doc:`msd <compute_msd>`
* :doc:`msd/chunk <compute_msd_chunk>`
* :doc:`msd/nongauss <compute_msd_nongauss>`
* :doc:`omega/chunk <compute_omega_chunk>`
* :doc:`orientorder/atom <compute_orientorder_atom>`
* :doc:`orientorder/atom (k) <compute_orientorder_atom>`
* :doc:`pair <compute_pair>`
* :doc:`pair/local <compute_pair_local>`
* :doc:`pe <compute_pe>`
@ -134,6 +131,9 @@ KOKKOS, o = USER-OMP, t = OPT.
* :doc:`sna/atom <compute_sna_atom>`
* :doc:`snad/atom <compute_sna_atom>`
* :doc:`snav/atom <compute_sna_atom>`
* :doc:`sph/e/atom <compute_sph_e_atom>`
* :doc:`sph/rho/atom <compute_sph_rho_atom>`
* :doc:`sph/t/atom <compute_sph_t_atom>`
* :doc:`spin <compute_spin>`
* :doc:`stress/atom <compute_stress_atom>`
* :doc:`stress/mop <compute_stress_mop>`
@ -162,5 +162,6 @@ KOKKOS, o = USER-OMP, t = OPT.
* :doc:`torque/chunk <compute_torque_chunk>`
* :doc:`vacf <compute_vacf>`
* :doc:`vcm/chunk <compute_vcm_chunk>`
* :doc:`viscosity/cos <compute_viscosity_cos>`
* :doc:`voronoi/atom <compute_voronoi_atom>`
* :doc:`xrd <compute_xrd>`

5
doc/src/Commands_fix.rst
View File

@ -22,6 +22,7 @@ OPT.
.. table_from_list::
:columns: 5
* :doc:`accelerate/cos <fix_accelerate_cos>`
* :doc:`adapt <fix_adapt>`
* :doc:`adapt/fep <fix_adapt_fep>`
* :doc:`addforce <fix_addforce>`
@ -94,9 +95,7 @@ OPT.
* :doc:`lb/viscous <fix_lb_viscous>`
* :doc:`lineforce <fix_lineforce>`
* :doc:`manifoldforce <fix_manifoldforce>`
* :doc:`meso <fix_meso>`
* :doc:`meso/move <fix_meso_move>`
* :doc:`meso/stationary <fix_meso_stationary>`
* :doc:`momentum (k) <fix_momentum>`
* :doc:`move <fix_move>`
* :doc:`mscg <fix_mscg>`
@ -201,6 +200,8 @@ OPT.
* :doc:`smd/move_tri_surf <fix_smd_move_triangulated_surface>`
* :doc:`smd/setvel <fix_smd_setvel>`
* :doc:`smd/wall_surface <fix_smd_wall_surface>`
* :doc:`sph <fix_sph>`
* :doc:`sph/stationary <fix_sph_stationary>`
* :doc:`spring <fix_spring>`
* :doc:`spring/chunk <fix_spring_chunk>`
* :doc:`spring/rg <fix_spring_rg>`

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

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/presets/minimal.cmake -D PKG_MISC=on ../cmake
cmake -C ../cmake/presets/clang.cmake -C ../cmake/presets/most.cmake ../cmake
cmake -C ../cmake/presets/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/presets/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

21
doc/src/Howto_viscosity.rst
View File

@ -1,10 +1,11 @@
Calculate viscosity
===================
The shear viscosity eta of a fluid can be measured in at least 5 ways
The shear viscosity eta of a fluid can be measured in at least 6 ways
using various options in LAMMPS. See the examples/VISCOSITY directory
for scripts that implement the 5 methods discussed here for a simple
Lennard-Jones fluid model. Also, see the :doc:`Howto kappa <Howto_kappa>` doc page for an analogous discussion for
Lennard-Jones fluid model and 1 method for SPC/E water model.
Also, see the :doc:`Howto kappa <Howto_kappa>` doc page for an analogous discussion for
thermal conductivity.
Eta is a measure of the propensity of a fluid to transmit momentum in
@ -130,9 +131,25 @@ time-integrated momentum fluxes play the role of Cartesian
coordinates, whose mean-square displacement increases linearly
with time at sufficiently long times.
The sixth is periodic perturbation method. It is also a non-equilibrium MD method.
However, instead of measure the momentum flux in response of applied velocity gradient,
it measures the velocity profile in response of applied stress.
A cosine-shaped periodic acceleration is added to the system via the
:doc:`fix accelerate/cos <fix_accelerate_cos>` command,
and the :doc:`compute viscosity/cos<compute_viscosity_cos>` command is used to monitor the
generated velocity profile and remove the velocity bias before thermostatting.
.. note::
An article by :ref:`(Hess) <Hess3>` discussed the accuracy and efficiency of these methods.
----------
.. _Daivis-viscosity:
**(Daivis and Todd)** Daivis and Todd, Nonequilibrium Molecular Dynamics (book),
Cambridge University Press, https://doi.org/10.1017/9781139017848, (2017).
.. _Hess3:
**(Hess)** Hess, B. The Journal of Chemical Physics 2002, 116 (1), 209-217.

68
doc/src/Install_linux.rst
View File

@ -24,12 +24,13 @@ allows you to install LAMMPS with a single command, and stay
up-to-date with the current version of LAMMPS by simply updating your
operating system.
To install the appropriate personal-package archive (PPA), do the
To install the appropriate personal-package archives (PPAs), do the
following once:
.. code-block:: bash
$ sudo add-apt-repository ppa:gladky-anton/lammps
$ sudo add-apt-repository ppa:openkim/latest
$ sudo apt-get update
To install LAMMPS do the following once:
@ -38,7 +39,7 @@ To install LAMMPS do the following once:
$ sudo apt-get install lammps-daily
This downloads an executable named "lmp_daily" to your box, which
This downloads an executable named ``lmp_daily`` to your box, which
can then be used in the usual way to run input scripts:
.. code-block:: bash
@ -60,11 +61,29 @@ To get a copy of the current documentation and examples:
$ sudo apt-get install lammps-daily-doc
which will download the doc files in
/usr/share/doc/lammps-daily-doc/doc and example problems in
/usr/share/doc/lammps-doc/examples.
``/usr/share/doc/lammps-daily-doc/doc`` and example problems in
``/usr/share/doc/lammps-doc/examples``.
Note that you may still wish to download the tarball to get potential
files and auxiliary tools.
To get a copy of the current potentials files:
.. code-block:: bash
$ sudo apt-get install lammps-daily-data
which will download the potentials files to
``/usr/share/lammps-daily/potentials``. The ``lmp_daily`` binary is
hard-coded to look for potential files in this directory (it does not
use the `LAMMPS_POTENTIALS` environment variable, as described
in :doc:`pair_coeff <pair_coeff>` command).
The ``lmp_daily`` binary is built with the :ref:`KIM package <kim>` which
results in the above command also installing the `kim-api` binaries when LAMMPS
is installed. In order to use potentials from `openkim.org <openkim_>`_, you
can install the `openkim-models` package
.. code-block:: bash
$ sudo apt-get install openkim-models
To un-install LAMMPS, do the following:
@ -72,17 +91,8 @@ To un-install LAMMPS, do the following:
$ sudo apt-get remove lammps-daily
Note that the lammps-daily executable is built with the following
sequence of make commands, as if you had done the same with the
unpacked tarball files in the src directory:
.. code-block:: bash
$ make yes-all
$ make no-lib
$ make mpi
Thus it builds with FFTW3 and OpenMPI.
Please use ``lmp_daily -help`` to see which compilation options, packages,
and styles are included in the binary.
Thanks to Anton Gladky (gladky.anton at gmail.com) for setting up this
Ubuntu package capability.
@ -103,14 +113,14 @@ linking to the C library interface (lammps-devel, lammps-mpich-devel,
lammps-openmpi-devel), the header for compiling programs using
the C library interface (lammps-headers), and the LAMMPS python
module for Python 3. All packages can be installed at the same
time and the name of the LAMMPS executable is *lmp* and *lmp_openmpi*
or *lmp_mpich* respectively. By default, *lmp* will refer to the
time and the name of the LAMMPS executable is ``lmp`` and ``lmp_openmpi``
or ``lmp_mpich`` respectively. By default, ``lmp`` will refer to the
serial executable, unless one of the MPI environment modules is loaded
("module load mpi/mpich-x86_64" or "module load mpi/openmpi-x86_64").
(``module load mpi/mpich-x86_64`` or ``module load mpi/openmpi-x86_64``).
Then the corresponding parallel LAMMPS executable can be used.
The same mechanism applies when loading the LAMMPS python module.
To install LAMMPS with OpenMPI and run an input in.lj with 2 CPUs do:
To install LAMMPS with OpenMPI and run an input ``in.lj`` with 2 CPUs do:
.. code-block:: bash
@ -118,10 +128,10 @@ To install LAMMPS with OpenMPI and run an input in.lj with 2 CPUs do:
$ module load mpi/openmpi-x86_64
$ mpirun -np 2 lmp -in in.lj
The "dnf install" command is needed only once. In case of a new LAMMPS
stable release, "dnf update" will automatically update to the newer
The ``dnf install`` command is needed only once. In case of a new LAMMPS
stable release, ``dnf update`` will automatically update to the newer
version as soon at the RPM files are built and uploaded to the download
mirrors. The "module load" command is needed once per (shell) session
mirrors. The ``module load`` command is needed once per (shell) session
or shell terminal instance, unless it is automatically loaded from the
shell profile.
@ -134,7 +144,7 @@ can install the `openkim-models` package
$ dnf install openkim-models
Please use "lmp -help" to see which compilation options, packages,
Please use ``lmp -help`` to see which compilation options, packages,
and styles are included in the binary.
Thanks to Christoph Junghans (LANL) for making LAMMPS available in Fedora.
@ -153,10 +163,10 @@ in the `Extra Packages for Enterprise Linux (EPEL) repository <https://fedorapro
for use with Red Hat Enterprise Linux (RHEL) or CentOS version 7.x
and compatible Linux distributions. Names of packages, executable,
and content are the same as described above for Fedora Linux.
But RHEL/CentOS 7.x uses the "yum" package manager instead of "dnf"
But RHEL/CentOS 7.x uses the ``yum`` package manager instead of ``dnf``
in Fedora 28.
Please use "lmp -help" to see which compilation options, packages,
Please use ``lmp -help`` to see which compilation options, packages,
and styles are included in the binary.
Thanks to Christoph Junghans (LANL) for making LAMMPS available in EPEL.
@ -176,13 +186,13 @@ in OpenSuse as of Leap 15.0. You can install the package with:
$ zypper install lammps
This includes support for OpenMPI. The name of the LAMMPS executable
is *lmp*\ . Thus to run an input in parallel on 2 CPUs you would do:
is ``lmp``. Thus to run an input in parallel on 2 CPUs you would do:
.. code-block:: bash
$ mpirun -np 2 lmp -in in.lj
Please use "lmp -help" to see which compilation options, packages,
Please use ``lmp -help`` to see which compilation options, packages,
and styles are included in the binary.
The LAMMPS binary is built with the :ref:`KIM package <kim>` which

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

252
doc/src/Modify_atom.rst
View File

@ -3,115 +3,169 @@ Atom styles
Classes that define an :doc:`atom style <atom_style>` are derived from
the AtomVec class and managed by the Atom class. The atom style
determines what attributes are associated with an atom. A new atom
style can be created if one of the existing atom styles does not
define all the attributes you need to store and communicate with
atoms.
determines what attributes are associated with an atom and
communicated when it is a ghost atom or migrates to a new processor.
A new atom style can be created if one of the existing atom styles
does not define all the attributes you need to store and communicate
with atoms.
Atom_vec_atomic.cpp is a simple example of an atom style.
Atom_vec_atomic.cpp is the simplest example of an atom style.
Examining the code for others will make these instructions more clear.
Here is a brief description of methods you define in your new derived
class. See atom_vec.h for details.
Note that the :doc:`atom style hybrid <atom_style>` command can be
used to define atoms or particles which have the union of properties
of individual styles. Also the :doc:`fix property/atom <fix_property_atom>`
command can be used to add a single property (e.g. charge
or a molecule ID) to a style that does not have it. It can also be
used to add custom properties to an atom, with options to communicate
them with ghost atoms or read them from a data file. Other LAMMPS
commands can access these custom properties, as can new pair, fix,
compute styles that are written to work with these properties. For
example, the :doc:`set <set>` command can be used to set the values of
custom per-atom properties from an input script. All of these methods
are less work than writing code for a new atom style.
+-------------------------+--------------------------------------------------------------------------------+
| init | one time setup (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| grow | re-allocate atom arrays to longer lengths (required) |
+-------------------------+--------------------------------------------------------------------------------+
| grow_reset | make array pointers in Atom and AtomVec classes consistent (required) |
+-------------------------+--------------------------------------------------------------------------------+
| copy | copy info for one atom to another atom's array locations (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack_comm | store an atom's info in a buffer communicated every timestep (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack_comm_vel | add velocity info to communication buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack_comm_hybrid | store extra info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack_comm | retrieve an atom's info from the buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack_comm_vel | also retrieve velocity info (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack_comm_hybrid | retrieve extra info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| pack_reverse | store an atom's info in a buffer communicating partial forces (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack_reverse_hybrid | store extra info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack_reverse | retrieve an atom's info from the buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack_reverse_hybrid | retrieve extra info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| pack_border | store an atom's info in a buffer communicated on neighbor re-builds (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack_border_vel | add velocity info to buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack_border_hybrid | store extra info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack_border | retrieve an atom's info from the buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack_border_vel | also retrieve velocity info (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack_border_hybrid | retrieve extra info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| pack_exchange | store all an atom's info to migrate to another processor (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack_exchange | retrieve an atom's info from the buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| size_restart | number of restart quantities associated with proc's atoms (required) |
+-------------------------+--------------------------------------------------------------------------------+
| pack_restart | pack atom quantities into a buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| unpack_restart | unpack atom quantities from a buffer (required) |
+-------------------------+--------------------------------------------------------------------------------+
| create_atom | create an individual atom of this style (required) |
+-------------------------+--------------------------------------------------------------------------------+
| data_atom | parse an atom line from the data file (required) |
+-------------------------+--------------------------------------------------------------------------------+
| data_atom_hybrid | parse additional atom info unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| data_vel | parse one line of velocity information from data file (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| data_vel_hybrid | parse additional velocity data unique to this atom style (optional) |
+-------------------------+--------------------------------------------------------------------------------+
| memory_usage | tally memory allocated by atom arrays (required) |
+-------------------------+--------------------------------------------------------------------------------+
If you follow these directions your new style will automatically work
in tandem with others via the :doc:`atom_style hybrid <atom_style>`
command.
The constructor of the derived class sets values for several variables
that you must set when defining a new atom style, which are documented
in atom_vec.h. New atom arrays are defined in atom.cpp. Search for
the word "customize" and you will find locations you will need to
modify.
The first step is to define a set of strings in the constructor of the
new derived class. Each string will have zero or more space-separated
variable names which are identical to those used in the atom.h header
file for per-atom properties. Note that some represent per-atom
vectors (q, molecule) while other are per-atom arrays (x,v). For all
but the last 2 strings you do not need to specify any of
(id,type,x,v,f). Those are included automatically as needed in the
other strings.
.. note::
.. list-table::
It is possible to add some attributes, such as a molecule ID, to
atom styles that do not have them via the :doc:`fix property/atom <fix_property_atom>` command. This command also
allows new custom attributes consisting of extra integer or
floating-point values to be added to atoms. See the :doc:`fix property/atom <fix_property_atom>` doc page for examples of cases
where this is useful and details on how to initialize, access, and
output the custom values.
* - fields_grow
- full list of properties which is allocated and stored
* - fields_copy
- list of properties to copy atoms are rearranged on-processor
* - fields_comm
- list of properties communicated to ghost atoms every step
* - fields_comm_vel
- additional properties communicated if :doc:`comm_modify vel <atom_style>` is used
* - fields_reverse
- list of properties summed from ghost atoms every step
* - fields_border
- list of properties communicated with ghost atoms every reneighboring step
* - fields_border_vel
- additional properties communicated if :doc:`comm_modify vel <atom_style>` is used
* - fields_exchange
- list of properties communicated when an atom migrates to another processor
* - fields_restart
- list of properties written/read to/from a restart file
* - fields_create
- list of properties defined when an atom is created by :doc:`create_atoms <create_atoms>`
* - fields_data_atom
- list of properties (in order) in the Atoms section of a data file, as read by :doc:`read_data <read_data>`
* - fields_data_vel
- list of properties (in order) in the Velocities section of a data file, as read by :doc:`read_data <read_data>`
New :doc:`pair styles <pair_style>`, :doc:`fixes <fix>`, or
:doc:`computes <compute>` can be added to LAMMPS, as discussed below.
The code for these classes can use the per-atom properties defined by
fix property/atom. The Atom class has a find_custom() method that is
useful in this context:
In these strings you can list variable names which LAMMPS already
defines (in some other atom style), or you can create new variable
names. You should not re-use a LAMMPS variable for something with
different meaning in your atom style. If the meaning is related, but
interpreted differently by your atom style, then using the same
variable name means a user should not use your style and the other
style together in a :doc:`atom_style hybrid <atom_style>` command.
Because there will only be one value of the variable and different
parts of LAMMPS will then likely use it differently. LAMMPS has
no way of checking for this.
.. code-block:: c++
If you are defining new variable names then make them descriptive and
unique to your new atom style. For example choosing "e" for energy is
a bad choice; it is too generic. A better choice would be "e_foo",
where "foo" is specific to your style.
int index = atom->find_custom(char *name, int &flag);
If any of the variable names in your new atom style do not exist in
LAMMPS, you need to add them to the src/atom.h and atom.cpp files.
The "name" of a custom attribute, as specified in the :doc:`fix property/atom <fix_property_atom>` command, is checked to verify
that it exists and its index is returned. The method also sets flag =
0/1 depending on whether it is an integer or floating-point attribute.
The vector of values associated with the attribute can then be
accessed using the returned index as
Search for the word "customize" or "customization" in these 2 files to
see where to add your variable. Adding a flag to the 2nd
customization section in atom.h is only necessary if your code (e.g. a
pair style) needs to check that a per-atom property is defined. These
flags should also be set in the constructor of the atom style child
class.
.. code-block:: c++
In atom.cpp, aside from the constructor and destructor, there are 3
methods that a new variable name or flag needs to be added to.
int *ivector = atom->ivector[index];
double *dvector = atom->dvector[index];
In Atom::peratom_create() when using the add_peratom() method, a
final length argument of 0 is for per-atom vectors, a length > 1 is
for per-atom arrays. Note the use of an extra per-thread flag and the
add_peratom_vary() method when last dimension of the array is
variable-length.
Ivector or dvector are vectors of length Nlocal = # of owned atoms,
which store the attributes of individual atoms.
Adding the variable name to Atom::extract() enable the per-atom data
to be accessed through the :doc:`LAMMPS library interface
<Howto_library>` by a calling code, including from :doc:`Python
<Python_head>`.
The constructor of the new atom style will also typically set a few
flags which are defined at the top of atom_vec.h. If these are
unclear, see how other atom styles use them.
The grow_pointers() method is also required to make
a copy of peratom data pointers, as explained in the code.
There are a number of other optional methods which your atom style can
implement. These are only needed if you need to do something
out-of-the-ordinary which the default operation of the AtomVec parent
class does not take care of. The best way to figure out why they are
sometimes useful is to look at how other atom styles use them.
* process_args = use if the atom style has arguments
* init = called before each run
* force_clear = called before force computations each timestep
A few atom styles define "bonus" data associated with some or all of
their particles, such as :doc:`atom_style ellipsoid or tri
<atom_style>`. These methods work with that data:
* copy_bonus
* clear_bonus
* pack_comm_bonus
* unpack_comm_bonus
* pack_border_bonus
* unpack_border_bonus
* pack_exchange_bonus
* unpack_exchange_bonus
* size_restart_bonus
* pack_restart_bonus
* unpack_restart_bonus
* data_atom_bonus
* memory_usage_bonus
The :doc:`atom_style body <atom_style>` command can define a particle
geometry with an arbitrary number of values. This method reads it
from a data file:
* data_body
These methods are called before or after operations handled by the
parent AtomVec class. They allow an atom style to do customized
operations on the per-atom values. For example :doc:`atom_style
sphere <atom_style>` reads a diameter and density of each particle
from a data file. But these need to be converted internally to a
radius and mass. That operation is done in the data_atom_post()
method.
* pack_restart_pre
* pack_restart_post
* unpack_restart_init
* create_atom_post
* data_atom_post
* pack_data_pre
* pack_data_post
These methods enable the :doc:`compute property/atom <compute_property_atom>`
command to access per-atom variables it does not
already define as arguments, so that they can be written to a dump
file or used by other LAMMPS commands.
* property_atom
* pack_property_atom

28
doc/src/Packages_details.rst
View File

@ -366,12 +366,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.
@ -393,13 +398,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)

152
doc/src/Speed_kokkos.rst
View File

@ -9,10 +9,7 @@ different back end languages such as CUDA, OpenMP, or Pthreads. The
Kokkos library also provides data abstractions to adjust (at compile
time) the memory layout of data structures like 2d and 3d arrays to
optimize performance on different hardware. For more information on
Kokkos, see `GitHub <https://github.com/kokkos/kokkos>`_. Kokkos is
part of `Trilinos <https://www.trilinos.org/>`_. The Kokkos
library was written primarily by Carter Edwards, Christian Trott, and
Dan Sunderland (all Sandia).
Kokkos, see `GitHub <https://github.com/kokkos/kokkos>`_.
The LAMMPS KOKKOS package contains versions of pair, fix, and atom
styles that use data structures and macros provided by the Kokkos
@ -21,7 +18,7 @@ package was developed primarily by Christian Trott (Sandia) and Stan
Moore (Sandia) with contributions of various styles by others,
including Sikandar Mashayak (UIUC), Ray Shan (Sandia), and Dan Ibanez
(Sandia). For more information on developing using Kokkos abstractions
see the Kokkos programmers' guide at /lib/kokkos/doc/Kokkos_PG.pdf.
see the Kokkos `Wiki <https://github.com/kokkos/kokkos/wiki>`_.
Kokkos currently provides support for 3 modes of execution (per MPI
task). These are Serial (MPI-only for CPUs and Intel Phi), OpenMP
@ -31,33 +28,30 @@ compatible with specific hardware.
.. note::
Kokkos support within LAMMPS must be built with a C++11 compatible
compiler. This means GCC version 4.7.2 or later, Intel 14.0.4 or later, or
Clang 3.5.2 or later is required.
To build with Kokkos support for NVIDIA GPUs, the NVIDIA CUDA toolkit
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.
.. note::
To build with Kokkos support for NVIDIA GPUs, NVIDIA CUDA
software version 7.5 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.
Kokkos with CUDA currently implicitly assumes that the MPI library is
CUDA-aware. This is not always the case, especially when using
pre-compiled MPI libraries provided by a Linux distribution. This is
not a problem when using only a single GPU with a single MPI
rank. When running with multiple MPI ranks, you may see segmentation
faults without CUDA-aware MPI support. These can be avoided by adding
the flags :doc:`-pk kokkos cuda/aware off <Run_options>` to the
LAMMPS command line or by using the command :doc:`package kokkos
cuda/aware off <package>` in the input file.
.. note::
Kokkos with CUDA currently implicitly assumes that the MPI library
is CUDA-aware. This is not always the case, especially when using
pre-compiled MPI libraries provided by a Linux distribution. This is not
a problem when using only a single GPU with a single MPI rank. When
running with multiple MPI ranks, you may see segmentation faults without
CUDA-aware MPI support. These can be avoided by adding the flags :doc:`-pk kokkos cuda/aware off <Run_options>` to the LAMMPS command line or by
using the command :doc:`package kokkos cuda/aware off <package>` in the
input file.
**Building LAMMPS with the KOKKOS package:**
Building LAMMPS with the KOKKOS package
"""""""""""""""""""""""""""""""""""""""
See the :ref:`Build extras <kokkos>` doc page for instructions.
**Running LAMMPS with the KOKKOS package:**
Running LAMMPS with the KOKKOS package
""""""""""""""""""""""""""""""""""""""
All Kokkos operations occur within the context of an individual MPI
task running on a single node of the machine. The total number of MPI
@ -66,7 +60,8 @@ usual manner via the mpirun or mpiexec commands, and is independent of
Kokkos. E.g. the mpirun command in OpenMPI does this via its -np and
-npernode switches. Ditto for MPICH via -np and -ppn.
**Running on a multi-core CPU:**
Running on a multi-core CPU
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here is a quick overview of how to use the KOKKOS package
for CPU acceleration, assuming one or more 16-core nodes.
@ -142,7 +137,8 @@ atom. When using the Kokkos Serial back end or the OpenMP back end with
a single thread, no duplication or atomic operations are used. For CUDA
and half neighbor lists, the KOKKOS package always uses atomic operations.
**Core and Thread Affinity:**
CPU Cores, Sockets and Thread Affinity
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When using multi-threading, it is important for performance to bind
both MPI tasks to physical cores, and threads to physical cores, so
@ -156,15 +152,16 @@ for your MPI installation), binding can be forced with these flags:
OpenMPI 1.8: mpirun -np 2 --bind-to socket --map-by socket ./lmp_openmpi ...
Mvapich2 2.0: mpiexec -np 2 --bind-to socket --map-by socket ./lmp_mvapich ...
For binding threads with KOKKOS OpenMP, use thread affinity
environment variables to force binding. With OpenMP 3.1 (gcc 4.7 or
later, intel 12 or later) setting the environment variable
OMP_PROC_BIND=true should be sufficient. In general, for best
performance with OpenMP 4.0 or better set OMP_PROC_BIND=spread and
OMP_PLACES=threads. For binding threads with the KOKKOS pthreads
option, compile LAMMPS the KOKKOS HWLOC=yes option as described below.
For binding threads with KOKKOS OpenMP, use thread affinity environment
variables to force binding. With OpenMP 3.1 (gcc 4.7 or later, intel 12
or later) setting the environment variable ``OMP_PROC_BIND=true`` should
be sufficient. In general, for best performance with OpenMP 4.0 or later
set ``OMP_PROC_BIND=spread`` and ``OMP_PLACES=threads``. For binding
threads with the KOKKOS pthreads option, compile LAMMPS with the hwloc
or libnuma support enabled as described in the :ref:`extra build options page <kokkos>`.
**Running on Knight's Landing (KNL) Intel Xeon Phi:**
Running on Knight's Landing (KNL) Intel Xeon Phi
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here is a quick overview of how to use the KOKKOS package for the
Intel Knight's Landing (KNL) Xeon Phi:
@ -222,7 +219,8 @@ threads/task as Nt. The product of these two values should be N, i.e.
them in "native" mode, not "offload" mode like the USER-INTEL package
supports.
**Running on GPUs:**
Running on GPUs
^^^^^^^^^^^^^^^
Use the "-k" :doc:`command-line switch <Run_options>` to specify the
number of GPUs per node. Typically the -np setting of the mpirun command
@ -257,7 +255,7 @@ one or more nodes, each with two GPUs:
running on GPUs is to use "full" neighbor lists and set the Newton flag
to "off" for both pairwise and bonded interactions, along with threaded
communication. When running on Maxwell or Kepler GPUs, this will
typically be best. For Pascal GPUs, using "half" neighbor lists and
typically be best. For Pascal GPUs and beyond, using "half" neighbor lists and
setting the Newton flag to "on" may be faster. For many pair styles,
setting the neighbor binsize equal to twice the CPU default value will
give speedup, which is the default when running on GPUs. Use the "-pk
@ -270,13 +268,6 @@ one or more nodes, each with two GPUs:
mpirun -np 2 lmp_kokkos_cuda_openmpi -k on g 2 -sf kk -pk kokkos newton on neigh half binsize 2.8 -in in.lj # Newton on, half neighbor list, set binsize = neighbor ghost cutoff
.. note::
For good performance of the KOKKOS package on GPUs, you must
have Kepler generation GPUs (or later). The Kokkos library exploits
texture cache options not supported by Telsa generation GPUs (or
older).
.. note::
When using a GPU, you will achieve the best performance if your
@ -293,7 +284,8 @@ one or more nodes, each with two GPUs:
kspace, etc., you must set the environment variable CUDA_LAUNCH_BLOCKING=1.
However, this will reduce performance and is not recommended for production runs.
**Run with the KOKKOS package by editing an input script:**
Run with the KOKKOS package by editing an input script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Alternatively the effect of the "-sf" or "-pk" switches can be
duplicated by adding the :doc:`package kokkos <package>` or :doc:`suffix kk <suffix>` commands to your input script.
@ -316,17 +308,24 @@ You only need to use the :doc:`package kokkos <package>` command if you
wish to change any of its option defaults, as set by the "-k on"
:doc:`command-line switch <Run_options>`.
**Using OpenMP threading and CUDA together (experimental):**
**Using OpenMP threading and CUDA together:**
With the KOKKOS package, both OpenMP multi-threading and GPUs can be
used together in a few special cases. In the Makefile, the
KOKKOS_DEVICES variable must include both "Cuda" and "OpenMP", as is
the case for /src/MAKE/OPTIONS/Makefile.kokkos_cuda_mpi
compiled and used together in a few special cases. In the makefile for
the conventional build, the KOKKOS_DEVICES variable must include both,
"Cuda" and "OpenMP", as is the case for ``/src/MAKE/OPTIONS/Makefile.kokkos_cuda_mpi``.
.. code-block:: bash
KOKKOS_DEVICES=Cuda,OpenMP
When building with CMake you need to enable both features as it is done
in the ``kokkos-cuda.cmake`` CMake preset file.
.. code-block:: bash
cmake ../cmake -DKokkos_ENABLE_CUDA=yes -DKokkos_ENABLE_OPENMP=yes
The suffix "/kk" is equivalent to "/kk/device", and for Kokkos CUDA,
using the "-sf kk" in the command line gives the default CUDA version
everywhere. However, if the "/kk/host" suffix is added to a specific
@ -360,7 +359,8 @@ suffix for kspace and bonds, angles, etc. in the input file and the
sure the environment variable CUDA_LAUNCH_BLOCKING is not set to "1"
so CPU/GPU overlap can occur.
**Speed-ups to expect:**
Performance to expect
"""""""""""""""""""""
The performance of KOKKOS running in different modes is a function of
your hardware, which KOKKOS-enable styles are used, and the problem
@ -377,52 +377,26 @@ Generally speaking, the following rules of thumb apply:
performance of a KOKKOS style is a bit slower than the USER-OMP
package.
* When running large number of atoms per GPU, KOKKOS is typically faster
than the GPU package.
than the GPU package when compiled for double precision. The benefit
of using single or mixed precision with the GPU package depends
significantly on the hardware in use and the simulated system and pair
style.
* When running on Intel hardware, KOKKOS is not as fast as
the USER-INTEL package, which is optimized for that hardware.
the USER-INTEL package, which is optimized for x86 hardware (not just
from Intel) and compilation with the Intel compilers. The USER-INTEL
package also can increase the vector length of vector instructions
by switching to single or mixed precision mode.
See the `Benchmark page <https://lammps.sandia.gov/bench.html>`_ of the
LAMMPS web site for performance of the KOKKOS package on different
hardware.
**Advanced Kokkos options:**
Advanced Kokkos options
"""""""""""""""""""""""
There are other allowed options when building with the KOKKOS package.
As explained on the :ref:`Build extras <kokkos>` doc page,
they can be set either as variables on the make command line or in
Makefile.machine, or they can be specified as CMake variables. Each
takes a value shown below. The default value is listed, which is set
in the lib/kokkos/Makefile.kokkos file.
* KOKKOS_DEBUG, values = *yes*\ , *no*\ , default = *no*
* KOKKOS_USE_TPLS, values = *hwloc*\ , *librt*\ , *experimental_memkind*, default = *none*
* KOKKOS_CXX_STANDARD, values = *c++11*\ , *c++1z*\ , default = *c++11*
* KOKKOS_OPTIONS, values = *aggressive_vectorization*, *disable_profiling*, default = *none*
* KOKKOS_CUDA_OPTIONS, values = *force_uvm*, *use_ldg*, *rdc*\ , *enable_lambda*, default = *enable_lambda*
KOKKOS_USE_TPLS=hwloc binds threads to hardware cores, so they do not
migrate during a simulation. KOKKOS_USE_TPLS=hwloc should always be
used if running with KOKKOS_DEVICES=Pthreads for pthreads. It is not
necessary for KOKKOS_DEVICES=OpenMP for OpenMP, because OpenMP
provides alternative methods via environment variables for binding
threads to hardware cores. More info on binding threads to cores is
given on the :doc:`Speed omp <Speed_omp>` doc page.
KOKKOS_USE_TPLS=librt enables use of a more accurate timer mechanism
on most Unix platforms. This library is not available on all
platforms.
KOKKOS_DEBUG is only useful when developing a Kokkos-enabled style
within LAMMPS. KOKKOS_DEBUG=yes enables printing of run-time
debugging information that can be useful. It also enables runtime
bounds checking on Kokkos data structures.
KOKKOS_CXX_STANDARD and KOKKOS_OPTIONS are typically not changed when
building LAMMPS.
KOKKOS_CUDA_OPTIONS are additional options for CUDA. The LAMMPS KOKKOS
package must be compiled with the *enable_lambda* option when using
GPUs.
There are other allowed options when building with the KOKKOS package
that can improve performance or assist in debugging or profiling.
They are explained on the :ref:`KOKKOS section of the build extras <kokkos>` doc page,
Restrictions
""""""""""""

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 |
+-----------------------------------------+-------------------------------------------------------+

38
doc/src/atom_style.rst
View File

@ -10,7 +10,7 @@ Syntax
atom_style style args
* style = *angle* or *atomic* or *body* or *bond* or *charge* or *dipole* or *dpd* or *edpd* or *mdpd* or *tdpd* or *electron* or *ellipsoid* or *full* or *line* or *meso* or *molecular* or *peri* or *smd* or *sphere* or *spin* or *tri* or *template* or *hybrid*
* style = *angle* or *atomic* or *body* or *bond* or *charge* or *dipole* or *dpd* or *edpd* or *electron* or *ellipsoid* or *full* or *line* or *mdpd* or *molecular* or *peri* or *smd* or *sph* or *sphere* or *spin* or *tdpd* or *tri* or *template* or *hybrid*
.. parsed-literal::
@ -18,7 +18,9 @@ Syntax
*body* args = bstyle bstyle-args
bstyle = style of body particles
bstyle-args = additional arguments specific to the bstyle
see the :doc:`Howto body <Howto_body>` doc page for details
see the :doc:`Howto body <Howto_body>` doc
page for details
*sphere* arg = 0/1 (optional) for static/dynamic particle radii
*tdpd* arg = Nspecies
Nspecies = # of chemical species
*template* arg = template-ID
@ -91,10 +93,6 @@ quantities.
+--------------+-----------------------------------------------------+--------------------------------------+
| *edpd* | temperature and heat capacity | eDPD particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *mdpd* | density | mDPD particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *tdpd* | chemical concentration | tDPD particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *electron* | charge and spin and eradius | electronic force field |
+--------------+-----------------------------------------------------+--------------------------------------+
| *ellipsoid* | shape, quaternion, angular momentum | aspherical particles |
@ -103,7 +101,7 @@ quantities.
+--------------+-----------------------------------------------------+--------------------------------------+
| *line* | end points, angular velocity | rigid bodies |
+--------------+-----------------------------------------------------+--------------------------------------+
| *meso* | rho, e, cv | SPH particles |
| *mdpd* | density | mDPD particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *mesont* | mass, radius, length, buckling, connections, tube id| mesoscopic nanotubes |
+--------------+-----------------------------------------------------+--------------------------------------+
@ -113,10 +111,14 @@ quantities.
+--------------+-----------------------------------------------------+--------------------------------------+
| *smd* | volume, kernel diameter, contact radius, mass | solid and fluid SPH particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *sph* | rho, esph, cv | SPH particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *sphere* | diameter, mass, angular velocity | granular models |
+--------------+-----------------------------------------------------+--------------------------------------+
| *spin* | magnetic moment | system with magnetic particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *tdpd* | chemical concentration | tDPD particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *template* | template index, template atom | small molecules with fixed topology |
+--------------+-----------------------------------------------------+--------------------------------------+
| *tri* | corner points, angular momentum | rigid bodies |
@ -146,9 +148,16 @@ basis.
For the *sphere* style, the particles are spheres and each stores a
per-particle diameter and mass. If the diameter > 0.0, the particle
is a finite-size sphere. If the diameter = 0.0, it is a point
particle. Note that by use of the *disc* keyword with the :doc:`fix nve/sphere <fix_nve_sphere>`, :doc:`fix nvt/sphere <fix_nvt_sphere>`,
:doc:`fix nph/sphere <fix_nph_sphere>`, :doc:`fix npt/sphere <fix_npt_sphere>` commands, spheres can be effectively
treated as 2d discs for a 2d simulation if desired. See also the :doc:`set density/disc <set>` command.
particle. Note that by use of the *disc* keyword with the :doc:`fix
nve/sphere <fix_nve_sphere>`, :doc:`fix nvt/sphere <fix_nvt_sphere>`,
:doc:`fix nph/sphere <fix_nph_sphere>`, :doc:`fix npt/sphere
<fix_npt_sphere>` commands, spheres can be effectively treated as 2d
discs for a 2d simulation if desired. See also the :doc:`set
density/disc <set>` command. The *sphere* style takes an optional 0
or 1 argument. A value of 0 means the radius of each sphere is
constant for the duration of the simulation. A value of 1 means the
radii may vary dynamically during the simulation, e.g. due to use of
the :doc:`fix adapt <fix_adapt>` command.
For the *ellipsoid* style, the particles are ellipsoids and each
stores a flag which indicates whether it is a finite-size ellipsoid or
@ -191,8 +200,8 @@ particles which store a set of chemical concentration. An integer
"cc_species" is required to specify the number of chemical species
involved in a tDPD system.
The *meso* style is for smoothed particle hydrodynamics (SPH)
particles which store a density (rho), energy (e), and heat capacity
The *sph* style is for smoothed particle hydrodynamics (SPH)
particles which store a density (rho), energy (esph), and heat capacity
(cv).
The *smd* style is for a general formulation of Smooth Particle
@ -337,7 +346,7 @@ for energy-conserving dissipative particle dynamics (eDPD), many-body
dissipative particle dynamics (mDPD), and transport dissipative particle
dynamics (tDPD), respectively.
The *meso* style is part of the USER-SPH package for smoothed particle
The *sph* style is part of the USER-SPH package for smoothed particle
hydrodynamics (SPH). See `this PDF guide <USER/sph/SPH_LAMMPS_userguide.pdf>`_ to using SPH in LAMMPS.
The *mesont* style is part of the USER-MESONT package.
@ -355,7 +364,8 @@ Related commands
Default
"""""""
atom_style atomic
The default atom style is atomic. If atom_style sphere is used its
default argument is 0.
----------

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

46
doc/src/change_box.rst
View File

@ -142,24 +142,40 @@ new owning processors.
.. note::
The simulation box size/shape can be changed by arbitrarily
large amounts by this command. This is not a problem, except that the
The simulation box size/shape can be changed by arbitrarily large
amounts by this command. This is not a problem, except that the
mapping of processors to the simulation box is not changed from its
initial 3d configuration; see the :doc:`processors <processors>`
command. Thus, if the box size/shape changes dramatically, the
mapping of processors to the simulation box may not end up as optimal
as the initial mapping attempted to be.
mapping of processors to the simulation box may not end up as
optimal as the initial mapping attempted to be. You may wish to
re-balance the atoms by using the :doc:`balance <balance>` command
if that is the case.
.. note::
Because the keywords used in this command are applied one at a
time to the simulation box and the atoms in it, care must be taken
with triclinic cells to avoid exceeding the limits on skew after each
transformation in the sequence. If skew is exceeded before the final
transformation this can be avoided by changing the order of the
sequence, or breaking the transformation into two or more smaller
transformations. For more information on the allowed limits for box
skew see the discussion on triclinic boxes on :doc:`Howto triclinic <Howto_triclinic>` doc page.
You cannot use this command after reading a restart file (and
before a run is performed) if the restart file stored per-atom
information from a fix and any of the specified keywords change the
box size or shape or boundary conditions. This is because atoms
may be moved to new processors and the restart info will not
migrate with them. LAMMPS will generate an error if this could
happen. Only the *ortho* and *triclinic* keywords do not trigger
this error. One solution is to perform a "run 0" command before
using the change_box command. This clears the per-atom restart
data, whether it has been re-assigned to a new fix or not.
.. note::
Because the keywords used in this command are applied one at a time
to the simulation box and the atoms in it, care must be taken with
triclinic cells to avoid exceeding the limits on skew after each
transformation in the sequence. If skew is exceeded before the
final transformation this can be avoided by changing the order of
the sequence, or breaking the transformation into two or more
smaller transformations. For more information on the allowed
limits for box skew see the discussion on triclinic boxes on
:doc:`Howto triclinic <Howto_triclinic>` doc page.
----------
@ -283,6 +299,12 @@ match what is stored in the restart file. So if you wish to change
them, you should use the change_box command after the read_restart
command.
.. note::
Changing a periodic boundary to a non-periodic one will also
cause the image flag for that dimension to be reset to 0 for
all atoms. LAMMPS will print a warning message, if that happens.
----------
The *ortho* and *triclinic* keywords convert the simulation box to be

7
doc/src/compute.rst
View File

@ -225,9 +225,6 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` doc
* :doc:`ke/atom/eff <compute_ke_atom_eff>` - per-atom translational and radial kinetic energy in the electron force field model
* :doc:`ke/eff <compute_ke_eff>` - kinetic energy of a group of nuclei and electrons in the electron force field model
* :doc:`ke/rigid <compute_ke_rigid>` - translational kinetic energy of rigid bodies
* :doc:`meso/e/atom <compute_meso_e_atom>` - per-atom internal energy of Smooth-Particle Hydrodynamics atoms
* :doc:`meso/rho/atom <compute_meso_rho_atom>` - per-atom mesoscopic density of Smooth-Particle Hydrodynamics atoms
* :doc:`meso/t/atom <compute_meso_t_atom>` - per-atom internal temperature of Smooth-Particle Hydrodynamics atoms
* :doc:`momentum <compute_momentum>` - translational momentum
* :doc:`msd <compute_msd>` - mean-squared displacement of group of atoms
* :doc:`msd/chunk <compute_msd_chunk>` - mean-squared displacement for each chunk
@ -280,6 +277,9 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` doc
* :doc:`sna/atom <compute_sna_atom>` - bispectrum components for each atom
* :doc:`snad/atom <compute_sna_atom>` - derivative of bispectrum components for each atom
* :doc:`snav/atom <compute_sna_atom>` - virial contribution from bispectrum components for each atom
* :doc:`sph/e/atom <compute_sph_e_atom>` - per-atom internal energy of Smooth-Particle Hydrodynamics atoms
* :doc:`sph/rho/atom <compute_sph_rho_atom>` - per-atom density of Smooth-Particle Hydrodynamics atoms
* :doc:`sph/t/atom <compute_sph_t_atom>` - per-atom internal temperature of Smooth-Particle Hydrodynamics atoms
* :doc:`spin <compute_spin>` - magnetic quantities for a system of atoms having spins
* :doc:`stress/atom <compute_stress_atom>` - stress tensor for each atom
* :doc:`stress/mop <compute_stress_mop>` - normal components of the local stress tensor using the method of planes
@ -308,6 +308,7 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` doc
* :doc:`torque/chunk <compute_torque_chunk>` - torque applied on each chunk
* :doc:`vacf <compute_vacf>` - velocity auto-correlation function of group of atoms
* :doc:`vcm/chunk <compute_vcm_chunk>` - velocity of center-of-mass for each chunk
* :doc:`viscosity/cos <compute_viscosity_cos>` - velocity profile under cosine-shaped acceleration
* :doc:`voronoi/atom <compute_voronoi_atom>` - Voronoi volume and neighbors for each atom
* :doc:`xrd <compute_xrd>` - x-ray diffraction intensity on a mesh of reciprocal lattice nodes

27
doc/src/compute_coord_atom.rst
View File

@ -3,6 +3,9 @@
compute coord/atom command
==========================
compute coord/atom/kk command
===================================
Syntax
""""""
@ -109,6 +112,30 @@ too frequently.
:doc:`special_bonds <special_bonds>` command that includes all pairs in
the neighbor list.
----------
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
----------
**Output info:**
For *cstyle* cutoff, this compute can calculate a per-atom vector or

40
doc/src/compute_orientorder_atom.rst
View File

@ -3,6 +3,9 @@
compute orientorder/atom command
================================
compute orientorder/atom/kk command
===================================
Syntax
""""""
@ -16,13 +19,14 @@ Syntax
.. parsed-literal::
keyword = *cutoff* or *nnn* or *degrees* or *components*
keyword = *cutoff* or *nnn* or *degrees* or *components* or *chunksize*
*cutoff* value = distance cutoff
*nnn* value = number of nearest neighbors
*degrees* values = nlvalues, l1, l2,...
*wl* value = yes or no
*wl/hat* value = yes or no
*components* value = ldegree
*chunksize* value = number of atoms in each pass
Examples
""""""""
@ -104,6 +108,14 @@ in conjunction with :doc:`compute coord_atom <compute_coord_atom>` to
calculate the ten Wolde's criterion to identify crystal-like
particles, as discussed in :ref:`ten Wolde <tenWolde2>`.
The optional keyword *chunksize* is only applicable when using the
the KOKKOS package and is ignored otherwise. This keyword controls
the number of atoms in each pass used to compute the bond-orientational
order parameters and is used to avoid running out of memory. For example
if there are 4000 atoms in the simulation and the *chunksize*
is set to 2000, the parameter calculation will be broken up
into two passes.
The value of :math:`Q_l` is set to zero for atoms not in the
specified compute group, as well as for atoms that have less than
*nnn* neighbors within the distance cutoff, unless *nnn* is NULL.
@ -128,6 +140,30 @@ too frequently.
:doc:`special_bonds <special_bonds>` command that includes all pairs in
the neighbor list.
----------
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
----------
**Output info:**
This compute calculates a per-atom array with *nlvalues* columns,
@ -165,7 +201,7 @@ Default
The option defaults are *cutoff* = pair style cutoff, *nnn* = 12,
*degrees* = 5 4 6 8 10 12 i.e. :math:`Q_4`, :math:`Q_6`, :math:`Q_8`, :math:`Q_{10}`, and :math:`Q_{12}`,
*wl* = no, *wl/hat* = no, and *components* off
*wl* = no, *wl/hat* = no, *components* off, and *chunksize* = 2000
----------

54
doc/src/compute_property_atom.rst
View File

@ -69,8 +69,8 @@ Syntax
.. parsed-literal::
PERI package per-atom properties:
vfrac = ???
s0 = ???
vfrac = volume fraction
s0 = max stretch of any bond a particle is part of
.. parsed-literal::
@ -83,11 +83,11 @@ Syntax
.. parsed-literal::
USER-SPH package per-atom properties:
rho = ???
drho = ???
e = ???
de = ???
cv = ???
rho = density of SPH particles
drho = change in density
e = energy
de = change in thermal energy
cv = heat capacity
.. parsed-literal::
@ -110,13 +110,17 @@ Description
Define a computation that simply stores atom attributes for each atom
in the group. This is useful so that the values can be used by other
:doc:`output commands <Howto_output>` that take computes as inputs. See
for example, the :doc:`compute reduce <compute_reduce>`, :doc:`fix ave/atom <fix_ave_atom>`, :doc:`fix ave/histo <fix_ave_histo>`, :doc:`fix ave/chunk <fix_ave_chunk>`, and :doc:`atom-style variable <variable>`
commands.
:doc:`output commands <Howto_output>` that take computes as inputs.
See for example, the :doc:`compute reduce <compute_reduce>`, :doc:`fix
ave/atom <fix_ave_atom>`, :doc:`fix ave/histo <fix_ave_histo>`,
:doc:`fix ave/chunk <fix_ave_chunk>`, and :doc:`atom-style variable
<variable>` commands.
The list of possible attributes is the same as that used by the :doc:`dump custom <dump>` command, which describes their meaning, with some
additional quantities that are only defined for certain :doc:`atom styles <atom_style>`. Basically, this augmented list gives an
input script access to any per-atom quantity stored by LAMMPS.
The list of possible attributes is the same as that used by the
:doc:`dump custom <dump>` command, which describes their meaning, with
some additional quantities that are only defined for certain
:doc:`atom styles <atom_style>`. Basically, this augmented list gives
an input script access to any per-atom quantity stored by LAMMPS.
The values are stored in a per-atom vector or array as discussed
below. Zeroes are stored for atoms not in the specified group or for
@ -134,8 +138,9 @@ particles and body particles and store the 4-vector quaternion
representing the orientation of each particle. See the :doc:`set <set>`
command for an explanation of the quaternion vector.
*End1x*\ , *end1y*\ , *end1z*\ , *end2x*\ , *end2y*\ , *end2z*\ , are defined for
line segment particles and define the end points of each line segment.
*End1x*\ , *end1y*\ , *end1z*\ , *end2x*\ , *end2y*\ , *end2z*\ , are
defined for line segment particles and define the end points of each
line segment.
*Corner1x*\ , *corner1y*\ , *corner1z*\ , *corner2x*\ , *corner2y*\ ,
*corner2z*\ , *corner3x*\ , *corner3y*\ , *corner3z*\ , are defined for
@ -146,14 +151,14 @@ number of explicit bonds assigned to an atom. Note that if the
:doc:`newton bond <newton>` command is set to *on*\ , which is the
default, then every bond in the system is assigned to only one of the
two atoms in the bond. Thus a bond between atoms I,J may be tallied
for either atom I or atom J. If :doc:`newton bond off <newton>` is set,
it will be tallied with both atom I and atom J.
for either atom I or atom J. If :doc:`newton bond off <newton>` is
set, it will be tallied with both atom I and atom J.
The *i_name* and *d_name* attributes refer to custom integer and
floating-point properties that have been added to each atom via the
:doc:`fix property/atom <fix_property_atom>` command. When that command
is used specific names are given to each attribute which are what is
specified as the "name" portion of *i_name* or *d_name*.
:doc:`fix property/atom <fix_property_atom>` command. When that
command is used specific names are given to each attribute which are
what is specified as the "name" portion of *i_name* or *d_name*.
**Output info:**
@ -162,8 +167,8 @@ on the number of input values. If a single input is specified, a
per-atom vector is produced. If two or more inputs are specified, a
per-atom array is produced where the number of columns = the number of
inputs. The vector or array can be accessed by any command that uses
per-atom values from a compute as input. See the :doc:`Howto output <Howto_output>` doc page for an overview of LAMMPS output
options.
per-atom values from a compute as input. See the :doc:`Howto output
<Howto_output>` doc page for an overview of LAMMPS output options.
The vector or array values will be in whatever :doc:`units <units>` the
corresponding attribute is in, e.g. velocity units for vx, charge
@ -180,7 +185,8 @@ Restrictions
Related commands
""""""""""""""""
:doc:`dump custom <dump>`, :doc:`compute reduce <compute_reduce>`, :doc:`fix ave/atom <fix_ave_atom>`, :doc:`fix ave/chunk <fix_ave_chunk>`,
:doc:`fix property/atom <fix_property_atom>`
:doc:`dump custom <dump>`, :doc:`compute reduce <compute_reduce>`,
:doc::doc:`fix ave/atom <fix_ave_atom>`, :doc:`fix ave/chunk
:doc:<fix_ave_chunk>`, `fix property/atom <fix_property_atom>`
**Default:** none

14
doc/src/compute_meso_e_atom.rst → doc/src/compute_sph_e_atom.rst
View File

@ -1,6 +1,6 @@
.. index:: compute meso/e/atom
.. index:: compute sph/e/atom
compute meso/e/atom command
compute sph/e/atom command
===========================
Syntax
@ -8,17 +8,17 @@ Syntax
.. parsed-literal::
compute ID group-ID meso/e/atom
compute ID group-ID sph/e/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* meso/e/atom = style name of this compute command
* sph/e/atom = style name of this compute command
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all meso/e/atom
compute 1 all sph/e/atom
Description
"""""""""""
@ -27,8 +27,8 @@ Define a computation that calculates the per-atom internal energy
for each atom in a group.
The internal energy is the energy associated with the internal degrees
of freedom of a mesoscopic particles, e.g. a Smooth-Particle
Hydrodynamics particle.
of freedom of an SPH particle, i.e. a Smooth-Particle Hydrodynamics
particle.
See `this PDF guide <USER/sph/SPH_LAMMPS_userguide.pdf>`_ to using SPH in
LAMMPS.

21
doc/src/compute_meso_rho_atom.rst → doc/src/compute_sph_rho_atom.rst
View File

@ -1,6 +1,6 @@
.. index:: compute meso/rho/atom
.. index:: compute sph/rho/atom
compute meso/rho/atom command
compute sph/rho/atom command
=============================
Syntax
@ -8,32 +8,31 @@ Syntax
.. parsed-literal::
compute ID group-ID meso/rho/atom
compute ID group-ID sph/rho/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* meso/rho/atom = style name of this compute command
* sph/rho/atom = style name of this compute command
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all meso/rho/atom
compute 1 all sph/rho/atom
Description
"""""""""""
Define a computation that calculates the per-atom mesoscopic density
for each atom in a group.
Define a computation that calculates the per-atom SPH density for each
atom in a group, i.e. a Smooth-Particle Hydrodynamics density.
The mesoscopic density is the mass density of a mesoscopic particle,
calculated by kernel function interpolation using "pair style
sph/rhosum".
The SPH density is the mass density of an SPH particle, calculated by
kernel function interpolation using "pair style sph/rhosum".
See `this PDF guide <USER/sph/SPH_LAMMPS_userguide.pdf>`_ to using SPH in
LAMMPS.
The value of the mesoscopic density will be 0.0 for atoms not in the
The value of the SPH density will be 0.0 for atoms not in the
specified compute group.
**Output info:**

14
doc/src/compute_meso_t_atom.rst → doc/src/compute_sph_t_atom.rst
View File

@ -1,6 +1,6 @@
.. index:: compute meso/t/atom
.. index:: compute sph/t/atom
compute meso/t/atom command
compute sph/t/atom command
===========================
Syntax
@ -8,17 +8,17 @@ Syntax
.. parsed-literal::
compute ID group-ID meso/t/atom
compute ID group-ID sph/t/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* meso/t/atom = style name of this compute command
* sph/t/atom = style name of this compute command
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all meso/t/atom
compute 1 all sph/t/atom
Description
"""""""""""
@ -27,8 +27,8 @@ Define a computation that calculates the per-atom internal temperature
for each atom in a group.
The internal temperature is the ratio of internal energy over the heat
capacity associated with the internal degrees of freedom of a mesoscopic
particles, e.g. a Smooth-Particle Hydrodynamics particle.
capacity associated with the internal degrees of freedom of an SPH
particles, i.e. a Smooth-Particle Hydrodynamics particle.
.. math::

18
doc/src/compute_stress_atom.rst
View File

@ -2,6 +2,7 @@
compute stress/atom command
===========================
compute centroid/stress/atom command
====================================
@ -223,15 +224,14 @@ The per-atom array values will be in pressure\*volume
Restrictions
""""""""""""
Currently, compute *centroid/stress/atom* does not support
pair styles with many-body interactions,
such as :doc:`Tersoff <pair_tersoff>`,
and LAMMPS will generate an error in such cases.
In principal, equivalent formulation
to that of angle, dihedral and improper contributions
in the virial :math:`W_{ab}` formula
can also be applied to the many-body pair styles,
and is planned in the future.
Currently (Spring 2020), compute *centroid/stress/atom* does not support
pair styles with many-body interactions, such as :doc:`Tersoff
<pair_tersoff>`, or pair styles with long-range Coulomb interactions.
LAMMPS will generate an error in such cases. In principal, equivalent
formulation to that of angle, dihedral and improper contributions in the
virial :math:`W_{ab}` formula can also be applied to the many-body pair
styles, and is planned in the future.
Related commands
""""""""""""""""

156
doc/src/compute_viscosity_cos.rst Normal file
View File

@ -0,0 +1,156 @@
.. index:: compute viscosity/cos
compute viscosity/cos command
=============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID viscosity/cos
* ID, group-ID are documented in :doc:`compute <compute>` command
* viscosity/cos = style name of this compute command
Examples
""""""""
.. code-block:: LAMMPS
compute cos all viscosity/cos
variable V equal c_cos[7]
variable A equal 0.02E-5
variable density equal density
variable lz equal lz
variable reciprocalViscosity equal v_V/${A}/v_density*39.4784/v_lz/v_lz*100
Description
"""""""""""
Define a computation that calculates the velocity amplitude of a group of atoms
with an cosine-shaped velocity profile and the temperature of them
after subtracting out the velocity profile before computing the kinetic energy.
A compute of this style can be used by any command that computes a temperature,
e.g. :doc:`thermo_modify <thermo_modify>`, :doc:`fix npt <fix_nh>`, etc.
This command together with :doc:`fix_accelerate/cos<fix_accelerate_cos>`
enables viscosity calculation with periodic perturbation method,
as described by :ref:`Hess<Hess1>`.
An acceleration along the x-direction is applied to the simulation system
by using :doc:`fix_accelerate/cos<fix_accelerate_cos>` command.
The acceleration is a periodic function along the z-direction:
.. math::
a_{x}(z) = A \cos \left(\frac{2 \pi z}{l_{z}}\right)
where :math:`A` is the acceleration amplitude, :math:`l_z` is the z-length
of the simulation box. At steady state, the acceleration generates
a velocity profile:
.. math::
v_{x}(z) = V \cos \left(\frac{2 \pi z}{l_{z}}\right)
The generated velocity amplitude :math:`V` is related to the
shear viscosity :math:`\eta` by:
.. math::
V = \frac{A \rho}{\eta}\left(\frac{l_{z}}{2 \pi}\right)^{2}
and it can be obtained from ensemble average of the velocity profile:
.. math::
V = \frac{\sum_i 2 m_{i} v_{i, x} \cos \left(\frac{2 \pi z_i}{l_{z}}\right)}{\sum_i m_{i}}
where :math:`m_i`, :math:`v_{i,x}` and :math:`z_i` are the mass,
x-component velocity and z coordinate of a particle.
After the cosine-shaped collective velocity in :math:`x` direction
has been subtracted for each atom, the temperature is calculated by the formula
KE = dim/2 N k T, where KE = total kinetic energy of the group of
atoms (sum of 1/2 m v\^2), dim = 2 or 3 = dimensionality of the
simulation, N = number of atoms in the group, k = Boltzmann constant,
and T = temperature.
A kinetic energy tensor, stored as a 6-element vector, is also
calculated by this compute for use in the computation of a pressure
tensor. The formula for the components of the tensor is the same as
the above formula, except that v\^2 is replaced by vx\*vy for the xy
component, etc. The 6 components of the vector are ordered xx, yy,
zz, xy, xz, yz.
The number of atoms contributing to the temperature is assumed to be
constant for the duration of the run; use the *dynamic* option of the
:doc:`compute_modify <compute_modify>` command if this is not the case.
However, in order to get meaningful result, the group ID of this compute should be all.
The removal of the cosine-shaped velocity component by this command is
essentially computing the temperature after a "bias" has been removed
from the velocity of the atoms. If this compute is used with a fix
command that performs thermostatting then this bias will be subtracted
from each atom, thermostatting of the remaining thermal velocity will
be performed, and the bias will be added back in. Thermostatting
fixes that work in this way include :doc:`fix nvt <fix_nh>`, :doc:`fix temp/rescale <fix_temp_rescale>`, :doc:`fix temp/berendsen <fix_temp_berendsen>`, and :doc:`fix langevin <fix_langevin>`.
This compute subtracts out degrees-of-freedom due to fixes that
constrain molecular motion, such as :doc:`fix shake <fix_shake>` and
:doc:`fix rigid <fix_rigid>`. This means the temperature of groups of
atoms that include these constraints will be computed correctly. If
needed, the subtracted degrees-of-freedom can be altered using the
*extra* option of the :doc:`compute_modify <compute_modify>` command.
See the :doc:`Howto thermostat <Howto_thermostat>` doc page for a
discussion of different ways to compute temperature and perform
thermostatting.
----------
**Output info:**
This compute calculates a global scalar (the temperature) and a global
vector of length 7, which can be accessed by indices 1-7.
The first 6 elements of the vector are the KE tensor,
and the 7-th is the cosine-shaped velocity amplitude :math:`V`,
which can be used to calculate the reciprocal viscosity, as shown in the example.
These values can be used by any command that uses global scalar or
vector values from a compute as input.
See the :doc:`Howto output <Howto_output>` doc page for an overview of LAMMPS output options.
The scalar value calculated by this compute is "intensive". The
first 6 elements of vector values are "extensive",
and the 7-th element of vector values is "intensive".
The scalar value will be in temperature :doc:`units <units>`. The
first 6 elements of vector values will be in energy :doc:`units <units>`.
The 7-th element of vector value will be in velocity :doc:`units <units>`.
Restrictions
""""""""""""
This command is only available when LAMMPS was built with the USER-MISC package.
Since this compute depends on :doc:`fix accelerate/cos <fix_accelerate_cos>` which can
only work for 3d systems, it cannot be used for 2d systems.
Related commands
""""""""""""""""
:doc:`fix accelerate/cos <fix_accelerate_cos>`
Default
"""""""
none
----------
.. _Hess1:
**(Hess)** Hess, B. The Journal of Chemical Physics 2002, 116 (1), 209-217.

5
doc/src/fix.rst
View File

@ -165,6 +165,7 @@ The individual style names on the :doc:`Commands fix <Commands_fix>` doc
page are followed by one or more of (g,i,k,o,t) to indicate which
accelerated styles exist.
* :doc:`accelerate/cos <fix_accelerate_cos>` - apply cosine-shaped acceleration to atoms
* :doc:`adapt <fix_adapt>` - change a simulation parameter over time
* :doc:`adapt/fep <fix_adapt_fep>` - enhanced version of fix adapt
* :doc:`addforce <fix_addforce>` - add a force to each atom
@ -237,9 +238,7 @@ accelerated styles exist.
* :doc:`lb/viscous <fix_lb_viscous>` -
* :doc:`lineforce <fix_lineforce>` - constrain atoms to move in a line
* :doc:`manifoldforce <fix_manifoldforce>` - restrain atoms to a manifold during minimization
* :doc:`meso <fix_meso>` - time integration for SPH/DPDE particles
* :doc:`meso/move <fix_meso_move>` - move mesoscopic SPH/SDPD particles in a prescribed fashion
* :doc:`meso/stationary <fix_meso_stationary>` -
* :doc:`momentum <fix_momentum>` - zero the linear and/or angular momentum of a group of atoms
* :doc:`move <fix_move>` - move atoms in a prescribed fashion
* :doc:`mscg <fix_mscg>` - apply MSCG method for force-matching to generate coarse grain models
@ -344,6 +343,8 @@ accelerated styles exist.
* :doc:`smd/move_tri_surf <fix_smd_move_triangulated_surface>` -
* :doc:`smd/setvel <fix_smd_setvel>` -
* :doc:`smd/wall_surface <fix_smd_wall_surface>` -
* :doc:`sph <fix_sph>` - time integration for SPH/DPDE particles
* :doc:`sph/stationary <fix_sph_stationary>` -
* :doc:`spring <fix_spring>` - apply harmonic spring force to group of atoms
* :doc:`spring/chunk <fix_spring_chunk>` - apply harmonic spring force to each chunk of atoms
* :doc:`spring/rg <fix_spring_rg>` - spring on radius of gyration of group of atoms

104
doc/src/fix_accelerate_cos.rst Normal file
View File

@ -0,0 +1,104 @@
.. index:: fix accelerate/cos
fix accelerate/cos command
==========================
Syntax
""""""
.. parsed-literal::
fix ID group-ID accelerate value
* ID, group-ID are documented in :doc:`fix <fix>` command
* accelerate/cos = style name of this fix command
* value = amplitude of acceleration (in unit of force/mass)
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all accelerate/cos 0.02e-5
Description
"""""""""""
Give each atom a acceleration in x-direction based on its z coordinate.
The acceleration is a periodic function along the z-direction:
.. math::
a_{x}(z) = A \cos \left(\frac{2 \pi z}{l_{z}}\right)
where :math:`A` is the acceleration amplitude, :math:`l_z` is the z-length
of the simulation box.
At steady state, the acceleration generates a velocity profile:
.. math::
v_{x}(z) = V \cos \left(\frac{2 \pi z}{l_{z}}\right)
The generated velocity amplitude :math:`V` is related to the
shear viscosity :math:`\eta` by:
.. math::
V = \frac{A \rho}{\eta}\left(\frac{l_{z}}{2 \pi}\right)^{2}
and it can be obtained from ensemble average of the velocity profile:
.. math::
V = \frac{\sum_i 2 m_{i} v_{i, x} \cos \left(\frac{2 \pi z_i}{l_{z}}\right)}{\sum_i m_{i}}
where :math:`m_i`, :math:`v_{i,x}` and :math:`z_i` are the mass,
x-component velocity and z coordinate of a particle.
The velocity amplitude :math:`V` can be calculated with :doc:`compute viscosity/cos <compute_viscosity_cos>`,
which enables viscosity calculation with periodic perturbation method,
as described by :ref:`Hess<Hess2>`.
Because the applied acceleration drives the system away from equilibration,
the calculated shear viscosity is lower than the intrinsic viscosity
due to the shear-thinning effect.
Extrapolation to zero acceleration should generally be performed to
predict the zero-shear viscosity.
As the shear stress decreases, the signal-noise ratio decreases rapidly,
the simulation time must be extended accordingly to get converged result.
In order to get meaningful result, the group ID of this fix should be all.
----------
**Restart, fix_modify, output, run start/stop, minimize info:**
No information about this fix is written to binary restart files.
None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands.
No parameter of this fix can be used with the start/stop keywords of the run command.
This fix is not invoked during energy minimization.
Restrictions
""""""""""""
This command is only available when LAMMPS was built with the USER-MISC package.
Since this fix depends on the z-coordinate of atoms, it cannot be used in 2d simulations.
Related commands
""""""""""""""""
:doc:`compute viscosity/cos <compute_viscosity_cos>`
Default
"""""""
none
----------
.. _Hess2:
**(Hess)** Hess, B. The Journal of Chemical Physics 2002, 116 (1), 209-217.

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

2
doc/src/fix_ave_correlate_long.rst
View File

@ -26,7 +26,7 @@ Syntax
v_name = global value calculated by an equal-style variable with name
* zero or more keyword/arg pairs may be appended
* keyword = *type* or *start* or *file* or *overwrite* or *title1* or *title2* or *ncorr* or *p* or *m*
* keyword = *type* or *start* or *file* or *overwrite* or *title1* or *title2* or *ncorr* or *nlen* or *ncount*
.. parsed-literal::

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

52
doc/src/fix_bond_react.rst Normal file → Executable file
View File

@ -158,7 +158,9 @@ The following comments pertain to each *react* argument (in other
words, can be customized for each reaction, or reaction step):
A check for possible new reaction sites is performed every *Nevery*
timesteps.
timesteps. *Nevery* can be specified with an equal-style
:doc:`variable <variable>`, whose value is rounded up to the nearest
integer.
Three physical conditions must be met for a reaction to occur. First,
a bonding atom pair must be identified within the reaction distance
@ -171,19 +173,29 @@ modified to match the post-reaction template.
A bonding atom pair will be identified if several conditions are met.
First, a pair of atoms I,J within the specified react-group-ID of type
itype and jtype must be separated by a distance between *Rmin* and
*Rmax*\ . It is possible that multiple bonding atom pairs are
identified: if the bonding atoms in the pre-reacted template are 1-2
neighbors, i.e. directly bonded, the farthest bonding atom partner is
set as its bonding partner; otherwise, the closest potential partner
is chosen. Then, if both an atom I and atom J have each other as their
bonding partners, these two atoms are identified as the bonding atom
pair of the reaction site. Once this unique bonding atom pair is
identified for each reaction, there could two or more reactions that
involve a given atom on the same timestep. If this is the case, only
one such reaction is permitted to occur. This reaction is chosen
randomly from all potential reactions. This capability allows e.g. for
different reaction pathways to proceed from identical reaction sites
with user-specified probabilities.
*Rmax*\ . *Rmin* and *Rmax* can be specified with equal-style
:doc:`variables <variable>`. For example, these reaction cutoffs can
be a function of the reaction conversion using the following commands:
.. code-block:: LAMMPS
variable rmax equal 0 # initialize variable before bond/react
fix myrxn all bond/react react myrxn1 all 1 0 v_rmax mol1 mol2 map_file.txt
variable rmax equal 3+f_myrxn[1]/100 # arbitrary function of reaction count
It is possible that multiple bonding atom pairs are identified: if the
bonding atoms in the pre-reacted template are 1-2 neighbors, i.e.
directly bonded, the farthest bonding atom partner is set as its
bonding partner; otherwise, the closest potential partner is chosen.
Then, if both an atom I and atom J have each other as their bonding
partners, these two atoms are identified as the bonding atom pair of
the reaction site. Once this unique bonding atom pair is identified
for each reaction, there could two or more reactions that involve a
given atom on the same timestep. If this is the case, only one such
reaction is permitted to occur. This reaction is chosen randomly from
all potential reactions. This capability allows e.g. for different
reaction pathways to proceed from identical reaction sites with
user-specified probabilities.
The pre-reacted molecule template is specified by a molecule command.
This molecule template file contains a sample reaction site and its
@ -419,7 +431,8 @@ it occurs:
The *prob* keyword can affect whether or not an eligible reaction
actually occurs. The fraction setting must be a value between 0.0 and
1.0. A uniform random number between 0.0 and 1.0 is generated and the
1.0, and can be specified with an equal-style :doc:`variable <variable>`.
A uniform random number between 0.0 and 1.0 is generated and the
eligible reaction only occurs if the random number is less than the
fraction. Up to N reactions are permitted to occur, as optionally
specified by the *max_rxn* keyword.
@ -489,10 +502,11 @@ local command.
**Restart, fix_modify, output, run start/stop, minimize info:**
Cumulative reaction counts for each reaction are written to :doc:`binary restart files <restart>`. These values are associated with the
reaction name (react-ID). Additionally, internally-created per-atom
properties are stored to allow for smooth restarts. None of the
:doc:`fix_modify <fix_modify>` options are relevant to this fix.
Cumulative reaction counts for each reaction are written to :doc:`binary restart files <restart>`.
These values are associated with the reaction name (react-ID).
Additionally, internally-created per-atom properties are stored to
allow for smooth restarts. None of the :doc:`fix_modify <fix_modify>`
options are relevant to this fix.
This fix computes one statistic for each *react* argument that it
stores in a global vector, of length 'number of react arguments', that

2
doc/src/fix_halt.rst
View File

@ -160,7 +160,7 @@ the :doc:`run <run>` command.
Restrictions
""""""""""""
The *diskfree* attribute is currently only supported on Linux and MacOS.
The *diskfree* attribute is currently only supported on Linux, MacOSX, and BSD.
Related commands
""""""""""""""""

32
doc/src/fix_heat.rst
View File

@ -47,16 +47,22 @@ and the specified geometric :doc:`region <region>` in order to have
energy added or subtracted to it. If not specified, then the atoms in
the group are affected wherever they may move to.
Heat addition/subtraction is performed every N timesteps. The *eflux*
parameter can be specified as a numeric constant or as a variable (see
below). If it is a numeric constant or equal-style variable which
evaluates to a scalar value, then the *eflux* determines the change in
aggregate energy of the entire group of atoms per unit time, e.g. in
eV/psec for :doc:`metal units <units>`. In this case it is an
"extensive" quantity, meaning its magnitude should be scaled with the
number of atoms in the group. Note that since *eflux* has per-time
units (i.e. it is a flux), this means that a larger value of N will
add/subtract a larger amount of energy each time the fix is invoked.
Heat addition/subtraction is performed every N timesteps.
The *eflux* parameter can be specified as a numeric constant or as an
equal- or atom-style :doc:`variable <variable>`. If the value is a
variable, it should be specified as v_name, where *name* is the variable
name. In this case, the variable will be evaluated each timestep, and
its current value(s) used to determine the flux.
If *eflux* is a numeric constant or equal-style variable which evaluates
to a scalar value, then *eflux* determines the change in aggregate energy
of the entire group of atoms per unit time, e.g. in eV/psec for
:doc:`metal units <units>`. In this case it is an "extensive" quantity,
meaning its magnitude should be scaled with the number of atoms in the
group. Note that since *eflux* also has per-time units (i.e. it is a
flux), this means that a larger value of N will add/subtract a larger
amount of energy each time the fix is invoked.
.. note::
@ -71,12 +77,6 @@ the energy flux for a single atom, again in units of energy per unit
time. In this case, each value is an "intensive" quantity, which need
not be scaled with the number of atoms in the group.
As mentioned above, the *eflux* parameter can be specified as an
equal-style or atom_style :doc:`variable <variable>`. If the value is a
variable, it should be specified as v_name, where name is the variable
name. In this case, the variable will be evaluated each timestep, and
its value(s) used to determine the flux.
Equal-style variables can specify formulas with various mathematical
functions, and include :doc:`thermo_style <thermo_style>` command
keywords for the simulation box parameters and timestep and elapsed

39
doc/src/fix_meso_move.rst
View File

@ -60,17 +60,19 @@ internal energy and extrapolated velocity are also updated.
.. note::
The particles affected by this fix should not be time integrated
by other fixes (e.g. :doc:`fix meso <fix_meso>`, :doc:`fix meso/stationary <fix_meso_stationary>`), since that will change their
The particles affected by this fix should not be time integrated by
other fixes (e.g. :doc:`fix sph <fix_sph>`, :doc:`fix
sph/stationary <fix_sph_stationary>`), since that will change their
positions and velocities twice.
.. note::
As particles move due to this fix, they will pass through periodic
boundaries and be remapped to the other side of the simulation box,
just as they would during normal time integration (e.g. via the :doc:`fix meso <fix_meso>` command). It is up to you to decide whether periodic
boundaries are appropriate with the kind of particle motion you are
prescribing with this fix.
just as they would during normal time integration (e.g. via the
:doc:`fix sph <fix_sph>` command). It is up to you to decide
whether periodic boundaries are appropriate with the kind of
particle motion you are prescribing with this fix.
.. note::
@ -100,7 +102,7 @@ specified, *V* is the specified velocity vector with components
specified. This style also sets the velocity of each particle to V =
(Vx,Vy,Vz). If any of the velocity components is specified as NULL,
then the position and velocity of that component is time integrated
the same as the :doc:`fix meso <fix_meso>` command would perform, using
the same as the :doc:`fix sph <fix_sph>` command would perform, using
the corresponding force component on the particle.
Note that the *linear* style is identical to using the *variable*
@ -128,7 +130,7 @@ elapsed since the fix was specified. This style also sets the
velocity of each particle to the time derivative of this expression.
If any of the amplitude components is specified as NULL, then the
position and velocity of that component is time integrated the same as
the :doc:`fix meso <fix_meso>` command would perform, using the
the :doc:`fix sph <fix_sph>` command would perform, using the
corresponding force component on the particle.
Note that the *wiggle* style is identical to using the *variable*
@ -180,15 +182,15 @@ particle.
Any of the 6 variables can be specified as NULL. If both the
displacement and velocity variables for a particular x,y,z component
are specified as NULL, then the position and velocity of that
component is time integrated the same as the :doc:`fix meso <fix_meso>`
component is time integrated the same as the :doc:`fix sph <fix_sph>`
command would perform, using the corresponding force component on the
particle. If only the velocity variable for a component is specified as
NULL, then the displacement variable will be used to set the position
of the particle, and its velocity component will not be changed. If only
the displacement variable for a component is specified as NULL, then
the velocity variable will be used to set the velocity of the particle,
and the position of the particle will be time integrated using that
velocity.
particle. If only the velocity variable for a component is specified
as NULL, then the displacement variable will be used to set the
position of the particle, and its velocity component will not be
changed. If only the displacement variable for a component is
specified as NULL, then the velocity variable will be used to set the
velocity of the particle, and the position of the particle will be
time integrated using that velocity.
The *units* keyword determines the meaning of the distance units used
to define the *linear* velocity and *wiggle* amplitude and *rotate*
@ -236,17 +238,18 @@ Restrictions
""""""""""""
This fix is part of the USER-SDPD package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` doc page for more info.
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` doc page for more info.
This fix requires that atoms store density and internal energy as
defined by the :doc:`atom_style meso <atom_style>` command.
defined by the :doc:`atom_style sph <atom_style>` command.
All particles in the group must be mesoscopic SPH/SDPD particles.
Related commands
""""""""""""""""
:doc:`fix move <fix_move>`, :doc:`fix meso <fix_meso>`,
:doc:`fix move <fix_move>`, :doc:`fix sph <fix_sph>`,
:doc:`displace_atoms <displace_atoms>`
Default

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

36
doc/src/fix_restrain.rst
View File

@ -17,10 +17,18 @@ Syntax
.. parsed-literal::
*bond* args = atom1 atom2 Kstart Kstop r0
*bond* args = atom1 atom2 Kstart Kstop r0start (r0stop)
atom1,atom2 = IDs of 2 atoms in bond
Kstart,Kstop = restraint coefficients at start/end of run (energy units)
r0 = equilibrium bond distance (distance units)
r0start = equilibrium bond distance at start of run (distance units)
r0stop = equilibrium bond distance at end of run (optional) (distance units). If not
specified it is assumed to be equal to r0start
*lbond* args = atom1 atom2 Kstart Kstop r0start (r0stop)
atom1,atom2 = IDs of 2 atoms in bond
Kstart,Kstop = restraint coefficients at start/end of run (energy units)
r0start = equilibrium bond distance at start of run (distance units)
r0stop = equilibrium bond distance at end of run (optional) (distance units). If not
specified it is assumed to be equal to r0start
*angle* args = atom1 atom2 atom3 Kstart Kstop theta0
atom1,atom2,atom3 = IDs of 3 atoms in angle, atom2 = middle atom
Kstart,Kstop = restraint coefficients at start/end of run (energy units)
@ -38,6 +46,7 @@ Examples
.. code-block:: LAMMPS
fix holdem all restrain bond 45 48 2000.0 2000.0 2.75
fix holdem all restrain lbond 45 48 2000.0 2000.0 2.75
fix holdem all restrain dihedral 1 2 3 4 2000.0 2000.0 120.0
fix holdem all restrain bond 45 48 2000.0 2000.0 2.75 dihedral 1 2 3 4 2000.0 2000.0 120.0
fix texas_holdem all restrain dihedral 1 2 3 4 0.0 2000.0 120.0 dihedral 1 2 3 5 0.0 2000.0 -120.0 dihedral 1 2 3 6 0.0 2000.0 0.0
@ -141,6 +150,29 @@ is included in :math:`K`.
----------
The *lbond* keyword applies a lower bound bond restraint to the specified atoms
using the same functional form used by the :doc:`bond_style harmonic <bond_harmonic>` command if the distance between
the atoms is smaller than the equilibrium bond distance and 0 otherwise. The potential associated with
the restraint is
.. math::
E = K (r - r_0)^2 ,if\;r < r_0
.. math::
E = 0 \qquad\quad\quad ,if\;r \ge r_0
with the following coefficients:
* :math:`K` (energy/distance\^2)
* :math:`r_0` (distance)
:math:`K` and :math:`r_0` are specified with the fix. Note that the usual 1/2 factor
is included in :math:`K`.
----------
The *angle* keyword applies an angle restraint to the specified atoms
using the same functional form used by the :doc:`angle_style harmonic <angle_harmonic>` command. The potential associated with
the restraint is

24
doc/src/fix_rigid_meso.rst
View File

@ -75,19 +75,21 @@ internal energy and extrapolated velocity are also updated.
.. note::
You should not update the particles in rigid bodies via other
time-integration fixes (e.g. :doc:`fix meso <fix_meso>`,
:doc:`fix meso/stationary <fix_meso_stationary>`), or you will have conflicting
updates to positions and velocities resulting in unphysical behavior in most
cases. When performing a hybrid simulation with some atoms in rigid bodies,
and some not, a separate time integration fix like :doc:`fix meso <fix_meso>`
should be used for the non-rigid particles.
time-integration fixes (e.g. :doc:`fix sph <fix_sph>`, :doc:`fix
sph/stationary <fix_sph_stationary>`), or you will have conflicting
updates to positions and velocities resulting in unphysical
behavior in most cases. When performing a hybrid simulation with
some atoms in rigid bodies, and some not, a separate time
integration fix like :doc:`fix sph <fix_sph>` should be used for
the non-rigid particles.
.. note::
These fixes are overkill if you simply want to hold a collection
of particles stationary or have them move with a constant velocity. To
hold particles stationary use :doc:`fix meso/stationary <fix_meso_stationary>` instead. If you would like to
move particles with a constant velocity use :doc:`fix meso/move <fix_meso_move>`.
These fixes are overkill if you simply want to hold a collection of
particles stationary or have them move with a constant velocity. To
hold particles stationary use :doc:`fix sph/stationary
<fix_sph_stationary>` instead. If you would like to move particles
with a constant velocity use :doc:`fix meso/move <fix_meso_move>`.
.. warning::
@ -346,7 +348,7 @@ package. It is only enabled if LAMMPS was built with both packages. See
the :doc:`Build package <Build_package>` doc page for more info.
This fix requires that atoms store density and internal energy as
defined by the :doc:`atom_style meso <atom_style>` command.
defined by the :doc:`atom_style sph <atom_style>` command.
All particles in the group must be mesoscopic SPH/SDPD particles.

17
doc/src/fix_meso.rst → doc/src/fix_sph.rst
View File

@ -1,6 +1,6 @@
.. index:: fix meso
.. index:: fix sph
fix meso command
fix sph command
================
Syntax
@ -8,25 +8,26 @@ Syntax
.. parsed-literal::
fix ID group-ID meso
fix ID group-ID sph
* ID, group-ID are documented in :doc:`fix <fix>` command
* meso = style name of this fix command
* sph = style name of this fix command
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all meso
fix 1 all sph
Description
"""""""""""
Perform time integration to update position, velocity, internal energy
and local density for atoms in the group each timestep. This fix is
needed to time-integrate mesoscopic systems where particles carry
internal variables such as SPH or DPDE.
needed to time-integrate SPH systems where particles carry internal
variables such as internal energy. SPH stands for Smoothed Particle
Hydrodynamics.
See `this PDF guide <USER/sph/SPH_LAMMPS_userguide.pdf>`_ to using SPH in
LAMMPS.
@ -48,6 +49,6 @@ LAMMPS was built with that package. See the :doc:`Build package <Build_package>
Related commands
""""""""""""""""
"fix meso/stationary"
:doc:`fix sph/stationary <fix_sph_stationary>`
**Default:** none

14
doc/src/fix_meso_stationary.rst → doc/src/fix_sph_stationary.rst
View File

@ -1,6 +1,6 @@
.. index:: fix meso/stationary
.. index:: fix sph/stationary
fix meso/stationary command
fix sph/stationary command
===========================
Syntax
@ -8,17 +8,17 @@ Syntax
.. parsed-literal::
fix ID group-ID meso/stationary
fix ID group-ID sph/stationary
* ID, group-ID are documented in :doc:`fix <fix>` command
* meso = style name of this fix command
* sph = style name of this fix command
Examples
""""""""
.. code-block:: LAMMPS
fix 1 boundary meso/stationary
fix 1 boundary sph/stationary
Description
"""""""""""
@ -27,7 +27,7 @@ Perform time integration to update internal energy and local density,
but not position or velocity for atoms in the group each timestep.
This fix is needed for SPH simulations to correctly time-integrate
fixed boundary particles which constrain a fluid to a given region in
space.
space. SPH stands for Smoothed Particle Hydrodynamics.
See `this PDF guide <USER/sph/SPH_LAMMPS_userguide.pdf>`_ to using SPH in
LAMMPS.
@ -49,6 +49,6 @@ LAMMPS was built with that package. See the :doc:`Build package <Build_package>
Related commands
""""""""""""""""
"fix meso"
:doc:`fix sph <fix_sph>`
**Default:** none

13
doc/src/fix_wall_body_polyhedron.rst
View File

@ -15,15 +15,14 @@ Syntax
* k_n = normal repulsion strength (force/distance units or pressure units - see discussion below)
* c_n = normal damping coefficient (force/distance units or pressure units - see discussion below)
* c_t = tangential damping coefficient (force/distance units or pressure units - see discussion below)
* wallstyle = *xplane* or *yplane* or *zplane* or *zcylinder*
* wallstyle = *xplane* or *yplane* or *zplane*
* args = list of arguments for a particular style
.. parsed-literal::
*xplane* or *yplane* args = lo hi
*xplane* or *yplane* or *zplane* args = lo hi
lo,hi = position of lower and upper plane (distance units), either can be NULL)
*zcylinder* args = radius
radius = cylinder radius (distance units)
* zero or more keyword/value pairs may be appended to args
* keyword = *wiggle*
@ -60,8 +59,7 @@ those specified with the :doc:`pair_style body/rounded/polyhedron <pair_body_rou
The *wallstyle* can be planar or cylindrical. The 3 planar options
specify a pair of walls in a dimension. Wall positions are given by
*lo* and *hi*\ . Either of the values can be specified as NULL if a
single wall is desired. For a *zcylinder* wallstyle, the cylinder's
axis is at x = y = 0.0, and the radius of the cylinder is specified.
single wall is desired.
Optionally, the wall can be moving, if the *wiggle* keyword is appended.
@ -71,8 +69,7 @@ particles. The arguments to the *wiggle* keyword specify a dimension
for the motion, as well as it's *amplitude* and *period*\ . Note that
if the dimension is in the plane of the wall, this is effectively a
shearing motion. If the dimension is perpendicular to the wall, it is
more of a shaking motion. A *zcylinder* wall can only be wiggled in
the z dimension.
more of a shaking motion.
Each timestep, the position of a wiggled wall in the appropriate *dim*
is set according to this equation:

24
doc/src/hyper.rst
View File

@ -51,19 +51,17 @@ each timestep. In the bond-boost hyperdynamics context, a "bond" is
not a covalent bond between a pair of atoms in a molecule. Rather it
is simply a pair of nearby atoms as discussed below.
Both global and local HD are described in :ref:`(Voter2013) <Voter2013>` by
Art Voter and collaborators. Similar to parallel replica dynamics
(PRD), global and local HD are methods for performing accelerated
dynamics that are suitable for infrequent-event systems that obey
first-order kinetics. A good overview of accelerated dynamics methods
for such systems in given in :ref:`(Voter2002) <Voter2002hd>` from the same
group. To quote from the review paper: "The dynamical evolution is
characterized by vibrational excursions within a potential basin,
punctuated by occasional transitions between basins." The transition
probability is characterized by p(t) = k\*exp(-kt) where k is the rate
constant. Running multiple replicas gives an effective enhancement in
the timescale spanned by the multiple simulations, while waiting for
an event to occur.
Both global and local HD are described in :ref:`(Voter2013)
<Voter2013>` by Art Voter and collaborators. Similar to parallel
replica dynamics (PRD), global and local HD are methods for performing
accelerated dynamics that are suitable for infrequent-event systems
that obey first-order kinetics. A good overview of accelerated
dynamics methods (AMD) for such systems in given in :ref:`(Voter2002)
<Voter2002hd>` from the same group. To quote from the review paper:
"The dynamical evolution is characterized by vibrational excursions
within a potential basin, punctuated by occasional transitions between
basins. The transition probability is characterized by p(t) =
k\*exp(-kt) where k is the rate constant."
Both HD and PRD produce a time-accurate trajectory that effectively
extends the timescale over which a system can be simulated, but they

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

2
doc/src/pair_cosine_squared.rst
View File

@ -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

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_momb.rst
View File

@ -31,7 +31,7 @@ Style *momb* computes pairwise van der Waals (vdW) and short-range
interactions using the Morse potential and :ref:`(Grimme) <Grimme>` method
implemented in the Many-Body Metal-Organic (MOMB) force field
described comprehensively in :ref:`(Fichthorn) <Fichthorn>` and
:ref:`(Zhou) <Zhou4>`. Grimme's method is widely used to correct for
:ref:`(Zhou) <Zhou5>`. Grimme's method is widely used to correct for
dispersion in density functional theory calculations.
.. math::
@ -76,6 +76,6 @@ Related commands
**(Fichthorn)** Fichthorn, Balankura, Qi, CrystEngComm, 18(29), 5410-5417 (2016).
.. _Zhou4:
.. _Zhou5:
**(Zhou)** Zhou, Saidi, Fichthorn, J Phys Chem C, 118(6), 3366-3374 (2014).

376
doc/src/pair_polymorphic.rst
View File

@ -18,21 +18,22 @@ Examples
.. code-block:: LAMMPS
pair_style polymorphic
pair_coeff * * TlBr_msw.polymorphic Tl Br
pair_coeff * * AlCu_eam.polymorphic Al Cu
pair_coeff * * GaN_tersoff.polymorphic Ga N
pair_coeff * * GaN_sw.polymorphic GaN
pair_coeff * * FeCH_BOP_I.poly Fe C H
pair_coeff * * TlBr_msw.poly Tl Br
pair_coeff * * CuTa_eam.poly Cu Ta
pair_coeff * * GaN_tersoff.poly Ga N
pair_coeff * * GaN_sw.poly Ga N
Description
"""""""""""
The *polymorphic* pair style computes a 3-body free-form potential
(:ref:`Zhou <Zhou3>`) for the energy E of a system of atoms as
(:ref:`Zhou3 <Zhou3>`) for the energy E of a system of atoms as
.. math::
E & = \frac{1}{2}\sum_{i=1}^{i=N}\sum_{j=1}^{j=N}\left[\left(1-\delta_{ij}\right)\cdot U_{IJ}\left(r_{ij}\right)-\left(1-\eta_{ij}\right)\cdot F_{IJ}\left(r_{ij}\right)\cdot V_{IJ}\left(r_{ij}\right)\right] \\
X_{ij} & = \sum_{k=i_1,k\neq i,j}^{i_N}W_{IK}\left(r_{ik}\right)\cdot G_{JIK}\left(\theta_{jik}\right)\cdot P_{IK}\left(\Delta r_{jik}\right) \\
E & = \frac{1}{2}\sum_{i=1}^{i=N}\sum_{j=1}^{j=N}\left[\left(1-\delta_{ij}\right)\cdot U_{IJ}\left(r_{ij}\right)-\left(1-\eta_{ij}\right)\cdot F_{IJ}\left(X_{ij}\right)\cdot V_{IJ}\left(r_{ij}\right)\right] \\
X_{ij} & = \sum_{k=i_1,k\neq j}^{i_N}W_{IK}\left(r_{ik}\right)\cdot G_{JIK}\left(\cos\theta_{jik}\right)\cdot P_{JIK}\left(\Delta r_{jik}\right) \\
\Delta r_{jik} & = r_{ij}-\xi_{IJ}\cdot r_{ik}
where I, J, K represent species of atoms i, j, and k, :math:`i_1, ...,
@ -42,230 +43,267 @@ Dirac constant (i.e., :math:`\delta_{ij} = 1` when :math:`i = j`, and
constant that can be set either to :math:`\eta_{ij} = \delta_{ij}` or
:math:`\eta_{ij} = 1 - \delta_{ij}` depending on the potential type,
:math:`U_{IJ}(r_{ij})`, :math:`V_{IJ}(r_{ij})`, :math:`W_{IK}(r_{ik})`
are pair functions, :math:`G_{JIK}(\cos(\theta))` is an angular
function, :math:`P_{IK}(\Delta r_{jik})` is a function of atomic spacing
differential :math:`\Delta r_{jik} = r_{ij} - \xi_{IJ} \cdot r_{ik}`
with :math:`\xi_{IJ}` being a pair-dependent parameter, and
are pair functions, :math:`G_{JIK}(\cos\theta_{jik})` is an angular
function, :math:`P_{JIK}(\Delta r_{jik})` is a function of atomic
spacing differential :math:`\Delta r_{jik} = r_{ij} - \xi_{IJ} \cdot
r_{ik}` with :math:`\xi_{IJ}` being a pair-dependent parameter, and
:math:`F_{IJ}(X_{ij})` is a function of the local environment variable
:math:`X_{ij}`. This generic potential is fully defined once the
constants :math:`\eta_{ij}` and :math:`\xi_{IJ}`, and the six functions
:math:`U_{IJ}(r_{ij})`, :math:`V_{IJ}(r_{ij})`, :math:`W_{IK}(r_{ik})`,
:math:`G_{JIK}(\cos(\theta))`, :math:`P_{IK}(\Delta r_{jik})`, and
:math:`F_{IJ}(X_{ij})` are given. Note that these six functions are all
one dimensional, and hence can be provided in an analytic or tabular
form. This allows users to design different potentials solely based on a
manipulation of these functions. For instance, the potential reduces to
Stillinger-Weber potential (:ref:`SW <SW>`) if we set
:math:`G_{JIK}(\cos\theta_{jik})`, :math:`P_{JIK}(\Delta r_{jik})`, and
:math:`F_{IJ}(X_{ij})` are given. Here LAMMPS uses a global parameter
:math:`\eta` to represent :math:`\eta_{ij}`. When :math:`\eta = 1`,
:math:`\eta_{ij} = 1 - \delta_{ij}`, otherwise :math:`\eta_{ij} =
\delta_{ij}`. Additionally, :math:`\eta = 3` indicates that the function
:math:`P_{JIK}(\Delta r)` depends on species I, J and K, otherwise
:math:`P_{JIK}(\Delta r) = P_{IK}(\Delta r)` only depends on species I
and K. Note that these six functions are all one dimensional, and hence
can be provided in a tabular form. This allows users to design different
potentials solely based on a manipulation of these functions. For
instance, the potential reduces to a Stillinger-Weber potential
(:ref:`SW <SW>`) if we set
.. math::
\left\{\begin{array}{l}
\eta_{ij} = \delta_{ij},\xi_{IJ}=0 \\
U_{IJ}\left(r\right)=A_{IJ}\cdot\epsilon_{IJ}\cdot \left(\frac{\sigma_{IJ}}{r}\right)^q\cdot \left[B_{IJ}\cdot \left(\frac{\sigma_{IJ}}{r}\right)^{p-q}-1\right]\cdot exp\left(\frac{\sigma_{IJ}}{r-a_{IJ}\cdot \sigma_{IJ}}\right) \\
V_{IJ}\left(r\right)=\sqrt{\lambda_{IJ}\cdot \epsilon_{IJ}}\cdot exp\left(\frac{\gamma_{IJ}\cdot \sigma_{IJ}}{r-a_{IJ}\cdot \sigma_{IJ}}\right) \\
F_{IJ}\left(X\right)=-X \\
P_{IJ}\left(\Delta r\right)=1 \\
W_{IJ}\left(r\right)=\sqrt{\lambda_{IJ}\cdot \epsilon_{IJ}}\cdot exp\left(\frac{\gamma_{IJ}\cdot \sigma_{IJ}}{r-a_{IJ}\cdot \sigma_{IJ}}\right) \\
G_{JIK}\left(\theta\right)=\left(cos\theta+\frac{1}{3}\right)^2
\end{array}\right.
\eta_{ij} & = \delta_{ij} (\eta = 2~or~\eta = 0),\xi_{IJ}=0 \\
U_{IJ}\left(r\right) & = A_{IJ}\cdot\epsilon_{IJ}\cdot \left(\frac{\sigma_{IJ}}{r}\right)^q\cdot \left[B_{IJ}\cdot \left(\frac{\sigma_{IJ}}{r}\right)^{p-q}-1\right]\cdot exp\left(\frac{\sigma_{IJ}}{r-a_{IJ}\cdot \sigma_{IJ}}\right) \\
V_{IJ}\left(r\right) & = \sqrt{\lambda_{IJ}\cdot \epsilon_{IJ}}\cdot exp\left(\frac{\gamma_{IJ}\cdot \sigma_{IJ}}{r-a_{IJ}\cdot \sigma_{IJ}}\right) \\
F_{IJ}\left(X\right) & = -X \\
P_{JIK}\left(\Delta r\right) & = P_{IK}\left(\Delta r\right) = 1 \\
W_{IJ}\left(r\right) & = \sqrt{\lambda_{IJ}\cdot \epsilon_{IJ}}\cdot exp\left(\frac{\gamma_{IJ}\cdot \sigma_{IJ}}{r-a_{IJ}\cdot \sigma_{IJ}}\right) \\
G_{JIK}\left(\cos\theta\right) & = \left(\cos\theta+\frac{1}{3}\right)^2
The potential reduces to Tersoff types of potential
(:ref:`Tersoff <Tersoff>` or :ref:`Albe <poly-Albe>`) if we set
The potential reduces to a Tersoff potential (:ref:`Tersoff <Tersoff>`
or :ref:`Albe <poly-Albe>`) if we set
.. math::
\left\{\begin{array}{l}
\eta_{ij}=\delta_{ij},\xi_{IJ}=1 \\
U_{IJ}\left(r\right)=\frac{D_{e,IJ}}{S_{IJ}-1}\cdot exp\left[-\beta_{IJ}\sqrt{2S_{IJ}\left(r-r_{e,IJ}\right)}\right]\cdot f_{c,IJ}\left(r\right) \\
V_{IJ}\left(r\right)=\frac{S_{IJ}\cdot D_{e,IJ}}{S_{IJ}-1}\cdot exp\left[-\beta_{IJ}\sqrt{\frac{2}{S_{IJ}}\left(r-r_{e,IJ}\right)}\right]\cdot f_{c,IJ}\left(r\right) \\
F_{IJ}\left(X\right)=\left(1+X\right)^{-\frac{1}{2}} \\
P_{IJ}\left(\Delta r\right)=exp\left(2\mu_{IK}\cdot \Delta r\right) \\
W_{IJ}\left(r\right)=f_{c,IK}\left(r\right) \\
G_{JIK}\left(\theta\right)=\gamma_{IK}\left[1+\frac{c_{IK}^2}{d_{IK}^2}-\frac{c_{IK}^2}{d_{IK}^2+\left(h_{IK}+cos\theta\right)^2}\right]
\end{array}\right.
\eta_{ij} & = \delta_{ij} (\eta = 2~or~\eta = 0),\xi_{IJ}=1 \\
U_{IJ}\left(r\right) & = \frac{D_{e,IJ}}{S_{IJ}-1}\cdot exp\left[-\beta_{IJ}\sqrt{2S_{IJ}}\left(r-r_{e,IJ}\right)\right]\cdot f_{c,IJ}\left(r\right) \\
V_{IJ}\left(r\right) & = \frac{S_{IJ}\cdot D_{e,IJ}}{S_{IJ}-1}\cdot exp\left[-\beta_{IJ}\sqrt{\frac{2}{S_{IJ}}}\left(r-r_{e,IJ}\right)\right]\cdot f_{c,IJ}\left(r\right) \\
F_{IJ}\left(X\right) & = \left(1+X\right)^{-\frac{1}{2}} \\
P_{JIK}\left(\Delta r\right) & = P_{IK}\left(\Delta r\right) = exp\left(2\mu_{IK}\cdot \Delta r\right) \\
W_{IJ}\left(r\right) & = f_{c,IJ}\left(r\right) \\
G_{JIK}\left(\cos\theta\right) & = \gamma_{IK}\left[1+\frac{c_{IK}^2}{d_{IK}^2}-\frac{c_{IK}^2}{d_{IK}^2+\left(h_{IK}+\cos\theta\right)^2}\right]
where
.. math::
f_{c,IJ}=\left\{\begin{array}{lr}
1, & r\leq r_{s,IJ} \\
\frac{1}{2}+\frac{1}{2} cos \left[\frac{\pi \left(r-r_{s,IJ}\right)}{r_{c,IJ}-r_{s,IJ}}\right], & r_{s,IJ}<r<r_{c,IJ} \\
0, & r \geq r_{c,IJ} \\
f_{c,IJ}\left(r\right)=\left\{\begin{array}{l}
1, r\leq R_{IJ}-D_{IJ} \\
\frac{1}{2}+\frac{1}{2}cos\left[\frac{\pi\left(r+D_{IJ}-R_{IJ}\right)}{2D_{IJ}}\right], R_{IJ}-D_{IJ} < r < R_{IJ}+D_{IJ} \\
0, r \geq R_{IJ}+D_{IJ}
\end{array}\right.
The potential reduces to Rockett-Tersoff (:ref:`Wang <Wang3>`) type if we set
The potential reduces to a modified Stillinger-Weber potential
(:ref:`Zhou3 <Zhou3>`) if we set
.. math::
\left\{\begin{array}{l}
\eta_{ij}=\delta_{ij},\xi_{IJ}=1 \\
U_{IJ}\left(r\right)=\left\{\begin{array}{lr}
A_{IJ}\cdot exp\left(-\lambda_{1,IJ}\cdot r\right)\cdot f_{c,IJ}\left(r\right), & r\leq r_{s,1,IJ} \\
A_{IJ}\cdot exp\left(-\lambda_{1,IJ}\cdot r\right)\cdot f_{c,IJ}\left(r\right)\cdot f_{c,1,IJ}\left(r\right), & r_{s,1,IJ}<r<r_{c,1,IJ} \\
0, & r\ge r_{c,1,IJ}
\end{array}\right. \\
V_{IJ}\left(r\right)=\left\{\begin{array}{lr}
B_{IJ} \cdot exp\left(-\lambda_{2,IJ}\cdot r\right)\cdot f_{c,IJ}\left(r\right), & r\le r_{s,1,IJ} \\
B_{IJ} \cdot exp\left(-\lambda_{2,IJ}\cdot r\right)\cdot f_{c,IJ}\left(r\right)+A_{IJ}\cdot exp\left(-\lambda_{1,IJ}\cdot r\right)\cdot & \\ ~~~~~~ f_{c,IJ}\left(r\right)\cdot \left[1-f_{c,1,IJ}\left(r\right)\right], & r_{s,1,IJ}<r<r_{c,1,IJ} \\
B_{IJ} \cdot exp\left(-\lambda_{2,IJ}\cdot r\right)\cdot f_{c,IJ}\left(r\right)+A_{IJ}\cdot exp\left(-\lambda_{1,IJ}\cdot r\right)\cdot & \\ ~~~~~~ f_{c,IJ}\left(r\right) & r \ge r_{c,1,IJ}
\end{array}\right. \\
F_{IJ}\left(X\right)=\left[1+\left(\beta_{IJ}\cdot X\right)^{n_{IJ}}\right]^{-\frac{1}{2n_{IJ}}} \\
P_{IJ}\left(\Delta r\right)=exp\left(\lambda_{3,IK}\cdot \Delta r^3\right) \\
W_{IJ}\left(r\right)=f_{c,IK}\left(r\right) \\
G_{JIK}\left(\theta\right)=1+\frac{c_{IK}^2}{d_{IK}^2}-\frac{c_{IK}^2}{d_{IK}^2+\left(h_{IK}+cos\theta\right)^2}
\end{array}\right.
\eta_{ij} & = \delta_{ij} (\eta = 2~or~\eta = 0),\xi_{IJ}=0 \\
U_{IJ}\left(r\right) & = \varphi_{R,IJ}\left(r\right)-\varphi_{A,IJ}\left(r\right) \\
V_{IJ}\left(r\right) & = u_{IJ}\left(r\right) \\
F_{IJ}\left(X\right) & = -X \\
P_{JIK}\left(\Delta r\right) & = P_{IK}\left(\Delta r\right) = 1 \\
W_{IJ}\left(r\right) & = u_{IJ}\left(r\right) \\
G_{JIK}\left(\cos\theta\right) & = g_{JIK}\left(\cos\theta\right)
The potential reduces to a Rockett-Tersoff potential (:ref:`Wang3
<Wang3>`) if we set
.. math::
f_{c,IJ}=\left\{\begin{array}{lr}
1, & r\leq r_{s,IJ} \\
\frac{1}{2}+\frac{1}{2} cos \left[\frac{\pi \left(r-r_{s,IJ}\right)}{r_{c,IJ}-r_{s,IJ}}\right], & r_{s,IJ}<r<r_{c,IJ} \\
0, & r \geq r_{c,IJ} \\
\end{array}\right.
\eta_{ij} & = \delta_{ij} (\eta = 2~or~\eta = 0),\xi_{IJ}=1 \\
U_{IJ}\left(r\right) & = A_{IJ}exp\left(-\lambda_{1,IJ}\cdot r\right)f_{c,IJ}\left(r\right)f_{ca,IJ}\left(r\right) \\
V_{IJ}\left(r\right) & = \left\{\begin{array}{l}B_{IJ}exp\left(-\lambda_{2,IJ}\cdot r\right)f_{c,IJ}\left(r\right)+ \\ A_{IJ}exp\left(-\lambda_{1,IJ}\cdot r\right)f_{c,IJ}\left(r\right) \left[1-f_{ca,IJ}\left(r\right)\right]\end{array} \right\} \\
F_{IJ}\left(X\right) & = \left[1+\left(\beta_{IJ}X\right)^{n_{IJ}}\right]^{-\frac{1}{2n_{IJ}}} \\
P_{JIK}\left(\Delta r\right) & = P_{IK}\left(\Delta r\right) = exp\left(\lambda_{3,IK}\cdot \Delta r^3\right) \\
W_{IJ}\left(r\right) & = f_{c,IJ}\left(r\right) \\
G_{JIK}\left(\cos\theta\right) & = 1+\frac{c_{IK}^2}{d_{IK}^2}-\frac{c_{IK}^2}{d_{IK}^2+\left(h_{IK}+\cos\theta\right)^2}
where :math:`f_{ca,IJ}(r)` is similar to the :math:`f_{c,IJ}(r)` defined
above:
.. math::
f_{c,1,IJ}=\left\{\begin{array}{lr}
1, & r\leq r_{s,1,IJ} \\
\frac{1}{2}+\frac{1}{2} cos \left[\frac{\pi \left(r-r_{s,1,IJ}\right)}{r_{c,1,IJ}-r_{s,1,IJ}}\right], & r_{s,1,IJ}<r<r_{c,1,IJ} \\
0, & r \geq r_{c,1,IJ} \\
f_{ca,IJ}\left(r\right)=\left\{\begin{array}{l}
1, r\leq R_{a,IJ}-D_{a,IJ} \\
\frac{1}{2}+\frac{1}{2}cos\left[\frac{\pi\left(r+D_{a,IJ}-R_{a,IJ}\right)}{2D_{a,IJ}}\right], R_{a,IJ}-D_{a,IJ} < r < R_{a,IJ}+D_{a,IJ} \\
0, r \geq R_{a,IJ}+D_{a,IJ}
\end{array}\right.
The potential becomes embedded atom method (:ref:`Daw <poly-Daw>`) if we set
The potential becomes the embedded atom method (:ref:`Daw <poly-Daw>`)
if we set
.. math::
\left\{\begin{array}{l}
\eta_{ij}=1-\delta_{ij},\xi_{IJ}=0 \\
U_{IJ}\left(r\right)=\phi_{IJ}\left(r\right) \\
V_{IJ}\left(r\right)=1 \\
F_{II}\left(X\right)=-2F_I\left(X\right) \\
P_{IJ}\left(\Delta r\right)=1 \\
W_{IJ}\left(r\right)=f_{K}\left(r\right) \\
G_{JIK}\left(\theta\right)=1
\end{array}\right.
\eta_{ij} & = 1-\delta_{ij} (\eta = 1),\xi_{IJ}=0 \\
U_{IJ}\left(r\right) & = \phi_{IJ}\left(r\right) \\
V_{IJ}\left(r\right) & = 1 \\
F_{II}\left(X\right) & = -2F_I\left(X\right) \\
P_{JIK}\left(\Delta r\right) & = P_{IK}\left(\Delta r\right) = 1 \\
W_{IJ}\left(r\right) & = f_{J}\left(r\right) \\
G_{JIK}\left(\cos\theta\right) & = 1
In the embedded atom method case, :math:`\phi_{IJ}(r_{ij})` is the pair
In the embedded atom method case, :math:`\phi_{IJ}(r)` is the pair
energy, :math:`F_I(X)` is the embedding energy, *X* is the local
electron density, and :math:`f_K(r)` is the atomic electron density function.
electron density, and :math:`f_J(r)` is the atomic electron density
function.
If the tabulated functions are created using the parameters of sw,
tersoff, and eam potentials, the polymorphic pair style will produce
the same global properties (energies and stresses) and the same forces
as the sw, tersoff, and eam pair styles. The polymorphic pair style
also produces the same atom properties (energies and stresses) as the
corresponding tersoff and eam pair styles. However, due to a different
partition of global properties to atom properties, the polymorphic
pair style will produce different atom properties (energies and
stresses) as the sw pair style. This does not mean that polymorphic
pair style is different from the sw pair style in this case. It just
means that the definitions of the atom energies and atom stresses are
different.
The potential reduces to another type of Tersoff potential (:ref:`Zhou4
<Zhou4>`) if we set
Only a single pair_coeff command is used with the polymorphic style
which specifies an potential file for all needed elements. These are
.. math::
\eta_{ij} & = \delta_{ij} (\eta = 3),\xi_{IJ}=1 \\
U_{IJ}\left(r\right) & = \frac{D_{e,IJ}}{S_{IJ}-1}\cdot exp\left[-\beta_{IJ}\sqrt{2S_{IJ}}\left(r-r_{e,IJ}\right)\right]\cdot f_{c,IJ}\left(r\right) \cdot T_{IJ}\left(r\right)+V_{ZBL,IJ}\left(r\right)\left[1-T_{IJ}\left(r\right)\right] \\
V_{IJ}\left(r\right) & = \frac{S_{IJ}\cdot D_{e,IJ}}{S_{IJ}-1}\cdot exp\left[-\beta_{IJ}\sqrt{\frac{2}{S_{IJ}}}\left(r-r_{e,IJ}\right)\right]\cdot f_{c,IJ}\left(r\right) \cdot T_{IJ}\left(r\right) \\
F_{IJ}\left(X\right) & = \left(1+X\right)^{-\frac{1}{2}} \\
P_{JIK}\left(\Delta r\right) & = \omega_{JIK} \cdot exp\left(\alpha_{JIK}\cdot \Delta r\right) \\
W_{IJ}\left(r\right) & = f_{c,IJ}\left(r\right) \\
G_{JIK}\left(\cos\theta\right) & = \gamma_{JIK}\left[1+\frac{c_{JIK}^2}{d_{JIK}^2}-\frac{c_{JIK}^2}{d_{JIK}^2+\left(h_{JIK}+\cos\theta\right)^2}\right] \\
T_{IJ}\left(r\right) & = \frac{1}{1+exp\left[-b_{f,IJ}\left(r-r_{f,IJ}\right)\right]} \\
V_{ZBL,IJ}\left(r\right) & = 14.4 \cdot \frac{Z_I \cdot Z_J}{r}\sum_{k=1}^{4}\mu_k \cdot exp\left[-\nu_k \left(Z_I^{0.23}+Z_J^{0.23}\right) r\right]
where :math:`f_{c,IJ}(r)` is the same as defined above. This Tersoff
potential differs from the one above because the :math:`P_{JIK}(\Delta
r)` function is now dependent on all three species I, J, and K.
If the tabulated functions are created using the parameters of
Stillinger-Weber, Tersoff, and EAM potentials, the polymorphic pair
style will produce the same global properties (energies and stresses)
and the same forces as the :doc:`sw <pair_sw>`, :doc:`tersoff
<pair_tersoff>`, and :doc:`eam <pair_eam>` pair styles. The polymorphic
pair style also produces the same per-atom properties (energies and
stresses) as the corresponding :doc:`tersoff <pair_tersoff>` and
:doc:`eam <pair_eam>` pair styles. However, due to a different
partitioning of global properties to per-atom properties, the
polymorphic pair style will produce different per-atom properties
(energies and stresses) as the :doc:`sw <pair_sw>` pair style. This does
not mean that polymorphic pair style is different from the sw pair
style. It just means that the definitions of the atom energies and atom
stresses are different.
Only a single pair_coeff command is used with the polymorphic pair style
which specifies a potential file for all needed elements. These are
mapped to LAMMPS atom types by specifying N additional arguments after
the filename in the pair_coeff command, where N is the number of
LAMMPS atom types:
the filename in the pair_coeff command, where N is the number of LAMMPS
atom types:
* filename
* N element names = mapping of Tersoff elements to atom types
* N element names = mapping of polymorphic potential elements to atom types
See the pair_coeff doc page for alternate ways to specify the path for
the potential file. Several files for polymorphic potentials are
included in the potentials directory of the LAMMPS distribution. They
the potential file. Several files for polymorphic potentials are
included in the potentials directory of the LAMMPS distribution. They
have a "poly" suffix.
As an example, imagine the SiC_tersoff.poly file has tabulated
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:
As an example, imagine the GaN_tersoff.poly file has tabulated functions
for Ga-N tersoff potential. If your LAMMPS simulation has 4 atoms types
and you want the 1st 3 to be Ga, and the 4th to be N, you would use the
following pair_coeff command:
.. code-block:: LAMMPS
pair_coeff * * SiC_tersoff.poly Si Si Si C
pair_coeff * * GaN_tersoff.poly Ga Ga Ga N
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
Si element in the polymorphic file. The final C argument maps LAMMPS
atom type 4 to the C element in the polymorphic file. If a mapping
value is specified as NULL, the mapping is not performed. This can be
used when an polymorphic potential is used as part of the hybrid pair
style. The NULL values are placeholders for atom types that will be
used with other potentials.
The first two arguments must be \* \* to span all pairs of LAMMPS atom
types. The first three Ga arguments map LAMMPS atom types 1,2,3 to the
Ga element in the polymorphic file. The final N argument maps LAMMPS
atom type 4 to the N element in the polymorphic file. If a mapping value
is specified as NULL, the mapping is not performed. This can be used
when an polymorphic potential is used as part of the hybrid pair
style. The NULL values are placeholders for atom types that will be used
with other potentials.
Potential files in the potentials directory of the LAMMPS distribution
have a ".poly" suffix. At the beginning of the files, an unlimited
number of lines starting with '#' are used to describe the potential
and are ignored by LAMMPS. The next line lists two numbers:
number of lines starting with '#' are used to describe the potential and
are ignored by LAMMPS. The next line lists two numbers:
.. parsed-literal::
ntypes :math:`\eta`
ntypes eta
Here ntypes represent total number of species defined in the potential
file, and :math:`\eta = 0` or 1. The number ntypes must equal the total
number of different species defined in the pair_coeff command. When
:math:`\eta = 1`, :math:\eta_{ij}` defined in the potential functions
above is set to :math:`1 - \delta_{ij}`, otherwise :math:`\eta_{ij}` is
set to :math:`\delta_{ij}`. The next ntypes lines each lists two numbers
and a character string representing atomic number, atomic mass, and name
of the species of the ntypes elements:
Here *ntypes* represent total number of species defined in the potential
file, :math:`\eta = 1` reduces to embedded atom method, :math:`\eta = 3`
assumes a three species dependent :math:`P_{JIK}(\Delta r)` function,
and all other values of :math:`\eta` assume a two species dependent
:math:`P_{JK}(\Delta r)` function. The value of *ntypes* must equal the
total number of different species defined in the pair_coeff command. The
next *ntypes* lines each lists two numbers and a character string
representing atomic number, atomic mass, and name of the species of the
ntypes elements:
.. parsed-literal::
atomic_number atomic-mass element (1)
atomic_number atomic-mass element (2)
atomic-number atomic-mass element-name(1)
atomic-number atomic-mass element-name(2)
...
atomic_number atomic-mass element (ntypes)
atomic-number atomic-mass element-name(ntypes)
The next line contains four numbers:
.. parsed-literal::
nr ntheta nx xmax
Here nr is total number of tabular points for radial functions U, V, W,
P, ntheta is total number of tabular points for the angular function G,
nx is total number of tabular points for the function F, xmax is a
maximum value of the argument of function F. Note that the pair
functions :math:`U_{IJ}(r)`, :math:`V_{IJ}(r)`, :math:`W_{IJ}(r)` are
uniformly tabulated between 0 and cutoff distance of the IJ pair,
:math:`G_{JIK}(\cos\theta)` is uniformly tabulated between -1 and 1,
:math:`P_{JIK}(\Delta r)` is uniformly tabulated between -rcmax and
rcmax where rcmax is the maximum cutoff distance of all pairs, and
:math:`F_{IJ}(X)` is uniformly tabulated between 0 and xmax. Linear
extrapolation is assumed if actual simulations exceed these ranges.
The next ntypes\*(ntypes+1)/2 lines contain two numbers:
.. parsed-literal::
cut :math:`xi` (1)
cut :math:`xi` (2)
cut xi(1)
cut xi(2)
...
cut :math:`xi` (ntypes\*(ntypes+1)/2)
cut xi(ntypes\*(ntypes+1)/2)
Here cut means the cutoff distance of the pair functions, :math:`\xi` is
the same as defined in the potential functions above. The
Here cut means the cutoff distance of the pair functions, "xi" is
:math:`\xi` as defined in the potential functions above. The
ntypes\*(ntypes+1)/2 lines are related to the pairs according to the
sequence of first ii (self) pairs, i = 1, 2, ..., ntypes, and then then
ij (cross) pairs, i = 1, 2, ..., ntypes-1, and j = i+1, i+2, ..., ntypes
sequence of first ii (self) pairs, i = 1, 2, ..., ntypes, and then ij
(cross) pairs, i = 1, 2, ..., ntypes-1, and j = i+1, i+2, ..., ntypes
(i.e., the sequence of the ij pairs follows 11, 22, ..., 12, 13, 14,
..., 23, 24, ...).
The final blocks of the potential file are the U, V, W, P, G, and F
functions are listed sequentially. First, U functions are given for
each of the ntypes\*(ntypes+1)/2 pairs according to the sequence
described above. For each of the pairs, nr values are listed. Next,
similar arrays are given for V, W, and P functions. Then G functions
are given for all the ntypes\*ntypes\*ntypes ijk triplets in a natural
sequence i from 1 to ntypes, j from 1 to ntypes, and k from 1 to
ntypes (i.e., ijk = 111, 112, 113, ..., 121, 122, 123 ..., 211, 212,
...). Each of the ijk functions contains ng values. Finally, the F
functions are listed for all ntypes\*(ntypes+1)/2 pairs, each
containing nx values. Either analytic or tabulated functions can be
specified. Currently, constant, exponential, sine and cosine analytic
functions are available which are specified with: constant c1 , where
f(x) = c1 exponential c1 c2 , where f(x) = c1 exp(c2\*x) sine c1 c2 ,
where f(x) = c1 sin(c2\*x) cos c1 c2 , where f(x) = c1 cos(c2\*x)
Tabulated functions are specified by spline n x1 x2, where n=number of
point, (x1,x2)=range and then followed by n values evaluated uniformly
over these argument ranges. The valid argument ranges of the
functions are between 0 <= r <= cut for the U(r), V(r), W(r)
functions, -cutmax <= delta_r <= cutmax for the P(delta_r) functions,
-1 <= :math:`\cos\theta` <= 1 for the G(:math:`\cos\theta`) functions,
and 0 <= X <= maxX for the F(X) functions.
In the final blocks of the potential file, U, V, W, P, G, and F
functions are listed sequentially. First, U functions are given for each
of the ntypes\*(ntypes+1)/2 pairs according to the sequence described
above. For each of the pairs, nr values are listed. Next, similar arrays
are given for V and W functions. If P functions depend only on pair
species, i.e., :math:`\eta \neq 3`, then P functions are also listed the
same way the next. If P functions depend on three species, i.e.,
:math:`\eta = 3`, then P functions are listed for all the
ntypes*ntypes*ntypes IJK triplets in a natural sequence I from 1 to
ntypes, J from 1 to ntypes, and K from 1 to ntypes (i.e., IJK = 111,
112, 113, ..., 121, 122, 123 ..., 211, 212, ...). Next, G functions are
listed for all the ntypes*ntypes*ntypes IJK triplets similarly. For each
of the G functions, ntheta values are listed. Finally, F functions are
listed for all the ntypes*(ntypes+1)/2 pairs in the same sequence as
described above. For each of the F functions, nx values are listed.
**Mixing, shift, table tail correction, restart**\ :
This pair styles does not support the :doc:`pair_modify <pair_modify>`
shift, table, and tail options.
This pair style does not write their information to :doc:`binary restart files <restart>`, since it is stored in potential files. Thus, you
need to re-specify the pair_style and pair_coeff commands in an input
script that reads a restart file.
This pair style does not write their information to :doc:`binary restart
files <restart>`, since it is stored in potential files. Thus, you need
to re-specify the pair_style and pair_coeff commands in an input script
that reads a restart file.
----------
@ -277,15 +315,15 @@ input script. If using read_data, atomic masses must be defined in the
atomic structure data file.
This pair style is part of the MANYBODY package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` doc page for more info.
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` doc page for more info.
This pair potential requires the :doc:`newtion <newton>` setting to be
"on" for pair interactions.
The potential files provided with LAMMPS (see the potentials
directory) are parameterized for metal :doc:`units <units>`. You can use
any LAMMPS units, but you would need to create your own potential
files.
The potential files provided with LAMMPS (see the potentials directory)
are parameterized for metal :doc:`units <units>`. You can use any LAMMPS
units, but you would need to create your own potential files.
Related commands
""""""""""""""""
@ -296,12 +334,15 @@ Related commands
.. _Zhou3:
**(Zhou)** X. W. Zhou, M. E. Foster, R. E. Jones, P. Yang, H. Fan, and
F. P. Doty, J. Mater. Sci. Res., 4, 15 (2015).
**(Zhou3)** X. W. Zhou, M. E. Foster, R. E. Jones, P. Yang, H. Fan, and F. P. Doty, J. Mater. Sci. Res., 4, 15 (2015).
.. _Zhou4:
**(Zhou4)** X. W. Zhou, M. E. Foster, J. A. Ronevich, and C. W. San Marchi, J. Comp. Chem., 41, 1299 (2020).
.. _SW:
**(SW)** F. H. Stillinger-Weber, and T. A. Weber, Phys. Rev. B, 31, 5262 (1985).
**(SW)** F. H. Stillinger, and T. A. Weber, Phys. Rev. B, 31, 5262 (1985).
.. _Tersoff:
@ -309,8 +350,7 @@ F. P. Doty, J. Mater. Sci. Res., 4, 15 (2015).
.. _poly-Albe:
**(Albe)** K. Albe, K. Nordlund, J. Nord, and A. Kuronen, Phys. Rev. B,
66, 035205 (2002).
**(Albe)** K. Albe, K. Nordlund, J. Nord, and A. Kuronen, Phys. Rev. B, 66, 035205 (2002).
.. _Wang3:

15
doc/src/pair_reaxc.rst
View File

@ -21,12 +21,13 @@ Syntax
.. parsed-literal::
keyword = *checkqeq* or *lgvdw* or *safezone* or *mincap*
keyword = *checkqeq* or *lgvdw* or *safezone* or *mincap* or *minhbonds*
*checkqeq* value = *yes* or *no* = whether or not to require qeq/reax fix
*enobonds* value = *yes* or *no* = whether or not to tally energy of atoms with no bonds
*lgvdw* value = *yes* or *no* = whether or not to use a low gradient vdW correction
*safezone* = factor used for array allocation
*mincap* = minimum size for array allocation
*minhbonds* = minimum size use for storing hydrogen bonds
Examples
""""""""
@ -146,11 +147,11 @@ zero. The latter behavior is usual not desired, as it causes
discontinuities in the potential energy when the bonding of an atom
drops to zero.
Optional keywords *safezone* and *mincap* are used for allocating
reax/c arrays. Increasing these values can avoid memory problems,
such as segmentation faults and bondchk failed errors, that could
occur under certain conditions. These keywords are not used by the
Kokkos version, which instead uses a more robust memory allocation
Optional keywords *safezone*\ , *mincap*\ , and *minhbonds* are used
for allocating reax/c arrays. Increasing these values can avoid memory
problems, such as segmentation faults and bondchk failed errors, that
could occur under certain conditions. These keywords are not used by
the Kokkos version, which instead uses a more robust memory allocation
scheme that checks if the sizes of the arrays have been exceeded and
automatically allocates more memory.
@ -352,7 +353,7 @@ Default
"""""""
The keyword defaults are checkqeq = yes, enobonds = yes, lgvdw = no,
safezone = 1.2, mincap = 50.
safezone = 1.2, mincap = 50, minhbonds = 25.
----------

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
@ -256,7 +257,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>` -
@ -316,7 +317,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>` -

23
doc/src/prd.rst
View File

@ -52,19 +52,16 @@ replicas of a system. One or more replicas can be used. The total
number of steps *N* to run can be interpreted in one of two ways; see
discussion of the *time* keyword below.
PRD is described in :ref:`(Voter1998) <Voter1998>` by Art Voter. Similar to
global or local hyperdynamics (HD), PRD is a method for performing
accelerated dynamics that is suitable for infrequent-event systems
that obey first-order kinetics. A good overview of accelerated
dynamics methods for such systems in given in this review paper
:ref:`(Voter2002) <Voter2002prd>` from Art's group. To quote from the
paper: "The dynamical evolution is characterized by vibrational
excursions within a potential basin, punctuated by occasional
transitions between basins." The transition probability is
characterized by p(t) = k\*exp(-kt) where k is the rate constant.
Running multiple replicas gives an effective enhancement in the
timescale spanned by the multiple simulations, while waiting for an
event to occur.
PRD is described in :ref:`(Voter1998) <Voter1998>` by Art Voter.
Similar to global or local hyperdynamics (HD), PRD is a method for
performing accelerated dynamics that is suitable for infrequent-event
systems that obey first-order kinetics. A good overview of
accelerated dynamics methods (AMD) for such systems in given in this
review paper :ref:`(Voter2002) <Voter2002prd>` from Art's group. To
quote from the paper: "The dynamical evolution is characterized by
vibrational excursions within a potential basin, punctuated by
occasional transitions between basins. The transition probability is
characterized by p(t) = k\*exp(-kt) where k is the rate constant."
Both PRD and HD produce a time-accurate trajectory that effectively
extends the timescale over which a system can be simulated, but they

Some files were not shown because too many files have changed in this diff Show More