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

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

Browse Source
This commit is contained in:
Jacob Gissinger
2021-11-04 21:20:29 -04:00
parent 67ae6eb7b6 a4ceda9706
commit 8d4956046b
727 changed files with 31087 additions and 8662 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/CODEOWNERS vendored
View File

@ -83,7 +83,7 @@ src/library.* @sjplimp
src/main.cpp @sjplimp
src/min_*.* @sjplimp
src/memory.* @sjplimp
src/modify.* @sjplimp
src/modify.* @sjplimp @stanmoore1
src/molecule.* @sjplimp
src/my_page.h @sjplimp
src/my_pool_chunk.h @sjplimp

2
.github/workflows/codeql-analysis.yml vendored
View File

@ -3,7 +3,7 @@ name: "CodeQL Code Analysis"
on:
push:
branches: [master]
branches: [develop]
jobs:
analyze:

33
.github/workflows/compile-msvc.yml vendored Normal file
View File

@ -0,0 +1,33 @@
# GitHub action to build LAMMPS on Windows with Visual C++
name: "Native Windows Compilation"
on:
push:
branches: [develop]
jobs:
build:
name: Windows Compilation Test
if: ${{ github.repository == 'lammps/lammps' }}
runs-on: windows-latest
steps:
- name: Checkout repository
uses: actions/checkout@v2
with:
fetch-depth: 2
- name: Building LAMMPS via CMake
shell: bash
run: |
cmake -C cmake/presets/windows.cmake \
-S cmake -B build \
-D BUILD_SHARED_LIBS=on \
-D LAMMPS_EXCEPTIONS=on
cmake --build build --config Release
- name: Run LAMMPS executable
shell: bash
run: |
./build/Release/lmp.exe -h
./build/Release/lmp.exe -in bench/in.lj

2
.github/workflows/unittest-macos.yml vendored
View File

@ -3,7 +3,7 @@ name: "Unittest for MacOS"
on:
push:
branches: [master]
branches: [develop]
jobs:
build:

7
.gitignore vendored
View File

@ -37,8 +37,8 @@ vgcore.*
.Trashes
ehthumbs.db
Thumbs.db
.clang-format
.lammps_history
.vs
#cmake
/build*
@ -49,3 +49,8 @@ Thumbs.db
/Testing
/cmake_install.cmake
/lmp
out/Debug
out/RelWithDebInfo
out/Release
out/x86
out/x64

4
SECURITY.md
View File

