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

Merge branch 'develop' into gran-temp

Browse Source
This commit is contained in:
jtclemm
2023-01-10 09:58:50 -07:00
parent 531912a3c8 b3396f109b
commit f175a15627
1738 changed files with 304144 additions and 98116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.github/CODEOWNERS vendored
View File

@ -37,6 +37,7 @@ src/MESONT/* @iafoss
src/ML-HDNNP/* @singraber
src/ML-IAP/* @athomps
src/ML-PACE/* @yury-lysogorskiy
src/ML-POD/* @exapde @rohskopf
src/MOFFF/* @hheenen
src/MOLFILE/* @akohlmey
src/NETCDF/* @pastewka
@ -63,6 +64,8 @@ src/MANYBODY/pair_atm.* @sergeylishchuk
src/REPLICA/*_grem.* @dstelter92
src/EXTRA-COMPUTE/compute_stress_mop*.* @RomainVermorel
src/MISC/*_tracker.* @jtclemm
src/MC/fix_gcmc.* @athomps
src/MC/fix_sgcmc.* @athomps
# core LAMMPS classes
src/lammps.* @sjplimp

2
.github/workflows/compile-msvc.yml vendored
View File

@ -54,4 +54,4 @@ jobs:
- name: Run Unit Tests
working-directory: build
shell: bash
run: ctest -V -C Release
run: ctest -V -C Release -E FixTimestep:python_move_nve

67
cmake/CMakeLists.txt
View File

@ -3,6 +3,7 @@
# This file is part of LAMMPS
# Created by Christoph Junghans and Richard Berger
cmake_minimum_required(VERSION 3.10)
########################################
# set policy to silence warnings about ignoring <PackageName>_ROOT but use it
if(POLICY CMP0074)
cmake_policy(SET CMP0074 NEW)
@ -20,7 +21,13 @@ endif()
if(POLICY CMP0135)
cmake_policy(SET CMP0135 OLD)
endif()
########################################
# Use CONFIGURE_DEPENDS as option for file(GLOB...) when available
if(CMAKE_VERSION VERSION_LESS 3.12)
unset(CONFIGURE_DEPENDS)
else()
set(CONFIGURE_DEPENDS CONFIGURE_DEPENDS)
endif()
########################################
project(lammps CXX)
@ -195,8 +202,8 @@ else()
endif()
include(GNUInstallDirs)
file(GLOB ALL_SOURCES ${LAMMPS_SOURCE_DIR}/[^.]*.cpp)
file(GLOB MAIN_SOURCES ${LAMMPS_SOURCE_DIR}/main.cpp)
file(GLOB ALL_SOURCES ${CONFIGURE_DEPENDS} ${LAMMPS_SOURCE_DIR}/[^.]*.cpp)
file(GLOB MAIN_SOURCES ${CONFIGURE_DEPENDS} ${LAMMPS_SOURCE_DIR}/main.cpp)
list(REMOVE_ITEM ALL_SOURCES ${MAIN_SOURCES})
add_library(lammps ${ALL_SOURCES})
@ -251,13 +258,13 @@ set(STANDARD_PACKAGES
KSPACE
LATBOLTZ
LATTE
LEPTON
MACHDYN
MANIFOLD
MANYBODY
MC
MDI
MEAM
MESONT
MGPT
MISC
ML-HDNNP
@ -266,6 +273,7 @@ set(STANDARD_PACKAGES
ML-QUIP
ML-RANN
ML-SNAP
ML-POD
MOFFF
MOLECULE
MOLFILE
@ -300,8 +308,9 @@ set(STANDARD_PACKAGES
YAFF)
set(SUFFIX_PACKAGES CORESHELL GPU KOKKOS OPT INTEL OPENMP)
set(EXTRA_PACKAGES MESONT)
foreach(PKG ${STANDARD_PACKAGES} ${SUFFIX_PACKAGES})
foreach(PKG ${STANDARD_PACKAGES} ${EXTRA_PACKAGES} ${SUFFIX_PACKAGES})
option(PKG_${PKG} "Build ${PKG} Package" OFF)
endforeach()
@ -432,23 +441,19 @@ if(BUILD_OMP)
target_link_libraries(lmp PRIVATE OpenMP::OpenMP_CXX)
endif()
if(PKG_MSCG OR PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_LATTE OR PKG_ELECTRODE)
if(PKG_MSCG OR PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_ML-POD OR PKG_LATTE OR PKG_ELECTRODE)
enable_language(C)
if (NOT USE_INTERNAL_LINALG)
find_package(LAPACK)
find_package(BLAS)
endif()
if(NOT LAPACK_FOUND OR NOT BLAS_FOUND OR USE_INTERNAL_LINALG)
include(CheckGeneratorSupport)
if(NOT CMAKE_GENERATOR_SUPPORT_FORTRAN)
status(FATAL_ERROR "Cannot build internal linear algebra library as CMake build tool lacks Fortran support")
endif()
enable_language(Fortran)
file(GLOB LAPACK_SOURCES ${LAMMPS_LIB_SOURCE_DIR}/linalg/[^.]*.[fF])
add_library(linalg STATIC ${LAPACK_SOURCES})
file(GLOB LINALG_SOURCES ${CONFIGURE_DEPENDS} ${LAMMPS_LIB_SOURCE_DIR}/linalg/[^.]*.cpp)
add_library(linalg STATIC ${LINALG_SOURCES})
set_target_properties(linalg PROPERTIES OUTPUT_NAME lammps_linalg${LAMMPS_MACHINE})
set(BLAS_LIBRARIES "$<TARGET_FILE:linalg>")
set(LAPACK_LIBRARIES "$<TARGET_FILE:linalg>")
target_link_libraries(lammps PRIVATE linalg)
else()
list(APPEND LAPACK_LIBRARIES ${BLAS_LIBRARIES})
endif()
@ -515,8 +520,8 @@ else()
set(CUDA_REQUEST_PIC)
endif()
foreach(PKG_WITH_INCL KSPACE PYTHON ML-IAP VORONOI COLVARS ML-HDNNP MDI MOLFILE NETCDF
PLUMED QMMM ML-QUIP SCAFACOS MACHDYN VTK KIM LATTE MSCG COMPRESS ML-PACE)
foreach(PKG_WITH_INCL KSPACE PYTHON ML-IAP VORONOI COLVARS ML-HDNNP MDI MOLFILE MESONT NETCDF
PLUMED QMMM ML-QUIP SCAFACOS MACHDYN VTK KIM LATTE MSCG COMPRESS ML-PACE LEPTON)
if(PKG_${PKG_WITH_INCL})
include(Packages/${PKG_WITH_INCL})
endif()
@ -561,7 +566,7 @@ RegisterStyles(${LAMMPS_SOURCE_DIR})
########################################################
# Fetch missing external files and archives for packages
########################################################
foreach(PKG ${STANDARD_PACKAGES} ${SUFFIX_PACKAGES})
foreach(PKG ${STANDARD_PACKAGES} ${EXTRA_PACKAGES} ${SUFFIX_PACKAGES})
if(PKG_${PKG})
FetchPotentials(${LAMMPS_SOURCE_DIR}/${PKG} ${LAMMPS_POTENTIALS_DIR})
endif()
@ -573,8 +578,8 @@ endforeach()
foreach(PKG ${STANDARD_PACKAGES})
set(${PKG}_SOURCES_DIR ${LAMMPS_SOURCE_DIR}/${PKG})
file(GLOB ${PKG}_SOURCES ${${PKG}_SOURCES_DIR}/[^.]*.cpp)
file(GLOB ${PKG}_HEADERS ${${PKG}_SOURCES_DIR}/[^.]*.h)
file(GLOB ${PKG}_SOURCES ${CONFIGURE_DEPENDS} ${${PKG}_SOURCES_DIR}/[^.]*.cpp)
file(GLOB ${PKG}_HEADERS ${CONFIGURE_DEPENDS} ${${PKG}_SOURCES_DIR}/[^.]*.h)
# check for package files in src directory due to old make system
DetectBuildSystemConflict(${LAMMPS_SOURCE_DIR} ${${PKG}_SOURCES} ${${PKG}_HEADERS})
@ -601,8 +606,8 @@ endforeach()
foreach(PKG ${SUFFIX_PACKAGES})
set(${PKG}_SOURCES_DIR ${LAMMPS_SOURCE_DIR}/${PKG})
file(GLOB ${PKG}_SOURCES ${${PKG}_SOURCES_DIR}/[^.]*.cpp)
file(GLOB ${PKG}_HEADERS ${${PKG}_SOURCES_DIR}/[^.]*.h)
file(GLOB ${PKG}_SOURCES ${CONFIGURE_DEPENDS} ${${PKG}_SOURCES_DIR}/[^.]*.cpp)
file(GLOB ${PKG}_HEADERS ${CONFIGURE_DEPENDS} ${${PKG}_SOURCES_DIR}/[^.]*.h)
# check for package files in src directory due to old make system
DetectBuildSystemConflict(${LAMMPS_SOURCE_DIR} ${${PKG}_SOURCES} ${${PKG}_HEADERS})
@ -613,18 +618,11 @@ endforeach()
##############################################
# add lib sources of (simple) enabled packages
############################################
foreach(PKG_LIB POEMS ATC AWPMD H5MD MESONT)
foreach(PKG_LIB POEMS ATC AWPMD H5MD)
if(PKG_${PKG_LIB})
string(TOLOWER "${PKG_LIB}" PKG_LIB)
if(PKG_LIB STREQUAL "mesont")
enable_language(Fortran)
file(GLOB_RECURSE ${PKG_LIB}_SOURCES
${LAMMPS_LIB_SOURCE_DIR}/${PKG_LIB}/[^.]*.f90)
else()
file(GLOB_RECURSE ${PKG_LIB}_SOURCES
${LAMMPS_LIB_SOURCE_DIR}/${PKG_LIB}/[^.]*.c
${LAMMPS_LIB_SOURCE_DIR}/${PKG_LIB}/[^.]*.cpp)
endif()
file(GLOB_RECURSE ${PKG_LIB}_SOURCES ${CONFIGURE_DEPENDS}
${LAMMPS_LIB_SOURCE_DIR}/${PKG_LIB}/[^.]*.c ${LAMMPS_LIB_SOURCE_DIR}/${PKG_LIB}/[^.]*.cpp)
add_library(${PKG_LIB} STATIC ${${PKG_LIB}_SOURCES})
set_target_properties(${PKG_LIB} PROPERTIES OUTPUT_NAME lammps_${PKG_LIB}${LAMMPS_MACHINE})
target_link_libraries(lammps PRIVATE ${PKG_LIB})
@ -638,7 +636,7 @@ foreach(PKG_LIB POEMS ATC AWPMD H5MD MESONT)
endif()
endforeach()
if(PKG_ELECTRODE)
if(PKG_ELECTRODE OR PKG_ML-POD)
target_link_libraries(lammps PRIVATE ${LAPACK_LIBRARIES})
endif()
@ -667,7 +665,7 @@ endif()
# packages which selectively include variants based on enabled styles
# e.g. accelerator packages
######################################################################
foreach(PKG_WITH_INCL CORESHELL DPD-SMOOTH MISC PHONON QEQ OPENMP KOKKOS OPT INTEL GPU)
foreach(PKG_WITH_INCL CORESHELL DPD-SMOOTH MC MISC PHONON QEQ OPENMP KOKKOS OPT INTEL GPU)
if(PKG_${PKG_WITH_INCL})
include(Packages/${PKG_WITH_INCL})
endif()
@ -708,7 +706,7 @@ target_include_directories(lammps PRIVATE ${LAMMPS_STYLE_HEADERS_DIR})
######################################
set(temp "#ifndef LMP_INSTALLED_PKGS_H\n#define LMP_INSTALLED_PKGS_H\n")
set(temp "${temp}const char * LAMMPS_NS::LAMMPS::installed_packages[] = {\n")
set(temp_PKG_LIST ${STANDARD_PACKAGES} ${SUFFIX_PACKAGES})
set(temp_PKG_LIST ${STANDARD_PACKAGES} ${EXTRA_PACKAGES} ${SUFFIX_PACKAGES})
list(SORT temp_PKG_LIST)
foreach(PKG ${temp_PKG_LIST})
if(PKG_${PKG})
@ -904,6 +902,7 @@ feature_summary(DESCRIPTION "The following tools and libraries have been found a
message(STATUS "<<< Build configuration >>>
LAMMPS Version: ${PROJECT_VERSION}
Operating System: ${CMAKE_SYSTEM_NAME} ${CMAKE_LINUX_DISTRO} ${CMAKE_DISTRO_VERSION}
CMake Version: ${CMAKE_VERSION}
Build type: ${LAMMPS_BUILD_TYPE}
Install path: ${CMAKE_INSTALL_PREFIX}
Generator: ${CMAKE_GENERATOR} using ${CMAKE_MAKE_PROGRAM}")
@ -911,7 +910,7 @@ message(STATUS "<<< Build configuration >>>
# Print package summary
###############################################################################
set(ENABLED_PACKAGES)
foreach(PKG ${STANDARD_PACKAGES} ${SUFFIX_PACKAGES})
foreach(PKG ${STANDARD_PACKAGES} ${EXTRA_PACKAGES} ${SUFFIX_PACKAGES})
if(PKG_${PKG})
list(APPEND ENABLED_PACKAGES ${PKG})
endif()

6
cmake/CMakeSettings.json
View File

@ -72,7 +72,7 @@
"configurationType": "Debug",
"buildRoot": "${workspaceRoot}\\build\\${name}",
"installRoot": "${workspaceRoot}\\install\\${name}",
"cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DCMAKE_C_COMPILER=clang-cl.exe -DCMAKE_CXX_COMPILER=clang-cl.exe",
"cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DCMAKE_C_COMPILER=clang-cl.exe -DCMAKE_CXX_COMPILER=clang-cl.exe -DBUILD_MPI=off",
"buildCommandArgs": "",
"ctestCommandArgs": "",
"inheritEnvironments": [ "clang_cl_x64" ],
@ -105,7 +105,7 @@
"configurationType": "Release",
"buildRoot": "${workspaceRoot}\\build\\${name}",
"installRoot": "${workspaceRoot}\\install\\${name}",
"cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DCMAKE_C_COMPILER=clang-cl.exe -DCMAKE_CXX_COMPILER=clang-cl.exe",
"cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DCMAKE_C_COMPILER=clang-cl.exe -DCMAKE_CXX_COMPILER=clang-cl.exe -DBUILD_MPI=off",
"buildCommandArgs": "",
"ctestCommandArgs": "-V",
"inheritEnvironments": [ "clang_cl_x64" ],
@ -305,4 +305,4 @@
]
}
]
}
}

4
cmake/Modules/Documentation.cmake
View File

@ -17,7 +17,7 @@ if(BUILD_DOC)
endif()
find_package(Doxygen 1.8.10 REQUIRED)
file(GLOB DOC_SOURCES ${LAMMPS_DOC_DIR}/src/[^.]*.rst)
file(GLOB DOC_SOURCES ${CONFIGURE_DEPENDS} ${LAMMPS_DOC_DIR}/src/[^.]*.rst)
add_custom_command(
@ -65,7 +65,7 @@ if(BUILD_DOC)
"${CMAKE_CURRENT_BINARY_DIR}/mathjax.tar.gz"
EXPECTED_MD5 ${MATHJAX_MD5})
execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf mathjax.tar.gz WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
file(GLOB MATHJAX_VERSION_DIR ${CMAKE_CURRENT_BINARY_DIR}/MathJax-*)
file(GLOB MATHJAX_VERSION_DIR ${CONFIGURE_DEPENDS} ${CMAKE_CURRENT_BINARY_DIR}/MathJax-*)
execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${DOC_BUILD_STATIC_DIR}/mathjax)
endif()

2
cmake/Modules/LAMMPSInterfacePlugin.cmake
View File

@ -65,7 +65,7 @@ endfunction(validate_option)
# helper function for getting the most recently modified file or folder from a glob pattern
function(get_newest_file path variable)
file(GLOB _dirs ${path})
file(GLOB _dirs ${CONFIGURE_DEPENDS} ${path})
set(_besttime 2000-01-01T00:00:00)
set(_bestfile "<unknown>")
foreach(_dir ${_dirs})

8
cmake/Modules/LAMMPSUtils.cmake
View File

@ -41,7 +41,7 @@ endfunction()
# helper function for getting the most recently modified file or folder from a glob pattern
function(get_newest_file path variable)
file(GLOB _dirs ${path})
file(GLOB _dirs ${CONFIGURE_DEPENDS} ${path})
set(_besttime 2000-01-01T00:00:00)
set(_bestfile "<unknown>")
foreach(_dir ${_dirs})
@ -80,8 +80,8 @@ endfunction()
function(check_for_autogen_files source_dir)
message(STATUS "Running check for auto-generated files from make-based build system")
file(GLOB SRC_AUTOGEN_FILES ${source_dir}/style_*.h)
file(GLOB SRC_AUTOGEN_PACKAGES ${source_dir}/packages_*.h)
file(GLOB SRC_AUTOGEN_FILES ${CONFIGURE_DEPENDS} ${source_dir}/style_*.h)
file(GLOB SRC_AUTOGEN_PACKAGES ${CONFIGURE_DEPENDS} ${source_dir}/packages_*.h)
list(APPEND SRC_AUTOGEN_FILES ${SRC_AUTOGEN_PACKAGES} ${source_dir}/lmpinstalledpkgs.h ${source_dir}/lmpgitversion.h)
list(APPEND SRC_AUTOGEN_FILES ${SRC_AUTOGEN_PACKAGES} ${source_dir}/mliap_model_python_couple.h ${source_dir}/mliap_model_python_couple.cpp)
foreach(_SRC ${SRC_AUTOGEN_FILES})
@ -100,7 +100,7 @@ endfunction()
macro(pkg_depends PKG1 PKG2)
if(PKG_${PKG1} AND NOT (PKG_${PKG2} OR BUILD_${PKG2}))
message(FATAL_ERROR "The ${PKG1} package needs LAMMPS to be build with the ${PKG2} package")
message(FATAL_ERROR "The ${PKG1} package needs LAMMPS to be built with the ${PKG2} package")
endif()
endmacro()

24
cmake/Modules/Packages/COLVARS.cmake
View File

@ -1,20 +1,15 @@
set(COLVARS_SOURCE_DIR ${LAMMPS_LIB_SOURCE_DIR}/colvars)
file(GLOB COLVARS_SOURCES ${COLVARS_SOURCE_DIR}/[^.]*.cpp)
file(GLOB COLVARS_SOURCES ${CONFIGURE_DEPENDS} ${COLVARS_SOURCE_DIR}/[^.]*.cpp)
option(COLVARS_DEBUG "Debugging messages for Colvars (quite verbose)" OFF)
option(COLVARS_DEBUG "Enable debugging messages for Colvars (quite verbose)" OFF)
# Build Lepton by default
option(COLVARS_LEPTON "Build and link the Lepton library" ON)
option(COLVARS_LEPTON "Use the Lepton library for custom expressions" ON)
if(COLVARS_LEPTON)
set(LEPTON_DIR ${LAMMPS_LIB_SOURCE_DIR}/colvars/lepton)
file(GLOB LEPTON_SOURCES ${LEPTON_DIR}/src/[^.]*.cpp)
add_library(lepton STATIC ${LEPTON_SOURCES})
# Change the define below to LEPTON_BUILDING_SHARED_LIBRARY when linking Lepton as a DLL with MSVC
target_compile_definitions(lepton PRIVATE -DLEPTON_BUILDING_STATIC_LIBRARY)
set_target_properties(lepton PROPERTIES OUTPUT_NAME lammps_lepton${LAMMPS_MACHINE})
target_include_directories(lepton PRIVATE ${LEPTON_DIR}/include)
if(NOT LEPTON_SOURCE_DIR)
include(Packages/LEPTON)
endif()
endif()
add_library(colvars STATIC ${COLVARS_SOURCES})
@ -30,14 +25,11 @@ target_include_directories(colvars PRIVATE ${LAMMPS_SOURCE_DIR})
target_link_libraries(lammps PRIVATE colvars)
if(COLVARS_DEBUG)
# Need to export the macro publicly to also affect the proxy
# Need to export the define publicly to be valid in interface code
target_compile_definitions(colvars PUBLIC -DCOLVARS_DEBUG)
endif()
if(COLVARS_LEPTON)
target_link_libraries(lammps PRIVATE lepton)
target_compile_definitions(colvars PRIVATE -DLEPTON)
# Disable the line below when linking Lepton as a DLL with MSVC
target_compile_definitions(colvars PRIVATE -DLEPTON_USE_STATIC_LIBRARIES)
target_include_directories(colvars PUBLIC ${LEPTON_DIR}/include)
target_link_libraries(colvars PUBLIC lepton)
endif()

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

@ -26,7 +26,7 @@ elseif(GPU_PREC STREQUAL "SINGLE")
set(GPU_PREC_SETTING "SINGLE_SINGLE")
endif()
file(GLOB GPU_LIB_SOURCES ${LAMMPS_LIB_SOURCE_DIR}/gpu/[^.]*.cpp)
file(GLOB GPU_LIB_SOURCES ${CONFIGURE_DEPENDS} ${LAMMPS_LIB_SOURCE_DIR}/gpu/[^.]*.cpp)
file(MAKE_DIRECTORY ${LAMMPS_LIB_BINARY_DIR}/gpu)
if(GPU_API STREQUAL "CUDA")
@ -55,7 +55,7 @@ if(GPU_API STREQUAL "CUDA")
set(GPU_ARCH "sm_50" CACHE STRING "LAMMPS GPU CUDA SM primary architecture (e.g. sm_60)")
# ensure that no *cubin.h files exist from a compile in the lib/gpu folder
file(GLOB GPU_LIB_OLD_CUBIN_HEADERS ${LAMMPS_LIB_SOURCE_DIR}/gpu/*_cubin.h)
file(GLOB GPU_LIB_OLD_CUBIN_HEADERS ${CONFIGURE_DEPENDS} ${LAMMPS_LIB_SOURCE_DIR}/gpu/*_cubin.h)
if(GPU_LIB_OLD_CUBIN_HEADERS)
message(FATAL_ERROR "########################################################################\n"
"Found file(s) generated by the make-based build system in lib/gpu\n"
@ -65,15 +65,15 @@ if(GPU_API STREQUAL "CUDA")
"########################################################################")
endif()
file(GLOB GPU_LIB_CU ${LAMMPS_LIB_SOURCE_DIR}/gpu/[^.]*.cu ${CMAKE_CURRENT_SOURCE_DIR}/gpu/[^.]*.cu)
file(GLOB GPU_LIB_CU ${CONFIGURE_DEPENDS} ${LAMMPS_LIB_SOURCE_DIR}/gpu/[^.]*.cu ${CMAKE_CURRENT_SOURCE_DIR}/gpu/[^.]*.cu)
list(REMOVE_ITEM GPU_LIB_CU ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_pppm.cu)
cuda_include_directories(${LAMMPS_LIB_SOURCE_DIR}/gpu ${LAMMPS_LIB_BINARY_DIR}/gpu)
if(CUDPP_OPT)
cuda_include_directories(${LAMMPS_LIB_SOURCE_DIR}/gpu/cudpp_mini)
file(GLOB GPU_LIB_CUDPP_SOURCES ${LAMMPS_LIB_SOURCE_DIR}/gpu/cudpp_mini/[^.]*.cpp)
file(GLOB GPU_LIB_CUDPP_CU ${LAMMPS_LIB_SOURCE_DIR}/gpu/cudpp_mini/[^.]*.cu)
file(GLOB GPU_LIB_CUDPP_SOURCES ${CONFIGURE_DEPENDS} ${LAMMPS_LIB_SOURCE_DIR}/gpu/cudpp_mini/[^.]*.cpp)
file(GLOB GPU_LIB_CUDPP_CU ${CONFIGURE_DEPENDS} ${LAMMPS_LIB_SOURCE_DIR}/gpu/cudpp_mini/[^.]*.cu)
endif()
# build arch/gencode commands for nvcc based on CUDA toolkit version and use choice
@ -82,6 +82,7 @@ if(GPU_API STREQUAL "CUDA")
# apply the following to build "fat" CUDA binaries only for known CUDA toolkits since version 8.0
# only the Kepler achitecture and beyond is supported
# comparison chart according to: https://en.wikipedia.org/wiki/CUDA#GPUs_supported
if(CUDA_VERSION VERSION_LESS 8.0)
message(FATAL_ERROR "CUDA Toolkit version 8.0 or later is required")
elseif(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
@ -120,14 +121,14 @@ if(GPU_API STREQUAL "CUDA")
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.1")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_86,code=[sm_86,compute_86]")
endif()
# Hopper (GPU Arch 9.0) is supported by CUDA 12.0? and later
# Lovelace (GPU Arch 8.9) is supported by CUDA 11.8 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.8")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_90,code=[sm_90,compute_90]")
endif()
# Hopper (GPU Arch 9.0) is supported by CUDA 12.0 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_90,code=[sm_90,compute_90]")
endif()
# # Lovelace (GPU Arch 9.x) is supported by CUDA 12.0? and later
#if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
# string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_9x,code=[sm_9x,compute_9x]")
#endif()
endif()
cuda_compile_fatbin(GPU_GEN_OBJS ${GPU_LIB_CU} OPTIONS ${CUDA_REQUEST_PIC}
@ -182,7 +183,7 @@ elseif(GPU_API STREQUAL "OPENCL")
include(OpenCLUtils)
set(OCL_COMMON_HEADERS ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_preprocessor.h ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_aux_fun1.h)
file(GLOB GPU_LIB_CU ${LAMMPS_LIB_SOURCE_DIR}/gpu/[^.]*.cu)
file(GLOB GPU_LIB_CU ${CONFIGURE_DEPENDS} ${LAMMPS_LIB_SOURCE_DIR}/gpu/[^.]*.cu)
list(REMOVE_ITEM GPU_LIB_CU
${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_gayberne.cu
${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_gayberne_lj.cu
@ -276,6 +277,7 @@ elseif(GPU_API STREQUAL "HIP")
else()
# build arch/gencode commands for nvcc based on CUDA toolkit version and use choice
# --arch translates directly instead of JIT, so this should be for the preferred or most common architecture
# comparison chart according to: https://en.wikipedia.org/wiki/CUDA#GPUs_supported
set(HIP_CUDA_GENCODE "-arch=${HIP_ARCH}")
# Kepler (GPU Arch 3.0) is supported by CUDA 5 to CUDA 10.2
if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "11.0"))
@ -305,14 +307,22 @@ elseif(GPU_API STREQUAL "HIP")
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.0")
string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_80,code=[sm_80,compute_80]")
endif()
# Hopper (GPU Arch 9.0) is supported by CUDA 12.0? and later
# Ampere (GPU Arch 8.6) is supported by CUDA 11.1 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.1")
string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_86,code=[sm_86,compute_86]")
endif()
# Lovelace (GPU Arch 8.9) is supported by CUDA 11.8 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.8")
string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_90,code=[sm_90,compute_90]")
endif()
# Hopper (GPU Arch 9.0) is supported by CUDA 12.0 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_90,code=[sm_90,compute_90]")
string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_90,code=[sm_90,compute_90]")
endif()
endif()
endif()
file(GLOB GPU_LIB_CU ${LAMMPS_LIB_SOURCE_DIR}/gpu/[^.]*.cu ${CMAKE_CURRENT_SOURCE_DIR}/gpu/[^.]*.cu)
file(GLOB GPU_LIB_CU ${CONFIGURE_DEPENDS} ${LAMMPS_LIB_SOURCE_DIR}/gpu/[^.]*.cu ${CMAKE_CURRENT_SOURCE_DIR}/gpu/[^.]*.cu)
list(REMOVE_ITEM GPU_LIB_CU ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_pppm.cu)
set(GPU_LIB_CU_HIP "")

4
cmake/Modules/Packages/INTEL.cmake
View File

@ -112,9 +112,5 @@ if(PKG_KSPACE)
RegisterIntegrateStyle(${INTEL_SOURCES_DIR}/verlet_lrt_intel.h)
endif()
if(PKG_ELECTRODE)
list(APPEND INTEL_SOURCES ${INTEL_SOURCES_DIR}/electrode_accel_intel.cpp)
endif()
target_sources(lammps PRIVATE ${INTEL_SOURCES})
target_include_directories(lammps PRIVATE ${INTEL_SOURCES_DIR})

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

@ -3,6 +3,7 @@
if(CMAKE_CXX_STANDARD LESS 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
if(Kokkos_ENABLE_CUDA)
@ -89,7 +90,6 @@ else()
endif()
add_subdirectory(${LAMMPS_LIB_KOKKOS_SRC_DIR} ${LAMMPS_LIB_KOKKOS_BIN_DIR})
set(Kokkos_INCLUDE_DIRS ${LAMMPS_LIB_KOKKOS_SRC_DIR}/core/src
${LAMMPS_LIB_KOKKOS_SRC_DIR}/containers/src
${LAMMPS_LIB_KOKKOS_SRC_DIR}/algorithms/src
@ -124,7 +124,7 @@ set(KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/kokkos.cpp
if(PKG_KSPACE)
list(APPEND KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/fft3d_kokkos.cpp
${KOKKOS_PKG_SOURCES_DIR}/gridcomm_kokkos.cpp
${KOKKOS_PKG_SOURCES_DIR}/grid3d_kokkos.cpp
${KOKKOS_PKG_SOURCES_DIR}/remap_kokkos.cpp)
if(Kokkos_ENABLE_CUDA)
if(NOT (FFT STREQUAL "KISS"))
@ -143,7 +143,23 @@ if(PKG_ML-IAP)
list(APPEND KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/mliap_data_kokkos.cpp
${KOKKOS_PKG_SOURCES_DIR}/mliap_descriptor_so3_kokkos.cpp
${KOKKOS_PKG_SOURCES_DIR}/mliap_model_linear_kokkos.cpp
${KOKKOS_PKG_SOURCES_DIR}/mliap_model_python_kokkos.cpp
${KOKKOS_PKG_SOURCES_DIR}/mliap_so3_kokkos.cpp)
# Add KOKKOS version of ML-IAP Python coupling if non-KOKKOS version is included
if(MLIAP_ENABLE_PYTHON AND Cythonize_EXECUTABLE)
file(GLOB MLIAP_KOKKOS_CYTHON_SRC ${CONFIGURE_DEPENDS} ${LAMMPS_SOURCE_DIR}/KOKKOS/*.pyx)
foreach(MLIAP_CYTHON_FILE ${MLIAP_KOKKOS_CYTHON_SRC})
get_filename_component(MLIAP_CYTHON_BASE ${MLIAP_CYTHON_FILE} NAME_WE)
add_custom_command(OUTPUT ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.cpp ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.h
COMMAND ${CMAKE_COMMAND} -E copy_if_different ${MLIAP_CYTHON_FILE} ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.pyx
COMMAND ${Cythonize_EXECUTABLE} -3 ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.pyx
WORKING_DIRECTORY ${MLIAP_BINARY_DIR}
MAIN_DEPENDENCY ${MLIAP_CYTHON_FILE}
COMMENT "Generating C++ sources with cythonize...")
list(APPEND KOKKOS_PKG_SOURCES ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.cpp)
endforeach()
endif()
endif()
if(PKG_PHONON)

35
cmake/Modules/Packages/LEPTON.cmake Normal file
View File

@ -0,0 +1,35 @@
# avoid including this file twice
if(LEPTON_SOURCE_DIR)
return()
endif()
set(LEPTON_SOURCE_DIR ${LAMMPS_LIB_SOURCE_DIR}/lepton)
file(GLOB LEPTON_SOURCES ${LEPTON_SOURCE_DIR}/src/[^.]*.cpp)
if((CMAKE_HOST_SYSTEM_PROCESSOR STREQUAL "amd64") OR
(CMAKE_HOST_SYSTEM_PROCESSOR STREQUAL "AMD64") OR
(CMAKE_HOST_SYSTEM_PROCESSOR STREQUAL "x86_64"))
option(LEPTON_ENABLE_JIT "Enable Just-In-Time compiler for Lepton" ON)
else()
option(LEPTON_ENABLE_JIT "Enable Just-In-Time compiler for Lepton" OFF)
endif()
if(LEPTON_ENABLE_JIT)
file(GLOB ASMJIT_SOURCES ${LEPTON_SOURCE_DIR}/asmjit/*/[^.]*.cpp)
endif()
add_library(lepton STATIC ${LEPTON_SOURCES} ${ASMJIT_SOURCES})
set_target_properties(lepton PROPERTIES OUTPUT_NAME lammps_lepton${LAMMPS_MACHINE})
target_compile_definitions(lepton PUBLIC LEPTON_BUILDING_STATIC_LIBRARY=1)
target_include_directories(lepton PUBLIC ${LEPTON_SOURCE_DIR}/include)
if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
find_library(LIB_RT rt QUIET)
target_link_libraries(lepton PUBLIC ${LIB_RT})
endif()
if(LEPTON_ENABLE_JIT)
target_compile_definitions(lepton PUBLIC "LEPTON_USE_JIT=1;ASMJIT_BUILD_X86=1;ASMJIT_STATIC=1;ASMJIT_BUILD_RELEASE=1")
target_include_directories(lepton PUBLIC ${LEPTON_SOURCE_DIR})
endif()
target_link_libraries(lammps PRIVATE lepton)

