lijiext
/
lammps
mirror of https://github.com/lammps/lammps.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' of https://github.com/lammps/lammps into lammps-master

This commit is contained in:
Jacob Gissinger 2020-08-27 12:02:08 -04:00
parent bc49e854ba d00807ee9a
commit 583a09c808
3215 changed files with 120242 additions and 112924 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.gitattributes vendored Normal file
View File

@ -0,0 +1,3 @@
.gitattributes export-ignore
.gitignore export-ignore
.github export-ignore

29
.github/codecov.yml vendored Normal file
View File

@ -0,0 +1,29 @@
comment: false
coverage:
notify:
slack:
default:
url: "secret:HWZbvgtc6OD7F3v3PfrK3/rzCJvScbh69Fi1CkLwuHK0+wIBIHVR+Q5i7q6F9Ln4OChbiRGtYAEUUsT8/jmBu4qDpIi8mx746codc0z/Z3aafLd24pBrCEPLvdCfIZxqPnw3TuUgGhwmMDZf0+thg8YNUr/MbOZ7Li2L6+ZbYuA="
threshold: 10%
only_pulls: false
branches:
- "master"
flags:
- "unit"
paths:
- "src"
status:
project:
default:
branches:
- "master"
paths:
- "src"
informational: true
patch:
default:
branches:
- "master"
paths:
- "src"
informational: true

20
cmake/CMakeLists.txt
View File

@ -69,18 +69,10 @@ if(${CMAKE_CXX_COMPILER_ID} STREQUAL "Intel")
endif()
endif()
if(${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
set(CMAKE_TUNE_DEFAULT "-march=native")
endif()
if(${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang")
set(CMAKE_TUNE_DEFAULT "-march=native")
endif()
# we require C++11 without extensions
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)
set(CMAKE_CXX_EXTENSIONS OFF CACHE BOOL "Use compiler extensions")
########################################################################
# User input options #
@ -193,7 +185,7 @@ if(NOT ${LAMMPS_MEMALIGN} STREQUAL "0")
target_compile_definitions(lammps PRIVATE -DLAMMPS_MEMALIGN=${LAMMPS_MEMALIGN})
endif()
option(LAMMPS_EXCEPTIONS "enable the use of C++ exceptions for error messages (useful for library interface)" OFF)
option(LAMMPS_EXCEPTIONS "enable the use of C++ exceptions for error messages (useful for library interface)" ${ENABLE_TESTING})
if(LAMMPS_EXCEPTIONS)
target_compile_definitions(lammps PUBLIC -DLAMMPS_EXCEPTIONS)
endif()
@ -366,7 +358,7 @@ foreach(PKG_WITH_INCL KSPACE PYTHON VORONOI USER-COLVARS USER-MOLFILE USER-NETCD
endif()
endforeach()
set(CMAKE_TUNE_FLAGS "${CMAKE_TUNE_DEFAULT}" CACHE STRING "Compiler specific optimization or instrumentation")
set(CMAKE_TUNE_FLAGS "${CMAKE_TUNE_DEFAULT}" CACHE STRING "Compiler and machine specific optimization flags (compilation only)")
separate_arguments(CMAKE_TUNE_FLAGS)
foreach(_FLAG ${CMAKE_TUNE_FLAGS})
target_compile_options(lammps PRIVATE ${_FLAG})
@ -755,6 +747,12 @@ if (${_index} GREATER -1)
endif()
message(STATUS "<<< Linker flags: >>>")
message(STATUS "Executable name: ${LAMMPS_BINARY}")
if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.13)
get_target_property(OPTIONS lammps LINK_OPTIONS)
if(OPTIONS)
message(STATUS "Linker options: ${OPTIONS}")
endif()
endif()
if(CMAKE_EXE_LINKER_FLAGS)
message(STATUS "Executable linker flags: ${CMAKE_EXE_LINKER_FLAGS}")
endif()

90
cmake/Modules/Documentation.cmake
View File

@ -15,75 +15,93 @@ if(BUILD_DOC)
endif()
set(VIRTUALENV ${Python3_EXECUTABLE} -m virtualenv -p ${Python3_EXECUTABLE})
endif()
find_package(Doxygen 1.8.10 REQUIRED)
file(GLOB DOC_SOURCES ${LAMMPS_DOC_DIR}/src/[^.]*.rst)
add_custom_command(
OUTPUT docenv
COMMAND ${VIRTUALENV} docenv
)
set(DOCENV_BINARY_DIR ${CMAKE_BINARY_DIR}/docenv/bin)
set(DOCENV_REQUIREMENTS_FILE ${LAMMPS_DOC_DIR}/utils/requirements.txt)
set(SPHINX_CONFIG_DIR ${LAMMPS_DOC_DIR}/utils/sphinx-config)
set(SPHINX_CONFIG_FILE_TEMPLATE ${SPHINX_CONFIG_DIR}/conf.py.in)
set(SPHINX_STATIC_DIR ${SPHINX_CONFIG_DIR}/_static)
# configuration and static files are copied to binary dir to avoid collisions with parallel builds
set(DOC_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/doc)
set(DOC_BUILD_CONFIG_FILE ${DOC_BUILD_DIR}/conf.py)
set(DOC_BUILD_STATIC_DIR ${DOC_BUILD_DIR}/_static)
set(DOXYGEN_BUILD_DIR ${DOC_BUILD_DIR}/doxygen)
set(DOXYGEN_XML_DIR ${DOXYGEN_BUILD_DIR}/xml)
# copy entire configuration folder to doc build directory
# files in _static are automatically copied during sphinx-build, so no need to copy them individually
file(COPY ${SPHINX_CONFIG_DIR}/ DESTINATION ${DOC_BUILD_DIR})
# configure paths in conf.py, since relative paths change when file is copied
configure_file(${SPHINX_CONFIG_FILE_TEMPLATE} ${DOC_BUILD_CONFIG_FILE})
add_custom_command(
OUTPUT requirements.txt
DEPENDS docenv
COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/utils/requirements.txt requirements.txt
COMMAND ${DOCENV_BINARY_DIR}/pip install -r requirements.txt --upgrade
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
)
# download mathjax distribution and unpack to folder "mathjax"
if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/mathjax/es5)
if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/mathjax/es5)
file(DOWNLOAD "https://github.com/mathjax/MathJax/archive/3.0.5.tar.gz"
"${CMAKE_CURRENT_BINARY_DIR}/mathjax.tar.gz"
EXPECTED_MD5 5d9d3799cce77a1a95eee6be04eb68e7)
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} ${CMAKE_CURRENT_BINARY_DIR}/mathjax)
execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${DOC_BUILD_STATIC_DIR}/mathjax)
endif()
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax)
file(COPY ${CMAKE_CURRENT_BINARY_DIR}/mathjax/es5 DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax/)
# for increased browser compatibility
if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js)
if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/polyfill.js)
file(DOWNLOAD "https://polyfill.io/v3/polyfill.min.js?features=es6"
"${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js")
"${DOC_BUILD_STATIC_DIR}/polyfill.js")
endif()
# note, this may run in parallel with other tasks, so we must not use multiple processes here
# set up doxygen and add targets to run it
file(MAKE_DIRECTORY ${DOXYGEN_BUILD_DIR})
file(COPY ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png DESTINATION ${DOXYGEN_BUILD_DIR}/lammps-logo.png)
configure_file(${LAMMPS_DOC_DIR}/doxygen/Doxyfile.in ${DOXYGEN_BUILD_DIR}/Doxyfile)
get_target_property(LAMMPS_SOURCES lammps SOURCES)
add_custom_command(
OUTPUT html
DEPENDS ${DOC_SOURCES} docenv requirements.txt
COMMAND ${DOCENV_BINARY_DIR}/sphinx-build -b html -c ${LAMMPS_DOC_DIR}/utils/sphinx-config -d ${CMAKE_BINARY_DIR}/doctrees ${LAMMPS_DOC_DIR}/src html
COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${CMAKE_CURRENT_BINARY_DIR}/html/index.html
OUTPUT ${DOXYGEN_XML_DIR}/index.xml
DEPENDS ${DOC_SOURCES} ${LAMMPS_SOURCES}
COMMAND Doxygen::doxygen ${DOXYGEN_BUILD_DIR}/Doxyfile WORKING_DIRECTORY ${DOXYGEN_BUILD_DIR}
COMMAND ${CMAKE_COMMAND} -E touch ${DOXYGEN_XML_DIR}/run.stamp
)
# copy selected image files to html output tree
file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/html/JPG)
set(HTML_EXTRA_IMAGES balance_nonuniform.jpg balance_rcb.jpg
balance_uniform.jpg bow_tutorial_01.png bow_tutorial_02.png
bow_tutorial_03.png bow_tutorial_04.png bow_tutorial_05.png
dump1.jpg dump2.jpg examples_mdpd.gif gran_funnel.png gran_mixer.png
hop1.jpg hop2.jpg saed_ewald_intersect.jpg saed_mesh.jpg
screenshot_atomeye.jpg screenshot_gl.jpg screenshot_pymol.jpg
screenshot_vmd.jpg sinusoid.jpg xrd_mesh.jpg)
set(HTML_IMAGE_TARGETS "")
foreach(_IMG ${HTML_EXTRA_IMAGES})
string(PREPEND _IMG JPG/)
list(APPEND HTML_IMAGE_TARGETS "${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG}")
add_custom_command(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG}
DEPENDS ${LAMMPS_DOC_DIR}/src/${_IMG} ${CMAKE_CURRENT_BINARY_DIR}/html/JPG
COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/src/${_IMG} ${CMAKE_BINARY_DIR}/html/${_IMG}
)
endforeach()
if(EXISTS ${DOXYGEN_XML_DIR}/run.stamp)
set(SPHINX_EXTRA_OPTS "-E")
else()
set(SPHINX_EXTRA_OPTS "")
endif()
add_custom_command(
OUTPUT html
DEPENDS ${DOC_SOURCES} docenv ${DOC_BUILD_DIR}/requirements.txt ${DOXYGEN_XML_DIR}/index.xml ${BUILD_DOC_CONFIG_FILE}
COMMAND ${DOCENV_BINARY_DIR}/sphinx-build ${SPHINX_EXTRA_OPTS} -b html -c ${DOC_BUILD_DIR} -d ${DOC_BUILD_DIR}/doctrees ${LAMMPS_DOC_DIR}/src ${DOC_BUILD_DIR}/html
COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${DOC_BUILD_DIR}/html/index.html
COMMAND ${CMAKE_COMMAND} -E copy_directory ${LAMMPS_DOC_DIR}/src/PDF ${DOC_BUILD_DIR}/html/PDF
COMMAND ${CMAKE_COMMAND} -E remove -f ${DOXYGEN_XML_DIR}/run.stamp
)
add_custom_target(
doc ALL
DEPENDS html ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax/es5 ${HTML_IMAGE_TARGETS}
DEPENDS html ${DOC_BUILD_STATIC_DIR}/mathjax/es5
SOURCES ${LAMMPS_DOC_DIR}/utils/requirements.txt ${DOC_SOURCES}
)
install(DIRECTORY ${CMAKE_BINARY_DIR}/html DESTINATION ${CMAKE_INSTALL_DOCDIR})
install(DIRECTORY ${DOC_BUILD_DIR}/html DESTINATION ${CMAKE_INSTALL_DOCDIR})
endif()

14
cmake/Modules/GTest.cmake
View File

@ -7,9 +7,11 @@ else()
endif()
include(ExternalProject)
set(GTEST_URL "https://github.com/google/googletest/archive/release-1.10.0.tar.gz" CACHE STRING "URL for GTest tarball")
mark_as_advanced(GTEST_URL)
ExternalProject_Add(googletest
GIT_REPOSITORY https://github.com/google/googletest.git
GIT_TAG release-1.10.0
URL ${GTEST_URL}
URL_MD5 ecd1fa65e7de707cd5c00bdac56022cd
SOURCE_DIR "${CMAKE_BINARY_DIR}/gtest-src"
BINARY_DIR "${CMAKE_BINARY_DIR}/gtest-build"
CMAKE_ARGS ${CMAKE_REQUEST_PIC} ${CMAKE_EXTRA_GTEST_OPTS}
@ -52,26 +54,26 @@ add_library(GTest::GTest UNKNOWN IMPORTED)
set_target_properties(GTest::GTest PROPERTIES
IMPORTED_LOCATION ${GTEST_LIBRARY_PATH}
INTERFACE_INCLUDE_DIRECTORIES ${GTEST_INCLUDE_DIR}
IMPORTED_LINK_INTERFACE_LIBRARIES ${CMAKE_THREAD_LIBS_INIT})
INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
add_dependencies(GTest::GTest googletest)
add_library(GTest::GMock UNKNOWN IMPORTED)
set_target_properties(GTest::GMock PROPERTIES
IMPORTED_LOCATION ${GMOCK_LIBRARY_PATH}
INTERFACE_INCLUDE_DIRECTORIES ${GMOCK_INCLUDE_DIR}
IMPORTED_LINK_INTERFACE_LIBRARIES ${CMAKE_THREAD_LIBS_INIT})
INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
add_dependencies(GTest::GMock googletest)
add_library(GTest::GTestMain UNKNOWN IMPORTED)
set_target_properties(GTest::GTestMain PROPERTIES
IMPORTED_LOCATION ${GTEST_MAIN_LIBRARY_PATH}
INTERFACE_INCLUDE_DIRECTORIES ${GTEST_INCLUDE_DIR}
IMPORTED_LINK_INTERFACE_LIBRARIES ${CMAKE_THREAD_LIBS_INIT})
INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
add_dependencies(GTest::GTestMain googletest)
add_library(GTest::GMockMain UNKNOWN IMPORTED)
set_target_properties(GTest::GMockMain PROPERTIES
IMPORTED_LOCATION ${GMOCK_MAIN_LIBRARY_PATH}
INTERFACE_INCLUDE_DIRECTORIES ${GMOCK_INCLUDE_DIR}
IMPORTED_LINK_INTERFACE_LIBRARIES ${CMAKE_THREAD_LIBS_INIT})
INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
add_dependencies(GTest::GMockMain googletest)

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

@ -64,30 +64,41 @@ if(GPU_API STREQUAL "CUDA")
# build arch/gencode commands for nvcc based on CUDA toolkit version and use choice
# --arch translates directly instead of JIT, so this should be for the preferred or most common architecture
set(GPU_CUDA_GENCODE "-arch=${GPU_ARCH} ")
set(GPU_CUDA_GENCODE "-arch=${GPU_ARCH}")
# Fermi (GPU Arch 2.x) is supported by CUDA 3.2 to CUDA 8.0
if((CUDA_VERSION VERSION_GREATER "3.1") AND (CUDA_VERSION VERSION_LESS "9.0"))
string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_20,code=[sm_20,compute_20] ")
if((CUDA_VERSION VERSION_GREATER_EQUAL "3.2") AND (CUDA_VERSION VERSION_LESS "9.0"))
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_20,code=[sm_20,compute_20] ")
endif()
# Kepler (GPU Arch 3.x) is supported by CUDA 5 and later
if(CUDA_VERSION VERSION_GREATER "4.9")
string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_30,code=[sm_30,compute_30] -gencode arch=compute_35,code=[sm_35,compute_35] ")
# Kepler (GPU Arch 3.0) is supported by CUDA 5 to CUDA 10.2
if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "11.0"))
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30] ")
endif()
# Kepler (GPU Arch 3.5) is supported by CUDA 5 to CUDA 11
if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "12.0"))
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30] -gencode arch=compute_35,code=[sm_35,compute_35]")
endif()
# Maxwell (GPU Arch 5.x) is supported by CUDA 6 and later
if(CUDA_VERSION VERSION_GREATER "5.9")
string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52] ")
if(CUDA_VERSION VERSION_GREATER_EQUAL "6.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52]")
endif()
# Pascal (GPU Arch 6.x) is supported by CUDA 8 and later
if(CUDA_VERSION VERSION_GREATER "7.9")
string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61] ")
if(CUDA_VERSION VERSION_GREATER_EQUAL "8.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61]")
endif()
# Volta (GPU Arch 7.0) is supported by CUDA 9 and later
if(CUDA_VERSION VERSION_GREATER "8.9")
string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_70,code=[sm_70,compute_70] ")
if(CUDA_VERSION VERSION_GREATER_EQUAL "9.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_70,code=[sm_70,compute_70]")
endif()
# Turing (GPU Arch 7.5) is supported by CUDA 10 and later
if(CUDA_VERSION VERSION_GREATER "9.9")
string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_75,code=[sm_75,compute_75] ")
if(CUDA_VERSION VERSION_GREATER_EQUAL "10.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_75,code=[sm_75,compute_75]")
endif()
# Ampere (GPU Arch 8.0) is supported by CUDA 11 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_80,code=[sm_80,compute_80]")
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}
@ -226,30 +237,41 @@ elseif(GPU_API STREQUAL "HIP")
# build arch/gencode commands for nvcc based on CUDA toolkit version and use choice
# --arch translates directly instead of JIT, so this should be for the preferred or most common architecture
set(HIP_CUDA_GENCODE "-arch=${HIP_ARCH} ")
set(HIP_CUDA_GENCODE "-arch=${HIP_ARCH}")
# Fermi (GPU Arch 2.x) is supported by CUDA 3.2 to CUDA 8.0
if((CUDA_VERSION VERSION_GREATER "3.1") AND (CUDA_VERSION VERSION_LESS "9.0"))
string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_20,code=[sm_20,compute_20] ")
if((CUDA_VERSION VERSION_GREATER_EQUAL "3.2") AND (CUDA_VERSION VERSION_LESS "9.0"))
string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_20,code=[sm_20,compute_20]")
endif()
# Kepler (GPU Arch 3.x) is supported by CUDA 5 and later
if(CUDA_VERSION VERSION_GREATER "4.9")
string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_30,code=[sm_30,compute_30] -gencode arch=compute_35,code=[sm_35,compute_35] ")
# Kepler (GPU Arch 3.0) is supported by CUDA 5 to CUDA 10.2
if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "11.0"))
string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30]")
endif()
# Kepler (GPU Arch 3.5) is supported by CUDA 5 to CUDA 11.0
if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "12.0"))
string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_35,code=[sm_35,compute_35]")
endif()
# Maxwell (GPU Arch 5.x) is supported by CUDA 6 and later
if(CUDA_VERSION VERSION_GREATER "5.9")
string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52] ")
if(CUDA_VERSION VERSION_GREATER_EQUAL "6.0")
string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52]")
endif()
# Pascal (GPU Arch 6.x) is supported by CUDA 8 and later
if(CUDA_VERSION VERSION_GREATER "7.9")
string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61] ")
if(CUDA_VERSION VERSION_GREATER_EQUAL "8.0")
string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61]")
endif()
# Volta (GPU Arch 7.0) is supported by CUDA 9 and later
if(CUDA_VERSION VERSION_GREATER "8.9")
string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_70,code=[sm_70,compute_70] ")
if(CUDA_VERSION VERSION_GREATER_EQUAL "9.0")
string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_70,code=[sm_70,compute_70]")
endif()
# Turing (GPU Arch 7.5) is supported by CUDA 10 and later
if(CUDA_VERSION VERSION_GREATER "9.9")
string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_75,code=[sm_75,compute_75] ")
if(CUDA_VERSION VERSION_GREATER_EQUAL "10.0")
string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_75,code=[sm_75,compute_75]")
endif()
# Ampere (GPU Arch 8.0) is supported by CUDA 11 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.0")
string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_80,code=[sm_80,compute_80]")
endif()
if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
message(WARNING "Unsupported CUDA version. Use at your own risk.")
endif()
endif()

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