@ -23,6 +23,10 @@ either a user mistake or a bug in the code. Bugs can be reported in
the LAMMPS project
[issue tracker on GitHub](https://github.com/lammps/lammps/issues).
To mitigate issues with using homoglyphs or bidirectional reordering in
unicode, which have been demonstrated as a vector to obfuscate and hide
malicious changes to the source code, all LAMMPS submissions are checked
for unicode characters and only all-ASCII source code is accepted.
# Version Updates

66
cmake/CMakeLists.txt
View File

@ -81,22 +81,40 @@ check_for_autogen_files(${LAMMPS_SOURCE_DIR})
include(CheckIncludeFileCXX)
# set required compiler flags and compiler/CPU arch specific optimizations
if((CMAKE_CXX_COMPILER_ID STREQUAL "Intel") OR (CMAKE_CXX_COMPILER_ID STREQUAL "IntelLLVM"))
if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
if(CMAKE_SYSTEM_NAME STREQUAL "Windows")
if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /Qrestrict")
endif()
if(CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.3 OR CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.4)
set(CMAKE_TUNE_DEFAULT "/QxCOMMON-AVX512")
else()
set(CMAKE_TUNE_DEFAULT "/QxHost")
endif()
else()
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -restrict")
if(CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.3 OR CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.4)
set(CMAKE_TUNE_DEFAULT "-xCOMMON-AVX512")
else()
set(CMAKE_TUNE_DEFAULT "-xHost")
endif()
endif()
endif()
# we require C++11 without extensions
# we require C++11 without extensions. Kokkos requires at least C++14 (currently)
set(CMAKE_CXX_STANDARD 11)
if(PKG_KOKKOS AND (CMAKE_CXX_STANDARD LESS 14))
set(CMAKE_CXX_STANDARD 14)
endif()
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF CACHE BOOL "Use compiler extensions")
# ugly hack for MSVC which by default always reports an old C++ standard in the __cplusplus macro
# ugly hacks for MSVC which by default always reports an old C++ standard in the __cplusplus macro
# and prints lots of pointless warnings about "unsafe" functions
if(MSVC)
add_compile_options(/Zc:__cplusplus)
add_compile_options(/wd4244)
add_compile_options(/wd4267)
add_compile_definitions(_CRT_SECURE_NO_WARNINGS)
endif()
# export all symbols when building a .dll file on windows
@ -115,10 +133,7 @@ endif()
set(LAMMPS_BINARY lmp${LAMMPS_MACHINE})
option(BUILD_SHARED_LIBS "Build shared library" OFF)
if(BUILD_SHARED_LIBS) # for all pkg libs, mpi_stubs and linalg
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
endif()
option(CMAKE_POSITION_INDEPENDENT_CODE "Create object compatible with shared libraries" ON)
option(BUILD_TOOLS "Build and install LAMMPS tools (msi2lmp, binary2txt, chain)" OFF)
option(BUILD_LAMMPS_SHELL "Build and install the LAMMPS shell" OFF)
@ -281,9 +296,16 @@ else()
target_include_directories(mpi_stubs PUBLIC $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
if(BUILD_SHARED_LIBS)
target_link_libraries(lammps PRIVATE mpi_stubs)
if(MSVC)
target_link_libraries(lmp PRIVATE mpi_stubs)
target_include_directories(lmp INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
target_compile_definitions(lmp INTERFACE $<INSTALL_INTERFACE:LAMMPS_LIB_NO_MPI>)
endif()
target_include_directories(lammps INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
target_compile_definitions(lammps INTERFACE $<INSTALL_INTERFACE:LAMMPS_LIB_NO_MPI>)
else()
target_include_directories(lammps INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
target_compile_definitions(lammps INTERFACE $<INSTALL_INTERFACE:LAMMPS_LIB_NO_MPI>)
target_link_libraries(lammps PUBLIC mpi_stubs)
endif()
add_library(MPI::MPI_CXX ALIAS mpi_stubs)
@ -468,9 +490,12 @@ foreach(HEADER cmath)
endif(NOT FOUND_${HEADER})
endforeach(HEADER)
set(MATH_LIBRARIES "m" CACHE STRING "math library")
mark_as_advanced( MATH_LIBRARIES )
target_link_libraries(lammps PRIVATE ${MATH_LIBRARIES})
# make the standard math library overrideable and autodetected (for systems that don't have it)
find_library(STANDARD_MATH_LIB m DOC "Standard Math library")
mark_as_advanced(STANDARD_MATH_LIB)
if(STANDARD_MATH_LIB)
target_link_libraries(lammps PRIVATE ${STANDARD_MATH_LIB})
endif()
######################################
# Generate Basic Style files
@ -591,15 +616,12 @@ foreach(PKG_WITH_INCL CORESHELL QEQ OPENMP DPD-SMOOTH KOKKOS OPT INTEL GPU)
endforeach()
if(PKG_PLUGIN)
if(BUILD_SHARED_LIBS)
target_compile_definitions(lammps PRIVATE -DLMP_PLUGIN)
else()
message(WARNING "Plugin loading will not work unless BUILD_SHARED_LIBS is enabled")
endif()
# link with -ldl or equivalent for plugin loading; except on Windows
if(NOT ${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
endif()
# link with -ldl or equivalent for plugin loading; except on Windows
if(NOT ${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
target_link_libraries(lammps PRIVATE ${CMAKE_DL_LIBS})
endif()
endif()
######################################################################
@ -608,7 +630,7 @@ endif()
# and after everything else that is compiled locally
######################################################################
if(CMAKE_SYSTEM_NAME STREQUAL "Windows")
target_link_libraries(lammps PRIVATE -lwsock32 -lpsapi)
target_link_libraries(lammps PRIVATE "wsock32;psapi")
endif()
######################################################
@ -786,11 +808,17 @@ if(ClangFormat_FOUND)
endif()
get_target_property(DEFINES lammps COMPILE_DEFINITIONS)
get_property(BUILD_IS_MULTI_CONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
if(BUILD_IS_MULTI_CONFIG)
set(LAMMPS_BUILD_TYPE "Multi-Config")
else()
set(LAMMPS_BUILD_TYPE ${CMAKE_BUILD_TYPE})
endif()
include(FeatureSummary)
feature_summary(DESCRIPTION "The following tools and libraries have been found and configured:" WHAT PACKAGES_FOUND)
message(STATUS "<<< Build configuration >>>
Operating System: ${CMAKE_SYSTEM_NAME} ${CMAKE_LINUX_DISTRO} ${CMAKE_DISTRO_VERSION}
Build type: ${CMAKE_BUILD_TYPE}
Build type: ${LAMMPS_BUILD_TYPE}
Install path: ${CMAKE_INSTALL_PREFIX}
Generator: ${CMAKE_GENERATOR} using ${CMAKE_MAKE_PROGRAM}")
###############################################################################

111
cmake/CMakeSettings.json Normal file
View File

@ -0,0 +1,111 @@
{
"configurations": [
{
"name": "x64-Debug-MSVC",
"generator": "Ninja",
"configurationType": "Debug",
"buildRoot": "${workspaceRoot}\\build\\${name}",
"installRoot": "${workspaceRoot}\\install\\${name}",
"cmakeCommandArgs": "-S ${workspaceRoot}\\cmake -C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DENABLE_TESTING=on",
"buildCommandArgs": "",
"ctestCommandArgs": "",
"inheritEnvironments": [ "msvc_x64_x64" ],
"variables": [
{
"name": "BUILD_SHARED_LIBS",
"value": "True",
"type": "BOOL"
},
{
"name": "BUILD_TOOLS",
"value": "True",
"type": "BOOL"
},
{
"name": "LAMMPS_EXCEPTIONS",
"value": "True",
"type": "BOOL"
}
]
},
{
"name": "x64-Debug-Clang",
"generator": "Ninja",
"configurationType": "Debug",
"buildRoot": "${workspaceRoot}\\build\\${name}",
"installRoot": "${workspaceRoot}\\install\\${name}",
"cmakeCommandArgs": "-S ${workspaceRoot}\\cmake -C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DENABLE_TESTING=on",
"buildCommandArgs": "",
"ctestCommandArgs": "",
"inheritEnvironments": [ "clang_cl_x64" ],
"variables": [
{
"name": "BUILD_TOOLS",
"value": "True",
"type": "BOOL"
},
{
"name": "LAMMPS_EXCEPTIONS",
"value": "True",
"type": "BOOL"
}
]
},
{
"name": "x64-Debug-OneAPI",
"generator": "Ninja",
"configurationType": "Debug",
"buildRoot": "${workspaceRoot}\\build\\${name}",
"installRoot": "${workspaceRoot}\\install\\${name}",
"cmakeCommandArgs": "-S ${workspaceRoot}\\cmake -C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DENABLE_TESTING=on -DCMAKE_CXX_COMPILER=icx -DCMAKE_C_COMPILER=icx -DBUILD_MPI=off",
"buildCommandArgs": "",
"ctestCommandArgs": "",
"inheritEnvironments": [ "msvc_x64_x64" ],
"variables": [
{
"name": "BUILD_SHARED_LIBS",
"value": "True",
"type": "BOOL"
},
{
"name": "BUILD_TOOLS",
"value": "True",
"type": "BOOL"
},
{
"name": "LAMMPS_EXCEPTIONS",
"value": "True",
"type": "BOOL"
}
]
},
{
"name": "x64-Debug-Intel",
"generator": "Ninja",
"configurationType": "Debug",
"buildRoot": "${workspaceRoot}\\build\\${name}",
"installRoot": "${workspaceRoot}\\install\\${name}",
"cmakeCommandArgs": "-S ${workspaceRoot}\\cmake -C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DENABLE_TESTING=off -DCMAKE_CXX_COMPILER=icl -DCMAKE_C_COMPILER=icl -DCMAKE_Fortran_COMPILER=ifort -DBUILD_MPI=off",
"buildCommandArgs": "",
"ctestCommandArgs": "",
"inheritEnvironments": [ "msvc_x64_x64" ],
"variables": [
{
"name": "BUILD_SHARED_LIBS",
"value": "True",
"type": "BOOL"
},
{
"name": "BUILD_TOOLS",
"value": "True",
"type": "BOOL"
},
{
"name": "LAMMPS_EXCEPTIONS",
"value": "True",
"type": "BOOL"
}
]
}
]
}

33
cmake/Modules/ExternalCMakeProject.cmake Normal file
View File

@ -0,0 +1,33 @@
# Build a CMake based external library as subdirectory.
# The sources will be unpacked to ${CMAKE_BINARY_DIR}/_deps/${target}-src
# The binaries will be built in ${CMAKE_BINARY_DIR}/_deps/${target}-build
#
function(ExternalCMakeProject target url hash basedir cmakedir cmakefile)
# change settings locally
set(BUILD_SHARED_LIBS OFF)
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
get_filename_component(archive ${url} NAME)
file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/_deps/src)
message(STATUS "Downloading ${url}")
file(DOWNLOAD ${url} ${CMAKE_BINARY_DIR}/_deps/${archive} EXPECTED_HASH MD5=${hash} SHOW_PROGRESS)
message(STATUS "Unpacking and configuring ${archive}")
execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf ${CMAKE_BINARY_DIR}/_deps/${archive}
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/_deps/src)
file(GLOB TARGET_SOURCE "${CMAKE_BINARY_DIR}/_deps/src/${basedir}*")
list(LENGTH TARGET_SOURCE _num)
if(_num GREATER 1)
message(FATAL_ERROR "Inconsistent ${target} library sources. "
"Please delete ${CMAKE_BINARY_DIR}/_deps/src and re-run cmake")
endif()
file(REMOVE_RECURSE ${CMAKE_BINARY_DIR}/_deps/${target}-src)
file(RENAME ${TARGET_SOURCE} ${CMAKE_BINARY_DIR}/_deps/${target}-src)
if(NOT (cmakefile STREQUAL ""))
file(COPY ${cmakefile} DESTINATION ${CMAKE_BINARY_DIR}/_deps/${target}-src/${cmakedir}/)
get_filename_component(_cmakefile ${cmakefile} NAME)
file(RENAME "${CMAKE_BINARY_DIR}/_deps/${target}-src/${cmakedir}/${_cmakefile}"
"${CMAKE_BINARY_DIR}/_deps/${target}-src/${cmakedir}/CMakeLists.txt")
endif()
add_subdirectory("${CMAKE_BINARY_DIR}/_deps/${target}-src/${cmakedir}"
"${CMAKE_BINARY_DIR}/_deps/${target}-build")
endfunction(ExternalCMakeProject)

81
cmake/Modules/GTest.cmake
View File

@ -1,81 +0,0 @@
message(STATUS "Downloading and building Google Test library")
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
set(GTEST_LIB_POSTFIX d)
else()
set(GTEST_LIB_POSTFIX)
endif()
include(ExternalProject)
set(GTEST_URL "https://github.com/google/googletest/archive/release-1.10.0.tar.gz" CACHE STRING "URL for GTest tarball")
set(GTEST_MD5 "ecd1fa65e7de707cd5c00bdac56022cd" CACHE STRING "MD5 checksum of GTest tarball")
mark_as_advanced(GTEST_URL)
mark_as_advanced(GTEST_MD5)
ExternalProject_Add(googletest
URL ${GTEST_URL}
URL_MD5 ${GTEST_MD5}
SOURCE_DIR "${CMAKE_BINARY_DIR}/gtest-src"
BINARY_DIR "${CMAKE_BINARY_DIR}/gtest-build"
CMAKE_ARGS ${CMAKE_REQUEST_PIC} ${CMAKE_EXTRA_GTEST_OPTS}
-DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
-DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>
-DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
-DCMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM}
-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
BUILD_BYPRODUCTS <BINARY_DIR>/lib/libgtest${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
<BINARY_DIR>/lib/libgmock${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
<BINARY_DIR>/lib/libgtest_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
<BINARY_DIR>/lib/libgmock_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
LOG_DOWNLOAD ON
LOG_CONFIGURE ON
LOG_BUILD ON
INSTALL_COMMAND ""
TEST_COMMAND "")
ExternalProject_Get_Property(googletest SOURCE_DIR)
set(GTEST_INCLUDE_DIR ${SOURCE_DIR}/googletest/include)
set(GMOCK_INCLUDE_DIR ${SOURCE_DIR}/googlemock/include)
# workaround for CMake 3.10 on ubuntu 18.04
file(MAKE_DIRECTORY ${GTEST_INCLUDE_DIR})
file(MAKE_DIRECTORY ${GMOCK_INCLUDE_DIR})
ExternalProject_Get_Property(googletest BINARY_DIR)
set(GTEST_LIBRARY_PATH ${BINARY_DIR}/lib/libgtest${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
set(GMOCK_LIBRARY_PATH ${BINARY_DIR}/lib/libgmock${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
set(GTEST_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/libgtest_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
set(GMOCK_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/libgmock_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
# Prevent GoogleTest from overriding our compiler/linker options
# when building with Visual Studio
set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
find_package(Threads QUIET)
add_library(GTest::GTest UNKNOWN IMPORTED)
set_target_properties(GTest::GTest PROPERTIES
IMPORTED_LOCATION ${GTEST_LIBRARY_PATH}
INTERFACE_INCLUDE_DIRECTORIES ${GTEST_INCLUDE_DIR}
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}
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}
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}
INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
add_dependencies(GTest::GMockMain googletest)

2
cmake/Modules/LAMMPSUtils.cmake
View File

@ -85,7 +85,7 @@ endfunction(GenerateBinaryHeader)
# fetch missing potential files
function(FetchPotentials pkgfolder potfolder)
if (EXISTS "${pkgfolder}/potentials.txt")
if(EXISTS "${pkgfolder}/potentials.txt")
file(STRINGS "${pkgfolder}/potentials.txt" linelist REGEX "^[^#].")
foreach(line ${linelist})
string(FIND ${line} " " blank)

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

@ -1,7 +1,7 @@
########################################################################
# As of version 3.3.0 Kokkos requires C++14
if(CMAKE_CXX_STANDARD LESS 14)
set(CMAKE_CXX_STANDARD 14)
message(FATAL_ERROR "The KOKKOS package requires the C++ standard to be set to at least C++14")
endif()
########################################################################
# consistency checks and Kokkos options/settings required by LAMMPS

5
cmake/Modules/Packages/MACHDYN.cmake
View File

@ -7,8 +7,9 @@ endif()
option(DOWNLOAD_EIGEN3 "Download Eigen3 instead of using an already installed one)" ${DOWNLOAD_EIGEN3_DEFAULT})
if(DOWNLOAD_EIGEN3)
message(STATUS "Eigen3 download requested - we will build our own")
set(EIGEN3_URL "https://gitlab.com/libeigen/eigen/-/archive/3.3.9/eigen-3.3.9.tar.gz" CACHE STRING "URL for Eigen3 tarball")
set(EIGEN3_MD5 "609286804b0f79be622ccf7f9ff2b660" CACHE STRING "MD5 checksum of Eigen3 tarball")
set(EIGEN3_URL "${LAMMPS_THIRDPARTY_URL}/eigen-3.4.0.tar.gz" CACHE STRING "URL for Eigen3 tarball")
set(EIGEN3_MD5 "4c527a9171d71a72a9d4186e65bea559" CACHE STRING "MD5 checksum of Eigen3 tarball")
mark_as_advanced(EIGEN3_URL)
mark_as_advanced(EIGEN3_MD5)
include(ExternalProject)

21
cmake/Modules/Packages/ML-PACE.cmake
View File

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

3
cmake/Modules/Packages/ML-QUIP.cmake
View File

@ -32,7 +32,8 @@ if(DOWNLOAD_QUIP)
foreach(flag ${LAPACK_LIBRARIES})
set(temp "${temp} ${flag}")
endforeach()
set(temp "${temp}\n")
# Fix cmake crashing when MATH_LINKOPTS not set, required for e.g. recent Cray Programming Environment
set(temp "${temp} -L/_DUMMY_PATH_\n")
set(temp "${temp}PYTHON=python\nPIP=pip\nEXTRA_LINKOPTS=\n")
set(temp "${temp}HAVE_CP2K=0\nHAVE_VASP=0\nHAVE_TB=0\nHAVE_PRECON=1\nHAVE_LOTF=0\nHAVE_ONIOM=0\n")
set(temp "${temp}HAVE_LOCAL_E_MIX=0\nHAVE_QC=0\nHAVE_GAP=1\nHAVE_DESCRIPTORS_NONCOMMERCIAL=1\n")

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

@ -12,41 +12,12 @@ if(DOWNLOAD_MSCG)
mark_as_advanced(MSCG_URL)
mark_as_advanced(MSCG_MD5)
# CMake cannot pass BLAS or LAPACK library variable to external project if they are a list
list(LENGTH BLAS_LIBRARIES} NUM_BLAS)
list(LENGTH LAPACK_LIBRARIES NUM_LAPACK)
if((NUM_BLAS GREATER 1) OR (NUM_LAPACK GREATER 1))
message(FATAL_ERROR "Cannot compile downloaded MSCG library due to a technical limitation")
endif()
include(ExternalCMakeProject)
ExternalCMakeProject(mscg ${MSCG_URL} ${MSCG_MD5} MSCG-release src/CMake "")
include(ExternalProject)
ExternalProject_Add(mscg_build
URL ${MSCG_URL}
URL_MD5 ${MSCG_MD5}
SOURCE_SUBDIR src/CMake
CMAKE_ARGS ${CMAKE_REQUEST_PIC} ${EXTRA_MSCG_OPTS}
-DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}
-DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
-DCMAKE_Fortran_COMPILER=${CMAKE_Fortran_COMPILER}
-DBLAS_LIBRARIES=${BLAS_LIBRARIES} -DLAPACK_LIBRARIES=${LAPACK_LIBRARIES}
-DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>
-DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
-DCMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM}
-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
BUILD_COMMAND ${CMAKE_COMMAND} --build . --target mscg
INSTALL_COMMAND ""
BUILD_BYPRODUCTS <BINARY_DIR>/libmscg.a
)
ExternalProject_get_property(mscg_build BINARY_DIR)
ExternalProject_get_property(mscg_build SOURCE_DIR)
file(MAKE_DIRECTORY ${SOURCE_DIR}/src)
add_library(LAMMPS::MSCG UNKNOWN IMPORTED)
set_target_properties(LAMMPS::MSCG PROPERTIES
IMPORTED_LOCATION "${BINARY_DIR}/libmscg.a"
INTERFACE_INCLUDE_DIRECTORIES "${SOURCE_DIR}/src"
INTERFACE_LINK_LIBRARIES "${LAPACK_LIBRARIES}")
target_link_libraries(lammps PRIVATE LAMMPS::MSCG)
add_dependencies(LAMMPS::MSCG mscg_build)
# set include and link library
target_include_directories(lammps PRIVATE "${CMAKE_BINARY_DIR}/_deps/mscg-src/src")
target_link_libraries(lammps PRIVATE mscg)
else()
find_package(MSCG)
if(NOT MSCG_FOUND)

4
cmake/Modules/Tools.cmake
View File

@ -25,7 +25,9 @@ if(BUILD_TOOLS)
get_filename_component(MSI2LMP_SOURCE_DIR ${LAMMPS_TOOLS_DIR}/msi2lmp/src ABSOLUTE)
file(GLOB MSI2LMP_SOURCES ${MSI2LMP_SOURCE_DIR}/[^.]*.c)
add_executable(msi2lmp ${MSI2LMP_SOURCES})
target_link_libraries(msi2lmp PRIVATE ${MATH_LIBRARIES})
if(STANDARD_MATH_LIB)
target_link_libraries(msi2lmp PRIVATE ${STANDARD_MATH_LIB})
endif()
install(TARGETS msi2lmp DESTINATION ${CMAKE_INSTALL_BINDIR})
install(FILES ${LAMMPS_DOC_DIR}/msi2lmp.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
endif()

47
cmake/Modules/YAML.cmake
View File

@ -1,47 +0,0 @@
message(STATUS "Downloading and building YAML library")
include(ExternalProject)
set(YAML_URL "https://pyyaml.org/download/libyaml/yaml-0.2.5.tar.gz" CACHE STRING "URL for libyaml tarball")
set(YAML_MD5 "bb15429d8fb787e7d3f1c83ae129a999" CACHE STRING "MD5 checksum of libyaml tarball")
mark_as_advanced(YAML_URL)
mark_as_advanced(YAML_MD5)
# support cross-compilation to windows
if(CMAKE_CROSSCOMPILING AND (CMAKE_SYSTEM_NAME STREQUAL "Windows"))
if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86")
set(YAML_CROSS_HOST --host=i686-mingw64)
elseif(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
set(YAML_CROSS_HOST --host=x86_64-mingw64)
else()
message(FATAL_ERROR "Unsupported cross-compilation "
" for ${CMAKE_SYSTEM_NAME}/${CMAKE_SYSTEM_PROCESSOR}"
" on ${CMAKE_HOST_SYSTEM}/${CMAKE_HOST_SYSTEM_PROCESSOR}")
endif()
endif()
ExternalProject_Add(libyaml
URL ${YAML_URL}
URL_MD5 ${YAML_MD5}
SOURCE_DIR "${CMAKE_BINARY_DIR}/yaml-src"
BINARY_DIR "${CMAKE_BINARY_DIR}/yaml-build"
CONFIGURE_COMMAND <SOURCE_DIR>/configure ${CONFIGURE_REQUEST_PIC}
CXX=${CMAKE_CXX_COMPILER} CC=${CMAKE_C_COMPILER}
--prefix=<INSTALL_DIR> --disable-shared ${YAML_CROSS_HOST}
BUILD_BYPRODUCTS <INSTALL_DIR>/lib/libyaml${CMAKE_STATIC_LIBRARY_SUFFIX}
TEST_COMMAND "")
ExternalProject_Get_Property(libyaml INSTALL_DIR)
set(YAML_INCLUDE_DIR ${INSTALL_DIR}/include)
set(YAML_LIBRARY_DIR ${INSTALL_DIR}/lib)
# workaround for CMake 3.10 on ubuntu 18.04
file(MAKE_DIRECTORY ${YAML_INCLUDE_DIR})
file(MAKE_DIRECTORY ${YAML_LIBRARY_DIR})
set(YAML_LIBRARY_PATH ${INSTALL_DIR}/lib/libyaml${CMAKE_STATIC_LIBRARY_SUFFIX})
add_library(Yaml::Yaml UNKNOWN IMPORTED)
set_target_properties(Yaml::Yaml PROPERTIES
IMPORTED_LOCATION ${YAML_LIBRARY_PATH}
INTERFACE_INCLUDE_DIRECTORIES ${YAML_INCLUDE_DIR})
add_dependencies(Yaml::Yaml libyaml)

64
cmake/presets/windows.cmake Normal file
View File

@ -0,0 +1,64 @@
set(WIN_PACKAGES
ASPHERE
BOCS
BODY
BROWNIAN
CG-DNA
CG-SDK
CLASS2
COLLOID
COLVARS
CORESHELL
DIELECTRIC
DIFFRACTION
DIPOLE
DPD-BASIC
DPD-MESO
DPD-REACT
DPD-SMOOTH
DRUDE
EFF
EXTRA-COMPUTE
EXTRA-DUMP
EXTRA-FIX
EXTRA-MOLECULE
EXTRA-PAIR
FEP
GRANULAR
INTERLAYER
KSPACE
MANIFOLD
MANYBODY
MC
MEAM
MISC
ML-IAP
ML-SNAP
MOFFF
MOLECULE
MOLFILE
OPENMP
ORIENT
PERI
PHONON
POEMS
PTM
QEQ
QTB
REACTION
REAXFF
REPLICA
RIGID
SHOCK
SMTBQ
SPH
SPIN
SRD
TALLY
UEF
YAFF)
foreach(PKG ${WIN_PACKAGES})
set(PKG_${PKG} ON CACHE BOOL "" FORCE)
endforeach()

2
doc/Makefile
View File

@ -230,7 +230,7 @@ $(VENV):
)
$(MATHJAX):
@git clone -b 3.2.0 -c advice.detachedHead=0 --depth 1 git://github.com/mathjax/MathJax.git $@
@git clone -b 3.2.0 -c advice.detachedHead=0 --depth 1 https://github.com/mathjax/MathJax.git $@
$(ANCHORCHECK): $(VENV)
@( \

2
doc/doxygen/Doxyfile.in
View File

@ -435,6 +435,8 @@ INPUT = @LAMMPS_SOURCE_DIR@/utils.cpp \
@LAMMPS_SOURCE_DIR@/my_pool_chunk.cpp \
@LAMMPS_SOURCE_DIR@/my_pool_chunk.h \
@LAMMPS_SOURCE_DIR@/math_eigen.h \
@LAMMPS_SOURCE_DIR@/platform.h \
@LAMMPS_SOURCE_DIR@/platform.cpp \
# 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

12
doc/github-development-workflow.md
View File

@ -33,9 +33,9 @@ when necessary.
## Pull Requests
ALL changes to the LAMMPS code and documentation, however trivial, MUST
be submitted as a pull request to GitHub. All changes to the "master"
be submitted as a pull request to GitHub. All changes to the "develop"
branch must be made exclusively through merging pull requests. The
"unstable" and "stable" branches, respectively are only to be updated
"release" and "stable" branches, respectively are only to be updated
upon patch or stable releases with fast-forward merges based on the
associated tags. Pull requests may also be submitted to (long-running)
feature branches created by LAMMPS developers inside the LAMMPS project,
@ -123,16 +123,16 @@ and thus were this comment should be placed.
LAMMPS uses a continuous release development model with incremental
changes, i.e. significant effort is made - including automated pre-merge
testing - that the code in the branch "master" does not get easily
testing - that the code in the branch "develop" does not get easily
broken. These tests are run after every update to a pull request. More
extensive and time consuming tests (including regression testing) are
performed after code is merged to the "master" branch. There are patch
performed after code is merged to the "develop" branch. There are patch
releases of LAMMPS every 3-5 weeks at a point, when the LAMMPS
developers feel, that a sufficient amount of changes have happened, and
the post-merge testing has been successful. These patch releases are
marked with a `patch_<version date>` tag and the "unstable" branch
marked with a `patch_<version date>` tag and the "release" branch
follows only these versions (and thus is always supposed to be of
production quality, unlike "master", which may be temporary broken, in
production quality, unlike "develop", which may be temporary broken, in
the case of larger change sets or unexpected incompatibilities or side
effects.

2
doc/lammps.1
View File

@ -1,4 +1,4 @@
.TH LAMMPS "29 September 2021" "2021-09-29"
.TH LAMMPS "1" "27 October 2021" "2021-10-27"
.SH NAME
.B LAMMPS
\- Molecular Dynamics Simulator.

2
doc/msi2lmp.1
View File

@ -1,4 +1,4 @@
.TH MSI2LMP "v3.9.9" "2018-11-05"
.TH MSI2LMP "1" "v3.9.9" "2018-11-05"
.SH NAME
.B MSI2LMP
\- Converter for Materials Studio files to LAMMPS

36
doc/src/Build_cmake.rst
View File

@ -150,6 +150,42 @@ for IDEs like Eclipse, CodeBlocks, or Kate can be selected using the *-G*
command line flag. A list of available generator settings for your
specific CMake version is given when running ``cmake --help``.
.. _cmake_multiconfig:
Multi-configuration build systems
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Throughout this manual it is mostly assumed that LAMMPS is being built
on a Unix-like operating system with "make" as the underlying "builder",
since this is the most common case. In this case the build "configuration"
is chose using ``-D CMAKE_BUILD_TYPE=<configuration>`` with ``<configuration>``
being one of "Release", "Debug", "RelWithDebInfo", or "MinSizeRel".
Some build tools, however, can also use or even require to have a so-called
multi-configuration build system setup. For those the built type (or
configuration) is chosen at compile time using the same build files. E.g.
with:
.. code-block:: bash
cmake --build build-multi --config Release
In that case the resulting binaries are not in the build folder directly
but in sub-directories corresponding to the build type (i.e. Release in
the example from above). Similarly, for running unit tests the
configuration is selected with the *-C* flag:
.. code-block:: bash
ctest -C Debug
The CMake scripts in LAMMPS have basic support for being compiled using a
multi-config build system, but not all of it has been ported. This is in
particular applicable to compiling packages that require additional libraries
that would be downloaded and compiled by CMake. The "windows" preset file
tries to keep track of which packages can be compiled natively with the
MSVC compilers out-of-the box. Not all of those external libraries are
portable to Windows either.
Installing CMake
^^^^^^^^^^^^^^^^

2
doc/src/Build_diskspace.rst
View File

@ -14,7 +14,7 @@ environments with restricted disk space capacity it may be needed to
reduce the storage requirements. Here are some suggestions:
- Create a so-called shallow repository by cloning only the last commit
instead of the full project history by using ``git clone git@github.com:lammps/lammps --depth=1 --branch=master``.
instead of the full project history by using ``git clone git@github.com:lammps/lammps --depth=1 --branch=develop``.
This reduces the downloaded size to about half. With ``--depth=1`` it is not possible to check out different
versions/branches of LAMMPS, using ``--depth=1000`` will make multiple recent versions available at little
extra storage needs (the entire git history had nearly 30,000 commits in fall 2021).

15
doc/src/Build_manual.rst
View File

@ -33,12 +33,15 @@ various tools and files. Some of them have to be installed (see below). For
the rest the build process will attempt to download and install them into
a python virtual environment and local folders.
A current version of the manual (latest patch release, aka unstable
branch) is is available online at:
`https://docs.lammps.org/Manual.html <https://docs.lammps.org/Manual.html>`_.
A version of the manual corresponding to the ongoing development (aka master branch)
is available online at: `https://docs.lammps.org/latest/
<https://docs.lammps.org/latest/>`_
A current version of the manual (latest patch release, that is the state
of the *release* branch) is is available online at:
`https://docs.lammps.org/ <https://docs.lammps.org/>`_.
A version of the manual corresponding to the ongoing development (that is
the state of the *develop* branch) is available online at:
`https://docs.lammps.org/latest/ <https://docs.lammps.org/latest/>`_
A version of the manual corresponding to the latest stable LAMMPS release
(that is the state of the *stable* branch) is available online at:
`https://docs.lammps.org/stable/ <https://docs.lammps.org/stable/>`_
Build using GNU make
--------------------

32
doc/src/Build_settings.rst
View File

@ -321,9 +321,7 @@ following settings:
.. code-block:: make
LMP_INC = -DLAMMPS_JPEG
LMP_INC = -DLAMMPS_PNG
LMP_INC = -DLAMMPS_FFMPEG
LMP_INC = -DLAMMPS_JPEG -DLAMMPS_PNG -DLAMMPS_FFMPEG <other LMP_INC settings>
JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header files if make cannot find them
JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them
@ -354,8 +352,10 @@ Read or write compressed files
-----------------------------------------
If this option is enabled, large files can be read or written with
gzip compression by several LAMMPS commands, including
:doc:`read_data <read_data>`, :doc:`rerun <rerun>`, and :doc:`dump <dump>`.
compression by ``gzip`` or similar tools by several LAMMPS commands,
including :doc:`read_data <read_data>`, :doc:`rerun <rerun>`, and
:doc:`dump <dump>`. Currently supported compression tools are:
``gzip``, ``bzip2``, ``zstd``, and ``lzma``.
.. tabs::
@ -364,23 +364,23 @@ gzip compression by several LAMMPS commands, including
.. code-block:: bash
-D WITH_GZIP=value # yes or no
# default is yes if CMake can find gzip, else no
-D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it
# default is yes if CMake can find the gzip program, else no
.. tab:: Traditional make
.. code-block:: make
LMP_INC = -DLAMMPS_GZIP
LMP_INC = -DLAMMPS_GZIP <other LMP_INC settings>
This option requires that your operating system fully supports the "popen()"
function in the standard runtime library and that a ``gzip`` executable can be
found by LAMMPS during a run.
This option requires that your operating system fully supports the
"popen()" function in the standard runtime library and that a ``gzip``
or other executable can be found by LAMMPS in the standard search path
during a run.
.. note::
On some clusters with high-speed networks, using the "fork()" library
call (required by "popen()") can interfere with the fast communication
On clusters with high-speed networks, using the "fork()" library call
(required by "popen()") can interfere with the fast communication
library and lead to simulations using compressed output or input to
hang or crash. For selected operations, compressed file I/O is also
available using a compression library instead, which is what the
@ -452,7 +452,7 @@ those systems:
.. code-block:: make
LMP_INC = -DLAMMPS_LONGLONG_TO_LONG
LMP_INC = -DLAMMPS_LONGLONG_TO_LONG <other LMP_INC settings>
----------
@ -479,7 +479,7 @@ e.g. to Python. Of course, the calling code has to be set up to
.. code-block:: make
LMP_INC = -DLAMMPS_EXCEPTIONS
LMP_INC = -DLAMMPS_EXCEPTIONS <other LMP_INC settings>
.. note::
@ -520,7 +520,7 @@ executable, not the library.
.. code-block:: make
LMP_INC = -DLAMMPS_TRAP_FPE
LMP_INC = -DLAMMPS_TRAP_FPE <other LMP_INC settings>
After compilation with this flag set, the LAMMPS executable will stop
and produce a core dump when a division by zero, overflow, illegal math

49
doc/src/Build_windows.rst
View File

@ -4,6 +4,7 @@ Notes for building LAMMPS on Windows
* :ref:`General remarks <generic>`
* :ref:`Running Linux on Windows <linux>`
* :ref:`Using GNU GCC ported to Windows <gnu>`
* :ref:`Using Visual Studio <msvc>`
* :ref:`Using a cross-compiler <cross>`
----------
@ -31,13 +32,13 @@ pre-compiled Windows binary packages are sufficient for your needs. If
it is necessary for you to compile LAMMPS on a Windows machine
(e.g. because it is your main desktop), please also consider using a
virtual machine software and compile and run LAMMPS in a Linux virtual
machine, or - if you have a sufficiently up-to-date Windows 10
installation - consider using the Windows subsystem for Linux. This
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_wsl>`.
machine, or - if you have a sufficiently up-to-date Windows 10 or
Windows 11 installation - consider using the Windows subsystem for
Linux. This 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_wsl>`.
.. _gnu:
@ -67,6 +68,40 @@ requiring changes to the LAMMPS source code, or figure out corrections
yourself, please report them on the lammps-users mailing list, or file
them as an issue or pull request on the LAMMPS GitHub project.
.. _msvc:
Using Microsoft Visual Studio
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Following the integration of the :doc:`platform namespace
<Developer_platform>` into the LAMMPS code base, portability of LAMMPS
to be compiled on Windows using Visual Studio has been significantly
improved. This has been tested with Visual Studio 2019 (aka version
16). Not all features and packages in LAMMPS are currently supported
out of the box, but a preset ``cmake/presets/windows.cmake`` is provided
that contains the packages that have been compiled successfully. You
must use the CMake based build procedure, and either use the integrated
CMake support of Visual Studio or use an external CMake installation to
create build files for the Visual Studio build system. Please note that
on launching Visual Studio it will scan the directory tree and likely
miss the correct master ``CMakeLists.txt``. Try to open the
``cmake/CMakeSettings.json`` and use those CMake configurations as a
starting point. It is also possible to configure and compile LAMMPS
from the command line with a CMake binary from `cmake.org <https://cmake.org>`_.
Please note, that for either approach CMake will create a so-called
:ref:`"multi-configuration" build environment <cmake_multiconfig>`, and
the command lines for building and testing LAMMPS must be adjusted
accordingly.
To support running in parallel you can compile with OpenMP enabled using
the OPENMP package or install Microsoft MPI (including the SDK) and compile
LAMMPS with MPI enabled.
This is work in progress and you should contact the LAMMPS developers
via GitHub, the forum, or the mailing list, if you have questions or
LAMMPS specific problems.
.. _cross:
Using a cross-compiler

2
doc/src/Commands_fix.rst
View File

@ -23,6 +23,7 @@ OPT.
:columns: 5
* :doc:`accelerate/cos <fix_accelerate_cos>`
* :doc:`acks2/reaxff (k) <fix_acks2_reaxff>`
* :doc:`adapt <fix_adapt>`
* :doc:`adapt/fep <fix_adapt_fep>`
* :doc:`addforce <fix_addforce>`
@ -103,6 +104,7 @@ OPT.
* :doc:`manifoldforce <fix_manifoldforce>`
* :doc:`mdi/engine <fix_mdi_engine>`
* :doc:`meso/move <fix_meso_move>`
* :doc:`mol/swap <fix_mol_swap>`
* :doc:`momentum (k) <fix_momentum>`
* :doc:`momentum/chunk <fix_momentum>`
* :doc:`move <fix_move>`

1
doc/src/Developer.rst
View File

@ -18,4 +18,5 @@ of time and requests from the LAMMPS user community.
Developer_plugins
Developer_unittest
Classes
Developer_platform
Developer_utils

155
doc/src/Developer_platform.rst Normal file
View File

@ -0,0 +1,155 @@
Platform abstraction functions
------------------------------
The ``platform`` sub-namespace inside the ``LAMMPS_NS`` namespace
provides a collection of wrapper and convenience functions and utilities
that perform common tasks for which platform specific code would be
required or for which a more high-level abstraction would be convenient
and reduce duplicated code. This reduces redundant implementations and
encourages consistent behavior and thus has some overlap with the
:doc:`"utils" sub-namespace <Developer_utils>`.
Time functions
^^^^^^^^^^^^^^
.. doxygenfunction:: cputime
:project: progguide
.. doxygenfunction:: walltime
:project: progguide
.. doxygenfunction:: usleep
:project: progguide
Platform information functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: os_info
:project: progguide
.. doxygenfunction:: compiler_info
:project: progguide
.. doxygenfunction:: cxx_standard
:project: progguide
.. doxygenfunction:: openmp_standard
:project: progguide
.. doxygenfunction:: mpi_vendor
:project: progguide
.. doxygenfunction:: mpi_info
:project: progguide
.. doxygenfunction:: compress_info
:project: progguide
File and path functions and global constants
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenvariable:: filepathsep
:project: progguide
.. doxygenvariable:: pathvarsep
:project: progguide
.. doxygenfunction:: guesspath
:project: progguide
.. doxygenfunction:: path_basename
:project: progguide
.. doxygenfunction:: path_join
:project: progguide
.. doxygenfunction:: file_is_readable
:project: progguide
.. doxygenfunction:: is_console
:project: progguide
.. doxygenfunction:: path_is_directory
:project: progguide
.. doxygenfunction:: current_directory
:project: progguide
.. doxygenfunction:: list_directory
:project: progguide
.. doxygenfunction:: chdir
:project: progguide
.. doxygenfunction:: mkdir
:project: progguide
.. doxygenfunction:: rmdir
:project: progguide
.. doxygenfunction:: unlink
:project: progguide
Standard I/O function wrappers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenvariable:: END_OF_FILE
:project: progguide
.. doxygenfunction:: ftell
:project: progguide
.. doxygenfunction:: fseek
:project: progguide
.. doxygenfunction:: ftruncate
:project: progguide
.. doxygenfunction:: popen
:project: progguide
.. doxygenfunction:: pclose
:project: progguide
Environment variable functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: putenv
:project: progguide
.. doxygenfunction:: unsetenv
:project: progguide
.. doxygenfunction:: list_pathenv
:project: progguide
.. doxygenfunction:: find_exe_path
:project: progguide
Dynamically loaded object or library functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: dlopen
:project: progguide
.. doxygenfunction:: dlclose
:project: progguide
.. doxygenfunction:: dlsym
:project: progguide
.. doxygenfunction:: dlerror
:project: progguide
Compressed file I/O functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: has_compress_extension
:project: progguide
.. doxygenfunction:: compressed_read
:project: progguide
.. doxygenfunction:: compressed_write
:project: progguide

25
doc/src/Developer_utils.rst
View File

@ -7,7 +7,9 @@ a collection of convenience functions and utilities that perform common
tasks that are required repeatedly throughout the LAMMPS code like
reading or writing to files with error checking or translation of
strings into specific types of numbers with checking for validity. This
reduces redundant implementations and encourages consistent behavior.
reduces redundant implementations and encourages consistent behavior and
thus has some overlap with the :doc:`"platform" sub-namespace
<Developer_platform>`.
I/O with status check and similar functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -101,6 +103,12 @@ and parsing files or arguments.
.. doxygenfunction:: strdup
:project: progguide
.. doxygenfunction:: lowercase
:project: progguide
.. doxygenfunction:: uppercase
:project: progguide
.. doxygenfunction:: trim
:project: progguide
@ -143,21 +151,6 @@ and parsing files or arguments.
.. doxygenfunction:: is_double
:project: progguide
File and path functions
^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: guesspath
:project: progguide
.. doxygenfunction:: path_basename
:project: progguide
.. doxygenfunction:: path_join
:project: progguide
.. doxygenfunction:: file_is_readable
:project: progguide
Potential file functions
^^^^^^^^^^^^^^^^^^^^^^^^

4
doc/src/Developer_write.rst
View File

@ -29,7 +29,9 @@ of code in the header before include guards:
.. code-block:: c
#ifdef FIX_CLASS
FixStyle(print/vel,FixPrintVel)
// clang-format off
FixStyle(print/vel,FixPrintVel);
// clang-format on
#else
/* the definition of the FixPrintVel class comes here */
...

4
doc/src/Examples.rst
View File

@ -80,7 +80,7 @@ Lowercase directories
+-------------+------------------------------------------------------------------+
| friction | frictional contact of spherical asperities between 2d surfaces |
+-------------+------------------------------------------------------------------+
| gcmc | Grand Canonical Monte Carlo (GCMC) via the fix gcmc command |
| mc | Monte Carlo features via fix gcmc, widom and other commands |
+-------------+------------------------------------------------------------------+
| granregion | use of fix wall/region/gran as boundary on granular particles |
+-------------+------------------------------------------------------------------+
@ -205,7 +205,7 @@ Uppercase directories
+------------+--------------------------------------------------------------------------------------------------+
| KAPPA | compute thermal conductivity via several methods |
+------------+--------------------------------------------------------------------------------------------------+
| MC | using LAMMPS in a Monte Carlo mode to relax the energy of a system |
| MC-LOOP | using LAMMPS in a Monte Carlo mode to relax the energy of a system in a input script loop |
+------------+--------------------------------------------------------------------------------------------------+
| PACKAGES | examples for specific packages and contributed commands |
+------------+--------------------------------------------------------------------------------------------------+

133
doc/src/Howto_github.rst
View File

@ -7,11 +7,11 @@ LAMMPS GitHub tutorial
This document describes the process of how to use GitHub to integrate
changes or additions you have made to LAMMPS into the official LAMMPS
distribution. It uses the process of updating this very tutorial as
an example to describe the individual steps and options. You need to
be familiar with git and you may want to have a look at the
`git book <http://git-scm.com/book/>`_ to reacquaint yourself with some
of the more advanced git features used below.
distribution. It uses the process of updating this very tutorial as an
example to describe the individual steps and options. You need to be
familiar with git and you may want to have a look at the `git book
<http://git-scm.com/book/>`_ to familiarize yourself with some of the
more advanced git features used below.
As of fall 2016, submitting contributions to LAMMPS via pull requests
on GitHub is the preferred option for integrating contributed features
@ -37,15 +37,15 @@ username or e-mail address and password.
**Forking the repository**
To get changes into LAMMPS, you need to first fork the `lammps/lammps`
repository on GitHub. At the time of writing, *master* is the preferred
repository on GitHub. At the time of writing, *develop* is the preferred
target branch. Thus go to `LAMMPS on GitHub <https://github.com/lammps/lammps>`_
and make sure branch is set to "master", as shown in the figure below.
and make sure branch is set to "develop", as shown in the figure below.
.. image:: JPG/tutorial_branch.png
:align: center
If it is not, use the button to change it to *master*\ . Once it is, use the
fork button to create a fork.
If it is not, use the button to change it to *develop*. Once it is, use
the fork button to create a fork.
.. image:: JPG/tutorial_fork.png
:align: center
@ -64,11 +64,12 @@ LAMMPS development.
**Adding changes to your own fork**
Additions to the upstream version of LAMMPS are handled using *feature
branches*\ . For every new feature, a so-called feature branch is
branches*. For every new feature, a so-called feature branch is
created, which contains only those modification relevant to one specific
feature. For example, adding a single fix would consist of creating a
branch with only the fix header and source file and nothing else. It is
explained in more detail here: `feature branch workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow>`_.
explained in more detail here: `feature branch workflow
<https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow>`_.
**Feature branches**
@ -94,8 +95,8 @@ The above command copies ("clones") the git repository to your local
machine to a directory with the name you chose. If none is given, it will
default to "lammps". Typical names are "mylammps" or something similar.
You can use this local clone to make changes and
test them without interfering with the repository on GitHub.
You can use this local clone to make changes and test them without
interfering with the repository on GitHub.
To pull changes from upstream into this copy, you can go to the directory
and use git pull:
@ -103,28 +104,45 @@ and use git pull:
.. code-block:: bash
$ cd mylammps
$ git checkout master
$ git pull https://github.com/lammps/lammps
$ git checkout develop
$ git pull https://github.com/lammps/lammps develop
You can also add this URL as a remote:
.. code-block:: bash
$ git remote add lammps_upstream https://www.github.com/lammps/lammps
$ git remote add upstream https://www.github.com/lammps/lammps
At this point, you typically make a feature branch from the updated master
From then on you can update your upstream branches with:
.. code-block:: bash
$ git fetch upstream
and then refer to the upstream repository branches with
`upstream/develop` or `upstream/release` and so on.
At this point, you typically make a feature branch from the updated
branch for the feature you want to work on. This tutorial contains the
workflow that updated this tutorial, and hence we will call the branch
"github-tutorial-update":
.. code-block:: bash
$ git checkout -b github-tutorial-update master
$ git fetch upstream
$ git checkout -b github-tutorial-update upstream/develop
Now that we have changed branches, we can make our changes to our local
repository. Just remember that if you want to start working on another,
unrelated feature, you should switch branches!
.. note::
Committing changes to the *develop*, *release*, or *stable* branches
is strongly discouraged. While it may be convenient initially, it
will create more work in the long run. Various texts and tutorials
on using git effectively discuss the motivation for this.
**After changes are made**
After everything is done, add the files to the branch and commit them:
@ -287,28 +305,32 @@ After each push, the automated checks are run again.
LAMMPS developers may add labels to your pull request to assign it to
categories (mostly for bookkeeping purposes), but a few of them are
important: needs_work, work_in_progress, test-for-regression, and
full-regression-test. The first two indicate, that your pull request
is not considered to be complete. With "needs_work" the burden is on
exclusively on you; while "work_in_progress" can also mean, that a
LAMMPS developer may want to add changes. Please watch the comments
to the pull requests. The two "test" labels are used to trigger
extended tests before the code is merged. This is sometimes done by
LAMMPS developers, if they suspect that there may be some subtle
side effects from your changes. It is not done by default, because
those tests are very time consuming.
important: *needs_work*, *work_in_progress*, *run_tests*,
*test_for_regression*, and *ready_for_merge*. The first two indicate,
that your pull request is not considered to be complete. With
"needs_work" the burden is on exclusively on you; while
"work_in_progress" can also mean, that a LAMMPS developer may want to
add changes. Please watch the comments to the pull requests. The two
"test" labels are used to trigger extended tests before the code is
merged. This is sometimes done by LAMMPS developers, if they suspect
that there may be some subtle side effects from your changes. It is not
done by default, because those tests are very time consuming. The
*ready_for_merge* label is usually attached when the LAMMPS developer
assigned to the pull request considers this request complete and to
trigger a final full test evaluation.
**Reviews**
As of Summer 2018, a pull request needs at least 1 approving review
from a LAMMPS developer with write access to the repository.
In case your changes touch code that certain developers are associated
with, they are auto-requested by the GitHub software. Those associations
are set in the file
`.github/CODEOWNERS <https://github.com/lammps/lammps/blob/master/.github/CODEOWNERS>`_
Thus if you want to be automatically notified to review when anybody
changes files or packages, that you have contributed to LAMMPS, you can
add suitable patterns to that file, or a LAMMPS developer may add you.
As of Fall 2021, a pull request needs to pass all automatic tests and at
least 1 approving review from a LAMMPS developer with write access to
the repository before it is eligible for merging. In case your changes
touch code that certain developers are associated with, they are
auto-requested by the GitHub software. Those associations are set in
the file `.github/CODEOWNERS
<https://github.com/lammps/lammps/blob/develop/.github/CODEOWNERS>`_ Thus
if you want to be automatically notified to review when anybody changes
files or packages, that **you** have contributed to LAMMPS, you can add
suitable patterns to that file, or a LAMMPS developer may add you.
Otherwise, you can also manually request reviews from specific developers,
or LAMMPS developers - in their assessment of your pull request - may
@ -329,7 +351,7 @@ LAMMPS developer (including him/herself) or c) Axel Kohlmeyer (akohlmey).
After the review, the developer can choose to implement changes directly
or suggest them to you.
* Case c) means that the pull request has been assigned to the developer
overseeing the merging of pull requests into the master branch.
overseeing the merging of pull requests into the *develop* branch.
In this case, Axel assigned the tutorial to Steve:
@ -351,11 +373,11 @@ Sometimes, however, you might not feel comfortable having other people
push changes into your own branch, or maybe the maintainers are not sure
their idea was the right one. In such a case, they can make changes,
reassign you as the assignee, and file a "reverse pull request", i.e.
file a pull request in your GitHub repository to include changes in the
branch, that you have submitted as a pull request yourself. In that
case, you can choose to merge their changes back into your branch,
possibly make additional changes or corrections and proceed from there.
It looks something like this:
file a pull request in **your** forked GitHub repository to include
changes in the branch, that you have submitted as a pull request
yourself. In that case, you can choose to merge their changes back into
your branch, possibly make additional changes or corrections and proceed
from there. It looks something like this:
.. image:: JPG/tutorial_reverse_pull_request.png
:align: center
@ -419,7 +441,7 @@ This merge also shows up on the lammps GitHub page:
**After a merge**
When everything is fine, the feature branch is merged into the master branch:
When everything is fine, the feature branch is merged into the *develop* branch:
.. image:: JPG/tutorial_merged.png
:align: center
@ -433,8 +455,8 @@ branch!
.. code-block:: bash
$ git checkout master
$ git pull master
$ git checkout develop
$ git pull https://github.com/lammps/lammps develop
$ git branch -d github-tutorial-update
If you do not pull first, it is not really a problem but git will warn
@ -442,6 +464,7 @@ you at the next statement that you are deleting a local branch that
was not yet fully merged into HEAD. This is because git does not yet
know your branch just got merged into LAMMPS upstream. If you
first delete and then pull, everything should still be fine.
You can display all branches that are fully merged by:
Finally, if you delete the branch locally, you might want to push this
to your remote(s) as well:
@ -453,14 +476,14 @@ to your remote(s) as well:
**Recent changes in the workflow**
Some changes to the workflow are not captured in this tutorial. For
example, in addition to the master branch, to which all new features
should be submitted, there is now also an "unstable" and a "stable"
branch; these have the same content as "master", but are only updated
after a patch release or stable release was made.
Furthermore, the naming of the patches now follow the pattern
"patch_<Day><Month><Year>" to simplify comparisons between releases.
Finally, all patches and submissions are subject to automatic testing
and code checks to make sure they at the very least compile.
example, in addition to the *develop* branch, to which all new features
should be submitted, there is also a *release* and a *stable* branch;
these have the same content as *develop*, but are only updated after a
patch release or stable release was made. Furthermore, the naming of
the patches now follow the pattern "patch_<Day><Month><Year>" to
simplify comparisons between releases. Finally, all patches and
submissions are subject to automatic testing and code checks to make
sure they at the very least compile.
A discussion of the LAMMPS developer GitHub workflow can be found in the file
`doc/github-development-workflow.md <https://github.com/lammps/lammps/blob/master/doc/github-development-workflow.md>`_
`doc/github-development-workflow.md <https://github.com/lammps/lammps/blob/develop/doc/github-development-workflow.md>`_

80
doc/src/Howto_thermostat.rst
View File

@ -2,8 +2,8 @@ Thermostats
===========
Thermostatting means controlling the temperature of particles in an MD
simulation. :doc:`Barostatting <Howto_barostat>` means controlling the
pressure. Since the pressure includes a kinetic component due to
simulation. :doc:`Barostatting <Howto_barostat>` means controlling
the pressure. Since the pressure includes a kinetic component due to
particle velocities, both these operations require calculation of the
temperature. Typically a target temperature (T) and/or pressure (P)
is specified by the user, and the thermostat or barostat attempts to
@ -26,11 +26,13 @@ can be invoked via the *dpd/tstat* pair style:
* :doc:`pair_style dpd/tstat <pair_dpd>`
:doc:`Fix nvt <fix_nh>` only thermostats the translational velocity of
particles. :doc:`Fix nvt/sllod <fix_nvt_sllod>` also does this, except
that it subtracts out a velocity bias due to a deforming box and
integrates the SLLOD equations of motion. See the :doc:`Howto nemd <Howto_nemd>` page for further details. :doc:`Fix nvt/sphere <fix_nvt_sphere>` and :doc:`fix nvt/asphere <fix_nvt_asphere>` thermostat not only translation
velocities but also rotational velocities for spherical and aspherical
particles.
particles. :doc:`Fix nvt/sllod <fix_nvt_sllod>` also does this,
except that it subtracts out a velocity bias due to a deforming box
and integrates the SLLOD equations of motion. See the :doc:`Howto
nemd <Howto_nemd>` page for further details. :doc:`Fix nvt/sphere
<fix_nvt_sphere>` and :doc:`fix nvt/asphere <fix_nvt_asphere>`
thermostat not only translation velocities but also rotational
velocities for spherical and aspherical particles.
.. note::
@ -40,25 +42,31 @@ particles.
e.g. molecular systems. The latter can be tricky to do correctly.
DPD thermostatting alters pairwise interactions in a manner analogous
to the per-particle thermostatting of :doc:`fix langevin <fix_langevin>`.
to the per-particle thermostatting of :doc:`fix langevin
<fix_langevin>`.
Any of the thermostatting fixes can be instructed to use custom temperature
computes that remove bias which has two effects: first, the current
calculated temperature, which is compared to the requested target temperature,
is calculated with the velocity bias removed; second, the thermostat adjusts
only the thermal temperature component of the particle's velocities, which are
the velocities with the bias removed. The removed bias is then added back
to the adjusted velocities. See the doc pages for the individual
fixes and for the :doc:`fix_modify <fix_modify>` command for
instructions on how to assign a temperature compute to a
thermostatting fix. For example, you can apply a thermostat to only
the x and z components of velocity by using it in conjunction with
:doc:`compute temp/partial <compute_temp_partial>`. Of you could
thermostat only the thermal temperature of a streaming flow of
particles without affecting the streaming velocity, by using
:doc:`compute temp/profile <compute_temp_profile>`.
Any of the thermostatting fixes can be instructed to use custom
temperature computes that remove bias which has two effects: first,
the current calculated temperature, which is compared to the requested
target temperature, is calculated with the velocity bias removed;
second, the thermostat adjusts only the thermal temperature component
of the particle's velocities, which are the velocities with the bias
removed. The removed bias is then added back to the adjusted
velocities. See the doc pages for the individual fixes and for the
:doc:`fix_modify <fix_modify>` command for instructions on how to
assign a temperature compute to a thermostatting fix.
Below is a list of some custom temperature computes that can be used like that:
For example, you can apply a thermostat only to atoms in a spatial
region by using it in conjunction with :doc:`compute temp/region
<compute_temp_region>`. Or you can apply a thermostat to only the x
and z components of velocity by using it with :doc:`compute
temp/partial <compute_temp_partial>`. Of you could thermostat only
the thermal temperature of a streaming flow of particles without
affecting the streaming velocity, by using :doc:`compute temp/profile
<compute_temp_profile>`.
Below is a list of custom temperature computes that can be used like
that:
* :doc:`compute_temp_asphere`
* :doc:`compute_temp_body`
@ -72,8 +80,6 @@ Below is a list of some custom temperature computes that can be used like that:
* :doc:`compute_temp_rotate`
* :doc:`compute_temp_sphere`
.. note::
Only the nvt fixes perform time integration, meaning they update
@ -86,17 +92,17 @@ Below is a list of some custom temperature computes that can be used like that:
* :doc:`fix nve/sphere <fix_nve_sphere>`
* :doc:`fix nve/asphere <fix_nve_asphere>`
Thermodynamic output, which can be setup via the
:doc:`thermo_style <thermo_style>` command, often includes temperature
values. As explained on the page for the
:doc:`thermo_style <thermo_style>` command, the default temperature is
setup by the thermo command itself. It is NOT the temperature
associated with any thermostatting fix you have defined or with any
compute you have defined that calculates a temperature. The doc pages
for the thermostatting fixes explain the ID of the temperature compute
they create. Thus if you want to view these temperatures, you need to
specify them explicitly via the :doc:`thermo_style custom <thermo_style>` command. Or you can use the
:doc:`thermo_modify <thermo_modify>` command to re-define what
Thermodynamic output, which can be setup via the :doc:`thermo_style
<thermo_style>` command, often includes temperature values. As
explained on the page for the :doc:`thermo_style <thermo_style>`
command, the default temperature is setup by the thermo command
itself. It is NOT the temperature associated with any thermostatting
fix you have defined or with any compute you have defined that
calculates a temperature. The doc pages for the thermostatting fixes
explain the ID of the temperature compute they create. Thus if you
want to view these temperatures, you need to specify them explicitly
via the :doc:`thermo_style custom <thermo_style>` command. Or you can
use the :doc:`thermo_modify <thermo_modify>` command to re-define what
temperature compute is used for default thermodynamic output.
----------

51
doc/src/Install_git.rst
View File

@ -9,7 +9,8 @@ has several advantages:
command.
* You can create your own development branches to add code to LAMMPS.
* You can submit your new features back to GitHub for inclusion in
LAMMPS.
LAMMPS. For that you should first create your own :doc:`fork on
GitHub <Howto_github>`.
You must have `git <git_>`_ installed on your system to use the
commands explained below to communicate with the git servers on
@ -20,35 +21,53 @@ provides `limited support for subversion clients <svn_>`_.
As of October 2016, the official home of public LAMMPS development is
on GitHub. The previously advertised LAMMPS git repositories on
git.lammps.org and bitbucket.org are now deprecated or offline.
git.lammps.org and bitbucket.org are now offline or deprecated.
.. _git: https://git-scm.com
.. _svn: https://help.github.com/en/github/importing-your-projects-to-github/working-with-subversion-on-github
You can follow LAMMPS development on 3 different git branches:
You can follow the LAMMPS development on 3 different git branches:
* **stable** : this branch is updated with every stable release
* **unstable** : this branch is updated with every patch release
* **master** : this branch continuously follows ongoing development
* **stable** : this branch is updated with every stable release;
updates are always "fast forward" merges from *develop*
* **release** : this branch is updated with every patch release;
updates are always "fast forward" merges from *develop*
* **develop** : this branch follows the ongoing development and
is updated with every merge commit of a pull request
To access the git repositories on your box, use the clone command to
create a local copy of the LAMMPS repository with a command like:
.. code-block:: bash
$ git clone -b unstable https://github.com/lammps/lammps.git mylammps
$ git clone -b release https://github.com/lammps/lammps.git mylammps
where "mylammps" is the name of the directory you wish to create on
your machine and "unstable" is one of the 3 branches listed above.
your machine and "release" is one of the 3 branches listed above.
(Note that you actually download all 3 branches; you can switch
between them at any time using "git checkout <branch name>".)
.. note::
The complete git history of the LAMMPS project is quite large because
it contains the entire commit history of the project since fall 2006,
which includes the time when LAMMPS was managed with subversion. This
also includes commits that have added and removed some large files
(mostly by accident). If you do not need access to the entire commit
history, you can speed up the "cloning" process and reduce local disk
space requirements by using the *--depth* git command line flag thus
create a "shallow clone" of the repository that contains only a
subset of the git history. Using a depth of 1000 is usually sufficient
to include the head commits of the *develop* and the *release* branches.
To include the head commit of the *stable* branch you may need a depth
of up to 10000.
Once the command completes, your directory will contain the same files
as if you unpacked a current LAMMPS tarball, with the exception, that
the HTML documentation files are not included. They can be fetched
from the LAMMPS website by typing ``make fetch`` in the doc directory.
Or they can be generated from the content provided in doc/src by
typing ``make html`` from the doc directory.
Or they can be generated from the content provided in ``doc/src`` by
typing ``make html`` from the ``doc`` directory.
After initial cloning, as bug fixes and new features are added to
LAMMPS you can stay up-to-date by typing the following git commands
@ -56,9 +75,9 @@ from within the "mylammps" directory:
.. code-block:: bash
$ git checkout unstable # not needed if you always stay in this branch
$ git checkout release # not needed if you always stay in this branch
$ git checkout stable # use one of these 3 checkout commands
$ git checkout master # to choose the branch to follow
$ git checkout develop # to choose the branch to follow
$ git pull
Doing a "pull" will not change any files you have added to the LAMMPS
@ -81,7 +100,7 @@ Stable versions and what tagID to use for a particular stable version
are discussed on `this page <https://www.lammps.org/bug.html#version>`_.
Note that this command will print some warnings, because in order to get
back to the latest revision and to be able to update with ``git pull``
again, you will need to do ``git checkout unstable`` (or
again, you will need to do ``git checkout release`` (or
check out any other desired branch) first.
Once you have updated your local files with a ``git pull`` (or ``git
@ -137,9 +156,9 @@ changed. How to do this depends on the build system you are using.
.. admonition:: Git protocols
:class: note
The servers at github.com support the "git://" and "https://" access
protocols for anonymous, read-only access. If you have a suitably
configured GitHub account, you may also use SSH protocol with the
The servers at github.com support the "https://" access protocol for
anonymous, read-only access. If you have a suitably configured GitHub
account, you may also use SSH protocol with the
URL "git@github.com:lammps/lammps.git".
The LAMMPS GitHub project is currently managed by Axel Kohlmeyer

2
doc/src/Intro_citing.rst
View File

@ -16,7 +16,7 @@ source code design, the program structure, the spatial decomposition
approach, the neighbor finding, basic communications algorithms, and how
users and developers have contributed to LAMMPS is:
`LAMMPS - A flexible simulation tool for particle-based materials modeling at the atomic, meso, and continuum scales, Comp. Phys. Comm. (accepted 09/2021), DOI:10.1016/j.cpc.2021.108171 <https://doi.org/10.1016/j.cpc.2021.108171>`_
`LAMMPS - A flexible simulation tool for particle-based materials modeling at the atomic, meso, and continuum scales, Comp. Phys. Comm. 271, 108171 (2022) <https://doi.org/10.1016/j.cpc.2021.108171>`_
So a project using LAMMPS or a derivative application that uses LAMMPS
as a simulation engine should cite this paper. The paper is expected to

2
doc/src/Intro_opensource.rst
View File

@ -19,7 +19,7 @@ software and open-source distribution, see `www.gnu.org <gnuorg_>`_
or `www.opensource.org <opensource_>`_. The legal text of the GPL as it
applies to LAMMPS is in the LICENSE file included in the LAMMPS distribution.
.. _gpl: https://github.com/lammps/lammps/blob/master/LICENSE
.. _gpl: https://github.com/lammps/lammps/blob/develop/LICENSE
.. _lgpl: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html

2
doc/src/Manual_version.rst
View File

@ -7,7 +7,7 @@ correctly and reliably at all times. You can follow its development
in a public `git repository on GitHub <https://github.com/lammps/lammps>`_.
Whenever we fix a bug or update or add a feature, it will be merged into
the `master` branch of the git repository. When a sufficient number of
the *develop* branch of the git repository. When a sufficient number of
changes have accumulated *and* the software passes a set of automated
tests, we release it in the next *patch* release, which are made every
few weeks. Info on patch releases are on `this website page

2
doc/src/Speed.rst
View File

@ -14,7 +14,7 @@ Intel Xeon Phi co-processors.
The `Benchmark page <https://www.lammps.org/bench.html>`_ of the LAMMPS
website gives performance results for the various accelerator
packages discussed on the :doc:`Speed packages <Speed_packages>` doc
packages discussed on the :doc:`Accelerator packages <Speed_packages>`
page, for several of the standard LAMMPS benchmark problems, as a
function of problem size and number of compute nodes, on different
hardware platforms.

4
doc/src/accel_styles.rst
View File

@ -1,7 +1,7 @@
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
hardware, as discussed on the :doc:`Accelerator packages <Speed_packages>`
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
@ -13,5 +13,5 @@ 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>` page for more
See the :doc:`Accelerator packages <Speed_packages>` page for more
instructions on how to use the accelerated styles effectively.

18
doc/src/angle_charmm.rst
View File

@ -56,23 +56,7 @@ 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, INTEL, KOKKOS,
OPENMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` 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 :doc:`Speed packages <Speed_packages>` page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------

23
doc/src/atom_style.rst
View File

@ -319,28 +319,9 @@ styles; see the :doc:`Modify <Modify>` doc page.
----------
Styles with a *kk* 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 in 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.
.. include:: accel_styles.rst
Note that other acceleration packages in LAMMPS, specifically the GPU,
INTEL, OPENMP, and OPT packages do not use accelerated atom
styles.
The accelerated styles are part of the KOKKOS package. They are only
enabled if LAMMPS was built with those packages. See the :doc:`Build
package <Build_package>` 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>` page for more
instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""

499
doc/src/dump_image.rst
View File

@ -6,6 +6,8 @@ dump image command
dump movie command
==================
(see below for :ref:`dump_modify options <dump_modify_image>` specific to dump image/movie)
Syntax
""""""
@ -15,7 +17,7 @@ Syntax
* ID = user-assigned name for the dump
* group-ID = ID of the group of atoms to be imaged
* style = *image* or *movie* = style of dump command (other styles *atom* or *cfg* or *dcd* or *xtc* or *xyz* or *local* or *custom* are discussed on the :doc:`dump <dump>` doc page)
* style = *image* or *movie* = style of dump command (other styles such as *atom* or *cfg* or *dcd* or *xtc* or *xyz* or *local* or *custom* are discussed on the :doc:`dump <dump>` doc page)
* N = dump every this many timesteps
* file = name of file to write image to
* color = atom attribute that determines color of each atom
@ -79,6 +81,69 @@ Syntax
seed = random # seed (positive integer)
dfactor = strength of shading from 0.0 to 1.0
.. _dump_modify_image:
dump_modify options for dump image/movie
========================================
Syntax
""""""
.. parsed-literal::
dump_modify dump-ID keyword values ...
* these keywords apply only to the *image* and *movie* styles and are documented on this page
* keyword = *acolor* or *adiam* or *amap* or *backcolor* or *bcolor* or *bdiam* or *boxcolor* or *color* or *bitrate* or *framerate*
* see the :doc:`dump modify <dump_modify>` doc page for more general keywords
.. parsed-literal::
*acolor* args = type color
type = atom type or range of types (see below)
color = name of color or color1/color2/...
*adiam* args = type diam
type = atom type or range of types (see below)
diam = diameter of atoms of that type (distance units)
*amap* args = lo hi style delta N entry1 entry2 ... entryN
lo = number or *min* = lower bound of range of color map
hi = number or *max* = upper bound of range of color map
style = 2 letters = "c" or "d" or "s" plus "a" or "f"
"c" for continuous
"d" for discrete
"s" for sequential
"a" for absolute
"f" for fractional
delta = binsize (only used for style "s", otherwise ignored)
binsize = range is divided into bins of this width
N = # of subsequent entries
entry = value color (for continuous style)
value = number or *min* or *max* = single value within range
color = name of color used for that value
entry = lo hi color (for discrete style)
lo/hi = number or *min* or *max* = lower/upper bound of subset of range
color = name of color used for that subset of values
entry = color (for sequential style)
color = name of color used for a bin of values
*backcolor* arg = color
color = name of color for background
*bcolor* args = type color
type = bond type or range of types (see below)
color = name of color or color1/color2/...
*bdiam* args = type diam
type = bond type or range of types (see below)
diam = diameter of bonds of that type (distance units)
*boxcolor* arg = color
color = name of color for simulation box lines and processor sub-domain lines
*color* args = name R G B
name = name of color
R,G,B = red/green/blue numeric values from 0.0 to 1.0
*bitrate* arg = rate
rate = target bitrate for movie in kbps
*framerate* arg = fps
fps = frames per second for movie
Examples
""""""""
@ -91,6 +156,8 @@ Examples
dump m1 all movie 1000 movie.avi type type size 640 480
dump m2 all movie 100 movie.m4v type type zoom 1.8 adiam v_value size 1280 720
dump_modify 1 amap min max cf 0.0 3 min green 0.5 yellow max blue boxcolor red
Description
"""""""""""
@ -145,10 +212,10 @@ is used.
Similarly, the format of the resulting movie is chosen with the
*movie* dump style. This is handled by the underlying FFmpeg converter
and thus details have to be looked up in the `FFmpeg documentation
<http://ffmpeg.org/ffmpeg.html>`_.
Typical examples are: .avi, .mpg, .m4v, .mp4, .mkv, .flv, .mov, .gif
Additional settings of the movie compression like bitrate and
framerate can be set using the :doc:`dump_modify <dump_modify>` command.
<http://ffmpeg.org/ffmpeg.html>`_. Typical examples are: .avi, .mpg,
.m4v, .mp4, .mkv, .flv, .mov, .gif Additional settings of the movie
compression like bitrate and framerate can be set using the
dump_modify command as described below.
To write out JPEG and PNG format files, you must build LAMMPS with
support for the corresponding JPEG or PNG library. To convert images
@ -210,19 +277,20 @@ to colors is as follows:
* type 6 = cyan
and repeats itself for types > 6. This mapping can be changed by the
:doc:`dump_modify acolor <dump_modify>` command.
"dump_modify acolor" command, as described below.
If *type* is specified for the *diameter* setting then the diameter of
each atom is determined by its atom type. By default all types have
diameter 1.0. This mapping can be changed by the :doc:`dump_modify adiam <dump_modify>` command.
diameter 1.0. This mapping can be changed by the "dump_modify adiam"
command, as described below.
If *element* is specified for the *color* and/or *diameter* setting,
then the color and/or diameter of each atom is determined by which
element it is, which in turn is specified by the element-to-type
mapping specified by the "dump_modify element" command. By default
every atom type is C (carbon). Every element has a color and diameter
associated with it, which is the same as the colors and sizes used by
the `AtomEye <atomeye_>`_ visualization package.
mapping specified by the "dump_modify element" command, as described
below. By default every atom type is C (carbon). Every element has a
color and diameter associated with it, which is the same as the colors
and sizes used by the `AtomEye <atomeye_>`_ visualization package.
.. _atomeye: http://li.mit.edu/Archive/Graphics/A/
@ -232,13 +300,13 @@ settings, they are interpreted in the following way.
If "vx", for example, is used as the *color* setting, then the color
of the atom will depend on the x-component of its velocity. The
association of a per-atom value with a specific color is determined by
a "color map", which can be specified via the
:doc:`dump_modify <dump_modify>` command. The basic idea is that the
atom-attribute will be within a range of values, and every value
within the range is mapped to a specific color. Depending on how the
color map is defined, that mapping can take place via interpolation so
that a value of -3.2 is halfway between "red" and "blue", or
discretely so that the value of -3.2 is "orange".
a "color map", which can be specified via the dump_modify command, as
described below. The basic idea is that the atom-attribute will be
within a range of values, and every value within the range is mapped
to a specific color. Depending on how the color map is defined, that
mapping can take place via interpolation so that a value of -3.2 is
halfway between "red" and "blue", or discretely so that the value of
-3.2 is "orange".
If "vx", for example, is used as the *diameter* setting, then the atom
will be rendered using the x-component of its velocity as the
@ -251,9 +319,10 @@ diameter, which can be used as the *diameter* setting.
The various keywords listed above control how the image is rendered.
As listed below, all of the keywords have defaults, most of which you
will likely not need to change. The :doc:`dump modify <dump_modify>`
also has options specific to the dump image style, particularly for
assigning colors to atoms, bonds, and other image features.
will likely not need to change. As described below, the dump modify
command also has options specific to the dump image style,
particularly for assigning colors to atoms, bonds, and other image
features.
----------
@ -295,7 +364,7 @@ types to colors is as follows:
* type 6 = cyan
and repeats itself for bond types > 6. This mapping can be changed by
the :doc:`dump_modify bcolor <dump_modify>` command.
the "dump_modify bcolor" command, as described below.
The bond *width* value can be a numeric value or *atom* or *type* (or
*none* as indicated above).
@ -310,7 +379,8 @@ of the 2 atoms in the bond.
If *type* is specified for the *width* value then the diameter of each
bond is determined by its bond type. By default all types have
diameter 0.5. This mapping can be changed by the :doc:`dump_modify bdiam <dump_modify>` command.
diameter 0.5. This mapping can be changed by the "dump_modify bdiam" command,
as described below.
----------
@ -330,7 +400,7 @@ mapping of types to colors is as follows:
* type 6 = cyan
and repeats itself for types > 6. There is not yet an option to
change this via the :doc:`dump_modify <dump_modify>` command.
change this via the dump_modify command.
The line *width* can only be a numeric value, which specifies that all
lines will be drawn as cylinders with that diameter, e.g. 1.0, which
@ -357,7 +427,7 @@ default the mapping of types to colors is as follows:
* type 6 = cyan
and repeats itself for types > 6. There is not yet an option to
change this via the :doc:`dump_modify <dump_modify>` command.
change this via the dump_modify command.
----------
@ -390,7 +460,7 @@ particle. By default the mapping of types to colors is as follows:
* type 6 = cyan
and repeats itself for types > 6. There is not yet an option to
change this via the :doc:`dump_modify <dump_modify>` command.
change this via the dump_modify command.
----------
@ -414,7 +484,7 @@ the mapping of types to colors is as follows:
* type 6 = cyan
and repeats itself for types > 6. There is not yet an option to
change this via the :doc:`dump_modify <dump_modify>` command.
change this via the dump_modify command.
----------
@ -488,7 +558,8 @@ are rendered as thin cylinders in the image. If *no* is set, then the
box boundaries are not drawn and the *diam* setting is ignored. If
*yes* is set, the 12 edges of the box are drawn, with a diameter that
is a fraction of the shortest box length in x,y,z (for 3d) or x,y (for
2d). The color of the box boundaries can be set with the :doc:`dump_modify boxcolor <dump_modify>` command.
2d). The color of the box boundaries can be set with the "dump_modify
boxcolor" command.
The *axes* keyword determines if and how the coordinate axes are
rendered as thin cylinders in the image. If *no* is set, then the
@ -507,7 +578,8 @@ set (default), then the sub-domain boundaries are not drawn and the
*diam* setting is ignored. If *yes* is set, the 12 edges of each
processor sub-domain are drawn, with a diameter that is a fraction of
the shortest box length in x,y,z (for 3d) or x,y (for 2d). The color
of the sub-domain boundaries can be set with the :doc:`dump_modify boxcolor <dump_modify>` command.
of the sub-domain boundaries can be set with the "dump_modify
boxcolor" command.
----------
@ -607,9 +679,272 @@ Play the movie:
----------
See the :doc:`Modify <Modify>` page for information on how to add
new compute and fix styles to LAMMPS to calculate per-atom quantities
which could then be output into dump files.
Dump_modify keywords for dump image and dump movie
""""""""""""""""""""""""""""""""""""""""""""""""""
The following dump_modify keywords apply only to the dump image and
dump movie styles. Any keyword that works with dump image also works
with dump movie, since the movie is simply a collection of images.
Some of the keywords only affect the dump movie style. The
descriptions give details.
----------
The *acolor* keyword can be used with the dump image command, when its
atom color setting is *type*, to set the color that atoms of each type
will be drawn in the image.
The specified *type* should be an integer from 1 to Ntypes = the
number of atom types. A wildcard asterisk can be used in place of or
in conjunction with the *type* argument to specify a range of atom
types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N =
the number of atom types, then an asterisk with no numeric values
means all types from 1 to N. A leading asterisk means all types from
1 to n (inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive).
The specified *color* can be a single color which is any of the 140
pre-defined colors (see below) or a color name defined by the
"dump_modify color" command, as described below. Or it can be two or
more colors separated by a "/" character, e.g. red/green/blue. In the
former case, that color is assigned to all the specified atom types.
In the latter case, the list of colors are assigned in a round-robin
fashion to each of the specified atom types.
----------
The *adiam* keyword can be used with the dump image command, when its
atom diameter setting is *type*, to set the size that atoms of each
type will be drawn in the image. The specified *type* should be an
integer from 1 to Ntypes. As with the *acolor* keyword, a wildcard
asterisk can be used as part of the *type* argument to specify a range
of atom types. The specified *diam* is the size in whatever distance
:doc:`units <units>` the input script is using, e.g. Angstroms.
----------
The *amap* keyword can be used with the dump image command, with its
*atom* keyword, when its atom setting is an atom-attribute, to setup a
color map. The color map is used to assign a specific RGB
(red/green/blue) color value to an individual atom when it is drawn,
based on the atom's attribute, which is a numeric value, e.g. its
x-component of velocity if the atom-attribute "vx" was specified.
The basic idea of a color map is that the atom-attribute will be
within a range of values, and that range is associated with a series
of colors (e.g. red, blue, green). An atom's specific value (vx =
-3.2) can then mapped to the series of colors (e.g. halfway between
red and blue), and a specific color is determined via an interpolation
procedure.
There are many possible options for the color map, enabled by the
*amap* keyword. Here are the details.
The *lo* and *hi* settings determine the range of values allowed for
the atom attribute. If numeric values are used for *lo* and/or *hi*,
then values that are lower/higher than that value are set to the
value. I.e. the range is static. If *lo* is specified as *min* or
*hi* as *max* then the range is dynamic, and the lower and/or
upper bound will be calculated each time an image is drawn, based
on the set of atoms being visualized.
The *style* setting is two letters, such as "ca". The first letter is
either "c" for continuous, "d" for discrete, or "s" for sequential.
The second letter is either "a" for absolute, or "f" for fractional.
A continuous color map is one in which the color changes continuously
from value to value within the range. A discrete color map is one in
which discrete colors are assigned to sub-ranges of values within the
range. A sequential color map is one in which discrete colors are
assigned to a sequence of sub-ranges of values covering the entire
range.
An absolute color map is one in which the values to which colors are
assigned are specified explicitly as values within the range. A
fractional color map is one in which the values to which colors are
assigned are specified as a fractional portion of the range. For
example if the range is from -10.0 to 10.0, and the color red is to be
assigned to atoms with a value of 5.0, then for an absolute color map
the number 5.0 would be used. But for a fractional map, the number
0.75 would be used since 5.0 is 3/4 of the way from -10.0 to 10.0.
The *delta* setting must be specified for all styles, but is only used
for the sequential style; otherwise the value is ignored. It
specifies the bin size to use within the range for assigning
consecutive colors to. For example, if the range is from -10.0 to
10.0 and a *delta* of 1.0 is used, then 20 colors will be assigned to
the range. The first will be from -10.0 <= color1 < -9.0, then second
from -9.0 <= color2 < -8.0, etc.
The *N* setting is how many entries follow. The format of the entries
depends on whether the color map style is continuous, discrete or
sequential. In all cases the *color* setting can be any of the 140
pre-defined colors (see below) or a color name defined by the
dump_modify color option.
For continuous color maps, each entry has a *value* and a *color*\ .
The *value* is either a number within the range of values or *min* or
*max*\ . The *value* of the first entry must be *min* and the *value*
of the last entry must be *max*\ . Any entries in between must have
increasing values. Note that numeric values can be specified either
as absolute numbers or as fractions (0.0 to 1.0) of the range,
depending on the "a" or "f" in the style setting for the color map.
Here is how the entries are used to determine the color of an
individual atom, given the value X of its atom attribute. X will fall
between 2 of the entry values. The color of the atom is linearly
interpolated (in each of the RGB values) between the 2 colors
associated with those entries. For example, if X = -5.0 and the 2
surrounding entries are "red" at -10.0 and "blue" at 0.0, then the
atom's color will be halfway between "red" and "blue", which happens
to be "purple".
For discrete color maps, each entry has a *lo* and *hi* value and a
*color*\ . The *lo* and *hi* settings are either numbers within the
range of values or *lo* can be *min* or *hi* can be *max*\ . The *lo*
and *hi* settings of the last entry must be *min* and *max*\ . Other
entries can have any *lo* and *hi* values and the sub-ranges of
different values can overlap. Note that numeric *lo* and *hi* values
can be specified either as absolute numbers or as fractions (0.0 to
1.0) of the range, depending on the "a" or "f" in the style setting
for the color map.
Here is how the entries are used to determine the color of an
individual atom, given the value X of its atom attribute. The entries
are scanned from first to last. The first time that *lo* <= X <=
*hi*, X is assigned the color associated with that entry. You can
think of the last entry as assigning a default color (since it will
always be matched by X), and the earlier entries as colors that
override the default. Also note that no interpolation of a color RGB
is done. All atoms will be drawn with one of the colors in the list
of entries.
For sequential color maps, each entry has only a *color*\ . Here is how
the entries are used to determine the color of an individual atom,
given the value X of its atom attribute. The range is partitioned
into N bins of width *binsize*\ . Thus X will fall in a specific bin
from 1 to N, say the Mth bin. If it falls on a boundary between 2
bins, it is considered to be in the higher of the 2 bins. Each bin is
assigned a color from the E entries. If E < N, then the colors are
repeated. For example if 2 entries with colors red and green are
specified, then the odd numbered bins will be red and the even bins
green. The color of the atom is the color of its bin. Note that the
sequential color map is really a shorthand way of defining a discrete
color map without having to specify where all the bin boundaries are.
Here is an example of using a sequential color map to color all the
atoms in individual molecules with a different color. See the
examples/pour/in.pour.2d.molecule input script for an example of how
this is used.
.. code-block:: LAMMPS
variable colors string &
"red green blue yellow white &
purple pink orange lime gray"
variable mol atom mol%10
dump 1 all image 250 image.*.jpg v_mol type &
zoom 1.6 adiam 1.5
dump_modify 1 pad 5 amap 0 10 sa 1 10 ${colors}
In this case, 10 colors are defined, and molecule IDs are
mapped to one of the colors, even if there are 1000s of molecules.
----------
The *backcolor* sets the background color of the images. The color
name can be any of the 140 pre-defined colors (see below) or a color
name defined by the dump_modify color option.
----------
The *bcolor* keyword can be used with the dump image command, with its
*bond* keyword, when its color setting is *type*, to set the color
that bonds of each type will be drawn in the image.
The specified *type* should be an integer from 1 to Nbondtypes = the
number of bond types. A wildcard asterisk can be used in place of or
in conjunction with the *type* argument to specify a range of bond
types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N =
the number of bond types, then an asterisk with no numeric values
means all types from 1 to N. A leading asterisk means all types from
1 to n (inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive).
The specified *color* can be a single color which is any of the 140
pre-defined colors (see below) or a color name defined by the
dump_modify color option. Or it can be two or more colors separated
by a "/" character, e.g. red/green/blue. In the former case, that
color is assigned to all the specified bond types. In the latter
case, the list of colors are assigned in a round-robin fashion to each
of the specified bond types.
----------
The *bdiam* keyword can be used with the dump image command, with its
*bond* keyword, when its diam setting is *type*, to set the diameter
that bonds of each type will be drawn in the image. The specified
*type* should be an integer from 1 to Nbondtypes. As with the
*bcolor* keyword, a wildcard asterisk can be used as part of the
*type* argument to specify a range of bond types. The specified
*diam* is the size in whatever distance :doc:`units <units>` you are
using, e.g. Angstroms.
----------
The *bitrate* keyword can be used with the :doc:`dump movie
<dump_image>` command to define the size of the resulting movie file
and its quality via setting how many kbits per second are to be used
for the movie file. Higher bitrates require less compression and will
result in higher quality movies. The quality is also determined by
the compression format and encoder. The default setting is 2000
kbit/s, which will result in average quality with older compression
formats.
.. note::
Not all movie file formats supported by dump movie allow the
bitrate to be set. If not, the setting is silently ignored.
----------
The *boxcolor* keyword sets the color of the simulation box drawn
around the atoms in each image as well as the color of processor
sub-domain boundaries. See the "dump image box" command for how to
specify that a box be drawn via the *box* keyword, and the sub-domain
boundaries via the *subbox* keyword. The color name can be any of the
140 pre-defined colors (see below) or a color name defined by the
dump_modify color option.
----------
The *color* keyword allows definition of a new color name, in addition
to the 140-predefined colors (see below), and associates 3
red/green/blue RGB values with that color name. The color name can
then be used with any other dump_modify keyword that takes a color
name as a value. The RGB values should each be floating point values
between 0.0 and 1.0 inclusive.
When a color name is converted to RGB values, the user-defined color
names are searched first, then the 140 pre-defined color names. This
means you can also use the *color* keyword to overwrite one of the
pre-defined color names with new RBG values.
----------
The *framerate* keyword can be used with the :doc:`dump movie
<dump_image>` command to define the duration of the resulting movie
file. Movie files written by the dump *movie* command have a default
frame rate of 24 frames per second and the images generated will be
converted at that rate. Thus a sequence of 1000 dump images will
result in a movie of about 42 seconds. To make a movie run longer you
can either generate images more frequently or lower the frame rate.
To speed a movie up, you can do the inverse. Using a frame rate
higher than 24 is not recommended, as it will result in simply
dropping the rendered images. It is more efficient to dump images less
frequently.
----------
@ -664,7 +999,7 @@ Related commands
Default
"""""""
The defaults for the keywords are as follows:
The defaults for the dump image and dump movie keywords are as follows:
* adiam = not specified (use diameter setting)
* atom = yes
@ -682,3 +1017,101 @@ The defaults for the keywords are as follows:
* subbox no 0.0
* shiny = 1.0
* ssao = no
----------
The defaults for the dump_modify keywords specific to dump image and dump movie are as follows:
* acolor = \* red/green/blue/yellow/aqua/cyan
* adiam = \* 1.0
* amap = min max cf 0.0 2 min blue max red
* backcolor = black
* bcolor = \* red/green/blue/yellow/aqua/cyan
* bdiam = \* 0.5
* bitrate = 2000
* boxcolor = yellow
* color = 140 color names are pre-defined as listed below
* framerate = 24
----------
These are the standard 109 element names that LAMMPS pre-defines for
use with the dump image and dump_modify commands.
* 1-10 = "H", "He", "Li", "Be", "B", "C", "N", "O", "F", "Ne"
* 11-20 = "Na", "Mg", "Al", "Si", "P", "S", "Cl", "Ar", "K", "Ca"
* 21-30 = "Sc", "Ti", "V", "Cr", "Mn", "Fe", "Co", "Ni", "Cu", "Zn"
* 31-40 = "Ga", "Ge", "As", "Se", "Br", "Kr", "Rb", "Sr", "Y", "Zr"
* 41-50 = "Nb", "Mo", "Tc", "Ru", "Rh", "Pd", "Ag", "Cd", "In", "Sn"
* 51-60 = "Sb", "Te", "I", "Xe", "Cs", "Ba", "La", "Ce", "Pr", "Nd"
* 61-70 = "Pm", "Sm", "Eu", "Gd", "Tb", "Dy", "Ho", "Er", "Tm", "Yb"
* 71-80 = "Lu", "Hf", "Ta", "W", "Re", "Os", "Ir", "Pt", "Au", "Hg"
* 81-90 = "Tl", "Pb", "Bi", "Po", "At", "Rn", "Fr", "Ra", "Ac", "Th"
* 91-100 = "Pa", "U", "Np", "Pu", "Am", "Cm", "Bk", "Cf", "Es", "Fm"
* 101-109 = "Md", "No", "Lr", "Rf", "Db", "Sg", "Bh", "Hs", "Mt"
----------
These are the 140 colors that LAMMPS pre-defines for use with the dump
image and dump_modify commands. Additional colors can be defined with
the dump_modify color command. The 3 numbers listed for each name are
the RGB (red/green/blue) values. Divide each value by 255 to get the
equivalent 0.0 to 1.0 value.
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| aliceblue = 240, 248, 255 | antiquewhite = 250, 235, 215 | aqua = 0, 255, 255 | aquamarine = 127, 255, 212 | azure = 240, 255, 255 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| beige = 245, 245, 220 | bisque = 255, 228, 196 | black = 0, 0, 0 | blanchedalmond = 255, 255, 205 | blue = 0, 0, 255 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| blueviolet = 138, 43, 226 | brown = 165, 42, 42 | burlywood = 222, 184, 135 | cadetblue = 95, 158, 160 | chartreuse = 127, 255, 0 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| chocolate = 210, 105, 30 | coral = 255, 127, 80 | cornflowerblue = 100, 149, 237 | cornsilk = 255, 248, 220 | crimson = 220, 20, 60 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| cyan = 0, 255, 255 | darkblue = 0, 0, 139 | darkcyan = 0, 139, 139 | darkgoldenrod = 184, 134, 11 | darkgray = 169, 169, 169 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| darkgreen = 0, 100, 0 | darkkhaki = 189, 183, 107 | darkmagenta = 139, 0, 139 | darkolivegreen = 85, 107, 47 | darkorange = 255, 140, 0 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| darkorchid = 153, 50, 204 | darkred = 139, 0, 0 | darksalmon = 233, 150, 122 | darkseagreen = 143, 188, 143 | darkslateblue = 72, 61, 139 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| darkslategray = 47, 79, 79 | darkturquoise = 0, 206, 209 | darkviolet = 148, 0, 211 | deeppink = 255, 20, 147 | deepskyblue = 0, 191, 255 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| dimgray = 105, 105, 105 | dodgerblue = 30, 144, 255 | firebrick = 178, 34, 34 | floralwhite = 255, 250, 240 | forestgreen = 34, 139, 34 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| fuchsia = 255, 0, 255 | gainsboro = 220, 220, 220 | ghostwhite = 248, 248, 255 | gold = 255, 215, 0 | goldenrod = 218, 165, 32 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| gray = 128, 128, 128 | green = 0, 128, 0 | greenyellow = 173, 255, 47 | honeydew = 240, 255, 240 | hotpink = 255, 105, 180 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| indianred = 205, 92, 92 | indigo = 75, 0, 130 | ivory = 255, 240, 240 | khaki = 240, 230, 140 | lavender = 230, 230, 250 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| lavenderblush = 255, 240, 245 | lawngreen = 124, 252, 0 | lemonchiffon = 255, 250, 205 | lightblue = 173, 216, 230 | lightcoral = 240, 128, 128 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| lightcyan = 224, 255, 255 | lightgoldenrodyellow = 250, 250, 210 | lightgreen = 144, 238, 144 | lightgrey = 211, 211, 211 | lightpink = 255, 182, 193 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| lightsalmon = 255, 160, 122 | lightseagreen = 32, 178, 170 | lightskyblue = 135, 206, 250 | lightslategray = 119, 136, 153 | lightsteelblue = 176, 196, 222 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| lightyellow = 255, 255, 224 | lime = 0, 255, 0 | limegreen = 50, 205, 50 | linen = 250, 240, 230 | magenta = 255, 0, 255 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| maroon = 128, 0, 0 | mediumaquamarine = 102, 205, 170 | mediumblue = 0, 0, 205 | mediumorchid = 186, 85, 211 | mediumpurple = 147, 112, 219 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| mediumseagreen = 60, 179, 113 | mediumslateblue = 123, 104, 238 | mediumspringgreen = 0, 250, 154 | mediumturquoise = 72, 209, 204 | mediumvioletred = 199, 21, 133 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| midnightblue = 25, 25, 112 | mintcream = 245, 255, 250 | mistyrose = 255, 228, 225 | moccasin = 255, 228, 181 | navajowhite = 255, 222, 173 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| navy = 0, 0, 128 | oldlace = 253, 245, 230 | olive = 128, 128, 0 | olivedrab = 107, 142, 35 | orange = 255, 165, 0 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| orangered = 255, 69, 0 | orchid = 218, 112, 214 | palegoldenrod = 238, 232, 170 | palegreen = 152, 251, 152 | paleturquoise = 175, 238, 238 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| palevioletred = 219, 112, 147 | papayawhip = 255, 239, 213 | peachpuff = 255, 239, 213 | peru = 205, 133, 63 | pink = 255, 192, 203 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| plum = 221, 160, 221 | powderblue = 176, 224, 230 | purple = 128, 0, 128 | red = 255, 0, 0 | rosybrown = 188, 143, 143 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| royalblue = 65, 105, 225 | saddlebrown = 139, 69, 19 | salmon = 250, 128, 114 | sandybrown = 244, 164, 96 | seagreen = 46, 139, 87 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| seashell = 255, 245, 238 | sienna = 160, 82, 45 | silver = 192, 192, 192 | skyblue = 135, 206, 235 | slateblue = 106, 90, 205 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| slategray = 112, 128, 144 | snow = 255, 250, 250 | springgreen = 0, 255, 127 | steelblue = 70, 130, 180 | tan = 210, 180, 140 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| teal = 0, 128, 128 | thistle = 216, 191, 216 | tomato = 253, 99, 71 | turquoise = 64, 224, 208 | violet = 238, 130, 238 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| wheat = 245, 222, 179 | white = 255, 255, 255 | whitesmoke = 245, 245, 245 | yellow = 255, 255, 0 | yellowgreen = 154, 205, 50 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+

464
doc/src/dump_modify.rst
View File

@ -3,6 +3,9 @@
dump_modify command
===================
:doc:`dump_modify <dump_image>` command for image/movie options
===============================================================
Syntax
""""""
@ -12,8 +15,9 @@ Syntax
* dump-ID = ID of dump to modify
* one or more keyword/value pairs may be appended
* these keywords apply to various dump styles
* keyword = *append* or *at* or *buffer* or *delay* or *element* or *every* or *fileper* or *first* or *flush* or *format* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap*
* keyword = *append* or *at* or *buffer* or *delay* or *element* or *every* or *fileper* or *first* or *flush* or *format* or *header* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap*
.. parsed-literal::
@ -35,6 +39,9 @@ Syntax
*format* args = *line* string, *int* string, *float* string, M string, or *none*
string = C-style format string
M = integer from 1 to N, where N = # of per-atom quantities being output
*header* arg = *yes* or *no*
*yes* to write the header
*no* to not write the header
*image* arg = *yes* or *no*
*label* arg = string
string = character string (e.g. BONDS) to use in header of dump local file
@ -66,56 +73,11 @@ Syntax
*unwrap* arg = *yes* or *no*
* these keywords apply only to the *image* and *movie* :doc:`styles <dump_image>`
* keyword = *acolor* or *adiam* or *amap* or *backcolor* or *bcolor* or *bdiam* or *boxcolor* or *color* or *bitrate* or *framerate* or *header*
* keyword = *acolor* or *adiam* or *amap* or *backcolor* or *bcolor* or *bdiam* or *boxcolor* or *color* or *bitrate* or *framerate*
.. parsed-literal::
*acolor* args = type color
type = atom type or range of types (see below)
color = name of color or color1/color2/...
*adiam* args = type diam
type = atom type or range of types (see below)
diam = diameter of atoms of that type (distance units)
*amap* args = lo hi style delta N entry1 entry2 ... entryN
lo = number or *min* = lower bound of range of color map
hi = number or *max* = upper bound of range of color map
style = 2 letters = "c" or "d" or "s" plus "a" or "f"
"c" for continuous
"d" for discrete
"s" for sequential
"a" for absolute
"f" for fractional
delta = binsize (only used for style "s", otherwise ignored)
binsize = range is divided into bins of this width
N = # of subsequent entries
entry = value color (for continuous style)
value = number or *min* or *max* = single value within range
color = name of color used for that value
entry = lo hi color (for discrete style)
lo/hi = number or *min* or *max* = lower/upper bound of subset of range
color = name of color used for that subset of values
entry = color (for sequential style)
color = name of color used for a bin of values
*backcolor* arg = color
color = name of color for background
*bcolor* args = type color
type = bond type or range of types (see below)
color = name of color or color1/color2/...
*bdiam* args = type diam
type = bond type or range of types (see below)
diam = diameter of bonds of that type (distance units)
*boxcolor* arg = color
color = name of color for simulation box lines and processor sub-domain lines
*color* args = name R G B
name = name of color
R,G,B = red/green/blue numeric values from 0.0 to 1.0
*bitrate* arg = rate
rate = target bitrate for movie in kbps
*framerate* arg = fps
fps = frames per second for movie
*header* arg = *yes* or *no*
*yes* to write the header
*no* to not write the header
see the :doc:`dump image <dump_image>` doc page for details
* these keywords apply only to the */gz* and */zstd* dump styles
* keyword = *compression_level*
@ -126,7 +88,7 @@ Syntax
level = integer specifying the compression level that should be used (see below for supported levels)
* these keywords apply only to the */zstd* dump styles
* keyword = *compression_level*
* keyword = *checksum*
.. parsed-literal::
@ -144,7 +106,6 @@ Examples
dump_modify xtcdump precision 10000 sfactor 0.1
dump_modify 1 every 1000 nfile 20
dump_modify 1 every v_myVar
dump_modify 1 amap min max cf 0.0 3 min green 0.5 yellow max blue boxcolor red
Description
"""""""""""
@ -163,8 +124,9 @@ which allow for use of MPI-IO.
----------
These keywords apply to various dump styles, including the :doc:`dump image <dump_image>` and :doc:`dump movie <dump_image>` styles. The
description gives details.
Unless otherwise noted, the following keywords apply to all the
various dump styles, including the :doc:`dump image <dump_image>` and
:doc:`dump movie <dump_image>` styles.
----------
@ -380,6 +342,13 @@ The *fileper* keyword is documented below with the *nfile* keyword.
----------
The *header* keyword toggles whether the dump file will include a header.
Excluding a header will reduce the size of the dump file for fixes such as
:doc:`fix pair/tracker <fix_pair_tracker>` which do not require the information
typically written to the header.
----------
The *image* keyword applies only to the dump *atom* style. If the
image value is *yes*, 3 flags are appended to each atom's coords which
are the absolute box image of the atom in each dimension. For
@ -715,297 +684,27 @@ box size stored with the snapshot.
----------
These keywords apply only to the :doc:`dump image <dump_image>` and
:doc:`dump movie <dump_image>` styles. Any keyword that affects an
image, also affects a movie, since the movie is simply a collection of
images. Some of the keywords only affect the :doc:`dump movie <dump_image>` style. The descriptions give details.
The COMPRESS package offers both GZ and Zstd compression variants of
styles atom, custom, local, cfg, and xyz. When using these styles the
compression level can be controlled by the :code:`compression_level`
keyword. File names with these styles have to end in either
:code:`.gz` or :code:`.zst`.
----------
The *acolor* keyword can be used with the :doc:`dump image <dump_image>`
command, when its atom color setting is *type*, to set the color that
atoms of each type will be drawn in the image.
The specified *type* should be an integer from 1 to Ntypes = the
number of atom types. A wildcard asterisk can be used in place of or
in conjunction with the *type* argument to specify a range of atom
types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N = the
number of atom types, then an asterisk with no numeric values means
all types from 1 to N. A leading asterisk means all types from 1 to n
(inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive).
The specified *color* can be a single color which is any of the 140
pre-defined colors (see below) or a color name defined by the
dump_modify color option. Or it can be two or more colors separated
by a "/" character, e.g. red/green/blue. In the former case, that
color is assigned to all the specified atom types. In the latter
case, the list of colors are assigned in a round-robin fashion to each
of the specified atom types.
----------
The *adiam* keyword can be used with the :doc:`dump image <dump_image>`
command, when its atom diameter setting is *type*, to set the size
that atoms of each type will be drawn in the image. The specified
*type* should be an integer from 1 to Ntypes. As with the *acolor*
keyword, a wildcard asterisk can be used as part of the *type*
argument to specify a range of atom types. The specified *diam* is
the size in whatever distance :doc:`units <units>` the input script is
using, e.g. Angstroms.
----------
The *amap* keyword can be used with the :doc:`dump image <dump_image>`
command, with its *atom* keyword, when its atom setting is an
atom-attribute, to setup a color map. The color map is used to assign
a specific RGB (red/green/blue) color value to an individual atom when
it is drawn, based on the atom's attribute, which is a numeric value,
e.g. its x-component of velocity if the atom-attribute "vx" was
specified.
The basic idea of a color map is that the atom-attribute will be
within a range of values, and that range is associated with a series
of colors (e.g. red, blue, green). An atom's specific value (vx =
-3.2) can then mapped to the series of colors (e.g. halfway between
red and blue), and a specific color is determined via an interpolation
procedure.
There are many possible options for the color map, enabled by the
*amap* keyword. Here are the details.
The *lo* and *hi* settings determine the range of values allowed for
the atom attribute. If numeric values are used for *lo* and/or *hi*,
then values that are lower/higher than that value are set to the
value. I.e. the range is static. If *lo* is specified as *min* or
*hi* as *max* then the range is dynamic, and the lower and/or
upper bound will be calculated each time an image is drawn, based
on the set of atoms being visualized.
The *style* setting is two letters, such as "ca". The first letter is
either "c" for continuous, "d" for discrete, or "s" for sequential.
The second letter is either "a" for absolute, or "f" for fractional.
A continuous color map is one in which the color changes continuously
from value to value within the range. A discrete color map is one in
which discrete colors are assigned to sub-ranges of values within the
range. A sequential color map is one in which discrete colors are
assigned to a sequence of sub-ranges of values covering the entire
range.
An absolute color map is one in which the values to which colors are
assigned are specified explicitly as values within the range. A
fractional color map is one in which the values to which colors are
assigned are specified as a fractional portion of the range. For
example if the range is from -10.0 to 10.0, and the color red is to be
assigned to atoms with a value of 5.0, then for an absolute color map
the number 5.0 would be used. But for a fractional map, the number
0.75 would be used since 5.0 is 3/4 of the way from -10.0 to 10.0.
The *delta* setting must be specified for all styles, but is only used
for the sequential style; otherwise the value is ignored. It
specifies the bin size to use within the range for assigning
consecutive colors to. For example, if the range is from -10.0 to
10.0 and a *delta* of 1.0 is used, then 20 colors will be assigned to
the range. The first will be from -10.0 <= color1 < -9.0, then second
from -9.0 <= color2 < -8.0, etc.
The *N* setting is how many entries follow. The format of the entries
depends on whether the color map style is continuous, discrete or
sequential. In all cases the *color* setting can be any of the 140
pre-defined colors (see below) or a color name defined by the
dump_modify color option.
For continuous color maps, each entry has a *value* and a *color*\ .
The *value* is either a number within the range of values or *min* or
*max*\ . The *value* of the first entry must be *min* and the *value*
of the last entry must be *max*\ . Any entries in between must have
increasing values. Note that numeric values can be specified either
as absolute numbers or as fractions (0.0 to 1.0) of the range,
depending on the "a" or "f" in the style setting for the color map.
Here is how the entries are used to determine the color of an
individual atom, given the value X of its atom attribute. X will fall
between 2 of the entry values. The color of the atom is linearly
interpolated (in each of the RGB values) between the 2 colors
associated with those entries. For example, if X = -5.0 and the 2
surrounding entries are "red" at -10.0 and "blue" at 0.0, then the
atom's color will be halfway between "red" and "blue", which happens
to be "purple".
For discrete color maps, each entry has a *lo* and *hi* value and a
*color*\ . The *lo* and *hi* settings are either numbers within the
range of values or *lo* can be *min* or *hi* can be *max*\ . The *lo*
and *hi* settings of the last entry must be *min* and *max*\ . Other
entries can have any *lo* and *hi* values and the sub-ranges of
different values can overlap. Note that numeric *lo* and *hi* values
can be specified either as absolute numbers or as fractions (0.0 to
1.0) of the range, depending on the "a" or "f" in the style setting
for the color map.
Here is how the entries are used to determine the color of an
individual atom, given the value X of its atom attribute. The entries
are scanned from first to last. The first time that *lo* <= X <=
*hi*, X is assigned the color associated with that entry. You can
think of the last entry as assigning a default color (since it will
always be matched by X), and the earlier entries as colors that
override the default. Also note that no interpolation of a color RGB
is done. All atoms will be drawn with one of the colors in the list
of entries.
For sequential color maps, each entry has only a *color*\ . Here is how
the entries are used to determine the color of an individual atom,
given the value X of its atom attribute. The range is partitioned
into N bins of width *binsize*\ . Thus X will fall in a specific bin
from 1 to N, say the Mth bin. If it falls on a boundary between 2
bins, it is considered to be in the higher of the 2 bins. Each bin is
assigned a color from the E entries. If E < N, then the colors are
repeated. For example if 2 entries with colors red and green are
specified, then the odd numbered bins will be red and the even bins
green. The color of the atom is the color of its bin. Note that the
sequential color map is really a shorthand way of defining a discrete
color map without having to specify where all the bin boundaries are.
Here is an example of using a sequential color map to color all the
atoms in individual molecules with a different color. See the
examples/pour/in.pour.2d.molecule input script for an example of how
this is used.
.. code-block:: LAMMPS
variable colors string &
"red green blue yellow white &
purple pink orange lime gray"
variable mol atom mol%10
dump 1 all image 250 image.*.jpg v_mol type &
zoom 1.6 adiam 1.5
dump_modify 1 pad 5 amap 0 10 sa 1 10 ${colors}
In this case, 10 colors are defined, and molecule IDs are
mapped to one of the colors, even if there are 1000s of molecules.
----------
The *backcolor* sets the background color of the images. The color
name can be any of the 140 pre-defined colors (see below) or a color
name defined by the dump_modify color option.
----------
The *bcolor* keyword can be used with the :doc:`dump image <dump_image>`
command, with its *bond* keyword, when its color setting is *type*, to
set the color that bonds of each type will be drawn in the image.
The specified *type* should be an integer from 1 to Nbondtypes = the
number of bond types. A wildcard asterisk can be used in place of or
in conjunction with the *type* argument to specify a range of bond
types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N = the
number of bond types, then an asterisk with no numeric values means
all types from 1 to N. A leading asterisk means all types from 1 to n
(inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive).
The specified *color* can be a single color which is any of the 140
pre-defined colors (see below) or a color name defined by the
dump_modify color option. Or it can be two or more colors separated
by a "/" character, e.g. red/green/blue. In the former case, that
color is assigned to all the specified bond types. In the latter
case, the list of colors are assigned in a round-robin fashion to each
of the specified bond types.
----------
The *bdiam* keyword can be used with the :doc:`dump image <dump_image>`
command, with its *bond* keyword, when its diam setting is *type*, to
set the diameter that bonds of each type will be drawn in the image.
The specified *type* should be an integer from 1 to Nbondtypes. As
with the *bcolor* keyword, a wildcard asterisk can be used as part of
the *type* argument to specify a range of bond types. The specified
*diam* is the size in whatever distance :doc:`units <units>` you are
using, e.g. Angstroms.
----------
The *bitrate* keyword can be used with the :doc:`dump movie <dump_image>` command to define the size of the resulting
movie file and its quality via setting how many kbits per second are
to be used for the movie file. Higher bitrates require less
compression and will result in higher quality movies. The quality is
also determined by the compression format and encoder. The default
setting is 2000 kbit/s, which will result in average quality with
older compression formats.
.. note::
Not all movie file formats supported by dump movie allow the
bitrate to be set. If not, the setting is silently ignored.
----------
The *boxcolor* keyword sets the color of the simulation box drawn
around the atoms in each image as well as the color of processor
sub-domain boundaries. See the "dump image box" command for how to
specify that a box be drawn via the *box* keyword, and the sub-domain
boundaries via the *subbox* keyword. The color name can be any of the
140 pre-defined colors (see below) or a color name defined by the
dump_modify color option.
----------
The *color* keyword allows definition of a new color name, in addition
to the 140-predefined colors (see below), and associates 3
red/green/blue RGB values with that color name. The color name can
then be used with any other dump_modify keyword that takes a color
name as a value. The RGB values should each be floating point values
between 0.0 and 1.0 inclusive.
When a color name is converted to RGB values, the user-defined color
names are searched first, then the 140 pre-defined color names. This
means you can also use the *color* keyword to overwrite one of the
pre-defined color names with new RBG values.
----------
The *framerate* keyword can be used with the :doc:`dump movie <dump_image>` command to define the duration of the resulting
movie file. Movie files written by the dump *movie* command have a
default frame rate of 24 frames per second and the images generated
will be converted at that rate. Thus a sequence of 1000 dump images
will result in a movie of about 42 seconds. To make a movie run
longer you can either generate images more frequently or lower the
frame rate. To speed a movie up, you can do the inverse. Using a
frame rate higher than 24 is not recommended, as it will result in
simply dropping the rendered images. It is more efficient to dump
images less frequently.
----------
The *header* keyword toggles whether the dump file will include a header.
Excluding a header will reduce the size of the dump file for fixes such as
:doc:`fix pair/tracker <fix_pair_tracker>` which do not require the information
typically written to the header.
----------
The COMPRESS package offers both GZ and Zstd compression variants of styles
atom, custom, local, cfg, and xyz. When using these styles the compression
level can be controlled by the :code:`compression_level` parameter. File names
with these styles have to end in either :code:`.gz` or :code:`.zst`.
GZ supports compression levels from -1 (default), 0 (no compression), and 1 to
9. 9 being the best compression. The COMPRESS :code:`/gz` styles use 9 as
default compression level.
GZ supports compression levels from -1 (default), 0 (no compression),
and 1 to
9. 9 being the best compression. The COMPRESS :code:`/gz` styles use 9
as default compression level.
Zstd offers a wider range of compression levels, including negative
levels that sacrifice compression for performance. 0 is the
default, positive levels are 1 to 22, with 22 being the most expensive
levels that sacrifice compression for performance. 0 is the default,
positive levels are 1 to 22, with 22 being the most expensive
compression. Zstd promises higher compression/decompression speeds for
similar compression ratios. For more details see
`http://facebook.github.io/zstd/`.
In addition, Zstd compressed files can have a checksum of the entire
contents. The Zstd enabled dump styles enable this feature by default and it
can be disabled with the :code:`checksum` parameter.
In addition, Zstd compressed files can include a checksum of the
entire contents. The Zstd enabled dump styles enable this feature by
default and it can be disabled with the :code:`checksum` keyword.
----------
@ -1046,100 +745,7 @@ The option defaults are
* units = no
* unwrap = no
* acolor = \* red/green/blue/yellow/aqua/cyan
* adiam = \* 1.0
* amap = min max cf 0.0 2 min blue max red
* backcolor = black
* bcolor = \* red/green/blue/yellow/aqua/cyan
* bdiam = \* 0.5
* bitrate = 2000
* boxcolor = yellow
* color = 140 color names are pre-defined as listed below
* framerate = 24
* compression_level = 9 (gz variants)
* compression_level = 0 (zstd variants)
* checksum = yes (zstd variants)
----------
These are the standard 109 element names that LAMMPS pre-defines for
use with the :doc:`dump image <dump_image>` and dump_modify commands.
* 1-10 = "H", "He", "Li", "Be", "B", "C", "N", "O", "F", "Ne"
* 11-20 = "Na", "Mg", "Al", "Si", "P", "S", "Cl", "Ar", "K", "Ca"
* 21-30 = "Sc", "Ti", "V", "Cr", "Mn", "Fe", "Co", "Ni", "Cu", "Zn"
* 31-40 = "Ga", "Ge", "As", "Se", "Br", "Kr", "Rb", "Sr", "Y", "Zr"
* 41-50 = "Nb", "Mo", "Tc", "Ru", "Rh", "Pd", "Ag", "Cd", "In", "Sn"
* 51-60 = "Sb", "Te", "I", "Xe", "Cs", "Ba", "La", "Ce", "Pr", "Nd"
* 61-70 = "Pm", "Sm", "Eu", "Gd", "Tb", "Dy", "Ho", "Er", "Tm", "Yb"
* 71-80 = "Lu", "Hf", "Ta", "W", "Re", "Os", "Ir", "Pt", "Au", "Hg"
* 81-90 = "Tl", "Pb", "Bi", "Po", "At", "Rn", "Fr", "Ra", "Ac", "Th"
* 91-100 = "Pa", "U", "Np", "Pu", "Am", "Cm", "Bk", "Cf", "Es", "Fm"
* 101-109 = "Md", "No", "Lr", "Rf", "Db", "Sg", "Bh", "Hs", "Mt"
----------
These are the 140 colors that LAMMPS pre-defines for use with the
:doc:`dump image <dump_image>` and dump_modify commands. Additional
colors can be defined with the dump_modify color command. The 3
numbers listed for each name are the RGB (red/green/blue) values.
Divide each value by 255 to get the equivalent 0.0 to 1.0 value.
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| aliceblue = 240, 248, 255 | antiquewhite = 250, 235, 215 | aqua = 0, 255, 255 | aquamarine = 127, 255, 212 | azure = 240, 255, 255 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| beige = 245, 245, 220 | bisque = 255, 228, 196 | black = 0, 0, 0 | blanchedalmond = 255, 255, 205 | blue = 0, 0, 255 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| blueviolet = 138, 43, 226 | brown = 165, 42, 42 | burlywood = 222, 184, 135 | cadetblue = 95, 158, 160 | chartreuse = 127, 255, 0 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| chocolate = 210, 105, 30 | coral = 255, 127, 80 | cornflowerblue = 100, 149, 237 | cornsilk = 255, 248, 220 | crimson = 220, 20, 60 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| cyan = 0, 255, 255 | darkblue = 0, 0, 139 | darkcyan = 0, 139, 139 | darkgoldenrod = 184, 134, 11 | darkgray = 169, 169, 169 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| darkgreen = 0, 100, 0 | darkkhaki = 189, 183, 107 | darkmagenta = 139, 0, 139 | darkolivegreen = 85, 107, 47 | darkorange = 255, 140, 0 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| darkorchid = 153, 50, 204 | darkred = 139, 0, 0 | darksalmon = 233, 150, 122 | darkseagreen = 143, 188, 143 | darkslateblue = 72, 61, 139 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| darkslategray = 47, 79, 79 | darkturquoise = 0, 206, 209 | darkviolet = 148, 0, 211 | deeppink = 255, 20, 147 | deepskyblue = 0, 191, 255 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| dimgray = 105, 105, 105 | dodgerblue = 30, 144, 255 | firebrick = 178, 34, 34 | floralwhite = 255, 250, 240 | forestgreen = 34, 139, 34 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| fuchsia = 255, 0, 255 | gainsboro = 220, 220, 220 | ghostwhite = 248, 248, 255 | gold = 255, 215, 0 | goldenrod = 218, 165, 32 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| gray = 128, 128, 128 | green = 0, 128, 0 | greenyellow = 173, 255, 47 | honeydew = 240, 255, 240 | hotpink = 255, 105, 180 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| indianred = 205, 92, 92 | indigo = 75, 0, 130 | ivory = 255, 240, 240 | khaki = 240, 230, 140 | lavender = 230, 230, 250 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| lavenderblush = 255, 240, 245 | lawngreen = 124, 252, 0 | lemonchiffon = 255, 250, 205 | lightblue = 173, 216, 230 | lightcoral = 240, 128, 128 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| lightcyan = 224, 255, 255 | lightgoldenrodyellow = 250, 250, 210 | lightgreen = 144, 238, 144 | lightgrey = 211, 211, 211 | lightpink = 255, 182, 193 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| lightsalmon = 255, 160, 122 | lightseagreen = 32, 178, 170 | lightskyblue = 135, 206, 250 | lightslategray = 119, 136, 153 | lightsteelblue = 176, 196, 222 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| lightyellow = 255, 255, 224 | lime = 0, 255, 0 | limegreen = 50, 205, 50 | linen = 250, 240, 230 | magenta = 255, 0, 255 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| maroon = 128, 0, 0 | mediumaquamarine = 102, 205, 170 | mediumblue = 0, 0, 205 | mediumorchid = 186, 85, 211 | mediumpurple = 147, 112, 219 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| mediumseagreen = 60, 179, 113 | mediumslateblue = 123, 104, 238 | mediumspringgreen = 0, 250, 154 | mediumturquoise = 72, 209, 204 | mediumvioletred = 199, 21, 133 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| midnightblue = 25, 25, 112 | mintcream = 245, 255, 250 | mistyrose = 255, 228, 225 | moccasin = 255, 228, 181 | navajowhite = 255, 222, 173 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| navy = 0, 0, 128 | oldlace = 253, 245, 230 | olive = 128, 128, 0 | olivedrab = 107, 142, 35 | orange = 255, 165, 0 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| orangered = 255, 69, 0 | orchid = 218, 112, 214 | palegoldenrod = 238, 232, 170 | palegreen = 152, 251, 152 | paleturquoise = 175, 238, 238 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| palevioletred = 219, 112, 147 | papayawhip = 255, 239, 213 | peachpuff = 255, 239, 213 | peru = 205, 133, 63 | pink = 255, 192, 203 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| plum = 221, 160, 221 | powderblue = 176, 224, 230 | purple = 128, 0, 128 | red = 255, 0, 0 | rosybrown = 188, 143, 143 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| royalblue = 65, 105, 225 | saddlebrown = 139, 69, 19 | salmon = 250, 128, 114 | sandybrown = 244, 164, 96 | seagreen = 46, 139, 87 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| seashell = 255, 245, 238 | sienna = 160, 82, 45 | silver = 192, 192, 192 | skyblue = 135, 206, 235 | slateblue = 106, 90, 205 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| slategray = 112, 128, 144 | snow = 255, 250, 250 | springgreen = 0, 255, 127 | steelblue = 70, 130, 180 | tan = 210, 180, 140 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| teal = 0, 128, 128 | thistle = 216, 191, 216 | tomato = 253, 99, 71 | turquoise = 64, 224, 208 | violet = 238, 130, 238 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
| wheat = 245, 222, 179 | white = 255, 255, 255 | whitesmoke = 245, 245, 245 | yellow = 255, 255, 0 | yellowgreen = 154, 205, 50 |
+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+

2
doc/src/fix.rst
View File

@ -166,6 +166,7 @@ page are followed by one or more of (g,i,k,o,t) to indicate which
accelerated styles exist.
* :doc:`accelerate/cos <fix_accelerate_cos>` - apply cosine-shaped acceleration to atoms
* :doc:`acks2/reaxff <fix_acks2_reaxff>` - apply ACKS2 charge equilibration
* :doc:`adapt <fix_adapt>` - change a simulation parameter over time
* :doc:`adapt/fep <fix_adapt_fep>` - enhanced version of fix adapt
* :doc:`addforce <fix_addforce>` - add a force to each atom
@ -246,6 +247,7 @@ accelerated styles exist.
* :doc:`manifoldforce <fix_manifoldforce>` - restrain atoms to a manifold during minimization
* :doc:`mdi/engine <fix_mdi_engine>` - connect LAMMPS to external programs via the MolSSI Driver Interface (MDI)
* :doc:`meso/move <fix_meso_move>` - move mesoscopic SPH/SDPD particles in a prescribed fashion
* :doc:`mol/swap <fix_mol_swap>` - Monte Carlo atom type swapping with a molecule
* :doc:`momentum <fix_momentum>` - zero the linear and/or angular momentum of a group of atoms
* :doc:`momentum/chunk <fix_momentum>` - zero the linear and/or angular momentum of a chunk of atoms
* :doc:`move <fix_move>` - move atoms in a prescribed fashion

118
doc/src/fix_acks2_reaxff.rst Normal file
View File

@ -0,0 +1,118 @@
.. index:: fix acks2/reaxff
.. index:: fix acks2/reaxff/kk
fix acks2/reaxff command
========================
Accelerator Variants: *acks2/reaxff/kk*
Syntax
""""""
.. parsed-literal::
fix ID group-ID acks2/reaxff Nevery cutlo cuthi tolerance params args
* ID, group-ID are documented in :doc:`fix <fix>` command
* acks2/reaxff = style name of this fix command
* Nevery = perform ACKS2 every this many steps
* cutlo,cuthi = lo and hi cutoff for Taper radius
* tolerance = precision to which charges will be equilibrated
* params = reaxff or a filename
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all acks2/reaxff 1 0.0 10.0 1.0e-6 reaxff
fix 1 all acks2/reaxff 1 0.0 10.0 1.0e-6 param.acks2
Description
"""""""""""
Perform the atom-condensed Kohn-Sham DFT to second order (ACKS2) charge
equilibration method as described in :ref:`(Verstraelen) <Verstraelen>`.
ACKS2 impedes unphysical long-range charge transfer sometimes seen with
QEq (e.g. for dissociation of molecules), at increased computational
cost. It is typically used in conjunction with the ReaxFF force field
model as implemented in the :doc:`pair_style reaxff <pair_reaxff>`
command, but it can be used with any potential in LAMMPS, so long as it
defines and uses charges on each atom. For more technical details about
the charge equilibration performed by fix acks2/reaxff, see the
:ref:`(O'Hearn) <O'Hearn>` paper.
The ACKS2 method minimizes the electrostatic energy of the system by
adjusting the partial charge on individual atoms based on interactions
with their neighbors. It requires some parameters for each atom type.
If the *params* setting above is the word "reaxff", then these are
extracted from the :doc:`pair_style reaxff <pair_reaxff>` command and
the ReaxFF force field file it reads in. If a file name is specified
for *params*\ , then the parameters are taken from the specified file
and the file must contain one line for each atom type. The latter form
must be used when performing QeQ with a non-ReaxFF potential. The lines
should be formatted as follows:
.. parsed-literal::
bond_softness
itype chi eta gamma bcut
where the first line is the global parameter *bond_softness*. The
remaining 1 to Ntypes lines include *itype*, the atom type from 1 to
Ntypes, *chi*, the electronegativity in eV, *eta*, the self-Coulomb
potential in eV, *gamma*, the valence orbital exponent, and *bcut*, the
bond cutoff distance. Note that these 4 quantities are also in the
ReaxFF potential file, except that eta is defined here as twice the eta
value in the ReaxFF file. Note that unlike the rest of LAMMPS, the units
of this fix are hard-coded to be A, eV, and electronic charge.
**Restart, fix_modify, output, run start/stop, minimize info:**
No information about this fix is written to :doc:`binary restart files
<restart>`. No global scalar or vector or per-atom quantities are
stored by this fix for access by various :doc:`output commands
<Howto_output>`. No parameter of this fix can be used with the
*start/stop* keywords of the :doc:`run <run>` command.
This fix is invoked during :doc:`energy minimization <minimize>`.
----------
.. include:: accel_styles.rst
----------
Restrictions
""""""""""""
This fix is part of the REAXFF package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` doc page for more info.
This fix does not correctly handle interactions involving multiple
periodic images of the same atom. Hence, it should not be used for
periodic cell dimensions less than 10 angstroms.
This fix may be used in combination with :doc:`fix efield <fix_efield>`
and will apply the external electric field during charge equilibration,
but there may be only one fix efield instance used, it may only use a
constant electric field, and the electric field vector may only have
components in non-periodic directions.
Related commands
""""""""""""""""
:doc:`pair_style reaxff <pair_reaxff>`, :doc:`fix qeq/reaxff <fix_qeq_reaxff>`
**Default:** none
----------
.. _O'Hearn:
**(O'Hearn)** O'Hearn, Alperen, Aktulga, SIAM J. Sci. Comput., 42(1), C1-C22 (2020).
.. _Verstraelen:
**(Verstraelen)** Verstraelen, Ayers, Speybroeck, Waroquier, J. Chem. Phys. 138, 074108 (2013).

103
doc/src/fix_atom_swap.rst
View File

@ -73,51 +73,51 @@ is the same after the swap as it was before the swap, even though the
atom masses have changed.
The *semi-grand* keyword can be set to *yes* to switch to the
semi-grand canonical ensemble as discussed in :ref:`(Sadigh) <Sadigh>`. This
means that the total number of each particle type does not need to be
conserved. The default is *no*, which means that the only kind of swap
allowed exchanges an atom of one type with an atom of a different
given type. In other words, the relative mole fractions of the swapped
atoms remains constant. Whereas in the semi-grand canonical ensemble,
the composition of the system can change. Note that when using
*semi-grand*, atoms in the fix group whose type is not listed
in the *types* keyword are ineligible for attempted
conversion. An attempt is made to switch
the selected atom (if eligible) to one of the other listed types
with equal probability. Acceptance of each attempt depends upon the Metropolis criterion.
semi-grand canonical ensemble as discussed in :ref:`(Sadigh)
<Sadigh>`. This means that the total number of each particle type does
not need to be conserved. The default is *no*, which means that the
only kind of swap allowed exchanges an atom of one type with an atom
of a different given type. In other words, the relative mole fractions
of the swapped atoms remains constant. Whereas in the semi-grand
canonical ensemble, the composition of the system can change. Note
that when using *semi-grand*, atoms in the fix group whose type is not
listed in the *types* keyword are ineligible for attempted
conversion. An attempt is made to switch the selected atom (if
eligible) to one of the other listed types with equal
probability. Acceptance of each attempt depends upon the Metropolis
criterion.
The *mu* keyword allows users to specify chemical
potentials. This is required and allowed only when using *semi-grand*\ .
All chemical potentials are absolute, so there is one for
each swap type listed following the *types* keyword.
In semi-grand canonical ensemble simulations the chemical composition
of the system is controlled by the difference in these values. So
shifting all values by a constant amount will have no effect
on the simulation.
The *mu* keyword allows users to specify chemical potentials. This is
required and allowed only when using *semi-grand*\ . All chemical
potentials are absolute, so there is one for each swap type listed
following the *types* keyword. In semi-grand canonical ensemble
simulations the chemical composition of the system is controlled by
the difference in these values. So shifting all values by a constant
amount will have no effect on the simulation.
This command may optionally use the *region* keyword to define swap
volume. The specified region must have been previously defined with a
:doc:`region <region>` command. It must be defined with side = *in*\ .
Swap attempts occur only between atoms that are both within the
:doc:`region <region>` command. It must be defined with side = *in*\
. Swap attempts occur only between atoms that are both within the
specified region. Swaps are not otherwise attempted.
You should ensure you do not swap atoms belonging to a molecule, or
LAMMPS will soon generate an error when it tries to find those atoms.
LAMMPS will warn you if any of the atoms eligible for swapping have a
non-zero molecule ID, but does not check for this at the time of
LAMMPS will eventually generate an error when it tries to find those
atoms. LAMMPS will warn you if any of the atoms eligible for swapping
have a non-zero molecule ID, but does not check for this at the time of
swapping.
If not using *semi-grand* this fix checks to ensure all atoms of the
given types have the same atomic charge. LAMMPS does not enforce this
in general, but it is needed for this fix to simplify the
swapping procedure. Successful swaps will swap the atom type and charge
of the swapped atoms. Conversely, when using *semi-grand*, it is assumed that all the atom
types involved in switches have the same charge. Otherwise, charge
would not be conserved. As a consequence, no checks on atomic charges are
performed, and successful switches update the atom type but not the
atom charge. While it is possible to use *semi-grand* with groups of
atoms that have different charges, these charges will not be changed when the
atom types change.
in general, but it is needed for this fix to simplify the swapping
procedure. Successful swaps will swap the atom type and charge of the
swapped atoms. Conversely, when using *semi-grand*, it is assumed that
all the atom types involved in switches have the same
charge. Otherwise, charge would not be conserved. As a consequence, no
checks on atomic charges are performed, and successful switches update
the atom type but not the atom charge. While it is possible to use
*semi-grand* with groups of atoms that have different charges, these
charges will not be changed when the atom types change.
Since this fix computes total potential energies before and after
proposed swaps, so even complicated potential energy calculations are
@ -133,23 +133,24 @@ OK, including the following:
Some fixes have an associated potential energy. Examples of such fixes
include: :doc:`efield <fix_efield>`, :doc:`gravity <fix_gravity>`,
:doc:`addforce <fix_addforce>`, :doc:`langevin <fix_langevin>`,
:doc:`restrain <fix_restrain>`, :doc:`temp/berendsen <fix_temp_berendsen>`,
:doc:`temp/rescale <fix_temp_rescale>`, and :doc:`wall fixes <fix_wall>`.
For that energy to be included in the total potential energy of the
system (the quantity used when performing GCMC moves),
you MUST enable the :doc:`fix_modify <fix_modify>` *energy* option for
that fix. The doc pages for individual :doc:`fix <fix>` commands
specify if this should be done.
:doc:`restrain <fix_restrain>`, :doc:`temp/berendsen
<fix_temp_berendsen>`, :doc:`temp/rescale <fix_temp_rescale>`, and
:doc:`wall fixes <fix_wall>`. For that energy to be included in the
total potential energy of the system (the quantity used when
performing GCMC moves), you MUST enable the :doc:`fix_modify
<fix_modify>` *energy* option for that fix. The doc pages for
individual :doc:`fix <fix>` commands specify if this should be done.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This fix writes the state of the fix to :doc:`binary restart files <restart>`. This includes information about the random
number generator seed, the next timestep for MC exchanges, the number
of exchange attempts and successes etc. See
the :doc:`read_restart <read_restart>` command for info on how to
re-specify a fix in an input script that reads a restart file, so that
the operation of the fix continues in an uninterrupted fashion.
This fix writes the state of the fix to :doc:`binary restart files
<restart>`. This includes information about the random number
generator seed, the next timestep for MC exchanges, the number of
exchange attempts and successes etc. See the :doc:`read_restart
<read_restart>` command for info on how to re-specify a fix in an
input script that reads a restart file, so that the operation of the
fix continues in an uninterrupted fashion.
.. note::
@ -165,12 +166,13 @@ by various :doc:`output commands <Howto_output>`. The vector values are
the following global cumulative quantities:
* 1 = swap attempts
* 2 = swap successes
* 2 = swap accepts
The vector values calculated by this fix are "extensive".
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command. This fix is not invoked during :doc:`energy minimization <minimize>`.
the :doc:`run <run>` command. This fix is not invoked during
:doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
@ -184,7 +186,8 @@ Related commands
:doc:`fix nvt <fix_nh>`, :doc:`neighbor <neighbor>`,
:doc:`fix deposit <fix_deposit>`, :doc:`fix evaporate <fix_evaporate>`,
:doc:`delete_atoms <delete_atoms>`, :doc:`fix gcmc <fix_gcmc>`
:doc:`delete_atoms <delete_atoms>`, :doc:`fix gcmc <fix_gcmc>`,
:doc:`fix mol/swap <fix_mol_swap>`
Default
"""""""

25
doc/src/fix_langevin.rst
View File

@ -138,16 +138,18 @@ temperature with optional time-dependence as well.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. removing the center-of-mass velocity from a
group of atoms or removing the x-component of velocity from the
calculation. This is not done by default, but only if the
:doc:`fix_modify <fix_modify>` command is used to assign a temperature
compute to this fix that includes such a bias term. See the doc pages
for individual :doc:`compute commands <compute>` to determine which ones
include a bias. In this case, the thermostat works in the following
manner: bias is removed from each atom, thermostatting is performed on
the remaining thermal degrees of freedom, and the bias is added back
in.
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
The *damp* parameter is specified in time units and determines how
rapidly the temperature is relaxed. For example, a value of 100.0 means
@ -183,7 +185,8 @@ omega (which is derived from the angular momentum in the case of
aspherical particles).
The rotational temperature of the particles can be monitored by the
:doc:`compute temp/sphere <compute_temp_sphere>` and :doc:`compute temp/asphere <compute_temp_asphere>` commands with their rotate
:doc:`compute temp/sphere <compute_temp_sphere>` and :doc:`compute
temp/asphere <compute_temp_asphere>` commands with their rotate
options.
For the *omega* keyword there is also a scale factor of

25
doc/src/fix_langevin_drude.rst
View File

@ -167,17 +167,20 @@ functions, and include :doc:`thermo_style <thermo_style>` command
keywords for the simulation box parameters and timestep and elapsed
time. Thus it is easy to specify a time-dependent temperature.
Like other fixes that perform thermostatting, this fix can be used with
:doc:`compute commands <compute>` that remove a "bias" from the atom
velocities. E.g. removing the center-of-mass velocity from a group of
atoms. This is not done by default, but only if the
:doc:`fix_modify <fix_modify>` command is used to assign a temperature
compute to this fix that includes such a bias term. See the doc pages
for individual :doc:`compute commands <compute>` to determine which ones
include a bias. In this case, the thermostat works in the following
manner: bias is removed from each atom, thermostatting is performed on
the remaining thermal degrees of freedom, and the bias is added back
in. NOTE: this feature has not been tested.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
Note: The temperature thermostatting the core-Drude particle pairs
should be chosen low enough, so as to mimic as closely as possible the

170
doc/src/fix_mol_swap.rst Normal file
View File

@ -0,0 +1,170 @@
.. index:: fix mol/swap
fix mol/swap command
=====================
Syntax
""""""
.. parsed-literal::
fix ID group-ID mol/swap N X itype jtype seed T keyword value ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* atom/swap = style name of this fix command
* N = invoke this fix every N steps
* X = number of swaps to attempt every N steps
* itype,jtype = two atom types to swap with each other
* seed = random # seed (positive integer)
* T = scaling temperature of the MC swaps (temperature units)
* zero or more keyword/value pairs may be appended to args
* keyword = *ke*
.. parsed-literal::
*ke* value = *no* or *yes*
*no* = no conservation of kinetic energy after atom swaps
*yes* = kinetic energy is conserved after atom swaps
Examples
""""""""
.. code-block:: LAMMPS
fix 2 all mol/swap 100 1 2 3 29494 300.0 ke no
fix mySwap fluid mol/swap 500 10 1 2 482798 1.0
Description
"""""""""""
This fix performs Monte Carlo swaps of two specified atom types within
a randomly selected molecule. Two possible use cases are as follows.
First, consider a mixture of some molecules with atoms of itype and
other molecules with atoms of jtype. The fix will select a random
molecule and attempt to swap all the itype atoms to jtype for the
first kind of molecule, or all the jtype atoms to itype for the second
kind. Because the swap will only take place if it is energetically
favorable, the fix can be used to determine the miscibility of 2
different kinds of molecules much more quickly than just dynamics
would do it.
Second, consider diblock co-polymers with two types of monomers itype
and jtype. The fix will select a random molecule and attempt to do a
itype <--> jtype swap of all those monomers within the molecule. Thus
the fix can be used to find the energetically favorable fractions of
two flavors of diblock co-polymers.
Intra-molecular swaps of atom types are attempted every N timesteps. On
that timestep, X swaps are attempted. For each attempt a single
molecule ID is randomly selected. The range of possible molecule IDs
from loID to hiID is pre-computed before each run begins. The
loID/hiID is set for the molecule with the smallest/largest ID which
has any itype or jtype atoms in it. Note that if you define a system
with many molecule IDs between loID and hiID which have no itype or
jtype atoms, then the fix will be inefficient at performing swaps.
Also note that if atoms with molecule ID = 0 exist, they are not
considered molecules by this fix; they are assumed to be solvent atoms
or molecules.
Candidate atoms for swapping must also be in the fix group. Atoms
within the selected molecule which are not itype or jtype are ignored.
When an atom is swapped from itype to jtype (or vice versa), if
charges are defined, the charge values for itype versus jtype atoms
are also swapped. This requires that all itype atoms in the system
have the same charge value. Likewise all jtype atoms in the system
must have the same charge value. If this is not the case, LAMMPS
issues a warning that it cannot swap charge values.
If the *ke* keyword is set to yes, which is the default, and the
masses of itype and jtype atoms are different, then when a swap
occurs, the velocity of the swapped atom is rescaled by the sqrt of
the mass ratio, so as to conserve the kinetic energy of the atom.
----------
The potential energy of the entire system is computed before and after
each swap is performed within a single molecule. The specified
temperature T is used in the Metropolis criterion to accept or reject
the attempted swap. If the swap is rejected all swapped values are
reversed.
The potential energy calculations can include systems and models with
the following features:
* manybody pair styles, including EAM
* hybrid pair styles
* long-range electrostatics (kspace)
* triclinic systems
* potential energy contributions from other fixes
For the last bullet point, fixes can have an associated potential
energy. Examples of such fixes include: :doc:`efield <fix_efield>`,
:doc:`gravity <fix_gravity>`, :doc:`addforce <fix_addforce>`,
:doc:`langevin <fix_langevin>`, :doc:`restrain <fix_restrain>`,
:doc:`temp/berendsen <fix_temp_berendsen>`, :doc:`temp/rescale
<fix_temp_rescale>`, and :doc:`wall fixes <fix_wall>`. For that
energy to be included in the total potential energy of the system (the
quantity used for the swap accept/reject decision), you MUST enable
the :doc:`fix_modify <fix_modify>` *energy* option for that fix. The
doc pages for individual :doc:`fix <fix>` commands specify if this
should be done.
.. note::
One comment on computational efficiency. If the cutoff lengths
defined for the pair style are different for itype versus jtype
atoms (for any of their interactions with any other atom type), then
a new neighbor list needs to be generated for every attempted swap.
This is potentially expensive if N is small or X is large.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This fix writes the state of the fix to :doc:`binary restart files
<restart>`. This includes information about the random number
generator seed, the next timestep for MC exchanges, the number of
exchange attempts and successes etc. See the :doc:`read_restart
<read_restart>` command for info on how to re-specify a fix in an
input script that reads a restart file, so that the operation of the
fix continues in an uninterrupted fashion.
.. note::
For this to work correctly, the timestep must **not** be changed
after reading the restart with :doc:`reset_timestep <reset_timestep>`.
The fix will try to detect it and stop with an error.
None of the :doc:`fix_modify <fix_modify>` options are relevant to this
fix.
This fix computes a global vector of length 2, which can be accessed
by various :doc:`output commands <Howto_output>`. The vector values are
the following global cumulative quantities:
* 1 = swap attempts
* 2 = swap accepts
The vector values calculated by this fix are "extensive".
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command. This fix is not invoked during
:doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
This fix is part of the MC package. It is only enabled if LAMMPS was
built with that package. See the :doc:`Build package <Build_package>`
doc page for more info.
Related commands
""""""""""""""""
:doc:`fix atom/swap <fix_atom_swap>`, :doc:`fix gcmc <fix_gcmc>`
Default
"""""""
The option default is ke = yes.

27
doc/src/fix_nh.rst
View File

@ -486,19 +486,20 @@ temperature or pressure during thermodynamic output via the
compute-ID. It also means that changing attributes of *thermo_temp*
or *thermo_press* will have no effect on this fix.
Like other fixes that perform thermostatting, fix nvt and fix npt can
be used with :doc:`compute commands <compute>` that calculate a
temperature after removing a "bias" from the atom velocities.
E.g. removing the center-of-mass velocity from a group of atoms or
only calculating temperature on the x-component of velocity or only
calculating temperature for atoms in a geometric region. This is not
done by default, but only if the :doc:`fix_modify <fix_modify>` command
is used to assign a temperature compute to this fix that includes such
a bias term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

30
doc/src/fix_npt_asphere.rst
View File

@ -48,8 +48,9 @@ can also have a bias velocity removed from them before thermostatting
takes place; see the description below.
Additional parameters affecting the thermostat and barostat are
specified by keywords and values documented with the :doc:`fix npt <fix_nh>` command. See, for example, discussion of the *temp*,
*iso*, *aniso*, and *dilate* keywords.
specified by keywords and values documented with the :doc:`fix npt
<fix_nh>` command. See, for example, discussion of the *temp*, *iso*,
*aniso*, and *dilate* keywords.
The particles in the fix group are the only ones whose velocities and
positions are updated by the velocity/position update portion of the
@ -89,18 +90,19 @@ It also means that changing attributes of *thermo_temp* or
*thermo_press* will have no effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

25
doc/src/fix_npt_body.rst
View File

@ -87,18 +87,19 @@ It also means that changing attributes of *thermo_temp* or
*thermo_press* will have no effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

27
doc/src/fix_npt_cauchy.rst
View File

@ -400,19 +400,20 @@ temperature or pressure during thermodynamic output via the
compute-ID. It also means that changing attributes of *thermo_temp*
or *thermo_press* will have no effect on this fix.
Like other fixes that perform thermostatting, fix npt/cauchy can
be used with :doc:`compute commands <compute>` that calculate a
temperature after removing a "bias" from the atom velocities.
E.g. removing the center-of-mass velocity from a group of atoms or
only calculating temperature on the x-component of velocity or only
calculating temperature for atoms in a geometric region. This is not
done by default, but only if the :doc:`fix_modify <fix_modify>` command
is used to assign a temperature compute to this fix that includes such
a bias term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

25
doc/src/fix_npt_sphere.rst
View File

@ -103,18 +103,19 @@ appropriate compute-ID. It also means that changing attributes of
*thermo_temp* or *thermo_press* will have no effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

25
doc/src/fix_nvt_asphere.rst
View File

@ -72,18 +72,19 @@ It also means that changing attributes of *thermo_temp* will have no
effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

25
doc/src/fix_nvt_body.rst
View File

@ -69,18 +69,19 @@ It also means that changing attributes of *thermo_temp* will have no
effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

74
doc/src/fix_nvt_sllod.rst
View File

@ -37,15 +37,16 @@ trajectory consistent with the canonical ensemble.
This thermostat is used for a simulation box that is changing size
and/or shape, for example in a non-equilibrium MD (NEMD) simulation.
The size/shape change is induced by use of the :doc:`fix deform <fix_deform>` command, so each point in the simulation box
can be thought of as having a "streaming" velocity. This
position-dependent streaming velocity is subtracted from each atom's
actual velocity to yield a thermal velocity which is used for
temperature computation and thermostatting. For example, if the box
is being sheared in x, relative to y, then points at the bottom of the
box (low y) have a small x velocity, while points at the top of the
box (hi y) have a large x velocity. These velocities do not
contribute to the thermal "temperature" of the atom.
The size/shape change is induced by use of the :doc:`fix deform
<fix_deform>` command, so each point in the simulation box can be
thought of as having a "streaming" velocity. This position-dependent
streaming velocity is subtracted from each atom's actual velocity to
yield a thermal velocity which is used for temperature computation and
thermostatting. For example, if the box is being sheared in x,
relative to y, then points at the bottom of the box (low y) have a
small x velocity, while points at the top of the box (hi y) have a
large x velocity. These velocities do not contribute to the thermal
"temperature" of the atom.
.. note::
@ -60,13 +61,15 @@ contribute to the thermal "temperature" of the atom.
consistent.
The SLLOD equations of motion, originally proposed by Hoover and Ladd
(see :ref:`(Evans and Morriss) <Evans3>`), were proven to be equivalent to
Newton's equations of motion for shear flow by :ref:`(Evans and Morriss) <Evans3>`. They were later shown to generate the desired
velocity gradient and the correct production of work by stresses for
all forms of homogeneous flow by :ref:`(Daivis and Todd) <Daivis>`. As
implemented in LAMMPS, they are coupled to a Nose/Hoover chain
thermostat in a velocity Verlet formulation, closely following the
implementation used for the :doc:`fix nvt <fix_nh>` command.
(see :ref:`(Evans and Morriss) <Evans3>`), were proven to be
equivalent to Newton's equations of motion for shear flow by
:ref:`(Evans and Morriss) <Evans3>`. They were later shown to generate
the desired velocity gradient and the correct production of work by
stresses for all forms of homogeneous flow by :ref:`(Daivis and Todd)
<Daivis>`. As implemented in LAMMPS, they are coupled to a
Nose/Hoover chain thermostat in a velocity Verlet formulation, closely
following the implementation used for the :doc:`fix nvt <fix_nh>`
command.
.. note::
@ -94,27 +97,28 @@ underscore + "temp", and the group for the new compute is the same as
the fix group.
Note that this is NOT the compute used by thermodynamic output (see
the :doc:`thermo_style <thermo_style>` command) with ID = *thermo_temp*.
This means you can change the attributes of this fix's temperature
(e.g. its degrees-of-freedom) via the
:doc:`compute_modify <compute_modify>` command or print this temperature
during thermodynamic output via the :doc:`thermo_style custom <thermo_style>` command using the appropriate compute-ID.
It also means that changing attributes of *thermo_temp* will have no
effect on this fix.
the :doc:`thermo_style <thermo_style>` command) with ID =
*thermo_temp*. This means you can change the attributes of this fix's
temperature (e.g. its degrees-of-freedom) via the :doc:`compute_modify
<compute_modify>` command or print this temperature during
thermodynamic output via the :doc:`thermo_style custom <thermo_style>`
command using the appropriate compute-ID. It also means that changing
attributes of *thermo_temp* will have no effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

25
doc/src/fix_nvt_sphere.rst
View File

@ -86,18 +86,19 @@ It also means that changing attributes of *thermo_temp* will have no
effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

5
doc/src/fix_qeq.rst
View File

@ -230,7 +230,10 @@ These fixes are part of the QEQ package. They are only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
The qeq fixes are not compatible with the GPU and USER-INTEL packages.
These qeq fixes are not compatible with the GPU and USER-INTEL packages.
These qeq fixes will ignore electric field contributions from
:doc:`fix efield <fix_efield>`.
Related commands
""""""""""""""""

6
doc/src/fix_qeq_reaxff.rst
View File

@ -116,6 +116,12 @@ This fix does not correctly handle interactions involving multiple
periodic images of the same atom. Hence, it should not be used for
periodic cell dimensions less than 10 angstroms.
This fix may be used in combination with :doc:`fix efield <fix_efield>`
and will apply the external electric field during charge equilibration,
but there may be only one fix efield instance used, it may only use a
constant electric field, and the electric field vector may only have
components in non-periodic directions.
Related commands
""""""""""""""""

11
doc/src/fix_reaxff_species.rst
View File

@ -56,6 +56,17 @@ number of molecules of each species. In this context, "species" means
a unique molecule. The chemical formula of each species is given in
the first line.
.. warning::
In order to compute averaged data, it is required that there are no
neighbor list rebuilds between the *Nfreq* steps. For that reason, fix
*reaxff/species* may change your neighbor list settings. There will
be a warning message showing the new settings. Having an *Nfreq*
setting that is larger than what is required for correct computation
of the ReaxFF force field interactions can thus lead to incorrect
results. For typical ReaxFF calculations a value of 100 is already
quite large.
If the filename ends with ".gz", the output file is written in gzipped
format. A gzipped dump file will be about 3x smaller than the text version,
but will also take longer to write.

5
doc/src/fix_saed_vtk.rst
View File

@ -28,7 +28,6 @@ Syntax
Nstart = start averaging on this timestep
*file* arg = filename
filename = name of file to output time averages to
*overwrite* arg = none = overwrite output file with only latest output
Examples
""""""""
@ -161,10 +160,6 @@ the *file* keyword and this string is appended with _N.vtk where N is
an index (0,1,2...) to account for situations with multiple diffraction
intensity outputs.
The *overwrite* keyword will continuously overwrite the output file
with the latest output, so that it only contains one timestep worth of
output. This option can only be used with the *ave running* setting.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

23
doc/src/fix_setforce.rst
View File

@ -89,26 +89,13 @@ precession vectors instead of the forces.
----------
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.
.. include:: accel_styles.rst
The region keyword is also supported by Kokkos, but a Kokkos-enabled
region must be used. See the region :doc:`region <region>` command for
more information.
.. note::
These accelerated styles are part of the r Kokkos package. They are
only enabled if LAMMPS was built with that package. See the :doc:`Build package <Build_package>` 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>` page for more
instructions on how to use the accelerated styles effectively.
The region keyword is supported by Kokkos, but a Kokkos-enabled
region must be used. See the region :doc:`region <region>` command for
more information.
----------

25
doc/src/fix_temp_berendsen.rst
View File

@ -102,18 +102,19 @@ It also means that changing attributes of *thermo_temp* will have no
effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

41
doc/src/fix_temp_csvr.rst
View File

@ -110,28 +110,29 @@ during thermodynamic output via the :doc:`thermo_style custom <thermo_style>` co
It also means that changing attributes of *thermo_temp* will have no
effect on this fix.
Like other fixes that perform thermostatting, these fixes can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
An important feature of these thermostats is that they have an
associated effective energy that is a constant of motion.
The effective energy is the total energy (kinetic + potential) plus
the accumulated kinetic energy changes due to the thermostat. The
latter quantity is the global scalar computed by these fixes. This
feature is useful to check the integration of the equations of motion
against discretization errors. In other words, the conservation of
the effective energy can be used to choose an appropriate integration
associated effective energy that is a constant of motion. The
effective energy is the total energy (kinetic + potential) plus the
accumulated kinetic energy changes due to the thermostat. The latter
quantity is the global scalar computed by these fixes. This feature is
useful to check the integration of the equations of motion against
discretization errors. In other words, the conservation of the
effective energy can be used to choose an appropriate integration
:doc:`timestep <timestep>`. This is similar to the usual paradigm of
checking the conservation of the total energy in the microcanonical
ensemble.

26
doc/src/fix_temp_rescale.rst
View File

@ -109,19 +109,19 @@ command using the appropriate compute-ID. It also means that changing
attributes of *thermo_temp* will have no effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is
used to assign a temperature compute to this fix that includes such a
bias term. See the doc pages for individual :doc:`compute commands
<compute>` to determine which ones include a bias. In this case, the
thermostat works in the following manner: the current temperature is
calculated taking the bias into account, bias is removed from each
atom, thermostatting is performed on the remaining thermal degrees of
freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

40
doc/src/fix_tgnh_drude.rst
View File

@ -187,26 +187,32 @@ barostatting.
----------
Like other fixes that perform thermostatting, these fixes can
be used with :doc:`compute commands <compute>` that calculate a
temperature after removing a "bias" from the atom velocities.
This is not done by default, but only if the :doc:`fix_modify <fix_modify>` command
is used to assign a temperature compute to this fix that includes such
a bias term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal DOF, and the bias is added back in.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
.. note::
However, not all temperature compute commands are valid to be used with these fixes.
Precisely, only temperature compute that does not modify the DOF of the group can be used.
E.g. :doc:`compute temp/ramp <compute_temp_ramp>` and :doc:`compute viscosity/cos <compute_viscosity_cos>`
compute the kinetic energy after remove a velocity gradient without affecting the DOF of the group,
then they can be invoked in this way.
In contrast, :doc:`compute temp/partial <compute_temp_partial>` may remove the DOF at one or more dimensions,
therefore it cannot be used with these fixes.
However, not all temperature compute commands are valid to be used
with these fixes. Precisely, only temperature compute that does
not modify the DOF of the group can be used. E.g. :doc:`compute
temp/ramp <compute_temp_ramp>` and :doc:`compute viscosity/cos
<compute_viscosity_cos>` compute the kinetic energy after remove a
velocity gradient without affecting the DOF of the group, then they
can be invoked in this way. In contrast, :doc:`compute
temp/partial <compute_temp_partial>` may remove the DOF at one or
more dimensions, therefore it cannot be used with these fixes.
----------

20
doc/src/improper_harmonic.rst
View File

@ -64,25 +64,7 @@ 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, INTEL, KOKKOS,
OPENMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package
<Build_package>` 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>` page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------

41
doc/src/kspace_style.rst
View File

@ -310,7 +310,7 @@ Forschungszentrum Juelich.
The library is available for download at "http://scafacos.de" or can
be cloned from the git-repository
"git://github.com/scafacos/scafacos.git".
"https://github.com/scafacos/scafacos.git".
In order to use this KSpace style, you must download and build the
ScaFaCoS library, then build LAMMPS with the SCAFACOS package
@ -414,33 +414,26 @@ relative RMS error.
----------
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.
.. include:: accel_styles.rst
More specifically, the *pppm/gpu* style performs charge assignment and
force interpolation calculations on the GPU. These processes are
performed either in single or double precision, depending on whether
the -DFFT_SINGLE setting was specified in your low-level Makefile, as
discussed above. The FFTs themselves are still calculated on the CPU.
If *pppm/gpu* is used with a GPU-enabled pair style, part of the PPPM
calculation can be performed concurrently on the GPU while other
calculations for non-bonded and bonded force calculation are performed
on the CPU.
.. note::
The *pppm/kk* style performs charge assignment and force interpolation
calculations, along with the FFTs themselves, on the GPU or (optionally) threaded
on the CPU when using OpenMP and FFTW3.
For the GPU package, the *pppm/gpu* style performs charge assignment
and force interpolation calculations on the GPU. These processes
are performed either in single or double precision, depending on
whether the -DFFT_SINGLE setting was specified in your low-level
Makefile, as discussed above. The FFTs themselves are still
calculated on the CPU. If *pppm/gpu* is used with a GPU-enabled
pair style, part of the PPPM calculation can be performed
concurrently on the GPU while other calculations for non-bonded and
bonded force calculation are performed on the CPU.
These accelerated styles are part of the GPU, INTEL, KOKKOS,
OPENMP, and OPT packages respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` page for more info.
.. note::
See the :doc:`Speed packages <Speed_packages>` page for more
instructions on how to use the accelerated styles effectively.
For the KOKKOS package, the *pppm/kk* style performs charge
assignment and force interpolation calculations, along with the FFTs
themselves, on the GPU or (optionally) threaded on the CPU when
using OpenMP and FFTW3.
----------

2
doc/src/package.rst
View File

@ -166,7 +166,7 @@ intel", or "package omp" command with default settings.
set, either to default values or to specified settings. I.e. settings
from previous invocations do not persist across multiple invocations.
See the :doc:`Speed packages <Speed_packages>` page for more details
See the :doc:`Accelerator packages <Speed_packages>` page for more details
about using the various accelerator packages for speeding up LAMMPS
simulations.

16
doc/src/pair_agni.rst
View File

@ -67,21 +67,7 @@ and input files are provided in the examples/PACKAGES/agni directory.
----------
Styles with *omp* suffix is 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 style takes
the same arguments and should produce the same results, except for
round-off and precision issues.
The accelerated style is part of the OPENMP. They are only enabled
if LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` page for more info.
You can specify the accelerated style 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>` page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------

33
doc/src/pair_hybrid.rst
View File

@ -383,30 +383,19 @@ coefficients to 0.0.
----------
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. Pair style *hybrid/scaled* does (currently) not support the
*gpu*, *omp*, *kk*, or *intel* suffix.
.. include:: accel_styles.rst
Since the *hybrid*, *hybrid/overlay*, *hybrid/scaled* styles delegate
computation to the individual sub-styles, the suffix versions of the
*hybrid* and *hybrid/overlay* styles are used to propagate the
corresponding suffix to all sub-styles, if those versions
exist. Otherwise the non-accelerated version will be used.
.. note::
The individual accelerated sub-styles are part of the GPU, KOKKOS,
INTEL, OPENMP, and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :doc:`Build
package <Build_package>` 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>` page for more
instructions on how to use the accelerated styles effectively.
Since the *hybrid*, *hybrid/overlay*, *hybrid/scaled* styles
delegate computation to the individual sub-styles, the suffix
versions of the *hybrid* and *hybrid/overlay* styles are used to
propagate the corresponding suffix to all sub-styles, if those
versions exist. Otherwise the non-accelerated version will be used.
The individual accelerated sub-styles are part of the GPU, KOKKOS,
INTEL, OPENMP, and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the
:doc:`Build package <Build_package>` page for more info.
----------

16
doc/src/pair_meam.rst
View File

@ -28,16 +28,16 @@ Description
as of November 2010; see description below of the mixture_ref_t
parameter
Style *meam* computes pairwise interactions for a variety of materials
using modified embedded-atom method (MEAM) potentials
Pair style *meam* computes non-bonded interactions for a variety of materials
using the modified embedded-atom method (MEAM)
:ref:`(Baskes) <Baskes>`. Conceptually, it is an extension to the original
:doc:`EAM potentials <pair_eam>` which adds angular forces. It is
:doc:`EAM method <pair_eam>` which adds angular forces. It is
thus suitable for modeling metals and alloys with fcc, bcc, hcp and
diamond cubic structures, as well as covalently bonded materials like
silicon and carbon. Style *meam* is a translation of the (now obsolete)
*meam* code from Fortran to C++. It is functionally equivalent to *meam*
but more efficient, and thus *meam* has been removed from LAMMPS after
the 12 December 2018 release.
diamond cubic structures, as well as materials with covalent interactions
like silicon and carbon. This *meam* pair style is a translation of the
original Fortran version to C++. It is functionally equivalent but more
efficient and has additional features. The Fortran version of the *meam*
pair style has been removed from LAMMPS after the 12 December 2018 release.
In the MEAM formulation, the total energy E of a system of atoms is
given by:

11
doc/src/pair_reaxff.rst
View File

@ -20,7 +20,7 @@ Syntax
.. parsed-literal::
keyword = *checkqeq* or *lgvdw* or *safezone* or *mincap* or *minhbonds*
*checkqeq* value = *yes* or *no* = whether or not to require qeq/reaxff fix
*checkqeq* value = *yes* or *no* = whether or not to require qeq/reaxff or acks2/reaxff fix
*enobonds* value = *yes* or *no* = whether or not to tally energy of atoms with no bonds
*lgvdw* value = *yes* or *no* = whether or not to use a low gradient vdW correction
*safezone* = factor used for array allocation
@ -119,7 +119,8 @@ The ReaxFF parameter files provided were created using a charge
equilibration (QEq) model for handling the electrostatic interactions.
Therefore, by default, LAMMPS requires that either the
:doc:`fix qeq/reaxff <fix_qeq_reaxff>` or the
:doc:`fix qeq/shielded <fix_qeq>` command be used with
:doc:`fix qeq/shielded <fix_qeq>` or :doc:`fix acks2/reaxff <fix_acks2_reaxff>`
command be used with
*pair_style reaxff* when simulating a ReaxFF model, to equilibrate
the charges each timestep.
@ -128,7 +129,8 @@ for the QEq fixes, allowing a simulation to be run without charge
equilibration. In this case, the static charges you assign to each
atom will be used for computing the electrostatic interactions in
the system. See the :doc:`fix qeq/reaxff <fix_qeq_reaxff>` or
:doc:`fix qeq/shielded <fix_qeq>` command documentation for more details.
:doc:`fix qeq/shielded <fix_qeq>` or :doc:`fix acks2/reaxff <fix_acks2_reaxff>`
command documentation for more details.
Using the optional keyword *lgvdw* with the value *yes* turns on the
low-gradient correction of ReaxFF for long-range London Dispersion,
@ -352,7 +354,8 @@ Related commands
""""""""""""""""
:doc:`pair_coeff <pair_coeff>`, :doc:`fix qeq/reaxff <fix_qeq_reaxff>`,
:doc:`fix reaxff/bonds <fix_reaxff_bonds>`, :doc:`fix reaxff/species <fix_reaxff_species>`
:doc:`fix acks2/reaxff <fix_acks2_reaxff>`, :doc:`fix reaxff/bonds <fix_reaxff_bonds>`,
:doc:`fix reaxff/species <fix_reaxff_species>`
Default
"""""""

26
doc/src/pair_sw.rst
View File

@ -159,28 +159,14 @@ taken from the ij and ik pairs (:math:`\sigma`, *a*, :math:`\gamma`)
----------
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.
.. include:: accel_styles.rst
These accelerated styles are part of the GPU, INTEL, KOKKOS,
OPENMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` page for more info.
.. note::
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.
When using the INTEL package with this style, there is an
additional 5 to 10 percent performance improvement when the
Stillinger-Weber parameters p and q are set to 4 and 0 respectively.
These parameters are common for modeling silicon and water.
See the :doc:`Speed packages <Speed_packages>` page for more
instructions on how to use the accelerated styles effectively.
When using the INTEL package with this style, there is an additional
5 to 10 percent performance improvement when the Stillinger-Weber
parameters p and q are set to 4 and 0 respectively. These
parameters are common for modeling silicon and water.
----------

6
doc/src/plugin.rst
View File

@ -65,10 +65,8 @@ only enabled if LAMMPS was built with that package.
See the :doc:`Build package <Build_package>` page for
more info. Plugins are not available on Windows.
For the loading of plugins to work the LAMMPS library must be
:ref:`compiled as a shared library <library>`. If plugins
access functions or classes from a package, LAMMPS must have
been compiled with that package included.
If plugins access functions or classes from a package, LAMMPS must
have been compiled with that package included.
Plugins are dependent on the LAMMPS binary interface (ABI)
and particularly the MPI library used. So they are not guaranteed

4
doc/src/read_data.rst
View File

@ -254,7 +254,9 @@ the fix defines the syntax of the header line(s) and section that it
reads from the data file. Note that the *header-string* can be
specified as NULL, in which case no header lines are passed to the
fix. This means the fix can infer the length of its Section from
standard header settings, such as the number of atoms.
standard header settings, such as the number of atoms. Also the
*section-string* may be specified as NULL, and in that case the fix
ID is used as section name.
The formatting of individual lines in the data file (indentation,
spacing between words and numbers) is not important except that header

23
doc/src/region.rst
View File

@ -371,26 +371,13 @@ sub-regions can be defined with the *open* keyword.
----------
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.
.. include:: accel_styles.rst
The code using the region (such as a fix or compute) must also be supported
by Kokkos or no acceleration will occur. Currently, only *block* style
regions are supported by Kokkos.
.. note::
These accelerated styles are part of the Kokkos package. They are
only enabled if LAMMPS was built with that package. See the :doc:`Build package <Build_package>` 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>` page for more
instructions on how to use the accelerated styles effectively.
Currently, only *block* style regions are supported by Kokkos. The
code using the region (such as a fix or compute) must also be
supported by Kokkos or no acceleration will occur.
----------

22
doc/src/run_style.rst
View File

@ -125,12 +125,13 @@ screen.0 by default; see the :doc:`-plog and -pscreen command-line switches <Run
for the second partition will not contain thermodynamic output beyond the
first timestep of the run.
See the :doc:`Speed packages <Speed_packages>` page for performance
details of the speed-up offered by the *verlet/split* style. One
important performance consideration is the assignment of logical
processors in the 2 partitions to the physical cores of a parallel
machine. The :doc:`processors <processors>` command has options to
support this, and strategies are discussed in :doc:`Section 5 <Speed>` of the manual.
See the :doc:`Accelerator packages <Speed_packages>` page for
performance details of the speed-up offered by the *verlet/split*
style. One important performance consideration is the assignment of
logical processors in the 2 partitions to the physical cores of a
parallel machine. The :doc:`processors <processors>` command has
options to support this, and strategies are discussed in :doc:`Section
5 <Speed>` of the manual.
----------
@ -295,10 +296,10 @@ except for round-off and precision issues.
You can specify *respa/omp* explicitly in your input script, 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.
invoke LAMMPS, or you can use the :doc:`suffix <suffix>` command in
your input script.
See the :doc:`Speed packages <Speed_packages>` page for more
See the :doc:`Accelerator packages <Speed_packages>` page for more
instructions on how to use the accelerated styles effectively.
----------
@ -308,7 +309,8 @@ Restrictions
The *verlet/split* style can only be used if LAMMPS was built with the
REPLICA package. Correspondingly the *respa/omp* style is available
only if the OPENMP package was included. See the :doc:`Build package <Build_package>` page for more info.
only if the OPENMP package was included. See the :doc:`Build package
<Build_package>` page for more info.
Whenever using rRESPA, the user should experiment with trade-offs in
speed and accuracy for their system, and verify that they are

4
doc/utils/check-styles.py
View File

@ -254,7 +254,7 @@ for command_type, entries in index.items():
print("Total number of style index entries:", total_index)
skip_fix = ('python', 'NEIGH_HISTORY/omp','qeq/reax','reax/c/bonds','reax/c/species')
skip_fix = ('python', 'NEIGH_HISTORY/omp','acks2/reax','qeq/reax','reax/c/bonds','reax/c/species')
skip_pair = ('meam/c','lj/sf','reax/c')
counter = 0
@ -282,7 +282,7 @@ if counter:
counter = 0
counter += check_style_index("compute", compute, index["compute"])
counter += check_style_index("fix", fix, index["fix"], skip=['python','qeq/reax','reax/c/bonds','reax/c/species'])
counter += check_style_index("fix", fix, index["fix"], skip=['python','acks2/reax','qeq/reax','reax/c/bonds','reax/c/species'])
counter += check_style_index("angle_style", angle, index["angle_style"])
counter += check_style_index("bond_style", bond, index["bond_style"])
counter += check_style_index("dihedral_style", dihedral, index["dihedral_style"])

14
doc/utils/requirements.txt
View File

@ -1,7 +1,7 @@
Sphinx==4.0.3
sphinxcontrib-spelling==7.2.1
git+git://github.com/akohlmey/sphinx-fortran@parallel-read
sphinx_tabs==3.2.0
breathe==4.31.0
Pygments==2.10.0
six==1.16.0
Sphinx
sphinxcontrib-spelling
git+https://github.com/akohlmey/sphinx-fortran@parallel-read
sphinx_tabs
breathe
Pygments
six

16
doc/utils/sphinx-config/false_positives.txt
View File

@ -19,6 +19,7 @@ accuracies
ach
ackland
Ackland
acks
acolor
acos
Acta
@ -77,6 +78,7 @@ allocators
allosws
AlO
Alonso
Alperen
alphak
alphashrink
amap
@ -685,6 +687,7 @@ diagonalized
diagonalizers
diagonalizing
Diallo
diblock
Dickel
diel
differentiable
@ -1135,6 +1138,7 @@ Germann
Germano
gerolf
Gerolf
getrusage
Gershgorin
getter
gettimeofday
@ -1222,6 +1226,7 @@ Guo
gw
gyromagnetic
gz
gzip
gzipped
Haak
Hafskjold
@ -1252,6 +1257,7 @@ hbond
hcp
hdnnp
HDNNP
Hearn
heatconduction
Hebbeker
Hebenstreit
@ -1278,6 +1284,7 @@ hgrid
hhmrr
Hibbs
Higdon
hiID
Hijazi
Hilger
Hinestrosa
@ -1774,6 +1781,7 @@ Loewen
logfile
logfreq
logicals
loID
Lomdahl
Lond
lookup
@ -1809,6 +1817,7 @@ lyon
Lysogorskiy
Lyulin
lz
lzma
Maaravi
MACHDYN
machdyn
@ -1986,6 +1995,7 @@ minimizer
minimizers
minneigh
minorder
MinSizeRel
minSteps
mintcream
Mintmire
@ -2762,6 +2772,7 @@ REAXFF
ReaxFF
reaxff
rebo
recurse
recursing
Ree
refactored
@ -2774,6 +2785,7 @@ relink
relres
relTol
relu
RelWithDebInfo
remappings
remd
Ren
@ -3076,6 +3088,7 @@ Spearot
specular
spellcheck
Spellmeyer
Speybroeck
sph
SPH
Spickermann
@ -3441,6 +3454,7 @@ usec
uSemiParallel
userguide
username
usleep
usr
util
utils
@ -3488,6 +3502,7 @@ Verlag
verlet
Verlet
versa
Verstraelen
ves
vflag
vhi
@ -3554,6 +3569,7 @@ vzcm
vzi
Waals
Wadley
Waroquier
wallstyle
walltime
Waltham

0
examples/MC/README → examples/MC-LOOP/README
View File

0
examples/MC/in.mc → examples/MC-LOOP/in.mc
View File

0
examples/MC/log.13Oct16.mc.g++.1 → examples/MC-LOOP/log.13Oct16.mc.g++.1
View File

4
examples/README
View File

@ -75,7 +75,6 @@ eim: NaCl using the EIM potential
ellipse: ellipsoidal particles in spherical solvent, 2d system
flow: Couette and Poiseuille flow in a 2d channel
friction: frictional contact of spherical asperities between 2d surfaces
gcmc: Grand Canonical MC with fix gcmc, Widom insertion with fix widom
gjf: use of fix langevin Gronbech-Jensen/Farago option
granregion: use of fix wall/region/gran as boundary on granular particles
hugoniostat: Hugoniostat shock dynamics
@ -83,6 +82,7 @@ hyper: global and local hyperdynamics of diffusion on Pt surface
indent: spherical indenter into a 2d solid
kim: use of potentials in Knowledge Base for Interatomic Models (KIM)
latte: use of LATTE density-functional tight-binding quantum code
mc: MC package models: GCMC, Widom, fix mol/swap
meam: MEAM test for SiC and shear (same as shear examples)
melt: rapid melt of 3d LJ system
message: client/server coupling of 2 codes
@ -167,7 +167,7 @@ The KAPPA directory has example scripts for computing the thermal
conductivity (kappa) of a LJ liquid using 5 different methods. See
the KAPPA/README file for more info.
The MC directory has an example script for using LAMMPS as an
The MC-LOOP directory has an example script for using LAMMPS as an
energy-evaluation engine in a iterative Monte Carlo energy-relaxation
loop.

0
examples/gcmc/CO2.txt → examples/mc/CO2.txt
View File

0
examples/gcmc/H2O.txt → examples/mc/H2O.txt
View File

11733
examples/mc/data.bead Normal file
View File

File diff suppressed because it is too large Load Diff

0
examples/gcmc/data.spce → examples/mc/data.spce
View File

0
examples/gcmc/data.widom.lj → examples/mc/data.widom.lj
View File

0
examples/gcmc/in.gcmc.co2 → examples/mc/in.gcmc.co2
View File

0
examples/gcmc/in.gcmc.h2o → examples/mc/in.gcmc.h2o
View File

0
examples/gcmc/in.gcmc.lj → examples/mc/in.gcmc.lj
View File

44
examples/mc/in.mixed Normal file
View File

@ -0,0 +1,44 @@
# test script for fix mol/swap
# initial system is 50/50 chains of type 1 and type 2
# b/c epsilon12 is set to 1.02 (weakly same as 1/1 or 1/2) the
# system will stay in equilibrium as a mix of both chain types
# fix mol/swap helps this happen quickly
# see the last 2 columns of thermo output for counts of 2 chain types
units lj
atom_style angle
neighbor 0.36 bin
neigh_modify delay 0
pair_style lj/cut 1.1224620483
bond_style fene
angle_style cosine
special_bonds lj 0.0 1.0 1.0
read_data data.bead
pair_coeff * * 1.0 1.0 1.1224620483
pair_coeff 1 2 1.02 1.0 1.1224620483
bond_coeff 1 30.0 1.5 1.0 1.0
angle_coeff 1 1.500
pair_modify shift yes
variable vt1 atom type==1
variable vt2 atom type==2
group g1 dynamic all var vt1 every 100
group g2 dynamic all var vt2 every 100
variable count1 equal count(g1)
variable count2 equal count(g2)
timestep 0.010
fix 1 all langevin 1.0 1.0 100.0 702547
fix 2 all nve
fix 3 all mol/swap 100 1 1 2 482794 1.0
compute p all pressure thermo_temp
thermo 1000
thermo_style custom step temp etotal press f_3[1] f_3[2] v_count1 v_count2
run 50000

44
examples/mc/in.pure Normal file
View File

@ -0,0 +1,44 @@
# test script for fix mol/swap
# initial system is 50/50 chains of type 1 and type 2
# b/c epsilon12 is set to 1.1 (stronger than 1/1 or 2/2) the
# system will go to equilibrium as mostly one type or the other
# fix mol/swap helps this happen quickly
# see the last 2 columns of thermo output for counts of 2 chain types
units lj
atom_style angle
neighbor 0.36 bin
neigh_modify delay 0
pair_style lj/cut 1.1224620483
bond_style fene
angle_style cosine
special_bonds lj 0.0 1.0 1.0
read_data data.bead
pair_coeff * * 1.0 1.0 1.1224620483
pair_coeff 1 2 1.1 1.0 1.1224620483
bond_coeff 1 30.0 1.5 1.0 1.0
angle_coeff 1 1.500
pair_modify shift yes
variable vt1 atom type==1
variable vt2 atom type==2
group g1 dynamic all var vt1 every 100
group g2 dynamic all var vt2 every 100
variable count1 equal count(g1)
variable count2 equal count(g2)
timestep 0.010
fix 1 all langevin 1.0 1.0 100.0 702547
fix 2 all nve
fix 3 all mol/swap 100 1 1 2 482794 1.0
compute p all pressure thermo_temp
thermo 1000
thermo_style custom step temp etotal press f_3[1] f_3[2] v_count1 v_count2
run 50000

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