9
cmake/Modules/Packages/MC.cmake Normal file
View File

@ -0,0 +1,9 @@
# fix sgcmc may only be installed if also the EAM pair style from MANYBODY is installed
if(NOT PKG_MANYBODY)
get_property(LAMMPS_FIX_HEADERS GLOBAL PROPERTY FIX)
list(REMOVE_ITEM LAMMPS_FIX_HEADERS ${LAMMPS_SOURCE_DIR}/MC/fix_sgcmc.h)
set_property(GLOBAL PROPERTY FIX "${LAMMPS_FIX_HEADERS}")
get_target_property(LAMMPS_SOURCES lammps SOURCES)
list(REMOVE_ITEM LAMMPS_SOURCES ${LAMMPS_SOURCE_DIR}/MC/fix_sgcmc.cpp)
set_property(TARGET lammps PROPERTY SOURCES "${LAMMPS_SOURCES}")
endif()

73
cmake/Modules/Packages/MESONT.cmake Normal file
View File

@ -0,0 +1,73 @@
set(MESONT_SOURCES_DIR ${LAMMPS_SOURCE_DIR}/MESONT)
include(StyleHeaderUtils)
include(CheckLanguage)
# always include C++-only sources
file(GLOB MESONT_SOURCES ${CONFIGURE_DEPENDS} ${MESONT_SOURCES_DIR}/[^.]*mesocnt*.cpp)
file(GLOB MESONT_HEADERS ${CONFIGURE_DEPENDS} ${MESONT_SOURCES_DIR}/[^.]*mesocnt*.h)
# remove derived class when base class is not available
if(NOT PKG_MOLECULE)
list(REMOVE_ITEM MESONT_SOURCES ${MESONT_SOURCES_DIR}/bond_mesocnt.cpp)
list(REMOVE_ITEM MESONT_HEADERS ${MESONT_SOURCES_DIR}/bond_mesocnt.h)
endif()
# include styles dependent on Fortran library only when Fortran is available.
check_language(Fortran)
if(CMAKE_Fortran_COMPILER)
enable_language(Fortran)
file(GLOB MESONT_LIB_SOURCES ${CONFIGURE_DEPENDS} ${LAMMPS_LIB_SOURCE_DIR}/mesont/[^.]*.f90)
add_library(mesont STATIC ${MESONT_LIB_SOURCES})
set_target_properties(mesont PROPERTIES OUTPUT_NAME lammps_mesont${LAMMPS_MACHINE})
target_link_libraries(lammps PRIVATE mesont)
list(APPEND MESONT_SOURCES ${MESONT_SOURCES_DIR}/pair_mesont_tpm.cpp)
list(APPEND MESONT_SOURCES ${MESONT_SOURCES_DIR}/atom_vec_mesont.cpp)
list(APPEND MESONT_SOURCES ${MESONT_SOURCES_DIR}/compute_mesont.cpp)
list(APPEND MESONT_HEADERS ${MESONT_SOURCES_DIR}/pair_mesont_tpm.h)
list(APPEND MESONT_HEADERS ${MESONT_SOURCES_DIR}/atom_vec_mesont.h)
list(APPEND MESONT_HEADERS ${MESONT_SOURCES_DIR}/compute_mesont.h)
endif()
# check for package files in src directory due to old make system
DetectBuildSystemConflict(${LAMMPS_SOURCE_DIR} ${MESONT_SOURCES} ${MESONT_HEADERS})
# manually register style headers
get_property(alist GLOBAL PROPERTY ANGLE)
get_property(blist GLOBAL PROPERTY BOND)
get_property(clist GLOBAL PROPERTY COMPUTE)
get_property(plist GLOBAL PROPERTY PAIR)
get_property(vlist GLOBAL PROPERTY ATOM_VEC)
foreach(fname ${MESONT_HEADERS})
file(STRINGS ${fname} is_style LIMIT_COUNT 1 REGEX ANGLE_CLASS)
if(is_style)
list(APPEND alist ${fname})
endif()
file(STRINGS ${fname} is_style LIMIT_COUNT 1 REGEX BOND_CLASS)
if(is_style)
list(APPEND blist ${fname})
endif()
file(STRINGS ${fname} is_style LIMIT_COUNT 1 REGEX COMPUTE_CLASS)
if(is_style)
list(APPEND clist ${fname})
endif()
file(STRINGS ${fname} is_style LIMIT_COUNT 1 REGEX PAIR_CLASS)
if(is_style)
list(APPEND plist ${fname})
endif()
file(STRINGS ${fname} is_style LIMIT_COUNT 1 REGEX ATOM_CLASS)
if(is_style)
list(APPEND vlist ${fname})
endif()
endforeach()
set_property(GLOBAL PROPERTY ANGLE "${alist}")
set_property(GLOBAL PROPERTY BOND "${blist}")
set_property(GLOBAL PROPERTY COMPUTE "${clist}")
set_property(GLOBAL PROPERTY PAIR "${plist}")
set_property(GLOBAL PROPERTY ATOM_VEC "${vlist}")
target_sources(lammps PRIVATE ${MESONT_SOURCES})
target_include_directories(lammps PRIVATE ${MESONT_SOURCES_DIR})
RegisterPackages(${MESONT_SOURCES_DIR})

2
cmake/Modules/Packages/ML-IAP.cmake
View File

