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

Update to latest changes from upstream

Browse Source
This commit is contained in:
Axel Kohlmeyer
2021-05-11 17:49:03 -04:00
parent b88cdd6890 3eef759bb1
commit 92c5951d6c
5027 changed files with 286731 additions and 199007 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.github/CONTRIBUTING.md vendored
View File

@ -26,11 +26,11 @@ __
## I don't want to read this whole thing I just have a question!
> **Note:** Please do not file an issue to ask a general question about LAMMPS, its features, how to use specific commands, or how perform simulations or analysis in LAMMPS. Instead post your question to the ['lammps-users' mailing list](https://lammps.sandia.gov/mail.html). You do not need to be subscribed to post to the list (but a mailing list subscription avoids having your post delayed until it is approved by a mailing list moderator). Most posts to the mailing list receive a response within less than 24 hours. Before posting to the mailing list, please read the [mailing list guidelines](https://lammps.sandia.gov/guidelines.html). Following those guidelines will help greatly to get a helpful response. Always mention which LAMMPS version you are using.
> **Note:** Please do not file an issue to ask a general question about LAMMPS, its features, how to use specific commands, or how perform simulations or analysis in LAMMPS. Instead post your question to either the ['lammps-users' mailing list](https://lammps.sandia.gov/mail.html) or the [LAMMPS Material Science Discourse forum](https://matsci.org/lammps). You do not need to be subscribed to post to the list (but a mailing list subscription avoids having your post delayed until it is approved by a mailing list moderator). Most posts to the mailing list receive a response within less than 24 hours. Before posting to the mailing list, please read the [mailing list guidelines](https://lammps.sandia.gov/guidelines.html). Following those guidelines will help greatly to get a helpful response. Always mention which LAMMPS version you are using. The LAMMPS forum was recently created as part of a larger effort to build a materials science community and have discussions not just about using LAMMPS. Thus the forum may be also used for discussions that would be off-topic for the mailing list. Those will just have to be moved to a more general category.
## How Can I Contribute?
There are several ways how you can actively contribute to the LAMMPS project: you can discuss compiling and using LAMMPS, and solving LAMMPS related problems with other LAMMPS users on the lammps-users mailing list, you can report bugs or suggest enhancements by creating issues on GitHub (or posting them to the lammps-users mailing list), and you can contribute by submitting pull requests on GitHub or e-mail your code
There are several ways how you can actively contribute to the LAMMPS project: you can discuss compiling and using LAMMPS, and solving LAMMPS related problems with other LAMMPS users on the lammps-users mailing list, you can report bugs or suggest enhancements by creating issues on GitHub (or posting them to the lammps-users mailing list or posting in the LAMMPS Materials Science Discourse forum), and you can contribute by submitting pull requests on GitHub or e-mail your code
to one of the [LAMMPS core developers](https://lammps.sandia.gov/authors.html). As you may see from the aforementioned developer page, the LAMMPS software package includes the efforts of a very large number of contributors beyond the principal authors and maintainers.
### Discussing How To Use LAMMPS
@ -42,6 +42,8 @@ Anyone can browse/search previous questions/answers in the archives. You do not
If you post a message and you are a subscriber, your message will appear immediately. If you are not a subscriber, your message will be moderated, which typically takes one business day. Either way, when someone replies the reply will usually be sent to both, your personal email address and the mailing list. When replying to people, that responded to your post to the list, please always included the mailing list in your replies (i.e. use "Reply All" and **not** "Reply"). Responses will appear on the list in a few minutes, but it can take a few hours for postings and replies to show up in the SourceForge archive. Sending replies also to the mailing list is important, so that responses are archived and people with a similar issue can search for possible solutions in the mailing list archive.
The LAMMPS Materials Science Discourse forum was created recently to facilitate discussion not just about LAMMPS and as part of a larger effort towards building a materials science community. The forum contains a read-only sub-category with the continually updated mailing list archive, so you won't miss anything by joining only the forum and not the mailing list.
### Reporting Bugs
While developers writing code for LAMMPS are careful to test their code, LAMMPS is such a large and complex software, that it is impossible to test for all combinations of features under all normal and not so normal circumstances. Thus bugs do happen, and if you suspect, that you have encountered one, please try to document it and report it as an [Issue](https://github.com/lammps/lammps/issues) on the LAMMPS GitHub project web page. However, before reporting a bug, you need to check whether this is something that may have already been corrected. The [Latest Features and Bug Fixes in LAMMPS](https://lammps.sandia.gov/bug.html) web page lists all significant changes to LAMMPS over the years. It also tells you what the current latest development version of LAMMPS is, and you should test whether your issue still applies to that version.

47
.github/workflows/codeql-analysis.yml vendored Normal file
View File

@ -0,0 +1,47 @@
# GitHub action to run static code analysis on C++ and Python code
name: "CodeQL Code Analysis"
on:
push:
branches: [master]
jobs:
analyze:
name: Analyze
if: ${{ github.repository == 'lammps/lammps' }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
language: ['cpp', 'python']
steps:
- name: Checkout repository
uses: actions/checkout@v2
with:
fetch-depth: 2
- name: Setup Python
uses: actions/setup-python@v2
with:
python-version: '3.x'
- name: Initialize CodeQL
uses: github/codeql-action/init@v1
with:
languages: ${{ matrix.language }}
- name: Create Build Environment
run: cmake -E make_directory ${{github.workspace}}/build
- name: Building LAMMPS via CMake
if: ${{ matrix.language == 'cpp' }}
shell: bash
working-directory: ${{github.workspace}}/build
run: |
cmake -C $GITHUB_WORKSPACE/cmake/presets/most.cmake $GITHUB_WORKSPACE/cmake
cmake --build . --parallel 2
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v1

54
.github/workflows/unittest-macos.yml vendored Normal file
View File

@ -0,0 +1,54 @@
# GitHub action to build LAMMPS on MacOS and run unit tests
name: "Unittest for MacOS"
on:
push:
branches: [master]
jobs:
build:
name: MacOS Unit Test
if: ${{ github.repository == 'lammps/lammps' }}
runs-on: macos-latest
env:
CCACHE_DIR: ${{ github.workspace }}/.ccache
steps:
- name: Checkout repository
uses: actions/checkout@v2
with:
fetch-depth: 2
- name: Install ccache
run: brew install ccache
- name: Create Build Environment
run: mkdir build
- name: Set up ccache
uses: actions/cache@v2
with:
path: ${{ env.CCACHE_DIR }}
key: macos-ccache-${{ github.sha }}
restore-keys: macos-ccache-
- name: Building LAMMPS via CMake
shell: bash
working-directory: build
run: |
ccache -z
cmake -C ../cmake/presets/clang.cmake \
-C ../cmake/presets/most.cmake \
-D CMAKE_CXX_COMPILER_LAUNCHER=ccache \
-D CMAKE_C_COMPILER_LAUNCHER=ccache \
-D ENABLE_TESTING=on \
-D BUILD_SHARED_LIBS=on \
-D LAMMPS_EXCEPTIONS=on \
../cmake
cmake --build . --parallel 2
ccache -s
- name: Run Tests
working-directory: build
shell: bash
run: ctest -V

5
LICENSE
View File

@ -301,9 +301,8 @@ one line to give the program's name and an idea of what it does.
Copyright (C) yyyy name of author
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.
it under the terms of the GNU General Public License version 2 as
published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of

150
cmake/CMakeLists.txt
View File

@ -22,18 +22,30 @@ set(LAMMPS_TOOLS_DIR ${LAMMPS_DIR}/tools)
set(LAMMPS_PYTHON_DIR ${LAMMPS_DIR}/python)
set(LAMMPS_POTENTIALS_DIR ${LAMMPS_DIR}/potentials)
set(LAMMPS_DOWNLOADS_URL "https://download.lammps.org" CACHE STRING "Base URL for LAMMPS downloads")
set(LAMMPS_POTENTIALS_URL "${LAMMPS_DOWNLOADS_URL}/potentials")
set(LAMMPS_THIRDPARTY_URL "${LAMMPS_DOWNLOADS_URL}/thirdparty")
mark_as_advanced(LAMMPS_DOWNLOADS_URL)
find_package(Git)
# by default, install into $HOME/.local (not /usr/local), so that no root access (and sudo!!) is needed
if (CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
set(CMAKE_INSTALL_PREFIX "$ENV{HOME}/.local" CACHE PATH "default install path" FORCE )
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
set(CMAKE_INSTALL_PREFIX "$ENV{HOME}/.local" CACHE PATH "Default install path" FORCE)
endif()
# If enabled, no need to use LD_LIBRARY_PATH / DYLD_LIBRARY_PATH when installed
option(LAMMPS_INSTALL_RPATH "Set runtime path for shared libraries linked to LAMMPS binaries" OFF)
if(LAMMPS_INSTALL_RPATH)
set(CMAKE_INSTALL_RPATH ${CMAKE_INSTALL_FULL_LIBDIR})
set(CMAKE_INSTALL_RPATH_USE_LINK_PATH ON)
endif()
# Cmake modules/macros are in a subdirectory to keep this file cleaner
set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/Modules)
# make sure LIBRARY_PATH is set if environment variable is set
if (DEFINED ENV{LIBRARY_PATH})
if(DEFINED ENV{LIBRARY_PATH})
list(APPEND CMAKE_LIBRARY_PATH "$ENV{LIBRARY_PATH}")
message(STATUS "Appending $ENV{LIBRARY_PATH} to CMAKE_LIBRARY_PATH: ${CMAKE_LIBRARY_PATH}")
endif()
@ -106,14 +118,16 @@ option(CMAKE_VERBOSE_MAKEFILE "Generate verbose Makefiles" OFF)
set(STANDARD_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS DIPOLE
GRANULAR KSPACE LATTE MANYBODY MC MESSAGE MISC MLIAP MOLECULE PERI POEMS
QEQ REPLICA RIGID SHOCK SPIN SNAP SRD KIM PYTHON MSCG MPIIO VORONOI
USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-MESODPD USER-CGSDK USER-COLVARS
USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP USER-H5MD USER-LB
USER-MANIFOLD USER-MEAMC USER-MESONT USER-MGPT USER-MISC USER-MOFFF USER-MOLFILE
USER-NETCDF USER-PHONON USER-PLUMED USER-PTM USER-QTB USER-REACTION
USER-REAXC USER-SCAFACOS USER-SDPD USER-SMD USER-SMTBQ USER-SPH USER-TALLY
USER-UEF USER-VTK USER-QUIP USER-QMMM USER-YAFF USER-ADIOS USER-BROWNIAN)
set(SUFFIX_PACKAGES CORESHELL USER-OMP KOKKOS OPT USER-INTEL GPU)
PLUGIN QEQ REPLICA RIGID SHOCK SPIN SNAP SRD KIM PYTHON MSCG MPIIO VORONOI
USER-ADIOS USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-MESODPD USER-CGSDK
USER-COLVARS USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP USER-H5MD
USER-LB USER-MANIFOLD USER-MEAMC USER-MESONT USER-MGPT USER-MISC USER-MOFFF
USER-MOLFILE USER-NETCDF USER-PHONON USER-PLUMED USER-PTM USER-QTB
USER-REACTION USER-REAXC USER-SCAFACOS USER-SDPD USER-SMD USER-SMTBQ USER-SPH
USER-TALLY USER-UEF USER-VTK USER-QUIP USER-QMMM USER-YAFF USER-PACE USER-BROWNIAN)
set(SUFFIX_PACKAGES CORESHELL GPU KOKKOS OPT USER-INTEL USER-OMP)
foreach(PKG ${STANDARD_PACKAGES} ${SUFFIX_PACKAGES})
option(PKG_${PKG} "Build ${PKG} Package" OFF)
endforeach()
@ -154,8 +168,7 @@ if(BUILD_MPI)
endif()
endif()
else()
enable_language(C)
file(GLOB MPI_SOURCES ${LAMMPS_SOURCE_DIR}/STUBS/mpi.c)
file(GLOB MPI_SOURCES ${LAMMPS_SOURCE_DIR}/STUBS/mpi.cpp)
add_library(mpi_stubs STATIC ${MPI_SOURCES})
set_target_properties(mpi_stubs PROPERTIES OUTPUT_NAME lammps_mpi_stubs${LAMMPS_MACHINE})
target_include_directories(mpi_stubs PUBLIC $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
@ -220,6 +233,7 @@ if(BUILD_OMP)
endif()
if (((CMAKE_CXX_COMPILER_ID STREQUAL "GNU") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 9.0)) OR
(CMAKE_CXX_COMPILER_ID STREQUAL "PGI") OR
((CMAKE_CXX_COMPILER_ID STREQUAL "Clang") 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.
@ -231,68 +245,6 @@ if(BUILD_OMP)
target_link_libraries(lammps PRIVATE OpenMP::OpenMP_CXX)
endif()
# Compiler specific features for testing
if(${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
option(ENABLE_COVERAGE "Enable collecting code coverage data" OFF)
mark_as_advanced(ENABLE_COVERAGE)
if(ENABLE_COVERAGE)
if(CMAKE_VERSION VERSION_LESS 3.13)
if(CMAKE_CXX_FLAGS)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} --coverage")
else()
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_${CMAKE_BUILD_TYPE}_FLAGS} --coverage")
endif()
else()
target_compile_options(lammps PUBLIC --coverage)
target_link_options(lammps PUBLIC --coverage)
endif()
endif()
endif()
#######################################
# add custom target for IWYU analysis
#######################################
set(ENABLE_IWYU OFF CACHE BOOL "Add 'iwyu' build target to call the include-what-you-use tool")
mark_as_advanced(ENABLE_IWYU)
if(ENABLE_IWYU)
find_program(IWYU_EXE NAMES include-what-you-use iwyu)
find_program(IWYU_TOOL NAMES iwyu_tool iwyu-tool iwyu_tool.py)
if (IWYU_EXE AND IWYU_TOOL)
add_custom_target(
iwyu
${IWYU_TOOL} -o clang -p ${CMAKE_CURRENT_BINARY_DIR} -- -Xiwyu --mapping_file=${CMAKE_CURRENT_SOURCE_DIR}/iwyu/iwyu-extra-map.imp
COMMENT "Running IWYU")
add_dependencies(iwyu lammps)
else()
message(FATAL_ERROR "To use IWYU you need the include-what-you-use/iwyu executable"
"and the iwyu-tool/iwyu_tool script installed in your PATH")
endif()
endif()
set(ENABLE_SANITIZER "none" CACHE STRING "Select a code sanitizer option (none (default), address, leak, thread, undefined)")
mark_as_advanced(ENABLE_SANITIZER)
set(ENABLE_SANITIZER_VALUES none address leak thread undefined)
set_property(CACHE ENABLE_SANITIZER PROPERTY STRINGS ${ENABLE_SANITIZER_VALUES})
validate_option(ENABLE_SANITIZER ENABLE_SANITIZER_VALUES)
string(TOLOWER ${ENABLE_SANITIZER} ENABLE_SANITIZER)
if(NOT ENABLE_SANITIZER STREQUAL "none")
if((${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU") OR (${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang"))
if(CMAKE_VERSION VERSION_LESS 3.13)
if(CMAKE_CXX_FLAGS)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=${ENABLE_SANITIZER}")
else()
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_${CMAKE_BUILD_TYPE}_FLAGS} -fsanitize=${ENABLE_SANITIZER}")
endif()
else()
target_compile_options(lammps PUBLIC -fsanitize=${ENABLE_SANITIZER})
target_link_options(lammps PUBLIC -fsanitize=${ENABLE_SANITIZER})
endif()
else()
message(WARNING "ENABLE_SANITIZER option not supported by ${CMAKE_CXX_COMPILER_ID} compilers. Ignoring.")
set(ENABLE_SANITIZER "none")
endif()
endif()
if(PKG_MSCG OR PKG_USER-ATC OR PKG_USER-AWPMD OR PKG_USER-QUIP OR PKG_LATTE)
enable_language(C)
find_package(LAPACK)
@ -372,8 +324,8 @@ else()
set(CUDA_REQUEST_PIC)
endif()
foreach(PKG_WITH_INCL KSPACE PYTHON VORONOI USER-COLVARS USER-MOLFILE USER-NETCDF USER-PLUMED USER-QMMM
USER-QUIP USER-SCAFACOS USER-SMD USER-VTK KIM LATTE MESSAGE MSCG COMPRESS)
foreach(PKG_WITH_INCL KSPACE PYTHON MLIAP VORONOI USER-COLVARS USER-MOLFILE USER-NETCDF USER-PLUMED USER-QMMM
USER-QUIP USER-SCAFACOS USER-SMD USER-VTK KIM LATTE MESSAGE MSCG COMPRESS USER-PACE)
if(PKG_${PKG_WITH_INCL})
include(Packages/${PKG_WITH_INCL})
endif()
@ -524,6 +476,18 @@ foreach(PKG_WITH_INCL CORESHELL QEQ USER-OMP USER-SDPD KOKKOS OPT USER-INTEL GPU
endif()
endforeach()
if(PKG_PLUGIN)
if(BUILD_SHARED_LIBS)
target_compile_definitions(lammps PRIVATE -DLMP_PLUGIN)
else()
message(WARNING "Plugin loading will not work unless BUILD_SHARED_LIBS is enabled")
endif()
# link with -ldl or equivalent for plugin loading; except on Windows
if(NOT ${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
target_link_libraries(lammps PRIVATE ${CMAKE_DL_LIBS})
endif()
endif()
######################################################################
# the windows version of LAMMPS requires a couple extra libraries
# and the MPI library - if use - has to be linked right before those
@ -579,7 +543,7 @@ add_dependencies(lammps gitversion)
############################################
get_property(LANGUAGES GLOBAL PROPERTY ENABLED_LANGUAGES)
list (FIND LANGUAGES "Fortran" _index)
if (${_index} GREATER -1)
if(${_index} GREATER -1)
target_link_libraries(lammps PRIVATE ${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES})
endif()
set(LAMMPS_CXX_HEADERS angle.h atom.h bond.h citeme.h comm.h compute.h dihedral.h domain.h error.h fix.h force.h group.h improper.h
@ -649,7 +613,7 @@ install(
if(BUILD_SHARED_LIBS)
if(CMAKE_VERSION VERSION_LESS 3.12)
# adjust so we find Python 3 versions before Python 2 on old systems with old CMake
set(Python_ADDITIONAL_VERSIONS 3.8 3.7 3.6 3.5)
set(Python_ADDITIONAL_VERSIONS 3.9 3.8 3.7 3.6 3.5)
find_package(PythonInterp) # Deprecated since version 3.12
if(PYTHONINTERP_FOUND)
set(Python_EXECUTABLE ${PYTHON_EXECUTABLE})
@ -659,10 +623,10 @@ if(BUILD_SHARED_LIBS)
endif()
if (Python_EXECUTABLE)
add_custom_target(
install-python
${Python_EXECUTABLE} install.py -v ${LAMMPS_SOURCE_DIR}/version.h
-m ${LAMMPS_PYTHON_DIR}/lammps.py
-l ${CMAKE_BINARY_DIR}/liblammps${CMAKE_SHARED_LIBRARY_SUFFIX}
install-python ${CMAKE_COMMAND} -E remove_directory build
COMMAND ${Python_EXECUTABLE} install.py -v ${LAMMPS_SOURCE_DIR}/version.h
-p ${LAMMPS_PYTHON_DIR}/lammps
-l ${CMAKE_BINARY_DIR}/liblammps${LAMMPS_MACHINE}${CMAKE_SHARED_LIBRARY_SUFFIX}
WORKING_DIRECTORY ${LAMMPS_PYTHON_DIR}
COMMENT "Installing LAMMPS Python module")
else()
@ -691,11 +655,8 @@ if(BUILD_SHARED_LIBS OR PKG_PYTHON)
find_package(Python COMPONENTS Interpreter)
endif()
if (Python_EXECUTABLE)
execute_process(COMMAND ${Python_EXECUTABLE}
-c "import distutils.sysconfig as cg; print(cg.get_python_lib(1,0,prefix='${CMAKE_INSTALL_PREFIX}'))"
OUTPUT_VARIABLE PYTHON_DEFAULT_INSTDIR OUTPUT_STRIP_TRAILING_WHITESPACE)
set(PYTHON_INSTDIR ${PYTHON_DEFAULT_INSTDIR} CACHE PATH "Installation folder for LAMMPS Python module")
install(FILES ${LAMMPS_PYTHON_DIR}/lammps.py DESTINATION ${PYTHON_INSTDIR})
file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/python)
install(CODE "execute_process(COMMAND ${Python_EXECUTABLE} setup.py build -b ${CMAKE_BINARY_DIR}/python install --prefix=${CMAKE_INSTALL_PREFIX} --root=\$ENV{DESTDIR}/ WORKING_DIRECTORY ${LAMMPS_PYTHON_DIR})")
endif()
endif()
@ -707,7 +668,7 @@ get_target_property(DEFINES lammps COMPILE_DEFINITIONS)
include(FeatureSummary)
feature_summary(DESCRIPTION "The following tools and libraries have been found and configured:" WHAT PACKAGES_FOUND)
message(STATUS "<<< Build configuration >>>
Operating System: ${CMAKE_SYSTEM_NAME}
Operating System: ${CMAKE_SYSTEM_NAME} ${CMAKE_LINUX_DISTRO} ${CMAKE_DISTRO_VERSION}
Build type: ${CMAKE_BUILD_TYPE}
Install path: ${CMAKE_INSTALL_PREFIX}
Generator: ${CMAKE_GENERATOR} using ${CMAKE_MAKE_PROGRAM}")
@ -739,14 +700,14 @@ if(OPTIONS)
endif()
get_property(LANGUAGES GLOBAL PROPERTY ENABLED_LANGUAGES)
list (FIND LANGUAGES "Fortran" _index)
if (${_index} GREATER -1)
if(${_index} GREATER -1)
message(STATUS "Fortran Compiler: ${CMAKE_Fortran_COMPILER}
Type: ${CMAKE_Fortran_COMPILER_ID}
Version: ${CMAKE_Fortran_COMPILER_VERSION}
Fortran Flags:${CMAKE_Fortran_FLAGS} ${CMAKE_Fortran_FLAGS_${BTYPE}}")
endif()
list (FIND LANGUAGES "C" _index)
if (${_index} GREATER -1)
if(${_index} GREATER -1)
message(STATUS "C compiler: ${CMAKE_C_COMPILER}
Type: ${CMAKE_C_COMPILER_ID}
Version: ${CMAKE_C_COMPILER_VERSION}
@ -778,9 +739,10 @@ if(PKG_GPU)
message(STATUS "<<< GPU package settings >>>
-- GPU API: ${GPU_API}")
if(GPU_API STREQUAL "CUDA")
message(STATUS "GPU architecture: ${GPU_ARCH}")
elseif(GPU_API STREQUAL "OPENCL")
message(STATUS "OpenCL tuning: ${OCL_TUNE}")
message(STATUS "CUDA Compiler: ${CUDA_NVCC_EXECUTABLE}")
message(STATUS "GPU default architecture: ${GPU_ARCH}")
message(STATUS "GPU binning with CUDPP: ${CUDPP_OPT}")
message(STATUS "CUDA MPS support: ${CUDA_MPS_SUPPORT}")
elseif(GPU_API STREQUAL "HIP")
message(STATUS "HIP platform: ${HIP_PLATFORM}")
message(STATUS "HIP architecture: ${HIP_ARCH}")

2
cmake/Modules/CodingStandard.cmake
View File

@ -8,7 +8,7 @@ else()
find_package(Python3 COMPONENTS Interpreter QUIET)
endif()
if (Python3_EXECUTABLE)
if(Python3_EXECUTABLE)
if(Python3_VERSION VERSION_GREATER_EQUAL 3.5)
add_custom_target(
check-whitespace

14
cmake/Modules/Documentation.cmake
View File

@ -50,16 +50,20 @@ if(BUILD_DOC)
OUTPUT ${DOC_BUILD_DIR}/requirements.txt
DEPENDS docenv ${DOCENV_REQUIREMENTS_FILE}
COMMAND ${CMAKE_COMMAND} -E copy ${DOCENV_REQUIREMENTS_FILE} ${DOC_BUILD_DIR}/requirements.txt
COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade pip
COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade ${LAMMPS_DOC_DIR}/utils/converters
COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r ${DOC_BUILD_DIR}/requirements.txt --upgrade
COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install --upgrade pip
COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install --upgrade ${LAMMPS_DOC_DIR}/utils/converters
COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install -r ${DOC_BUILD_DIR}/requirements.txt --upgrade
)
set(MATHJAX_URL "https://github.com/mathjax/MathJax/archive/3.1.3.tar.gz" CACHE STRING "URL for MathJax tarball")
set(MATHJAX_MD5 "d1c98c746888bfd52ca8ebc10704f92f" CACHE STRING "MD5 checksum of MathJax tarball")
mark_as_advanced(MATHJAX_URL)
# download mathjax distribution and unpack to folder "mathjax"
if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/mathjax/es5)
file(DOWNLOAD "https://github.com/mathjax/MathJax/archive/3.1.2.tar.gz"
file(DOWNLOAD ${MATHJAX_URL}
"${CMAKE_CURRENT_BINARY_DIR}/mathjax.tar.gz"
EXPECTED_MD5 a4a6a093a89bc2ccab1452d766b98e53)
EXPECTED_MD5 ${MATHJAX_MD5})
execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf mathjax.tar.gz WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
file(GLOB MATHJAX_VERSION_DIR ${CMAKE_CURRENT_BINARY_DIR}/MathJax-*)
execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${DOC_BUILD_STATIC_DIR}/mathjax)

30
cmake/Modules/FindCythonize.cmake Normal file
View File

@ -0,0 +1,30 @@
# Find the Cythonize tool.
#
# This code sets the following variables:
#
# Cythonize_EXECUTABLE
#
# adapted from https://github.com/cmarshall108/cython-cmake-example/blob/master/cmake/FindCython.cmake
#=============================================================================
if(CMAKE_VERSION VERSION_LESS 3.12)
find_package(PythonInterp 3.6 QUIET) # Deprecated since version 3.12
if(PYTHONINTERP_FOUND)
set(Python3_EXECUTABLE ${PYTHON_EXECUTABLE})
endif()
else()
find_package(Python3 3.6 COMPONENTS Interpreter QUIET)
endif()
# Use the Cython executable that lives next to the Python executable
# if it is a local installation.
if(Python3_EXECUTABLE)
get_filename_component(_python_path ${Python3_EXECUTABLE} PATH)
find_program(Cythonize_EXECUTABLE
NAMES cythonize3 cythonize cythonize.bat
HINTS ${_python_path})
endif()
include(FindPackageHandleStandardArgs)
FIND_PACKAGE_HANDLE_STANDARD_ARGS(Cythonize REQUIRED_VARS Cythonize_EXECUTABLE)
mark_as_advanced(Cythonize_EXECUTABLE)

20
cmake/Modules/GTest.cmake
View File

@ -8,10 +8,12 @@ endif()
include(ExternalProject)
set(GTEST_URL "https://github.com/google/googletest/archive/release-1.10.0.tar.gz" CACHE STRING "URL for GTest tarball")
set(GTEST_MD5 "ecd1fa65e7de707cd5c00bdac56022cd" CACHE STRING "MD5 checksum of GTest tarball")
mark_as_advanced(GTEST_URL)
mark_as_advanced(GTEST_MD5)
ExternalProject_Add(googletest
URL ${GTEST_URL}
URL_MD5 ecd1fa65e7de707cd5c00bdac56022cd
URL_MD5 ${GTEST_MD5}
SOURCE_DIR "${CMAKE_BINARY_DIR}/gtest-src"
BINARY_DIR "${CMAKE_BINARY_DIR}/gtest-build"
CMAKE_ARGS ${CMAKE_REQUEST_PIC} ${CMAKE_EXTRA_GTEST_OPTS}
@ -20,10 +22,10 @@ ExternalProject_Add(googletest
-DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
-DCMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM}
-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
BUILD_BYPRODUCTS <BINARY_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gtest${GTEST_LIB_POSTFIX}.a
<BINARY_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gmock${GTEST_LIB_POSTFIX}.a
<BINARY_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gtest_main${GTEST_LIB_POSTFIX}.a
<BINARY_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gmock_main${GTEST_LIB_POSTFIX}.a
BUILD_BYPRODUCTS <BINARY_DIR>/lib/libgtest${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
<BINARY_DIR>/lib/libgmock${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
<BINARY_DIR>/lib/libgtest_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
<BINARY_DIR>/lib/libgmock_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
LOG_DOWNLOAD ON
LOG_CONFIGURE ON
LOG_BUILD ON
@ -39,10 +41,10 @@ file(MAKE_DIRECTORY ${GTEST_INCLUDE_DIR})
file(MAKE_DIRECTORY ${GMOCK_INCLUDE_DIR})
ExternalProject_Get_Property(googletest BINARY_DIR)
set(GTEST_LIBRARY_PATH ${BINARY_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gtest${GTEST_LIB_POSTFIX}.a)
set(GMOCK_LIBRARY_PATH ${BINARY_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gmock${GTEST_LIB_POSTFIX}.a)
set(GTEST_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gtest_main${GTEST_LIB_POSTFIX}.a)
set(GMOCK_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gmock_main${GTEST_LIB_POSTFIX}.a)
set(GTEST_LIBRARY_PATH ${BINARY_DIR}/lib/libgtest${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
set(GMOCK_LIBRARY_PATH ${BINARY_DIR}/lib/libgmock${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
set(GTEST_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/libgtest_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
set(GMOCK_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/libgmock_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
# Prevent GoogleTest from overriding our compiler/linker options
# when building with Visual Studio

3
cmake/Modules/GenerateOpenCLHeader.cmake Normal file
View File

@ -0,0 +1,3 @@
# utility script to call WriteOpenCLHeader function
include(${SOURCE_DIR}/Modules/OpenCLUtils.cmake)
WriteOpenCLHeader(${VARNAME} ${HEADER_FILE} ${SOURCE_FILES})

12
cmake/Modules/LAMMPSUtils.cmake
View File

@ -50,6 +50,7 @@ function(check_for_autogen_files source_dir)
file(GLOB SRC_AUTOGEN_FILES ${source_dir}/style_*.h)
file(GLOB SRC_AUTOGEN_PACKAGES ${source_dir}/packages_*.h)
list(APPEND SRC_AUTOGEN_FILES ${SRC_AUTOGEN_PACKAGES} ${source_dir}/lmpinstalledpkgs.h ${source_dir}/lmpgitversion.h)
list(APPEND SRC_AUTOGEN_FILES ${SRC_AUTOGEN_PACKAGES} ${source_dir}/mliap_model_python_couple.h ${source_dir}/mliap_model_python_couple.cpp)
foreach(_SRC ${SRC_AUTOGEN_FILES})
get_filename_component(FILENAME "${_SRC}" NAME)
if(EXISTS ${source_dir}/${FILENAME})
@ -85,7 +86,6 @@ endfunction(GenerateBinaryHeader)
# fetch missing potential files
function(FetchPotentials pkgfolder potfolder)
if (EXISTS "${pkgfolder}/potentials.txt")
set(LAMMPS_POTENTIALS_URL "https://download.lammps.org/potentials")
file(STRINGS "${pkgfolder}/potentials.txt" linelist REGEX "^[^#].")
foreach(line ${linelist})
string(FIND ${line} " " blank)
@ -104,3 +104,13 @@ function(FetchPotentials pkgfolder potfolder)
endforeach()
endif()
endfunction(FetchPotentials)
# set CMAKE_LINUX_DISTRO and CMAKE_DISTRO_VERSION on Linux
if((CMAKE_SYSTEM_NAME STREQUAL Linux) AND (EXISTS /etc/os-release))
file(STRINGS /etc/os-release distro REGEX "^NAME=")
string(REGEX REPLACE "NAME=\"?([^\"]*)\"?" "\\1" distro "${distro}")
file(STRINGS /etc/os-release disversion REGEX "^VERSION_ID=")
string(REGEX REPLACE "VERSION_ID=\"?([^\"]*)\"?" "\\1" disversion "${disversion}")
set(CMAKE_LINUX_DISTRO ${distro})
set(CMAKE_DISTRO_VERSION ${disversion})
endif()

19
cmake/Modules/MPI4WIN.cmake
View File

@ -1,16 +1,25 @@
# Download and configure custom MPICH files for Windows
message(STATUS "Downloading and configuring MPICH-1.4.1 for Windows")
set(MPICH2_WIN64_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/mpich2-win64-devel.tar.gz" CACHE STRING "URL for MPICH2 (win64) tarball")
set(MPICH2_WIN32_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/mpich2-win32-devel.tar.gz" CACHE STRING "URL for MPICH2 (win32) tarball")
set(MPICH2_WIN64_DEVEL_MD5 "4939fdb59d13182fd5dd65211e469f14" CACHE STRING "MD5 checksum of MPICH2 (win64) tarball")
set(MPICH2_WIN32_DEVEL_MD5 "a61d153500dce44e21b755ee7257e031" CACHE STRING "MD5 checksum of MPICH2 (win32) tarball")
mark_as_advanced(MPICH2_WIN64_DEVEL_URL)
mark_as_advanced(MPICH2_WIN32_DEVEL_URL)
mark_as_advanced(MPICH2_WIN64_DEVEL_MD5)
mark_as_advanced(MPICH2_WIN32_DEVEL_MD5)
include(ExternalProject)
if (CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
ExternalProject_Add(mpi4win_build
URL https://download.lammps.org/thirdparty/mpich2-win64-devel.tar.gz
URL_MD5 4939fdb59d13182fd5dd65211e469f14
URL ${MPICH2_WIN64_DEVEL_URL}
URL_MD5 ${MPICH2_WIN64_DEVEL_MD5}
CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmpi.a)
else()
ExternalProject_Add(mpi4win_build
URL https://download.lammps.org/thirdparty/mpich2-win32-devel.tar.gz
URL_MD5 a61d153500dce44e21b755ee7257e031
URL ${MPICH2_WIN32_DEVEL_URL}
URL_MD5 ${MPICH2_WIN32_DEVEL_MD5}
CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmpi.a)
endif()

50
cmake/Modules/OpenCLLoader.cmake Normal file
View File

@ -0,0 +1,50 @@
message(STATUS "Downloading and building OpenCL loader library")
set(OPENCL_LOADER_URL "${LAMMPS_THIRDPARTY_URL}/opencl-loader-2021.05.02.tar.gz" CACHE STRING "URL for OpenCL loader tarball")
set(OPENCL_LOADER_MD5 "29180b05056578afda92f0d394c3a373" CACHE STRING "MD5 checksum of OpenCL loader tarball")
mark_as_advanced(OPENCL_LOADER_URL)
mark_as_advanced(OPENCL_LOADER_MD5)
include(ExternalProject)
ExternalProject_Add(opencl_loader
URL ${OPENCL_LOADER_URL}
URL_MD5 ${OPENCL_LOADER_MD5}
SOURCE_DIR "${CMAKE_BINARY_DIR}/opencl_loader-src"
BINARY_DIR "${CMAKE_BINARY_DIR}/opencl_loader-build"
CMAKE_ARGS ${CMAKE_REQUEST_PIC} ${CMAKE_EXTRA_OPENCL_LOADER_OPTS}
-DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
-DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>
-DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
-DCMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM}
-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
BUILD_BYPRODUCTS <BINARY_DIR>/libOpenCL${CMAKE_STATIC_LIBRARY_SUFFIX}
LOG_DOWNLOAD ON
LOG_CONFIGURE ON
LOG_BUILD ON
INSTALL_COMMAND ""
TEST_COMMAND "")
ExternalProject_Get_Property(opencl_loader SOURCE_DIR)
set(OPENCL_LOADER_INCLUDE_DIR ${SOURCE_DIR}/inc)
# workaround for CMake 3.10 on ubuntu 18.04
file(MAKE_DIRECTORY ${OPENCL_LOADER_INCLUDE_DIR})
ExternalProject_Get_Property(opencl_loader BINARY_DIR)
set(OPENCL_LOADER_LIBRARY_PATH "${BINARY_DIR}/libOpenCL${CMAKE_STATIC_LIBRARY_SUFFIX}")
find_package(Threads QUIET)
if(NOT WIN32)
set(OPENCL_LOADER_DEP_LIBS "Threads::Threads;${CMAKE_DL_LIBS}")
else()
set(OPENCL_LOADER_DEP_LIBS "cfgmgr32;runtimeobject")
endif()
add_library(OpenCL::OpenCL UNKNOWN IMPORTED)
add_dependencies(OpenCL::OpenCL opencl_loader)
set_target_properties(OpenCL::OpenCL PROPERTIES
IMPORTED_LOCATION ${OPENCL_LOADER_LIBRARY_PATH}
INTERFACE_INCLUDE_DIRECTORIES ${OPENCL_LOADER_INCLUDE_DIR}
INTERFACE_LINK_LIBRARIES "${OPENCL_LOADER_DEP_LIBS}")

20
cmake/Modules/OpenCLUtils.cmake
View File

@ -1,10 +1,8 @@
function(GenerateOpenCLHeader varname outfile files)
message("Creating ${outfile}...")
function(WriteOpenCLHeader varname outfile files)
file(WRITE ${outfile} "const char * ${varname} = \n")
math(EXPR ARG_END "${ARGC}-1")
separate_arguments(files)
foreach(IDX RANGE 2 ${ARG_END})
list(GET ARGV ${IDX} filename)
foreach(filename ${files})
file(READ ${filename} content)
string(REGEX REPLACE "\\s*//[^\n]*\n" "\n" content "${content}")
string(REGEX REPLACE "\\\\" "\\\\\\\\" content "${content}")
@ -15,4 +13,16 @@ function(GenerateOpenCLHeader varname outfile files)
endforeach()
file(APPEND ${outfile} ";\n")
endfunction(WriteOpenCLHeader)
function(GenerateOpenCLHeader varname outfile files)
list(REMOVE_AT ARGV 0 1)
add_custom_command(OUTPUT ${outfile}
COMMAND ${CMAKE_COMMAND} -D SOURCE_DIR=${CMAKE_CURRENT_SOURCE_DIR}
-D VARNAME=${varname}
-D HEADER_FILE=${outfile}
-D SOURCE_FILES="${ARGV}"
-P ${CMAKE_CURRENT_SOURCE_DIR}/Modules/GenerateOpenCLHeader.cmake
DEPENDS ${ARGV}
COMMENT "Generating ${outfile}...")
endfunction(GenerateOpenCLHeader)

86
cmake/Modules/Packages/GPU.cmake
View File

@ -1,7 +1,10 @@
set(GPU_SOURCES_DIR ${LAMMPS_SOURCE_DIR}/GPU)
set(GPU_SOURCES ${GPU_SOURCES_DIR}/gpu_extra.h
${GPU_SOURCES_DIR}/fix_gpu.h
${GPU_SOURCES_DIR}/fix_gpu.cpp)
${GPU_SOURCES_DIR}/fix_gpu.cpp
${GPU_SOURCES_DIR}/fix_nh_gpu.h
${GPU_SOURCES_DIR}/fix_nh_gpu.cpp)
target_compile_definitions(lammps PRIVATE -DLMP_GPU)
set(GPU_API "opencl" CACHE STRING "API used by GPU package")
set(GPU_API_VALUES opencl cuda hip)
@ -32,9 +35,12 @@ if(GPU_API STREQUAL "CUDA")
if(NOT BIN2C)
message(FATAL_ERROR "Could not find bin2c, use -DBIN2C=/path/to/bin2c to help cmake finding it.")
endif()
option(CUDPP_OPT "Enable CUDPP_OPT" ON)
option(CUDPP_OPT "Enable GPU binning via CUDAPP (should be off for modern GPUs)" OFF)
option(CUDA_MPS_SUPPORT "Enable tweaks to support CUDA Multi-process service (MPS)" OFF)
if(CUDA_MPS_SUPPORT)
if(CUDPP_OPT)
message(FATAL_ERROR "Must use -DCUDPP_OPT=OFF with -DGPU_CUDA_MPS_SUPPORT=ON")
endif()
set(GPU_CUDA_MPS_FLAGS "-DCUDA_PROXY")
endif()
@ -97,15 +103,19 @@ if(GPU_API STREQUAL "CUDA")
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_80,code=[sm_80,compute_80]")
endif()
# Ampere (GPU Arch 8.6) is supported by CUDA 11.1 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.1")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_86,code=[sm_86,compute_86]")
endif()
if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
message(WARNING "Unsupported CUDA version. Use at your own risk.")
endif()
cuda_compile_fatbin(GPU_GEN_OBJS ${GPU_LIB_CU} OPTIONS ${CUDA_REQUEST_PIC}
-DUNIX -O3 --use_fast_math -Wno-deprecated-gpu-targets -DNV_KERNEL -DUCL_CUDADR ${GPU_CUDA_GENCODE} -D_${GPU_PREC_SETTING})
-DUNIX -O3 --use_fast_math -Wno-deprecated-gpu-targets -DNV_KERNEL -DUCL_CUDADR ${GPU_CUDA_GENCODE} -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES})
cuda_compile(GPU_OBJS ${GPU_LIB_CUDPP_CU} OPTIONS ${CUDA_REQUEST_PIC}
-DUNIX -O3 --use_fast_math -Wno-deprecated-gpu-targets -DUCL_CUDADR ${GPU_CUDA_GENCODE} -D_${GPU_PREC_SETTING})
-DUNIX -O3 --use_fast_math -Wno-deprecated-gpu-targets -DUCL_CUDADR ${GPU_CUDA_GENCODE} -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES})
foreach(CU_OBJ ${GPU_GEN_OBJS})
get_filename_component(CU_NAME ${CU_OBJ} NAME_WE)
@ -121,7 +131,7 @@ if(GPU_API STREQUAL "CUDA")
add_library(gpu STATIC ${GPU_LIB_SOURCES} ${GPU_LIB_CUDPP_SOURCES} ${GPU_OBJS})
target_link_libraries(gpu PRIVATE ${CUDA_LIBRARIES} ${CUDA_CUDA_LIBRARY})
target_include_directories(gpu PRIVATE ${LAMMPS_LIB_BINARY_DIR}/gpu ${CUDA_INCLUDE_DIRS})
target_compile_definitions(gpu PRIVATE -D_${GPU_PREC_SETTING} -DMPI_GERYON -DUCL_NO_EXIT ${GPU_CUDA_MPS_FLAGS})
target_compile_definitions(gpu PRIVATE -DUSE_CUDA -D_${GPU_PREC_SETTING} -DMPI_GERYON -DUCL_NO_EXIT ${GPU_CUDA_MPS_FLAGS})
if(CUDPP_OPT)
target_include_directories(gpu PRIVATE ${LAMMPS_LIB_SOURCE_DIR}/gpu/cudpp_mini)
target_compile_definitions(gpu PRIVATE -DUSE_CUDPP)
@ -135,27 +145,20 @@ if(GPU_API STREQUAL "CUDA")
target_include_directories(nvc_get_devices PRIVATE ${CUDA_INCLUDE_DIRS})
elseif(GPU_API STREQUAL "OPENCL")
if(${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
# download and unpack support binaries for compilation of windows binaries.
set(LAMMPS_THIRDPARTY_URL "https://download.lammps.org/thirdparty")
file(DOWNLOAD "${LAMMPS_THIRDPARTY_URL}/opencl-win-devel.tar.gz" "${CMAKE_CURRENT_BINARY_DIR}/opencl-win-devel.tar.gz"
EXPECTED_MD5 2c00364888d5671195598b44c2e0d44d)
execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf opencl-win-devel.tar.gz WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
add_library(OpenCL::OpenCL UNKNOWN IMPORTED)
if(${CMAKE_SYSTEM_PROCESSOR} STREQUAL "x86")
set_target_properties(OpenCL::OpenCL PROPERTIES IMPORTED_LOCATION "${CMAKE_CURRENT_BINARY_DIR}/OpenCL/lib_win32/libOpenCL.dll")
elseif(${CMAKE_SYSTEM_PROCESSOR} STREQUAL "x86_64")
set_target_properties(OpenCL::OpenCL PROPERTIES IMPORTED_LOCATION "${CMAKE_CURRENT_BINARY_DIR}/OpenCL/lib_win64/libOpenCL.dll")
# the static OpenCL loader doesn't seem to work on macOS. use the system provided
# version by default instead (for as long as it will be available)
if("${CMAKE_SYSTEM_NAME}" STREQUAL "Darwin")
set(_opencl_static_default OFF)
else()
set(_opencl_static_default ON)
endif()
set_target_properties(OpenCL::OpenCL PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_BINARY_DIR}/OpenCL/include")
option(USE_STATIC_OPENCL_LOADER "Download and include a static OpenCL ICD loader" ${_opencl_static_default})
mark_as_advanced(USE_STATIC_OPENCL_LOADER)
if (USE_STATIC_OPENCL_LOADER)
include(OpenCLLoader)
else()
find_package(OpenCL REQUIRED)
endif()
set(OCL_TUNE "generic" CACHE STRING "OpenCL Device Tuning")
set(OCL_TUNE_VALUES intel fermi kepler cypress generic)
set_property(CACHE OCL_TUNE PROPERTY STRINGS ${OCL_TUNE_VALUES})
validate_option(OCL_TUNE OCL_TUNE_VALUES)
string(TOUPPER ${OCL_TUNE} OCL_TUNE)
include(OpenCLUtils)
set(OCL_COMMON_HEADERS ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_preprocessor.h ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_aux_fun1.h)
@ -199,7 +202,7 @@ elseif(GPU_API STREQUAL "OPENCL")
add_library(gpu STATIC ${GPU_LIB_SOURCES})
target_link_libraries(gpu PRIVATE OpenCL::OpenCL)
target_include_directories(gpu PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/gpu)
target_compile_definitions(gpu PRIVATE -D_${GPU_PREC_SETTING} -D${OCL_TUNE}_OCL -DMPI_GERYON -DUCL_NO_EXIT)
target_compile_definitions(gpu PRIVATE -D_${GPU_PREC_SETTING} -DMPI_GERYON -DGERYON_NUMA_FISSION -DUCL_NO_EXIT)
target_compile_definitions(gpu PRIVATE -DUSE_OPENCL)
target_link_libraries(lammps PRIVATE gpu)
@ -207,6 +210,7 @@ elseif(GPU_API STREQUAL "OPENCL")
add_executable(ocl_get_devices ${LAMMPS_LIB_SOURCE_DIR}/gpu/geryon/ucl_get_devices.cpp)
target_compile_definitions(ocl_get_devices PRIVATE -DUCL_OPENCL)
target_link_libraries(ocl_get_devices PRIVATE OpenCL::OpenCL)
add_dependencies(ocl_get_devices OpenCL::OpenCL)
elseif(GPU_API STREQUAL "HIP")
if(NOT DEFINED HIP_PATH)
if(NOT DEFINED ENV{HIP_PATH})
@ -221,7 +225,7 @@ elseif(GPU_API STREQUAL "HIP")
if(NOT DEFINED HIP_PLATFORM)
if(NOT DEFINED ENV{HIP_PLATFORM})
set(HIP_PLATFORM "hcc" CACHE PATH "HIP Platform to be used during compilation")
set(HIP_PLATFORM "amd" CACHE PATH "HIP Platform to be used during compilation")
else()
set(HIP_PLATFORM $ENV{HIP_PLATFORM} CACHE PATH "HIP Platform used during compilation")
endif()
@ -229,7 +233,7 @@ elseif(GPU_API STREQUAL "HIP")
set(ENV{HIP_PLATFORM} ${HIP_PLATFORM})
if(HIP_PLATFORM STREQUAL "hcc")
if(HIP_PLATFORM STREQUAL "hcc" OR HIP_PLATFORM STREQUAL "amd")
set(HIP_ARCH "gfx906" CACHE STRING "HIP target architecture")
elseif(HIP_PLATFORM STREQUAL "nvcc")
find_package(CUDA REQUIRED)
@ -287,23 +291,23 @@ elseif(GPU_API STREQUAL "HIP")
set(CUBIN_FILE "${LAMMPS_LIB_BINARY_DIR}/gpu/${CU_NAME}.cubin")
set(CUBIN_H_FILE "${LAMMPS_LIB_BINARY_DIR}/gpu/${CU_NAME}_cubin.h")
if(HIP_PLATFORM STREQUAL "hcc")
if(HIP_PLATFORM STREQUAL "hcc" OR HIP_PLATFORM STREQUAL "amd")
configure_file(${CU_FILE} ${CU_CPP_FILE} COPYONLY)
if(HIP_COMPILER STREQUAL "clang")
add_custom_command(OUTPUT ${CUBIN_FILE}
VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco --offload-arch=${HIP_ARCH} -O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_CPP_FILE}
VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco --offload-arch=${HIP_ARCH} -O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_CPP_FILE}
DEPENDS ${CU_CPP_FILE}
COMMENT "Generating ${CU_NAME}.cubin")
else()
add_custom_command(OUTPUT ${CUBIN_FILE}
VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco -t="${HIP_ARCH}" -f=\"-O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -I${LAMMPS_LIB_SOURCE_DIR}/gpu\" -o ${CUBIN_FILE} ${CU_CPP_FILE}
VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco -t="${HIP_ARCH}" -f=\"-O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu\" -o ${CUBIN_FILE} ${CU_CPP_FILE}
DEPENDS ${CU_CPP_FILE}
COMMENT "Generating ${CU_NAME}.cubin")
endif()
elseif(HIP_PLATFORM STREQUAL "nvcc")
add_custom_command(OUTPUT ${CUBIN_FILE}
VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --fatbin --use_fast_math -DUSE_HIP -D_${GPU_PREC_SETTING} ${HIP_CUDA_GENCODE} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_FILE}
VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --fatbin --use_fast_math -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} ${HIP_CUDA_GENCODE} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_FILE}
DEPENDS ${CU_FILE}
COMMENT "Generating ${CU_NAME}.cubin")
endif()
@ -341,11 +345,16 @@ elseif(GPU_API STREQUAL "HIP")
if(DOWNLOAD_CUB)
message(STATUS "CUB download requested")
set(CUB_URL "https://github.com/NVlabs/cub/archive/1.12.0.tar.gz" CACHE STRING "URL for CUB tarball")
set(CUB_MD5 "1cf595beacafff104700921bac8519f3" CACHE STRING "MD5 checksum of CUB tarball")
mark_as_advanced(CUB_URL)
mark_as_advanced(CUB_MD5)
include(ExternalProject)
ExternalProject_Add(CUB
GIT_REPOSITORY https://github.com/NVlabs/cub
TIMEOUT 5
URL ${CUB_URL}
URL_MD5 ${CUB_MD5}
PREFIX "${CMAKE_CURRENT_BINARY_DIR}"
CONFIGURE_COMMAND ""
BUILD_COMMAND ""
@ -357,7 +366,7 @@ elseif(GPU_API STREQUAL "HIP")
else()
find_package(CUB)
if(NOT CUB_FOUND)
message(FATAL_ERROR "CUB library not found. Help CMake to find it by setting CUB_INCLUDE_DIR, or set DOWNLOAD_VORO=ON to download it")
message(FATAL_ERROR "CUB library not found. Help CMake to find it by setting CUB_INCLUDE_DIR, or set DOWNLOAD_CUB=ON to download it")
endif()
endif()
@ -384,18 +393,21 @@ elseif(GPU_API STREQUAL "HIP")
target_compile_definitions(hip_get_devices PRIVATE -D__HIP_PLATFORM_HCC__)
target_include_directories(hip_get_devices PRIVATE ${HIP_ROOT_DIR}/../include)
elseif(HIP_PLATFORM STREQUAL "amd")
target_compile_definitions(gpu PRIVATE -D__HIP_PLATFORM_AMD__)
target_include_directories(gpu PRIVATE ${HIP_ROOT_DIR}/../include)
target_compile_definitions(hip_get_devices PRIVATE -D__HIP_PLATFORM_AMD__)
target_include_directories(hip_get_devices PRIVATE ${HIP_ROOT_DIR}/../include)
endif()
target_link_libraries(lammps PRIVATE gpu)
endif()
# GPU package
FindStyleHeaders(${GPU_SOURCES_DIR} FIX_CLASS fix_ FIX)
set_property(GLOBAL PROPERTY "GPU_SOURCES" "${GPU_SOURCES}")
# detects styles which have GPU version
# detect styles which have a GPU version
RegisterStylesExt(${GPU_SOURCES_DIR} gpu GPU_SOURCES)
RegisterFixStyle(${GPU_SOURCES_DIR}/fix_gpu.h)
get_property(GPU_SOURCES GLOBAL PROPERTY GPU_SOURCES)

16
cmake/Modules/Packages/KIM.cmake
View File

@ -19,6 +19,8 @@ if(CURL_FOUND)
target_compile_definitions(lammps PRIVATE -DLMP_NO_SSL_CHECK)
endif()
endif()
set(KIM_EXTRA_UNITTESTS OFF CACHE STRING "Set extra unit tests verbose mode on/off. If on, extra tests are included.")
mark_as_advanced(KIM_EXTRA_UNITTESTS)
find_package(PkgConfig QUIET)
set(DOWNLOAD_KIM_DEFAULT ON)
if(PKG_CONFIG_FOUND)
@ -33,9 +35,13 @@ if(DOWNLOAD_KIM)
include(ExternalProject)
enable_language(C)
enable_language(Fortran)
set(KIM_URL "https://s3.openkim.org/kim-api/kim-api-2.2.1.txz" CACHE STRING "URL for KIM tarball")
set(KIM_MD5 "ae1ddda2ef7017ea07934e519d023dca" CACHE STRING "MD5 checksum of KIM tarball")
mark_as_advanced(KIM_URL)
mark_as_advanced(KIM_MD5)
ExternalProject_Add(kim_build
URL https://s3.openkim.org/kim-api/kim-api-2.2.0.txz
URL_MD5 e7f944e1593cffd7444679a660607f6c
URL ${KIM_URL}
URL_MD5 ${KIM_MD5}
BINARY_DIR build
CMAKE_ARGS ${CMAKE_REQUEST_PIC}
-DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}
@ -67,14 +73,14 @@ if(DOWNLOAD_KIM)
BUILD_RPATH "${_rpath_prefix}/kim_build-prefix/lib"
)
else()
if(KIM-API_FOUND AND KIM_API_VERSION VERSION_GREATER_EQUAL 2.2.0)
if(KIM-API_FOUND AND KIM-API_VERSION VERSION_GREATER_EQUAL 2.2.0)
# For kim-api >= 2.2.0
find_package(KIM-API ${KIM-API_MIN_VERSION} CONFIG REQUIRED)
find_package(KIM-API 2.2.0 CONFIG REQUIRED)
target_link_libraries(lammps PRIVATE KIM-API::kim-api)
else()
# For kim-api 2.1.3 (consistent with previous version of this file)
find_package(PkgConfig REQUIRED)
pkg_check_modules(KIM-API REQUIRED IMPORTED_TARGET libkim-api>=KIM-API_MIN_VERSION)
pkg_check_modules(KIM-API REQUIRED IMPORTED_TARGET libkim-api>=${KIM-API_MIN_VERSION})
target_link_libraries(lammps PRIVATE PkgConfig::KIM-API)
endif()
endif()

16
cmake/Modules/Packages/KOKKOS.cmake
View File

@ -1,4 +1,7 @@
########################################################################
# As of version 3.3.0 Kokkos requires C++14
set(CMAKE_CXX_STANDARD 14)
########################################################################
# consistency checks and Kokkos options/settings required by LAMMPS
if(Kokkos_ENABLE_CUDA)
message(STATUS "KOKKOS: Enabling CUDA LAMBDA function support")
@ -34,9 +37,13 @@ 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/3.3.01.tar.gz" CACHE STRING "URL for KOKKOS tarball")
set(KOKKOS_MD5 "08201d1c7cf5bc458ce0f5b44a629d5a" CACHE STRING "MD5 checksum of KOKKOS tarball")
mark_as_advanced(KOKKOS_URL)
mark_as_advanced(KOKKOS_MD5)
ExternalProject_Add(kokkos_build
URL https://github.com/kokkos/kokkos/archive/3.2.01.tar.gz
URL_MD5 ba72440e285ccde05b403694ea0c92e5
URL ${KOKKOS_URL}
URL_MD5 ${KOKKOS_MD5}
CMAKE_ARGS ${KOKKOS_LIB_BUILD_ARGS}
BUILD_BYPRODUCTS <INSTALL_DIR>/lib/libkokkoscore.a
)
@ -48,10 +55,12 @@ if(DOWNLOAD_KOKKOS)
INTERFACE_INCLUDE_DIRECTORIES "${INSTALL_DIR}/include"
INTERFACE_LINK_LIBRARIES ${CMAKE_DL_LIBS})
target_link_libraries(lammps PRIVATE LAMMPS::KOKKOS)
target_link_libraries(lmp PRIVATE LAMMPS::KOKKOS)
add_dependencies(LAMMPS::KOKKOS kokkos_build)
elseif(EXTERNAL_KOKKOS)
find_package(Kokkos 3.2.01 REQUIRED CONFIG)
find_package(Kokkos 3.3.01 REQUIRED CONFIG)
target_link_libraries(lammps PRIVATE Kokkos::kokkos)
target_link_libraries(lmp PRIVATE Kokkos::kokkos)
else()
set(LAMMPS_LIB_KOKKOS_SRC_DIR ${LAMMPS_LIB_SOURCE_DIR}/kokkos)
set(LAMMPS_LIB_KOKKOS_BIN_DIR ${LAMMPS_LIB_BINARY_DIR}/kokkos)
@ -63,6 +72,7 @@ else()
${LAMMPS_LIB_KOKKOS_BIN_DIR})
target_include_directories(lammps PRIVATE ${Kokkos_INCLUDE_DIRS})
target_link_libraries(lammps PRIVATE kokkos)
target_link_libraries(lmp PRIVATE kokkos)
endif()
target_compile_definitions(lammps PRIVATE -DLMP_KOKKOS)

8
cmake/Modules/Packages/LATTE.cmake
View File

@ -15,10 +15,14 @@ endif()
option(DOWNLOAD_LATTE "Download the LATTE library instead of using an already installed one" ${DOWNLOAD_LATTE_DEFAULT})
if(DOWNLOAD_LATTE)
message(STATUS "LATTE download requested - we will build our own")
set(LATTE_URL "https://github.com/lanl/LATTE/archive/v1.2.2.tar.gz" CACHE STRING "URL for LATTE tarball")
set(LATTE_MD5 "820e73a457ced178c08c71389a385de7" CACHE STRING "MD5 checksum of LATTE tarball")
mark_as_advanced(LATTE_URL)
mark_as_advanced(LATTE_MD5)
include(ExternalProject)
ExternalProject_Add(latte_build
URL https://github.com/lanl/LATTE/archive/v1.2.2.tar.gz
URL_MD5 820e73a457ced178c08c71389a385de7
URL ${LATTE_URL}
URL_MD5 ${LATTE_MD5}
SOURCE_SUBDIR cmake
CMAKE_ARGS -DCMAKE_INSTALL_PREFIX=<INSTALL_DIR> ${CMAKE_REQUEST_PIC} -DCMAKE_INSTALL_LIBDIR=lib
-DBLAS_LIBRARIES=${BLAS_LIBRARIES} -DLAPACK_LIBRARIES=${LAPACK_LIBRARIES}

3
cmake/Modules/Packages/MESSAGE.cmake
View File

@ -2,8 +2,7 @@ if(LAMMPS_SIZES STREQUAL BIGBIG)
message(FATAL_ERROR "The MESSAGE Package is not compatible with -DLAMMPS_BIGBIG")
endif()
option(MESSAGE_ZMQ "Use ZeroMQ in MESSAGE package" OFF)
file(GLOB_RECURSE cslib_SOURCES ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/[^.]*.F
${LAMMPS_LIB_SOURCE_DIR}/message/cslib/[^.]*.c
file(GLOB_RECURSE cslib_SOURCES
${LAMMPS_LIB_SOURCE_DIR}/message/cslib/[^.]*.cpp)
add_library(cslib STATIC ${cslib_SOURCES})

40
cmake/Modules/Packages/MLIAP.cmake Normal file
View File

@ -0,0 +1,40 @@
# if PYTHON package is included we may also include Python support in MLIAP
set(MLIAP_ENABLE_PYTHON_DEFAULT OFF)
if(PKG_PYTHON)
find_package(Cythonize QUIET)
if(Cythonize_FOUND)
set(MLIAP_ENABLE_PYTHON_DEFAULT ON)
endif()
endif()
option(MLIAP_ENABLE_PYTHON "Build MLIAP package with Python support" ${MLIAP_ENABLE_PYTHON_DEFAULT})
if(MLIAP_ENABLE_PYTHON)
find_package(Cythonize REQUIRED)
if(NOT PKG_PYTHON)
message(FATAL_ERROR "Must enable PYTHON package for including Python support in MLIAP")
endif()
if(CMAKE_VERSION VERSION_LESS 3.12)
if(PYTHONLIBS_VERSION_STRING VERSION_LESS 3.6)
message(FATAL_ERROR "Python support in MLIAP requires Python 3.6 or later")
endif()
else()
if(Python_VERSION VERSION_LESS 3.6)
message(FATAL_ERROR "Python support in MLIAP requires Python 3.6 or later")
endif()
endif()
set(MLIAP_BINARY_DIR ${CMAKE_BINARY_DIR}/cython)
set(MLIAP_CYTHON_SRC ${LAMMPS_SOURCE_DIR}/MLIAP/mliap_model_python_couple.pyx)
get_filename_component(MLIAP_CYTHON_BASE ${MLIAP_CYTHON_SRC} NAME_WE)
file(MAKE_DIRECTORY ${MLIAP_BINARY_DIR})
add_custom_command(OUTPUT ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.cpp ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.h
COMMAND ${CMAKE_COMMAND} -E copy_if_different ${MLIAP_CYTHON_SRC} ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.pyx
COMMAND ${Cythonize_EXECUTABLE} -3 ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.pyx
WORKING_DIRECTORY ${MLIAP_BINARY_DIR}
MAIN_DEPENDENCY ${MLIAP_CYTHON_SRC}
COMMENT "Generating C++ sources with cythonize...")
target_compile_definitions(lammps PRIVATE -DMLIAP_PYTHON)
target_sources(lammps PRIVATE ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.cpp)
target_include_directories(lammps PRIVATE ${MLIAP_BINARY_DIR})
endif()

9
cmake/Modules/Packages/MSCG.cmake
View File

@ -7,10 +7,15 @@ else()
endif()
option(DOWNLOAD_MSCG "Download MSCG library instead of using an already installed one)" ${DOWNLOAD_MSCG_DEFAULT})
if(DOWNLOAD_MSCG)
set(MSCG_URL "https://github.com/uchicago-voth/MSCG-release/archive/1.7.3.1.tar.gz" CACHE STRING "URL for MSCG tarball")
set(MSCG_MD5 "8c45e269ee13f60b303edd7823866a91" CACHE STRING "MD5 checksum of MSCG tarball")
mark_as_advanced(MSCG_URL)
mark_as_advanced(MSCG_MD5)
include(ExternalProject)
ExternalProject_Add(mscg_build
URL https://github.com/uchicago-voth/MSCG-release/archive/1.7.3.1.tar.gz
URL_MD5 8c45e269ee13f60b303edd7823866a91
URL ${MSCG_URL}
URL_MD5 ${MSCG_MD5}
SOURCE_SUBDIR src/CMake
CMAKE_ARGS ${CMAKE_REQUEST_PIC} ${EXTRA_MSCG_OPTS}
-DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}

13
cmake/Modules/Packages/USER-INTEL.cmake
View File

@ -30,7 +30,12 @@ if(INTEL_LRT_MODE STREQUAL "THREADS")
endif()
endif()
if(INTEL_LRT_MODE STREQUAL "C++11")
if(Threads_FOUND)
target_compile_definitions(lammps PRIVATE -DLMP_INTEL_USELRT -DLMP_INTEL_LRT11)
target_link_libraries(lammps PRIVATE Threads::Threads)
else()
message(FATAL_ERROR "Must have working threads library for Long-range thread support")
endif()
endif()
if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
@ -74,9 +79,11 @@ if(INTEL_ARCH STREQUAL "KNL")
else()
if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
include(CheckCXXCompilerFlag)
foreach(_FLAG -O2 -fp-model fast=2 -no-prec-div -qoverride-limits -qopt-zmm-usage=high -qno-offload -fno-alias -ansi-alias -restrict)
check_cxx_compiler_flag("${_FLAG}" COMPILER_SUPPORTS${_FLAG})
if(COMPILER_SUPPORTS${_FLAG})
foreach(_FLAG -O2 "-fp-model fast=2" -no-prec-div -qoverride-limits -qopt-zmm-usage=high -qno-offload -fno-alias -ansi-alias -restrict)
string(REGEX REPLACE "[ =\"]" "" _FLAGX ${_FLAG})
check_cxx_compiler_flag("${_FLAG}" COMPILER_SUPPORTS${_FLAGX})
if(COMPILER_SUPPORTS${_FLAGX})
separate_arguments(_FLAG UNIX_COMMAND "${_FLAG}")
target_compile_options(lammps PRIVATE ${_FLAG})
endif()
endforeach()

4
cmake/Modules/Packages/USER-MOLFILE.cmake
View File

@ -2,8 +2,4 @@ set(MOLFILE_INCLUDE_DIR "${LAMMPS_LIB_SOURCE_DIR}/molfile" CACHE STRING "Path to
set(MOLFILE_INCLUDE_DIRS "${MOLFILE_INCLUDE_DIR}")
add_library(molfile INTERFACE)
target_include_directories(molfile INTERFACE ${MOLFILE_INCLUDE_DIRS})
# no need to link with -ldl on windows
if(NOT ${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
target_link_libraries(molfile INTERFACE ${CMAKE_DL_LIBS})
endif()
target_link_libraries(lammps PRIVATE molfile)

26
cmake/Modules/Packages/USER-PACE.cmake Normal file
View File

@ -0,0 +1,26 @@
set(PACELIB_URL "https://github.com/ICAMS/lammps-user-pace/archive/refs/tags/v.2021.4.9.tar.gz" CACHE STRING "URL for PACE evaluator library sources")
set(PACELIB_MD5 "4db54962fbd6adcf8c18d46e1798ceb5" CACHE STRING "MD5 checksum of PACE evaluator library tarball")
mark_as_advanced(PACELIB_URL)
mark_as_advanced(PACELIB_MD5)
# download library sources to build folder
file(DOWNLOAD ${PACELIB_URL} ${CMAKE_BINARY_DIR}/libpace.tar.gz SHOW_PROGRESS EXPECTED_HASH MD5=${PACELIB_MD5})
# uncompress downloaded sources
execute_process(
COMMAND ${CMAKE_COMMAND} -E remove_directory lammps-user-pace*
COMMAND ${CMAKE_COMMAND} -E tar xzf libpace.tar.gz
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
)
file(GLOB PACE_EVALUATOR_INCLUDE_DIR ${CMAKE_BINARY_DIR}/lammps-user-pace-*/USER-PACE)
file(GLOB PACE_EVALUATOR_SOURCES ${CMAKE_BINARY_DIR}/lammps-user-pace-*/USER-PACE/*.cpp)
list(FILTER PACE_EVALUATOR_SOURCES EXCLUDE REGEX pair_pace.cpp)
add_library(pace STATIC ${PACE_EVALUATOR_SOURCES})
set_target_properties(pace PROPERTIES OUTPUT_NAME lammps_pace${LAMMPS_MACHINE})
target_include_directories(pace PUBLIC ${PACE_EVALUATOR_INCLUDE_DIR})
target_link_libraries(lammps PRIVATE pace)

11
cmake/Modules/Packages/USER-PLUMED.cmake
View File

@ -53,10 +53,17 @@ if(DOWNLOAD_PLUMED)
elseif(PLUMED_MODE STREQUAL "RUNTIME")
set(PLUMED_BUILD_BYPRODUCTS "<INSTALL_DIR>/lib/libplumedWrapper.a")
endif()
set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.7.1/plumed-src-2.7.1.tgz" CACHE STRING "URL for PLUMED tarball")
set(PLUMED_MD5 "4eac6a462ec84dfe0cec96c82421b8e8" CACHE STRING "MD5 checksum of PLUMED tarball")
mark_as_advanced(PLUMED_URL)
mark_as_advanced(PLUMED_MD5)
include(ExternalProject)
ExternalProject_Add(plumed_build
URL https://github.com/plumed/plumed2/releases/download/v2.6.1/plumed-src-2.6.1.tgz
URL_MD5 89a9a450fc6025299fe16af235957163
URL ${PLUMED_URL}
URL_MD5 ${PLUMED_MD5}
BUILD_IN_SOURCE 1
CONFIGURE_COMMAND <SOURCE_DIR>/configure --prefix=<INSTALL_DIR>
${CONFIGURE_REQUEST_PIC}

10
cmake/Modules/Packages/USER-SCAFACOS.cmake
View File

@ -14,15 +14,19 @@ endif()
option(DOWNLOAD_SCAFACOS "Download ScaFaCoS library instead of using an already installed one" ${DOWNLOAD_SCAFACOS_DEFAULT})
if(DOWNLOAD_SCAFACOS)
message(STATUS "ScaFaCoS download requested - we will build our own")
set(SCAFACOS_URL "https://github.com/scafacos/scafacos/releases/download/v1.0.1/scafacos-1.0.1.tar.gz" CACHE STRING "URL for SCAFACOS tarball")
set(SCAFACOS_MD5 "bd46d74e3296bd8a444d731bb10c1738" CACHE STRING "MD5 checksum of SCAFACOS tarball")
mark_as_advanced(SCAFACOS_URL)
mark_as_advanced(SCAFACOS_MD5)
# version 1.0.1 needs a patch to compile and linke cleanly with GCC 10 and later.
file(DOWNLOAD https://download.lammps.org/thirdparty/scafacos-1.0.1-fix.diff ${CMAKE_CURRENT_BINARY_DIR}/scafacos-1.0.1.fix.diff
file(DOWNLOAD ${LAMMPS_THIRDPARTY_URL}/scafacos-1.0.1-fix.diff ${CMAKE_CURRENT_BINARY_DIR}/scafacos-1.0.1.fix.diff
EXPECTED_HASH MD5=4baa1333bb28fcce102d505e1992d032)
include(ExternalProject)
ExternalProject_Add(scafacos_build
URL https://github.com/scafacos/scafacos/releases/download/v1.0.1/scafacos-1.0.1.tar.gz
URL_MD5 bd46d74e3296bd8a444d731bb10c1738
URL ${SCAFACOS_URL}
URL_MD5 ${SCAFACOS_MD5}
PATCH_COMMAND patch -p1 < ${CMAKE_CURRENT_BINARY_DIR}/scafacos-1.0.1.fix.diff
CONFIGURE_COMMAND <SOURCE_DIR>/configure --prefix=<INSTALL_DIR> --disable-doc
--enable-fcs-solvers=fmm,p2nfft,direct,ewald,p3m

8
cmake/Modules/Packages/USER-SMD.cmake
View File

@ -7,10 +7,14 @@ endif()
option(DOWNLOAD_EIGEN3 "Download Eigen3 instead of using an already installed one)" ${DOWNLOAD_EIGEN3_DEFAULT})
if(DOWNLOAD_EIGEN3)
message(STATUS "Eigen3 download requested - we will build our own")
set(EIGEN3_URL "https://gitlab.com/libeigen/eigen/-/archive/3.3.7/eigen-3.3.7.tar.gz" CACHE STRING "URL for Eigen3 tarball")
set(EIGEN3_MD5 "9e30f67e8531477de4117506fe44669b" CACHE STRING "MD5 checksum of Eigen3 tarball")
mark_as_advanced(EIGEN3_URL)
mark_as_advanced(EIGEN3_MD5)
include(ExternalProject)
ExternalProject_Add(Eigen3_build
URL https://gitlab.com/libeigen/eigen/-/archive/3.3.7/eigen-3.3.7.tar.gz
URL_MD5 9e30f67e8531477de4117506fe44669b
URL ${EIGEN3_URL}
URL_MD5 ${EIGEN3_MD5}
CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
)
ExternalProject_get_property(Eigen3_build SOURCE_DIR)

9
cmake/Modules/Packages/VORONOI.cmake
View File

@ -7,6 +7,11 @@ endif()
option(DOWNLOAD_VORO "Download and compile the Voro++ library instead of using an already installed one" ${DOWNLOAD_VORO_DEFAULT})
if(DOWNLOAD_VORO)
message(STATUS "Voro++ download requested - we will build our own")
set(VORO_URL "${LAMMPS_THIRDPARTY_URL}/voro++-0.4.6.tar.gz" CACHE STRING "URL for Voro++ tarball")
set(VORO_MD5 "2338b824c3b7b25590e18e8df5d68af9" CACHE STRING "MD5 checksum for Voro++ tarball")
mark_as_advanced(VORO_URL)
mark_as_advanced(VORO_MD5)
include(ExternalProject)
if(BUILD_SHARED_LIBS)
@ -22,8 +27,8 @@ if(DOWNLOAD_VORO)
endif()
ExternalProject_Add(voro_build
URL https://download.lammps.org/thirdparty/voro++-0.4.6.tar.gz
URL_MD5 2338b824c3b7b25590e18e8df5d68af9
URL ${VORO_URL}
URL_MD5 ${VORO_MD5}
PATCH_COMMAND patch -b -p0 < ${LAMMPS_LIB_SOURCE_DIR}/voronoi/voro-make.patch
CONFIGURE_COMMAND ""
BUILD_COMMAND make ${VORO_BUILD_OPTIONS}

86
cmake/Modules/Testing.cmake
View File

@ -16,11 +16,14 @@ if(ENABLE_TESTING)
set(MEMORYCHECK_COMMAND "${VALGRIND_BINARY}" CACHE FILEPATH "Memory Check Command")
set(MEMORYCHECK_COMMAND_OPTIONS "${VALGRIND_DEFAULT_OPTIONS}" CACHE STRING "Memory Check Command Options")
# check if a faster linker is available.
# only verified with GNU and Clang compilers and new CMake
if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.13)
if((${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
OR (${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang"))
# we need to build and link a LOT of tester executables, so it is worth checking if
# a faster linker is available. requires GNU or Clang compiler, newer CMake.
# also only verified with Fedora Linux > 30 and Ubuntu <= 18.04 (Ubuntu 20.04 fails)
if((CMAKE_SYSTEM_NAME STREQUAL Linux) AND (CMAKE_VERSION VERSION_GREATER_EQUAL 3.13)
AND ((${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
OR (${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang")))
if (((CMAKE_LINUX_DISTRO STREQUAL Ubuntu) AND (CMAKE_DISTRO_VERSION VERSION_LESS_EQUAL 18.04))
OR ((CMAKE_LINUX_DISTRO STREQUAL Fedora) AND (CMAKE_DISTRO_VERSION VERSION_GREATER 30)))
include(CheckCXXCompilerFlag)
set(CMAKE_CUSTOM_LINKER_DEFAULT default)
check_cxx_compiler_flag(-fuse-ld=lld HAVE_LLD_LINKER_FLAG)
@ -53,3 +56,76 @@ if(ENABLE_TESTING)
get_filename_component(LAMMPS_UNITTEST_BIN ${CMAKE_BINARY_DIR}/unittest ABSOLUTE)
add_subdirectory(${LAMMPS_UNITTEST_DIR} ${LAMMPS_UNITTEST_BIN})
endif()
# Compiler specific features for testing
if(${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
option(ENABLE_COVERAGE "Enable collecting code coverage data" OFF)
mark_as_advanced(ENABLE_COVERAGE)
if(ENABLE_COVERAGE)
if(CMAKE_VERSION VERSION_LESS 3.13)
if(CMAKE_CXX_FLAGS)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} --coverage")
else()
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_${CMAKE_BUILD_TYPE}_FLAGS} --coverage")
endif()
else()
target_compile_options(lammps PUBLIC --coverage)
target_link_options(lammps PUBLIC --coverage)
endif()
endif()
endif()
#######################################
# add custom target for IWYU analysis
#######################################
set(ENABLE_IWYU OFF CACHE BOOL "Add 'iwyu' build target to call the include-what-you-use tool")
mark_as_advanced(ENABLE_IWYU)
if(ENABLE_IWYU)
# enforce these settings
set(CMAKE_EXPORT_COMPILE_COMMANDS ON CACHE BOOL "Enable reporting compilation commands to compile_commands.json" FORCE)
if (NOT ((CMAKE_CXX_COMPILER_ID STREQUAL "Clang") OR (CMAKE_CXX_COMPILER_ID STREQUAL "GNU")))
message(FATAL_ERROR "IWYU is only supported with Clang or GNU compilers")
endif()
# detect the "native" header folder so we can include them first
execute_process(COMMAND ${CMAKE_CXX_COMPILER} --print-search-dirs OUTPUT_VARIABLE IWYU_SEARCH_PATHS)
string(REGEX REPLACE ".*libraries: *=([^:]+):.*" "\\1/include" IWYU_EXTRA_INCLUDE_DIR ${IWYU_SEARCH_PATHS})
find_program(IWYU_EXE NAMES include-what-you-use iwyu)
find_program(IWYU_TOOL NAMES iwyu_tool iwyu-tool iwyu_tool.py)
if (IWYU_EXE AND IWYU_TOOL)
add_custom_target(
iwyu
${IWYU_TOOL} -o clang -p ${CMAKE_CURRENT_BINARY_DIR} -- -I${IWYU_EXTRA_INCLUDE_DIR} -Xiwyu --mapping_file=${CMAKE_CURRENT_SOURCE_DIR}/iwyu/iwyu-extra-map.imp
COMMENT "Running IWYU")
add_dependencies(iwyu lammps)
else()
message(FATAL_ERROR "To use IWYU you need the include-what-you-use/iwyu executable"
"and the iwyu-tool/iwyu_tool script installed in your PATH")
endif()
endif()
#######################################
# select code sanitizer options
#######################################
set(ENABLE_SANITIZER "none" CACHE STRING "Select a code sanitizer option (none (default), address, leak, thread, undefined)")
mark_as_advanced(ENABLE_SANITIZER)
set(ENABLE_SANITIZER_VALUES none address leak thread undefined)
set_property(CACHE ENABLE_SANITIZER PROPERTY STRINGS ${ENABLE_SANITIZER_VALUES})
validate_option(ENABLE_SANITIZER ENABLE_SANITIZER_VALUES)
string(TOLOWER ${ENABLE_SANITIZER} ENABLE_SANITIZER)
if(NOT ENABLE_SANITIZER STREQUAL "none")
if((${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU") OR (${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang"))
if(CMAKE_VERSION VERSION_LESS 3.13)
if(CMAKE_CXX_FLAGS)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=${ENABLE_SANITIZER}")
else()
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_${CMAKE_BUILD_TYPE}_FLAGS} -fsanitize=${ENABLE_SANITIZER}")
endif()
else()
target_compile_options(lammps PUBLIC -fsanitize=${ENABLE_SANITIZER})
target_link_options(lammps PUBLIC -fsanitize=${ENABLE_SANITIZER})
endif()
else()
message(WARNING "ENABLE_SANITIZER option not supported by ${CMAKE_CXX_COMPILER_ID} compilers. Ignoring.")
set(ENABLE_SANITIZER "none")
endif()
endif()

9
cmake/Modules/YAML.cmake
View File

@ -2,17 +2,20 @@ message(STATUS "Downloading and building YAML library")
include(ExternalProject)
set(YAML_URL "https://pyyaml.org/download/libyaml/yaml-0.2.5.tar.gz" CACHE STRING "URL for libyaml tarball")
set(YAML_MD5 "bb15429d8fb787e7d3f1c83ae129a999" CACHE STRING "MD5 checksum of libyaml tarball")
mark_as_advanced(YAML_URL)
mark_as_advanced(YAML_MD5)
ExternalProject_Add(libyaml
URL ${YAML_URL}
URL_MD5 bb15429d8fb787e7d3f1c83ae129a999
URL_MD5 ${YAML_MD5}
SOURCE_DIR "${CMAKE_BINARY_DIR}/yaml-src"
BINARY_DIR "${CMAKE_BINARY_DIR}/yaml-build"
CONFIGURE_COMMAND <SOURCE_DIR>/configure ${CONFIGURE_REQUEST_PIC}
CXX=${CMAKE_CXX_COMPILER}
CC=${CMAKE_C_COMPILER}
--prefix=<INSTALL_DIR> --disable-shared
BUILD_BYPRODUCTS <INSTALL_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}yaml.a
BUILD_BYPRODUCTS <INSTALL_DIR>/lib/libyaml${CMAKE_STATIC_LIBRARY_SUFFIX}
TEST_COMMAND "")
ExternalProject_Get_Property(libyaml INSTALL_DIR)
@ -23,7 +26,7 @@ set(YAML_LIBRARY_DIR ${INSTALL_DIR}/lib)
file(MAKE_DIRECTORY ${YAML_INCLUDE_DIR})
file(MAKE_DIRECTORY ${YAML_LIBRARY_DIR})
set(YAML_LIBRARY_PATH ${INSTALL_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}yaml.a)
set(YAML_LIBRARY_PATH ${INSTALL_DIR}/lib/libyaml${CMAKE_STATIC_LIBRARY_SUFFIX})
add_library(Yaml::Yaml UNKNOWN IMPORTED)
set_target_properties(Yaml::Yaml PROPERTIES

2
cmake/Modules/generate_lmpgitversion.cmake
View File

@ -17,7 +17,7 @@ if(GIT_FOUND AND EXISTS ${LAMMPS_DIR}/.git)
ERROR_QUIET
WORKING_DIRECTORY ${LAMMPS_DIR}
OUTPUT_STRIP_TRAILING_WHITESPACE)
execute_process(COMMAND ${GIT_EXECUTABLE} describe --dirty=-modified
execute_process(COMMAND ${GIT_EXECUTABLE} describe --dirty=-modified --always
OUTPUT_VARIABLE temp_git_describe
ERROR_QUIET
WORKING_DIRECTORY ${LAMMPS_DIR}

20
cmake/presets/all_off.cmake
View File

@ -2,16 +2,16 @@
# an existing package selection without losing any other settings
set(ALL_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS CORESHELL DIPOLE GPU
GRANULAR KIM KOKKOS KSPACE LATTE MANYBODY MC MISC MESSAGE MLIAP
MOLECULE MPIIO MSCG OPT PERI POEMS PYTHON QEQ REPLICA RIGID SHOCK
SNAP SPIN SRD VORONOI
USER-ADIOS USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-CGSDK
USER-COLVARS USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP
USER-H5MD USER-INTEL USER-LB USER-MANIFOLD USER-MEAMC USER-MESODPD
USER-MESONT USER-MGPT USER-MISC USER-MOFFF USER-MOLFILE USER-NETCDF USER-OMP
USER-PHONON USER-PLUMED USER-PTM USER-QMMM USER-QTB USER-QUIP
USER-REACTION USER-REAXC USER-SCAFACOS USER-SDPD USER-SMD USER-SMTBQ
USER-SPH USER-TALLY USER-UEF USER-VTK USER-YAFF)
GRANULAR KIM KOKKOS KSPACE LATTE MANYBODY MC MESSAGE MISC MLIAP MOLECULE
MPIIO MSCG OPT PERI PLUGIN POEMS PYTHON QEQ REPLICA RIGID SHOCK SNAP SPIN
SRD VORONOI
USER-ADIOS USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-CGSDK USER-COLVARS
USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP USER-H5MD USER-INTEL
USER-LB USER-MANIFOLD USER-MEAMC USER-MESODPD USER-MESONT USER-MGPT
USER-MISC USER-MOFFF USER-MOLFILE USER-NETCDF USER-OMP USER-PACE USER-PHONON
USER-PLUMED USER-PTM USER-QMMM USER-QTB USER-QUIP USER-REACTION USER-REAXC
USER-SCAFACOS USER-SDPD USER-SMD USER-SMTBQ USER-SPH USER-TALLY USER-UEF
USER-VTK USER-YAFF)
foreach(PKG ${ALL_PACKAGES})
set(PKG_${PKG} OFF CACHE BOOL "" FORCE)

20
cmake/presets/all_on.cmake
View File

@ -4,16 +4,16 @@
# with just a working C++ compiler and an MPI library.
set(ALL_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS CORESHELL DIPOLE GPU
GRANULAR KIM KOKKOS KSPACE LATTE MANYBODY MC MISC MESSAGE MLIAP
MOLECULE MPIIO MSCG OPT PERI POEMS PYTHON QEQ REPLICA RIGID SHOCK
SNAP SPIN SRD VORONOI
USER-ADIOS USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-CGSDK
USER-COLVARS USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP
USER-H5MD USER-INTEL USER-LB USER-MANIFOLD USER-MEAMC USER-MESODPD
USER-MESONT USER-MGPT USER-MISC USER-MOFFF USER-MOLFILE USER-NETCDF USER-OMP
USER-PHONON USER-PLUMED USER-PTM USER-QMMM USER-QTB USER-QUIP
USER-REACTION USER-REAXC USER-SCAFACOS USER-SDPD USER-SMD USER-SMTBQ
USER-SPH USER-TALLY USER-UEF USER-VTK USER-YAFF)
GRANULAR KIM KOKKOS KSPACE LATTE MANYBODY MC MESSAGE MISC MLIAP MOLECULE
MPIIO MSCG OPT PERI PLUGIN POEMS PYTHON QEQ REPLICA RIGID SHOCK SNAP SPIN
SRD VORONOI
USER-ADIOS USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-CGSDK USER-COLVARS
USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP USER-H5MD USER-INTEL
USER-LB USER-MANIFOLD USER-MEAMC USER-MESODPD USER-MESONT USER-MGPT
USER-MISC USER-MOFFF USER-MOLFILE USER-NETCDF USER-OMP USER-PACE USER-PHONON
USER-PLUMED USER-PTM USER-QMMM USER-QTB USER-QUIP USER-REACTION USER-REAXC
USER-SCAFACOS USER-SDPD USER-SMD USER-SMTBQ USER-SPH USER-TALLY USER-UEF
USER-VTK USER-YAFF)
foreach(PKG ${ALL_PACKAGES})
set(PKG_${PKG} ON CACHE BOOL "" FORCE)

2
cmake/presets/most.cmake
View File

@ -4,7 +4,7 @@
set(ALL_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS CORESHELL DIPOLE
GRANULAR KSPACE MANYBODY MC MISC MLIAP MOLECULE OPT PERI
POEMS PYTHON QEQ REPLICA RIGID SHOCK SNAP SPIN SRD VORONOI
PLUGIN POEMS PYTHON QEQ REPLICA RIGID SHOCK SNAP SPIN SRD VORONOI
USER-BOCS USER-CGDNA USER-CGSDK USER-COLVARS USER-DIFFRACTION
USER-DPD USER-DRUDE USER-EFF USER-FEP USER-MEAMC USER-MESODPD
USER-MISC USER-MOFFF USER-OMP USER-PHONON USER-REACTION

9
cmake/presets/nolib.cmake
View File

@ -1,10 +1,11 @@
# preset that turns off all packages that require some form of external
# library or special compiler (fortran or cuda) or equivalent.
set(PACKAGES_WITH_LIB COMPRESS GPU KIM KOKKOS LATTE MPIIO MSCG PYTHON
VORONOI USER-ADIOS USER-ATC USER-AWPMD USER-H5MD USER-LB
USER-MOLFILE USER-MESONT USER-NETCDF USER-PLUMED USER-QMMM USER-QUIP
USER-SCAFACOS USER-SMD USER-VTK)
set(PACKAGES_WITH_LIB COMPRESS GPU KIM KOKKOS LATTE MESSAGE MPIIO MSCG
PYTHON VORONOI
USER-ADIOS USER-ATC USER-AWPMD USER-H5MD USER-LB USER-MOLFILE USER-MESONT
USER-NETCDF USER-PACE USER-PLUMED USER-QMMM USER-QUIP USER-SCAFACOS
USER-SMD USER-VTK)
foreach(PKG ${PACKAGES_WITH_LIB})
set(PKG_${PKG} OFF CACHE BOOL "" FORCE)

18
cmake/presets/oneapi.cmake Normal file
View File

@ -0,0 +1,18 @@
# preset that will enable the LLVM based Intel compilers with support for MPI and OpenMP (on Linux boxes)
set(CMAKE_CXX_COMPILER "icpx" CACHE STRING "" FORCE)
set(CMAKE_C_COMPILER "icx" CACHE STRING "" FORCE)
set(CMAKE_Fortran_COMPILER "ifx" CACHE STRING "" FORCE)
set(MPI_CXX "icpx" CACHE STRING "" FORCE)
set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
unset(HAVE_OMP_H_INCLUDE CACHE)
set(OpenMP_C "icx" CACHE STRING "" FORCE)
set(OpenMP_C_FLAGS "-qopenmp" CACHE STRING "" FORCE)
set(OpenMP_C_LIB_NAMES "omp" CACHE STRING "" FORCE)
set(OpenMP_CXX "icpx" CACHE STRING "" FORCE)
set(OpenMP_CXX_FLAGS "-qopenmp" CACHE STRING "" FORCE)
set(OpenMP_CXX_LIB_NAMES "omp" CACHE STRING "" FORCE)
set(OpenMP_Fortran_FLAGS "-qopenmp" CACHE STRING "" FORCE)
set(OpenMP_omp_LIBRARY "libiomp5.so" CACHE PATH "" FORCE)

16
cmake/presets/pgi.cmake Normal file
View File

@ -0,0 +1,16 @@
# preset that will enable clang/clang++ with support for MPI and OpenMP (on Linux boxes)
set(CMAKE_CXX_COMPILER "pgc++" CACHE STRING "" FORCE)
set(CMAKE_C_COMPILER "pgcc" CACHE STRING "" FORCE)
set(CMAKE_Fortran_COMPILER "pgfortran" CACHE STRING "" FORCE)
set(MPI_CXX "pgc++" CACHE STRING "" FORCE)
set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
unset(HAVE_OMP_H_INCLUDE CACHE)
set(OpenMP_C "pgcc" CACHE STRING "" FORCE)
set(OpenMP_C_FLAGS "-mp" CACHE STRING "" FORCE)
set(OpenMP_C_LIB_NAMES "omp" CACHE STRING "" FORCE)
set(OpenMP_CXX "pgc++" CACHE STRING "" FORCE)
set(OpenMP_CXX_FLAGS "-mp" CACHE STRING "" FORCE)
set(OpenMP_CXX_LIB_NAMES "omp" CACHE STRING "" FORCE)
set(OpenMP_omp_LIBRARY "libomp.so" CACHE PATH "" FORCE)

12
doc/Makefile
View File

@ -47,6 +47,8 @@ HAS_PDFLATEX = YES
endif
endif
# override settings for PIP commands
# PIP_OPTIONS = --cert /etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt --proxy http://proxy.mydomain.org
#SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') $(shell test -f $(BUILDDIR)/doxygen/xml/run.stamp && printf -- "-E")
@ -94,7 +96,7 @@ $(SPHINXCONFIG)/conf.py: $(SPHINXCONFIG)/conf.py.in
-e 's,@LAMMPS_PYTHON_DIR@,$(BUILDDIR)/../python,g' \
-e 's,@LAMMPS_DOC_DIR@,$(BUILDDIR),g' $< > $@
html: xmlgen $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
html: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
@$(MAKE) $(MFLAGS) -C graphviz all
@(\
@ -118,7 +120,7 @@ html: xmlgen $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
@rm -rf html/PDF/.[sg]*
@echo "Build finished. The HTML pages are in doc/html."
spelling: xmlgen $(VENV) $(SPHINXCONFIG)/false_positives.txt
spelling: xmlgen $(SPHINXCONFIG)/conf.py $(VENV) $(SPHINXCONFIG)/false_positives.txt
@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
@(\
. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
@ -228,13 +230,13 @@ $(VENV):
@( \
$(VIRTUALENV) -p $(PYTHON) $(VENV); \
. $(VENV)/bin/activate; \
pip install --upgrade pip; \
pip install --use-feature=2020-resolver -r $(BUILDDIR)/utils/requirements.txt; \
pip $(PIP_OPTIONS) install --upgrade pip; \
pip $(PIP_OPTIONS) install -r $(BUILDDIR)/utils/requirements.txt; \
deactivate;\
)
$(MATHJAX):
@git clone --depth 1 https://github.com/mathjax/MathJax.git $@
@git clone -b 3.1.4 -c advice.detachedHead=0 --depth 1 git://github.com/mathjax/MathJax.git $@
$(TXT2RST) $(ANCHORCHECK): $(VENV)
@( \

2
doc/doxygen/Doxyfile.in
View File

@ -424,6 +424,8 @@ INPUT = @LAMMPS_SOURCE_DIR@/utils.cpp \
@LAMMPS_SOURCE_DIR@/input.h \
@LAMMPS_SOURCE_DIR@/tokenizer.cpp \
@LAMMPS_SOURCE_DIR@/tokenizer.h \
@LAMMPS_SOURCE_DIR@/arg_info.cpp \
@LAMMPS_SOURCE_DIR@/arg_info.h \
@LAMMPS_SOURCE_DIR@/text_file_reader.cpp \
@LAMMPS_SOURCE_DIR@/text_file_reader.h \
@LAMMPS_SOURCE_DIR@/potential_file_reader.cpp \

10
doc/graphviz/lammps-classes.dot
View File

@ -18,8 +18,8 @@ digraph lammps {
Up [shape=box label="Update" color=blue]
Un [shape=box label="Universe" color=blue]
Ti [shape=box label="Timer" color=blue]
Lt [label="Lattice"]
Rg [label="Region" color=red]
Lt [label="Lattice"]
Rb [shape=box label="RegionBlock"]
Rs [shape=box label="RegionSphere"]
Av [label="AtomVec" color=red]
@ -34,6 +34,7 @@ digraph lammps {
Du [label="Dump" color=red]
Fi [label="Fix" color=red]
Cp [label="Compute" color=red]
Cm [label="Command" color=red]
Th [label="Thermo"]
Va [label="Variable"]
Ew [shape=box label="Ewald"]
@ -71,16 +72,19 @@ digraph lammps {
Dg [shape=box label="DumpCFG"]
Ve [shape=box label="Verlet"]
Rr [shape=box label="Respa"]
Ru [shape=box label="Run"]
Se [shape=box label="Set"]
Pt [shape=box label="PPPMTIP4P"]
Vs [shape=box label="VerletSplit"]
Ro [shape=box label="RespaOMP"]
Mc [shape=box label="MinCG"]
Mf [shape=box label="MinFire"]
La -> {At Ci Co Do Er Fo Gr In Me Mo Ne Ou Ti Up Un} [penwidth=2]
Do -> {Lt Rg} [penwidth=2]
Do -> {Rg Lt} [penwidth=2]
Rg -> {Rb Rs} [style=dashed penwidth=2]
Co -> {Cb Ct} [style=dashed penwidth=2]
In -> Va [penwidth=2]
In -> {Va Cm} [penwidth=2]
Cm -> {Ru Se} [style=dashed penwidth=2]
Mo -> {Fi Cp} [penwidth=2]
Fo -> {Pa Bo An Di Im Ks} [penwidth=2]
Ks -> {Ew Pp} [style=dashed penwidth=2]

2
doc/lammps.1
View File

@ -1,4 +1,4 @@
.TH LAMMPS "30 November 2020" "2020-10-29"
.TH LAMMPS "8 April 2021" "2021-04-08"
.SH NAME
.B LAMMPS
\- Molecular Dynamics Simulator.

27
doc/src/Build_basics.rst
View File

@ -1,7 +1,7 @@
Basic build options
===================
The following topics are covered on this page, for building both with
The following topics are covered on this page, for building with both
CMake and make:
* :ref:`Serial vs parallel build <serial>`
@ -95,7 +95,7 @@ standard. A more detailed discussion of that is below.
.. note::
The file ``src/STUBS/mpi.c`` provides a CPU timer function
The file ``src/STUBS/mpi.cpp`` provides a CPU timer function
called ``MPI_Wtime()`` that calls ``gettimeofday()``. If your
operating system does not support ``gettimeofday()``, you will
need to insert code to call another timer. Note that the
@ -234,14 +234,21 @@ LAMMPS.
cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran
# Building with Intel Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort
# Building with Intel oneAPI Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx -DCMAKE_Fortran_COMPILER=ifx
# Building with LLVM/Clang Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang
# Building with PGI/Nvidia Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=pgcc -DCMAKE_CXX_COMPILER=pgc++ -DCMAKE_Fortran_COMPILER=pgfortran
For compiling with the Clang/LLVM compilers a CMake preset is
provided that can be loaded with
`-C ../cmake/presets/clang.cmake`. Similarly,
`-C ../cmake/presets/intel.cmake` should switch the compiler
toolchain to the Intel compilers.
toolchain to the legacy Intel compilers, `-C ../cmake/presets/oneapi.cmake`
will switch to the LLVM based oneAPI Intel compilers,
and `-C ../cmake/presets/pgi.cmake`
will switch the compiler to the PGI compilers.
In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
compiler flags to tune for optimal performance on given hosts. By
@ -523,6 +530,20 @@ you want to copy files to is protected.
make # perform make after CMake command
make install # perform the installation into prefix
During the installation process CMake will by default remove any runtime
path settings for loading shared libraries. Because of this you may
have to set or modify the ``LD_LIBRARY_PATH`` (or ``DYLD_LIBRARY_PATH``)
environment variable, if you are installing LAMMPS into a non-system
location and/or are linking to libraries in a non-system location that
depend on such runtime path settings.
As an alternative you may set the CMake variable ``LAMMPS_INSTALL_RPATH``
to ``on`` and then the runtime paths for any linked shared libraries
and the library installation folder for the LAMMPS library will be
embedded and thus the requirement to set environment variables is avoided.
The ``off`` setting is usually preferred for packaged binaries or when
setting up environment modules, the ``on`` setting is more convenient
for installing software into a non-system or personal folder.
.. tab:: Traditional make
There is no "install" option in the ``src/Makefile`` for LAMMPS.

188
doc/src/Build_extras.rst
View File

@ -37,6 +37,7 @@ This is the list of packages that may require additional steps.
* :ref:`KOKKOS <kokkos>`
* :ref:`LATTE <latte>`
* :ref:`MESSAGE <message>`
* :ref:`MLIAP <mliap>`
* :ref:`MSCG <mscg>`
* :ref:`OPT <opt>`
* :ref:`POEMS <poems>`
@ -51,6 +52,7 @@ This is the list of packages that may require additional steps.
* :ref:`USER-MESONT <user-mesont>`
* :ref:`USER-MOLFILE <user-molfile>`
* :ref:`USER-NETCDF <user-netcdf>`
* :ref:`USER-PACE <user-pace>`
* :ref:`USER-PLUMED <user-plumed>`
* :ref:`USER-OMP <user-omp>`
* :ref:`USER-QMMM <user-qmmm>`
@ -119,21 +121,21 @@ CMake build
-D GPU_API=value # value = opencl (default) or cuda or hip
-D GPU_PREC=value # precision setting
# value = double or mixed (default) or single
-D OCL_TUNE=value # hardware choice for GPU_API=opencl
# generic (default) or intel (Intel CPU) or fermi, kepler, cypress (NVIDIA)
-D GPU_ARCH=value # primary GPU hardware choice for GPU_API=cuda
# value = sm_XX, see below
# default is sm_50
-D HIP_ARCH=value # primary GPU hardware choice for GPU_API=hip
# value depends on selected HIP_PLATFORM
# default is 'gfx906' for HIP_PLATFORM=hcc and 'sm_50' for HIP_PLATFORM=nvcc
# default is 'gfx906' for HIP_PLATFORM=amd and 'sm_50' for HIP_PLATFORM=nvcc
-D HIP_USE_DEVICE_SORT=value # enables GPU sorting
# value = yes (default) or no
-D CUDPP_OPT=value # optimization setting for GPU_API=cuda
# enables CUDA Performance Primitives Optimizations
# value = yes (default) or no
-D CUDPP_OPT=value # use GPU binning on with CUDA (should be off for modern GPUs)
# enables CUDA Performance Primitives, must be "no" for CUDA_MPS_SUPPORT=yes
# value = yes or no (default)
-D CUDA_MPS_SUPPORT=value # enables some tweaks required to run with active nvidia-cuda-mps daemon
# value = yes or no (default)
-D USE_STATIC_OPENCL_LOADER=value # downloads/includes OpenCL ICD loader library, no local OpenCL headers/libs needed
# value = yes (default) or no
:code:`GPU_ARCH` settings for different GPU hardware is as follows:
@ -160,19 +162,32 @@ When building with CMake, you **must NOT** build the GPU library in ``lib/gpu``
using the traditional build procedure. CMake will detect files generated by that
process and will terminate with an error and a suggestion for how to remove them.
If you are compiling for OpenCL, the default setting is to download, build, and
link with a static OpenCL ICD loader library and standard OpenCL headers. This
way no local OpenCL development headers or library needs to be present and only
OpenCL compatible drivers need to be installed to use OpenCL. If this is not
desired, you can set :code:`USE_STATIC_OPENCL_LOADER` to :code:`no`.
If you are compiling with HIP, note that before running CMake you will have to
set appropriate environment variables. Some variables such as
:code:`HCC_AMDGPU_TARGET` or :code:`CUDA_PATH` are necessary for :code:`hipcc`
:code:`HCC_AMDGPU_TARGET` (for ROCm <= 4.0) or :code:`CUDA_PATH` are necessary for :code:`hipcc`
and the linker to work correctly.
.. code:: bash
# AMDGPU target
# AMDGPU target (ROCm <= 4.0)
export HIP_PLATFORM=hcc
export HCC_AMDGPU_TARGET=gfx906
cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=gfx906 -D CMAKE_CXX_COMPILER=hipcc ..
make -j 4
.. code:: bash
# AMDGPU target (ROCm >= 4.1)
export HIP_PLATFORM=amd
cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=gfx906 -D CMAKE_CXX_COMPILER=hipcc ..
make -j 4
.. code:: bash
# CUDA target (not recommended, use GPU_ARCH=cuda)
@ -218,11 +233,20 @@ Makefile if desired:
* ``CUDA_PRECISION`` = precision (double, mixed, single)
* ``EXTRAMAKE`` = which Makefile.lammps.\* file to copy to Makefile.lammps
The file Makefile.linux_multi is set up to include support for multiple
The file Makefile.cuda is set up to include support for multiple
GPU architectures as supported by the CUDA toolkit in use. This is done
through using the "--gencode " flag, which can be used multiple times and
thus support all GPU architectures supported by your CUDA compiler.
To enable GPU binning via CUDA performance primitives set the Makefile variable
``CUDPP_OPT = -DUSE_CUDPP -Icudpp_mini``. This should **not** be used with
most modern GPUs.
To support the CUDA multiprocessor server you can set the define
``-DCUDA_PROXY``. Please note that in this case you must **not** use
the CUDA performance primitives and thus set the variable ``CUDPP_OPT``
to empty.
If the library build is successful, 3 files should be created:
``lib/gpu/libgpu.a``\ , ``lib/gpu/nvc_get_devices``\ , and
``lib/gpu/Makefile.lammps``\ . The latter has settings that enable LAMMPS
@ -249,18 +273,18 @@ To build with this package, the KIM library with API v2 must be downloaded
and built on your system. It must include the KIM models that you want to
use with LAMMPS.
If you would like to use the :doc:`kim_query <kim_commands>`
If you would like to use the :doc:`kim query <kim_commands>`
command, you also need to have libcurl installed with the matching
development headers and the curl-config tool.
If you would like to use the :doc:`kim_property <kim_commands>`
If you would like to use the :doc:`kim property <kim_commands>`
command, you need to build LAMMPS with the PYTHON package installed
and linked to Python 3.6 or later. See the :ref:`PYTHON package build info <python>`
for more details on this. After successfully building LAMMPS with Python, you
also need to install the kim-property Python package, which can be easily done using
*pip* as ``pip install kim-property``, or from the *conda-forge* channel as
``conda install kim-property`` if LAMMPS is built in Conda. More detailed
information is available at:
also need to install the ``kim-property`` Python package, which can be easily
done using *pip* as ``pip install kim-property``, or from the *conda-forge*
channel as ``conda install kim-property`` if LAMMPS is built in Conda. More
detailed information is available at:
`kim-property installation <https://github.com/openkim/kim-property#installing-kim-property>`_.
In addition to installing the KIM API, it is also necessary to install the
@ -282,6 +306,7 @@ minutes to hours) to build. Of course you only need to do that once.)
-D DOWNLOAD_KIM=value # download OpenKIM API v2 for build, value = no (default) or yes
-D LMP_DEBUG_CURL=value # set libcurl verbose mode on/off, value = off (default) or on
-D LMP_NO_SSL_CHECK=value # tell libcurl to not verify the peer, value = no (default) or yes
-D KIM_EXTRA_UNITTESTS=value # enables extra unit tests, value = no (default) or yes
If ``DOWNLOAD_KIM`` is set to *yes* (or *on*), the KIM API library
will be downloaded and built inside the CMake build directory. If
@ -290,11 +315,16 @@ minutes to hours) to build. Of course you only need to do that once.)
``PKG_CONFIG_PATH`` environment variable so that libkim-api can be
found, or run the command ``source kim-api-activate``.
Extra unit tests can only be available if they are explicitly requested
(``KIM_EXTRA_UNITTESTS`` is set to *yes* (or *on*)) and the prerequisites
are met. See :ref:`KIM Extra unit tests <kim_extra_unittests>` for
more details on this.
.. tab:: Traditional make
You can download and build the KIM library manually if you prefer;
follow the instructions in ``lib/kim/README``. You can also do
this in one step from the lammps/src dir, using a command like
this in one step from the lammps/src directory, using a command like
these, which simply invoke the ``lib/kim/Install.py`` script with
the specified args.
@ -338,6 +368,39 @@ specify your own CA cert path by setting the environment variable
``CURL_CA_BUNDLE`` to the path of your choice. A call to the KIM web
query would get this value from the environment variable.
.. _kim_extra_unittests:
KIM Extra unit tests (CMake only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
During development, testing, or debugging, if
:doc:`unit testing <Build_development>` is enabled in LAMMPS, one can also
enable extra tests on :doc:`KIM commands <kim_commands>` by setting the
``KIM_EXTRA_UNITTESTS`` to *yes* (or *on*).
Enabling the extra unit tests have some requirements,
* It requires to have internet access.
* It requires to have libcurl installed with the matching development headers
and the curl-config tool.
* It requires to build LAMMPS with the PYTHON package installed and linked to
Python 3.6 or later. See the :ref:`PYTHON package build info <python>` for
more details on this.
* It requires to have ``kim-property`` Python package installed, which can be
easily done using *pip* as ``pip install kim-property``, or from the
*conda-forge* channel as ``conda install kim-property`` if LAMMPS is built in
Conda. More detailed information is available at:
`kim-property installation <https://github.com/openkim/kim-property#installing-kim-property>`_.
* It is also necessary to install
``EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000``,
``EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005``, and
``LennardJones612_UniversalShifted__MO_959249795837_003`` KIM models.
See `Obtaining KIM Models <http://openkim.org/doc/usage/obtaining-models>`_
to learn how to install a pre-built binary of the OpenKIM Repository of
Models or see
`Installing KIM Models <https://openkim.org/doc/usage/obtaining-models/#installing_models>`_
to learn how to install the specific KIM models.
----------
.. _kokkos:
@ -482,11 +545,14 @@ They must be specified in uppercase.
* - VEGA906
- GPU
- AMD GPU MI50/MI60 GFX906
* - VEGA908
- GPU
- AMD GPU GFX908
* - INTEL_GEN
- GPU
- Intel GPUs Gen9+
This list was last updated for version 3.2 of the Kokkos library.
This list was last updated for version 3.3 of the Kokkos library.
.. tabs::
@ -732,6 +798,54 @@ be installed on your system.
----------
.. _mliap:
MLIAP package
---------------------------
Building the MLIAP package requires including the :ref:`SNAP <PKG-SNAP>`
package. There will be an error message if this requirement is not satisfied.
Using the *mliappy* model also requires enabling Python support, which
in turn requires the :ref:`PYTHON <PKG-PYTHON>`
package **and** requires you have the `cython <https://cython.org>`_ software
installed and with it a working ``cythonize`` command. This feature requires
compiling LAMMPS with Python version 3.6 or later.
.. tabs::
.. tab:: CMake build
.. code-block:: bash
-D MLIAP_ENABLE_PYTHON=value # enable mliappy model (default is autodetect)
Without this setting, CMake will check whether it can find a
suitable Python version and the ``cythonize`` command and choose
the default accordingly. During the build procedure the provided
.pyx file(s) will be automatically translated to C++ code and compiled.
Please do **not** run ``cythonize`` manually in the ``src/MLIAP`` folder,
as that can lead to compilation errors if Python support is not enabled.
If you did by accident, please remove the generated .cpp and .h files.
.. tab:: Traditional make
The build uses the ``lib/python/Makefile.mliap_python`` file in the
compile/link process to add a rule to update the files generated by
the ``cythonize`` command in case the corresponding .pyx file(s) were
modified. You may need to modify ``lib/python/Makefile.lammps``
if the LAMMPS build fails.
To manually enforce building MLIAP with Python support enabled,
you can add
``-DMLIAP_PYTHON`` to the ``LMP_INC`` variable in your machine makefile.
You may have to manually run the ``cythonize`` command on .pyx file(s)
in the ``src`` folder, if this is not automatically done during
installing the MLIAP package. Please do **not** run ``cythonize``
in the ``src/MLIAP`` folder, as that can lead to compilation errors
if Python support is not enabled.
If you did by accident, please remove the generated .cpp and .h files.
----------
.. _mscg:
MSCG package
@ -1134,6 +1248,46 @@ be built for the most part with all major versions of the C++ language.
----------
.. _user-pace:
USER-PACE package
-----------------------------
This package requires a library that can be downloaded and built
in lib/pace or somewhere else, which must be done before building
LAMMPS with this package. The code for the library can be found
at: `https://github.com/ICAMS/lammps-user-pace/ <https://github.com/ICAMS/lammps-user-pace/>`_
.. tabs::
.. tab:: CMake build
By default the library will be downloaded from the git repository
and built automatically when the USER-PACE package is enabled with
``-D PKG_USER-PACE=yes``. The location for the sources may be
customized by setting the variable ``PACELIB_URL`` when
configuring with CMake (e.g. to use a local archive on machines
without internet access). Since CMake checks the validity of the
archive with ``md5sum`` you may also need to set ``PACELIB_MD5``
if you provide a different library version than what is downloaded
automatically.
.. tab:: Traditional make
You can download and build the USER-PACE library
in one step from the ``lammps/src`` dir, using these commands,
which invoke the ``lib/pace/Install.py`` script.
.. code-block:: bash
$ make lib-pace # print help message
$ make lib-pace args="-b" # download and build the default version in lib/pace
You should not need to edit the ``lib/pace/Makefile.lammps`` file.
----------
.. _user-plumed:
USER-PLUMED package

16
doc/src/Build_link.rst
View File

@ -20,16 +20,8 @@ the suffix ``.so.0`` (or some other number).
.. note::
Care should be taken to use the same MPI library for the calling code
and the LAMMPS library. The ``library.h`` file includes ``mpi.h``
and uses definitions from it so those need to be available and
consistent. When LAMMPS is compiled with the included STUBS MPI
library, then its ``mpi.h`` file needs to be included. While it is
technically possible to use a full MPI library in the calling code
and link to a serial LAMMPS library compiled with MPI STUBS, it is
recommended to use the *same* MPI library for both, and then use
``MPI_Comm_split()`` in the calling code to pass a suitable
communicator with a subset of MPI ranks to the function creating the
LAMMPS instance.
and the LAMMPS library unless LAMMPS is to be compiled without (real)
MPI support using the include STUBS MPI library.
Link with LAMMPS as a static library
------------------------------------
@ -110,7 +102,7 @@ executable, that are also required to link the LAMMPS executable.
.. code-block:: bash
gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
gcc -c -O -I${HOME}/lammps/src -caller.c
g++ -o caller caller.o -L${HOME}/lammps/lib/poems \
-L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src \
-llammps_serial -lpoems -lmpi_stubs
@ -174,7 +166,7 @@ the POEMS package installed becomes:
.. code-block:: bash
gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
gcc -c -O -I${HOME}/lammps/src -caller.c
g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial
Locating liblammps.so at runtime

11
doc/src/Build_manual.rst
View File

@ -74,7 +74,11 @@ For the documentation build a python virtual environment is set up in
the folder ``doc/docenv`` and various python packages are installed into
that virtual environment via the ``pip`` tool. For rendering embedded
LaTeX code also the `MathJax <https://www.mathjax.org/>`_ JavaScript
engine needs to be downloaded.
engine needs to be downloaded. If you need to pass additional options
to the pip commands to work (e.g. to use a web proxy or to point to
additional SSL certificates) you can set them via the ``PIP_OPTIONS``
environment variable or uncomment and edit the ``PIP_OPTIONS`` setting
at beginning of the makefile.
The actual translation is then done via ``make`` commands in the doc
folder. The following ``make`` commands are available:
@ -108,7 +112,10 @@ installation of the HTML manual pages into the "install" step when
installing LAMMPS after the CMake build via ``cmake --build . --target
install``. The documentation build is included in the default build
target, but can also be requested independently with
``cmake --build . --target doc``.
``cmake --build . --target doc``. If you need to pass additional options
to the pip commands to work (e.g. to use a web proxy or to point to
additional SSL certificates) you can set them via the ``PIP_OPTIONS``
environment variable.
.. code-block:: bash

17
doc/src/Build_package.rst
View File

@ -30,17 +30,17 @@ steps, as explained on the :doc:`Build extras <Build_extras>` page.
These links take you to the extra instructions for those select
packages:
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`COMPRESS <compress>` | :ref:`GPU <gpu>` | :ref:`KIM <kim>` | :ref:`KOKKOS <kokkos>` | :ref:`LATTE <latte>` | :ref:`MESSAGE <message>` |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`MSCG <mscg>` | :ref:`OPT <opt>` | :ref:`POEMS <poems>` | :ref:`PYTHON <python>` | :ref:`VORONOI <voronoi>` | :ref:`USER-ADIOS <user-adios>` |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-ATC <user-atc>` | :ref:`USER-AWPMD <user-awpmd>` | :ref:`USER-COLVARS <user-colvars>` | :ref:`USER-H5MD <user-h5md>` | :ref:`USER-INTEL <user-intel>` | :ref:`USER-MOLFILE <user-molfile>` |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-NETCDF <user-netcdf>` | :ref:`USER-PLUMED <user-plumed>` | :ref:`USER-OMP <user-omp>` | :ref:`USER-QMMM <user-qmmm>` | :ref:`USER-QUIP <user-quip>` | :ref:`USER-SCAFACOS <user-scafacos>` |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-SMD <user-smd>` | :ref:`USER-VTK <user-vtk>` | | | | |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-NETCDF <user-netcdf>` | :ref:`USER-PACE <user-pace>` | :ref:`USER-PLUMED <user-plumed>` | :ref:`USER-OMP <user-omp>` | :ref:`USER-QMMM <user-qmmm>` | :ref:`USER-QUIP <user-quip>` |
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-SCAFACOS <user-scafacos>` | :ref:`USER-SMD <user-smd>` | :ref:`USER-VTK <user-vtk>` | | | |
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
The mechanism for including packages is simple but different for CMake
versus make.
@ -160,6 +160,7 @@ one of them as a starting point and customize it to your needs.
cmake -C ../cmake/presets/clang.cmake [OPTIONS] ../cmake # change settings to use the Clang compilers by default
cmake -C ../cmake/presets/gcc.cmake [OPTIONS] ../cmake # change settings to use the GNU compilers by default
cmake -C ../cmake/presets/intel.cmake [OPTIONS] ../cmake # change settings to use the Intel compilers by default
cmake -C ../cmake/presets/pgi.cmake [OPTIONS] ../cmake # change settings to use the PGI compilers by default
cmake -C ../cmake/presets/all_on.cmake [OPTIONS] ../cmake # enable all packages
cmake -C ../cmake/presets/all_off.cmake [OPTIONS] ../cmake # disable all packages
mingw64-cmake -C ../cmake/presets/mingw-cross.cmake [OPTIONS] ../cmake # compile with MinGW cross compilers

7
doc/src/Commands_all.rst
View File

@ -60,11 +60,7 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`include <include>`
* :doc:`info <info>`
* :doc:`jump <jump>`
* :doc:`kim_init <kim_commands>`
* :doc:`kim_interactions <kim_commands>`
* :doc:`kim_param <kim_commands>`
* :doc:`kim_property <kim_commands>`
* :doc:`kim_query <kim_commands>`
* :doc:`kim <kim_commands>`
* :doc:`kspace_modify <kspace_modify>`
* :doc:`kspace_style <kspace_style>`
* :doc:`label <label>`
@ -90,6 +86,7 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`pair_style <pair_style>`
* :doc:`pair_write <pair_write>`
* :doc:`partition <partition>`
* :doc:`plugin <plugin>`
* :doc:`prd <prd>`
* :doc:`print <print>`
* :doc:`processors <processors>`

2
doc/src/Commands_bond.rst
View File

@ -126,7 +126,7 @@ OPT.
* :doc:`quadratic (o) <dihedral_quadratic>`
* :doc:`spherical <dihedral_spherical>`
* :doc:`table (o) <dihedral_table>`
* :doc:`table/cut <dihedral_table_cut>`
* :doc:`table/cut <dihedral_table>`
.. _improper:

11
doc/src/Commands_fix.rst
View File

@ -49,6 +49,7 @@ OPT.
* :doc:`bond/react <fix_bond_react>`
* :doc:`bond/swap <fix_bond_swap>`
* :doc:`box/relax <fix_box_relax>`
* :doc:`charge/regulation <fix_charge_regulation>`
* :doc:`client/md <fix_client_md>`
* :doc:`cmap <fix_cmap>`
* :doc:`colvars <fix_colvars>`
@ -117,7 +118,7 @@ OPT.
* :doc:`nph/eff <fix_nh_eff>`
* :doc:`nph/sphere (o) <fix_nph_sphere>`
* :doc:`nphug <fix_nphug>`
* :doc:`npt (iko) <fix_nh>`
* :doc:`npt (giko) <fix_nh>`
* :doc:`npt/asphere (o) <fix_npt_asphere>`
* :doc:`npt/body <fix_npt_body>`
* :doc:`npt/cauchy <fix_npt_cauchy>`
@ -125,8 +126,8 @@ OPT.
* :doc:`npt/sphere (o) <fix_npt_sphere>`
* :doc:`npt/uef <fix_nh_uef>`
* :doc:`numdiff <fix_numdiff>`
* :doc:`nve (iko) <fix_nve>`
* :doc:`nve/asphere (i) <fix_nve_asphere>`
* :doc:`nve (giko) <fix_nve>`
* :doc:`nve/asphere (gi) <fix_nve_asphere>`
* :doc:`nve/asphere/noforce <fix_nve_asphere_noforce>`
* :doc:`nve/awpmd <fix_nve_awpmd>`
* :doc:`nve/body <fix_nve_body>`
@ -141,7 +142,7 @@ OPT.
* :doc:`nve/spin <fix_nve_spin>`
* :doc:`nve/tri <fix_nve_tri>`
* :doc:`nvk <fix_nvk>`
* :doc:`nvt (iko) <fix_nh>`
* :doc:`nvt (giko) <fix_nh>`
* :doc:`nvt/asphere (o) <fix_nvt_asphere>`
* :doc:`nvt/body <fix_nvt_body>`
* :doc:`nvt/eff <fix_nh_eff>`
@ -224,6 +225,8 @@ OPT.
* :doc:`temp/rescale <fix_temp_rescale>`
* :doc:`temp/rescale/eff <fix_temp_rescale_eff>`
* :doc:`tfmc <fix_tfmc>`
* :doc:`tgnpt/drude <fix_tgnh_drude>`
* :doc:`tgnvt/drude <fix_tgnh_drude>`
* :doc:`thermal/conductivity <fix_thermal_conductivity>`
* :doc:`ti/spring <fix_ti_spring>`
* :doc:`tmd <fix_tmd>`

13
doc/src/Commands_pair.rst
View File

@ -26,6 +26,7 @@ OPT.
* :doc:`zero <pair_zero>`
* :doc:`hybrid (k) <pair_hybrid>`
* :doc:`hybrid/overlay (k) <pair_hybrid>`
* :doc:`hybrid/scaled <pair_hybrid>`
* :doc:`kim <pair_kim>`
* :doc:`list <pair_list>`
*
@ -33,7 +34,6 @@ OPT.
*
*
*
*
* :doc:`adp (o) <pair_adp>`
* :doc:`agni (o) <pair_agni>`
* :doc:`airebo (io) <pair_airebo>`
@ -69,6 +69,7 @@ OPT.
* :doc:`comb3 <pair_comb>`
* :doc:`cosine/squared <pair_cosine_squared>`
* :doc:`coul/cut (gko) <pair_coul>`
* :doc:`coul/cut/global (o) <pair_coul>`
* :doc:`coul/cut/soft (o) <pair_fep_soft>`
* :doc:`coul/debye (gko) <pair_coul>`
* :doc:`coul/diel (o) <pair_coul_diel>`
@ -86,6 +87,8 @@ OPT.
* :doc:`coul/wolf/cs <pair_cs>`
* :doc:`dpd (gio) <pair_dpd>`
* :doc:`dpd/fdt <pair_dpd_fdt>`
* :doc:`dpd/ext <pair_dpd_ext>`
* :doc:`dpd/ext/tstat <pair_dpd_ext>`
* :doc:`dpd/fdt/energy (k) <pair_dpd_fdt>`
* :doc:`dpd/tstat (go) <pair_dpd>`
* :doc:`dsmc <pair_dsmc>`
@ -96,6 +99,7 @@ OPT.
* :doc:`eam/cd <pair_eam>`
* :doc:`eam/cd/old <pair_eam>`
* :doc:`eam/fs (gikot) <pair_eam>`
* :doc:`eam/he <pair_eam>`
* :doc:`edip (o) <pair_edip>`
* :doc:`edip/multi <pair_edip>`
* :doc:`edpd <pair_mesodpd>`
@ -121,7 +125,7 @@ OPT.
* :doc:`lebedeva/z <pair_lebedeva_z>`
* :doc:`lennard/mdf <pair_mdf>`
* :doc:`line/lj <pair_line_lj>`
* :doc:`lj/charmm/coul/charmm (iko) <pair_charmm>`
* :doc:`lj/charmm/coul/charmm (giko) <pair_charmm>`
* :doc:`lj/charmm/coul/charmm/implicit (ko) <pair_charmm>`
* :doc:`lj/charmm/coul/long (gikot) <pair_charmm>`
* :doc:`lj/charmm/coul/long/soft (o) <pair_fep_soft>`
@ -162,6 +166,7 @@ OPT.
* :doc:`lj/long/dipole/long <pair_dipole>`
* :doc:`lj/long/tip4p/long (o) <pair_lj_long>`
* :doc:`lj/mdf <pair_mdf>`
* :doc:`lj/relres (o) <pair_lj_relres>`
* :doc:`lj/sdk (gko) <pair_sdk>`
* :doc:`lj/sdk/coul/long (go) <pair_sdk>`
* :doc:`lj/sdk/coul/msm (o) <pair_sdk>`
@ -185,7 +190,7 @@ OPT.
* :doc:`mgpt <pair_mgpt>`
* :doc:`mie/cut (g) <pair_mie>`
* :doc:`mliap <pair_mliap>`
* :doc:`mm3/switch3/coulgauss/long <pair_mm3_switch3_coulgauss_long>`
* :doc:`mm3/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>`
* :doc:`momb <pair_momb>`
* :doc:`morse (gkot) <pair_morse>`
* :doc:`morse/smooth/linear (o) <pair_morse>`
@ -213,6 +218,7 @@ OPT.
* :doc:`oxrna2/stk <pair_oxrna2>`
* :doc:`oxrna2/xstk <pair_oxrna2>`
* :doc:`oxrna2/coaxstk <pair_oxrna2>`
* :doc:`pace <pair_pace>`
* :doc:`peri/eps <pair_peri>`
* :doc:`peri/lps (o) <pair_peri>`
* :doc:`peri/pmb (o) <pair_peri>`
@ -262,6 +268,7 @@ OPT.
* :doc:`ufm (got) <pair_ufm>`
* :doc:`vashishta (gko) <pair_vashishta>`
* :doc:`vashishta/table (o) <pair_vashishta>`
* :doc:`wf/cut <pair_wf_cut>`
* :doc:`yukawa (gko) <pair_yukawa>`
* :doc:`yukawa/colloid (go) <pair_yukawa_colloid>`
* :doc:`zbl (gko) <pair_zbl>`

23
doc/src/Commands_parse.rst
View File

@ -162,3 +162,26 @@ LAMMPS:
triple quotes can be nested in the usual manner. See the doc pages
for those commands for examples. Only one of level of nesting is
allowed, but that should be sufficient for most use cases.
.. admonition:: ASCII versus UTF-8
:class: note
LAMMPS expects and processes 7-bit ASCII format text internally.
Many modern environments use UTF-8 encoding, which is a superset
of the 7-bit ASCII character table and thus mostly compatible.
However, there are several non-ASCII characters that can look
very similar to their ASCII equivalents or are invisible (so they
look like a blank), but are encoded differently. Web browsers,
PDF viewers, document editors are known to sometimes replace one
with the other for a better looking output. However, that can
lead to problems, for instance, when using cut-n-paste of input
file examples from web pages, or when using a document editor
(not a dedicated plain text editor) for writing LAMMPS inputs.
LAMMPS will try to detect this and substitute the non-ASCII
characters with their ASCII equivalents where known. There also
is going to be a warning printed, if this occurs. It is
recommended to avoid such characters altogether in LAMMPS input,
data and potential files. The replacement tables are likely
incomplete and dependent on users reporting problems processing
correctly looking input containing UTF-8 encoded non-ASCII
characters.

2
doc/src/Developer.rst
View File

@ -13,6 +13,8 @@ of time and requests from the LAMMPS user community.
Developer_org
Developer_flow
Developer_write
Developer_notes
Developer_plugins
Developer_unittest
Classes
Developer_utils

227
doc/src/Developer_notes.rst Normal file
View File

@ -0,0 +1,227 @@
Notes for developers and code maintainers
-----------------------------------------
This section documents how some of the code functionality within
LAMMPS works at a conceptual level. Comments on code in source files
typically document what a variable stores, what a small section of
code does, or what a function does and its input/outputs. The topics
on this page are intended to document code functionality at a higher level.
Fix contributions to instantaneous energy, virial, and cumulative energy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Fixes can calculate contributions to the instantaneous energy and/or
virial of the system, both in a global and peratom sense. Fixes that
perform thermostatting or barostatting can calculate the cumulative
energy they add to or subtract from the system, which is accessed by
the *ecouple* and *econserve* thermodynamic keywords. This subsection
explains how both work and what flags to set in a new fix to enable
this functionality.
Let's start with thermostatting and barostatting fixes. Examples are
the :doc:`fix langevin <fix_langevin>` and :doc:`fix npt <fix_nh>`
commands. Here is what the fix needs to do:
* Set the variable *ecouple_flag* = 1 in the constructor. Also set
*scalar_flag* = 1, *extscalar* = 1, and *global_freq* to a timestep
increment which matches how often the fix is invoked.
* Implement a compute_scalar() method that returns the cumulative
energy added or subtracted by the fix, e.g. by rescaling the
velocity of atoms. The sign convention is that subtracted energy is
positive, added energy is negative. This must be the total energy
added to the entire system, i.e. an "extensive" quantity, not a
per-atom energy. Cumulative means the summed energy since the fix
was instantiated, even across multiple runs. This is because the
energy is used by the *econserve* thermodynamic keyword to check
that the fix is conserving the total energy of the system,
i.e. potential energy + kinetic energy + coupling energy = a
constant.
And here is how the code operates:
* The Modify class makes a list of all fixes that set *ecouple_flag* = 1.
* The :doc:`thermo_style custom <thermo_style>` command defines
*ecouple* and *econserve* keywords.
* These keywords sum the energy contributions from all the
*ecouple_flag* = 1 fixes by invoking the energy_couple() method in
the Modify class, which calls the compute_scalar() method of each
fix in the list.
------------------
Next, here is how a fix contributes to the instantaneous energy and
virial of the system. First, it sets any or all of these flags to a
value of 1 in their constructor:
* *energy_global_flag* to contribute to global energy, example: :doc:`fix indent <fix_indent>`
* *energy_peratom_flag* to contribute to peratom energy, :doc:`fix cmap <fix_cmap>`
* *virial_global_flag* to contribute to global virial, example: :doc:`fix wall <fix_wall>`
* *virial_peratom_flag* to contribute to peratom virial, example: :doc:`fix wall <fix_wall>`
The fix must also do the following:
* For global energy, implement a compute_scalar() method that returns
the energy added or subtracted on this timestep. Here the sign
convention is that added energy is positive, subtracted energy is
negative.
* For peratom energy, invoke the ev_init(eflag,vflag) function each
time the fix is invoked, which initializes per-atom energy storage.
The value of eflag may need to be stored from an earlier call to the
fix during the same timestep. See how the :doc:`fix cmap
<fix_cmap>` command does this in src/MOLECULE/fix_cmap.cpp. When an
energy for one or more atoms is calculated, invoke the ev_tally()
function to tally the contribution to each atom. Both the ev_init()
and ev_tally() methods are in the parent Fix class.
* For global and/or peratom virial, invoke the v_init(vflag) function
each time the fix is invoked, which initializes virial storage.
When forces on one or more atoms are calculated, invoke the
v_tally() function to tally the contribution. Both the v_init() and
v_tally() methods are in the parent Fix class. Note that there are
several variants of v_tally(); choose the one appropriate to your
fix.
.. note::
The ev_init() and ev_tally() methods also account for global and
peratom virial contributions. Thus you do not need to invoke the
v_init() and v_tally() methods, if the fix also calculates peratom
energies.
The fix must also specify whether (by default) to include or exclude
these contributions to the global/peratom energy/virial of the system.
For the fix to include the contributions, set either of both of these
variables in the constructor:
* *thermo_energy* = 1, for global and peratom energy
* *thermo_virial* = 1, for global and peratom virial
Note that these variables are zeroed in fix.cpp. Thus if you don't
set the variables, the contributions will be excluded (by default)
However, the user has ultimate control over whether to include or
exclude the contributions of the fix via the :doc:`fix modify
<fix_modify>` command:
* fix modify *energy yes* to include global and peratom energy contributions
* fix modify *virial yes* to include global and peratom virial contributions
If the fix contributes to any of the global/peratom energy/virial
values for the system, it should be explained on the fix doc page,
along with the default values for the *energy yes/no* and *virial
yes/no* settings of the :doc:`fix modify <fix_modify>` command.
Finally, these 4 contributions are included in the output of 4
computes:
* global energy in :doc:`compute pe <compute_pe>`
* peratom energy in :doc:`compute pe/atom <compute_pe_atom>`
* global virial in :doc:`compute pressure <compute_pressure>`
* peratom virial in :doc:`compute stress/atom <compute_stress_atom>`
These computes invoke a method of the Modify class to include
contributions from fixes that have the corresponding flags set,
e.g. *energy_peratom_flag* and *thermo_energy* for :doc:`compute
pe/atom <compute_pe_atom>`.
Note that each compute has an optional keyword to either include or
exclude all contributions from fixes. Also note that :doc:`compute pe
<compute_pe>` and :doc:`compute pressure <compute_pressure>` are what
is used (by default) by :doc:`thermodynamic output <thermo_style>` to
calculate values for its *pe* and *press* keywords.
KSpace PPPM FFT grids
^^^^^^^^^^^^^^^^^^^^^
The various :doc:`KSpace PPPM <kspace_style>` styles in LAMMPS use
FFTs to solve Poisson's equation. This subsection describes:
* how FFT grids are defined
* how they are decomposed across processors
* how they are indexed by each processor
* how particle charge and electric field values are mapped to/from
the grid
An FFT grid cell is a 3d volume; grid points are corners of a grid
cell and the code stores values assigned to grid points in vectors or
3d arrays. A global 3d FFT grid has points indexed 0 to N-1 inclusive
in each dimension.
Each processor owns two subsets of the grid, each subset is
brick-shaped. Depending on how it is used, these subsets are
allocated as a 1d vector or 3d array. Either way, the ordering of
values within contiguous memory x fastest, then y, z slowest.
For the ``3d decomposition`` of the grid, the global grid is
partitioned into bricks that correspond to the sub-domains of the
simulation box that each processor owns. Often, this is a regular 3d
array (Px by Py by Pz) of bricks, where P = number of processors =
Px * Py * Pz. More generally it can be a tiled decomposition, where
each processor owns a brick and the union of all the bricks is the
global grid. Tiled decompositions are produced by load balancing with
the RCB algorithm; see the :doc:`balance rcb <balance>` command.
For the ``FFT decompostion`` of the grid, each processor owns a brick
that spans the entire x dimension of the grid while the y and z
dimensions are partitioned as a regular 2d array (P1 by P2), where P =
P1 * P2.
The following indices store the inclusive bounds of the brick a
processor owns, within the global grid:
.. parsed-literal::
nxlo_in,nxhi_in,nylo_in,nyhi_in,nzlo_in,nzhi_in = 3d decomposition brick
nxlo_fft,nxhi_fft,nylo_fft,nyhi_fft,nzlo_fft,nzhi_fft = FFT decomposition brick
nxlo_out,nxhi_out,nylo_out,nyhi_out,nzlo_out,nzhi_out = 3d decomposition brick + ghost cells
The ``in`` and ``fft`` indices are from 0 to N-1 inclusive in each
dimension, where N is the grid size.
The ``out`` indices index an array which stores the ``in`` subset of
the grid plus ghost cells that surround it. These indices can thus be
< 0 or >= N.
The number of ghost cells a processor owns in each of the 6 directions
is a function of:
.. parsed-literal::
neighbor skin distance (since atoms can move outside a proc subdomain)
qdist = offset or charge from atom due to TIP4P fictitious charge
order = mapping stencil size
shift = factor used when order is an even number (see below)
Here is an explanation of how the PPPM variables ``order``,
``nlower`` / ``nupper``, ``shift``, and ``OFFSET`` work. They are the
relevant variables that determine how atom charge is mapped to grid
points and how field values are mapped from grid points to atoms:
.. parsed-literal::
order = # of nearby grid points in each dim that atom charge/field are mapped to/from
nlower,nupper = extent of stencil around the grid point an atom is assigned to
OFFSET = large integer added/subtracted when mapping to avoid int(-0.75) = 0 when -1 is the desired result
The particle_map() method assigns each atom to a grid point.
If order is even, say 4:
.. parsed-literal::
atom is assigned to grid point to its left (in each dim)
shift = OFFSET
nlower = -1, nupper = 2, which are offsets from assigned grid point
window of mapping grid pts is thus 2 grid points to left of atom, 2 to right
If order is odd, say 5:
.. parsed-literal::
atom is assigned to left/right grid pt it is closest to (in each dim)
shift = OFFSET + 0.5
nlower = 2, nupper = 2
if point is in left half of cell, then window of affected grid pts is 3 grid points to left of atom, 2 to right
if point is in right half of cell, then window of affected grid pts is 2 grid points to left of atom, 3 to right
These settings apply to each dimension, so that if order = 5, an
atom's charge is mapped to 125 grid points that surround the atom.

197
doc/src/Developer_org.rst
View File

@ -1,68 +1,75 @@
Source files
------------
The source files of the LAMMPS code are found in two
directories of the distribution: ``src`` and ``lib``.
Most of the code is C++ but there are small numbers of files
in several other languages.
The source files of the LAMMPS code are found in two directories of the
distribution: ``src`` and ``lib``. Most of the code is written in C++
but there are small a number of files in several other languages like C,
Fortran, Shell script, or Python.
The core of the code is located in the
``src`` folder and its sub-directories.
A sizable number of these files are in the ``src`` directory
itself, but there are plenty of :doc:`packages <Packages>`, which can be
included or excluded when LAMMPS is built. See the :doc:`Include
packages in build <Build_package>` section of the manual for more
information about that part of the build process. LAMMPS currently
supports building with :doc:`conventional makefiles <Build_make>` and
through :doc:`CMake <Build_cmake>` which differ in how packages are
enabled or disabled for a LAMMPS binary. The source files for each
The core of the code is located in the ``src`` folder and its
sub-directories. A sizable number of these files are in the ``src``
directory itself, but there are plenty of :doc:`packages <Packages>`,
which can be included or excluded when LAMMPS is built. See the
:doc:`Include packages in build <Build_package>` section of the manual
for more information about that part of the build process. LAMMPS
currently supports building with :doc:`conventional makefiles
<Build_make>` and through :doc:`CMake <Build_cmake>`. Those procedures
differ in how packages are enabled or disabled for inclusion into a
LAMMPS binary so they cannot be mixed. The source files for each
package are in all-uppercase sub-directories of the ``src`` folder, for
example ``src/MOLECULE`` or ``src/USER-MISC``. The ``src/STUBS``
sub-directory is not a package but contains a dummy MPI library, that is
used when building a serial version of the code. The ``src/MAKE``
directory contains makefiles with settings and flags for a variety of
configuration and machines for the build process with traditional
makefiles.
directory and its sub-directories contain makefiles with settings and
flags for a variety of configuration and machines for the build process
with traditional makefiles.
The ``lib`` directory contains the source code for several supporting
libraries or files with configuration settings to use globally installed
libraries, that are required by some of the optional packages.
Each sub-directory, like ``lib/poems`` or ``lib/gpu``, contains the
source files, some of which are in different languages such as Fortran
or CUDA. These libraries are linked to during a LAMMPS build, if the
corresponding package is installed.
libraries, that are required by some of the optional packages. They may
include python scripts that can transparently download additional source
code on request. Each sub-directory, like ``lib/poems`` or ``lib/gpu``,
contains the source files, some of which are in different languages such
as Fortran or CUDA. These libraries included in the LAMMPS build,
if the corresponding package is installed.
LAMMPS C++ source files almost always come in pairs, such as
``src/run.cpp`` (implementation file) and ``src/run.h`` (header file).
Each pair of files defines a C++
class, for example the :cpp:class:`LAMMPS_NS::Run` class which contains
the code invoked by the :doc:`run <run>` command in a LAMMPS input script.
As this example illustrates, source file and class names often have a
one-to-one correspondence with a command used in a LAMMPS input script.
Some source files and classes do not have a corresponding input script
Each pair of files defines a C++ class, for example the
:cpp:class:`LAMMPS_NS::Run` class which contains the code invoked by the
:doc:`run <run>` command in a LAMMPS input script. As this example
illustrates, source file and class names often have a one-to-one
correspondence with a command used in a LAMMPS input script. Some
source files and classes do not have a corresponding input script
command, e.g. ``src/force.cpp`` and the :cpp:class:`LAMMPS_NS::Force`
class. They are discussed in the next section.
A small number of C++ classes and utility functions are implemented with
only a ``.h`` file. Examples are the Pointer class or the MathVec functions.
The names of all source files are in lower case and may use the
underscore character '_' to separate words. Outside of bundled libraries
which may have different conventions, all C and C++ header files have a
``.h`` extension, all C++ files have a ``.cpp`` extension, and C files a
``.c`` extension. A small number of C++ classes and utility functions
are implemented with only a ``.h`` file. Examples are the Pointers and
Commands classes or the MathVec functions.
Class topology
--------------
Though LAMMPS has a lot of source files and classes, its class topology
is relative flat, as outlined in the :ref:`class-topology` figure. Each
name refers to a class and has a pair of associated source files in the
``src`` folder, for example the class :cpp:class:`LAMMPS_NS::Memory`
corresponds to the files ``memory.cpp`` and ``memory.h``, or the class
:cpp:class:`LAMMPS_NS::AtomVec` corresponds to the files
``atom_vec.cpp`` and ``atom_vec.h``. Full lines in the figure represent
compositing: that is the class to the left holds a pointer to an
instance of the class to the right. Dashed lines instead represent
inheritance: the class to the right is derived from the class on the
left. Classes with a red boundary are not instantiated directly, but
they represent the base classes for "styles". Those "styles" make up
the bulk of the LAMMPS code and only a few typical examples are included
in the figure for demonstration purposes.
is not very deep, which can be seen from the :ref:`class-topology`
figure. In that figure, each name refers to a class and has a pair of
associated source files in the ``src`` folder, for example the class
:cpp:class:`LAMMPS_NS::Memory` corresponds to the files ``memory.cpp``
and ``memory.h``, or the class :cpp:class:`LAMMPS_NS::AtomVec`
corresponds to the files ``atom_vec.cpp`` and ``atom_vec.h``. Full
lines in the figure represent compositing: that is the class at the base
of the arrow holds a pointer to an instance of the class at the tip.
Dashed lines instead represent inheritance: the class to the tip of the
arrow is derived from the class at the base. Classes with a red boundary
are not instantiated directly, but they represent the base classes for
"styles". Those "styles" make up the bulk of the LAMMPS code and only
a few representative examples are included in the figure so it remains
readable.
.. _class-topology:
.. figure:: JPG/lammps-classes.png
@ -82,8 +89,8 @@ in the figure for demonstration purposes.
derived classes, which may also hold instances of other classes.
The :cpp:class:`LAMMPS_NS::LAMMPS` class is the topmost class and
represents what is referred to an "instance" of LAMMPS. It is a
composite holding references to instances of other core classes
represents what is generally referred to an "instance" of LAMMPS. It is
a composite holding pointers to instances of other core classes
providing the core functionality of the MD engine in LAMMPS and through
them abstractions of the required operations. The constructor of the
LAMMPS class will instantiate those instances, process the command line
@ -91,60 +98,67 @@ flags, initialize MPI (if not already done) and set up file pointers for
input and output. The destructor will shut everything down and free all
associated memory. Thus code for the standalone LAMMPS executable in
``main.cpp`` simply initializes MPI, instantiates a single instance of
LAMMPS, and passes it the command line flags and input script. It
LAMMPS while passing it the command line flags and input script. It
deletes the LAMMPS instance after the method reading the input returns
and shuts down the MPI environment before it exits the executable.
The :cpp:class:`LAMMPS_NS::Pointers` is not shown in the
:ref:`class-topology` figure, it holds references to members of the
`LAMMPS_NS::LAMMPS`, so that all classes derived from
:cpp:class:`LAMMPS_NS::Pointers` have direct access to those reference.
From the class topology all classes with blue boundary are referenced in
this class and all classes in the second and third columns, that are not
listed as derived classes are instead derived from
:cpp:class:`LAMMPS_NS::Pointers`.
:ref:`class-topology` figure for clarity. It holds references to many
of the members of the `LAMMPS_NS::LAMMPS`, so that all classes derived
from :cpp:class:`LAMMPS_NS::Pointers` have direct access to those
reference. From the class topology all classes with blue boundary are
referenced in the Pointers class and all classes in the second and third
columns, that are not listed as derived classes are instead derived from
:cpp:class:`LAMMPS_NS::Pointers`. To initialize the pointer references
in Pointers, a pointer to the LAMMPS class instance needs to be passed
to the constructor and thus all constructors for classes derived from it
must do so and pass this pointer to the constructor for Pointers.
Since all storage is encapsulated, the LAMMPS class can also be
instantiated multiple times by a calling code, and that can be either
simultaneously or consecutively. When running in parallel with MPI,
care has to be taken, that suitable communicators are used to not
create conflicts between different instances.
Since all storage is supposed to be encapsulated (there are a few
exceptions), the LAMMPS class can also be instantiated multiple times by
a calling code. Outside of the aforementioned exceptions, those LAMMPS
instances can be used alternately. As of the time of this writing
(early 2021) LAMMPS is not yet sufficiently thread-safe for concurrent
execution. When running in parallel with MPI, care has to be taken,
that suitable copies of communicators are used to not create conflicts
between different instances.
The LAMMPS class currently holds instances of 19 classes representing
different core functionalities There are a handful of virtual parent
classes in LAMMPS that define what LAMMPS calls ``styles``. They are
shaded red in the :ref:`class-topology` figure. Each of these are
The LAMMPS class currently (early 2021) holds instances of 19 classes
representing the core functionality. There are a handful of virtual
parent classes in LAMMPS that define what LAMMPS calls ``styles``. They
are shaded red in the :ref:`class-topology` figure. Each of these are
parents of a number of child classes that implement the interface
defined by the parent class. There are two main categories of these
``styles``: some may only have one instance active at a time (e.g. atom,
pair, bond, angle, dihedral, improper, kspace, comm) and there is a
dedicated pointer variable in the composite class that manages them.
dedicated pointer variable for each of them in the composite class.
Setups that require a mix of different such styles have to use a
*hybrid* class that manages and forwards calls to the corresponding
sub-styles for the designated subset of atoms or data. or the composite
class may have lists of class instances, e.g. Modify handles lists of
compute and fix styles, while Output handles dumps class instances.
*hybrid* class that takes the place of the one allowed instance and then
manages and forwards calls to the corresponding sub-styles for the
designated subset of atoms or data. The composite class may also have
lists of class instances, e.g. Modify handles lists of compute and fix
styles, while Output handles a list of dump class instances.
The exception to this scheme are the ``command`` style classes. These
implement specific commands that can be invoked before, after, or between
runs or are commands which launch a simulation. For these an instance
of the class is created, its command() method called and then, after
completion, the class instance deleted. Examples for this are the
create_box, create_atoms, minimize, run, or velocity command styles.
implement specific commands that can be invoked before, after, or in
between runs. For these an instance of the class is created, its
command() method called and then, after completion, the class instance
deleted. Examples for this are the create_box, create_atoms, minimize,
run, set, or velocity command styles.
For all those ``styles`` certain naming conventions are employed: for
the fix nve command the class is called FixNVE and the files are
the fix nve command the class is called FixNVE and the source files are
``fix_nve.h`` and ``fix_nve.cpp``. Similarly for fix ave/time we have
FixAveTime and ``fix_ave_time.h`` and ``fix_ave_time.cpp``. Style names
are lower case and without spaces or special characters. A suffix or
multiple appended with a forward slash '/' denotes a variant of the
corresponding class without the suffix. To connect the style name and
the class name, LAMMPS uses macros like the following ATOM\_CLASS,
PAIR\_CLASS, BOND\_CLASS, REGION\_CLASS, FIX\_CLASS, COMPUTE\_CLASS,
or DUMP\_CLASS in the corresponding header file. During compilation
files with the pattern ``style_name.h`` are created that contain include
statements including all headers of all styles of a given type that
are currently active (or "installed).
words are appended with a forward slash '/' which denotes a variant of
the corresponding class without the suffix. To connect the style name
and the class name, LAMMPS uses macros like: ``AtomStyle()``,
``PairStyle()``, ``BondStyle()``, ``RegionStyle()``, and so on in the
corresponding header file. During configuration or compilation files
with the pattern ``style_<name>.h`` are created that consist of a list
of include statements including all headers of all styles of a given
type that are currently active (or "installed).
More details on individual classes in the :ref:`class-topology` are as
@ -152,20 +166,20 @@ follows:
- The Memory class handles allocation of all large vectors and arrays.
- The Error class prints all error and warning messages.
- The Error class prints all (terminal) error and warning messages.
- The Universe class sets up partitions of processors so that multiple
simulations can be run, each on a subset of the processors allocated
for a run, e.g. by the mpirun command.
- The Universe class sets up one or more partitions of processors so
that one or multiple simulations can be run, on the processors
allocated for a run, e.g. by the mpirun command.
- The Input class reads and processes input input strings and files,
stores variables, and invokes :doc:`commands <Commands_all>`.
- As discussed above, command style classes are directly derived from
the Pointers class. They provide input script commands that perform
one-time operations before/after/between simulations or which invoke a
simulation. They are instantiated from within the Input class,
invoked, then immediately destructed.
- Command style classes are derived from the Command class. They provide
input script commands that perform one-time operations
before/after/between simulations or which invoke a simulation. They
are usually instantiated from within the Input class, its ``command``
method invoked, and then immediately destructed.
- The Finish class is instantiated to print statistics to the screen
after a simulation is performed, by commands like run and minimize.
@ -241,7 +255,8 @@ follows:
.. TODO section on "Spatial decomposition and parallel operations"
.. diagram of 3d processor grid, brick vs. tiled. local vs. ghost
.. atoms, 6-way communication with pack/unpack functions,
.. PBC as part of the communication
.. PBC as part of the communication, forward and reverse communication
.. rendezvous communication, ring communication.
.. TODO section on "Fixes, Computes, and Variables"
.. how and when data is computed and provided and how it is

251
doc/src/Developer_plugins.rst Normal file
View File

@ -0,0 +1,251 @@
Writing plugins
---------------
Plugins provide a mechanism to add functionality to a LAMMPS executable
without recompiling LAMMPS. The functionality for this and the
:doc:`plugin command <plugin>` are implemented in the
:ref:`PLUGIN package <PKG-PLUGIN>` which must be installed to use plugins.
Plugins use the operating system's capability to load dynamic shared
object (DSO) files in a way similar shared libraries and then reference
specific functions in those DSOs. Any DSO file with plugins has to include
an initialization function with a specific name, "lammpsplugin_init", that
has to follow specific rules described below. When loading the DSO with
the "plugin" command, this function is looked up and called and will then
register the contained plugin(s) with LAMMPS.
From the programmer perspective this can work because of the object
oriented design of LAMMPS where all pair style commands are derived from
the class Pair, all fix style commands from the class Fix and so on and
usually only functions present in those base classes are called
directly. When a :doc:`pair_style` command or :doc:`fix` command is
issued a new instance of such a derived class is created. This is done
by a so-called factory function which is mapped to the style name. Thus
when, for example, the LAMMPS processes the command ``pair_style lj/cut
2.5``, LAMMPS will look up the factory function for creating the
``PairLJCut`` class and then execute it. The return value of that
function is a ``Pair *`` pointer and the pointer will be assigned to the
location for the currently active pair style.
A DSO file with a plugin thus has to implement such a factory function
and register it with LAMMPS so that it gets added to the map of available
styles of the given category. To register a plugin with LAMMPS an
initialization function has to be present in the DSO file called
``lammpsplugin_init`` which is called with three ``void *`` arguments:
a pointer to the current LAMMPS instance, a pointer to the opened DSO
handle, and a pointer to the registration function. The registration
function takes two arguments: a pointer to a ``lammpsplugin_t`` struct
with information about the plugin and a pointer to the current LAMMPS
instance. Please see below for an example of how the registration is
done.
Members of ``lammpsplugin_t``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: auto
* - Member
- Description
* - version
- LAMMPS Version string the plugin was compiled for
* - style
- Style of the plugin (pair, bond, fix, command, etc.)
* - name
- Name of the plugin style
* - info
- String with information about the plugin
* - author
- String with the name and email of the author
* - creator.v1
- Pointer to factory function for pair, bond, angle, dihedral, improper or command styles
* - creator.v2
- Pointer to factory function for compute, fix, or region styles
* - handle
- Pointer to the open DSO file handle
Only one of the three alternate creator entries can be used at a time
and which of those is determined by the style of plugin. The
"creator.v1" element is for factory functions of supported styles
computing forces (i.e. command, pair, bond, angle, dihedral, or
improper styles) and the function takes as single argument the pointer
to the LAMMPS instance. The factory function is cast to the
``lammpsplugin_factory1`` type before assignment. The "creator.v2"
element is for factory functions creating an instance of a fix, compute,
or region style and takes three arguments: a pointer to the LAMMPS
instance, an integer with the length of the argument list and a ``char
**`` pointer to the list of arguments. The factory function pointer
needs to be cast to the ``lammpsplugin_factory2`` type before
assignment.
Pair style example
^^^^^^^^^^^^^^^^^^
As an example, a hypothetical pair style plugin "morse2" implemented in
a class ``PairMorse2`` in the files ``pair_morse2.h`` and
``pair_morse2.cpp`` with the factory function and initialization
function would look like this:
.. code-block:: C++
#include "lammpsplugin.h"
#include "version.h"
#include "pair_morse2.h"
using namespace LAMMPS_NS;
static Pair *morse2creator(LAMMPS *lmp)
{
return new PairMorse2(lmp);
}
extern "C" void lammpsplugin_init(void *lmp, void *handle, void *regfunc)
{
lammpsplugin_regfunc register_plugin = (lammpsplugin_regfunc) regfunc;
lammpsplugin_t plugin;
plugin.version = LAMMPS_VERSION;
plugin.style = "pair";
plugin.name = "morse2";
plugin.info = "Morse2 variant pair style v1.0";
plugin.author = "Axel Kohlmeyer (akohlmey@gmail.com)";
plugin.creator.v1 = (lammpsplugin_factory1 *) &morse2creator;
plugin.handle = handle;
(*register_plugin)(&plugin,lmp);
}
The factory function in this example is called ``morse2creator()``. It
receives a pointer to the LAMMPS class as only argument and thus has to
be assigned to the *creator.v1* member of the plugin struct and cast to
the ``lammpsplugin_factory1`` function pointer type. It returns a
pointer to the allocated class instance derived from the ``Pair`` class.
This function may be declared static to avoid clashes with other
plugins. The name of the derived class, ``PairMorse2``, however must be
unique inside the entire LAMMPS executable.
Fix style example
^^^^^^^^^^^^^^^^^
If the factory function would be for a fix or compute, which take three
arguments (a pointer to the LAMMPS class, the number of arguments and the
list of argument strings), then the pointer type is ``lammpsplugin_factory2``
and it must be assigned to the *creator.v2* member of the plugin struct.
Below is an example for that:
.. code-block:: C++
#include "lammpsplugin.h"
#include "version.h"
#include "fix_nve2.h"
using namespace LAMMPS_NS;
static Fix *nve2creator(LAMMPS *lmp, int argc, char **argv)
{
return new FixNVE2(lmp,argc,argv);
}
extern "C" void lammpsplugin_init(void *lmp, void *handle, void *regfunc)
{
lammpsplugin_regfunc register_plugin = (lammpsplugin_regfunc) regfunc;
lammpsplugin_t plugin;
plugin.version = LAMMPS_VERSION;
plugin.style = "fix";
plugin.name = "nve2";
plugin.info = "NVE2 variant fix style v1.0";
plugin.author = "Axel Kohlmeyer (akohlmey@gmail.com)";
plugin.creator.v2 = (lammpsplugin_factory2 *) &nve2creator;
plugin.handle = handle;
(*register_plugin)(&plugin,lmp);
}
Command style example
^^^^^^^^^^^^^^^^^^^^^
Command styles also use the first variant of factory function as
demonstrated in the following example, which also shows that the
implementation of the plugin class may be within the same source
file as the plugin interface code:
.. code-block:: C++
#include "lammpsplugin.h"
#include "comm.h"
#include "error.h"
#include "command.h"
#include "version.h"
#include <cstring>
namespace LAMMPS_NS {
class Hello : public Command {
public:
Hello(class LAMMPS *lmp) : Command(lmp) {};
void command(int, char **);
};
}
using namespace LAMMPS_NS;
void Hello::command(int argc, char **argv)
{
if (argc != 1) error->all(FLERR,"Illegal hello command");
if (comm->me == 0)
utils::logmesg(lmp,fmt::format("Hello, {}!\n",argv[0]));
}
static void hellocreator(LAMMPS *lmp)
{
return new Hello(lmp);
}
extern "C" void lammpsplugin_init(void *lmp, void *handle, void *regfunc)
{
lammpsplugin_t plugin;
lammpsplugin_regfunc register_plugin = (lammpsplugin_regfunc) regfunc;
plugin.version = LAMMPS_VERSION;
plugin.style = "command";
plugin.name = "hello";
plugin.info = "Hello world command v1.1";
plugin.author = "Axel Kohlmeyer (akohlmey@gmail.com)";
plugin.creator.v1 = (lammpsplugin_factory1 *) &hellocreator;
plugin.handle = handle;
(*register_plugin)(&plugin,lmp);
}
Additional Details
^^^^^^^^^^^^^^^^^^
The initialization function **must** be called ``lammpsplugin_init``, it
**must** have C bindings and it takes three void pointers as arguments.
The first is a pointer to the LAMMPS class that calls it and it needs to
be passed to the registration function. The second argument is a
pointer to the internal handle of the DSO file, this needs to be added
to the plugin info struct, so that the DSO can be closed and unloaded
when all its contained plugins are unloaded. The third argument is a
function pointer to the registration function and needs to be stored
in a variable of ``lammpsplugin_regfunc`` type and then called with a
pointer to the ``lammpsplugin_t`` struct and the pointer to the LAMMPS
instance as arguments to register a single plugin. There may be multiple
calls to multiple plugins in the same initialization function.
To register a plugin a struct of the ``lammpsplugin_t`` needs to be filled
with relevant info: current LAMMPS version string, kind of style, name of
style, info string, author string, pointer to factory function, and the
DSO handle. The registration function is called with a pointer to the address
of this struct and the pointer of the LAMMPS class. The registration function
will then add the factory function of the plugin style to the respective
style map under the provided name. It will also make a copy of the struct
in a list of all loaded plugins and update the reference counter for loaded
plugins from this specific DSO file.
The pair style itself (i.e. the PairMorse2 class in this example) can be
written just like any other pair style that is included in LAMMPS. For
a plugin, the use of the ``PairStyle`` macro in the section encapsulated
by ``#ifdef PAIR_CLASS`` is not needed, since the mapping of the class
name to the style name is done by the plugin registration function with
the information from the ``lammpsplugin_t`` struct. It may be included
in case the new code is intended to be later included in LAMMPS directly.

45
doc/src/Developer_unittest.rst
View File

@ -4,10 +4,10 @@ Adding tests for unit testing
This section discusses adding or expanding tests for the unit test
infrastructure included into the LAMMPS source code distribution.
Unlike example inputs, unit tests focus on testing the "local" behavior
of individual features, tend to run very fast, and should be set up to
cover as much of the added code as possible. When contributing code to
the distribution, the LAMMPS developers will appreciate if additions
to the integrated unit test facility are included.
of individual features, tend to run fast, and should be set up to cover
as much of the added code as possible. When contributing code to the
distribution, the LAMMPS developers will appreciate if additions to the
integrated unit test facility are included.
Given the complex nature of MD simulations where many operations can
only be performed when suitable "real" simulation environment has been
@ -50,6 +50,9 @@ available:
* - File name:
- Test name:
- Description:
* - ``test_argutils.cpp``
- ArgInfo
- Tests for ``ArgInfo`` class used by LAMMPS
* - ``test_fmtlib.cpp``
- FmtLib
- Tests for ``fmtlib::`` functions used by LAMMPS
@ -155,23 +158,27 @@ have the desired effect:
{
ASSERT_EQ(lmp->update->ntimestep, 0);
if (!verbose) ::testing::internal::CaptureStdout();
lmp->input->one("reset_timestep 10");
if (!verbose) ::testing::internal::GetCapturedStdout();
BEGIN_HIDE_OUTPUT();
command("reset_timestep 10");
END_HIDE_OUTPUT();
ASSERT_EQ(lmp->update->ntimestep, 10);
if (!verbose) ::testing::internal::CaptureStdout();
lmp->input->one("reset_timestep 0");
if (!verbose) ::testing::internal::GetCapturedStdout();
BEGIN_HIDE_OUTPUT();
command("reset_timestep 0");
END_HIDE_OUTPUT();
ASSERT_EQ(lmp->update->ntimestep, 0);
TEST_FAILURE(".*ERROR: Timestep must be >= 0.*", command("reset_timestep -10"););
TEST_FAILURE(".*ERROR: Illegal reset_timestep .*", command("reset_timestep"););
TEST_FAILURE(".*ERROR: Illegal reset_timestep .*", command("reset_timestep 10 10"););
TEST_FAILURE(".*ERROR: Expected integer .*", command("reset_timestep xxx"););
}
Please note the use of the (global) verbose variable to control whether
the LAMMPS command will be silent by capturing the output or not. In
the default case, verbose == false, the test output will be compact and
not mixed with LAMMPS output. However setting the verbose flag (via
setting the ``TEST_ARGS`` environment variable, ``TEST_ARGS=-v``) can be
helpful to understand why tests fail unexpectedly.
Please note the use of the ``BEGIN_HIDE_OUTPUT`` and ``END_HIDE_OUTPUT``
functions that will capture output from running LAMMPS. This is normally
discarded but by setting the verbose flag (via setting the ``TEST_ARGS``
environment variable, ``TEST_ARGS=-v``) it can be printed and used to
understand why tests fail unexpectedly.
Another complexity of these tests stems from the need to capture
situations where LAMMPS will stop with an error, i.e. handle so-called
@ -210,6 +217,12 @@ The following test programs are currently available:
* - ``test_lattice_region.cpp``
- LatticeRegion
- Tests to validate the :doc:`lattice <lattice>` and :doc:`region <region>` commands
* - ``test_groups.cpp``
- GroupTest
- Tests to validate the :doc:`group <group>` command
* - ``test_variables.cpp``
- VariableTest
- Tests to validate the :doc:`variable <variable>` command
* - ``test_kim_commands.cpp``
- KimCommands
- Tests for several commands from the :ref:`KIM package <PKG-KIM>`

99
doc/src/Developer_utils.rst
View File

@ -9,14 +9,29 @@ reading or writing to files with error checking or translation of
strings into specific types of numbers with checking for validity. This
reduces redundant implementations and encourages consistent behavior.
I/O with status check
^^^^^^^^^^^^^^^^^^^^^
I/O with status check and similar functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These are wrappers around the corresponding C library calls like
``fgets()`` or ``fread()``. They will check if there were errors
on reading or an unexpected end-of-file state was reached. In that
case, the functions will stop the calculation with an error message,
indicating the name of the problematic file, if possible.
The the first two functions are wrappers around the corresponding C
library calls ``fgets()`` or ``fread()``. They will check if there
were errors on reading or an unexpected end-of-file state was reached.
In that case, the functions will stop with an error message, indicating
the name of the problematic file, if possible unless the *error* argument
is a NULL pointer.
The :cpp:func:`fgets_trunc` function will work similar for ``fgets()``
but it will read in a whole line (i.e. until the end of line or end
of file), but store only as many characters as will fit into the buffer
including a final newline character and the terminating NULL byte.
If the line in the file is longer it will thus be truncated in the buffer.
This function is used by :cpp:func:`read_lines_from_file` to read individual
lines but make certain they follow the size constraints.
The :cpp:func:`read_lines_from_file` function will read the requested
number of lines of a maximum length into a buffer and will return 0
if successful or 1 if not. It also guarantees that all lines are
terminated with a newline character and the entire buffer with a
NULL character.
----------
@ -26,6 +41,12 @@ indicating the name of the problematic file, if possible.
.. doxygenfunction:: sfread
:project: progguide
.. doxygenfunction:: fgets_trunc
:project: progguide
.. doxygenfunction:: read_lines_from_file
:project: progguide
----------
String to number conversions with validity check
@ -71,12 +92,21 @@ and parsing files or arguments.
----------
.. doxygenfunction:: strdup
:project: progguide
.. doxygenfunction:: trim
:project: progguide
.. doxygenfunction:: trim_comment
:project: progguide
.. doxygenfunction:: has_utf8
:project: progguide
.. doxygenfunction:: utf8_subst
:project: progguide
.. doxygenfunction:: count_words(const char *text)
:project: progguide
@ -92,9 +122,15 @@ and parsing files or arguments.
.. doxygenfunction:: split_words
:project: progguide
.. doxygenfunction:: split_lines
:project: progguide
.. doxygenfunction:: strmatch
:project: progguide
.. doxygenfunction:: strfind
:project: progguide
.. doxygenfunction:: is_integer
:project: progguide
@ -149,7 +185,10 @@ Argument processing
Convenience functions
^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: logmesg
.. doxygenfunction:: logmesg(LAMMPS *lmp, const S &format, Args&&... args)
:project: progguide
.. doxygenfunction:: logmesg(LAMMPS *lmp, const std::string &mesg)
:project: progguide
.. doxygenfunction:: getsyserror
@ -286,6 +325,50 @@ This code example should produce the following output:
----------
Argument parsing classes
---------------------------
The purpose of argument parsing classes it to simplify and unify how
arguments of commands in LAMMPS are parsed and to make abstractions of
repetitive tasks.
The :cpp:class:`LAMMPS_NS::ArgInfo` class provides an abstraction
for parsing references to compute or fix styles or variables. These
would start with a "c\_", "f\_", "v\_" followed by the ID or name of
than instance and may be postfixed with one or two array indices
"[<number>]" with numbers > 0.
A typical code segment would look like this:
.. code-block:: C++
:caption: Usage example for ArgInfo class
int nvalues = 0;
for (iarg = 0; iarg < nargnew; iarg++) {
ArgInfo argi(arg[iarg]);
which[nvalues] = argi.get_type();
argindex[nvalues] = argi.get_index1();
ids[nvalues] = argi.copy_name();
if ((which[nvalues] == ArgInfo::UNKNOWN)
|| (which[nvalues] == ArgInfo::NONE)
|| (argi.get_dim() > 1))
error->all(FLERR,"Illegal compute XXX command");
nvalues++;
}
----------
.. doxygenclass:: LAMMPS_NS::ArgInfo
:project: progguide
:members:
----------
File reader classes
-------------------

1
doc/src/Howto_bioFF.rst
View File

@ -91,6 +91,7 @@ documentation for the formula it computes.
* :doc:`bond_style <bond_harmonic>` harmonic
* :doc:`bond_style <bond_morse>` morse
* :doc:`angle_style <angle_cosine_squared>` cosine/squared
* :doc:`angle_style <angle_harmonic>` harmonic
* :doc:`angle_style <angle_cosine>` cosine
* :doc:`angle_style <angle_cosine_periodic>` cosine/periodic

10
doc/src/Howto_cmake.rst
View File

@ -296,6 +296,8 @@ Some common CMake variables
- Description
* - ``CMAKE_INSTALL_PREFIX``
- root directory of install location for ``make install`` (default: ``$HOME/.local``)
* - ``LAMMPS_INSTALL_RPATH``
- set or remove runtime path setting from binaries for ``make install`` (default: ``off``)
* - ``CMAKE_BUILD_TYPE``
- controls compilation options:
one of ``RelWithDebInfo`` (default), ``Release``, ``Debug``, ``MinSizeRel``
@ -409,10 +411,10 @@ interface (``ccmake`` or ``cmake-gui``).
.. note::
Using a preset to select a compiler package (``clang.cmake``,
``gcc.cmake``, or ``intel.cmake``) are an exception to the option
of updating the configuration incrementally, as they will trigger
a reset of cached internal CMake settings and thus reset them to
their default values.
``gcc.cmake``, ``intel.cmake``, ``oneapi.cmake``, or ``pgi.cmake``)
are an exception to the mechanism of updating the configuration incrementally,
as they will trigger a reset of cached internal CMake settings and thus
reset settings to their default values.
Compilation and build targets
-----------------------------

5
doc/src/Howto_drude.rst
View File

@ -42,10 +42,11 @@ screening. It may be necessary to use the *extra/special/per/atom*
keyword of the :doc:`read_data <read_data>` command. If using :doc:`fix shake <fix_shake>`, make sure no Drude particle is in this fix
group.
There are two ways to thermostat the Drude particles at a low
There are three ways to thermostat the Drude particles at a low
temperature: use either :doc:`fix langevin/drude <fix_langevin_drude>`
for a Langevin thermostat, or :doc:`fix drude/transform/\* <fix_drude_transform>` for a Nose-Hoover
thermostat. The former requires use of the command :doc:`comm_modify vel yes <comm_modify>`. The latter requires two separate integration
thermostat, or :doc:`fix tgnvt/drude <fix_tgnh_drude>` for a temperature-grouped Nose-Hoover thermostat.
The first and third require use of the command :doc:`comm_modify vel yes <comm_modify>`. The second requires two separate integration
fixes like *nvt* or *npt*\ . The correct temperatures of the reduced
degrees of freedom can be calculated using the :doc:`compute temp/drude <compute_temp_drude>`. This requires also to use the
command *comm_modify vel yes*.

48
doc/src/Howto_drude2.rst
View File

@ -9,6 +9,8 @@ USER-DRUDE package activated. Then, the data file and input scripts
have to be modified to include the Drude dipoles and how to handle
them.
Example input scripts available: examples/USER/drude
----------
**Overview of Drude induced dipoles**
@ -221,6 +223,14 @@ modification of forces but no position/velocity updates), the fix
fix NVE all nve
To avoid the flying ice cube artifact, where the atoms progressively freeze and the
center of mass of the whole system drifts faster and faster, the *fix momentum*
can be used. For instance:
.. code-block:: LAMMPS
fix MOMENTUM all momentum 100 linear 1 1 1
Finally, do not forget to update the atom type elements if you use
them in a *dump_modify ... element ...* command, by adding the element
type of the DPs. Here for instance
@ -376,14 +386,7 @@ For our phenol example, the groups would be defined as
Note that with the fixes *drude/transform*\ , it is not required to
specify *comm_modify vel yes* because the fixes do it anyway (several
times and for the forces also). To avoid the flying ice cube artifact
:ref:`(Lamoureux and Roux) <Lamoureux2>`, where the atoms progressively freeze and the
center of mass of the whole system drifts faster and faster, the *fix
momentum* can be used. For instance:
.. code-block:: LAMMPS
fix MOMENTUM all momentum 100 linear 1 1 1
times and for the forces also).
It is a bit more tricky to run a NPT simulation with Nose-Hoover
barostat and thermostat. First, the volume should be integrated only
@ -404,6 +407,31 @@ instructions for thermostatting and barostatting will look like
fix NVT DRUDES nvt temp 1. 1. 20
fix INVERSE all drude/transform/inverse
Another option for thermalizing the Drude model is to use the
temperature-grouped Nose-Hoover (TGNH) thermostat proposed by :ref:`(Son) <TGNH-SON>`.
This is implemented as :doc:`fix tgnvt/drude <fix_tgnh_drude>` and :doc:`fix tgnpt/drude <fix_tgnh_drude>`.
It separates the kinetic energy into three contributions:
the molecular center of mass (COM) motion, the motion of atoms or atom-Drude pairs relative to molecular COMs,
and the relative motion of atom-Drude pairs.
An independent Nose-Hoover chain is applied to each type of motion.
When TGNH is used, the temperatures of molecular, atomic and Drude motion can be printed out with :doc:`thermo_style` command.
NVT simulation with TGNH thermostat
.. code-block:: LAMMPS
comm_modify vel yes
fix TGNVT all tgnvt/drude temp 300. 300. 100 1. 20
thermo_style custom f_TGNVT[1] f_TGNVT[2] f_TGNVT[3]
NPT simulation with TGNH thermostat
.. code-block:: LAMMPS
comm_modify vel yes
fix TGNPT all tgnpt/drude temp 300. 300. 100 1. 20 iso 1. 1. 500
thermo_style custom f_TGNPT[1] f_TGNPT[2] f_TGNPT[3]
----------
**Rigid bodies**
@ -480,3 +508,7 @@ NPT ensemble using Nose-Hoover thermostat:
**(SWM4-NDP)** Lamoureux, Harder, Vorobyov, Roux, MacKerell, Chem Phys
Let, 418, 245-249 (2006)
.. _TGNH-Son:
**(Son)** Son, McDaniel, Cui and Yethiraj, J Phys Chem Lett, 10, 7523 (2019).

10
doc/src/Howto_granular.rst
View File

@ -18,12 +18,13 @@ This compute
calculates rotational kinetic energy which can be :doc:`output with thermodynamic info <Howto_output>`.
Use one of these 3 pair potentials, which compute forces and torques
Use one of these 4 pair potentials, which compute forces and torques
between interacting pairs of particles:
* :doc:`pair_style <pair_style>` gran/history
* :doc:`pair_style <pair_style>` gran/no_history
* :doc:`pair_style <pair_style>` gran/hertzian
* :doc:`pair_style gran/history <pair_gran>`
* :doc:`pair_style gran/no_history <pair_gran>`
* :doc:`pair_style gran/hertzian <pair_gran>`
* :doc:`pair_style granular <pair_granular>`
These commands implement fix options specific to granular systems:
@ -31,6 +32,7 @@ These commands implement fix options specific to granular systems:
* :doc:`fix pour <fix_pour>`
* :doc:`fix viscous <fix_viscous>`
* :doc:`fix wall/gran <fix_wall_gran>`
* :doc:`fix wall/gran/region <fix_wall_gran_region>`
The fix style *freeze* zeroes both the force and torque of frozen
atoms, and should be used for granular system instead of the fix style

4
doc/src/Howto_pylammps.rst
View File

@ -9,8 +9,8 @@ Overview
``PyLammps`` is a Python wrapper class for LAMMPS which can be created
on its own or use an existing lammps Python object. It creates a simpler,
more "pythonic" interface to common LAMMPS functionality, in contrast to
the ``lammps.py`` wrapper for the C-style LAMMPS library interface which
is written using `Python ctypes <ctypes_>`_. The ``lammps.py`` wrapper
the ``lammps`` wrapper for the C-style LAMMPS library interface which
is written using `Python ctypes <ctypes_>`_. The ``lammps`` wrapper
is discussed on the :doc:`Python_head` doc page.
Unlike the flat ``ctypes`` interface, PyLammps exposes a discoverable

4
doc/src/Howto_spins.rst
View File

@ -21,8 +21,8 @@ orientations and their associated inter-atomic distances.
The command :doc:`fix precession/spin <fix_precession_spin>` allows to
apply a constant magnetic torque on all the spins in the system. This
torque can be an external magnetic field (Zeeman interaction), or an
uniaxial magnetic anisotropy.
torque can be an external magnetic field (Zeeman interaction), and an
uniaxial or cubic magnetic anisotropy.
A Langevin thermostat can be applied to those magnetic spins using
:doc:`fix langevin/spin <fix_langevin_spin>`. Typically, this thermostat

64
doc/src/Install_git.rst
View File

@ -86,33 +86,59 @@ check out any other desired branch) first.
Once you have updated your local files with a ``git pull`` (or ``git
checkout``), you still need to re-build LAMMPS if any source files have
changed. To do this, you should cd to the src directory and type:
changed. How to do this depends on the build system you are using.
.. code-block:: bash
.. tabs::
.. tab:: CMake build
Change to your build folder and type:
.. code-block:: bash
cmake . --build
CMake should auto-detect whether it needs to re-run the CMake
configuration step and otherwise redo the build for all files
that have been changed or files that depend on changed files.
In case some build options have been changed or renamed, you
may have to update those by running:
.. code-block:: bash
cmake .
and then rebuild.
.. tab:: Traditional make
Switch to the src directory and type:
.. code-block:: bash
$ make purge # remove any deprecated src files
$ make package-update # sync package files with src files
$ make foo # re-build for your machine (mpi, serial, etc)
just as described on the :doc:`Apply patch <Install_patch>` page,
after a patch has been installed.
Just as described on the :doc:`Apply patch <Install_patch>` page,
after a patch has been installed.
.. warning::
.. warning::
If you wish to edit/change a src file that is from a
package, you should edit the version of the file inside the package
sub-directory with src, then re-install the package. The version in
the source directory is merely a copy and will be wiped out if you type "make
package-update".
If you wish to edit/change a src file that is from a package,
you should edit the version of the file inside the package
sub-directory with src, then re-install the package. The
version in the source directory is merely a copy and will be
wiped out if you type "make package-update".
.. warning::
.. admonition:: Git protocols
:class: note
The GitHub servers support both the "git://" and
"https://" access protocols for anonymous read-only access. If you
have a correspondingly configured GitHub account, you may also use
SSH access with the URL "git@github.com:lammps/lammps.git".
The servers at github.com support the "git://" and "https://" access
protocols for anonymous, read-only access. If you have a suitably
configured GitHub account, you may also use SSH protocol with the
URL "git@github.com:lammps/lammps.git".
The LAMMPS GitHub project is managed by Christoph Junghans (LANL,
junghans at lanl.gov), Axel Kohlmeyer (Temple U, akohlmey at
gmail.com) and Richard Berger (Temple U, richard.berger at
temple.edu).
The LAMMPS GitHub project is currently managed by Axel Kohlmeyer
(Temple U, akohlmey at gmail.com) and Richard Berger (Temple U,
richard.berger at temple.edu).

60
doc/src/Install_patch.rst
View File

@ -43,24 +43,54 @@ up to date.
* A list of updated files print out to the screen. The -b switch
creates backup files of your originals (e.g. src/force.cpp.orig), so
you can manually undo the patch if something goes wrong.
* Type the following from the src directory, to enforce consistency
between the src and package directories. This is OK to do even if you
don't use one or more packages. If you are applying several patches
successively, you only need to type this once at the end. The purge
command removes deprecated src files if any were removed by the patch
from package sub-directories.
* Once you have updated your local files you need to re-build LAMMPS.
If you are applying several patches successively, you only need to
do the rebuild once at the end. How to do it depends on the build
system you are using.
.. tabs::
.. tab:: CMake build
Change to your build folder and type:
.. code-block:: bash
$ make purge
$ make package-update
cmake . --build
* Re-build LAMMPS via the "make" command.
CMake should auto-detect whether it needs to re-run the CMake
configuration step and otherwise redo the build for all files
that have been changed or files that depend on changed files.
In case some build options have been changed or renamed, you
may have to update those by running:
.. warning::
.. code-block:: bash
If you wish to edit/change a source file that is part of a package,
you should edit the version of the file inside the package folder in
src, and then re-install or update the package. The version in the
src directory is merely a copy and will be wiped out when you type
"make package-update".
cmake .
and then rebuild.
.. tab:: Traditional make
Switch to the src directory and type:
.. code-block:: bash
$ make purge # remove any deprecated src files
$ make package-update # sync package files with src files
$ make foo # re-build for your machine (mpi, serial, etc)
to enforce consistency of the source between the src folder
and package directories. This is OK to do even if you don't
use any packages. The "make purge" command removes any deprecated
src files if they were removed by the patch from a package
sub-directory.
.. warning::
If you wish to edit/change a src file that is from a package,
you should edit the version of the file inside the package
sub-directory with src, then re-install the package. The
version in the source directory is merely a copy and will be
wiped out if you type "make package-update".

17
doc/src/Install_tarball.rst
View File

@ -33,22 +33,19 @@ in its name, e.g. lammps-23Jun18.
----------
You can also download a zip file via the "Clone or download" button on
the `LAMMPS GitHub site <git_>`_. The file name will be lammps-master.zip
which can be unzipped with the following command, to create
a lammps-master dir:
You can also download a compressed tar or zip archives from the
"Assets" sections of the `LAMMPS GitHub releases site <git_>`_.
The file name will be lammps-<version>.zip which can be unzipped
with the following command, to create a lammps-<version> dir:
.. code-block:: bash
$ unzip lammps*.zip
This version is the most up-to-date LAMMPS development version. It
will have the date of the most recent patch release (see the file
src/version.h). But it will also include any new bug-fixes or
features added since the last patch release. They will be included in
the next patch release tarball.
This version corresponds to the selected LAMMPS patch or stable
release.
.. _git: https://github.com/lammps/lammps
.. _git: https://github.com/lammps/lammps/releases
----------

19
doc/src/Intro_citing.rst
View File

@ -38,17 +38,18 @@ In addition there are DOIs for individual stable releases. Currently there are:
Home page
^^^^^^^^^
The LAMMPS website at `https://lammps.sandia.gov/ <https://lammps.sandia.gov>`_ is the canonical
location for information about LAMMPS and more detailed lists of publications
using LAMMPS and contributing features.
The LAMMPS website at `https://lammps.sandia.gov/
<https://lammps.sandia.gov>`_ is the canonical location for information
about LAMMPS and its features.
Citing contributions
^^^^^^^^^^^^^^^^^^^^
LAMMPS has many features and uses previously published methods and
algorithms or novel features. It also includes potential parameter
filed for specific models. You can look up relevant publications either
in the LAMMPS output to the screen, the ``log.cite`` file (which is
populated with references to relevant papers through embedding them into
the source code) and in the documentation of the :doc:`corresponding commands
LAMMPS has many features and that use either previously published
methods and algorithms or novel features. It also includes potential
parameter filed for specific models. Where available, a reminder about
references for optional features used in a specific run is printed to
the screen and log file. Style and output location can be selected with
the :ref:`-cite command-line switch <cite>`. Additional references are
given in the documentation of the :doc:`corresponding commands
<Commands_all>` or in the :doc:`Howto tutorials <Howto>`.

2
doc/src/Intro_features.rst
View File

@ -85,7 +85,7 @@ commands)
* water potentials: TIP3P, TIP4P, SPC
* implicit solvent potentials: hydrodynamic lubrication, Debye
* force-field compatibility with common CHARMM, AMBER, DREIDING, OPLS, GROMACS, COMPASS options
* access to the `OpenKIM Repository <http://openkim.org>`_ of potentials via :doc:`kim_init, kim_interactions, and kim_query <kim_commands>` commands
* access to the `OpenKIM Repository <http://openkim.org>`_ of potentials via :doc:`kim command <kim_commands>`
* hybrid potentials: multiple pair, bond, angle, dihedral, improper potentials can be used in one simulation
* overlaid potentials: superposition of multiple pair potentials

BIN
doc/src/JPG/WF_LJ.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 292 KiB

BIN
doc/src/JPG/lammps-classes.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 254 KiB

After

Width:  |  Height:  |  Size: 286 KiB

6
doc/src/Library_config.rst
View File

@ -14,6 +14,7 @@ This section documents the following functions:
- :cpp:func:`lammps_config_has_package`
- :cpp:func:`lammps_config_package_count`
- :cpp:func:`lammps_config_package_name`
- :cpp:func:`lammps_config_accelerator`
- :cpp:func:`lammps_has_style`
- :cpp:func:`lammps_style_count`
- :cpp:func:`lammps_style_name`
@ -126,6 +127,11 @@ approach.
-----------------------
.. doxygenfunction:: lammps_config_accelerator
:project: progguide
-----------------------
.. doxygenfunction:: lammps_has_style
:project: progguide

2
doc/src/Library_scatter.rst
View File

@ -76,7 +76,7 @@ It documents the following functions:
-----------------------
.. doxygenfunction:: lammps_create_atoms(void *handle, int n, int *id, int *type, double *x, double *v, int *image, int bexpand)
.. doxygenfunction:: lammps_create_atoms(void *handle, int n, const int *id, const int *type, const double *x, const double *v, const int *image, int bexpand)
:project: progguide

17
doc/src/Modify_command.rst
View File

@ -1,14 +1,15 @@
Input script command style
==========================
New commands can be added to LAMMPS input scripts by adding new
classes that have a "command" method. For example, the create_atoms,
read_data, velocity, and run commands are all implemented in this
fashion. When such a command is encountered in the LAMMPS input
script, LAMMPS simply creates a class with the corresponding name,
invokes the "command" method of the class, and passes it the arguments
from the input script. The command method can perform whatever
operations it wishes on LAMMPS data structures.
New commands can be added to LAMMPS input scripts by adding new classes
that are derived from the Command class and thus must have a "command"
method. For example, the create_atoms, read_data, velocity, and run
commands are all implemented in this fashion. When such a command is
encountered in the LAMMPS input script, LAMMPS simply creates a class
instance with the corresponding name, invokes the "command" method of
the class, and passes it the arguments from the input script. The
command method can perform whatever operations it wishes on LAMMPS data
structures.
The single method your new class must define is as follows:

26
doc/src/Modify_contribute.rst
View File

@ -206,16 +206,22 @@ packages in the src directory for examples. If you are uncertain, please ask.
algorithm/science behind the feature itself, or its initial usage, or
its implementation in LAMMPS), you can add the citation to the \*.cpp
source file. See src/USER-EFF/atom_vec_electron.cpp for an example.
A LaTeX citation is stored in a variable at the top of the file and a
single line of code that references the variable is added to the
constructor of the class. Whenever a user invokes your feature from
their input script, this will cause LAMMPS to output the citation to a
log.cite file and prompt the user to examine the file. Note that you
should only use this for a paper you or your group authored.
E.g. adding a cite in the code for a paper by Nose and Hoover if you
write a fix that implements their integrator is not the intended
usage. That kind of citation should just be in the doc page you
provide.
A LaTeX citation is stored in a variable at the top of the file and
a single line of code registering this variable is added to the
constructor of the class. If there is additional functionality (which
may have been added later) described in a different publication,
additional citation descriptions may be added for as long as they
are only registered when the corresponding keyword activating this
functionality is used. With these options it is possible to have
LAMMPS output a specific citation reminder whenever a user invokes
your feature from their input script. Note that you should only use
this for the most relevant paper for a feature and a publication that
you or your group authored. E.g. adding a citation in the code for
a paper by Nose and Hoover if you write a fix that implements their
integrator is not the intended usage. That kind of citation should
just be included in the documentation page you provide describing
your contribution. If you are not sure what the best option would
be, please contact the LAMMPS developers for advice.
Finally, as a general rule-of-thumb, the more clear and
self-explanatory you make your documentation and README files, and the

120
doc/src/Packages_details.rst
View File

@ -50,6 +50,7 @@ page gives those details.
* :ref:`MSCG <PKG-MSCG>`
* :ref:`OPT <PKG-OPT>`
* :ref:`PERI <PKG-PERI>`
* :ref:`PLUGIN <PKG-PLUGIN>`
* :ref:`POEMS <PKG-POEMS>`
* :ref:`PYTHON <PKG-PYTHON>`
* :ref:`QEQ <PKG-QEQ>`
@ -89,6 +90,7 @@ page gives those details.
* :ref:`USER-MOLFILE <PKG-USER-MOLFILE>`
* :ref:`USER-NETCDF <PKG-USER-NETCDF>`
* :ref:`USER-OMP <PKG-USER-OMP>`
* :ref:`USER-PACE <PKG-USER-PACE>`
* :ref:`USER-PHONON <PKG-USER-PHONON>`
* :ref:`USER-PLUMED <PKG-USER-PLUMED>`
* :ref:`USER-PTM <PKG-USER-PTM>`
@ -367,17 +369,19 @@ KIM package
**Contents:**
This package contains a set of commands that serve as a wrapper on the
This package contains a command with a set of sub-commands that serve as a
wrapper on the
`Open Knowledgebase of Interatomic Models (OpenKIM) <https://openkim.org>`_
repository of interatomic models (IMs) enabling compatible ones to be used in
LAMMPS simulations.
This includes :doc:`kim_init <kim_commands>`, and
:doc:`kim_interactions <kim_commands>` commands to select, initialize and
instantiate the IM, a :doc:`kim_query <kim_commands>` command to perform web
This includes :doc:`kim init <kim_commands>`, and
:doc:`kim interactions <kim_commands>` commands to select, initialize and
instantiate the IM, a :doc:`kim query <kim_commands>` command to perform web
queries for material property predictions of OpenKIM IMs, a
:doc:`kim_param <kim_commands>` command to access KIM Model Parameters from
LAMMPS, and a :doc:`kim_property <kim_commands>` command to write material
:doc:`kim param <kim_commands>` command to access KIM Model Parameters from
LAMMPS, and a :doc:`kim property <kim_commands>` command to write material
properties computed in LAMMPS to standard KIM property instance format.
Support for KIM IMs that conform to the
@ -386,8 +390,8 @@ is provided by the :doc:`pair_style kim <pair_kim>` command.
.. note::
The command *pair_style kim* is called by *kim_interactions* and
is not recommended to be directly used in input scripts.
The command *pair_style kim* is called by *kim interactions* and is not
recommended to be directly used in input scripts.
To use this package you must have the KIM API library available on your
system. The KIM API is available for download on the
@ -404,7 +408,7 @@ and is funded by the `National Science Foundation <https://www.nsf.gov/>`_.
API and the *pair_style kim* command. Yaser Afshar (U Minnesota),
Axel Kohlmeyer (Temple U), Ellad Tadmor (U Minnesota), and
Daniel Karls (U Minnesota) contributed to the
:doc:`kim_commands <kim_commands>` interface in close collaboration with
:doc:`kim command <kim_commands>` interface in close collaboration with
Ryan Elliott.
**Install:**
@ -414,7 +418,7 @@ This package has :ref:`specific installation instructions <kim>` on the
**Supporting info:**
* :doc:`kim_commands <kim_commands>`
* :doc:`kim command <kim_commands>`
* :doc:`pair_style kim <pair_kim>`
* src/KIM: filenames -> commands
* src/KIM/README
@ -582,7 +586,7 @@ MC package
Several fixes and a pair style that have Monte Carlo (MC) or MC-like
attributes. These include fixes for creating, breaking, and swapping
bonds, for performing atomic swaps, and performing grand-canonical MC
(GCMC) in conjunction with dynamics.
(GCMC) or similar processes in conjunction with dynamics.
**Supporting info:**
@ -590,8 +594,12 @@ bonds, for performing atomic swaps, and performing grand-canonical MC
* :doc:`fix atom/swap <fix_atom_swap>`
* :doc:`fix bond/break <fix_bond_break>`
* :doc:`fix bond/create <fix_bond_create>`
* :doc:`fix bond/create/angle <fix_bond_create>`
* :doc:`fix bond/swap <fix_bond_swap>`
* :doc:`fix charge/regulation <fix_charge_regulation>`
* :doc:`fix gcmc <fix_gcmc>`
* :doc:`fix tfmc <fix_tfmc>`
* :doc:`fix widom <fix_widom>`
* :doc:`pair_style dsmc <pair_dsmc>`
* https://lammps.sandia.gov/movies.html#gcmc
@ -662,19 +670,31 @@ MLIAP package
**Contents:**
A general interface for machine-learning interatomic potentials.
A general interface for machine-learning interatomic potentials, including PyTorch.
**Install:**
To use this package, also the :ref:`SNAP package <PKG-SNAP>` needs to be installed.
To use this package, also the :ref:`SNAP package <PKG-SNAP>` package needs
to be installed. To make the *mliappy* model available, also the
:ref:`PYTHON package <PKG-PYTHON>` package needs to be installed, the version
of Python must be 3.6 or later, and the `cython <https://cython.org/>`_ software
must be installed.
**Author:** Aidan Thompson (Sandia).
**Author:** Aidan Thompson (Sandia), Nicholas Lubbers (LANL).
**Supporting info:**
* src/MLIAP: filenames -> commands
* src/MLIAP/README
* :doc:`pair_style mliap <pair_mliap>`
* examples/mliap
* :doc:`compute_style mliap <compute_mliap>`
* examples/mliap (see README)
When built with the *mliappy* model this package includes an extension for
coupling with Python models, including PyTorch. In this case, the Python
interpreter linked to LAMMPS will need the ``cython`` and ``numpy`` modules
installed. The provided examples build models with PyTorch, which would
therefore also needs to be installed to run those examples.
----------
@ -829,6 +849,28 @@ Foster (UTSA).
----------
.. _PKG-PLUGIN:
PLUGIN package
--------------
**Contents:**
A :doc:`plugin <plugin>` command that can load and unload several
kind of styles in LAMMPS from shared object files at runtime without
having to recompile and relink LAMMPS.
**Authors:** Axel Kohlmeyer (Temple U)
**Supporting info:**
* src/PLUGIN: filenames -> commands
* :doc:`plugin command <plugin>`
* :doc:`Information on writing plugins <Developer_plugins>`
* examples/plugin
----------
.. _PKG-POEMS:
POEMS package
@ -1312,6 +1354,46 @@ This package has :ref:`specific installation instructions <user-colvars>` on the
----------
.. _PKG-USER-PACE:
USER-PACE package
-------------------
**Contents:**
A pair style for the Atomic Cluster Expansion potential (ACE).
ACE is a methodology for deriving a highly accurate classical potential
fit to a large archive of quantum mechanical (DFT) data. The USER-PACE
package provides an efficient implementation for running simulations
with ACE potentials.
**Authors:**
This package was written by Yury Lysogorskiy^1,
Cas van der Oord^2, Anton Bochkarev^1,
Sarath Menon^1, Matteo Rinaldi^1, Thomas Hammerschmidt^1, Matous Mrovec^1,
Aidan Thompson^3, Gabor Csanyi^2, Christoph Ortner^4, Ralf Drautz^1.
^1: Ruhr-University Bochum, Bochum, Germany
^2: University of Cambridge, Cambridge, United Kingdom
^3: Sandia National Laboratories, Albuquerque, New Mexico, USA
^4: University of British Columbia, Vancouver, BC, Canada
**Install:**
This package has :ref:`specific installation instructions <user-pace>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
* src/USER-PACE: filenames -> commands
* :doc:`pair_style pace <pair_pace>`
* examples/USER/pace
----------
.. _PKG-USER-PLUMED:
USER-PLUMED package
@ -1418,8 +1500,8 @@ oscillators as a model of polarization. See the :doc:`Howto drude <Howto_drude>
for an overview of how to use the package. There are auxiliary tools
for using this package in tools/drude.
**Authors:** Alain Dequidt (U Blaise Pascal Clermont-Ferrand), Julien
Devemy (CNRS), and Agilio Padua (U Blaise Pascal).
**Authors:** Alain Dequidt (U Clermont Auvergne), Julien
Devemy (CNRS), and Agilio Padua (ENS de Lyon).
**Supporting info:**
@ -1486,7 +1568,7 @@ methods for performing FEP simulations by using a :doc:`fix adapt/fep <fix_adapt
which have a "soft" in their style name. There are auxiliary tools
for using this package in tools/fep; see its README file.
**Author:** Agilio Padua (Universite Blaise Pascal Clermont-Ferrand)
**Author:** Agilio Padua (ENS de Lyon)
**Supporting info:**
@ -2442,6 +2524,6 @@ which discuss the `QuickFF <quickff_>`_ methodology.
* :doc:`bond_style mm3 <bond_mm3>`
* :doc:`improper_style distharm <improper_distharm>`
* :doc:`improper_style sqdistharm <improper_sqdistharm>`
* :doc:`pair_style mm3/switch3/coulgauss/long <pair_mm3_switch3_coulgauss_long>`
* :doc:`pair_style mm3/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>`
* :doc:`pair_style lj/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>`
* examples/USER/yaff

2
doc/src/Packages_standard.rst
View File

@ -71,6 +71,8 @@ package:
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`PERI <PKG-PERI>` | Peridynamics models | :doc:`pair_style peri <pair_peri>` | peri | no |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`PLUGIN <PKG-PLUGIN>` | Plugin loader command | :doc:`plugin <plugin>` | plugins | no |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`POEMS <PKG-POEMS>` | coupled rigid body motion | :doc:`fix poems <fix_poems>` | rigid | int |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`PYTHON <PKG-PYTHON>` | embed Python code in an input script | :doc:`python <python>` | python | sys |

2
doc/src/Packages_user.rst
View File

@ -81,6 +81,8 @@ package:
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-OMP <PKG-USER-OMP>` | OpenMP-enabled styles | :doc:`Speed omp <Speed_omp>` | `Benchmarks <https://lammps.sandia.gov/bench.html>`_ | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-PACE <PKG-USER-PACE>` | Fast implementation of Atomic Cluster Expansion (ACE) potential | :doc:`pair pace <pair_pace>` | USER/pace | ext |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-PHONON <PKG-USER-PHONON>` | phonon dynamical matrix | :doc:`fix phonon <fix_phonon>` | USER/phonon | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-PLUMED <PKG-USER-PLUMED>` | :ref:`PLUMED <PLUMED>` free energy library | :doc:`fix plumed <fix_plumed>` | USER/plumed | ext |

2
doc/src/Python_atoms.rst
View File

@ -50,7 +50,7 @@ against invalid accesses.
**Numpy Methods**:
* :py:meth:`numpy.extract_atom() <lammps.numpy_wrapper.extract_atom()>`: extract a per-atom quantity as numpy array
* :py:meth:`numpy.extract_atom() <lammps.numpy_wrapper.numpy_wrapper.extract_atom()>`: extract a per-atom quantity as numpy array
.. tab:: PyLammps/IPyLammps API

4
doc/src/Python_config.rst
View File

@ -39,7 +39,9 @@ about compile time settings and included packages and styles.
* :py:attr:`lammps.has_jpeg_support <lammps.lammps.has_jpeg_support>`
* :py:attr:`lammps.has_ffmpeg_support <lammps.lammps.has_ffmpeg_support>`
* :py:attr:`lammps.installed_packages <lammps.lammps.installed_pages>`
* :py:attr:`lammps.installed_packages <lammps.lammps.installed_packages>`
* :py:meth:`lammps.get_accelerator_config <lammps.lammps.accelerator_config>`
* :py:meth:`lammps.has_style() <lammps.lammps.has_style()>`
* :py:meth:`lammps.available_styles() <lammps.lammps.available_styles()>`

2
doc/src/Python_ext.rst
View File

@ -9,7 +9,7 @@ This means you can extend the Python wrapper by following these steps:
* Add a new interface function to ``src/library.cpp`` and
``src/library.h``.
* Rebuild LAMMPS as a shared library.
* Add a wrapper method to ``python/lammps.py`` for this interface
* Add a wrapper method to ``python/lammps/core.py`` for this interface
function.
* Define the corresponding ``argtypes`` list and ``restype``
in the ``lammps.__init__()`` function.

11
doc/src/Python_formats.rst Normal file
View File

@ -0,0 +1,11 @@
Output Readers
==============
.. py:module:: lammps.formats
The Python package contains the :py:mod:`lammps.formats` module, which
provides classes to post-process some of the output files generated by LAMMPS.
.. automodule:: lammps.formats
:members:
:noindex:

1
doc/src/Python_head.rst
View File

@ -13,6 +13,7 @@ together.
Python_module
Python_ext
Python_call
Python_formats
Python_examples
Python_error
Python_trouble

160
doc/src/Python_install.rst
View File

@ -8,9 +8,9 @@ module. Because of the dynamic loading, it is required that LAMMPS is
compiled in :ref:`"shared" mode <exe>`. It is also recommended to
compile LAMMPS with :ref:`C++ exceptions <exceptions>` enabled.
Two files are necessary for Python to be able to invoke LAMMPS code:
Two components are necessary for Python to be able to invoke LAMMPS code:
* The LAMMPS Python Module (``lammps.py``) from the ``python`` folder
* The LAMMPS Python Package (``lammps``) from the ``python`` folder
* The LAMMPS Shared Library (``liblammps.so``, ``liblammps.dylib`` or
``liblammps.dll``) from the folder where you compiled LAMMPS.
@ -25,10 +25,10 @@ Installing the LAMMPS Python Module and Shared Library
======================================================
Making LAMMPS usable within Python and vice versa requires putting the
LAMMPS Python module file (``lammps.py``) into a location where the
LAMMPS Python package (``lammps``) into a location where the
Python interpreter can find it and installing the LAMMPS shared library
into a folder that the dynamic loader searches or into the same folder
where the ``lammps.py`` file is. There are multiple ways to achieve
into a folder that the dynamic loader searches or inside of the installed
``lammps`` package folder. There are multiple ways to achieve
this.
#. Do a full LAMMPS installation of libraries, executables, selected
@ -36,13 +36,13 @@ this.
available via CMake), which can also be either system-wide or into
user specific folders.
#. Install both files into a Python ``site-packages`` folder, either
#. Install both components into a Python ``site-packages`` folder, either
system-wide or in the corresponding user-specific folder. This way no
additional environment variables need to be set, but the shared
library is otherwise not accessible.
#. Do an installation into a virtual environment. This can either be
an installation of the python module only or a full installation.
#. Do an installation into a virtual environment. This can either be an
installation of the Python package only or a full installation of LAMMPS.
#. Leave the files where they are in the source/development tree and
adjust some environment variables.
@ -69,7 +69,7 @@ this.
cd build
# configure LAMMPS compilation
cmake -C cmake/presets/minimal.cmake -D BUILD_SHARED_LIBS=on \
cmake -C ../cmake/presets/minimal.cmake -D BUILD_SHARED_LIBS=on \
-D LAMMPS_EXCEPTIONS=on -D PKG_PYTHON=on ../cmake
# compile LAMMPS
@ -81,40 +81,42 @@ this.
This leads to an installation to the following locations:
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===========================================================+=============================================================+
| LAMMPS Python Module | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/`` (32bit) | |
| | * ``$HOME/.local/lib64/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+========================+=================================================================+=============================================================+
| LAMMPS Python package | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/`` (32bit) | Set shared loader environment variable to this path |
| | * ``$HOME/.local/lib64/`` (64bit) | (see below for more info on this) |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``$HOME/.local/bin/`` | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$HOME/.local/share/lammps/potentials/`` | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
For a system-wide installation you need to set
``CMAKE_INSTALL_PREFIX`` to a system folder like ``/usr`` (or
``/usr/local``). The installation step (**not** the
``/usr/local``); the default is ``${HOME}/.local``. The
installation step for a system folder installation (**not** the
configuration/compilation) needs to be done with superuser
privilege, e.g. by using ``sudo cmake --install .``. The
installation folders will then by changed to:
installation folders will then be changed to (assuming ``/usr`` as
prefix):
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===================================================+=============================================================+
| LAMMPS Python Module | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
+========================+=========================================================+=============================================================+
| LAMMPS Python package | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``/usr/lib/`` (32bit) | |
| | * ``/usr/lib64/`` (64bit) | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``/usr/bin/`` | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``/usr/share/lammps/potentials/`` | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
To be able to use the "user" installation you have to ensure that
the folder containing the LAMMPS shared library is either included
@ -146,7 +148,7 @@ this.
necessary due to files installed in system folders that are loaded
automatically when a login shell is started.
.. tab:: Python module only
.. tab:: Python package only
Compile LAMMPS with either :doc:`CMake <Build_cmake>` or the
:doc:`traditional make <Build_make>` procedure in :ref:`shared
@ -157,37 +159,37 @@ this.
make install-python
This will try to install (only) the shared library and the python
module into a system folder and if that fails (due to missing
This will try to install (only) the shared library and the Python
package into a system folder and if that fails (due to missing
write permissions) will instead do the installation to a user
folder under ``$HOME/.local``. For a system-wide installation you
would have to gain superuser privilege, e.g. though ``sudo``
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===========================================================+=============================================================+
| LAMMPS Python Module | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+========================+=================================================================+=============================================================+
| LAMMPS Python package | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
For a system-wide installation those folders would then become.
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===================================================+=============================================================+
| LAMMPS Python Module | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
+========================+=========================================================+=============================================================+
| LAMMPS Python package | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
No environment variables need to be set for those, as those
folders are searched by default by Python or the LAMMPS Python
module.
package.
For the traditional make process you can override the python
version to version x.y when calling ``make`` with
@ -199,9 +201,9 @@ this.
.. code-block:: bash
$ python install.py -m <python module> -l <shared library> -v <version.h file> [-d <pydir>]
$ python install.py -p <python package> -l <shared library> -v <version.h file> [-d <pydir>]
* The ``-m`` flag points to the ``lammps.py`` python module file to be installed,
* The ``-p`` flag points to the ``lammps`` Python package folder to be installed,
* the ``-l`` flag points to the LAMMPS shared library file to be installed,
* the ``-v`` flag points to the ``version.h`` file in the LAMMPS source
* and the optional ``-d`` flag to a custom (legacy) installation folder
@ -249,38 +251,38 @@ this.
When using CMake to build LAMMPS, you need to set
``CMAKE_INSTALL_PREFIX`` to the value of the ``$VIRTUAL_ENV``
environment variable during the configuration step. For the
traditional make procedure, not additional steps are needed.
After compiling LAMMPS you can do a "Python module only"
traditional make procedure, no additional steps are needed.
After compiling LAMMPS you can do a "Python package only"
installation with ``make install-python`` and the LAMMPS Python
module and the shared library file are installed into the
package and the shared library file are installed into the
following locations:
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===========================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+========================+=================================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
If you do a full installation (CMake only) with "install", this
leads to the following installation locations:
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===========================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/`` (32bit) | |
| | * ``$VIRTUAL_ENV/lib64/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+========================+=================================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/`` (32bit) | Set shared loader environment variable to this path |
| | * ``$VIRTUAL_ENV/lib64/`` (64bit) | (see below for more info on this) |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``$VIRTUAL_ENV/bin/`` | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$VIRTUAL_ENV/share/lammps/potentials/`` | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$VIRTUAL_ENV/share/lammps/potentials/`` | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
In that case you need to modify the ``$HOME/myenv/bin/activate``
script in a similar fashion you need to update your
@ -296,15 +298,15 @@ this.
echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
# MacOS
echo 'export DYLD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
echo 'export DYLD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$DYLD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
.. tab:: In place usage
You can also :doc:`compile LAMMPS <Build>` as usual in
:ref:`"shared" mode <exe>` leave the shared library and Python
module files inside the source/compilation folders. Instead of
package inside the source/compilation folders. Instead of
copying the files where they can be found, you need to set the environment
variables ``PYTHONPATH`` (for the Python module) and
variables ``PYTHONPATH`` (for the Python package) and
``LD_LIBRARY_PATH`` (or ``DYLD_LIBRARY_PATH`` on MacOS
For Bourne shells (bash, ksh and similar) the commands are:
@ -325,6 +327,10 @@ this.
You can make those changes permanent by editing your ``$HOME/.bashrc``
or ``$HOME/.login`` files, respectively.
.. note::
The ``PYTHONPATH`` needs to point to the parent folder that contains the ``lammps`` package!
To verify if LAMMPS can be successfully started from Python, start the
Python interpreter, load the ``lammps`` Python module and create a
@ -346,7 +352,7 @@ output similar to the following:
.. note::
Unless you opted for "In place use", you will have to rerun the installation
any time you recompile LAMMPS to ensure the latest Python module and shared
any time you recompile LAMMPS to ensure the latest Python package and shared
library are installed and used.
.. note::

43
doc/src/Python_module.rst
View File

@ -3,12 +3,12 @@ The ``lammps`` Python module
.. py:module:: lammps
The LAMMPS Python interface is implemented as a module called
:py:mod:`lammps` in the ``lammps.py`` file in the ``python`` folder of
the LAMMPS source code distribution. After compilation of LAMMPS, the
module can be installed into a Python system folder or a user folder
with ``make install-python``. Components of the module can then loaded
into a Python session with the ``import`` command.
The LAMMPS Python interface is implemented as a module called :py:mod:`lammps`
which is defined in the ``lammps`` package in the ``python`` folder of the
LAMMPS source code distribution. After compilation of LAMMPS, the module can
be installed into a Python system folder or a user folder with ``make
install-python``. Components of the module can then loaded into a Python
session with the ``import`` command.
There are multiple Python interface classes in the :py:mod:`lammps` module:
@ -26,6 +26,23 @@ There are multiple Python interface classes in the :py:mod:`lammps` module:
.. _mpi4py_url: https://mpi4py.readthedocs.io
.. admonition:: Version check
:class: note
The :py:mod:`lammps` module stores the version number of the LAMMPS
version it is installed from. When initializing the
:py:class:`lammps <lammps.lammps>` class, this version is checked to
be the same as the result from :py:func:`lammps.version`, the version
of the LAMMPS shared library that the module interfaces to. If the
they are not the same an AttributeError exception is raised since a
mismatch of versions (e.g. due to incorrect use of the
``LD_LIBRARY_PATH`` or ``PYTHONPATH`` environment variables can lead
to crashes or data corruption and otherwise incorrect behavior.
.. automodule:: lammps
:members:
:noindex:
----------
The ``lammps`` class API
@ -44,7 +61,7 @@ functions. Below is a detailed documentation of the API.
.. autoclass:: lammps.lammps
:members:
.. autoclass:: lammps.numpy_wrapper
.. autoclass:: lammps.numpy_wrapper::numpy_wrapper
:members:
----------
@ -117,23 +134,23 @@ Style Constants
to request from computes or fixes. See :cpp:enum:`_LMP_STYLE_CONST`
for the equivalent constants in the C library interface. Used in
:py:func:`lammps.extract_compute`, :py:func:`lammps.extract_fix`, and their NumPy variants
:py:func:`lammps.numpy.extract_compute() <numpy_wrapper.extract_compute>` and
:py:func:`lammps.numpy.extract_fix() <numpy_wrapper.extract_fix>`.
:py:func:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.numpy_wrapper.extract_compute>` and
:py:func:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.numpy_wrapper.extract_fix>`.
.. _py_type_constants:
Type Constants
--------------
.. py:data:: LMP_TYPE_SCALAR, LMP_TYLE_VECTOR, LMP_TYPE_ARRAY, LMP_SIZE_VECTOR, LMP_SIZE_ROWS, LMP_SIZE_COLS
.. py:data:: LMP_TYPE_SCALAR, LMP_TYPE_VECTOR, LMP_TYPE_ARRAY, LMP_SIZE_VECTOR, LMP_SIZE_ROWS, LMP_SIZE_COLS
:type: int
Constants in the :py:mod:`lammps` module to select what type of data
to request from computes or fixes. See :cpp:enum:`_LMP_TYPE_CONST`
for the equivalent constants in the C library interface. Used in
:py:func:`lammps.extract_compute`, :py:func:`lammps.extract_fix`, and their NumPy variants
:py:func:`lammps.numpy.extract_compute() <numpy_wrapper.extract_compute>` and
:py:func:`lammps.numpy.extract_fix() <numpy_wrapper.extract_fix>`.
:py:func:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.numpy_wrapper.extract_compute>` and
:py:func:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.numpy_wrapper.extract_fix>`.
.. _py_vartype_constants:
@ -153,6 +170,6 @@ Classes representing internal objects
:members:
:no-undoc-members:
.. autoclass:: lammps.NumPyNeighList
.. autoclass:: lammps.numpy_wrapper::NumPyNeighList
:members:
:no-undoc-members:

41
doc/src/Python_neighbor.rst
View File

@ -1,6 +1,43 @@
Neighbor list access
====================
Access to neighbor lists is handled through a couple of wrapper classes
that allows to treat it like either a python list or a NumPy array. The
access procedure is similar to that of the C-library interface: use one
of the "find" functions to look up the index of the neighbor list in the
global table of neighbor lists and then get access to the neighbor list
data. The code sample below demonstrates reading the neighbor list data
using the NumPy access method.
.. code-block:: python
from lammps import lammps
import numpy as np
lmp = lammps()
lmp.commands_string("""
region box block -2 2 -2 2 -2 2
lattice fcc 1.0
create_box 1 box
create_atoms 1 box
mass 1 1.0
pair_style lj/cut 2.5
pair_coeff 1 1 1.0 1.0
run 0 post no""")
# look up the neighbor list
nlidx = lmp.find_pair_neighlist('lj/cut')
nl = lmp.numpy.get_neighlist(nlidx)
tags = lmp.extract_atom('id')
print("half neighbor list with {} entries".format(nl.size))
# print neighbor list contents
for i in range(0,nl.size):
idx, nlist = nl.get(i)
print("\natom {} with ID {} has {} neighbors:".format(idx,tags[idx],nlist.size))
if nlist.size > 0:
for n in np.nditer(nlist):
print(" atom {} with ID {}".format(n,tags[n]))
**Methods:**
* :py:meth:`lammps.get_neighlist() <lammps.lammps.get_neighlist()>`: Get neighbor list for given index
@ -14,5 +51,5 @@ Neighbor list access
**NumPy Methods:**
* :py:meth:`lammps.numpy.get_neighlist() <lammps.numpy_wrapper.get_neighlist()>`: Get neighbor list for given index, which uses NumPy arrays for its element neighbor arrays
* :py:meth:`lammps.numpy.get_neighlist_element_neighbors() <lammps.numpy_wrapper.get_neighlist_element_neighbors()>`: Get element in neighbor list and its neighbors (as numpy array)
* :py:meth:`lammps.numpy.get_neighlist() <lammps.numpy_wrapper.numpy_wrapper.get_neighlist()>`: Get neighbor list for given index, which uses NumPy arrays for its element neighbor arrays
* :py:meth:`lammps.numpy.get_neighlist_element_neighbors() <lammps.numpy_wrapper.numpy_wrapper.get_neighlist_element_neighbors()>`: Get element in neighbor list and its neighbors (as numpy array)

12
doc/src/Python_objects.rst
View File

@ -36,9 +36,9 @@ computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
Python subscripting. The values will be zero for atoms not in the
specified group.
:py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.extract_compute()>`,
:py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.extract_fix()>`, and
:py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.extract_variable()>` are
:py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.numpy_wrapper.extract_compute()>`,
:py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.numpy_wrapper.extract_fix()>`, and
:py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.numpy_wrapper.extract_variable()>` are
equivalent NumPy implementations that return NumPy arrays instead of ``ctypes`` pointers.
The :py:meth:`lammps.set_variable() <lammps.lammps.set_variable()>` method sets an
@ -54,9 +54,9 @@ computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
**NumPy Methods**:
* :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.extract_compute()>`: extract value(s) from a compute, return arrays as numpy arrays
* :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.extract_fix()>`: extract value(s) from a fix, return arrays as numpy arrays
* :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.extract_variable()>`: extract value(s) from a variable, return arrays as numpy arrays
* :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.numpy_wrapper.extract_compute()>`: extract value(s) from a compute, return arrays as numpy arrays
* :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.numpy_wrapper.extract_fix()>`: extract value(s) from a fix, return arrays as numpy arrays
* :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.numpy_wrapper.extract_variable()>`: extract value(s) from a variable, return arrays as numpy arrays
.. tab:: PyLammps/IPyLammps API

10
doc/src/Python_overview.rst
View File

@ -2,9 +2,9 @@ Overview
========
The LAMMPS distribution includes a ``python`` directory with the Python
code needed to run LAMMPS from Python. The ``python/lammps.py``
contains :doc:`the "lammps" Python <Python_module>` that wraps the
LAMMPS C-library interface. This file makes it is possible to do the
code needed to run LAMMPS from Python. The ``python/lammps`` package
contains :doc:`the "lammps" Python module <Python_module>` that wraps the
LAMMPS C-library interface. This module makes it is possible to do the
following either from a Python script, or interactively from a Python
prompt:
@ -20,8 +20,8 @@ have a version of Python that extends Python to enable multiple
instances of Python to read what you type.
To do all of this, you must build LAMMPS in :ref:`"shared" mode <exe>`
and make certain that your Python interpreter can find the ``lammps.py``
file and the LAMMPS shared library file.
and make certain that your Python interpreter can find the ``lammps``
Python package and the LAMMPS shared library file.
.. _ctypes: https://docs.python.org/3/library/ctypes.html

2
doc/src/Python_trouble.rst
View File

@ -33,7 +33,7 @@ the constructor call as follows (see :ref:`python_create_lammps` for more detail
>>> lmp = lammps(name='mpi')
You can also test the load directly in Python as follows, without
first importing from the lammps.py file:
first importing from the ``lammps`` module:
.. code-block:: python

26
doc/src/Run_options.rst
View File

@ -11,6 +11,7 @@ letter abbreviation can be used:
* :ref:`-k or -kokkos <run-kokkos>`
* :ref:`-l or -log <log>`
* :ref:`-m or -mpicolor <mpicolor>`
* :ref:`-c or -cite <cite>`
* :ref:`-nc or -nocite <nocite>`
* :ref:`-pk or -package <package>`
* :ref:`-p or -partition <partition>`
@ -220,14 +221,31 @@ links with from the lib/message directory. See the
----------
.. _cite:
**-cite style or file name**
Select how and where to output a reminder about citing contributions
to the LAMMPS code that were used during the run. Available styles are
"both", "none", "screen", or "log". Any flag will be considered a file
name to write the detailed citation info to. Default is the "log" style
where there is a short summary in the screen output and detailed citations
in BibTeX format in the logfile. The option "both" selects the detailed
output for both, "none", the short output for both, and "screen" will
write the detailed info to the screen and the short version to the log
file. If a dedicated citation info file is requested, the screen and
log file output will be in the short format (same as with "none").
See the :doc:`citation page <Intro_citing>` for more details on
how to correctly reference and cite LAMMPS.
----------
.. _nocite:
**-nocite**
Disable writing the log.cite file which is normally written to list
references for specific cite-able features used during a LAMMPS run.
See the `citation page <https://lammps.sandia.gov/cite.html>`_ for more
details.
Disable generating a citation reminder (see above) at all.
----------

64
doc/src/Speed_gpu.rst
View File

@ -1,11 +1,14 @@
GPU package
===========
The GPU package was developed by Mike Brown while at SNL and ORNL
and his collaborators, particularly Trung Nguyen (now at Northwestern).
It provides GPU versions of many pair styles and for parts of the
:doc:`kspace_style pppm <kspace_style>` for long-range Coulombics.
It has the following general features:
The GPU package was developed by Mike Brown while at SNL and ORNL (now
at Intel Corp.) and his collaborators, particularly Trung Nguyen (now at
Northwestern). Support for AMD GPUs via HIP was added by Vsevolod Nikolskiy
and coworkers at HSE University.
The GPU package provides GPU versions of many pair styles and for
parts of the :doc:`kspace_style pppm <kspace_style>` for long-range
Coulombics. It has the following general features:
* It is designed to exploit common GPU hardware configurations where one
or more GPUs are coupled to many cores of one or more multi-core CPUs,
@ -24,8 +27,9 @@ It has the following general features:
force vectors.
* LAMMPS-specific code is in the GPU package. It makes calls to a
generic GPU library in the lib/gpu directory. This library provides
NVIDIA support as well as more general OpenCL support, so that the
same functionality is supported on a variety of hardware.
either Nvidia support, AMD support, or more general OpenCL support
(for Nvidia GPUs, AMD GPUs, Intel GPUs, and multi-core CPUs).
so that the same functionality is supported on a variety of hardware.
**Required hardware/software:**
@ -45,12 +49,23 @@ to have the OpenCL headers and the (vendor neutral) OpenCL library installed.
In OpenCL mode, the acceleration depends on having an `OpenCL Installable Client Driver (ICD) <https://www.khronos.org/news/permalink/opencl-installable-client-driver-icd-loader>`_
installed. There can be multiple of them for the same or different hardware
(GPUs, CPUs, Accelerators) installed at the same time. OpenCL refers to those
as 'platforms'. The GPU library will select the **first** suitable platform,
but this can be overridden using the device option of the :doc:`package <package>`
as 'platforms'. The GPU library will try to auto-select the best suitable platform,
but this can be overridden using the platform option of the :doc:`package <package>`
command. run lammps/lib/gpu/ocl_get_devices to get a list of available
platforms and devices with a suitable ICD available.
To compute and use this package in HIP mode, you have to have the AMD ROCm
To compile and use this package for Intel GPUs, OpenCL or the Intel oneAPI
HPC Toolkit can be installed using linux package managers. The latter also
provides optimized C++, MPI, and many other libraries and tools. See:
* https://software.intel.com/content/www/us/en/develop/tools/oneapi/hpc-toolkit/download.html
If you do not have a discrete GPU card installed, this package can still provide
significant speedups on some CPUs that include integrated GPUs. Additionally, for
many macs, OpenCL is already included with the OS and Makefiles are available
in the lib/gpu directory.
To compile and use this package in HIP mode, you have to have the AMD ROCm
software installed. Versions of ROCm older than 3.5 are currently deprecated
by AMD.
@ -75,10 +90,20 @@ automatically if you create more MPI tasks/node than there are
GPUs/mode. E.g. with 8 MPI tasks/node and 2 GPUs, each GPU will be
shared by 4 MPI tasks.
The GPU package also has limited support for OpenMP for both
multi-threading and vectorization of routines that are run on the CPUs.
This requires that the GPU library and LAMMPS are built with flags to
enable OpenMP support (e.g. -fopenmp). Some styles for time integration
are also available in the GPU package. These run completely on the CPUs
in full double precision, but exploit multi-threading and vectorization
for faster performance.
Use the "-sf gpu" :doc:`command-line switch <Run_options>`, which will
automatically append "gpu" to styles that support it. Use the "-pk
gpu Ng" :doc:`command-line switch <Run_options>` to set Ng = # of
GPUs/node to use.
GPUs/node to use. If Ng is 0, the number is selected automatically as
the number of matching GPUs that have the highest number of compute
cores.
.. code-block:: bash
@ -87,8 +112,8 @@ GPUs/node to use.
mpirun -np 48 -ppn 12 lmp_machine -sf gpu -pk gpu 2 -in in.script # ditto on 4 16-core nodes
Note that if the "-sf gpu" switch is used, it also issues a default
:doc:`package gpu 1 <package>` command, which sets the number of
GPUs/node to 1.
:doc:`package gpu 0 <package>` command, which will result in
automatic selection of the number of GPUs to use.
Using the "-pk" switch explicitly allows for setting of the number of
GPUs/node to use and additional options. Its syntax is the same as
@ -138,6 +163,13 @@ Likewise, you should experiment with the precision setting for the GPU
library to see if single or mixed precision will give accurate
results, since they will typically be faster.
MPI parallelism typically outperforms OpenMP parallelism, but in some
cases using fewer MPI tasks and multiple OpenMP threads with the GPU
package can give better performance. 3-body potentials can often perform
better with multiple OMP threads because the inter-process communication
is higher for these styles with the GPU package in order to allow
deterministic results.
**Guidelines for best performance:**
* Using multiple MPI tasks per GPU will often give the best performance,
@ -161,6 +193,12 @@ results, since they will typically be faster.
:doc:`angle <angle_style>`, :doc:`dihedral <dihedral_style>`,
:doc:`improper <improper_style>`, and :doc:`long-range <kspace_style>`
calculations will not be included in the "Pair" time.
* Since only part of the pppm kspace style is GPU accelerated, it
may be faster to only use GPU acceleration for Pair styles with
long-range electrostatics. See the "pair/only" keyword of the
package command for a shortcut to do that. The work between kspace
on the CPU and non-bonded interactions on the GPU can be balanced
through adjusting the coulomb cutoff without loss of accuracy.
* When the *mode* setting for the package gpu command is force/neigh,
the time for neighbor list calculations on the GPU will be added into
the "Pair" time, not the "Neigh" time. An additional breakdown of the

21
doc/src/Speed_kokkos.rst
View File

@ -26,6 +26,15 @@ task). These are Serial (MPI-only for CPUs and Intel Phi), OpenMP
GPUs) and HIP (for AMD GPUs). You choose the mode at build time to
produce an executable compatible with a specific hardware.
.. admonition:: C++14 support
:class: note
Kokkos requires using a compiler that supports the c++14 standard. For
some compilers, it may be necessary to add a flag to enable c++14 support.
For example, the GNU compiler uses the -std=c++14 flag. For a list of
compilers that have been tested with the Kokkos library, see the Kokkos
`README <https://github.com/kokkos/kokkos/blob/master/README.md>`_.
.. admonition:: NVIDIA CUDA support
:class: note
@ -38,14 +47,14 @@ produce an executable compatible with a specific hardware.
:class: note
Kokkos with CUDA currently implicitly assumes that the MPI library is
CUDA-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
faults without CUDA-aware MPI support. These can be avoided by adding
the flags :doc:`-pk kokkos cuda/aware off <Run_options>` to the
faults without GPU-aware MPI support. These can be avoided by adding
the flags :doc:`-pk kokkos gpu/aware off <Run_options>` to the
LAMMPS command line or by using the command :doc:`package kokkos
cuda/aware off <package>` in the input file.
gpu/aware off <package>` in the input file.
.. admonition:: AMD GPU support
:class: note
@ -242,8 +251,8 @@ case, also packing/unpacking communication buffers on the host may give
speedup (see the KOKKOS :doc:`package <package>` command). Using CUDA MPS
is recommended in this scenario.
Using a CUDA-aware MPI library is highly recommended. CUDA-aware MPI use can be
avoided by using :doc:`-pk kokkos cuda/aware no <package>`. As above for
Using a GPU-aware MPI library is highly recommended. GPU-aware MPI use can be
avoided by using :doc:`-pk kokkos gpu/aware off <package>`. As above for
multi-core CPUs (and no GPU), if N is the number of physical cores/node,
then the number of MPI tasks/node should not exceed N.

8
doc/src/Speed_packages.rst
View File

@ -16,7 +16,7 @@ These are the accelerator packages currently in LAMMPS, either as
standard or user packages:
+-----------------------------------------+-------------------------------------------------------+
| :doc:`GPU Package <Speed_gpu>` | for NVIDIA GPUs as well as OpenCL support |
| :doc:`GPU Package <Speed_gpu>` | for GPUs via CUDA, OpenCL, or ROCm HIP |
+-----------------------------------------+-------------------------------------------------------+
| :doc:`USER-INTEL Package <Speed_intel>` | for Intel CPUs and Intel Xeon Phi |
+-----------------------------------------+-------------------------------------------------------+
@ -43,7 +43,7 @@ three kinds of hardware, via the listed packages:
+-----------------+-----------------------------------------------------------------------------------------------------------------------------+
| Many-core CPUs | :doc:`USER-INTEL <Speed_intel>`, :doc:`KOKKOS <Speed_kokkos>`, :doc:`USER-OMP <Speed_omp>`, :doc:`OPT <Speed_opt>` packages |
+-----------------+-----------------------------------------------------------------------------------------------------------------------------+
| NVIDIA/AMD GPUs | :doc:`GPU <Speed_gpu>`, :doc:`KOKKOS <Speed_kokkos>` packages |
| GPUs | :doc:`GPU <Speed_gpu>`, :doc:`KOKKOS <Speed_kokkos>` packages |
+-----------------+-----------------------------------------------------------------------------------------------------------------------------+
| Intel Phi/AVX | :doc:`USER-INTEL <Speed_intel>`, :doc:`KOKKOS <Speed_kokkos>` packages |
+-----------------+-----------------------------------------------------------------------------------------------------------------------------+
@ -154,8 +154,8 @@ Here is a brief summary of what the various packages provide. Details
are in the individual accelerator sections.
* Styles with a "gpu" suffix are part of the GPU package and can be run
on NVIDIA or AMD GPUs. The speed-up on a GPU depends on a variety of
factors, discussed in the accelerator sections.
on Intel, NVIDIA, or AMD GPUs. The speed-up on a GPU depends on a
variety of factors, discussed in the accelerator sections.
* Styles with an "intel" suffix are part of the USER-INTEL
package. These styles support vectorized single and mixed precision
calculations, in addition to full double precision. In extreme cases,

137
doc/src/Tools.rst
View File

@ -93,6 +93,8 @@ Miscellaneous tools
* :ref:`i-pi <ipi>`
* :ref:`kate <kate>`
* :ref:`LAMMPS shell <lammps_shell>`
* :ref:`LAMMPS magic patterns for file(1) <magic>`
* :ref:`Offline build tool <offline>`
* :ref:`singularity <singularity_tool>`
* :ref:`SWIG interface <swig>`
* :ref:`vim <vim>`
@ -267,7 +269,7 @@ data file in the required format.
See the header of the polarizer.py file for details.
The tool is authored by Agilio Padua and Alain Dequidt: agilio.padua
at univ-bpclermont.fr, alain.dequidt at univ-bpclermont.fr
at ens-lyon.fr, alain.dequidt at uca.fr
----------
@ -341,8 +343,7 @@ The tools/fep directory contains Python scripts useful for
post-processing results from performing free-energy perturbation
simulations using the USER-FEP package.
The scripts were contributed by Agilio Padua (Universite Blaise
Pascal Clermont-Ferrand), agilio.padua at univ-bpclermont.fr.
The scripts were contributed by Agilio Padua (ENS de Lyon), agilio.padua at ens-lyon.fr.
See README file in the tools/fep directory.
@ -642,6 +643,39 @@ This tool was written by Ara Kooser at Sandia (askoose at sandia.gov).
----------
.. _magic:
Magic patterns for the "file" command
-------------------------------------
.. versionadded:: 10Mar2021
The file ``magic`` contains patterns that are used by the
`file program <https://en.wikipedia.org/wiki/File_(command)>`_
available on most Unix-like operating systems which enables it
to detect various LAMMPS files and print some useful information
about them. To enable these patterns, append or copy the contents
of the file to either the file ``.magic`` in your home directory
or (as administrator) to ``/etc/magic`` (for a system-wide
installation). Afterwards the ``file`` command should be able to
detect most LAMMPS restarts, dump, data and log files. Examples:
.. code-block:: bash
$ file *.*
dihedral-quadratic.restart: LAMMPS binary restart file (rev 2), Version 10 Mar 2021, Little Endian
mol-pair-wf_cut.restart: LAMMPS binary restart file (rev 2), Version 24 Dec 2020, Little Endian
atom.bin: LAMMPS atom style binary dump (rev 2), Little Endian, First time step: 445570
custom.bin: LAMMPS custom style binary dump (rev 2), Little Endian, First time step: 100
bn1.lammpstrj: LAMMPS text mode dump, First time step: 5000
data.fourmol: LAMMPS data file written by LAMMPS
pnc.data: LAMMPS data file written by msi2lmp
data.spce: LAMMPS data file written by TopoTools
B.data: LAMMPS data file written by OVITO
log.lammps: LAMMPS log file written by version 10 Feb 2021
----------
.. _matlab:
matlab tool
@ -723,6 +757,103 @@ See the README file in the tools/msi2lmp folder for more information.
----------
.. _offline:
Scripts for building LAMMPS when offline
----------------------------------------
In some situations it might be necessary to build LAMMPS on a system
without direct internet access. The scripts in ``tools/offline`` folder
allow you to pre-load external dependencies for both the documentation
build and for building LAMMPS with CMake.
It does so by
#. downloading necessary ``pip`` packages,
#. cloning ``git`` repositories
#. downloading tarballs
to a designated cache folder.
As of April 2021, all of these downloads make up around 600MB. By
default, the offline scripts will download everything into the
``$HOME/.cache/lammps`` folder, but this can be changed by setting the
``LAMMPS_CACHING_DIR`` environment variable.
Once the caches have been initialized, they can be used for building the
LAMMPS documentation or compiling LAMMPS using CMake on an offline
system.
The ``use_caches.sh`` script must be sourced into the current shell
to initialize the offline build environment. Note that it must use
the same ``LAMMPS_CACHING_DIR``. This script does the following:
#. Set up environment variables that modify the behavior of both,
``pip`` and ``git``
#. Start a simple local HTTP server using Python to host files for CMake
Afterwards, it will print out instruction on how to modify the CMake
command line to make sure it uses the local HTTP server.
To undo the environment changes and shutdown the local HTTP server,
run the ``deactivate_caches`` command.
Examples
^^^^^^^^
For all of the examples below, you first need to create the cache, which
requires an internet connection.
.. code-block:: bash
./tools/offline/init_caches.sh
Afterwards, you can disconnect or copy the contents of the
``LAMMPS_CACHING_DIR`` folder to an offline system.
Documentation Build
^^^^^^^^^^^^^^^^^^^
The documentation build will create a new virtual environment that
typically first installs dependencies from ``pip``. With the offline
environment loaded, these installations will instead grab the necessary
packages from your local cache.
.. code-block:: bash
# if LAMMPS_CACHING_DIR is different from default, make sure to set it first
# export LAMMPS_CACHING_DIR=path/to/folder
source tools/offline/use_caches.sh
cd doc/
make html
deactivate_caches
CMake Build
^^^^^^^^^^^
When compiling certain packages with external dependencies, the CMake
build system will download necessary files or sources from the web. For
more flexibility the CMake configuration allows users to specify the URL
of each of these dependencies. What the ``init_caches.sh`` script does
is create a CMake "preset" file, which sets the URLs for all of the known
dependencies and redirects the download to the local cache.
.. code-block:: bash
# if LAMMPS_CACHING_DIR is different from default, make sure to set it first
# export LAMMPS_CACHING_DIR=path/to/folder
source tools/offline/use_caches.sh
mkdir build
cd build
cmake -D LAMMPS_DOWNLOADS_URL=${HTTP_CACHE_URL} -C "${LAMMPS_HTTP_CACHE_CONFIG}" -C ../cmake/presets/most.cmake ../cmake
make -j 8
deactivate_caches
----------
.. _phonon:
phonon tool

22
doc/src/angle_cosine_periodic.rst
View File

@ -24,20 +24,17 @@ Examples
Description
"""""""""""
The *cosine/periodic* angle style uses the following potential, which
is commonly used in the :doc:`DREIDING <Howto_bioFF>` force field,
particularly for organometallic systems where :math:`n` = 4 might be used
The *cosine/periodic* angle style uses the following potential, which may be
particularly used for organometallic systems where :math:`n` = 4 might be used
for an octahedral complex and :math:`n` = 3 might be used for a trigonal
center:
.. math::
E = C \left[ 1 - B(-1)^n\cos\left( n\theta\right) \right]
E = \frac{2.0}{n^2} * C \left[ 1 - B(-1)^n\cos\left( n\theta\right) \right]
where :math:`C`, :math:`B` and :math:`n` are coefficients defined for each angle type.
See :ref:`(Mayo) <cosine-Mayo>` for a description of the DREIDING force field
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
@ -47,10 +44,9 @@ or :doc:`read_restart <read_restart>` commands:
* :math:`B` = 1 or -1
* :math:`n` = 1, 2, 3, 4, 5 or 6 for periodicity
Note that the prefactor :math:`C` is specified and not the overall force
constant :math:`K = \frac{C}{n^2}`. When :math:`B = 1`, it leads to a minimum for the
linear geometry. When :math:`B = -1`, it leads to a maximum for the linear
geometry.
Note that the prefactor :math:`C` is specified as coefficient and not the overall force
constant :math:`K = \frac{2 C}{n^2}`. When :math:`B = 1`, it leads to a minimum for the
linear geometry. When :math:`B = -1`, it leads to a maximum for the linear geometry.
----------
@ -75,9 +71,3 @@ Default
none
----------
.. _cosine-Mayo:
**(Mayo)** Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909
(1990).

14
doc/src/angle_cosine_squared.rst
View File

@ -30,8 +30,11 @@ The *cosine/squared* angle style uses the potential
E = K [\cos(\theta) - \cos(\theta_0)]^2
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`.
, which is commonly used in the :doc:`DREIDING <Howto_bioFF>` 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:`(Mayo) <cosine-Mayo>` for a description of the DREIDING force field.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
@ -66,3 +69,10 @@ Default
"""""""
none
----------
.. _cosine-Mayo:
**(Mayo)** Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909
(1990).

2
doc/src/atom_style.rst
View File

@ -27,7 +27,7 @@ Syntax
template-ID = ID of molecule template specified in a separate :doc:`molecule <molecule>` command
*hybrid* args = list of one or more sub-styles, each with their args
* accelerated styles (with same args) = *angle/kk* or *atomic/kk* or *bond/kk* or *charge/kk* or *full/kk* or *molecular/kk*
* accelerated styles (with same args) = *angle/kk* or *atomic/kk* or *bond/kk* or *charge/kk* or *full/kk* or *molecular/kk* or *spin/kk*
Examples
""""""""

6
doc/src/balance.rst
View File

@ -257,7 +257,7 @@ factor, similar to how the :doc:`fix balance shift <fix_balance>`
command operates.
The *dimstr* argument is a string of characters, each of which must be
an "x" or "y" or "z". Eacn character can appear zero or one time,
an "x" or "y" or "z". Each character can appear zero or one time,
since there is no advantage to balancing on a dimension more than
once. You should normally only list dimensions where you expect there
to be a density variation in the particles.
@ -285,10 +285,10 @@ plane gets closer to the target value.
After the balanced plane positions are determined, if any pair of
adjacent planes are closer together than the neighbor skin distance
(as specified by the :doc`neigh_modify <neigh_modify>` command), then
(as specified by the :doc:`neigh_modify <neigh_modify>` command), then
the plane positions are shifted to separate them by at least this
amount. This is to prevent particles being lost when dynamics are run
with processor subdomains that are too narrow in one or more
with processor sub-domains that are too narrow in one or more
dimensions.
Once the re-balancing is complete and final processor sub-domains

6
doc/src/comm_modify.rst
View File

@ -84,13 +84,15 @@ information is available, then also a heuristic based on that bond length
is computed. It is used as communication cutoff, if there is no pair
style present and no *comm_modify cutoff* command used. Otherwise a
warning is printed, if this bond based estimate is larger than the
communication cutoff used. A
communication cutoff used.
The *cutoff/multi* option is equivalent to *cutoff*\ , but applies to
communication mode *multi* instead. Since in this case the communication
cutoffs are determined per atom type, a type specifier is needed and
cutoff for one or multiple types can be extended. Also ranges of types
using the usual asterisk notation can be given.
using the usual asterisk notation can be given. For granular pair styles,
the default cutoff is set to the sum of the current maximum atomic radii
for each type.
These are simulation scenarios in which it may be useful or even
necessary to set a ghost cutoff > neighbor cutoff:

1
doc/src/commands_list.rst
View File

@ -77,6 +77,7 @@ Commands
pair_style
pair_write
partition
plugin
prd
print
processors

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