@ -35,8 +35,8 @@ if(DOWNLOAD_KOKKOS)
list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}")
include(ExternalProject)
ExternalProject_Add(kokkos_build
URL https://github.com/kokkos/kokkos/archive/3.1.01.tar.gz
URL_MD5 3ccb2100f7fc316891e7dad3bc33fa37
URL https://github.com/kokkos/kokkos/archive/3.2.00.tar.gz
URL_MD5 81569170fe232e5e64ab074f7cca5e50
CMAKE_ARGS ${KOKKOS_LIB_BUILD_ARGS}
BUILD_BYPRODUCTS <INSTALL_DIR>/lib/libkokkoscore.a
)
@ -50,7 +50,7 @@ if(DOWNLOAD_KOKKOS)
target_link_libraries(lammps PRIVATE LAMMPS::KOKKOS)
add_dependencies(LAMMPS::KOKKOS kokkos_build)
elseif(EXTERNAL_KOKKOS)
find_package(Kokkos 3.1.01 REQUIRED CONFIG)
find_package(Kokkos 3.2.00 REQUIRED CONFIG)
target_link_libraries(lammps PRIVATE Kokkos::kokkos)
else()
set(LAMMPS_LIB_KOKKOS_SRC_DIR ${LAMMPS_LIB_SOURCE_DIR}/kokkos)

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

@ -9,8 +9,8 @@ if(DOWNLOAD_EIGEN3)
message(STATUS "Eigen3 download requested - we will build our own")
include(ExternalProject)
ExternalProject_Add(Eigen3_build
URL https://bitbucket.org/eigen/eigen/get/3.3.7.tar.gz
URL_MD5 f2a417d083fe8ca4b8ed2bc613d20f07
URL https://gitlab.com/libeigen/eigen/-/archive/3.3.7/eigen-3.3.7.tar.gz
URL_MD5 9e30f67e8531477de4117506fe44669b
CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
)
ExternalProject_get_property(Eigen3_build SOURCE_DIR)

30
cmake/Modules/Testing.cmake
View File

@ -16,6 +16,36 @@ 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"))
include(CheckCXXCompilerFlag)
set(CMAKE_CUSTOM_LINKER_DEFAULT default)
check_cxx_compiler_flag(-fuse-ld=lld HAVE_LLD_LINKER_FLAG)
check_cxx_compiler_flag(-fuse-ld=gold HAVE_GOLD_LINKER_FLAG)
check_cxx_compiler_flag(-fuse-ld=bfd HAVE_BFD_LINKER_FLAG)
find_program(HAVE_LLD_LINKER_BIN lld ld.lld)
find_program(HAVE_GOLD_LINKER_BIN ld.gold)
find_program(HAVE_BFD_LINKER_BIN ld.bfd)
if(HAVE_LLD_LINKER_FLAG AND HAVE_LLD_LINKER_BIN)
set(CMAKE_CUSTOM_LINKER_DEFAULT lld)
elseif(HAVE_GOLD_LINKER_FLAG AND HAVE_GOLD_LINKER_BIN)
set(CMAKE_CUSTOM_LINKER_DEFAULT gold)
elseif(HAVE_BFD_LINKER_FLAG AND HAVE_BFD_LINKER_BIN)
set(CMAKE_CUSTOM_LINKER_DEFAULT bfd)
endif()
set(CMAKE_CUSTOM_LINKER_VALUES lld gold bfd default)
set(CMAKE_CUSTOM_LINKER ${CMAKE_CUSTOM_LINKER_DEFAULT} CACHE STRING "Choose a custom linker for faster linking (lld, gold, bfd, default)")
validate_option(CMAKE_CUSTOM_LINKER CMAKE_CUSTOM_LINKER_VALUES)
mark_as_advanced(CMAKE_CUSTOM_LINKER)
if(NOT "${CMAKE_CUSTOM_LINKER}" STREQUAL "default")
target_link_options(lammps PUBLIC -fuse-ld=${CMAKE_CUSTOM_LINKER})
endif()
endif()
endif()
include(CTest)
enable_testing()

7
doc/.gitignore vendored
View File

@ -1,6 +1,7 @@
/old
/html
/html-offline
/epub
/latex
/mathjax
/spelling
@ -10,3 +11,9 @@
/Developer.pdf
/doctrees
/docenv
/doxygen-warn.log
/utils/sphinx-config/conf.py
/doxygen/Doxyfile
*.el
/utils/sphinx-config/_static/mathjax
/utils/sphinx-config/_static/polyfill.js

108
doc/Makefile
View File

