diff --git a/bench/in.chain b/bench/in.chain index 3993357140..d079f8d99f 100644 --- a/bench/in.chain +++ b/bench/in.chain @@ -1,25 +1,25 @@ # FENE beadspring benchmark -units lj -atom_style bond +units lj +atom_style bond special_bonds fene -read_data data.chain +read_data data.chain -neighbor 0.4 bin -neigh_modify every 1 delay 1 +neighbor 0.4 bin +neigh_modify every 1 delay 1 bond_style fene -bond_coeff 1 30.0 1.5 1.0 1.0 +bond_coeff 1 30.0 1.5 1.0 1.0 -pair_style lj/cut 1.12 -pair_modify shift yes -pair_coeff 1 1 1.0 1.0 1.12 +pair_style lj/cut 1.12 +pair_modify shift yes +pair_coeff 1 1 1.0 1.0 1.12 -fix 1 all nve -fix 2 all langevin 1.0 1.0 10.0 904297 +fix 1 all nve +fix 2 all langevin 1.0 1.0 10.0 904297 thermo 100 -timestep 0.012 +timestep 0.012 -run 100 +run 100 diff --git a/bench/in.chain.scaled b/bench/in.chain.scaled index c2648cc0e8..a56a2788ef 100644 --- a/bench/in.chain.scaled +++ b/bench/in.chain.scaled @@ -1,32 +1,32 @@ # FENE beadspring benchmark -variable x index 1 -variable y index 1 -variable z index 1 +variable x index 1 +variable y index 1 +variable z index 1 -units lj -atom_style bond -atom_modify map hash +units lj +atom_style bond +atom_modify map hash special_bonds fene -read_data data.chain +read_data data.chain -replicate $x $y $z +replicate $x $y $z -neighbor 0.4 bin -neigh_modify every 1 delay 1 +neighbor 0.4 bin +neigh_modify every 1 delay 1 bond_style fene -bond_coeff 1 30.0 1.5 1.0 1.0 +bond_coeff 1 30.0 1.5 1.0 1.0 -pair_style lj/cut 1.12 -pair_modify shift yes -pair_coeff 1 1 1.0 1.0 1.12 +pair_style lj/cut 1.12 +pair_modify shift yes +pair_coeff 1 1 1.0 1.0 1.12 -fix 1 all nve -fix 2 all langevin 1.0 1.0 10.0 904297 +fix 1 all nve +fix 2 all langevin 1.0 1.0 10.0 904297 thermo 100 -timestep 0.012 +timestep 0.012 -run 100 +run 100 diff --git a/bench/in.chute b/bench/in.chute index 9f7c28ada3..2478e98c96 100644 --- a/bench/in.chute +++ b/bench/in.chute @@ -1,33 +1,33 @@ # LAMMPS benchmark of granular flow # chute flow of 32000 atoms with frozen base at 26 degrees -units lj -atom_style sphere -boundary p p fs -newton off -comm_modify vel yes +units lj +atom_style sphere +boundary p p fs +newton off +comm_modify vel yes -read_data data.chute +read_data data.chute -pair_style gran/hooke/history 200000.0 NULL 50.0 NULL 0.5 0 -pair_coeff * * +pair_style gran/hooke/history 200000.0 NULL 50.0 NULL 0.5 0 +pair_coeff * * -neighbor 0.1 bin -neigh_modify every 1 delay 0 +neighbor 0.1 bin +neigh_modify every 1 delay 0 -timestep 0.0001 +timestep 0.0001 -group bottom type 2 -group active subtract all bottom -neigh_modify exclude group bottom bottom +group bottom type 2 +group active subtract all bottom +neigh_modify exclude group bottom bottom -fix 1 all gravity 1.0 chute 26.0 -fix 2 bottom freeze -fix 3 active nve/sphere +fix 1 all gravity 1.0 chute 26.0 +fix 2 bottom freeze +fix 3 active nve/sphere -compute 1 all erotate/sphere -thermo_style custom step atoms ke c_1 vol -thermo_modify norm no -thermo 100 +compute 1 all erotate/sphere +thermo_style custom step atoms ke c_1 vol +thermo_modify norm no +thermo 100 -run 100 +run 100 diff --git a/bench/in.chute.scaled b/bench/in.chute.scaled index 7bac8fe12d..09a6921145 100644 --- a/bench/in.chute.scaled +++ b/bench/in.chute.scaled @@ -1,38 +1,38 @@ # LAMMPS benchmark of granular flow # chute flow of 32000 atoms with frozen base at 26 degrees -variable x index 1 -variable y index 1 +variable x index 1 +variable y index 1 -units lj -atom_style sphere -boundary p p fs -newton off -comm_modify vel yes +units lj +atom_style sphere +boundary p p fs +newton off +comm_modify vel yes -read_data data.chute +read_data data.chute -replicate $x $y 1 +replicate $x $y 1 -pair_style gran/hooke/history 200000.0 NULL 50.0 NULL 0.5 0 -pair_coeff * * +pair_style gran/hooke/history 200000.0 NULL 50.0 NULL 0.5 0 +pair_coeff * * -neighbor 0.1 bin -neigh_modify every 1 delay 0 +neighbor 0.1 bin +neigh_modify every 1 delay 0 -timestep 0.0001 +timestep 0.0001 -group bottom type 2 -group active subtract all bottom -neigh_modify exclude group bottom bottom +group bottom type 2 +group active subtract all bottom +neigh_modify exclude group bottom bottom -fix 1 all gravity 1.0 chute 26.0 -fix 2 bottom freeze -fix 3 active nve/sphere +fix 1 all gravity 1.0 chute 26.0 +fix 2 bottom freeze +fix 3 active nve/sphere -compute 1 all erotate/sphere -thermo_style custom step atoms ke c_1 vol -thermo_modify norm no -thermo 100 +compute 1 all erotate/sphere +thermo_style custom step atoms ke c_1 vol +thermo_modify norm no +thermo 100 -run 100 +run 100 diff --git a/bench/in.eam b/bench/in.eam index 1dc0e1a646..b681ab9163 100644 --- a/bench/in.eam +++ b/bench/in.eam @@ -1,32 +1,32 @@ # bulk Cu lattice -variable x index 1 -variable y index 1 -variable z index 1 +variable x index 1 +variable y index 1 +variable z index 1 -variable xx equal 20*$x -variable yy equal 20*$y -variable zz equal 20*$z +variable xx equal 20*$x +variable yy equal 20*$y +variable zz equal 20*$z -units metal -atom_style atomic +units metal +atom_style atomic -lattice fcc 3.615 -region box block 0 ${xx} 0 ${yy} 0 ${zz} -create_box 1 box -create_atoms 1 box +lattice fcc 3.615 +region box block 0 ${xx} 0 ${yy} 0 ${zz} +create_box 1 box +create_atoms 1 box -pair_style eam -pair_coeff 1 1 Cu_u3.eam +pair_style eam +pair_coeff 1 1 Cu_u3.eam -velocity all create 1600.0 376847 loop geom +velocity all create 1600.0 376847 loop geom -neighbor 1.0 bin +neighbor 1.0 bin neigh_modify every 1 delay 5 check yes -fix 1 all nve +fix 1 all nve -timestep 0.005 -thermo 50 +timestep 0.005 +thermo 50 -run 100 +run 100 diff --git a/bench/in.lj b/bench/in.lj index 01e12ef8a9..7945e67fa5 100644 --- a/bench/in.lj +++ b/bench/in.lj @@ -1,30 +1,30 @@ # 3d Lennard-Jones melt -variable x index 1 -variable y index 1 -variable z index 1 +variable x index 1 +variable y index 1 +variable z index 1 -variable xx equal 20*$x -variable yy equal 20*$y -variable zz equal 20*$z +variable xx equal 20*$x +variable yy equal 20*$y +variable zz equal 20*$z -units lj -atom_style atomic +units lj +atom_style atomic -lattice fcc 0.8442 -region box block 0 ${xx} 0 ${yy} 0 ${zz} -create_box 1 box -create_atoms 1 box -mass 1 1.0 +lattice fcc 0.8442 +region box block 0 ${xx} 0 ${yy} 0 ${zz} +create_box 1 box +create_atoms 1 box +mass 1 1.0 -velocity all create 1.44 87287 loop geom +velocity all create 1.44 87287 loop geom -pair_style lj/cut 2.5 -pair_coeff 1 1 1.0 1.0 2.5 +pair_style lj/cut 2.5 +pair_coeff 1 1 1.0 1.0 2.5 -neighbor 0.3 bin -neigh_modify delay 0 every 20 check no +neighbor 0.3 bin +neigh_modify delay 0 every 20 check no -fix 1 all nve +fix 1 all nve -run 100 +run 100 diff --git a/bench/in.rhodo b/bench/in.rhodo index bd7e3df7f5..2f34b2721b 100644 --- a/bench/in.rhodo +++ b/bench/in.rhodo @@ -1,27 +1,27 @@ # Rhodopsin model -units real -neigh_modify delay 5 every 1 +units real +neigh_modify delay 5 every 1 -atom_style full -bond_style harmonic -angle_style charmm -dihedral_style charmm -improper_style harmonic -pair_style lj/charmm/coul/long 8.0 10.0 -pair_modify mix arithmetic -kspace_style pppm 1e-4 +atom_style full +bond_style harmonic +angle_style charmm +dihedral_style charmm +improper_style harmonic +pair_style lj/charmm/coul/long 8.0 10.0 +pair_modify mix arithmetic +kspace_style pppm 1e-4 read_data data.rhodo fix 1 all shake 0.0001 5 0 m 1.0 a 232 fix 2 all npt temp 300.0 300.0 100.0 & - z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1 + z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1 special_bonds charmm - + thermo 50 -thermo_style multi +thermo_style multi timestep 2.0 -run 100 +run 100 diff --git a/bench/in.rhodo.scaled b/bench/in.rhodo.scaled index 3debe44867..49a0864fb9 100644 --- a/bench/in.rhodo.scaled +++ b/bench/in.rhodo.scaled @@ -1,34 +1,34 @@ # Rhodopsin model -variable x index 1 -variable y index 1 -variable z index 1 +variable x index 1 +variable y index 1 +variable z index 1 -units real -neigh_modify delay 5 every 1 +units real +neigh_modify delay 5 every 1 -atom_style full -atom_modify map hash -bond_style harmonic -angle_style charmm -dihedral_style charmm -improper_style harmonic -pair_style lj/charmm/coul/long 8.0 10.0 -pair_modify mix arithmetic -kspace_style pppm 1e-4 +atom_style full +atom_modify map hash +bond_style harmonic +angle_style charmm +dihedral_style charmm +improper_style harmonic +pair_style lj/charmm/coul/long 8.0 10.0 +pair_modify mix arithmetic +kspace_style pppm 1e-4 read_data data.rhodo -replicate $x $y $z +replicate $x $y $z fix 1 all shake 0.0001 5 0 m 1.0 a 232 fix 2 all npt temp 300.0 300.0 100.0 & - z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1 + z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1 special_bonds charmm - + thermo 50 -thermo_style multi +thermo_style multi timestep 2.0 -run 100 +run 100 diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index 14961209c8..88b7ec422e 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -257,7 +257,6 @@ set(STANDARD_PACKAGES KIM KSPACE LATBOLTZ - LATTE LEPTON MACHDYN MANIFOLD @@ -441,7 +440,7 @@ 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_ML-POD 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_ELECTRODE OR BUILD_TOOLS) enable_language(C) if (NOT USE_INTERNAL_LINALG) find_package(LAPACK) @@ -521,7 +520,7 @@ else() 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 LEPTON) + PLUMED QMMM ML-QUIP SCAFACOS MACHDYN VTK KIM MSCG COMPRESS ML-PACE LEPTON) if(PKG_${PKG_WITH_INCL}) include(Packages/${PKG_WITH_INCL}) endif() @@ -842,7 +841,7 @@ if(BUILD_SHARED_LIBS) if(Python_EXECUTABLE) add_custom_target( install-python ${Python_EXECUTABLE} ${LAMMPS_PYTHON_DIR}/install.py -p ${LAMMPS_PYTHON_DIR}/lammps - -l ${LIBLAMMPS_SHARED_BINARY} -w ${MY_BUILD_DIR} + -l ${LIBLAMMPS_SHARED_BINARY} -w ${MY_BUILD_DIR} -v ${LAMMPS_SOURCE_DIR}/version.h COMMENT "Installing LAMMPS Python module") else() add_custom_target( diff --git a/cmake/Modules/CodingStandard.cmake b/cmake/Modules/CodingStandard.cmake index 6bb607be12..4efd373d22 100644 --- a/cmake/Modules/CodingStandard.cmake +++ b/cmake/Modules/CodingStandard.cmake @@ -5,6 +5,10 @@ if(CMAKE_VERSION VERSION_LESS 3.12) set(Python3_VERSION ${PYTHON_VERSION_STRING}) endif() else() + # use default (or custom) Python executable, if version is sufficient + if(Python_VERSION VERSION_GREATER_EQUAL 3.5) + set(Python3_EXECUTABLE ${Python_EXECUTABLE}) + endif() find_package(Python3 COMPONENTS Interpreter QUIET) endif() diff --git a/cmake/Modules/DetectHIPInstallation.cmake b/cmake/Modules/DetectHIPInstallation.cmake new file mode 100644 index 0000000000..0b425435b6 --- /dev/null +++ b/cmake/Modules/DetectHIPInstallation.cmake @@ -0,0 +1,16 @@ +if(NOT DEFINED HIP_PATH) + if(NOT DEFINED ENV{HIP_PATH}) + message(FATAL_ERROR "HIP support requires HIP_PATH to be defined.\n" + "Either pass the HIP_PATH as a CMake option via -DHIP_PATH=... or set the HIP_PATH environment variable.") + else() + set(HIP_PATH $ENV{HIP_PATH} CACHE PATH "Path to HIP installation") + endif() +endif() +if(NOT DEFINED ROCM_PATH) + if(NOT DEFINED ENV{ROCM_PATH}) + set(ROCM_PATH "/opt/rocm" CACHE PATH "Path to ROCm installation") + else() + set(ROCM_PATH $ENV{ROCM_PATH} CACHE PATH "Path to ROCm installation") + endif() +endif() +list(APPEND CMAKE_PREFIX_PATH ${HIP_PATH} ${ROCM_PATH}) diff --git a/cmake/Modules/Documentation.cmake b/cmake/Modules/Documentation.cmake index 46295feea3..0b01407cd9 100644 --- a/cmake/Modules/Documentation.cmake +++ b/cmake/Modules/Documentation.cmake @@ -4,14 +4,18 @@ option(BUILD_DOC "Build LAMMPS HTML documentation" OFF) if(BUILD_DOC) - # Sphinx 3.x requires at least Python 3.5 + # Current Sphinx versions require at least Python 3.8 if(CMAKE_VERSION VERSION_LESS 3.12) - find_package(PythonInterp 3.5 REQUIRED) + find_package(PythonInterp 3.8 REQUIRED) set(VIRTUALENV ${PYTHON_EXECUTABLE} -m venv) else() + # use default (or custom) Python executable, if version is sufficient + if(Python_VERSION VERSION_GREATER_EQUAL 3.8) + set(Python3_EXECUTABLE ${Python_EXECUTABLE}) + endif() find_package(Python3 REQUIRED COMPONENTS Interpreter) - if(Python3_VERSION VERSION_LESS 3.5) - message(FATAL_ERROR "Python 3.5 and up is required to build the HTML documentation") + if(Python3_VERSION VERSION_LESS 3.8) + message(FATAL_ERROR "Python 3.8 and up is required to build the HTML documentation") endif() set(VIRTUALENV ${Python3_EXECUTABLE} -m venv) endif() diff --git a/cmake/Modules/LAMMPSUtils.cmake b/cmake/Modules/LAMMPSUtils.cmake index 8a118e7a3b..1ceec7e06e 100644 --- a/cmake/Modules/LAMMPSUtils.cmake +++ b/cmake/Modules/LAMMPSUtils.cmake @@ -152,7 +152,7 @@ endfunction(FetchPotentials) # set CMAKE_LINUX_DISTRO and CMAKE_DISTRO_VERSION on Linux if((CMAKE_SYSTEM_NAME STREQUAL "Linux") AND (EXISTS /etc/os-release)) file(STRINGS /etc/os-release distro REGEX "^NAME=") - string(REGEX REPLACE "NAME=\"?([^\"]*)\"?" "\\1" distro "${distro}") + string(REGEX REPLACE "NAME=\"?([^ ]+).*\"?" "\\1" distro "${distro}") file(STRINGS /etc/os-release disversion REGEX "^VERSION_ID=") string(REGEX REPLACE "VERSION_ID=\"?([^\"]*)\"?" "\\1" disversion "${disversion}") set(CMAKE_LINUX_DISTRO ${distro}) diff --git a/cmake/Modules/Packages/GPU.cmake b/cmake/Modules/Packages/GPU.cmake index 034c4b3a9f..4a70eb7a1e 100644 --- a/cmake/Modules/Packages/GPU.cmake +++ b/cmake/Modules/Packages/GPU.cmake @@ -256,22 +256,7 @@ elseif(GPU_API STREQUAL "OPENCL") add_dependencies(ocl_get_devices OpenCL::OpenCL) elseif(GPU_API STREQUAL "HIP") - if(NOT DEFINED HIP_PATH) - if(NOT DEFINED ENV{HIP_PATH}) - message(FATAL_ERROR "GPU_API=HIP requires HIP_PATH to be defined.\n" - "Either pass the HIP_PATH as a CMake option via -DHIP_PATH=... or set the HIP_PATH environment variable.") - else() - set(HIP_PATH $ENV{HIP_PATH} CACHE PATH "Path to HIP installation") - endif() - endif() - if(NOT DEFINED ROCM_PATH) - if(NOT DEFINED ENV{ROCM_PATH}) - set(ROCM_PATH "/opt/rocm" CACHE PATH "Path to ROCm installation") - else() - set(ROCM_PATH $ENV{ROCM_PATH} CACHE PATH "Path to ROCm installation") - endif() - endif() - list(APPEND CMAKE_PREFIX_PATH ${HIP_PATH} ${ROCM_PATH}) + include(DetectHIPInstallation) find_package(hip REQUIRED) option(HIP_USE_DEVICE_SORT "Use GPU sorting" ON) diff --git a/cmake/Modules/Packages/KIM.cmake b/cmake/Modules/Packages/KIM.cmake index 2a2a1cde78..995d2d9490 100644 --- a/cmake/Modules/Packages/KIM.cmake +++ b/cmake/Modules/Packages/KIM.cmake @@ -19,7 +19,7 @@ if(CURL_FOUND) target_compile_definitions(lammps PRIVATE -DLMP_NO_SSL_CHECK) endif() endif() -set(KIM_EXTRA_UNITTESTS OFF CACHE STRING "Set extra unit tests verbose mode on/off. If on, extra tests are included.") +option(KIM_EXTRA_UNITTESTS "Enable extra unit tests for the KIM package." OFF) mark_as_advanced(KIM_EXTRA_UNITTESTS) find_package(PkgConfig QUIET) set(DOWNLOAD_KIM_DEFAULT ON) diff --git a/cmake/Modules/Packages/KOKKOS.cmake b/cmake/Modules/Packages/KOKKOS.cmake index 00486e73db..aa93e0cd7c 100644 --- a/cmake/Modules/Packages/KOKKOS.cmake +++ b/cmake/Modules/Packages/KOKKOS.cmake @@ -16,8 +16,8 @@ if(Kokkos_ENABLE_OPENMP) if(NOT BUILD_OMP) message(FATAL_ERROR "Must enable BUILD_OMP with Kokkos_ENABLE_OPENMP") else() - # NVHPC does not seem to provide a detectable OpenMP version, but is far beyond version 3.1 - if((OpenMP_CXX_VERSION VERSION_LESS 3.1) AND NOT (CMAKE_CXX_COMPILER_ID STREQUAL "NVHPC")) + # NVHPC/(AMD)Clang does not seem to provide a detectable OpenMP version, but is far beyond version 3.1 + if((OpenMP_CXX_VERSION VERSION_LESS 3.1) AND NOT ((CMAKE_CXX_COMPILER_ID STREQUAL "NVHPC") OR (CMAKE_CXX_COMPILER_ID STREQUAL "Clang"))) message(FATAL_ERROR "Compiler must support OpenMP 3.1 or later with Kokkos_ENABLE_OPENMP") endif() endif() @@ -121,6 +121,11 @@ set(KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/domain_kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/modify_kokkos.cpp) +# fix wall/gran has been refactored in an incompatible way. Use old version of base class for now +if(PKG_GRANULAR) + list(APPEND KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/fix_wall_gran_old.cpp) +endif() + if(PKG_KSPACE) list(APPEND KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/fft3d_kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/grid3d_kokkos.cpp @@ -132,8 +137,10 @@ if(PKG_KSPACE) endif() elseif(Kokkos_ENABLE_HIP) if(NOT (FFT STREQUAL "KISS")) + include(DetectHIPInstallation) + find_package(hipfft REQUIRED) target_compile_definitions(lammps PRIVATE -DFFT_HIPFFT) - target_link_libraries(lammps PRIVATE hipfft) + target_link_libraries(lammps PRIVATE hip::hipfft) endif() endif() endif() diff --git a/cmake/Modules/Packages/LATTE.cmake b/cmake/Modules/Packages/LATTE.cmake deleted file mode 100644 index bedd7a64fc..0000000000 --- a/cmake/Modules/Packages/LATTE.cmake +++ /dev/null @@ -1,54 +0,0 @@ -enable_language(Fortran) - -# using lammps in a super-build setting -if(TARGET LATTE::latte) - target_link_libraries(lammps PRIVATE LATTE::latte) - return() -endif() - -find_package(LATTE 1.2.2 CONFIG) -if(LATTE_FOUND) - set(DOWNLOAD_LATTE_DEFAULT OFF) -else() - set(DOWNLOAD_LATTE_DEFAULT ON) -endif() -option(DOWNLOAD_LATTE "Download the LATTE library instead of using an already installed one" ${DOWNLOAD_LATTE_DEFAULT}) -if(DOWNLOAD_LATTE) - message(STATUS "LATTE download requested - we will build our own") - set(LATTE_URL "https://github.com/lanl/LATTE/archive/v1.2.2.tar.gz" CACHE STRING "URL for LATTE tarball") - set(LATTE_MD5 "820e73a457ced178c08c71389a385de7" CACHE STRING "MD5 checksum of LATTE tarball") - mark_as_advanced(LATTE_URL) - mark_as_advanced(LATTE_MD5) - GetFallbackURL(LATTE_URL LATTE_FALLBACK) - - # CMake cannot pass BLAS or LAPACK library variable to external project if they are a list - list(LENGTH BLAS_LIBRARIES} NUM_BLAS) - list(LENGTH LAPACK_LIBRARIES NUM_LAPACK) - if((NUM_BLAS GREATER 1) OR (NUM_LAPACK GREATER 1) AND NOT USE_INTERNAL_LINALG) - message(FATAL_ERROR "Cannot compile downloaded LATTE library due to a technical limitation. " - "Try to configure LAMMPS with '-D USE_INTERNAL_LINALG=on' added as a workaround.") - endif() - - include(ExternalProject) - ExternalProject_Add(latte_build - URL ${LATTE_URL} ${LATTE_FALLBACK} - URL_MD5 ${LATTE_MD5} - SOURCE_SUBDIR cmake - CMAKE_ARGS -DCMAKE_INSTALL_PREFIX= ${CMAKE_REQUEST_PIC} -DCMAKE_INSTALL_LIBDIR=lib - -DBLAS_LIBRARIES=${BLAS_LIBRARIES} -DLAPACK_LIBRARIES=${LAPACK_LIBRARIES} - -DCMAKE_Fortran_COMPILER=${CMAKE_Fortran_COMPILER} -DCMAKE_Fortran_FLAGS=${CMAKE_Fortran_FLAGS} - -DCMAKE_Fortran_FLAGS_${BTYPE}=${CMAKE_Fortran_FLAGS_${BTYPE}} -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} - -DCMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM} -DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE} - BUILD_BYPRODUCTS /lib/liblatte.a - ) - ExternalProject_get_property(latte_build INSTALL_DIR) - add_library(LAMMPS::LATTE UNKNOWN IMPORTED) - set_target_properties(LAMMPS::LATTE PROPERTIES - IMPORTED_LOCATION "${INSTALL_DIR}/lib/liblatte.a" - INTERFACE_LINK_LIBRARIES "${LAPACK_LIBRARIES}") - target_link_libraries(lammps PRIVATE LAMMPS::LATTE) - add_dependencies(LAMMPS::LATTE latte_build) -else() - find_package(LATTE 1.2.2 REQUIRED CONFIG) - target_link_libraries(lammps PRIVATE LATTE::latte) -endif() diff --git a/cmake/Modules/Packages/MDI.cmake b/cmake/Modules/Packages/MDI.cmake index 67c1b82dab..dc3af94a0a 100644 --- a/cmake/Modules/Packages/MDI.cmake +++ b/cmake/Modules/Packages/MDI.cmake @@ -8,8 +8,8 @@ option(DOWNLOAD_MDI "Download and compile the MDI library instead of using an al if(DOWNLOAD_MDI) message(STATUS "MDI download requested - we will build our own") - set(MDI_URL "https://github.com/MolSSI-MDI/MDI_Library/archive/v1.4.12.tar.gz" CACHE STRING "URL for MDI tarball") - set(MDI_MD5 "7a222353ae8e03961d5365e6cd48baee" CACHE STRING "MD5 checksum for MDI tarball") + set(MDI_URL "https://github.com/MolSSI-MDI/MDI_Library/archive/v1.4.16.tar.gz" CACHE STRING "URL for MDI tarball") + set(MDI_MD5 "407db44e2d79447ab5c1233af1965f65" CACHE STRING "MD5 checksum for MDI tarball") mark_as_advanced(MDI_URL) mark_as_advanced(MDI_MD5) GetFallbackURL(MDI_URL MDI_FALLBACK) diff --git a/cmake/Modules/Packages/PLUMED.cmake b/cmake/Modules/Packages/PLUMED.cmake index 9a4a9556ee..b90bff4b9c 100644 --- a/cmake/Modules/Packages/PLUMED.cmake +++ b/cmake/Modules/Packages/PLUMED.cmake @@ -1,106 +1,169 @@ -set(PLUMED_MODE "static" CACHE STRING "Linkage mode for Plumed2 library") -set(PLUMED_MODE_VALUES static shared runtime) -set_property(CACHE PLUMED_MODE PROPERTY STRINGS ${PLUMED_MODE_VALUES}) -validate_option(PLUMED_MODE PLUMED_MODE_VALUES) -string(TOUPPER ${PLUMED_MODE} PLUMED_MODE) +# Plumed2 support for PLUMED package -set(PLUMED_LINK_LIBS) -if(PLUMED_MODE STREQUAL "STATIC") - find_package(LAPACK REQUIRED) - find_package(BLAS REQUIRED) - find_package(GSL REQUIRED) - list(APPEND PLUMED_LINK_LIBS ${LAPACK_LIBRARIES} ${BLAS_LIBRARIES} GSL::gsl) - find_package(ZLIB QUIET) - if(ZLIB_FOUND) - list(APPEND PLUMED_LINK_LIBS ZLIB::ZLIB) - endif() - find_package(FFTW3 QUIET) - if(FFTW3_FOUND) - list(APPEND PLUMED_LINK_LIBS FFTW3::FFTW3) - endif() +if(BUILD_MPI) + set(PLUMED_CONFIG_MPI "--enable-mpi") + set(PLUMED_CONFIG_CC ${CMAKE_MPI_C_COMPILER}) + set(PLUMED_CONFIG_CXX ${CMAKE_MPI_CXX_COMPILER}) + set(PLUMED_CONFIG_CPP "-I ${MPI_CXX_INCLUDE_PATH}") + set(PLUMED_CONFIG_LIB "${MPI_CXX_LIBRARIES}") + set(PLUMED_CONFIG_DEP "mpi4win_build") +else() + set(PLUMED_CONFIG_MPI "--disable-mpi") + set(PLUMED_CONFIG_CC ${CMAKE_C_COMPILER}) + set(PLUMED_CONFIG_CXX ${CMAKE_CXX_COMPILER}) + set(PLUMED_CONFIG_CPP "") + set(PLUMED_CONFIG_LIB "") + set(PLUMED_CONFIG_DEP "") +endif() +if(BUILD_OMP) + set(PLUMED_CONFIG_OMP "--enable-openmp") +else() + set(PLUMED_CONFIG_OMP "--disable-openmp") endif() -find_package(PkgConfig QUIET) -set(DOWNLOAD_PLUMED_DEFAULT ON) -if(PKG_CONFIG_FOUND) - pkg_check_modules(PLUMED QUIET plumed) - if(PLUMED_FOUND) - set(DOWNLOAD_PLUMED_DEFAULT OFF) - endif() -endif() +set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.8.2/plumed-src-2.8.2.tgz" + CACHE STRING "URL for PLUMED tarball") +set(PLUMED_MD5 "599092b6a0aa6fff992612537ad98994" CACHE STRING "MD5 checksum of PLUMED tarball") -option(DOWNLOAD_PLUMED "Download Plumed package instead of using an already installed one" ${DOWNLOAD_PLUMED_DEFAULT}) -if(DOWNLOAD_PLUMED) - if(BUILD_MPI) - set(PLUMED_CONFIG_MPI "--enable-mpi") - set(PLUMED_CONFIG_CC ${CMAKE_MPI_C_COMPILER}) - set(PLUMED_CONFIG_CXX ${CMAKE_MPI_CXX_COMPILER}) +mark_as_advanced(PLUMED_URL) +mark_as_advanced(PLUMED_MD5) +GetFallbackURL(PLUMED_URL PLUMED_FALLBACK) + +if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND (CMAKE_CROSSCOMPILING)) + if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64") + set(CROSS_CONFIGURE mingw64-configure) + elseif(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86") + set(CROSS_CONFIGURE mingw32-configure) else() - set(PLUMED_CONFIG_MPI "--disable-mpi") - set(PLUMED_CONFIG_CC ${CMAKE_C_COMPILER}) - set(PLUMED_CONFIG_CXX ${CMAKE_CXX_COMPILER}) + message(FATAL_ERROR "Unsupported target system: ${CMAKE_SYSTEM_NAME}/${CMAKE_SYSTEM_PROCESSOR}") endif() - if(BUILD_OMP) - set(PLUMED_CONFIG_OMP "--enable-openmp") - else() - set(PLUMED_CONFIG_OMP "--disable-openmp") - endif() - message(STATUS "PLUMED download requested - we will build our own") - if(PLUMED_MODE STREQUAL "STATIC") - set(PLUMED_BUILD_BYPRODUCTS "/lib/${CMAKE_STATIC_LIBRARY_PREFIX}plumed${CMAKE_STATIC_LIBRARY_SUFFIX}") - elseif(PLUMED_MODE STREQUAL "SHARED") - set(PLUMED_BUILD_BYPRODUCTS "/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumed${CMAKE_SHARED_LIBRARY_SUFFIX};/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX}") - elseif(PLUMED_MODE STREQUAL "RUNTIME") - set(PLUMED_BUILD_BYPRODUCTS "/lib/${CMAKE_STATIC_LIBRARY_PREFIX}plumedWrapper${CMAKE_STATIC_LIBRARY_PREFIX}") - endif() - - set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.8.2/plumed-src-2.8.2.tgz" CACHE STRING "URL for PLUMED tarball") - set(PLUMED_MD5 "599092b6a0aa6fff992612537ad98994" CACHE STRING "MD5 checksum of PLUMED tarball") - - mark_as_advanced(PLUMED_URL) - mark_as_advanced(PLUMED_MD5) - GetFallbackURL(PLUMED_URL PLUMED_FALLBACK) - + message(STATUS "Downloading and cross-compiling Plumed2 for ${CMAKE_SYSTEM_NAME}/${CMAKE_SYSTEM_PROCESSOR} with ${CROSS_CONFIGURE}") include(ExternalProject) ExternalProject_Add(plumed_build URL ${PLUMED_URL} ${PLUMED_FALLBACK} URL_MD5 ${PLUMED_MD5} BUILD_IN_SOURCE 1 - CONFIGURE_COMMAND /configure --prefix= + CONFIGURE_COMMAND ${CROSS_CONFIGURE} --disable-shared --disable-bsymbolic + --disable-python --enable-cxx=11 + --enable-modules=-adjmat:+crystallization:-dimred:+drr:+eds:-fisst:+funnel:+logmfd:+manyrestraints:+maze:+opes:+multicolvar:-pamm:-piv:+s2cm:-sasa:-ves + ${PLUMED_CONFIG_OMP} + ${PLUMED_CONFIG_MPI} + CXX=${PLUMED_CONFIG_CXX} + CC=${PLUMED_CONFIG_CC} + CPPFLAGS=${PLUMED_CONFIG_CPP} + LIBS=${PLUMED_CONFIG_LIB} + INSTALL_COMMAND "" + BUILD_BYPRODUCTS "/src/lib/install/libplumed.a" "/src/lib/install/plumed.exe" + DEPENDS "${PLUMED_MPI_CONFIG_DEP}" + ) + ExternalProject_Get_Property(plumed_build SOURCE_DIR) + set(PLUMED_BUILD_DIR ${SOURCE_DIR}) + set(PLUMED_INSTALL_DIR ${PLUMED_BUILD_DIR}/src/lib/install) + file(MAKE_DIRECTORY ${PLUMED_BUILD_DIR}/src/include) + + add_library(LAMMPS::PLUMED UNKNOWN IMPORTED) + add_dependencies(LAMMPS::PLUMED plumed_build) + set_target_properties(LAMMPS::PLUMED PROPERTIES + IMPORTED_LOCATION "${PLUMED_INSTALL_DIR}/libplumed.a" + INTERFACE_LINK_LIBRARIES "-Wl,--image-base -Wl,0x10000000 -lfftw3 -lz -fstack-protector -lssp -fopenmp" + INTERFACE_INCLUDE_DIRECTORIES "${PLUMED_BUILD_DIR}/src/include") + + add_custom_target(plumed_copy ALL ${CMAKE_COMMAND} -E rm -rf ${CMAKE_BINARY_DIR}/plumed.exe ${CMAKE_BINARY_DIR}/plumed_patches + COMMAND ${CMAKE_COMMAND} -E copy ${PLUMED_INSTALL_DIR}/plumed.exe ${CMAKE_BINARY_DIR}/plumed.exe + COMMAND ${CMAKE_COMMAND} -E copy_directory ${PLUMED_BUILD_DIR}/patches ${CMAKE_BINARY_DIR}/patches + BYPRODUCTS ${CMAKE_BINARY_DIR}/plumed.exe ${CMAKE_BINARY_DIR}/patches + DEPENDS plumed_build + COMMENT "Copying Plumed files" + ) + +else() + + set(PLUMED_MODE "static" CACHE STRING "Linkage mode for Plumed2 library") + set(PLUMED_MODE_VALUES static shared runtime) + set_property(CACHE PLUMED_MODE PROPERTY STRINGS ${PLUMED_MODE_VALUES}) + validate_option(PLUMED_MODE PLUMED_MODE_VALUES) + string(TOUPPER ${PLUMED_MODE} PLUMED_MODE) + + set(PLUMED_LINK_LIBS) + if(PLUMED_MODE STREQUAL "STATIC") + find_package(LAPACK REQUIRED) + find_package(BLAS REQUIRED) + find_package(GSL REQUIRED) + list(APPEND PLUMED_LINK_LIBS ${LAPACK_LIBRARIES} ${BLAS_LIBRARIES} GSL::gsl) + find_package(ZLIB QUIET) + if(ZLIB_FOUND) + list(APPEND PLUMED_LINK_LIBS ZLIB::ZLIB) + endif() + find_package(FFTW3 QUIET) + if(FFTW3_FOUND) + list(APPEND PLUMED_LINK_LIBS FFTW3::FFTW3) + endif() + endif() + + find_package(PkgConfig QUIET) + set(DOWNLOAD_PLUMED_DEFAULT ON) + if(PKG_CONFIG_FOUND) + pkg_check_modules(PLUMED QUIET plumed) + if(PLUMED_FOUND) + set(DOWNLOAD_PLUMED_DEFAULT OFF) + endif() + endif() + + option(DOWNLOAD_PLUMED "Download Plumed package instead of using an already installed one" ${DOWNLOAD_PLUMED_DEFAULT}) + if(DOWNLOAD_PLUMED) + message(STATUS "PLUMED download requested - we will build our own") + if(PLUMED_MODE STREQUAL "STATIC") + set(PLUMED_BUILD_BYPRODUCTS "/lib/${CMAKE_STATIC_LIBRARY_PREFIX}plumed${CMAKE_STATIC_LIBRARY_SUFFIX}") + elseif(PLUMED_MODE STREQUAL "SHARED") + set(PLUMED_BUILD_BYPRODUCTS "/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumed${CMAKE_SHARED_LIBRARY_SUFFIX};/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX}") + elseif(PLUMED_MODE STREQUAL "RUNTIME") + set(PLUMED_BUILD_BYPRODUCTS "/lib/${CMAKE_STATIC_LIBRARY_PREFIX}plumedWrapper${CMAKE_STATIC_LIBRARY_PREFIX}") + endif() + + include(ExternalProject) + ExternalProject_Add(plumed_build + URL ${PLUMED_URL} ${PLUMED_FALLBACK} + URL_MD5 ${PLUMED_MD5} + BUILD_IN_SOURCE 1 + CONFIGURE_COMMAND /configure --prefix= ${CONFIGURE_REQUEST_PIC} --enable-modules=all + --enable-cxx=11 + --disable-python ${PLUMED_CONFIG_MPI} ${PLUMED_CONFIG_OMP} CXX=${PLUMED_CONFIG_CXX} CC=${PLUMED_CONFIG_CC} - BUILD_BYPRODUCTS ${PLUMED_BUILD_BYPRODUCTS} - ) - ExternalProject_get_property(plumed_build INSTALL_DIR) - add_library(LAMMPS::PLUMED UNKNOWN IMPORTED) - add_dependencies(LAMMPS::PLUMED plumed_build) - if(PLUMED_MODE STREQUAL "STATIC") - set_target_properties(LAMMPS::PLUMED PROPERTIES IMPORTED_LOCATION ${INSTALL_DIR}/lib/${CMAKE_STATIC_LIBRARY_PREFIX}plumed${CMAKE_STATIC_LIBRARY_SUFFIX} INTERFACE_LINK_LIBRARIES "${PLUMED_LINK_LIBS};${CMAKE_DL_LIBS}") - elseif(PLUMED_MODE STREQUAL "SHARED") - set_target_properties(LAMMPS::PLUMED PROPERTIES IMPORTED_LOCATION ${INSTALL_DIR}/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumed${CMAKE_SHARED_LIBRARY_SUFFIX} INTERFACE_LINK_LIBRARIES "${INSTALL_DIR}/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX};${CMAKE_DL_LIBS}") - elseif(PLUMED_MODE STREQUAL "RUNTIME") - set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_COMPILE_DEFINITIONS "__PLUMED_DEFAULT_KERNEL=${INSTALL_DIR}/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX}") - set_target_properties(LAMMPS::PLUMED PROPERTIES IMPORTED_LOCATION ${INSTALL_DIR}/lib/${CMAKE_STATIC_LIBRARY_PREFIX}plumedWrapper${CMAKE_STATIC_LIBRARY_SUFFIX} INTERFACE_LINK_LIBRARIES "${CMAKE_DL_LIBS}") + BUILD_BYPRODUCTS ${PLUMED_BUILD_BYPRODUCTS} + ) + ExternalProject_get_property(plumed_build INSTALL_DIR) + add_library(LAMMPS::PLUMED UNKNOWN IMPORTED) + add_dependencies(LAMMPS::PLUMED plumed_build) + if(PLUMED_MODE STREQUAL "STATIC") + set_target_properties(LAMMPS::PLUMED PROPERTIES IMPORTED_LOCATION ${INSTALL_DIR}/lib/${CMAKE_STATIC_LIBRARY_PREFIX}plumed${CMAKE_STATIC_LIBRARY_SUFFIX} INTERFACE_LINK_LIBRARIES "${PLUMED_LINK_LIBS};${CMAKE_DL_LIBS}") + elseif(PLUMED_MODE STREQUAL "SHARED") + set_target_properties(LAMMPS::PLUMED PROPERTIES IMPORTED_LOCATION ${INSTALL_DIR}/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumed${CMAKE_SHARED_LIBRARY_SUFFIX} INTERFACE_LINK_LIBRARIES "${INSTALL_DIR}/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX};${CMAKE_DL_LIBS}") + elseif(PLUMED_MODE STREQUAL "RUNTIME") + set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_COMPILE_DEFINITIONS "__PLUMED_DEFAULT_KERNEL=${INSTALL_DIR}/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX}") + set_target_properties(LAMMPS::PLUMED PROPERTIES IMPORTED_LOCATION ${INSTALL_DIR}/lib/${CMAKE_STATIC_LIBRARY_PREFIX}plumedWrapper${CMAKE_STATIC_LIBRARY_SUFFIX} INTERFACE_LINK_LIBRARIES "${CMAKE_DL_LIBS}") + endif() + set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_INCLUDE_DIRECTORIES ${INSTALL_DIR}/include) + file(MAKE_DIRECTORY ${INSTALL_DIR}/include) + else() + find_package(PkgConfig REQUIRED) + pkg_check_modules(PLUMED REQUIRED plumed) + add_library(LAMMPS::PLUMED INTERFACE IMPORTED) + if(PLUMED_MODE STREQUAL "STATIC") + include(${PLUMED_LIBDIR}/plumed/src/lib/Plumed.cmake.static) + elseif(PLUMED_MODE STREQUAL "SHARED") + include(${PLUMED_LIBDIR}/plumed/src/lib/Plumed.cmake.shared) + elseif(PLUMED_MODE STREQUAL "RUNTIME") + set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_COMPILE_DEFINITIONS "__PLUMED_DEFAULT_KERNEL=${PLUMED_LIBDIR}/${CMAKE_SHARED_LIBRARY_PREFIX}plumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX}") + include(${PLUMED_LIBDIR}/plumed/src/lib/Plumed.cmake.runtime) + endif() + set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_LINK_LIBRARIES "${PLUMED_LOAD}") + set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${PLUMED_INCLUDE_DIRS}") endif() - set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_INCLUDE_DIRECTORIES ${INSTALL_DIR}/include) - file(MAKE_DIRECTORY ${INSTALL_DIR}/include) -else() - find_package(PkgConfig REQUIRED) - pkg_check_modules(PLUMED REQUIRED plumed) - add_library(LAMMPS::PLUMED INTERFACE IMPORTED) - if(PLUMED_MODE STREQUAL "STATIC") - include(${PLUMED_LIBDIR}/plumed/src/lib/Plumed.cmake.static) - elseif(PLUMED_MODE STREQUAL "SHARED") - include(${PLUMED_LIBDIR}/plumed/src/lib/Plumed.cmake.shared) - elseif(PLUMED_MODE STREQUAL "RUNTIME") - set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_COMPILE_DEFINITIONS "__PLUMED_DEFAULT_KERNEL=${PLUMED_LIBDIR}/${CMAKE_SHARED_LIBRARY_PREFIX}plumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX}") - include(${PLUMED_LIBDIR}/plumed/src/lib/Plumed.cmake.runtime) - endif() - set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_LINK_LIBRARIES "${PLUMED_LOAD}") - set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${PLUMED_INCLUDE_DIRS}") endif() + target_link_libraries(lammps PRIVATE LAMMPS::PLUMED) diff --git a/cmake/Modules/Testing.cmake b/cmake/Modules/Testing.cmake index c82114a1dd..5345211178 100644 --- a/cmake/Modules/Testing.cmake +++ b/cmake/Modules/Testing.cmake @@ -18,29 +18,33 @@ if(ENABLE_TESTING) # we need to build and link a LOT of tester executables, so it is worth checking if # a faster linker is available. requires GNU or Clang compiler, newer CMake. - # also only verified with Fedora Linux > 30 and Ubuntu <= 18.04 (Ubuntu 20.04 fails) + # also only verified with Fedora Linux > 30 and Ubuntu 18.04 or 22.04+(Ubuntu 20.04 fails) if((CMAKE_SYSTEM_NAME STREQUAL "Linux") AND (CMAKE_VERSION VERSION_GREATER_EQUAL 3.13) - AND ((CMAKE_CXX_COMPILER_ID STREQUAL "GNU") - OR (CMAKE_CXX_COMPILER_ID STREQUAL "Clang"))) - if(((CMAKE_LINUX_DISTRO STREQUAL "Ubuntu") AND (CMAKE_DISTRO_VERSION VERSION_LESS_EQUAL 18.04)) + AND ((CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR (CMAKE_CXX_COMPILER_ID STREQUAL "Clang"))) + if(((CMAKE_LINUX_DISTRO STREQUAL "Ubuntu") AND + ((CMAKE_DISTRO_VERSION VERSION_LESS_EQUAL 18.04) OR (CMAKE_DISTRO_VERSION VERSION_GREATER_EQUAL 22.04))) OR ((CMAKE_LINUX_DISTRO STREQUAL "Fedora") AND (CMAKE_DISTRO_VERSION VERSION_GREATER 30))) include(CheckCXXCompilerFlag) set(CMAKE_CUSTOM_LINKER_DEFAULT default) + check_cxx_compiler_flag(-fuse-ld=mold HAVE_MOLD_LINKER_FLAG) check_cxx_compiler_flag(-fuse-ld=lld HAVE_LLD_LINKER_FLAG) check_cxx_compiler_flag(-fuse-ld=gold HAVE_GOLD_LINKER_FLAG) check_cxx_compiler_flag(-fuse-ld=bfd HAVE_BFD_LINKER_FLAG) + find_program(HAVE_MOLD_LINKER_BIN ld.mold) find_program(HAVE_LLD_LINKER_BIN lld ld.lld) find_program(HAVE_GOLD_LINKER_BIN ld.gold) find_program(HAVE_BFD_LINKER_BIN ld.bfd) - if(HAVE_LLD_LINKER_FLAG AND HAVE_LLD_LINKER_BIN) + if(HAVE_MOLD_LINKER_FLAG AND HAVE_MOLD_LINKER_BIN) + set(CMAKE_CUSTOM_LINKER_DEFAULT mold) + elseif(HAVE_LLD_LINKER_FLAG AND HAVE_LLD_LINKER_BIN) set(CMAKE_CUSTOM_LINKER_DEFAULT lld) elseif(HAVE_GOLD_LINKER_FLAG AND HAVE_GOLD_LINKER_BIN) set(CMAKE_CUSTOM_LINKER_DEFAULT gold) elseif(HAVE_BFD_LINKER_FLAG AND HAVE_BFD_LINKER_BIN) set(CMAKE_CUSTOM_LINKER_DEFAULT bfd) endif() - set(CMAKE_CUSTOM_LINKER_VALUES lld gold bfd default) - set(CMAKE_CUSTOM_LINKER ${CMAKE_CUSTOM_LINKER_DEFAULT} CACHE STRING "Choose a custom linker for faster linking (lld, gold, bfd, default)") + set(CMAKE_CUSTOM_LINKER_VALUES mold lld gold bfd default) + set(CMAKE_CUSTOM_LINKER ${CMAKE_CUSTOM_LINKER_DEFAULT} CACHE STRING "Choose a custom linker for faster linking (mold, lld, gold, bfd, default)") validate_option(CMAKE_CUSTOM_LINKER CMAKE_CUSTOM_LINKER_VALUES) mark_as_advanced(CMAKE_CUSTOM_LINKER) if(NOT "${CMAKE_CUSTOM_LINKER}" STREQUAL "default") diff --git a/cmake/Modules/Tools.cmake b/cmake/Modules/Tools.cmake index c4c33cc40c..285c5f2405 100644 --- a/cmake/Modules/Tools.cmake +++ b/cmake/Modules/Tools.cmake @@ -33,6 +33,8 @@ if(BUILD_TOOLS) endif() install(TARGETS msi2lmp DESTINATION ${CMAKE_INSTALL_BINDIR}) install(FILES ${LAMMPS_DOC_DIR}/msi2lmp.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1) + + add_subdirectory(${LAMMPS_TOOLS_DIR}/phonon ${CMAKE_BINARY_DIR}/phana_build) endif() if(BUILD_LAMMPS_SHELL) diff --git a/cmake/presets/all_off.cmake b/cmake/presets/all_off.cmake index 3d5ee95b3d..2db615f533 100644 --- a/cmake/presets/all_off.cmake +++ b/cmake/presets/all_off.cmake @@ -43,7 +43,6 @@ set(ALL_PACKAGES KOKKOS KSPACE LATBOLTZ - LATTE LEPTON MACHDYN MANIFOLD diff --git a/cmake/presets/all_on.cmake b/cmake/presets/all_on.cmake index 474051f6ec..79444f96aa 100644 --- a/cmake/presets/all_on.cmake +++ b/cmake/presets/all_on.cmake @@ -45,7 +45,6 @@ set(ALL_PACKAGES KOKKOS KSPACE LATBOLTZ - LATTE LEPTON MACHDYN MANIFOLD diff --git a/cmake/presets/download.cmake b/cmake/presets/download.cmake index 2030a97dbb..13b93569f9 100644 --- a/cmake/presets/download.cmake +++ b/cmake/presets/download.cmake @@ -1,14 +1,13 @@ # Preset that turns on packages with automatic downloads of sources or potentials. # Compilation of libraries like Plumed or ScaFaCoS can take a considerable amount of time. -set(ALL_PACKAGES KIM LATTE MSCG VORONOI PLUMED SCAFACOS MACHDYN MESONT MDI ML-PACE) +set(ALL_PACKAGES KIM MSCG VORONOI PLUMED SCAFACOS MACHDYN MESONT MDI ML-PACE) foreach(PKG ${ALL_PACKAGES}) set(PKG_${PKG} ON CACHE BOOL "" FORCE) endforeach() set(DOWNLOAD_KIM ON CACHE BOOL "" FORCE) -set(DOWNLOAD_LATTE ON CACHE BOOL "" FORCE) set(DOWNLOAD_MDI ON CACHE BOOL "" FORCE) set(DOWNLOAD_MSCG ON CACHE BOOL "" FORCE) set(DOWNLOAD_VORO ON CACHE BOOL "" FORCE) diff --git a/cmake/presets/mingw-cross.cmake b/cmake/presets/mingw-cross.cmake index 6c6170acd3..85f61be95b 100644 --- a/cmake/presets/mingw-cross.cmake +++ b/cmake/presets/mingw-cross.cmake @@ -35,7 +35,6 @@ set(WIN_PACKAGES INTEL INTERLAYER KSPACE - LATTE LEPTON MACHDYN MANIFOLD diff --git a/cmake/presets/nolib.cmake b/cmake/presets/nolib.cmake index 00a69cd22d..0e1b09b6cc 100644 --- a/cmake/presets/nolib.cmake +++ b/cmake/presets/nolib.cmake @@ -12,7 +12,6 @@ set(PACKAGES_WITH_LIB KIM KOKKOS LATBOLTZ - LATTE LEPTON MACHDYN MDI diff --git a/doc/lammps.1 b/doc/lammps.1 index e4f6c61477..b1be867e60 100644 --- a/doc/lammps.1 +++ b/doc/lammps.1 @@ -1,7 +1,7 @@ -.TH LAMMPS "1" "8 February 2023" "2023-02-08" +.TH LAMMPS "1" "28 March 2023" "2023-03-28" .SH NAME .B LAMMPS -\- Molecular Dynamics Simulator. Version 8 February 2023 +\- Molecular Dynamics Simulator. Version 28 March 2023 .SH SYNOPSIS .B lmp diff --git a/doc/src/Build_basics.rst b/doc/src/Build_basics.rst index 25326897b8..0a0d4919a0 100644 --- a/doc/src/Build_basics.rst +++ b/doc/src/Build_basics.rst @@ -128,14 +128,14 @@ and adds vectorization support when compiled with compatible compilers, in particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS`` package can be compiled to include OpenMP threading. -In addition, there are a few commands in LAMMPS that have native OpenMP -support included as well. These are commands in the ``MPIIO``, -``ML-SNAP``, ``DIFFRACTION``, and ``DPD-REACT`` packages. Furthermore, -some packages support OpenMP threading indirectly through the libraries -they interface to: e.g. ``LATTE``, ``KSPACE``, and ``COLVARS``. See the -:doc:`Packages details ` page for more info on these -packages, and the pages for their respective commands for OpenMP -threading info. +In addition, there are a few commands in LAMMPS that have native +OpenMP support included as well. These are commands in the ``MPIIO``, +``ML-SNAP``, ``DIFFRACTION``, and ``DPD-REACT`` packages. +Furthermore, some packages support OpenMP threading indirectly through +the libraries they interface to: e.g. ``KSPACE``, and ``COLVARS``. +See the :doc:`Packages details ` page for more info +on these packages, and the pages for their respective commands for +OpenMP threading info. For CMake, if you use ``BUILD_OMP=yes``, you can use these packages and turn on their native OpenMP support and turn on their native OpenMP diff --git a/doc/src/Build_development.rst b/doc/src/Build_development.rst index 416b49c685..c75c7a6a41 100644 --- a/doc/src/Build_development.rst +++ b/doc/src/Build_development.rst @@ -523,6 +523,8 @@ The following options are available. These should help to make source and documentation files conforming to some the coding style preferences of the LAMMPS developers. +.. _clang-format: + Clang-format support -------------------- diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index e6366075ff..0ecf54f744 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -43,7 +43,6 @@ This is the list of packages that may require additional steps. * :ref:`INTEL ` * :ref:`KIM ` * :ref:`KOKKOS ` - * :ref:`LATTE ` * :ref:`LEPTON ` * :ref:`MACHDYN ` * :ref:`MDI ` @@ -684,20 +683,11 @@ This list was last updated for version 3.7.1 of the Kokkos library. -D Kokkos_ARCH_GPUARCH=yes # GPUARCH = GPU from list above -D Kokkos_ENABLE_CUDA=yes -D Kokkos_ENABLE_OPENMP=yes - -D CMAKE_CXX_COMPILER=wrapper # wrapper = full path to Cuda nvcc wrapper This will also enable executing FFTs on the GPU, either via the internal KISSFFT library, or - by preference - with the cuFFT library bundled with the CUDA toolkit, depending on whether CMake - can identify its location. The *wrapper* value for - ``CMAKE_CXX_COMPILER`` variable is the path to the CUDA nvcc - compiler wrapper provided in the Kokkos library: - ``lib/kokkos/bin/nvcc_wrapper``\ . The setting should include the - full path name to the wrapper, e.g. - - .. code-block:: bash - - -D CMAKE_CXX_COMPILER=${HOME}/lammps/lib/kokkos/bin/nvcc_wrapper + can identify its location. For AMD or NVIDIA GPUs using HIP, set these variables: @@ -832,63 +822,6 @@ will thus always enable it. ---------- -.. _latte: - -LATTE package -------------------------- - -To build with this package, you must download and build the LATTE -library. - -.. tabs:: - - .. tab:: CMake build - - .. code-block:: bash - - -D DOWNLOAD_LATTE=value # download LATTE for build, value = no (default) or yes - -D LATTE_LIBRARY=path # LATTE library file (only needed if a custom location) - -D USE_INTERNAL_LINALG=value # Use the internal linear algebra library instead of LAPACK - # value = no (default) or yes - - If ``DOWNLOAD_LATTE`` is set, the LATTE library will be downloaded - and built inside the CMake build directory. If the LATTE library - is already on your system (in a location CMake cannot find it), - ``LATTE_LIBRARY`` is the filename (plus path) of the LATTE library - file, not the directory the library file is in. - - The LATTE library requires LAPACK (and BLAS) and CMake can identify - their locations and pass that info to the LATTE build script. But - on some systems this triggers a (current) limitation of CMake and - the configuration will fail. Try enabling ``USE_INTERNAL_LINALG`` in - those cases to use the bundled linear algebra library and work around - the limitation. - - .. tab:: Traditional make - - You can download and build the LATTE library manually if you - prefer; follow the instructions in ``lib/latte/README``\ . You - can also do it in one step from the ``lammps/src`` dir, using a - command like these, which simply invokes the - ``lib/latte/Install.py`` script with the specified args: - - .. 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 - - Note that 3 symbolic (soft) links, ``includelink`` and ``liblink`` - and ``filelink.o``, are created in ``lib/latte`` to point to - required folders and files in the LATTE home directory. When - LAMMPS itself is built it will use these links. You should also - check that the ``Makefile.lammps`` file you create is appropriate - for the compiler you use on your system to build LATTE. - ----------- - .. _lepton: LEPTON package @@ -1413,9 +1346,9 @@ This package depends on the KSPACE package. KSPACE package so the latter one *must* be enabled. The ELECTRODE package also requires LAPACK (and BLAS) and CMake - can identify their locations and pass that info to the LATTE build - script. But on some systems this may cause problems when linking - or the dependency is not desired. Try enabling + can identify their locations and pass that info to the ELECTRODE + build script. But on some systems this may cause problems when + linking or the dependency is not desired. Try enabling ``USE_INTERNAL_LINALG`` in those cases to use the bundled linear algebra library and work around the limitation. diff --git a/doc/src/Build_make.rst b/doc/src/Build_make.rst index f1e34bbc55..f6764100e0 100644 --- a/doc/src/Build_make.rst +++ b/doc/src/Build_make.rst @@ -117,8 +117,8 @@ their settings may become outdated, too: .. code-block:: bash - make mac # build serial LAMMPS on a Mac - make mac_mpi # build parallel LAMMPS on a Mac + make mac # build serial LAMMPS on macOS + make mac_mpi # build parallel LAMMPS on macOS make intel_cpu # build with the INTEL package optimized for CPUs make knl # build with the INTEL package optimized for KNLs make opt # build with the OPT package optimized for CPUs diff --git a/doc/src/Build_manual.rst b/doc/src/Build_manual.rst index d86ad85827..e9a55134da 100644 --- a/doc/src/Build_manual.rst +++ b/doc/src/Build_manual.rst @@ -52,11 +52,11 @@ can be translated to different output format using the `Sphinx incorporates programmer documentation extracted from the LAMMPS C++ sources through the `Doxygen `_ program. Currently the translation to HTML, PDF (via LaTeX), ePUB (for many e-book readers) -and MOBI (for Amazon Kindle readers) are supported. For that to work a -Python 3 interpreter, the ``doxygen`` tools and internet access to -download additional files and tools are required. This download is -usually only required once or after the documentation folder is returned -to a pristine state with ``make clean-all``. +and MOBI (for Amazon Kindle(tm) readers) are supported. For that to work a +Python interpreter version 3.8 or later, the ``doxygen`` tools and +internet access to download additional files and tools are required. +This download is usually only required once or after the documentation +folder is returned to a pristine state with ``make clean-all``. For the documentation build a python virtual environment is set up in the folder ``doc/docenv`` and various python packages are installed into diff --git a/doc/src/Build_package.rst b/doc/src/Build_package.rst index 5e9019afde..2328e4d1e5 100644 --- a/doc/src/Build_package.rst +++ b/doc/src/Build_package.rst @@ -46,7 +46,6 @@ packages: * :ref:`INTEL ` * :ref:`KIM ` * :ref:`KOKKOS ` - * :ref:`LATTE ` * :ref:`LEPTON ` * :ref:`MACHDYN ` * :ref:`MDI ` diff --git a/doc/src/Commands_compute.rst b/doc/src/Commands_compute.rst index f073212524..755000c976 100644 --- a/doc/src/Commands_compute.rst +++ b/doc/src/Commands_compute.rst @@ -46,6 +46,7 @@ KOKKOS, o = OPENMP, t = OPT. * :doc:`com/chunk ` * :doc:`contact/atom ` * :doc:`coord/atom (k) ` + * :doc:`count/type ` * :doc:`damage/atom ` * :doc:`dihedral ` * :doc:`dihedral/local ` @@ -63,7 +64,7 @@ KOKKOS, o = OPENMP, t = OPT. * :doc:`entropy/atom ` * :doc:`erotate/asphere ` * :doc:`erotate/rigid ` - * :doc:`erotate/sphere ` + * :doc:`erotate/sphere (k) ` * :doc:`erotate/sphere/atom ` * :doc:`event/displace ` * :doc:`fabric ` diff --git a/doc/src/Commands_fix.rst b/doc/src/Commands_fix.rst index a9af64d800..6fe321e3c9 100644 --- a/doc/src/Commands_fix.rst +++ b/doc/src/Commands_fix.rst @@ -104,13 +104,13 @@ OPT. * :doc:`langevin/drude ` * :doc:`langevin/eff ` * :doc:`langevin/spin ` - * :doc:`latte ` * :doc:`lb/fluid ` * :doc:`lb/momentum ` * :doc:`lb/viscous ` * :doc:`lineforce ` * :doc:`manifoldforce ` * :doc:`mdi/qm ` + * :doc:`mdi/qmmm ` * :doc:`meso/move ` * :doc:`mol/swap ` * :doc:`momentum (k) ` @@ -261,7 +261,7 @@ OPT. * :doc:`wall/body/polyhedron ` * :doc:`wall/colloid ` * :doc:`wall/ees ` - * :doc:`wall/gran ` + * :doc:`wall/gran (k) ` * :doc:`wall/gran/region ` * :doc:`wall/harmonic ` * :doc:`wall/lj1043 ` diff --git a/doc/src/Commands_pair.rst b/doc/src/Commands_pair.rst index 0912ddcc41..5f79015aaf 100644 --- a/doc/src/Commands_pair.rst +++ b/doc/src/Commands_pair.rst @@ -55,6 +55,7 @@ OPT. * :doc:`born/coul/msm (o) ` * :doc:`born/coul/wolf (go) ` * :doc:`born/coul/wolf/cs (g) ` + * :doc:`born/gauss ` * :doc:`bpm/spring ` * :doc:`brownian (o) ` * :doc:`brownian/poly (o) ` @@ -136,6 +137,7 @@ OPT. * :doc:`lennard/mdf ` * :doc:`lepton (o) ` * :doc:`lepton/coul (o) ` + * :doc:`lepton/sphere (o) ` * :doc:`line/lj ` * :doc:`lj/charmm/coul/charmm (giko) ` * :doc:`lj/charmm/coul/charmm/implicit (ko) ` @@ -170,12 +172,14 @@ OPT. * :doc:`lj/cut/dipole/long (g) ` * :doc:`lj/cut/dipole/sf (go) ` * :doc:`lj/cut/soft (o) ` + * :doc:`lj/cut/sphere (o) ` * :doc:`lj/cut/thole/long (o) ` * :doc:`lj/cut/tip4p/cut (o) ` * :doc:`lj/cut/tip4p/long (got) ` * :doc:`lj/cut/tip4p/long/soft (o) ` * :doc:`lj/expand (gko) ` * :doc:`lj/expand/coul/long (gk) ` + * :doc:`lj/expand/sphere (o) ` * :doc:`lj/gromacs (gko) ` * :doc:`lj/gromacs/coul/gromacs (ko) ` * :doc:`lj/long/coul/long (iot) ` diff --git a/doc/src/Commands_removed.rst b/doc/src/Commands_removed.rst index 06b0303037..d50eab3a41 100644 --- a/doc/src/Commands_removed.rst +++ b/doc/src/Commands_removed.rst @@ -38,6 +38,20 @@ been folded into the :doc:`reset_atoms ` command. If present, LAMMPS will replace the commands accordingly and print a warning. +LATTE package +------------- + +.. deprecated:: TBD + +The LATTE package with the fix latte command was removed from LAMMPS. +This functionality has been superseded by :doc:`fix mdi/qm ` +and :doc:`fix mdi/qmmm ` from the :ref:`MDI package +`. These fixes are compatible with several quantum software +packages, including LATTE. See the ``examples/QUANTUM`` dir and the +:doc:`MDI coupling HOWTO ` page. MDI supports running LAMMPS +with LATTE as a plugin library (similar to the way fix latte worked), as +well as on a different set of MPI processors. + MEAM package ------------ diff --git a/doc/src/Developer.rst b/doc/src/Developer.rst index 406dd26f59..b0cfcc14fc 100644 --- a/doc/src/Developer.rst +++ b/doc/src/Developer.rst @@ -13,6 +13,7 @@ of time and requests from the LAMMPS user community. Developer_org Developer_code_design Developer_parallel + Developer_atom Developer_comm_ops Developer_flow Developer_write diff --git a/doc/src/Developer_atom.rst b/doc/src/Developer_atom.rst new file mode 100644 index 0000000000..8bc187ae7f --- /dev/null +++ b/doc/src/Developer_atom.rst @@ -0,0 +1,88 @@ +Accessing per-atom data +----------------------- + +This page discusses how per-atom data is managed in LAMMPS, how it can +be accessed, what communication patters apply, and some of the utility +functions that exist for a variety of purposes. + + +Owned and ghost atoms +^^^^^^^^^^^^^^^^^^^^^ + +As described on the :doc:`parallel partitioning algorithms +` page, LAMMPS uses a domain decomposition of the +simulation domain, either in a *brick* or *tiled* manner. Each MPI +process *owns* exactly one subdomain and the atoms within it. To compute +forces for tuples of atoms that are spread across sub-domain boundaries, +also a "halo" of *ghost* atoms are maintained within a the communication +cutoff distance of its subdomain. + +The total number of atoms is stored in `Atom::natoms` (within any +typical class this can be referred to at `atom->natoms`. The number of +*owned* (or "local" atoms) are stored in `Atom::nlocal`; the number of +*ghost* atoms is stored in `Atom::nghost`. The sum of `Atom::nlocal` +over all MPI processes should be `Atom::natoms`. This is by default +regularly checked by the Thermo class, and if the sum does not match, +LAMMPS stops with a "lost atoms" error. For convenience also the +property `Atom::nmax` is available, this is the maximum of +`Atom::nlocal + Atom::nghost` across all MPI processes. + +Per-atom properties are either managed by the atom style, or individual +classes. or as custom arrays by the individual classes. If only access +to *owned* atoms is needed, they are usually allocated to be of size +`Atom::nlocal`, otherwise of size `Atom::nmax`. Please note that not all +per-atom properties are available or updated on *ghost* atoms. For +example, per-atom velocities are only updated with :doc:`comm_modify vel +yes `. + + +Atom indexing +^^^^^^^^^^^^^ + +When referring to individual atoms, they may be indexed by their local +*index*, their index in their `Atom::x` array. This is densely populated +containing first all *owned* atoms (index < `Atom::nlocal`) and then all +*ghost* atoms. The order of atoms in these arrays can change due to +atoms migrating between between subdomains, atoms being added or +deleted, or atoms being sorted for better cache efficiency. Atoms are +globally uniquely identified by their *atom ID*. There may be multiple +atoms with the same atom ID present, but only one of them may be an +*owned* atom. + +To find the local *index* of an atom, when the *atom ID* is known, the +`Atom::map()` function may be used. It will return the local atom index +or -1. If the returned value is between 0 (inclusive) and `Atom::nlocal` +(exclusive) it is an *owned* or "local" atom; for larger values the atom +is present as a ghost atom; for a value of -1, the atom is not present +on the current subdomain at all. + +If multiple atoms with the same tag exist in the same subdomain, they +can be found via the `Atom::sametag` array. It points to the next atom +index with the same tag or -1 if there are no more atoms with the same +tag. The list will be exhaustive when starting with an index of an +*owned* atom, since the atom IDs are unique, so there can only be one +such atom. Example code to count atoms with same atom ID in subdomain: + +.. code-block:: c++ + + for (int i = 0; i < atom->nlocal; ++i) { + int count = 0; + while (sametag[i] >= 0) { + i = sametag[i]; + ++count; + } + printf("Atom ID: %ld is present %d times\n", atom->tag[i], count); + } + +Atom class versus AtomVec classes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `Atom` class contains all kinds of flags and counters about atoms in +the system and that includes pointers to **all** per-atom properties +available for atoms. However, only a subset of these pointers are +non-NULL and which those are depends on the atom style. For each atom +style there is a corresponding `AtomVecXXX` class derived from the +`AtomVec` base class, where the XXX indicates the atom style. This +`AtomVecXXX` class will update the counters and per-atom pointers if +atoms are added or removed to the system or migrate between subdomains. + diff --git a/doc/src/Developer_notes.rst b/doc/src/Developer_notes.rst index 07b289b583..9f950dda8a 100644 --- a/doc/src/Developer_notes.rst +++ b/doc/src/Developer_notes.rst @@ -74,6 +74,8 @@ when converting "12.5", while the ValueTokenizer class will throw an :cpp:func:`ValueTokenizer::next_int() ` is called on the same string. +.. _request-neighbor-list: + Requesting and accessing neighbor lists ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/src/Developer_updating.rst b/doc/src/Developer_updating.rst index 28b3712ae0..36c6974b30 100644 --- a/doc/src/Developer_updating.rst +++ b/doc/src/Developer_updating.rst @@ -389,7 +389,7 @@ This change is **required** or else the code will not compile. Rename of fix STORE/PERATOM to fix STORE/ATOM and change of arguments ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. versionchanged:: TBD +.. versionchanged:: 28Mar2023 The available functionality of the internal fix to store per-atom properties was expanded to enable storing data with ghost atoms and to diff --git a/doc/src/Developer_write.rst b/doc/src/Developer_write.rst index c374ec2e77..ef4d06a5f6 100644 --- a/doc/src/Developer_write.rst +++ b/doc/src/Developer_write.rst @@ -6,250 +6,9 @@ be extended by writing new classes that derive from existing parent classes in LAMMPS. Here, some specific coding details are provided for writing code for LAMMPS. -Writing a new fix style -^^^^^^^^^^^^^^^^^^^^^^^ -Writing fixes is a flexible way of extending LAMMPS. Users can -implement many things using fixes: - -- changing particles attributes (positions, velocities, forces, etc.). Examples: FixNVE, FixFreeze. -- reading/writing data. Example: FixRestart. -- adding or modifying properties due to geometry. Example: FixWall. -- interacting with other subsystems or external code: Examples: FixTTM, FixExternal, FixLATTE -- saving information for analysis or future use (previous positions, - for instance). Examples: Fix AveTime, FixStoreState. - - -All fixes are derived from the Fix base class and must have a -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++ - - #ifdef FIX_CLASS - // clang-format off - FixStyle(print/vel,FixPrintVel); - // clang-format on - #else - /* the definition of the FixPrintVel class comes here */ - ... - #endif - -Where ``print/vel`` is the style name of your fix in the input script and -``FixPrintVel`` is the name of the class. The header file would be called -``fix_print_vel.h`` and the implementation file ``fix_print_vel.cpp``. -These conventions allow LAMMPS to automatically integrate it into the -executable when compiling and associate your new fix class with the designated -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++ - - FixPrintVel::FixPrintVel(LAMMPS *lmp, int narg, char **arg) - : Fix(lmp, narg, arg) - { - if (narg < 4) - error->all(FLERR,"Illegal fix print/vel command"); - - nevery = utils::inumeric(FLERR,arg[3],false,lmp); - if (nevery <= 0) - error->all(FLERR,"Illegal fix print/vel command"); - } - -In the constructor you should parse your fix arguments which are -specified in the script. All fixes have pretty much the same syntax: -``fix ``. The -first 3 parameters are parsed by Fix base class constructor, while -```` should be parsed by you. In our case, we need to -specify how often we want to print an average velocity. For instance, -once in 50 timesteps: ``fix 1 print/vel 50``. There is a special variable -in the Fix class called ``nevery`` which specifies how often the method -``end_of_step()`` is called. Thus all we need to do is just set it up. - -The next method we need to implement is ``setmask()``: - -.. code-block:: c++ - - int FixPrintVel::setmask() - { - int mask = 0; - mask |= FixConst::END_OF_STEP; - return mask; - } - -Here the user specifies which methods of your fix should be called -during execution. The constant ``END_OF_STEP`` corresponds to the -``end_of_step()`` method. The most important available methods that -are called during a timestep and the order in which they are called -are shown in the previous section. - -.. code-block:: c++ - - void FixPrintVel::end_of_step() - { - // for add3, scale3 - using namespace MathExtra; - - double** v = atom->v; - int nlocal = atom->nlocal; - double localAvgVel[4]; // 4th element for particles count - memset(localAvgVel, 0, 4 * sizeof(double)); - for (int particleInd = 0; particleInd < nlocal; ++particleInd) { - add3(localAvgVel, v[particleInd], localAvgVel); - } - localAvgVel[3] = nlocal; - double globalAvgVel[4]; - memset(globalAvgVel, 0, 4 * sizeof(double)); - MPI_Allreduce(localAvgVel, globalAvgVel, 4, MPI_DOUBLE, MPI_SUM, world); - scale3(1.0 / globalAvgVel[3], globalAvgVel); - if ((comm->me == 0) && screen) { - fmt::print(screen,"{}, {}, {}\n", - globalAvgVel[0], globalAvgVel[1], globalAvgVel[2]); - } - } - -In the code above, we use MathExtra routines defined in -``math_extra.h``. There are bunch of math functions to work with -arrays of doubles as with math vectors. It is also important to note -that LAMMPS code should always assume to be run in parallel and that -atom data is thus distributed across the MPI ranks. Thus you can -only process data from local atoms directly and need to use MPI library -calls to combine or exchange data. For serial execution, LAMMPS -comes bundled with the MPI STUBS library that contains the MPI library -function calls in dummy versions that only work for a single MPI rank. - -In this code we use an instance of Atom class. This object is stored -in the Pointers class (see ``pointers.h``) which is the base class of -the Fix base class. This object contains references to various class -instances (the original instances are created and held by the LAMMPS -class) with all global information about the simulation system. -Data from the Pointers class is available to all classes inherited from -it using protected inheritance. Hence when you write you own class, -which is going to use LAMMPS data, don't forget to inherit from Pointers -or pass an Pointer to it to all functions that need access. When writing -fixes we inherit from class Fix which is inherited from Pointers so -there is no need to inherit from it directly. - -The code above computes average velocity for all particles in the -simulation. Yet you have one unused parameter in fix call from the -script: ``group_name``. This parameter specifies the group of atoms -used in the fix. So we should compute average for all particles in the -simulation only if ``group_name == "all"``, but it can be any group. -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++ - - for (int i = 0; i < nlocal; ++i) { - if (atom->mask[i] & groupbit) { - // Do all job here - } - } - -Class Atom encapsulates atoms positions, velocities, forces, etc. User -can access them using particle index. Note, that particle indexes are -usually changed every few timesteps because of neighbor list rebuilds -and spatial sorting (to improve cache efficiency). - -Let us consider another Fix example: We want to have a fix which stores -atoms position from previous time step in your fix. The local atoms -indexes may not be valid on the next iteration. In order to handle -this situation there are several methods which should be implemented: - -- ``double memory_usage()``: return how much memory the fix uses (optional) -- ``void grow_arrays(int)``: do reallocation of the per particle arrays in your fix -- ``void copy_arrays(int i, int j, int delflag)``: copy i-th per-particle - information to j-th. Used when atom sorting is performed. if delflag is set - and atom j owns a body, move the body information to atom i. -- ``void set_arrays(int i)``: sets i-th particle related information to zero - -Note, that if your class implements these methods, it must call add calls of -add_callback and delete_callback to constructor and destructor. Since we want -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++ - - FixSavePos::FixSavePos(LAMMPS *lmp, int narg, char **arg), xold(nullptr) - { - //... - memory->create(xold, atom->nmax, 3, "FixSavePos:x"); - atom->add_callback(0); - } - - FixSavePos::~FixSavePos() { - atom->delete_callback(id, 0); - memory->destroy(xold); - } - -Implement the aforementioned methods: - -.. code-block:: c++ - - double FixSavePos::memory_usage() - { - int nmax = atom->nmax; - double bytes = 0.0; - bytes += nmax * 3 * sizeof(double); - return bytes; - } - - void FixSavePos::grow_arrays(int nmax) - { - memory->grow(xold, nmax, 3, "FixSavePos:xold"); - } - - void FixSavePos::copy_arrays(int i, int j, int delflag) - { - memcpy(xold[j], xold[i], sizeof(double) * 3); - } - - void FixSavePos::set_arrays(int i) - { - memset(xold[i], 0, sizeof(double) * 3); - } - - int FixSavePos::pack_exchange(int i, double *buf) - { - int m = 0; - buf[m++] = xold[i][0]; - buf[m++] = xold[i][1]; - buf[m++] = xold[i][2]; - - return m; - } - - int FixSavePos::unpack_exchange(int nlocal, double *buf) - { - int m = 0; - xold[nlocal][0] = buf[m++]; - xold[nlocal][1] = buf[m++]; - xold[nlocal][2] = buf[m++]; - - return m; - } - -Now, a little bit about memory allocation. We use the Memory class which -is just a bunch of template functions for allocating 1D and 2D -arrays. So you need to add include ``memory.h`` to have access to them. - -Finally, if you need to write/read some global information used in -your fix to the restart file, you might do it by setting flag -``restart_global = 1`` in the constructor and implementing methods void -``write_restart(FILE *fp)`` and ``void restart(char *buf)``. -If, in addition, you want to write the per-atom property to restart -files additional settings and functions are needed: - -- a fix flag indicating this needs to be set ``restart_peratom = 1;`` -- ``atom->add_callback()`` and ``atom->delete_callback()`` must be called - a second time with the final argument set to 1 instead of 0 (indicating - restart processing instead of per-atom data memory management). -- the functions ``void pack_restart(int i, double *buf)`` and - ``void unpack_restart(int nlocal, int nth)`` need to be implemented +.. toctree:: + :maxdepth: 1 + Developer_write_pair + Developer_write_fix diff --git a/doc/src/Developer_write_fix.rst b/doc/src/Developer_write_fix.rst new file mode 100644 index 0000000000..f8732f74e3 --- /dev/null +++ b/doc/src/Developer_write_fix.rst @@ -0,0 +1,245 @@ +Writing a new fix style +^^^^^^^^^^^^^^^^^^^^^^^ + +Writing fix styles is a flexible way of extending LAMMPS. Users can +implement many things using fixes. Some fix styles are only used +internally to support compute styles or pair styles: + +- change particles attributes (positions, velocities, forces, etc.). Examples: ``FixNVE``, ``FixFreeze``. +- read or write data. Example: ``FixRestart``. +- adding or modifying properties due to geometry. Example: ``FixWall``. +- interacting with other subsystems or external code: Examples: ``FixTTM``, ``FixExternal``, ``FixMDI`` +- saving information for analysis or future use (previous positions, + for instance). Examples: ``FixAveTime``, ``FixStoreState``. + +All fixes are derived from the ``Fix`` base class and must have a +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++ + + #ifdef FIX_CLASS + // clang-format off + FixStyle(print/vel,FixPrintVel); + // clang-format on + #else + /* the definition of the FixPrintVel class comes here */ + ... + #endif + +Where ``print/vel`` is the style name of your fix in the input script and +``FixPrintVel`` is the name of the class. The header file would be called +``fix_print_vel.h`` and the implementation file ``fix_print_vel.cpp``. +These conventions allow LAMMPS to automatically integrate it into the +executable when compiling and associate your new fix class with the designated +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++ + + FixPrintVel::FixPrintVel(LAMMPS *lmp, int narg, char **arg) + : Fix(lmp, narg, arg) + { + if (narg < 4) utils::missing_cmd_args(FLERR, "fix print/vel", error); + + nevery = utils::inumeric(FLERR,arg[3],false,lmp); + if (nevery <= 0) + error->all(FLERR,"Illegal fix print/vel nevery value: {}", nevery); + } + +In the constructor you should parse the fix arguments which are +specified in the script. All fixes have pretty much the same syntax: +``fix ``. The first 3 +parameters are parsed by Fix base class constructor, while ```` should be parsed by you. In our case, we need to specify +how often we want to print an average velocity. For instance, once in 50 +timesteps: ``fix 1 print/vel 50``. There is a special variable in the +Fix class called ``nevery`` which specifies how often the method +``end_of_step()`` is called. Thus all we need to do is just set it up. + +The next method we need to implement is ``setmask()``: + +.. code-block:: c++ + + int FixPrintVel::setmask() + { + int mask = 0; + mask |= FixConst::END_OF_STEP; + return mask; + } + +Here the we specify which methods of the fix should be called during +:doc:`execution of a timestep `. The constant +``END_OF_STEP`` corresponds to the ``end_of_step()`` method. The most +important available methods that are called during a timestep. + +.. code-block:: c++ + + void FixPrintVel::end_of_step() + { + // for add3, scale3 + using namespace MathExtra; + + double** v = atom->v; + int nlocal = atom->nlocal; + double localAvgVel[4]; // 4th element for particles count + memset(localAvgVel, 0, 4 * sizeof(double)); + for (int particleInd = 0; particleInd < nlocal; ++particleInd) { + add3(localAvgVel, v[particleInd], localAvgVel); + } + localAvgVel[3] = nlocal; + double globalAvgVel[4]; + memset(globalAvgVel, 0, 4 * sizeof(double)); + MPI_Allreduce(localAvgVel, globalAvgVel, 4, MPI_DOUBLE, MPI_SUM, world); + scale3(1.0 / globalAvgVel[3], globalAvgVel); + if ((comm->me == 0) && screen) { + fmt::print(screen,"{}, {}, {}\n", + globalAvgVel[0], globalAvgVel[1], globalAvgVel[2]); + } + } + +In the code above, we use MathExtra routines defined in +``math_extra.h``. There are bunch of math functions to work with +arrays of doubles as with math vectors. It is also important to note +that LAMMPS code should always assume to be run in parallel and that +atom data is thus distributed across the MPI ranks. Thus you can +only process data from local atoms directly and need to use MPI library +calls to combine or exchange data. For serial execution, LAMMPS +comes bundled with the MPI STUBS library that contains the MPI library +function calls in dummy versions that only work for a single MPI rank. + +In this code we use an instance of Atom class. This object is stored +in the Pointers class (see ``pointers.h``) which is the base class of +the Fix base class. This object contains references to various class +instances (the original instances are created and held by the LAMMPS +class) with all global information about the simulation system. +Data from the Pointers class is available to all classes inherited from +it using protected inheritance. Hence when you write you own class, +which is going to use LAMMPS data, don't forget to inherit from Pointers +or pass a Pointer to it to all functions that need access. When writing +fixes we inherit from class Fix which is inherited from Pointers so +there is no need to inherit from it directly. + +The code above computes average velocity for all particles in the +simulation. Yet you have one unused parameter in fix call from the +script: ``group_name``. This parameter specifies the group of atoms +used in the fix. So we should compute average for all particles in the +simulation only if ``group_name == "all"``, but it can be any group. +The group membership information of an atom is contained in the *mask* +property of an 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++ + + for (int i = 0; i < nlocal; ++i) { + if (atom->mask[i] & groupbit) { + // Do all job here + } + } + +Class Atom encapsulates atoms positions, velocities, forces, etc. Users +can access them using particle index. Note, that particle indexes are +usually changed every few timesteps because of neighbor list rebuilds +and spatial sorting (to improve cache efficiency). + +Let us consider another Fix example: We want to have a fix which stores +atoms position from the previous time step in your fix. The local atoms +indexes may not be valid on the next iteration. In order to handle +this situation there are several methods which should be implemented: + +- ``double memory_usage()``: return how much memory the fix uses (optional) +- ``void grow_arrays(int)``: do reallocation of the per-particle arrays in your fix +- ``void copy_arrays(int i, int j, int delflag)``: copy i-th per-particle + information to j-th. Used when atom sorting is performed. if delflag is set + and atom j owns a body, move the body information to atom i. +- ``void set_arrays(int i)``: sets i-th particle related information to zero + +Note, that if your class implements these methods, it must add calls of +add_callback and delete_callback to the constructor and destructor. Since we want +to store positions of atoms from the previous timestep, we need to add +``double** xold`` to the header file. Than add allocation code +to the constructor: + +.. code-block:: c++ + + FixSavePos::FixSavePos(LAMMPS *lmp, int narg, char **arg), xold(nullptr) + { + //... + memory->create(xold, atom->nmax, 3, "FixSavePos:x"); + atom->add_callback(0); + } + + FixSavePos::~FixSavePos() { + atom->delete_callback(id, 0); + memory->destroy(xold); + } + +Implement the aforementioned methods: + +.. code-block:: c++ + + double FixSavePos::memory_usage() + { + int nmax = atom->nmax; + double bytes = 0.0; + bytes += nmax * 3 * sizeof(double); + return bytes; + } + + void FixSavePos::grow_arrays(int nmax) + { + memory->grow(xold, nmax, 3, "FixSavePos:xold"); + } + + void FixSavePos::copy_arrays(int i, int j, int delflag) + { + memcpy(xold[j], xold[i], sizeof(double) * 3); + } + + void FixSavePos::set_arrays(int i) + { + memset(xold[i], 0, sizeof(double) * 3); + } + + int FixSavePos::pack_exchange(int i, double *buf) + { + int m = 0; + buf[m++] = xold[i][0]; + buf[m++] = xold[i][1]; + buf[m++] = xold[i][2]; + + return m; + } + + int FixSavePos::unpack_exchange(int nlocal, double *buf) + { + int m = 0; + xold[nlocal][0] = buf[m++]; + xold[nlocal][1] = buf[m++]; + xold[nlocal][2] = buf[m++]; + + return m; + } + +Now, a little bit about memory allocation. We use the Memory class which +is just a bunch of template functions for allocating 1D and 2D +arrays. So you need to add include ``memory.h`` to have access to them. + +Finally, if you need to write/read some global information used in +your fix to the restart file, you might do it by setting flag +``restart_global = 1`` in the constructor and implementing methods void +``write_restart(FILE *fp)`` and ``void restart(char *buf)``. +If, in addition, you want to write the per-atom property to restart +files additional settings and functions are needed: + +- a fix flag indicating this needs to be set ``restart_peratom = 1;`` +- ``atom->add_callback()`` and ``atom->delete_callback()`` must be called + a second time with the final argument set to 1 instead of 0 (indicating + restart processing instead of per-atom data memory management). +- the functions ``void pack_restart(int i, double *buf)`` and + ``void unpack_restart(int nlocal, int nth)`` need to be implemented + diff --git a/doc/src/Developer_write_pair.rst b/doc/src/Developer_write_pair.rst new file mode 100644 index 0000000000..d70f8ec50b --- /dev/null +++ b/doc/src/Developer_write_pair.rst @@ -0,0 +1,1354 @@ +Writing new pair styles +^^^^^^^^^^^^^^^^^^^^^^^ + +Pair styles are at the core of most simulations with LAMMPS, since they +are used to compute the forces (plus energy and virial contributions, if +needed) on atoms for pairs or small clusters of atoms within a given +cutoff. This is often the dominant computation in LAMMPS, and sometimes +even the only one. Pair styles can be grouped into multiple categories: + +#. simple pairwise additive interactions of point particles + (e.g. :doc:`Lennard-Jones `, :doc:`Morse `, + :doc:`Buckingham `) +#. pairwise additive interactions of point particles with added + :doc:`Coulomb ` interactions or *only* the Coulomb interactions +#. manybody interactions of point particles (e.g. :doc:`EAM `, + :doc:`Tersoff `) +#. complex interactions that include additional per-atom properties + (e.g. Discrete Element Models (DEM), Peridynamics, Ellipsoids) +#. special purpose pair styles that may not even compute forces like + :doc:`pair_style zero ` and :doc:`pair_style tracker + `, or are a wrapper for multiple kinds of interactions + like :doc:`pair_style hybrid `, :doc:`pair_style list `, + and :doc:`pair_style kim ` + +In the text below, we will discuss aspects of implementing pair styles +in LAMMPS by looking at representative case studies. The design of +LAMMPS allows developers to focus on the essentials, which is to compute +the forces (and energies or virial contributions), enter and manage the +global settings as well as the potential parameters, and the pair style +specific parts of reading and writing restart and data files. Most of +the complex tasks like management of the atom positions, domain +decomposition and boundaries, or neighbor list creation are handled +transparently by other parts of the LAMMPS code. + +As shown on the page for :doc:`writing or extending pair styles +`, in order to implement a new pair style, a new class must +be written that is either directly or indirectly derived from the +``Pair`` class. If that class is directly derived from ``Pair``, there +are three methods that *must* be re-implemented, since they are "pure" +in the base class: ``Pair::compute()``, ``Pair::settings()``, +``Pair::coeff()``. In addition, a custom constructor is needed. All +other methods are optional and have default implementations in the base +class (most of which do nothing), but they may need to be overridden +depending on the requirements of the model. + +We are looking at the following cases: + +- `Case 1: a pairwise additive model`_ +- `Case 2: a many-body potential`_ +- `Case 3: a potential requiring communication`_ +- `Case 4: potentials without a compute() function`_ + +---- + +Case 1: a pairwise additive model +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this section, we will describe the procedure of adding a simple pair +style to LAMMPS: an empirical model that can be used to model liquid +mercury. The pair style shall be called :doc:`bond/gauss +` and the complete implementation can be found in the +files ``src/EXTRA-PAIR/pair_born_gauss.cpp`` and +``src/EXTRA-PAIR/pair_born_gauss.h`` of the LAMMPS source code. + +Model and general considerations +"""""""""""""""""""""""""""""""" + +The functional form of the model according to :ref:`(Bomont) ` +consists of a repulsive Born-Mayer exponential term and a temperature +dependent, attractive Gaussian term. + +.. math:: + + E = A_0 \exp \left( -\alpha r \right) - A_1 \exp\left[ -\beta \left(r - r_0 \right)^2 \right] + +For the application to mercury, the following parameters are listed: + +- :math:`A_0 = 8.2464 \times 10^{13} \; \textrm{eV}` +- :math:`\alpha = 12.48 \; \AA^{-1}` +- :math:`\beta = 0.44 \; \AA^{-2}` +- :math:`r_0 = 3.56 \; \AA` +- :math:`A_1` is temperature dependent and can be determined from + :math:`A_1 = a_0 + a_1 T + a_2 T^2` with: + + - :math:`a_0 = 1.97475 \times 10^{-2} \; \textrm{eV}` + - :math:`a_1 = 8.40841 \times 10^{-5} \; \textrm{eV/K}` + - :math:`a_2 = -2.58717 \times 10^{-8} \; \textrm{eV/K}^{-2}` + +With the optional cutoff, this means we have a total of 5 or 6 +parameters for each pair of atom types. Additionally, we need to input a +default cutoff value as a global setting. + +Because of the combination of Born-Mayer with a Gaussian, the pair style +shall be named "born/gauss" and thus the class name would be +``PairBornGauss`` and the source files ``pair_born_gauss.h`` and +``pair_born_gauss.cpp``. Since this is a rather uncommon potential, it +shall be added to the :ref:`EXTRA-PAIR ` package. + +Header file +""""""""""" + +The first segment of any LAMMPS source should be the copyright and +license statement. Note the marker in the first line to indicate to +editors like emacs that this file is a C++ source, even though the .h +extension suggests a C source (this is a convention inherited from the +very beginning of the C++ version of LAMMPS). + +.. code-block:: c++ + + /* -*- c++ -*- ---------------------------------------------------------- + LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator + https://www.lammps.org/, Sandia National Laboratories + LAMMPS development team: developers@lammps.org + + Copyright (2003) Sandia Corporation. Under the terms of Contract + DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains + certain rights in this software. This software is distributed under + the GNU General Public License. + + See the README file in the top-level LAMMPS directory. + ------------------------------------------------------------------------- */ + +Every pair style must be registered in LAMMPS by including the following +lines of code in the second part of the header after the copyright +message and before the include guards for the class definition: + +.. code-block:: c++ + + #ifdef PAIR_CLASS + // clang-format off + PairStyle(born/gauss,PairBornGauss); + // clang-format on + #else + + /* the definition of the PairBornGauss class (see below) is inserted here */ + + #endif + +This block of between ``#ifdef PAIR_CLASS`` and ``#else`` will be +included by the ``Force`` class in ``force.cpp`` to build a map of +"factory functions" that will create an instance of these classes and +return a pointer to it. The map connects the name of the pair style, +"born/gauss", to the name of the class, ``PairBornGauss``. During +compilation, LAMMPS constructs a file ``style_pair.h`` that contains +``#include`` statements for all "installed" pair styles. Before +including ``style_pair.h`` into ``force.cpp``, the ``PAIR_CLASS`` define +is set and the ``PairStyle(name,class)`` macro defined. The code of the +macro adds the installed pair styles to the "factory map" which enables +the :doc:`pair_style command ` to create the pair style +instance. + +The list of header files to include is automatically updated by the +build system if there are new files, so the presence of the new header +file in the ``src/EXTRA-PAIR`` folder and the enabling of the EXTRA-PAIR +package will trigger LAMMPS to include the new pair style when it is +(re-)compiled. The "// clang-format" format comments are needed so that +running :ref:`clang-format ` on the file will not insert +unwanted blanks between "born", "/", and "gauss" which would break the +``PairStyle`` macro. + +The third part of the header file is the actual class definition of the +``PairBornGauss`` class. This has the prototypes for all member +functions that will be implemented by this pair style. This includes +:doc:`a few required and a number of optional functions `. +All functions that were labeled in the base class as "virtual" must be +given the "override" property, as it is done in the code shown below. + +The "override" property helps to detect unexpected mismatches because +compilation will stop with an error in case the signature of a function +is changed in the base class without also changing it in all derived +classes. For example, if this change added an optional argument with a +default value, then all existing source code *calling* the function +would not need changes and still compile, but the function in the +derived class would no longer override the one in the base class due to +the different number of arguments and the behavior of the pair style is +thus changed in an unintended way. Using the "override" keyword +prevents such issues. + +.. code-block:: c++ + + #ifndef LMP_PAIR_BORN_GAUSS_H + #define LMP_PAIR_BORN_GAUSS_H + + #include "pair.h" + + namespace LAMMPS_NS { + + class PairBornGauss : public Pair { + public: + PairBornGauss(class LAMMPS *); + ~PairBornGauss() override; + + void compute(int, int) override; + void settings(int, char **) override; + void coeff(int, char **) override; + double init_one(int, int) override; + + void write_restart(FILE *) override; + void read_restart(FILE *) override; + void write_restart_settings(FILE *) override; + void read_restart_settings(FILE *) override; + void write_data(FILE *) override; + void write_data_all(FILE *) override; + + double single(int, int, int, int, double, double, double, double &) override; + void *extract(const char *, int &) override; + +Also, variables and arrays for storing global settings and potential +parameters are defined. Since these are internal to the class, they are +placed after a "protected:" label. + +.. code-block:: c++ + + protected: + double cut_global; + double **cut; + double **biga0, **alpha, **biga1, **beta, **r0; + double **a0, **a1, **a2; + double **offset; + + virtual void allocate(); + }; + } // namespace LAMMPS_NS + #endif + +Implementation file +""""""""""""""""""" + +We move on to the implementation of the ``PairBornGauss`` class in the +``pair_born_gauss.cpp`` file. This file also starts with a LAMMPS +copyright and license header. Below that notice is typically the space +where comments may be added with additional information about this +specific file, the author(s), affiliation(s), and email address(es). +This way the contributing author(s) can be easily contacted, when +there are questions about the implementation later. Since the file(s) +may be around for a long time, it is beneficial to use some kind of +"permanent" email address, if possible. + +.. code-block:: c++ + + /* ---------------------------------------------------------------------- + LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator + https://www.lammps.org/, Sandia National Laboratories + LAMMPS development team: developers@lammps.org + + Copyright (2003) Sandia Corporation. Under the terms of Contract + DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains + certain rights in this software. This software is distributed under + the GNU General Public License. + + See the README file in the top-level LAMMPS directory. + ------------------------------------------------------------------------- */ + + // Contributing author: Axel Kohlmeyer, Temple University, akohlmey@gmail.com + + #include "pair_born_gauss.h" + + #include "atom.h" + #include "comm.h" + #include "error.h" + #include "fix.h" + #include "force.h" + #include "memory.h" + #include "neigh_list.h" + + #include + #include + + using namespace LAMMPS_NS; + +The second section of the implementation file has various include +statements. The include file for the class header has to come first, +then a block of LAMMPS classes (sorted alphabetically) followed by a +block of system headers and others, if needed. Note the standardized +C++ notation for headers of C-library functions (``cmath`` instead of +``math.h``). The final statement of this segment imports the +``LAMMPS_NS::`` namespace globally for this file. This way, all LAMMPS +specific functions and classes do not have to be prefixed with +``LAMMPS_NS::``. + +Constructor and destructor (required) +""""""""""""""""""""""""""""""""""""" + +The first two functions in the implementation source file are typically +the constructor and the destructor. + +Pair styles are different from most classes in LAMMPS that define a +"style", as their constructor only uses the LAMMPS class instance +pointer as an argument, but **not** the command line arguments of the +:doc:`pair_style command `. Instead, those arguments are +processed in the ``Pair::settings()`` function (or rather the version in +the derived class). The constructor is the place where global defaults +are set and specifically flags are set indicating which optional +features of a pair style are available. + +.. code-block:: c++ + + /* ---------------------------------------------------------------------- */ + + PairBornGauss::PairBornGauss(LAMMPS *lmp) : Pair(lmp) + { + writedata = 1; + } + +The `writedata = 1;` statement indicates that the pair style is capable +of writing the current pair coefficient parameters to data files. That +is, the class implements specific versions for ``Pair::data()`` and +``Pair::data_all()``. Other statements that could be added here would +be `single_enable = 1;` or `respa_enable = 0;` to indicate that the +``Pair::single()`` function is present and the +``Pair::compute_(inner|middle|outer)`` functions are not, but those are +also the default settings and already set in the base class. + +In the destructor, we need to delete all memory that was allocated by the +pair style, usually to hold force field parameters that were entered +with the :doc:`pair_coeff command `. Most of those array +pointers will need to be declared in the derived class header, but some +(e.g. setflag, cutsq) are already declared in the base class. + +.. code-block:: c++ + + PairBornGauss::~PairBornGauss() + { + if (allocated) { + memory->destroy(setflag); + memory->destroy(cutsq); + memory->destroy(cut); + memory->destroy(biga0); + memory->destroy(alpha); + memory->destroy(biga1); + memory->destroy(beta); + memory->destroy(r0); + memory->destroy(offset); + } + } + + +Settings and coefficients (required) +"""""""""""""""""""""""""""""""""""" + +To enter the global pair style settings and the pair style parameters, +the functions ``Pair::settings()`` and ``Pair::coeff()`` need to be +re-implemented. The arguments to the ``settings()`` function are the +arguments given to the :doc:`pair_style command `. +Normally, those would already be processed as part of the constructor, +but moving this to a separate function allows users to change global +settings like the default cutoff without having to reissue all +pair_coeff commands or re-read the ``Pair Coeffs`` sections from the +data file. In the ``settings()`` function, also the arrays for storing +parameters, to define cutoffs, track with pairs of parameters have been +explicitly set are allocated and, if needed, initialized. In this case, +the memory allocation and initialization is moved to a function +``allocate()``. + +.. code-block:: c++ + + /* ---------------------------------------------------------------------- + allocate all arrays + ------------------------------------------------------------------------- */ + + void PairBornGauss::allocate() + { + allocated = 1; + int np1 = atom->ntypes + 1; + + memory->create(setflag, np1, np1, "pair:setflag"); + for (int i = 1; i < np1; i++) + for (int j = i; j < np1; j++) setflag[i][j] = 0; + + memory->create(cutsq, np1, np1, "pair:cutsq"); + memory->create(cut, np1, np1, "pair:cut"); + memory->create(biga0, np1, np1, "pair:biga0"); + memory->create(alpha, np1, np1, "pair:alpha"); + memory->create(biga1, np1, np1, "pair:biga1"); + memory->create(beta, np1, np1, "pair:beta"); + memory->create(r0, np1, np1, "pair:r0"); + memory->create(offset, np1, np1, "pair:offset"); + } + + /* ---------------------------------------------------------------------- + global settings + ------------------------------------------------------------------------- */ + + void PairBornGauss::settings(int narg, char **arg) + { + if (narg != 1) error->all(FLERR, "Pair style bond/gauss must have exactly one argument"); + cut_global = utils::numeric(FLERR, arg[0], false, lmp); + + // reset per-type pair cutoffs that have been explicitly set previously + + if (allocated) { + for (int i = 1; i <= atom->ntypes; i++) + for (int j = i; j <= atom->ntypes; j++) + if (setflag[i][j]) cut[i][j] = cut_global; + } + } + +The arguments to the ``coeff()`` function are the arguments to the +:doc:`pair_coeff command `. The function is also called +when processing the ``Pair Coeffs`` or ``PairIJ Coeffs`` sections of +data files. In the case of the ``Pair Coeffs`` section, there is only +one atom type per line and thus the first argument is duplicated. Since +the atom type arguments of the :doc:`pair_coeff command ` +may be a range (e.g. \*\ 3 for atom types 1, 2, and 3), the +corresponding arguments are passed to the :cpp:func:`utils::bounds() +` function which will then return the low +and high end of the range. Note that the ``setflag`` array is set to 1 +for all pairs of atom types processed by this call. This information is +later used in the ``init_one()`` function to determine if any coefficients +are missing and, if supported by the potential, generate those missing +coefficients from the selected mixing rule. + +.. code-block:: c++ + + /* ---------------------------------------------------------------------- + set coeffs for one or more type pairs + ------------------------------------------------------------------------- */ + + void PairBornGauss::coeff(int narg, char **arg) + { + if (narg < 7 || narg > 8) error->all(FLERR, "Incorrect args for pair coefficients"); + if (!allocated) allocate(); + + int ilo, ihi, jlo, jhi; + utils::bounds(FLERR, arg[0], 1, atom->ntypes, ilo, ihi, error); + utils::bounds(FLERR, arg[1], 1, atom->ntypes, jlo, jhi, error); + + double biga0_one = utils::numeric(FLERR, arg[2], false, lmp); + double alpha_one = utils::numeric(FLERR, arg[3], false, lmp); + double biga1_one = utils::numeric(FLERR, arg[4], false, lmp); + double beta_one = utils::numeric(FLERR, arg[5], false, lmp); + double r0_one = utils::numeric(FLERR, arg[6], false, lmp); + double cut_one = cut_global; + if (narg == 10) cut_one = utils::numeric(FLERR, arg[7], false, lmp); + + int count = 0; + for (int i = ilo; i <= ihi; i++) { + for (int j = MAX(jlo, i); j <= jhi; j++) { + biga0[i][j] = biga0_one; + alpha[i][j] = alpha_one; + biga1[i][j] = biga1_one; + beta[i][j] = beta_one; + r0[i][j] = r0_one; + cut[i][j] = cut_one; + setflag[i][j] = 1; + count++; + } + } + + if (count == 0) error->all(FLERR, "Incorrect args for pair coefficients"); + } + +Initialization +"""""""""""""" + +The ``init_one()`` function is called during the :doc:`"init" phase +` of a simulation. This is where potential parameters +are checked for completeness, derived parameters computed (e.g. the +"offset" of the potential energy at the cutoff distance for use with the +:doc:`pair_modify shift yes ` command). If a pair style +supports generating "mixed" parameters (i.e. where both atoms of a pair +have a different atom type) using a "mixing rule" from the parameters of +the type with itself, this is the place to compute and store those mixed +values. The *born/gauss* pair style does not support mixing, so we only +check for completeness. Another purpose of the ``init_one()`` function +is to symmetrize the potential parameter arrays. The return value of +the function is the cutoff for the given pair of atom types. This +information is used by the neighbor list code to determine the largest +cutoff and then build the neighbor lists accordingly. + +.. code-block:: c++ + + /* ---------------------------------------------------------------------- + init for one type pair i,j and corresponding j,i + ------------------------------------------------------------------------- */ + + double PairBornGauss::init_one(int i, int j) + { + if (setflag[i][j] == 0) error->all(FLERR, "All pair coeffs are not set"); + + if (offset_flag) { + double dr = cut[i][j] - r0[i][j]; + offset[i][j] = + biga0[i][j] * exp(-alpha[i][j] * cut[i][j]) - biga1[i][j] * exp(-beta[i][j] * dr * dr); + } else + offset[i][j] = 0.0; + + biga0[j][i] = biga0[i][j]; + alpha[j][i] = alpha[i][j]; + biga1[j][i] = biga1[i][j]; + beta[j][i] = beta[i][j]; + r0[j][i] = r0[i][j]; + offset[j][i] = offset[i][j]; + + return cut[i][j]; + } + + +Computing forces from the neighbor list (required) +"""""""""""""""""""""""""""""""""""""""""""""""""" + +The ``compute()`` function is the "workhorse" of a pair style. This is +where we have the nested loops over all pairs of particles from the +neighbor list to compute forces and - if needed - energies and virials. + +The first part is to define some variables for later use and store +cached copies of data or pointers that we need to access frequently. Also, +this is a good place to call ``Pair::ev_init()``, which initializes +several flags derived from the `eflag` and `vflag` parameters signaling +whether the energy and virial need to be tallied and whether only globally +or also per-atom. + +.. code-block:: c++ + + /* ---------------------------------------------------------------------- */ + + void PairBornGauss::compute(int eflag, int vflag) + { + int i, j, ii, jj, inum, jnum, itype, jtype; + double xtmp, ytmp, ztmp, delx, dely, delz, evdwl, fpair; + double rsq, r, dr, aexp, bexp, factor_lj; + int *ilist, *jlist, *numneigh, **firstneigh; + + evdwl = 0.0; + ev_init(eflag, vflag); + + double **x = atom->x; + double **f = atom->f; + int *type = atom->type; + int nlocal = atom->nlocal; + double *special_lj = force->special_lj; + int newton_pair = force->newton_pair; + + inum = list->inum; + ilist = list->ilist; + numneigh = list->numneigh; + firstneigh = list->firstneigh; + +The outer loop (index *i*) is over local atoms of our sub-domain. +Typically, the value of `inum` (the number of neighbor lists) is the +same as the number of local atoms (= atoms *owned* by this sub-domain). +But when the pair style is used as a sub-style of a :doc:`hybrid pair +style ` or neighbor list entries are removed with +:doc:`neigh_modify exclude `, this number may be +smaller. The array ``list->ilist`` has the (local) indices of the atoms +for which neighbor lists have been created. Then ``list->numneigh`` is +an `inum` sized array with the number of entries of each list of +neighbors, and ``list->firstneigh`` is a list of pointers to those lists. + +For efficiency reasons, cached copies of some properties of the outer +loop atoms are also initialized. + +.. code-block:: c++ + + // loop over neighbors of my atoms + + for (ii = 0; ii < inum; ii++) { + i = ilist[ii]; + xtmp = x[i][0]; + ytmp = x[i][1]; + ztmp = x[i][2]; + itype = type[i]; + jlist = firstneigh[i]; + jnum = numneigh[i]; + +The inner loop (index *j*) processes the neighbor lists. The neighbor +list code encodes in the upper 2 bits whether a pair is a regular pair +of neighbor (= 0) or a pair of 1-2 (= 1), 1-3 (= 2), or 1-4 (= 3) +:doc:`"special" neighbor `. The ``sbmask()`` inline +function extracts those bits and converts them into a number. This +number is used to look up the corresponding scaling factor for the +non-bonded interaction from the ``force->special_lj`` array and stores +it in the `factor_lj` variable. Due to the additional bits, the value +of *j* would be out of range when accessing data from per-atom arrays, +so we apply the NEIGHMASK constant with a bit-wise and operation to mask +them out. This step *must* be done, even if a pair style does not use +special bond scaling of forces and energies to avoid segmentation faults. + +With the corrected *j* index, it is now possible to compute the distance +of the pair. For efficiency reasons, the square root is only taken +*after* the check for the cutoff (which has been stored as squared +cutoff by the ``Pair`` base class). For some pair styles, like the 12-6 +Lennard-Jones potential, computing the square root can be avoided +entirely. + +.. code-block:: c++ + + for (jj = 0; jj < jnum; jj++) { + j = jlist[jj]; + factor_lj = special_lj[sbmask(j)]; + j &= NEIGHMASK; + + delx = xtmp - x[j][0]; + dely = ytmp - x[j][1]; + delz = ztmp - x[j][2]; + rsq = delx * delx + dely * dely + delz * delz; + jtype = type[j]; + +The following block of code is the actual application of the model +potential to compute the force. Note, that *fpair* is the pair-wise +force divided by the distance, as this simplifies the projection of the +x-, y-, and z-components of the force vector by simply multiplying with +the respective distances in those directions. + +.. code-block:: c++ + + if (rsq < cutsq[itype][jtype]) { + r = sqrt(rsq); + dr = r - r0[itype][jtype]; + aexp = biga0[itype][jtype] * exp(-alpha[itype][jtype] * r); + bexp = biga1[itype][jtype] * exp(-beta[itype][jtype] * dr * dr); + fpair = alpha[itype][jtype] * aexp; + fpair -= 2.0 * beta[itype][jtype] * dr * bexp; + fpair *= factor_lj / r; + +In the next block, the force is added to the per-atom force arrays. This +pair style uses a "half" neighbor list (each pair is listed only once) +so we take advantage of the fact that :math:`\vec{F}_{ij} = +-\vec{F}_{ji}`, i.e. apply Newton's third law. The force is *always* +stored when the atom is a "local" atom. Index *i* atoms are always "local" +(i.e. *i* < nlocal); index *j* atoms may be "ghost" atoms (*j* >= nlocal). + +Depending on the settings used with the :doc:`newton command `, +those pairs are only listed once globally (newton_pair == 1), then +forces must be stored even with ghost atoms and after all forces are +computed a "reverse communication" is performed to add those ghost atom +forces to their corresponding local atoms. If the setting is disabled, +then the extra communication is skipped, since for pairs straddling +sub-domain boundaries, the forces are computed twice and only stored +with the local atoms in the domain that *owns* it. + +.. code-block:: c++ + + f[i][0] += delx * fpair; + f[i][1] += dely * fpair; + f[i][2] += delz * fpair; + if (newton_pair || j < nlocal) { + f[j][0] -= delx * fpair; + f[j][1] -= dely * fpair; + f[j][2] -= delz * fpair; + } + +The ``ev_tally()`` function tallies global or per-atom energy and +virial. For typical MD simulations, the potential energy is merely a +diagnostic and only needed on output. Similarly, the pressure may only +be computed for (infrequent) thermodynamic output. For all timesteps +where this information is not needed either, `eflag` or `evflag` are +zero and the computation and call to the tally function skipped. Note +that evdwl is initialized to zero at the beginning of the function, so +that it still is valid to access it, even if the energy is not computed +(e.g. when only the virial is needed). + +.. code-block:: c++ + + if (eflag) evdwl = factor_lj * (aexp - bexp - offset[itype][jtype]); + if (evflag) ev_tally(i, j, nlocal, newton_pair, evdwl, 0.0, fpair, delx, dely, delz); + } + } + } + +If only the global virial is needed and no energy, then calls to +``ev_tally()`` can be avoided altogether, and the global virial can be +computed more efficiently from the dot product of the total per-atom +force vector and the position vector of the corresponding atom, +:math:`\vec{F}\cdot\vec{r}`. This has to be done *after* all pair-wise +forces are computed and *before* the reverse communication to collect +data from ghost atoms, since the position has to be the position that was +used to compute the force, i.e. *not* the "local" position if that ghost +atom is a periodic copy. + +.. code-block:: c++ + + if (vflag_fdotr) virial_fdotr_compute(); + } + + +Computing force and energy for a single pair +"""""""""""""""""""""""""""""""""""""""""""" + +Certain features in LAMMPS only require computing interactions between +individual pairs of atoms and the (optional) ``single()`` function is +needed to support those features (e.g. for tabulation of force and +energy with :doc:`pair_write `). This is a repetition of +the force kernel in the ``compute()`` function, but only for a single +pair of atoms, where the (squared) distance is provided as a parameter +(so it may not even be an existing distance between two specific atoms). +The energy is returned as the return value of the function and the force +as the `fforce` reference. Note, that this is, similar to how *fpair* +is used in the ``compute()`` function, the magnitude of the force along +the vector between the two atoms *divided* by the distance. + +The ``single()`` function is optional, but it is expected to be +implemented for any true pair-wise additive potential. Many-body +potentials and special case potentials do not implement it. In a few +special cases (EAM, long-range Coulomb), the ``single()`` function +implements the pairwise additive part of the complete force interaction +and depends on either pre-computed properties (derivative of embedding +term for EAM) or post-computed non-pair-wise force contributions (KSpace +style in case of long-range Coulomb). + +The member variable `single_enable` should be set to 0 in the +constructor, if it is not implemented (its default value is 1). + +.. code-block:: c++ + + /* ---------------------------------------------------------------------- */ + + double PairBornGauss::single(int /*i*/, int /*j*/, int itype, int jtype, double rsq, + double /*factor_coul*/, double factor_lj, double &fforce) + { + double r, dr, aexp, bexp; + + r = sqrt(rsq); + dr = r - r0[itype][jtype]; + aexp = biga0[itype][jtype] * exp(-alpha[itype][jtype] * r); + bexp = biga1[itype][jtype] * exp(-beta[itype][jtype] * dr * dr); + + fforce = factor_lj * (alpha[itype][jtype] * aexp - 2.0 * dr * beta[itype][jtype] * bexp) / r; + return factor_lj * (aexp - bexp - offset[itype][jtype]); + } + + +Reading and writing of restart files +"""""""""""""""""""""""""""""""""""" + +Support for writing and reading binary restart files is provided by the +following four functions. Writing is only done by MPI processor rank 0. +The output of global (not related to atom types) settings is usually +delegated to the ``write_restart_settings()`` function. This restart +facility is commonly only used, if there are small number of per-type +parameters. For potentials that use per-element parameters or tabulated +data and read these from files, those parameters and the name of the +potential file are not written to restart files and the :doc:`pair_coeff +command ` has to re-issued when restarting. For pair styles +like "born/gauss" that do support writing to restart files, this is not +required. + +Implementing the functions to read and write binary restart files is +optional. The member variable `restartinfo` should be set to 0 in the +constructor, if they are not implemented (its default value is 1). + +.. code-block:: c++ + + /* ---------------------------------------------------------------------- + proc 0 writes to restart file + ------------------------------------------------------------------------- */ + + void PairBornGauss::write_restart(FILE *fp) + { + write_restart_settings(fp); + + int i, j; + for (i = 1; i <= atom->ntypes; i++) { + for (j = i; j <= atom->ntypes; j++) { + fwrite(&setflag[i][j], sizeof(int), 1, fp); + if (setflag[i][j]) { + fwrite(&biga0[i][j], sizeof(double), 1, fp); + fwrite(&alpha[i][j], sizeof(double), 1, fp); + fwrite(&biga1[i][j], sizeof(double), 1, fp); + fwrite(&beta[i][j], sizeof(double), 1, fp); + fwrite(&r0[i][j], sizeof(double), 1, fp); + fwrite(&cut[i][j], sizeof(double), 1, fp); + } + } + } + } + + /* ---------------------------------------------------------------------- + proc 0 writes to restart file + ------------------------------------------------------------------------- */ + + void PairBornGauss::write_restart_settings(FILE *fp) + { + fwrite(&cut_global, sizeof(double), 1, fp); + fwrite(&offset_flag, sizeof(int), 1, fp); + fwrite(&mix_flag, sizeof(int), 1, fp); + } + +Similarly, on reading, only MPI processor rank 0 has opened the restart +file and will read the data. The data is then distributed across all +parallel processes using calls to ``MPI_Bcast()``. Before reading atom +type specific data, the corresponding storage needs to be allocated. +Order and number or storage size of items read must be exactly the same +as when writing, or else the data will be read incorrectly. + +Reading uses the :cpp:func:`utils::sfread ` +utility function to detect read errors and short reads, so that LAMMPS +can abort if that happens, e.g. when the restart file is corrupted. + +.. code-block:: c++ + + /* ---------------------------------------------------------------------- + proc 0 reads from restart file, bcasts + ------------------------------------------------------------------------- */ + + void PairBornGauss::read_restart(FILE *fp) + { + read_restart_settings(fp); + + allocate(); + + int i, j; + int me = comm->me; + for (i = 1; i <= atom->ntypes; i++) { + for (j = i; j <= atom->ntypes; j++) { + if (me == 0) utils::sfread(FLERR, &setflag[i][j], sizeof(int), 1, fp, nullptr, error); + MPI_Bcast(&setflag[i][j], 1, MPI_INT, 0, world); + if (setflag[i][j]) { + if (me == 0) { + utils::sfread(FLERR, &biga0[i][j], sizeof(double), 1, fp, nullptr, error); + utils::sfread(FLERR, &alpha[i][j], sizeof(double), 1, fp, nullptr, error); + utils::sfread(FLERR, &biga1[i][j], sizeof(double), 1, fp, nullptr, error); + utils::sfread(FLERR, &beta[i][j], sizeof(double), 1, fp, nullptr, error); + utils::sfread(FLERR, &r0[i][j], sizeof(double), 1, fp, nullptr, error); + utils::sfread(FLERR, &cut[i][j], sizeof(double), 1, fp, nullptr, error); + } + MPI_Bcast(&biga0[i][j], 1, MPI_DOUBLE, 0, world); + MPI_Bcast(&alpha[i][j], 1, MPI_DOUBLE, 0, world); + MPI_Bcast(&biga1[i][j], 1, MPI_DOUBLE, 0, world); + MPI_Bcast(&beta[i][j], 1, MPI_DOUBLE, 0, world); + MPI_Bcast(&r0[i][j], 1, MPI_DOUBLE, 0, world); + MPI_Bcast(&cut[i][j], 1, MPI_DOUBLE, 0, world); + } + } + } + } + + /* ---------------------------------------------------------------------- + proc 0 reads from restart file, bcasts + ------------------------------------------------------------------------- */ + + void PairBornGauss::read_restart_settings(FILE *fp) + { + if (comm->me == 0) { + utils::sfread(FLERR, &cut_global, sizeof(double), 1, fp, nullptr, error); + utils::sfread(FLERR, &offset_flag, sizeof(int), 1, fp, nullptr, error); + utils::sfread(FLERR, &mix_flag, sizeof(int), 1, fp, nullptr, error); + } + MPI_Bcast(&cut_global, 1, MPI_DOUBLE, 0, world); + MPI_Bcast(&offset_flag, 1, MPI_INT, 0, world); + MPI_Bcast(&mix_flag, 1, MPI_INT, 0, world); + } + +Writing coefficients to data files +"""""""""""""""""""""""""""""""""" + +The ``write_data()`` and ``write_data_all()`` functions are optional and +write out the current state of the :doc:`pair_coeff +settings` as "Pair Coeffs" or "PairIJ Coeffs" sections to a +data file when using the :doc:`write_data command `. The +``write_data()`` only writes out the diagonal elements of the pair +coefficient matrix, as that is required for the format of the "Pair +Coeffs" section. It is called when the "pair" option of the +:doc:`write_data command ` is "ii" (the default). This is +suitable for force fields where *all* off-diagonal terms of the pair +coefficient matrix are generated from mixing. If explicit settings for +off-diagonal elements were made, LAMMPS will print a warning, as those +would be lost. To avoid this, the "pair ij" option of :doc:`write_data +` can be used which will trigger calling the +``write_data_all()`` function instead, which will write out all settings +of the pair coefficient matrix (regardless of whether they were +originally created from mixing or not). + +These data file output functions are only useful for true pair-wise +additive potentials, where the potential parameters can be entered +through *multiple* :doc:`pair_coeff commands `. Pair styles +that require a single "pair_coeff \* \*" command line are not compatible +with reading their parameters from data files. For pair styles like +*born/gauss* that do support writing to data files, the potential +parameters will be read from the data file, if present and +:doc:`pair_coeff commands ` may not be needed. + +The member variable ``writedata`` should be set to 1 in the constructor, +if these functions are implemented (the default value is 0). + +.. code-block:: c++ + + /* ---------------------------------------------------------------------- + proc 0 writes to data file + ------------------------------------------------------------------------- */ + + void PairBornGauss::write_data(FILE *fp) + { + for (int i = 1; i <= atom->ntypes; i++) + fprintf(fp, "%d %g %g %g %g %g\n", i, biga0[i][i], alpha[i][i], biga1[i][i], beta[i][i], + r0[i][i]); + } + + /* ---------------------------------------------------------------------- + proc 0 writes all pairs to data file + ------------------------------------------------------------------------- */ + + void PairBornGauss::write_data_all(FILE *fp) + { + for (int i = 1; i <= atom->ntypes; i++) + for (int j = i; j <= atom->ntypes; j++) + fprintf(fp, "%d %d %g %g %g %g %g %g\n", i, j, biga0[i][j], alpha[i][j], biga1[i][j], + beta[i][j], r0[i][j], cut[i][j]); + } + + +Give access to internal data +"""""""""""""""""""""""""""" + +The purpose of the ``extract()`` function is to facilitate access to +internal data of the pair style by other parts of LAMMPS. One possible +application is to use :doc:`fix adapt ` to gradually change +potential parameters during a run. Here, we implement access to the +pair coefficient matrix parameters. + +.. code-block:: c++ + + /* ---------------------------------------------------------------------- */ + + void *PairBornGauss::extract(const char *str, int &dim) + { + dim = 2; + if (strcmp(str, "biga0") == 0) return (void *) biga0; + if (strcmp(str, "biga1") == 0) return (void *) biga1; + if (strcmp(str, "r0") == 0) return (void *) r0; + return nullptr; + } + +Since the mercury potential, for which we have implemented the +born/gauss pair style, has a temperature dependent parameter "biga1", we +can automatically adapt the potential based on the Taylor-MacLaurin +expansion for "biga1" when performing a simulation with a temperature +ramp. LAMMPS commands for that application are given below: + +.. code-block:: LAMMPS + + variable tlo index 300.0 + variable thi index 600.0 + variable temp equal ramp(v_tlo,v_thi) + variable biga1 equal (-2.58717e-8*v_temp+8.40841e-5)*v_temp+1.97475e-2 + + fix 1 all nvt temp ${tlo} ${thi} 0.1 + fix 2 all adapt 1 pair born/gauss biga1 * * v_biga1 + +Case 2: a many-body potential +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Since there is a detailed description of the purpose and general layout +of a pair style in the previous case, we will focus on where the +implementation of a typical many-body potential *differs* from a +pair-wise additive potential. We will use the implementation of the +Tersoff potential as :doc:`pair_style tersoff ` as an +example. The complete implementation can be found in the files +``src/MANYBODY/pair_tersoff.cpp`` and ``src/MANYBODY/pair_tersoff.h`` of +the LAMMPS source code. + +Constructor +""""""""""" + +In the constructor, several :doc:`pair style flags ` must +be set differently for many-body potentials: + +- the potential is not pair-wise additive, so the ``single()`` function + cannot be used. This is indicated by setting the `single_enable` + member variable to 0 (default value is 1) +- many-body potentials are usually not written to :doc:`binary + restart files `. This is indicated by setting the member + variable `restartinfo` to 0 (default is 1) +- many-body potentials typically read *all* parameters from a file which + stores parameters indexed with a string (e.g. the element). For this, + only a single :doc:`pair_coeff \* \* ` command is allowed. + This requirement is set and checked for, when the member variable + `one_coeff` is set to 1 (default value is 0) +- many-body potentials can produce incorrect results if pairs of atoms + are excluded from the neighbor list, e.g. explicitly by + :doc:`neigh_modify exclude ` or implicitly through + defining bonds, angles, etc. and having a :doc:`special_bonds setting + ` that is not "special_bonds lj/coul 1.0 1.0 1.0". + LAMMPS will check for this and print a suitable warning, when the + member variable `manybody_flag` is set to 1 (default value is 0). + +.. code-block:: c++ + + PairTersoff::PairTersoff(LAMMPS *lmp) : Pair(lmp) + { + single_enable = 0; + restartinfo = 0; + one_coeff = 1; + manybody_flag = 1; + +Neighbor list request +""""""""""""""""""""" + +For computing the three-body interactions of the Tersoff potential a +"full" neighbor list (both atoms of a pair are listed in each other's +neighbor list) is required. By default a "half" neighbor list is +requested (each pair is listed only once). The request is made in +the ``init_style()`` function. A more in-depth discussion of neighbor +lists in LAMMPS and how to request them is in :ref:`this section of the +documentation ` + +Also, additional conditions must be met for some global settings which +are checked in the ``init_style()`` function. + +.. code-block:: c++ + + /* ---------------------------------------------------------------------- + init specific to this pair style + ------------------------------------------------------------------------- */ + + void PairTersoff::init_style() + { + if (atom->tag_enable == 0) + error->all(FLERR,"Pair style Tersoff requires atom IDs"); + if (force->newton_pair == 0) + error->all(FLERR,"Pair style Tersoff requires newton pair on"); + + // need a full neighbor list + + neighbor->add_request(this,NeighConst::REQ_FULL); + } + +Computing forces from the neighbor list +""""""""""""""""""""""""""""""""""""""" + +Computing forces for a many-body potential is usually more complex than +for a pair-wise additive potential and there are multiple components. +For Tersoff, there is a pair-wise additive two-body term (two nested +loops over indices *i* and *j*) and a three-body term (three nested +loops over indices *i*, *j*, and *k*). Since the neighbor list has +all neighbors up to the maximum cutoff (for the two-body term), but +the three-body interactions have a significantly shorter cutoff, +a "short neighbor list" is also constructed at the same time while computing +the two-body term and looping over the neighbor list for the first time. + +.. code-block:: c++ + + if (rsq < cutshortsq) { + neighshort[numshort++] = j; + if (numshort >= maxshort) { + maxshort += maxshort/2; + memory->grow(neighshort,maxshort,"pair:neighshort"); + } + } + +For the two-body term, only a half neighbor list would be needed, even +though we have requested a full list (for the three-body loops). +Rather than computing all interactions twice, we skip over half of +the entries. This is done in a slightly complex way to make certain +the same choice is made across all subdomains and so that there is +no load imbalance introduced. + +.. code-block:: c++ + + jtag = tag[j]; + if (itag > jtag) { + if ((itag+jtag) % 2 == 0) continue; + } else if (itag < jtag) { + if ((itag+jtag) % 2 == 1) continue; + } else { + if (x[j][2] < x[i][2]) continue; + if (x[j][2] == ztmp && x[j][1] < ytmp) continue; + if (x[j][2] == ztmp && x[j][1] == ytmp && x[j][0] < xtmp) continue; + } + +For the three-body term, there is one additional nested loop and it uses +the "short" neighbor list, accumulated previously. + +.. code-block:: c++ + + // three-body interactions + // skip immediately if I-J is not within cutoff + double fjxtmp,fjytmp,fjztmp; + + for (jj = 0; jj < numshort; jj++) { + j = neighshort[jj]; + jtype = map[type[j]]; + + [...] + + for (kk = 0; kk < numshort; kk++) { + if (jj == kk) continue; + k = neighshort[kk]; + ktype = map[type[k]]; + + [...] + } + [...] + + +Reading potential parameters +"""""""""""""""""""""""""""" + +For the Tersoff potential, the parameters are listed in a file and +associated with triples of elements. Because we have set the +``one_coeff`` flag to 1 in the constructor, there may only be a single +:doc:`pair_coeff \* \* ` line in the input for this pair +style, and as a consequence the ``coeff()`` function will only be called +once. Thus, the ``coeff()`` function has to do three tasks, each of +which is delegated to a function in the ``PairTersoff`` class: + +#. map elements to atom types. Those follow the potential file name in the + command line arguments and are processed by the ``map_element2type()`` function. +#. read and parse the potential parameter file in the ``read_file()`` function. +#. Build data structures where the original and derived parameters are + indexed by all possible triples of atom types and thus can be looked + up quickly in the loops for the force computation + +.. code-block:: c++ + + void PairTersoff::coeff(int narg, char **arg) + { + if (!allocated) allocate(); + + map_element2type(narg-3,arg+3); + + // read potential file and initialize potential parameters + + read_file(arg[2]); + setup_params(); + } + + +Case 3: a potential requiring communication +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For some models, the interactions between atoms depends on properties of +their environment which have to be computed *before* the the forces can +be computed. Since LAMMPS is designed to run in parallel using a +:doc:`domain decomposition strategy `, not all +information of the atoms may be directly available and thus +communication steps may be need to collect data from ghost atoms of +neighboring subdomains or send data to ghost atoms for application +during the pairwise computation. + +Specifically, two communication patterns are needed: a "reverse +communication" and a "forward communication". The reverse communication +collects data added to "ghost" atoms from neighboring sub-domains and +sums it to their corresponding "local" atoms. This communication is +only required and thus executed when the ``Force::newton_pair`` setting +is 1 (i.e. :doc:`newton on `, the default). The forward +communication is used to copy computed per-atom data from "local" atoms +to their corresponding "ghost" atoms in neighboring sub-domains. + +For this we will look at how the embedding term of the :doc:`embedded +atom potential EAM ` is implemented in LAMMPS. The complete +implementation of this pair style can be found in the files +``src/MANYBODY/pair_eam.cpp`` and ``src/MANYBODY/pair_eam.h`` of the +LAMMPS source code. + +Allocating additional per-atom storage +"""""""""""""""""""""""""""""""""""""" + +First suitable (local) per-atom arrays (`rho`, `fp`, `numforce`) are +allocated. These have to be large enough to include ghost atoms, are not +used outside the ``compute()`` function and are re-initialized to zero +once per timestep. + +.. code-block:: c++ + + if (atom->nmax > nmax) { + memory->destroy(rho); + memory->destroy(fp); + memory->destroy(numforce); + nmax = atom->nmax; + memory->create(rho,nmax,"pair:rho"); + memory->create(fp,nmax,"pair:fp"); + memory->create(numforce,nmax,"pair:numforce"); + } + +Reverse communication +""""""""""""""""""""" + +Then a first loop over all pairs (*i* and *j*) is performed, where data +is stored in the `rho` array representing the electron density at the site of +*i* contributed from all neighbors *j*. Since the EAM pair style uses +a half neighbor list (for efficiency reasons), a reverse communication is +needed to collect the contributions to `rho` from ghost atoms (only if +:doc:`newton on ` is set for pair styles). + +.. code-block:: c++ + + if (newton_pair) comm->reverse_comm(this); + +To support the reverse communication, two functions must be defined: +``pack_reverse_comm()`` that copies relevant data into a buffer for ghost +atoms and ``unpack_reverse_comm()`` that takes the collected data and adds +it to the `rho` array for the corresponding local atoms that match the +ghost atoms. In order to allocate sufficiently sized buffers, a flag +must be set in the pair style constructor. Since in this case a single +double precision number is communicated per atom, the `comm_reverse` +member variable is set to 1 (default is 0 = no reverse communication). + +.. code-block:: c++ + + int PairEAM::pack_reverse_comm(int n, int first, double *buf) + { + int i,m,last; + + m = 0; + last = first + n; + for (i = first; i < last; i++) buf[m++] = rho[i]; + return m; + } + + void PairEAM::unpack_reverse_comm(int n, int *list, double *buf) + { + int i,j,m; + + m = 0; + for (i = 0; i < n; i++) { + j = list[i]; + rho[j] += buf[m++]; + } + } + +Forward communication +""""""""""""""""""""" + +From the density array `rho`, the derivative of the embedding energy +`fp` is computed. The computation is only done for "local" atoms, but +for the force computation, that property also is needed on ghost atoms. +For that a forward communication is needed. + +.. code-block:: c++ + + comm->forward_comm(this); + +Similar to the reverse communication, this requires implementing a +``pack_forward_comm()`` and an ``unpack_forward_comm()`` function. +Since there is one double precision number per atom that needs to be +communicated, we must set the `comm_forward` member variable to 1 +(default is 0 = no forward communication). + +.. code-block:: c++ + + int PairEAM::pack_forward_comm(int n, int *list, double *buf, int pbc_flag, int *pbc) + { + int i,j,m; + + m = 0; + for (i = 0; i < n; i++) { + j = list[i]; + buf[m++] = fp[j]; + } + return m; + } + + void PairEAM::unpack_forward_comm(int n, int first, double *buf) + { + int i,m,last; + + m = 0; + last = first + n; + for (i = first; i < last; i++) fp[i] = buf[m++]; + } + +Case 4: potentials without a compute() function +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A small number of pair style classes do not implement a ``compute()`` +function, but instead use that of a different pair style. + +Embedded atom variants "eam/fs" and "eam/alloy" +""""""""""""""""""""""""""""""""""""""""""""""" + +The pair styles :doc:`eam/fs and eam/alloy ` share the same +model and potential function as the :doc:`eam pair style `. +They differ in the format of the potential files. Pair style :doc:`eam +` supports only potential files for single elements. For +multi-element systems, the mixed terms are computed from mixed +parameters. The *eam/fs* and *eam/alloy* pair styles, however, +**require** the use of a single potential file for all elements where +the mixed element potential is included in the tabulation. That enables +more accurate models for alloys, since the mixed terms can be adjusted +for a better representation of material properties compared to terms +created from mixing of per-element terms in the ``PairEAM`` class. + +We take a closer at the *eam/alloy* pair style. The complete +implementation is in the files ``src/MANYBODY/pair_eam_alloy.cpp`` and +``src/MANYBODY/pair_eam_alloy.h``. + +The ``PairEAMAlloy`` class is derived from ``PairEAM`` and not ``Pair`` +and overrides only a small number of functions: + +.. code-block:: c++ + + class PairEAMAlloy : virtual public PairEAM { + public: + PairEAMAlloy(class LAMMPS *); + void coeff(int, char **) override; + + protected: + void read_file(char *) override; + void file2array() override; + }; + +All other functionality is inherited from the base classes. In the +constructor we set the ``one_coeff`` flag and the ``many_body`` flag to +1 to indicate the different behavior. + +.. code-block:: c++ + + PairEAMAlloy::PairEAMAlloy(LAMMPS *lmp) : PairEAM(lmp) + { + one_coeff = 1; + manybody_flag = 1; + } + +The ``coeff()`` function (not shown here) implements the different +behavior when processing the :doc:`pair_coeff command `. +The ``read_file()`` and ``file2array()`` replace the corresponding +``PairEAM`` class functions to accommodate the different data and +file format. + +AIREBO and AIREBO-M potentials +"""""""""""""""""""""""""""""" + +The AIREBO-M potential differs from the better known AIREBO potential in +that it use a Morse potential instead of a Lennard-Jones potential for +non-bonded interactions. Since this difference is very minimal compared +to the entire potential, both potentials are implemented in the +``PairAIREBO`` class and which non-bonded potential is used is +determined by the value of the ``morseflag`` flag, which would be set to +either 0 or 1. + +.. code-block:: c++ + + class PairAIREBOMorse : public PairAIREBO { + public: + PairAIREBOMorse(class LAMMPS *); + void settings(int, char **) override; + }; + +The ``morseflag`` variable defaults to 0 and is set to 1 in the +``PairAIREBOMorse::settings()`` function which is called by the +:doc:`pair_style ` command. This function delegates +all command line processing and setting of other parameters to the +``PairAIREBO::settings()`` function of the base class. + +.. code-block:: c++ + + void PairAIREBOMorse::settings(int narg, char **arg) + { + PairAIREBO::settings(narg, arg); + + morseflag = 1; + } + +The complete implementation is in the files +``src/MANYBODY/pair_airebo.cpp``, ``src/MANYBODY/pair_airebo.h``, +``src/MANYBODY/pair_airebo_morse.cpp``, +``src/MANYBODY/pair_airebo_morse.h``. + +-------------- + +.. _Bomont2: + +**(Bomont)** Bomont, Bretonnet, J. Chem. Phys. 124, 054504 (2006) diff --git a/doc/src/Examples.rst b/doc/src/Examples.rst index de3eae8714..f2ca9a43ce 100644 --- a/doc/src/Examples.rst +++ b/doc/src/Examples.rst @@ -94,8 +94,6 @@ Lowercase directories +-------------+------------------------------------------------------------------+ | kim | use of potentials from the `OpenKIM Repository `_ | +-------------+------------------------------------------------------------------+ -| latte | examples for using fix latte for DFTB via the LATTE library | -+-------------+------------------------------------------------------------------+ | mdi | use of the MDI package and MolSSI MDI code coupling library | +-------------+------------------------------------------------------------------+ | meam | MEAM test for SiC and shear (same as shear examples) | diff --git a/doc/src/Howto.rst b/doc/src/Howto.rst index 1366ecb839..4752cf6aea 100644 --- a/doc/src/Howto.rst +++ b/doc/src/Howto.rst @@ -23,7 +23,6 @@ General howto Howto_library Howto_couple Howto_mdi - Howto_bpm Howto_broken_bonds Settings howto @@ -83,6 +82,7 @@ Packages howto Howto_spherical Howto_granular Howto_body + Howto_bpm Howto_polarizable Howto_coreshell Howto_drude diff --git a/doc/src/Howto_broken_bonds.rst b/doc/src/Howto_broken_bonds.rst index 88c8acb87f..2eb9f4bdf4 100644 --- a/doc/src/Howto_broken_bonds.rst +++ b/doc/src/Howto_broken_bonds.rst @@ -1,48 +1,56 @@ Broken Bonds ============ -Typically, bond interactions persist for the duration of a simulation in -LAMMPS. However, there are some exceptions that allow for bonds to -break, including the :doc:`quartic bond style ` and the -bond styles in the :doc:`BPM package ` which contains the -:doc:`bpm/spring ` and :doc:`bpm/rotational -` bond styles. In these cases, a bond can be broken -if it is stretched beyond a user-defined threshold. LAMMPS accomplishes -this by setting the bond type to 0, such that the bond force is no -longer computed. +Typically, molecular bond interactions persist for the duration of a +simulation in LAMMPS. However, some commands break bonds dynamically, +including the following: -Users are normally able to weight the contribution of pair forces to atoms -that are bonded using the :doc:`special_bonds command `. -When bonds break, this is not always the case. For the quartic bond style, -pair forces are always turned off between bonded particles. LAMMPS does -this via a computational sleight-of-hand. It subtracts the pairwise -interaction as part of the bond computation. When the bond breaks, the -subtraction stops. For this to work, the pairwise interaction must always -be computed by the :doc:`pair_style ` command, whether the bond -is broken or not. This means that :doc:`special_bonds ` must -be set to 1,1,1. After the bond breaks, the pairwise interaction between the -two atoms is turned on, since they are no longer bonded. +* :doc:`bond_style quartic ` +* :doc:`fix bond/break ` +* :doc:`fix bond/react ` +* :doc:`BPM package ` bond styles -In the BPM package, one can either turn off all pair interactions between -bonded particles or leave them on, overlaying pair forces on top of bond -forces. To remove pair forces, the special bond list is dynamically -updated. More details can be found on the :doc:`Howto BPM ` -page. +A bond can break if it is stretched beyond a user-defined threshold or +more generally if other criteria are met. -Bonds can also be broken by fixes which change bond topology, including -:doc:`fix bond/break ` and -:doc:`fix bond/react `. These fixes will automatically -trigger a rebuild of the neighbor list and update special bond data structures -when bonds are broken. +For the quartic bond style, when a bond is broken its bond type is set +to 0 to effectively break it and pairwise forces between the two atoms +in the broken bond are "turned on". Angles, dihedrals, etc cannot be +defined for a system when :doc:`bond_style quartic ` is +used. -Note that when bonds are dumped to a file via the :doc:`dump local ` command, bonds with type 0 are not included. The -:doc:`delete_bonds ` command can also be used to query the -status of broken bonds or permanently delete them, e.g.: +Similarly, bond styles in the BPM package are also incompatible with +angles, dihedrals, etc. and when a bond breaks its type is set to zero. +However, in the BPM package one can either turn off all pair interactions +between bonded particles or leave them on, overlaying pair forces on +top of bond forces. To remove pair forces, the special bond list is +dynamically updated. More details can be found on the :doc:`Howto BPM +` page. + +The :doc:`fix bond/break ` and :doc:`fix bond/react +` commands allow breaking of bonds within a molecular +topology with may also define angles, dihedrals, etc. These commands +update internal topology data structures to remove broken bonds, as +well as the appropriate angle, dihedral, etc interactions which +include the bond. They also trigger a rebuild of the neighbor list +when this occurs, to turn on the appropriate pairwise forces. + +Note that when bonds are dumped to a file via the :doc:`dump local +` command, bonds with type 0 are not included. + +The :doc:`delete_bonds ` command can be used to query +the status of broken bonds with type = 0 or permanently delete them, +e.g.: .. code-block:: LAMMPS delete_bonds all stats delete_bonds all bond 0 remove -The compute :doc:`nbond/atom ` can also be used -to tally the current number of bonds per atom, excluding broken bonds. +The compute :doc:`count/type ` command tallies the +current number of bonds (or angles, etc) for each bond (angle, etc) +type. It also tallies broken bonds with type = 0. + +The compute :doc:`nbond/atom ` command tallies the +current number of bonds each atom is part of, excluding broken bonds +with type = 0. diff --git a/doc/src/Howto_couple.rst b/doc/src/Howto_couple.rst index 4cd764adf1..7c8ee1e793 100644 --- a/doc/src/Howto_couple.rst +++ b/doc/src/Howto_couple.rst @@ -12,16 +12,16 @@ LAMMPS can be coupled to other codes in at least 4 different ways. Each has advantages and disadvantages, which you will have to think about in the context of your application. -1. Define a new :doc:`fix ` command that calls the other code. In - this scenario, LAMMPS is the driver code. During timestepping, the - fix is invoked, and can make library calls to the other code, which - has been linked to LAMMPS as a library. This is the way the - :ref:`LATTE ` package, which performs density-functional - tight-binding calculations using the `LATTE software - `_ to compute forces, is interfaced to - LAMMPS. See the :doc:`fix latte ` command for more +1. Define a new :doc:`fix ` or :doc:`compute ` command + that calls the other code. In this scenario, LAMMPS is the driver + code. During timestepping, the fix or compute is invoked, and can + make library calls to the other code, which has been linked to LAMMPS + as a library. This is the way the :ref:`VORONOI ` + package, which computes Voronoi tesselations using the `Voro++ + library `_, is interfaced to LAMMPS. See + the :doc:`compute voronoi ` command for more details. Also see the :doc:`Modify ` pages for information - on how to add a new fix to LAMMPS. + on how to add a new fix or compute to LAMMPS. .. spacer diff --git a/doc/src/Howto_mdi.rst b/doc/src/Howto_mdi.rst index 7567462397..51cf99b237 100644 --- a/doc/src/Howto_mdi.rst +++ b/doc/src/Howto_mdi.rst @@ -76,9 +76,16 @@ energy minimizations, or to evaluate the quantum energy and forces for a series of independent systems. The ``examples/mdi`` directory has example input scripts for all of these use cases. +The package also has a :doc:`fix mdi/qmmm ` command in +which LAMMPS operates as an MDI driver in conjunction with a quantum +mechanics code as an MDI engine to perform QM/MM simulations. The +LAMMPS input script partitions the system into QM and MM (molecular +mechanics) atoms. As described below the ``examples/QUANTUM`` directory +has examples for coupling to 3 different quantum codes in this manner. + ---------- -The examples/mdi directory contains Python scripts and LAMMPS input +The ``examples/mdi`` directory contains Python scripts and LAMMPS input script which use LAMMPS as either an MDI driver or engine, or both. Currently, 5 example use cases are provided: @@ -119,45 +126,26 @@ as a plugin library. ------------- -Currently, there are at least two quantum DFT codes which have direct MDI +As of March 2023, these are quantum codes with MDI support provided via +Python wrapper scripts included in the LAMMPS distribution. These can +be used with the fix mdi/qm and fix mdi/qmmm commands to perform QM +calculations of an entire system (e.g. AIMD) or QM/MM simulations. See +the ``examples/QUANTUM`` sub-directories for more details: + +* LATTE - AIMD only +* PySCF - QM/MM only +* NWChem - AIMD or QM/MM + +There are also at least two quantum codes which have direct MDI support, `Quantum ESPRESSO (QE) `_ -and `INQ `_. There are also several -QM codes which have indirect support through QCEngine or i-PI. The -former means they require a wrapper program (QCEngine) with MDI support -which writes/read files to pass data to the quantum code itself. The -list of QCEngine-supported and i-PI-supported quantum codes is on the -`MDI webpage +and `INQ `_. There are also +several QM codes which have indirect support through QCEngine or i-PI. +The former means they require a wrapper program (QCEngine) with MDI +support which writes/read files to pass data to the quantum code +itself. The list of QCEngine-supported and i-PI-supported quantum +codes is on the `MDI webpage `_. -Here is how to build QE as a stand-alone ``pw.x`` file which can be -used in stand-alone mode: - -.. code-block:: bash - - git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git /q-e - build the executable pw.x, following the `QE build guide `_ - -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 ``/q-e/MDI/src``: - -.. code-block:: bash - - git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git /q-e - cd /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 -plugin mode, which results in a ``libinqmdi.so`` file in -``/inq/build/examples``: - -.. code-block:: bash - - git clone --branch mdi --recurse-submodules https://gitlab.com/taylor-a-barnes/inq.git /inq - cd /inq - mkdir -p build - cd build - ../configure --prefix=/install - make -j 4 - make install +These direct- and indirect-support codes should be usable for full +system calculations (e.g. AIMD). Whether they support QM/MM models +depends on the individual QM code. diff --git a/doc/src/Howto_tip4p.rst b/doc/src/Howto_tip4p.rst index 0a263499cc..7775d43e76 100644 --- a/doc/src/Howto_tip4p.rst +++ b/doc/src/Howto_tip4p.rst @@ -101,7 +101,7 @@ not as part of the pair coefficients. - 0.52422 * - LJ :math:`\epsilon` of OO (kcal/mole) - 0.1550 - - 0.1577 + - 0.21084 - 0.1852 - 0.16275 * - LJ :math:`\sigma` of OO (:math:`\AA`) diff --git a/doc/src/Install_conda.rst b/doc/src/Install_conda.rst index 5140e4e17d..a1a7213609 100644 --- a/doc/src/Install_conda.rst +++ b/doc/src/Install_conda.rst @@ -1,13 +1,13 @@ -Download an executable for Linux or Mac via Conda -------------------------------------------------- +Download an executable for Linux or macOS via Conda +--------------------------------------------------- Pre-compiled LAMMPS binaries are available for macOS and Linux via the `Conda `_ package management system. -First, one must set up the Conda package manager on your system. Follow the -instructions to install `Miniconda `_, then create a conda -environment (named `my-lammps-env` or whatever you prefer) for your LAMMPS -install: +First, one must set up the Conda package manager on your system. Follow +the instructions to install `Miniconda `_, then +create a conda environment (named `my-lammps-env` or whatever you +prefer) for your LAMMPS install: .. code-block:: bash diff --git a/doc/src/Install_mac.rst b/doc/src/Install_mac.rst index 39146c5afc..880ddca7a2 100644 --- a/doc/src/Install_mac.rst +++ b/doc/src/Install_mac.rst @@ -1,12 +1,12 @@ -Download an executable for Mac ------------------------------- +Download an executable for macOS +-------------------------------- -LAMMPS can be downloaded, built, and configured for OS X on a Mac with -`Homebrew `_. (Alternatively, see the installation -instructions for :doc:`downloading an executable via Conda -`.) The following LAMMPS packages are unavailable at -this time because of additional requirements not yet met: GPU, KOKKOS, -LATTE, MSCG, MPIIO, POEMS, VORONOI. +LAMMPS can be downloaded, built, and configured for macOS with `Homebrew +`_. (Alternatively, see the installation instructions for +:doc:`downloading an executable via Conda `.) The +following LAMMPS packages are unavailable at this time because of +additional requirements not yet met: GPU, KOKKOS, MSCG, MPIIO, POEMS, +VORONOI. After installing Homebrew, you can install LAMMPS on your system with the following commands: @@ -15,8 +15,9 @@ the following commands: 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. +This will install the executables "lammps_serial" and "lammps_mpi", as +well as the LAMMPS "doc", "potentials", "tools", "bench", and "examples" +directories. Once LAMMPS is installed, you can test the installation with the Lennard-Jones benchmark file: diff --git a/doc/src/Install_tarball.rst b/doc/src/Install_tarball.rst index 64d73ee356..90dd27fa67 100644 --- a/doc/src/Install_tarball.rst +++ b/doc/src/Install_tarball.rst @@ -2,7 +2,7 @@ Download source and documentation as a tarball ---------------------------------------------- You can download a current LAMMPS tarball from the `download page `_ -of the `LAMMPS website `_. +of the `LAMMPS website `_ or from GitHub (see below). .. _download: https://www.lammps.org/download.html .. _bug: https://www.lammps.org/bug.html @@ -17,21 +17,21 @@ tarball occasionally updated. Feature releases occur every 4 to 8 weeks. The new contents in all feature releases are listed on the `bug and feature page `_ of the LAMMPS homepage. -Both tarballs include LAMMPS documentation (HTML and PDF files) -corresponding to that version. - Tarballs of older LAMMPS versions can also be downloaded from `this page `_. -Once you have a tarball, unzip and untar it with the following +Tarballs downloaded from the LAMMPS homepage include the pre-translated +LAMMPS documentation (HTML and PDF files) corresponding to that version. + +Once you have a tarball, uncompress and untar it with the following command: .. code-block:: bash tar -xzvf lammps*.tar.gz -This will create a LAMMPS directory with the version date -in its name, e.g. lammps-23Jun18. +This will create a LAMMPS directory with the version date in its name, +e.g. lammps-28Mar23. ---------- @@ -45,7 +45,8 @@ with the following command, to create a lammps- directory: unzip lammps*.zip This version corresponds to the selected LAMMPS feature or stable -release. +release (as indicated by the matching git tag) and will only contain the +source code and no pre-built documentation. .. _git: https://github.com/lammps/lammps/releases diff --git a/doc/src/Intro_features.rst b/doc/src/Intro_features.rst index d8fb2269e5..f7b4dd319b 100644 --- a/doc/src/Intro_features.rst +++ b/doc/src/Intro_features.rst @@ -88,7 +88,7 @@ commands) * charge equilibration (QEq via dynamic, point, shielded, Slater methods) * coarse-grained potentials: DPD, GayBerne, REsquared, colloidal, DLVO, oxDNA / oxRNA, SPICA * mesoscopic potentials: granular, Peridynamics, SPH, mesoscopic tubular potential (MESONT) -* semi-empirical potentials: multi-ion generalized pseudopotential theory (MGPT), second moment tight binding + QEq (SMTB-Q), density functional tight-binding (LATTE) +* semi-empirical potentials: multi-ion generalized pseudopotential theory (MGPT), second moment tight binding + QEq (SMTB-Q) * electron force field (eFF, AWPMD) * bond potentials: harmonic, FENE, Morse, nonlinear, Class II (COMPASS), quartic (breakable), tabulated, scripted * angle potentials: harmonic, CHARMM, cosine, cosine/squared, cosine/periodic, Class II (COMPASS), tabulated, scripted diff --git a/doc/src/Manual.rst b/doc/src/Manual.rst index 0af27e5f71..eb630c4fe2 100644 --- a/doc/src/Manual.rst +++ b/doc/src/Manual.rst @@ -136,10 +136,21 @@ Indices and tables :class: note The HTML version of the manual makes use of advanced features present - in "modern" web browsers. This can lead to incompatibilities with older - web browsers (released more than 4 years ago) and specific vendor browsers - (e.g. Internet Explorer on Windows; Microsoft Edge works well though) + in "modern" web browsers. This leads to incompatibilities with older + web browsers and specific vendor browsers (e.g. Internet Explorer on Windows) where parts of the pages are not rendered as expected (e.g. the layout is broken or mathematical expressions not typeset). In that case we recommend to install/use a different/newer web browser or use the `PDF version of the manual `_. + + The following web browser versions have been verified to work as + expected on Linux, macOS, and Windows where available: + + - Safari version 11.1 and later + - Firefox version 54 and later + - Chrome version 54 and later + - Opera version 41 and later + - Edge version 80 and later + + Also Android version 7.1 and later and iOS version 11 and later have + been verified to render this website as expected. diff --git a/doc/src/Modify.rst b/doc/src/Modify.rst index 8ea7850fc5..0d7d4d6b97 100644 --- a/doc/src/Modify.rst +++ b/doc/src/Modify.rst @@ -1,23 +1,30 @@ Modifying & extending LAMMPS **************************** -LAMMPS is designed in a modular fashion and to be easy to modify or -extend with new functionality. In fact, about 95% of its source code -are optional. The following pages give basic instructions on what -is required when adding new styles of different kinds to LAMMPS. +LAMMPS has a modular design, so that it is easy to modify or extend with +new functionality. In fact, about 95% of its source code is optional. +The following pages give basic instructions on adding new features to +LAMMPS. More in-depth explanations and documentation of individual +functions and classes are given in :doc:`Developer`. If you add a new feature to LAMMPS and think it will be of general interest to other users, we encourage you to submit it for inclusion in -LAMMPS as a pull request on our `GitHub site -`_, after reading about :doc:`how to -prepare your code for submission ` and :doc:`the -style requirements and recommendations `. +LAMMPS. This process is explained in the following three pages: + +* :doc:`how to prepare and submit your code ` +* :doc:`requirements for submissions ` +* :doc:`style guidelines ` + +A summary description of various types of styles in LAMMPS follows. +A discussion of implementing specific styles from scratch is given +in :doc:`writing new styles `. .. toctree:: :maxdepth: 1 Modify_overview Modify_contribute + Modify_requirements Modify_style .. toctree:: diff --git a/doc/src/Modify_contribute.rst b/doc/src/Modify_contribute.rst index d36e68b093..8992e63c00 100644 --- a/doc/src/Modify_contribute.rst +++ b/doc/src/Modify_contribute.rst @@ -2,74 +2,59 @@ Submitting new features for inclusion in LAMMPS =============================================== We encourage LAMMPS users to submit new features they wrote for LAMMPS -to be included into the LAMMPS distribution and thus become easily -accessible to all LAMMPS users. The LAMMPS source code is managed with -git and public development is hosted on `GitHub -`_. You can monitor the repository to -be notified of releases, follow the ongoing development, and comment on -topics of interest to you. +to be included in the LAMMPS distribution and thus become easily +accessible to all LAMMPS users. The LAMMPS source code is managed +with git and public development is hosted on `GitHub +`_. You can monitor the repository +to be notified of releases, follow the ongoing development, and +comment on topics of interest to you. + +This section contains general information regarding the preparation +and submission of new features to LAMMPS. If you are new to +development in LAMMPS, we recommend you read one of the tutorials on +developing a new :doc:`pair style ` or :doc:`fix +style ` which provide a friendly introduction to +what LAMMPS development entails and common vocabulary used on this +section. + Communication with the LAMMPS developers ---------------------------------------- -For any larger modifications or programming project, you are encouraged -to contact the LAMMPS developers ahead of time in order to discuss -implementation strategies and coding guidelines. That will make it -easier to integrate your contribution and results in less work for -everybody involved. You are also encouraged to search through the list -of `open issues on GitHub `_ -and submit a new issue for a planned feature, so you would not duplicate -the work of others (and possibly get scooped by them) or have your work -duplicated by others. +For any larger modifications or programming project, you are +encouraged to contact the LAMMPS developers ahead of time to discuss +implementation strategies. That will make it easier to integrate your +contribution and typically results in less work for everyone involved. +You are also encouraged to search through the list of `open issues on +GitHub `_ and submit a new +issue for a planned feature, to avoid duplicating work (and possibly +being scooped). -For informal communication with the LAMMPS developers you may ask to -join the `LAMMPS developers on Slack `_. This -slack work space is by invitation only. Thus for access, please send an -e-mail to ``slack@lammps.org`` explaining what part of LAMMPS you are -working on. Only discussions related to LAMMPS development are -tolerated in that work space, so this is **NOT** for people that look +For informal communication with the LAMMPS developers, you may ask to +join the `LAMMPS developers on Slack `_. +This slack work space is by invitation only. For access, please send +an e-mail to ``slack@lammps.org`` explaining what part of LAMMPS you +are working on. Only discussions related to LAMMPS development are +tolerated in that work space, so this is **NOT** for people looking for help with compiling, installing, or using LAMMPS. Please post a message to the `LAMMPS forum `_ for those purposes. -Packages versus individual files --------------------------------- - -The remainder of this chapter describes how to add new "style" files of -various kinds to LAMMPS. Packages are simply collections of one or more -such new class files which are invoked as a new style within a LAMMPS -input script. In some cases also collections of supporting functions or -classes are included as separate files in a package, especially when -they can be shared between multiple styles. If designed correctly, these -additions typically do not require any changes to the core code of -LAMMPS; they are simply add-on files that are compiled with the rest of -LAMMPS. To make those styles work, you may need some trivial changes to -the core code; an example of a trivial change is making a parent-class -method "virtual" when you derive a new child class from it. - -If you think your new feature or package requires some non-trivial -changes in core LAMMPS files, you should communicate with the LAMMPS -developers `on Slack `_, `on GitHub -`_, or `via email -`_, since we may have -recommendations about what changes to do where, or may not want to -include certain changes for some reason and thus you would need to look -for alternatives. Time and effort required ------------------------ -How quickly your contribution will be integrated can vary a lot. It -depends largely on how much effort it will cause the LAMMPS developers -to integrate and test it, how many and what kind of changes to the core -code are required, how quickly you can address them and of how much -interest it is to the larger LAMMPS community. Please see the section -on :doc:`LAMMPS programming style and requirements ` for -instructions, recommendations, and formal requirements. A small, -modular, well written contribution may be integrated within hours, but a -complex change that will require a redesign of some core functionality -in LAMMPS for a clean integration can take many months until it is -considered ready for inclusion (though this is rare). +How quickly your contribution will be integrated can vary widely. It +depends largely on how much effort is required by the LAMMPS +developers to integrate and test it, if any and what kind of changes +to the core code are required, how quickly you can address them, and +how much interest the contribution is to the larger LAMMPS +community. This process can be streamlined by following the +:doc:`requirements ` and :doc:`style +guidelines`. A small, modular, well written +contribution may be integrated within hours, but a complex change that +requires a re-design of a core functionality in LAMMPS can take months +before inclusion (though this is rare). Submission procedure @@ -78,36 +63,24 @@ Submission procedure All changes to LAMMPS (including those from LAMMPS developers) are integrated via pull requests on GitHub and cannot be merged without passing the automated testing and an approving review by a LAMMPS core -developer. Thus before submitting your contribution, you should first -make certain, that your added or modified code compiles and works -correctly with the latest development version of LAMMPS and contains all -bug fixes from it. +developer. Before submitting your contribution, you should therefore +first ensure that your added or modified code compiles and works +correctly with the latest development version of LAMMPS and contains +all bug fixes from it. -Once you have prepared everything, see the :doc:`LAMMPS GitHub Tutorial -` page for instructions on how to submit your changes or -new files through a GitHub pull request yourself. If you are unable or -unwilling to submit via GitHub yourself, you may also submit patch files -or full files to the LAMMPS developers and ask them to submit a pull -request on GitHub on your behalf. Then create a gzipped tar file of -all changed or added files or a corresponding patch file using -'diff -u' or 'diff -c' format and compress it with gzip. Please only -use gzip compression, as this works well and is available on all platforms. +Once you have prepared everything, see the :doc:`LAMMPS GitHub +Tutorial ` page for instructions on how to submit your +changes or new files through a GitHub pull request. If you are unable +or unwilling to submit via GitHub yourself, you may also send patch +files or full files to the `LAMMPS developers +`_ and ask them to submit a pull +request on GitHub on your behalf. If this is the case, create a +gzipped tar file of all new or changed files or a corresponding patch +file using 'diff -u' or 'diff -c' format and compress it with gzip. +Please only use gzip compression, as this works well and is available +on all platforms. This mode of submission may delay the integration +as it depends more on the LAMMPS developers. -If the new features/files are broadly useful we may add them as core -files to LAMMPS or as part of a :doc:`package `. All -packages are listed and described on the :doc:`Packages details -` doc page. - -Licensing ---------- - -Note that by providing us files to release, you agree to make them -open-source, i.e. we can release them under the terms of the GPL -(version 2) with the rest of LAMMPS. And similarly as part of a LGPL -(version 2.1) distribution of LAMMPS that we make available to -developers on request only and with files that are not authorized for -that kind of distribution removed (e.g. interface to FFTW). See the -:doc:`LAMMPS license ` page for details. External contributions ---------------------- @@ -115,11 +88,42 @@ External contributions If you prefer to do so, you can also develop and support your add-on feature **without** having it included in the LAMMPS distribution, for example as a download from a website of your own. See the `External -LAMMPS packages and tools `_ page -of the LAMMPS website for examples of groups that do this. We are happy -to advertise your package and website from that page. Simply email the -`developers `_ with info about your -package and we will post it there. We recommend to name external -packages USER-\ so they can be easily distinguished from bundled -packages that do not have the USER- prefix. +LAMMPS packages and tools `_ +page of the LAMMPS website for examples of groups that do this. We +are happy to advertise your package and website from that page. +Simply email the `developers `_ +with info about your package, and we will post it there. We recommend +naming external packages USER-\ so they can be easily +distinguished from packages in the LAMMPS distribution which do not +have the USER- prefix. + +Location of files: individual files and packages +------------------------------------------------ + +We rarely accept new styles in the core src folder. Thus, please +review the list of :doc:`available Packages ` to see +if your contribution should be added to one of them. It should fit +into the general purpose of that package. If it does not fit well, it +may be added to one of the EXTRA- packages or the MISC package. + +However, if your project includes many related features that are not +covered by one of the existing packages or is dependent on a library +(bundled or external), it is best to create a new package with its own +directory (with a name like FOO). In addition to your new files, the +directory should contain a README text file containing your name and +contact information and a brief description of what your new package +does. + + +Changes to core LAMMPS files +-------------------------------- + +If designed correctly, most additions do not require any changes to +the core code of LAMMPS; they are simply add-on files that are +compiled with the rest of LAMMPS. To make those styles work, you may +need some trivial changes to the core code. An example of a trivial +change is making a parent-class method "virtual" when you derive a new +child class from it. If your features involve more substantive +changes to the core LAMMPS files, it is particularly encouraged that +you communicate with the LAMMPS developers early in development. diff --git a/doc/src/Modify_gran_sub_mod.rst b/doc/src/Modify_gran_sub_mod.rst index e1d559e6bf..40692952ed 100644 --- a/doc/src/Modify_gran_sub_mod.rst +++ b/doc/src/Modify_gran_sub_mod.rst @@ -25,7 +25,7 @@ specific implementation. For instance, from the GranSubModNormal class the GranSubModNormalHooke, GranSubModNormalHertz, and GranSubModNormalJKR classes are derived which calculate Hookean, Hertzian, or JKR normal forces, respectively. This modular structure simplifies the addition of new granular -contact models as as one only needs to create a new GranSubMod class without +contact models as one only needs to create a new GranSubMod class without having to modify the more complex PairGranular, FixGranWall, and GranularModel classes. Most GranSubMod methods are also already defined by the parent classes so new contact models typically only require edits to a few relevant methods @@ -80,8 +80,8 @@ There are also several type-specific methods - Optional method to test when particles are in contact. By default, this is when particles overlap. * - ``GranSubModNormal->pulloff_distance()`` - Optional method to return the distance at which particles stop interacting. By default, this is when particles no longer overlap. - * - ``GranSubModNormal->calculate_area()`` - - Optional method to return the surface area of the contact. By default, this returns the geometric cross section. + * - ``GranSubModNormal->calculate_radius()`` + - Optional method to return the radius of the contact. By default, this returns the radius of the geometric cross section. * - ``GranSubModNormal->set_fncrit()`` - Optional method that defines the critical force to break the contact used by some tangential, rolling, and twisting sub-models. By default, this is the current total normal force including damping. * - ``GranSubModNormal->calculate_forces()`` @@ -105,9 +105,7 @@ set of files ``gran_sub_mod_custom.h``: #ifdef GranSubMod_CLASS // clang-format off - GranSubModStyle(hooke/piecewise, - GranSubModNormalHookePiecewise, - NORMAL); + GranSubModStyle(hooke/piecewise,GranSubModNormalHookePiecewise,NORMAL); // clang-format on #else @@ -119,15 +117,14 @@ set of files ``gran_sub_mod_custom.h``: namespace LAMMPS_NS { namespace Granular_NS { - - class GranSubModNormalHookePiecewise : public GranSubModNormal { - public: - GranSubModNormalHookePiecewise(class GranularModel *, class LAMMPS *); - void coeffs_to_local() override; - double calculate_forces(); - protected: - double k1, k2, delta_switch; - }; + class GranSubModNormalHookePiecewise : public GranSubModNormal { + public: + GranSubModNormalHookePiecewise(class GranularModel *, class LAMMPS *); + void coeffs_to_local() override; + double calculate_forces() override; + protected: + double k1, k2, delta_switch; + }; } // namespace Granular_NS } // namespace LAMMPS_NS @@ -147,7 +144,8 @@ and ``gran_sub_mod_custom.cpp`` using namespace LAMMPS_NS; using namespace Granular_NS; - GranSubModNormalHookePiecewise::GranSubModNormalHookePiecewise(GranularModel *gm, LAMMPS *lmp) : GranSubModNormal(gm, lmp) + GranSubModNormalHookePiecewise::GranSubModNormalHookePiecewise(GranularModel *gm, LAMMPS *lmp) : + GranSubModNormal(gm, lmp) { num_coeffs = 4; } diff --git a/doc/src/Modify_overview.rst b/doc/src/Modify_overview.rst index ed7ff1a8ac..ab1fa43ed4 100644 --- a/doc/src/Modify_overview.rst +++ b/doc/src/Modify_overview.rst @@ -1,42 +1,44 @@ Overview ======== -The best way to add a new feature to LAMMPS is to find a similar feature -and look at the corresponding source and header files to figure out what -it does. You will need some knowledge of C++ to be able to understand -the high-level structure of LAMMPS and its class organization, but -functions (class methods) that do actual computations are mostly written -in C-style code and operate on simple C-style data structures (vectors -and arrays). A high-level overview of the programming style choices in -LAMMPS is :doc:`given elsewhere `. +The best way to add a new feature to LAMMPS is to find a similar +feature and look at the corresponding source and header files to +figure out what it does. You will need some knowledge of C++ to +understand the high-level structure of LAMMPS and its class +organization. Functions (class methods) that do actual computations +are mostly written in C-style code and operate on simple C-style data +structures (vectors and arrays). A high-level overview of the +programming style choices in LAMMPS is :doc:`given elsewhere +`. Most of the new features described on the :doc:`Modify ` doc -page require you to write a new C++ derived class (except for exceptions -described below, where you can make small edits to existing files). -Creating a new class requires 2 files, a source code file (\*.cpp) and a -header file (\*.h). The derived class must provide certain methods to -work as a new option. Depending on how different your new feature is -compared to existing features, you can either derive from the base class -itself, or from a derived class that already exists. Enabling LAMMPS to -invoke the new class is as simple as putting the two source files in the -src directory and re-building LAMMPS. +page require you to write a new C++ derived class (except for +exceptions described below, where you can make small edits to existing +files). Creating a new class requires 2 files, a source code file +(\*.cpp) and a header file (\*.h). The derived class must provide +certain methods to work as a new option. Depending on how different +your new feature is compared to existing features, you can either +derive from the base class itself, or from a derived class that +already exists. Enabling LAMMPS to invoke the new class is as simple +as putting the two source files in the src directory and re-building +LAMMPS. The advantage of C++ and its object-orientation is that all the code and variables needed to define the new feature are in the 2 files you -write, and thus should not make the rest of LAMMPS more complex or -cause side-effect bugs. +write. Thus, it should not make the rest of LAMMPS more complex or +cause bugs through unwanted side effects. -Here is a concrete example. Suppose you write 2 files pair_foo.cpp -and pair_foo.h that define a new class PairFoo that computes pairwise -potentials described in the classic 1997 :ref:`paper ` by Foo, et al. -If you wish to invoke those potentials in a LAMMPS input script with a -command like +Here is a concrete example. Suppose you write 2 files +``pair_foo.cpp`` and ``pair_foo.h`` that define a new class +``PairFoo`` which computes pairwise potentials described in the +classic 1997 :ref:`paper ` by Foo, *et al.* If you wish to invoke +those potentials in a LAMMPS input script with a command like: .. code-block:: LAMMPS pair_style foo 0.1 3.5 -then your pair_foo.h file should be structured as follows: +then your ``pair_foo.h`` file should be structured as follows: .. code-block:: c++ @@ -51,28 +53,27 @@ then your pair_foo.h file should be structured as follows: #endif where "foo" is the style keyword in the pair_style command, and -PairFoo is the class name defined in your pair_foo.cpp and pair_foo.h -files. +``PairFoo`` is the class name defined in your ``pair_foo.cpp`` and +``pair_foo.h`` files. When you re-build LAMMPS, your new pairwise potential becomes part of the executable and can be invoked with a pair_style command like the example above. Arguments like 0.1 and 3.5 can be defined and processed by your new class. -As illustrated by this example pair style, many kinds of options are -referred to in the LAMMPS documentation as the "style" of a particular -command. +As illustrated by this example, many features referred to in the +LAMMPS documentation are called a "style" of a particular command. The :doc:`Modify page ` lists all the common styles in LAMMPS, -and discusses the header file for the base class that these styles are -derived from. Public variables in that file are ones used and set by -the derived classes which are also used by the base class. Sometimes -they are also used by the rest of LAMMPS. Pure functions, which means -functions declared as virtual in the base class header file which are -also set to 0, are functions you **must** implement in your new derived -class to give it the functionality LAMMPS expects. Virtual functions -that are not set to 0 are functions you may override or not. Those -are usually defined with an empty function body. +and discusses the header file for the base class that these styles +derive from. Public variables in that file can be used and set by the +derived classes, and may also be used by the base class. Sometimes +they are also accessed by the rest of LAMMPS. Pure functions, which +means functions declared as virtual in the base class header file and +which are also set to 0, are functions you **must** implement in your +new derived class to give it the functionality LAMMPS expects. Virtual +functions that are not set to 0 are functions you may override or not. +Those are usually defined with an empty function body. Additionally, new output options can be added directly to the thermo.cpp, dump_custom.cpp, and variable.cpp files. These are also @@ -85,9 +86,9 @@ functionality: post-processing step. Many computations are more easily and more quickly done that way. * Do not try to do anything within the timestepping of a run that is not - parallel. For example do not accumulate a bunch of data on a single - processor and analyze it. You run the risk of seriously degrading - the parallel efficiency this way. + parallel. For example, do not accumulate a bunch of data on a single + processor and analyze it. That would run the risk of seriously degrading + the parallel efficiency. * If your new feature reads arguments or writes output, make sure you follow the unit conventions discussed by the :doc:`units ` command. diff --git a/doc/src/Modify_pair.rst b/doc/src/Modify_pair.rst index 38f5ade567..7d7d96609a 100644 --- a/doc/src/Modify_pair.rst +++ b/doc/src/Modify_pair.rst @@ -2,11 +2,11 @@ Pair styles =========== 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 +the ``Pair`` class. In LAMMPS, pairwise force calculations 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 ` where the accelerated style @@ -15,10 +15,13 @@ names differ from their base classes by an appended suffix. 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 ` and :doc:`compute -group/group `. +group/group `. :doc:`Developer_write_pair` contains +a detailed discussion of writing new pair styles from scratch, and how +simple and more complex pair styles can be implemented with examples +from existing pair styles. 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. +*must* be or *may* be overridden in a derived class for a new pair style. +---------------------------------+---------------------------------------------------------------------+ | Required | "pure" methods that *must* be overridden in a derived class | diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst new file mode 100644 index 0000000000..0637c860ab --- /dev/null +++ b/doc/src/Modify_requirements.rst @@ -0,0 +1,384 @@ +Requirements for contributions to LAMMPS +======================================== + +The following is a summary of the current requirements and +recommendations for including contributed source code or documentation +into the LAMMPS software distribution. + +Motivation +---------- + +The LAMMPS developers are committed to provide a software package that +is versatile, reliable, high-quality, efficient, portable, and easy to +maintain and modify. Achieving all of these goals is challenging +since a large part of LAMMPS consists of contributed code from many +different authors who may not be professionally trained programmers or +familiar with the idiosyncrasies of maintaining a large software +package. In addition, changes that interfere with the parallel +efficiency of the core code must be avoided. As LAMMPS continues to +grow and more features and functionality are added, it is necessary to +follow established guidelines when accepting new contributions while +also working at the same time to improve the existing code. + +The following requirements and recommendations are provided as a +guide. They indicate which individual requirements are strict, and +which represent a preference and thus are negotiable or optional. +Please feel free to contact the LAMMPS core developers in case you +need additional explanations or clarifications, or you need assistance +in implementing the (strict) requirements for your contributions. +Requirements include: + +* :ref:`Licensing requirements ` (strict) +* :ref:`Integration testing ` (strict) +* :ref:`Documentation ` (strict) +* :ref:`Programming language standards ` (strict) +* :ref:`Build system ` (strict) +* :ref:`Command or style names ` (strict) +* :ref:`Programming style requirements ` (varied) +* :ref:`Examples ` (preferred) +* :ref:`Error or warning messages and explanations ` (preferred) +* :ref:`Citation reminder ` (optional) +* :ref:`Testing ` (optional) + +.. _ReqLicense: + +Licensing requirements (strict) +------------------------------- + +Contributing authors agree when submitting a pull request that their +contributions can be distributed under the LAMMPS license conditions. +This is the GNU public license in version 2 (not 3 or later) for the +publicly distributed versions, e.g. on the LAMMPS homepage or on +GitHub. We also have a version of LAMMPS under LGPL 2.1 terms which +is available on request; this will usually be the latest available or +a previous stable version with a few LGPL 2.1 incompatible files +removed. More details are found on the :doc:`LAMMPS open-source +license page `. + +Your new source files should have the LAMMPS copyright and GPL notice, +followed by your name and email address at the top, like other +user-contributed LAMMPS source files. + +Contributions may be under a different license as long as that license +does not conflict with the aforementioned terms. Contributions that +use code with a conflicting license can be split into two parts: + +1. the core parts (i.e. parts that must be in the `src` tree) that are + licensed under compatible terms and bundled with the LAMMPS sources +2. an external library that must be downloaded and compiled (either + separately or as part of the LAMMPS compilation) + +Please note, that this split licensing mode may complicate including +the contribution in binary packages. + +.. _ReqIntegrationTesting: + +Integration testing (strict) +---------------------------- + +Where possible we use available continuous integration tools to search +for common programming mistakes, portability limitations, incompatible +formatting, and undesired side effects. Contributed code must pass the +automated tests on GitHub before it can be merged with the LAMMPS +distribution. These tests compile LAMMPS in a variety of environments +and settings and run the bundled unit tests. At the discretion of the +LAMMPS developer managing the pull request, additional tests may be +activated that test for "side effects" on running a collection of +input decks and create consistent results. The translation of the +documentation to HTML and PDF is also tested. + +This means that contributed source code **must** compile with the most +current version of LAMMPS with ``-DLAMMPS_BIGBIG`` in addition to the +default setting of ``-DLAMMPS_SMALLBIG``. The code needs to work +correctly in both cases, and also in serial and parallel using MPI. + +Some "disruptive" changes may break tests and require updates to the +testing tools or scripts or tests themselves. This is rare. If in +doubt, contact the LAMMPS developer that is assigned to the pull +request. + +.. _ReqDocumentation: + +Documentation (strict) +---------------------- + +Contributions that add new styles or commands or augment existing ones +must include the corresponding new or modified documentation in +`ReStructuredText format `_ (.rst files in the ``doc/src/`` +folder). The documentation should be written in American English and the +.rst file must only use ASCII characters, so it can be cleanly +translated to PDF files (via `sphinx `_ and +PDFLaTeX). Special characters may be included via embedded math +expression typeset in a LaTeX subset. + +.. _rst: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html + +When adding new commands, they need to be integrated into the sphinx +documentation system, and the corresponding command tables and lists +updated. When translating the documentation into html files there +should be no warnings. When adding a new package, some lists +describing packages must also be updated as well as a package specific +description added. Likewise, if necessary, some package specific +build instructions should be included. + +As appropriate, the text files with the documentation can include +inline mathematical expressions or figures (see ``doc/JPG`` for +examples). Additional PDF files with further details may also be +included; see ``doc/PDF`` for examples. The page should also include +literature citations as appropriate; see the bottom of +``doc/fix_nh.rst`` for examples and the earlier part of the same file +for how to format the cite itself. Citation labels must be unique +across **all** .rst files. The "Restrictions" section of the page +should indicate if your command is only available if LAMMPS is built +with the appropriate package. See other command doc files for +examples of how to do this. + +Please run at least "make html" and "make spelling" from within the +doc/src directory, and carefully inspect and proofread the resulting +HTML format doc page before submitting your code. Upon submission of +a pull request, checks for error free completion of the HTML and PDF +build will be performed and also a spell check, a check for correct +anchors and labels, and a check for completeness of references to all +styles in their corresponding tables and lists is run. In case the +spell check reports false positives, they can be added to the file +``doc/utils/sphinx-config/false_positives.txt`` + +Contributions that add or modify the library interface or "public" +APIs from the C++ code or the Fortran module must include suitable +doxygen comments in the source and corresponding changes to the +documentation sources for the "Programmer Guide" guide section of the +LAMMPS manual. + +If your feature requires some more complex steps and explanations to +be used correctly or some external or bundled tools or scripts, we +recommend that you also contribute a :doc:`Howto document ` +providing some more background information and some tutorial material. +This can also be used to provide more in-depth explanations of models +that require use of multiple commands. + +As a rule-of-thumb, the more clear and self-explanatory you make your +documentation, README files and examples, and the easier you make it +for people to get started, the more likely it is that users will try +out your new feature. + +.. _ReqProgrammingStandards: + +Programming language standards (strict) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The core of LAMMPS is written in C++11 in a style that can be mostly +described as "C with classes". Advanced C++ features like operator +overloading or excessive use of templates are avoided with the intent to +keep the code readable to programmers that have limited C++ programming +experience. C++ constructs are acceptable when they help improve the +readability and reliability of the code, e.g. when using the +`std::string` class instead of manipulating pointers and calling the +string functions of the C library. In addition, a collection of +convenient :doc:`utility functions and classes ` for +recurring tasks and a collection of :doc:`platform neutral functions +` for improved portability are provided. +Contributions with code requiring more recent C++ standards are only +accepted as packages with the post C++11 standard code confined to the +package so that it is optional. + +Included Fortran code has to be compatible with the Fortran 2003 +standard. Since not all platforms supported by LAMMPS provide good +support for compiling Fortran files, it should be considered to rewrite +these parts as C++ code, if possible and thus allow for a wider adoption +of the contribution. As of January 2023, all previously included +Fortran code for the LAMMPS executable has been replaced by equivalent +C++ code. + +Python code must be compatible with Python 3.5 and later. Large parts +of LAMMPS (including the :ref:`PYTHON package `) are also +compatible with Python 2.7. Compatibility with Python 2.7 is desirable, +but compatibility with Python 3.5 is **required**. + +Compatibility with older programming language standards is very +important to maintain portability and availability of LAMMPS on many +platforms. This applies especially to HPC cluster environments, which +tend to be running older software stacks and where LAMMPS users may be +required to use those older tools for access to advanced hardware +features or not have the option to install newer compilers or libraries. + +.. _ReqBuildSystem: + +Build system (strict) +--------------------- + +LAMMPS currently supports two build systems: one that is based on +:doc:`traditional Makefiles ` and one that is based on +:doc:`CMake `. Therefore, your contribution must be +compatible with and support both build systems. + +For a single pair of header and implementation files that are an +independent feature, it is usually only required to add them to +``src/.gitignore``. + +For traditional make, if your contributed files or package depend on +other LAMMPS style files or packages also being installed +(e.g. because your file is a derived class from the other LAMMPS +class), then an ``Install.sh`` file is also needed to check for those +dependencies and modifications to ``src/Depend.sh`` to trigger the checks. +See other README and Install.sh files in other directories as +examples. + +Similarly, for CMake support, changes may need to be made to +``cmake/CMakeLists.txt``, some of the files in ``cmake/presets``, and +possibly a file with specific instructions needs to be added to +``cmake/Modules/Packages/``. Please check out how this is handled for +existing packages and ask the LAMMPS developers if you need assistance. + +.. _ReqNaming: + +Command or style names, file names, and keywords (strict) +--------------------------------------------------------- + +All user-visible command or style names should be all lower case and +should only use letters, numbers, or forward slashes. They should be +descriptive and initialisms should be avoided unless they are well +established (e.g. lj for Lennard-Jones). For a compute style +"some/name" the source files must be called ``compute_some_name.h`` and +``compute_some_name.cpp``. The "include guard" in the header file would +then be ``LMP_COMPUTE_SOME_NAME_H`` and the class name +``ComputeSomeName``. + +.. _ReqProgrammingStyle: + +Programming style requirements (varied) +--------------------------------------- + +To maintain source code consistency across contributions from many +people, there are various programming style requirements for +contributions to LAMMPS. Some of these requirements are strict and +must be followed, while others are only preferred and thus may be +skipped. An in-depth discussion of the style guidelines is provided +in the :doc:`programming style doc page `. + +.. _ReqExamples: + +Examples (preferred) +-------------------- + +For many new features, it is preferred that example scripts (simple, +small, fast to complete on 1 CPU) are included that demonstrate the +use of new or extended functionality. These are typically include +under the examples or examples/PACKAGES directory and are further +described on the :doc:`examples page `. Guidelines for +input scripts include: + +- commands that generate output should be commented out (except when the + output is the sole purpose or the feature, e.g. for a new compute) + +- commands like :doc:`log `, :doc:`echo `, :doc:`package + `, :doc:`processors `, :doc:`suffix ` may + **not** be used in the input file (exception: "processors * * 1" or + similar is acceptable when used to avoid unwanted domain decomposition + of empty volumes) + +- outside of the log files, no generated output should be included + +- custom thermo_style settings may not include output measuring CPU or other + time as it complicates comparisons between different runs + +- input files should be named ``in.name``, data files should be named + ``data.name`` and log files should be named ``log.version.name..`` + +- the total file size of all the inputs and outputs should be small + +- where possible, potential files from the "potentials" folder or data + file from other folders should be re-used through symbolic links + +.. _ReqErrorMessages: + +Error or warning messages and explanations (preferred) +------------------------------------------------------ + +.. versionchanged:: 4May2022 + +Starting with LAMMPS version 4 May 2022, the LAMMPS developers have +agreed on a new policy for error and warning messages. + +Previously, all error and warning strings were supposed to be listed in +the class header files with an explanation. Those would then be +regularly "harvested" and transferred to alphabetically sorted lists in +the manual. To avoid excessively long lists and to reduce effort, this +came with a requirement to have rather generic error messages (e.g. +"Illegal ... command"). To identify the specific cause, the name of the +source file and the line number of the error location would be printed, +so that one could look up the cause by reading the source code. + +The new policy encourages more specific error messages that ideally +indicate the cause directly, and requiring no further lookup. This is +aided by the `{fmt} library `_ enabling Error class +methods that take a variable number of arguments and an error text that +will be treated like a {fmt} syntax format string. Error messages should +still preferably be kept to a single line or two lines at most. + +For more complex explanations or errors that have multiple possible +reasons, a paragraph should be added to the `Error_details` page with an +error code reference (e.g. ``.. _err0001:``) then the utility function +:cpp:func:`utils::errorurl() ` can be used +to generate a URL that will directly lead to that paragraph. An error +for missing arguments can be easily generated using the +:cpp:func:`utils::missing_cmd_args() +` convenience function. +An example for this approach would be the +``src/read_data.cpp`` and ``src/atom.cpp`` files that implement the +:doc:`read_data ` and :doc:`atom_modify ` +commands and that may create :ref:`"Unknown identifier in data file" ` +errors that may have multiple possible reasons which complicates debugging, +and thus require some additional explanation. + +The transformation of existing LAMMPS code to this new scheme is +ongoing. Given the size of the LAMMPS code base, it will take a +significant amount of time to complete. For new code, however, +following the new approach is strongly preferred. The expectation is +that the new scheme will make understanding errors easier for LAMMPS +users, developers, and maintainers. + +.. _ReqCitation: + +Citation reminder (optional) +----------------------------- + +If there is a paper of yours describing your feature (either the +algorithm/science behind the feature itself, or its initial usage, or +its implementation in LAMMPS), you can add the citation to the \*.cpp +source file. See ``src/DIFFRACTION/compute_saed.cpp`` for an example. +A BibTeX format citation is stored in a string variable at the top of +the file, and a single line of code registering this variable is added +to the constructor of the class. When your feature is used, then +LAMMPS (by default) will print the brief info and the DOI in the first +line to the screen and the full citation to the log file. + +If there is additional functionality (which may have been added later) +described in a different publication, additional citation descriptions +may be added so long as they are only registered when the +corresponding keyword activating this functionality is used. + +With these options, it is possible to have LAMMPS output a specific +citation reminder whenever a user invokes your feature from their +input script. Please note that you should *only* use this for the +*most* relevant paper for a feature and a publication that you or your +group authored. E.g. adding a citation in the source code for a paper +by Nose and Hoover if you write a fix that implements their integrator +is not the intended usage. That kind of citation should just be +included in the documentation page you provide describing your +contribution. If you are not sure what the best option would be, +please contact the LAMMPS developers for advice. + +.. _ReqUnitTesting: + +Testing (optional) +------------------ + +If your contribution contains new utility functions or a supporting +class (i.e. anything that does not depend on a LAMMPS object), new +unit tests should be added to a suitable folder in the ``unittest`` +tree. When adding a new LAMMPS style computing forces or selected +fixes, a ``.yaml`` file with a test configuration and reference data +should be added for the styles where a suitable tester program already +exists (e.g. pair styles, bond styles, etc.). Please see :ref:`this +section in the manual ` for more information on how to +enable, run, and expand testing. diff --git a/doc/src/Modify_style.rst b/doc/src/Modify_style.rst index ad2cb656d0..c5aef71597 100644 --- a/doc/src/Modify_style.rst +++ b/doc/src/Modify_style.rst @@ -1,350 +1,58 @@ -LAMMPS programming style and requirements for contributions -=========================================================== - -The following is a summary of the current requirements and -recommendations for including contributed source code or documentation -into the LAMMPS software distribution. - -Motivation ----------- - -The LAMMPS developers are committed to providing a software package that -is versatile, reliable, high-quality, efficient, portable, and easy to -maintain and modify. Achieving all of these goals is challenging since -a large part of LAMMPS consists of contributed code from many different -authors and not many of them are professionally trained programmers and -familiar with the idiosyncrasies of maintaining a large software -package. In addition, changes that interfere with the parallel -efficiency of the core code must be avoided. As LAMMPS continues to -grow and more features and functionality are added, it becomes a -necessity to be more discriminating with new contributions while also -working at the same time to improve the existing code. - -The following requirements and recommendations are provided to help -maintaining or improving that status. Where possible we utilize -available continuous integration tools to search for common programming -mistakes, portability limitations, incompatible formatting, and -undesired side effects. It is indicated which requirements are strict, -and which represent a preference and thus are negotiable or optional. - -Please feel free to contact the LAMMPS core developers in case you need -additional explanations or clarifications or in case you need assistance -in realizing the (strict) requirements for your contributions. - -Licensing requirements (strict) -------------------------------- - -Contributing authors agree when submitting a pull request that their -contributions can be distributed under the LAMMPS license -conditions. This is the GNU public license in version 2 (not 3 or later) -for the publicly distributed versions, e.g. on the LAMMPS homepage or on -GitHub. On request we also make a version of LAMMPS available under -LGPL 2.1 terms; this will usually be the latest available or a previous -stable version with a few LGPL 2.1 incompatible files removed. - -Your new source files should have the LAMMPS copyright, GPL notice, and -your name and email address at the top, like other user-contributed -LAMMPS source files. - -Contributions may be under a different license for long as that -license does not conflict with the aforementioned terms. Contributions -that use code with a conflicting license can be split into two parts: - -1. the core parts (i.e. parts that must be in the `src` tree) that are - licensed under compatible terms and bundled with the LAMMPS sources -2. an external library that must be downloaded and compiled (either - separately or as part of the LAMMPS compilation) - -Please note, that this split licensed mode may complicate including the -contribution in binary packages. - -Using Pull Requests on GitHub (preferred) ------------------------------------------ - -All contributions to LAMMPS are processed as pull requests on GitHub -(this also applies to the work of the core LAMMPS developers). A -:doc:`tutorial for submitting pull requests on GitHub ` is -provided. If this is still problematic, contributors may contact any of -the core LAMMPS developers for help or to create a pull request on their -behalf. This latter way of submission may delay the integration as it -depends on the amount of time required to prepare the pull request and -free time available by the LAMMPS developer in question to spend on this -task. - -Integration Testing (strict) ----------------------------- - -Contributed code, like all pull requests, must pass the automated -tests on GitHub before it can be merged with the LAMMPS distribution. -These tests compile LAMMPS in a variety of environments and settings and -run the bundled unit tests. At the discretion of the LAMMPS developer -managing the pull request, additional tests may be activated that test -for "side effects" on running a collection of input decks and create -consistent results. Also, the translation of the documentation to HTML -and PDF is tested for. - -More specifically, this means that contributed source code **must** -compile with the most current version of LAMMPS with ``-DLAMMPS_BIGBIG`` -in addition to the default setting of ``-DLAMMPS_SMALLBIG``. The code -needs to work correctly in both cases and also in serial and parallel -using MPI. - -Some "disruptive" changes may break tests and require updates to the -testing tools or scripts or tests themselves. This is rare. If in -doubt, contact the LAMMPS developer that is assigned to the pull request -for further details and explanations and suggestions of what needs to be -done. - -Documentation (strict) ----------------------- - -Contributions that add new styles or commands or augment existing ones -must include the corresponding new or modified documentation in -`ReStructuredText format `_ (.rst files in the ``doc/src/`` -folder). The documentation shall be written in American English and the -.rst file must use only ASCII characters so it can be cleanly translated -to PDF files (via `sphinx `_ and PDFLaTeX). -Special characters may be included via embedded math expression typeset -in a LaTeX subset. - -.. _rst: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html - -When adding new commands, they need to be integrated into the sphinx -documentation system, and the corresponding command tables and lists -updated. When translating the documentation into html files there should -be no warnings. When adding a new package also some lists describing -packages must be updated as well as a package specific description added -and, if necessary, some package specific build instructions included. - -As appropriate, the text files with the documentation can include inline -mathematical expression or figures (see ``doc/JPG`` for examples). -Additional PDF files with further details (see ``doc/PDF`` for examples) may -also be included. The page should also include literature citations as -appropriate; see the bottom of ``doc/fix_nh.rst`` for examples and the -earlier part of the same file for how to format the cite itself. -Citation labels must be unique across **all** .rst files. The -"Restrictions" section of the page should indicate if your command is -only available if LAMMPS is built with the appropriate FOO package. See -other package doc files for examples of how to do this. - -Please run at least "make html" and "make spelling" and carefully -inspect and proofread the resulting HTML format doc page before -submitting your code. Upon submission of a pull request, checks for -error free completion of the HTML and PDF build will be performed and -also a spell check, a check for correct anchors and labels, and a check -for completeness of references all styles in their corresponding tables -and lists is run. In case the spell check reports false positives they -can be added to the file ``doc/utils/sphinx-config/false_positives.txt`` - -Contributions that add or modify the library interface or "public" APIs -from the C++ code or the Fortran module must include suitable doxygen -comments in the source and corresponding changes to the documentation -sources for the "Programmer Guide" guide section of the LAMMPS manual. - -Examples (preferred) --------------------- - -In most cases, it is preferred that example scripts (simple, small, fast -to complete on 1 CPU) are included that demonstrate the use of new or -extended functionality. These are typically under the examples or -examples/PACKAGES directory. A few guidelines for such example input -decks. - -- commands that generate output should be commented out (except when the - output is the sole purpose or the feature, e.g. for a new compute). - -- commands like :doc:`log `, :doc:`echo `, :doc:`package - `, :doc:`processors `, :doc:`suffix ` may - **not** be used in the input file (exception: "processors * * 1" or - similar is acceptable when used to avoid unwanted domain decomposition - of empty volumes). - -- outside of the log files no generated output should be included - -- custom thermo_style settings may not include output measuring CPU or other time - as that makes comparing the thermo output between different runs more complicated. - -- input files should be named ``in.name``, data files should be named - ``data.name`` and log files should be named ``log.version.name..`` - -- the total file size of all the inputs and outputs should be small - -- where possible potential files from the "potentials" folder or data - file from other folders should be re-used through symbolic links - -Howto document (optional) -------------------------- - -If your feature requires some more complex steps and explanations to be -used correctly or some external or bundled tools or scripts, we -recommend that you also contribute a :doc:`Howto document ` -providing some more background information and some tutorial material. -This can also be used to provide more in-depth explanations for bundled -examples. - -As a general rule-of-thumb, the more clear and self-explanatory you make -your documentation, README files and examples, and the easier you make -it for people to get started, the more likely it is that users will try -out your new feature. - -Programming Style Requirements (varied) ---------------------------------------- - -The LAMMPS developers aim to employ a consistent programming style and -naming conventions across the entire code base, as this helps with -maintenance, debugging, and understanding the code, both for developers -and users. - -The files `pair_lj_cut.h`, `pair_lj_cut.cpp`, `utils.h`, and `utils.cpp` -may serve as representative examples. - -Command or Style names, file names, and keywords (mostly strict) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -All user-visible command or style names should be all lower case and -should only use letters, numbers, or forward slashes. They should be -descriptive and initialisms should be avoided unless they are well -established (e.g. lj for Lennard-Jones). For a compute style -"some/name" the source files must be called `compute_some_name.h` and -`compute_some_name.cpp`. The "include guard" would then be -`LMP_COMPUTE_SOME_NAME_H` and the class name `ComputeSomeName`. - -Whitespace and permissions (preferred) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Source files should not contain TAB characters unless required by the -syntax (e.g. in makefiles) and no trailing whitespace. Text files -should be added with Unix-style line endings (LF-only). Git will -automatically convert those in both directions when running on Windows; -use dos2unix on Linux machines to convert files. Text files should have -a line ending on the last line. - -All files should have 0644 permissions, i.e writable to the user only -and readable by all and no executable permissions. Executable -permissions (0755) should only be on shell scripts or python or similar -scripts for interpreted script languages. - -You can check for these issues with the python scripts in the -:ref:`"tools/coding_standard" ` folder. When run -normally with a source file or a source folder as argument, they will -list all non-conforming lines. By adding the `-f` flag to the command -line, they will modify the flagged files to try removing the detected -issues. - -Indentation and Placement of Braces (strongly preferred) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -LAMMPS uses 2 characters per indentation level and lines should be -kept within 100 characters wide. - -For new files added to the "src" tree, a `clang-format -`_ configuration file is -provided under the name `.clang-format`. This file is compatible with -clang-format version 8 and later. With that file present files can be -reformatted according to the configuration with a command like: -`clang-format -i new-file.cpp`. Ideally, this is done while writing the -code or before a pull request is submitted. Blocks of code where the -reformatting from clang-format yields undesirable output may be -protected with placing a pair `// clang-format off` and `// clang-format -on` comments around that block. - -Error or warning messages and explanations (preferred) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. versionchanged:: 4May2022 - -Starting with LAMMPS version 4 May 2022 the LAMMPS developers have -agreed on a new policy for error and warning messages. - -Previously, all error and warning strings were supposed to be listed in -the class header files with an explanation. Those would then be -regularly "harvested" and transferred to alphabetically sorted lists in -the manual. To avoid excessively long lists and to reduce effort, this -came with a requirement to have rather generic error messages (e.g. -"Illegal ... command"). To identify the specific cause, the name of the -source file and the line number of the error location would be printed, -so that one could look up the cause by reading the source code. - -The new policy encourages more specific error messages that ideally -indicate the cause directly and no further lookup would be needed. -This is aided by using the `{fmt} library `_ to convert -the Error class commands so that they take a variable number of arguments -and error text will be treated like a {fmt} syntax format string. -Error messages should still kept to a single line or two lines at the most. - -For more complex explanations or errors that have multiple possible -reasons, a paragraph should be added to the `Error_details` page with an -error code reference (e.g. ``.. _err0001:``) then the utility function -:cpp:func:`utils::errorurl() ` can be used -to generate an URL that will directly lead to that paragraph. An error -for missing arguments can be easily generated using the -:cpp:func:`utils::missing_cmd_args() -` convenience function. - -The transformation of existing LAMMPS code to this new scheme is ongoing -and - given the size of the LAMMPS source code - will take a significant -amount of time until completion. However, for new code following the -new approach is strongly preferred. The expectation is that the new -scheme will make it easier for LAMMPS users, developers, and -maintainers. - -An example for this approach would be the -``src/read_data.cpp`` and ``src/atom.cpp`` files that implement the -:doc:`read_data ` and :doc:`atom_modify ` -commands and that may create :ref:`"Unknown identifier in data file" ` -errors that seem difficult to debug for users because they may have -one of multiple possible reasons, and thus require some additional explanations. - -Programming language standards (required) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The core of LAMMPS is written in C++11 in a style that can be mostly -described as "C with classes". Advanced C++ features like operator -overloading or excessive use of templates are avoided with the intent to -keep the code readable to programmers that have limited C++ programming -experience. C++ constructs are acceptable when they help improving the -readability and reliability of the code, e.g. when using the -`std::string` class instead of manipulating pointers and calling the -string functions of the C library. In addition a collection of -convenient :doc:`utility functions and classes ` for -recurring tasks and a collection of -:doc:`platform neutral functions ` for improved -portability are provided. - -Included Fortran code has to be compatible with the Fortran 2003 -standard. Python code must be compatible with Python 3.5. Large parts -or LAMMPS (including the :ref:`PYTHON package `) are also -compatible with Python 2.7. Compatibility with Python 2.7 is -desirable, but compatibility with Python 3.5 is **required**. - -Compatibility with these older programming language standards is very -important to maintain portability and availability of LAMMPS on many -platforms. This applies especially to HPC cluster environments, which -tend to be running older software stacks and LAMMPS users may be -required to use those older tools for access to advanced hardware -features or not have the option to install newer compilers or libraries. - -Programming conventions (varied) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following is a collection of conventions that should be applied when -writing code for LAMMPS. Following these steps will make it much easier -to integrate your contribution. Please have a look at the existing files -in packages in the src directory for examples. As a demonstration for -how can be adapted to these conventions you may compare the REAXFF -package with the what it looked like when it was called USER-REAXC. If -you are uncertain, please ask. - -- system headers or from installed libraries are include with angular - brackets (example: ``#include ``), while local include file - use double quotes (example: ``#include "atom.h"``). - -- when including system header files from the C library use the - C++-style names (```` or ````) instead of the - C-style names (```` or ````) - -- the order of ``#include`` statements in a file ``some_name.cpp`` that - implements a class ``SomeName`` defined in a header file +LAMMPS programming style +======================== + +The aim of the LAMMPS developers is to use a consistent programming +style and naming conventions across the entire code base, as this +helps with maintenance, debugging, and understanding the code, both +for developers and users. This page provides a list of standard style +choices used in LAMMPS. Some of these standards are required, while +others are just preferred. Following these conventions will make it +much easier to integrate your contribution. If you are uncertain, +please ask. + +The files `pair_lj_cut.h`, `pair_lj_cut.cpp`, `utils.h`, and +`utils.cpp` may serve as representative examples. + +Include files (varied) +^^^^^^^^^^^^^^^^^^^^^^ + +- Header files that define a new LAMMPS style (i.e. that have a + ``SomeStyle(some/name,SomeName);`` macro in them) should only use + the include file for the base class and otherwise use forward + declarations and pointers; when interfacing to a library use the + PIMPL (pointer to implementation) approach where you have a pointer + to a struct that contains all library specific data (and thus + requires the library header) but use a forward declaration and + define the struct only in the implementation file. This is a + **strict** requirement since this is where type clashes between + packages and hard-to-find bugs have regularly manifested in the + past. + +- Header files, especially those defining a "style", should only use + the absolute minimum number of include files and **must not** + contain any ``using`` statements. Typically, that would only be the + header for the base class. Instead, any include statements should + be put in the corresponding implementation files and forward + declarations be used. For implementation files, the "include what + you use" principle should be employed. However, there is the + notable exception that when the ``pointers.h`` header is included + (or one of the base classes derived from it) certain headers will + always be included and thus do not need to be explicitly specified. + These are: `mpi.h`, `cstddef`, `cstdio`, `cstdlib`, `string`, + `utils.h`, `vector`, `fmt/format.h`, `climits`, `cinttypes`. This + also means any such file can assume that `FILE`, `NULL`, and + `INT_MAX` are defined. + +- System headers or headers from installed libraries are included with + angular brackets (example: ``#include ``), while local + include files use double quotes (example: ``#include "atom.h"``) + +- When including system header files from the C library use the + C++-style names (```` or ````) instead of the + C-style names (```` or ````) + +- The order of ``#include`` statements in a file ``some_name.cpp`` + that implements a class ``SomeName`` defined in a header file ``some_name.h`` should be as follows: - ``#include "some_name.h"`` followed by an empty line @@ -352,34 +60,70 @@ you are uncertain, please ask. - LAMMPS include files e.g. ``#include "comm.h"`` or ``#include "modify.h"`` in alphabetical order followed by an empty line - - system header files from the C++ or C standard library followed by + - System header files from the C++ or C standard library followed by an empty line - ``using namespace LAMMPS_NS`` or other namespace imports. +Whitespace (preferred) +^^^^^^^^^^^^^^^^^^^^^^ + +Source files should not contain TAB characters unless required by the +syntax (e.g. in makefiles) and no trailing whitespace. Text files +should have Unix-style line endings (LF-only). Git will automatically +convert those in both directions when running on Windows; use dos2unix +on Linux machines to convert files to Unix-style line endings. The +last line of text files include a line ending. + +You can check for these issues with the python scripts in the +:ref:`"tools/coding_standard" ` folder. When run +normally with a source file or a source folder as argument, they will +list all non-conforming lines. By adding the `-f` flag to the command +line, they will modify the flagged files to try to remove the detected +issues. + +Placement of braces (strongly preferred) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For new files added to the "src" tree, a `clang-format +`_ configuration file is +provided under the name `.clang-format`. This file is compatible with +clang-format version 8 and later. With that file present, files can be +reformatted according to the configuration with a command like: +`clang-format -i new-file.cpp`. Ideally, this is done while writing +the code or before a pull request is submitted. Blocks of code where +the reformatting from clang-format yields hard-to-read or otherwise +undesirable output may be protected with placing a pair `// +clang-format off` and `// clang-format on` comments around that block. + +Miscellaneous standards (varied) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + - I/O is done via the C-style stdio library and **not** iostreams. - Do not use so-called "alternative tokens" like ``and``, ``or``, ``not`` and similar, but rather use the corresponding operators ``&&``, ``||``, and ``!``. The alternative tokens are not available - by default on all compilers, and also we want to maintain a consistent - programming style. + by default on all compilers. -- Output to the screen and the logfile should be using the corresponding - FILE pointers and only be done on MPI rank 0. Use the :cpp:func:`utils::logmesg` - convenience function where possible. +- Output to the screen and the logfile should use the corresponding + FILE pointers and only be done on MPI rank 0. Use the + :cpp:func:`utils::logmesg` convenience function where possible. -- Usage of C++11 `virtual`, `override`, `final` keywords: Please follow the - `C++ Core Guideline C.128 `_. +- Usage of C++11 `virtual`, `override`, `final` keywords: Please + follow the `C++ Core Guideline C.128 + `_. That means, you should only use `virtual` to declare a new virtual - function, `override` to indicate you are overriding an existing virtual - function, and `final` to prevent any further overriding. + function, `override` to indicate you are overriding an existing + virtual function, and `final` to prevent any further overriding. -- Trivial destructors: Prefer not writing destructors when they are empty and `default`. +- Trivial destructors: Do not write destructors when they are empty + and `default`. .. code-block:: c++ // don't write destructors for A or B like this + class A : protected Pointers { public: A(); @@ -393,6 +137,7 @@ you are uncertain, please ask. }; // instead, let the compiler create the implicit default destructor by not writing it + class A : protected Pointers { public: A(); @@ -403,37 +148,11 @@ you are uncertain, please ask. B(); }; -- Header files, especially those defining a "style", should only use - the absolute minimum number of include files and **must not** contain - any ``using`` statements. Typically that would be only the header for - the base class. Instead any include statements should be put into the - corresponding implementation files and forward declarations be used. - For implementation files, the "include what you use" principle should - be employed. However, there is the notable exception that when the - ``pointers.h`` header is included (or one of the base classes derived - from it) certain headers will always be included and thus do not need - to be explicitly specified. - These are: `mpi.h`, `cstddef`, `cstdio`, `cstdlib`, `string`, `utils.h`, - `vector`, `fmt/format.h`, `climits`, `cinttypes`. - This also means any such file can assume that `FILE`, `NULL`, and - `INT_MAX` are defined. - -- Header files that define a new LAMMPS style (i.e. that have a - ``SomeStyle(some/name,SomeName);`` macro in them) should only use the - include file for the base class and otherwise use forward declarations - and pointers; when interfacing to a library use the PIMPL (pointer - to implementation) approach where you have a pointer to a struct - that contains all library specific data (and thus requires the library - header) but use a forward declaration and define the struct only in - the implementation file. This is a **strict** requirement since this - is where type clashes between packages and hard to find bugs have - regularly manifested in the past. - - Please use clang-format only to reformat files that you have contributed. For header files containing a ``SomeStyle(keyword, - ClassName)`` macros it is required to have this macro embedded with a - pair of ``// clang-format off``, ``// clang-format on`` commends and - the line must be terminated with a semi-colon (;). Example: + ClassName)`` macros it is required to have this macro embedded with + a pair of ``// clang-format off``, ``// clang-format on`` comments + and the line must be terminated with a semicolon (;). Example: .. code-block:: c++ @@ -446,92 +165,10 @@ you are uncertain, please ask. #ifndef LMP_RUN_H [...] - You may also use ``// clang-format on/off`` throughout your files - to protect individual sections from being reformatted. + You may also use ``// clang-format on/off`` throughout your files to + protect individual sections from being reformatted. -- We rarely accept new styles in the core src folder. Thus please - review the list of :doc:`available Packages ` to see - if your contribution could be added to be added to one of them. It - should fit into the general purposed of that package. If it does not - fit well, it may be added to one of the EXTRA- packages or the MISC - package. - - -Contributing a package ----------------------- - -If your contribution has several related features that are not covered -by one of the existing packages or is dependent on a library (bundled or -external), it is best to make it a package directory with a name like -FOO. In addition to your new files, the directory should contain a -README text file. The README should contain your name and contact -information and a brief description of what your new package does. - - -Build system (strongly preferred) ---------------------------------- - -LAMMPS currently supports two build systems: one that is based on -:doc:`traditional Makefiles ` and one that is based on -:doc:`CMake `. Thus your contribution must be compatible -with and support both. - -For a single pair of header and implementation files that are an -independent feature, it is usually only required to add them to -`src/.gitignore``. - -For traditional make, if your contributed files or package depend on -other LAMMPS style files or packages also being installed (e.g. because -your file is a derived class from the other LAMMPS class), then an -Install.sh file is also needed to check for those dependencies and -modifications to src/Depend.sh to trigger the checks. See other README -and Install.sh files in other directories as examples. - -Similarly for CMake support, changes may need to be made to -cmake/CMakeLists.txt, some of the files in cmake/presets, and possibly a -file with specific instructions needs to be added to -cmake/Modules/Packages/. Please check out how this is handled for -existing packages and ask the LAMMPS developers if you need assistance. - - -Citation reminder (suggested) ------------------------------ - -If there is a paper of yours describing your feature (either the -algorithm/science behind the feature itself, or its initial usage, or -its implementation in LAMMPS), you can add the citation to the \*.cpp -source file. See ``src/DIFFRACTION/compute_saed.cpp`` for an example. -A BibTeX format citation is stored in a string variable at the top -of the file and a single line of code registering this variable is -added to the constructor of the class. When your feature is used, -by default, LAMMPS will print the brief info and the DOI -in the first line to the screen and the full citation to the log file. - -If there is additional functionality (which may have been added later) -described in a different publication, additional citation descriptions -may be added for as long as they are only registered when the -corresponding keyword activating this functionality is used. With these -options it is possible to have LAMMPS output a specific citation -reminder whenever a user invokes your feature from their input script. -Please note that you should *only* use this for the *most* relevant -paper for a feature and a publication that you or your group authored. -E.g. adding a citation in the code for a paper by Nose and Hoover if you -write a fix that implements their integrator is not the intended usage. -That latter kind of citation should just be included in the -documentation page you provide describing your contribution. If you are -not sure what the best option would be, please contact the LAMMPS -developers for advice. - - -Testing (optional) ------------------- - -If your contribution contains new utility functions or a supporting class -(i.e. anything that does not depend on a LAMMPS object), new unit tests -should be added to a suitable folder in the ``unittest`` tree. -When adding a new LAMMPS style computing forces or selected fixes, -a ``.yaml`` file with a test configuration and reference data should be -added for the styles where a suitable tester program already exists -(e.g. pair styles, bond styles, etc.). Please see -:ref:`this section in the manual ` for more information on -how to enable, run, and expand testing. +- All files should have 0644 permissions, i.e. writable by the user + only and readable by all and no executable permissions. Executable + permissions (0755) should only be for shell scripts or python or + similar scripts for interpreted script languages. diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst index c9f19f4988..d397638e59 100644 --- a/doc/src/Packages_details.rst +++ b/doc/src/Packages_details.rst @@ -67,7 +67,6 @@ page gives those details. * :ref:`KOKKOS ` * :ref:`KSPACE ` * :ref:`LATBOLTZ ` - * :ref:`LATTE ` * :ref:`LEPTON ` * :ref:`MACHDYN ` * :ref:`MANIFOLD ` @@ -1357,43 +1356,6 @@ The LATBOLTZ package requires that LAMMPS is build in :ref:`MPI parallel mode `_. A brief technical -description is given with the :doc:`fix latte ` command. - -.. _latte-home: https://github.com/lanl/LATTE - -**Authors:** Christian Negre (LANL) and Steve Plimpton (Sandia). LATTE -itself is developed at Los Alamos National Laboratory by Marc -Cawkwell, Anders Niklasson, and Christian Negre. - -**Install:** - -This package has :ref:`specific installation instructions ` on -the :doc:`Build extras ` page. - -**Supporting info:** - -* src/LATTE: filenames -> commands -* src/LATTE/README -* lib/latte/README -* :doc:`fix latte ` -* examples/latte -* `LAMMPS-LATTE tutorial `_ - ----------- - .. _PKG-LEPTON: LEPTON package diff --git a/doc/src/Packages_list.rst b/doc/src/Packages_list.rst index 8f2aca5d69..77812a236a 100644 --- a/doc/src/Packages_list.rst +++ b/doc/src/Packages_list.rst @@ -233,11 +233,6 @@ whether an extra library is needed to build and use the package: - :doc:`fix lb/fluid ` - PACKAGES/latboltz - no - * - :ref:`LATTE ` - - quantum DFTB forces via LATTE - - :doc:`fix latte ` - - latte - - ext * - :ref:`LEPTON ` - evaluate strings as potential function - :doc:`pair_style lepton ` diff --git a/doc/src/Python_install.rst b/doc/src/Python_install.rst index cc1e2cb5c9..c4fbec0be4 100644 --- a/doc/src/Python_install.rst +++ b/doc/src/Python_install.rst @@ -43,19 +43,20 @@ folder that the dynamic loader searches or inside of the installed Compile LAMMPS with either :doc:`CMake ` or the :doc:`traditional make ` procedure in :ref:`shared - mode `. After compilation has finished type (in the + mode `. After compilation has finished, type (in the compilation folder): .. code-block:: bash make install-python - This will try to build a so-called (binary) 'wheel', a compressed - binary python package and then install it with the python package - manager 'pip'. Installation will be attempted into a system-wide - ``site-packages`` folder and if that fails into the corresponding - folder in the user's home directory. For a system-wide installation you - would have to gain superuser privilege, e.g. though ``sudo`` + This will try to build a so-called (binary) wheel file, a + compressed binary python package and then install it with the + python package manager 'pip'. Installation will be attempted into + a system-wide ``site-packages`` folder and if that fails into the + corresponding folder in the user's home directory. For a + system-wide installation you usually would have to gain superuser + privilege first, e.g. though ``sudo`` +------------------------+----------------------------------------------------------+-------------------------------------------------------------+ | File | Location | Notes | @@ -106,10 +107,11 @@ folder that the dynamic loader searches or inside of the installed .. code-block:: bash - python install.py -p -l [-n] + python install.py -p -l -v [-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, + * the ``-v`` flag points to the LAMMPS version header file to extract the version date, * and the optional ``-n`` instructs the script to only build a wheel file but not attempt to install it. diff --git a/doc/src/Speed_kokkos.rst b/doc/src/Speed_kokkos.rst index 569a24f1c2..8161e69a1c 100644 --- a/doc/src/Speed_kokkos.rst +++ b/doc/src/Speed_kokkos.rst @@ -285,6 +285,16 @@ one or more nodes, each with two GPUs: settings. Experimenting with its options can provide a speed-up for specific calculations. For example: +.. note:: + + The default binsize for :doc:`atom sorting ` on GPUs + is equal to the default CPU neighbor binsize (i.e. 2x smaller than the + default GPU neighbor binsize). When running simple pair-wise + potentials like Lennard Jones on GPUs, using a 2x larger binsize for + atom sorting (equal to the default GPU neighbor binsize) and a more + frequent sorting than default (e.g. sorting every 100 time steps + instead of 1000) may improve performance. + .. code-block:: bash mpirun -np 2 lmp_kokkos_cuda_openmpi -k on g 2 -sf kk -pk kokkos newton on neigh half binsize 2.8 -in in.lj # Newton on, half neighbor list, set binsize = neighbor ghost cutoff diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst index 2eae1aabc7..bccb9abe73 100644 --- a/doc/src/Tools.rst +++ b/doc/src/Tools.rst @@ -883,9 +883,9 @@ dependencies and redirects the download to the local cache. phonon tool ------------------------ -The phonon subdirectory contains a post-processing tool useful for -analyzing the output of the :doc:`fix phonon ` command in -the PHONON package. +The phonon subdirectory contains a post-processing tool, *phana*, useful +for analyzing the output of the :doc:`fix phonon ` command +in the PHONON package. See the README file for instruction on building the tool and what library it needs. And see the examples/PACKAGES/phonon directory diff --git a/doc/src/angle_dipole.rst b/doc/src/angle_dipole.rst index 8aaed55132..4bc08d9530 100644 --- a/doc/src/angle_dipole.rst +++ b/doc/src/angle_dipole.rst @@ -28,15 +28,15 @@ The *dipole* angle style is used to control the orientation of a dipolar atom within a molecule :ref:`(Orsi) `. Specifically, the *dipole* angle style restrains the orientation of a point dipole :math:`\mu_j` (embedded in atom :math:`j`) with respect to a reference (bond) vector -:math:`\vec{r_{ij}} = \vec{r_i} - \vec{r_j}`, where :math:`i` is another atom of +:math:`\vec{r}_{ij} = \vec{r}_i - \vec{r}_j`, where :math:`i` is another atom of the same molecule (typically, :math:`i` and :math:`j` are also covalently bonded). -It is convenient to define an angle gamma between the 'free' vector :math:`\vec{\mu_j}` -and the reference (bond) vector :math:`\vec{r_{ij}}`: +It is convenient to define an angle gamma between the 'free' vector :math:`\vec{\mu}_j` +and the reference (bond) vector :math:`\vec{r}_{ij}`: .. math:: - \cos\gamma = \frac{\vec{\mu_j}\cdot\vec{r_{ij}}}{\mu_j\,r_{ij}} + \cos\gamma = \frac{\vec{\mu}_j\cdot\vec{r}_{ij}}{\mu_j\,r_{ij}} The *dipole* angle style uses the potential: @@ -53,23 +53,23 @@ potential using the 'chain rule' as in appendix C.3 of .. math:: - \vec{T_j} = \frac{2K(\cos\gamma - \cos\gamma_0)}{\mu_j\,r_{ij}}\, \vec{r_{ij}} \times \vec{\mu_j} + \vec{T}_j = \frac{2K(\cos\gamma - \cos\gamma_0)}{\mu_j\,r_{ij}}\, \vec{r}_{ij} \times \vec{\mu}_j Example: if :math:`\gamma_0` is set to 0 degrees, the torque generated by the potential will tend to align the dipole along the reference -direction defined by the (bond) vector :math:`\vec{r_{ij}}` (in other words, :math:`\vec{\mu_j}` is +direction defined by the (bond) vector :math:`\vec{r}_{ij}` (in other words, :math:`\vec{\mu}_j` is restrained to point towards atom :math:`i`). -The dipolar torque :math:`\vec{T_j}` must be counterbalanced in order to conserve +The dipolar torque :math:`\vec{T}_j` must be counterbalanced in order to conserve the local angular momentum. This is achieved via an additional force -couple generating a torque equivalent to the opposite of :math:`\vec{T_j}`: +couple generating a torque equivalent to the opposite of :math:`\vec{T}_j`: .. math:: - -\vec{T_j} & = \vec{r_{ij}} \times \vec{F_i} \\ - \vec{F_j} & = -\vec{F_i} + -\vec{T}_j & = \vec{r}_{ij} \times \vec{F}_i \\ + \vec{F}_j & = -\vec{F}_i -where :math:`\vec{F_i}` and :math:`\vec{F_j}` are applied on atoms :math:`i` +where :math:`\vec{F}_i` and :math:`\vec{F}_j` are applied on atoms :math:`i` and :math:`j`, respectively. The following coefficients must be defined for each angle type via the diff --git a/doc/src/atom_modify.rst b/doc/src/atom_modify.rst index 9049a24fde..1e5a3d49ff 100644 --- a/doc/src/atom_modify.rst +++ b/doc/src/atom_modify.rst @@ -153,6 +153,13 @@ cache locality will be undermined. order of atoms in a :doc:`dump ` file will also typically change if sorting is enabled. +.. note:: + + When running simple pair-wise potentials like Lennard Jones on GPUs + with the KOKKOS package, using a larger binsize (e.g. 2x larger than + default) and a more frequent reordering than default (e.g. every 100 + time steps) may improve performance. + Restrictions """""""""""" diff --git a/doc/src/bond_bpm_rotational.rst b/doc/src/bond_bpm_rotational.rst index d9d0f160fb..ba93d679ba 100644 --- a/doc/src/bond_bpm_rotational.rst +++ b/doc/src/bond_bpm_rotational.rst @@ -10,7 +10,7 @@ Syntax bond_style bpm/rotational keyword value attribute1 attribute2 ... -* optional keyword = *overlay/pair* or *store/local* or *smooth* +* optional keyword = *overlay/pair* or *store/local* or *smooth* or *break/no* .. parsed-literal:: @@ -30,6 +30,9 @@ Syntax *smooth* value = *yes* or *no* smooths bond forces near the breaking point + *break/no* + indicates that bonds should not break during a run + Examples """""""" @@ -140,6 +143,12 @@ the *overlay/pair* keyword. These settings require specific restrictions. Further details can be found in the `:doc: how to ` page on BPMs. +.. versionadded:: 28Mar2023 + +If the *break/no* keyword is used, then LAMMPS assumes bonds should not break +during a simulation run. This will prevent some unnecessary calculation. +However, if a bond does break, it will trigger an error. + If the *store/local* keyword is used, an internal fix will track bonds that break during the simulation. Whenever a bond breaks, data is processed and transferred to an internal fix labeled *fix_ID*. This allows the diff --git a/doc/src/bond_bpm_spring.rst b/doc/src/bond_bpm_spring.rst index 46c300d364..5762dbe208 100644 --- a/doc/src/bond_bpm_spring.rst +++ b/doc/src/bond_bpm_spring.rst @@ -10,7 +10,7 @@ Syntax bond_style bpm/spring keyword value attribute1 attribute2 ... -* optional keyword = *overlay/pair* or *store/local* or *smooth* +* optional keyword = *overlay/pair* or *store/local* or *smooth* or *break/no* .. parsed-literal:: @@ -30,6 +30,9 @@ Syntax *smooth* value = *yes* or *no* smooths bond forces near the breaking point + *break/no* + indicates that bonds should not break during a run + Examples """""""" @@ -47,7 +50,7 @@ Description .. versionadded:: 4May2022 -The *bpm/spring* bond style computes forces and torques based on +The *bpm/spring* bond style computes forces based on deviations from the initial reference state of the two atoms. The reference state is stored by each bond when it is first computed in the setup of a run. Data is then preserved across run commands and is @@ -56,7 +59,8 @@ the system will not reset the reference state of a bond. This bond style only applies central-body forces which conserve the translational and rotational degrees of freedom of a bonded set of -particles. The force has a magnitude of +particles based on a model described by Clemmer and Robbins +:ref:`(Clemmer) `. The force has a magnitude of .. math:: @@ -105,6 +109,12 @@ the *overlay/pair* keyword. These settings require specific restrictions. Further details can be found in the `:doc: how to ` page on BPMs. +.. versionadded:: 28Mar2023 + +If the *break/no* keyword is used, then LAMMPS assumes bonds should not break +during a simulation run. This will prevent some unnecessary calculation. +However, if a bond does break, it will trigger an error. + If the *store/local* keyword is used, an internal fix will track bonds that break during the simulation. Whenever a bond breaks, data is processed and transferred to an internal fix labeled *fix_ID*. This allows the @@ -200,6 +210,10 @@ The option defaults are *smooth* = *yes* ---------- +.. _fragment-Clemmer: + +**(Clemmer)** Clemmer and Robbins, Phys. Rev. Lett. (2022). + .. _Groot4: **(Groot)** Groot and Warren, J Chem Phys, 107, 4423-35 (1997). diff --git a/doc/src/bond_harmonic_restrain.rst b/doc/src/bond_harmonic_restrain.rst index c9707f5546..8ef92d8b44 100644 --- a/doc/src/bond_harmonic_restrain.rst +++ b/doc/src/bond_harmonic_restrain.rst @@ -21,7 +21,7 @@ Examples Description """"""""""" -.. versionadded:: TBD +.. versionadded:: 28Mar2023 The *harmonic/restrain* bond style uses the potential diff --git a/doc/src/bond_style.rst b/doc/src/bond_style.rst index b33d0a9e9a..95f463e695 100644 --- a/doc/src/bond_style.rst +++ b/doc/src/bond_style.rst @@ -32,13 +32,13 @@ Set the formula(s) LAMMPS uses to compute bond interactions between pairs of atoms. In LAMMPS, a bond differs from a pairwise interaction, which are set via the :doc:`pair_style ` command. Bonds are defined between specified pairs of atoms and -remain in force for the duration of the simulation (unless the bond -breaks which is possible in some bond potentials). The list of bonded -atoms is read in by a :doc:`read_data ` or -:doc:`read_restart ` command from a data or restart file. -By contrast, pair potentials are typically defined between all pairs -of atoms within a cutoff distance and the set of active interactions -changes over time. +remain in force for the duration of the simulation (unless new bonds +are created or existing bonds break, which is possible in some fixes +and bond potentials). The list of bonded atoms is read in by a +:doc:`read_data ` or :doc:`read_restart ` +command from a data or restart file. By contrast, pair potentials are +typically defined between all pairs of atoms within a cutoff distance +and the set of active interactions changes over time. Hybrid models where bonds are computed using different bond potentials can be setup using the *hybrid* bond style. diff --git a/doc/src/comm_modify.rst b/doc/src/comm_modify.rst index 11bfe18ac5..c416ca21ea 100644 --- a/doc/src/comm_modify.rst +++ b/doc/src/comm_modify.rst @@ -69,6 +69,7 @@ For many systems this is an efficient algorithm, but for systems with widely varying cutoffs for different type pairs, the *multi* or *multi/old* mode can be faster. In *multi*, each atom is assigned to a collection which should correspond to a set of atoms with similar interaction cutoffs. +See the :doc:`neighbor ` command for a detailed description of collections. In this case, each atom collection is assigned its own distance cutoff for communication purposes, and fewer atoms will be communicated. in *multi/old*, a similar technique is used but atoms diff --git a/doc/src/compute.rst b/doc/src/compute.rst index 880f60a8a6..950487cb72 100644 --- a/doc/src/compute.rst +++ b/doc/src/compute.rst @@ -200,6 +200,7 @@ The individual style names on the :doc:`Commands compute ` pag * :doc:`com/chunk ` - center of mass for each chunk * :doc:`contact/atom ` - contact count for each spherical particle * :doc:`coord/atom ` - coordination number for each atom +* :doc:`count/type ` - count of atoms or bonds by type * :doc:`damage/atom ` - Peridynamic damage for each atom * :doc:`dihedral ` - energy of each dihedral sub-style * :doc:`dihedral/local ` - angle of each dihedral diff --git a/doc/src/compute_count_type.rst b/doc/src/compute_count_type.rst new file mode 100644 index 0000000000..81fffb4f28 --- /dev/null +++ b/doc/src/compute_count_type.rst @@ -0,0 +1,130 @@ +.. index:: compute count/type + +compute count/type command +========================== + +Syntax +"""""" + +.. code-block:: LAMMPS + + compute ID group-ID count/type mode + +* ID, group-ID are documented in :doc:`compute ` command +* count/type = style name of this compute command +* mode = {atom} or {bond} or {angle} or {dihedral} or {improper} + +Examples +"""""""" + +.. code-block:: LAMMPS + + compute 1 all count/type atom + compute 1 flowmols count/type bond + +Description +""""""""""" + +.. versionadded:: TBD + +Define a computation that counts the current number of atoms for each +atom type. Or the number of bonds (angles, dihedrals, impropers) for +each bond (angle, dihedral, improper) type. + +The former can be useful if atoms are added to or deleted from the +system in random ways, e.g. via the :doc:`fix deposit `, +:doc:`fix pour `, or :doc:`fix evaporate ` +commands. The latter can be useful in reactive simulations where +molecular bonds are broken or created, as well as angles, dihedrals, +impropers. + +Note that for this command, bonds (angles, etc) are the topological +kind enumerated in a data file, initially read by the :doc:`read_data +` command or defined by the :doc:`molecule ` +command. They do not refer to implicit bonds defined on-the-fly by +bond-order or reactive pair styles based on the current conformation +of small clusters of atoms. + +These commands can turn off topological bonds (angles, etc) by setting +their bond (angle, etc) types to negative values. This command +includes the turned-off bonds (angles, etc) in the count for each +type: + +* :doc:`fix shake ` +* :doc:`delete_bonds ` + +These commands can create and/or break topological bonds (angles, +etc). In the case of breaking, they remove the bond (angle, etc) from +the system, so that they no longer exist (:doc:`bond_style quartic +` and :doc:`BPM bond styles ` are exceptions, +see the discussion below). Thus they are not included in the counts +for each type: + +* :doc:`delete_bonds remove ` +* :doc:`bond_style quartic ` +* :doc:`fix bond/react ` +* :doc:`fix bond/create ` +* :doc:`fix bond/break ` +* :doc:`BPM package ` bond styles + +---------- + +If the {mode} setting is {atom} then the count of atoms for each atom +type is tallied. Only atoms in the specified group are counted. + +If the {mode} setting is {bond} then the count of bonds for each bond +type is tallied. Only bonds with both atoms in the specified group +are counted. + +For {mode} = {bond}, broken bonds with a bond type of zero are also +counted. The :doc:`bond_style quartic ` and :doc:`BPM +bond styles ` break bonds by doing this. See the :doc:` +Howto broken bonds ` doc page for more details. +Note that the group setting is ignored for broken bonds; all broken +bonds in the system are counted. + +If the {mode} setting is {angle} then the count of angles for each +angle type is tallied. Only angles with all 3 atoms in the specified +group are counted. + +If the {mode} setting is {dihedral} then the count of dihedrals for +each dihedral type is tallied. Only dihedrals with all 4 atoms in the +specified group are counted. + +If the {mode} setting is {improper} then the count of impropers for +each improper type is tallied. Only impropers with all 4 atoms in the +specified group are counted. + +---------- + +Output info +""""""""""" + +This compute calculates a global vector of counts. If the mode is +{atom} or {bond} or {angle} or {dihedral} or {improper}, then the +vector length is the number of atom types or bond types or angle types +or dihedral types or improper types, respectively. + +If the mode is {bond} this compute also calculates a global scalar +which is the number of broken bonds with type = 0, as explained above. + +These values can be used by any command that uses global scalar or +vector values from a compute as input. See the :doc:`Howto output +` page for an overview of LAMMPS output options. + +The scalar and vector values calculated by this compute are "extensive". + +Restrictions +"""""""""""" + +none + +Related commands +"""""""""""""""" + +none + +Default +""""""" + +none diff --git a/doc/src/compute_dipole.rst b/doc/src/compute_dipole.rst index fa1ca4ce0b..d8bcb29c71 100644 --- a/doc/src/compute_dipole.rst +++ b/doc/src/compute_dipole.rst @@ -42,7 +42,7 @@ geometric center times the net charge from the computed dipole vector. Both per-atom charges and per-atom dipole moments, if present, contribute to the computed dipole. -.. versionadded:: TBD +.. versionadded:: 28Mar2023 Compute *dipole/tip4p* includes adjustments for the charge carrying point M in molecules with TIP4P water geometry. The corresponding diff --git a/doc/src/compute_dipole_chunk.rst b/doc/src/compute_dipole_chunk.rst index 4e89bb748a..92289e10f9 100644 --- a/doc/src/compute_dipole_chunk.rst +++ b/doc/src/compute_dipole_chunk.rst @@ -51,7 +51,7 @@ center times the net charge from the computed dipole vector. Both per-atom charges and per-atom dipole moments, if present, contribute to the computed dipole. -.. versionadded:: TBD +.. versionadded:: 28Mar2023 Compute *dipole/tip4p/chunk* includes adjustments for the charge carrying point M in molecules with TIP4P water geometry. The diff --git a/doc/src/compute_erotate_sphere.rst b/doc/src/compute_erotate_sphere.rst index aae37277a4..2962ba698c 100644 --- a/doc/src/compute_erotate_sphere.rst +++ b/doc/src/compute_erotate_sphere.rst @@ -1,8 +1,12 @@ .. index:: compute erotate/sphere +.. index:: compute erotate/sphere/kk compute erotate/sphere command ============================== +Accelerator Variants: *erotate/sphere/kk* + + Syntax """""" @@ -36,6 +40,12 @@ is the particle's angular velocity. spheres, not disks, meaning their moment of inertia will be the same as in 3d. +---------- + +.. include:: accel_styles.rst + +---------- + Output info """"""""""" diff --git a/doc/src/compute_pressure_alchemy.rst b/doc/src/compute_pressure_alchemy.rst index bdf9802e20..dcf6754c02 100644 --- a/doc/src/compute_pressure_alchemy.rst +++ b/doc/src/compute_pressure_alchemy.rst @@ -26,7 +26,7 @@ Examples Description """"""""""" -.. versionadded:: TBD +.. versionadded:: 28Mar2023 Define a compute style that makes the "mixed" system pressure available for a system that uses the :doc:`fix alchemy ` command to diff --git a/doc/src/compute_ptm_atom.rst b/doc/src/compute_ptm_atom.rst index 3d024802ab..a47684224a 100644 --- a/doc/src/compute_ptm_atom.rst +++ b/doc/src/compute_ptm_atom.rst @@ -66,8 +66,8 @@ The deviation is calculated as: \text{RMSD}(\mathbf{u}, \mathbf{v}) = \min_{s, \mathbf{Q}} \sqrt{\frac{1}{N} \sum\limits_{i=1}^{N} - {\left\lVert s[\vec{u_i} - \mathbf{\bar{u}}] - - \mathbf{Q} \cdot \vec{v_i} \right\rVert}^2} + {\left\lVert s[\vec{u}_i - \mathbf{\bar{u}}] + - \mathbf{Q} \cdot \vec{v}_i \right\rVert}^2} Here, :math:`\vec u` and :math:`\vec v` contain the coordinates of the local and ideal structures respectively, :math:`s` is a scale factor, and diff --git a/doc/src/compute_reduce.rst b/doc/src/compute_reduce.rst index 89554ebece..204f1c090d 100644 --- a/doc/src/compute_reduce.rst +++ b/doc/src/compute_reduce.rst @@ -23,7 +23,7 @@ Syntax *reduce/region* arg = region-ID region-ID = ID of region to use for choosing atoms -* mode = *sum* or *min* or *max* or *ave* or *sumsq* or *avesq* or *sumabs* or *aveabs* +* mode = *sum* or *min* or *minabs* or *max* or *maxabs* or *ave* or *sumsq* or *avesq* or *sumabs* or *aveabs* * one or more inputs can be listed * input = *x* or *y* or *z* or *vx* or *vy* or *vz* or *fx* or *fy* or *fz* or c_ID or c_ID[N] or f_ID or f_ID[N] or v_name @@ -71,12 +71,13 @@ vectors. The reduction operation is specified by the *mode* setting. The *sum* option adds the values in the vector into a global total. The *min* or *max* options find the minimum or maximum value across all vector -values. The *ave* setting adds the vector values into a global total, -then divides by the number of values in the vector. The *sumsq* -option sums the square of the values in the vector into a global -total. The *avesq* setting does the same as *sumsq*, then divides the -sum of squares by the number of values. The last two options can be -useful for calculating the variance of some quantity (e.g., variance = +values. The *minabs* or *maxabs* options find the minimum or maximum +value across all absolute vector values. The *ave* setting adds the +vector values into a global total, then divides by the number of values +in the vector. The *sumsq* option sums the square of the values in the +vector into a global total. The *avesq* setting does the same as *sumsq*, +then divides the sum of squares by the number of values. The last two options +can be useful for calculating the variance of some quantity (e.g., variance = sumsq :math:`-` ave\ :math:`^2`). The *sumabs* option sums the absolute values in the vector into a global total. The *aveabs* setting does the same as *sumabs*, then divides the sum of absolute values by the number of diff --git a/doc/src/compute_saed.rst b/doc/src/compute_saed.rst index c2e1f3d1e0..deb6a61f7c 100644 --- a/doc/src/compute_saed.rst +++ b/doc/src/compute_saed.rst @@ -246,8 +246,9 @@ All array values calculated by this compute are "intensive". Restrictions """""""""""" -This compute is part of the DIFFRACTION package. It is only -enabled if LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +This compute is part of the DIFFRACTION package. It is only enabled if +LAMMPS was built with that package. See the :doc:`Build package +` page for more info. The compute_saed command does not work for triclinic cells. diff --git a/doc/src/compute_stress_profile.rst b/doc/src/compute_stress_profile.rst index cb4628bd5d..7a4b6a38e6 100644 --- a/doc/src/compute_stress_profile.rst +++ b/doc/src/compute_stress_profile.rst @@ -136,12 +136,12 @@ More information on the similarities and differences can be found in Restrictions """""""""""" -These computes calculate the stress tensor contributions for pair -styles only (i.e., no bond, angle, dihedral, etc. contributions, and in -the presence of bonded interactions, the result will be incorrect due to -exclusions for special bonds) and requires pairwise force calculations -not available for most many-body pair styles. -Note that :math:`k`-space calculations are also excluded. +These computes calculate the stress tensor contributions for pair styles +only (i.e., no bond, angle, dihedral, etc. contributions, and in the +presence of bonded interactions, the result may be incorrect due to +exclusions for :doc:`special bonds ` excluding pairs of atoms +completely). It requires pairwise force calculations not available for most +many-body pair styles. Note that :math:`k`-space calculations are also excluded. These computes are part of the EXTRA-COMPUTE package. They are only enabled if LAMMPS was built with that package. See the :doc:`Build diff --git a/doc/src/compute_tally.rst b/doc/src/compute_tally.rst index 6eff1e186e..fe2cbe7cca 100644 --- a/doc/src/compute_tally.rst +++ b/doc/src/compute_tally.rst @@ -187,16 +187,22 @@ Both the scalar and vector values calculated by this compute are Restrictions """""""""""" -This compute is part of the TALLY package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +This compute is part of the TALLY package. It is only enabled if LAMMPS +was built with that package. See the :doc:`Build package +` page for more info. Not all pair styles can be evaluated in a pairwise mode as required by -this compute. For example, 3-body and other many-body potentials, -such as :doc:`Tersoff ` and -:doc:`Stillinger-Weber ` cannot be used. :doc:`EAM ` -potentials only include the pair potential portion of the EAM -interaction when used by this compute, not the embedding term. Also -bonded or Kspace interactions do not contribute to this compute. +this compute. For example, 3-body and other many-body potentials, such +as :doc:`Tersoff ` and :doc:`Stillinger-Weber ` +cannot be used. :doc:`EAM ` potentials only include the pair +potential portion of the EAM interaction when used by this compute, not +the embedding term. Also bonded or Kspace interactions do not +contribute to this compute. + +These computes are not compatible with accelerated pair styles from the +GPU, INTEL, KOKKOS, or OPENMP packages. They will either create an error +or print a warning when required data was not tallied in the required way +and thus the data acquisition functions from these computes not called. When used with dynamic groups, a :doc:`run 0 ` command needs to be inserted in order to initialize the dynamic groups before accessing diff --git a/doc/src/dump_molfile.rst b/doc/src/dump_molfile.rst index f8cc06d039..ffc0b443e0 100644 --- a/doc/src/dump_molfile.rst +++ b/doc/src/dump_molfile.rst @@ -63,7 +63,7 @@ like element names. The *path* keyword determines which in directories. This is a "path" like other search paths, i.e. it can contain multiple directories -separated by a colon (or semi-colon on windows). This keyword is +separated by a colon (or semicolon on Windows). This keyword is optional and default to ".", the current directory. The *unwrap* option of the :doc:`dump_modify ` command allows diff --git a/doc/src/fix.rst b/doc/src/fix.rst index cc17ebec39..cdf6be866b 100644 --- a/doc/src/fix.rst +++ b/doc/src/fix.rst @@ -256,13 +256,13 @@ accelerated styles exist. * :doc:`langevin/drude ` - Langevin temperature control of Drude oscillators * :doc:`langevin/eff ` - Langevin temperature control for the electron force field model * :doc:`langevin/spin ` - Langevin temperature control for a spin or spin-lattice system -* :doc:`latte ` - wrapper on LATTE density-functional tight-binding code * :doc:`lb/fluid ` - lattice-Boltzmann fluid on a uniform mesh * :doc:`lb/momentum ` - :doc:`fix momentum ` replacement for use with a lattice-Boltzmann fluid * :doc:`lb/viscous ` - :doc:`fix viscous ` replacement for use with a lattice-Boltzmann fluid * :doc:`lineforce ` - constrain atoms to move in a line * :doc:`manifoldforce ` - restrain atoms to a manifold during minimization -* :doc:`mdi/qm ` - LAMMPS operates as driver for a quantum code via the MolSSI Driver Interface (MDI) +* :doc:`mdi/qm ` - LAMMPS operates as a client for a quantum code via the MolSSI Driver Interface (MDI) +* :doc:`mdi/qmmm ` - LAMMPS operates as client for QM/MM simulation with a quantum code via the MolSSI Driver Interface (MDI) * :doc:`meso/move ` - move mesoscopic SPH/SDPD particles in a prescribed fashion * :doc:`mol/swap ` - Monte Carlo atom type swapping with a molecule * :doc:`momentum ` - zero the linear and/or angular momentum of a group of atoms diff --git a/doc/src/fix_adapt.rst b/doc/src/fix_adapt.rst index 926b8ed0c6..86eec3eadb 100644 --- a/doc/src/fix_adapt.rst +++ b/doc/src/fix_adapt.rst @@ -133,6 +133,8 @@ formulas for the meaning of these parameters: +------------------------------------------------------------------------------+--------------------------------------------------+-------------+ | :doc:`born/coul/long, born/coul/msm ` | coulombic_cutoff | type global | +------------------------------------------------------------------------------+--------------------------------------------------+-------------+ +| :doc:`born/gauss ` | biga0,biga1,r0 | type pairs | ++------------------------------------------------------------------------------+--------------------------------------------------+-------------+ | :doc:`buck, buck/coul/cut ` | a,c | type pairs | +------------------------------------------------------------------------------+--------------------------------------------------+-------------+ | :doc:`buck/coul/long, buck/coul/msm ` | a,c,coulombic_cutoff | type pairs | @@ -161,6 +163,8 @@ formulas for the meaning of these parameters: +------------------------------------------------------------------------------+--------------------------------------------------+-------------+ | :doc:`harmonic/cut ` | k, cutoff | type pairs | +------------------------------------------------------------------------------+--------------------------------------------------+-------------+ +| :doc:`kim ` | scale | type global | ++------------------------------------------------------------------------------+--------------------------------------------------+-------------+ | :doc:`lennard/mdf ` | A,B | type pairs | +------------------------------------------------------------------------------+--------------------------------------------------+-------------+ | :doc:`lj/class2 ` | epsilon,sigma | type pairs | diff --git a/doc/src/fix_alchemy.rst b/doc/src/fix_alchemy.rst index 367b6d1cca..4f0ad06fd4 100644 --- a/doc/src/fix_alchemy.rst +++ b/doc/src/fix_alchemy.rst @@ -24,7 +24,7 @@ Examples Description """"""""""" -.. versionadded:: TBD +.. versionadded:: 28Mar2023 This fix command enables an "alchemical transformation" to be performed between two systems, whereby one system slowly transforms into the other diff --git a/doc/src/fix_ave_correlate_long.rst b/doc/src/fix_ave_correlate_long.rst index d5120b1af5..e2b23248f2 100644 --- a/doc/src/fix_ave_correlate_long.rst +++ b/doc/src/fix_ave_correlate_long.rst @@ -15,7 +15,7 @@ Syntax * Nevery = use input values every this many time steps * Nfreq = save state of the time correlation functions every this many time steps * one or more input values can be listed -* value = c_ID, c_ID[N], f_ID, f_ID[N], v_name +* value = c_ID, c_ID[N], f_ID, f_ID[N], v_name, v_name[I] .. parsed-literal:: @@ -24,6 +24,7 @@ Syntax f_ID = global scalar calculated by a fix with ID f_ID[I] = Ith component of global vector calculated by a fix with ID v_name = global value calculated by an equal-style variable with name + v_name[I] = Ith component of global vector calculated by a vector-style variable with name * zero or more keyword/arg pairs may be appended * keyword = *type* or *start* or *file* or *overwrite* or *title1* or *title2* or *ncorr* or *nlen* or *ncount* diff --git a/doc/src/fix_dpd_source.rst b/doc/src/fix_dpd_source.rst index ef1a70c3d4..ade9659d00 100644 --- a/doc/src/fix_dpd_source.rst +++ b/doc/src/fix_dpd_source.rst @@ -18,18 +18,21 @@ Syntax * ID, group-ID are documented in :doc:`fix ` command * edpd/source or tdpd/source = style name of this fix command * index (only specified for tdpd/source) = index of chemical species (1 to Nspecies) -* keyword = *sphere* or *cuboid* +* keyword = *sphere* or *cuboid* or *region* .. parsed-literal:: - *sphere* values = cx,cy,cz,radius,source + *sphere* args = cx cy cz radius source cx,cy,cz = x,y,z center of spherical domain (distance units) radius = radius of a spherical domain (distance units) source = heat source or concentration source (flux units, see below) - *cuboid* values = cx,cy,cz,dLx,dLy,dLz,source - cx,cy,cz = x,y,z lower left corner of a cuboid domain (distance units) + *cuboid* values = cx cy cz dLx dLy dLz source + cx,cy,cz = x,y,z center of a cuboid domain (distance units) dLx,dLy,dLz = x,y,z side length of a cuboid domain (distance units) source = heat source or concentration source (flux units, see below) + *region* values = region-ID source + region = ID of region for heat or concentration source + source = heat source or concentration source (flux units, see below) Examples """""""" @@ -40,6 +43,7 @@ Examples fix 1 all edpd/source cuboid 0.0 0.0 0.0 20.0 10.0 10.0 -0.01 fix 1 all tdpd/source 1 sphere 5.0 0.0 0.0 5.0 0.01 fix 1 all tdpd/source 2 cuboid 0.0 0.0 0.0 20.0 10.0 10.0 0.01 + fix 1 all tdpd/source 1 region lower -0.01 Description """"""""""" @@ -57,37 +61,50 @@ heat conduction with a source term (see Fig.12 in :ref:`(Li2014) `) or diffusion with a source term (see Fig.1 in :ref:`(Li2015) `), as an analog of a periodic Poiseuille flow problem. -If the *sphere* keyword is used, the *cx,cy,cz,radius* defines a -spherical domain to apply the source flux to. +.. deprecated:: TBD -If the *cuboid* keyword is used, the *cx,cy,cz,dLx,dLy,dLz* defines a -cuboid domain to apply the source flux to. + The *sphere* and *cuboid* keywords will be removed in a future version + of LAMMPS. The same functionality and more can be achieved with a region. + +If the *sphere* keyword is used, the *cx, cy, cz, radius* values define +a spherical domain to apply the source flux to. + +If the *cuboid* keyword is used, the *cx, cy, cz, dLx, dLy, dLz* define +a cuboid domain to apply the source flux to. + +If the *region* keyword is used, the *region-ID* selects which +:doc:`region ` to apply the source flux to. ---------- Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" -No information about this fix is written to :doc:`binary restart files `. None of the :doc:`fix_modify ` options -are relevant to this fix. No global or per-atom quantities are stored -by this fix for access by various :doc:`output commands `. -No parameter of this fix can be used with the *start/stop* keywords of -the :doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. +No information of these fixes is written to :doc:`binary restart files +`. None of the :doc:`fix_modify ` options are +relevant to these fixes. No global or per-atom quantities are stored by +these fixes for access by various :doc:`output commands `. +No parameter of these fixes can be used with the *start/stop* keywords +of the :doc:`run ` command. These fixes are not invoked during +:doc:`energy minimization `. Restrictions """""""""""" -This fix is part of the DPD-MESO package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +These fixes are part of the DPD-MESO package. They are only enabled if +LAMMPS was built with that package. See the :doc:`Build package +` page for more info. -Fix *edpd/source* must be used with the :doc:`pair_style edpd ` command. Fix *tdpd/source* must be used with the +Fix *edpd/source* must be used with the :doc:`pair_style edpd +` command. Fix *tdpd/source* must be used with the :doc:`pair_style tdpd ` command. Related commands """""""""""""""" :doc:`pair_style edpd `, :doc:`pair_style tdpd `, -:doc:`compute edpd/temp/atom `, :doc:`compute tdpd/cc/atom ` +:doc:`compute edpd/temp/atom `, +:doc:`compute tdpd/cc/atom ` Default """"""" diff --git a/doc/src/fix_efield.rst b/doc/src/fix_efield.rst index eebfaba8c6..e72510e4da 100644 --- a/doc/src/fix_efield.rst +++ b/doc/src/fix_efield.rst @@ -45,7 +45,7 @@ external electric field being applied to the system. If the system contains point-dipoles, also add a torque on the dipoles due to the external electric field. -.. versionadded:: TBD +.. versionadded:: 28Mar2023 When the *efield/tip4p* style is used, the E-field will be applied to the position of the virtual charge site M of a TIP4P molecule instead of diff --git a/doc/src/fix_indent.rst b/doc/src/fix_indent.rst index bb4b450c94..c8349e9381 100644 --- a/doc/src/fix_indent.rst +++ b/doc/src/fix_indent.rst @@ -19,7 +19,7 @@ Syntax .. parsed-literal:: *sphere* args = x y z R - x,y,z = initial position of center of indenter (distance units) + x,y,z = position of center of indenter (distance units) R = sphere radius of indenter (distance units) any of x,y,z,R can be a variable (see below) *cylinder* args = dim c1 c2 R diff --git a/doc/src/fix_latte.rst b/doc/src/fix_latte.rst deleted file mode 100644 index de3ac5adde..0000000000 --- a/doc/src/fix_latte.rst +++ /dev/null @@ -1,269 +0,0 @@ -.. index:: fix latte - -fix latte command -================= - -Syntax -"""""" - -.. parsed-literal:: - - fix ID group-ID latte keyword value ... - -* ID, group-ID are documented in :doc:`fix ` command -* latte = style name of this fix command -* zero or more keyword/value pairs may be appended - - .. parsed-literal:: - - keyword = *coulomb* or *exclude* - *coulomb* value = peID - peID = ID of compute used to calculate per-atom energy - *exclude* value = fixID - fixID = ID of fix which potentially excludes atoms before calling LATTE - -Examples -"""""""" - -.. code-block:: LAMMPS - - fix dftb all latte - fix dftb all exclude GCMC - -Description -""""""""""" - -This fix style is a wrapper on the self-consistent charge transfer -density functional based tight binding (DFTB) code LATTE. If you -download and build LATTE, it can be called as a library by LAMMPS via -this fix to run dynamics or perform energy minimization using DFTB -forces and energies computed by LATTE. - -LATTE is principally developed and supported by Marc Cawkwell and -co-workers at Los Alamos National Laboratory (LANL). See the full -list of contributors in the src/LATTE/README file. - -To use this fix, the LATTE program needs to be compiled as a library -and linked with LAMMPS. LATTE can be downloaded (or cloned) from -`https://github.com/lanl/LATTE `_. -Instructions on how to download and build LATTE on your system can be -found in the lib/latte/README. Note that you can also use the "make -lib-latte" command from the LAMMPS src directory to automate this -process. - -Once LAMMPS is built with the LATTE package, you can run the example -input scripts for molecular dynamics or energy minimization that are -found in examples/latte. - -A step-by-step tutorial can be followed at: `LAMMPS-LATTE tutorial `_ - -Currently, LAMMPS must be run in serial or as a single MPI task, to -use this fix. This is because the version of the LATTE library LAMMPS -uses does not support MPI. On the LAMMPS size, this is typically not -a bottleneck, since LATTE will be doing 99% or more of the work to -compute quantum-accurate forces. On the LATTE side, the LATTE library -does support threaded parallelism via OpenMP. You must build the -LATTE library with OpenMP support, then set the OMP_NUM_THREADS -environment variable before performing a LAMMPS + LATTE simulation to -tell LATTE how many threads to invoke. - -.. note:: - - NEB calculations can be done using this fix using multiple - replicas and running LAMMPS in parallel. However, each replica must - be run on a single MPI task. For details, see the :doc:`neb ` - command page and the :doc:`-partition command-line switch ` - ----------- - -The *coulomb* argument is not yet supported by fix latte (as of Sept -2022). Eventually it will be used to enable LAMMPS to calculate a -Coulomb potential as an alternative to LATTE performing the -calculation. - -.. versionadded:: 15Sep2022 - -The *exclude* argument allows this fix to work in tandem with another -fix which may decide to delete one or more atoms of molecules. The -specified fixID is the ID of the other fix. - -The one current example of such a fix is the :doc:`fix gcmc -` command which performs Monte Carlo insertions and -deletions. If a trial deletion is performed, then LAMMPS needs to -only pass LATTE the atoms which remain. Fix gcmc does not actually -remove any atoms until after the new energy is computed (in this case -by LATTE), and a Monte Carlo accept/reject decision is made for the -trial deletion. - ----------- - -LATTE is a code for performing self-consistent charge transfer -tight-binding (SC-TB) calculations of total energies and the forces -acting on atoms in molecules and solids. This tight-binding method is -becoming more and more popular and widely used in chemistry, -biochemistry, material science, etc. - -The SC-TB formalism is derived from an expansion of the Kohn-Sham -density functional to second order in charge fluctuations about a -reference charge of overlapping atom-centered densities and bond -integrals are parameterized using a Slater-Koster tight-binding -approach. This procedure, which usually is referred to as the DFTB -method has been described in detail by (:ref:`Elstner `) and -(:ref:`Finnis `) and coworkers. - -The work of the LATTE developers follows that of Elstner closely with -respect to the physical model. However, the development of LATTE is -geared principally toward large-scale, long duration, microcanonical -quantum-based Born-Oppenheimer molecular dynamics (QMD) simulations. -One of the main bottlenecks of an electronic structure calculation is -the solution of the generalized eigenvalue problem which scales with -the cube of the system size O(N\^3). - -The Theoretical and Computer sciences divisions at Los Alamos National -Laboratory have accumulated large experience addressing this issue by -calculating the density matrix directly instead of using -diagonalization. We typically use a recursive sparse Fermi-operator -expansion using second-order spectral projection functions -(SP2-algorithm), which was introduced by Niklasson in 2002 -(:ref:`Niklasson2002 `), (:ref:`Rubensson `), -(:ref:`Mniszewski `). When the matrices involved in the -recursive expansion are sufficiently sparse, the calculation of the -density matrix scales linearly as a function of the system size O(N). - -Another important feature is the extended Lagrangian framework for -Born-Oppenheimer molecular dynamics (XL-BOMD) -(:ref:`Niklasson2008 `) (:ref:`Niklasson2014 `), -(:ref:`Niklasson2017 `) that allows for a drastic reduction -or even a complete removal of the iterative self-consistent field -optimization. Often only a single density matrix calculation per -molecular dynamics time step is required, yet total energy stability -is well maintained. The SP2 and XL-BOMD techniques enables stable -linear scaling MD simulations with a very small computational -overhead. This opens a number of opportunities in many different -areas of chemistry and materials science, as we now can simulate -larger system sizes and longer time scales -(:ref:`Cawkwell2012 `), (:ref:`Negre2016 `). - ----------- - -Restart, fix_modify, output, run start/stop, minimize info -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -No information about this fix is written to :doc:`binary restart files -`. - -The :doc:`fix_modify ` *energy* option is supported by -this fix to add the potential energy computed by LATTE to the global -potential energy of the system as part of :doc:`thermodynamic output -`. The default setting for this fix is :doc:`fix_modify -energy yes `. - -The :doc:`fix_modify ` *virial* option is supported by -this fix to add the contribution computed by LATTE to the global -pressure of the system as part of :doc:`thermodynamic output -`. The default setting for this fix is :doc:`fix_modify -virial yes `. - -This fix computes a global scalar which can be accessed by various -:doc:`output commands `. The scalar is the potential -energy discussed above. The scalar value calculated by this fix is -"extensive". - -No parameter of this fix can be used with the *start/stop* keywords of -the :doc:`run ` command. - -The DFTB forces computed by LATTE via this fix are used during an -energy minimization, invoked by the :doc:`minimize ` -command. - -.. note:: - - If you want the potential energy associated with the DFTB - forces to be included in the total potential energy of the system (the - quantity being minimized), you MUST not disable the - :doc:`fix_modify ` *energy* option for this fix. - -Restrictions -"""""""""""" - -This fix is part of the LATTE package. It is only enabled if LAMMPS -was built with that package. See the :doc:`Build package -` page for more info. - -You must use metal units, as set by the :doc:`units ` command to -use this fix. - -LATTE does not currently compute per-atom energy or per-atom virial -contributions. So they will not show up as part of the calculations -performed by the :doc:`compute pe/atom ` or -:doc:`compute stress/atom ` commands. - -Related commands -"""""""""""""""" - -none - - -Default -""""""" - -none - ----------- - -.. _Elstner: - -**(Elstner)** M. Elstner, D. Poresag, G. Jungnickel, J. Elsner, -M. Haugk, T. Frauenheim, S. Suhai, and G. Seifert, Phys. Rev. B, 58, -7260 (1998). - -.. _Elstner1: - -**(Elstner)** M. Elstner, D. Poresag, G. Jungnickel, J. Elsner, -M. Haugk, T. Frauenheim, S. Suhai, and G. Seifert, Phys. Rev. B, 58, -7260 (1998). - -.. _Finnis2: - -**(Finnis)** M. W. Finnis, A. T. Paxton, M. Methfessel, and M. van -Schilfgarde, Phys. Rev. Lett., 81, 5149 (1998). - -.. _Mniszewski: - -**(Mniszewski)** S. M. Mniszewski, M. J. Cawkwell, M. E. Wall, -J. Mohd-Yusof, N. Bock, T. C. Germann, and A. M. N. Niklasson, -J. Chem. Theory Comput., 11, 4644 (2015). - -.. _Niklasson2002: - -**(Niklasson2002)** A. M. N. Niklasson, Phys. Rev. B, 66, 155115 (2002). - -.. _Rubensson: - -**(Rubensson)** E. H. Rubensson, A. M. N. Niklasson, SIAM -J. Sci. Comput. 36 (2), 147-170, (2014). - -.. _Niklasson2008: - -**(Niklasson2008)** A. M. N. Niklasson, Phys. Rev. Lett., 100, 123004 -(2008). - -.. _Niklasson2014: - -**(Niklasson2014)** A. M. N. Niklasson and M. Cawkwell, J. Chem. Phys., -141, 164123, (2014). - -.. _Niklasson2017: - -**(Niklasson2017)** A. M. N. Niklasson, J. Chem. Phys., 147, 054103 (2017). - -.. _Cawkwell2012: - -**(Cawkwell2012)** A. M. N. Niklasson, M. J. Cawkwell, Phys. Rev. B, 86 -(17), 174308 (2012). - -.. _Negre2016: - -**(Negre2016)** C. F. A. Negre, S. M. Mniszewski, M. J. Cawkwell, -N. Bock, M. E. Wall, and A. M. N. Niklasson, J. Chem. Theory Comp., -12, 3063 (2016). diff --git a/doc/src/fix_mdi_qm.rst b/doc/src/fix_mdi_qm.rst index 411231dc04..3d0b350407 100644 --- a/doc/src/fix_mdi_qm.rst +++ b/doc/src/fix_mdi_qm.rst @@ -8,12 +8,12 @@ Syntax .. parsed-literal:: - fix ID group-ID mdi/qm keyword + fix ID group-ID mdi/qm keyword value(s) keyword value(s) ... * ID, group-ID are documented in :doc:`fix ` command * mdi/qm = style name of this fix command * zero or more keyword/value pairs may be appended -* keyword = *virial* or *add* or *every* or *connect* or *elements* +* keyword = *virial* or *add* or *every* or *connect* or *elements* or *mc* .. parsed-literal:: @@ -29,7 +29,9 @@ Syntax yes = perform a one-time connection to the MDI engine code no = do not perform the connection operation *elements* args = N_1 N_2 ... N_ntypes - N_1,N_2,...N_ntypes = atomic number for each of ntypes LAMMPS atom types + N_1,N_2,...N_ntypes = chemical symbol for each of ntypes LAMMPS atom types + *mc* args = mcfixID + mcfixID = ID of a Monte Carlo fix designed to work with this fix Examples """""""" @@ -38,7 +40,7 @@ Examples fix 1 all mdi/qm fix 1 all mdi/qm virial yes - fix 1 all mdi/qm add no every 100 elements 13 29 + fix 1 all mdi/qm add no every 100 elements C C H O Description """"""""""" @@ -57,12 +59,27 @@ The server code must support use of the `MDI Library `_ as explained below. +Typically, to use this fix, the input script should not define any +other classical force field components, e.g. a pair style, bond style, +etc. + These are example use cases for this fix, discussed further below: * perform an ab initio MD (AIMD) simulation with quantum forces * perform an energy minimization with quantum forces * perform a nudged elastic band (NEB) calculation with quantum forces -* perform a QM calculation for a series of independent systems which LAMMPS reads or generates +* perform a QM calculation for a series of independent systems which + LAMMPS reads or generates once +* run a classical MD simulation and calculate QM energy/forces once + every N steps on the current configuration + +More generally any command which calculates per-atom forces can instead +use quantum forces by defining this fix. Examples are the Monte Carlo +commands :doc:`fix gcmc ` and :doc:`fix atom/swap +`, as well as the :doc:`compute born/matrix +` command. The only requirement is that internally +the command invokes the post_force() method of fixes such as this one, +which will trigger the quantum calculation. The code coupling performed by this command is done via the `MDI Library `_. @@ -72,27 +89,32 @@ for MDI. See the :doc:`Howto mdi ` page for more information about how LAMMPS can operate as either an MDI driver or engine. -The examples/mdi directory contains input scripts using this fix in +The ``examples/mdi`` directory contains input scripts using this fix in the various use cases discussed below. In each case, two instances of -LAMMPS are used, once as an MDI driver, once as an MDI engine -(surrogate for a QM code). The examples/mdi/README file explains how -to launch two codes so that they communicate via the MDI library using -either MPI or sockets. Any QM code that supports MDI could be used in -place of LAMMPS acting as a QM surrogate. See the :doc:`Howto mdi -` page for a current list (March 2022) of such QM codes. +LAMMPS are used, once as an MDI driver, once as an MDI engine (surrogate +for a QM code). The ``examples/mdi/README`` file explains how to launch +two codes so that they communicate via the MDI library using either MPI +or sockets. Any QM code that supports MDI could be used in place of +LAMMPS acting as a QM surrogate. See the :doc:`Howto mdi ` +page for a current list (March 2022) of such QM codes. The +``examples/QUANTUM`` directory has examples for coupling LAMMPS to 3 QM +codes either via this fix or the :doc:`fix mdi/qmmm ` +command. -Note that an engine code can support MDI in either or both of two -modes. It can be used as a stand-alone code, launched at the same -time as LAMMPS. Or it can be used as a plugin library, which LAMMPS -loads. See the :doc:`mdi plugin ` command for how to trigger -LAMMPS to load a plugin library. The examples/mdi/README file -explains how to launch the two codes in either mode. +Note that an engine code can support MDI in either or both of two modes. +It can be used as a stand-alone code, launched at the same time as +LAMMPS. Or it can be used as a plugin library, which LAMMPS loads. See +the :doc:`mdi plugin ` command for how to trigger LAMMPS to load a +plugin library. The ``examples/mdi/README`` file and +``examples/QUANTUM/QM-code/README`` files explain how to launch the two +codes in either mode. ---------- -The *virial* keyword setting of yes or no determines whether -LAMMPS will request the QM code to also compute and return -a 6-element symmetric virial tensor for the system. +The *virial* keyword setting of yes or no determines whether LAMMPS +will request the QM code to also compute and return the QM +contribution to a stress tensor for the system which LAMMPS will +convert to a 6-element symmetric virial tensor. The *add* keyword setting of *yes* or *no* determines whether the energy and forces and virial returned by the QM code will be added to @@ -109,25 +131,27 @@ commands. See details below. The *every* keyword determines how often the QM code will be invoked during a dynamics run with the current LAMMPS simulation box and configuration of atoms. The QM code will be called once every -*Nevery* timesteps. +*Nevery* timesteps. By default *Nevery* = 1. The *connect* keyword determines whether this fix performs a one-time -connection to the QM code. The default is *yes*. The only time a -*no* is needed is if this command is used multiple times in an input -script. E.g. if it used inside a loop which also uses the :doc:`clear -` command to destroy the system (including any defined fixes). -See the examples/mdi/in.series.driver script as an example of this, -where LAMMPS is using the QM code to compute energy and forces for a -series of system configurations. In this use case *connect no* -is used along with the :doc:`mdi connect and exit ` command -to one-time initiate/terminate the connection outside the loop. +connection to the QM code. The default is *yes*. The only time a *no* +is needed is if this command is used multiple times in an input script +and the MDI coupling is between two stand-alone codes (not plugin mode). +E.g. if it used inside a loop which also uses the :doc:`clear ` +command to destroy the system (including this fix). See the +``examples/mdi/in.series.driver`` script as an example of this, where +LAMMPS is using the QM code to compute energy and forces for a series of +system configurations. In this use case *connect no* is used along with +the :doc:`mdi connect and exit ` command to one-time +initiate/terminate the connection outside the loop. The *elements* keyword allows specification of what element each -LAMMPS atom type corresponds to. This is specified by the atomic -number of the element, e.g. 13 for Al. An atomic number must be -specified for each of the ntypes LAMMPS atom types. Ntypes is -typically specified via the create_box command or in the data file -read by the read_data command. +LAMMPS atom type corresponds to. This is specified by the chemical +symbol of the element, e.g. C or Al or Si. A symbol must be specified +for each of the ntypes LAMMPS atom types. Multiple LAMMPS types can +represent the same element. Ntypes is typically specified via the +:doc:`create_box ` command or in the data file read by the +:doc:`read_data ` command. If this keyword is specified, then this fix will send the MDI ">ELEMENTS" command to the engine, to ensure the two codes are @@ -136,10 +160,18 @@ not specified, then this fix will send the MDI >TYPES command to the engine. This is fine if both the LAMMPS driver and the MDI engine are initialized so that the atom type values are consistent in both codes. +The *mc* keyword enables this fix to be used with a Monte Carlo (MC) +fix to calculate before/after quantum energies as part of the MC +accept/reject criterion. The :doc:`fix gcmc ` and :doc:`fix +atom/swap ` commands can be used in this manner. +Specify the ID of the MC fix following the *mc* keyword. This allows +the two fixes to coordinate when MC events are being calculated versus +MD timesteps between the MC events. + ---------- -The following 3 example use cases are illustrated in the examples/mdi -directory. See its README file for more details. +The following 3 example use cases are illustrated in the +``examples/mdi`` directory. See its README file for more details. (1) To run an ab initio MD (AIMD) dynamics simulation, or an energy minimization with QM forces, or a multi-replica NEB calculation, use @@ -248,29 +280,31 @@ invoked by the :doc:`minimize ` command. Restrictions """""""""""" -This command is part of the MDI package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package +This fix is part of the MDI package. It is only enabled if LAMMPS +was built with that package. See the :doc:`Build package ` page for more info. -The QM code does not currently compute and return per-atom energy or -per-atom virial contributions. So they will not show up as part of -the calculations performed by the :doc:`compute pe/atom -` or :doc:`compute stress/atom ` -commands. - To use LAMMPS as an MDI driver in conjunction with other MDI-enabled -codes (MD or QM codes), the :doc:`units ` command should be -used to specify *real* or *metal* units. This will ensure the correct -unit conversions between LAMMPS and MDI units. The other code will -also perform similar unit conversions into its preferred units. +codes (MD or QM codes), the :doc:`units ` command should be used +to specify *real* or *metal* units. This will ensure the correct unit +conversions between LAMMPS and MDI units. The other code will also +perform similar unit conversions into its preferred units. LAMMPS can also be used as an MDI driver in other unit choices it -supports, e.g. *lj*, but then no unit conversion is performed. +supports, e.g. *lj*, but then no unit conversion to MDI units is +performed. + +If this fix is used in conjunction with a QM code that does not support +periodic boundary conditions (more specifically, a QM code that does not +support the ``>CELL`` MDI command), the LAMMPS system must be fully +non-periodic. I.e. no dimension of the system can be periodic. Related commands """""""""""""""" -:doc:`mdi plugin `, :doc:`mdi engine ` +:doc:`mdi plugin `, +:doc:`mdi engine `, +:doc:`fix mdi/qmmm ` Default """"""" diff --git a/doc/src/fix_mdi_qmmm.rst b/doc/src/fix_mdi_qmmm.rst new file mode 100644 index 0000000000..1afce0f7e4 --- /dev/null +++ b/doc/src/fix_mdi_qmmm.rst @@ -0,0 +1,279 @@ +.. index:: fix mdi/qmmm + +fix mdi/qmmm command +==================== + +Syntax +"""""" + +.. parsed-literal:: + + fix ID group-ID mdi/qmmm mode keyword value(s) keyword value(s) ... + +* ID, group-ID are documented in :doc:`fix ` command +* mdi/qmmm = style name of this fix command +* mode = *direct* or *potential* +* zero or more keyword/value pairs may be appended +* keyword = *virial* or *add* or *every* or *connect* or *elements* + + .. parsed-literal:: + + *virial* args = *yes* or *no* + yes = request virial tensor from server code + no = do not request virial tensor from server code + *connect* args = *yes* or *no* + yes = perform a one-time connection to the MDI engine code + no = do not perform the connection operation + *elements* args = N_1 N_2 ... N_ntypes + N_1,N_2,...N_ntypes = chemical symbol for each of ntypes LAMMPS atom types + +Examples +"""""""" + +.. code-block:: LAMMPS + + fix 1 all mdi/qmmm direct + fix 1 all mdi/qmmm potential virial yes + fix 1 all mdi/qmmm potential virial yes elements 13 29 + +Description +""""""""""" + +.. versionadded:: 28Mar2023 + +This command enables LAMMPS to act as a client with another server code +to perform a coupled QM/MM (quantum-mechanics/molecular-mechanics) +simulation. LAMMPS will perform classical MD (molecular mechanics +or MM) for the (typically larger) MM portion of the system. A quantum +mechanics code will calculate quantum energy and forces for the QM +portion of the system. The two codes work together to calculate the +energy and forces due to the cross interactions between QM and MM atoms. +The QM server code must support use of the `MDI Library +`_ as +explained below. + +The partitioning of the system between QM and MM atoms is as follows. +Atoms in the specified group are QM atoms; the remaining atoms are MM +atoms. The input script should thus define this partitioning. +See additional information below about other requirements for an input +script to use this fix and perform a QM/MM simulation. + +The code coupling performed by this command is done via the `MDI +Library `_. +LAMMPS runs as an MDI driver (client), and sends MDI commands to an +external MDI engine code (server), in this case a QM code which has +support for MDI. See the :doc:`Howto mdi ` page for more +information about how LAMMPS can operate as either an MDI driver or +engine. + +The ``examples/QUANTUM`` directory has sub-directories with example +input scripts using this fix in tandem with different QM codes. The +README files in the sub-directories explain how to download and build +the various QM codes. They also explain how to launch LAMMPS and the QM +code so that they communicate via the MDI library using either MPI or +sockets. Any QM code that supports MDI could be used in addition to +those discussed in the sub-directories. See the :doc:`Howto mdi +` page for a current list (March 2022) of such QM codes. + +Note that an engine code can support MDI in either or both of two modes. +It can be used as a stand-alone code, launched at the same time as +LAMMPS. Or it can be used as a plugin library, which LAMMPS loads. See +the :doc:`mdi plugin ` command for how to trigger LAMMPS to load a +plugin library. The ``examples/QUANTUM`` sub-directory README files +explains how to launch the two codes in either mode. + +---------- + +The *mode* setting determines which QM/MM coupling algorithm is used. +LAMMPS currently supports *direct* and *potential* algorithms, based +on the *mode* setting. Both algorithms should give reasonably +accurate results, but some QM codes support only one of the two modes. +E.g. in the ``examples/QUANTUM`` directory, PySCF supports only *direct*, +NWChem supports only *potential*, and LATTE currently supports +neither, so it cannot be used for QM/MM simulations using this fix. + +The *direct* option passes the coordinates and charges of each MM atom +to the quantum code, in addition to the coordinates of each QM atom. +The quantum code returns forces on each QM atom as well as forces on +each MM atom. The latter is effectively the force on MM atoms due to +the QM atoms. + +The input script for performing a *direct* mode QM/MM simulation should +do the following: + +* delete all bonds (angles, dihedrals, etc) between QM atoms +* set the charge on each QM atom to zero +* define no bonds (angles, dihedrals, etc) which involve both QM and MM atoms +* define a force field (pair, bonds, angles, optional kspace) for the entire system + +The first two bullet can be performed using the :doc:`delete_bonds +` and :doc:`set ` commands. + +The third bullet is required to have a consistent model, but is not +checked by LAMMPS. + +The fourth bullet implies that non-bonded non-Coulombic interactions +(e.g. van der Waals) between QM/QM and QM/MM pairs of atoms are +computed by LAMMPS. + +See the ``examples/QUANTUM/PySCF/in.*`` files for examples of input +scripts for QM/MM simulations using the *direct* mode. + +The *potential* option passes the coordinates of each QM atom and a +Coulomb potential for each QM atom to the quantum code. The latter is +calculated by performing a Coulombics-only calculation for the entire +system, subtracting all QM/QM pairwise Coulombic terms, and dividing +the Coulomb energy on each QM atom by the charge of the QM atom. The +potential value represents the Coulombic influence of all the MM atoms +on each QM atom. + +The quantum code returns forces and charge on each QM atom. The new +charges on the QM atom are used to re-calculate the MM force field, +resulting in altered forces on the MM atoms. + +The input script for performing a *potential* mode QM/MM simulation +should do the following: + +* delete all bonds (angles, dihedrals, etc) between QM atoms +* define a hybrid pair style which includes a Coulomb-only pair sub-style +* define no bonds (angles, dihedrals, etc) which involve both QM and MM atoms +* define a force field (pair, bonds, angles, optional kspace) for the entire system + +The first operation can be performed using the :doc:`delete_bonds +` command. See the ``examples/QUANTUM/NWChem/in.*`` files +for examples of how to do this. + +The second operation is necessary so that this fix can calculate the +Coulomb potential for the QM atoms. + +The third bullet is required to have a consistent model, but is not +checked by LAMMPS. + +The fourth bullet implies that non-bonded non-Coulombic interactions +(e.g. van der Waals) between QM/QM and QM/MM pairs of atoms are computed +by LAMMPS. However, some QM codes do not want the MM code (LAMMPS) to +compute QM/QM van der Waals interactions. NWChem is an example. In +this case, the coefficients for those interactions need to be turned +off, which typically requires the atom types for the QM atoms be +different than those for the MM atoms. + +See the ``examples/QUANTUM/NWChem/in.*`` files for examples of input +scripts for QM/MM simulations using the *potential* mode. Those scripts +also illustrate how to turn off QM/QM van der Waals interactions. + +---------- + +The *virial* keyword setting of yes or no determines whether LAMMPS +will request the QM code to also compute and return the QM +contribution to a stress tensor for the system which LAMMPS will +convert to a 6-element symmetric virial tensor. + +The *connect* keyword determines whether this fix performs a one-time +connection to the QM code. The default is *yes*. The only time a +*no* is needed is if this command is used multiple times in an input +script. E.g. if it used inside a loop which also uses the :doc:`clear +` command to destroy the system (including this fix). As +example would be a script which loop over a series of independent QM/MM +simulations, e.g. each with their own data file. In this use case +*connect no* could be used along with the :doc:`mdi connect and exit +` command to one-time initiate/terminate the connection outside +the loop. + +The *elements* keyword allows specification of what element each +LAMMPS atom type corresponds to. This is specified by the chemical +symbol of the element, e.g. C or Al or Si. A symbol must be specified +for each of the ntypes LAMMPS atom types. Multiple LAMMPS types can +represent the same element. Ntypes is typically specified via the +:doc:`create_box ` command or in the data file read by the +:doc:`read_data ` command. + +If this keyword is specified, then this fix will send the MDI +">ELEMENTS" command to the engine, to insure the two codes are +consistent in their definition of atomic species. If this keyword is +not specified, then this fix will send the MDI >TYPES command to the +engine. This is fine if both the LAMMPS driver and the MDI engine are +initialized so that the atom type values are consistent in both codes. + +---------- + +Restart, fix_modify, output, run start/stop, minimize info +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +No information about this fix is written to :doc:`binary restart files +`. + +The :doc:`fix_modify ` *energy* option is supported by +this fix to add the potential energy computed by the QM code to the +global potential energy of the system as part of :doc:`thermodynamic +output `. The default setting for this fix is +:doc:`fix_modify energy yes `. + +The :doc:`fix_modify ` *virial* option is supported by +this fix to add the contribution computed by the QM code to the global +pressure of the system as part of :doc:`thermodynamic output +`. The default setting for this fix is :doc:`fix_modify +virial yes `. + +This fix computes a global scalar which can be accessed by various +:doc:`output commands `. The scalar is the energy +returned by the QM code. The scalar value calculated by this fix is +"extensive". + +This fix also computes a global vector with of length 6 which contains +the symmetric virial tensor values returned by the QM code. It can +likewise be accessed by various :doc:`output commands `. + +The ordering of values in the symmetric virial tensor is as follows: +vxx, vyy, vzz, vxy, vxz, vyz. The values will be in pressure +:doc:`units `. + +This fix also computes a peratom array with 3 columns which contains +the peratom forces returned by the QM code. It can likewise be +accessed by various :doc:`output commands `. Note that +for *direct* mode this will be quantum forces on both QM and MM atoms. +For *potential* mode it will only be quantum forces on QM atoms; the +forces for MM atoms will be zero. + +No parameter of this fix can be used with the *start/stop* keywords of +the :doc:`run ` command. + +The forces computed by the QM code are used during an energy +minimization, invoked by the :doc:`minimize ` command. + +.. note:: + + If you want the potential energy associated with the QM forces to + be included in the total potential energy of the system (the + quantity being minimized), you MUST not disable the + :doc:`fix_modify ` *energy* option for this fix. + + +Restrictions +"""""""""""" + +This command is part of the MDI package. It is only enabled if LAMMPS +was built with that package. See the :doc:`Build package +` page for more info. + +To use LAMMPS as an MDI driver in conjunction with other MDI-enabled +codes (MD or QM codes), the :doc:`units ` command should be used +to specify *real* or *metal* units. This will ensure the correct unit +conversions between LAMMPS and MDI units. The other code will also +perform similar unit conversions into its preferred units. + +If this fix is used in conjunction with a QM code that does not support +periodic boundary conditions (more specifically, a QM code that does not +support the ``>CELL`` MDI command), the LAMMPS system must be fully +non-periodic. I.e. no dimension of the system can be periodic. + +Related commands +"""""""""""""""" + +:doc:`mdi plugin `, +:doc:`mdi engine `, +:doc:`fix mdi/qm ` + +Default +""""""" + +The default for the optional keywords are virial = no and connect = yes. diff --git a/doc/src/fix_pimd.rst b/doc/src/fix_pimd.rst index 7116ce526b..22c064b60b 100644 --- a/doc/src/fix_pimd.rst +++ b/doc/src/fix_pimd.rst @@ -65,7 +65,7 @@ Examples Description """"""""""" -.. versionchanged:: TBD +.. versionchanged:: 28Mar2023 Fix pimd was renamed to fix *pimd/nvt* and fix *pimd/langevin* was added. diff --git a/doc/src/fix_precession_spin.rst b/doc/src/fix_precession_spin.rst index 36a10c8ce6..7440989d7a 100644 --- a/doc/src/fix_precession_spin.rst +++ b/doc/src/fix_precession_spin.rst @@ -103,15 +103,15 @@ possible easy axis for the magnetic spins in the defined group: H_{cubic} = -\sum_{{ i}=1}^{N} K_{1} \Big[ - \left(\vec{s}_{i} \cdot \vec{n_1} \right)^2 - \left(\vec{s}_{i} \cdot \vec{n_2} \right)^2 + - \left(\vec{s}_{i} \cdot \vec{n_2} \right)^2 - \left(\vec{s}_{i} \cdot \vec{n_3} \right)^2 + - \left(\vec{s}_{i} \cdot \vec{n_1} \right)^2 - \left(\vec{s}_{i} \cdot \vec{n_3} \right)^2 \Big] - +K_{2}^{(c)} \left(\vec{s}_{i} \cdot \vec{n_1} \right)^2 - \left(\vec{s}_{i} \cdot \vec{n_2} \right)^2 - \left(\vec{s}_{i} \cdot \vec{n_3} \right)^2 + \left(\vec{s}_{i} \cdot \vec{n}_1 \right)^2 + \left(\vec{s}_{i} \cdot \vec{n}_2 \right)^2 + + \left(\vec{s}_{i} \cdot \vec{n}_2 \right)^2 + \left(\vec{s}_{i} \cdot \vec{n}_3 \right)^2 + + \left(\vec{s}_{i} \cdot \vec{n}_1 \right)^2 + \left(\vec{s}_{i} \cdot \vec{n}_3 \right)^2 \Big] + +K_{2}^{(c)} \left(\vec{s}_{i} \cdot \vec{n}_1 \right)^2 + \left(\vec{s}_{i} \cdot \vec{n}_2 \right)^2 + \left(\vec{s}_{i} \cdot \vec{n}_3 \right)^2 with :math:`K_1` and :math:`K_{2c}` (in eV) the intensity coefficients and :math:`\vec{n}_1`, :math:`\vec{n}_2` and :math:`\vec{n}_3` diff --git a/doc/src/fix_press_berendsen.rst b/doc/src/fix_press_berendsen.rst index 6d92a00178..dee93c5b8b 100644 --- a/doc/src/fix_press_berendsen.rst +++ b/doc/src/fix_press_berendsen.rst @@ -61,7 +61,7 @@ unchanged and controlling the pressure of a surrounding fluid. atoms. This fix can be used in conjunction with thermostatting fixes to control the temperature, such as :doc:`fix nvt ` or :doc:`fix langevin ` or :doc:`fix temp/berendsen `. -See the :doc:`Howto baroostat ` page for a +See the :doc:`Howto barostat ` page for a discussion of different ways to perform barostatting. ---------- diff --git a/doc/src/fix_print.rst b/doc/src/fix_print.rst index 545283b4ef..938b40d1f9 100644 --- a/doc/src/fix_print.rst +++ b/doc/src/fix_print.rst @@ -44,6 +44,20 @@ one word. If it contains variables it must be enclosed in double quotes to ensure they are not evaluated when the input script line is read, but will instead be evaluated each time the string is printed. +.. versionadded:: TBD + + support for vector style variables + +See the :doc:`variable ` command for a description of +*equal* and *vector* style variables which are typically the most +useful ones to use with the print command. Equal- and vector-style +variables can calculate formulas involving mathematical operations, +atom properties, group properties, thermodynamic properties, global +values calculated by a :doc:`compute ` or :doc:`fix `, +or references to other :doc:`variables `. Vector-style +variables are printed in a bracketed, comma-separated format, +e.g. [1,2,3,4] or [12.5,2,4.6,10.1]. + .. note:: As discussed on the :doc:`Commands parse ` doc @@ -77,15 +91,6 @@ timesteps 10,20,30,100,200,300,1000,2000,etc: The specified group-ID is ignored by this fix. -See the :doc:`variable ` command for a description of -*equal* style variables which are the most useful ones to use with the -fix print command, since they are evaluated afresh each timestep that -the fix print line is output. Equal-style variables calculate -formulas involving mathematical operations, atom properties, group -properties, thermodynamic properties, global values calculated by a -:doc:`compute ` or :doc:`fix `, or references to other -:doc:`variables `. - If the *file* or *append* keyword is used, a filename is specified to which the output generated by this fix will be written. If *file* is used, then the filename is overwritten if it already exists. If diff --git a/doc/src/fix_reaxff_species.rst b/doc/src/fix_reaxff_species.rst index 383b8212f9..f57132f08b 100644 --- a/doc/src/fix_reaxff_species.rst +++ b/doc/src/fix_reaxff_species.rst @@ -148,7 +148,8 @@ formulae). The *specieslist* and *masslimit* keywords cannot both be used in the same *reaxff/species* fix. The *delete_rate_limit* keyword can enforce an upper limit on the overall rate of molecule deletion. The number of deletion occurrences is limited to Nlimit -within an interval of Nsteps timesteps. When using the +within an interval of Nsteps timesteps. Nlimit can be specified with +an equal-style :doc:`variable `. When using the *delete_rate_limit* keyword, no deletions are permitted to occur within the first Nsteps timesteps of the first run (after reading a either a data or restart file). diff --git a/doc/src/fix_saed_vtk.rst b/doc/src/fix_saed_vtk.rst index dd5db32966..cd3cad7c72 100644 --- a/doc/src/fix_saed_vtk.rst +++ b/doc/src/fix_saed_vtk.rst @@ -163,11 +163,17 @@ intensity outputs. Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" -No information about this fix is written to :doc:`binary restart files `. None of the :doc:`fix_modify ` options -are relevant to this fix. +This fix is part of the DIFFRACTION package. It is only enabled if +LAMMPS was built with that package. See the :doc:`Build package +` page for more info. + +No information about this fix is written to :doc:`binary restart files +`. None of the :doc:`fix_modify ` options are +relevant to this fix. No parameter of this fix can be used with the *start/stop* keywords of -the :doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. +the :doc:`run ` command. This fix is not invoked during +:doc:`energy minimization `. Restrictions """""""""""" diff --git a/doc/src/fix_wall.rst b/doc/src/fix_wall.rst index cdf3c16cef..42cd94978d 100644 --- a/doc/src/fix_wall.rst +++ b/doc/src/fix_wall.rst @@ -194,7 +194,7 @@ For style *wall/morse*, the energy E is given by a Morse potential: E = D_0 \left[ e^{- 2 \alpha (r - r_0)} - 2 e^{- \alpha (r - r_0)} \right] \qquad r < r_c -.. versionadded:: TBD +.. versionadded:: 28Mar2023 For style *wall/lepton*, the energy E is provided as an Lepton expression string using "r" as the distance variable. The `Lepton @@ -209,13 +209,13 @@ it as a single keyword. Optionally, the expression may use "rc" to refer to the cutoff distance for the given wall. Further constants in the expression can be defined -in the same string as additional expressions separated by semi-colons. +in the same string as additional expressions separated by semicolons. The expression "k*(r-rc)^2;k=100.0" represents a repulsive-only harmonic spring as in fix *wall/harmonic* with a force constant *K* (same as :math:`\epsilon` above) of 100 energy units. More details on the Lepton expression strings are given below. -.. versionadded:: TBD +.. versionadded:: 28Mar2023 For style *wall/table*, the energy E and forces are determined from interpolation tables listed in one or more files as a function of diff --git a/doc/src/fix_wall_gran.rst b/doc/src/fix_wall_gran.rst index 0006e1750b..27d19d60b5 100644 --- a/doc/src/fix_wall_gran.rst +++ b/doc/src/fix_wall_gran.rst @@ -1,8 +1,11 @@ .. index:: fix wall/gran +.. index:: fix wall/gran/kk fix wall/gran command ===================== +Accelerator Variants: *wall/gran/kk* + Syntax """""" @@ -71,9 +74,9 @@ Examples fix 1 all wall/gran hooke 200000.0 NULL 50.0 NULL 0.5 0 xplane -10.0 10.0 fix 1 all wall/gran hooke/history 200000.0 NULL 50.0 NULL 0.5 0 zplane 0.0 NULL fix 2 all wall/gran hooke 100000.0 20000.0 50.0 30.0 0.5 1 zcylinder 15.0 wiggle z 3.0 2.0 - fix 3 all wall/gran/region granular hooke 1000.0 50.0 tangential linear_nohistory 1.0 0.4 damping velocity region myBox - fix 4 all wall/gran/region granular jkr 1e5 1500.0 0.3 10.0 tangential mindlin NULL 1.0 0.5 rolling sds 500.0 200.0 0.5 twisting marshall region myCone - fix 5 all wall/gran/region granular dmt 1e5 0.2 0.3 10.0 tangential mindlin NULL 1.0 0.5 rolling sds 500.0 200.0 0.5 twisting marshall damping tsuji heat 10 region myCone temperature 1.0 + fix 3 all wall/gran granular hooke 1000.0 50.0 tangential linear_nohistory 1.0 0.4 damping velocity region myBox + fix 4 all wall/gran granular jkr 1e5 1500.0 0.3 10.0 tangential mindlin NULL 1.0 0.5 rolling sds 500.0 200.0 0.5 twisting marshall region myCone + fix 5 all wall/gran granular dmt 1e5 0.2 0.3 10.0 tangential mindlin NULL 1.0 0.5 rolling sds 500.0 200.0 0.5 twisting marshall damping tsuji heat 10 region myCone temperature 1.0 fix 6 all wall/gran hooke 200000.0 NULL 50.0 NULL 0.5 0 xplane -10.0 10.0 contacts Description @@ -120,18 +123,17 @@ material. .. note:: As discussed on the page for :doc:`pair_style gran/\* `, - versions of LAMMPS before 9Jan09 used a - different equation for Hertzian interactions. This means Hertizian - wall/particle interactions have also changed. They now include a - sqrt(radius) term which was not present before. Also the previous - versions used Kn and Kt from the pairwise interaction and hardwired - dampflag to 1, rather than letting them be specified directly. This - means you can set the values of the wall/particle coefficients - appropriately in the current code to reproduce the results of a - previous Hertzian monodisperse calculation. For example, for the - common case of a monodisperse system with particles of diameter 1, Kn, - Kt, gamma_n, and gamma_s should be set sqrt(2.0) larger than they were - previously. + versions of LAMMPS before 9Jan09 used a different equation for + Hertzian interactions. This means Hertizian wall/particle + interactions have also changed. They now include a sqrt(radius) term + which was not present before. Also the previous versions used Kn and + Kt from the pairwise interaction and hardwired dampflag to 1, rather + than letting them be specified directly. This means you can set the + values of the wall/particle coefficients appropriately in the current + code to reproduce the results of a previous Hertzian monodisperse + calculation. For example, for the common case of a monodisperse + system with particles of diameter 1, Kn, Kt, gamma_n, and gamma_s + should be set sqrt(2.0) larger than they were previously. The effective mass *m_eff* in the formulas listed on the :doc:`pair_style granular ` page is the mass of the particle for particle/wall interactions (mass of wall is infinite). If the @@ -190,6 +192,12 @@ conduction model defined in :doc:`pair_style granular `, heat flow, and :doc:`fix heat/flow ` to integrate heat flow. +---------- + +.. include:: accel_styles.rst + +---------- + Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/improper_amoeba.rst b/doc/src/improper_amoeba.rst index 9b8260b853..18c7f11080 100644 --- a/doc/src/improper_amoeba.rst +++ b/doc/src/improper_amoeba.rst @@ -1,7 +1,7 @@ .. index:: improper_style amoeba -improper_style harmonic command -=============================== +improper_style amoeba command +============================= Syntax """""" diff --git a/doc/src/kspace_modify.rst b/doc/src/kspace_modify.rst index 2d3921e281..351e387c0f 100644 --- a/doc/src/kspace_modify.rst +++ b/doc/src/kspace_modify.rst @@ -142,7 +142,8 @@ the code will stop with an error message. When this option is set to For a typical application, using the automatic parameter generation will provide simulations that are either inaccurate or slow. Using this option is thus not recommended. For guidelines on how to obtain good -parameters, see the :doc:`How-To ` discussion. +parameters, see the :doc:`long-range dispersion howto ` +discussion. ---------- diff --git a/doc/src/mdi.rst b/doc/src/mdi.rst index 2f7fc65852..cdb5e432cc 100644 --- a/doc/src/mdi.rst +++ b/doc/src/mdi.rst @@ -17,7 +17,7 @@ Syntax *engine* args = zero or more keyword/args pairs keywords = *elements* *elements* args = N_1 N_2 ... N_ntypes - N_1,N_2,...N_ntypes = atomic number for each of ntypes LAMMPS atom types + N_1,N_2,...N_ntypes = chemical symbol for each of ntypes LAMMPS atom types *plugin* args = name keyword value keyword value ... name = name of plugin library (e.g., *lammps* means a liblammps.so library will be loaded) keyword/value pairs in any order, some are required, some are optional @@ -35,7 +35,7 @@ Examples .. code-block:: LAMMPS mdi engine - mdi engine elements 13 29 + mdi engine elements Al Cu mdi plugin lammps mdi "-role ENGINE -name lammps -method LINK" & infile in.aimd.engine extra "-log log.aimd.engine.plugin" & command "run 5" @@ -173,13 +173,16 @@ commands, which are described further below. atom type values are consistent in both codes, then the >TYPES command can be used. If not, the optional *elements* keyword can be used to specify what element each LAMMPS atom type corresponds - to. This is specified by the atomic number of the element (e.g., 13 - for Al). An atomic number must be specified for each of the ntypes - LAMMPS atom types. Ntypes is typically specified via the - create_box command or in the data file read by the read_data - command. In this has been done, the MDI driver can send an - >ELEMENTS command to the LAMMPS driver with the atomic number of - each atom. + to. This is specified by the chemical symbol of the element, + e.g. C or Al or Si. A symbol must be specified for each of the + ntypes LAMMPS atom types. Each LAMMPS type must map to a unique + element; two or more types cannot map to the same element. Ntypes + is typically specified via the :doc:`create_box ` + command or in the data file read by the :doc:`read_data + ` command. Once this has been done, the MDI driver can + send an >ELEMENTS command to the LAMMPS driver with the atomic + number of each atom and the LAMMPS engine will be able to map it to + a LAMMPS atom type. The MD and OPTG commands perform an entire MD simulation or energy minimization (to convergence) with no communication from the driver diff --git a/doc/src/neighbor.rst b/doc/src/neighbor.rst index 663170ef47..9dcdd1daf2 100644 --- a/doc/src/neighbor.rst +++ b/doc/src/neighbor.rst @@ -59,9 +59,21 @@ long cutoff, but other type pairs have a much shorter cutoff. The sized particles, where "size" may mean the physical size of the particle or its cutoff distance for interacting with other particles. Different sets of bins are then used to construct the neighbor lists as as further -described by Shire, Hanley, and Stratford :ref:`(Shire) `. -This imposes some extra setup overhead, but the searches themselves may -be much faster. By default, each atom type defines a separate collection +described by Shire, Hanley, and Stratford :ref:`(Shire) ` +and Monti et al. :ref:`(Monti) `. This imposes some extra +setup overhead, but the searches themselves may be much faster. + +For instance in a dense binary system in d-dimensions with a ratio of the size +of the largest to smallest collection bin :math:`\lambda`, the computational +costs of building a default neighbor list grows as :math:`\lambda^{2d}` while +the costs for *multi* grows as :math:`\lambda^d`, equivalent to the cost +of force evaluations, as argued in Monti et al. :ref:`(Monti) `. +In other words, the neighboring costs of *multi* are expected to scale the +same as force calculations, such that its relative cost is independent of +the particle size ratio. This is not the case for the default style which +becomes substantially more expensive with increasing size ratios. + +By default in *multi*, each atom type defines a separate collection of particles. For systems where two or more atom types have the same size (either physical size or cutoff distance), the definition of collections can be customized, which can result in less overhead and @@ -75,8 +87,11 @@ An alternate style, *multi/old*, sets the bin size to 1/2 of the shortest cutoff distance and multiple sets of bins are defined to search over for different atom types. This algorithm used to be the default *multi* algorithm in LAMMPS but was found to be significantly slower than the new -approach. For now we are keeping the old option in case there are use cases -where multi/old outperforms the new multi style. +approach. For the dense binary system, computational costs still grew as +:math:`\lambda^{2d}` at large enough :math:`\lambda`. This is equivalent +to the default style, albeit with a smaller prefactor. For now we are +keeping the old option in case there are use cases where multi/old +outperforms the new multi style. .. note:: @@ -118,6 +133,10 @@ Default ---------- -.. _bytype-Shire: +.. _multi-Shire: -**(Shire)** Shire, Hanley and Stratford, Comp Part Mech, (2020). +**(Shire)** Shire, Hanley and Stratford, Comp. Part. Mech., (2020). + +.. _multi-Monti: + +**(Monti)** Monti, Clemmer, Srivastava, Silbert, Grest, and Lechman, Phys. Rev. E, (2022). diff --git a/doc/src/package.rst b/doc/src/package.rst index 76bf20a97f..6d425b63dd 100644 --- a/doc/src/package.rst +++ b/doc/src/package.rst @@ -71,7 +71,7 @@ Syntax *no_affinity* values = none *kokkos* args = keyword value ... zero or more keyword/value pairs may be appended - keywords = *neigh* or *neigh/qeq* or *neigh/thread* or *neigh/transpose* or *newton* or *binsize* or *comm* or *comm/exchange* or *comm/forward* or *comm/pair/forward* or *comm/fix/forward* or *comm/reverse* or *comm/pair/reverse* or *gpu/aware* or *pair/only* + keywords = *neigh* or *neigh/qeq* or *neigh/thread* or *neigh/transpose* or *newton* or *binsize* or *comm* or *comm/exchange* or *comm/forward* or *comm/pair/forward* or *comm/fix/forward* or *comm/reverse* or *comm/pair/reverse* or *sort* or *gpu/aware* or *pair/only* *neigh* value = *full* or *half* full = full neighbor list half = half neighbor list built in thread-safe manner @@ -102,6 +102,9 @@ Syntax *comm/pair/reverse* value = *no* or *device* *no* = perform communication pack/unpack in non-KOKKOS mode *device* = perform pack/unpack on device (e.g. on GPU) + *sort* value = *no* or *device* + *no* = perform atom sorting in non-KOKKOS mode + *device* = perform atom sorting on device (e.g. on GPU) *gpu/aware* = *off* or *on* *off* = do not use GPU-aware MPI *on* = use GPU-aware MPI (default) @@ -554,6 +557,17 @@ pack/unpack communicated data. When running small systems on a GPU, performing the exchange pack/unpack on the host CPU can give speedup since it reduces the number of CUDA kernel launches. +The *sort* keyword determines whether the host or device performs atom +sorting, see the :doc:`atom_modify sort ` command. The +value options for the *sort* keyword are *no* or *device* similar to the +*comm* keywords above. If a value of *host* is used it will be +automatically be changed to *no* since the *sort* keyword does not +support *host* mode. The value of *no* will also always be used when +running on the CPU, i.e. setting the value to *device* will have no +effect if the simulation is running on the CPU. Not all fix styles with +extra atom data support *device* mode and in that case a warning will be +given and atom sorting will run in *no* mode instead. + The *gpu/aware* keyword chooses whether GPU-aware MPI will be used. When this keyword is set to *on*, buffers in GPU memory are passed directly through MPI send/receive calls. This reduces overhead of first copying @@ -705,12 +719,12 @@ script or via the "-pk intel" :doc:`command-line switch `. For the KOKKOS package, the option defaults for GPUs are neigh = full, neigh/qeq = full, newton = off, binsize for GPUs = 2x LAMMPS default -value, comm = device, neigh/transpose = off, gpu/aware = on. When -LAMMPS can safely detect that GPU-aware MPI is not available, the -default value of gpu/aware becomes "off". For CPUs or Xeon Phis, the -option defaults are neigh = half, neigh/qeq = half, newton = on, -binsize = 0.0, and comm = no. The option neigh/thread = on when there -are 16K atoms or less on an MPI rank, otherwise it is "off". These +value, comm = device, sort = device, neigh/transpose = off, gpu/aware = +on. When LAMMPS can safely detect that GPU-aware MPI is not available, +the default value of gpu/aware becomes "off". For CPUs or Xeon Phis, the +option defaults are neigh = half, neigh/qeq = half, newton = on, binsize += 0.0, comm = no, and sort = no. The option neigh/thread = on when +there are 16K atoms or less on an MPI rank, otherwise it is "off". These settings are made automatically by the required "-k on" :doc:`command-line switch `. You can change them by using the package kokkos command in your input script or via the :doc:`-pk diff --git a/doc/src/pair_amoeba.rst b/doc/src/pair_amoeba.rst index a7f19ba91e..c369ee5e42 100644 --- a/doc/src/pair_amoeba.rst +++ b/doc/src/pair_amoeba.rst @@ -94,22 +94,22 @@ The formulas for the AMOEBA energy terms are: .. math:: - U_{hal} = \epsilon_{ij} \left( \frac{1.07}{\rho_{ij} + 0.07} \right)^7 \left( \frac{1.12}{\rho_{ij}^7 + 0.12} - 2 \right) - U_{multipole} = \vec{M_i}\bold{T_{ij}}\vec{M_j} - \vec{M} = \left( q, \vec{\mu_{perm}}, \bold{\Theta} \right) - U_{polar} = \frac{1}{2}\vec{\mu_i}^{ind} \vec{E_i}^{perm} + U_{hal} = & \epsilon_{ij} \left( \frac{1.07}{\rho_{ij} + 0.07} \right)^7 \left( \frac{1.12}{\rho_{ij}^7 + 0.12} - 2 \right) \\ + U_{multipole} = & \vec{M}_i\boldsymbol{T_{ij}}\vec{M}_j, \quad \mbox{with} \quad + \vec{M} = \left(q, \vec{\mu}_{perm}, \boldsymbol{\Theta} \right) \\ + U_{polar} = & \frac{1}{2}\vec{\mu}_i^{ind} \vec{E}_i^{perm} The formulas for the HIPPO energy terms are: .. math:: - U_{multipole} = Z_i \frac{1}{r_{ij}} Z_j + Z_i T_{ij}^{damp} \vec{M_j} + Z_j T_{ji}^{damp} \vec{M_i} + \vec{M_i} T_{ij}^{damp} \vec{M_j} - \vec{M} = \left( Q, \vec{\mu_{perm}}, \bold{\Theta} \right) - U_{polar} = \frac{1}{2}\vec{\mu_i}^{ind} \vec{E_i}^{perm} - U_{qxfer} = \epsilon_i e^{-\eta_j r_{ij}} + \epsilon_j e^{-\eta_i r_{ij}} - U_{repulsion} = \frac{K_i K_j}{r_{ij}} S^2 - S^2 = \left( \int{\phi_i \phi_j} dv \right)^2 = \vec{M_i}\bold{T_{ij}^{repulsion}}\vec{M_j} - U_{dispersion} = -\frac{C_6^iC_6^j}{r_{ij}^6} \left( f_{damp}^{dispersion} \right)_{ij}^2 + U_{multipole} = & Z_i \frac{1}{r_{ij}} Z_j + Z_i T_{ij}^{damp} \vec{M}_j + Z_j T_{ji}^{damp} \vec{M}_i + \vec{M}_i T_{ij}^{damp} \vec{M}_j, \quad \mbox{with} \quad + \vec{M} = \left(q, \vec{\mu}_{perm}, \boldsymbol{\Theta} \right) \\ + U_{polar} = & \frac{1}{2}\vec{\mu}_i^{ind} \vec{E}_i^{perm} \\ + U_{qxfer} = & \epsilon_i e^{-\eta_j r_{ij}} + \epsilon_j e^{-\eta_i r_{ij}} \\ + U_{repulsion} = & \frac{K_i K_j}{r_{ij}} S^2 + S^2 = \left( \int{\phi_i \phi_j} dv \right)^2 = \vec{M}_i\boldsymbol{T_{ij}^{repulsion}}\vec{M}_j \\ + U_{dispersion} = & -\frac{C_6^iC_6^j}{r_{ij}^6} \left( f_{damp}^{dispersion} \right)_{ij}^2 .. note:: diff --git a/doc/src/pair_born_gauss.rst b/doc/src/pair_born_gauss.rst new file mode 100644 index 0000000000..97f0042ee7 --- /dev/null +++ b/doc/src/pair_born_gauss.rst @@ -0,0 +1,103 @@ +.. index:: pair_style born/gauss + +pair_style born/gauss command +============================= + +Syntax +"""""" + +.. code-block:: LAMMPS + + pair_style born/gauss cutoff + +* born/gauss = name of the pair style +* cutoff = global cutoff (distance units) + +Examples +"""""""" + +.. code-block:: LAMMPS + + pair_style born/gauss 10.0 + pair_coeff 1 1 1 1 8.2464e13 12.48 0.042644277 0.44 3.56 + +Description +""""""""""" + +.. versionadded:: 28Mar2023 + +Pair style *born/gauss* computes pairwise interactions from a combination of a Born-Mayer +repulsive term and a Gaussian attractive term according to :ref:`(Bomont) `: + +.. math:: + + E = A_0 \exp \left( -\alpha r \right) - A_1 \exp\left[ -\beta \left(r - r_0 \right)^2 \right] + \qquad r < r_c + +:math:`r_c` is the cutoff. + +The following coefficients must be defined for each pair of atoms +types via the :doc:`pair_coeff ` command as in the examples +above, or in the data file or restart files read by the +:doc:`read_data ` or :doc:`read_restart ` +commands: + +* :math:`A_0` (energy units) +* :math:`\alpha` (1/distance units) +* :math:`A_1` (energy units) +* :math:`\beta` (1/(distance units)^2) +* :math:`r_0` (distance units) +* cutoff (distance units) + +The last coefficient is optional. If not specified, the global cutoff is used. + +---------- + +Mixing, shift, table, tail correction, restart, rRESPA info +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +This pair style does not support mixing. Thus, coefficients for all I,J +pairs must be specified explicitly. + +This pair style supports the :doc:`pair_modify ` shift +option for the energy of the pair interaction. + +The :doc:`pair_modify ` table options are not relevant for +this pair style. + +This pair style does not support the :doc:`pair_modify ` +tail option for adding long-range tail corrections to energy and +pressure. + +This pair style writes its information to :doc:`binary restart files +`, so pair_style and pair_coeff commands do not need to be +specified in an input script that reads a restart file. + +This pair style can only be used via the *pair* keyword of the +:doc:`run_style respa ` command. It does not support the +*inner*, *middle*, *outer* keywords. + +---------- + +Restrictions +"""""""""""" + +This pair style is only enabled if LAMMPS was built with the EXTRA-PAIR +package. See the :doc:`Build package ` page for more +info. + +Related commands +"""""""""""""""" + +:doc:`pair_coeff `, :doc:`pair_style born ` + +Default +""""""" + +none + +-------------- + +.. _Bomont: + +**(Bomont)** Bomont, Bretonnet, J. Chem. Phys. 124, 054504 (2006) diff --git a/doc/src/pair_colloid.rst b/doc/src/pair_colloid.rst index 1e75ae1c78..26e7fa7da4 100644 --- a/doc/src/pair_colloid.rst +++ b/doc/src/pair_colloid.rst @@ -93,7 +93,7 @@ with :math:`A_{ss}` set appropriately, which results from letting both particle sizes go to zero. When used in combination with :doc:`pair_style yukawa/colloid -`, the two terms become the so-called DLVO potential, +`, the two terms become the so-called DLVO potential, which combines electrostatic repulsion and van der Waals attraction. The following coefficients must be defined for each pair of atoms diff --git a/doc/src/pair_dipole.rst b/doc/src/pair_dipole.rst index 10d0061948..bea80bfc45 100644 --- a/doc/src/pair_dipole.rst +++ b/doc/src/pair_dipole.rst @@ -96,29 +96,29 @@ force (F), and torque (T) between particles I and J. \left(\frac{\sigma}{r}\right)^6 \right] \\ E_{qq} = & \frac{q_i q_j}{r} \\ E_{qp} = & \frac{q}{r^3} (p \bullet \vec{r}) \\ - E_{pp} = & \frac{1}{r^3} (\vec{p_i} \bullet \vec{p_j}) - - \frac{3}{r^5} (\vec{p_i} \bullet \vec{r}) (\vec{p_j} \bullet \vec{r}) \\ + E_{pp} = & \frac{1}{r^3} (\vec{p}_i \bullet \vec{p}_j) - + \frac{3}{r^5} (\vec{p}_i \bullet \vec{r}) (\vec{p}_j \bullet \vec{r}) \\ & \\ F_{qq} = & \frac{q_i q_j}{r^3} \vec{r} \\ F_{qp} = & -\frac{q}{r^3} \vec{p} + \frac{3q}{r^5} (\vec{p} \bullet \vec{r}) \vec{r} \\ - F_{pp} = & \frac{3}{r^5} (\vec{p_i} \bullet \vec{p_j}) \vec{r} - - \frac{15}{r^7} (\vec{p_i} \bullet \vec{r}) - (\vec{p_j} \bullet \vec{r}) \vec{r} + - \frac{3}{r^5} \left[ (\vec{p_j} \bullet \vec{r}) \vec{p_i} + - (\vec{p_i} \bullet \vec{r}) \vec{p_j} \right] \\ + F_{pp} = & \frac{3}{r^5} (\vec{p}_i \bullet \vec{p}_j) \vec{r} - + \frac{15}{r^7} (\vec{p}_i \bullet \vec{r}) + (\vec{p}_j \bullet \vec{r}) \vec{r} + + \frac{3}{r^5} \left[ (\vec{p}_j \bullet \vec{r}) \vec{p}_i + + (\vec{p}_i \bullet \vec{r}) \vec{p}_j \right] \\ & \\ - T_{pq} = T_{ij} = & \frac{q_j}{r^3} (\vec{p_i} \times \vec{r}) \\ - T_{qp} = T_{ji} = & - \frac{q_i}{r^3} (\vec{p_j} \times \vec{r}) \\ - T_{pp} = T_{ij} = & -\frac{1}{r^3} (\vec{p_i} \times \vec{p_j}) + - \frac{3}{r^5} (\vec{p_j} \bullet \vec{r}) - (\vec{p_i} \times \vec{r}) \\ - T_{pp} = T_{ji} = & -\frac{1}{r^3} (\vec{p_j} \times \vec{p_i}) + - \frac{3}{r^5} (\vec{p_i} \bullet \vec{r}) - (\vec{p_j} \times \vec{r}) + T_{pq} = T_{ij} = & \frac{q_j}{r^3} (\vec{p}_i \times \vec{r}) \\ + T_{qp} = T_{ji} = & - \frac{q_i}{r^3} (\vec{p}_j \times \vec{r}) \\ + T_{pp} = T_{ij} = & -\frac{1}{r^3} (\vec{p}_i \times \vec{p}_j) + + \frac{3}{r^5} (\vec{p}_j \bullet \vec{r}) + (\vec{p}_i \times \vec{r}) \\ + T_{pp} = T_{ji} = & -\frac{1}{r^3} (\vec{p}_j \times \vec{p}_i) + + \frac{3}{r^5} (\vec{p}_i \bullet \vec{r}) + (\vec{p}_j \times \vec{r}) where :math:`q_i` and :math:`q_j` are the charges on the two -particles, :math:`\vec{p_i}` and :math:`\vec{p_j}` are the dipole +particles, :math:`\vec{p}_i` and :math:`\vec{p}_j` are the dipole moment vectors of the two particles, r is their separation distance, and the vector r = Ri - Rj is the separation vector between the two particles. Note that Eqq and Fqq are simply Coulombic energy and @@ -163,8 +163,8 @@ energy (E), force (F), and torque (T) between particles I and J: 2\left(\frac{r}{r_c}\right)^{\!3}\right] (\vec{p}\bullet\vec{r}) \\ E_{pp} = & \left[1-4\left(\frac{r}{r_c}\right)^{\!3} + 3\left(\frac{r}{r_c}\right)^{\!4}\right]\left[\frac{1}{r^3} - (\vec{p_i} \bullet \vec{p_j}) - \frac{3}{r^5} - (\vec{p_i} \bullet \vec{r}) (\vec{p_j} \bullet \vec{r})\right] \\ + (\vec{p}_i \bullet \vec{p}_j) - \frac{3}{r^5} + (\vec{p}_i \bullet \vec{r}) (\vec{p}_j \bullet \vec{r})\right] \\ & \\ F_{LJ} = & \left\{\left[48\epsilon \left(\frac{\sigma}{r}\right)^{\!12} - @@ -182,37 +182,37 @@ energy (E), force (F), and torque (T) between particles I and J: \frac{q}{r^3}\left[1-3\left(\frac{r}{r_c}\right)^{\!2} + 2\left(\frac{r}{r_c}\right)^{\!3}\right] \vec{p} \\ F_{pp} = &\frac{3}{r^5}\Bigg\{\left[1-\left(\frac{r}{r_c}\right)^{\!4}\right] - \left[(\vec{p_i}\bullet\vec{p_j}) - \frac{3}{r^2} (\vec{p_i}\bullet\vec{r}) - (\vec{p_j} \bullet \vec{r})\right] \vec{r} + \\ + \left[(\vec{p}_i\bullet\vec{p}_j) - \frac{3}{r^2} (\vec{p}_i\bullet\vec{r}) + (\vec{p}_j \bullet \vec{r})\right] \vec{r} + \\ & \left[1 - 4\left(\frac{r}{r_c}\right)^{\!3}+3\left(\frac{r}{r_c}\right)^{\!4}\right] - \left[ (\vec{p_j} \bullet \vec{r}) \vec{p_i} + (\vec{p_i} \bullet \vec{r}) - \vec{p_j} -\frac{2}{r^2} (\vec{p_i} \bullet \vec{r}) - (\vec{p_j} \bullet \vec{r})\vec{r}\right] \Bigg\} + \left[ (\vec{p}_j \bullet \vec{r}) \vec{p}_i + (\vec{p}_i \bullet \vec{r}) + \vec{p}_j -\frac{2}{r^2} (\vec{p}_i \bullet \vec{r}) + (\vec{p}_j \bullet \vec{r})\vec{r}\right] \Bigg\} .. math:: T_{pq} = T_{ij} = & \frac{q_j}{r^3} \left[ 1 - 3\left(\frac{r}{r_c}\right)^{\!2} + - 2\left(\frac{r}{r_c}\right)^{\!3}\right] (\vec{p_i}\times\vec{r}) \\ + 2\left(\frac{r}{r_c}\right)^{\!3}\right] (\vec{p}_i\times\vec{r}) \\ T_{qp} = T_{ji} = & - \frac{q_i}{r^3} \left[ 1 - 3\left(\frac{r}{r_c}\right)^{\!2} + - 2\left(\frac{r}{r_c}\right)^{\!3} \right] (\vec{p_j}\times\vec{r}) \\ + 2\left(\frac{r}{r_c}\right)^{\!3} \right] (\vec{p}_j\times\vec{r}) \\ T_{pp} = T_{ij} = & -\frac{1}{r^3}\left[1-4\left(\frac{r}{r_c}\right)^{\!3} + - e3\left(\frac{r}{r_c}\right)^{\!4}\right] (\vec{p_i} \times \vec{p_j}) + \\ + e3\left(\frac{r}{r_c}\right)^{\!4}\right] (\vec{p}_i \times \vec{p}_j) + \\ & \frac{3}{r^5}\left[1-4\left(\frac{r}{r_c}\right)^{\!3} + - 3\left(\frac{r}{r_c}\right)^{\!4}\right] (\vec{p_j}\bullet\vec{r}) - (\vec{p_i} \times \vec{r}) \\ + 3\left(\frac{r}{r_c}\right)^{\!4}\right] (\vec{p}_j\bullet\vec{r}) + (\vec{p}_i \times \vec{r}) \\ T_{pp} = T_{ji} = & -\frac{1}{r^3}\left[1-4\left(\frac{r}{r_c}\right)^{\!3} + - 3\left(\frac{r}{r_c}\right)^{\!4}\right](\vec{p_j} \times \vec{p_i}) + \\ + 3\left(\frac{r}{r_c}\right)^{\!4}\right](\vec{p}_j \times \vec{p}_i) + \\ & \frac{3}{r^5}\left[1-4\left(\frac{r}{r_c}\right)^{\!3} + - 3\left(\frac{r}{r_c}\right)^{\!4}\right] (\vec{p_i} \bullet \vec{r}) - (\vec{p_j} \times \vec{r}) + 3\left(\frac{r}{r_c}\right)^{\!4}\right] (\vec{p}_i \bullet \vec{r}) + (\vec{p}_j \times \vec{r}) where :math:`\epsilon` and :math:`\sigma` are the standard LJ parameters, :math:`r_c` is the cutoff, :math:`q_i` and :math:`q_j` are -the charges on the two particles, :math:`\vec{p_i}` and -:math:`\vec{p_j}` are the dipole moment vectors of the two particles, +the charges on the two particles, :math:`\vec{p}_i` and +:math:`\vec{p}_j` are the dipole moment vectors of the two particles, r is their separation distance, and the vector r = Ri - Rj is the separation vector between the two particles. Note that Eqq and Fqq are simply Coulombic energy and force, Fij = -Fji as symmetric forces, diff --git a/doc/src/pair_dpd.rst b/doc/src/pair_dpd.rst index aef085ca6e..4c8deab152 100644 --- a/doc/src/pair_dpd.rst +++ b/doc/src/pair_dpd.rst @@ -26,8 +26,8 @@ Syntax pair_style dpd T cutoff seed pair_style dpd/tstat Tstart Tstop cutoff seed -* T = temperature (temperature units) -* Tstart,Tstop = desired temperature at start/end of run (temperature units) +* T = temperature (temperature units) (dpd only) +* Tstart,Tstop = desired temperature at start/end of run (temperature units) (dpd/tstat only) * cutoff = global cutoff for DPD interactions (distance units) * seed = random # seed (positive integer) @@ -40,9 +40,9 @@ Examples pair_coeff * * 3.0 1.0 pair_coeff 1 1 3.0 1.0 1.0 - pair_style dpd/tstat 1.0 1.0 2.5 34387 - pair_coeff * * 1.0 - pair_coeff 1 1 1.0 1.0 + pair_style hybrid/overlay lj/cut 2.5 dpd/tstat 1.0 1.0 2.5 34387 + pair_coeff * * lj/cut 1.0 1.0 + pair_coeff * * dpd/tstat 1.0 Description """"""""""" @@ -53,7 +53,7 @@ Style *dpd* computes a force field for dissipative particle dynamics Style *dpd/tstat* invokes a DPD thermostat on pairwise interactions, which is equivalent to the non-conservative portion of the DPD force field. This pairwise thermostat can be used in conjunction with any -:doc:`pair style `, and in leiu of per-particle thermostats +:doc:`pair style `, and instead of per-particle thermostats like :doc:`fix langevin ` or ensemble thermostats like Nose Hoover as implemented by :doc:`fix nvt `. To use *dpd/tstat* as a thermostat for another pair style, use the @@ -68,13 +68,13 @@ of 3 terms \vec{f} = & (F^C + F^D + F^R) \hat{r_{ij}} \qquad \qquad r < r_c \\ F^C = & A w(r) \\ - F^D = & - \gamma w^2(r) (\hat{r_{ij}} \bullet \vec{v_{ij}}) \\ + F^D = & - \gamma w^2(r) (\hat{r_{ij}} \bullet \vec{v}_{ij}) \\ F^R = & \sigma w(r) \alpha (\Delta t)^{-1/2} \\ w(r) = & 1 - \frac{r}{r_c} where :math:`F^C` is a conservative force, :math:`F^D` is a dissipative force, and :math:`F^R` is a random force. :math:`\hat{r_{ij}}` is a -unit vector in the direction :math:`r_i - r_j`, :math:`\vec{v_{ij}}` is +unit vector in the direction :math:`r_i - r_j`, :math:`\vec{v}_{ij}` is the vector difference in velocities of the two atoms :math:`\vec{v}_i - \vec{v}_j`, :math:`\alpha` is a Gaussian random number with zero mean and unit variance, *dt* is the timestep size, and :math:`w(r)` is a @@ -105,14 +105,18 @@ commands: * :math:`\gamma` (force/velocity units) * cutoff (distance units) -The last coefficient is optional. If not specified, the global DPD +The cutoff coefficient is optional. If not specified, the global DPD cutoff is used. Note that sigma is set equal to sqrt(2 T gamma), where T is the temperature set by the :doc:`pair_style ` command so it does not need to be specified. For style *dpd/tstat*, the coefficients defined for each pair of -atoms types via the :doc:`pair_coeff ` command is the same, -except that A is not included. +atoms types via the :doc:`pair_coeff ` command are: + +* :math:`\gamma` (force/velocity units) +* cutoff (distance units) + +The cutoff coefficient is optional. The GPU-accelerated versions of these styles are implemented based on the work of :ref:`(Afshar) ` and :ref:`(Phillips) `. @@ -135,6 +139,12 @@ the work of :ref:`(Afshar) ` and :ref:`(Phillips) `. numbers are applied and thus the individual forces and therefore also the virial/pressure. +.. note:: + + For more consistent time integration and force computation you may + consider using :doc:`fix mvv/dpd ` instead of :doc:`fix + nve `. + ---------- .. include:: accel_styles.rst @@ -206,7 +216,9 @@ command for more details. Related commands """""""""""""""" -:doc:`pair_coeff `, :doc:`fix nvt `, :doc:`fix langevin `, :doc:`pair_style srp ` +:doc:`pair_style dpd/ext `, :doc:`pair_coeff `, +:doc:`fix nvt `, :doc:`fix langevin `, +:doc:`pair_style srp `, :doc:`fix mvv/dpd `. Default """"""" diff --git a/doc/src/pair_dpd_ext.rst b/doc/src/pair_dpd_ext.rst index 47c14fa813..1caed4689b 100644 --- a/doc/src/pair_dpd_ext.rst +++ b/doc/src/pair_dpd_ext.rst @@ -18,7 +18,6 @@ Accelerator Variants: dpd/ext/tstat/kk dpd/ext/tstat/omp Syntax """""" - .. code-block:: LAMMPS pair_style dpd/ext T cutoff seed @@ -32,16 +31,15 @@ Syntax Examples """""""" - .. code-block:: LAMMPS pair_style dpd/ext 1.0 2.5 34387 pair_coeff 1 1 25.0 4.5 4.5 0.5 0.5 1.2 pair_coeff 1 2 40.0 4.5 4.5 0.5 0.5 1.2 - pair_style dpd/ext/tstat 1.0 1.0 2.5 34387 - pair_coeff 1 1 4.5 4.5 0.5 0.5 1.2 - pair_coeff 1 2 4.5 4.5 0.5 0.5 1.2 + pair_style hybrid/overlay lj/cut 2.5 dpd/ext/tstat 1.0 1.0 2.5 34387 + pair_coeff * * lj/cut 1.0 1.0 + pair_coeff * * 4.5 4.5 0.5 0.5 1.2 Description """"""""""" @@ -128,20 +126,39 @@ the :doc:`pair_style ` command so it does not need to be specified. For the style *dpd/ext/tstat*, the coefficients defined for each pair of -atoms types via the :doc:`pair_coeff ` command is the same, -except that A is not included. +atoms types via the :doc:`pair_coeff ` command are: + +* :math:`\gamma_{\parallel}` (force/velocity units) +* :math:`\gamma_{\perp}` (force/velocity units) +* :math:`s_{\parallel}` (unitless) +* :math:`s_{\perp}` (unitless) +* :math:`r_c` (distance units) + +The last coefficient is optional. .. note:: If you are modeling DPD polymer chains, you may want to use the :doc:`pair_style srp ` command in conjunction with these pair - styles. It is a soft segmental repulsive potential (SRP) that can + styles. It is a soft segmental repulsive potential (SRP) that can prevent DPD polymer chains from crossing each other. .. note:: - The virial calculation for pressure when using this pair style includes - all the components of force listed above, including the random force. + The virial calculation for pressure when using these pair styles + includes all the components of force listed above, including the + random force. Since the random force depends on random numbers, + everything that changes the order of atoms in the neighbor list + (e.g. different number of MPI ranks or a different neighbor list + skin distance) will also change the sequence in which the random + numbers are applied and thus the individual forces and therefore + also the virial/pressure. + +.. note:: + + For more consistent time integration and force computation you may + consider using :doc:`fix mvv/dpd ` instead of :doc:`fix + nve `. ---------- @@ -207,7 +224,7 @@ Related commands :doc:`pair_style dpd `, :doc:`pair_coeff `, :doc:`fix nvt `, :doc:`fix langevin `, -:doc:`pair_style srp ` +:doc:`pair_style srp `, :doc:`fix mvv/dpd `. **Default:** none diff --git a/doc/src/pair_dpd_fdt.rst b/doc/src/pair_dpd_fdt.rst index 133e7ab52c..efe7b3ed66 100644 --- a/doc/src/pair_dpd_fdt.rst +++ b/doc/src/pair_dpd_fdt.rst @@ -56,13 +56,13 @@ given as a sum of 3 terms \vec{f} = & (F^C + F^D + F^R) \hat{r_{ij}} \qquad \qquad r < r_c \\ F^C = & A w(r) \\ - F^D = & - \gamma w^2(r) (\hat{r_{ij}} \bullet \vec{v_{ij}}) \\ + F^D = & - \gamma w^2(r) (\hat{r_{ij}} \bullet \vec{v}_{ij}) \\ F^R = & \sigma w(r) \alpha (\Delta t)^{-1/2} \\ w(r) = & 1 - \frac{r}{r_c} where :math:`F^C` is a conservative force, :math:`F^D` is a dissipative force, and :math:`F^R` is a random force. :math:`\hat{r_{ij}}` is a -unit vector in the direction :math:`r_i - r_j`, :math:`\vec{v_{ij}}` is +unit vector in the direction :math:`r_i - r_j`, :math:`\vec{v}_{ij}` is the vector difference in velocities of the two atoms, :math:`\vec{v}_i - \vec{v}_j`, :math:`\alpha` is a Gaussian random number with zero mean and unit variance, *dt* is the timestep size, and :math:`w(r)` is a @@ -99,9 +99,9 @@ energies are computed within style *dpd/fdt/energy* as: .. math:: du_{i}^{cond} = & \kappa_{ij}(\frac{1}{\theta_{i}}-\frac{1}{\theta_{j}})\omega_{ij}^{2} + \alpha_{ij}\omega_{ij}\zeta_{ij}^{q}(\Delta{t})^{-1/2} \\ - du_{i}^{mech} = & -\frac{1}{2}\gamma_{ij}\omega_{ij}^{2}(\frac{\vec{r_{ij}}}{r_{ij}}\bullet\vec{v_{ij}})^{2} - + du_{i}^{mech} = & -\frac{1}{2}\gamma_{ij}\omega_{ij}^{2}(\frac{\vec{r}_{ij}}{r_{ij}}\bullet\vec{v}_{ij})^{2} - \frac{\sigma^{2}_{ij}}{4}(\frac{1}{m_{i}}+\frac{1}{m_{j}})\omega_{ij}^{2} - - \frac{1}{2}\sigma_{ij}\omega_{ij}(\frac{\vec{r_{ij}}}{r_{ij}}\bullet\vec{v_{ij}})\zeta_{ij}(\Delta{t})^{-1/2} + \frac{1}{2}\sigma_{ij}\omega_{ij}(\frac{\vec{r}_{ij}}{r_{ij}}\bullet\vec{v}_{ij})\zeta_{ij}(\Delta{t})^{-1/2} where diff --git a/doc/src/pair_gauss.rst b/doc/src/pair_gauss.rst index 5ac8f2aff4..dbbe39d4cf 100644 --- a/doc/src/pair_gauss.rst +++ b/doc/src/pair_gauss.rst @@ -170,7 +170,7 @@ The *gauss* and *gauss/cut* styles are part of the EXTRA-PAIR package. They are only enabled if LAMMPS is build with that package. See the :doc:`Build package ` page for more info. -.. versionchanged:: TBD +.. versionchanged:: 28Mar2023 Prior to this version, the *gauss* pair style did not apply :doc:`special_bonds ` factors. diff --git a/doc/src/pair_granular.rst b/doc/src/pair_granular.rst index 0911a3486a..21afc1b4fc 100644 --- a/doc/src/pair_granular.rst +++ b/doc/src/pair_granular.rst @@ -650,13 +650,13 @@ For *heat* *area*, the heat .. math:: - Q = k_{s} a \Delta T + Q = k_{s} A \Delta T where :math:`\Delta T` is the difference in the two particles' temperature, :math:`k_{s}` is a non-negative numeric value for the conductivity, and -:math:`a` is the area of the contact and depends on the normal force model. +:math:`A` is the area of the contact and depends on the normal force model. Note that the option *none* must either be used in all or none of of the *pair_coeff* calls. See :doc:`fix heat/flow ` and diff --git a/doc/src/pair_lepton.rst b/doc/src/pair_lepton.rst index dbe3d74588..608265ecbd 100644 --- a/doc/src/pair_lepton.rst +++ b/doc/src/pair_lepton.rst @@ -2,11 +2,13 @@ .. index:: pair_style lepton/omp .. index:: pair_style lepton/coul .. index:: pair_style lepton/coul/omp +.. index:: pair_style lepton/sphere +.. index:: pair_style lepton/sphere/omp pair_style lepton command ========================= -Accelerator Variants: *lepton/omp*, *lepton/coul/comp* +Accelerator Variants: *lepton/omp*, *lepton/coul/comp*, *lepton/sphere/comp* Syntax """""" @@ -15,7 +17,7 @@ Syntax pair_style style args -* style = *lepton* or *lepton/coul* +* style = *lepton* or *lepton/coul* or *lepton/sphere* * args = list of arguments for a particular style .. parsed-literal:: @@ -26,6 +28,8 @@ Syntax cutoff = global cutoff for the interactions (distance units) zero or more keywords may be appended keyword = *ewald* or *pppm* or *msm* or *dispersion* or *tip4p* + *lepton/sphere* args = cutoff + cutoff = global cutoff for the interactions (distance units) Examples """""""" @@ -48,19 +52,32 @@ Examples kspace_style pppm 1.0e-4 pair_coeff 1 1 "qi*qj/r*erfc(alpha*r); alpha=1.067" + pair_style lepton/sphere 2.5 + pair_coeff 1 * "k*((r-r0)^2*step(r0-r)); k=200; r0=radi+radj" + pair_coeff 2 2 "4.0*eps*((sig/r)^12 - (sig/r)^6); eps=1.0; sig=2.0*sqrt(radi*radj)" + Description """"""""""" .. versionadded:: 8Feb2023 -Pair styles *lepton* and *lepton/coul* compute pairwise interactions -between particles which depend solely on the distance and have a cutoff. -The potential function must be provided as an expression string using -"r" as the distance variable. With pair style *lepton/coul* one may -additionally reference the charges of the two atoms of the pair with -"qi" and "qj", respectively. Note that further constants in the -expression can be defined in the same string as additional expressions -separated by semi-colons as shown in the examples above. +.. versionchanged:: TBD + + added pair style lepton/sphere + +Pair styles *lepton*, *lepton/coul*, *lepton/sphere* compute pairwise +interactions between particles which depend on the distance and have a +cutoff. The potential function must be provided as an expression string +using "r" as the distance variable. With pair style *lepton/coul* one +may additionally reference the charges of the two atoms of the pair with +"qi" and "qj", respectively. With pair style *lepton/coul* one may +instead reference the radii of the two atoms of the pair with "radi" and +"radj", respectively; this is half of the diameter that can be set in +:doc:`data files ` or the :doc:`set command `. + +Note that further constants in the expressions can be defined in the +same string as additional expressions separated by semicolons as shown +in the examples above. The expression `"200.0*(r-1.5)^2"` represents a harmonic potential around the pairwise distance :math:`r_0` of 1.5 distance units and a @@ -76,6 +93,14 @@ The expression `"qi*qj/r"` represents a regular Coulombic potential with cutoff: U_{ij} = \frac{C q_i q_j}{\epsilon r} \qquad r < r_c +The expression `"200.0*(r-(radi+radj)^2"` represents a harmonic potential +that has the equilibrium distance chosen so that the radii of the two +atoms touch: + +.. math:: + + U_{ij} = K (r-(r_i+r_j))^2 + The `Lepton library `_, that the *lepton* pair style interfaces with, evaluates this expression string at run time to compute the pairwise energy. It also creates an analytical @@ -97,13 +122,20 @@ More on valid Lepton expressions below. The last coefficient is optional; it allows to set the cutoff for a pair of atom types to a different value than the global cutoff. -For pair style *lepton* only the "lj" value of the :doc:`special_bonds ` -settings apply in case the interacting pair is also connected with a bond. -The potential energy will *only* be added to the "evdwl" property. +For pair style *lepton* only the "lj" values of the :doc:`special_bonds +` settings apply in case the interacting pair is also +connected with a bond. The potential energy will *only* be added to the +"evdwl" property. -For pair style *lepton/coul* only the "coul" value of the :doc:`special_bonds ` -settings apply in case the interacting pair is also connected with a bond. -The potential energy will *only* be added to the "ecoul" property. +For pair style *lepton/coul* only the "coul" values of the +:doc:`special_bonds ` settings apply in case the +interacting pair is also connected with a bond. The potential energy +will *only* be added to the "ecoul" property. + +For pair style *lepton/sphere* only the "lj" values of the +:doc:`special_bonds ` settings apply in case the +interacting pair is also connected with a bond. The potential energy +will *only* be added to the "evdwl" property. In addition to the functions listed below, both pair styles support in addition a custom "zbl(zi,zj,r)" function which computes the @@ -127,12 +159,13 @@ above. Mixing, shift, table, tail correction, restart, rRESPA info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" -Pair styles *lepton* and *lepton/coul* do not support mixing. Thus, -expressions for *all* I,J pairs must be specified explicitly. +Pair styles *lepton*, *lepton/coul*, and *lepton/sphere* do not support +mixing. Thus, expressions for *all* I,J pairs must be specified +explicitly. Only pair style *lepton* supports the :doc:`pair_modify shift ` option for shifting the energy of the pair interaction so that it is -0 at the cutoff, pair style *lepton/coul* does *not*. +0 at the cutoff, pair styles *lepton/coul* and *lepton/sphere* do *not*. The :doc:`pair_modify table ` options are not relevant for the these pair styles. @@ -141,7 +174,7 @@ These pair styles do not support the :doc:`pair_modify tail ` option for adding long-range tail corrections to energy and pressure. -These pair styles write its information to :doc:`binary restart files +These pair styles write their information to :doc:`binary restart files `, so pair_style and pair_coeff commands do not need to be specified in an input script that reads a restart file. @@ -158,6 +191,12 @@ These pair styles are part of the LEPTON package and only enabled if LAMMPS was built with this package. See the :doc:`Build package ` page for more info. +Pair style *lepton/coul* requires that atom atoms have a charge +property, e.g. via :doc:`atom_style charge `. + +Pair style *lepton/sphere* requires that atom atoms have a radius +property, e.g. via :doc:`atom_style sphere `. + Related commands """""""""""""""" diff --git a/doc/src/pair_lj.rst b/doc/src/pair_lj.rst index 939756e550..1a099e009b 100644 --- a/doc/src/pair_lj.rst +++ b/doc/src/pair_lj.rst @@ -43,8 +43,7 @@ given by .. math:: E = 4 \epsilon \left[ \left(\frac{\sigma}{r}\right)^{12} - - \left(\frac{\sigma}{r}\right)^6 \right] - \qquad r < r_c + \left(\frac{\sigma}{r}\right)^6 \right] \qquad r < r_c :math:`r_c` is the cutoff. @@ -64,11 +63,23 @@ file or restart files read by the :doc:`read_data ` or * :math:`\sigma` (distance units) * LJ cutoff (distance units) -Note that :math:`\sigma` is defined in the LJ formula as the zero-crossing -distance for the potential, not as the energy minimum at :math:`2^{\frac{1}{6}} \sigma`. - The last coefficient is optional. If not specified, the global -LJ cutoff specified in the pair_style command are used. +LJ cutoff specified in the pair_style command is used. + +Note that :math:`\sigma` is defined in the LJ formula as the +zero-crossing distance for the potential, *not* as the energy minimum at +:math:`r_0 = 2^{\frac{1}{6}} \sigma`. The _same_ potential function becomes: + +.. math:: + + E = \epsilon \left[ \left(\frac{r_0}{r}\right)^{12} - + 2 \left(\frac{r_0}{r}\right)^6 \right] \qquad r < r_c + +When using the minimum as reference width. In the literature both +formulations are used, but the describe the same potential, only the +:math:`\sigma` value must be computed by :math:`\sigma = r_0 / +2^{\frac{1}{6}}` for use with LAMMPS, if this latter formulation is +used. ---------- @@ -103,11 +114,12 @@ portion of the pair interaction. All of the *lj/cut* pair styles write their information to :doc:`binary restart files `, so pair_style and pair_coeff commands do not need to be specified in an input script that reads a restart file. -The *lj/cut* pair styles support the use of the -*inner*, *middle*, and *outer* keywords of the :doc:`run_style respa ` command, meaning the pairwise forces can be -partitioned by distance at different levels of the rRESPA hierarchy. -The other styles only support the *pair* keyword of run_style respa. -See the :doc:`run_style ` command for details. +The *lj/cut* pair styles support the use of the *inner*, *middle*, and +*outer* keywords of the :doc:`run_style respa ` command, +meaning the pairwise forces can be partitioned by distance at different +levels of the rRESPA hierarchy. The other styles only support the +*pair* keyword of run_style respa. See the :doc:`run_style ` +command for details. ---------- diff --git a/doc/src/pair_lj_cut_sphere.rst b/doc/src/pair_lj_cut_sphere.rst new file mode 100644 index 0000000000..428047d5df --- /dev/null +++ b/doc/src/pair_lj_cut_sphere.rst @@ -0,0 +1,192 @@ +.. index:: pair_style lj/cut/sphere +.. index:: pair_style lj/cut/sphere/omp + +pair_style lj/cut/sphere command +================================ + +Accelerator Variant: *lj/cut/sphere/omp* + +Syntax +"""""" + +.. code-block:: LAMMPS + + pair_style style args + +* style = *lj/cut/sphere* +* args = list of arguments for a particular style + +.. parsed-literal:: + + *lj/cut/sphere* args = cutoff ratio + cutoff = global cutoff ratio for Lennard Jones interactions (unitless) + +Examples +"""""""" + +.. code-block:: LAMMPS + + pair_style lj/cut/sphere 2.5 + pair_coeff * * 1.0 + pair_coeff 1 1 1.1 2.8 + +Description +""""""""""" + +.. versionadded:: TBD + +The *lj/cut/sphere* style compute the standard 12/6 Lennard-Jones potential, +given by + +.. math:: + + E = 4 \epsilon \left[ \left(\frac{\sigma_{ij}}{r}\right)^{12} - + \left(\frac{\sigma_{ij}}{r}\right)^6 \right] \qquad r < r_c * \sigma_{ij} + +:math:`r_c` is the cutoff ratio. + +This is the same potential function used by the :doc:`lj/cut +` pair style, but the :math:`\sigma_{ij}` parameter is not +set as a per-type parameter via the :doc:`pair_coeff command +`. Instead it is calculated individually for each pair +using the per-atom diameter attribute of :doc:`atom_style sphere +` for the two atoms as :math:`\sigma_{i}` and +:math:`\sigma_{j}`; :math:`\sigma_{ij}` is then computed by the mixing +rule for pair coefficients as set by the :doc:`pair_modify mix +` command (defaults to geometric mixing). The cutoff is +not specified as a distance, but as ratio that is internally +multiplied by :math:`\sigma_{ij}` to obtain the actual cutoff for each +pair of atoms. + +Note that :math:`\sigma_{ij}` is defined in the LJ formula above as the +zero-crossing distance for the potential, *not* as the energy minimum which +is at :math:`2^{\frac{1}{6}} \sigma_{ij}`. + +.. admonition:: Notes on cutoffs, neighbor lists, and efficiency + :class: note + + If your system is mildly polydisperse, meaning the ratio of the + diameter of the largest particle to the smallest is less than 2.0, + then the neighbor lists built by the code should be reasonably + efficient. Which means they will not contain too many particle + pairs that do not interact. However, if your system is highly + polydisperse (ratio > 2.0), the neighbor list build and force + computations may be inefficient. There are two ways to try and + speed up the simulations. + + The first is to assign atoms to different atom types so that atoms of + each type are similar in size. E.g. if particle diameters range from + 1 to 5 use 4 atom types, ensuring atoms of type 1 have diameters from + 1.0-2.0, type 2 from 2.0-3.0, etc. This will reduce the number of + non-interacting pairs in the neighbor lists and thus reduce the time + spent on computing pairwise interactions. + + The second is to use the :doc:`neighbor multi ` command + which enabled a different algorithm for building neighbor lists. This + will also require that you assign multiple atom types according to + diameters, but will in addition use a more efficient size-dependent + strategy to construct the neighbor lists and thus reduce the time + spent on building neighbor lists. + + Here are example input script commands using both ideas for a + highly polydisperse system: + + .. code-block:: c++ + + units lj + atom_style sphere + lattice fcc 0.8442 + region box block 0 10 0 10 0 10 + create_box 2 box + create_atoms 1 box + + # create atoms with random diameters from bimodal distribution + variable switch atom random(0.0,1.0,345634) + variable diam atom (v_switch<0.75)*normal(0.4,0.075,325)+(v_switch>=0.7)*normal(1.2,0.2,453) + set group all diameter v_diam + + # assign type 2 to atoms with diameter > 0.6 + variable large atom (2.0*radius)>0.6 + group large variable large + set group large type 2 + + pair_style lj/cut/sphere 2.5 + pair_coeff * * 1.0 + + neighbor 0.3 multi + + Using multiple atom types speeds up the calculation for this example + by more than a factor of 2, and using the multi-style neighbor list + build causes an additional speedup of about 20 percent. + +Coefficients +"""""""""""" + +The following coefficients must be defined for each pair of atoms types via the +:doc:`pair_coeff ` command as in the examples above, or in the data +file or restart files read by the :doc:`read_data ` or +:doc:`read_restart ` commands, or by mixing as described below: + +* :math:`\epsilon` (energy units) +* LJ cutoff ratio (unitless) (optional) + +The last coefficient is optional. If not specified, the global LJ +cutoff ratio specified in the :doc:`pair_style command ` is +used. + +If a repulsive only LJ interaction is desired, the coefficient for the cutoff +ratio should be set to the minimum of the LJ potential using ``$(2.0^(1.0/6.0))`` + +---------- + +.. include:: accel_styles.rst + +---------- + +Mixing, shift, table, tail correction, restart, rRESPA info +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +For atom type pairs I,J and I != J, the epsilon coefficients and cutoff +ratio for the *lj/cut/sphere* pair style can be mixed. The default mixing +style is *geometric*. See the :doc:`pair_modify command ` +for details. + +The *lj/cut/sphere* pair style supports the :doc:`pair_modify shift ` +option for the energy of the Lennard-Jones portion of the pair interaction. + +The *lj/cut/sphere* pair style does *not* support the :doc:`pair_modify +` tail option for adding a long-range tail corrections to +the energy and pressure. + +The *lj/cut/sphere* pair style writes its information to :doc:`binary +restart files `, so pair_style and pair_coeff commands do not +need to be specified in an input script that reads a restart file. + +This pair style can only be used via the *pair* keyword of the +:doc:`run_style respa ` command. It does *not* support the +*inner*, *middle*, *outer* keywords. + +---------- + +Restrictions +"""""""""""" + +The *lj/cut/sphere* pair style is only enabled if LAMMPS was built with the +EXTRA-PAIR package. See the :doc:`Build package ` page +for more info. + +The *lj/cut/sphere* pair style does not support the *sixthpower* mixing rule. + +---------- + +Related commands +"""""""""""""""" + +* :doc:`pair_coeff ` +* :doc:`pair_style lj/cut ` +* :doc:`pair_style lj/expnd/sphere ` + +Default +""""""" + +none diff --git a/doc/src/pair_lj_expand_sphere.rst b/doc/src/pair_lj_expand_sphere.rst new file mode 100644 index 0000000000..c60cf160f0 --- /dev/null +++ b/doc/src/pair_lj_expand_sphere.rst @@ -0,0 +1,187 @@ +.. index:: pair_style lj/expand/sphere +.. index:: pair_style lj/expand/sphere/omp + +pair_style lj/expand/sphere command +=================================== + +Accelerator Variant: *lj/expand/sphere/omp* + +Syntax +"""""" + +.. code-block:: LAMMPS + + pair_style style args + +* style = *lj/expand/sphere* +* args = list of arguments for a particular style + +.. parsed-literal:: + + *lj/expand/sphere* args = cutoff + cutoff = global cutoff for Lennard Jones interactions (distance units) + +Examples +"""""""" + +.. code-block:: LAMMPS + + pair_style lj/expand/sphere 2.5 + pair_coeff * * 1.0 1.0 + pair_coeff 1 1 1.1 0.4 2.8 + +Description +""""""""""" + +.. versionadded:: TBD + +The *lj/expand/sphere* style compute a 12/6 Lennard-Jones potential with +a distance shifted by :math:`\Delta = \frac{1}{2} (d_i + d_j)`, the +average diameter of both atoms. This can be used to model particles of +different sizes but same interactions, which is different from using +different sigma values as in :doc:`pair style lj/cut/sphere +`. + +.. math:: + + E = 4 \epsilon \left[ \left(\frac{\sigma}{r - \Delta}\right)^{12} - + \left(\frac{\sigma}{r - \Delta}\right)^6 \right] + \qquad r < r_c + \Delta + +:math:`r_c` is the cutoff which does not include the distance :math:`\Delta`. +I.e. the actual force cutoff is the sum :math:`r_c + \Delta`. + +This is the same potential function used by the :doc:`lj/expand +` pair style, but the :math:`\Delta` parameter is not +set as a per-type parameter via the :doc:`pair_coeff command +`. Instead it is calculated individually for each pair +using the per-atom diameter attribute of :doc:`atom_style sphere +` for the two atoms as the average diameter, :math:`\Delta = \frac{1}{2} (d_i + d_j)` + +Note that :math:`\sigma` is defined in the LJ formula above as the +zero-crossing distance for the potential, *not* as the energy minimum which +is at :math:`2^{\frac{1}{6}} \sigma`. + +.. admonition:: Notes on cutoffs, neighbor lists, and efficiency + :class: note + + If your system is mildly polydisperse, meaning the ratio of the + diameter of the largest particle to the smallest is less than 2.0, + then the neighbor lists built by the code should be reasonably + efficient. Which means they will not contain too many particle + pairs that do not interact. However, if your system is highly + polydisperse (ratio > 2.0), the neighbor list build and force + computations may be inefficient. There are two ways to try and + speed up the simulations. + + The first is to assign atoms to different atom types so that atoms of + each type are similar in size. E.g. if particle diameters range from + 1 to 5 use 4 atom types, ensuring atoms of type 1 have diameters from + 1.0-2.0, type 2 from 2.0-3.0, etc. This will reduce the number of + non-interacting pairs in the neighbor lists and thus reduce the time + spent on computing pairwise interactions. + + The second is to use the :doc:`neighbor multi ` command + which enabled a different algorithm for building neighbor lists. This + will also require that you assign multiple atom types according to + diameters, but will in addition use a more efficient size-dependent + strategy to construct the neighbor lists and thus reduce the time + spent on building neighbor lists. + + Here are example input script commands using the first option for a + highly polydisperse system: + + .. code-block:: c++ + + units lj + atom_style sphere + lattice fcc 0.8442 + region box block 0 10 0 10 0 10 + create_box 2 box + create_atoms 1 box + + # create atoms with random diameters from bimodal distribution + variable switch atom random(0.0,1.0,345634) + variable diam atom (v_switch<0.75)*normal(0.2,0.04,325)+(v_switch>=0.7)*normal(0.6,0.2,453) + set group all diameter v_diam + + # assign type 2 to atoms with diameter > 0.35 + variable large atom (2.0*radius)>0.35 + group large variable large + set group large type 2 + + pair_style lj/expand/sphere 2.0 + pair_coeff * * 1.0 0.5 + + neighbor 0.3 bin + + Using multiple atom types speeds up the calculation for this example + by more than 30 percent, but using the multi-style neighbor list does + not provide a speedup. + +Coefficients +"""""""""""" + +The following coefficients must be defined for each pair of atoms types via the +:doc:`pair_coeff ` command as in the examples above, or in the data +file or restart files read by the :doc:`read_data ` or +:doc:`read_restart ` commands, or by mixing as described below: + +* :math:`\epsilon` (energy units) +* :math:`\sigma` (distance units) +* LJ cutoff (distance units) (optional) + +The last coefficient is optional. If not specified, the global LJ +cutoff specified in the :doc:`pair_style command ` is used. + +---------- + +.. include:: accel_styles.rst + +---------- + +Mixing, shift, table, tail correction, restart, rRESPA info +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +For atom type pairs I,J and I != J, the epsilon, sigma, and cutoff +coefficients for the *lj/expand/sphere* pair style can be mixed. The +default mixing style is *geometric*. See the :doc:`pair_modify command +` for details. + +The *lj/expand/sphere* pair style supports the :doc:`pair_modify shift ` +option for the energy of the Lennard-Jones portion of the pair interaction. + +The *lj/expand/sphere* pair style does *not* support the :doc:`pair_modify +` tail option for adding a long-range tail corrections to +the energy and pressure. + +The *lj/expand/sphere* pair style writes its information to :doc:`binary +restart files `, so pair_style and pair_coeff commands do not +need to be specified in an input script that reads a restart file. + +This pair style can only be used via the *pair* keyword of the +:doc:`run_style respa ` command. It does *not* support the +*inner*, *middle*, *outer* keywords. + +---------- + +Restrictions +"""""""""""" + +The *lj/expand/sphere* pair style is only enabled if LAMMPS was built with the +EXTRA-PAIR package. See the :doc:`Build package ` page +for more info. + +---------- + +Related commands +"""""""""""""""" + +* :doc:`pair_coeff ` +* :doc:`pair_style lj/cut ` +* :doc:`pair_style lj/cut/sphere ` + +Default +""""""" + +none diff --git a/doc/src/pair_pace.rst b/doc/src/pair_pace.rst index 10c91e31e1..d815f663fe 100644 --- a/doc/src/pair_pace.rst +++ b/doc/src/pair_pace.rst @@ -48,9 +48,9 @@ Description Pair style *pace* computes interactions using the Atomic Cluster Expansion (ACE), which is a general expansion of the atomic energy in -multi-body basis functions. :ref:`(Drautz) `. The *pace* +multi-body basis functions. :ref:`(Drautz19) `. The *pace* pair style provides an efficient implementation that is described in -this paper :ref:`(Lysogorskiy) `. +this paper :ref:`(Lysogorskiy21) `. In ACE, the total energy is decomposed into a sum over atomic energies. The energy of atom *i* is expressed as a linear or non-linear @@ -91,7 +91,7 @@ Extrapolation grade Calculation of extrapolation grade in PACE is implemented in `pair_style pace/extrapolation`. It is based on the MaxVol algorithm similar to Moment Tensor Potential (MTP) by Shapeev et al. and is described in -:ref:`(Lysogorskiy2) `. In order to compute +:ref:`(Lysogorskiy23) `. In order to compute extrapolation grade one needs to provide: #. ACE potential in B-basis form (`.yaml` format) and @@ -182,12 +182,12 @@ recursive, chunksize = 4096, .. _Drautz20191: -**(Drautz)** Drautz, Phys Rev B, 99, 014104 (2019). +**(Drautz19)** Drautz, Phys Rev B, 99, 014104 (2019). .. _Lysogorskiy20211: -**(Lysogorskiy)** Lysogorskiy, van der Oord, Bochkarev, Menon, Rinaldi, Hammerschmidt, Mrovec, Thompson, Csanyi, Ortner, Drautz, npj Comp Mat, 7, 97 (2021). +**(Lysogorskiy21)** Lysogorskiy, van der Oord, Bochkarev, Menon, Rinaldi, Hammerschmidt, Mrovec, Thompson, Csanyi, Ortner, Drautz, npj Comp Mat, 7, 97 (2021). -.. _Lysogorskiy2022: +.. _Lysogorskiy2023: -**(Lysogorskiy2022)** Lysogorskiy, Bochkarev, Mrovec, Drautz, arXiv:2212.08716 (2022). +**(Lysogorskiy23)** Lysogorskiy, Bochkarev, Mrovec, Drautz, Phys Rev Mater, 7, 043801 (2023) / arXiv:2212.08716 (2022). diff --git a/doc/src/pair_smtbq.rst b/doc/src/pair_smtbq.rst index ea55b2f2d9..85b7f95fb5 100644 --- a/doc/src/pair_smtbq.rst +++ b/doc/src/pair_smtbq.rst @@ -23,8 +23,9 @@ Description This pair style computes a variable charge SMTB-Q (Second-Moment tight-Binding QEq) potential as described in :ref:`SMTB-Q_1 ` and -:ref:`SMTB-Q_2 `. Briefly, the energy of metallic-oxygen systems -is given by three contributions: +:ref:`SMTB-Q_2 `. +This potential was first proposed in :ref:`SMTB-Q_0 `. +Briefly, the energy of metallic-oxygen systems is given by three contributions: .. math:: @@ -208,7 +209,7 @@ For each cations (metal): 6) Coordination parameter: * First (:math:`r_{1n}`) and second (:math:`r_{2n}`) neighbor distances - in Angstrom + in angstroms * Divider line 7) Charge initialization mode: @@ -306,6 +307,12 @@ and R. Tetot, Comput. Mater. Sci. 111 (2016) 181-189 ---------- +.. _SMTB-Q_0: + +**(SMTB-Q_0)** A. Hallil, E. Amzallag, S. Landron, R. Tetot, +Surface Science 605 738-745 (2011); +R. Tetot, A. Hallil, J. Creuze and I. Braems, EPL, 83 40001 (2008) + .. _SMTB-Q_1: **(SMTB-Q_1)** N. Salles, O. Politano, E. Amzallag, R. Tetot, diff --git a/doc/src/pair_style.rst b/doc/src/pair_style.rst index b3f7276480..441313b0b8 100644 --- a/doc/src/pair_style.rst +++ b/doc/src/pair_style.rst @@ -132,6 +132,7 @@ accelerated styles exist. * :doc:`born/coul/msm ` - Born with long-range MSM Coulomb * :doc:`born/coul/wolf ` - Born with Wolf potential for Coulomb * :doc:`born/coul/wolf/cs ` - Born with Wolf potential for Coulomb and core/shell model +* :doc:`born/gauss ` - Born-Mayer / Gaussian potential * :doc:`bpm/spring ` - repulsive harmonic force with damping * :doc:`brownian ` - Brownian potential for Fast Lubrication Dynamics * :doc:`brownian/poly ` - Brownian potential for Fast Lubrication Dynamics with polydispersity @@ -214,6 +215,7 @@ accelerated styles exist. * :doc:`lennard/mdf ` - LJ potential in A/B form with a taper function * :doc:`lepton ` - pair potential from evaluating a string * :doc:`lepton/coul ` - pair potential from evaluating a string with support for charges +* :doc:`lepton/sphere ` - pair potential from evaluating a string with support for radii * :doc:`line/lj ` - LJ potential between line segments * :doc:`list ` - potential between pairs of atoms explicitly listed in an input file * :doc:`lj/charmm/coul/charmm ` - CHARMM potential with cutoff Coulomb @@ -248,12 +250,14 @@ accelerated styles exist. * :doc:`lj/cut/dipole/cut ` - point dipoles with cutoff * :doc:`lj/cut/dipole/long ` - point dipoles with long-range Ewald * :doc:`lj/cut/soft ` - LJ with a soft core +* :doc:`lj/cut/sphere ` - LJ where per-atom radius is used as LJ sigma * :doc:`lj/cut/thole/long ` - LJ with Coulomb with thole damping * :doc:`lj/cut/tip4p/cut ` - LJ with cutoff Coulomb for TIP4P water * :doc:`lj/cut/tip4p/long ` - LJ with long-range Coulomb for TIP4P water * :doc:`lj/cut/tip4p/long/soft ` - LJ with cutoff Coulomb for TIP4P water with a soft core * :doc:`lj/expand ` - Lennard-Jones for variable size particles * :doc:`lj/expand/coul/long ` - Lennard-Jones for variable size particles with long-range Coulomb +* :doc:`lj/expand/sphere ` - Variable size LJ where per-atom radius is used as delta (size) * :doc:`lj/gromacs ` - GROMACS-style Lennard-Jones potential * :doc:`lj/gromacs/coul/gromacs ` - GROMACS-style LJ and Coulomb potential * :doc:`lj/long/coul/long ` - long-range LJ and long-range Coulomb diff --git a/doc/src/print.rst b/doc/src/print.rst index 1211fdd569..f5a872e768 100644 --- a/doc/src/print.rst +++ b/doc/src/print.rst @@ -46,6 +46,20 @@ lines of output, the string can be enclosed in triple quotes, as in the last example above. If the text string contains variables, they will be evaluated and their current values printed. +.. versionadded:: TBD + + support for vector style variables + +See the :doc:`variable ` command for a description of +*equal* and *vector* style variables which are typically the most +useful ones to use with the print command. Equal- and vector-style +variables can calculate formulas involving mathematical operations, +atom properties, group properties, thermodynamic properties, global +values calculated by a :doc:`compute ` or :doc:`fix `, +or references to other :doc:`variables `. Vector-style +variables are printed in a bracketed, comma-separated format, +e.g. [1,2,3,4] or [12.5,2,4.6,10.1]. + .. note:: As discussed on the :doc:`Commands parse ` doc @@ -60,6 +74,15 @@ will be evaluated and their current values printed. This is also explained on the :doc:`Commands parse ` doc page. +If you want the print command to be executed multiple times (with +changing variable values), there are 3 options. First, consider using +the :doc:`fix print ` command, which will print a string +periodically during a simulation. Second, the print command can be +used as an argument to the *every* option of the :doc:`run ` +command. Third, the print command could appear in a section of the +input script that is looped over (see the :doc:`jump ` and +:doc:`next ` commands). + If the *file* or *append* keyword is used, a filename is specified to which the output will be written. If *file* is used, then the filename is overwritten if it already exists. If *append* is used, @@ -74,23 +97,6 @@ logfile can be turned on or off as desired. In multi-partition calculations, the *screen* option and the corresponding output only apply to the screen and logfile of the individual partition. -If you want the print command to be executed multiple times (with -changing variable values), there are 3 options. First, consider using -the :doc:`fix print ` command, which will print a string -periodically during a simulation. Second, the print command can be -used as an argument to the *every* option of the :doc:`run ` -command. Third, the print command could appear in a section of the -input script that is looped over (see the :doc:`jump ` and -:doc:`next ` commands). - -See the :doc:`variable ` command for a description of *equal* -style variables which are typically the most useful ones to use with -the print command. Equal-style variables can calculate formulas -involving mathematical operations, atom properties, group properties, -thermodynamic properties, global values calculated by a -:doc:`compute ` or :doc:`fix `, or references to other -:doc:`variables `. - Restrictions """""""""""" none diff --git a/doc/src/read_dump.rst b/doc/src/read_dump.rst index c03b3b50de..59d6cca78d 100644 --- a/doc/src/read_dump.rst +++ b/doc/src/read_dump.rst @@ -132,7 +132,7 @@ files can be written by LAMMPS via the :doc:`dump dcd ` command. The *path* value specifies a list of directories which LAMMPS will search for the molfile plugins appropriate to the specified *style*\ . The syntax of the *path* value is like other search paths: it can -contain multiple directories separated by a colon (or semi-colon on +contain multiple directories separated by a colon (or semicolon on windows). The *path* keyword is optional and defaults to ".", i.e. the current directory. diff --git a/doc/src/region.rst b/doc/src/region.rst index 4ebd731073..4589e6deb1 100644 --- a/doc/src/region.rst +++ b/doc/src/region.rst @@ -18,6 +18,7 @@ Syntax *delete* = no args *block* args = xlo xhi ylo yhi zlo zhi xlo,xhi,ylo,yhi,zlo,zhi = bounds of block in all dimensions (distance units) + xlo,xhi,ylo,yhi,zlo,zhi can be a variable *cone* args = dim c1 c2 radlo radhi lo hi dim = *x* or *y* or *z* = axis of cone c1,c2 = coords of cone axis in other 2 dimensions (distance units) diff --git a/doc/src/set.rst b/doc/src/set.rst index 0073e44bf8..2ba1057ef5 100644 --- a/doc/src/set.rst +++ b/doc/src/set.rst @@ -11,7 +11,16 @@ Syntax set style ID keyword values ... * style = *atom* or *type* or *mol* or *group* or *region* -* ID = atom ID range or type range or mol ID range or group ID or region ID +* ID = depends on style + +.. parsed-literal:: + + for style = *atom*, ID = a range of atom IDs + for style = *type*, ID = a range of numeric types or a single type label + for style = *mol*, ID = a range of molecule IDs + for style = *group*, ID = a group ID + for style = *region*, ID = a region ID + * one or more keyword/value pairs may be appended * keyword = *type* or *type/fraction* or *type/ratio* or *type/subset* or *mol* or *x* or *y* or *z* or *vx* or *vy* or *vz* or *charge* or @@ -28,22 +37,22 @@ Syntax .. parsed-literal:: - *type* value = atom type + *type* value = numeric atom type or type label value can be an atom-style variable (see below) *type/fraction* values = type fraction seed - type = new atom type + type = numeric atom type or type label fraction = approximate fraction of selected atoms to set to new atom type seed = random # seed (positive integer) *type/ratio* values = type fraction seed - type = new atom type + type = numeric atom type or type label fraction = exact fraction of selected atoms to set to new atom type seed = random # seed (positive integer) *type/subset* values = type Nsubset seed - type = new atom type + type = numeric atom type or type label Nsubset = exact number of selected atoms to set to new atom type seed = random # seed (positive integer) *mol* value = molecule ID - value can be an atom-style variable (see below) + value can be an atom-style variable (see below) *x*,\ *y*,\ *z* value = atom coordinate (distance units) value can be an atom-style variable (see below) *vx*,\ *vy*,\ *vz* value = atom velocity (velocity units) @@ -107,10 +116,10 @@ Syntax *image* nx ny nz nx,ny,nz = which periodic image of the simulation box the atom is in any of nx,ny,nz can be an atom-style variable (see below) - *bond* value = bond type for all bonds between selected atoms - *angle* value = angle type for all angles between selected atoms - *dihedral* value = dihedral type for all dihedrals between selected atoms - *improper* value = improper type for all impropers between selected atoms + *bond* value = numeric bond type or bond type label, for all bonds between selected atoms + *angle* value = numeric angle type or angle type label, for all angles between selected atoms + *dihedral* value = numeric dihedral type or dihedral type label, for all dihedrals between selected atoms + *improper* value = numeric improper type or improper type label, for all impropers between selected atoms *sph/e* value = energy of SPH particles (need units) value can be an atom-style variable (see below) *sph/cv* value = heat capacity of SPH particles (need units) @@ -145,15 +154,19 @@ Examples .. code-block:: LAMMPS set group solvent type 2 + set group solvent type C set group solvent type/fraction 2 0.5 12393 + set group solvent type/fraction C 0.5 12393 set group edge bond 4 set region half charge 0.5 set type 3 charge 0.5 + set type H charge 0.5 set type 1*3 charge 0.5 set atom * charge v_atomfile set atom 100*200 x 0.5 y 1.0 set atom 100 vx 0.0 vy 0.0 vz -1.0 set atom 1492 type 3 + set atom 1492 type H set atom * i_myVal 5 set atom * d2_Sxyz[1] 6.4 @@ -183,9 +196,17 @@ properties to reset and what the new values are. Some strings like This section describes how to select which atoms to change the properties of, via the *style* and *ID* arguments. -The style *atom* selects all the atoms in a range of atom IDs. The -style *type* selects all the atoms in a range of types. The style -*mol* selects all the atoms in a range of molecule IDs. +.. versionchanged:: 28Mar2023 + + Support for type labels was added for selecting atoms by type + +The style *atom* selects all the atoms in a range of atom IDs. + +The style *type* selects all the atoms in a range of types or type +labels. The style *type* selects atoms in one of two ways. A range +of numeric atom types can be specified. Or a single atom type label +can be specified, e.g. "C". The style *mol* selects all the atoms in +a range of molecule IDs. In each of the range cases, the range can be specified as a single numeric value, or a wildcard asterisk can be used to specify a range @@ -237,14 +258,23 @@ from a file. such as the molecule ID, then the floating point value is truncated to its integer portion, e.g. a value of 2.6 would become 2. -Keyword *type* sets the atom type for all selected atoms. The -specified value must be from 1 to ntypes, where ntypes was set by the -:doc:`create_box ` command or the *atom types* field in the -header of the data file read by the :doc:`read_data ` -command. +.. versionchanged:: 28Mar2023 -Keyword *type/fraction* sets the atom type for a fraction of the -selected atoms. The actual number of atoms changed is not guaranteed + Support for type labels was added for setting atom, bond, angle, + dihedral, and improper types + +Keyword *type* sets the atom type for all selected atoms. A specified +value can be either a numeric atom type or an atom type label. When +using a numeric type, the specified value must be from 1 to ntypes, +where ntypes was set by the :doc:`create_box ` command or +the *atom types* field in the header of the data file read by the +:doc:`read_data ` command. When using a type label it must +have been defined previously. See the :doc:`Howto type labels +` doc page for the allowed syntax of type labels +and a general discussion of how type labels can be used. + +Keyword *type/fraction* sets the atom type for a fraction of the selected +atoms. The actual number of atoms changed is not guaranteed to be exactly the specified fraction (0 <= *fraction* <= 1), but should be statistically close. Random numbers are used in such a way that a particular atom is changed or not changed, regardless of how @@ -463,14 +493,18 @@ simulation, but may mess up analysis of the trajectories if a LAMMPS diagnostic or your own analysis relies on the image flags to unwrap a molecule which straddles the periodic box. -Keywords *bond*, *angle*, *dihedral*, and *improper*, set the bond type -(angle type, etc) of all bonds (angles, etc) of selected atoms to the -specified value from 1 to nbondtypes (nangletypes, etc). All atoms in a -particular bond (angle, etc) must be selected atoms in order for the -change to be made. The value of nbondtype (nangletypes, etc) was set by -the *bond types* (\ *angle types*, etc) field in the header of the data -file read by the :doc:`read_data ` command. These keywords -do not allow use of an atom-style variable. +Keywords *bond*, *angle*, *dihedral*, and *improper*, set the bond +type (angle type, etc) of all bonds (angles, etc) of selected atoms to +the specified value. The value can be a numeric type from 1 to +nbondtypes (nangletypes, etc). Or it can be a type label (bond type +label, angle type label, etc). See the :doc:`Howto type labels +` doc page for the allowed syntax of type labels +and a general discussion of how type labels can be used. All atoms in +a particular bond (angle, etc) must be selected atoms in order for the +change to be made. The value of nbondtypes (nangletypes, etc) was set +by the *bond types* (\ *angle types*, etc) field in the header of the +data file read by the :doc:`read_data ` command. These +keywords do not allow use of an atom-style variable. Keywords *sph/e*, *sph/cv*, and *sph/rho* set the energy, heat capacity, and density of smoothed particle hydrodynamics (SPH) particles. See diff --git a/doc/src/special_bonds.rst b/doc/src/special_bonds.rst index 61c7976974..b1104d57cf 100644 --- a/doc/src/special_bonds.rst +++ b/doc/src/special_bonds.rst @@ -92,9 +92,24 @@ The Coulomb factors are applied to any Coulomb (charge interaction) term that the potential calculates. The LJ factors are applied to the remaining terms that the potential calculates, whether they represent LJ interactions or not. The weighting factors are a scaling -prefactor on the energy and force between the pair of atoms. A value -of 1.0 means include the full interaction; a value of 0.0 means -exclude it completely. +prefactor on the energy and force between the pair of atoms. + +A value of 1.0 means include the full interaction without flagging the +pair as a "special pair"; a value of 0.0 means exclude the pair +completely from the neighbor list, except for pair styles that require a +:doc:`kspace style ` and pair styles :doc:`amoeba +`, :doc:`hippo `, :doc:`thole `, +:doc:`coul/exclude `, and pair styles that include +"coul/dsf" or "coul/wolf". + +.. note:: + + To include pairs that would otherwise be excluded (so they are + included in the neighbor list for certain analysis compute styles), + you can use a very small but non-zero value like 1.0e-100 instead of + 0.0. Due to using floating-point math, the computed force, energy, + and virial contributions from the pairs will be too small to cause + differences. The first of the 3 coefficients (LJ or Coulombic) is the weighting factor on 1-2 atom pairs, which are pairs of atoms directly bonded to diff --git a/doc/src/variable.rst b/doc/src/variable.rst index 31338279ea..afa491e96e 100644 --- a/doc/src/variable.rst +++ b/doc/src/variable.rst @@ -11,12 +11,19 @@ Syntax variable name style args ... * name = name of variable to define -* style = *delete* or *index* or *loop* or *world* or *universe* or *uloop* or *string* or *format* or *getenv* or *file* or *atomfile* or *python* or *timer* or *internal* or *equal* or *vector* or *atom* +* style = *delete* or *atomfile* or *file* or *format* or *getenv* or *index* or *internal* or *loop* or *python* or *string* or *timer* or *uloop* or *universe* or *world* or *equal* or *vector* or *atom* .. parsed-literal:: *delete* = no args + *atomfile* arg = filename + *file* arg = filename + *format* args = vname fstr + vname = name of equal-style variable to evaluate + fstr = C-style format string + *getenv* arg = one string *index* args = one or more strings + *internal* arg = numeric value *loop* args = N N = integer size of loop, loop from 1 to N inclusive *loop* args = N pad @@ -27,24 +34,18 @@ Syntax *loop* args = N1 N2 pad N1,N2 = loop from N1 to N2 inclusive pad = all values will be same length, e.g. 050, 051, ..., 100 - *world* args = one string for each partition of processors - *universe* args = one or more strings + *python* arg = function + *string* arg = one string + *timer* arg = no arguments *uloop* args = N N = integer size of loop *uloop* args = N pad N = integer size of loop pad = all values will be same length, e.g. 001, 002, ..., 100 - *string* arg = one string - *format* args = vname fstr - vname = name of equal-style variable to evaluate - fstr = C-style format string - *getenv* arg = one string - *file* arg = filename - *atomfile* arg = filename - *python* arg = function - *timer* arg = no arguments - *internal* arg = numeric value - *equal* or *vector* or *atom* args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references + *universe* args = one or more strings + *world* args = one string for each partition of processors + + *equal* or *vector* or *atom* args = one formula containing numbers, thermo keywords, math operations, built-in functions, atom values and vectors, compute/fix/variable references numbers = 0.0, 100, -5.4, 2.8e-4, etc constants = PI, version, on, off, true, false, yes, no thermo keywords = vol, ke, press, etc from :doc:`thermo_style ` @@ -67,12 +68,13 @@ Syntax angmom(group,dim,region), torque(group,dim,region), inertia(group,dimdim,region), omega(group,dim,region) special functions = sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x), is_file(name), is_os(name), extract_setting(name), label2type(kind,label) - feature functions = is_active(category,feature), is_available(category,feature), is_defined(category,id) + feature functions = is_available(category,feature), is_active(category,feature), is_defined(category,id) atom value = id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i] - atom vector = id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q + atom vector = id, mass, type, mol, radius, q, x, y, z, vx, vy, vz, fx, fy, fz compute references = c_ID, c_ID[i], c_ID[i][j], C_ID, C_ID[i] fix references = f_ID, f_ID[i], f_ID[i][j], F_ID, F_ID[i] variable references = v_name, v_name[i] + vector initialization = [1,3,7,10] (for *vector* variables only) Examples """""""" @@ -95,6 +97,7 @@ Examples variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 variable x uloop 15 pad variable str format x %.6g + variable myvec vector [1,3,7,10] variable x delete .. code-block:: LAMMPS @@ -252,9 +255,10 @@ commands before the variable would become exhausted. For example, ---------- -This section describes how all the various variable styles are defined -and what they store. Except for the *equal* and *vector* and *atom* -styles, which are explained in the next section. +The next sections describe in how all the various variable styles are +defined and what they store. The styles are listed alphabetically, +except for the *equal* and *vector* and *atom* styles, which are +explained together after all the others. Many of the styles store one or more strings. Note that a single string can contain spaces (multiple words), if it is enclosed in @@ -262,111 +266,7 @@ quotes in the variable command. When the variable is substituted for in another input script command, its returned string will then be interpreted as multiple arguments in the expanded command. -For the *index* style, one or more strings are specified. Initially, -the first string is assigned to the variable. Each time a -:doc:`next ` command is used with the variable name, the next -string is assigned. All processors assign the same string to the -variable. - -Index-style variables with a single string value can also be set by -using the :doc:`command-line switch -var `. - -The *loop* style is identical to the *index* style except that the -strings are the integers from 1 to N inclusive, if only one argument N -is specified. This allows generation of a long list of runs -(e.g. 1000) without having to list N strings in the input script. -Initially, the string "1" is assigned to the variable. Each time a -:doc:`next ` command is used with the variable name, the next -string ("2", "3", etc) is assigned. All processors assign the same -string to the variable. The *loop* style can also be specified with -two arguments N1 and N2. In this case the loop runs from N1 to N2 -inclusive, and the string N1 is initially assigned to the variable. -N1 <= N2 and N2 >= 0 is required. - -For the *world* style, one or more strings are specified. There must -be one string for each processor partition or "world". LAMMPS can be -run with multiple partitions via the :doc:`-partition command-line -switch `. This variable command assigns one string to -each world. All processors in the world are assigned the same string. -The next command cannot be used with equal-style variables, since -there is only one value per world. This style of variable is useful -when you wish to run different simulations on different partitions, or -when performing a parallel tempering simulation (see the :doc:`temper -` command), to assign different temperatures to different -partitions. - -For the *universe* style, one or more strings are specified. There -must be at least as many strings as there are processor partitions or -"worlds". LAMMPS can be run with multiple partitions via the -:doc:`-partition command-line switch `. This variable -command initially assigns one string to each world. When a -:doc:`next ` command is encountered using this variable, the first -processor partition to encounter it, is assigned the next available -string. This continues until all the variable strings are consumed. -Thus, this command can be used to run 50 simulations on 8 processor -partitions. The simulations will be run one after the other on -whatever partition becomes available, until they are all finished. -Universe-style variables are incremented using the files -"tmp.lammps.variable" and "tmp.lammps.variable.lock" which you will -see in your directory during such a LAMMPS run. - -The *uloop* style is identical to the *universe* style except that the -strings are the integers from 1 to N. This allows generation of long -list of runs (e.g. 1000) without having to list N strings in the input -script. - -For the *string* style, a single string is assigned to the variable. -Two differences between this style and using the *index* style exist: -a variable with *string* style can be redefined, e.g. by another command later -in the input script, or if the script is read again in a loop. The other -difference is that *string* performs variable substitution even if the -string parameter is quoted. - -For the *format* style, an equal-style or compatible variable is -specified along with a C-style format string, e.g. "%f" or "%.10g", -which must be appropriate for formatting a double-precision -floating-point value and may not have extra characters. The default -format is "%.15g". This variable style allows an equal-style variable -to be formatted precisely when it is evaluated. - -Note that if you simply wish to print a variable value with desired -precision to the screen or logfile via the :doc:`print ` or -:doc:`fix print ` commands, you can also do this by -specifying an "immediate" variable with a trailing colon and format -string, as part of the string argument of those commands. This is -explained on the :doc:`Commands parse ` doc page. - -For the *getenv* style, a single string is assigned to the variable -which should be the name of an environment variable. When the -variable is evaluated, it returns the value of the environment -variable, or an empty string if it not defined. This style of -variable can be used to adapt the behavior of LAMMPS input scripts via -environment variable settings, or to retrieve information that has -been previously stored with the :doc:`shell putenv ` command. -Note that because environment variable settings are stored by the -operating systems, they persist even if the corresponding *getenv* -style variable is deleted, and also are set for sub-shells executed -by the :doc:`shell ` command. - -For the *file* style, a filename is provided which contains a list of -strings to assign to the variable, one per line. The strings can be -numeric values if desired. See the discussion of the next() function -below for equal-style variables, which will convert the string of a -file-style variable into a numeric value in a formula. - -When a file-style variable is defined, the file is opened and the -string on the first line is read and stored with the variable. This -means the variable can then be evaluated as many times as desired and -will return that string. There are two ways to cause the next string -from the file to be read: use the :doc:`next ` command or the -next() function in an equal- or atom-style variable, as discussed -below. - -The rules for formatting the file are as follows. A comment character -"#" can be used anywhere on a line; text starting with the comment -character is stripped. Blank lines are skipped. The first "word" of -a non-blank line, delimited by white-space, is the "string" assigned -to the variable. +---------- For the *atomfile* style, a filename is provided which contains one or more sets of values, to assign on a per-atom basis to the variable. @@ -406,6 +306,97 @@ will be assigned to that atom. IDs can be listed in any order. atoms is first set to 0.0. Thus values for atoms whose ID does not appear in the set, will remain 0.0. +---------- + +For the *file* style, a filename is provided which contains a list of +strings to assign to the variable, one per line. The strings can be +numeric values if desired. See the discussion of the next() function +below for equal-style variables, which will convert the string of a +file-style variable into a numeric value in a formula. + +When a file-style variable is defined, the file is opened and the +string on the first line is read and stored with the variable. This +means the variable can then be evaluated as many times as desired and +will return that string. There are two ways to cause the next string +from the file to be read: use the :doc:`next ` command or the +next() function in an equal- or atom-style variable, as discussed +below. + +The rules for formatting the file are as follows. A comment character +"#" can be used anywhere on a line; text starting with the comment +character is stripped. Blank lines are skipped. The first "word" of +a non-blank line, delimited by white-space, is the "string" assigned +to the variable. + +---------- + +For the *format* style, an equal-style or compatible variable is +specified along with a C-style format string, e.g. "%f" or "%.10g", +which must be appropriate for formatting a double-precision +floating-point value and may not have extra characters. The default +format is "%.15g". This variable style allows an equal-style variable +to be formatted precisely when it is evaluated. + +Note that if you simply wish to print a variable value with desired +precision to the screen or logfile via the :doc:`print ` or +:doc:`fix print ` commands, you can also do this by +specifying an "immediate" variable with a trailing colon and format +string, as part of the string argument of those commands. This is +explained on the :doc:`Commands parse ` doc page. + +---------- + +For the *getenv* style, a single string is assigned to the variable +which should be the name of an environment variable. When the +variable is evaluated, it returns the value of the environment +variable, or an empty string if it not defined. This style of +variable can be used to adapt the behavior of LAMMPS input scripts via +environment variable settings, or to retrieve information that has +been previously stored with the :doc:`shell putenv ` command. +Note that because environment variable settings are stored by the +operating systems, they persist even if the corresponding *getenv* +style variable is deleted, and also are set for sub-shells executed +by the :doc:`shell ` command. + +---------- + +For the *index* style, one or more strings are specified. Initially, +the first string is assigned to the variable. Each time a +:doc:`next ` command is used with the variable name, the next +string is assigned. All processors assign the same string to the +variable. + +Index-style variables with a single string value can also be set by +using the :doc:`command-line switch -var `. + +---------- + +For the *internal* style a numeric value is provided. This value will +be assigned to the variable until a LAMMPS command sets it to a new +value. There are currently only two LAMMPS commands that require +*internal* variables as inputs, because they reset them: +:doc:`create_atoms ` and :doc:`fix controller +`. As mentioned above, an internal-style variable can +be used in place of an equal-style variable anywhere else in an input +script, e.g. as an argument to another command that allows for +equal-style variables. + +---------- + +The *loop* style is identical to the *index* style except that the +strings are the integers from 1 to N inclusive, if only one argument N +is specified. This allows generation of a long list of runs +(e.g. 1000) without having to list N strings in the input script. +Initially, the string "1" is assigned to the variable. Each time a +:doc:`next ` command is used with the variable name, the next +string ("2", "3", etc) is assigned. All processors assign the same +string to the variable. The *loop* style can also be specified with +two arguments N1 and N2. In this case the loop runs from N1 to N2 +inclusive, and the string N1 is initially assigned to the variable. +N1 <= N2 and N2 >= 0 is required. + +---------- + For the *python* style a Python function name is provided. This needs to match a function name specified in a :doc:`python ` command which returns a value to this variable as defined by its *return* @@ -433,25 +424,52 @@ python-style variable can be used in place of an equal-style variable anywhere in an input script, e.g. as an argument to another command that allows for equal-style variables. -For the *timer* style no additional argument is specified. The value of -the variable is set by querying the current elapsed wall time of the -simulation. This is done at the point in time when the variable is -defined in the input script. If a second timer-style variable is also -defined, then a simple formula can be used to calculate the elapsed time -between the two timers, as in the example at the top of this manual -entry. As mentioned above, timer-style variables can be redefined -elsewhere in the input script, so the same pair of variables can be used -in a loop or to time a series of operations. +---------- -For the *internal* style a numeric value is provided. This value will -be assigned to the variable until a LAMMPS command sets it to a new -value. There are currently only two LAMMPS commands that require -*internal* variables as inputs, because they reset them: -:doc:`create_atoms ` and :doc:`fix controller -`. As mentioned above, an internal-style variable can -be used in place of an equal-style variable anywhere else in an input -script, e.g. as an argument to another command that allows for -equal-style variables. +For the *string* style, a single string is assigned to the variable. +Two differences between this style and using the *index* style exist: +a variable with *string* style can be redefined, e.g. by another command later +in the input script, or if the script is read again in a loop. The other +difference is that *string* performs variable substitution even if the +string parameter is quoted. + +---------- + +The *uloop* style is identical to the *universe* style except that the +strings are the integers from 1 to N. This allows generation of long +list of runs (e.g. 1000) without having to list N strings in the input +script. + +---------- + +For the *universe* style, one or more strings are specified. There +must be at least as many strings as there are processor partitions or +"worlds". LAMMPS can be run with multiple partitions via the +:doc:`-partition command-line switch `. This variable +command initially assigns one string to each world. When a +:doc:`next ` command is encountered using this variable, the first +processor partition to encounter it, is assigned the next available +string. This continues until all the variable strings are consumed. +Thus, this command can be used to run 50 simulations on 8 processor +partitions. The simulations will be run one after the other on +whatever partition becomes available, until they are all finished. +Universe-style variables are incremented using the files +"tmp.lammps.variable" and "tmp.lammps.variable.lock" which you will +see in your directory during such a LAMMPS run. + +---------- + +For the *world* style, one or more strings are specified. There must +be one string for each processor partition or "world". LAMMPS can be +run with multiple partitions via the :doc:`-partition command-line +switch `. This variable command assigns one string to +each world. All processors in the world are assigned the same string. +The next command cannot be used with equal-style variables, since +there is only one value per world. This style of variable is useful +when you wish to run different simulations on different partitions, or +when performing a parallel tempering simulation (see the :doc:`temper +` command), to assign different temperatures to different +partitions. ---------- @@ -495,36 +513,39 @@ is a valid (though strange) variable formula: Specifically, a formula can contain numbers, constants, thermo keywords, math operators, math functions, group functions, region -functions, atom values, atom vectors, compute references, fix -references, and references to other variables. +functions, special functions, feature functions, atom values, atom +vectors, compute references, fix references, and references to other +variables. -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Number | 0.2, 100, 1.0e20, -15.4, etc | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Constant | PI, version, on, off, true, false, yes, no | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Thermo keywords | vol, pe, ebond, etc | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Math operators | (), -x, x+y, x-y, x\*y, x/y, x\^y, x%y, x == y, x != y, x < y, x <= y, x > y, x >= y, x && y, x \|\| y, x \|\^ y, !x | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Math functions | sqrt(x), exp(x), ln(x), log(x), abs(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x), random(x,y,z), normal(x,y,z), ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y), logfreq(x,y,z), logfreq2(x,y,z), logfreq3(x,y,z), stride(x,y,z), stride2(x,y,z,a,b,c), vdisplace(x,y), swiggle(x,y,z), cwiggle(x,y,z) | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Group functions | count(ID), mass(ID), charge(ID), xcm(ID,dim), vcm(ID,dim), fcm(ID,dim), bound(ID,dir), gyration(ID), ke(ID), angmom(ID,dim), torque(ID,dim), inertia(ID,dimdim), omega(ID,dim) | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Region functions | count(ID,IDR), mass(ID,IDR), charge(ID,IDR), xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR), bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR), angmom(ID,dim,IDR), torque(ID,dim,IDR), inertia(ID,dimdim,IDR), omega(ID,dim,IDR) | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Special functions | sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x), label2type(kind,label) | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Atom values | id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i] | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Atom vectors | id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Compute references | c_ID, c_ID[i], c_ID[i][j], C_ID, C_ID[i] | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Fix references | f_ID, f_ID[i], f_ID[i][j], F_ID, F_ID[i] | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Other variables | v_name, v_name[i] | -+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Number | 0.2, 100, 1.0e20, -15.4, etc | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Constant | PI, version, on, off, true, false, yes, no | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Thermo keywords | vol, pe, ebond, etc | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Math operators | (), -x, x+y, x-y, x\*y, x/y, x\^y, x%y, x == y, x != y, x < y, x <= y, x > y, x >= y, x && y, x \|\| y, x \|\^ y, !x | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Math functions | sqrt(x), exp(x), ln(x), log(x), abs(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x), random(x,y,z), normal(x,y,z), ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y), logfreq(x,y,z), logfreq2(x,y,z), logfreq3(x,y,z), stride(x,y,z), stride2(x,y,z,a,b,c), vdisplace(x,y), swiggle(x,y,z), cwiggle(x,y,z) | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Group functions | count(ID), mass(ID), charge(ID), xcm(ID,dim), vcm(ID,dim), fcm(ID,dim), bound(ID,dir), gyration(ID), ke(ID), angmom(ID,dim), torque(ID,dim), inertia(ID,dimdim), omega(ID,dim) | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Region functions | count(ID,IDR), mass(ID,IDR), charge(ID,IDR), xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR), bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR), angmom(ID,dim,IDR), torque(ID,dim,IDR), inertia(ID,dimdim,IDR), omega(ID,dim,IDR) | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Special functions | sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x), is_file(name), is_os(name), extract_setting(name), label2type(kind,label) | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Feature functions | is_available(category,feature), is_active(category,feature), is_defined(category,id) | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Atom values | id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i] | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Atom vectors | id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Compute references | c_ID, c_ID[i], c_ID[i][j], C_ID, C_ID[i] | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Fix references | f_ID, f_ID[i], f_ID[i][j], F_ID, F_ID[i] | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Other variables | v_name, v_name[i] | ++--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Most of the formula elements produce a scalar value. Some produce a global or per-atom vector of values. Global vectors can be produced @@ -574,9 +595,9 @@ will not work, since the *version* has been introduced more recently): if $(version<20140513) then "communicate vel yes" else "comm_modify vel yes" The thermo keywords allowed in a formula are those defined by the -:doc:`thermo_style custom ` command. Thermo keywords that -require a :doc:`compute ` to calculate their values such as -"temp" or "press", use computes stored and invoked by the +:doc:`thermo_style custom ` command. Thermo keywords +that require a :doc:`compute ` to calculate their values such +as "temp" or "press", use computes stored and invoked by the :doc:`thermo_style ` command. This means that you can only use those keywords in a variable if the style you are using with the thermo_style command (and the thermo keywords associated with that @@ -714,10 +735,12 @@ new timestep. X,y,z > 0 and y < z are required. The generated timesteps are on a base-z logarithmic scale, starting with x, and the y value is how many of the z-1 possible timesteps within one logarithmic interval are generated. I.e. the timesteps follow the -sequence x,2x,3x,...y\*x,x\*z,2x\*z,3x\*z,...y\*x\*z,x\*z\^2,2x\*z\^2,etc. For +sequence +x,2x,3x,...y\*x,x\*z,2x\*z,3x\*z,...y\*x\*z,x\*z\^2,2x\*z\^2,etc. For any current timestep, the next timestep in the sequence is returned. -Thus if logfreq(100,4,10) is used in a variable by the :doc:`dump_modify every ` command, it will generate this sequence of -output timesteps: +Thus if logfreq(100,4,10) is used in a variable by the +:doc:`dump_modify every ` command, it will generate this +sequence of output timesteps: .. parsed-literal:: @@ -726,9 +749,10 @@ output timesteps: The logfreq2(x,y,z) function is similar to logfreq, except a single logarithmic interval is divided into y equally-spaced timesteps and all of them are output. Y < z is not required. Thus, if -logfreq2(100,18,10) is used in a variable by the :doc:`dump_modify every ` command, then the interval between 100 and -1000 is divided as 900/18 = 50 steps, and it will generate the -sequence of output timesteps: +logfreq2(100,18,10) is used in a variable by the :doc:`dump_modify +every ` command, then the interval between 100 and 1000 +is divided as 900/18 = 50 steps, and it will generate the sequence of +output timesteps: .. parsed-literal:: @@ -970,53 +994,87 @@ types, bond types and so on. For the full list of available keywords *name* and their meaning, see the documentation for extract_setting() via the link in this paragraph. -The label2type() function converts type labels into numeric types, using label -maps created by the :doc:`labelmap ` or :doc:`read_data ` -commands. The first argument is the label map kind (atom, bond, angle, -dihedral, or improper) and the second argument is the label. The function -returns the corresponding numeric type. +The label2type(kind,label) function converts type labels into numeric +types, using label maps created by the :doc:`labelmap ` or +:doc:`read_data ` commands. The first argument is the +label map kind (atom, bond, angle, dihedral, or improper) and the +second argument is the label. The function returns the corresponding +numeric type. ---------- Feature Functions ----------------- -Feature functions allow to probe the running LAMMPS executable for -whether specific features are either active, defined, or available. The -functions take two arguments, a *category* and a corresponding -*argument*\ . The arguments are strings and thus cannot be formulas +Feature functions allow probing of the running LAMMPS executable for +whether specific features are available, active, or defined. All 3 of +the functions take two arguments, a *category* and a category-specific +second argument. Both are strings and thus cannot be formulas themselves; only $-style immediate variable expansion is possible. -Return value is either 1.0 or 0.0 depending on whether the function -evaluates to true or false, respectively. +The return value of the functions is either 1.0 or 0.0 depending on +whether the function evaluates to true or false, respectively. -The *is_active(category,feature)* function allows to query for active -settings which are grouped by categories. Currently supported categories -and arguments are: +The *is_available(category,name)* function queries whether a specific +feature is available in the LAMMPS executable that is being run, i.e +whether it was included or enabled at compile time. -* *package*\ : argument = *gpu* or *intel* or *kokkos* or *omp* -* *newton*\ : argument = *pair* or *bond* or *any* -* *pair*\ : argument = *single* or *respa* or *manybody* or *tail* or *shift* -* *comm_style*\ : argument = *brick* or *tiled* -* *min_style*\ : argument = any of the compiled in minimizer styles -* *run_style*\ : argument = any of the compiled in run styles -* *atom_style*\ : argument = any of the compiled in atom style) -* *pair_style*\ : argument = any of the compiled in pair styles -* *bond_style*\ : argument = any of the compiled in bond styles -* *angle_style*\ : argument = any of the compiled in angle styles -* *dihedral_style*\ : argument = any of the compiled in dihedral styles -* *improper_style*\ : argument = any of the compiled in improper styles -* *kspace_style*\ : argument = any of the compiled in kspace styles +This supports the following categories: *command*, *compute*, *fix*, +*pair_style* and *feature*\ . For all the categories except *feature* +the *name* is a style name, e.g. *nve* for the *fix* category. Note +that many LAMMPS input script commands such as *create_atoms* are +actually instances of a command style which LAMMPS defines, as opposed +to built-in commands. For all of these styles except *command*, +appending of active suffixes is also tried before reporting failure. -Most of the settings are self-explanatory, the *single* argument in the -*pair* category allows to check whether a pair style supports a -Pair::single() function as needed by compute group/group and others -features or LAMMPS, *respa* allows to check whether the inner/middle/outer -mode of r-RESPA is supported. In the various style categories, -the checking is also done using suffix flags, if available and enabled. +The *feature* category checks the availability of the following +compile-time enabled features: GZIP support, PNG support, JPEG +support, FFMPEG support, and C++ exceptions for error +handling. Corresponding names are *gzip*, *png*, *jpeg*, *ffmpeg* and +*exceptions*\ . -Example 1: disable use of suffix for pppm when using GPU package -(i.e. run it on the CPU concurrently to running the pair style on the -GPU), but do use the suffix otherwise (e.g. with OPENMP). +Example: Only dump in a given format if the compiled binary supports it. + +.. code-block:: LAMMPS + + if "$(is_available(feature,png))" then "print 'PNG supported'" else "print 'PNG not supported'" + if "$(is_available(feature,ffmpeg)" then "dump 3 all movie 25 movie.mp4 type type zoom 1.6 adiam 1.0" + +The *is_active(category,feature)* function queries whether a specific +feature is currently active within LAMMPS. The features are grouped +by categories. Supported categories and features are: + +* *package*\ : features = *gpu* or *intel* or *kokkos* or *omp* +* *newton*\ : features = *pair* or *bond* or *any* +* *pair*\ : features = *single* or *respa* or *manybody* or *tail* or *shift* +* *comm_style*\ : features = *brick* or *tiled* +* *min_style*\ : features = a minimizer style name +* *run_style*\ : features = a run style name +* *atom_style*\ : features = an atom style name +* *pair_style*\ : features = a pair style name +* *bond_style*\ : features = a bond style name +* *angle_style*\ : features = an angle style name +* *dihedral_style*\ : features = a dihedral style name +* *improper_style*\ : features = an improper style name +* *kspace_style*\ : features = a kspace style name + +Most of the settings are self-explanatory. For the *package* +category, a package may have been included in the LAMMPS build, but +not have enabled by any input script command, and hence be inactive. +The *single* feature in the *pair* category checks whether the +currently defined pair style supports a Pair::single() function as +needed by compute group/group and others features or LAMMPS. +Similarly, the *respa* feature checks whether the inner/middle/outer +mode of r-RESPA is supported by the current pair style. + +For the categories with *style* in their name, only a single instance +of the style is ever active at any time in a LAMMPS simulation. Thus +the check is whether the currently active style matches the specified +name. This check is also done using suffix flags, if available and +enabled. + +Example 1: Disable use of suffix for PPPM when using GPU package +(i.e. run it on the CPU concurrently while running the pair style on +the GPU), but do use the suffix otherwise (e.g. with OPENMP). .. code-block:: LAMMPS @@ -1024,39 +1082,23 @@ GPU), but do use the suffix otherwise (e.g. with OPENMP). if $(is_active(package,gpu)) then "suffix off" kspace_style pppm -Example 2: use r-RESPA with inner/outer cutoff, if supported by pair -style, otherwise fall back to using pair and reducing the outer time -step +Example 2: Use r-RESPA with inner/outer cutoff, if supported by the +current pair style, otherwise fall back to using r-RESPA with simply +the pair keyword and reducing the outer time step. .. code-block:: LAMMPS timestep $(2.0*(1.0+2.0*is_active(pair,respa))) - if $(is_active(pair,respa)) then "run_style respa 4 3 2 2 improper 1 inner 2 5.5 7.0 outer 3 kspace 4" else "run_style respa 3 3 2 improper 1 pair 2 kspace 3" + if $(is_active(pair,respa)) then "run_style respa 4 3 2 2 improper 1 inner 2 5.5 7.0 outer 3 kspace 4" else "run_style respa 3 3 2 improper 1 pair 2 kspace 3" -The *is_available(category,name)* function allows to query whether -a specific optional feature is available, i.e. compiled in. -This currently works for the following categories: *command*, -*compute*, *fix*, *pair_style* and *feature*\ . For all categories -except *command* and *feature* also appending active suffixes is -tried before reporting failure. - -The *feature* category is used to check the availability of compiled in -features such as GZIP support, PNG support, JPEG support, FFMPEG support, -and C++ exceptions for error handling. Corresponding values for name are -*gzip*, *png*, *jpeg*, *ffmpeg* and *exceptions*\ . - -This enables writing input scripts which only dump using a given format if -the compiled binary supports it. - -.. code-block:: LAMMPS - - if "$(is_available(feature,png))" then "print 'PNG supported'" else "print 'PNG not supported'" - - if "$(is_available(feature,ffmpeg)" then "dump 3 all movie 25 movie.mp4 type type zoom 1.6 adiam 1.0" - -The *is_defined(categoy,id)* function allows to query categories like -*compute*, *dump*, *fix*, *group*, *region*, and *variable* whether an -entry with the provided name or id is defined. +The *is_defined(category,id)* function checks whether an instance of a +style or variable with a specific ID or name is currently defined +within LAMMPS. The supported categories are *compute*, *dump*, +*fix*, *group*, *region*, and *variable*. Each of these styles (as +well as the variable command) can be specified multiple times within +LAMMPS, each with a unique *id*. This function checks whether the +specified *id* exists. For category *variable", the *id* is the +variable name. ---------- @@ -1268,6 +1310,35 @@ Vectors" discussion above. ---------- +Vector Initialization +--------------------- + +.. versionadded:: TBD + +*Vector*-style variables only can be initialized with a special +syntax, instead of using a formula. The syntax is a bracketed, +comma-separated syntax like the following: + +.. code-block:: LAMMPS + + variable myvec vector [1,3.5,7,10.2] + +The 3rd argument formula is replaced by the vector values in brackets, +separated by commas. This example creates a 4-length vector with +specific numeric values, each of which can be specified as an integer +or floating point value. Note that while whitespace can be added +before or after individual values, no other mathematical operations +can be specified. E.g. "3*10" or "3*v_abc" are not valid vector +elements, nor is "10*[1,2,3,4]" valid for the entire vector. + +Unlike vector variables specified with formulas, this vector variable +is static; its length and values never changes. Its values can be +used in other commands (including vector-style variables specified +with formulas) via the usual syntax for accessing individual vector +elements or the entire vector. + +---------- + Immediate Evaluation of Variables """"""""""""""""""""""""""""""""" @@ -1285,18 +1356,19 @@ with a leading $ sign (e.g. $x or ${abc}) versus with a leading "v\_" (e.g. v_x or v_abc). The former can be used in any input script command, including a variable command. The input script parser evaluates the reference variable immediately and substitutes its value -into the command. As explained on the :doc:`Commands parse ` doc page, you can also use un-named -"immediate" variables for this purpose. For example, a string like -this $((xlo+xhi)/2+sqrt(v_area)) in an input script command evaluates -the string between the parenthesis as an equal-style variable formula. +into the command. As explained on the :doc:`Commands parse +` doc page, you can also use un-named "immediate" +variables for this purpose. For example, a string like this +$((xlo+xhi)/2+sqrt(v_area)) in an input script command evaluates the +string between the parenthesis as an equal-style variable formula. Referencing a variable with a leading "v\_" is an optional or required -kind of argument for some commands (e.g. the :doc:`fix ave/chunk ` or :doc:`dump custom ` or -:doc:`thermo_style ` commands) if you wish it to evaluate -a variable periodically during a run. It can also be used in a -variable formula if you wish to reference a second variable. The -second variable will be evaluated whenever the first variable is -evaluated. +kind of argument for some commands (e.g. the :doc:`fix ave/chunk +` or :doc:`dump custom ` or :doc:`thermo_style +` commands) if you wish it to evaluate a variable +periodically during a run. It can also be used in a variable formula +if you wish to reference a second variable. The second variable will +be evaluated whenever the first variable is evaluated. As an example, suppose you use this command in your input script to define the variable "v" as @@ -1309,8 +1381,9 @@ before a run where the simulation box size changes. You might think this will assign the initial volume to the variable "v". That is not the case. Rather it assigns a formula which evaluates the volume (using the thermo_style keyword "vol") to the variable "v". If you -use the variable "v" in some other command like :doc:`fix ave/time ` then the current volume of the box will be -evaluated continuously during the run. +use the variable "v" in some other command like :doc:`fix ave/time +` then the current volume of the box will be evaluated +continuously during the run. If you want to store the initial volume of the system, you can do it this way: @@ -1347,132 +1420,75 @@ will occur when the formula for "vratio" is evaluated later. Variable Accuracy """"""""""""""""" -Obviously, LAMMPS attempts to evaluate variables containing formulas -(\ *equal* and *atom* style variables) accurately whenever the -evaluation is performed. Depending on what is included in the -formula, this may require invoking a :doc:`compute `, either -directly or indirectly via a thermo keyword, or accessing a value -previously calculated by a compute, or accessing a value calculated -and stored by a :doc:`fix `. If the compute is one that calculates -the pressure or energy of the system, then these quantities need to be -tallied during the evaluation of the interatomic potentials (pair, -bond, etc) on timesteps that the variable will need the values. +Obviously, LAMMPS attempts to evaluate variables which contain +formulas (\ *equal* and *vector* and *atom* style variables) +accurately whenever the evaluation is performed. Depending on what is +included in the formula, this may require invoking a :doc:`compute +`, either directly or indirectly via a thermo keyword, or +accessing a value previously calculated by a compute, or accessing a +value calculated and stored by a :doc:`fix `. If the compute is +one that calculates the energy or pressure of the system, then the +corresponding energy or virial quantities need to be tallied during +the evaluation of the interatomic potentials (pair, bond, etc) on any +timestep that the variable needs the tallies. An input script can +also request variables be evaluated before or after or in between +runs, e.g. by including them in a :doc:`print ` command. -LAMMPS keeps track of all of this during a :doc:`run ` or :doc:`energy minimization `. An error will be generated if you -attempt to evaluate a variable on timesteps when it cannot produce -accurate values. For example, if a :doc:`thermo_style custom ` command prints a variable which accesses -values stored by a :doc:`fix ave/time ` command and the -timesteps on which thermo output is generated are not multiples of the -averaging frequency used in the fix command, then an error will occur. +LAMMPS keeps track of all of this as it performs a doc:`run ` or +:doc:`minimize ` simulation, as well as in between +simulations. An error will be generated if you attempt to evaluate a +variable when LAMMPS knows it cannot produce accurate values. For +example, if a :doc:`thermo_style custom ` command prints +a variable which accesses values stored by a :doc:`fix ave/time +` command and the timesteps on which thermo output is +generated are not multiples of the averaging frequency used in the fix +command, then an error will occur. -An input script can also request variables be evaluated before or -after or in between runs, e.g. by including them in a -:doc:`print ` command. In this case, if a compute is needed to -evaluate a variable (either directly or indirectly), LAMMPS will not -invoke the compute, but it will use a value previously calculated by -the compute, and can do this only if it was invoked on the current -timestep. Fixes will always provide a quantity needed by a variable, -but the quantity may or may not be current. This leads to one of -three kinds of behavior: +However, there are two special cases to be aware when a variable +requires invocation of a compute (directly or indirectly). The first +is if the variable is evaluated before the first doc:`run ` or +:doc:`minimize ` command in the input script. In this case, +LAMMPS will generate an error. This is because many computes require +initializations which have not yet taken place. One example is the +calculation of degrees of freedom for temperature computes. Another +example are the computes mentioned above which require tallying of +energy or virial quantities; these values are not tallied until the +first simulation begins. -(1) The variable may be evaluated accurately. If it contains -references to a compute or fix, and these values were calculated on -the last timestep of a preceding run, then they will be accessed and -used by the variable and the result will be accurate. +The second special case is when a variable that depends on a compute +is evaluated in between doc:`run ` or :doc:`minimize ` +commands. It is possible for other input script commands issued +following the previous run, but before the variable is evaluated, to +change the system. For example, the doc:`delete_atoms ` +command could be used to remove atoms. Since the compute will not +re-initialize itself until the next simulation or it may depend on +energy/virial computations performed before the system was changed, it +will potentially generate an incorrect answer when evaluated. Note +that LAMMPS will not generate an error in this case; the evaluated +variable may simply be incorrect. -(2) LAMMPS may not be able to evaluate the variable and will generate -an error message stating so. For example, if the variable requires a -quantity from a :doc:`compute ` that has not been invoked on -the current timestep, LAMMPS will generate an error. This means, for -example, that such a variable cannot be evaluated before the first run -has occurred. Likewise, in between runs, a variable containing a -compute cannot be evaluated unless the compute was invoked on the last -timestep of the preceding run, e.g. by thermodynamic output. - -One way to get around this problem is to perform a 0-timestep run -before using the variable. For example, these commands +The way to get around both of these special cases is to perform a +0-timestep run before evaluating the variable. For example, these +commands .. code-block:: LAMMPS - variable t equal temp - print "Initial temperature = $t" + # delete_atoms random fraction 0.5 yes all NULL 49839 + # run 0 + variable t equal temp # this thermo keyword invokes a temperature compute + print "Temperature of system = $t" run 1000 -will generate an error if the run is the first run specified in the -input script, because generating a value for the "t" variable requires -a compute for calculating the temperature to be invoked. +will generate an error if the "run 1000" command is the first +simulation in the input script. If there were a previous run, these +commands will print the correct temperature of the system. But if the +:doc:`delete_atoms ` command is uncommented, the printed +temperature will be incorrect, because information stored by +temperature compute is no longer valid. -However, this sequence of commands would be fine: - -.. code-block:: LAMMPS - - run 0 - variable t equal temp - print "Initial temperature = $t" - run 1000 - -The 0-timestep run initializes and invokes various computes, including -the one for temperature, so that the value it stores is current and -can be accessed by the variable "t" after the run has completed. Note -that a 0-timestep run does not alter the state of the system, so it -does not change the input state for the 1000-timestep run that -follows. Also note that the 0-timestep run must actually use and -invoke the compute in question (e.g. via :doc:`thermo ` or -:doc:`dump ` output) in order for it to enable the compute to be -used in a variable after the run. Thus if you are trying to print a -variable that uses a compute you have defined, you can ensure it is -invoked on the last timestep of the preceding run by including it in -thermodynamic output. - -Unlike computes, :doc:`fixes ` will never generate an error if -their values are accessed by a variable in between runs. They always -return some value to the variable. However, the value may not be what -you expect if the fix has not yet calculated the quantity of interest -or it is not current. For example, the :doc:`fix indent ` -command stores the force on the indenter. But this is not computed -until a run is performed. Thus if a variable attempts to print this -value before the first run, zeroes will be output. Again, performing -a 0-timestep run before printing the variable has the desired effect. - -(3) The variable may be evaluated incorrectly and LAMMPS may have no -way to detect this has occurred. Consider the following sequence of -commands: - -.. code-block:: LAMMPS - - pair_coeff 1 1 1.0 1.0 - run 1000 - pair_coeff 1 1 1.5 1.0 - variable e equal pe - print "Final potential energy = $e" - -The first run is performed using one setting for the pairwise -potential defined by the :doc:`pair_style ` and -:doc:`pair_coeff ` commands. The potential energy is -evaluated on the final timestep and stored by the :doc:`compute pe -` compute (this is done by the :doc:`thermo_style -` command). Then a pair coefficient is changed, -altering the potential energy of the system. When the potential -energy is printed via the "e" variable, LAMMPS will use the potential -energy value stored by the :doc:`compute pe ` compute, -thinking it is current. There are many other commands which could -alter the state of the system between runs, causing a variable to -evaluate incorrectly. - -The solution to this issue is the same as for case (2) above, namely -perform a 0-timestep run before the variable is evaluated to ensure -the system is up-to-date. For example, this sequence of commands -would print a potential energy that reflected the changed pairwise -coefficient: - -.. code-block:: LAMMPS - - pair_coeff 1 1 1.0 1.0 - run 1000 - pair_coeff 1 1 1.5 1.0 - run 0 - variable e equal pe - print "Final potential energy = $e" +Both these issues are resolved, if the "run 0" command is uncommented. +This is because the "run 0" simulation will initialize (or +re-initialize) the temperature compute correctly. ---------- @@ -1482,11 +1498,12 @@ Restrictions Indexing any formula element by global atom ID, such as an atom value, requires the :doc:`atom style ` to use a global mapping in order to look up the vector indices. By default, only atom styles -with molecular information create global maps. The :doc:`atom_modify map ` command can override the default, e.g. for +with molecular information create global maps. The :doc:`atom_modify +map ` command can override the default, e.g. for atomic-style atom styles. -All *universe*\ - and *uloop*\ -style variables defined in an input script -must have the same number of values. +All *universe*\ - and *uloop*\ -style variables defined in an input +script must have the same number of values. Related commands """""""""""""""" diff --git a/doc/utils/check-styles.py b/doc/utils/check-styles.py index 3015ece7a9..d9f7381473 100644 --- a/doc/utils/check-styles.py +++ b/doc/utils/check-styles.py @@ -227,6 +227,8 @@ for header in headers: register_style(reader,style,info) elif m[0] == 'Region': register_style(region,style,info) + elif m[0] == 'GranSubMod': + pass # ignore GranSubMod styles for now else: print("Skipping over: ",m) diff --git a/doc/utils/requirements.txt b/doc/utils/requirements.txt index a7a03e6e41..3f7bc065d0 100644 --- a/doc/utils/requirements.txt +++ b/doc/utils/requirements.txt @@ -1,8 +1,8 @@ -Sphinx < 7.0.0 +Sphinx >= 5.3.0, <7.1.0 sphinxcontrib-spelling -sphinxcontrib-jquery >=3.0.0 +sphinxcontrib-jquery git+https://github.com/akohlmey/sphinx-fortran@parallel-read -sphinx_tabs +git+https://github.com/executablebooks/sphinx-tabs@v3.4.1 breathe Pygments six diff --git a/doc/utils/sphinx-config/_themes/lammps_theme/__init__.py b/doc/utils/sphinx-config/_themes/lammps_theme/__init__.py index 16935585b0..458d105363 100644 --- a/doc/utils/sphinx-config/_themes/lammps_theme/__init__.py +++ b/doc/utils/sphinx-config/_themes/lammps_theme/__init__.py @@ -12,7 +12,7 @@ from sphinx.locale import _ from sphinx.util.logging import getLogger -__version__ = '1.1.1' +__version__ = '1.2.0' __version_full__ = __version__ logger = getLogger(__name__) @@ -40,15 +40,24 @@ def extend_html_context(app, pagename, templatename, context, doctree): # See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package def setup(app): if python_version[0] < 3: - logger.warning("Python 2 is deprecated with sphinx_rtd_theme, update to Python 3") + logger.warning("Python 2 is deprecated with lammps_theme, update to Python 3") app.require_sphinx('1.6') if sphinx_version <= (2, 0, 0): - logger.warning("Sphinx 1.x is deprecated with sphinx_rtd_theme, update to Sphinx 2.x or greater") + logger.warning("Sphinx 1.x is deprecated with lammps_theme, update to Sphinx 2.x or greater") if not app.config.html_experimental_html5_writer: - logger.warning("'html4_writer' is deprecated with sphinx_rtd_theme") + logger.warning("'html4_writer' is deprecated with lammps_theme") else: if app.config.html4_writer: - logger.warning("'html4_writer' is deprecated with sphinx_rtd_theme") + logger.warning("'html4_writer' is deprecated with lammps_theme") + + # Since Sphinx 6, jquery isn't bundled anymore and we need to ensure that + # the sphinxcontrib-jquery extension is enabled. + # See: https://dev.readthedocs.io/en/latest/design/sphinx-jquery.html + if sphinx_version >= (6, 0, 0): + # Documentation of Sphinx guarantees that an extension is added and + # enabled at most once. + # See: https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.setup_extension + app.setup_extension("sphinxcontrib.jquery") # Register the theme that can be referenced without adding a theme path app.add_html_theme('lammps_theme', path.abspath(path.dirname(__file__))) diff --git a/doc/utils/sphinx-config/_themes/lammps_theme/breadcrumbs.html b/doc/utils/sphinx-config/_themes/lammps_theme/breadcrumbs.html index f672cf097a..96ee0286bd 100644 --- a/doc/utils/sphinx-config/_themes/lammps_theme/breadcrumbs.html +++ b/doc/utils/sphinx-config/_themes/lammps_theme/breadcrumbs.html @@ -22,7 +22,7 @@
    {%- block breadcrumbs %} -
  • +
  • {%- for doc in parents %} {%- endfor %} diff --git a/doc/utils/sphinx-config/_themes/lammps_theme/footer.html b/doc/utils/sphinx-config/_themes/lammps_theme/footer.html index 77e826a505..7b831c1f99 100644 --- a/doc/utils/sphinx-config/_themes/lammps_theme/footer.html +++ b/doc/utils/sphinx-config/_themes/lammps_theme/footer.html @@ -60,4 +60,3 @@ {%- block extrafooter %} {% endblock %} - diff --git a/doc/utils/sphinx-config/_themes/lammps_theme/layout.html b/doc/utils/sphinx-config/_themes/lammps_theme/layout.html index 260279a2e5..83fdb7054b 100644 --- a/doc/utils/sphinx-config/_themes/lammps_theme/layout.html +++ b/doc/utils/sphinx-config/_themes/lammps_theme/layout.html @@ -40,14 +40,14 @@ {%- endfor -%} - {#- FAVICON #} - {%- if favicon %} - {%- if sphinx_version_info < (4, 0) -%} - - {%- else %} - - {%- endif %} - {%- endif -%} + {#- FAVICON + favicon_url is the only context var necessary since Sphinx 4. + In Sphinx<4, we use favicon but need to prepend path info. + #} + {%- set _favicon_url = favicon_url | default(pathto('_static/' + (favicon or ""), 1)) %} + {%- if favicon_url or favicon %} + + {%- endif %} {#- CANONICAL URL (deprecated) #} {%- if theme_canonical_url and not pageurl %} @@ -133,27 +133,20 @@