@ -34,7 +34,7 @@ if(MLIAP_ENABLE_PYTHON)
endif()
set(MLIAP_BINARY_DIR ${CMAKE_BINARY_DIR}/cython)
file(GLOB MLIAP_CYTHON_SRC ${LAMMPS_SOURCE_DIR}/ML-IAP/*.pyx)
file(GLOB MLIAP_CYTHON_SRC ${CONFIGURE_DEPENDS} ${LAMMPS_SOURCE_DIR}/ML-IAP/*.pyx)
file(MAKE_DIRECTORY ${MLIAP_BINARY_DIR})
foreach(MLIAP_CYTHON_FILE ${MLIAP_CYTHON_SRC})
get_filename_component(MLIAP_CYTHON_BASE ${MLIAP_CYTHON_FILE} NAME_WE)

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

@ -1,6 +1,6 @@
set(PACELIB_URL "https://github.com/ICAMS/lammps-user-pace/archive/refs/tags/v.2022.10.15.tar.gz" CACHE STRING "URL for PACE evaluator library sources")
set(PACELIB_URL "https://github.com/ICAMS/lammps-user-pace/archive/refs/tags/v.2023.01.3.tar.gz" CACHE STRING "URL for PACE evaluator library sources")
set(PACELIB_MD5 "848ad6a6cc79fa82745927001fb1c9b5" CACHE STRING "MD5 checksum of PACE evaluator library tarball")
set(PACELIB_MD5 "f418d32b60e531063ac4285bf702b468" CACHE STRING "MD5 checksum of PACE evaluator library tarball")
mark_as_advanced(PACELIB_URL)
mark_as_advanced(PACELIB_MD5)

4
cmake/Modules/StyleHeaderUtils.cmake
View File

@ -1,5 +1,5 @@
function(FindStyleHeaders path style_class file_pattern headers)
file(GLOB files "${path}/${file_pattern}*.h")
file(GLOB files ${CONFIGURE_DEPENDS} "${path}/${file_pattern}*.h")
get_property(hlist GLOBAL PROPERTY ${headers})
foreach(file_name ${files})
@ -187,7 +187,7 @@ endfunction(DetectBuildSystemConflict)
function(FindPackagesHeaders path style_class file_pattern headers)
file(GLOB files "${path}/${file_pattern}*.h")
file(GLOB files ${CONFIGURE_DEPENDS} "${path}/${file_pattern}*.h")
get_property(plist GLOBAL PROPERTY ${headers})
foreach(file_name ${files})

2
cmake/Modules/Testing.cmake
View File

@ -6,7 +6,7 @@ if(ENABLE_TESTING)
find_program(VALGRIND_BINARY NAMES valgrind)
# generate custom suppression file
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/lammps.supp "\n")
file(GLOB VALGRIND_SUPPRESSION_FILES ${LAMMPS_TOOLS_DIR}/valgrind/[^.]*.supp)
file(GLOB VALGRIND_SUPPRESSION_FILES ${CONFIGURE_DEPENDS} ${LAMMPS_TOOLS_DIR}/valgrind/[^.]*.supp)
foreach(SUPP ${VALGRIND_SUPPRESSION_FILES})
file(READ ${SUPP} SUPPRESSIONS)
file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/lammps.supp "${SUPPRESSIONS}")

2
cmake/Modules/Tools.cmake
View File

@ -26,7 +26,7 @@ if(BUILD_TOOLS)
enable_language(C)
get_filename_component(MSI2LMP_SOURCE_DIR ${LAMMPS_TOOLS_DIR}/msi2lmp/src ABSOLUTE)
file(GLOB MSI2LMP_SOURCES ${MSI2LMP_SOURCE_DIR}/[^.]*.c)
file(GLOB MSI2LMP_SOURCES ${CONFIGURE_DEPENDS} ${MSI2LMP_SOURCE_DIR}/[^.]*.c)
add_executable(msi2lmp ${MSI2LMP_SOURCES})
if(STANDARD_MATH_LIB)
target_link_libraries(msi2lmp PRIVATE ${STANDARD_MATH_LIB})

2
cmake/presets/all_off.cmake
View File

@ -44,6 +44,7 @@ set(ALL_PACKAGES
KSPACE
LATBOLTZ
LATTE
LEPTON
MACHDYN
MANIFOLD
MANYBODY
@ -56,6 +57,7 @@ set(ALL_PACKAGES
ML-HDNNP
ML-IAP
ML-PACE
ML-POD
ML-QUIP
ML-RANN
ML-SNAP

2
cmake/presets/all_on.cmake
View File

@ -46,6 +46,7 @@ set(ALL_PACKAGES
KSPACE
LATBOLTZ
LATTE
LEPTON
MACHDYN
MANIFOLD
MANYBODY
@ -58,6 +59,7 @@ set(ALL_PACKAGES
ML-HDNNP
ML-IAP
ML-PACE
ML-POD
ML-QUIP
ML-RANN
ML-SNAP

2
cmake/presets/mingw-cross.cmake
View File

@ -36,6 +36,7 @@ set(WIN_PACKAGES
INTERLAYER
KSPACE
LATTE
LEPTON
MACHDYN
MANIFOLD
MANYBODY
@ -47,6 +48,7 @@ set(WIN_PACKAGES
MISC
ML-HDNNP
ML-IAP
ML-POD
ML-RANN
ML-SNAP
MOFFF

2
cmake/presets/most.cmake
View File

@ -35,12 +35,14 @@ set(ALL_PACKAGES
GRANULAR
INTERLAYER
KSPACE
LEPTON
MACHDYN
MANYBODY
MC
MEAM
MISC
ML-IAP
ML-POD
ML-SNAP
MOFFF
MOLECULE

1
cmake/presets/nolib.cmake
View File

@ -13,6 +13,7 @@ set(PACKAGES_WITH_LIB
KOKKOS
LATBOLTZ
LATTE
LEPTON
MACHDYN
MDI
MESONT

4
cmake/presets/windows.cmake
View File

@ -1,6 +1,7 @@
set(WIN_PACKAGES
AMOEBA
ASPHERE
AWPMD
BOCS
BODY
BPM
@ -20,6 +21,7 @@ set(WIN_PACKAGES
DPD-SMOOTH
DRUDE
EFF
ELECTRODE
EXTRA-COMPUTE
EXTRA-DUMP
EXTRA-FIX
@ -29,12 +31,14 @@ set(WIN_PACKAGES
GRANULAR
INTERLAYER
KSPACE
LEPTON
MANIFOLD
MANYBODY
MC
MEAM
MISC
ML-IAP
ML-POD
ML-SNAP
MOFFF
MOLECULE

7
doc/Makefile
View File

@ -45,7 +45,7 @@ SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocess
# we only want to use explicitly listed files.
DOXYFILES = $(shell sed -n -e 's/\#.*$$//' -e '/^ *INPUT \+=/,/^[A-Z_]\+ \+=/p' doxygen/Doxyfile.in | sed -e 's/@LAMMPS_SOURCE_DIR@/..\/src/g' -e 's/\\//g' -e 's/ \+/ /' -e 's/[A-Z_]\+ \+= *\(YES\|NO\|\)//')
.PHONY: help clean-all clean clean-spelling epub mobi html pdf spelling anchor_check style_check char_check xmlgen fasthtml
.PHONY: help clean-all clean clean-spelling epub mobi html pdf spelling anchor_check style_check char_check role_check xmlgen fasthtml
# ------------------------------------------
@ -96,6 +96,7 @@ html: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
rst_anchor_check src/*.rst ;\
python $(BUILDDIR)/utils/check-packages.py -s ../src -d src ;\
env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\
env LC_ALL=C grep -n ' :[a-z]\+`' $(RSTDIR)/*.rst ;\
python $(BUILDDIR)/utils/check-styles.py -s ../src -d src ;\
echo "############################################" ;\
deactivate ;\
@ -175,6 +176,7 @@ pdf: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK)
rst_anchor_check src/*.rst ;\
python utils/check-packages.py -s ../src -d src ;\
env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\
env LC_ALL=C grep -n ' :[a-z]\+`' $(RSTDIR)/*.rst ;\
python utils/check-styles.py -s ../src -d src ;\
echo "############################################" ;\
deactivate ;\
@ -220,6 +222,9 @@ package_check : $(VENV)
char_check :
@( env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst && exit 1 || : )
role_check :
@( env LC_ALL=C grep -n ' :[a-z]\+`' $(RSTDIR)/*.rst && exit 1 || : )
xmlgen : doxygen/xml/index.xml
doxygen/Doxyfile: doxygen/Doxyfile.in

5
doc/README
View File

@ -40,8 +40,9 @@ environment and local folders.
Installing prerequisites for the documentation build
To run the HTML documention build toolchain, python 3.x, doxygen, git,
and virtualenv have to be installed. Also internet access is initially
required to download external files and tools.
and the venv python module have to be installed if not already available.
Also internet access is initially required to download external files
and tools.
Building the PDF format manual requires in addition a compatible LaTeX
installation with support for PDFLaTeX and several add-on LaTeX packages

113
doc/documentation_conventions.md
View File

@ -4,45 +4,44 @@ This purpose of this document is to provide a point of reference
for LAMMPS developers and contributors as to what conventions
should be used to structure and format files in the LAMMPS manual.
Last change: 2020-04-23
Last change: 2022-12-30
## File format and tools
In fall 2019, the LAMMPS documentation file format has changed from
a home grown minimal markup designed to generate HTML format files
from a mostly plain text format to using the reStructuredText file
format. For a transition period all files in the old .txt format
were transparently converted to .rst and then processed. The txt2rst
tool is still included in the distribution to obtain an initial .rst
file for integration into the manual. Since the transition to
reStructured text as source format, many of the artifacts or the
translation have been removed though and parts of the documentation
refactored and expanded to take advantage of the capabilities
reStructuredText and associated tools. The conversion from the
source to the final formats (HTML, PDF, and optionally e-book
reader formats ePUB and MOBI) is mostly automated and controlled
by a Makefile in the `doc` folder. This makefile assumes that the
processing is done on a Unix-like machine and Python 3.5 or later
and a matching virtualenv module are available. Additional Python
packages (like the Sphinx tool and several extensions) are
transparently installed into a virtual environment over the
internet using the `pip` package manager. Further requirements
and details are discussed in the manual.
In fall 2019, the LAMMPS documentation file format has changed from a
home grown markup designed to generate HTML format files only, to
[reStructuredText](https://docutils.sourceforge.io/rst.html>. For a
transition period all files in the old .txt format were transparently
converted to .rst and then processed. The `txt2rst tool` is still
included in the distribution to obtain an initial .rst file for legacy
integration into the manual. Since that transition to reStructured
text, many of the artifacts of the translation have been removed though,
and parts of the documentation refactored and expanded to take advantage
of the capabilities reStructuredText and associated tools. The
conversion from the source to the final formats (HTML, PDF, and
optionally e-book reader formats ePUB and MOBI) is mostly automated and
controlled by a Makefile in the `doc` folder. This makefile assumes that
the processing is done on a Unix-like machine and Python 3.5 or later
and a matching venv module are available. Additional Python
packages (like the Sphinx tool and several extensions) are transparently
installed into a virtual environment over the internet using the `pip`
package manager. Further requirements and details are discussed in the
manual.
## Work in progress
The refactoring and improving of the documentation is an ongoing
process, so statements in this document may not always be fully
up-to-date. If in doubt, contact the LAMMPS developers.
up-to-date. When in doubt, contact the LAMMPS developers.
## General structure
The layout and formatting of added files should follow the example
of the existing files. Since those are directly derived from their
former .txt format versions and the manual has been maintained in
The layout and formatting of added files should follow the example of
the existing files. Since many of those were initially derived from
their former .txt format versions and the manual has been maintained in
that format for many years, there is a large degree of consistency
already, so comparison with similar files should give you a good
idea what kind of information and sections are needed.
already, so comparison with similar files should give you a good idea
what kind of information and sections are needed.
## Formatting conventions
@ -52,21 +51,27 @@ It seems to be sufficient to have this consistent only within
any single file and it is not (yet) enforced strictly, but making
this globally consistent makes it easier to move sections around.
Filenames, folders, paths, (shell) commands, definitions, makefile
File names, folders, paths, (shell) commands, definitions, makefile
settings and similar should be formatted as "literals" with
double backward quotes bracketing the item: \`\`path/to/some/file\`\`
Keywords and options are formatted in italics: \*option\*
Mathematical expressions, equations, symbols are typeset using
either a `.. math:`` block or the `:math:` role.
either a `.. math:` block or the `:math:` role.
Groups of shell commands or LAMMPS input script or C/C++ source
Groups of shell commands or LAMMPS input script or C/C++/Python source
code should be typeset into a `.. code-block::` section. A syntax
highlighting extension for LAMMPS input scripts is provided, so
`LAMMPS` can be used to indicate the language in the code block
in addition to `bash`, `c`, or `python`. When no syntax style
is indicated, no syntax highlighting is performed.
highlighting extension for LAMMPS input scripts is provided, so `LAMMPS`
can be used to indicate the language in the code block in addition to
`bash`, `c`, `c++`, `console`, `csh`, `diff', `fortran`, `json`, `make`,
`perl`, `powershell`, `python`, `sh`, or `tcl`, `text`, or `yaml`. When
no syntax style is indicated, no syntax highlighting is performed. When
typesetting commands executed on the shell, please do not prefix
commands with a shell prompt and use `bash` highlighting, except when
the block also shows the output from that command. In the latter case,
please use a dollar sign as the shell prompt and `console` for syntax
highlighting.
As an alternative, e.g. to typeset the syntax of file formats
a `.. parsed-literal::` block can be used, which allows some
@ -89,22 +94,30 @@ by ` :class: note`.
## Required steps when adding a custom style to LAMMPS
When adding a new style (e.g. pair style or a compute or a fix)
or a new command, it is **required** to include the corresponding
documentation. Those are often new files that need to be added.
In order to be included in the documentation, those new files
need to be reference in a `.. toctree::` block. Most of those
use patterns with wildcards, so the addition will be automatic.
However, those additions also need to be added to some lists of
styles or commands. The `make style\_check` command will perform
a test and report any missing entries and list the affected files.
Any references defined with `.. \_refname:` have to be unique
across all documentation files and this can be checked for with
`make anchor\_check`. Finally, a spell-check should be done,
which is triggered via `make spelling`. Any offenses need to
be corrected and false positives should be added to the file
`utils/sphinx-config/false\_positives.txt`.
When adding a new style (e.g. pair style or a compute or a fix) or a new
command, it is **required** to include the **corresponding documentation**
in [reStructuredText format](https://docutils.sourceforge.io/rst.html).
Those are often new files that need to be added. In order to be
included in the documentation, those new files need to be referenced in a
`.. toctree::` block. Most of those use patterns with wild cards, so the
addition will be automatic. However, those additions also need to be
added to some lists of styles or commands. The `make style\_check`
command when executed in the `doc` folder will perform a test and report
any missing entries and list the affected files. Any references defined
with `.. \_refname:` have to be unique across all documentation files
and this can be checked for with `make anchor\_check`. Finally, a
spell-check should be done, which is triggered via `make spelling`. Any
offenses need to be corrected and false positives should be added to the
file `utils/sphinx-config/false\_positives.txt`.
## Required additional steps when adding a new package to LAMMPS
TODO
When adding a new package, the package must be added to the list of
packages in the `Packages_list.rst` file. If additional build instructions
need to be followed, a corresponding section should be added to the
`Build_extras.rst` file and linked from the list at the top of the
file as well as the equivalent list in the `Build_packages.rst` file.
A detailed description of the package and pointers to configuration,
included commands and examples, external pages, author information and
more should be added to the `Packages_details.rst` file.

4
doc/lammps.1
View File

@ -1,7 +1,7 @@
.TH LAMMPS "1" "3 November 2022" "2022-11-3"
.TH LAMMPS "1" "22 December 2022" "2022-12-22"
.SH NAME
.B LAMMPS
\- Molecular Dynamics Simulator. Version 3 November 2022
\- Molecular Dynamics Simulator. Version 22 December 2022
.SH SYNOPSIS
.B lmp

4
doc/src/Build_basics.rst
View File

@ -276,7 +276,7 @@ LAMMPS.
Parallel build (see ``src/MAKE/Makefile.mpi``):
.. code-block:: bash
.. code-block:: make
CC = mpicxx
CCFLAGS = -g -O3
@ -296,7 +296,7 @@ LAMMPS.
If compilation stops with a message like the following:
.. code-block::
.. code-block:: output
g++ -g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I../STUBS -c ../main.cpp
In file included from ../pointers.h:24:0,

82
doc/src/Build_development.rst
View File

@ -154,32 +154,48 @@ for implementing the tests.
framework are more strict than for the main part of LAMMPS. For
example the default GNU C++ and Fortran compilers of RHEL/CentOS 7.x
(version 4.8.x) are not sufficient. The CMake configuration will try
to detect compatible versions and either skip incompatible tests or
stop with an error.
to detect incompatible versions and either skip incompatible tests or
stop with an error. Also the number of tests will depend on
installed LAMMPS packages, development environment, operating system,
and configuration settings.
After compilation is complete, the unit testing is started in the build
folder using the ``ctest`` command, which is part of the CMake software.
The output of this command will be looking something like this::
The output of this command will be looking something like this:
[...]$ ctest
Test project /home/akohlmey/compile/lammps/build-testing
Start 1: MolPairStyle:hybrid-overlay
1/109 Test #1: MolPairStyle:hybrid-overlay ......... Passed 0.02 sec
Start 2: MolPairStyle:hybrid
2/109 Test #2: MolPairStyle:hybrid ................. Passed 0.01 sec
Start 3: MolPairStyle:lj_class2
[...]
Start 107: PotentialFileReader
107/109 Test #107: PotentialFileReader ................ Passed 0.04 sec
Start 108: EIMPotentialFileReader
108/109 Test #108: EIMPotentialFileReader ............. Passed 0.03 sec
Start 109: TestSimpleCommands
109/109 Test #109: TestSimpleCommands ................. Passed 0.02 sec
.. code-block:: console
100% tests passed, 0 tests failed out of 26
$ ctest
Test project /home/akohlmey/compile/lammps/build-testing
Start 1: RunLammps
1/563 Test #1: RunLammps .......................................... Passed 0.28 sec
Start 2: HelpMessage
2/563 Test #2: HelpMessage ........................................ Passed 0.06 sec
Start 3: InvalidFlag
3/563 Test #3: InvalidFlag ........................................ Passed 0.06 sec
Start 4: Tokenizer
4/563 Test #4: Tokenizer .......................................... Passed 0.05 sec
Start 5: MemPool
5/563 Test #5: MemPool ............................................ Passed 0.05 sec
Start 6: ArgUtils
6/563 Test #6: ArgUtils ........................................... Passed 0.05 sec
[...]
Start 561: ImproperStyle:zero
561/563 Test #561: ImproperStyle:zero ................................. Passed 0.07 sec
Start 562: TestMliapPyUnified
562/563 Test #562: TestMliapPyUnified ................................. Passed 0.16 sec
Start 563: TestPairList
563/563 Test #563: TestPairList ....................................... Passed 0.06 sec
Total Test time (real) = 25.57 sec
100% tests passed, 0 tests failed out of 563
Label Time Summary:
generated = 0.85 sec*proc (3 tests)
noWindows = 4.16 sec*proc (2 tests)
slow = 78.33 sec*proc (67 tests)
unstable = 28.23 sec*proc (34 tests)
Total Test time (real) = 132.34 sec
The ``ctest`` command has many options, the most important ones are:
@ -210,11 +226,13 @@ Fortran) and testing different aspects of the LAMMPS software and its features.
The tests will adapt to the compilation settings of LAMMPS, so that tests
will be skipped if prerequisite features are not available in LAMMPS.
.. note::
.. admonition:: Work in Progress
:class: note
The unit test framework was added in spring 2020 and is under active
development. The coverage is not complete and will be expanded over
time.
time. Preference is given to parts of the code base that are easy to
test or commonly used.
Tests for styles of the same kind of style (e.g. pair styles or bond
styles) are performed with the same test executable using different
@ -248,9 +266,9 @@ the CMake option ``-D BUILD_MPI=off`` can significantly speed up testing,
since this will skip the MPI initialization for each test run.
Below is an example command and output:
.. parsed-literal::
.. code-block:: console
[tests]$ test_pair_style mol-pair-lj_cut.yaml
$ test_pair_style mol-pair-lj_cut.yaml
[==========] Running 6 tests from 1 test suite.
[----------] Global test environment set-up.
[----------] 6 tests from PairStyle
@ -530,7 +548,7 @@ commands like the following:
.. code-block:: bash
$ clang-format -i some_file.cpp
clang-format -i some_file.cpp
The following target are available for both, GNU make and CMake:
@ -539,3 +557,19 @@ The following target are available for both, GNU make and CMake:
make format-src # apply clang-format to all files in src and the package folders
make format-tests # apply clang-format to all files in the unittest tree
----------
.. _gh-cli:
GitHub command line interface
-----------------------------
GitHub is developing a `tool for the command line
<https://cli.github.com>`_ that interacts with the GitHub website via a
command called ``gh``. This can be extremely convenient when working
with a Git repository hosted on GitHub (like LAMMPS). It is thus highly
recommended to install it when doing LAMMPS development.
The capabilities of the ``gh`` command is continually expanding, so
please see the documentation at https://cli.github.com/manual/

350
doc/src/Build_extras.rst
View File

@ -12,11 +12,11 @@ in addition to
- Traditional make
* - .. code-block:: bash
$ cmake -D PKG_NAME=yes
cmake -D PKG_NAME=yes
- .. code-block:: bash
- .. code-block:: console
$ make yes-name
make yes-name
as described on the :doc:`Build_package <Build_package>` page.
@ -28,26 +28,30 @@ You may need to tell LAMMPS where it is found on your system.
This is the list of packages that may require additional steps.
.. this list must be kept in sync with its counterpart in Build_package.rst
.. table_from_list::
:columns: 6
* :ref:`ADIOS <adios>`
* :ref:`ATC <atc>`
* :ref:`AWPMD <awpmd>`
* :ref:`COLVARS <colvars>`
* :ref:`COLVARS <colvar>`
* :ref:`COMPRESS <compress>`
* :ref:`ELECTRODE <electrode>`
* :ref:`GPU <gpu>`
* :ref:`H5MD <h5md>`
* :ref:`INTEL <intel>`
* :ref:`KIM <kim>`
* :ref:`KOKKOS <kokkos>`
* :ref:`LATTE <latte>`
* :ref:`LEPTON <lepton>`
* :ref:`MACHDYN <machdyn>`
* :ref:`MDI <mdi>`
* :ref:`MESONT <mesont>`
* :ref:`ML-HDNNP <ml-hdnnp>`
* :ref:`ML-IAP <mliap>`
* :ref:`ML-PACE <ml-pace>`
* :ref:`ML-POD <ml-pod>`
* :ref:`ML-QUIP <ml-quip>`
* :ref:`MOLFILE <molfile>`
* :ref:`MSCG <mscg>`
@ -148,7 +152,9 @@ CMake build
* sm_60 or sm_61 for Pascal (supported since CUDA 8)
* sm_70 for Volta (supported since CUDA 9)
* sm_75 for Turing (supported since CUDA 10)
* sm_80 for Ampere (supported since CUDA 11)
* sm_80 or sm_86 for Ampere (supported since CUDA 11, sm_86 since CUDA 11.1)
* sm_89 for Lovelace (supported since CUDA 11.8)
* sm_90 for Hopper (supported since CUDA 12.0)
A more detailed list can be found, for example,
at `Wikipedia's CUDA article <https://en.wikipedia.org/wiki/CUDA#GPUs_supported>`_
@ -239,10 +245,10 @@ script with the specified args:
.. code-block:: bash
$ make lib-gpu # print help message
$ make lib-gpu args="-b" # build GPU library with default Makefile.linux
$ make lib-gpu args="-m xk7 -p single -o xk7.single" # create new Makefile.xk7.single, altered for single-precision
$ make lib-gpu args="-m mpi -a sm_60 -p mixed -b" # build GPU library with mixed precision and P100 using other settings in Makefile.mpi
make lib-gpu # print help message
make lib-gpu args="-b" # build GPU library with default Makefile.linux
make lib-gpu args="-m xk7 -p single -o xk7.single" # create new Makefile.xk7.single, altered for single-precision
make lib-gpu args="-m mpi -a sm_60 -p mixed -b" # build GPU library with mixed precision and P100 using other settings in Makefile.mpi
Note that this procedure starts with a Makefile.machine in lib/gpu, as
specified by the "-m" switch. For your convenience, machine makefiles
@ -355,13 +361,13 @@ minutes to hours) to build. Of course you only need to do that once.)
.. code-block:: bash
$ make lib-kim # print help message
$ make lib-kim args="-b " # (re-)install KIM API lib with only example models
$ make lib-kim args="-b -a Glue_Ercolessi_Adams_Al__MO_324507536345_001" # ditto plus one model
$ make lib-kim args="-b -a everything" # install KIM API lib with all models
$ make lib-kim args="-n -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # add one model or model driver
$ make lib-kim args="-p /usr/local" # use an existing KIM API installation at the provided location
$ make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver
make lib-kim # print help message
make lib-kim args="-b " # (re-)install KIM API lib with only example models
make lib-kim args="-b -a Glue_Ercolessi_Adams_Al__MO_324507536345_001" # ditto plus one model
make lib-kim args="-b -a everything" # install KIM API lib with all models
make lib-kim args="-n -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # add one model or model driver
make lib-kim args="-p /usr/local" # use an existing KIM API installation at the provided location
make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver
When using the "-b " option, the KIM library is built using its native
cmake build system. The ``lib/kim/Install.py`` script supports a
@ -373,7 +379,7 @@ minutes to hours) to build. Of course you only need to do that once.)
.. code-block:: bash
$ CMAKE=cmake3 CXX=g++-11 CC=gcc-11 FC=gfortran-11 make lib-kim args="-b " # (re-)install KIM API lib using cmake3 and gnu v11 compilers with only example models
CMAKE=cmake3 CXX=g++-11 CC=gcc-11 FC=gfortran-11 make lib-kim args="-b " # (re-)install KIM API lib using cmake3 and gnu v11 compilers with only example models
Settings for debugging OpenKIM web queries discussed below need to
be applied by adding them to the ``LMP_INC`` variable through
@ -856,11 +862,11 @@ library.
.. code-block:: bash
$ make lib-latte # print help message
$ make lib-latte args="-b" # download and build in lib/latte/LATTE-master
$ make lib-latte args="-p $HOME/latte" # use existing LATTE installation in $HOME/latte
$ make lib-latte args="-b -m gfortran" # download and build in lib/latte and
# copy Makefile.lammps.gfortran to Makefile.lammps
make lib-latte # print help message
make lib-latte args="-b" # download and build in lib/latte/LATTE-master
make lib-latte args="-p $HOME/latte" # use existing LATTE installation in $HOME/latte
make lib-latte args="-b -m gfortran" # download and build in lib/latte and
# copy Makefile.lammps.gfortran to Makefile.lammps
Note that 3 symbolic (soft) links, ``includelink`` and ``liblink``
and ``filelink.o``, are created in ``lib/latte`` to point to
@ -871,6 +877,55 @@ library.
----------
.. _lepton:
LEPTON package
--------------
To build with this package, you must build the Lepton library which is
included in the LAMMPS source distribution in the ``lib/lepton`` folder.
.. tabs::
.. tab:: CMake build
This is the recommended build procedure for using Lepton in
LAMMPS. No additional settings are normally needed besides
``-D PKG_LEPTON=yes``.
On x86 hardware the Lepton library will also include a just-in-time
compiler for faster execution. This is auto detected but can
be explicitly disabled by setting ``-D LEPTON_ENABLE_JIT=no``
(or enabled by setting it to yes).
.. tab:: Traditional make
Before building LAMMPS, one must build the Lepton library in lib/lepton.
This can be done manually in the same folder by using or adapting
one of the provided Makefiles: for example, ``Makefile.serial`` for
the GNU C++ compiler, or ``Makefile.mpi`` for the MPI compiler wrapper.
The Lepton library is written in C++-11 and thus the C++ compiler
may need to be instructed to enable support for that.
In general, it is safer to use build setting consistent with the
rest of LAMMPS. This is best carried out from the LAMMPS src
directory using a command like these, which simply invokes the
``lib/lepton/Install.py`` script with the specified args:
.. code-block:: bash
$ make lib-lepton # print help message
$ make lib-lepton args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
$ make lib-lepton args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
The "machine" argument of the "-m" flag is used to find a
Makefile.machine to use as build recipe.
The build should produce a ``build`` folder and the library ``lib/lepton/liblmplepton.a``
----------
.. _mliap:
ML-IAP package
@ -959,12 +1014,12 @@ more details.
.. code-block:: bash
$ make lib-mscg # print help message
$ make lib-mscg args="-b -m serial" # download and build in lib/mscg/MSCG-release-master
# with the settings compatible with "make serial"
$ make lib-mscg args="-b -m mpi" # download and build in lib/mscg/MSCG-release-master
# with the settings compatible with "make mpi"
$ make lib-mscg args="-p /usr/local/mscg-release" # use the existing MS-CG installation in /usr/local/mscg-release
make lib-mscg # print help message
make lib-mscg args="-b -m serial" # download and build in lib/mscg/MSCG-release-master
# with the settings compatible with "make serial"
make lib-mscg args="-b -m mpi" # download and build in lib/mscg/MSCG-release-master
# with the settings compatible with "make mpi"
make lib-mscg args="-p /usr/local/mscg-release" # use the existing MS-CG installation in /usr/local/mscg-release
Note that 2 symbolic (soft) links, ``includelink`` and ``liblink``,
will be created in ``lib/mscg`` to point to the MS-CG
@ -1016,10 +1071,10 @@ POEMS package
.. code-block:: bash
$ make lib-poems # print help message
$ make lib-poems args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
$ make lib-poems args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
$ make lib-poems args="-m icc" # build with Intel icc compiler
make lib-poems # print help message
make lib-poems args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
make lib-poems args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
make lib-poems args="-m icc" # build with Intel icc compiler
The build should produce two files: ``lib/poems/libpoems.a`` and
``lib/poems/Makefile.lammps``. The latter is copied from an
@ -1105,10 +1160,10 @@ binary package provided by your operating system.
.. code-block:: bash
$ make lib-voronoi # print help message
$ make lib-voronoi args="-b" # download and build the default version in lib/voronoi/voro++-<version>
$ make lib-voronoi args="-p $HOME/voro++" # use existing Voro++ installation in $HOME/voro++
$ make lib-voronoi args="-b -v voro++0.4.6" # download and build the 0.4.6 version in lib/voronoi/voro++-0.4.6
make lib-voronoi # print help message
make lib-voronoi args="-b" # download and build the default version in lib/voronoi/voro++-<version>
make lib-voronoi args="-p $HOME/voro++" # use existing Voro++ installation in $HOME/voro++
make lib-voronoi args="-b -v voro++0.4.6" # download and build the 0.4.6 version in lib/voronoi/voro++-0.4.6
Note that 2 symbolic (soft) links, ``includelink`` and
``liblink``, are created in lib/voronoi to point to the Voro++
@ -1149,13 +1204,13 @@ systems.
.. code-block:: bash
$ make yes-adios
make yes-adios
otherwise, set ADIOS2_DIR environment variable when turning on the package:
.. code-block:: bash
$ ADIOS2_DIR=path make yes-adios # path is where ADIOS 2.x is installed
ADIOS2_DIR=path make yes-adios # path is where ADIOS 2.x is installed
----------
@ -1184,10 +1239,10 @@ The ATC package requires the MANYBODY package also be installed.
.. code-block:: bash
$ make lib-atc # print help message
$ make lib-atc args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
$ make lib-atc args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
$ make lib-atc args="-m icc" # build with Intel icc compiler
make lib-atc # print help message
make lib-atc args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
make lib-atc args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
make lib-atc args="-m icc" # build with Intel icc compiler
The build should produce two files: ``lib/atc/libatc.a`` and
``lib/atc/Makefile.lammps``. The latter is copied from an
@ -1206,17 +1261,17 @@ The ATC package requires the MANYBODY package also be installed.
.. code-block:: bash
$ make lib-linalg # print help message
$ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
$ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
$ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler
make lib-linalg # print help message
make lib-linalg args="-m serial" # build with GNU C++ compiler (settings as with "make serial")
make lib-linalg args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
make lib-linalg args="-m g++" # build with GNU Fortran compiler
----------
.. _awpmd:
AWPMD package
------------------
-------------
.. tabs::
@ -1235,10 +1290,10 @@ AWPMD package
.. code-block:: bash
$ make lib-awpmd # print help message
$ make lib-awpmd args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
$ make lib-awpmd args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
$ make lib-awpmd args="-m icc" # build with Intel icc compiler
make lib-awpmd # print help message
make lib-awpmd args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
make lib-awpmd args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
make lib-awpmd args="-m icc" # build with Intel icc compiler
The build should produce two files: ``lib/awpmd/libawpmd.a`` and
``lib/awpmd/Makefile.lammps``. The latter is copied from an
@ -1257,21 +1312,20 @@ AWPMD package
.. code-block:: bash
$ make lib-linalg # print help message
$ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
$ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
$ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler
make lib-linalg # print help message
make lib-linalg args="-m serial" # build with GNU C++ compiler (settings as with "make serial")
make lib-linalg args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
make lib-linalg args="-m g++" # build with GNU C++ compiler
----------
.. _colvars:
.. _colvar:
COLVARS package
---------------------------------------
---------------
This package includes the `Colvars library
<https://colvars.github.io/>`_ into the LAMMPS distribution, which can
be built for the most part with all major versions of the C++ language.
This package enables the use of the `Colvars <https://colvars.github.io/>`_
module included in the LAMMPS source distribution.
.. tabs::
@ -1284,42 +1338,45 @@ be built for the most part with all major versions of the C++ language.
.. tab:: Traditional make
Before building LAMMPS, one must build the Colvars library in lib/colvars.
As with other libraries distributed with LAMMPS, the Colvars library
needs to be built before building the LAMMPS program with the COLVARS
package enabled.
This can be done manually in the same folder by using or adapting
one of the provided Makefiles: for example, ``Makefile.g++`` for
the GNU C++ compiler. C++11 compatibility may need to be enabled
for some older compilers (as is done in the example makefile).
In general, it is safer to use build setting consistent with the
rest of LAMMPS. This is best carried out from the LAMMPS src
directory using a command like these, which simply invokes the
``lib/colvars/Install.py`` script with the specified args:
From the LAMMPS ``src`` directory, this is most easily and safely done
via one of the following commands, which implicitly rely on the
``lib/colvars/Install.py`` script with optional arguments:
.. code-block:: bash
$ make lib-colvars # print help message
$ make lib-colvars args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
$ make lib-colvars args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
$ make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled
make lib-colvars # print help message
make lib-colvars args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
make lib-colvars args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled
The "machine" argument of the "-m" flag is used to find a
Makefile.machine to use as build recipe. If it does not already
exist in ``lib/colvars``, it will be auto-generated by using
compiler flags consistent with those parsed from the core LAMMPS
makefiles.
``Makefile.machine`` file to use as build recipe. If such recipe does
not already exist in ``lib/colvars``, suitable settings will be
auto-generated consistent with those used in the core LAMMPS makefiles.
.. versionchanged:: TBD
Please note that Colvars uses the Lepton library, which is now
included with the LEPTON package; if you use anything other than
the ``make lib-colvars`` command, please make sure to :ref:`build
Lepton beforehand <lepton>`.
Optional flags may be specified as environment variables:
.. code-block:: bash
$ COLVARS_DEBUG=yes make lib-colvars args="-m machine" # Build with debug code (much slower)
$ COLVARS_LEPTON=no make lib-colvars args="-m machine" # Build without Lepton (included otherwise)
COLVARS_DEBUG=yes make lib-colvars args="-m machine" # Build with debug code (much slower)
COLVARS_LEPTON=no make lib-colvars args="-m machine" # Build without Lepton (included otherwise)
The build should produce two files: the library ``lib/colvars/libcolvars.a``
(which also includes Lepton objects if enabled) and the specification file
``lib/colvars/Makefile.lammps``. The latter is auto-generated, and normally does
not need to be edited.
The build should produce two files: the library
``lib/colvars/libcolvars.a`` and the specification file
``lib/colvars/Makefile.lammps``. The latter is auto-generated,
and normally does not need to be edited.
----------
@ -1348,9 +1405,9 @@ This package depends on the KSPACE package.
.. code-block:: bash
$ make lib-electrode # print help message
$ make lib-electrode args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
$ make lib-electrode args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
make lib-electrode # print help message
make lib-electrode args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
make lib-electrode args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
Note that the ``Makefile.lammps`` file has settings for the BLAS
@ -1361,10 +1418,10 @@ This package depends on the KSPACE package.
.. code-block:: bash
$ make lib-linalg # print help message
$ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
$ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
$ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler
make lib-linalg # print help message
make lib-linalg args="-m serial" # build with GNU C++ compiler (settings as with "make serial")
make lib-linalg args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
make lib-linalg args="-m g++" # build with GNU C++ compiler
The package itself is activated with ``make yes-KSPACE`` and
``make yes-ELECTRODE``
@ -1404,13 +1461,56 @@ at: `https://github.com/ICAMS/lammps-user-pace/ <https://github.com/ICAMS/lammps
.. code-block:: bash
$ make lib-pace # print help message
$ make lib-pace args="-b" # download and build the default version in lib/pace
make lib-pace # print help message
make lib-pace args="-b" # download and build the default version in lib/pace
You should not need to edit the ``lib/pace/Makefile.lammps`` file.
----------
.. _ml-pod:
ML-POD package
-----------------------------
.. tabs::
.. tab:: CMake build
No additional settings are needed besides ``-D PKG_ML-POD=yes``.
.. tab:: Traditional make
Before building LAMMPS, you must configure the ML-POD support
settings in ``lib/mlpod``. You can do this manually, if you
prefer, or do it in one step from the ``lammps/src`` dir, using a
command like the following, which simply invoke the
``lib/mlpod/Install.py`` script with the specified args:
.. code-block:: bash
make lib-mlpod # print help message
make lib-mlpod args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
make lib-mlpod args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
make lib-mlpod args="-m mpi -e linalg" # same as above but use the bundled linalg lib
Note that the ``Makefile.lammps`` file has settings to use the BLAS
and LAPACK linear algebra libraries. These can either exist on
your system, or you can use the files provided in ``lib/linalg``.
In the latter case you also need to build the library in
``lib/linalg`` with a command like these:
.. code-block:: bash
make lib-linalg # print help message
make lib-linalg args="-m serial" # build with GNU C++ compiler (settings as with "make serial")
make lib-linalg args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
make lib-linalg args="-m g++" # build with GNU C++ compiler
The package itself is activated with ``make yes-ML-POD``.
----------
.. _plumed:
PLUMED package
@ -1504,10 +1604,10 @@ LAMMPS build.
.. code-block:: bash
$ make lib-plumed # print help message
$ make lib-plumed args="-b" # download and build PLUMED in lib/plumed/plumed2
$ make lib-plumed args="-p $HOME/.local" # use existing PLUMED installation in $HOME/.local
$ make lib-plumed args="-p /usr/local -m shared" # use existing PLUMED installation in
make lib-plumed # print help message
make lib-plumed args="-b" # download and build PLUMED in lib/plumed/plumed2
make lib-plumed args="-p $HOME/.local" # use existing PLUMED installation in $HOME/.local
make lib-plumed args="-p /usr/local -m shared" # use existing PLUMED installation in
# /usr/local and use shared linkage mode
Note that 2 symbolic (soft) links, ``includelink`` and ``liblink``
@ -1520,8 +1620,8 @@ LAMMPS build.
.. code-block:: bash
$ make yes-plumed
$ make machine
make yes-plumed
make machine
Once this compilation completes you should be able to run LAMMPS
in the usual way. For shared linkage mode, libplumed.so must be
@ -1573,8 +1673,8 @@ the HDF5 library.
.. code-block:: bash
$ make lib-h5md # print help message
$ make lib-h5md args="-m h5cc" # build with h5cc compiler
make lib-h5md # print help message
make lib-h5md args="-m h5cc" # build with h5cc compiler
The build should produce two files: ``lib/h5md/libch5md.a`` and
``lib/h5md/Makefile.lammps``. The latter is copied from an
@ -1628,10 +1728,10 @@ details please see ``lib/hdnnp/README`` and the `n2p2 build documentation
.. code-block:: bash
$ make lib-hdnnp # print help message
$ make lib-hdnnp args="-b" # download and build in lib/hdnnp/n2p2-...
$ make lib-hdnnp args="-b -v 2.1.4" # download and build specific version
$ make lib-hdnnp args="-p /usr/local/n2p2" # use the existing n2p2 installation in /usr/local/n2p2
make lib-hdnnp # print help message
make lib-hdnnp args="-b" # download and build in lib/hdnnp/n2p2-...
make lib-hdnnp args="-b -v 2.1.4" # download and build specific version
make lib-hdnnp args="-p /usr/local/n2p2" # use the existing n2p2 installation in /usr/local/n2p2
Note that 3 symbolic (soft) links, ``includelink``, ``liblink`` and
``Makefile.lammps``, will be created in ``lib/hdnnp`` to point to
@ -1731,8 +1831,8 @@ MDI package
.. code-block:: bash
$ python Install.py -m gcc # build using gcc compiler
$ python Install.py -m icc # build using icc compiler
python Install.py -m gcc # build using gcc compiler
python Install.py -m icc # build using icc compiler
The build should produce two files: ``lib/mdi/includelink/mdi.h``
and ``lib/mdi/liblink/libmdi.so``\ .
@ -1766,9 +1866,9 @@ they will be downloaded the first time this package is installed.
.. code-block:: bash
$ make lib-mesont # print help message
$ make lib-mesont args="-m gfortran" # build with GNU g++ compiler (settings as with "make serial")
$ make lib-mesont args="-m ifort" # build with Intel icc compiler
make lib-mesont # print help message
make lib-mesont args="-m gfortran" # build with GNU g++ compiler (settings as with "make serial")
make lib-mesont args="-m ifort" # build with Intel icc compiler
The build should produce two files: ``lib/mesont/libmesont.a`` and
``lib/mesont/Makefile.lammps``\ . The latter is copied from an
@ -1881,6 +1981,22 @@ OPENMP package
For other platforms and compilers, please consult the
documentation about OpenMP support for your compiler.
.. admonition:: Adding OpenMP support on macOS
:class: note
Apple offers the `Xcode package and IDE
<https://developer.apple.com/xcode/>`_ for compiling software on
macOS, so you have likely installed it to compile LAMMPS. Their
compiler is based on `Clang <https://clang.llvm.org/>`, but while it
is capable of processing OpenMP directives, the necessary header
files and OpenMP runtime library are missing. The `R developers
<https://www.r-project.org/>` have figured out a way to build those
in a compatible fashion. One can download them from
`https://mac.r-project.org/openmp/
<https://mac.r-project.org/openmp/>`_. Simply adding those files as
instructed enables the Xcode C++ compiler to compile LAMMPS with ``-D
BUILD_OMP=yes``.
----------
.. _qmmm:
@ -1935,10 +2051,10 @@ verified to work in February 2020 with Quantum Espresso versions 6.3 to
.. code-block:: bash
$ make lib-qmmm # print help message
$ make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial")
$ make lib-qmmm args="-m mpi" # build with default MPI compiler (settings as in "make mpi")
$ make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler
make lib-qmmm # print help message
make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial")
make lib-qmmm args="-m mpi" # build with default MPI compiler (settings as in "make mpi")
make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler
The build should produce two files: ``lib/qmmm/libqmmm.a`` and
``lib/qmmm/Makefile.lammps``. The latter is copied from an
@ -2087,9 +2203,9 @@ Eigen3 is a template library, so you do not need to build it.
.. code-block:: bash
$ make lib-smd # print help message
$ make lib-smd args="-b" # download to lib/smd/eigen3
$ make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3
make lib-smd # print help message
make lib-smd args="-b" # download to lib/smd/eigen3
make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3
Note that a symbolic (soft) link named ``includelink`` is created
in ``lib/smd`` to point to the Eigen dir. When LAMMPS builds it

4
doc/src/Build_link.rst
View File

@ -209,7 +209,7 @@ You can verify whether all required shared libraries are found with the
.. code-block:: bash
$ LD_LIBRARY_PATH=/home/user/lammps/src ldd caller
LD_LIBRARY_PATH=/home/user/lammps/src ldd caller
linux-vdso.so.1 (0x00007ffe729e0000)
liblammps.so => /home/user/lammps/src/liblammps.so (0x00007fc91bb9e000)
libstdc++.so.6 => /lib64/libstdc++.so.6 (0x00007fc91b984000)
@ -222,7 +222,7 @@ If a required library is missing, you would get a 'not found' entry:
.. code-block:: bash
$ ldd caller
ldd caller
linux-vdso.so.1 (0x00007ffd672fe000)
liblammps.so => not found
libstdc++.so.6 => /usr/lib64/libstdc++.so.6 (0x00007fb7c7e86000)

21
doc/src/Build_manual.rst
View File

@ -125,38 +125,29 @@ common setups:
.. code-block:: bash
sudo apt-get install python-virtualenv git doxygen
sudo apt-get install git doxygen
.. tab:: RHEL or CentOS (Version 7.x)
.. code-block:: bash
sudo yum install python3-virtualenv git doxygen
sudo yum install git doxygen
.. tab:: Fedora or RHEL/CentOS (8.x or later)
.. code-block:: bash
sudo dnf install python3-virtualenv git doxygen
sudo dnf install git doxygen
.. tab:: MacOS X
.. tab:: macOS
*Python 3*
Download the latest Python 3 MacOS X package from
If Python 3 is not available on your macOS system, you can
download the latest Python 3 macOS package from
`https://www.python.org <https://www.python.org>`_ and install it.
This will install both Python 3 and pip3.
*virtualenv*
Once Python 3 is installed, open a Terminal and type
.. code-block:: bash
pip3 install virtualenv
This will install virtualenv from the Python Package Index.
Prerequisites for PDF
---------------------

9
doc/src/Build_package.rst
View File

@ -30,23 +30,30 @@ steps, as explained on the :doc:`Build extras <Build_extras>` page.
These links take you to the extra instructions for those select
packages:
.. this list must be kept in sync with its counterpart in Build_extras.rst
.. table_from_list::
:columns: 6
* :ref:`ADIOS <adios>`
* :ref:`ATC <atc>`
* :ref:`AWPMD <awpmd>`
* :ref:`COLVARS <colvars>`
* :ref:`COLVARS <colvar>`
* :ref:`COMPRESS <compress>`
* :ref:`ELECTRODE <electrode>`
* :ref:`GPU <gpu>`
* :ref:`H5MD <h5md>`
* :ref:`INTEL <intel>`
* :ref:`KIM <kim>`
* :ref:`KOKKOS <kokkos>`
* :ref:`LATTE <latte>`
* :ref:`LEPTON <lepton>`
* :ref:`MACHDYN <machdyn>`
* :ref:`MDI <mdi>`
* :ref:`MESONT <mesont>`
* :ref:`ML-HDNNP <ml-hdnnp>`
* :ref:`ML-IAP <mliap>`
* :ref:`ML-PACE <ml-pace>`
* :ref:`ML-POD <ml-pod>`
* :ref:`ML-QUIP <ml-quip>`
* :ref:`MOLFILE <molfile>`
* :ref:`MSCG <mscg>`

3
doc/src/Commands_all.rst
View File

@ -24,6 +24,7 @@ table above.
* :doc:`angle_coeff <angle_coeff>`
* :doc:`angle_style <angle_style>`
* :doc:`angle_write <angle_write>`
* :doc:`atom_modify <atom_modify>`
* :doc:`atom_style <atom_style>`
* :doc:`balance <balance>`
@ -45,6 +46,7 @@ table above.
* :doc:`dielectric <dielectric>`
* :doc:`dihedral_coeff <dihedral_coeff>`
* :doc:`dihedral_style <dihedral_style>`
* :doc:`dihedral_write <dihedral_write>`
* :doc:`dimension <dimension>`
* :doc:`displace_atoms <displace_atoms>`
* :doc:`dump <dump>`
@ -125,6 +127,7 @@ additional letter in parenthesis: k = KOKKOS.
* :doc:`group2ndx <group2ndx>`
* :doc:`hyper <hyper>`
* :doc:`kim <kim_commands>`
* :doc:`fitpod <fitpod_command>`
* :doc:`mdi <mdi>`
* :doc:`ndx2group <group2ndx>`
* :doc:`neb <neb>`

3
doc/src/Commands_bond.rst
View File

@ -44,6 +44,7 @@ OPT.
* :doc:`harmonic (iko) <bond_harmonic>`
* :doc:`harmonic/shift (o) <bond_harmonic_shift>`
* :doc:`harmonic/shift/cut (o) <bond_harmonic_shift_cut>`
* :doc:`lepton (o) <bond_lepton>`
* :doc:`mesocnt <bond_mesocnt>`
* :doc:`mm3 <bond_mm3>`
* :doc:`morse (o) <bond_morse>`
@ -93,6 +94,7 @@ OPT.
* :doc:`fourier/simple (o) <angle_fourier_simple>`
* :doc:`gaussian <angle_gaussian>`
* :doc:`harmonic (iko) <angle_harmonic>`
* :doc:`lepton (o) <angle_lepton>`
* :doc:`mesocnt <angle_mesocnt>`
* :doc:`mm3 <angle_mm3>`
* :doc:`quartic (o) <angle_quartic>`
@ -127,6 +129,7 @@ OPT.
* :doc:`fourier (io) <dihedral_fourier>`
* :doc:`harmonic (iko) <dihedral_harmonic>`
* :doc:`helix (o) <dihedral_helix>`
* :doc:`lepton (o) <dihedral_lepton>`
* :doc:`multi/harmonic (o) <dihedral_multi_harmonic>`
* :doc:`nharmonic (o) <dihedral_nharmonic>`
* :doc:`opls (iko) <dihedral_opls>`

2
doc/src/Commands_compute.rst
View File

@ -57,6 +57,7 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`dpd/atom <compute_dpd_atom>`
* :doc:`edpd/temp/atom <compute_edpd_temp_atom>`
* :doc:`efield/atom <compute_efield_atom>`
* :doc:`efield/wolf/atom <compute_efield_wolf_atom>`
* :doc:`entropy/atom <compute_entropy_atom>`
* :doc:`erotate/asphere <compute_erotate_asphere>`
* :doc:`erotate/rigid <compute_erotate_rigid>`
@ -107,6 +108,7 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`pressure/uef <compute_pressure_uef>`
* :doc:`property/atom <compute_property_atom>`
* :doc:`property/chunk <compute_property_chunk>`
* :doc:`property/grid <compute_property_grid>`
* :doc:`property/local <compute_property_local>`
* :doc:`ptm/atom <compute_ptm_atom>`
* :doc:`rdf <compute_rdf>`

3
doc/src/Commands_dump.rst
View File

@ -36,7 +36,8 @@ An alphabetic list of all LAMMPS :doc:`dump <dump>` commands.
* :doc:`custom/mpiio <dump>`
* :doc:`custom/zstd <dump>`
* :doc:`dcd <dump>`
* :doc:`deprecated <dump>`
* :doc:`grid <dump>`
* :doc:`grid/vtk <dump>`
* :doc:`h5md <dump_h5md>`
* :doc:`image <dump_image>`
* :doc:`local <dump>`

12
doc/src/Commands_fix.rst
View File

@ -38,6 +38,7 @@ OPT.
* :doc:`ave/chunk <fix_ave_chunk>`
* :doc:`ave/correlate <fix_ave_correlate>`
* :doc:`ave/correlate/long <fix_ave_correlate_long>`
* :doc:`ave/grid <fix_ave_grid>`
* :doc:`ave/histo <fix_ave_histo>`
* :doc:`ave/histo/weight <fix_ave_histo>`
* :doc:`ave/time <fix_ave_time>`
@ -65,13 +66,13 @@ OPT.
* :doc:`drude <fix_drude>`
* :doc:`drude/transform/direct <fix_drude_transform>`
* :doc:`drude/transform/inverse <fix_drude_transform>`
* :doc:`dt/reset <fix_dt_reset>`
* :doc:`dt/reset (k) <fix_dt_reset>`
* :doc:`edpd/source <fix_dpd_source>`
* :doc:`efield <fix_efield>`
* :doc:`ehex <fix_ehex>`
* :doc:`electrode/conp (i) <fix_electrode_conp>`
* :doc:`electrode/conq (i) <fix_electrode_conp>`
* :doc:`electrode/thermo (i) <fix_electrode_conp>`
* :doc:`electrode/conp (i) <fix_electrode>`
* :doc:`electrode/conq (i) <fix_electrode>`
* :doc:`electrode/thermo (i) <fix_electrode>`
* :doc:`electron/stopping <fix_electron_stopping>`
* :doc:`electron/stopping/fit <fix_electron_stopping>`
* :doc:`enforce2d (k) <fix_enforce2d>`
@ -214,6 +215,7 @@ OPT.
* :doc:`saed/vtk <fix_saed_vtk>`
* :doc:`setforce (k) <fix_setforce>`
* :doc:`setforce/spin <fix_setforce>`
* :doc:`sgcmc <fix_sgcmc>`
* :doc:`shake (k) <fix_shake>`
* :doc:`shardlow (k) <fix_shardlow>`
* :doc:`smd <fix_smd>`
@ -250,7 +252,7 @@ OPT.
* :doc:`tune/kspace <fix_tune_kspace>`
* :doc:`vector <fix_vector>`
* :doc:`viscosity <fix_viscosity>`
* :doc:`viscous <fix_viscous>`
* :doc:`viscous (k) <fix_viscous>`
* :doc:`viscous/sphere <fix_viscous_sphere>`
* :doc:`wall/body/polygon <fix_wall_body_polygon>`
* :doc:`wall/body/polyhedron <fix_wall_body_polyhedron>`

9
doc/src/Commands_pair.rst
View File

@ -93,8 +93,8 @@ OPT.
* :doc:`coul/wolf/cs <pair_cs>`
* :doc:`dpd (giko) <pair_dpd>`
* :doc:`dpd/fdt <pair_dpd_fdt>`
* :doc:`dpd/ext (k) <pair_dpd_ext>`
* :doc:`dpd/ext/tstat (k) <pair_dpd_ext>`
* :doc:`dpd/ext (ko) <pair_dpd_ext>`
* :doc:`dpd/ext/tstat (ko) <pair_dpd_ext>`
* :doc:`dpd/fdt/energy (k) <pair_dpd_fdt>`
* :doc:`dpd/tstat (gko) <pair_dpd>`
* :doc:`dsmc <pair_dsmc>`
@ -134,6 +134,8 @@ OPT.
* :doc:`lcbop <pair_lcbop>`
* :doc:`lebedeva/z <pair_lebedeva_z>`
* :doc:`lennard/mdf <pair_mdf>`
* :doc:`lepton (o) <pair_lepton>`
* :doc:`lepton/coul (o) <pair_lepton>`
* :doc:`line/lj <pair_line_lj>`
* :doc:`lj/charmm/coul/charmm (giko) <pair_charmm>`
* :doc:`lj/charmm/coul/charmm/implicit (ko) <pair_charmm>`
@ -236,7 +238,8 @@ OPT.
* :doc:`oxrna2/xstk <pair_oxrna2>`
* :doc:`oxrna2/coaxstk <pair_oxrna2>`
* :doc:`pace (k) <pair_pace>`
* :doc:`pace/extrapolation <pair_pace>`
* :doc:`pace/extrapolation (k) <pair_pace>`
* :doc:`pod <pair_pod>`
* :doc:`peri/eps <pair_peri>`
* :doc:`peri/lps (o) <pair_peri>`
* :doc:`peri/pmb (o) <pair_peri>`

6
doc/src/Commands_removed.rst
View File

@ -11,6 +11,8 @@ with the direct alternative (if available) and print a warning.
Fix ave/spatial and fix ave/spatial/sphere
------------------------------------------
.. deprecated:: 11Dec2015
The fixes ave/spatial and ave/spatial/sphere have been removed from LAMMPS
since they were superseded by the more general and extensible "chunk
infrastructure". Here the system is partitioned in one of many possible
@ -21,7 +23,7 @@ Please refer to the :doc:`chunk HOWTO <Howto_chunk>` section for an overview.
Box command
-----------
.. deprecated:: TBD
.. deprecated:: 22Dec2022
The *box* command has been removed and the LAMMPS code changed so it won't
be needed. If present, LAMMPS will ignore the command and print a warning.
@ -29,7 +31,7 @@ be needed. If present, LAMMPS will ignore the command and print a warning.
Reset_ids, reset_atom_ids, reset_mol_ids commands
-------------------------------------------------
.. deprecated:: TBD
.. deprecated:: 22Dec2022
The *reset_ids*, *reset_atom_ids*, and *reset_mol_ids* commands have
been folded into the :doc:`reset_atoms <reset_atoms>` command. If

1
doc/src/Developer.rst
View File

@ -23,3 +23,4 @@ of time and requests from the LAMMPS user community.
Classes
Developer_platform
Developer_utils
Developer_grid

14
doc/src/Developer_code_design.rst
View File

@ -50,7 +50,7 @@ parallel each MPI process creates such an instance. This can be seen
in the ``main.cpp`` file where the core steps of running a LAMMPS
simulation are the following 3 lines of code:
.. code-block:: C++
.. code-block:: c++
LAMMPS *lammps = new LAMMPS(argc, argv, lammps_comm);
lammps->input->file();
@ -78,7 +78,7 @@ LAMMPS makes extensive use of the object oriented programming (OOP)
principles of *compositing* and *inheritance*. Classes like the
``LAMMPS`` class are a **composite** containing pointers to instances
of other classes like ``Atom``, ``Comm``, ``Force``, ``Neighbor``,
``Modify``, and so on. Each of these classes implement certain
``Modify``, and so on. Each of these classes implements certain
functionality by storing and manipulating data related to the
simulation and providing member functions that trigger certain
actions. Some of those classes like ``Force`` are themselves
@ -87,9 +87,9 @@ interactions. Similarly the ``Modify`` class contains a list of
``Fix`` and ``Compute`` classes. If the input commands that
correspond to these classes include the word *style*, then LAMMPS
stores only a single instance of that class. E.g. *atom_style*,
*comm_style*, *pair_style*, *bond_style*. It the input command does
not include the word *style*, there can be many instances of that
class defined. E.g. *region*, *fix*, *compute*, *dump*.
*comm_style*, *pair_style*, *bond_style*. If the input command does
**not** include the word *style*, then there may be many instances of
that class defined, for example *region*, *fix*, *compute*, *dump*.
**Inheritance** enables creation of *derived* classes that can share
common functionality in their base class while providing a consistent
@ -232,7 +232,7 @@ macro ``PairStyle()`` will associate the style name "lj/cut"
with a factory function creating an instance of the ``PairLJCut``
class.
.. code-block:: C++
.. code-block:: c++
// from force.h
typedef Pair *(*PairCreator)(LAMMPS *);
@ -360,7 +360,7 @@ characters; "{:<8}" would do this as left aligned, "{:^8}" as centered,
argument type must be compatible or else the {fmt} formatting code will
throw an exception. Some format string examples are given below:
.. code-block:: C
.. code-block:: c++
auto mesg = fmt::format(" CPU time: {:4d}:{:02d}:{:02d}\n", cpuh, cpum, cpus);
mesg = fmt::format("{:<8s}| {:<10.5g} | {:<10.5g} | {:<10.5g} |{:6.1f} |{:6.2f}\n",

846
doc/src/Developer_grid.rst Normal file
View File

@ -0,0 +1,846 @@
Use of distributed grids within style classes
---------------------------------------------
.. versionadded:: 22Dec2022
The LAMMPS source code includes two classes which facilitate the
creation and use of distributed grids. These are the Grid2d and
Grid3d classes in the src/grid2d.cpp.h and src/grid3d.cpp.h files
respectively. As the names imply, they are used for 2d or 3d
simulations, as defined by the :doc:`dimension <dimension>` command.
The :doc:`Howto_grid <Howto_grid>` page gives an overview of how
distributed grids are defined from a user perspective, lists LAMMPS
commands which use them, and explains how grid cell data is referenced
from an input script. Please read that page first as it motivates the
coding details discussed here.
This doc page is for users who wish to write new styles (input script
commands) which use distributed grids. There are a variety of
material models and analysis methods which use atoms (or
coarse-grained particles) and grids in tandem.
A *distributed* grid means each processor owns a subset of the grid
cells. In LAMMPS, the subset for each processor will be a sub-block
of grid cells with low and high index bounds in each dimension of the
grid. The union of the sub-blocks across all processors is the global
grid.
More specifically, a grid point is defined for each cell (by default
the center point), and a processor owns a grid cell if its point is
within the processor's spatial sub-domain. The union of processor
sub-domains is the global simulation box. If a grid point is on the
boundary of two sub-domains, the lower processor owns the grid cell. A
processor may also store copies of ghost cells which surround its
owned cells.
----------
Style commands
^^^^^^^^^^^^^^
Style commands which can define and use distributed grids include the
:doc:`compute <compute>`, :doc:`fix <fix>`, :doc:`pair <pair_style>`,
and :doc:`kspace <kspace_style>` styles. If you wish grid cell data
to persist across timesteps, then use a fix. If you wish grid cell
data to be accessible by other commands, then use a fix or compute.
Currently in LAMMPS, the :doc:`pair_style amoeba <pair_amoeba>`,
:doc:`kspace_style pppm <kspace_style>`, and :doc:`kspace_style msm
<kspace_style>` commands use distributed grids but do not require
either of these capabilities; they thus create and use distributed
grids internally. Note that a pair style which needs grid cell data
to persist could be coded to work in tandem with a fix style which
provides that capability.
The *size* of a grid is specified by the number of grid cells in each
dimension of the simulation domain. In any dimension the size can be
any value >= 1. Thus a 10x10x1 grid for a 3d simulation is
effectively a 2d grid, where each grid cell spans the entire
z-dimension. A 1x100x1 grid for a 3d simulation is effectively a 1d
grid, where grid cells are a series of thin xz slabs in the
y-dimension. It is even possible to define a 1x1x1 3d grid, though it
may be inefficient to use it in a computational sense.
Note that the choice of grid size is independent of the number of
processors or their layout in a grid of processor sub-domains which
overlays the simulations domain. Depending on the distributed grid
size, a single processor may own many 1000s or no grid cells.
A command can define multiple grids, each of a different size. Each
grid is an instantiation of the Grid2d or Grid3d class.
The command also defines what data it will store for each grid it
creates and it allocates the multi-dimensional array(s) needed to
store the data. No grid cell data is stored within the Grid2d or
Grid3d classes.
If a single value per grid cell is needed, the data array will have
the same dimension as the grid, i.e. a 2d array for a 2d grid,
likewise for 3d. If multiple values per grid cell are needed, the
data array will have one more dimension than the grid, i.e. a 3d array
for a 2d grid, or 4d array for a 3d grid. A command can choose to
define multiple data arrays for each grid it defines.
----------
Grid data allocation and access
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The simplest way for a command to allocate and access grid cell data
is to use the *create_offset()* methods provided by the Memory class.
Arguments for these methods can be values returned by the
*setup_grid()* method (described below), which define the extent of
the grid cells (owned+ghost) the processor owns. These 4 methods
allocate memory for 2d (first two) and 3d (second two) grid data. The
two methods that end in "_one" allocate an array which stores a single
value per grid cell. The two that end in "_multi" allocate an array
which stores *Nvalues* per grid cell.
.. code-block:: c++
// single value per cell for a 2d grid = 2d array
memory->create2d_offset(data2d_one, nylo_out, nyhi_out,
nxlo_out, nxhi_out, "data2d_one");
// nvalues per cell for a 2d grid = 3d array
memory->create3d_offset_last(data2d_multi, nylo_out, nyhi_out,
nxlo_out, nxhi_out, nvalues, "data2d_multi");
// single value per cell for a 3d grid = 3d array
memory->create3d_offset(data3d_one, nzlo_out, nzhi_out, nylo_out,
nyhi_out, nxlo_out, nxhi_out, "data3d_one");
// nvalues per cell for a 3d grid = 4d array
memory->create4d_offset_last(data3d_multi, nzlo_out, nzhi_out, nylo_out,
nyhi_out, nxlo_out, nxhi_out, nvalues,
"data3d_multi");
Note that these multi-dimensional arrays are allocated as contiguous
chunks of memory where the x-index of the grid varies fastest, then y,
and the z-index slowest. For multiple values per grid cell, the
Nvalues are contiguous, so their index varies even faster than the
x-index.
The key point is that the "offset" methods create arrays which are
indexed by the range of indices which are the bounds of the sub-block
of the global grid owned by this processor. This means loops like
these can be written in the caller code to loop over owned grid cells,
where the "i" loop bounds are the range of owned grid cells for the
processor. These are the bounds returned by the *setup_grid()*
method:
.. code-block:: c++
for (int iy = iylo; iy <= iyhi; iy++)
for (int ix = ixlo; ix <= ixhi; ix++)
data2d_one[iy][ix] = 0.0;
for (int iy = iylo; iy <= iyhi; iy++)
for (int ix = ixlo; ix <= ixhi; ix++)
for (int m = 0; m < nvalues; m++)
data2d_multi[iy][ix][m] = 0.0;
for (int iz = izlo; iz <= izhi; iz++)
for (int iy = iylo; iy <= iyhi; iy++)
for (int ix = ixlo; ix <= ixhi; ix++)
data3d_one[iz][iy][ix] = 0.0;
for (int iz = izlo; iz <= izhi; iz++)
for (int iy = iylo; iy <= iyhi; iy++)
for (int ix = ixlo; ix <= ixhi; ix++)
for (int m = 0; m < nvalues; m++)
data3d_multi[iz][iy][ix][m] = 0.0;
Simply replacing the "i" bounds with "o" bounds, also returned by the
*setup_grid()* method, would alter this code to loop over owned+ghost
cells (the entire allocated grid).
----------
Grid class constructors
^^^^^^^^^^^^^^^^^^^^^^^
The following sub-sections describe the public methods of the Grid3d
class which a style command can invoke. The Grid2d methods are
similar; simply remove arguments which refer to the z-dimension.
There are 2 constructors which can be used. They differ in the extra
i/o xyz lo/hi arguments:
.. code-block:: c++
Grid3d(class LAMMPS *lmp, MPI_Comm gcomm, int gnx, int gny, int gnz)
Grid3d(class LAMMPS *lmp, MPI_Comm gcomm, int gnx, int gny, int gnz,
int ixlo, int ixhi, int iylo, int iyhi, int izlo, int izhi,
int oxlo, int oxhi, int oylo, int oyhi, int ozlo, int ozhi)
Both constructors take the LAMMPS instance pointer and a communicator
over which the grid will be distributed. Typically this is the
*world* communicator the LAMMPS instance is using. The
:doc:`kspace_style msm <kspace_style>` command creates a series of
grids, each of different size, which are partitioned across different
sub-communicators of processors. Both constructors are also passed
the global grid size: *gnx* by *gny* by *gnz*.
The first constructor is used when the caller wants the Grid class to
partition the global grid across processors; the Grid class defines
which grid cells each processor owns and also which it stores as ghost
cells. A subsequent call to *setup_grid()*, discussed below, returns
this info to the caller.
The second constructor allows the caller to define the extent of owned
and ghost cells, and pass them to the Grid class. The 6 arguments
which start with "i" are the inclusive lower and upper index bounds of
the owned (inner) grid cells this processor owns in each of the 3
dimensions within the global grid. Owned grid cells are indexed from
0 to N-1 in each dimension.
The 6 arguments which start with "o" are the inclusive bounds of the
owned+ghost (outer) grid cells it stores. If the ghost cells are on
the other side of a periodic boundary, then these indices may be < 0
or >= N in any dimension, so that oxlo <= ixlo and ixhi >= ixhi is
always the case.
For example, if Nx = 100, then a processor might pass ixlo=50,
ixhi=60, oxlo=48, oxhi=62 to the Grid class. Or ixlo=0, ixhi=10,
oxlo=-2, oxhi=13. If a processor owns no grid cells in a dimension,
then the ihi value should be specified as one less than the ilo value.
Note that the only reason to use the second constructor is if the
logic for assigning ghost cells is too complex for the Grid class to
compute, using the various set() methods described next. Currently
only the kspace_style pppm/electrode and kspace_style msm commands use
the second constructor.
----------
Grid class set methods
^^^^^^^^^^^^^^^^^^^^^^
The following methods affect how the Grid class computes which owned
and ghost cells are assigned to each processor. *Set_shift_grid()* is
the only method which influences owned cell assignment; all the rest
influence ghost cell assignment. These methods are only used with the
first constructor; they are ignored if the second constructor is used.
These methods must be called before the *setup_grid()* method is
invoked, because they influence its operation.
.. code-block:: c++
void set_shift_grid(double shift);
void set_distance(double distance);
void set_stencil_atom(int lo, int hi);
void set_shift_atom(double shift_lo, double shift_hi);
void set_stencil_grid(int lo, int hi);
void set_zfactor(double factor);
Processors own a grid cell if a point within the grid cell is inside
the processor's sub-domain. By default this is the center point of the
grid cell. The *set_shift_grid()* method can change this. The *shift*
argument is a value from 0.0 to 1.0 (inclusive) which is the offset of
the point within the grid cell in each dimension. The default is 0.5
for the center of the cell. A value of 0.0 is the lower left corner
point; a value of 1.0 is the upper right corner point. There is
typically no need to change the default as it is optimal for
minimizing the number of ghost cells needed.
If a processor maps its particles to grid cells, it needs to allow for
its particles being outside its sub-domain between reneighboring. The
*distance* argument of the *set_distance()* method sets the furthest
distance outside a processor's sub-domain which a particle can move.
Typically this is half the neighbor skin distance, assuming
reneighboring is done appropriately. This distance is used in
determining how many ghost cells a processor needs to store to enable
its particles to be mapped to grid cells. The default value is 0.0.
Some commands, like the :doc:`kspace_style pppm <kspace_style>`
command, map values (charge in the case of PPPM) to a stencil of grid
cells beyond the grid cell the particle is in. The stencil extent may
be different in the low and high directions. The *set_stencil_atom()*
method defines the maximum values of those 2 extents, assumed to be
the same in each of the 3 dimensions. Both the lo and hi values are
specified as positive integers. The default values are both 0.
Some commands, like the :doc:`kspace_style pppm <kspace_style>`
command, shift the position of an atom when mapping it to a grid cell,
based on the size of the stencil used to map values to the grid
(charge in the case of PPPM). The lo and hi arguments of the
*set_shift_atom()* method are the minimum shift in the low direction
and the maximum shift in the high direction, assumed to be the same in
each of the 3 dimensions. The shifts should be fractions of a grid
cell size with values between 0.0 and 1.0 inclusive. The default
values are both 0.0. See the src/pppm.cpp file for examples of these
lo/hi values for regular and staggered grids.
Some methods like the :doc:`fix ttm/grid <fix_ttm>` command, perform
finite difference kinds of operations on the grid, to diffuse electron
heat in the case of the two-temperature model (TTM). This operation
uses ghost grid values beyond the owned grid values the processor
updates. The *set_stencil_grid()* method defines the extent of this
stencil in both directions, assumed to be the same in each of the 3
dimensions. Both the lo and hi values are specified as positive
integers. The default values are both 0.
The kspace_style pppm commands allow a grid to be defined which
overlays a volume which extends beyond the simulation box in the z
dimension. This is for the purpose of modeling a 2d-periodic slab
(non-periodic in z) as if it were a larger 3d periodic system,
extended (with empty space) in the z dimension. The
:doc:`kspace_modify slab <kspace_modify>` command is used to specify
the ratio of the larger volume to the simulation volume; a volume
ratio of ~3 is typical. For this kind of model, the PPPM caller sets
the global grid size *gnz* ~3x larger than it would be otherwise.
This same ratio is passed by the PPPM caller as the *factor* argument
to the Grid class via the *set_zfactor()* method (*set_yfactor()* for
2d grids). The Grid class will then assign ownership of the 1/3 of
grid cells that overlay the simulation box to the processors which
also overlay the simulation box. The remaining 2/3 of the grid cells
are assigned to processors whose sub-domains are adjacent to the upper
z boundary of the simulation box.
----------
Grid class setup_grid method
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The *setup_grid()* method is called after the first constructor
(above) to partition the grid across processors, which determines
which grid cells each processor owns. It also calculates how many
ghost grid cells in each dimension and each direction each processor
needs to store.
Note that this method is NOT called if the second constructor above is
used. In that case, the caller assigns owned and ghost cells to each
processor.
Also note that this method must be invoked after any *set_*()* methods have
been used, since they can influence the assignment of owned and ghost
cells.
.. code-block:: c++
void setup_grid(int &ixlo, int &ixhi, int &iylo, int &iyhi, int &izlo, int &izhi,
int &oxlo, int &oxhi, int &oylo, int &oyhi, int &ozlo, int &ozhi)
The 6 return arguments which start with "i" are the inclusive lower
and upper index bounds of the owned (inner) grid cells this processor
owns in each of the 3 dimensions within the global grid. Owned grid
cells are indexed from 0 to N-1 in each dimension.
The 6 return arguments which start with "o" are the inclusive bounds of
the owned+ghost cells it owns. If the ghost cells are on the other
side of a periodic boundary, then these indices may be < 0 or >= N in
any dimension, so that oxlo <= ixlo and ixhi >= ixhi is always the
case.
----------
More grid class set methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following 2 methods can be used to override settings made by the
constructors above. If used, they must be called called before the
*setup_comm()* method is invoked, since it uses the settings that
these methods override. In LAMMPS these methods are called by by the
:doc:`kspace_style msm <kspace_style>` command for the grids it
instantiates using the 2nd constructor above.
.. code-block:: c++
void set_proc_neighs(int pxlo, int pxhi, int pylo, int pyhi, int pzlo, int pzhi)
void set_caller_grid(int fxlo, int fxhi, int fylo, int fyhi, int fzlo, int fzhi)
The *set_proc_neighs()* method sets the processor IDs of the 6
neighboring processors for each processor. Normally these would match
the processor grid neighbors which LAMMPS creates to overlay the
simulation box (the default). However, MSM excludes non-participating
processors from coarse grid communication when less processors are
used. This method allows MSM to override the default values.
The *set_caller_grid()* method species the size of the data arrays the
caller allocates. Normally these would match the extent of the ghost
grid cells (the default). However the MSM caller allocates a larger
data array (more ghost cells) for its finest-level grid, for use in
other operations besides owned/ghost cell communication. This method
allows MSM to override the default values.
----------
Grid class get methods
^^^^^^^^^^^^^^^^^^^^^^
The following methods allow the caller to query the settings for a
specific grid, whether it created the grid or another command created
it.
.. code-block:: c++
void get_size(int &nxgrid, int &nygrid, int &nzgrid);
void get_bounds_owned(int &xlo, int &xhi, int &ylo, int &yhi, int &zlo, int &zhi)
void get_bounds_ghost(int &xlo, int &xhi, int &ylo, int &yhi, int &zlo, int &zhi)
The *get_size()* method returns the size of the global grid in each dimension.
The *get_bounds_owned()* method return the inclusive index bounds of
the grid cells this processor owns. The values range from 0 to N-1 in
each dimension. These values are the same as the "i" values returned
by *setup_grid()*.
The *get_bounds_ghost()* method return the inclusive index bounds of
the owned+ghost grid cells this processor stores. The owned cell
indices range from 0 to N-1, so these indices may be less than 0 or
greater than or equal to N in each dimension. These values are the
same as the "o" values returned by *setup_grid()*.
----------
Grid class owned/ghost communication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If needed by the command, the following methods setup and perform
communication of grid data to/from neighboring processors. The
*forward_comm()* method sends owned grid cell data to the
corresponding ghost grid cells on other processors. The
*reverse_comm()* method sends ghost grid cell data to the
corresponding owned grid cells on another processor. The caller can
choose to sum ghost grid cell data to the owned grid cell or simply
copy it.
.. code-block:: c++
void setup_comm(int &nbuf1, int &nbuf2)
void forward_comm(int caller, void *ptr, int which, int nper, int nbyte,
void *buf1, void *buf2, MPI_Datatype datatype);
void reverse_comm(int caller, void *ptr, int which, int nper, int nbyte,
void *buf1, void *buf2, MPI_Datatype datatype)
int ghost_adjacent();
The *setup_comm()* method must be called one time before performing
*forward* or *reverse* communication (multiple times if needed). It
returns two integers, which should be used to allocate two buffers.
The *nbuf1* and *nbuf2* values are the number of grid cells whose data
will be stored in two buffers by the Grid class when *forward* or
*reverse* communication is performed. The caller should thus allocate
them to a size large enough to hold all the data used in any single
forward or reverse communication operation it performs. Note that the
caller may allocate and communicate multiple data arrays for a grid it
instantiates. This size includes the bytes needed for the data type
of the grid data it stores, e.g. double precision values.
The *forward_comm()* and *reverse_comm()* methods send grid cell data
from owned to ghost cells, or ghost to owned cells, respectively, as
described above. The *caller* argument should be one of these values
-- Grid3d::COMPUTE, Grid3d::FIX, Grid3d::KSPACE, Grid3d::PAIR --
depending on the style of the caller class. The *ptr* argument is the
"this" pointer to the caller class. These 2 arguments are used to
call back to pack()/unpack() functions in the caller class, as
explained below.
The *which* argument is a flag the caller can set which is passed to
the caller's pack()/unpack() methods. This allows a single callback
method to pack/unpack data for several different flavors of
forward/reverse communication, e.g. operating on different grids or
grid data.
The *nper* argument is the number of values per grid cell to be
communicated. The *nbyte* argument is the number of bytes per value,
e.g. 8 for double-precision values. The *buf1* and *buf2* arguments
are the two allocated buffers described above. So long as they are
allocated for the maximum size communication, they can be re-used for
any *forward_comm()/reverse_comm()* call. The *datatype* argument is
the MPI_Datatype setting, which should match the buffer allocation and
the *nbyte* argument. E.g. MPI_DOUBLE for buffers storing double
precision values.
To use the *forward_grid()* method, the caller must provide two
callback functions; likewise for use of the *reverse_grid()* methods.
These are the 4 functions, their arguments are all the same.
.. code-block:: c++
void pack_forward_grid(int which, void *vbuf, int nlist, int *list);
void unpack_forward_grid(int which, void *vbuf, int nlist, int *list);
void pack_reverse_grid(int which, void *vbuf, int nlist, int *list);
void unpack_reverse_grid(int which, void *vbuf, int nlist, int *list);
The *which* argument is set to the *which* value of the
*forward_comm()* or *reverse_comm()* calls. It allows the pack/unpack
function to select what data values to pack/unpack. *Vbuf* is the
buffer to pack/unpack the data to/from. It is a void pointer so that
the caller can cast it to whatever data type it chooses, e.g. double
precision values. *Nlist* is the number of grid cells to pack/unpack
and *list* is a vector (nlist in length) of offsets to where the data
for each grid cell resides in the caller's data arrays, which is best
illustrated with an example from the src/EXTRA-FIX/fix_ttm_grid.cpp
class which stores the scalar electron temperature for 3d system in a
3d grid (one value per grid cell):
.. code-block:: c++
void FixTTMGrid::pack_forward_grid(int /*which*/, void *vbuf, int nlist, int *list)
{
auto buf = (double *) vbuf;
double *src = &T_electron[nzlo_out][nylo_out][nxlo_out];
for (int i = 0; i < nlist; i++) buf[i] = src[list[i]];
}
In this case, the *which* argument is not used, *vbuf* points to a
buffer of doubles, and the electron temperature is stored by the
FixTTMGrid class in a 3d array of owned+ghost cells called T_electron.
That array is allocated by the *memory->create_3d_offset()* method
described above so that the first grid cell it stores is indexed as
T_electron[nzlo_out][nylo_out][nxlo_out]. The *nlist* values in
*list* are integer offsets from that first grid cell. Setting *src*
to the address of the first cell allows those offsets to be used to
access the temperatures to pack into the buffer.
Here is a similar portion of code from the src/fix_ave_grid.cpp class
which can store two kinds of data, a scalar count of atoms in a grid
cell, and one or more grid-cell-averaged atom properties. The code
from its *unpack_reverse_grid()* function for 2d grids and multiple
per-atom properties per grid cell (*nvalues*) is shown here:
.. code-block:: c++
void FixAveGrid::unpack_reverse_grid(int /*which*/, void *vbuf, int nlist, int *list)
{
auto buf = (double *) vbuf;
double *count,*data,*values;
count = &count2d[nylo_out][nxlo_out];
data = &array2d[nylo_out][nxlo_out][0];
m = 0;
for (i = 0; i < nlist; i++) {
count[list[i]] += buf[m++];
values = &data[nvalues*list[i]];
for (j = 0; j < nvalues; j++)
values[j] += buf[m++];
}
}
Both the count and the multiple values per grid cell are communicated
in *vbuf*. Note that *data* is now a pointer to the first value in
the first grid cell. And *values* points to where the first value in
*data* is for an offset of grid cells, calculated by multiplying
*nvalues* by *list[i]*. Finally, because this is reverse
communication, the communicated buffer values are summed to the caller
values.
The *ghost_adjacent()* method returns a 1 if every processor can
perform the necessary owned/ghost communication with only its nearest
neighbor processors (4 in 2d, 6 in 3d). It returns a 0 if any
processor's ghost cells extend further than nearest neighbor
processors.
This can be checked by callers who have the option to change the
global grid size to insure more efficient nearest-neighbor-only
communication if they wish. In this case, they instantiate a grid of
a given size (resolution), then invoke *setup_comm()* followed by
*ghost_adjacent()*. If the ghost cells are not adjacent, they destroy
the grid instance and start over with a higher-resolution grid.
Several of the :doc:`kspace_style pppm <kspace_style>` command
variants have this option.
----------
Grid class remap methods for load balancing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following methods are used when a load-balancing operation,
triggered by the :doc:`balance <balance>` or :doc:`fix balance
<fix_balance>` commands, changes the partitioning of the simulation
domain into processor sub-domains.
In order to work with load-balancing, any style command (compute, fix,
pair, or kspace style) which allocates a grid and stores per-grid data
should define a *reset_grid()* method; it takes no arguments. It will
be called by the two balance commands after they have reset processor
sub-domains and migrated atoms (particles) to new owning processors.
The *reset_grid()* method will typically perform some or all of the
following operations. See the src/fix_ave_grid.cpp and
src/EXTRA_FIX/fix_ttm_grid.cpp files for examples of *reset_grid()*
methods, as well as the *pack_remap_grid()* and *unpack_remap_grid()*
functions.
First, the *reset_grid()* method can instantiate new grid(s) of the
same global size, then call *setup_grid()* to partition them via the
new processor sub-domains. At this point, it can invoke the
*identical()* method which compares the owned and ghost grid cell
index bounds between two grids, the old grid passed as a pointer
argument, and the new grid whose *identical()* method is being called.
It returns 1 if the indices match on all processors, otherwise 0. If
they all match, then the new grids can be deleted; the command can
continue to use the old grids.
If not, then the command should allocate new grid data array(s) which
depend on the new partitioning. If the command does not need to
persist its grid data from the old partitioning to the new one, then
the command can simply delete the old data array(s) and grid
instance(s). It can then return.
If the grid data does need to persist, then the data for each grid
needs to be "remapped" from the old grid partitioning to the new grid
partitioning. The *setup_remap()* and *remap()* methods are used for
that purpose.
.. code-block:: c++
int identical(Grid3d *old);
void setup_remap(Grid3d *old, int &nremap_buf1, int &nremap_buf2)
void remap(int caller, void *ptr, int which, int nper, int nbyte,
void *buf1, void *buf2, MPI_Datatype datatype)
The arguments to these methods are identical to those for
the *setup_comm()* and *forward_comm()* or *reverse_comm()* methods.
However the returned *nremap_buf1* and *nremap2_buf* values will be
different than the *nbuf1* and *nbuf2* values. They should be used to
allocate two different remap buffers, separate from the owned/ghost
communication buffers.
To use the *remap()* method, the caller must provide two
callback functions:
.. code-block:: c++
void pack_remap_grid(int which, void *vbuf, int nlist, int *list);
void unpack_remap_grid(int which, void *vbuf, int list, int *list);
Their arguments are identical to those for the *pack_forward_grid()*
and *unpack_forward_grid()* callback functions (or the reverse
variants) discussed above. Normally, both these methods pack/unpack
all the data arrays for a given grid. The *which* argument of the
*remap()* method sets the *which* value for the pack/unpack functions.
If the command instantiates multiple grids (of different sizes), it
can be used within the pack/unpack methods to select which grid's data
is being remapped.
Note that the *pack_remap_grid()* function must copy values from the
OLD grid data arrays into the *vbuf* buffer. The *unpack_remap_grid()*
function must copy values from the *vbuf* buffer into the NEW grid
data arrays.
After the remap operation for grid cell data has been performed, the
*reset_grid()* method can deallocate the two remap buffers it created,
and can then exit.
----------
Grid class I/O methods
^^^^^^^^^^^^^^^^^^^^^^
There are two I/O methods in the Grid classes which can be used to
read and write grid cell data to files. The caller can decide on the
precise format of each file, e.g. whether header lines are prepended
or comment lines are allowed. Fundamentally, the file should contain
one line per grid cell for the entire global grid. Each line should
contain identifying info as to which grid cell it is, e.g. a unique
grid cell ID or the ix,iy,iz indices of the cell within a 3d grid.
The line should also contain one or more data values which are stored
within the grid data arrays created by the command
For grid cell IDs, the LAMMPS convention is that the IDs run from 1 to
N, where N = Nx * Ny for 2d grids and N = Nx * Ny * Nz for 3d grids.
The x-index of the grid cell varies fastest, then y, and the z-index
varies slowest. So for a 10x10x10 grid the cell IDs from 901-1000
would be in the top xy layer of the z dimension.
The *read_file()* method does something simple. It reads a chunk of
consecutive lines from the file and passes them back to the caller to
process. The caller provides a *unpack_read_grid()* function for this
purpose. The function checks the grid cell ID or indices and only
stores grid cell data for the grid cells it owns.
The *write_file()* method does something slightly more complex. Each
processor packs the data for its owned grid cells into a buffer. The
caller provides a *pack_write_grid()* function for this purpose. The
*write_file()* method then loops over all processors and each sends
its buffer one at a time to processor 0, along with the 3d (or 2d)
index bounds of its grid cell data within the global grid. Processor
0 calls back to the *unpack_write_grid()* function provided by the
caller with the buffer. The function writes one line per grid cell to
the file.
See the src/EXTRA_FIX/fix_ttm_grid.cpp file for examples of now both
these methods are used to read/write electron temperature values
from/to a file, as well as for implementations of the the pack/unpack
functions described below.
Here are the details of the two I/O methods and the 3 callback
functions. See the src/fix_ave_grid.cpp file for examples of all of
them.
.. code-block:: c++
void read_file(int caller, void *ptr, FILE *fp, int nchunk, int maxline)
void write_file(int caller, void *ptr, int which,
int nper, int nbyte, MPI_Datatype datatype
The *caller* argument in both methods should be one of these values --
Grid3d::COMPUTE, Grid3d::FIX, Grid3d::KSPACE, Grid3d::PAIR --
depending on the style of the caller class. The *ptr* argument in
both methods is the "this" pointer to the caller class. These 2
arguments are used to call back to pack()/unpack() functions in the
caller class, as explained below.
For the *read_file()* method, the *fp* argument is a file pointer to
the file to be read from, opened on processor 0 by the caller.
*Nchunk* is the number of lines to read per chunk, and *maxline* is
the maximum number of characters per line. The Grid class will
allocate a buffer for storing chunks of lines based on these values.
For the *write_file()* method, the *which* argument is a flag the
caller can set which is passed back to the caller's pack()/unpack()
methods. If the command instantiates multiple grids (of different
sizes), this flag can be used within the pack/unpack methods to select
which grid's data is being written out (presumably to different
files). the *nper* argument is the number of values per grid cell to
be written out. The *nbyte* argument is the number of bytes per
value, e.g. 8 for double-precision values. The *datatype* argument is
the MPI_Datatype setting, which should match the *nbyte* argument.
E.g. MPI_DOUBLE for double precision values.
To use the *read_grid()* method, the caller must provide one callback
function. To use the *write_grid()* method, it provides two callback
functions:
.. code-block:: c++
int unpack_read_grid(int nlines, char *buffer)
void pack_write_grid(int which, void *vbuf)
void unpack_write_grid(int which, void *vbuf, int *bounds)
For *unpack_read_grid()* the *nlines* argument is the number of lines
of character data read from the file and contained in *buffer*. The
lines each include a newline character at the end. When the function
processes the lines, it may choose to skip some of them (header or
comment lines). It returns an integer count of the number of grid
cell lines it processed. This enables the Grid class *read_file()*
method to know when it has read the correct number of lines.
For *pack_write_grid()* and *unpack_write_grid()*, the *vbuf* argument
is the buffer to pack/unpack data to/from. It is a void pointer so
that the caller can cast it to whatever data type it chooses,
e.g. double precision values. the *which* argument is set to the
*which* value of the *write_file()* method. It allows the caller to
choose which grid data to operate on.
For *unpack_write_grid()*, the *bounds* argument is a vector of 4 or 6
integer grid indices (4 for 2d, 6 for 3d). They are the
xlo,xhi,ylo,yhi,zlo,zhi index bounds of the portion of the global grid
which the *vbuf* holds owned grid cell data values for. The caller
should loop over the values in *vbuf* with a double loop (2d) or
triple loop (3d), similar to the code snippets listed above. The
x-index varies fastest, then y, and the z-index slowest. If there are
multiple values per grid cell, the index for those values varies
fastest of all. The caller can add the x,y,z indices of the grid cell
(or the corresponding grid cell ID) to the data value(s) written as
one line to the output file.
----------
Style class grid access methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A style command can enable its grid cell data to be accessible from
other commands. For example :doc:`fix ave/grid <fix_ave_grid>` or
:doc:`dump grid <dump>` or :doc:`dump grid/vtk <dump>`. Those
commands access the grid cell data by using a *grid reference* in
their input script syntax, as described on the :doc:`Howto_grid
<Howto_grid>` doc page. They look like this:
* c_ID:gname:dname
* c_ID:gname:dname[I]
* f_ID:gname:dname
* f_ID:gname:dname[I]
Each grid a command instantiates has a unique *gname*, defined by the
command. Likewise each grid cell data structure (scalar or vector)
associated with a grid has a unique *dname*, also defined by the
command.
To provide access to its grid cell data, a style command needs to
implement the following 4 methods:
.. code-block:: c++
int get_grid_by_name(const std::string &name, int &dim);
void *get_grid_by_index(int index);
int get_griddata_by_name(int igrid, const std::string &name, int &ncol);
void *get_griddata_by_index(int index);
Currently only computes and fixes can implement these methods. If it
does so, the compute of fix should also set the variable
*pergrid_flag* to 1. See any of the compute or fix commands which set
"pergrid_flag = 1" for examples of how these 4 functions can be
implemented.
The *get_grid_by_name()* method takes a grid name as input and returns
two values. The *dim* argument is returned as 2 or 3 for the
dimensionality of the grid. The function return is a grid index from
0 to G-1 where *G* is the number of grids the command instantiates. A
value of -1 is returned if the grid name is not recognized.
The *get_grid_by_index()* method is called after the
*get_grid_by_name()* method, using the grid index it returned as its
argument. This method will return a pointer to the Grid2d or Grid3d
class. The caller can use this to query grid attributes, such as the
global size of the grid. The :doc:`dump grid <dump>` to insure each
its grid reference arguments are for grids of the same size.
The *get_griddata_by_name()* method takes a grid index *igrid* and a
data name as input. It returns two values. The *ncol* argument is
returned as a 0 if the grid data is a single value (scalar) per grid
cell, or an integer M > 0 if there are M values (vector) per grid
cell. Note that even if M = 1, it is still a 1-length vector, not a
scalar. The function return is a data index from 0 to D-1 where *D*
is the number of data sets associated with that grid by the command.
A value of -1 is returned if the data name is not recognized.
The *get_griddata_by_index()* method is called after the
*get_griddata_by_name()* method, using the data index it returned as
its argument. This method will return a pointer to the
multi-dimensional array which stores the requested data.
As in the discussion above of the Memory class *create_offset()*
methods, the dimensionality of the array associated with the returned
pointer depends on whether it is a 2d or 3d grid and whether there is
a single or multiple values stored for each grid cell:
* single value per cell for a 2d grid = 2d array pointer
* multiple values per cell for a 2d grid = 3d array pointer
* single value per cell for a 3d grid = 3d array pointer
* multiple values per cell for a 3d grid = 4d array pointer
The caller will typically access the data by casting the void pointer
to the corresponding array pointer and using nested loops in x,y,z
between owned or ghost index bounds returned by the
*get_bounds_owned()* or *get_bounds_ghost()* methods to index into the
array. Example code snippets with this logic were listed above,
----------
Final notes
^^^^^^^^^^^
Finally, here are some additional issues to pay attention to for
writing any style command which uses distributed grids via the Grid2d
or Grid3d class.
The command destructor should delete all instances of the Grid class,
any buffers it allocated for forward/reverse or remap communication,
and any data arrays it allocated to store grid cell data.
If a command is intended to work for either 2d or 3d simulations, then
it should have logic to instantiate either 2d or 3d grids and their
associated data arrays, depending on the dimension of the simulation
box. The :doc:`fix ave/grid <fix_ave_grid>` command is an example of
such a command.
When a command maps its particles to the grid and updates grid cell
values, it should check that it is not updating or accessing a grid
cell value outside the range of its owned+ghost cells, and generate an
error message if that is the case. This could happen, for example, if
a particle has moved further than half the neighbor skin distance,
because the neighbor list update criterion are not adequate to prevent
it from happening. See the src/KSPACE/pppm.cpp file and its
*particle_map()* method for an example of this kind of error check.