@ -1,21 +1,29 @@
# Makefile for LAMMPS documentation
SHELL = /bin/bash
BUILDDIR = ${CURDIR}
RSTDIR = $(BUILDDIR)/src
VENV = $(BUILDDIR)/docenv
MATHJAX = $(BUILDDIR)/mathjax
TXT2RST = $(VENV)/bin/txt2rst
ANCHORCHECK = $(VENV)/bin/rst_anchor_check
SHELL = /bin/bash
BUILDDIR = ${CURDIR}
RSTDIR = $(BUILDDIR)/src
VENV = $(BUILDDIR)/docenv
TXT2RST = $(VENV)/bin/txt2rst
ANCHORCHECK = $(VENV)/bin/rst_anchor_check
SPHINXCONFIG = $(BUILDDIR)/utils/sphinx-config
MATHJAX = $(SPHINXCONFIG)/_static/mathjax
POLYFILL = $(SPHINXCONFIG)/_static/polyfill.js
PYTHON = $(shell which python3)
PYTHON = $(shell which python3)
DOXYGEN = $(shell which doxygen)
VIRTUALENV = virtualenv
HAS_PYTHON3 = NO
HAS_VIRTUALENV = NO
HAS_DOXYGEN = NO
HAS_PDFLATEX = NO
ifeq ($(shell which python3 >/dev/null 2>&1; echo $$?), 0)
HAS_PYTHON3 = YES
HAS_PYTHON3 = YES
endif
ifeq ($(shell which doxygen >/dev/null 2>&1; echo $$?), 0)
HAS_DOXYGEN = YES
endif
ifeq ($(shell which virtualenv-3 >/dev/null 2>&1; echo $$?), 0)
@ -33,9 +41,13 @@ HAS_PDFLATEX = YES
endif
SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())')
SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') $(shell test -f $(BUILDDIR)/doxygen/xml/run.stamp && printf -- "-E")
.PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check
# grab list of sources from doxygen config file.
# we only want to use explicitly listed files.
DOXYFILES = $(shell sed -n -e 's/\#.*$$//' -e '/^ *INPUT \+=/,/^[A-Z_]\+ \+=/p' doxygen/Doxyfile.in | sed -e 's/@LAMMPS_SOURCE_DIR@/..\/src/g' -e 's/\\//g' -e 's/ \+/ /' -e 's/[A-Z_]\+ \+= *\(YES\|NO\|\)//')
.PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check xmlgen
# ------------------------------------------
@ -57,23 +69,32 @@ help:
# ------------------------------------------
clean-all: clean
rm -rf $(BUILDDIR)/docenv $(BUILDDIR)/doctrees $(BUILDDIR)/mathjax Manual.pdf Developer.pdf
rm -rf $(BUILDDIR)/docenv $(MATHJAX) $(BUILDDIR)/LAMMPS.mobi $(BUILDDIR)/LAMMPS.epub $(BUILDDIR)/Manual.pdf $(BUILDDIR)/Developer.pdf
clean: clean-spelling
rm -rf html epub latex
rm -rf $(BUILDDIR)/html $(BUILDDIR)/epub $(BUILDDIR)/latex $(BUILDDIR)/doctrees $(BUILDDIR)/doxygen/xml $(BUILDDIR)/doxygen-warn.log $(BUILDDIR)/doxygen/Doxyfile $(SPHINXCONFIG)/conf.py
clean-spelling:
rm -rf spelling
rm -rf $(BUILDDIR)/spelling
html: $(ANCHORCHECK) $(MATHJAX)
$(SPHINXCONFIG)/conf.py: $(SPHINXCONFIG)/conf.py.in
sed -e 's,@DOXYGEN_XML_DIR@,$(BUILDDIR)/doxygen/xml,g' \
-e 's,@LAMMPS_SOURCE_DIR@,$(BUILDDIR)/../src,g' \
-e 's,@LAMMPS_PYTHON_DIR@,$(BUILDDIR)/../python,g' \
-e 's,@LAMMPS_DOC_DIR@,$(BUILDDIR),g' $< > $@
html: xmlgen $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX) $(POLYFILL)
@$(MAKE) $(MFLAGS) -C graphviz all
@(\
. $(VENV)/bin/activate ;\
sphinx-build $(SPHINXEXTRA) -b html -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
sphinx-build $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
ln -sf Manual.html html/index.html;\
rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
echo "############################################" ;\
rst_anchor_check src/*.rst ;\
python utils/check-packages.py -s ../src -d src ;\
python $(BUILDDIR)/utils/check-packages.py -s ../src -d src ;\
env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\
python utils/check-styles.py -s ../src -d src ;\
python $(BUILDDIR)/utils/check-styles.py -s ../src -d src ;\
echo "############################################" ;\
deactivate ;\
)
@ -82,30 +103,28 @@ html: $(ANCHORCHECK) $(MATHJAX)
@rm -rf html/USER
@rm -rf html/JPG
@cp -r src/PDF html/PDF
@mkdir -p html/JPG
@cp `grep -A2 '\.\. .*\(image\|figure\)::' src/*.rst | grep ':target:' | sed -e 's,.*:target: JPG/,src/JPG/,' | sort | uniq` html/JPG/
@rm -rf html/PDF/.[sg]*
@mkdir -p html/_static/mathjax
@cp -r $(MATHJAX)/es5 html/_static/mathjax/
@echo "Build finished. The HTML pages are in doc/html."
spelling: $(VENV) utils/sphinx-config/false_positives.txt
spelling: xmlgen $(VENV) $(SPHINXCONFIG)/false_positives.txt
@(\
. $(VENV)/bin/activate ;\
cp utils/sphinx-config/false_positives.txt $(RSTDIR)/ ; env PYTHONWARNINGS= \
sphinx-build -b spelling -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\
. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
cp $(SPHINXCONFIG)/false_positives.txt $(RSTDIR)/ ; env PYTHONWARNINGS= \
sphinx-build -b spelling -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\
rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
deactivate ;\
)
@echo "Spell check finished."
epub: $(VENV)
epub: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK)
@$(MAKE) $(MFLAGS) -C graphviz all
@mkdir -p epub/JPG
@rm -f LAMMPS.epub
@cp src/JPG/lammps-logo.png epub/
@cp src/JPG/*.* epub/JPG
@(\
. $(VENV)/bin/activate ;\
sphinx-build $(SPHINXEXTRA) -b epub -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\
sphinx-build $(SPHINXEXTRA) -b epub -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\
rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
deactivate ;\
)
@mv epub/LAMMPS.epub .
@ -117,7 +136,8 @@ mobi: epub
@ebook-convert LAMMPS.epub LAMMPS.mobi
@echo "Conversion finished. The MOBI manual file is created."
pdf: $(ANCHORCHECK)
pdf: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK)
@$(MAKE) $(MFLAGS) -C graphviz all
@if [ "$(HAS_PDFLATEX)" == "NO" ] ; then echo "PDFLaTeX was not found! Please check README.md for further instructions" 1>&2; exit 1; fi
@(\
cd src/Developer; \
@ -127,8 +147,9 @@ pdf: $(ANCHORCHECK)
cd ../../; \
)
@(\
. $(VENV)/bin/activate ;\
sphinx-build $(SPHINXEXTRA) -b latex -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\
. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
sphinx-build $(SPHINXEXTRA) -b latex -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\
rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
echo "############################################" ;\
rst_anchor_check src/*.rst ;\
python utils/check-packages.py -s ../src -d src ;\
@ -185,23 +206,32 @@ package_check : $(VENV)
deactivate ;\
)
xmlgen : doxygen/xml/index.xml
doxygen/Doxyfile: doxygen/Doxyfile.in
sed -e 's/@LAMMPS_SOURCE_DIR@/..\/..\/src/g' $< > $@
doxygen/xml/index.xml : $(VENV) doxygen/Doxyfile $(DOXYFILES)
@(cd doxygen; $(DOXYGEN) Doxyfile && touch xml/run.stamp)
# ------------------------------------------
$(VENV):
@if [ "$(HAS_PYTHON3)" == "NO" ] ; then echo "Python3 was not found! Please check README.md for further instructions" 1>&2; exit 1; fi
@if [ "$(HAS_VIRTUALENV)" == "NO" ] ; then echo "virtualenv was not found! Please check README.md for further instructions" 1>&2; exit 1; fi
@if [ "$(HAS_PYTHON3)" == "NO" ] ; then echo "python3 was not found! Please see README for further instructions" 1>&2; exit 1; fi
@if [ "$(HAS_DOXYGEN)" == "NO" ] ; then echo "doxygen was not found! Please see README for further instructions" 1>&2; exit 1; fi
@if [ "$(HAS_VIRTUALENV)" == "NO" ] ; then echo "virtualenv was not found! Please see README for further instructions" 1>&2; exit 1; fi
@( \
$(VIRTUALENV) -p $(PYTHON) $(VENV); \
. $(VENV)/bin/activate; \
pip install --upgrade pip; \
pip install Sphinx; \
pip install sphinxcontrib-spelling ;\
pip install breathe; \
pip install --use-feature=2020-resolver -r $(BUILDDIR)/utils/requirements.txt; \
deactivate;\
)
$(MATHJAX):
@git clone --depth 1 https://github.com/mathjax/MathJax.git mathjax
@git clone --depth 1 https://github.com/mathjax/MathJax.git $@
$(POLYFILL): $(MATHJAX)
@curl -s -o $@ "https://polyfill.io/v3/polyfill.min.js?features=es6"
$(TXT2RST) $(ANCHORCHECK): $(VENV)
@( \

148
doc/README
View File

@ -1,97 +1,60 @@
LAMMPS Documentation
Depending on how you obtained LAMMPS, this directory has 2 or 3
sub-directories and optionally 2 PDF files and an ePUB file:
Depending on how you obtained LAMMPS and whether you have built
the manual yourself, this directory has a varying number of
sub-directories and files. Here is a list with descriptions:
src content files for LAMMPS documentation
html HTML version of the LAMMPS manual (see html/Manual.html)
utils utilities and settings for building the documentation
Manual.pdf large PDF version of entire manual
Developer.pdf small PDF with info about how LAMMPS is structured
LAMMPS.epub Manual in ePUB format
README this file
src content files for LAMMPS documentation
html HTML version of the LAMMPS manual (see html/Manual.html)
utils utilities and settings for building the documentation
Manual.pdf PDF version of entire manual
Developer.pdf PDF with info about how LAMMPS is structured
LAMMPS.epub Manual in ePUB format
LAMMPS.mobi Manual in MOBI (Kindle) format
lammps.1 man page for the lammps command
msi2lmp.1 man page for the msi2lmp command
mathjax code and fonts for rendering math in html
doctree temporary data
docenv python virtual environment for generating the manual
doxygen Doxygen configuration and output
.gitignore list of files and folders to be ignored by git
doxygen-warn.log logfile with warnings from running doxygen
If you downloaded LAMMPS as a tarball from the web site, all these
directories and files should be included.
and:
If you downloaded LAMMPS from the public SVN or Git repositories, then
the HTML and PDF files are not included. Instead you need to create
them, in one of three ways:
github-development-workflow.md notes on the LAMMPS development workflow
include-file-conventions.md notes on LAMMPS' include file conventions
documentation_conventions.md notes on writing documentation for LAMMPS
If you downloaded a LAMMPS tarball from lammps.sandia.gov, then the html
folder and the PDF manual should be included. If you downloaded LAMMPS
from GitHub then you either need to download them or build them.
(a) You can "fetch" the current HTML and PDF files from the LAMMPS web
site. Just type "make fetch". This should create a html_www dir and
Manual_www.pdf/Developer_www.pdf files. Note that if new LAMMPS
features have been added more recently than the date of your version,
the fetched documentation will include those changes (but your source
code will not, unless you update your local repository).
Manual_www.pdf/Developer_www.pdf files. These files will always
represent the latest published patch/development version of LAMMPS.
(b) You can build the HTML and PDF files yourself, by typing "make
html" or by "make pdf", respectively. This requires various tools
including the Python documentation processing tool Sphinx, which the
build process will attempt to download and install on your system into
a python virtual environment, if not already available. The PDF file
will require a working LaTeX installation with several add-on packages
in addition to the Python/Sphinx setup. See more details below.
(b) You can build the HTML and PDF files yourself, by typing "make html"
or by "make pdf", respectively. This requires various tools and files.
Some of them have to be installed (more on that below). For the rest the
build process will attempt to download and install into a python virtual
environment and local folders.
----------------
The generation of all documentation is managed by the Makefile in this
dir.
Installing prerequisites for the documentation build
Options:
To run the HTML documention build toolchain, python 3.x, doxygen, git,
and virtualenv have to be installed. Also internet access is initially
required to download external files and tools.
make html # generate HTML in html dir using Sphinx
make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf)
# in this dir via Sphinx and PDFLaTeX
make fetch # fetch HTML doc pages and 2 PDF files from web site
# as a tarball and unpack into html dir and 2 PDFs
make epub # generate LAMMPS.epub in ePUB format using Sphinx
make clean # remove intermediate RST files created by HTML build
make clean-all # remove entire build folder and any cached data
----------------
Installing prerequisites for HTML build
To run the HTML documention build toolchain, Python 3 and virtualenv
have to be installed. Here are instructions for common setups:
# Ubuntu
sudo apt-get install python-virtualenv
# Fedora (up to version 21)
# Red Hat Enterprise Linux or CentOS (up to version 7.x)
sudo yum install python3-virtualenv
# Fedora (since version 22)
sudo dnf install python3-virtualenv
# MacOS X
## Python 3
Download the latest Python 3 MacOS X package from
https://www.python.org and install it. This will install both Python
3 and pip3.
## virtualenv
Once Python 3 is installed, open a Terminal and type
pip3 install virtualenv
This will install virtualenv from the Python Package Index.
----------------
Installing prerequisites for PDF build
Same as for HTML plus a compatible LaTeX installation with
support for PDFLaTeX. Also the following LaTeX packages need
to be installed (e.g. from texlive):
Building the PDF format manual requires in addition a compatible LaTeX
installation with support for PDFLaTeX and several add-on LaTeX packages
installed. This includes:
- amsmath
- anysize
- babel
- capt-of
- cmap
@ -105,24 +68,13 @@ to be installed (e.g. from texlive):
- tabulary
- upquote
- wrapfig
Building the EPUB format requires LaTeX installation with the same packages
as for the PDF format plus the 'dvipng' command to convert the embedded math
into images. The MOBI format is generated from the EPUB format file by using
the tool 'ebook-convert' from the 'calibre' e-book management software
(https://calibre-ebook.com).
----------------
Installing prerequisites for epub build
## ePUB
Same as for HTML. This uses the same tools and configuration
files as the HTML tree. The ePUB format conversion currently
does not support processing mathematical expressions via MathJAX,
so there will be limitations on some pages. For the time being
until this is resolved, building and using the PDF format file
is recommended instead.
For converting the generated ePUB file to a mobi format file
(for e-book readers like Kindle, that cannot read ePUB), you
also need to have the 'ebook-convert' tool from the "calibre"
software installed. http://calibre-ebook.com/
You first create the ePUB file with 'make epub' and then do:
ebook-convert LAMMPS.epub LAMMPS.mobi
More details this can be found in the manual itself. The online
version is at: https://lammps.sandia.gov/doc/Manual_build.html

93
doc/documentation_conventions.md Normal file
View File

@ -0,0 +1,93 @@
# Outline of LAMMPS documentation file conventions
This purpose of this document is to provide a point of reference
for LAMMPS developers and contributors as to what conventions
should be used to structure and format files in the LAMMPS manual.
Last change: 2020-04-23
## File format and tools
In fall 2019, the LAMMPS documentation file format has changed from
a home grown minimal markup designed to generate HTML format files
from a mostly plain text format to using the reStructuredText file
format. For a transition period all files in the old .txt format
were transparently converted to .rst and then processed. The txt2rst
tool is still included in the distribution to obtain an initial .rst
file for integration into the manual. Since the transition to
reStructured text as source format, many of the artifacts or the
translation have been removed though and parts of the documentation
refactored and expanded to take advantage of the capabilities
reStructuredText and associated tools. The conversion from the
source to the final formats (HTML, PDF, and optionally e-book
reader formats ePUB and MOBI) is mostly automated and controlled
by a Makefile in the `doc` folder. This makefile assumes that the
processing is done on a Unix-like machine and Python 3.5 or later
and a matching virtualenv module are available. Additional Python
packages (like the Sphinx tool and several extensions) are
transparently installed into a virtual environment over the
internet using the `pip` package manager. Further requirements
and details are discussed in the manual.
## Work in progress
The refactoring and improving of the documentation is an ongoing
process, so statements in this document may not always be fully
up-to-date. If in doubt, contact the LAMMPS developers.
## General structure
The layout and formatting of added files should follow the example
of the existing files. Since those are directly derived from their
former .txt format versions and the manual has been maintained in
that format for many years, there is a large degree of consistency
already, so comparision with similar files should give you a good
idea what kind of information and sections are needed.
## Formatting conventions
Filenames, folders, paths, (shell) commands, definitions, makefile
settings and similar should be formatted as "literals" with
double backward quotes bracketing the item: \`\`path/to/some/file\`\`
Keywords and options are formatted in italics: \*option\*
Mathematical expressions, equations, symbols are typeset using
either a `.. math:`` block or the `:math:` role.
Groups of shell commands or LAMMPS input script or C/C++ source
code should be typeset into a `.. code-block::` section. A syntax
highlighting extension for LAMMPS input scripts is provided, so
`LAMMPS` can be used to indicate the language in the code block
in addition to `bash`, `c`, or `python`. When no syntax style
is indicated, no syntax highlighting is performed.
As an alternative, e.g. to typeset the syntax of file formats
a `.. parsed-literal::` block can be used, which allows some
formatting directives, which means that related characters need
to be escaped with a preceding backslash: `\*`.
Special remarks can be highlighted with a `.. note::` block and
strong warnings can be put into a `.. warning::` block.
## Required steps when adding a custom style to LAMMPS
When adding a new style (e.g. pair style or a compute or a fix)
or a new command, it is **required** to include the corresponding
documentation. Those are often new files that need to be added.
In order to be included in the documentation, those new files
need to be reference in a `.. toctree::` block. Most of those
use patterns with wildcards, so the addition will be automatic.
However, those additions also need to be added to some lists of
styles or commands. The `make style\_check` command will perform
a test and report any missing entries and list the affected files.
Any references defined with `.. \_refname:` have to be unique
across all documentation files and this can be checked for with
`make anchor\_check`. Finally, a spell-check should be done,
which is triggered via `make spelling`. Any offenses need to
be corrected and false positives should be added to the file
`utils/sphinx-config/false\_positives.txt`.
## Required additional steps when adding a new package to LAMMPS
TODO

1
doc/doxygen/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
/xml

522
doc/doxygen/Doxyfile.in Normal file
View File

@ -0,0 +1,522 @@
# Doxyfile 1.8.15 -*- makefile -*-
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = "LAMMPS Programmer's Guide"
PROJECT_NUMBER = "24 August 2020"
PROJECT_BRIEF = "Documentation of the LAMMPS library interface and Python wrapper"
PROJECT_LOGO = lammps-logo.png
CREATE_SUBDIRS = NO
ALLOW_UNICODE_NAMES = NO
OUTPUT_LANGUAGE = English
OUTPUT_TEXT_DIRECTION = LTR
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ALWAYS_DETAILED_SEC = NO
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = NO
INHERIT_DOCS = YES
TAB_SIZE = 2
# When enabled doxygen tries to link words that correspond to documented
# classes, or namespaces to their corresponding documentation. Such a link can
# be prevented in individual cases by putting a % sign in front of the word or
# globally by setting AUTOLINK_SUPPORT to NO.
# The default value is: YES.
AUTOLINK_SUPPORT = YES
# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
# to include (a tag file for) the STL sources as input, then you should set this
# tag to YES in order to let doxygen match functions declarations and
# definitions whose arguments contain STL classes (e.g. func(std::string);
# versus func(std::string) {}). This also make the inheritance and collaboration
# diagrams that involve STL classes more complete and accurate.
# The default value is: NO.
BUILTIN_STL_SUPPORT = YES
IDL_PROPERTY_SUPPORT = NO
# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This
# cache is used to resolve symbols given their name and scope. Since this can be
# an expensive process and often the same symbol appears multiple times in the
# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small
# doxygen will become slower. If the cache is too large, memory is wasted. The
# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range
# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536
# symbols. At the end of a run doxygen will report the cache usage and suggest
# the optimal cache size from a speed point of view.
# Minimum value: 0, maximum value: 9, default value: 0.
LOOKUP_CACHE_SIZE = 2
#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------
# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in
# documentation are documented, even if no documentation was available. Private
# class members and static file members will be hidden unless the
# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES.
# Note: This will also disable the warnings about undocumented members that are
# normally produced when WARNINGS is set to YES.
# The default value is: NO.
EXTRACT_ALL = NO
# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
# be included in the documentation.
# The default value is: NO.
EXTRACT_PRIVATE = YES
# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal
# scope will be included in the documentation.
# The default value is: NO.
EXTRACT_PACKAGE = YES
# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be
# included in the documentation.
# The default value is: NO.
EXTRACT_STATIC = YES
# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
# locally in source files will be included in the documentation. If set to NO,
# only classes defined in header files are included. Does not have any effect
# for Java sources.
# The default value is: YES.
EXTRACT_LOCAL_CLASSES = YES
# If this flag is set to YES, the members of anonymous namespaces will be
# extracted and appear in the documentation as a namespace called
# 'anonymous_namespace{file}', where file will be replaced with the base name of
# the file that contains the anonymous namespace. By default anonymous namespace
# are hidden.
# The default value is: NO.
EXTRACT_ANON_NSPACES = YES
# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all
# undocumented members inside documented classes or files. If set to NO these
# members will be included in the various overviews, but no documentation
# section is generated. This option has no effect if EXTRACT_ALL is enabled.
# The default value is: NO.
HIDE_UNDOC_MEMBERS = YES
# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
# undocumented classes that are normally visible in the class hierarchy. If set
# to NO, these classes will be included in the various overviews. This option
# has no effect if EXTRACT_ALL is enabled.
# The default value is: NO.
HIDE_UNDOC_CLASSES = YES
# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend
# (class|struct|union) declarations. If set to NO, these declarations will be
# included in the documentation.
# The default value is: NO.
HIDE_FRIEND_COMPOUNDS = NO
# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any
# documentation blocks found inside the body of a function. If set to NO, these
# blocks will be appended to the function's detailed documentation block.
# The default value is: NO.
HIDE_IN_BODY_DOCS = NO
# The INTERNAL_DOCS tag determines if documentation that is typed after a
# \internal command is included. If the tag is set to NO then the documentation
# will be excluded. Set it to YES to include the internal documentation.
# The default value is: NO.
INTERNAL_DOCS = NO
# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file
# names in lower-case letters. If set to YES, upper-case letters are also
# allowed. This is useful if you have classes or files whose names only differ
# in case and if your file system supports case sensitive file names. Windows
# and Mac users are advised to set this option to NO.
# The default value is: system dependent.
CASE_SENSE_NAMES = YES
# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with
# their full class and namespace scopes in the documentation. If set to YES, the
# scope will be hidden.
# The default value is: NO.
HIDE_SCOPE_NAMES = YES
# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will
# append additional text to a page's title, such as Class Reference. If set to
# YES the compound reference will be hidden.
# The default value is: NO.
HIDE_COMPOUND_REFERENCE= NO
# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of
# the files that are included by a file in the documentation of that file.
# The default value is: YES.
SHOW_INCLUDE_FILES = NO
# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
# grouped member an include statement to the documentation, telling the reader
# which file to include in order to use the member.
# The default value is: NO.
SHOW_GROUPED_MEMB_INC = NO
# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include
# files with double quotes in the documentation rather than with sharp brackets.
# The default value is: NO.
FORCE_LOCAL_INCLUDES = NO
# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the
# documentation for inline members.
# The default value is: YES.
INLINE_INFO = YES
# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the
# (detailed) documentation of file and class members alphabetically by member
# name. If set to NO, the members will appear in declaration order.
# The default value is: YES.
SORT_MEMBER_DOCS = NO
# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
# descriptions of file, namespace and class members alphabetically by member
# name. If set to NO, the members will appear in declaration order. Note that
# this will also influence the order of the classes in the class list.
# The default value is: NO.
SORT_BRIEF_DOCS = NO
# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
# (brief and detailed) documentation of class members so that constructors and
# destructors are listed first. If set to NO the constructors will appear in the
# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS.
# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief
# member documentation.
# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting
# detailed member documentation.
# The default value is: NO.
SORT_MEMBERS_CTORS_1ST = NO
# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
# of group names into alphabetical order. If set to NO the group names will
# appear in their defined order.
# The default value is: NO.
SORT_GROUP_NAMES = NO
# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
# fully-qualified names, including namespaces. If set to NO, the class list will
# be sorted only by class name, not including the namespace part.
# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
# Note: This option applies only to the class list, not to the alphabetical
# list.
# The default value is: NO.
SORT_BY_SCOPE_NAME = NO
# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper
# type resolution of all parameters of a function it will reject a match between
# the prototype and the implementation of a member function even if there is
# only one candidate or it is obvious which candidate to choose by doing a
# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still
# accept a match between prototype and implementation in such cases.
# The default value is: NO.
STRICT_PROTO_MATCHING = NO
# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo
# list. This list is created by putting \todo commands in the documentation.
# The default value is: YES.
GENERATE_TODOLIST = YES
# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test
# list. This list is created by putting \test commands in the documentation.
# The default value is: YES.
GENERATE_TESTLIST = YES
# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug
# list. This list is created by putting \bug commands in the documentation.
# The default value is: YES.
GENERATE_BUGLIST = YES
# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO)
# the deprecated list. This list is created by putting \deprecated commands in
# the documentation.
# The default value is: YES.
GENERATE_DEPRECATEDLIST= YES
# The ENABLED_SECTIONS tag can be used to enable conditional documentation
# sections, marked by \if <section_label> ... \endif and \cond <section_label>
# ... \endcond blocks.
ENABLED_SECTIONS =
# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the
# initial value of a variable or macro / define can have for it to appear in the
# documentation. If the initializer consists of more lines than specified here
# it will be hidden. Use a value of 0 to hide initializers completely. The
# appearance of the value of individual variables and macros / defines can be
# controlled using \showinitializer or \hideinitializer command in the
# documentation regardless of this setting.
# Minimum value: 0, maximum value: 10000, default value: 30.
MAX_INITIALIZER_LINES = 30
# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at
# the bottom of the documentation of classes and structs. If set to YES, the
# list will mention the files that were used to generate the documentation.
# The default value is: YES.
SHOW_USED_FILES = YES
# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This
# will remove the Files entry from the Quick Index and from the Folder Tree View
# (if specified).
# The default value is: YES.
SHOW_FILES = NO
# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces
# page. This will remove the Namespaces entry from the Quick Index and from the
# Folder Tree View (if specified).
# The default value is: YES.
SHOW_NAMESPACES = YES
# The FILE_VERSION_FILTER tag can be used to specify a program or script that
# doxygen should invoke to get the current version for each file (typically from
# the version control system). Doxygen will invoke the program by executing (via
# popen()) the command command input-file, where command is the value of the
# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided
# by doxygen. Whatever the program writes to standard output is used as the file
# version. For an example see the documentation.
FILE_VERSION_FILTER =
# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed
# by doxygen. The layout file controls the global structure of the generated
# output files in an output format independent way. To create the layout file
# that represents doxygen's defaults, run doxygen with the -l option. You can
# optionally specify a file name after the option, if omitted DoxygenLayout.xml
# will be used as the name of the layout file.
#
# Note that if you run doxygen from a directory containing a file called
# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
# tag is left empty.
LAYOUT_FILE =
# The CITE_BIB_FILES tag can be used to specify one or more bib files containing
# the reference definitions. This must be a list of .bib files. The .bib
# extension is automatically appended if omitted. This requires the bibtex tool
# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info.
# For LaTeX the style of the bibliography can be controlled using
# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the
# search path. See also \cite for info how to create references.
CITE_BIB_FILES =
#---------------------------------------------------------------------------
# Configuration options related to warning and progress messages
#---------------------------------------------------------------------------
# The QUIET tag can be used to turn on/off the messages that are generated to
# standard output by doxygen. If QUIET is set to YES this implies that the
# messages are off.
# The default value is: NO.
QUIET = NO
# The WARNINGS tag can be used to turn on/off the warning messages that are
# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
# this implies that the warnings are on.
#
# Tip: Turn warnings on while writing the documentation.
# The default value is: YES.
WARNINGS = YES
# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate
# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag
# will automatically be disabled.
# The default value is: YES.
WARN_IF_UNDOCUMENTED = YES
# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
# potential errors in the documentation, such as not documenting some parameters
# in a documented function, or documenting parameters that don't exist or using
# markup commands wrongly.
# The default value is: YES.
WARN_IF_DOC_ERROR = YES
# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that
# are documented, but have no documentation for their parameters or return
# value. If set to NO, doxygen will only warn about wrong or incomplete
# parameter documentation, but not about the absence of documentation. If
# EXTRACT_ALL is set to YES then this flag will automatically be disabled.
# The default value is: NO.
WARN_NO_PARAMDOC = YES
# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when
# a warning is encountered.
# The default value is: NO.
WARN_AS_ERROR = NO
# The WARN_FORMAT tag determines the format of the warning messages that doxygen
# can produce. The string should contain the $file, $line, and $text tags, which
# will be replaced by the file and line number from which the warning originated
# and the warning text. Optionally the format may contain $version, which will
# be replaced by the version of the file (if it could be obtained via
# FILE_VERSION_FILTER)
# The default value is: $file:$line: $text.
WARN_FORMAT = "$file:$line: $text"
# The WARN_LOGFILE tag can be used to specify a file to which warning and error
# messages should be written. If left blank the output is written to standard
# error (stderr).
WARN_LOGFILE = "../doxygen-warn.log"
#---------------------------------------------------------------------------
# Configuration options related to the input files
#---------------------------------------------------------------------------
# The INPUT tag is used to specify the files and/or directories that contain
# documented source files. You may enter file names like myfile.cpp or
# directories like /usr/src/myproject. Separate the files or directories with
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
INPUT = @LAMMPS_SOURCE_DIR@/utils.cpp \
@LAMMPS_SOURCE_DIR@/utils.h \
@LAMMPS_SOURCE_DIR@/library.cpp \
@LAMMPS_SOURCE_DIR@/library.h \
@LAMMPS_SOURCE_DIR@/lammps.cpp \
@LAMMPS_SOURCE_DIR@/lammps.h \
@LAMMPS_SOURCE_DIR@/lmptype.h \
@LAMMPS_SOURCE_DIR@/pointers.h \
@LAMMPS_SOURCE_DIR@/atom.cpp \
@LAMMPS_SOURCE_DIR@/atom.h \
@LAMMPS_SOURCE_DIR@/input.cpp \
@LAMMPS_SOURCE_DIR@/input.h \
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded
# from the input.
# The default value is: NO.
EXCLUDE_SYMLINKS = YES
#---------------------------------------------------------------------------
# Configuration options related to output
#---------------------------------------------------------------------------
GENERATE_HTML = NO
GENERATE_LATEX = NO
GENERATE_XML = YES
XML_OUTPUT = xml
XML_PROGRAMLISTING = YES
XML_NS_MEMB_FILE_SCOPE = NO
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all
# C-preprocessor directives found in the sources and include files.
# The default value is: YES.
#ENABLE_PREPROCESSING = YES
ENABLE_PREPROCESSING = NO
# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
# in the source code. If set to NO, only conditional compilation will be
# performed. Macro expansion can be done in a controlled way by setting
# EXPAND_ONLY_PREDEF to YES.
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
MACRO_EXPANSION = NO
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
# the macro expansion is limited to the macros specified with the PREDEFINED and
# EXPAND_AS_DEFINED tags.
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
EXPAND_ONLY_PREDEF = NO
# If the SEARCH_INCLUDES tag is set to YES, the include files in the
# INCLUDE_PATH will be searched if a #include is found.
# The default value is: YES.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
SEARCH_INCLUDES = YES
# The INCLUDE_PATH tag can be used to specify one or more directories that
# contain include files that are not input files but should be processed by the
# preprocessor.
# This tag requires that the tag SEARCH_INCLUDES is set to YES.
INCLUDE_PATH =
# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
# patterns (like *.h and *.hpp) to filter out the header-files in the
# directories. If left blank, the patterns specified with FILE_PATTERNS will be
# used.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
INCLUDE_FILE_PATTERNS =
# The PREDEFINED tag can be used to specify one or more macro names that are
# defined before the preprocessor is started (similar to the -D option of e.g.
# gcc). The argument of the tag is a list of macros of the form: name or
# name=definition (no spaces). If the definition and the "=" are omitted, "=1"
# is assumed. To prevent a macro definition from being undefined via #undef or
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
PREDEFINED =
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
# macro definition that is found in the sources will be used. Use the PREDEFINED
# tag if you want to use a different macro definition that overrules the
# definition found in the source code.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
EXPAND_AS_DEFINED =
# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
# remove all references to function-like macros that are alone on a line, have
# an all uppercase name, and do not end with a semicolon. Such function macros
# are typically used for boiler-plate code, and will confuse the parser if not
# removed.
# The default value is: YES.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
SKIP_FUNCTION_MACROS = YES

BIN
doc/doxygen/lammps-logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

3
doc/graphviz/.gitignore vendored Normal file
View File

@ -0,0 +1,3 @@
/*.png
/*.svg
/*.pdf

30
doc/graphviz/Makefile Normal file
View File

@ -0,0 +1,30 @@
# Makefile for generating images with graphviz
#
SHELL = /bin/bash
BUILDDIR = ${CURDIR}/..
IMGDIR = $(BUILDDIR)/src/JPG
IMGSRC = $(wildcard *.dot)
IMGPNG = $(IMGSRC:%.dot=$(IMGDIR)/%.png)
HAS_DOT = NO
ifeq ($(shell which dot >/dev/null 2>&1; echo $$?), 0)
HAS_DOT = YES
endif
all: $(IMGPNG)
clean:
rm -f $(IMGSVG) $(IMGPDF) $(IMGPNG) *~
ifeq ($(HAS_DOT),YES)
$(IMGDIR)/%.png: %.dot
dot -Tpng -o $@ $<
endif
ifeq ($(HAS_DOT),NO)
$(IMGDIR)/%.png: %.dot
@echo '###################################################'
@echo '# Need to install "graphviz" to regenerate graphs #'
@echo '###################################################'
endif

90
doc/graphviz/lammps-classes.dot Normal file
View File

@ -0,0 +1,90 @@
// LAMMPS Class topology
digraph lammps {
rankdir="LR"
La [shape=circle label="LAMMPS"]
At [shape=box label="Atom" color=blue]
Ci [shape=box label="CiteMe"]
Co [shape=box label="Comm" color=blue]
Do [shape=box label="Domain" color=blue]
Er [shape=box label="Error" color=blue]
Fo [shape=box label="Force" color=blue]
Gr [shape=box label="Group" color=blue]
In [shape=box label="Input" color=blue]
Ko [shape=box label="KokkosLMP"]
Ak [shape=box label="AtomKK" color=blue]
Mk [shape=box label="MemoryKK" color=blue]
Me [shape=box label="Memory" color=blue]
Mo [shape=box label="Modify" color=blue]
Ne [shape=box label="Neighbor" color=blue]
Ou [shape=box label="Output" color=blue]
Py [shape=box label="Python" color=blue]
Up [shape=box label="Update" color=blue]
Un [shape=box label="Universe" color=blue]
Ti [shape=box label="Timer" color=blue]
Rg [label="Region" color=red]
Rb [shape=box label="RegionBlock"]
Rs [shape=box label="RegionSphere"]
Av [label="AtomVec" color=red]
It [label="Integrate" color=red]
Mi [label="Min" color=red]
Pa [label="Pair" color=red]
Bo [label="Bond" color=red]
An [label="Angle" color=red]
Di [label="Dihedral" color=red]
Im [label="Improper" color=red]
Ks [label="Kspace" color=red]
Du [label="Dump" color=red]
Fi [label="Fix" color=red]
Cp [label="Compute" color=red]
Th [label="Thermo"]
Va [label="Variable"]
Ew [shape=box label="Ewald"]
Pp [shape=box label="PPPM"]
Ff [label="FFT3d"]
Re [label="Remap"]
Gc [label="GridComm"]
Cb [shape=box label="CommBrick"]
Ct [shape=box label="CommTiled"]
Aa [shape=box label="AtomVecAtomic"]
Am [shape=box label="AtomVecMolecular"]
Lj [shape=box label="PairLJCut"]
Lo [shape=box label="PairLJCutOMP"]
Lg [shape=box label="PairLJCutGPU"]
Te [shape=box label="PairTersoff"]
Bh [shape=box label="BondHarmonic"]
Bf [shape=box label="BondFENE"]
Fa [shape=box label="FixAveTime"]
Fn [shape=box label="FixNVE"]
Fh [shape=box label="FixNH"]
Fp [shape=box label="FixNPT"]
Ft [shape=box label="FixNVT"]
Da [shape=box label="DumpAtom"]
Dc [shape=box label="DumpCustom"]
Dg [shape=box label="DumpCFG"]
Ve [shape=box label="Verlet"]
Rr [shape=box label="Respa"]
Po [shape=box label="PPPMOmp"]
La -> {At Ci Co Do Er Fo Gr In Ko Ak Mk Me Mo Ne Ou Py Ti Up Un} [penwidth=2]
Do -> {Rg} [penwidth=2]
Co -> {Cb Ct} [style=dashed penwidth=2]
Rg -> {Rb Rs} [style=dashed penwidth=2]
In -> Va [penwidth=2]
Mo -> {Fi Cp} [penwidth=2]
Fo -> {Pa Bo An Di Im Ks} [penwidth=2]
Ks -> {Ew Pp} [style=dashed penwidth=2]
Pp -> {Ff Re Gc} [penwidth=2]
Pp -> {Po} [style=dashed penwidth=2]
Up -> {It Mi} [penwidth=2]
It -> {Ve Rr} [style=dashed penwidth=2]
Ou -> {Du Th} [penwidth=2]
Du -> {Da Dc} [style=dashed penwidth=2]
Dc -> {Dg} [style=dashed penwidth=2]
At -> Av [penwidth=2]
Av -> {Aa Am} [style=dashed penwidth=2]
Pa -> {Lj Te} [style=dashed penwidth=2]
Lj -> {Lo Lg} [style=dashed penwidth=2]
Bo -> {Bh Bf} [style=dashed penwidth=2]
Fi -> {Fa Fn Fh} [style=dashed penwidth=2]
Fh -> {Fp Ft} [style=dashed penwidth=2]
}

2
doc/lammps.1
View File

@ -1,4 +1,4 @@
.TH LAMMPS "15 June 2020" "2020-06-15"
.TH LAMMPS "24 August 2020" "2020-08-24"
.SH NAME
.B LAMMPS
\- Molecular Dynamics Simulator.

25
doc/src/Build_basics.rst
View File

@ -193,14 +193,17 @@ compiler and any :doc:`accelerator packages <Speed_packages>` you have
included in the build.
You can tell CMake to look for a specific compiler with setting CMake
variable during configuration. For a few common choices, there are also
presets in the ``cmake/presets`` folder. For convenience, there is a
``CMAKE_TUNE_FLAGS`` variable that can be set to apply global compiler
options. More on that below, but you can also specify the corresponding
``CMAKE_*_FLAGS`` variables individually if you want to experiment with
alternate optimization flags. You should specify all 3 compilers, so
that the (few) LAMMPS source files written in C or Fortran are built
with a compiler consistent with the one used for the C++ files:
variables (listed below) during configuration. For a few common
choices, there are also presets in the ``cmake/presets`` folder. For
convenience, there is a ``CMAKE_TUNE_FLAGS`` variable that can be set to
apply global compiler options (applied to compilation only), to be used
for adding compiler or host specific optimization flags in addition to
the "flags" variables listed below. You may also specify the
corresponding ``CMAKE_*_FLAGS`` variables individually, if you want to
experiment with alternate optimization flags. You should specify all 3
compilers, so that the (few) LAMMPS source files written in C or Fortran
are built with a compiler consistent with the one used for the C++
files:
.. code-block:: bash
@ -229,11 +232,7 @@ can be loaded with `-C ../cmake/presets/clang.cmake`. Similarly,
In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
compiler flags to tune for optimal performance on given hosts. By
default these are initialized to some compiler specific flags, to
optimize the LAMMPS executable with optimizations and instructions
available on the host where LAMMPS is compiled. For example, for Intel
compilers this would be ``-xHost`` and for GNU compilers this would be
``-march=native``. To turn these flags off, do ``-D CMAKE_TUNE_FLAGS=``.
default this variable is empty.
.. note::

79
doc/src/Build_development.rst
View File

@ -159,8 +159,8 @@ A test run is then a a collection multiple individual test runs each
with many comparisons to reference results based on template input
files, individual command settings, relative error margins, and
reference data stored in a YAML format file with ``.yaml``
suffix. Currently the programs ``pair_style``, ``bond_style``, and
``angle_style`` are implemented. They will compare forces, energies and
suffix. Currently the programs ``test_pair_style``, ``test_bond_style``, and
``test_angle_style`` are implemented. They will compare forces, energies and
(global) stress for all atoms after a ``run 0`` calculation and after a
few steps of MD with :doc:`fix nve <fix_nve>`, each in multiple variants
with different settings and also for multiple accelerated styles. If a
@ -172,7 +172,7 @@ Below is an example command and output:
.. parsed-literal::
[tests]$ pair_style mol-pair-lj_cut.yaml
[tests]$ test_pair_style mol-pair-lj_cut.yaml
[==========] Running 6 tests from 1 test suite.
[----------] Global test environment set-up.
[----------] 6 tests from PairStyle
@ -259,6 +259,71 @@ and working.
of mis-compiled code (or an undesired large loss of precision due
to significant reordering of operations and thus less error cancellation).
Unit tests for timestepping related fixes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A substantial subset of :doc:`fix styles <fix>` are invoked regularly
during MD timestepping and manipulate per-atom properties like
positions, velocities, and forces. For those fix styles, testing can be
done in a very similar fashion as for force fields and thus there is a
test program `test_fix_timestep` that shares a lot of code, properties,
and command line flags with the force field style testers described in
the previous section.
This tester will set up a small molecular system run with verlet run
style for 4 MD steps, then write a binary restart and continue for
another 4 MD steps. At this point coordinates and velocities are
recorded and compared to reference data. Then the system is cleared,
restarted and running the second 4 MD steps again and the data is
compared to the same reference. That is followed by another restart
after which per atom type masses are replaced with per-atom masses and
the second 4 MD steps are repeated again and compared to the same
reference. Also global scalar and vector data of the fix is recorded
and compared. If the fix is a thermostat and thus the internal property
``t_target`` can be extracted, then this is compared to the reference
data. The tests are repeated with the respa run style.
If the fix has a multi-threaded version in the USER-OMP package, then
the entire set of tests is repeated for that version as well.
For this to work, some additional conditions have to be met by the
YAML format test inputs.
- The fix to be tested (and only this fix), should be listed in the
``prerequisites:`` section
- The fix to be tested must be specified in the ``post_commands:``
section with the fix-ID ``test``. This section may contain other
commands and other fixes (e.g. an instance of fix nve for testing
a thermostat or force manipulation fix)
- For fixes that can tally contributions to the global virial, the
line ``fix_modify test virial yes`` should be included in the
``post_commands:`` section of the test input.
- For thermostat fixes the target temperature should be ramped from
an arbitrary value (e.g. 50K) to a pre-defined target temperature
entered as ``${t_target}``.
- For fixes that have thermostatting support included, but do not
have it enabled in the input (e.g. fix rigid with default settings),
the ``post_commands:`` section should contain the line
``variable t_target delete`` to disable the target temperature ramp
check to avoid false positives.
Use custom linker for faster link times when ENABLE_TESTING is active
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When compiling LAMMPS with enabled tests, most test executables will
need to be linked against the LAMMPS library. Since this can be a very
large library with many C++ objects when many packages are enabled, link
times can become very long on machines that use the GNU BFD linker (e.g.
Linux systems). Alternatives like the ``lld`` linker of the LLVM project
or the ``gold`` linker available with GNU binutils can speed up this step
substantially. CMake will by default test if any of the two can be
enabled and use it when ``ENABLE_TESTING`` is active. It can also be
selected manually through the ``CMAKE_CUSTOM_LINKER`` CMake variable.
Allowed values are ``lld``, ``gold``, ``bfd``, or ``default``. The
``default`` option will use the system default linker otherwise, the
linker is chosen explicitly. This option is only available for the
GNU or Clang C++ compiler.
Tests for other components and utility functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -313,22 +378,22 @@ The images below illustrate how the data is presented.
.. list-table::
* - .. figure:: JPG/coverage-overview-top.png
:target: JPG/coverage-overview-top.png
:scale: 25%
Top of the overview page
- .. figure:: JPG/coverage-overview-manybody.png
:target: JPG/coverage-overview-manybody.png
:scale: 25%
Styles with good coverage
- .. figure:: JPG/coverage-file-top.png
:target: JPG/coverage-file-top.png
:scale: 25%
Top of individual source page
- .. figure:: JPG/coverage-file-branches.png
:target: JPG/coverage-file-branches.png
:scale: 25%
Source page with branches

26
doc/src/Build_extras.rst
View File

@ -105,10 +105,10 @@ CMake build
# generic (default) or intel (Intel CPU) or fermi, kepler, cypress (NVIDIA)
-D GPU_ARCH=value # primary GPU hardware choice for GPU_API=cuda
# value = sm_XX, see below
# default is sm_30
# 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_30' for HIP_PLATFORM=nvcc
# default is 'gfx906' for HIP_PLATFORM=hcc 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
@ -361,9 +361,12 @@ be specified in uppercase.
* - AMDAVX
- HOST
- AMD 64-bit x86 CPU (AVX 1)
* - EPYC
* - ZEN
- HOST
- AMD EPYC Zen class CPU (AVX 2)
- AMD Zen class CPU (AVX 2)
* - ZEN2
- HOST
- AMD Zen2 class CPU (AVX 2)
* - ARMV80
- HOST
- ARMv8.0 Compatible CPU
@ -445,12 +448,18 @@ be specified in uppercase.
* - TURING75
- GPU
- NVIDIA Turing generation CC 7.5 GPU
* - AMPERE80
- GPU
- NVIDIA Ampere generation CC 8.0 GPU
* - VEGA900
- GPU
- AMD GPU MI25 GFX900
* - VEGA906
- GPU
- AMD GPU MI50/MI60 GFX906
* - INTEL_GEN
- GPU
- Intel GPUs Gen9+
Basic CMake build settings:
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -1255,6 +1264,15 @@ also typically :ref:`install the USER-OMP package <user-omp>`, as it can be
used in tandem with the USER-INTEL package to good effect, as explained
on the :doc:`Speed intel <Speed_intel>` doc page.
When using Intel compilers version 16.0 or later is required. You can
also use the GNU or Clang compilers and they will provide performance
improvements over regular styles and USER-OMP styles, but less so than
with the Intel compilers. Please also note, that some compilers have
been found to apply memory alignment constraints incompletely or
incorrectly and thus can cause segmentation faults in otherwise correct
code when using features from the USER-INTEL package.
CMake build
^^^^^^^^^^^

4
doc/src/Build_package.rst
View File

@ -136,6 +136,7 @@ src directory.
.. _cmake_presets:
CMake presets for installing many packages
""""""""""""""""""""""""""""""""""""""""""
Instead of specifying all the CMake options via the command-line,
CMake allows initializing its settings cache using script files.
@ -168,7 +169,8 @@ one of them as a starting point and customize it to your needs.
in a single cmake run, or change settings incrementally by running
cmake with new flags.
**Example:**
Example
"""""""
.. code-block:: bash

2
doc/src/Build_windows.rst
View File

@ -38,7 +38,7 @@ optional Windows feature allows you to run the bash shell from Ubuntu
from within Windows and from there on, you can pretty much use that
shell like you are running on an Ubuntu Linux machine (e.g. installing
software via apt-get and more). For more details on that, please
see :doc:`this tutorial <Howto_bash>`
see :doc:`this tutorial <Howto_wsl>`
.. _gnu:

10
doc/src/Commands_all.rst
View File

@ -46,13 +46,6 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`dimension <dimension>`
* :doc:`displace_atoms <displace_atoms>`
* :doc:`dump <dump>`
* :doc:`dump atom/adios <dump_adios>`
* :doc:`dump custom/adios <dump_adios>`
* :doc:`dump image <dump_image>`
* :doc:`dump movie <dump_image>`
* :doc:`dump netcdf <dump_netcdf>`
* :doc:`dump netcdf/mpiio <dump_netcdf>`
* :doc:`dump vtk <dump_vtk>`
* :doc:`dump_modify <dump_modify>`
* :doc:`dynamical_matrix <dynamical_matrix>`
* :doc:`echo <echo>`
@ -108,7 +101,8 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`region <region>`
* :doc:`replicate <replicate>`
* :doc:`rerun <rerun>`
* :doc:`reset_ids <reset_ids>`
* :doc:`reset_atom_ids <reset_atom_ids>`
* :doc:`reset_mol_ids <reset_mol_ids>`
* :doc:`reset_timestep <reset_timestep>`
* :doc:`restart <restart>`
* :doc:`run <run>`

1
doc/src/Commands_bond.rst
View File

@ -46,6 +46,7 @@ OPT.
* :doc:`oxdna2/fene <bond_oxdna>`
* :doc:`oxrna2/fene <bond_oxdna>`
* :doc:`quartic (o) <bond_quartic>`
* :doc:`special <bond_special>`
* :doc:`table (o) <bond_table>`
.. _angle:

2
doc/src/Commands_compute.rst
View File

@ -80,6 +80,7 @@ KOKKOS, o = USER-OMP, t = OPT.
* :doc:`ke/eff <compute_ke_eff>`
* :doc:`ke/rigid <compute_ke_rigid>`
* :doc:`mesont <compute_mesont>`
* :doc:`mliap <compute_mliap>`
* :doc:`momentum <compute_momentum>`
* :doc:`msd <compute_msd>`
* :doc:`msd/chunk <compute_msd_chunk>`
@ -122,6 +123,7 @@ KOKKOS, o = USER-OMP, t = OPT.
* :doc:`smd/tlsph/strain/rate <compute_smd_tlsph_strain_rate>`
* :doc:`smd/tlsph/stress <compute_smd_tlsph_stress>`
* :doc:`smd/triangle/vertices <compute_smd_triangle_vertices>`
* :doc:`smd/ulsph/effm <compute_smd_ulsph_effm>`
* :doc:`smd/ulsph/num/neighs <compute_smd_ulsph_num_neighs>`
* :doc:`smd/ulsph/strain <compute_smd_ulsph_strain>`
* :doc:`smd/ulsph/strain/rate <compute_smd_ulsph_strain_rate>`

3
doc/src/Commands_fix.rst
View File

@ -42,6 +42,7 @@ OPT.
* :doc:`bocs <fix_bocs>`
* :doc:`bond/break <fix_bond_break>`
* :doc:`bond/create <fix_bond_create>`
* :doc:`bond/create/angle <fix_bond_create>`
* :doc:`bond/react <fix_bond_react>`
* :doc:`bond/swap <fix_bond_swap>`
* :doc:`box/relax <fix_box_relax>`
@ -97,6 +98,7 @@ OPT.
* :doc:`manifoldforce <fix_manifoldforce>`
* :doc:`meso/move <fix_meso_move>`
* :doc:`momentum (k) <fix_momentum>`
* :doc:`momentum/chunk <fix_momentum>`
* :doc:`move <fix_move>`
* :doc:`mscg <fix_mscg>`
* :doc:`msst <fix_msst>`
@ -243,3 +245,4 @@ OPT.
* :doc:`wall/region <fix_wall_region>`
* :doc:`wall/region/ees <fix_wall_ees>`
* :doc:`wall/srd <fix_wall_srd>`
* :doc:`widom <fix_widom>`

16
doc/src/Commands_pair.rst
View File

@ -136,22 +136,22 @@ OPT.
* :doc:`lj/class2/soft <pair_fep_soft>`
* :doc:`lj/cubic (go) <pair_lj_cubic>`
* :doc:`lj/cut (gikot) <pair_lj>`
* :doc:`lj/cut/coul/cut (gko) <pair_lj>`
* :doc:`lj/cut/coul/cut (gko) <pair_lj_cut_coul>`
* :doc:`lj/cut/coul/cut/soft (o) <pair_fep_soft>`
* :doc:`lj/cut/coul/debye (gko) <pair_lj>`
* :doc:`lj/cut/coul/dsf (gko) <pair_lj>`
* :doc:`lj/cut/coul/long (gikot) <pair_lj>`
* :doc:`lj/cut/coul/debye (gko) <pair_lj_cut_coul>`
* :doc:`lj/cut/coul/dsf (gko) <pair_lj_cut_coul>`
* :doc:`lj/cut/coul/long (gikot) <pair_lj_cut_coul>`
* :doc:`lj/cut/coul/long/cs <pair_cs>`
* :doc:`lj/cut/coul/long/soft (o) <pair_fep_soft>`
* :doc:`lj/cut/coul/msm (go) <pair_lj>`
* :doc:`lj/cut/coul/wolf (o) <pair_lj>`
* :doc:`lj/cut/coul/msm (go) <pair_lj_cut_coul>`
* :doc:`lj/cut/coul/wolf (o) <pair_lj_cut_coul>`
* :doc:`lj/cut/dipole/cut (go) <pair_dipole>`
* :doc:`lj/cut/dipole/long (g) <pair_dipole>`
* :doc:`lj/cut/dipole/sf (go) <pair_dipole>`
* :doc:`lj/cut/soft (o) <pair_fep_soft>`
* :doc:`lj/cut/thole/long (o) <pair_thole>`
* :doc:`lj/cut/tip4p/cut (o) <pair_lj>`
* :doc:`lj/cut/tip4p/long (got) <pair_lj>`
* :doc:`lj/cut/tip4p/cut (o) <pair_lj_cut_tip4p>`
* :doc:`lj/cut/tip4p/long (got) <pair_lj_cut_tip4p>`
* :doc:`lj/cut/tip4p/long/soft (o) <pair_fep_soft>`
* :doc:`lj/expand (gko) <pair_lj_expand>`
* :doc:`lj/expand/coul/long (g) <pair_lj_expand>`

4
doc/src/Errors_messages.rst
View File

@ -502,10 +502,10 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
*Bond/react: Unknown section in map file*
Please ensure reaction map files are properly formatted.
*Bond/react: Atom affected by reaction too close to template edge*
*Bond/react: Atom/Bond type affected by reaction too close to template edge*
This means an atom which changes type or connectivity during the
reaction is too close to an 'edge' atom defined in the map
file. This could cause incorrect assignment of bonds, angle, etc.
file. This could cause incorrect assignment of bonds, angle, etc.
Generally, this means you must include more atoms in your templates,
such that there are at least two atoms between each atom involved in
the reaction and an edge atom.

18
doc/src/Errors_warnings.rst
View File

@ -118,6 +118,24 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
incorrect periodic images of atoms in interaction lists. To avoid, either use
:doc:`pair style zero <pair_zero>` with a suitable cutoff or use :doc:`comm_modify cutoff <comm_modify>`.
*Communication cutoff is shorter than a bond length based estimate. This may lead to errors.*
Since LAMMPS stores topology data with individual atoms, all atoms
comprising a bond, angle, dihedral or improper must be present on any
sub-domain that "owns" the atom with the information, either as a
local or a ghost atom. The communication cutoff is what determines up
to what distance from a sub-domain boundary ghost atoms are created.
The communication cutoff is by default the largest non-bonded cutoff
plus the neighbor skin distance, but for short or non-bonded cutoffs
and/or long bonds, this may not be sufficient. This warning indicates
that there is an increased risk of a simulation stopping unexpectedly
because of Bond/Angle/Dihedral/Improper atoms missing. It can be
silenced by manually setting the communication cutoff via
:doc:`comm_modify cutoff <comm_modify>`. However, since the
heuristic used to determine the estimate is not always accurate, it
is not changed automatically and the warning may be ignored depending
on the specific system being simulated.
*Communication cutoff is too small for SNAP micro load balancing, increased to %lf*
Self-explanatory.

2
doc/src/Howto.rst
View File

@ -19,7 +19,7 @@ Tutorials howto
Howto_cmake
Howto_github
Howto_pylammps
Howto_bash
Howto_wsl
General howto
=============

264
doc/src/Howto_bash.rst
View File

@ -1,264 +0,0 @@
Using LAMMPS with Bash on Windows
=================================
**written by Richard Berger**
----------
Starting with Windows 10 you can install Linux tools directly in Windows. This
allows you to compile LAMMPS following the same procedure as on a real Ubuntu
Linux installation. Software can be easily installed using the package manager
via apt-get and all files are accessible in both the Windows Explorer and your
Linux shell (bash). This avoids switching to a different operating system or
installing a virtual machine. Everything runs on Windows.
.. seealso::
You can find more detailed information at the `Windows Subsystem for Linux Installation Guide for Windows 10 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_.
Installing Bash on Windows
--------------------------
Prerequisites
^^^^^^^^^^^^^
* Windows 10 (64bit only)
* Latest updates installed
Enable developer mode
^^^^^^^^^^^^^^^^^^^^^
You enable this feature by first opening Windows Settings and enabling
Developer mode. Go to the Windows settings and search for "developer". This
will allow you to install software which comes from outside of the Windows
Store. You might be prompted to reboot your compute. Please do so.
.. image:: JPG/bow_tutorial_01_small.png
:target: JPG/bow_tutorial_01.png
.. image:: JPG/bow_tutorial_02_small.png
:target: JPG/bow_tutorial_02.png
.. image:: JPG/bow_tutorial_03_small.png
:target: JPG/bow_tutorial_03.png
Install Windows Subsystem for Linux
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Next you must ensure that the Window Subsystem for Linux is installed. Again,
search for "enable windows features" in the Settings dialog. This opens a
dialog with a list of features you can install. Add a checkmark to Windows
Subsystem for Linux (Beta) and press OK.
.. image:: JPG/bow_tutorial_04_small.png
:target: JPG/bow_tutorial_04.png
.. image:: JPG/bow_tutorial_05.png
:target: JPG/bow_tutorial_05.png
Install Bash for Windows
^^^^^^^^^^^^^^^^^^^^^^^^
After installation completes, type "bash" in the Windows Start menu search.
Select the first found option. This will launch a command-line window which
will prompt you about installing Ubuntu on Windows. Confirm with "y" and press
enter. This will then download Ubuntu for Windows.
.. image:: JPG/bow_tutorial_06.png
.. image:: JPG/bow_tutorial_07.png
During installation, you will be asked for a new password. This will be used
for installing new software and running commands with sudo.
.. image:: JPG/bow_tutorial_08.png
Type exit to close the command-line window.
Go to the Start menu and type "bash" again. This time you will see a "Bash on
Ubuntu on Windows" Icon. Start this program.
.. image:: JPG/bow_tutorial_09.png
Congratulations, you have installed **Bash on Ubuntu on Windows**\ .
.. image:: JPG/bow_tutorial_10.png
----------
Compiling LAMMPS in Bash on Windows
-----------------------------------
The installation of LAMMPS in this environment is identical to working inside
of a real Ubuntu Linux installation. At the time writing, it uses Ubuntu 16.04.
Installing prerequisite packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
First upgrade all existing packages using
.. code-block:: bash
sudo apt update
sudo apt upgrade -y
Next install the following packages, which include compilers and libraries
needed for various LAMMPS features:
.. code-block:: bash
sudo apt install -y build-essential ccache gfortran openmpi-bin libopenmpi-dev libfftw3-dev libjpeg-dev libpng-dev python-dev python-virtualenv libblas-dev liblapack-dev libhdf5-serial-dev hdf5-tools
Files in Ubuntu on Windows
^^^^^^^^^^^^^^^^^^^^^^^^^^
When you launch "Bash on Ubuntu on Windows" you will start out in your Linux
user home directory /home/[username]\ . You can access your Windows user directory
using the /mnt/c/Users/[username] folder.
Download LAMMPS
^^^^^^^^^^^^^^^
Obtain a copy of the LAMMPS code and go into it using "cd"
Option 1: Downloading LAMMPS tarball using wget
"""""""""""""""""""""""""""""""""""""""""""""""
.. code-block:: bash
wget https://lammps.sandia.gov/tars/lammps-stable.tar.gz
tar xvzf lammps-stable.tar.gz
cd lammps-31Mar17
Option 2: Obtaining LAMMPS code from GitHub
"""""""""""""""""""""""""""""""""""""""""""
.. code-block:: bash
git clone https://github.com/lammps/lammps.git
cd lammps
Compiling LAMMPS
^^^^^^^^^^^^^^^^
At this point you can compile LAMMPS like on Ubuntu Linux.
Compiling serial version
""""""""""""""""""""""""
.. code-block:: bash
cd src/
make -j 4 serial
This will create an executable called lmp_serial in the src/ directory
Compiling MPI version
"""""""""""""""""""""
.. code-block:: bash
cd src/
make -j 4 mpi
This will create an executable called lmp_mpi in the src/ directory
----------
Finally, please note the absolute path of your src folder. You can get this using
.. code-block:: bash
pwd
or
.. code-block:: bash
echo $PWD
To run any examples you need the location of the executable. For now, let us
save this location in a temporary variable
.. code-block:: bash
LAMMPS_DIR=$PWD
----------
Running an example script
^^^^^^^^^^^^^^^^^^^^^^^^^
Once compiled you can execute some of the LAMMPS examples. Switch into the
examples/melt folder
.. code-block:: bash
cd ../examples/melt
The full path of the serial executable is $LAMMPS_DIR/lmp_serial, while the mpi
version is $LAMMPS_DIR/lmp_mpi. You can run the melt example with either
version as follows:
.. code-block:: bash
$LAMMPS_DIR/lmp_serial -in in.melt
or
.. code-block:: bash
mpirun -np 4 $LAMMPS_DIR/lmp_mpi -in in.melt
Note the use of our variable $LAMMPS_DIR, which expands into the full path of
the LAMMPS src folder we saved earlier.
Adding your executable directory to your PATH
"""""""""""""""""""""""""""""""""""""""""""""
You can avoid having to type the full path of your LAMMPS binary by adding its
parent folder to the PATH environment variable as follows:
.. code-block:: bash
export PATH=$LAMMPS_DIR:$PATH
Input scripts can then be run like this:
.. code-block:: bash
lmp_serial -in in.melt
or
.. code-block:: bash
mpirun -np 4 lmp_mpi -in in.melt
However, this PATH variable will not persist if you close your bash window.
To persist this setting edit the $HOME/.bashrc file using your favorite editor
and add this line
.. code-block:: bash
export PATH=/full/path/to/your/lammps/src:$PATH
**Example:**
For an executable lmp_serial with a full path
.. code-block:: bash
/home/richard/lammps/src/lmp_serial
the PATH variable should be
.. code-block:: bash
export PATH=/home/richard/lammps/src:$PATH
.. note::
This should give you a jump start when trying to run LAMMPS on Windows.
To become effective in this environment I encourage you to look into Linux
tutorials explaining Bash and Basic Unix commands (e.g., `Linux Journey <https://linuxjourney.com>`_)

4
doc/src/Howto_bioFF.rst
View File

@ -102,8 +102,8 @@ documentation for the formula it computes.
* :doc:`pair_style <pair_buck>` buck/coul/cut
* :doc:`pair_style <pair_buck>` buck/coul/long
* :doc:`pair_style <pair_lj>` lj/cut
* :doc:`pair_style <pair_lj>` lj/cut/coul/cut
* :doc:`pair_style <pair_lj>` lj/cut/coul/long
* :doc:`pair_style <pair_lj_cut_coul>` lj/cut/coul/cut
* :doc:`pair_style <pair_lj_cut_coul>` lj/cut/coul/long
* :doc:`pair_style <pair_hbond_dreiding>` hbond/dreiding/lj
* :doc:`pair_style <pair_hbond_dreiding>` hbond/dreiding/morse

171
doc/src/Howto_body.rst
View File

@ -9,13 +9,15 @@ surface meshes of discrete points, collections of sub-particles,
deformable objects, etc. Note that other kinds of finite-size
spherical and aspherical particles are also supported by LAMMPS, such
as spheres, ellipsoids, line segments, and triangles, but they are
simpler entities that body particles. See the :doc:`Howto spherical <Howto_spherical>` doc page for a general overview of all
these particle types.
simpler entities than body particles. See the :doc:`Howto spherical
<Howto_spherical>` doc page for a general overview of all these
particle types.
Body particles are used via the :doc:`atom_style body <atom_style>`
command. It takes a body style as an argument. The current body
styles supported by LAMMPS are as follows. The name in the first
column is used as the *bstyle* argument for the :doc:`atom_style body <atom_style>` command.
column is used as the *bstyle* argument for the :doc:`atom_style body
<atom_style>` command.
+----------------------+---------------------------------------------------+
| *nparticle* | rigid body with N sub-particles |
@ -30,8 +32,9 @@ thus how they can be used to compute pairwise body/body or
bond/non-body (point particle) interactions. More details of each
style are described below.
More styles may be added in the future. See the :doc:`Modify body <Modify_body>` doc page for details on how to add a new body
style to the code.
More styles may be added in the future. See the :doc:`Modify body
<Modify_body>` doc page for details on how to add a new body style to
the code.
----------
@ -55,10 +58,10 @@ interactions, building neighbor lists, migrating particles between
processors, output of particles to a dump file, etc. This means that
interactions between pairs of bodies or between a body and non-body
(point) particle need to be encoded in an appropriate pair style. If
such a pair style were to mimic the :doc:`fix rigid <fix_rigid>` model,
it would need to loop over the entire collection of interactions
between pairs of simple particles within the two bodies, each time a
single body/body interaction was computed.
such a pair style were to mimic the :doc:`fix rigid <fix_rigid>`
model, it would need to loop over the entire collection of
interactions between pairs of simple particles within the two bodies,
each time a single body/body interaction was computed.
Thus it only makes sense to use body particles and develop such a pair
style, when particle/particle interactions are more complex than what
@ -160,27 +163,6 @@ of the body particle.
The :doc:`pair_style body/nparticle <pair_body_nparticle>` command can be used
with this body style to compute body/body and body/non-body interactions.
For output purposes via the :doc:`compute body/local <compute_body_local>` and :doc:`dump local <dump>`
commands, this body style produces one datum for each of the N
sub-particles in a body particle. The datum has 3 values:
.. parsed-literal::
1 = x position of sub-particle
2 = y position of sub-particle
3 = z position of sub-particle
These values are the current position of the sub-particle within the
simulation domain, not a displacement from the center-of-mass (COM) of
the body particle itself. These values are calculated using the
current COM and orientation of the body particle.
For images created by the :doc:`dump image <dump_image>` command, if the
*body* keyword is set, then each body particle is drawn as a
collection of spheres, one for each sub-particle. The size of each
sphere is determined by the *bflag1* parameter for the *body* keyword.
The *bflag2* argument is ignored.
----------
**Specifics of body style rounded/polygon:**
@ -208,7 +190,7 @@ The Nmin and Nmax arguments are used to bound the size of data
structures used internally by each particle.
When the :doc:`read_data <read_data>` command reads a data file for this
body style, the following information must be provided for each entry
body style, the following information must be provided for each body
in the *Bodies* section of the data file:
.. parsed-literal::
@ -219,21 +201,25 @@ in the *Bodies* section of the data file:
x1 y1 z1
...
xN yN zN
i j j k k ...
diameter
where M = 6 + 3\*N + 2\*N + 1, and N is the number of vertices in the
body particle.
where M = 6 + 3\*N + 1, and N is the number of vertices in the body
particle.
The integer line has a single value N. The floating point line(s)
list 6 moments of inertia followed by the coordinates of the N
list 6 moments of inertia, followed by the coordinates of the N
vertices (x1 to zN) as 3N values (with z = 0.0 for each), followed by
2N vertex indices corresponding to the end points of the N edges,
followed by a single diameter value = the rounded diameter of the
circle that surrounds each vertex. The diameter value can be different
for each body particle. These floating-point values can be listed on
as many lines as you wish; see the :doc:`read_data <read_data>` command
for more details.
a diameter value = the rounded diameter of the circle that surrounds
each vertex. The diameter value can be different for each body
particle. These floating-point values can be listed on as many lines
as you wish; see the :doc:`read_data <read_data>` command for more
details.
.. note::
It is important that the vertices for each polygonal body particle be
listed in order around its perimeter, so that edges can be inferred.
LAMMPS does not check that this is the case.
The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the
values consistent with the current orientation of the rigid body
@ -260,10 +246,6 @@ is consistent with the 6 moments of inertia: ixx iyy izz ixy ixz iyz =
-0.7071 0.7071 0
0.7071 0.7071 0
0.7071 -0.7071 0
0 1
1 2
2 3
3 0
1.0
A rod in 2D, whose length is 4.0, mass 1.0, rounded at two ends
@ -345,8 +327,10 @@ in the *Bodies* section of the data file:
1 2 3 4
diameter
where M = 6 + 3\*N + 2\*E + 4\*F + 1, and N is the number of vertices in
the body particle, E = number of edges, F = number of faces.
where M = 6 + 3\*N + 2\*E + 4\*F + 1, and N is the number of vertices
in the body particle, E = number of edges, F = number of faces. For N
= 1 or 2, the format is simpler. E and F are ignored and no edges or
faces are listed, so that M = 6 + 3\*N + 1.
The integer line has three values: number of vertices (N), number of
edges (E) and number of faces (F). The floating point line(s) list 6
@ -356,16 +340,26 @@ the end points of the E edges, then 4\*F vertex indices defining F
faces. The last value is the diameter value = the rounded diameter of
the sphere that surrounds each vertex. The diameter value can be
different for each body particle. These floating-point values can be
listed on as many lines as you wish; see the
:doc:`read_data <read_data>` command for more details. Because the
maximum number of vertices per face is hard-coded to be 4
(i.e. quadrilaterals), faces with more than 4 vertices need to be
split into triangles or quadrilaterals. For triangular faces, the
last vertex index should be set to -1.
listed on as many lines as you wish; see the :doc:`read_data
<read_data>` command for more details.
The ordering of the 4 vertices within a face should follow
the right-hand rule so that the normal vector of the face points
outwards from the center of mass.
Note that vertices are numbered from 0 to N-1 inclusive. The order of
the 2 vertices in each edge does not matter. Faces can be triangles
or quadrilaterals. In both cases 4 vertices must be specified. For a
triangle the 4th vertex is -1. The 4 vertices within each triangle or
quadrilateral face should be ordered by the right-hand rule so that
the normal vector of the face points outwards from the center of mass.
For polyhedron with faces with more than 4 vertices, you should split
the complex face into multiple simple faces, each of which is a
triangle or quadrilateral.
.. note::
If a face is a quadrilateral then its 4 vertices must be co-planar.
LAMMPS does not check that this is the case. If you have a quad-face
of a polyhedron that is not planar (e.g. a cube whose vertices have
been randomly displaced), then you should represent the single quad
face as two triangle faces instead.
The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the
values consistent with the current orientation of the rigid body
@ -421,8 +415,8 @@ by circles of diameter 0.5, is specified as follows:
.. parsed-literal::
1 1 13
2
1 3 13
2 1 1
0 1.33333 1.33333 0 0 0
-2 0 0
2 0 0
@ -432,27 +426,34 @@ A sphere whose diameter is 3.0 and mass 1.0, is specified as follows:
.. parsed-literal::
1 1 10
1
1 3 10
1 1 1
0.9 0.9 0.9 0 0 0
0 0 0
3.0
The :doc:`pair_style body/rounded/polhedron <pair_body_rounded_polyhedron>` command can
be used with this body style to compute body/body interactions. The
:doc:`fix wall/body/polyhedron <fix_wall_body_polygon>` command can be
used with this body style to compute the interaction of body particles
with a wall.
The number of edges and faces for a rod or sphere must be listed,
but is ignored.
The :doc:`pair_style body/rounded/polhedron
<pair_body_rounded_polyhedron>` command can be used with this body
style to compute body/body interactions. The :doc:`fix
wall/body/polyhedron <fix_wall_body_polygon>` command can be used with
this body style to compute the interaction of body particles with a
wall.
----------
For output purposes via the :doc:`compute body/local <compute_body_local>` and :doc:`dump local <dump>`
commands, this body style produces one datum for each of the N
sub-particles in a body particle. The datum has 3 values:
**Output specifics for all body styles:**
For the :doc:`compute body/local <compute_body_local>` and :doc:`dump
local <dump>` commands, all 3 of the body styles described on his page
produces one datum for each of the N vertices (of sub-particles) in a
body particle. The datum has 3 values:
.. parsed-literal::
1 = x position of vertex
1 = x position of vertex (or sub-particle)
2 = y position of vertex
3 = z position of vertex
@ -461,15 +462,29 @@ simulation domain, not a displacement from the center-of-mass (COM) of
the body particle itself. These values are calculated using the
current COM and orientation of the body particle.
For images created by the :doc:`dump image <dump_image>` command, if the
*body* keyword is set, then each body particle is drawn as a polygon
consisting of N line segments. Note that the line segments are drawn
between the N vertices, which does not correspond exactly to the
physical extent of the body (because the :doc:`pair_style rounded/polygon <pair_body_rounded_polygon>` defines finite-size
spheres at those point and the line segments between the spheres are
tangent to the spheres). The drawn diameter of each line segment is
determined by the *bflag1* parameter for the *body* keyword. The
*bflag2* argument is ignored.
The :doc:`dump image <dump_image>` command and its *body* keyword can
be used to render body particles.
For the *nparticle* body style, each body is drawn as a
collection of spheres, one for each sub-particle. The size of each
sphere is determined by the *bflag1* parameter for the *body* keyword.
The *bflag2* argument is ignored.
For the *rounded/polygon* body style, each body is drawn as a polygon
with N line segments. For the *rounded/polyhedron* body style, each
face of each body is drawn as a polygon with N line segments. The
drawn diameter of each line segment is determined by the *bflag1*
parameter for the *body* keyword. The *bflag2* argument is ignored.
Note that for both the *rounded/polygon* and *rounded/polyhedron*
styles, line segments are drawn between the pairs of vertices.
Depending on the diameters of the line segments this may be slightly
different than the physical extent of the body as calculated by the
:doc:`pair_style rounded/polygon <pair_body_rounded_polygon>` or
:doc:`pair_style rounded/polyhedron <pair_body_rounded_polyhedron>`
commands. Conceptually, the pair styles define the surface of a 2d or
3d body by lines or planes that are tangent to the finite-size spheres
of specified diameter which are placed on each vertex position.
----------

16
doc/src/Howto_cmake.rst
View File

@ -47,7 +47,7 @@ using a shell like Bash.
- Linux: any Terminal window will work
- MacOS X: launch the Terminal application.
- Windows 10: install and run the :doc:`Windows subsystem for Linux <Howto_bash>`
- Windows 10: install and run the :doc:`Windows Subsystem for Linux <Howto_wsl>`
We also assume that you have downloaded and unpacked a recent LAMMPS source code package
or used Git to create a clone of the LAMMPS sources on your compilation machine.
@ -191,19 +191,19 @@ You start the command ``ccmake ../cmake`` in the ``build`` folder.
.. list-table::
* - .. figure:: JPG/ccmake-initial.png
:target: JPG/ccmake-initial.png
:scale: 33%
:align: center
Initial ``ccmake`` screen
- .. figure:: JPG/ccmake-config.png
:target: JPG/ccmake-config.png
:scale: 33%
:align: center
Configure output of ``ccmake``
- .. figure:: JPG/ccmake-options.png
:target: JPG/ccmake-options.png
:scale: 33%
:align: center
Options screen of ``ccmake``
@ -236,19 +236,19 @@ not required, it can also be entered from the GUI.
.. list-table::
* - .. figure:: JPG/cmake-gui-initial.png
:target: JPG/cmake-gui-initial.png
:scale: 40%
:align: center
Initial ``cmake-gui`` screen
- .. figure:: JPG/cmake-gui-popup.png
:target: JPG/cmake-gui-popup.png
:scale: 60%
:align: center
Generator selection in ``cmake-gui``
- .. figure:: JPG/cmake-gui-options.png
:target: JPG/cmake-gui-options.png
:scale: 40%
:align: center
Options screen of ``cmake-gui``
@ -331,7 +331,7 @@ Some common LAMMPS specific variables
* - ``BUILD_DOC``
- include building the HTML format documentation for packaging/installing (default: ``off``)
* - ``CMAKE_TUNE_FLAGS``
- common compiler flags, for optimization or instrumentation (default: compiler specific)
- common compiler flags, for optimization or instrumentation (default:)
* - ``LAMMPS_MACHINE``
- when set to ``name`` the LAMMPS executable and library will be called ``lmp_name`` and ``liblammps_name.a``
* - ``LAMMPS_EXCEPTIONS``

51
doc/src/Howto_output.rst
View File

@ -3,13 +3,15 @@ Output from LAMMPS (thermo, dumps, computes, fixes, variables)
There are four basic kinds of LAMMPS output:
* :doc:`Thermodynamic output <thermo_style>`, which is a list
of quantities printed every few timesteps to the screen and logfile.
* :doc:`Thermodynamic output <thermo_style>`, which is a list of
quantities printed every few timesteps to the screen and logfile.
* :doc:`Dump files <dump>`, which contain snapshots of atoms and various
per-atom values and are written at a specified frequency.
* Certain fixes can output user-specified quantities to files: :doc:`fix ave/time <fix_ave_time>` for time averaging, :doc:`fix ave/chunk <fix_ave_chunk>` for spatial or other averaging, and :doc:`fix print <fix_print>` for single-line output of
:doc:`variables <variable>`. Fix print can also output to the
screen.
* Certain fixes can output user-specified quantities to files:
:doc:`fix ave/time <fix_ave_time>` for time averaging,
:doc:`fix ave/chunk <fix_ave_chunk>` for spatial or other averaging, and
:doc:`fix print <fix_print>` for single-line output of
:doc:`variables <variable>`. Fix print can also output to the screen.
* :doc:`Restart files <restart>`.
A simulation prints one set of thermodynamic output and (optionally)
@ -41,7 +43,7 @@ to output and the kind of data they operate on and produce:
.. _global:
Global/per-atom/local data
---------------------------------------
--------------------------
Various output-related commands work with three different styles of
data: global, per-atom, or local. A global datum is one or more
@ -54,7 +56,7 @@ bond distances.
.. _scalar:
Scalar/vector/array data
-------------------------------------
------------------------
Global, per-atom, and local datums can each come in three kinds: a
single scalar value, a vector of values, or a 2d array of values. The
@ -81,10 +83,27 @@ the dimension twice (array -> scalar). Thus a command that uses
scalar values as input can typically also process elements of a vector
or array.
.. _disambiguation:
Disambiguation
--------------
Some computes and fixes produce data in multiple styles, e.g. a global
scalar and a per-atom vector. Usually the context in which the input
script references the data determines which style is meant. Example: if
a compute provides both a global scalar and a per-atom vector, the
former will be accessed by using ``c_ID`` in an equal-style variable,
while the latter will be accessed by using ``c_ID`` in an atom-style
variable. Note that atom-style variable formulas can also access global
scalars, but in this case it is not possible to do directly because of
the ambiguity. Instead, an equal-style variable can be defined which
accesses the global scalar, and that variable used in the atom-style
variable formula in place of ``c_ID``.
.. _thermo:
Thermodynamic output
---------------------------------
--------------------
The frequency and format of thermodynamic output is set by the
:doc:`thermo <thermo>`, :doc:`thermo_style <thermo_style>`, and
@ -112,7 +131,7 @@ intensive result.
.. _dump:
Dump file output
---------------------------
----------------
Dump file output is specified by the :doc:`dump <dump>` and
:doc:`dump_modify <dump_modify>` commands. There are several
@ -138,7 +157,7 @@ command.
.. _fixoutput:
Fixes that write output files
---------------------------------------------
-----------------------------
Several fixes take various quantities as input and can write output
files: :doc:`fix ave/time <fix_ave_time>`, :doc:`fix ave/chunk <fix_ave_chunk>`, :doc:`fix ave/histo <fix_ave_histo>`,
@ -192,7 +211,7 @@ from normal thermodynamic or dump file output.
.. _computeoutput:
Computes that process output quantities
-----------------------------------------------------------
---------------------------------------
The :doc:`compute reduce <compute_reduce>` and :doc:`compute reduce/region <compute_reduce>` commands take one or more per-atom
or local vector quantities as inputs and "reduce" them (sum, min, max,
@ -219,7 +238,7 @@ output commands.
.. _fixprocoutput:
Fixes that process output quantities
--------------------------------------------------------
------------------------------------
The :doc:`fix vector <fix_vector>` command can create global vectors as
output from global scalars as input, accumulating them one element at
@ -244,7 +263,7 @@ The output of this fix can be used as input to other output commands.
.. _compute:
Computes that generate values to output
-----------------------------------------------------
---------------------------------------
Every :doc:`compute <compute>` in LAMMPS produces either global or
per-atom or local values. The values can be scalars or vectors or
@ -257,7 +276,7 @@ without the word "atom" or "local" produce global values.
.. _fix:
Fixes that generate values to output
----------------------------------------------
------------------------------------
Some :doc:`fixes <fix>` in LAMMPS produces either global or per-atom or
local values which can be accessed by other commands. The values can
@ -269,7 +288,7 @@ describes them.
.. _variable:
Variables that generate values to output
-------------------------------------------------------
----------------------------------------
:doc:`Variables <variable>` defined in an input script can store one or
more strings. But equal-style, vector-style, and atom-style or
@ -284,7 +303,7 @@ commands described in this section.
.. _table:
Summary table of output options and data flow between commands
--------------------------------------------------------------------------
--------------------------------------------------------------
This table summarizes the various commands that can be used for
generating output from LAMMPS. Each command produces output data of

6
doc/src/Howto_tip4p.rst
View File

@ -11,11 +11,11 @@ angle style of *harmonic* or *charmm* should also be used.
A TIP4P model is run with LAMMPS using either this command
for a cutoff model:
* :doc:`pair_style lj/cut/tip4p/cut <pair_lj>`
* :doc:`pair_style lj/cut/tip4p/cut <pair_lj_cut_tip4p>`
or these two commands for a long-range model:
* :doc:`pair_style lj/cut/tip4p/long <pair_lj>`
* :doc:`pair_style lj/cut/tip4p/long <pair_lj_cut_tip4p>`
* :doc:`kspace_style pppm/tip4p <kspace_style>`
For both models, the bond lengths and bond angles should be held fixed
@ -95,7 +95,7 @@ typically best in an efficiency sense to use a LJ cutoff >= Coulomb
cutoff + 2\*(OM distance), to shrink the size of the neighbor list.
This leads to slightly larger cost for the long-range calculation, so
you can test the trade-off for your model. The OM distance and the LJ
and Coulombic cutoffs are set in the :doc:`pair_style lj/cut/tip4p/long <pair_lj>` command.
and Coulombic cutoffs are set in the :doc:`pair_style lj/cut/tip4p/long <pair_lj_cut_tip4p>` command.
Wikipedia also has a nice article on `water models <http://en.wikipedia.org/wiki/Water_model>`_.

359
doc/src/Howto_wsl.rst Normal file
View File

@ -0,0 +1,359 @@
Using LAMMPS on Windows 10 with WSL
###################################
**written by Richard Berger**
----------
It's always been tricky for us to have LAMMPS users and developers work on
Windows. We primarily develop LAMMPS to run on Linux clusters. To teach
LAMMPS in workshop settings, we had to redirect Windows users to
Linux Virtual Machines such as VirtualBox or Unix-like compilation with
Cygwin.
With the latest updates in Windows 10 (Version 2004, Build 19041 or higher),
Microsoft has added a new way to work on Linux-based code. The Windows
Subsystem for Linux (WSL). With WSL Version 2, you now get a Linux Virtual
Machine that transparently integrates into Windows. All you need is to ensure
you have the latest Windows updates installed and enable this new feature.
Linux VMs are then easily installed using the Microsoft Store.
In this tutorial, I'll show you how to set up and compile LAMMPS for both serial
and MPI usage in WSL2.
Installation
============
Upgrade to the latest Windows 10
--------------------------------
Type "Updates" in Windows Start and select "Check for Updates".
.. image:: img/wsl_tutorial/updates.png
:scale: 50%
Install all pending updates and reboot your system as many times as
necessary. Continue until your Windows installation is updated.
.. image:: img/wsl_tutorial/windows_update.png
:scale: 50%
Verify your system has at least **version 2004 and build 19041 or later**. You
can find this information by clicking on "OS build info".
.. image:: img/wsl_tutorial/osinfo.png
:scale: 50%
Enable WSL
----------
Next, we must install two additional Windows features to enable WSL support.
Open a PowerShell window as an administrator. Type "PowerShell" in Windows
Start and select "Run as Administrator".
.. image:: img/wsl_tutorial/powershell.png
:scale: 50%
Windows will ask you for administrator access. After you accept a new command
line window will appear. Type in the following command to install WSL:
.. code-block::
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
.. image:: img/wsl_tutorial/wsl_install1.png
Next, enable the VirtualMachinePlatform feature using the following command:
.. code-block::
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
.. image:: img/wsl_tutorial/wsl_install2.png
Finally, reboot your system.
Update WSL kernel component
---------------------------
Download and install the :download:`WSL Kernel Component Update <https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi>`.
Afterwards, reboot your system.
Set WSL2 as default
-------------------
Again, open PowerShell as administrator and run the following command:
.. code-block:: powershell
wsl --set-default-version 2
This command ensures that all future Linux installations will use WSL version 2.
.. image:: img/wsl_tutorial/wsl_install3.png
Install a Linux Distribution
----------------------------
Next, we need to install a Linux distribution via the Microsoft Store.
Install `Ubuntu 20.04 LTS <ms-windows-store://pdp/?ProductId=9n6svws3rx71>`_.
Once installed, you can launch it like any other application from the Start
Menu.
.. image:: img/wsl_tutorial/ubuntu_in_store.png
:scale: 50%
Initial Setup
^^^^^^^^^^^^^
The first time you launch the Ubuntu Linux console, it will prompt you for a
UNIX username and password. You will need this password to perform :code:`sudo`
commands later. Once completed, your Linux shell is ready for use. All your
actions and commands will run as the Linux user you specified.
.. image:: img/wsl_tutorial/first_login.png
:scale: 50%
Windows Explorer / WSL integration
==================================
Your Linux installation will have its own Linux filesystem, which contains
the Ubuntu files. Your Linux user will have a regular Linux home directory in
:code:`/home/<USERNAME>`. This directory is different from your Windows User
directory. Windows and Linux filesystems are connected through WSL.
All hard drives in Windows are accessible in the :code:`/mnt` directory in Linux.
E.g., WSL maps the :code:`C` hard drive to the :code:`/mnt/c` directory. That means you
can access your Windows User directory in :code:`/mnt/c/Users/<WINDOWS_USERNAME>`.
The Windows Explorer can also access the Linux filesystem. To illustrate this
integration, open an Ubuntu console and navigate to a directory of your
choice. To view this location in Windows Explorer, use the :code:`explorer.exe .`
command (do not forget the final dot!).
.. image:: img/wsl_tutorial/wsl_integration.png
:scale: 50%
--------
Compiling LAMMPS
================
You now have a fully functioning Ubuntu installation and can follow most
guides to install LAMMPS on a Linux system. Here are some of the essential
steps to follow:
Install prerequisite packages
-----------------------------
Before we can begin, we need to download the necessary compiler toolchain and
libraries to compile LAMMPS. In our Ubuntu-based Linux installation, we will
use the :code:`apt` package manager to install additional packages.
First, upgrade all existing packages using :code:`apt update` and :code:`apt upgrade`.
.. code-block:: bash
sudo apt update
sudo apt upgrade -y
Next, install the following packages with :code:`apt install`:
.. code-block:: bash
sudo apt install -y cmake build-essential ccache gfortran openmpi-bin libopenmpi-dev \
libfftw3-dev libjpeg-dev libpng-dev python3-dev python3-pip \
python3-virtualenv libblas-dev liblapack-dev libhdf5-serial-dev \
hdf5-tools
Download LAMMPS
---------------
Obtain a copy of the LAMMPS source code and go into it using the :code:`cd` command.
Option 1: Download a LAMMPS tarball using wget
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
wget https://github.com/lammps/lammps/archive/stable_3Mar2020.tar.gz
tar xvzf stable_3Mar2020.tar.gz
cd lammps
Option 2: Download a LAMMPS development version from GitHub
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
git clone --depth=1 https://github.com/lammps/lammps.git
cd lammps
Configure and Compile LAMMPS with CMake
---------------------------------------
A beginner-friendly way to compile LAMMPS is to use CMake. Create a :code:`build`
directory to compile LAMMPS and move into it. This directory will store the
build configuration and any binaries generated during compilation.
.. code-block:: bash
mkdir build
cd build
There are countless ways to compile LAMMPS. It is beyond the scope of this
tutorial. If you want to find out more about what can be enabled, please
consult the extensive `documentation <https://lammps.sandia.gov/doc/Build_cmake.html>`_.
To compile a minimal version of LAMMPS, we're going to use a preset.
Presets are a way to specify a collection of CMake options using a file.
.. code-block:: bash
cmake ../cmake/presets/minimal.cmake ../cmake
This command configures the build and generates the necessary Makefiles. To compile the binary, run the make command.
.. code-block:: bash
make -j 4
The :code:`-j` option specifies how many parallel processes will perform the
compilation. This option can significantly speed up compilation times. Use a
number that corresponds to the number of processors in your system.
After the compilation completes successfully, you will have an executable
called :code:`lmp` in the :code:`build` directory.
.. image:: img/wsl_tutorial/compilation_result.png
:scale: 50%
Please take note of the absolute path of your :code:`build` directory. You will
need to know the location to execute the LAMMPS binary later.
One way of getting the absolute path of the current directory is through the
:code:`$PWD` variable:
.. code-block:: bash
# prints out the current value of the PWD variable
echo $PWD
Let us save this value in a temporary variable :code:`LAMMPS_BUILD_DIR` for future use:
.. code-block:: bash
LAMMPS_BUILD_DIR=$PWD
The full path of the LAMMPS binary then is :code:`$LAMMPS_BUILD_DIR/lmp`.
------------
Running an example script
=========================
Now that we have a LAMMPS binary, we will run a script from the examples folder.
Switch into the :code:`examples/melt` folder:
.. code-block::
cd ../examples/melt
To run this example in serial, use the following command line:
.. code-block::
$LAMMPS_BUILD_DIR/lmp -in in.melt
To run the same script in parallel using MPI with 4 processes, do the following:
.. code-block:: bash
mpirun -np 4 $LAMMPS_BUILD_DIR/lmp -in in.melt
If you run LAMMPS for the first time, the Windows Firewall might prompt you
to confirm access. LAMMPS is accessing the network stack to enable parallel
computation. Allow the access.
.. image:: img/wsl_tutorial/windows_firewall.png
:scale: 75%
In either serial or MPI case, LAMMPS executes and will output something similar to this:
.. code-block::
LAMMPS (30 Jun 2020)
...
...
...
Total # of neighbors = 151513
Ave neighs/atom = 37.878250
Neighbor list builds = 12
Dangerous builds not checked
Total wall time: 0:00:00
**Congratulations! You've successfully compiled and executed LAMMPS on WSL!**
Final steps
===========
It is cumbersome to always specify the path of your LAMMPS binary. You can
avoid this by adding the absolute path of your :code:`build` directory to your PATH
environment variable.
.. code-block:: bash
export PATH=$LAMMPS_BUILD_DIR:$PATH
You can then run LAMMPS input scripts like this:
.. code-block:: bash
lmp -in in.melt
or
.. code-block:: bash
mpirun -np 4 lmp -in in.melt
.. note::
The value of this :code:`PATH` variable will disappear once you close your
console window. To persist this setting edit the :code:`$HOME/.bashrc` file using your
favorite text editor and add this line:
.. code-block:: bash
export PATH=/full/path/to/your/lammps/build:$PATH
**Example:**
If the LAMMPS executable `lmp` has the following absolute path:
.. code-block:: bash
/home/<USERNAME>/lammps/build/lmp
the :code:`PATH` variable should be:
.. code-block:: bash
export PATH=/home/<USERNAME>/lammps/build:$PATH
Once set up, all your Ubuntu consoles will always have access to your :code:`lmp`
binary without having to specify its location.
Conclusion
==========
I hope this gives you good overview on how to start compiling and running LAMMPS on
Windows. WSL makes preparing and running scripts on Windows a much better
experience.
If you are completely new to Linux, I highly recommend investing some time in
studying Linux online tutorials. E.g., tutorials about Bash Shell and Basic
Unix commands (e.g., `Linux Journey <https://linuxjourney.com/>`_). Acquiring
these skills will make you much more productive in this environment.
.. seealso::
* `Windows Subsystem for Linux Documentation <https://docs.microsoft.com/en-us/windows/wsl/>`_

32
doc/src/Install_linux.rst
View File

@ -21,8 +21,14 @@ Pre-built Ubuntu Linux executables
A pre-built LAMMPS executable suitable for running on the latest
Ubuntu Linux versions, can be downloaded as a Debian package. This
allows you to install LAMMPS with a single command, and stay
up-to-date with the current version of LAMMPS by simply updating your
operating system.
up-to-date with the current stable version of LAMMPS by simply updating
your operating system. Please note, that the repository below offers
two LAMMPS packages, ``lammps-daily`` and ``lammps-stable``. The
LAMMPS developers recommend to use the ``lammps-stable`` package for
any production simulations. The ``lammps-daily`` package is built
from the LAMMPS development sources, and those versions may have known
issues and bugs when new features are added and the software has not
undergone full release testing.
To install the appropriate personal-package archives (PPAs), do the
following once:
@ -37,16 +43,16 @@ To install LAMMPS do the following once:
.. code-block:: bash
$ sudo apt-get install lammps-daily
$ sudo apt-get install lammps-stable
This downloads an executable named ``lmp_daily`` to your box, which
This downloads an executable named ``lmp_stable`` to your box, which
can then be used in the usual way to run input scripts:
.. code-block:: bash
$ lmp_daily -in in.lj
$ lmp_stable -in in.lj
To update LAMMPS to the most current version, do the following:
To update LAMMPS to the most current stable version, do the following:
.. code-block:: bash
@ -58,25 +64,25 @@ To get a copy of the current documentation and examples:
.. code-block:: bash
$ sudo apt-get install lammps-daily-doc
$ sudo apt-get install lammps-stable-doc
which will download the doc files in
``/usr/share/doc/lammps-daily-doc/doc`` and example problems in
``/usr/share/doc/lammps-stable-doc/doc`` and example problems in
``/usr/share/doc/lammps-doc/examples``.
To get a copy of the current potentials files:
.. code-block:: bash
$ sudo apt-get install lammps-daily-data
$ sudo apt-get install lammps-stable-data
which will download the potentials files to
``/usr/share/lammps-daily/potentials``. The ``lmp_daily`` binary is
``/usr/share/lammps-stable/potentials``. The ``lmp_stable`` binary is
hard-coded to look for potential files in this directory (it does not
use the `LAMMPS_POTENTIALS` environment variable, as described
in :doc:`pair_coeff <pair_coeff>` command).
The ``lmp_daily`` binary is built with the :ref:`KIM package <kim>` which
The ``lmp_stable`` binary is built with the :ref:`KIM package <kim>` which
results in the above command also installing the `kim-api` binaries when LAMMPS
is installed. In order to use potentials from `openkim.org <openkim_>`_, you
can install the `openkim-models` package
@ -89,9 +95,9 @@ To un-install LAMMPS, do the following:
.. code-block:: bash
$ sudo apt-get remove lammps-daily
$ sudo apt-get remove lammps-stable
Please use ``lmp_daily -help`` to see which compilation options, packages,
Please use ``lmp_stable -help`` to see which compilation options, packages,
and styles are included in the binary.
Thanks to Anton Gladky (gladky.anton at gmail.com) for setting up this

BIN
doc/src/JPG/balance_nonuniform_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 16 KiB

BIN
doc/src/JPG/balance_rcb_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 15 KiB

BIN
doc/src/JPG/balance_uniform_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 17 KiB

BIN
doc/src/JPG/bow_tutorial_01.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 32 KiB

BIN
doc/src/JPG/bow_tutorial_01_small.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 15 KiB

BIN
doc/src/JPG/bow_tutorial_02.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 41 KiB

BIN
doc/src/JPG/bow_tutorial_02_small.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 16 KiB

BIN
doc/src/JPG/bow_tutorial_03.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 42 KiB

BIN
doc/src/JPG/bow_tutorial_03_small.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 20 KiB

BIN
doc/src/JPG/bow_tutorial_04.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 54 KiB

BIN
doc/src/JPG/bow_tutorial_04_small.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 21 KiB

BIN
doc/src/JPG/bow_tutorial_05.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 16 KiB

BIN
doc/src/JPG/bow_tutorial_06.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 13 KiB

BIN
doc/src/JPG/bow_tutorial_07.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 9.7 KiB

BIN
doc/src/JPG/bow_tutorial_08.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 24 KiB

BIN
doc/src/JPG/bow_tutorial_09.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 18 KiB

BIN
doc/src/JPG/bow_tutorial_10.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 7.6 KiB

BIN
doc/src/JPG/dump1_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 16 KiB

BIN
doc/src/JPG/dump2_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 6.4 KiB

BIN
doc/src/JPG/gran_funnel.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 117 KiB

BIN
doc/src/JPG/gran_funnel_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.2 KiB

BIN
doc/src/JPG/gran_mixer.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 224 KiB

BIN
doc/src/JPG/gran_mixer_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 3.0 KiB

BIN
doc/src/JPG/hop1_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 4.2 KiB

BIN
doc/src/JPG/hop2_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 4.1 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 245 KiB

BIN
doc/src/JPG/saed_ewald_intersect_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 40 KiB

BIN
doc/src/JPG/saed_mesh_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 42 KiB

BIN
doc/src/JPG/screenshot_atomeye_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 7.3 KiB

BIN
doc/src/JPG/screenshot_gl_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 5.7 KiB

BIN
doc/src/JPG/screenshot_pymol_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 7.5 KiB

BIN
doc/src/JPG/screenshot_vmd_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 6.6 KiB

BIN
doc/src/JPG/sinusoid_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 29 KiB

BIN
doc/src/JPG/xrd_mesh_small.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 45 KiB

13
doc/src/Manual.rst
View File

@ -60,6 +60,19 @@ every LAMMPS command.
Errors
Manual_build
.. _programmer_documentation:
.. toctree::
:maxdepth: 2
:numbered: 3
:caption: Programmer Documentation
:name: progdoc
:includehidden:
pg_developer
.. pg_library
.. pg_modify
.. pg_base
.. toctree::
:caption: Index
:name: index

3
doc/src/Packages_details.rst
View File

@ -306,7 +306,8 @@ gpu" or "-suffix gpu" :doc:`command-line switches <Run_options>`. See
also the :ref:`KOKKOS <PKG-KOKKOS>` package, which has GPU-enabled styles.
**Authors:** Mike Brown (Intel) while at Sandia and ORNL and Trung Nguyen
(Northwestern U) while at ORNL.
(Northwestern U) while at ORNL and later. AMD HIP support by Evgeny
Kuznetsov, Vladimir Stegailov, and Vsevolod Nikolskiy (HSE University).
**Install:**

25
doc/src/Python_examples.rst
View File

@ -80,16 +80,23 @@ See the python/README file for instructions on how to run them and the
source code for individual scripts for comments about what they do.
Here are screenshots of the vizplotgui_tool.py script in action for
different visualization package options. Click to see larger images:
different visualization package options:
.. image:: JPG/screenshot_gl_small.jpg
:target: JPG/screenshot_gl.jpg
.. |pyex1| image:: img/screenshot_gl.jpg
:width: 24%
.. image:: JPG/screenshot_atomeye_small.jpg
:target: JPG/screenshot_atomeye.jpg
.. |pyex2| image:: img/screenshot_atomeye.jpg
:width: 24%
.. image:: JPG/screenshot_pymol_small.jpg
:target: JPG/screenshot_pymol.jpg
.. |pyex3| image:: img/screenshot_pymol.jpg
:width: 24%
.. |pyex4| image:: img/screenshot_vmd.jpg
:width: 24%
|pyex1| |pyex2| |pyex3| |pyex4|
.. raw:: html
Click to see larger versions of the images.
.. image:: JPG/screenshot_vmd_small.jpg
:target: JPG/screenshot_vmd.jpg

2
doc/src/Python_test.rst
View File

@ -78,7 +78,7 @@ above, create a test.py file containing these lines:
pypar.finalize()
To run LAMMPS in parallel, assuming you have installed the
`mpi4py <https://bitbucket.org/mpi4py/mpi4py>`_ package as discussed
`mpi4py <https://mpi4py.readthedocs.io>`_ package as discussed
above, create a test.py file containing these lines:
.. code-block:: python

4
doc/src/Speed_gpu.rst
View File

@ -50,6 +50,10 @@ but this can be overridden using the device 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
software installed. Versions of ROCm older than 3.5 are currently deprecated
by AMD.
**Building LAMMPS with the GPU package:**
See the :ref:`Build extras <gpu>` doc page for

47
doc/src/Speed_intel.rst
View File

@ -12,7 +12,8 @@ When offloading to a co-processor from a CPU, the same routine is run
twice, once on the CPU and once with an offload flag. This allows
LAMMPS to run on the CPU cores and co-processor cores simultaneously.
**Currently Available USER-INTEL Styles:**
Currently Available USER-INTEL Styles
"""""""""""""""""""""""""""""""""""""
* Angle Styles: charmm, harmonic
* Bond Styles: fene, fourier, harmonic
@ -31,9 +32,10 @@ LAMMPS to run on the CPU cores and co-processor cores simultaneously.
support computing per-atom stress. If any compute or fix in your
input requires it, LAMMPS will abort with an error message.
**Speed-ups to expect:**
Speed-up to expect
"""""""""""""""""""
The speedups will depend on your simulation, the hardware, which
The speedup will depend on your simulation, the hardware, which
styles are used, the number of atoms, and the floating-point
precision mode. Performance improvements are shown compared to
LAMMPS *without using other acceleration packages* as these are
@ -59,7 +61,8 @@ instructions to reproduce.
----------
**Accuracy and order of operations:**
Accuracy and order of operations
""""""""""""""""""""""""""""""""
In most molecular dynamics software, parallelization parameters
(# of MPI, OpenMP, and vectorization) can change the results due
@ -96,7 +99,8 @@ mode should not be used without appropriate validation.
----------
**Quick Start for Experienced Users:**
Quick Start for Experienced Users
"""""""""""""""""""""""""""""""""
LAMMPS should be built with the USER-INTEL package installed.
Simulations should be run with 1 MPI task per physical *core*\ ,
@ -136,12 +140,13 @@ For Intel Xeon Phi co-processors (Offload):
----------
**Required hardware/software:**
Required hardware/software
""""""""""""""""""""""""""
When using Intel compilers version 16.0 or later is required.
In order to use offload to co-processors, an Intel Xeon Phi
co-processor and an Intel compiler are required. For this, the
recommended version of the Intel compiler is 14.0.1.106 or
versions 15.0.2.044 and higher.
co-processor and an Intel compiler are required.
Although any compiler can be used with the USER-INTEL package,
currently, vectorization directives are disabled by default when
@ -159,7 +164,8 @@ For best performance, we recommend that the MCDRAM is configured in
"Cache" mode can also be used, although the performance might be
slightly lower.
**Notes about Simultaneous Multithreading:**
Notes about Simultaneous Multithreading
"""""""""""""""""""""""""""""""""""""""
Modern CPUs often support Simultaneous Multithreading (SMT). On
Intel processors, this is called Hyper-Threading (HT) technology.
@ -196,7 +202,8 @@ this information can normally be obtained with:
cat /proc/cpuinfo
**Building LAMMPS with the USER-INTEL package:**
Building LAMMPS with the USER-INTEL package
"""""""""""""""""""""""""""""""""""""""""""
See the :ref:`Build extras <user-intel>` doc page for
instructions. Some additional details are covered here.
@ -263,7 +270,8 @@ recommended CCFLAG options for best performance are "-O2 -fno-alias
in most of the example Makefiles is to use "-xHost", however this
should not be used when cross-compiling.
**Running LAMMPS with the USER-INTEL package:**
Running LAMMPS with the USER-INTEL package
""""""""""""""""""""""""""""""""""""""""""
Running LAMMPS with the USER-INTEL package is similar to normal use
with the exceptions that one should 1) specify that LAMMPS should use
@ -304,7 +312,8 @@ almost all cases.
recommended, especially when running on a machine with Intel
Hyper-Threading technology disabled.
**Run with the USER-INTEL package from the command line:**
Run with the USER-INTEL package from the command line
"""""""""""""""""""""""""""""""""""""""""""""""""""""
To enable USER-INTEL optimizations for all available styles used in
the input script, the "-sf intel" :doc:`command-line switch <Run_options>` can be used without any requirement for
@ -339,7 +348,8 @@ launching MPI applications):
mpirun -np 72 -ppn 36 lmp_machine -sf intel -in in.script # 2 nodes, 36 MPI tasks/node, $OMP_NUM_THREADS OpenMP Threads
mpirun -np 72 -ppn 36 lmp_machine -sf intel -in in.script -pk intel 0 omp 2 mode double # Don't use any co-processors that might be available, use 2 OpenMP threads for each task, use double precision
**Or run with the USER-INTEL package by editing an input script:**
Or run with the USER-INTEL package by editing an input script
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
As an alternative to adding command-line arguments, the input script
can be edited to enable the USER-INTEL package. This requires adding
@ -361,7 +371,8 @@ Alternatively, the :doc:`suffix intel <suffix>` command can be added to
the input script to enable USER-INTEL styles for the commands that
follow in the input script.
**Tuning for Performance:**
Tuning for Performance
""""""""""""""""""""""
.. note::
@ -431,7 +442,8 @@ series processors will always perform better using MCDRAM. Please
consult your system documentation for the best approach to specify
that MPI runs are performed in MCDRAM.
**Tuning for Offload Performance:**
Tuning for Offload Performance
""""""""""""""""""""""""""""""
The default settings for offload should give good performance.
@ -521,7 +533,8 @@ the pair styles in the USER-INTEL package currently support the
:doc:`run_style respa <run_style>` command; only the "pair" option is
supported.
**References:**
References
""""""""""
* Brown, W.M., Carrillo, J.-M.Y., Mishra, B., Gavhane, N., Thakkar, F.M., De Kraker, A.R., Yamada, M., Ang, J.A., Plimpton, S.J., "Optimizing Classical Molecular Dynamics in LAMMPS," in Intel Xeon Phi Processor High Performance Programming: Knights Landing Edition, J. Jeffers, J. Reinders, A. Sodani, Eds. Morgan Kaufmann.
* Brown, W. M., Semin, A., Hebenstreit, M., Khvostov, S., Raman, K., Plimpton, S.J. `Increasing Molecular Dynamics Simulation Rates with an 8-Fold Increase in Electrical Power Efficiency. <http://dl.acm.org/citation.cfm?id=3014915>`_ 2016 High Performance Computing, Networking, Storage and Analysis, SC16: International Conference (pp. 82-95).

18
doc/src/Speed_omp.rst
View File

@ -8,18 +8,21 @@ improper), several Kspace styles, and a few fix styles. It uses
the OpenMP interface for multi-threading, but can also be compiled
without OpenMP support, providing optimized serial styles in that case.
**Required hardware/software:**
Required hardware/software
""""""""""""""""""""""""""
To enable multi-threading, your compiler must support the OpenMP interface.
You should have one or more multi-core CPUs, as multiple threads can only be
launched by each MPI task on the local node (using shared memory).
**Building LAMMPS with the USER-OMP package:**
Building LAMMPS with the USER-OMP package
"""""""""""""""""""""""""""""""""""""""""
See the :ref:`Build extras <user-omp>` doc page for
instructions.
**Run with the USER-OMP package from the command line:**
Run with the USER-OMP package from the command line
"""""""""""""""""""""""""""""""""""""""""""""""""""
These examples assume one or more 16-core nodes.
@ -52,7 +55,8 @@ details, including the default values used if it is not specified. It
also gives more details on how to set the number of threads via the
OMP_NUM_THREADS environment variable.
**Or run with the USER-OMP package by editing an input script:**
Or run with the USER-OMP package by editing an input script
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
The discussion above for the mpirun/mpiexec command, MPI tasks/node,
and threads/MPI task is the same.
@ -70,7 +74,8 @@ per MPI task to use. The command doc page explains other options and
how to set the number of threads via the OMP_NUM_THREADS environment
variable.
**Speed-ups to expect:**
Speed-up to expect
""""""""""""""""""
Depending on which styles are accelerated, you should look for a
reduction in the "Pair time", "Bond time", "KSpace time", and "Loop
@ -92,7 +97,8 @@ sub-section.
A description of the multi-threading strategy used in the USER-OMP
package and some performance examples are `presented here <http://sites.google.com/site/akohlmey/software/lammps-icms/lammps-icms-tms2011-talk.pdf?attredirects=0&d=1>`_
**Guidelines for best performance:**
Guidelines for best performance
"""""""""""""""""""""""""""""""
For many problems on current generation CPUs, running the USER-OMP
package with a single thread/task is faster than running with multiple

20
doc/src/Speed_opt.rst
View File

@ -7,15 +7,18 @@ Technologies). It contains a handful of pair styles whose compute()
methods were rewritten in C++ templated form to reduce the overhead
due to if tests and other conditional code.
**Required hardware/software:**
Required hardware/software
""""""""""""""""""""""""""
None.
Any hardware. Any compiler.
**Building LAMMPS with the OPT package:**
Building LAMMPS with the OPT package
""""""""""""""""""""""""""""""""""""
See the :ref:`Build extras <opt>` doc page for instructions.
**Run with the OPT package from the command line:**
Run with the OPT package from the command line
""""""""""""""""""""""""""""""""""""""""""""""
.. code-block:: bash
@ -25,7 +28,8 @@ See the :ref:`Build extras <opt>` doc page for instructions.
Use the "-sf opt" :doc:`command-line switch <Run_options>`, which will
automatically append "opt" to styles that support it.
**Or run with the OPT package by editing an input script:**
Or run with the OPT package by editing an input script
""""""""""""""""""""""""""""""""""""""""""""""""""""""
Use the :doc:`suffix opt <suffix>` command, or you can explicitly add an
"opt" suffix to individual styles in your input script, e.g.
@ -34,13 +38,15 @@ Use the :doc:`suffix opt <suffix>` command, or you can explicitly add an
pair_style lj/cut/opt 2.5
**Speed-ups to expect:**
Speed-up to expect
""""""""""""""""""
You should see a reduction in the "Pair time" value printed at the end
of a run. On most machines for reasonable problem sizes, it will be a
5 to 20% savings.
**Guidelines for best performance:**
Guidelines for best performance
"""""""""""""""""""""""""""""""
Just try out an OPT pair style to see how it performs.

17
doc/src/accel_styles.rst Normal file
View File

@ -0,0 +1,17 @@
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.

12
doc/src/angle_charmm.rst
View File

@ -49,13 +49,14 @@ The following coefficients must be defined for each angle type via the
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* :math:`K` (energy/radian\^2)
* :math:`K` (energy)
* :math:`\theta_0` (degrees)
* :math:`K_{ub}` (energy/distance\^2)
* :math:`r_{ub}` (distance)
:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of :math:`K` are in energy/radian\^2.
:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
radians internally; hence :math:`K` is effectively energy per
radian\^2.
----------
@ -91,7 +92,10 @@ Related commands
:doc:`angle_coeff <angle_coeff>`
**Default:** none
Default
"""""""
none
----------

65
doc/src/angle_class2.rst
View File

@ -41,27 +41,29 @@ The *class2* angle style uses the potential
E_{bb} & = M (r_{ij} - r_1) (r_{jk} - r_2) \\
E_{ba} & = N_1 (r_{ij} - r_1) (\theta - \theta_0) + N_2(r_{jk} - r_2)(\theta - \theta_0)
where :math:`E_a` is the angle term, :math:`E_{bb}` is a bond-bond term, and :math:`E_{ba}` is a
bond-angle term. :math:`\theta_0` is the equilibrium angle and :math:`r_1` and :math:`r_2` are
the equilibrium bond lengths.
where :math:`E_a` is the angle term, :math:`E_{bb}` is a bond-bond
term, and :math:`E_{ba}` is a bond-angle term. :math:`\theta_0` is
the equilibrium angle and :math:`r_1` and :math:`r_2` are the
equilibrium bond lengths.
See :ref:`(Sun) <angle-Sun>` for a description of the COMPASS class2 force field.
Coefficients for the :math:`E_a`, :math:`E_{bb}`, and :math:`E_{ba}` formulas 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>` or :doc:`read_restart <read_restart>`
commands.
Coefficients for the :math:`E_a`, :math:`E_{bb}`, and :math:`E_{ba}`
formulas 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>` or
:doc:`read_restart <read_restart>` commands.
These are the 4 coefficients for the :math:`E_a` formula:
* :math:`\theta_0` (degrees)
* :math:`K_2` (energy/radian\^2)
* :math:`K_3` (energy/radian\^3)
* :math:`K_4` (energy/radian\^4)
* :math:`K_2` (energy)
* :math:`K_3` (energy)
* :math:`K_4` (energy)
:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of the various :math:`K` are in per-radian.
:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
radians internally; hence the various :math:`K` are effectively energy
per radian\^2 or radian\^3 or radian\^4.
For the :math:`E_{bb}` formula, each line in a :doc:`angle_coeff <angle_coeff>`
command in the input script lists 4 coefficients, the first of which
@ -93,23 +95,7 @@ since it is the same value from the :math:`E_a` formula.
----------
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------
@ -122,11 +108,15 @@ The *class2/p6* angle style uses the *class2* potential expanded to sixth order:
In this expanded term 6 coefficients for the :math:`E_a` formula need to be set:
* :math:`\theta_0` (degrees)
* :math:`K_2` (energy/radian\^2)
* :math:`K_3` (energy/radian\^3)
* :math:`K_4` (energy/radian\^4)
* :math:`K_5` (energy/radian\^5)
* :math:`K_6` (energy/radian\^6)
* :math:`K_2` (energy)
* :math:`K_3` (energy)
* :math:`K_4` (energy)
* :math:`K_5` (energy)
* :math:`K_6` (energy)
:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
radians internally; hence the various :math:`K` are effectively energy
per radian\^2 or radian\^3 or radian\^4 or radian\^5 or radian\^6.
The bond-bond and bond-angle terms remain unchanged.
@ -145,7 +135,10 @@ Related commands
:doc:`angle_coeff <angle_coeff>`
**Default:** none
Default
"""""""
none
----------

5
doc/src/angle_coeff.rst
View File

@ -92,4 +92,7 @@ Related commands
:doc:`angle_style <angle_style>`
**Default:** none
Default
"""""""
none

23
doc/src/angle_cosine.rst
View File

@ -44,23 +44,7 @@ or :doc:`read_restart <read_restart>` commands:
----------
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------
@ -76,4 +60,7 @@ Related commands
:doc:`angle_coeff <angle_coeff>`
**Default:** none
Default
"""""""
none

5
doc/src/angle_cosine_buck6d.rst
View File

@ -68,4 +68,7 @@ Related commands
:doc:`angle_coeff <angle_coeff>`
**Default:** none
Default
"""""""
none

23
doc/src/angle_cosine_delta.rst
View File

@ -46,23 +46,7 @@ internally.
----------
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------
@ -78,4 +62,7 @@ Related commands
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_style cosine/squared <angle_cosine_squared>`
**Default:** none
Default
"""""""
none

23
doc/src/angle_cosine_periodic.rst
View File

@ -54,23 +54,7 @@ geometry.
----------
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------
@ -86,7 +70,10 @@ Related commands
:doc:`angle_coeff <angle_coeff>`
**Default:** none
Default
"""""""
none
----------

23
doc/src/angle_cosine_shift.rst
View File

@ -45,23 +45,7 @@ or :doc:`read_restart <read_restart>` commands:
----------
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------
@ -77,4 +61,7 @@ Related commands
:doc:`angle_coeff <angle_coeff>`,
:doc:`angle_style cosine/shift/exp <angle_cosine_shift_exp>`
**Default:** none
Default
"""""""
none

23
doc/src/angle_cosine_shift_exp.rst
View File

@ -56,23 +56,7 @@ or :doc:`read_restart <read_restart>` commands:
----------
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------
@ -90,4 +74,7 @@ Related commands
:doc:`angle_style cosine/shift <angle_cosine_shift>`,
:doc:`dihedral_style cosine/shift/exp <dihedral_cosine_shift_exp>`
**Default:** none
Default
"""""""
none

23
doc/src/angle_cosine_squared.rst
View File

@ -46,23 +46,7 @@ internally.
----------
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------
@ -78,4 +62,7 @@ Related commands
:doc:`angle_coeff <angle_coeff>`
**Default:** none
Default
"""""""
none

14
doc/src/angle_cross.rst
View File

@ -40,14 +40,15 @@ the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* :math:`K_{SS}` (energy/distance\^2)
* :math:`K_{BS0}` (energy/distance/rad)
* :math:`K_{BS1}` (energy/distance/rad)
* :math:`K_{BS0}` (energy/distance)
* :math:`K_{BS1}` (energy/distance)
* :math:`r_{12,0}` (distance)
* :math:`r_{32,0}` (distance)
* :math:`\theta_0` (degrees)
:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of :math:`K_{BS0}` and :math:`K_{BS1}` are in energy/distance/radian.
:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
radians internally; hence the :math:`K_{BS0}` and :math:`K_{BS1}` are
effectively energy/distance per radian.
Restrictions
""""""""""""
@ -61,4 +62,7 @@ Related commands
:doc:`angle_coeff <angle_coeff>`
**Default:** none
Default
"""""""
none

23
doc/src/angle_dipole.rst
View File

@ -82,23 +82,7 @@ or :doc:`read_restart <read_restart>` commands:
----------
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
Restrictions
""""""""""""
@ -129,7 +113,10 @@ Related commands
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_hybrid <angle_hybrid>`
**Default:** none
Default
"""""""
none
----------

23
doc/src/angle_fourier.rst
View File

@ -42,23 +42,7 @@ or :doc:`read_restart <read_restart>` commands:
----------
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------
@ -74,4 +58,7 @@ Related commands
:doc:`angle_coeff <angle_coeff>`
**Default:** none
Default
"""""""
none

23
doc/src/angle_fourier_simple.rst
View File

@ -41,23 +41,7 @@ or :doc:`read_restart <read_restart>` commands:
----------
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------
@ -73,4 +57,7 @@ Related commands
:doc:`angle_coeff <angle_coeff>`
**Default:** none
Default
"""""""
none

30
doc/src/angle_harmonic.rst
View File

@ -44,31 +44,16 @@ The following coefficients must be defined for each angle type via the
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* :math:`K` (energy/radian\^2)
* :math:`K` (energy)
* :math:`\theta_0` (degrees)
:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of :math:`K` are in energy/radian\^2.
:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
radians internally; hence :math:`K` is effectively energy per
radian\^2.
----------
Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` doc page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------
@ -84,4 +69,7 @@ Related commands
:doc:`angle_coeff <angle_coeff>`
**Default:** none
Default
"""""""
none

5
doc/src/angle_hybrid.rst
View File

@ -95,4 +95,7 @@ Related commands
:doc:`angle_coeff <angle_coeff>`
**Default:** none
Default
"""""""
none

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