diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 1b4cae3aaa..0e42635244 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -37,7 +37,7 @@ src/MESONT/* @iafoss
src/ML-HDNNP/* @singraber
src/ML-IAP/* @athomps
src/ML-PACE/* @yury-lysogorskiy
-src/ML-POD/* @exapde @rohskopf
+src/ML-POD/* @exapde
src/MOFFF/* @hheenen
src/MOLFILE/* @akohlmey
src/NETCDF/* @pastewka
@@ -65,9 +65,12 @@ src/MANYBODY/pair_nb3b_screened.* @flodesani
src/REPLICA/*_grem.* @dstelter92
src/EXTRA-COMPUTE/compute_stress_mop*.* @RomainVermorel
src/EXTRA-COMPUTE/compute_born_matrix.* @Bibobu @athomps
+src/EXTRA-FIX/fix_deform_pressure.* @jtclemm
src/MISC/*_tracker.* @jtclemm
src/MC/fix_gcmc.* @athomps
src/MC/fix_sgcmc.* @athomps
+src/REAXFF/compute_reaxff_atom.* @rbberger
+src/KOKKOS/compute_reaxff_atom_kokkos.* @rbberger
src/REPLICA/fix_pimd_langevin.* @Yi-FanLi
# core LAMMPS classes
@@ -80,7 +83,7 @@ src/bond.* @sjplimp
src/comm*.* @sjplimp
src/compute.* @sjplimp
src/dihedral.* @sjplimp
-src/domain.* @sjplimp
+src/domain.* @sjplimp @stanmoore1
src/dump*.* @sjplimp
src/error.* @sjplimp
src/finish.* @sjplimp
diff --git a/.github/workflows/unittest-macos.yml b/.github/workflows/unittest-macos.yml
index f9c2a838d6..b0bc4b2727 100644
--- a/.github/workflows/unittest-macos.yml
+++ b/.github/workflows/unittest-macos.yml
@@ -15,7 +15,7 @@ jobs:
build:
name: MacOS Unit Test
if: ${{ github.repository == 'lammps/lammps' }}
- runs-on: macos-latest
+ runs-on: macos-13
env:
CCACHE_DIR: ${{ github.workspace }}/.ccache
@@ -43,6 +43,8 @@ jobs:
working-directory: build
run: |
ccache -z
+ python3 -m venv macosenv
+ source macosenv/bin/activate
python3 -m pip install numpy
python3 -m pip install pyyaml
cmake -C ../cmake/presets/clang.cmake \
diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
index 835a54f382..f87c92396f 100644
--- a/cmake/CMakeLists.txt
+++ b/cmake/CMakeLists.txt
@@ -222,6 +222,10 @@ endif()
add_executable(lmp ${MAIN_SOURCES})
target_link_libraries(lmp PRIVATE lammps)
set_target_properties(lmp PROPERTIES OUTPUT_NAME ${LAMMPS_BINARY})
+# re-export all symbols for plugins
+if(PKG_PLUGIN AND (NOT ((CMAKE_SYSTEM_NAME STREQUAL "Windows"))))
+ set_target_properties(lmp PROPERTIES ENABLE_EXPORTS TRUE)
+endif()
install(TARGETS lmp EXPORT LAMMPS_Targets DESTINATION ${CMAKE_INSTALL_BINDIR})
option(CMAKE_VERBOSE_MAKEFILE "Generate verbose Makefiles" OFF)
@@ -428,6 +432,7 @@ if(BUILD_OMP)
(CMAKE_CXX_COMPILER_ID STREQUAL "IntelLLVM") OR (CMAKE_CXX_COMPILER_ID STREQUAL "XLClang") OR
((CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 10.0)) OR
((CMAKE_CXX_COMPILER_ID STREQUAL "Clang") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 10.0)) OR
+ ((CMAKE_CXX_COMPILER_ID STREQUAL "CrayClang") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 10.0)) OR
((CMAKE_CXX_COMPILER_ID STREQUAL "Intel") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 19.0)))
# GCC 9.x and later plus Clang 10.x and later implement strict OpenMP 4.0 semantics for consts.
# Intel 18.0 was tested to support both, so we switch to OpenMP 4+ from 19.x onward to be safe.
@@ -438,6 +443,21 @@ if(BUILD_OMP)
target_compile_definitions(lammps PRIVATE -DLAMMPS_OMP_COMPAT=${LAMMPS_OMP_COMPAT_LEVEL})
target_link_libraries(lammps PRIVATE OpenMP::OpenMP_CXX)
target_link_libraries(lmp PRIVATE OpenMP::OpenMP_CXX)
+
+ # this hack is required to correctly link with OpenMP support when using CrayClang version 15.0.2
+ # CrayClang is only directly recognized by version 3.28 and later
+ if(CMAKE_VERSION VERSION_LESS 3.28)
+ get_filename_component(_exe "${CMAKE_CXX_COMPILER}" NAME)
+ if((CMAKE_CXX_COMPILER_ID STREQUAL "Clang") AND (_exe STREQUAL "crayCC"))
+ set(CMAKE_SHARED_LINKER_FLAGS_${BTYPE} "${CMAKE_SHARED_LINKER_FLAGS_${BTYPE} -fopenmp")
+ set(CMAKE_STATIC_LINKER_FLAGS_${BTYPE} "${CMAKE_STATIC_LINKER_FLAGS_${BTYPE} -fopenmp")
+ endif()
+ else()
+ if(CMAKE_CXX_COMPILER_ID STREQUAL "CrayClang")
+ set(CMAKE_SHARED_LINKER_FLAGS_${BTYPE} "${CMAKE_SHARED_LINKER_FLAGS_${BTYPE} -fopenmp")
+ set(CMAKE_STATIC_LINKER_FLAGS_${BTYPE} "${CMAKE_STATIC_LINKER_FLAGS_${BTYPE} -fopenmp")
+ endif()
+ endif()
endif()
# lower C++ standard for fmtlib sources when using Intel classic compiler
@@ -552,12 +572,12 @@ endforeach()
########################################################################
# Basic system tests (standard libraries, headers, functions, types) #
########################################################################
-foreach(HEADER cmath)
- check_include_file_cxx(${HEADER} FOUND_${HEADER})
- if(NOT FOUND_${HEADER})
- message(FATAL_ERROR "Could not find needed header - ${HEADER}")
- endif(NOT FOUND_${HEADER})
-endforeach(HEADER)
+if (NOT ((CMAKE_CXX_COMPILER_ID STREQUAL "Intel") OR (CMAKE_CXX_COMPILER_ID STREQUAL "IntelLLVM")))
+ check_include_file_cxx(cmath FOUND_CMATH)
+ if(NOT FOUND_CMATH)
+ message(FATAL_ERROR "Could not find the required 'cmath' header")
+ endif(NOT FOUND_CMATH)
+endif()
# make the standard math library overrideable and autodetected (for systems that don't have it)
find_library(STANDARD_MATH_LIB m DOC "Standard Math library")
diff --git a/cmake/Modules/OpenCLLoader.cmake b/cmake/Modules/OpenCLLoader.cmake
index 4b5c5a1200..411058e0b1 100644
--- a/cmake/Modules/OpenCLLoader.cmake
+++ b/cmake/Modules/OpenCLLoader.cmake
@@ -1,6 +1,6 @@
message(STATUS "Downloading and building OpenCL loader library")
-set(OPENCL_LOADER_URL "${LAMMPS_THIRDPARTY_URL}/opencl-loader-2024.02.09.tar.gz" CACHE STRING "URL for OpenCL loader tarball")
-set(OPENCL_LOADER_MD5 "f3573cf9daa3558ba46fd5866517f38f" CACHE STRING "MD5 checksum of OpenCL loader tarball")
+set(OPENCL_LOADER_URL "${LAMMPS_THIRDPARTY_URL}/opencl-loader-2024.05.09.tar.gz" CACHE STRING "URL for OpenCL loader tarball")
+set(OPENCL_LOADER_MD5 "e7796826b21c059224fabe997e0f2075" CACHE STRING "MD5 checksum of OpenCL loader tarball")
mark_as_advanced(OPENCL_LOADER_URL)
mark_as_advanced(OPENCL_LOADER_MD5)
diff --git a/cmake/Modules/Packages/INTEL.cmake b/cmake/Modules/Packages/INTEL.cmake
index 006a23e7ac..e6755bf23b 100644
--- a/cmake/Modules/Packages/INTEL.cmake
+++ b/cmake/Modules/Packages/INTEL.cmake
@@ -111,6 +111,9 @@ if(PKG_KSPACE)
list(APPEND INTEL_SOURCES ${INTEL_SOURCES_DIR}/verlet_lrt_intel.cpp)
RegisterIntegrateStyle(${INTEL_SOURCES_DIR}/verlet_lrt_intel.h)
endif()
+if(PKG_ML-SNAP)
+ list(APPEND INTEL_SOURCES ${INTEL_SOURCES_DIR}/sna_intel.cpp)
+endif()
target_sources(lammps PRIVATE ${INTEL_SOURCES})
target_include_directories(lammps PRIVATE ${INTEL_SOURCES_DIR})
diff --git a/cmake/Modules/Packages/KOKKOS.cmake b/cmake/Modules/Packages/KOKKOS.cmake
index ce55c83b08..a2f462905a 100644
--- a/cmake/Modules/Packages/KOKKOS.cmake
+++ b/cmake/Modules/Packages/KOKKOS.cmake
@@ -45,8 +45,8 @@ if(DOWNLOAD_KOKKOS)
list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_CXX_EXTENSIONS=${CMAKE_CXX_EXTENSIONS}")
list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}")
include(ExternalProject)
- set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/4.2.00.tar.gz" CACHE STRING "URL for KOKKOS tarball")
- set(KOKKOS_MD5 "731647b61a4233f568d583702e9cd6d1" CACHE STRING "MD5 checksum of KOKKOS tarball")
+ set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/4.3.00.tar.gz" CACHE STRING "URL for KOKKOS tarball")
+ set(KOKKOS_MD5 "889dcea2b5ced3debdc5b0820044bdc4" CACHE STRING "MD5 checksum of KOKKOS tarball")
mark_as_advanced(KOKKOS_URL)
mark_as_advanced(KOKKOS_MD5)
GetFallbackURL(KOKKOS_URL KOKKOS_FALLBACK)
@@ -71,7 +71,7 @@ if(DOWNLOAD_KOKKOS)
add_dependencies(LAMMPS::KOKKOSCORE kokkos_build)
add_dependencies(LAMMPS::KOKKOSCONTAINERS kokkos_build)
elseif(EXTERNAL_KOKKOS)
- find_package(Kokkos 4.2.00 REQUIRED CONFIG)
+ find_package(Kokkos 4.3.00 REQUIRED CONFIG)
target_link_libraries(lammps PRIVATE Kokkos::kokkos)
else()
set(LAMMPS_LIB_KOKKOS_SRC_DIR ${LAMMPS_LIB_SOURCE_DIR}/kokkos)
@@ -139,8 +139,9 @@ if(PKG_KSPACE)
message(WARNING "Using KISS FFT with the CUDA backend of Kokkos may be sub-optimal.")
target_compile_definitions(lammps PRIVATE -DFFT_KOKKOS_KISS)
elseif(FFT_KOKKOS STREQUAL "CUFFT")
+ find_package(CUDAToolkit REQUIRED)
target_compile_definitions(lammps PRIVATE -DFFT_KOKKOS_CUFFT)
- target_link_libraries(lammps PRIVATE cufft)
+ target_link_libraries(lammps PRIVATE CUDA::cufft)
endif()
elseif(Kokkos_ENABLE_HIP)
if(NOT ((FFT_KOKKOS STREQUAL "KISS") OR (FFT_KOKKOS STREQUAL "HIPFFT")))
diff --git a/cmake/Modules/Packages/ML-IAP.cmake b/cmake/Modules/Packages/ML-IAP.cmake
index d6059c44b8..91b772efb5 100644
--- a/cmake/Modules/Packages/ML-IAP.cmake
+++ b/cmake/Modules/Packages/ML-IAP.cmake
@@ -10,6 +10,14 @@ endif()
option(MLIAP_ENABLE_PYTHON "Build ML-IAP package with Python support" ${MLIAP_ENABLE_PYTHON_DEFAULT})
+# if ML-PACE package *and* MLIAP with Python is enabled is included we may also include ML-PACE support in ML-IAP
+set(MLIAP_ENABLE_ACE_DEFAULT OFF)
+if(PKG_ML-PACE)
+ set(MLIAP_ENABLE_ACE_DEFAULT ON)
+endif()
+
+option(MLIAP_ENABLE_ACE "Build ML-IAP package with ACE support" ${MLIAP_ENABLE_ACE_DEFAULT})
+
if(MLIAP_ENABLE_PYTHON)
find_package(Cythonize REQUIRED)
find_package(Python COMPONENTS NumPy REQUIRED)
@@ -36,3 +44,10 @@ if(MLIAP_ENABLE_PYTHON)
target_compile_definitions(lammps PRIVATE -DMLIAP_PYTHON)
target_include_directories(lammps PRIVATE ${MLIAP_BINARY_DIR})
endif()
+
+if(MLIAP_ENABLE_ACE)
+ if(NOT PKG_ML-PACE)
+ message(FATAL_ERROR "Must enable ML-PACE package for including ACE support in ML-IAP")
+ endif()
+ target_compile_definitions(lammps PRIVATE -DMLIAP_ACE)
+endif()
diff --git a/cmake/presets/kokkos-cuda.cmake b/cmake/presets/kokkos-cuda.cmake
index 3205387044..878ce0c566 100644
--- a/cmake/presets/kokkos-cuda.cmake
+++ b/cmake/presets/kokkos-cuda.cmake
@@ -10,7 +10,7 @@ get_filename_component(NVCC_WRAPPER_CMD ${CMAKE_CURRENT_SOURCE_DIR}/../lib/kokko
set(CMAKE_CXX_COMPILER ${NVCC_WRAPPER_CMD} CACHE FILEPATH "" FORCE)
# If KSPACE is also enabled, use CUFFT for FFTs
-set(FFT_KOKKOS "CUFFT" CACHE STRING FORCE)
+set(FFT_KOKKOS "CUFFT" CACHE STRING "" FORCE)
# hide deprecation warnings temporarily for stable release
set(Kokkos_ENABLE_DEPRECATION_WARNINGS OFF CACHE BOOL "" FORCE)
diff --git a/cmake/presets/kokkos-hip.cmake b/cmake/presets/kokkos-hip.cmake
index ffc259a225..38bf27092f 100644
--- a/cmake/presets/kokkos-hip.cmake
+++ b/cmake/presets/kokkos-hip.cmake
@@ -13,7 +13,7 @@ set(CMAKE_CXX_COMPILER hipcc CACHE STRING "" FORCE)
set(CMAKE_TUNE_FLAGS "-munsafe-fp-atomics" CACHE STRING "" FORCE)
# If KSPACE is also enabled, use CUFFT for FFTs
-set(FFT_KOKKOS "HIPFFT" CACHE STRING FORCE)
+set(FFT_KOKKOS "HIPFFT" CACHE STRING "" FORCE)
# hide deprecation warnings temporarily for stable release
set(Kokkos_ENABLE_DEPRECATION_WARNINGS OFF CACHE BOOL "" FORCE)
diff --git a/doc/lammps.1 b/doc/lammps.1
index 0c7c9a0354..27ec20b1d3 100644
--- a/doc/lammps.1
+++ b/doc/lammps.1
@@ -1,7 +1,7 @@
-.TH LAMMPS "1" "7 February 2024" "2024-02-07"
+.TH LAMMPS "1" "17 April 2024" "2024-04-17"
.SH NAME
.B LAMMPS
-\- Molecular Dynamics Simulator. Version 7 February 2024
+\- Molecular Dynamics Simulator. Version 17 April 2024
.SH SYNOPSIS
.B lmp
@@ -297,7 +297,7 @@ the chapter on errors in the
manual gives some additional information about error messages, if possible.
.SH COPYRIGHT
-© 2003--2022 Sandia Corporation
+© 2003--2024 Sandia Corporation
This package is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
diff --git a/doc/src/Bibliography.rst b/doc/src/Bibliography.rst
index 4ed8e73dfe..9778340c94 100644
--- a/doc/src/Bibliography.rst
+++ b/doc/src/Bibliography.rst
@@ -877,6 +877,9 @@ Bibliography
**(PLUMED)**
G.A. Tribello, M. Bonomi, D. Branduardi, C. Camilloni and G. Bussi, Comp. Phys. Comm 185, 604 (2014)
+**(Pavlov)**
+D Pavlov, V Galigerov, D Kolotinskii, V Nikolskiy, V Stegailov, International Journal of High Performance Computing Applications, 38, 34-49 (2024).
+
**(Paquay)**
Paquay and Kusters, Biophys. J., 110, 6, (2016). preprint available at `arXiv:1411.3019 `_.
diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst
index 1f643a9d14..f66238c3c9 100644
--- a/doc/src/Build_extras.rst
+++ b/doc/src/Build_extras.rst
@@ -533,9 +533,6 @@ They must be specified in uppercase.
* - A64FX
- HOST
- ARMv8.2 with SVE Support
- * - WSM
- - HOST
- - Intel Westmere CPU (SSE 4.2)
* - SNB
- HOST
- Intel Sandy/Ivy Bridge CPU (AVX 1)
@@ -566,18 +563,15 @@ They must be specified in uppercase.
* - 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
+ * - RISCV_SG2042
+ - HOST
+ - SG2042 (RISC-V) CPU
* - KEPLER30
- GPU
- NVIDIA Kepler generation CC 3.0 GPU
@@ -666,7 +660,7 @@ They must be specified in uppercase.
- GPU
- Intel GPU Ponte Vecchio
-This list was last updated for version 4.2 of the Kokkos library.
+This list was last updated for version 4.3.0 of the Kokkos library.
.. tabs::
diff --git a/doc/src/Commands_bond.rst b/doc/src/Commands_bond.rst
index ef36b6b7c4..0c389df399 100644
--- a/doc/src/Commands_bond.rst
+++ b/doc/src/Commands_bond.rst
@@ -89,6 +89,7 @@ OPT.
* :doc:`cosine/shift (o) `
* :doc:`cosine/shift/exp (o) `
* :doc:`cosine/squared (o) `
+ * :doc:`cosine/squared/restricted (o) `
* :doc:`cross `
* :doc:`dipole (o) `
* :doc:`fourier (o) `
@@ -127,6 +128,7 @@ OPT.
* :doc:`charmmfsw (k) `
* :doc:`class2 (ko) `
* :doc:`cosine/shift/exp (o) `
+ * :doc:`cosine/squared/restricted `
* :doc:`fourier (io) `
* :doc:`harmonic (iko) `
* :doc:`helix (o) `
diff --git a/doc/src/Commands_fix.rst b/doc/src/Commands_fix.rst
index e89e302673..a7648218fa 100644
--- a/doc/src/Commands_fix.rst
+++ b/doc/src/Commands_fix.rst
@@ -61,6 +61,7 @@ OPT.
* :doc:`controller `
* :doc:`damping/cundall `
* :doc:`deform (k) `
+ * :doc:`deform/pressure `
* :doc:`deposit `
* :doc:`dpd/energy (k) `
* :doc:`drag `
@@ -262,6 +263,7 @@ OPT.
* :doc:`wall/body/polyhedron `
* :doc:`wall/colloid `
* :doc:`wall/ees `
+ * :doc:`wall/flow (k) `
* :doc:`wall/gran (k) `
* :doc:`wall/gran/region `
* :doc:`wall/harmonic `
diff --git a/doc/src/Commands_pair.rst b/doc/src/Commands_pair.rst
index 9f2bdbce79..514785c15c 100644
--- a/doc/src/Commands_pair.rst
+++ b/doc/src/Commands_pair.rst
@@ -245,6 +245,7 @@ OPT.
* :doc:`oxrna2/coaxstk `
* :doc:`pace (k) `
* :doc:`pace/extrapolation (k) `
+ * :doc:`pedone (o) `
* :doc:`pod `
* :doc:`peri/eps `
* :doc:`peri/lps (o) `
@@ -256,6 +257,7 @@ OPT.
* :doc:`rann `
* :doc:`reaxff (ko) `
* :doc:`rebo (io) `
+ * :doc:`rebomos (o) `
* :doc:`resquared (go) `
* :doc:`saip/metal (t) `
* :doc:`sdpd/taitwater/isothermal `
diff --git a/doc/src/Developer_updating.rst b/doc/src/Developer_updating.rst
index cd61eaa5a1..83491ac095 100644
--- a/doc/src/Developer_updating.rst
+++ b/doc/src/Developer_updating.rst
@@ -18,6 +18,7 @@ Available topics in mostly chronological order are:
- `Setting flags in the constructor`_
- `Rename of pack/unpack_comm() to pack/unpack_forward_comm()`_
- `Use ev_init() to initialize variables derived from eflag and vflag`_
+- `Use utils::count_words() functions instead of atom->count_words()`_
- `Use utils::numeric() functions instead of force->numeric()`_
- `Use utils::open_potential() function to open potential files`_
- `Use symbolic Atom and AtomVec constants instead of numerical values`_
@@ -130,6 +131,41 @@ Not applying this change will not cause a compilation error, but
can lead to inconsistent behavior and incorrect tallying of
energy or virial.
+Use utils::count_words() functions instead of atom->count_words()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 2Jun2020
+
+The "count_words()" functions for parsing text have been moved from the
+Atom class to the :doc:`utils namespace `. The
+"count_words()" function in "utils" uses the Tokenizer class internally
+to split a line into words and count them, thus it will not modify the
+argument string as the function in the Atoms class did and thus had a
+variant using a copy buffer. Unlike the old version, the new version
+does not remove comments. For that you can use the
+:cpp:func:`utils::trim_comment() function
+` as shown in the example below.
+
+Old:
+
+.. code-block:: c++
+
+ nwords = atom->count_words(line);
+ int nwords = atom->count_words(buf);
+
+New:
+
+.. code-block:: c++
+
+ nwords = utils::count_words(line);
+ int nwords = utils::count_words(utils::trim_comment(buf));
+
+.. seealso::
+
+ :cpp:func:`utils::count_words() `,
+ :cpp:func:`utils::trim_comments() `
+
+
Use utils::numeric() functions instead of force->numeric()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -137,11 +173,12 @@ Use utils::numeric() functions instead of force->numeric()
The "numeric()" conversion functions (including "inumeric()",
"bnumeric()", and "tnumeric()") have been moved from the Force class to
-the utils namespace. Also they take an additional argument that selects
-whether the ``Error::all()`` or ``Error::one()`` function should be
-called in case of an error. The former should be used when *all* MPI
-processes call the conversion function and the latter *must* be used
-when they are called from only one or a subset of the MPI processes.
+the :doc:`utils namespace `. Also they take an
+additional argument that selects whether the ``Error::all()`` or
+``Error::one()`` function should be called in case of an error. The
+former should be used when *all* MPI processes call the conversion
+function and the latter *must* be used when they are called from only
+one or a subset of the MPI processes.
Old:
diff --git a/doc/src/Developer_utils.rst b/doc/src/Developer_utils.rst
index 625ce15202..76e90e17ba 100644
--- a/doc/src/Developer_utils.rst
+++ b/doc/src/Developer_utils.rst
@@ -635,10 +635,10 @@ Tohoku University (under MIT license)
----------
-.. doxygenfunction:: MathEigen::jacobi3(double const *const *mat, double *eval, double **evec)
+.. doxygenfunction:: MathEigen::jacobi3(double const *const *mat, double *eval, double **evec, int sort)
:project: progguide
-.. doxygenfunction:: MathEigen::jacobi3(double const mat[3][3], double *eval, double evec[3][3])
+.. doxygenfunction:: MathEigen::jacobi3(double const mat[3][3], double *eval, double evec[3][3], int sort)
:project: progguide
---------------------------
diff --git a/doc/src/Errors_details.rst b/doc/src/Errors_details.rst
index b63d80a9ae..c798784106 100644
--- a/doc/src/Errors_details.rst
+++ b/doc/src/Errors_details.rst
@@ -13,15 +13,44 @@ discussions of such cases.
Unknown identifier in data file
-------------------------------
-This error happens when LAMMPS encounters a line of text in an unexpected format
-while reading a data file. This is most commonly cause by inconsistent header and
-section data. The header section informs LAMMPS how many entries or lines are expected in the
-various sections (like Atoms, Masses, Pair Coeffs, *etc.*\ ) of the data file.
-If there is a mismatch, LAMMPS will either keep reading beyond the end of a section
-or stop reading before the section has ended.
+This error happens when LAMMPS encounters a line of text with an
+unexpected keyword while :doc:`reading a data file `. This
+would be either header keywords or section header keywords. This is
+most commonly due to a mistyped keyword or due to a keyword that is
+inconsistent with the :doc:`atom style ` used.
-Such a mismatch can happen unexpectedly when the first line of the data
-is *not* a comment as required by the format. That would result in
-LAMMPS expecting, for instance, 0 atoms because the "atoms" header line
-is treated as a comment.
+The header section informs LAMMPS how many entries or lines are expected
+in the various sections (like Atoms, Masses, Pair Coeffs, *etc.*\ ) of
+the data file. If there is a mismatch, LAMMPS will either keep reading
+beyond the end of a section or stop reading before the section has
+ended. In that case the next line will not contain a recognized keyword.
+Such a mismatch can also happen when the first line of the data
+is *not* a comment as required by the format, but a line with a valid
+header keyword. That would result in LAMMPS expecting, for instance,
+0 atoms because the "atoms" header line is the first line and thus
+treated as a comment.
+
+Another possibility to trigger this error is to have a keyword in the
+data file that corresponds to a fix (e.g. :doc:`fix cmap `)
+but the :doc:`read_data ` command is missing the (optional)
+arguments that identify the fix and the header keyword and section
+keyword or those arguments are inconsistent with the keywords in the
+data file.
+
+.. _err0002:
+
+Incorrect format in ... section of data file
+--------------------------------------------
+
+This error happens when LAMMPS reads the contents of a section of a
+:doc:`data file ` and the number of parameters in the line
+differs from what is expected. This most commonly happens, when the
+atom style is different from what is expected for a specific data file
+since changing the atom style usually changes the format of the line.
+
+This error can also happen when the number of entries indicated in the
+header of a data file (e.g. the number of atoms) is larger than the
+number of lines provided (e.g. in the corresponding Atoms section)
+and then LAMMPS will continue reading into the next section and that
+would have a completely different format.
diff --git a/doc/src/Errors_messages.rst b/doc/src/Errors_messages.rst
index bfdba4f6a1..2a146a9184 100644
--- a/doc/src/Errors_messages.rst
+++ b/doc/src/Errors_messages.rst
@@ -7883,12 +7883,6 @@ keyword to allow for additional bonds to be formed
Fix poems cannot (yet) work with coupled bodies whose joints connect
the bodies in a tree structure.
-*Triclinic box skew is too large*
- The displacement in a skewed direction must be less than half the box
- length in that dimension. E.g. the xy tilt must be between -half and
- +half of the x box length. This constraint can be relaxed by using
- the box tilt command.
-
*Tried to convert a double to int, but input_double > INT_MAX*
Self-explanatory.
diff --git a/doc/src/Errors_warnings.rst b/doc/src/Errors_warnings.rst
index b0fa2e2173..d244818cc9 100644
--- a/doc/src/Errors_warnings.rst
+++ b/doc/src/Errors_warnings.rst
@@ -752,13 +752,6 @@ This will most likely cause errors in kinetic fluctuations.
More than the maximum # of neighbors was found multiple times. This
was unexpected.
-*Triclinic box skew is large*
- The displacement in a skewed direction is normally required to be less
- than half the box length in that dimension. E.g. the xy tilt must be
- between -half and +half of the x box length. You have relaxed the
- constraint using the box tilt command, but the warning means that a
- LAMMPS simulation may be inefficient as a result.
-
*Use special bonds = 0,1,1 with bond style fene*
Most FENE models need this setting for the special_bonds command.
diff --git a/doc/src/Fortran.rst b/doc/src/Fortran.rst
index 64fca57a02..e9976b9032 100644
--- a/doc/src/Fortran.rst
+++ b/doc/src/Fortran.rst
@@ -1255,8 +1255,8 @@ Procedures Bound to the :f:type:`lammps` Derived Type
three elements of the global vector calculated by fix recenter into the
variables *dx*, *dy*, and *dz*, respectively.
- If asked for per-atom or local data, :f:func:`extract_compute` returns a
- pointer to actual LAMMPS data. The pointer so returned will have the
+ If asked for per-atom or local data, :f:func:`extract_fix` returns a
+ pointer to actual LAMMPS data. The pointer returned will have the
appropriate size to match the internal data, and will be
type/kind/rank-checked at the time of the assignment. For example,
diff --git a/doc/src/Howto_2d.rst b/doc/src/Howto_2d.rst
index ae58711063..d02cfc0814 100644
--- a/doc/src/Howto_2d.rst
+++ b/doc/src/Howto_2d.rst
@@ -1,42 +1,112 @@
-2d simulations
-==============
+================
+ 2d simulations
+================
-Use the :doc:`dimension ` command to specify a 2d simulation.
+You must use the :doc:`dimension ` command to specify a 2d
+simulation. The default is 3d.
-Make the simulation box periodic in z via the :doc:`boundary `
-command. This is the default.
+A 2d simulation box must be periodic in z as set by the :doc:`boundary
+` command. This is the default.
-If using the :doc:`create_box ` command to define a
-simulation box, set the z dimensions narrow, but finite, so that the
-:doc:`create_atoms ` command will fill the 3d simulation
-box with a single z plane of atoms - e.g.
+Simulation boxes in LAMMPS can be either orthogonal or triclinic in
+shape. Orthogonal boxes in 2d are a rectangle with 4 edges that are
+each perpendicular to either the x or y coordinate axes. Triclinic
+boxes in 2d are a parallelogram with opposite pairs of faces parallel
+to each other. LAMMPS supports two forms of triclinic boxes,
+restricted and general, which for 2d differ in how the box is oriented
+with respect to the xy coordinate axes. See the :doc:`Howto triclinic
+` for a detailed description of all 3 kinds of
+simulation boxes.
+
+Here are examples of using the :doc:`create_box ` command
+to define the simulation box for a 2d system.
.. code-block:: LAMMPS
- create_box 1 -10 10 -10 10 -0.25 0.25
+ # 2d orthogonal box using a block-style region
+ region mybox block -10 10 0 10 -0.5 0.5
+ create_box 1 mybox
-If using the :doc:`read_data ` command to read in a file of
-atom coordinates, set the "zlo zhi" values to be finite but narrow,
-similar to the create_box command settings just described. For each
-atom in the file, assign a z coordinate so it falls inside the
-z-boundaries of the box - e.g. 0.0.
+ # 2d restricted triclinic box using a prism-style region with only xy tilt
+ region mybox prism 0 10 0 10 -0.5 0.5 2.0 0.0 0.0
+ create_box 1 mybox
-Use the :doc:`fix enforce2d ` command as the last
-defined fix to ensure that the z-components of velocities and forces
-are zeroed out every timestep. The reason to make it the last fix is
-so that any forces induced by other fixes will be zeroed out.
+ # 2d general triclinic box using a primitive cell for a 2d hex lattice
+ lattice custom 1.0 a1 1.0 0.0 0.0 a2 0.5 0.86602540378 0.0 &
+ a3 0.0 0.0 1.0 basis 0.0 0.0 0.0 triclinic/general
+ create_box 1 NULL 0 5 0 5 -0.5 0.5
-Many of the example input scripts included in the LAMMPS distribution
+Note that for 2d orthogonal or restricted triclinic boxes, the box has
+a 3rd dimension which must straddle z = 0.0 in the z dimension.
+Typically the width of box in the z dimension should be narrow,
+e.g. -0.5 to 0.5, but that is not required. For a 2d general
+triclinic box, the *a3* vector defined by the :doc:`lattice `
+command must be (0.0,0.0,1.0), which is its default value. Also the
+*clo* and *chi* arguments of the :doc:`create_box `
+command must be -0.5 and 0.5.
+
+Here are examples of using the :doc:`read_data ` command
+to define the simulation box for a 2d system via keywords in the
+header section of the data file. These are the same boxes as the examples
+for the :doc:`create_box ` command
+
+.. code-block:: LAMMPS
+
+ # 2d orthogonal box
+ -10 10 xlo xhi
+ 0 10 ylo yhi
+ -0.5 0.5 zlo zhi # this is the default, so no need to specify
+
+ # 2d restricted triclinic box with only xy tilt
+ -10 10 xlo xhi
+ 0 10 ylo yhi
+ -0.5 0.5 zlo zhi # this is the default, so no need to specify
+ 2.0 0.0 0.0 xy xz yz
+
+ # 3d general triclinic box using a primitive cell for a 2d hex lattice
+ 5 0 0 avec
+ 2.5 4.3301270189 0 bvec
+ 0 0 1 cvec # this is the default, so no need to specify
+ 0 0 -0.5 abc origin # this is the default for 2d, so no need to specify
+
+Note that for 2d orthogonal or restricted triclinic boxes, the box has
+a 3rd dimension specified by the *zlo zhi* values, which must straddle
+z = 0.0. Typically the width of box in the z dimension should be
+narrow, e.g. -0.5 to 0.5, but that is not required. For a 2d general
+triclinic box, the z component of *avec* and *bvec* must be zero, and
+*cvec* must be (0,0,1), which is the default. The z component of *abc
+origin* must also be -0.5, which is the default.
+
+If using the :doc:`create_atoms ` command to create
+atoms in the 2d simulation box, all the z coordinates of created atoms
+will be zero.
+
+If using the :doc:`read_data ` command to read in a data
+file of atom coordinates for a 2d system, the z coordinates of all
+atoms should be zero. A value within epsilon of zero is also allowed
+in case the data file was generated by another program with finite
+numeric precision, in which case the z coord for the atom will be set
+to zero.
+
+Use the :doc:`fix enforce2d ` command as the last fix
+defined in the input script. It ensures that the z-components of
+velocities and forces are zeroed out every timestep. The reason to
+make it the last fix is so that any forces added by other fixes will
+also be zeroed out.
+
+Many of the example input scripts included in the examples directory
are for 2d models.
.. note::
Some models in LAMMPS treat particles as finite-size spheres, as
- opposed to point particles. See the :doc:`atom_style sphere ` and :doc:`fix nve/sphere `
- commands for details. By default, for 2d simulations, such particles
- will still be modeled as 3d spheres, not 2d discs (circles), meaning
+ opposed to point particles. See the :doc:`atom_style sphere
+ ` and :doc:`fix nve/sphere ` commands
+ for details. By default, for 2d simulations, such particles will
+ still be modeled as 3d spheres, not 2d discs (circles), meaning
their moment of inertia will be that of a sphere. If you wish to
- model them as 2d discs, see the :doc:`set density/disc ` command
- and the *disc* option for the :doc:`fix nve/sphere `,
- :doc:`fix nvt/sphere `, :doc:`fix nph/sphere `, :doc:`fix npt/sphere `
- commands.
+ model them as 2d discs, see the :doc:`set density/disc `
+ command and the *disc* option for the :doc:`fix nve/sphere
+ `, :doc:`fix nvt/sphere `,
+ :doc:`fix nph/sphere `, :doc:`fix npt/sphere
+ ` commands.
diff --git a/doc/src/Howto_body.rst b/doc/src/Howto_body.rst
index 968e10edd8..23d0e1019d 100644
--- a/doc/src/Howto_body.rst
+++ b/doc/src/Howto_body.rst
@@ -102,8 +102,19 @@ particles of different styles
| :doc:`dump image ` | output body particle attributes as an image |
+------------------------------------------------+-----------------------------------------------------+
-The pair styles defined for use with specific body styles are listed
-in the sections below.
+The pair styles currently defined for use with specific body styles
+are listed in the sections below.
+
+Note that for all the body styles, if the data file defines a general
+triclinic box, then the orientation of the body particle and its
+corresponding 6 moments of inertia and other orientation-dependent
+values should reflect the fact the body is defined withing a general
+triclinic box with edge vectors **A**,**B**,**C**. LAMMPS will rotate
+the box to convert it to a restricted triclinic box. This operation
+will also rotate the orientation of the body particles. See the
+:doc:`Howto triclinic ` doc page for more details.
+The sections below highlight the orientation-dependent values specific
+to each body style.
----------
@@ -154,12 +165,18 @@ values consistent with the current orientation of the rigid body
around its center of mass. The values are with respect to the
simulation box XYZ axes, not with respect to the principal axes of the
rigid body itself. LAMMPS performs the latter calculation internally.
+
The coordinates of each sub-particle are specified as its x,y,z
displacement from the center-of-mass of the body particle. The
center-of-mass position of the particle is specified by the x,y,z
values in the *Atoms* section of the data file, as is the total mass
of the body particle.
+Note that if the data file defines a general triclinic simulation box,
+these sub-particle displacements are orientation-dependent and, as
+mentioned above, should reflect the body particle's orientation within
+the general triclinic box.
+
The :doc:`pair_style body/nparticle ` command can be used
with this body style to compute body/body and body/non-body interactions.
@@ -226,6 +243,7 @@ values consistent with the current orientation of the rigid body
around its center of mass. The values are with respect to the
simulation box XYZ axes, not with respect to the principal axes of the
rigid body itself. LAMMPS performs the latter calculation internally.
+
The coordinates of each vertex are specified as its x,y,z displacement
from the center-of-mass of the body particle. The center-of-mass
position of the particle is specified by the x,y,z values in the
@@ -270,6 +288,11 @@ A disk, whose diameter is 3.0, mass 1.0, is specified as follows:
0 0 0
3.0
+Note that if the data file defines a general triclinic simulation box,
+these polygon vertex displacements are orientation-dependent and, as
+mentioned above, should reflect the body particle's orientation within
+the general triclinic box.
+
The :doc:`pair_style body/rounded/polygon `
command can be used with this body style to compute body/body
interactions. The :doc:`fix wall/body/polygon `
@@ -366,6 +389,7 @@ values consistent with the current orientation of the rigid body
around its center of mass. The values are with respect to the
simulation box XYZ axes, not with respect to the principal axes of the
rigid body itself. LAMMPS performs the latter calculation internally.
+
The coordinates of each vertex are specified as its x,y,z displacement
from the center-of-mass of the body particle. The center-of-mass
position of the particle is specified by the x,y,z values in the
@@ -435,6 +459,11 @@ A sphere whose diameter is 3.0 and mass 1.0, is specified as follows:
The number of edges and faces for a rod or sphere must be listed,
but is ignored.
+Note that if the data file defines a general triclinic simulation box,
+these polyhedron vertex displacements are orientation-dependent and,
+as mentioned above, should reflect the body particle's orientation
+within the general triclinic box.
+
The :doc:`pair_style body/rounded/polhedron
` command can be used with this body
style to compute body/body interactions. The :doc:`fix
diff --git a/doc/src/Howto_bpm.rst b/doc/src/Howto_bpm.rst
index 0ca4e85fbb..5aa277275d 100644
--- a/doc/src/Howto_bpm.rst
+++ b/doc/src/Howto_bpm.rst
@@ -15,7 +15,8 @@ orientation for rotational models. This produces a stress-free initial
state. Furthermore, bonds are allowed to break under large strains,
producing fracture. The examples/bpm directory has sample input scripts
for simulations of the fragmentation of an impacted plate and the
-pouring of extended, elastic bodies.
+pouring of extended, elastic bodies. See :ref:`(Clemmer) `
+for more general information on the approach and the LAMMPS implementation.
----------
@@ -150,3 +151,9 @@ the following are currently compatible with BPM bond styles:
interactions, one will need to switch between different *special_bonds*
settings in the input script. An example is found in
``examples/bpm/impact``.
+
+----------
+
+.. _howto-Clemmer:
+
+**(Clemmer)** Clemmer, Monti, Lechman, Soft Matter, 20, 1702 (2024).
diff --git a/doc/src/Howto_granular.rst b/doc/src/Howto_granular.rst
index c22cab66bc..b0c801be11 100644
--- a/doc/src/Howto_granular.rst
+++ b/doc/src/Howto_granular.rst
@@ -45,10 +45,15 @@ atoms, and should be used for granular system instead of the fix style
To model heat conduction, one must add the temperature and heatflow
atom variables with:
+
* :doc:`fix property/atom `
+
a temperature integration fix
+
* :doc:`fix heat/flow `
+
and a heat conduction option defined in both
+
* :doc:`pair_style granular `
* :doc:`fix wall/gran `
diff --git a/doc/src/Howto_triclinic.rst b/doc/src/Howto_triclinic.rst
index 2983d013c6..3529579d65 100644
--- a/doc/src/Howto_triclinic.rst
+++ b/doc/src/Howto_triclinic.rst
@@ -2,43 +2,195 @@ Triclinic (non-orthogonal) simulation boxes
===========================================
By default, LAMMPS uses an orthogonal simulation box to encompass the
-particles. The :doc:`boundary ` command sets the boundary
-conditions of the box (periodic, non-periodic, etc). The orthogonal
-box has its "origin" at (xlo,ylo,zlo) and is defined by 3 edge vectors
-starting from the origin given by **a** = (xhi-xlo,0,0); **b** =
-(0,yhi-ylo,0); **c** = (0,0,zhi-zlo). The 6 parameters
+particles. The orthogonal box has its "origin" at (xlo,ylo,zlo) and
+extends to (xhi,yhi,zhi). Conceptually it is defined by 3 edge
+vectors starting from the origin given by **A** = (xhi-xlo,0,0); **B**
+= (0,yhi-ylo,0); **C** = (0,0,zhi-zlo). The :doc:`boundary
+` command sets the boundary conditions for the 6 faces of
+the box (periodic, non-periodic, etc). The 6 parameters
(xlo,xhi,ylo,yhi,zlo,zhi) are defined at the time the simulation box
-is created, e.g. by the :doc:`create_box ` or
-:doc:`read_data ` or :doc:`read_restart `
-commands. Additionally, LAMMPS defines box size parameters lx,ly,lz
-where lx = xhi-xlo, and similarly in the y and z dimensions. The 6
-parameters, as well as lx,ly,lz, can be output via the
-:doc:`thermo_style custom ` command.
+is created by one of these commands:
-LAMMPS also allows simulations to be performed in triclinic
-(non-orthogonal) simulation boxes shaped as a parallelepiped with
-triclinic symmetry. The parallelepiped has its "origin" at
-(xlo,ylo,zlo) and is defined by 3 edge vectors starting from the
-origin given by **a** = (xhi-xlo,0,0); **b** = (xy,yhi-ylo,0); **c** =
-(xz,yz,zhi-zlo). *xy,xz,yz* can be 0.0 or positive or negative values
-and are called "tilt factors" because they are the amount of
-displacement applied to faces of an originally orthogonal box to
-transform it into the parallelepiped. In LAMMPS the triclinic
-simulation box edge vectors **a**, **b**, and **c** cannot be arbitrary
-vectors. As indicated, **a** must lie on the positive x axis. **b** must
-lie in the xy plane, with strictly positive y component. **c** may have
-any orientation with strictly positive z component. The requirement
-that **a**, **b**, and **c** have strictly positive x, y, and z components,
-respectively, ensures that **a**, **b**, and **c** form a complete
-right-handed basis. These restrictions impose no loss of generality,
-since it is possible to rotate/invert any set of 3 crystal basis
-vectors so that they conform to the restrictions.
+* :doc:`create_box `
+* :doc:`read_data `
+* :doc:`read_restart `
+* :doc:`read_dump `
-For example, assume that the 3 vectors **A**,\ **B**,\ **C** are the edge
-vectors of a general parallelepiped, where there is no restriction on
-**A**,\ **B**,\ **C** other than they form a complete right-handed basis i.e.
-**A** x **B** . **C** > 0. The equivalent LAMMPS **a**,\ **b**,\ **c** are a linear
-rotation of **A**, **B**, and **C** and can be computed as follows:
+Internally, LAMMPS defines box size parameters lx,ly,lz where lx =
+xhi-xlo, and similarly in the y and z dimensions. The 6 parameters, as
+well as lx,ly,lz, can be output via the :doc:`thermo_style custom
+` command. See the :doc:`Howto 2d ` doc page
+for info on how zlo and zhi are defined for 2d simulations.
+
+----------
+
+Triclinic simulation boxes
+""""""""""""""""""""""""""
+
+LAMMPS also allows simulations to be performed using triclinic
+(non-orthogonal) simulation boxes shaped as a 3d parallelepiped with
+triclinic symmetry. For 2d simulations a triclinic simulation box is
+effectively a parallelogram; see the :doc:`Howto 2d ` doc
+page for details.
+
+One use of triclinic simulation boxes is to model solid-state crystals
+with triclinic symmetry. The :doc:`lattice ` command can be
+used with non-orthogonal basis vectors to define a lattice that will
+tile a triclinic simulation box via the :doc:`create_atoms
+` command.
+
+A second use is to run Parrinello-Rahman dynamics via the :doc:`fix
+npt ` command, which will adjust the xy, xz, yz tilt factors
+to compensate for off-diagonal components of the pressure tensor. The
+analog for an :doc:`energy minimization ` is the :doc:`fix
+box/relax ` command.
+
+A third use is to shear a bulk solid to study the response of the
+material. The :doc:`fix deform ` command can be used for
+this purpose. It allows dynamic control of the xy, xz, yz tilt
+factors as a simulation runs. This is discussed in the :doc:`Howto
+NEMD ` doc page on non-equilibrium MD (NEMD) simulations.
+
+Conceptually, a triclinic parallelepiped is defined with an "origin"
+at (xlo,ylo,zhi) and 3 edge vectors **A** = (ax,ay,az), **B** =
+(bx,by,bz), **C** = (cx,cy,cz) which can be arbitrary vectors, so long
+as they are non-zero, distinct, and not co-planar. In addition, they
+must define a right-handed system, such that (**A** cross **B**)
+points in the direction of **C**. Note that a left-handed system can
+be converted to a right-handed system by simply swapping the order of
+any pair of the **A**, **B**, **C** vectors.
+
+The 4 commands listed above for defining orthogonal simulation boxes
+have triclinic options which allow for specification of the origin and
+edge vectors **A**, **B**, **C**. For each command, this can be done
+in one of two ways, for what LAMMPS calls a *general* triclinic box or
+a *restricted* triclinic box.
+
+A *general* triclinic box is specified by an origin (xlo, ylo, zlo)
+and arbitrary edge vectors **A** = (ax,ay,az), **B** = (bx,by,bz), and
+**C** = (cx,cy,cz). So there are 12 parameters in total.
+
+A *restricted* triclinic box also has an origin (xlo,ylo,zlo), but its
+edge vectors are of the following restricted form: **A** =
+(xhi-xlo,0,0), **B** = (xy,yhi-ylo,0), **C** = (xz,yz,zhi-zlo). So
+there are 9 parameters in total. Note that the restricted form
+requires **A** to be along the x-axis, **B** to be in the xy plane
+with a y-component in the +y direction, and **C** to have its
+z-component in the +z direction. Note that a restricted triclinic box
+is *right-handed* by construction since (**A** cross **B**) points in
+the direction of **C**.
+
+The *xy,xz,yz* values can be zero or positive or negative. They are
+called "tilt factors" because they are the amount of displacement
+applied to edges of faces of an orthogonal box to change it into a
+restricted triclinic parallelepiped.
+
+.. note::
+
+ Any right-handed general triclinic box (i.e. solid-state crystal
+ basis vectors) can be rotated in 3d around its origin in order to
+ conform to the LAMMPS definition of a restricted triclinic box.
+ See the discussion in the next sub-section about general triclinic
+ simulation boxes in LAMMPS.
+
+Note that the :doc:`thermo_style custom ` command has
+keywords for outputting the various parameters that define the size
+and shape of orthogonal, restricted triclinic, and general triclinic
+simulation boxes.
+
+For orthogonal boxes there 6 thermo keywords (xlo,ylo,zlo) and
+(xhi,yhi,zhi).
+
+For restricted triclinic boxes there are 9 thermo keywords for
+(xlo,ylo,zlo), (xhi,yhi,zhi), and the (xy,xz,yz) tilt factors.
+
+For general triclinic boxes there are 12 thermo keywords for
+(xlo,ylo,zhi) and the components of the **A**, **B**, **C** edge
+vectors, namely (avecx,avecy,avecz), (bvecx,bvecy,bvecz), and
+(cvecx,cvecy,cvecz),
+
+The remainder of this doc page explains (a) how LAMMPS operates with
+general triclinic simulation boxes, (b) mathematical transformations
+between general and restricted triclinic boxes which may be useful
+when creating LAMMPS inputs or interpreting outputs for triclinic
+simulations, and (c) how LAMMPS uses tilt factors for restricted
+triclinic simulation boxes.
+
+----------
+
+General triclinic simulation boxes in LAMMPS
+""""""""""""""""""""""""""""""""""""""""""""
+
+LAMMPS allows specification of general triclinic simulation boxes with
+their atoms as a convenience for users who may be converting data from
+solid-state crystallographic representations or from DFT codes for
+input to LAMMPS. Likewise it allows output of dump files, data files,
+and thermodynamic data (e.g. pressure tensor) in a general triclinic
+format.
+
+However internally, LAMMPS only uses restricted triclinic simulation
+boxes. This is for parallel efficiency and to formulate partitioning
+of the simulation box across processors, neighbor list building, and
+inter-processor communication of per-atom data with methods similar to
+those used for orthogonal boxes.
+
+This means 4 things which are important to understand:
+
+* Input of a general triclinic system is immediately converted to a
+ restricted triclinic system.
+* If output of per-atom data for a general triclinic system is
+ requested (e.g. for atom coordinates in a dump file),
+ conversion from a restricted to general triclinic system is done at
+ the time of output.
+* The conversion of the simulation box and per-atom data from general
+ triclinic to restricted triclinic (and vice versa) is a 3d rotation
+ operation around an origin, which is the lower left corner of the
+ simulation box. This means an input data file for a general
+ triclinic system should specify all per-atom quantities consistent
+ with the general triclinic box and its orientation relative to the
+ standard x,y,z coordinate axes. For example, atom coordinates
+ should be inside the general triclinic simulation box defined by the
+ edge vectors **A**, **B**, **C** and its origin. Likewise per-atom
+ velocities should be in directions consistent with the general
+ triclinic box orientation. E.g. a velocity vector which will be in
+ the +x direction once LAMMPS converts from a general to restricted
+ triclinic box, should be specified in the data file in the direction
+ of the **A** edge vector. See the :doc:`read_data ` doc
+ page for info on all the per-atom vector quantities to which this
+ rule applies when a data file for a general triclinic box is input.
+* If commands such as :doc:`write_data ` or :doc:`dump
+ custom ` are used to output general triclinic information, it
+ is effectively the inverse of the operation described in the
+ preceding bullet.
+* Other LAMMPS commands such as :doc:`region ` or
+ :doc:`velocity ` or :doc:`set `, operate on a
+ restricted triclinic system even if a general triclinic system was
+ defined initially.
+
+This is the list of commands which have general triclinic options:
+
+* :doc:`create_box ` - define a general triclinic box
+* :doc:`create_atoms ` - add atoms to a general triclinic box
+* :doc:`lattice ` - define a custom lattice consistent with the **A**, **B**, **C** edge vectors of a general triclinic box
+* :doc:`read_data ` - read a data file for a general triclinic system
+* :doc:`write_data ` - write a data file for a general triclinic system
+* :doc:`dump atom, dump custom ` - output dump snapshots in general triclinic format
+* :doc:`dump_modify triclinic/general ` - select general triclinic format for dump output
+* :doc:`thermo_style ` - output the pressure tensor in
+ general triclinic format
+* :doc:`thermo_modify triclinic/general ` - select general triclinic format for thermo output
+* :doc:`read_restart ` - read a restart file for a general triclinic system
+* :doc:`write_restart ` - write a restart file for a general triclinic system
+
+----------
+
+Transformation from general to restricted triclinic boxes
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Let **A**,\ **B**,\ **C** be the right-handed edge vectors of a
+general triclinic simulation box. The equivalent LAMMPS **a**,\
+**b**,\ **c** for a restricted triclinic box are a 3d rotation of
+**A**, **B**, and **C** and can be computed as follows:
.. math::
@@ -55,23 +207,17 @@ rotation of **A**, **B**, and **C** and can be computed as follows:
c_y = & \mathbf{C} \cdot \widehat{(\mathbf{A} \times \mathbf{B})} \times \mathbf{\hat{A}} \quad = \quad \frac{\mathbf{B} \cdot \mathbf{C} - b_x c_x}{b_y} \\
c_z = & |\mathbf{C} \cdot \widehat{(\mathbf{A} \times \mathbf{B})}|\quad = \quad \sqrt{C^2 - {c_x}^2 - {c_y}^2}
-where A = \| **A** \| indicates the scalar length of **A**\ . The hat symbol (\^)
-indicates the corresponding unit vector. :math:`\beta` and :math:`\gamma` are angles
-between the vectors described below. Note that by construction,
-**a**, **b**, and **c** have strictly positive x, y, and z components, respectively.
-If it should happen that
-**A**, **B**, and **C** form a left-handed basis, then the above equations
-are not valid for **c**\ . In this case, it is necessary
-to first apply an inversion. This can be achieved
-by interchanging two basis vectors or by changing the sign of one of them.
+where A = \| **A** \| indicates the scalar length of **A**\ . The hat
+symbol (\^) indicates the corresponding unit vector. :math:`\beta` and
+:math:`\gamma` are angles between the **A**, **B**, **C** vectors
+as described below.
-For consistency, the same rotation/inversion applied to the basis vectors
-must also be applied to atom positions, velocities,
-and any other vector quantities.
-This can be conveniently achieved by first converting to
-fractional coordinates in the
-old basis and then converting to distance coordinates in the new basis.
-The transformation is given by the following equation:
+For consistency, the same rotation applied to the triclinic box edge
+vectors can also be applied to atom positions, velocities, and other
+vector quantities. This can be conveniently achieved by first
+converting to fractional coordinates in the general triclinic
+coordinates and then converting to coordinates in the restricted
+triclinic basis. The transformation is given by the following equation:
.. math::
@@ -82,87 +228,24 @@ The transformation is given by the following equation:
\mathbf{A \times B}
\end{pmatrix} \cdot \mathbf{X}
-where *V* is the volume of the box, **X** is the original vector quantity and
-**x** is the vector in the LAMMPS basis.
+where *V* is the volume of the box (same in either basis), **X** is
+the fractional vector in the general triclinic basis and **x** is the
+resulting vector in the restricted triclinic basis.
-There is no requirement that a triclinic box be periodic in any
-dimension, though it typically should be in at least the second dimension
-of the tilt (y in xy) if you want to enforce a shift in periodic
-boundary conditions across that boundary. Some commands that work
-with triclinic boxes, e.g. the :doc:`fix deform ` and :doc:`fix npt ` commands, require periodicity or non-shrink-wrap
-boundary conditions in specific dimensions. See the command doc pages
-for details.
+----------
-The 9 parameters (xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz) are defined at the
-time the simulation box is created. This happens in one of 3 ways.
-If the :doc:`create_box ` command is used with a region of
-style *prism*, then a triclinic box is setup. See the
-:doc:`region ` command for details. If the
-:doc:`read_data ` command is used to define the simulation
-box, and the header of the data file contains a line with the "xy xz
-yz" keyword, then a triclinic box is setup. See the
-:doc:`read_data ` command for details. Finally, if the
-:doc:`read_restart ` command reads a restart file which
-was written from a simulation using a triclinic box, then a triclinic
-box will be setup for the restarted simulation.
+Crystallographic general triclinic representation of a simulation box
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-Note that you can define a triclinic box with all 3 tilt factors =
-0.0, so that it is initially orthogonal. This is necessary if the box
-will become non-orthogonal, e.g. due to the :doc:`fix npt ` or
-:doc:`fix deform ` commands. Alternatively, you can use the
-:doc:`change_box ` command to convert a simulation box from
-orthogonal to triclinic and vice versa.
-
-As with orthogonal boxes, LAMMPS defines triclinic box size parameters
-lx,ly,lz where lx = xhi-xlo, and similarly in the y and z dimensions.
-The 9 parameters, as well as lx,ly,lz, can be output via the
-:doc:`thermo_style custom ` command.
-
-To avoid extremely tilted boxes (which would be computationally
-inefficient), LAMMPS normally requires that no tilt factor can skew
-the box more than half the distance of the parallel box length, which
-is the first dimension in the tilt factor (x for xz). This is required
-both when the simulation box is created, e.g. via the
-:doc:`create_box ` or :doc:`read_data ` commands,
-as well as when the box shape changes dynamically during a simulation,
-e.g. via the :doc:`fix deform ` or :doc:`fix npt `
-commands.
-
-For example, if xlo = 2 and xhi = 12, then the x box length is 10 and
-the xy tilt factor must be between -5 and 5. Similarly, both xz and
-yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is
-not a limitation, since if the maximum tilt factor is 5 (as in this
-example), then configurations with tilt = ..., -15, -5, 5, 15, 25,
-... are geometrically all equivalent. If the box tilt exceeds this
-limit during a dynamics run (e.g. via the :doc:`fix deform `
-command), then the box is "flipped" to an equivalent shape with a tilt
-factor within the bounds, so the run can continue. See the :doc:`fix deform ` page for further details.
-
-One exception to this rule is if the first dimension in the tilt
-factor (x for xy) is non-periodic. In that case, the limits on the
-tilt factor are not enforced, since flipping the box in that dimension
-does not change the atom positions due to non-periodicity. In this
-mode, if you tilt the system to extreme angles, the simulation will
-simply become inefficient, due to the highly skewed simulation box.
-
-Box flips that may occur using the :doc:`fix deform ` or
-:doc:`fix npt ` commands can be turned off using the *flip no*
-option with either of the commands.
-
-Note that if a simulation box has a large tilt factor, LAMMPS will run
-less efficiently, due to the large volume of communication needed to
-acquire ghost atoms around a processor's irregular-shaped subdomain.
-For extreme values of tilt, LAMMPS may also lose atoms and generate an
-error.
-
-Triclinic crystal structures are often defined using three lattice
-constants *a*, *b*, and *c*, and three angles :math:`\alpha`,
-:math:`\beta`, and :math:`\gamma`. Note that in this nomenclature,
-the a, b, and c lattice constants are the scalar lengths of the edge
+General triclinic crystal structures are often defined using three
+lattice constants *a*, *b*, and *c*, and three angles :math:`\alpha`,
+:math:`\beta`, and :math:`\gamma`. Note that in this nomenclature, the
+a, b, and c lattice constants are the scalar lengths of the edge
vectors **a**, **b**, and **c** defined above. The relationship
between these 6 quantities (a, b, c, :math:`\alpha`, :math:`\beta`,
-:math:`\gamma`) and the LAMMPS box sizes (lx,ly,lz) =
-(xhi-xlo,yhi-ylo,zhi-zlo) and tilt factors (xy,xz,yz) is as follows:
+:math:`\gamma`) and the LAMMPS restricted triclinic box sizes
+(lx,ly,lz) = (xhi-xlo,yhi-ylo,zhi-zlo) and tilt factors (xy,xz,yz) is
+as follows:
.. math::
@@ -186,15 +269,19 @@ The inverse relationship can be written as follows:
The values of *a*, *b*, *c*, :math:`\alpha` , :math:`\beta`, and
:math:`\gamma` can be printed out or accessed by computes using the
-:doc:`thermo_style custom ` keywords
-*cella*, *cellb*, *cellc*, *cellalpha*, *cellbeta*, *cellgamma*,
-respectively.
+:doc:`thermo_style custom ` keywords *cella*, *cellb*,
+*cellc*, *cellalpha*, *cellbeta*, *cellgamma*, respectively.
+
+----------
+
+Output of restricted and general triclinic boxes in a dump file
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
As discussed on the :doc:`dump ` command doc page, when the BOX
-BOUNDS for a snapshot is written to a dump file for a triclinic box,
-an orthogonal bounding box which encloses the triclinic simulation box
-is output, along with the 3 tilt factors (xy, xz, yz) of the triclinic
-box, formatted as follows:
+BOUNDS for a snapshot is written to a dump file for a restricted
+triclinic box, an orthogonal bounding box which encloses the triclinic
+simulation box is output, along with the 3 tilt factors (xy, xz, yz) of
+the restricted triclinic box, formatted as follows:
.. parsed-literal::
@@ -204,7 +291,7 @@ box, formatted as follows:
zlo_bound zhi_bound yz
This bounding box is convenient for many visualization programs and is
-calculated from the 9 triclinic box parameters
+calculated from the 9 restricted triclinic box parameters
(xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz) as follows:
.. parsed-literal::
@@ -217,22 +304,66 @@ calculated from the 9 triclinic box parameters
zhi_bound = zhi
These formulas can be inverted if you need to convert the bounding box
-back into the triclinic box parameters, e.g. xlo = xlo_bound -
-MIN(0.0,xy,xz,xy+xz).
+back into the restricted triclinic box parameters, e.g. xlo =
+xlo_bound - MIN(0.0,xy,xz,xy+xz).
-One use of triclinic simulation boxes is to model solid-state crystals
-with triclinic symmetry. The :doc:`lattice ` command can be
-used with non-orthogonal basis vectors to define a lattice that will
-tile a triclinic simulation box via the
-:doc:`create_atoms ` command.
+----------
-A second use is to run Parrinello-Rahman dynamics via the :doc:`fix npt ` command, which will adjust the xy, xz, yz tilt
-factors to compensate for off-diagonal components of the pressure
-tensor. The analog for an :doc:`energy minimization ` is
-the :doc:`fix box/relax ` command.
+Periodicity and tilt factors for triclinic simulation boxes
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-A third use is to shear a bulk solid to study the response of the
-material. The :doc:`fix deform ` command can be used for
-this purpose. It allows dynamic control of the xy, xz, yz tilt
-factors as a simulation runs. This is discussed in the next section
-on non-equilibrium MD (NEMD) simulations.
+There is no requirement that a triclinic box be periodic in any
+dimension, though it typically should be in y or z if you wish to
+enforce a shift in coordinates due to periodic boundary conditions
+across the y or z boundaries. See the doc page for the :doc:`boundary
+` command for an explanation of shifted coordinates for
+restricted triclinic boxes which are periodic.
+
+Some commands that work with triclinic boxes, e.g. the :doc:`fix
+deform ` and :doc:`fix npt ` commands, require
+periodicity or non-shrink-wrap boundary conditions in specific
+dimensions. See the command doc pages for details.
+
+A restricted triclinic box can be defined with all 3 tilt factors =
+0.0, so that it is initially orthogonal. This is necessary if the box
+will become non-orthogonal, e.g. due to use of the :doc:`fix npt
+` or :doc:`fix deform ` commands. Alternatively,
+you can use the :doc:`change_box ` command to convert a
+simulation box from orthogonal to restricted triclinic and vice versa.
+
+.. note::
+
+ Highly tilted restricted triclinic simulation boxes can be
+ computationally inefficient. This is due to the large volume of
+ communication needed to acquire ghost atoms around a processor's
+ irregular-shaped subdomain. For extreme values of tilt, LAMMPS may
+ also lose atoms and generate an error.
+
+LAMMPS will issue a warning if you define a restricted triclinic box
+with a tilt factor which skews the box more than half the distance of
+the parallel box length, which is the first dimension in the tilt
+factor (e.g. x for xz).
+
+For example, if xlo = 2 and xhi = 12, then the x box length is 10 and
+the xy tilt factor should be between -5 and 5 to avoid the warning.
+Similarly, both xz and yz should be between -(xhi-xlo)/2 and
++(yhi-ylo)/2. Note that these are not limitations, since if the
+maximum tilt factor is 5 (as in this example), then simulations boxes
+and atom configurations with tilt = ..., -15, -5, 5, 15, 25, ... are
+all geometrically equivalent.
+
+If the box tilt exceeds this limit during a dynamics run (e.g. due to
+the :doc:`fix deform ` command), then by default the box
+is "flipped" to an equivalent shape with a tilt factor within the
+warning bounds, and the run continues. See the :doc:`fix deform
+` page for further details. Box flips that would normally
+occur using the :doc:`fix deform ` or :doc:`fix npt
+` commands can be suppressed using the *flip no* option with
+either of the commands.
+
+One exception to box flipping is if the first dimension in the tilt
+factor (e.g. x for xy) is non-periodic. In that case, the limits on
+the tilt factor are not enforced, since flipping the box in that
+dimension would not change the atom positions due to non-periodicity.
+In this mode, if the system tilts to large angles, the simulation will
+simply become inefficient, due to the highly skewed simulation box.
diff --git a/doc/src/Howto_type_labels.rst b/doc/src/Howto_type_labels.rst
index 8f03f45ef9..6b734f5c8d 100644
--- a/doc/src/Howto_type_labels.rst
+++ b/doc/src/Howto_type_labels.rst
@@ -14,16 +14,17 @@ wherever they appear in LAMMPS input or output files. The total number
Ntypes for each interaction is "locked in" when the simulation box
is created.
-A recent addition to LAMMPS is the option to use strings - referred
-to as type labels - as an alternative. Using type labels instead of
+A recent addition to LAMMPS is the option to use strings - referred to
+as type labels - as an alternative. Using type labels instead of
numeric types can be advantageous in various scenarios. For example,
-type labels can make inputs more readable and generic (i.e. usable through
-the :doc:`include command ` for different systems with different
-numerical values assigned to types. This generality also applies to
-other inputs like data files read by :doc:`read_data ` or
-molecule template files read by the :doc:`molecule `
-command. See below for a list of other commands that can use
-type labels in different ways.
+type labels can make inputs more readable and generic (i.e. usable
+through the :doc:`include command ` for different systems with
+different numerical values assigned to types. This generality also
+applies to other inputs like data files read by :doc:`read_data
+` or molecule template files read by the :doc:`molecule
+` command. A discussion of the current type label support can
+be found in :ref:`(Gissinger) `. See below for a list of
+other commands that can use type labels in different ways.
LAMMPS will *internally* continue to use numeric types, which means
that many previous restrictions still apply. For example, the total
@@ -124,3 +125,9 @@ between the files. The creation of simulation-ready reaction templates
for :doc:`fix bond/react ` is much simpler when using
type labels, and results in templates that can be used without
modification in multiple simulations or different systems.
+
+-----------
+
+.. _Typelabel24:
+
+**(Gissinger)** J. R. Gissinger, I. Nikiforov, Y. Afshar, B. Waters, M. Choi, D. S. Karls, A. Stukowski, W. Im, H. Heinz, A. Kohlmeyer, and E. B. Tadmor, J Phys Chem B, 128, 3282-3297 (2024).
diff --git a/doc/src/Intro_citing.rst b/doc/src/Intro_citing.rst
index 69ccab6162..8b906bb725 100644
--- a/doc/src/Intro_citing.rst
+++ b/doc/src/Intro_citing.rst
@@ -47,6 +47,8 @@ In addition there are DOIs generated for individual stable releases:
- 3 March 2020 version: `DOI:10.5281/zenodo.3726417 `_
- 29 October 2020 version: `DOI:10.5281/zenodo.4157471 `_
- 29 September 2021 version: `DOI:10.5281/zenodo.6386596 `_
+- 23 June 2022 version: `DOI:10.5281/zenodo.10806836 `_
+- 2 August 2023 version: `DOI:10.5281/zenodo.10806852 `_
Home page
^^^^^^^^^
diff --git a/doc/src/Intro_features.rst b/doc/src/Intro_features.rst
index f7b4dd319b..98e9d981ed 100644
--- a/doc/src/Intro_features.rst
+++ b/doc/src/Intro_features.rst
@@ -29,7 +29,7 @@ General features
* spatial decomposition of simulation domain for MPI parallelism
* particle decomposition inside spatial decomposition for OpenMP and GPU parallelism
* GPLv2 licensed open-source distribution
-* highly portable C++-11
+* highly portable C++-11 (optional packages may require C++17)
* modular code with most functionality in optional packages
* only depends on MPI library for basic parallel functionality, MPI stub for serial compilation
* other libraries are optional and only required for specific packages
@@ -81,7 +81,7 @@ commands)
* pairwise potentials: Lennard-Jones, Buckingham, Morse, Born-Mayer-Huggins, Yukawa, soft, Class II (COMPASS), hydrogen bond, harmonic, gaussian, tabulated, scripted
* charged pairwise potentials: Coulombic, point-dipole
* many-body potentials: EAM, Finnis/Sinclair, MEAM, MEAM+SW, EIM, EDIP, ADP, Stillinger-Weber, Tersoff, REBO, AIREBO, ReaxFF, COMB, Streitz-Mintmire, 3-body polymorphic, BOP, Vashishta
-* machine learning potentials: ACE, AGNI, GAP, Behler-Parrinello (N2P2), POD, RANN
+* machine learning potentials: ACE, AGNI, GAP, Behler-Parrinello (N2P2), POD, RANN, SNAP
* interfaces to ML potentials distributed by external groups: ANI, ChIMES, DeepPot, HIPNN, MTP
* long-range interactions for charge, point-dipoles, and LJ dispersion: Ewald, Wolf, PPPM (similar to particle-mesh Ewald), MSM, ScaFaCoS
* polarization models: :doc:`QEq `, :doc:`core/shell model `, :doc:`Drude dipole model `
diff --git a/doc/src/Python_scatter.rst b/doc/src/Python_scatter.rst
index 002a36cc98..e4444fabe7 100644
--- a/doc/src/Python_scatter.rst
+++ b/doc/src/Python_scatter.rst
@@ -54,8 +54,21 @@ like this:
x[3] = x coord of atom with ID 2
...
x[n3-1] = z coord of atom with ID natoms
- lmp.scatter_atoms("x",1,3,x)
+ lmp.scatter_atoms("x", 1, 3, x)
+
+The coordinates can also be provided as arguments to the initializer of x:
+
+.. code-block:: python
+
+ from ctypes import c_double
+ natoms = 2
+ n3 = 3*natoms
+ # init in constructor
+ x = (n3*c_double)(0.0, 0.0, 0.0, 1.0, 1.0, 1.0)
+ lmp.scatter_atoms("x", 1, 3, x)
+ # or using a list
+ coords = [1.0, 2.0, 3.0, -3.0, -2.0, -1.0]
+ x = (c_double*len(coords))(*coords)
Alternatively, you can just change values in the vector returned by
the gather methods, since they are also ctypes vectors.
-
diff --git a/doc/src/Speed_kokkos.rst b/doc/src/Speed_kokkos.rst
index 1cae518f96..41ae4a4dfb 100644
--- a/doc/src/Speed_kokkos.rst
+++ b/doc/src/Speed_kokkos.rst
@@ -20,11 +20,28 @@ including Sikandar Mashayak (UIUC), Ray Shan (Sandia), and Dan Ibanez
(Sandia). For more information on developing using Kokkos abstractions
see the `Kokkos Wiki `_.
-Kokkos currently provides support for 4 modes of execution (per MPI
+.. note::
+
+ The Kokkos library is under active development and tracking the
+ availability of accelerator hardware, so is the KOKKOS package in
+ LAMMPS. This means that only a certain range of versions of the
+ Kokkos library are compatible with the KOKKOS package of a certain
+ range of LAMMPS versions. For that reason LAMMPS comes with a
+ bundled version of the Kokkos library that has been validated on
+ multiple platforms and may contain selected back-ported bug fixes
+ from upstream Kokkos versions. While it is possible to build LAMMPS
+ with an external version of Kokkos, it is untested and may result in
+ incorrect execution or crashes.
+
+Kokkos currently provides full support for 4 modes of execution (per MPI
task). These are Serial (MPI-only for CPUs and Intel Phi), OpenMP
-(threading for many-core CPUs and Intel Phi), CUDA (for NVIDIA
-GPUs) and HIP (for AMD GPUs). You choose the mode at build time to
-produce an executable compatible with a specific hardware.
+(threading for many-core CPUs and Intel Phi), CUDA (for NVIDIA GPUs) and
+HIP (for AMD GPUs). Additional modes (e.g. OpenMP target, Intel data
+center GPUs) are under development. You choose the mode at build time
+to produce an executable compatible with a specific hardware.
+
+The following compatibility notes have been last updated for LAMMPS
+version 23 November 2023 and Kokkos version 4.2.
.. admonition:: C++17 support
:class: note
@@ -54,22 +71,22 @@ produce an executable compatible with a specific hardware.
:class: note
Kokkos with CUDA currently implicitly assumes that the MPI library is
- GPU-aware. This is not always the case, especially when using
+ GPU-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
+ rank. When running with multiple MPI ranks, you may see segmentation
faults without GPU-aware MPI support. These can be avoided by adding
the flags :doc:`-pk kokkos gpu/aware off ` to the
LAMMPS command line or by using the command :doc:`package kokkos
gpu/aware off ` in the input file.
-.. admonition:: AMD GPU support
+.. admonition:: Intel Data Center GPU support
:class: note
- To build with Kokkos the HIPCC compiler from the AMD ROCm software
- version 3.5 or later is required. Supporting this Kokkos mode in
- LAMMPS is still work in progress. Please contact the LAMMPS developers
- if you run into problems.
+ Support for Kokkos with Intel Data Center GPU accelerators (formerly
+ known under the code name "Ponte Vecchio") in LAMMPS is still a work
+ in progress. Only a subset of the functionality works correctly.
+ Please contact the LAMMPS developers if you run into problems.
Building LAMMPS with the KOKKOS package
"""""""""""""""""""""""""""""""""""""""
@@ -292,6 +309,10 @@ one or more nodes, each with two GPUs:
settings. Experimenting with its options can provide a speed-up for
specific calculations. For example:
+.. code-block:: bash
+
+ 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::
The default binsize for :doc:`atom sorting ` on GPUs
@@ -302,9 +323,15 @@ one or more nodes, each with two GPUs:
frequent sorting than default (e.g. sorting every 100 time steps
instead of 1000) may improve performance.
-.. code-block:: bash
+.. note::
- 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
+ When running on GPUs with many MPI ranks (tens of thousands and
+ more), the creation of the atom map (required for molecular systems)
+ on the GPU can slow down significantly or run out of GPU memory and
+ thus slow down the whole calculation or cause a crash. You can use
+ the "-pk kokkos atom/map no" :doc:`command-line switch `
+ of the :doc:`package kokkos atom/map no ` command to create
+ the atom map on the CPU instead.
.. note::
@@ -416,15 +443,22 @@ Generally speaking, the following rules of thumb apply:
performance of a KOKKOS style is a bit slower than the OPENMP
package.
* When running large number of atoms per GPU, KOKKOS is typically faster
- than the GPU package when compiled for double precision. The benefit
+ 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
+* When running on Intel Phi hardware, KOKKOS is not as fast as
the INTEL package, which is optimized for x86 hardware (not just
from Intel) and compilation with the Intel compilers. The INTEL
package also can increase the vector length of vector instructions
by switching to single or mixed precision mode.
+* The KOKKOS package by default assumes that you are using exactly one
+ MPI rank per GPU. When trying to use multiple MPI ranks per GPU it is
+ mandatory to enable `CUDA Multi-Process Service (MPS)
+ `_ to get good
+ performance. In this case it is better to not use all available
+ MPI ranks in order to avoid competing with the MPS daemon for
+ CPU resources.
See the `Benchmark page `_ of the
LAMMPS website for performance of the KOKKOS package on different
diff --git a/doc/src/angle_cosine_squared_restricted.rst b/doc/src/angle_cosine_squared_restricted.rst
new file mode 100644
index 0000000000..008ebfebeb
--- /dev/null
+++ b/doc/src/angle_cosine_squared_restricted.rst
@@ -0,0 +1,80 @@
+.. index:: angle_style cosine/squared/restricted
+.. index:: angle_style cosine/squared/restricted/omp
+
+angle_style cosine/squared/restricted command
+=============================================
+
+Accelerator Variants: *cosine/squared/restricted/omp*
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+ angle_style cosine/squared/restricted
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+ angle_style cosine/squared/restricted
+ angle_coeff 2*4 75.0 100.0
+
+Description
+"""""""""""
+
+.. versionadded:: 17Apr2024
+
+The *cosine/squared/restricted* angle style uses the potential
+
+.. math::
+
+ E = K [\cos(\theta) - \cos(\theta_0)]^2 / \sin^2(\theta)
+
+, which is commonly used in the MARTINI force field,
+where :math:`\theta_0` is the equilibrium value of the angle, and :math:`K`
+is a prefactor. Note that the usual 1/2 factor is included in :math:`K`.
+
+See :ref:`(Bulacu) ` for a description of the restricted angle for the MARTINI force field.
+
+The following coefficients must be defined for each angle type via the
+:doc:`angle_coeff ` command as in the example above, or in
+the data file or restart files read by the :doc:`read_data `
+or :doc:`read_restart ` commands:
+
+* :math:`K` (energy)
+* :math:`\theta_0` (degrees)
+
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
+internally.
+
+----------
+
+.. include:: accel_styles.rst
+
+----------
+
+Restrictions
+""""""""""""
+
+This angle style can only be used if LAMMPS was built with the
+EXTRA-MOLECULE package. See the :doc:`Build package ` doc page
+for more info.
+
+Related commands
+""""""""""""""""
+
+:doc:`angle_coeff `
+
+Default
+"""""""
+
+none
+
+----------
+
+.. _restricted-Bulacu:
+
+**(Bulacu)** Bulacu, Goga, Zhao, Rossi, Monticelli, Periole, Tieleman, Marrink, J Chem Theory Comput, 9, 3282-3292
+(2013).
diff --git a/doc/src/angle_style.rst b/doc/src/angle_style.rst
index 1f1ae72647..eeb174e772 100644
--- a/doc/src/angle_style.rst
+++ b/doc/src/angle_style.rst
@@ -10,7 +10,7 @@ Syntax
angle_style style
-* style = *none* or *zero* or *hybrid* or *amoeba* or *charmm* or *class2* or *class2/p6* or *cosine* or *cosine/buck6d* or *cosine/delta* or *cosine/periodic* or *cosine/shift* or *cosine/shift/exp* or *cosine/squared* or *cross* or *dipole* or *fourier* or *fourier/simple* or *gaussian* or *harmonic* or *lepton* or *mm3* or *quartic* or *spica* or *table*
+* style = *none* or *zero* or *hybrid* or *amoeba* or *charmm* or *class2* or *class2/p6* or *cosine* or *cosine/buck6d* or *cosine/delta* or *cosine/periodic* or *cosine/shift* or *cosine/shift/exp* or *cosine/squared* or *cosine/squared/restricted* or *cross* or *dipole* or *fourier* or *fourier/simple* or *gaussian* or *harmonic* or *lepton* or *mm3* or *quartic* or *spica* or *table*
Examples
""""""""
@@ -84,6 +84,7 @@ of (g,i,k,o,t) to indicate which accelerated styles exist.
* :doc:`cosine/shift ` - angle cosine with a shift
* :doc:`cosine/shift/exp ` - cosine with shift and exponential term in spring constant
* :doc:`cosine/squared ` - angle with cosine squared term
+* :doc:`cosine/squared/restricted ` - angle with restricted cosine squared term
* :doc:`cross ` - cross term coupling angle and bond lengths
* :doc:`dipole ` - angle that controls orientation of a point dipole
* :doc:`fourier ` - angle with multiple cosine terms
diff --git a/doc/src/atom_style.rst b/doc/src/atom_style.rst
index 60a85e0bcb..f11cdf54b9 100644
--- a/doc/src/atom_style.rst
+++ b/doc/src/atom_style.rst
@@ -283,21 +283,22 @@ Note that there may be additional arguments required along with the
arguments are described on the :doc:`Howto body ` doc page.
For the *dielectric* style, each particle can be either a physical
-particle (e.g. an ion), or an interface particle representing a boundary
-element between two regions of different dielectric constant. For
-interface particles, in addition to the properties associated with
-atom_style full, each particle also should be assigned a normal unit
-vector (defined by normx, normy, normz), an area (area/patch), the
+particle (e.g. an ion), or an interface particle representing a
+boundary element between two regions of different dielectric
+constant. For interface particles, in addition to the properties
+associated with atom_style full, each particle also should be assigned
+a unit dipole vector (mu) representing the direction of the induced
+dipole moment at each interface particle, an area (area/patch), the
difference and mean of the dielectric constants of two sides of the
interface along the direction of the normal vector (ed and em), the
-local dielectric constant at the boundary element (epsilon), and a mean
-local curvature (curv). Physical particles must be assigned these
-values, as well, but only their local dielectric constants will be used;
-see documentation for associated :doc:`pair styles `
-and :doc:`fixes `. The distinction between the physical
-and interface particles is only meaningful when :doc:`fix polarize
-` commands are applied to the interface particles. This
-style is part of the DIELECTRIC package.
+local dielectric constant at the boundary element (epsilon), and a
+mean local curvature (curv). Physical particles must be assigned
+these values, as well, but only their local dielectric constants will
+be used; see documentation for associated :doc:`pair styles
+` and :doc:`fixes `. The distinction
+between the physical and interface particles is only meaningful when
+:doc:`fix polarize ` commands are applied to the
+interface particles. This style is part of the DIELECTRIC package.
For the *dipole* style, a point dipole vector mu is defined for each
point particle. Note that if you wish the particles to be finite-size
diff --git a/doc/src/boundary.rst b/doc/src/boundary.rst
index 8e019e801c..06f125ed4f 100644
--- a/doc/src/boundary.rst
+++ b/doc/src/boundary.rst
@@ -42,8 +42,10 @@ commands.
The style *p* means the box is periodic, so that particles interact
across the boundary, and they can exit one end of the box and re-enter
the other end. A periodic dimension can change in size due to
-constant pressure boundary conditions or box deformation (see the :doc:`fix npt ` and :doc:`fix deform ` commands). The *p*
-style must be applied to both faces of a dimension.
+constant pressure boundary conditions or box deformation (see the
+:doc:`fix npt ` and :doc:`fix deform ` commands).
+The *p* style must be applied to both faces of a dimension. For 2d
+simulations the z dimension must be periodic (which is the default).
The styles *f*, *s*, and *m* mean the box is non-periodic, so that
particles do not interact across the boundary and do not move from one
@@ -76,28 +78,44 @@ atoms becomes less than 50.0. This can be useful if you start a
simulation with an empty box or if you wish to leave room on one side
of the box, e.g. for atoms to evaporate from a surface.
-For triclinic (non-orthogonal) simulation boxes, if the second dimension
-of a tilt factor (e.g. y for xy) is periodic, then the periodicity is
-enforced with the tilt factor offset. If the first dimension is
-shrink-wrapped, then the shrink wrapping is applied to the tilted box
-face, to encompass the atoms. E.g. for a positive xy tilt, the xlo
-and xhi faces of the box are planes tilting in the +y direction as y
-increases. These tilted planes are shrink-wrapped around the atoms to
-determine the x extent of the box.
-
+LAMMPS also allows use of triclinic (non-orthogonal) simulation boxes.
See the :doc:`Howto triclinic ` page for a
-geometric description of triclinic boxes, as defined by LAMMPS, and
-how to transform these parameters to and from other commonly used
-triclinic representations.
+description of both general and restricted triclinic boxes and how to
+define them. General triclinic boxes (arbitrary edge vectors **A**,
+**B**, and **C**) are converted internally to restricted triclinic
+boxes with tilt factors (xy,xz,yz) which skew an otherwise orthogonal
+box.
+
+The boundary command settings explained above for the 6
+faces of an orthogonal box also apply in similar manner to the 6 faces
+of a restricted triclinic box (and thus to the corresponding 6 faces
+of a general triclinic box), with the following context.
+
+if the second dimension of a tilt factor (e.g. y for xy) is periodic,
+then the periodicity is enforced with the tilt factor offset. This
+means that for y periodicity a particle which exits the lower y
+boundary is displaced in the x-direction by xy before it re-enters the
+upper y boundary. And vice versa if a particle exits the upper y
+boundary. Likewise the ghost atoms surrounding a particle near the
+lower y boundary include images of particles near the upper y-boundary
+which are displaced in the x-direction by xy. Similar rules apply for
+z-periodicity and the xz and/or yz tilt factors.
+
+If the first dimension of a tilt factor is shrink-wrapped, then the
+shrink wrapping is applied to the tilted box face, to encompass the
+atoms. E.g. for a positive xy tilt, the xlo and xhi faces of the box
+are planes tilting in the +y direction as y increases. The position
+of these tilted planes are adjusted dynamically to shrink-wrap around
+the atoms to determine the xlo and xhi extents of the box.
Restrictions
""""""""""""
This command cannot be used after the simulation box is defined by a
-:doc:`read_data ` or :doc:`create_box ` command or
-:doc:`read_restart ` command. See the
-:doc:`change_box ` command for how to change the simulation
-box boundaries after it has been defined.
+:doc:`read_data ` or :doc:`create_box ` command
+or :doc:`read_restart ` command. See the
+:doc:`change_box ` command for how to change the
+simulation box boundaries after it has been defined.
For 2d simulations, the z dimension must be periodic.
diff --git a/doc/src/compute_adf.rst b/doc/src/compute_adf.rst
index fc1ad1ae0a..a43a10207c 100644
--- a/doc/src/compute_adf.rst
+++ b/doc/src/compute_adf.rst
@@ -204,8 +204,23 @@ angles per atom satisfying the ADF criteria.
Restrictions
""""""""""""
-This compute is part of the EXTRA-COMPUTE package. It is only enabled if
-LAMMPS was built with that package. See the :doc:`Build package ` page for more info.
+This compute is part of the EXTRA-COMPUTE package. It is only enabled
+if LAMMPS was built with that package. See the :doc:`Build package
+` page for more info.
+
+By default, the ADF is not computed for distances longer than the
+largest force cutoff, since the neighbor list creation will only contain
+pairs up to that distance (plus neighbor list skin). If you use outer
+cutoffs larger than that, you must use :doc:`neighbor style 'bin' or
+'nsq' `.
+
+If you want an ADF for a larger outer cutoff, you can also use the
+:doc:`rerun ` command to post-process a dump file, use :doc:`pair
+style zero ` and set the force cutoff to be larger in the
+rerun script. Note that in the rerun context, the force cutoff is
+arbitrary and with pair style zero you are not computing any forces, and
+since you are not running dynamics you are not changing the model that
+generated the trajectory.
The ADF is not computed for neighbors outside the force cutoff,
since processors (in parallel) don't know about atom coordinates for
diff --git a/doc/src/compute_ave_sphere_atom.rst b/doc/src/compute_ave_sphere_atom.rst
index ecb67ae7b5..4640b8534a 100644
--- a/doc/src/compute_ave_sphere_atom.rst
+++ b/doc/src/compute_ave_sphere_atom.rst
@@ -102,6 +102,8 @@ This compute is part of the EXTRA-COMPUTE package. It is only enabled
if LAMMPS was built with that package. See the :doc:`Build package
` page for more info.
+This compute requires :doc:`neighbor styles 'bin' or 'nsq' `.
+
Related commands
""""""""""""""""
diff --git a/doc/src/compute_composition_atom.rst b/doc/src/compute_composition_atom.rst
index e973eaa234..c3e6fb7c60 100644
--- a/doc/src/compute_composition_atom.rst
+++ b/doc/src/compute_composition_atom.rst
@@ -107,6 +107,8 @@ This compute is part of the EXTRA-COMPUTE package. It is only enabled
if LAMMPS was built with that package. See the :doc:`Build package
` page for more info.
+This compute requires :doc:`neighbor styles 'bin' or 'nsq' `.
+
Related commands
""""""""""""""""
diff --git a/doc/src/compute_count_type.rst b/doc/src/compute_count_type.rst
index ca3b02ecdb..5fbe6175a3 100644
--- a/doc/src/compute_count_type.rst
+++ b/doc/src/compute_count_type.rst
@@ -12,7 +12,7 @@ Syntax
* ID, group-ID are documented in :doc:`compute ` command
* count/type = style name of this compute command
-* mode = {atom} or {bond} or {angle} or {dihedral} or {improper}
+* mode = *atom* or *bond* or *angle* or *dihedral* or *improper*
Examples
""""""""
@@ -69,29 +69,42 @@ for each type:
----------
-If the {mode} setting is {atom} then the count of atoms for each atom
+If the *mode* setting is *atom* then the count of atoms for each atom
type is tallied. Only atoms in the specified group are counted.
-If the {mode} setting is {bond} then the count of bonds for each bond
+The atom count for each type can be normalized by the total number of
+atoms like so:
+
+.. code-block:: LAMMPS
+
+ compute typevec all count/type atom # number of atoms of each type
+ variable normtypes vector c_typevec/atoms # divide by total number of atoms
+ variable ntypes equal extract_setting(ntypes) # number of atom types
+ thermo_style custom step v_normtypes[*${ntypes}] # vector variable needs upper limit
+
+Similarly, bond counts can be normalized by the total number of bonds.
+The same goes for angles, dihedrals, and impropers (see below).
+
+If the *mode* setting is *bond* then the count of bonds for each bond
type is tallied. Only bonds with both atoms in the specified group
are counted.
-For {mode} = {bond}, broken bonds with a bond type of zero are also
+For *mode* = *bond*, broken bonds with a bond type of zero are also
counted. The :doc:`bond_style quartic ` and :doc:`BPM
-bond styles ` break bonds by doing this. See the :doc:`
-Howto broken bonds ` doc page for more details.
+bond styles ` break bonds by doing this. See the
+:doc:`Howto broken bonds ` doc page for more details.
Note that the group setting is ignored for broken bonds; all broken
bonds in the system are counted.
-If the {mode} setting is {angle} then the count of angles for each
+If the *mode* setting is *angle* then the count of angles for each
angle type is tallied. Only angles with all 3 atoms in the specified
group are counted.
-If the {mode} setting is {dihedral} then the count of dihedrals for
+If the *mode* setting is *dihedral* then the count of dihedrals for
each dihedral type is tallied. Only dihedrals with all 4 atoms in the
specified group are counted.
-If the {mode} setting is {improper} then the count of impropers for
+If the *mode* setting is *improper* then the count of impropers for
each improper type is tallied. Only impropers with all 4 atoms in the
specified group are counted.
@@ -101,18 +114,19 @@ Output info
"""""""""""
This compute calculates a global vector of counts. If the mode is
-{atom} or {bond} or {angle} or {dihedral} or {improper}, then the
+*atom* or *bond* or *angle* or *dihedral* or *improper*, then the
vector length is the number of atom types or bond types or angle types
or dihedral types or improper types, respectively.
-If the mode is {bond} this compute also calculates a global scalar
+If the mode is *bond* this compute also calculates a global scalar
which is the number of broken bonds with type = 0, as explained above.
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
` page for an overview of LAMMPS output options.
-The scalar and vector values calculated by this compute are "extensive".
+The scalar and vector values calculated by this compute are both
+"intensive".
Restrictions
""""""""""""
diff --git a/doc/src/compute_efield_wolf_atom.rst b/doc/src/compute_efield_wolf_atom.rst
index 1a709dc9f2..93bfa55151 100644
--- a/doc/src/compute_efield_wolf_atom.rst
+++ b/doc/src/compute_efield_wolf_atom.rst
@@ -106,6 +106,8 @@ Restrictions
This compute is part of the EXTRA-COMPUTE package. It is only enabled if
LAMMPS was built with that package.
+This compute requires :doc:`neighbor styles 'bin' or 'nsq' `.
+
Related commands
""""""""""""""""
diff --git a/doc/src/compute_fabric.rst b/doc/src/compute_fabric.rst
index b38ffafa48..77586e617a 100644
--- a/doc/src/compute_fabric.rst
+++ b/doc/src/compute_fabric.rst
@@ -64,7 +64,7 @@ tangential force tensor. The contact tensor is calculated as
.. math::
- C_{ab} = \frac{15}{2} (\phi_{ab} - \mathrm{Tr}(\phi) \delta_{ab})
+ C_{ab} = \frac{15}{2} (\phi_{ab} - \frac{1}{3} \mathrm{Tr}(\phi) \delta_{ab})
where :math:`a` and :math:`b` are the :math:`x`, :math:`y`, :math:`z`
directions, :math:`\delta_{ab}` is the Kronecker delta function, and
@@ -83,7 +83,7 @@ The branch tensor is calculated as
.. math::
- B_{ab} = \frac{15}{6 \mathrm{Tr}(D)} (D_{ab} - \mathrm{Tr}(D) \delta_{ab})
+ B_{ab} = \frac{15}{2\, \mathrm{Tr}(D)} (D_{ab} - \frac{1}{3} \mathrm{Tr}(D) \delta_{ab})
where the tensor :math:`D` is defined as
@@ -101,7 +101,7 @@ The normal force fabric tensor is calculated as
.. math::
- F^n_{ab} = \frac{15}{6\, \mathrm{Tr}(N)} (N_{ab} - \mathrm{Tr}(N) \delta_{ab})
+ F^n_{ab} = \frac{15}{2\, \mathrm{Tr}(N)} (N_{ab} - \frac{1}{3} \mathrm{Tr}(N) \delta_{ab})
where the tensor :math:`N` is defined as
@@ -119,7 +119,7 @@ as
.. math::
- F^t_{ab} = \frac{15}{9\, \mathrm{Tr}(N)} (T_{ab} - \mathrm{Tr}(T) \delta_{ab})
+ F^t_{ab} = \frac{5}{\mathrm{Tr}(N)} (T_{ab} - \frac{1}{3} \mathrm{Tr}(T) \delta_{ab})
where the tensor :math:`T` is defined as
diff --git a/doc/src/compute_mliap.rst b/doc/src/compute_mliap.rst
index 6abd3e5a6b..4bd5194bfd 100644
--- a/doc/src/compute_mliap.rst
+++ b/doc/src/compute_mliap.rst
@@ -20,7 +20,7 @@ Syntax
*model* values = style
style = *linear* or *quadratic* or *mliappy*
*descriptor* values = style filename
- style = *sna*
+ style = *sna* or *ace*
filename = name of file containing descriptor definitions
*gradgradflag* value = 0/1
toggle gradgrad method for force gradient
@@ -31,6 +31,7 @@ Examples
.. code-block:: LAMMPS
compute mliap model linear descriptor sna Ta06A.mliap.descriptor
+ compute mliap model linear descriptor ace H_N_O_ccs.yace gradgradflag 1
Description
"""""""""""
@@ -40,18 +41,15 @@ of machine-learning interatomic potentials with respect to model parameters.
It is used primarily for calculating the gradient of energy, force, and
stress components with respect to model parameters, which is useful when
training :doc:`mliap pair_style ` models to match target data.
-It provides separate
-definitions of the interatomic potential functional form (*model*)
-and the geometric quantities that characterize the atomic positions
-(*descriptor*). By defining *model* and *descriptor* separately,
+It provides separate definitions of the interatomic potential functional
+form (*model*) and the geometric quantities that characterize the atomic
+positions (*descriptor*). By defining *model* and *descriptor* separately,
it is possible to use many different models with a given descriptor,
-or many different descriptors with a given model. Currently, the
-compute supports just two models, *linear* and *quadratic*,
-and one descriptor, *sna*, the SNAP descriptor used by
-:doc:`pair_style snap `, including the linear, quadratic,
-and chem variants. Work is currently underway to extend
-the interface to handle neural network energy models,
-and it is also straightforward to add new descriptor styles.
+or many different descriptors with a given model. Currently, the compute
+supports *linear* and *quadratic* SNAP descriptor computes used in
+:doc:`pair_style snap `, *linear* SO3 descriptor computes, and
+*linear* ACE descriptor computes used in :doc:`pair_style pace `,
+and it is straightforward to add new descriptor styles.
The compute *mliap* command must be followed by two keywords
*model* and *descriptor* in either order.
@@ -60,19 +58,31 @@ The *model* keyword is followed by the model style (*linear*,
*quadratic* or *mliappy*). The *mliappy* model is only available if
LAMMPS is built with the *mliappy* Python module. There are
:ref:`specific installation instructions ` for that module.
+For the *mliap* compute, specifying a *linear* model will compute the
+specified descriptors and gradients with respect to linear model parameters
+whereas *quadratic* will do the same, but for the quadratic products of
+descriptors.
The *descriptor* keyword is followed by a descriptor style, and
-additional arguments. The compute currently supports two descriptor
-styles *sna* and *so3*, but it is is straightforward to add additional
-descriptor styles. The SNAP descriptor style *sna* is the same as that
-used by :doc:`pair_style snap `, including the linear,
-quadratic, and chem variants. A single additional argument specifies
-the descriptor filename containing the parameters and setting used by
-the SNAP descriptor. The descriptor filename usually ends in the
+additional arguments. The compute currently supports three descriptor
+styles: *sna*, *so3*, and *ace*, but it is is straightforward to add
+additional descriptor styles. The SNAP descriptor style *sna* is the
+same as that used by :doc:`pair_style snap `, including the
+linear, quadratic, and chem variants. A single additional argument
+specifies the descriptor filename containing the parameters and setting used
+by the SNAP descriptor. The descriptor filename usually ends in the
*.mliap.descriptor* extension. The format of this file is identical to
the descriptor file in the :doc:`pair_style mliap `, and is
described in detail there.
+The ACE descriptor style *ace* is the same as :doc:`pair_style pace `.
+A single additional argument specifies the *ace* descriptor filename
+that contains parameters and settings for the ACE descriptors. This file
+format differs from the SNAP or SO3 descriptor files, and has a *.yace* or
+*.ace* extension. However, as with other mliap descriptor styles, this file
+is identical to the ace descriptor file in :doc:`pair_style mliap