16
doc/src/Developer_notes.rst
View File

@ -105,7 +105,7 @@ list, where each pair of atoms is listed only once (except when the
pairs straddling sub-domains or periodic boundaries will be listed twice).
Thus these are the default settings when a neighbor list request is created in:
.. code-block:: C++
.. code-block:: c++
void Pair::init_style()
{
@ -129,7 +129,7 @@ neighbor list request to the specific needs of a style an additional
request flag is needed. The :doc:`tersoff <pair_tersoff>` pair style,
for example, needs a "full" neighbor list:
.. code-block:: C++
.. code-block:: c++
void PairTersoff::init_style()
{
@ -141,7 +141,7 @@ When a pair style supports r-RESPA time integration with different cutoff region
the request flag may depend on the corresponding r-RESPA settings. Here an example
from pair style lj/cut:
.. code-block:: C++
.. code-block:: c++
void PairLJCut::init_style()
{
@ -160,7 +160,7 @@ Granular pair styles need neighbor lists based on particle sizes and not cutoff
and also may require to have the list of previous neighbors available ("history").
For example with:
.. code-block:: C++
.. code-block:: c++
if (use_history) neighbor->add_request(this, NeighConst::REQ_SIZE | NeighConst::REQ_HISTORY);
else neighbor->add_request(this, NeighConst::REQ_SIZE);
@ -170,7 +170,7 @@ settings each request can set an id which is then used in the corresponding
``init_list()`` function to assign it to the suitable pointer variable. This is
done for example by the :doc:`pair style meam <pair_meam>`:
.. code-block:: C++
.. code-block:: c++
void PairMEAM::init_style()
{
@ -189,7 +189,7 @@ just once) and this can also be indicated by a flag. As an example here
is the request from the ``FixPeriNeigh`` class which is created
internally by :doc:`Peridynamics pair styles <pair_peri>`:
.. code-block:: C++
.. code-block:: c++
neighbor->add_request(this, NeighConst::REQ_FULL | NeighConst::REQ_OCCASIONAL);
@ -198,7 +198,7 @@ than what is usually inferred from the pair style settings (largest cutoff of
all pair styles plus neighbor list skin). The following is used in the
:doc:`compute rdf <compute_rdf>` command implementation:
.. code-block:: C++
.. code-block:: c++
if (cutflag)
neighbor->add_request(this, NeighConst::REQ_OCCASIONAL)->set_cutoff(mycutneigh);
@ -212,7 +212,7 @@ for printing the neighbor list summary the name of the requesting command
should be set. Below is the request from the :doc:`delete atoms <delete_atoms>`
command:
.. code-block:: C++
.. code-block:: c++
neighbor->add_request(this, "delete_atoms", NeighConst::REQ_FULL);

6
doc/src/Developer_parallel.rst
View File

@ -3,9 +3,9 @@ Parallel algorithms
LAMMPS is designed to enable running simulations in parallel using the
MPI parallel communication standard with distributed data via domain
decomposition. The parallelization aims to be efficient result in good
strong scaling (= good speedup for the same system) and good weak
scaling (= the computational cost of enlarging the system is
decomposition. The parallelization aims to be efficient, and resulting
in good strong scaling (= good speedup for the same system) and good
weak scaling (= the computational cost of enlarging the system is
proportional to the system size). Additional parallelization using GPUs
or OpenMP can also be applied within the sub-domain assigned to an MPI
process. For clarity, most of the following illustrations show the 2d

6
doc/src/Developer_plugins.rst
View File

@ -95,7 +95,7 @@ a class ``PairMorse2`` in the files ``pair_morse2.h`` and
``pair_morse2.cpp`` with the factory function and initialization
function would look like this:
.. code-block:: C++
.. code-block:: c++
#include "lammpsplugin.h"
#include "version.h"
@ -141,7 +141,7 @@ list of argument strings), then the pointer type is ``lammpsplugin_factory2``
and it must be assigned to the *creator.v2* member of the plugin struct.
Below is an example for that:
.. code-block:: C++
.. code-block:: c++
#include "lammpsplugin.h"
#include "version.h"
@ -176,7 +176,7 @@ demonstrated in the following example, which also shows that the
implementation of the plugin class may be within the same source
file as the plugin interface code:
.. code-block:: C++
.. code-block:: c++
#include "lammpsplugin.h"

10
doc/src/Developer_unittest.rst
View File

@ -194,7 +194,7 @@ macro. These tests operate by capturing the screen output when executing
the failing command and then comparing that with a provided regular
expression string pattern. Example:
.. code-block:: C++
.. code-block:: c++
TEST_F(SimpleCommandsTest, UnknownCommand)
{
@ -249,7 +249,7 @@ MPI support. These include tests where LAMMPS is run in multi-partition
mode or only on a subset of the MPI world communicator. The CMake
script code for adding this kind of test looks like this:
.. code-block:: CMake
.. code-block:: cmake
if (BUILD_MPI)
add_executable(test_library_mpi test_library_mpi.cpp)
@ -489,7 +489,7 @@ to update the YAML files. Running a command like
.. code-block:: bash
$ test_pair_style mol-pair-lennard_mdf.yaml -g new.yaml
test_pair_style mol-pair-lennard_mdf.yaml -g new.yaml
will read the settings from the ``mol-pair-lennard_mdf.yaml`` file and then compute
the reference data and write a new file with to ``new.yaml``. If this step fails,
@ -500,13 +500,13 @@ It is also possible to do an update in place with:
.. code-block:: bash
$ test_pair_style mol-pair-lennard_mdf.yaml -u
test_pair_style mol-pair-lennard_mdf.yaml -u
And one can finally run the full set of tests with:
.. code-block:: bash
$ test_pair_style mol-pair-lennard_mdf.yaml
test_pair_style mol-pair-lennard_mdf.yaml
This will just print a summary of the groups of tests. When using the "-v" flag
the test will also keep any LAMMPS output and when using the "-s" flag, there

98
doc/src/Developer_updating.rst
View File

@ -25,6 +25,7 @@ Available topics in mostly chronological order are:
- `Simplified and more compact neighbor list requests`_
- `Split of fix STORE into fix STORE/GLOBAL and fix STORE/PERATOM`_
- `Use Output::get_dump_by_id() instead of Output::find_dump()`_
- `Refactored grid communication using Grid3d/Grid2d classes instead of GridComm`_
----
@ -61,7 +62,7 @@ header file needs to be updated accordingly.
Old:
.. code-block:: C++
.. code-block:: c++
int PairEAM::pack_comm(int n, int *list, double *buf, int pbc_flag, int *pbc)
{
@ -75,7 +76,7 @@ Old:
New:
.. code-block:: C++
.. code-block:: c++
int PairEAM::pack_forward_comm(int n, int *list, double *buf, int pbc_flag, int *pbc)
{
@ -112,14 +113,14 @@ Example from a pair style:
Old:
.. code-block:: C++
.. code-block:: c++
if (eflag || vflag) ev_setup(eflag, vflag);
else evflag = vflag_fdotr = eflag_global = eflag_atom = 0;
New:
.. code-block:: C++
.. code-block:: c++
ev_init(eflag, vflag);
@ -142,14 +143,14 @@ when they are called from only one or a subset of the MPI processes.
Old:
.. code-block:: C++
.. code-block:: c++
val = force->numeric(FLERR, arg[1]);
num = force->inumeric(FLERR, arg[2]);
New:
.. code-block:: C++
.. code-block:: c++
val = utils::numeric(FLERR, true, arg[1], lmp);
num = utils::inumeric(FLERR, false, arg[2], lmp);
@ -183,14 +184,14 @@ copy them around for simulations.
Old:
.. code-block:: C++
.. code-block:: c++
fp = force->open_potential(filename);
fp = fopen(filename, "r");
New:
.. code-block:: C++
.. code-block:: c++
fp = utils::open_potential(filename, lmp);
@ -207,7 +208,7 @@ Example:
Old:
.. code-block:: C++
.. code-block:: c++
if (fptr == NULL) {
char str[128];
@ -217,7 +218,7 @@ Old:
New:
.. code-block:: C++
.. code-block:: c++
if (fptr == nullptr)
error->one(FLERR, "Cannot open AEAM potential file {}: {}", filename, utils::getsyserror());
@ -237,7 +238,7 @@ an example from the ``FixWallReflect`` class:
Old:
.. code-block:: C++
.. code-block:: c++
FixWallReflect(class LAMMPS *, int, char **);
virtual ~FixWallReflect();
@ -247,7 +248,7 @@ Old:
New:
.. code-block:: C++
.. code-block:: c++
FixWallReflect(class LAMMPS *, int, char **);
~FixWallReflect() override;
@ -271,7 +272,7 @@ the type of the "this" pointer argument.
Old:
.. code-block:: C++
.. code-block:: c++
comm->forward_comm_pair(this);
comm->forward_comm_fix(this);
@ -284,7 +285,7 @@ Old:
New:
.. code-block:: C++
.. code-block:: c++
comm->forward_comm(this);
comm->reverse_comm(this);
@ -304,7 +305,7 @@ requests can be :doc:`found here <Developer_notes>`. Example from the
Old:
.. code-block:: C++
.. code-block:: c++
int irequest = neighbor->request(this,instance_me);
neighbor->requests[irequest]->pair = 0;
@ -317,7 +318,7 @@ Old:
New:
.. code-block:: C++
.. code-block:: c++
auto req = neighbor->add_request(this, NeighConst::REQ_OCCASIONAL);
if (cutflag) req->set_cutoff(mycutneigh);
@ -340,7 +341,7 @@ these are internal fixes, there is no user visible change.
Old:
.. code-block:: C++
.. code-block:: c++
#include "fix_store.h"
@ -351,7 +352,7 @@ Old:
New:
.. code-block:: C++
.. code-block:: c++
#include "fix_store_peratom.h"
@ -362,7 +363,7 @@ New:
Old:
.. code-block:: C++
.. code-block:: c++
#include "fix_store.h"
@ -373,7 +374,7 @@ Old:
New:
.. code-block:: C++
.. code-block:: c++
#include "fix_store_global.h"
@ -396,7 +397,7 @@ the dump directly. Example:
Old:
.. code-block:: C++
.. code-block:: c++
int idump = output->find_dump(arg[iarg+1]);
if (idump < 0)
@ -412,7 +413,7 @@ Old:
New:
.. code-block:: C++
.. code-block:: c++
auto idump = output->get_dump_by_id(arg[iarg+1]);
if (!idump) error->all(FLERR,"Dump ID {} in hyper command does not exist", arg[iarg+1]);
@ -423,3 +424,56 @@ New:
if (dumpflag) for (auto idump : dumplist) idump->write();
This change is **required** or else the code will not compile.
Refactored grid communication using Grid3d/Grid2d classes instead of GridComm
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionchanged:: 22Dec2022
The ``GridComm`` class was for creating and communicating distributed
grids was replaced by the ``Grid3d`` class with added functionality.
A ``Grid2d`` class was also added for additional flexibility.
The new functionality and commands using the two grid classes are
discussed on the following documentation pages:
- :doc:`Howto_grid`
- :doc:`Developer_grid`
If you have custom LAMMPS code, which uses the GridComm class, here are some notes
on how to adapt it for using the Grid3d class.
(1) The constructor has changed to allow the ``Grid3d`` / ``Grid2d``
classes to partition the global grid across processors, both for
owned and ghost grid cells. Previously any class which called
``GridComm`` performed the partitioning itself and that information
was passed in the ``GridComm::GridComm()`` constructor. There are
several "set" functions which can be called to alter how ``Grid3d``
/ ``Grid2d`` perform the partitioning. They should be sufficient
for most use cases of the grid classes.
(2) The partitioning is triggered by the ``setup_grid()`` method.
(3) The ``setup()`` method of the ``GridComm`` class has been replaced
by the ``setup_comm()`` method in the new grid classes. The syntax
for the ``forward_comm()`` and ``reverse_comm()`` methods is
slightly altered as is the syntax of the associated pack/unpack
callback methods. But the functionality of these operations is the
same as before.
(4) The new ``Grid3d`` / ``Grid2d`` classes have additional
functionality for dynamic load-balancing of grids and their
associated data across processors. This did not exist in the
``GridComm`` class.
This and more is explained in detail on the :doc:`Developer_grid` page.
The following LAMMPS source files can be used as illustrative examples
for how the new grid classes are used by computes, fixes, and various
KSpace solvers which use distributed FFT grids:
- ``src/fix_ave_grid.cpp``
- ``src/compute_property_grid.cpp``
- ``src/EXTRA-FIX/fix_ttm_grid.cpp``
- ``src/KSPACE/pppm.cpp``
This change is **required** or else the code will not compile.

16
doc/src/Developer_utils.rst
View File

@ -133,6 +133,9 @@ and parsing files or arguments.
.. doxygenfunction:: trim_comment
:project: progguide
.. doxygenfunction:: strip_style_suffix
:project: progguide
.. doxygenfunction:: star_subst
:project: progguide
@ -211,6 +214,9 @@ Argument processing
.. doxygenfunction:: expand_args
:project: progguide
.. doxygenfunction:: parse_grid_id
:project: progguide
.. doxygenfunction:: expand_type
:project: progguide
@ -317,7 +323,7 @@ are all "whitespace" characters, i.e. the space character, the tabulator
character, the carriage return character, the linefeed character, and
the form feed character.
.. code-block:: C++
.. code-block:: c++
:caption: Tokenizer class example listing entries of the PATH environment variable
#include "tokenizer.h"
@ -349,7 +355,7 @@ tokenizer into a ``try`` / ``catch`` block to handle errors. The
when a (type of) number is requested as next token that is not
compatible with the string representing the next word.
.. code-block:: C++
.. code-block:: c++
:caption: ValueTokenizer class example with exception handling
#include "tokenizer.h"
@ -427,7 +433,7 @@ one or two array indices "[<number>]" with numbers > 0.
A typical code segment would look like this:
.. code-block:: C++
.. code-block:: c++
:caption: Usage example for ArgInfo class
int nvalues = 0;
@ -476,7 +482,7 @@ open the file, and will call the :cpp:class:`LAMMPS_NS::Error` class in
case of failures to read or to convert numbers, so that LAMMPS will be
aborted.
.. code-block:: C++
.. code-block:: c++
:caption: Use of PotentialFileReader class in pair style coul/streitz
PotentialFileReader reader(lmp, file, "coul/streitz");
@ -555,7 +561,7 @@ chunk size needs to be known in advance, 2) with :cpp:func:`MyPage::vget()
its size is registered later with :cpp:func:`MyPage::vgot()
<LAMMPS_NS::MyPage::vgot>`.
.. code-block:: C++
.. code-block:: c++
:caption: Example of using :cpp:class:`MyPage <LAMMPS_NS::MyPage>`
#include "my_page.h"

14
doc/src/Developer_write.rst
View File

@ -26,7 +26,7 @@ constructor with the signature: ``FixPrintVel(class LAMMPS *, int, char **)``.
Every fix must be registered in LAMMPS by writing the following lines
of code in the header before include guards:
.. code-block:: c
.. code-block:: c++
#ifdef FIX_CLASS
// clang-format off
@ -47,7 +47,7 @@ keyword when it parses the input script.
Let's write a simple fix which will print the average velocity at the end
of each timestep. First of all, implement a constructor:
.. code-block:: C++
.. code-block:: c++
FixPrintVel::FixPrintVel(LAMMPS *lmp, int narg, char **arg)
: Fix(lmp, narg, arg)
@ -72,7 +72,7 @@ in the Fix class called ``nevery`` which specifies how often the method
The next method we need to implement is ``setmask()``:
.. code-block:: C++
.. code-block:: c++
int FixPrintVel::setmask()
{
@ -87,7 +87,7 @@ during execution. The constant ``END_OF_STEP`` corresponds to the
are called during a timestep and the order in which they are called
are shown in the previous section.
.. code-block:: C++
.. code-block:: c++
void FixPrintVel::end_of_step()
{
@ -143,7 +143,7 @@ The group membership information of an atom is contained in the *mask*
property of and atom and the bit corresponding to a given group is
stored in the groupbit variable which is defined in Fix base class:
.. code-block:: C++
.. code-block:: c++
for (int i = 0; i < nlocal; ++i) {
if (atom->mask[i] & groupbit) {
@ -174,7 +174,7 @@ to store positions of atoms from previous timestep, we need to add
``double** xold`` to the header file. Than add allocation code
to the constructor:
.. code-block:: C++
.. code-block:: c++
FixSavePos::FixSavePos(LAMMPS *lmp, int narg, char **arg), xold(nullptr)
{
@ -190,7 +190,7 @@ to the constructor:
Implement the aforementioned methods:
.. code-block:: C++
.. code-block:: c++
double FixSavePos::memory_usage()
{

13
doc/src/Errors_debug.rst
View File

@ -40,7 +40,7 @@ We use it to show how to identify the origin of a segmentation fault.
After recompiling LAMMPS and running the input you should get something like this:
.. code-block::
.. code-block:: console
$ ./lmp -in in.melt
LAMMPS (19 Mar 2020)
@ -90,8 +90,9 @@ it. When it reaches the code causing the segmentation fault, it will
stop with a message why it stopped, print the current line of code, and
drop back to the GDB prompt.
.. code-block::
.. code-block:: console
(gdb) run
[...]
Setting up Verlet run ...
Unit style : lj
@ -106,7 +107,7 @@ drop back to the GDB prompt.
Now typing the command "where" will show the stack of functions starting from
the current function back to "main()".
.. code-block::
.. code-block:: console
(gdb) where
#0 0x00000000006653ab in LAMMPS_NS::PairLJCut::compute (this=0x829740, eflag=1, vflag=<optimized out>) at /home/akohlmey/compile/lammps/src/pair_lj_cut.cpp:139
@ -124,7 +125,7 @@ You can also print the value of variables and see if there is anything
unexpected. Segmentation faults, for example, commonly happen when a
pointer variable is not assigned and still initialized to NULL.
.. code-block::
.. code-block:: console
(gdb) print x
$1 = (double **) 0x7ffff7ca1010
@ -153,7 +154,7 @@ utility to the current folder. Example: ``coredumpctl -o core dump lmp``.
Now you can launch the debugger to load the executable, its debug info
and the core dump and drop you to a prompt like before.
.. code-block::
.. code-block:: console
$ gdb lmp core
Reading symbols from lmp...
@ -186,7 +187,7 @@ recommended to redirect the valgrind output to a file (e.g. with
process ID) so that the messages of the multiple valgrind instances to
the console are not mixed.
.. code-block::
.. code-block:: console
$ valgrind ./lmp -in in.melt
==1933642== Memcheck, a memory error detector

854
doc/src/Fortran.rst
View File

File diff suppressed because it is too large Load Diff

1
doc/src/Howto.rst
View File

@ -51,6 +51,7 @@ Analysis howto
Howto_output
Howto_chunk
Howto_grid
Howto_temperature
Howto_elastic
Howto_kappa

10
doc/src/Howto_amoeba.rst
View File

@ -261,11 +261,11 @@ all the options available to use with the tinker2lmp.py script:
.. code-block:: bash
% python tinker2lmp.py -xyz water_dimer.xyz -amoeba amoeba_water.prm -data data.water_dimer.amoeba # AMOEBA non-periodic system
% python tinker2lmp.py -xyz water_dimer.xyz -hippo hippo_water.prm -data data.water_dimer.hippo # HIPPO non-periodic system
% python tinker2lmp.py -xyz water_box.xyz -amoeba amoeba_water.prm -data data.water_box.amoeba -pbc 18.643 18.643 18.643 # AMOEBA periodic system
% python tinker2lmp.py -xyz water_box.xyz -hippo hippo_water.prm -data data.water_box.hippo -pbc 18.643 18.643 18.643 # HIPPO periodic system
% python tinker2lmp.py -xyz ubiquitin.xyz -amoeba amoeba_ubiquitin.prm -data data.ubiquitin.new -pbc 54.99 41.91 41.91 -bitorsion bitorsion.ubiquitin.data.new # system with bitorsions
python tinker2lmp.py -xyz water_dimer.xyz -amoeba amoeba_water.prm -data data.water_dimer.amoeba # AMOEBA non-periodic system
python tinker2lmp.py -xyz water_dimer.xyz -hippo hippo_water.prm -data data.water_dimer.hippo # HIPPO non-periodic system
python tinker2lmp.py -xyz water_box.xyz -amoeba amoeba_water.prm -data data.water_box.amoeba -pbc 18.643 18.643 18.643 # AMOEBA periodic system
python tinker2lmp.py -xyz water_box.xyz -hippo hippo_water.prm -data data.water_box.hippo -pbc 18.643 18.643 18.643 # HIPPO periodic system
python tinker2lmp.py -xyz ubiquitin.xyz -amoeba amoeba_ubiquitin.prm -data data.ubiquitin.new -pbc 54.99 41.91 41.91 -bitorsion bitorsion.ubiquitin.data.new # system with bitorsions
Switches and their arguments may be specified in any order.

6
doc/src/Howto_cmake.rst
View File

@ -46,7 +46,7 @@ This tutorial assumes that you are operating in a command-line environment
using a shell like Bash.
- Linux: any Terminal window will work
- MacOS X: launch the Terminal application.
- macOS: launch the Terminal application.
- Windows 10: install and run the :doc:`Windows Subsystem for Linux <Howto_wsl>`
We also assume that you have downloaded and unpacked a recent LAMMPS source code package
@ -56,7 +56,7 @@ You should change into the top level directory of the LAMMPS source tree all
paths mentioned in the tutorial are relative to that. Immediately after downloading
it should look like this:
.. code-block:: bash
.. code-block:: console
$ ls
bench doc lib potentials README tools
@ -104,7 +104,7 @@ the progress of the configuration printed to the screen followed by a
summary of the enabled features, options and compiler settings. A typical
summary screen will look like this:
.. code-block::
.. code-block:: console
$ cmake ../cmake/
-- The CXX compiler identification is GNU 8.2.0

61
doc/src/Howto_github.rst
View File

@ -78,13 +78,13 @@ machine via HTTPS:
.. code-block:: bash
$ git clone https://github.com/<your user name>/lammps.git <some name>
git clone https://github.com/<your user name>/lammps.git <some name>
or, if you have set up your GitHub account for using SSH keys, via SSH:
.. code-block:: bash
$ git clone git@github.com:<your user name>/lammps.git
git clone git@github.com:<your user name>/lammps.git
You can find the proper URL by clicking the "Clone or download"-button:
@ -103,21 +103,21 @@ and use git pull:
.. code-block:: bash
$ cd mylammps
$ git checkout develop
$ git pull https://github.com/lammps/lammps develop
cd mylammps
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 upstream https://www.github.com/lammps/lammps
git remote add upstream https://www.github.com/lammps/lammps
From then on you can update your upstream branches with:
.. code-block:: bash
$ git fetch upstream
git fetch upstream
and then refer to the upstream repository branches with
`upstream/develop` or `upstream/release` and so on.
@ -129,8 +129,8 @@ workflow that updated this tutorial, and hence we will call the branch
.. code-block:: bash
$ git fetch upstream
$ git checkout -b github-tutorial-update upstream/develop
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,
@ -150,8 +150,8 @@ After everything is done, add the files to the branch and commit them:
.. code-block:: bash
$ git add doc/src/Howto_github.txt
$ git add doc/src/JPG/tutorial*.png
git add doc/src/Howto_github.txt
git add doc/src/JPG/tutorial*.png
.. warning::
@ -174,13 +174,13 @@ useful message that explains the change.
.. code-block:: bash
$ git commit -m 'Finally updated the GitHub tutorial'
git commit -m 'Finally updated the GitHub tutorial'
After the commit, the changes can be pushed to the same branch on GitHub:
.. code-block:: bash
$ git push
git push
Git will ask you for your user name and password on GitHub if you have
not configured anything. If your local branch is not present on GitHub yet,
@ -188,7 +188,7 @@ it will ask you to add it by running
.. code-block:: bash
$ git push --set-upstream origin github-tutorial-update
git push --set-upstream origin github-tutorial-update
If you correctly type your user name and
password, the feature branch should be added to your fork on GitHub.
@ -198,13 +198,13 @@ If you want to make really sure you push to the right repository
.. code-block:: bash
$ git push origin
git push origin
or using an explicit URL:
.. code-block:: bash
$ git push git@github.com:Pakketeretet2/lammps.git
git push git@github.com:Pakketeretet2/lammps.git
----------
@ -412,10 +412,10 @@ we need to pull Axel's change back into our branch, and merge them:
.. code-block:: bash
$ git add Howto_github.txt
$ git add JPG/tutorial_reverse_pull_request*.png
$ git commit -m "Updated text and images on reverse pull requests"
$ git pull
git add Howto_github.txt
git add JPG/tutorial_reverse_pull_request*.png
git commit -m "Updated text and images on reverse pull requests"
git pull
In this case, the merge was painless because git could auto-merge:
@ -428,10 +428,10 @@ commit and push again:
.. code-block:: bash
$ git add Howto_github.txt
$ git add JPG/tutorial_reverse_pull_request6.png
$ git commit -m "Merged Axel's suggestions and updated text"
$ git push git@github.com:Pakketeretet2/lammps
git add Howto_github.txt
git add JPG/tutorial_reverse_pull_request6.png
git commit -m "Merged Axel's suggestions and updated text"
git push git@github.com:Pakketeretet2/lammps
This merge also shows up on the lammps GitHub page:
@ -456,9 +456,9 @@ branch!
.. code-block:: bash
$ git checkout develop
$ git pull https://github.com/lammps/lammps develop
$ git branch -d github-tutorial-update
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
you at the next statement that you are deleting a local branch that
@ -472,7 +472,7 @@ to your remote(s) as well:
.. code-block:: bash
$ git push origin :github-tutorial-update
git push origin :github-tutorial-update
**Recent changes in the workflow**
@ -486,5 +486,6 @@ 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/develop/doc/github-development-workflow.md>`_
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/develop/doc/github-development-workflow.md>`_

102
doc/src/Howto_grid.rst Normal file
View File

@ -0,0 +1,102 @@
Using distributed grids
=======================
.. versionadded:: 22Dec2022
LAMMPS has internal capabilities to create uniformly spaced grids
which overlay the simulation domain. For 2d and 3d simulations these
are 2d and 3d grids respectively. Conceptually a grid can be thought
of as a collection of grid cells. Each grid cell can store one or
more values (data).
The grid cells and data they store are distributed across processors.
Each processor owns the grid cells (and data) whose center points lie
within the spatial sub-domain of the processor. If needed for its
computations, a processor may also store ghost grid cells with their
data.
Distributed grids can overlay orthogonal or triclinic simulation
boxes; see the :doc:`Howto triclinic <Howto_triclinic>` doc page for
an explanation of the latter. For a triclinic box, the grid cell
shape conforms to the shape of the simulation domain,
e.g. parallelograms instead of rectangles in 2d.
If the box size or shape changes during a simulation, the grid changes
with it, so that it always overlays the entire simulation domain. For
non-periodic dimensions, the grid size in that dimension matches the
box size, as set by the :doc:`boundary <boundary>` command for fixed
or shrink-wrapped boundaries.
If load-balancing is invoked by the :doc:`balance <balance>` or
:doc:`fix balance <fix_balance>` commands, then the sub-domain owned
by a processor can change which may also change which grid cells they
own.
Post-processing and visualization of grid cell data can be enabled by
the :doc:`dump grid <dump>`, :doc:`dump grid/vtk <dump>`, and
:doc:`dump image <dump_image>` commands. The latter has an optional
*grid* keyword. The `OVITO visualization tool
<https://www.ovito.org>`_ also plans (as of Nov 2022) to add support
for visualizing grid cell data (along with atoms) using :doc:`dump
grid <dump>` output files as input.
.. note::
For developers, distributed grids are implemented within the code via
two classes: Grid2d and Grid3d. These partition the grid across
processors and have methods which allow forward and reverse
communication of ghost grid data as well as load balancing. If you
write a new compute or fix which needs a distributed grid, these are
the classes to look at. A new pair style could use a distributed
grid by having a fix define it. Please see the section on
:doc:`using distributed grids within style classes <Developer_grid>`
for a detailed description.
----------
These are the commands which currently define or use distributed
grids:
* :doc:`fix ttm/grid <fix_ttm>` - store electron temperature on grid
* :doc:`fix ave/grid <fix_ave_grid>` - time average per-atom or per-grid values
* :doc:`compute property/grid <compute_property_grid>` - generate grid IDs and coords
* :doc:`dump grid <dump>` - output per-grid values in LAMMPS format
* :doc:`dump grid/vtk <dump>` - output per-grid values in VTK format
* :doc:`dump image grid <dump_image>` - include colored grid in output images
* :doc:`pair_style amoeba <pair_amoeba>` - FFT grids
* :doc:`kspace_style pppm <kspace_style>` (and variants) - FFT grids
* :doc:`kspace_style msm <kspace_style>` (and variants) - MSM grids
The grids used by the :doc:`kspace_style <kspace_style>` can not be
referenced by an input script. However the grids and data created and
used by the other commands can be.
A compute or fix command may create one or more grids (of different
sizes). Each grid can store one or more data fields. A data field
can be a single value per grid point (per-grid vector) or multiple
values per grid point (per-grid array). See the :doc:`Howto output
<Howto_output>` doc page for an explanation of how per-grid data can
be generated by some commands and used by other commands.
A command accesses grid data from a compute or fix using a *grid
reference* with the following syntax:
* c_ID:gname:dname
* c_ID:gname:dname[I]
* f_ID:gname:dname
* f_ID:gname:dname[I]
The prefix "c\_" or "f\_" refers to the ID of the compute or fix; gname is
the name of the grid, which is assigned by the compute or fix; dname is
the name of the data field, which is also assigned by the compute or
fix.
If the data field is a per-grid vector (one value per grid point),
then no brackets are used to access the values. If the data field is
a per-grid array (multiple values per grid point), then brackets are
used to specify the column I of the array. I ranges from 1 to Ncol
inclusive, where Ncol is the number of columns in the array and is
defined by the compute or fix.
Currently, there are no per-grid variables implemented in LAMMPS. We
may add this feature at some point.

26
doc/src/Howto_mdi.rst
View File

@ -134,18 +134,18 @@ used in stand-alone mode:
.. code-block:: bash
% git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
% build the executable pw.x, following the `QE build guide <https://gitlab.com/QEF/q-e/-/wikis/Developers/CMake-build-system>`_
git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
build the executable pw.x, following the `QE build guide <https://gitlab.com/QEF/q-e/-/wikis/Developers/CMake-build-system>`_
Here is how to build QE as a shared library which can be used in plugin mode,
which results in a libqemdi.so file in <base_path>/q-e/MDI/src:
.. code-block:: bash
% git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
% cd <base_path>/q-e
% ./configure --enable-parallel --enable-openmp --enable-shared FFLAGS="-fPIC" FCFLAGS="-fPIC" CFLAGS="-fPIC" foxflags="-fPIC" try_foxflags="-fPIC"
% make -j 4 mdi
git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
cd <base_path>/q-e
./configure --enable-parallel --enable-openmp --enable-shared FFLAGS="-fPIC" FCFLAGS="-fPIC" CFLAGS="-fPIC" foxflags="-fPIC" try_foxflags="-fPIC"
make -j 4 mdi
INQ cannot be built as a stand-alone code; it is by design a library.
Here is how to build INQ as a shared library which can be used in
@ -154,10 +154,10 @@ plugin mode, which results in a libinqmdi.so file in
.. code-block:: bash
% git clone --branch mdi --recurse-submodules https://gitlab.com/taylor-a-barnes/inq.git <base_path>/inq
% cd <base_path>/inq
% mkdir -p build
% cd build
% ../configure --prefix=<install_path>/install
% make -j 4
% make install
git clone --branch mdi --recurse-submodules https://gitlab.com/taylor-a-barnes/inq.git <base_path>/inq
cd <base_path>/inq
mkdir -p build
cd build
../configure --prefix=<install_path>/install
make -j 4
make install

329
doc/src/Howto_output.rst
View File

@ -22,14 +22,17 @@ commands you specify.
As discussed below, LAMMPS gives you a variety of ways to determine
what quantities are computed and printed when the thermodynamics,
dump, or fix commands listed above perform output. Throughout this
discussion, note that users can also :doc:`add their own computes and fixes to LAMMPS <Modify>` which can then generate values that can then be
output with these commands.
discussion, note that users can also :doc:`add their own computes and
fixes to LAMMPS <Modify>` which can then generate values that can then
be output with these commands.
The following sub-sections discuss different LAMMPS command related
The following sub-sections discuss different LAMMPS commands related
to output and the kind of data they operate on and produce:
* :ref:`Global/per-atom/local data <global>`
* :ref:`Global/per-atom/local/per-grid data <global>`
* :ref:`Scalar/vector/array data <scalar>`
* :ref:`Per-grid data <grid>`
* :ref:`Disambiguation <disambiguation>`
* :ref:`Thermodynamic output <thermo>`
* :ref:`Dump file output <dump>`
* :ref:`Fixes that write output files <fixoutput>`
@ -42,27 +45,32 @@ to output and the kind of data they operate on and produce:
.. _global:
Global/per-atom/local data
--------------------------
Global/per-atom/local/per-grid data
-----------------------------------
Various output-related commands work with three different styles of
data: global, per-atom, or local. A global datum is one or more
system-wide values, e.g. the temperature of the system. A per-atom
datum is one or more values per atom, e.g. the kinetic energy of each
atom. Local datums are calculated by each processor based on the
atoms it owns, but there may be zero or more per atom, e.g. a list of
bond distances.
Various output-related commands work with four different styles of
data: global, per-atom, local, and per-grid. A global datum is one or
more system-wide values, e.g. the temperature of the system. A
per-atom datum is one or more values per atom, e.g. the kinetic energy
of each atom. Local datums are calculated by each processor based on
the atoms it owns, but there may be zero or more per atom, e.g. a list
of bond distances.
A per-grid datum is one or more values per grid cell, for a grid which
overlays the simulation domain. The grid cells and the data they
store are distributed across processors; each processor owns the grid
cells whose center point falls within its sub-domain.
.. _scalar:
Scalar/vector/array data
------------------------
Global, per-atom, and local datums can each come in three kinds: a
single scalar value, a vector of values, or a 2d array of values. The
doc page for a "compute" or "fix" or "variable" that generates data
will specify both the style and kind of data it produces, e.g. a
per-atom vector.
Global, per-atom, and local datums can come in three kinds: a single
scalar value, a vector of values, or a 2d array of values. The doc
page for a "compute" or "fix" or "variable" that generates data will
specify both the style and kind of data it produces, e.g. a per-atom
vector.
When a quantity is accessed, as in many of the output commands
discussed below, it can be referenced via the following bracket
@ -83,6 +91,18 @@ the dimension twice (array -> scalar). Thus a command that uses
scalar values as input can typically also process elements of a vector
or array.
.. _grid:
Per-grid data
------------------------
Per-grid data can come in two kinds: a vector of values (one per grid
cekk), or a 2d array of values (multiple values per grid ckk). The
doc page for a "compute" or "fix" that generates data will specify
names for both the grid(s) and datum(s) it produces, e.g. per-grid
vectors or arrays, which can be referenced by other commands. See the
:doc:`Howto grid <Howto_grid>` doc page for more details.
.. _disambiguation:
Disambiguation
@ -90,15 +110,15 @@ Disambiguation
Some computes and fixes produce data in multiple styles, e.g. a global
scalar and a per-atom vector. Usually the context in which the input
script references the data determines which style is meant. Example: if
a compute provides both a global scalar and a per-atom vector, the
script references the data determines which style is meant. Example:
if a compute provides both a global scalar and a per-atom vector, the
former will be accessed by using ``c_ID`` in an equal-style variable,
while the latter will be accessed by using ``c_ID`` in an atom-style
variable. Note that atom-style variable formulas can also access global
scalars, but in this case it is not possible to do directly because of
the ambiguity. Instead, an equal-style variable can be defined which
accesses the global scalar, and that variable used in the atom-style
variable formula in place of ``c_ID``.
variable. Note that atom-style variable formulas can also access
global scalars, but in this case it is not possible to do this
directly because of the ambiguity. Instead, an equal-style variable
can be defined which accesses the global scalar, and that variable can
be used in the atom-style variable formula in place of ``c_ID``.
.. _thermo:
@ -107,15 +127,14 @@ Thermodynamic output
The frequency and format of thermodynamic output is set by the
:doc:`thermo <thermo>`, :doc:`thermo_style <thermo_style>`, and
:doc:`thermo_modify <thermo_modify>` commands. The
:doc:`thermo_style <thermo_style>` command also specifies what values
are calculated and written out. Pre-defined keywords can be specified
(e.g. press, etotal, etc). Three additional kinds of keywords can
also be specified (c_ID, f_ID, v_name), where a :doc:`compute <compute>`
or :doc:`fix <fix>` or :doc:`variable <variable>` provides the value to be
output. In each case, the compute, fix, or variable must generate
global values for input to the :doc:`thermo_style custom <dump>`
command.
:doc:`thermo_modify <thermo_modify>` commands. The :doc:`thermo_style
<thermo_style>` command also specifies what values are calculated and
written out. Pre-defined keywords can be specified (e.g. press, etotal,
etc). Three additional kinds of keywords can also be specified (c_ID,
f_ID, v_name), where a :doc:`compute <compute>` or :doc:`fix <fix>` or
:doc:`variable <variable>` provides the value to be output. In each
case, the compute, fix, or variable must generate global values for
input to the :doc:`thermo_style custom <dump>` command.
Note that thermodynamic output values can be "extensive" or
"intensive". The former scale with the number of atoms in the system
@ -141,9 +160,10 @@ There is also a :doc:`dump custom <dump>` format where the user
specifies what values are output with each atom. Pre-defined atom
attributes can be specified (id, x, fx, etc). Three additional kinds
of keywords can also be specified (c_ID, f_ID, v_name), where a
:doc:`compute <compute>` or :doc:`fix <fix>` or :doc:`variable <variable>`
provides the values to be output. In each case, the compute, fix, or
variable must generate per-atom values for input to the :doc:`dump custom <dump>` command.
:doc:`compute <compute>` or :doc:`fix <fix>` or :doc:`variable
<variable>` provides the values to be output. In each case, the
compute, fix, or variable must generate per-atom values for input to
the :doc:`dump custom <dump>` command.
There is also a :doc:`dump local <dump>` format where the user specifies
what local values to output. A pre-defined index keyword can be
@ -154,18 +174,23 @@ provides the values to be output. In each case, the compute or fix
must generate local values for input to the :doc:`dump local <dump>`
command.
There is also a :doc:`dump grid <dump>` format where the user
specifies what per-grid values to output from computes or fixes that
generate per-grid data.
.. _fixoutput:
Fixes that write output files
-----------------------------
Several fixes take various quantities as input and can write output
files: :doc:`fix ave/time <fix_ave_time>`, :doc:`fix ave/chunk <fix_ave_chunk>`, :doc:`fix ave/histo <fix_ave_histo>`,
:doc:`fix ave/correlate <fix_ave_correlate>`, and :doc:`fix print <fix_print>`.
files: :doc:`fix ave/time <fix_ave_time>`, :doc:`fix ave/chunk
<fix_ave_chunk>`, :doc:`fix ave/histo <fix_ave_histo>`, :doc:`fix
ave/correlate <fix_ave_correlate>`, and :doc:`fix print <fix_print>`.
The :doc:`fix ave/time <fix_ave_time>` command enables direct output to
a file and/or time-averaging of global scalars or vectors. The user
specifies one or more quantities as input. These can be global
The :doc:`fix ave/time <fix_ave_time>` command enables direct output
to a file and/or time-averaging of global scalars or vectors. The
user specifies one or more quantities as input. These can be global
:doc:`compute <compute>` values, global :doc:`fix <fix>` values, or
:doc:`variables <variable>` of any style except the atom style which
produces per-atom values. Since a variable can refer to keywords used
@ -184,8 +209,14 @@ atoms, e.g. individual molecules. The per-atom quantities can be atom
density (mass or number) or atom attributes such as position,
velocity, force. They can also be per-atom quantities calculated by a
:doc:`compute <compute>`, by a :doc:`fix <fix>`, or by an atom-style
:doc:`variable <variable>`. The chunk-averaged output of this fix can
also be used as input to other output commands.
:doc:`variable <variable>`. The chunk-averaged output of this fix is
global and can also be used as input to other output commands.
Note that the :doc:`fix ave/grid <fix_ave_grid>` command can also
average the same per-atom quantities within spatial bins, but it does
this for a distributed grid whose grid cells are owned by different
processors. It outputs per-grid data, not global data, so it is more
efficient for large numbers of averaging bins.
The :doc:`fix ave/histo <fix_ave_histo>` command enables direct output
to a file of histogrammed quantities, which can be global or per-atom
@ -202,38 +233,53 @@ written to the screen and log file or to a separate file, periodically
during a running simulation. The line can contain one or more
:doc:`variable <variable>` values for any style variable except the
vector or atom styles). As explained above, variables themselves can
contain references to global values generated by :doc:`thermodynamic keywords <thermo_style>`, :doc:`computes <compute>`,
:doc:`fixes <fix>`, or other :doc:`variables <variable>`, or to per-atom
values for a specific atom. Thus the :doc:`fix print <fix_print>`
command is a means to output a wide variety of quantities separate
from normal thermodynamic or dump file output.
contain references to global values generated by :doc:`thermodynamic
keywords <thermo_style>`, :doc:`computes <compute>`, :doc:`fixes
<fix>`, or other :doc:`variables <variable>`, or to per-atom values
for a specific atom. Thus the :doc:`fix print <fix_print>` command is
a means to output a wide variety of quantities separate from normal
thermodynamic or dump file output.
.. _computeoutput:
Computes that process output quantities
---------------------------------------
The :doc:`compute reduce <compute_reduce>` and :doc:`compute reduce/region <compute_reduce>` commands take one or more per-atom
or local vector quantities as inputs and "reduce" them (sum, min, max,
The :doc:`compute reduce <compute_reduce>` and :doc:`compute
reduce/region <compute_reduce>` commands take one or more per-atom or
local vector quantities as inputs and "reduce" them (sum, min, max,
ave) to scalar quantities. These are produced as output values which
can be used as input to other output commands.
The :doc:`compute slice <compute_slice>` command take one or more global
vector or array quantities as inputs and extracts a subset of their
values to create a new vector or array. These are produced as output
values which can be used as input to other output commands.
The :doc:`compute slice <compute_slice>` command take one or more
global vector or array quantities as inputs and extracts a subset of
their values to create a new vector or array. These are produced as
output values which can be used as input to other output commands.
The :doc:`compute property/atom <compute_property_atom>` command takes a
list of one or more pre-defined atom attributes (id, x, fx, etc) and
The :doc:`compute property/atom <compute_property_atom>` command takes
a list of one or more pre-defined atom attributes (id, x, fx, etc) and
stores the values in a per-atom vector or array. These are produced
as output values which can be used as input to other output commands.
The list of atom attributes is the same as for the :doc:`dump custom <dump>` command.
The list of atom attributes is the same as for the :doc:`dump custom
<dump>` command.
The :doc:`compute property/local <compute_property_local>` command takes
a list of one or more pre-defined local attributes (bond info, angle
info, etc) and stores the values in a local vector or array. These
are produced as output values which can be used as input to other
output commands.
The :doc:`compute property/local <compute_property_local>` command
takes a list of one or more pre-defined local attributes (bond info,
angle info, etc) and stores the values in a local vector or array.
These are produced as output values which can be used as input to
other output commands.
The :doc:`compute property/grid <compute_property_grid>` command takes
a list of one or more pre-defined per-grid attributes (id, grid cell
coords, etc) and stores the values in a per-grid vector or array.
These are produced as output values which can be used as input to the
:doc:`dump grid <dump>` command.
The :doc:`compute property/chunk <compute_property_chunk>` command
takes a list of one or more pre-defined chunk attributes (id, count,
coords for spatial bins) and stores the values in a global vector or
array. These are produced as output values which can be used as input
to other output commands.
.. _fixprocoutput:
@ -247,18 +293,42 @@ a time.
The :doc:`fix ave/atom <fix_ave_atom>` command performs time-averaging
of per-atom vectors. The per-atom quantities can be atom attributes
such as position, velocity, force. They can also be per-atom
quantities calculated by a :doc:`compute <compute>`, by a
:doc:`fix <fix>`, or by an atom-style :doc:`variable <variable>`. The
quantities calculated by a :doc:`compute <compute>`, by a :doc:`fix
<fix>`, or by an atom-style :doc:`variable <variable>`. The
time-averaged per-atom output of this fix can be used as input to
other output commands.
The :doc:`fix store/state <fix_store_state>` command can archive one or
more per-atom attributes at a particular time, so that the old values
can be used in a future calculation or output. The list of atom
attributes is the same as for the :doc:`dump custom <dump>` command,
including per-atom quantities calculated by a :doc:`compute <compute>`,
by a :doc:`fix <fix>`, or by an atom-style :doc:`variable <variable>`.
The output of this fix can be used as input to other output commands.
The :doc:`fix store/state <fix_store_state>` command can archive one
or more per-atom attributes at a particular time, so that the old
values can be used in a future calculation or output. The list of
atom attributes is the same as for the :doc:`dump custom <dump>`
command, including per-atom quantities calculated by a :doc:`compute
<compute>`, by a :doc:`fix <fix>`, or by an atom-style :doc:`variable
<variable>`. The output of this fix can be used as input to other
output commands.
The :doc:`fix ave/grid <fix_ave_grid>` command performs time-averaging
of either per-atom or per-grid data.
For per-atom data it performs averaging for the atoms within each grid
cell, similar to the :doc:`fix ave/chunk <fix_ave_chunk>` command when
its chunks are defined as regular 2d or 3d bins. The per-atom
quantities can be atom density (mass or number) or atom attributes
such as position, velocity, force. They can also be per-atom
quantities calculated by a :doc:`compute <compute>`, by a :doc:`fix
<fix>`, or by an atom-style :doc:`variable <variable>`.
The chief difference between the :doc:`fix ave/grid <fix_ave_grid>`
and :doc:`fix ave/chunk <fix_ave_chunk>` commands when used in this
context is that the former uses a distributed grid, while the latter
uses a global grid. Distributed means that each processor owns the
subset of grid cells within its sub-domain. Global means that each
processor owns a copy of the entire grid. The :doc:`fix ave/grid
<fix_ave_grid>` command is thus more efficient for large grids.
For per-grid data, the :doc:`fix ave/grid <fix_ave_grid>` command
takes inputs for grid data produced by other computes or fixes and
averages the values for each grid point over time.
.. _compute:
@ -266,24 +336,25 @@ Computes that generate values to output
---------------------------------------
Every :doc:`compute <compute>` in LAMMPS produces either global or
per-atom or local values. The values can be scalars or vectors or
arrays of data. These values can be output using the other commands
described in this section. The page for each compute command
per-atom or local or per-grid values. The values can be scalars or
vectors or arrays of data. These values can be output using the other
commands described in this section. The page for each compute command
describes what it produces. Computes that produce per-atom or local
values have the word "atom" or "local" in their style name. Computes
without the word "atom" or "local" produce global values.
or per-grid values have the word "atom" or "local" or "grid as the
last word in their style name. Computes without the word "atom" or
"local" or "grid" produce global values.
.. _fix:
Fixes that generate values to output
------------------------------------
Some :doc:`fixes <fix>` in LAMMPS produces either global or per-atom or
local values which can be accessed by other commands. The values can
be scalars or vectors or arrays of data. These values can be output
using the other commands described in this section. The page for
each fix command tells whether it produces any output quantities and
describes them.
Some :doc:`fixes <fix>` in LAMMPS produces either global or per-atom
or local or per-grid values which can be accessed by other commands.
The values can be scalars or vectors or arrays of data. These values
can be output using the other commands described in this section. The
page for each fix command tells whether it produces any output
quantities and describes them.
.. _variable:
@ -300,6 +371,8 @@ computes, fixes, and other variables. The values generated by
variables can be used as input to and thus output by the other
commands described in this section.
Per-grid variables have not (yet) been implemented.
.. _table:
Summary table of output options and data flow between commands
@ -319,44 +392,52 @@ Also note that, as described above, when a command takes a scalar as
input, that could be an element of a vector or array. Likewise a
vector input could be a column of an array.
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| Command | Input | Output |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`thermo_style custom <thermo_style>` | global scalars | screen, log file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`dump custom <dump>` | per-atom vectors | dump file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`dump local <dump>` | local vectors | dump file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix print <fix_print>` | global scalar from variable | screen, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`print <print>` | global scalar from variable | screen |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`computes <compute>` | N/A | global/per-atom/local scalar/vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fixes <fix>` | N/A | global/per-atom/local scalar/vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`variables <variable>` | global scalars and vectors, per-atom vectors | global scalar and vector, per-atom vector |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`compute reduce <compute_reduce>` | per-atom/local vectors | global scalar/vector |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`compute slice <compute_slice>` | global vectors/arrays | global vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`compute property/atom <compute_property_atom>` | per-atom vectors | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`compute property/local <compute_property_local>` | local vectors | local vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix vector <fix_vector>` | global scalars | global vector |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/atom <fix_ave_atom>` | per-atom vectors | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/time <fix_ave_time>` | global scalars/vectors | global scalar/vector/array, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/chunk <fix_ave_chunk>` | per-atom vectors | global array, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/histo <fix_ave_histo>` | global/per-atom/local scalars and vectors | global array, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/correlate <fix_ave_correlate>` | global scalars | global array, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix store/state <fix_store_state>` | per-atom vectors | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| Command | Input | Output |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`thermo_style custom <thermo_style>` | global scalars | screen, log file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`dump custom <dump>` | per-atom vectors | dump file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`dump local <dump>` | local vectors | dump file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`dump grid <dump>` | per-grid vectors | dump file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix print <fix_print>` | global scalar from variable | screen, file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`print <print>` | global scalar from variable | screen |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`computes <compute>` | N/A | global/per-atom/local/per-grid scalar/vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fixes <fix>` | N/A | global/per-atom/local/per-grid scalar/vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`variables <variable>` | global scalars and vectors, per-atom vectors | global scalar and vector, per-atom vector |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`compute reduce <compute_reduce>` | per-atom/local vectors | global scalar/vector |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`compute slice <compute_slice>` | global vectors/arrays | global vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`compute property/atom <compute_property_atom>` | N/A | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`compute property/local <compute_property_local>` | N/A | local vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`compute property/grid <compute_property_grid>` | N/A | per-grid vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`compute property/chunk <compute_property_chunk>` | N/A | global vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix vector <fix_vector>` | global scalars | global vector |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix ave/atom <fix_ave_atom>` | per-atom vectors | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix ave/time <fix_ave_time>` | global scalars/vectors | global scalar/vector/array, file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix ave/chunk <fix_ave_chunk>` | per-atom vectors | global array, file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix ave/grid <fix_ave_grid>` | per-atom vectors or per-grid vectors | per-grid vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix ave/histo <fix_ave_histo>` | global/per-atom/local scalars and vectors | global array, file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix ave/correlate <fix_ave_correlate>` | global scalars | global array, file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix store/state <fix_store_state>` | per-atom vectors | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+

38
doc/src/Howto_pylammps.rst
View File

@ -152,14 +152,14 @@ Creating a new instance of PyLammps
To create a PyLammps object you need to first import the class from the lammps
module. By using the default constructor, a new *lammps* instance is created.
.. code-block:: Python
.. code-block:: python
from lammps import PyLammps
L = PyLammps()
You can also initialize PyLammps on top of this existing *lammps* object:
.. code-block:: Python
.. code-block:: python
from lammps import lammps, PyLammps
lmp = lammps()
@ -180,14 +180,14 @@ For instance, let's take the following LAMMPS command:
In the original interface this command can be executed with the following
Python code if *L* was a lammps instance:
.. code-block:: Python
.. code-block:: python
L.command("region box block 0 10 0 5 -0.5 0.5")
With the PyLammps interface, any command can be split up into arbitrary parts
separated by white-space, passed as individual arguments to a region method.
.. code-block:: Python
.. code-block:: python
L.region("box block", 0, 10, 0, 5, -0.5, 0.5)
@ -199,14 +199,14 @@ The benefit of this approach is avoiding redundant command calls and easier
parameterization. In the original interface parameterization needed to be done
manually by creating formatted strings.
.. code-block:: Python
.. code-block:: python
L.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi))
In contrast, methods of PyLammps accept parameters directly and will convert
them automatically to a final command string.
.. code-block:: Python
.. code-block:: python
L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi)
@ -256,7 +256,7 @@ LAMMPS variables can be both defined and accessed via the PyLammps interface.
To define a variable you can use the :doc:`variable <variable>` command:
.. code-block:: Python
.. code-block:: python
L.variable("a index 2")
@ -265,14 +265,14 @@ A dictionary of all variables is returned by L.variables
you can access an individual variable by retrieving a variable object from the
L.variables dictionary by name
.. code-block:: Python
.. code-block:: python
a = L.variables['a']
The variable value can then be easily read and written by accessing the value
property of this object.
.. code-block:: Python
.. code-block:: python
print(a.value)
a.value = 4
@ -284,7 +284,7 @@ LAMMPS expressions can be immediately evaluated by using the eval method. The
passed string parameter can be any expression containing global thermo values,
variables, compute or fix data.
.. code-block:: Python
.. code-block:: python
result = L.eval("ke") # kinetic energy
result = L.eval("pe") # potential energy
@ -298,7 +298,7 @@ All atoms in the current simulation can be accessed by using the L.atoms list.
Each element of this list is an object which exposes its properties (id, type,
position, velocity, force, etc.).
.. code-block:: Python
.. code-block:: python
# access first atom
L.atoms[0].id
@ -311,7 +311,7 @@ position, velocity, force, etc.).
Some properties can also be used to set:
.. code-block:: Python
.. code-block:: python
# set position in 2D simulation
L.atoms[0].position = (1.0, 0.0)
@ -328,7 +328,7 @@ after a run via the L.runs list. This list contains a growing list of run data.
The first element is the output of the first run, the second element that of
the second run.
.. code-block:: Python
.. code-block:: python
L.run(1000)
L.runs[0] # data of first 1000 time steps
@ -339,14 +339,14 @@ the second run.
Each run contains a dictionary of all trajectories. Each trajectory is
accessible through its thermo name:
.. code-block:: Python
.. code-block:: python
L.runs[0].thermo.Step # list of time steps in first run
L.runs[0].thermo.Ke # list of kinetic energy values in first run
Together with matplotlib plotting data out of LAMMPS becomes simple:
.. code-block:: Python
.. code-block:: python
import matplotlib.plot as plt
steps = L.runs[0].thermo.Step
@ -406,7 +406,7 @@ Four atoms are placed in the simulation and the dihedral potential is applied on
them using a datafile. Then one of the atoms is rotated along the central axis by
setting its position from Python, which changes the dihedral angle.
.. code-block:: Python
.. code-block:: python
phi = [d \* math.pi / 180 for d in range(360)]
@ -439,7 +439,7 @@ Initially, a 2D system is created in a state with minimal energy.
It is then disordered by moving each atom by a random delta.
.. code-block:: Python
.. code-block:: python
random.seed(27848)
deltaperturb = 0.2
@ -458,7 +458,7 @@ It is then disordered by moving each atom by a random delta.
Finally, the Monte Carlo algorithm is implemented in Python. It continuously
moves random atoms by a random delta and only accepts certain moves.
.. code-block:: Python
.. code-block:: python
estart = L.eval("pe")
elast = estart
@ -517,7 +517,7 @@ PyLammps can be run in parallel using mpi4py. This python package can be install
The following is a short example which reads in an existing LAMMPS input file and
executes it in parallel. You can find in.melt in the examples/melt folder.
.. code-block:: Python
.. code-block:: python
from mpi4py import MPI
from lammps import PyLammps

2
doc/src/Howto_structured_data.rst
View File

@ -43,7 +43,7 @@ JSON
"ke": $(ke)
}""" file current_state.json screen no
.. code-block:: JSON
.. code-block:: json
:caption: current_state.json
{

13
doc/src/Install_conda.rst
View File

@ -1,7 +1,8 @@
Download an executable for Linux or Mac via Conda
-------------------------------------------------
Binaries are available for MacOS or Linux via `Conda <conda_>`_.
Pre-compiled LAMMPS binaries are available for macOS or Linux via the
`Conda <conda_>`_ package management system.
First, one must setup the Conda package manager on your system. Follow the
instructions to install `Miniconda <mini_conda_install_>`_, then create a conda
@ -10,15 +11,15 @@ install:
.. code-block:: bash
% conda config --add channels conda-forge
% conda create -n my-lammps-env
conda config --add channels conda-forge
conda create -n my-lammps-env
Then, you can install LAMMPS on your system with the following command:
.. code-block:: bash
% conda activate my-lammps-env
% conda install lammps
conda activate my-lammps-env
conda install lammps
The LAMMPS binary is built with the :ref:`KIM package <kim>` which
results in Conda also installing the `kim-api` binaries when LAMMPS is
@ -27,7 +28,7 @@ install the `openkim-models` package
.. code-block:: bash
% conda install openkim-models
conda install openkim-models
If you have problems with the installation you can post issues to
`this link <conda_forge_lammps_>`_.

26
doc/src/Install_git.rst
View File

@ -41,7 +41,7 @@ create a local copy of the LAMMPS repository with a command like:
.. code-block:: bash
$ git clone -b release 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 "release" is one of the 3 branches listed above.
@ -78,10 +78,10 @@ from within the "mylammps" directory:
.. code-block:: bash
$ git checkout release # not needed if you always stay in this branch
$ git checkout stable # use one of these 3 checkout commands
$ git checkout develop # to choose the branch to follow
$ git pull
git checkout release # not needed if you always stay in this branch
git checkout stable # use one of these 3 checkout commands
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
directory structure. It will also not change any existing LAMMPS
@ -97,7 +97,7 @@ this is as follows.
.. code-block:: bash
$ git checkout tagID
git checkout tagID
Stable versions and what tagID to use for a particular stable version
are discussed on `this page <https://www.lammps.org/bug.html#version>`_.
@ -138,13 +138,13 @@ changed. How to do this depends on the build system you are using.
.. code-block:: bash
$ make purge # remove any deprecated src files
$ make package-update # sync package files with src files
$ make foo # re-build for your machine (mpi, serial, etc)
make purge # remove any deprecated src files
make package-update # sync package files with src files
make foo # re-build for your machine (mpi, serial, etc)
to enforce consistency of the source between the src folder
and package directories. This is OK to do even if you don't
use any packages. The "make purge" command removes any deprecated
use any packages. The ``make purge`` command removes any deprecated
src files if they were removed by the patch from a package
sub-directory.
@ -160,9 +160,9 @@ changed. How to do this depends on the build system you are using.
:class: note
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".
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
(Temple U, akohlmey at gmail.com).

38
doc/src/Install_linux.rst
View File

@ -34,7 +34,7 @@ To install LAMMPS do the following once:
.. code-block:: bash
$ sudo apt-get install lammps
sudo apt-get install lammps
This downloads an executable named ``lmp`` to your box and multiple
packages with supporting data, examples and libraries as well as any
@ -43,13 +43,13 @@ to run input scripts:
.. code-block:: bash
$ lmp -in in.lj
lmp -in in.lj
To update LAMMPS to the latest packaged version, do the following:
.. code-block:: bash
$ sudo apt-get update
sudo apt-get update
which will also update other packages on your system.
@ -61,14 +61,14 @@ package
.. code-block:: bash
$ sudo apt-get install openkim-models
sudo apt-get install openkim-models
Or use the KIM-API commands to download and install individual models.
To un-install LAMMPS, do the following:
.. code-block:: bash
$ sudo apt-get remove lammps
sudo apt-get remove lammps
Please use ``lmp -help`` to see which compilation options, packages,
and styles are included in the binary.
@ -103,9 +103,9 @@ To install LAMMPS with OpenMPI and run an input ``in.lj`` with 2 CPUs do:
.. code-block:: bash
$ dnf install lammps-openmpi
$ module load mpi/openmpi-x86_64
$ mpirun -np 2 lmp -in in.lj
dnf install lammps-openmpi
module load mpi/openmpi-x86_64
mpirun -np 2 lmp -in in.lj
The ``dnf install`` command is needed only once. In case of a new LAMMPS
stable release, ``dnf update`` will automatically update to the newer
@ -121,7 +121,7 @@ can install the `openkim-models` package
.. code-block:: bash
$ dnf install openkim-models
dnf install openkim-models
Please use ``lmp -help`` to see which compilation options, packages,
and styles are included in the binary.
@ -162,14 +162,14 @@ in OpenSuse as of Leap 15.0. You can install the package with:
.. code-block:: bash
$ zypper install lammps
zypper install lammps
This includes support for OpenMPI. The name of the LAMMPS executable
is ``lmp``. Thus to run an input in parallel on 2 CPUs you would do:
.. code-block:: bash
$ mpirun -np 2 lmp -in in.lj
mpirun -np 2 lmp -in in.lj
Please use ``lmp -help`` to see which compilation options, packages,
and styles are included in the binary.
@ -181,7 +181,7 @@ can install the `openkim-models` package
.. code-block:: bash
$ zypper install openkim-models
zypper install openkim-models
Thanks to Christoph Junghans (LANL) for making LAMMPS available in OpenSuse.
@ -197,7 +197,7 @@ typing:
.. code-block:: bash
% emerge --ask lammps
emerge --ask lammps
Note that in Gentoo the LAMMPS source is downloaded and the package is
built on the your machine.
@ -206,7 +206,7 @@ Certain LAMMPS packages can be enable via USE flags, type
.. code-block:: bash
% equery uses lammps
equery uses lammps
for details.
@ -229,10 +229,10 @@ any of the above names in-place of lammps.
.. code-block:: bash
$ git clone https://aur.archlinux.org/lammps.git
$ cd lammps
$ makepkg -s
$ makepkg -i
git clone https://aur.archlinux.org/lammps.git
cd lammps
makepkg -s
makepkg -i
To update, you may repeat the above, or change into the cloned directory,
and execute the following, after which, if there are any changes, you may
@ -240,7 +240,7 @@ use makepkg as above.
.. code-block:: bash
$ git pull
git pull
Alternatively, you may use an AUR helper to install these packages.

6
doc/src/Install_mac.rst
View File

@ -12,7 +12,7 @@ the following commands:
.. code-block:: bash
% brew install lammps
brew install lammps
This will install the executables "lammps_serial" and "lammps_mpi", as well as
the LAMMPS "doc", "potentials", "tools", "bench", and "examples" directories.
@ -22,7 +22,7 @@ Lennard-Jones benchmark file:
.. code-block:: bash
% brew test lammps -v
brew test lammps -v
The LAMMPS binary is built with the :ref:`KIM package <kim>` which
results in Homebrew also installing the `kim-api` binaries when LAMMPS is
@ -31,7 +31,7 @@ install the `openkim-models` package
.. code-block:: bash
% brew install openkim-models
brew install openkim-models
If you have problems with the installation you can post issues to
`this link <https://github.com/Homebrew/homebrew-core/issues>`_.

4
doc/src/Install_tarball.rst
View File

@ -26,7 +26,7 @@ command:
.. code-block:: bash
$ tar -xzvf lammps*.tar.gz
tar -xzvf lammps*.tar.gz
This will create a LAMMPS directory with the version date
in its name, e.g. lammps-23Jun18.
@ -40,7 +40,7 @@ with the following command, to create a lammps-<version> dir:
.. code-block:: bash
$ unzip lammps*.zip
unzip lammps*.zip
This version corresponds to the selected LAMMPS patch or stable
release.

2
doc/src/Library_config.rst
View File

@ -39,7 +39,7 @@ crashes within LAMMPS may be recovered from by enabling
:ref:`exceptions <exceptions>`, avoiding them proactively is a safer
approach.
.. code-block:: C
.. code-block:: c
:caption: Example for using configuration settings functions
#include "library.h"

2
doc/src/Library_create.rst
View File

@ -22,7 +22,7 @@ as the "handle" argument in subsequent function calls until that
instance is destroyed by calling :cpp:func:`lammps_close`. Here is a
simple example demonstrating its use:
.. code-block:: C
.. code-block:: c
#include "library.h"
#include <stdio.h>

2
doc/src/Library_execute.rst
View File

@ -30,7 +30,7 @@ be included in the file or strings, and expansion of variables with
``${name}`` or ``$(expression)`` syntax is performed.
Below is a short example using some of these functions.
.. code-block:: C
.. code-block:: c
/* define to make the otherwise hidden prototype for "lammps_open()" visible */
#define LAMMPS_LIB_MPI

2
doc/src/Library_properties.rst
View File

@ -32,7 +32,7 @@ indexed accordingly. Per-atom data can change sizes and ordering at
every neighbor list rebuild or atom sort event as atoms migrate between
sub-domains and processors.
.. code-block:: C
.. code-block:: c
#include "library.h"
#include <stdio.h>

6
doc/src/Library_utility.rst
View File

@ -7,6 +7,7 @@ functions. They do not directly call the LAMMPS library.
- :cpp:func:`lammps_encode_image_flags`
- :cpp:func:`lammps_decode_image_flags`
- :cpp:func:`lammps_set_fix_external_callback`
- :cpp:func:`lammps_fix_external_get_force`
- :cpp:func:`lammps_fix_external_set_energy_global`
- :cpp:func:`lammps_fix_external_set_energy_peratom`
- :cpp:func:`lammps_fix_external_set_virial_global`
@ -44,6 +45,11 @@ where such memory buffers were allocated that require the use of
-----------------------
.. doxygenfunction:: lammps_fix_external_get_force
:project: progguide
-----------------------
.. doxygenfunction:: lammps_fix_external_set_energy_global
:project: progguide

83
doc/src/Modify_bond.rst
View File

@ -13,24 +13,65 @@ Here is a brief description of common methods you define in your
new derived class. See bond.h, angle.h, dihedral.h, and improper.h
for details and specific additional methods.
+-----------------------+---------------------------------------------------------------------------------------+
| init | check if all coefficients are set, calls *init_style* (optional) |
+-----------------------+---------------------------------------------------------------------------------------+
| init_style | check if style specific conditions are met (optional) |
+-----------------------+---------------------------------------------------------------------------------------+
| compute | compute the molecular interactions (required) |
+-----------------------+---------------------------------------------------------------------------------------+
| settings | apply global settings for all types (optional) |
+-----------------------+---------------------------------------------------------------------------------------+
| coeff | set coefficients for one type (required) |
+-----------------------+---------------------------------------------------------------------------------------+
| equilibrium_distance | length of bond, used by SHAKE (required, bond only) |
+-----------------------+---------------------------------------------------------------------------------------+
| equilibrium_angle | opening of angle, used by SHAKE (required, angle only) |
+-----------------------+---------------------------------------------------------------------------------------+
| write & read_restart | writes/reads coeffs to restart files (required) |
+-----------------------+---------------------------------------------------------------------------------------+
| single | force (bond only) and energy of a single bond or angle (required, bond or angle only) |
+-----------------------+---------------------------------------------------------------------------------------+
| memory_usage | tally memory allocated by the style (optional) |
+-----------------------+---------------------------------------------------------------------------------------+
+-----------------------+---------------------------------------------------------------------+
| Required | "pure" methods that *must* be overridden in a derived class |
+=======================+=====================================================================+
| compute | compute the molecular interactions for all listed items |
+-----------------------+---------------------------------------------------------------------+
| coeff | set coefficients for one type |
+-----------------------+---------------------------------------------------------------------+
| equilibrium_distance | length of bond, used by SHAKE (bond styles only) |
+-----------------------+---------------------------------------------------------------------+
| equilibrium_angle | opening of angle, used by SHAKE (angle styles only) |
+-----------------------+---------------------------------------------------------------------+
| write & read_restart | writes/reads coeffs to restart files |
+-----------------------+---------------------------------------------------------------------+
| single | force/r (bond styles only) and energy of a single bond or angle |
+-----------------------+---------------------------------------------------------------------+
+--------------------------------+----------------------------------------------------------------------+
| Optional | methods that have a default or dummy implementation |
+================================+======================================================================+
| init | check if all coefficients are set, calls init_style() |
+--------------------------------+----------------------------------------------------------------------+
| init_style | check if style specific conditions are met |
+--------------------------------+----------------------------------------------------------------------+
| settings | apply global settings for all types |
+--------------------------------+----------------------------------------------------------------------+
| write & read_restart_settings | writes/reads global style settings to restart files |
+--------------------------------+----------------------------------------------------------------------+
| write_data | write corresponding Coeffs section(s) in data file |
+--------------------------------+----------------------------------------------------------------------+
| memory_usage | tally memory allocated by the style |
+--------------------------------+----------------------------------------------------------------------+
| extract | provide access to internal data (bond or angle styles only) |
+--------------------------------+----------------------------------------------------------------------+
| reinit | reset all type-based parameters, called by fix adapt (bonds only) |
+--------------------------------+----------------------------------------------------------------------+
| pack & unpack_forward_comm | copy data to and from buffer in forward communication (bonds only) |
+--------------------------------+----------------------------------------------------------------------+
| pack & unpack_reverse_comm | copy data to and from buffer in reverse communication (bonds only) |
+--------------------------------+----------------------------------------------------------------------+
Here is a list of flags or settings that should be set in the
constructor of the derived class when they differ from the default
setting.
+---------------------------------+------------------------------------------------------------------------------+---------+
| Name of flag | Description | default |
+=================================+==============================================================================+=========+
| writedata | 1 if write_data() is implemented | 1 |
+---------------------------------+------------------------------------------------------------------------------+---------+
| single_extra | number of extra single values calculated (bond styles only) | 0 |
+---------------------------------+------------------------------------------------------------------------------+---------+
| partial_flag | 1 if bond type can be set to 0 and deleted (bond styles only) | 0 |
+---------------------------------+------------------------------------------------------------------------------+---------+
| reinitflag | 1 if style has reinit() and is compatible with fix adapt | 1 |
+---------------------------------+------------------------------------------------------------------------------+---------+
| comm_forward | size of buffer (in doubles) for forward communication (bond styles only) | 0 |
+---------------------------------+------------------------------------------------------------------------------+---------+
| comm_reverse | size of buffer (in doubles) for reverse communication (bond styles only) | 0 |
+---------------------------------+------------------------------------------------------------------------------+---------+
| comm_reverse_off | size of buffer for reverse communication with newton off (bond styles only) | 0 |
+---------------------------------+------------------------------------------------------------------------------+---------+

132
doc/src/Modify_pair.rst
View File

@ -1,35 +1,121 @@
Pair styles
===========
Classes that compute pairwise interactions are derived from the Pair
class. In LAMMPS, pairwise calculation include many-body potentials
such as EAM or Tersoff where particles interact without a static bond
topology. New styles can be created to add new pair potentials to
LAMMPS.
Classes that compute pairwise non-bonded interactions are derived from
the Pair class. In LAMMPS, pairwise calculation include many-body
potentials such as EAM, Tersoff, or ReaxFF where particles interact
without an explicit bond topology but include interactions beyond
pairwise non-bonded contributions. New styles can be created to add
support for additional pair potentials to LAMMPS. When the
modifications are small, sometimes it is more effective to derive from
an existing pair style class. This latter approach is also used by
:doc:`Accelerator packages <Speed_packages>` where the accelerated style
names differ from their base classes by an appended suffix.
Pair_lj_cut.cpp is a simple example of a Pair class, though it
includes some optional methods to enable its use with rRESPA.
The file ``src/pair_lj_cut.cpp`` is an example of a Pair class with a
very simple potential function. It includes several optional methods to
enable its use with :doc:`run_style respa <run_style>` and :doc:`compute
group/group <compute_group_group>`.
Here is a brief description of the class methods in pair.h:
Here is a brief list of some the class methods in the Pair class that
*must* be or *may* be overridden in a derived class.
+---------------------------------+---------------------------------------------------------------------+
| Required | "pure" methods that *must* be overridden in a derived class |
+=================================+=====================================================================+
| compute | workhorse routine that computes pairwise interactions |
+---------------------------------+---------------------------------------------------------------------+
| settings | reads the input script line with arguments you define |
| settings | processes the arguments to the pair_style command |
+---------------------------------+---------------------------------------------------------------------+
| coeff | set coefficients for one i,j type pair |
+---------------------------------+---------------------------------------------------------------------+
| init_one | perform initialization for one i,j type pair |
+---------------------------------+---------------------------------------------------------------------+
| init_style | initialization specific to this pair style |
+---------------------------------+---------------------------------------------------------------------+
| write & read_restart | write/read i,j pair coeffs to restart files |
+---------------------------------+---------------------------------------------------------------------+
| write & read_restart_settings | write/read global settings to restart files |
+---------------------------------+---------------------------------------------------------------------+
| single | force/r and energy of a single pairwise interaction between 2 atoms |
+---------------------------------+---------------------------------------------------------------------+
| compute_inner/middle/outer | versions of compute used by rRESPA |
| coeff | set coefficients for one i,j type pair, called from pair_coeff |
+---------------------------------+---------------------------------------------------------------------+
The inner/middle/outer routines are optional.
+---------------------------------+----------------------------------------------------------------------+
| Optional | methods that have a default or dummy implementation |
+=================================+======================================================================+
| init_one | perform initialization for one i,j type pair |
+---------------------------------+----------------------------------------------------------------------+
| init_style | style initialization: request neighbor list(s), error checks |
+---------------------------------+----------------------------------------------------------------------+
| init_list | Neighbor class callback function to pass neighbor list to pair style |
+---------------------------------+----------------------------------------------------------------------+
| single | force/r and energy of a single pairwise interaction between 2 atoms |
+---------------------------------+----------------------------------------------------------------------+
| compute_inner/middle/outer | versions of compute used by rRESPA |
+---------------------------------+----------------------------------------------------------------------+
| memory_usage | return estimated amount of memory used by the pair style |
+---------------------------------+----------------------------------------------------------------------+
| modify_params | process arguments to pair_modify command |
+---------------------------------+----------------------------------------------------------------------+
| extract | provide access to internal scalar or per-type data like cutoffs |
+---------------------------------+----------------------------------------------------------------------+
| extract_peratom | provide access to internal per-atom data |
+---------------------------------+----------------------------------------------------------------------+
| setup | initialization at the beginning of a run |
+---------------------------------+----------------------------------------------------------------------+
| finish | called at the end of a run, e.g. to print |
+---------------------------------+----------------------------------------------------------------------+
| write & read_restart | write/read i,j pair coeffs to restart files |
+---------------------------------+----------------------------------------------------------------------+
| write & read_restart_settings | write/read global settings to restart files |
+---------------------------------+----------------------------------------------------------------------+
| write_data | write Pair Coeffs section to data file |
+---------------------------------+----------------------------------------------------------------------+
| write_data_all | write PairIJ Coeffs section to data file |
+---------------------------------+----------------------------------------------------------------------+
| pack & unpack_forward_comm | copy data to and from buffer if style uses forward communication |
+---------------------------------+----------------------------------------------------------------------+
| pack & unpack_reverse_comm | copy data to and from buffer if style uses reverse communication |
+---------------------------------+----------------------------------------------------------------------+
| reinit | reset all type-based parameters, called by fix adapt for example |
+---------------------------------+----------------------------------------------------------------------+
| reset_dt | called when the time step is changed by timestep or fix reset/dt |
+---------------------------------+----------------------------------------------------------------------+
Here is a list of flags or settings that should be set in the
constructor of the derived pair class when they differ from the default
setting.
+---------------------------------+-------------------------------------------------------------+---------+
| Name of flag | Description | default |
+=================================+=============================================================+=========+
| single_enable | 1 if single() method is implemented, 0 if missing | 1 |
+---------------------------------+-------------------------------------------------------------+---------+
| respa_enable | 1 if pair style has compute_inner/middle/outer() | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| restartinfo | 1 if pair style writes its settings to a restart | 1 |
+---------------------------------+-------------------------------------------------------------+---------+
| one_coeff | 1 if only a pair_coeff * * command is allowed | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| manybody_flag | 1 if pair style is a manybody potential | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| unit_convert_flag | value != 0 indicates support for unit conversion | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| no_virial_fdotr_compute | 1 if pair style does not call virial_fdotr_compute() | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| writedata | 1 if write_data() and write_data_all() are implemented | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| comm_forward | size of buffer (in doubles) for forward communication | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| comm_reverse | size of buffer (in doubles) for reverse communication | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| ghostneigh | 1 if cutghost is set and style uses neighbors of ghosts | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| finitecutflag | 1 if cutoff depends on diameter of atoms | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| reinitflag | 1 if style has reinit() and is compatible with fix adapt | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| ewaldflag | 1 if compatible with kspace_style ewald | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| pppmflag | 1 if compatible with kspace_style pppm | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| msmflag | 1 if compatible with kspace_style msm | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| dispersionflag | 1 if compatible with ewald/disp or pppm/disp | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| tip4pflag | 1 if compatible with kspace_style pppm/tip4p | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| dipoleflag | 1 if compatible with dipole kspace_style | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| spinflag | 1 if compatible with spin kspace_style | 0 |
+---------------------------------+-------------------------------------------------------------+---------+

156
doc/src/Packages_details.rst
View File

@ -68,6 +68,7 @@ page gives those details.
* :ref:`KSPACE <PKG-KSPACE>`
* :ref:`LATBOLTZ <PKG-LATBOLTZ>`
* :ref:`LATTE <PKG-LATTE>`
* :ref:`LEPTON <PKG-LEPTON>`
* :ref:`MACHDYN <PKG-MACHDYN>`
* :ref:`MANIFOLD <PKG-MANIFOLD>`
* :ref:`MANYBODY <PKG-MANYBODY>`
@ -80,6 +81,7 @@ page gives those details.
* :ref:`ML-HDNNP <PKG-ML-HDNNP>`
* :ref:`ML-IAP <PKG-ML-IAP>`
* :ref:`ML-PACE <PKG-ML-PACE>`
* :ref:`ML-POD <PKG-ML-POD>`
* :ref:`ML-QUIP <PKG-ML-QUIP>`
* :ref:`ML-RANN <PKG-ML-RANN>`
* :ref:`ML-SNAP <PKG-ML-SNAP>`
@ -491,22 +493,21 @@ COLVARS package
**Contents:**
COLVARS stands for collective variables, which can be used to
implement various enhanced sampling methods, including Adaptive
Biasing Force, Metadynamics, Steered MD, Umbrella Sampling and
Restraints. A :doc:`fix colvars <fix_colvars>` command is implemented
which wraps a COLVARS library, which implements these methods.
simulations.
Colvars stands for collective variables, which can be used to implement
various enhanced sampling methods, including Adaptive Biasing Force,
Metadynamics, Steered MD, Umbrella Sampling and Restraints. A :doc:`fix
colvars <fix_colvars>` command is implemented which wraps a COLVARS
library, which implements these methods. simulations.
**Authors:** The COLVARS library is written and maintained by
Giacomo Fiorin (ICMS, Temple University, Philadelphia, PA, USA)
and Jerome Henin (LISM, CNRS, Marseille, France), originally for
the NAMD MD code, but with portability in mind. Axel Kohlmeyer
(Temple U) provided the interface to LAMMPS.
**Authors:** The COLVARS library is written and maintained by Giacomo
Fiorin (NIH, Bethesda, MD, USA) and Jerome Henin (CNRS, Paris, France),
originally for the NAMD MD code, but with portability in mind. Axel
Kohlmeyer (Temple U) provided the interface to LAMMPS.
**Install:**
This package has :ref:`specific installation instructions <colvars>` on the :doc:`Build extras <Build_extras>` page.
This package has :ref:`specific installation instructions <colvar>` on
the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -515,6 +516,8 @@ This package has :ref:`specific installation instructions <colvars>` on the :doc
* src/COLVARS/README
* lib/colvars/README
* :doc:`fix colvars <fix_colvars>`
* :doc:`group2ndx <group2ndx>`
* :doc:`ndx2group <group2ndx>`
* examples/PACKAGES/colvars
----------
@ -559,9 +562,10 @@ CORESHELL package
Compute and pair styles that implement the adiabatic core/shell model
for polarizability. The pair styles augment Born, Buckingham, and
Lennard-Jones styles with core/shell capabilities. The :doc:`compute temp/cs <compute_temp_cs>` command calculates the temperature of a
system with core/shell particles. See the :doc:`Howto coreshell <Howto_coreshell>` page for an overview of how to use
this package.
Lennard-Jones styles with core/shell capabilities. The :doc:`compute
temp/cs <compute_temp_cs>` command calculates the temperature of a
system with core/shell particles. See the :doc:`Howto coreshell
<Howto_coreshell>` page for an overview of how to use this package.
**Author:** Hendrik Heenen (Technical U of Munich).
@ -865,7 +869,7 @@ ELECTRODE package
The ELECTRODE package allows the user to enforce a constant potential method for
groups of atoms that interact with the remaining atoms as electrolyte.
**Authors:** The ELECTRODE library is written and maintained by Ludwig
**Authors:** The ELECTRODE package is written and maintained by Ludwig
Ahrens-Iwers (TUHH, Hamburg, Germany), Shern Tee (UQ, Brisbane, Australia) and
Robert Meissner (TUHH, Hamburg, Germany).
@ -878,7 +882,7 @@ This package has :ref:`specific installation instructions <electrode>` on the
**Supporting info:**
* :doc:`fix electrode/conp <fix_electrode_conp>`
* :doc:`fix electrode/conp <fix_electrode>`
----------
@ -973,10 +977,11 @@ FEP package
**Contents:**
FEP stands for free energy perturbation. This package provides
methods for performing FEP simulations by using a :doc:`fix adapt/fep <fix_adapt_fep>` command with soft-core pair potentials,
which have a "soft" in their style name. There are auxiliary tools
for using this package in tools/fep; see its README file.
FEP stands for free energy perturbation. This package provides methods
for performing FEP simulations by using a :doc:`fix adapt/fep
<fix_adapt_fep>` command with soft-core pair potentials, which have a
"soft" in their style name. There are auxiliary tools for using this
package in tools/fep; see its README file.
**Author:** Agilio Padua (ENS de Lyon)
@ -1017,7 +1022,8 @@ Kuznetsov, Vladimir Stegailov, and Vsevolod Nikolskiy (HSE University).
**Install:**
This package has :ref:`specific installation instructions <gpu>` on the :doc:`Build extras <Build_extras>` page.
This package has :ref:`specific installation instructions <gpu>` on the
:doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1370,7 +1376,8 @@ Cawkwell, Anders Niklasson, and Christian Negre.
**Install:**
This package has :ref:`specific installation instructions <latte>` on the :doc:`Build extras <Build_extras>` page.
This package has :ref:`specific installation instructions <latte>` on
the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1383,6 +1390,46 @@ This package has :ref:`specific installation instructions <latte>` on the :doc:`
----------
.. _PKG-LEPTON:
LEPTON package
--------------
**Contents:**
Styles for pair, bond, and angle forces that evaluate the potential
function from a string using the `Lepton mathematical expression parser
<https://simtk.org/projects/lepton>`_. Lepton is a C++ library that is
bundled with `OpenMM <https://openmm.org/>`_ and can be used for
parsing, evaluating, differentiating, and analyzing mathematical
expressions. This is a more lightweight and efficient alternative for
evaluating custom potential function to an embedded Python interpreter
as used in the :ref:`PYTHON package <PKG-PYTHON>`. On the other hand,
since the potentials are evaluated form analytical expressions, they are
more precise than what can be done with :ref:`tabulated potentials
<tabulate>`.
**Authors:** Axel Kohlmeyer (Temple U). Lepton itself is developed
by Peter Eastman at Stanford University.
.. versionadded:: TBD
**Install:**
This package has :ref:`specific installation instructions <lepton>` on
the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
* src/LEPTON: filenames -> commands
* lib/lepton/README.md
* :doc:`pair_style lepton <pair_lepton>`
* :doc:`bond_style lepton <bond_lepton>`
* :doc:`angle_style lepton <angle_lepton>`
* :doc:`dihedral_style lepton <dihedral_lepton>`
----------
.. _PKG-MACHDYN:
MACHDYN package
@ -1485,8 +1532,9 @@ MC package
Several fixes and a pair style that have Monte Carlo (MC) or MC-like
attributes. These include fixes for creating, breaking, and swapping
bonds, for performing atomic swaps, and performing grand-canonical MC
(GCMC) or similar processes in conjunction with dynamics.
bonds, for performing atomic swaps, and performing grand canonical
MC (GCMC), semi-grand canonical MC (SGCMC), or similar processes in
conjunction with molecular dynamics (MD).
**Supporting info:**
@ -1498,6 +1546,7 @@ bonds, for performing atomic swaps, and performing grand-canonical MC
* :doc:`fix bond/swap <fix_bond_swap>`
* :doc:`fix charge/regulation <fix_charge_regulation>`
* :doc:`fix gcmc <fix_gcmc>`
* :doc:`fix sgcmc <fix_sgcmc>`
* :doc:`fix tfmc <fix_tfmc>`
* :doc:`fix widom <fix_widom>`
* :doc:`pair_style dsmc <pair_dsmc>`
@ -1796,6 +1845,39 @@ This package has :ref:`specific installation instructions <ml-pace>` on the
----------
.. _PKG-ML-POD:
ML-POD package
-------------------
**Contents:**
A pair style and fitpod style for Proper Orthogonal Descriptors
(POD). POD is a methodology for deriving descriptors based on the proper
orthogonal decomposition. The ML-POD package provides an efficient
implementation for running simulations with POD potentials, along with
fitting the potentials natively in LAMMPS.
**Authors:**
Ngoc Cuong Nguyen (MIT), Andrew Rohskopf (Sandia)
.. versionadded:: 22Dec2022
**Install:**
This package has :ref:`specific installation instructions <ml-pod>` on the
:doc:`Build extras <Build_extras>` page.
**Supporting info:**
* src/ML-POD: filenames -> commands
* :doc:`pair_style pod <pair_pod>`
* :doc:`command_style fitpod <fitpod_command>`
* examples/PACKAGES/pod
----------
.. _PKG-ML-QUIP:
ML-QUIP package
@ -2508,17 +2590,18 @@ REACTION package
**Contents:**
This package allows for complex bond topology changes (reactions)
during a running MD simulation, when using classical force fields.
Topology changes are defined in pre- and post-reaction molecule
templates and can include creation and deletion of bonds, angles,
dihedrals, impropers, atom types, bond types, angle types, dihedral
types, improper types, and/or atomic charges. Other options currently
available include reaction constraints (e.g. angle and Arrhenius
constraints), deletion of reaction byproducts or other small
molecules, and chiral-sensitive reactions.
This package implements the REACTER protocol, which allows for complex
bond topology changes (reactions) during a running MD simulation when
using classical force fields. Topology changes are defined in pre- and
post-reaction molecule templates and can include creation and deletion
of bonds, angles, dihedrals, impropers, atom types, bond types, angle
types, dihedral types, improper types, and/or atomic charges. Other
options currently available include reaction constraints (e.g., angle
and Arrhenius constraints), deletion of reaction byproducts or other
small molecules, creation of new atoms or molecules bonded to existing
atoms, and using LAMMPS variables for input parameters.
**Author:** Jacob R. Gissinger (CU Boulder) while at NASA Langley Research Center.
**Author:** Jacob R. Gissinger (NASA Langley Research Center).
**Supporting info:**
@ -2528,7 +2611,8 @@ molecules, and chiral-sensitive reactions.
* examples/PACKAGES/reaction
* `2017 LAMMPS Workshop <https://www.lammps.org/workshops/Aug17/pdf/gissinger.pdf>`_
* `2019 LAMMPS Workshop <https://www.lammps.org/workshops/Aug19/talk_gissinger.pdf>`_
* reacter.org
* `2021 LAMMPS Workshop <https://www.lammps.org/workshops/Aug21/talk/jacob-gissinger/>`_
* `REACTER website (reacter.org) <https://www.reacter.org/>`_
----------

30
doc/src/Packages_list.rst
View File

@ -8,10 +8,10 @@ Packages are supported by either the LAMMPS developers or the
contributing authors and written in a syntax and style consistent with
the rest of LAMMPS.
The "Example" column is a sub-directory in the examples directory of the
distribution which has an input script that uses the package.
The "Examples" column is a sub-directory in the examples directory of the
distribution which has one or more input scripts that use the package.
E.g. "peptide" refers to the examples/peptide directory; PACKAGES/atc refers
to the examples/PACKAGES/atc directory. The "Library" column indicates
to the examples/PACKAGES/atc directory. The "Lib" column indicates
whether an extra library is needed to build and use the package:
* no = no library
@ -26,8 +26,8 @@ whether an extra library is needed to build and use the package:
* - Package
- Description
- Doc page
- Example
- Library
- Examples
- Lib
* - :ref:`ADIOS <PKG-ADIOS>`
- dump output via ADIOS
- :doc:`dump adios <dump_adios>`
@ -94,7 +94,7 @@ whether an extra library is needed to build and use the package:
- colloid
- no
* - :ref:`COLVARS <PKG-COLVARS>`
- collective variables library
- `Colvars collective variables library <https://colvars.github.io/>`_
- :doc:`fix colvars <fix_colvars>`
- PACKAGES/colvars
- int
@ -125,7 +125,7 @@ whether an extra library is needed to build and use the package:
- no
* - :ref:`DPD-BASIC <PKG-DPD-BASIC>`
- basic DPD models
- :doc:`pair_styles dpd dpd/tstat <pair_dpd>` :doc:`dpd/ext dpd/ext/tstat <pair_dpd_ext>`
- :doc:`pair_styles dpd <pair_dpd>` :doc:`dpd/ext <pair_dpd_ext>`
- PACKAGES/dpd-basic
- no
* - :ref:`DPD-MESO <PKG-DPD-MESO>`
@ -155,7 +155,7 @@ whether an extra library is needed to build and use the package:
- no
* - :ref:`ELECTRODE <PKG-ELECTRODE>`
- electrode charges to match potential
- :doc:`fix electrode/conp <fix_electrode_conp>`
- :doc:`fix electrode/conp <fix_electrode>`
- PACKAGES/electrode
- no
* - :ref:`EXTRA-COMPUTE <PKG-EXTRA-COMPUTE>`
@ -238,6 +238,11 @@ whether an extra library is needed to build and use the package:
- :doc:`fix latte <fix_latte>`
- latte
- ext
* - :ref:`LEPTON <PKG-LEPTON>`
- evaluate strings as potential function
- :doc:`pair_style lepton <pair_lepton>`
- PACKAGES/lepton
- int
* - :ref:`MACHDYN <PKG-MACHDYN>`
- smoothed Mach dynamics
- `SMD User Guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_
@ -298,6 +303,11 @@ whether an extra library is needed to build and use the package:
- :doc:`pair pace <pair_pace>`
- PACKAGES/pace
- ext
* - :ref:`ML-POD <PKG-ML-POD>`
- Proper orthogonal decomposition potentials
- :doc:`pair pod <pair_pod>`
- pod
- ext
* - :ref:`ML-QUIP <PKG-ML-QUIP>`
- QUIP/libatoms interface
- :doc:`pair_style quip <pair_quip>`
@ -374,7 +384,7 @@ whether an extra library is needed to build and use the package:
- plugins
- no
* - :ref:`PLUMED <PKG-PLUMED>`
- :ref:`PLUMED <PLUMED>` free energy library
- `PLUMED free energy library <https://www.plumed.org>`_
- :doc:`fix plumed <fix_plumed>`
- PACKAGES/plumed
- ext
@ -440,7 +450,7 @@ whether an extra library is needed to build and use the package:
- no
* - :ref:`SMTBQ <PKG-SMTBQ>`
- second moment tight binding potentials
- :doc:`pair_style smtbq <pair_smtbq>` :doc:`pair_style smatb <pair_smatb>`
- pair styles :doc:`smtbq <pair_smtbq>`, :doc:`smatb <pair_smatb>`
- PACKAGES/smtbq
- no
* - :ref:`SPH <PKG-SPH>`

4
doc/src/Python_atoms.rst
View File

@ -58,7 +58,7 @@ against invalid accesses.
Each element of this list is a :py:class:`Atom <lammps.Atom>` or :py:class:`Atom2D <lammps.Atom2D>` object. The attributes of
these objects provide access to their data (id, type, position, velocity, force, etc.):
.. code-block:: Python
.. code-block:: python
# access first atom
L.atoms[0].id
@ -71,7 +71,7 @@ against invalid accesses.
Some attributes can be changed:
.. code-block:: Python
.. code-block:: python
# set position in 2D simulation
L.atoms[0].position = (1.0, 0.0)

2
doc/src/Python_config.rst
View File

@ -4,7 +4,7 @@ Configuration information
The following methods can be used to query the LAMMPS library
about compile time settings and included packages and styles.
.. code-block:: Python
.. code-block:: python
:caption: Example for using configuration settings functions
from lammps import lammps

6
doc/src/Python_create.rst
View File

@ -74,7 +74,7 @@ Here are simple examples using all three Python interfaces:
:py:class:`PyLammps <lammps.PyLammps>` objects can also be created on top of an existing
:py:class:`lammps <lammps.lammps>` object:
.. code-block:: Python
.. code-block:: python
from lammps import lammps, PyLammps
...
@ -113,7 +113,7 @@ Here are simple examples using all three Python interfaces:
You can also initialize IPyLammps on top of an existing :py:class:`lammps` or :py:class:`PyLammps` object:
.. code-block:: Python
.. code-block:: python
from lammps import lammps, IPyLammps
...
@ -142,7 +142,7 @@ the MPI and/or Kokkos environment if enabled and active.
Note that you can create multiple LAMMPS objects in your Python
script, and coordinate and run multiple simulations, e.g.
.. code-block:: Python
.. code-block:: python
from lammps import lammps
lmp1 = lammps()

2
doc/src/Python_error.rst
View File

@ -7,7 +7,7 @@ current Python process with an error message. C++ exceptions allow capturing
them on the C++ side and rethrowing them on the Python side. This way
LAMMPS errors can be handled through the Python exception handling mechanism.
.. code-block:: Python
.. code-block:: python
from lammps import lammps, MPIAbortException

8
doc/src/Python_execute.rst
View File

@ -60,7 +60,7 @@ it is possible to "compute" what the next LAMMPS command should be.
can be executed using with the lammps API with the following Python code if ``lmp`` is an
instance of :py:class:`lammps <lammps.lammps>`:
.. code-block:: Python
.. code-block:: python
from lammps import lammps
@ -73,7 +73,7 @@ it is possible to "compute" what the next LAMMPS command should be.
The arguments of the command can be passed as one string, or
individually.
.. code-block:: Python
.. code-block:: python
from lammps import PyLammps
@ -93,14 +93,14 @@ it is possible to "compute" what the next LAMMPS command should be.
parameterization. In the lammps API parameterization needed to be done
manually by creating formatted command strings.
.. code-block:: Python
.. code-block:: python
lmp.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi))
In contrast, methods of PyLammps accept parameters directly and will convert
them automatically to a final command string.
.. code-block:: Python
.. code-block:: python
L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi)

28
doc/src/Python_install.rst
View File

@ -54,7 +54,7 @@ folder that the dynamic loader searches or inside of the installed
``-DBUILD_SHARED_LIBS=on``, ``-DLAMMPS_EXCEPTIONS=on`` and
``-DPKG_PYTHON=on`` (The first option is required, the other two
are optional by recommended). The exact file name of the shared
library depends on the platform (Unix/Linux, MacOS, Windows) and
library depends on the platform (Unix/Linux, macOS, Windows) and
the build configuration being used. The installation base folder
is already set by default to the ``$HOME/.local`` directory, but
it can be changed to a custom location defined by the
@ -121,7 +121,7 @@ folder that the dynamic loader searches or inside of the installed
the folder containing the LAMMPS shared library is either included
in a path searched by the shared linker (e.g. like
``/usr/lib64/``) or part of the ``LD_LIBRARY_PATH`` environment
variable (or ``DYLD_LIBRARY_PATH`` on MacOS). Otherwise you will
variable (or ``DYLD_LIBRARY_PATH`` on macOS). Otherwise you will
get an error when trying to create a LAMMPS object through the
Python module.
@ -130,7 +130,7 @@ folder that the dynamic loader searches or inside of the installed
# Unix/Linux
export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
# MacOS
# macOS
export DYLD_LIBRARY_PATH=$HOME/.local/lib:$DYLD_LIBRARY_PATH
If you plan to use the LAMMPS executable (e.g., ``lmp``), you may
@ -214,7 +214,7 @@ folder that the dynamic loader searches or inside of the installed
.. code-block:: bash
$ python install.py -p <python package> -l <shared library> [-n]
python install.py -p <python package> -l <shared library> [-n]
* The ``-p`` flag points to the ``lammps`` Python package folder to be installed,
* the ``-l`` flag points to the LAMMPS shared library file to be installed,
@ -294,7 +294,7 @@ folder that the dynamic loader searches or inside of the installed
script in a similar fashion you need to update your
``$HOME/.bashrc`` file to include the shared library and
executable locations in ``LD_LIBRARY_PATH`` (or
``DYLD_LIBRARY_PATH`` on MacOS) and ``PATH``, respectively.
``DYLD_LIBRARY_PATH`` on macOS) and ``PATH``, respectively.
For example with:
@ -303,7 +303,7 @@ folder that the dynamic loader searches or inside of the installed
# Unix/Linux
echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
# MacOS
# macOS
echo 'export DYLD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$DYLD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
.. tab:: In place usage
@ -313,7 +313,7 @@ folder that the dynamic loader searches or inside of the installed
package inside the source/compilation folders. Instead of
copying the files where they can be found, you need to set the environment
variables ``PYTHONPATH`` (for the Python package) and
``LD_LIBRARY_PATH`` (or ``DYLD_LIBRARY_PATH`` on MacOS
``LD_LIBRARY_PATH`` (or ``DYLD_LIBRARY_PATH`` on macOS
For Bourne shells (bash, ksh and similar) the commands are:
@ -329,7 +329,7 @@ folder that the dynamic loader searches or inside of the installed
setenv PYTHONPATH ${PYTHONPATH}:${HOME}/lammps/python
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${HOME}/lammps/src
On MacOS you may also need to set ``DYLD_LIBRARY_PATH`` accordingly.
On macOS you may also need to set ``DYLD_LIBRARY_PATH`` accordingly.
You can make those changes permanent by editing your ``$HOME/.bashrc``
or ``$HOME/.login`` files, respectively.
@ -343,7 +343,7 @@ Python interpreter, load the ``lammps`` Python module and create a
LAMMPS instance. This should not generate an error message and produce
output similar to the following:
.. code-block:: bash
.. code-block:: console
$ python
Python 3.8.5 (default, Sep 5 2020, 10:50:12)
@ -403,7 +403,7 @@ follows:
- Via ``pip`` into a virtual environment (see above):
.. code-block:: bash
.. code-block:: console
$ source $HOME/myenv/activate
(myenv)$ pip install mpi4py
@ -449,7 +449,7 @@ on a simple test script
.. code-block:: bash
$ mpirun -np 4 python3 test.py
mpirun -np 4 python3 test.py
where ``test.py`` contains the lines
@ -459,11 +459,11 @@ where ``test.py`` contains the lines
comm = MPI.COMM_WORLD
print("Proc %d out of %d procs" % (comm.Get_rank(),comm.Get_size()))
and see one line of output for each processor you run on.
and see one line of output for each processor you run on. Please note
that the order of the lines is not deterministic
.. code-block:: bash
.. code-block:: console
# NOTE: the line order is not deterministic
$ mpirun -np 4 python3 test.py
Proc 0 out of 4 procs
Proc 1 out of 4 procs

40
doc/src/Python_launch.rst
View File

@ -6,15 +6,15 @@ interactively from the ``bench`` directory:
.. code-block:: python
>>> from lammps import lammps
>>> lmp = lammps()
>>> lmp.file("in.lj")
from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
Or put the same lines in the file ``test.py`` and run it as
.. code-block:: bash
$ python3 test.py
python3 test.py
Either way, you should see the results of running the ``in.lj`` benchmark
on a single processor appear on the screen, the same as if you had
@ -46,17 +46,17 @@ You can run the script in parallel as:
.. code-block:: bash
$ mpirun -np 4 python3 test.py
mpirun -np 4 python3 test.py
and you should see the same output as if you had typed
.. code-block:: bash
$ mpirun -np 4 lmp_mpi -in in.lj
mpirun -np 4 lmp_mpi -in in.lj
Note that without the mpi4py specific lines from ``test.py``
.. code-block:: Python
.. code-block:: python
from lammps import lammps
lmp = lammps()
@ -82,9 +82,9 @@ one of several ways:
.. code-block:: bash
$ python script.py
$ python -i script.py
$ ./script.py
python script.py
python -i script.py
./script.py
The last command requires that the first line of the script be
something like this:
@ -92,17 +92,23 @@ something like this:
.. code-block:: bash
#!/usr/bin/python
#!/usr/bin/python -i
where the path points to where you have Python installed, and that you
have made the script file executable:
or
.. code-block:: bash
$ chmod +x script.py
#!/usr/bin/env python
where the path in the first case needs to point to where you have Python
installed (the second option is workaround for when this may change),
and that you have made the script file executable:
.. code-block:: bash
chmod +x script.py
Without the ``-i`` flag, Python will exit when the script finishes.
With the ``-i`` flag, you will be left in the Python interpreter when
the script finishes, so you can type subsequent commands. As
mentioned above, you can only run Python interactively when running
Python on a single processor, not in parallel.
the script finishes, so you can type subsequent commands. As mentioned
above, you can only run Python interactively when running Python on a
single processor, not in parallel.

6
doc/src/Python_objects.rst
View File

@ -76,7 +76,7 @@ computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
To define a variable you can use the :doc:`variable <variable>` command:
.. code-block:: Python
.. code-block:: python
L.variable("a index 2")
@ -85,14 +85,14 @@ computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
you can access an individual variable by retrieving a variable object from the
``L.variables`` dictionary by name
.. code-block:: Python
.. code-block:: python
a = L.variables['a']
The variable value can then be easily read and written by accessing the value
property of this object.
.. code-block:: Python
.. code-block:: python
print(a.value)
a.value = 4

18
doc/src/Python_overview.rst
View File

@ -32,7 +32,7 @@ standard Python distribution since version 2.5. You can check which
version of Python you have by simply typing "python" at a shell prompt.
Below is an example output for Python version 3.8.5.
.. code-block::
.. code-block:: console
$ python
Python 3.8.5 (default, Aug 12 2020, 00:00:00)
@ -43,12 +43,16 @@ Below is an example output for Python version 3.8.5.
.. warning::
The options described in this section of the manual for using Python with
LAMMPS currently support either Python 2 or 3. Specifically version 2.7 or
later and 3.6 or later. Since the Python community no longer maintains Python
2 (see `this notice <https://www.python.org/doc/sunset-python-2/>`_), we
recommend use of Python 3 with LAMMPS. While Python 2 code should continue to
work, that is not something we can guarantee long-term.
The options described in this section of the manual for using Python
with LAMMPS currently support either Python 2 or 3. Specifically
version 2.7 or later and 3.6 or later. Since the Python community no
longer maintains Python 2 (see `this notice
<https://www.python.org/doc/sunset-python-2/>`_), we recommend use of
Python 3 with LAMMPS. While Python 2 code should continue to work,
that is not something we can guarantee long-term. If you notice
Python code in the LAMMPS distribution that is not compatible with
Python 3, please contact the LAMMPS developers or submit `and issue
on GitHub <https://github.com/lammps/lammps/issues>`_
---------

2
doc/src/Python_properties.rst
View File

@ -105,7 +105,7 @@ against invalid accesses.
variables, compute or fix data (see :doc:`Howto_output`):
.. code-block:: Python
.. code-block:: python
result = L.eval("ke") # kinetic energy
result = L.eval("pe") # potential energy

4
doc/src/Python_scatter.rst
View File

@ -1,7 +1,7 @@
Scatter/gather operations
=========================
.. code-block:: Python
.. code-block:: python
data = lmp.gather_atoms(name,type,count) # return per-atom property of all atoms gathered into data, ordered by atom ID
# name = "x", "charge", "type", etc
@ -42,7 +42,7 @@ For the scatter methods, the array of coordinates passed to must be a
ctypes vector of ints or doubles, allocated and initialized something
like this:
.. code-block:: Python
.. code-block:: python
from ctypes import c_double
natoms = lmp.get_natoms()

22
doc/src/Run_basics.rst
View File

@ -12,15 +12,15 @@ build LAMMPS:
.. code-block:: bash
$ lmp_serial -in in.file
$ lmp_serial < in.file
$ lmp -in in.file
$ lmp < in.file
$ /path/to/lammps/src/lmp_serial -i in.file
$ mpirun -np 4 lmp_mpi -in in.file
$ mpiexec -np 4 lmp -in in.file
$ mpirun -np 8 /path/to/lammps/src/lmp_mpi -in in.file
$ mpiexec -n 6 /usr/local/bin/lmp -in in.file
lmp_serial -in in.file
lmp_serial < in.file
lmp -in in.file
lmp < in.file
/path/to/lammps/src/lmp_serial -i in.file
mpirun -np 4 lmp_mpi -in in.file
mpiexec -np 4 lmp -in in.file
mpirun -np 8 /path/to/lammps/src/lmp_mpi -in in.file
mpiexec -n 6 /usr/local/bin/lmp -in in.file
You normally run the LAMMPS command in the directory where your input
script is located. That is also where output files are produced by
@ -78,8 +78,8 @@ variable OMP_NUM_THREADS, before you launch LAMMPS:
.. code-block:: bash
$ export OMP_NUM_THREADS=2 # bash
$ setenv OMP_NUM_THREADS 2 # csh or tcsh
export OMP_NUM_THREADS=2 # bash
setenv OMP_NUM_THREADS 2 # csh or tcsh
This can also be done via the :doc:`package <package>` command or via
the :doc:`-pk command-line switch <Run_options>` which invokes the

40
doc/src/Run_options.rst
View File

@ -31,8 +31,8 @@ For example, the lmp_mpi executable might be launched as follows:
.. code-block:: bash
$ mpirun -np 16 lmp_mpi -v f tmp.out -l my.log -sc none -i in.alloy
$ mpirun -np 16 lmp_mpi -var f tmp.out -log my.log -screen none -in in.alloy
mpirun -np 16 lmp_mpi -v f tmp.out -l my.log -sc none -i in.alloy
mpirun -np 16 lmp_mpi -var f tmp.out -log my.log -screen none -in in.alloy
----------
@ -444,7 +444,7 @@ the LAMMPS simulation domain.
.. _restart2data:
**-restart2data restartfile [remap] datafile keyword value ...**
**-restart2data restartfile datafile keyword value ...**
Convert the restart file into a data file and immediately exit. This
is the same operation as if the following 2-line input script were
@ -452,7 +452,7 @@ run:
.. code-block:: LAMMPS
read_restart restartfile [remap]
read_restart restartfile
write_data datafile keyword value ...
The specified restartfile and/or datafile name may contain the wild-card
@ -464,28 +464,21 @@ Note that a filename such as file.\* may need to be enclosed in quotes or
the "\*" character prefixed with a backslash ("\") to avoid shell
expansion of the "\*" character.
Following restartfile argument, the optional word "remap" may be used.
This has the same effect like adding it to a
:doc:`read_restart <read_restart>` command, and operates as explained on
its doc page. This is useful if reading the restart file triggers an
error that atoms have been lost. In that case, use of the remap flag
should allow the data file to still be produced.
The syntax following restartfile (or remap), namely
The syntax following restartfile, namely
.. parsed-literal::
datafile keyword value ...
is identical to the arguments of the :doc:`write_data <write_data>`
command. See its page for details. This includes its
command. See its documentation page for details. This includes its
optional keyword/value settings.
----------
.. _restart2dump:
**-restart2dump restartfile [remap] group-ID dumpstyle dumpfile arg1 arg2 ...**
**-restart2dump restartfile group-ID dumpstyle dumpfile arg1 arg2 ...**
Convert the restart file into a dump file and immediately exit. This
is the same operation as if the following 2-line input script were
@ -493,7 +486,7 @@ run:
.. code-block:: LAMMPS
read_restart restartfile [remap]
read_restart restartfile
write_dump group-ID dumpstyle dumpfile arg1 arg2 ...
Note that the specified restartfile and dumpfile names may contain
@ -505,24 +498,17 @@ such as file.\* may need to be enclosed in quotes or the "\*" character
prefixed with a backslash ("\") to avoid shell expansion of the "\*"
character.
Note that following the restartfile argument, the optional word "remap"
can be used. This has the effect as adding it to the
:doc:`read_restart <read_restart>` command, as explained on its doc page.
This is useful if reading the restart file triggers an error that atoms
have been lost. In that case, use of the remap flag should allow the
dump file to still be produced.
The syntax following restartfile (or remap), namely
The syntax following restartfile, namely
.. code-block:: LAMMPS
group-ID dumpstyle dumpfile arg1 arg2 ...
is identical to the arguments of the :doc:`write_dump <write_dump>`
command. See its page for details. This includes what per-atom
fields are written to the dump file and optional dump_modify settings,
including ones that affect how parallel dump files are written, e.g.
the *nfile* and *fileper* keywords. See the
command. See its documentation page for details. This includes what
per-atom fields are written to the dump file and optional dump_modify
settings, including ones that affect how parallel dump files are written,
e.g. the *nfile* and *fileper* keywords. See the
:doc:`dump_modify <dump_modify>` page for details.
----------

40
doc/src/Speed_kokkos.rst
View File

@ -212,14 +212,15 @@ threads/task as Nt. The product of these two values should be N, i.e.
.. note::
The default for the :doc:`package kokkos <package>` command when
running on KNL is to use "half" neighbor lists and set the Newton flag
to "on" for both pairwise and bonded interactions. This will typically
be best for many-body potentials. For simpler pairwise potentials, it
may be faster to use a "full" neighbor list with Newton flag to "off".
Use the "-pk kokkos" :doc:`command-line switch <Run_options>` to change
the default :doc:`package kokkos <package>` options. See its page for
details and default settings. Experimenting with its options can provide
a speed-up for specific calculations. For example:
running on KNL is to use "half" neighbor lists and set the Newton
flag to "on" for both pairwise and bonded interactions. This will
typically be best for many-body potentials. For simpler pairwise
potentials, it may be faster to use a "full" neighbor list with
Newton flag to "off". Use the "-pk kokkos" :doc:`command-line switch
<Run_options>` to change the default :doc:`package kokkos <package>`
options. See its documentation page for details and default
settings. Experimenting with its options can provide a speed-up for
specific calculations. For example:
.. code-block:: bash
@ -271,17 +272,18 @@ one or more nodes, each with two GPUs:
.. note::
The default for the :doc:`package kokkos <package>` command when
running on GPUs is to use "full" neighbor lists and set the Newton flag
to "off" for both pairwise and bonded interactions, along with threaded
communication. When running on Maxwell or Kepler GPUs, this will
typically be best. For Pascal GPUs and beyond, using "half" neighbor lists and
setting the Newton flag to "on" may be faster. For many pair styles,
setting the neighbor binsize equal to twice the CPU default value will
give speedup, which is the default when running on GPUs. Use the "-pk
kokkos" :doc:`command-line switch <Run_options>` to change the default
:doc:`package kokkos <package>` options. See its page for details and
default settings. Experimenting with its options can provide a speed-up
for specific calculations. For example:
running on GPUs is to use "full" neighbor lists and set the Newton
flag to "off" for both pairwise and bonded interactions, along with
threaded communication. When running on Maxwell or Kepler GPUs, this
will typically be best. For Pascal GPUs and beyond, using "half"
neighbor lists and setting the Newton flag to "on" may be faster. For
many pair styles, setting the neighbor binsize equal to twice the CPU
default value will give speedup, which is the default when running on
GPUs. Use the "-pk kokkos" :doc:`command-line switch <Run_options>`
to change the default :doc:`package kokkos <package>` options. See
its documentation page for details and default
settings. Experimenting with its options can provide a speed-up for
specific calculations. For example:
.. code-block:: bash

60
doc/src/Tools.rst
View File

@ -57,7 +57,7 @@ Pre-processing tools
* :ref:`msi2lmp <msi>`
* :ref:`polybond <polybond>`
* :ref:`stl_bin2txt <stlconvert>`
* :ref:`tabulate <tabulate>`
Post-processing tools
=====================
@ -683,7 +683,7 @@ or (as administrator) to ``/etc/magic`` (for a system-wide
installation). Afterwards the ``file`` command should be able to
detect most LAMMPS restarts, dump, data and log files. Examples:
.. code-block:: bash
.. code-block:: console
$ file *.*
dihedral-quadratic.restart: LAMMPS binary restart file (rev 2), Version 10 Mar 2021, Little Endian
@ -1100,18 +1100,18 @@ for Tcl with:
.. code-block:: bash
$ swig -tcl -module tcllammps lammps.i
$ gcc -fPIC -shared $(pkgconf --cflags tcl) -o tcllammps.so \
swig -tcl -module tcllammps lammps.i
gcc -fPIC -shared $(pkgconf --cflags tcl) -o tcllammps.so \
lammps_wrap.c -L ../src/ -llammps
$ tclsh
tclsh
Or one can build an extended Tcl shell command with the wrapped
functions included with:
.. code-block:: bash
$ swig -tcl -module tcllmps lammps_shell.i
$ gcc -o tcllmpsh lammps_wrap.c -Xlinker -export-dynamic \
swig -tcl -module tcllmps lammps_shell.i
gcc -o tcllmpsh lammps_wrap.c -Xlinker -export-dynamic \
-DHAVE_CONFIG_H $(pkgconf --cflags tcl) \
$(pkgconf --libs tcl) -L ../src -llammps
@ -1142,20 +1142,34 @@ For illustration purposes below is a part of the Tcl example script.
.. code-block:: tcl
% load ./tcllammps.so
% set lmp [lammps_open_no_mpi 0 NULL NULL]
% lammps_command $lmp "units real"
% lammps_command $lmp "lattice fcc 2.5"
% lammps_command $lmp "region box block -5 5 -5 5 -5 5"
% lammps_command $lmp "create_box 1 box"
% lammps_command $lmp "create_atoms 1 box"
%
% set dt [doublep_value [voidp_to_doublep [lammps_extract_global $lmp dt]]]
% puts "LAMMPS version $ver"
% puts [format "Number of created atoms: %g" [lammps_get_natoms $lmp]]
% puts "Current size of timestep: $dt"
% puts "LAMMPS version: [lammps_version $lmp]"
% lammps_close $lmp
load ./tcllammps.so
set lmp [lammps_open_no_mpi 0 NULL NULL]
lammps_command $lmp "units real"
lammps_command $lmp "lattice fcc 2.5"
lammps_command $lmp "region box block -5 5 -5 5 -5 5"
lammps_command $lmp "create_box 1 box"
lammps_command $lmp "create_atoms 1 box"
set dt [doublep_value [voidp_to_doublep [lammps_extract_global $lmp dt]]]
puts "LAMMPS version $ver"
puts [format "Number of created atoms: %g" [lammps_get_natoms $lmp]]
puts "Current size of timestep: $dt"
puts "LAMMPS version: [lammps_version $lmp]"
lammps_close $lmp
----------
.. _tabulate:
tabulate tool
--------------
.. versionadded:: 22Dec2022
The ``tabulate`` folder contains Python scripts scripts to generate tabulated
potential files for LAMMPS. The bulk of the code is in the ``tabulate`` module
in the ``tabulate.py`` file. Some example files demonstrating its use are
included. See the README file for more information.
----------
@ -1164,8 +1178,8 @@ For illustration purposes below is a part of the Tcl example script.
vim tool
------------------
The files in the tools/vim directory are add-ons to the VIM editor
that allow easier editing of LAMMPS input scripts. See the README.txt
The files in the ``tools/vim`` directory are add-ons to the VIM editor
that allow easier editing of LAMMPS input scripts. See the ``README.txt``
file for details.
These files were provided by Gerolf Ziegenhain (gerolf at

94
doc/src/angle_lepton.rst Normal file
View File

@ -0,0 +1,94 @@
.. index:: angle_style lepton
.. index:: angle_style lepton/omp
angle_style lepton command
==========================
Accelerator Variants: *lepton/omp*
Syntax
""""""
.. code-block:: LAMMPS
angle_style lepton
Examples
""""""""
.. code-block:: LAMMPS
angle_style lepton
angle_coeff 1 120.0 "k*theta^2; k=250.0"
angle_coeff 2 90.0 "k2*theta^2 + k3*theta^3 + k4*theta^4; k2=300.0; k3=-100.0; k4=50.0"
angle_coeff 3 109.47 "k*theta^2; k=350.0"
Description
"""""""""""
.. versionadded:: TBD
Angle style *lepton* computes angular interactions between three atoms
with a custom potential function. The potential function must be
provided as an expression string using "theta" as the angle variable
relative to the reference angle :math:`\theta_0` which is provided as an
angle coefficient. For example `"200.0*theta^2"` represents a
:doc:`harmonic angle <angle_harmonic>` potential with a force constant
*K* of 200.0 energy units:
.. math::
U_{angle,i} = K (\theta_i - \theta_0)^2 = K \theta^2 \qquad \theta = \theta_i - \theta_0
The `Lepton library <https://simtk.org/projects/lepton>`_, that the
*lepton* angle style interfaces with, evaluates this expression string
at run time to compute the pairwise energy. It also creates an
analytical representation of the first derivative of this expression
with respect to "theta" and then uses that to compute the force between
the angle atoms as defined by the topology data.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* Lepton expression (energy units)
* :math:`\theta_0` (degrees)
The Lepton expression must be either enclosed in quotes or must not
contain any whitespace so that LAMMPS recognizes it as a single keyword.
More on valid Lepton expressions below. The :math:`\theta_0`
coefficient is the "equilibrium angle". It is entered in degrees, but
internally converted to radians. Thus the expression must assume
"theta" is in radians. The potential energy function in the Lepton
expression is shifted in such a way, that the potential energy is 0 for
a angle :math:`\theta_i == \theta_0`.
----------
.. include:: lepton_expression.rst
----------
.. include:: accel_styles.rst
----------
Restrictions
""""""""""""
This angle style is part of the LEPTON package and only enabled if LAMMPS
was built with this package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_style table <angle_table>`,
:doc:`bond_style lepton <bond_lepton>`,:doc:`dihedral_style lepton <dihedral_lepton>`
Default
"""""""
none

3
doc/src/angle_style.rst
View File

@ -10,7 +10,7 @@ Syntax
angle_style style
* style = *none* or *zero* or *hybrid* or *amoeba* or *charmm* or *class2* or *class2/p6* or *cosine* or *cosine/buck6d* or *cosine/delta* or *cosine/periodic* or *cosine/shift* or *cosine/shift/exp* or *cosine/squared* or *cross* or *dipole* or *fourier* or *fourier/simple* or *gaussian* or *harmonic* or *mm3* or *quartic* or *spica* or *table*
* style = *none* or *zero* or *hybrid* or *amoeba* or *charmm* or *class2* or *class2/p6* or *cosine* or *cosine/buck6d* or *cosine/delta* or *cosine/periodic* or *cosine/shift* or *cosine/shift/exp* or *cosine/squared* or *cross* or *dipole* or *fourier* or *fourier/simple* or *gaussian* or *harmonic* or *lepton* or *mm3* or *quartic* or *spica* or *table*
Examples
""""""""
@ -90,6 +90,7 @@ of (g,i,k,o,t) to indicate which accelerated styles exist.
* :doc:`fourier/simple <angle_fourier_simple>` - angle with a single cosine term
* :doc:`gaussian <angle_gaussian>` - multi-centered Gaussian-based angle potential
* :doc:`harmonic <angle_harmonic>` - harmonic angle
* :doc:`lepton <angle_lepton>` - angle potential from evaluating a string
* :doc:`mesocnt <angle_mesocnt>` - piecewise harmonic and linear angle for bending-buckling of nanotubes
* :doc:`mm3 <angle_mm3>` - anharmonic angle
* :doc:`quartic <angle_quartic>` - angle with cubic and quartic terms

9
doc/src/angle_table.rst
View File

@ -59,6 +59,13 @@ format of this file is described below.
----------
Suitable tables for use with this angle style can be created by LAMMPS
itself from existing angle styles using the :doc:`angle_write
<angle_write>` command. This can be useful to have a template file for
testing the angle style settings and to build a compatible custom file.
Another option to generate tables is the Python code in the
``tools/tabulate`` folder of the LAMMPS source code distribution.
The format of a tabulated file is as follows (without the
parenthesized comments):
@ -150,7 +157,7 @@ for more info.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_write <angle_write>`
Default
"""""""

99
doc/src/angle_write.rst Normal file
View File

@ -0,0 +1,99 @@
.. index:: angle_write
angle_write command
===================
Syntax
""""""
.. code-block:: LAMMPS
angle_write atype N file keyword
* atype = angle type
* N = # of values
* file = name of file to write values to
* keyword = section name in file for this set of tabulated values
Examples
""""""""
.. code-block:: LAMMPS
angle_write 1 500 table.txt Harmonic_1
angle_write 3 1000 table.txt Harmonic_3
Description
"""""""""""
.. versionadded:: TBD
Write energy and force values to a file as a function of angle for the
currently defined angle potential. Force in this context means the
force with respect to the angle, not the force on individual atoms.
This is useful for plotting the potential function or otherwise
debugging its values. The resulting file can also be used as input for
use with :doc:`angle style table <angle_table>`.
If the file already exists, the table of values is appended to the end
of the file to allow multiple tables of energy and force to be included
in one file. The individual sections may be identified by the *keyword*.
The energy and force values are computed for angles ranging from 0
degrees to 180 degrees for 3 interacting atoms forming an angle type
atype, using the appropriate :doc:`angle_coeff <angle_coeff>`
coefficients. N evenly spaced angles are used.
For example, for N = 6, values are computed at :math:`\theta = 0, 36,
72, 108, 144, 180`.
The file is written in the format used as input for the
:doc:`angle_style table <angle_table>` option with *keyword* as the
section name. Each line written to the file lists an index number
(1-N), an angle (in degrees), an energy (in energy units), and a force
(in force units per radians^2). In case a new file is created, the
first line will be a comment with a "DATE:" and "UNITS:" tag with the
current date and :doc:`units <units>` settings. For subsequent
invocations of the *angle_write* command for the same file, data will be
appended and the current units settings will be compared to the data
from the header, if present. The *angle_write* will refuse to add a
table to an existing file if the units are not the same.
Restrictions
""""""""""""
All force field coefficients for angle and other kinds of interactions
must be set before this command can be invoked.
The table of the angle energy and force data data is created by using a
separate, internally created, new LAMMPS instance with a dummy system of
3 atoms for which the angle potential energy is computed after
transferring the angle style and coefficients and arranging the 3 atoms
into the corresponding geometries. The angle force is then determined
from the potential energies through numerical differentiation. As a
consequence of this approach, not all angle styles are compatible. The
following conditions must be met:
- The angle style must be able to write its coefficients to a data file.
This condition excludes for example :doc:`angle style hybrid <angle_hybrid>` and
:doc:`angle style table <angle_table>`.
- The potential function must not have any terms that depend on geometry
properties other than the angle. This condition excludes for example
:doc:`angle style class2 <angle_class2>` all angle types for
:doc:`angle style charmm <angle_charmm>` that have non-zero
Urey-Bradley terms. Please note that the *write_angle* command has no
way of checking for this condition, so the resulting tables may be
bogus if the requirement is not met. It is thus recommended to make
careful tests for any created tables.
Related commands
""""""""""""""""
:doc:`angle_style table <angle_table>`, :doc:`bond_write <bond_write>`,
:doc:`dihedral_write <dihedral_write>`, :doc:`angle_style <angle_style>`,
:doc:`angle_coeff <angle_coeff>`
Default
"""""""
none

2
doc/src/bond_bpm_rotational.rst
View File

@ -69,7 +69,7 @@ which is proportional to the tangential shear displacement with a
stiffness of :math:`k_s`. This tangential force also induces a torque.
In addition, bending and twisting torques are also applied to
particles which are proportional to angular bending and twisting
displacements with stiffnesses of :math`k_b` and :math:`k_t',
displacements with stiffnesses of :math:`k_b` and :math:`k_t`,
respectively. Details on the calculations of shear displacements and
angular displacements can be found in :ref:`(Wang) <Wang2009>` and
:ref:`(Wang and Mora) <Wang2009b>`.

92
doc/src/bond_lepton.rst Normal file
View File

@ -0,0 +1,92 @@
.. index:: bond_style lepton
.. index:: bond_style lepton/omp
bond_style lepton command
=========================
Accelerator Variants: *lepton/omp*
Syntax
""""""
.. code-block:: LAMMPS
bond_style lepton
Examples
""""""""
.. code-block:: LAMMPS
bond_style lepton
bond_coeff 1 1.5 "k*r^2; k=250.0"
bond_coeff 2 1.1 "k2*r^2 + k3*r^3 + k4*r^4; k2=300.0; k3=-100.0; k4=50.0"
bond_coeff 3 1.3 "k*r^2; k=350.0"
Description
"""""""""""
.. versionadded:: TBD
Bond style *lepton* computes bonded interactions between two atoms with
a custom function. The potential function must be provided as an
expression string using "r" as the distance variable relative to the
reference distance :math:`r_0` which is provided as a bond coefficient.
For example `"200.0*r^2"` represents a harmonic potential with a force
constant *K* of 200.0 energy units:
.. math::
U_{bond,i} = K (r_i - r_0)^2 = K r^2 \qquad r = r_i - r_0
The `Lepton library <https://simtk.org/projects/lepton>`_, that the
*lepton* bond style interfaces with, evaluates this expression string at
run time to compute the pairwise energy. It also creates an analytical
representation of the first derivative of this expression with respect to
"r" and then uses that to compute the force between the atom pairs forming
bonds as defined by the topology data.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the examples above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* Lepton expression (energy units)
* :math:`r_0` (distance)
The Lepton expression must be either enclosed in quotes or must not
contain any whitespace so that LAMMPS recognizes it as a single keyword.
More on valid Lepton expressions below. The :math:`r_0` is the
"equilibrium distance". The potential energy function in the Lepton
expression is shifted in such a way, that the potential energy is 0 for
a bond length :math:`r_i == r_0`.
----------
.. include:: lepton_expression.rst
----------
.. include:: accel_styles.rst
----------
Restrictions
""""""""""""
This bond style is part of the LEPTON package and only enabled if LAMMPS
was built with this package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`bond_style table <bond_table>`,
:doc:`bond_write <bond_write>`, :doc:`angle_style lepton <angle_lepton>`,
:doc:`dihedral_style lepton <dihedral_lepton>`
Default
"""""""
none

3
doc/src/bond_style.rst
View File

@ -10,7 +10,7 @@ Syntax
bond_style style args
* style = *none* or *zero* or *hybrid* or *bpm/rotational* or *bpm/spring* or *class2* or *fene* or *fene/expand* or *fene/nm* or *gaussian* or *gromos* or *harmonic* or *harmonic/shift* or *harmonic/shift/cut* or *morse* or *nonlinear* or *oxdna/fene* or *oxdena2/fene* or *oxrna2/fene* or *quartic* or *special* or *table*
* style = *none* or *zero* or *hybrid* or *bpm/rotational* or *bpm/spring* or *class2* or *fene* or *fene/expand* or *fene/nm* or *gaussian* or *gromos* or *harmonic* or *harmonic/shift* or *harmonic/shift/cut* or *lepton* or *morse* or *nonlinear* or *oxdna/fene* or *oxdena2/fene* or *oxrna2/fene* or *quartic* or *special* or *table*
* args = none for any style except *hybrid*
@ -95,6 +95,7 @@ accelerated styles exist.
* :doc:`harmonic <bond_harmonic>` - harmonic bond
* :doc:`harmonic/shift <bond_harmonic_shift>` - shifted harmonic bond
* :doc:`harmonic/shift/cut <bond_harmonic_shift_cut>` - shifted harmonic bond with a cutoff
* :doc:`lepton <bond_lepton>` - bond potential from evaluating a string
* :doc:`mesocnt <bond_mesocnt>` - Harmonic bond wrapper with parameterization presets for nanotubes
* :doc:`mm3 <bond_mm3>` - MM3 anharmonic bond
* :doc:`morse <bond_morse>` - Morse bond

10
doc/src/bond_table.rst
View File

@ -59,6 +59,13 @@ this file is described below.
----------
Suitable tables for use with this bond style can be created by LAMMPS
itself from existing bond styles using the :doc:`bond_write
<bond_write>` command. This can be useful to have a template file for
testing the bond style settings and to build a compatible custom file.
Another option to generate tables is the Python code in the
``tools/tabulate`` folder of the LAMMPS source code distribution.
The format of a tabulated file is as follows (without the
parenthesized comments):
@ -149,7 +156,8 @@ info.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`,
:doc:`bond_write <bond_write>`
Default
"""""""

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