diff --git a/.github/release_steps.md b/.github/release_steps.md index 15ddd59768..71388e115a 100644 --- a/.github/release_steps.md +++ b/.github/release_steps.md @@ -1,42 +1,54 @@ # LAMMPS Release Steps -The following notes chronicle the current steps for preparing and publishing LAMMPS releases. For -definitions of LAMMPS versions and releases mean, please refer to [the corresponding section in the -LAMMPS manual](https://docs.lammps.org/Manual_version.html). +The following notes chronicle the current steps for preparing and +publishing LAMMPS releases. For definitions of LAMMPS versions and +releases, please refer to [the corresponding section in the LAMMPS +manual](https://docs.lammps.org/Manual_version.html). ## LAMMPS Feature Release -A LAMMPS feature release is currently prepared after about 500 to 750 commits to the 'develop' -branch or after a period of four weeks up to two months. This is not a fixed rule, though, since -external circumstances can cause delays in preparing a release, or pull requests that are desired to -be merged for the release are not yet completed. +A LAMMPS feature release is currently prepared after about 500 to 750 +commits to the 'develop' branch or after a period of four weeks up to +two months. This is not a fixed rule, though, since external +circumstances can cause delays in preparing a release, or pull requests +that are desired to be merged for the release are not yet completed. ### Preparing a 'next\_release' branch Create a 'next\_release' branch off 'develop' and make the following changes: -- set the LAMMPS\_VERSION define to the planned release date in src/version.h in the format - "D Mmm YYYY" or "DD Mmm YYYY" +- set the LAMMPS\_VERSION define to the planned release date in + src/version.h in the format "D Mmm YYYY" or "DD Mmm YYYY" - remove the LAMMPS\_UPDATE define in src/version.h - update the release date in doc/lammps.1 -- update all TBD arguments for ..versionadded::, ..versionchanged:: ..deprecated:: to the - planned release date in the format "DMmmYYYY" or "DDMmmYYYY" -- check release notes for merged new features and check if ..versionadded:: or ..versionchanged:: - are missing and need to be added -Submit this pull request, rebase if needed. This is the last pull request merged for the release -and should not contain any other changes. (Exceptions: this document, last minute trivial(!) changes). +- update all TBD arguments for ..versionadded::, ..versionchanged:: + ..deprecated:: to the planned release date in the format "DMmmYYYY" or + "DDMmmYYYY" +- check release notes for merged new features and check if + ..versionadded:: or ..versionchanged:: are missing and need to be + added -This PR shall not be merged before **all** pending tests have completed and cleared. If needed, a -bugfix pull request should be created and merged to clear all tests. +Submit this pull request, rebase if needed. This is the last pull +request merged for the release and should not contain any other +changes. (Exceptions: this document, last minute trivial(!) changes). + +This PR shall not be merged before **all** pending tests have completed +and cleared. We currently use a mix of automated tests running on +either Temple's Jenkins cluster or GitHub workflows. Those include time +consuming tests not run on pull requests. If needed, a bugfix pull +request should be created and merged to clear all tests. ### Create release on GitHub -When all pending pull requests for the release are merged and have cleared testing, the -'next\_release' branch is merged into 'develop'. +When all pending pull requests for the release are merged and have +cleared testing, the 'next\_release' branch is merged into 'develop'. -Check out 'develop' locally, pull the latest changes, merge them into 'release', apply a suitable -release tag (for historical reasons the tag starts with "patch_" followed by the date, and finally -push everything back to GitHub. Example: +Check out or update the 'develop' branch locally, pull the latest +changes, merge them into 'release' with a fast forward(!) merge, and +apply a suitable release tag (for historical reasons the tag starts with +"patch_" followed by the date, and finally push everything back to +GitHub. There should be no commits made to 'release' but only +fast forward merges. Example: ``` git checkout develop @@ -48,58 +60,137 @@ git tag -s -m "LAMMPS feature release 19 November 2024" patch_19Nov2024 git push git@github.com:lammps/lammps.git --tags develop release ``` -Go to https://github.com/lammps/lammps/releases and create a new (draft) release page or check the -existing draft for any necessary changes from pull requests that were merged but are not listed. -Then select the applied tag for the release in the "Choose a tag" dropdown list. Go to the bottom of -the list and select the "Set as pre-release" checkbox. The "Set as the latest release" button is +Applying this tag will trigger two actions on the Temple Jenkins cluster: +- The online manual at https://docs.lammps.org/ will be updated to the + state of the 'release' branch. Merges to the 'develop' branch will + trigger updating https://docs.lammps.org/latest/ so by reviewing the + version of the manual under the "latest" URL, it is possible to preview + what the updated release documentation will look like. +- A downloadable tar archive of the LAMMPS distribution that includes the + html format documentation and a PDF of the manual will be created and + uploaded to the download server at https://download.lammps.org/tars + Note that the file is added, but the `index.html` file is not updated, + so it is not yet publicly visible. + +Go to https://github.com/lammps/lammps/releases and create a new (draft) +release page with a summary of all the changes included and references +to the pull requests they were merged from or check the existing draft +for any necessary changes from pull requests that were merged but are +not listed. Then select the applied tag for the release in the "Choose +a tag" dropdown list. Go to the bottom of the list and select the "Set +as pre-release" checkbox. The "Set as the latest release" button is reserved for stable releases and updates to them. -If everything is in order, you can click on the "Publish release" button. Otherwise, click on "Save -draft" and finish pending tasks until you can return to edit the release page and publish it. +If everything is in order, you can click on the "Publish release" +button. Otherwise, click on "Save draft" and finish pending tasks until +you can return to edit the release page and publish it. -### Update download website, prepare pre-compiled packages, update packages to GitHub +### Prepare pre-compiled packages, update packages to GitHub -Publishing the release on GitHub will trigger the Temple Jenkins cluster to update -the https://docs.lammps.org/ website with the documentation for the new feature release -and it will create a tarball for download (which contains the translated manual). +Build a fully static LAMMPS installation using a musl-libc +cross-compiler, install into a lammps-static folder, and create a +tarball called lammps-linux-x86_64-19Nov2024.tar.gz (or using a +corresponding date with a future release) from the lammps-static folder. +A suitable build environment is provided with the +https://download.lammps.org/static/fedora37_musl.sif container image. -Build a fully static LAMMPS installation using a musl-libc cross-compiler, install into a -lammps-static folder, and create a tarball called lammps-linux-x86_64-19Nov2024.tar.gz (or using a -corresponding date with a future release) from the lammps-static folder and upload it to GitHub +``` sh +rm -rf release-packages +mkdir release-packages +cd release-packages +wget https://download.lammps.org/static/fedora41_musl.sif +apptainer shell fedora41_musl.sif +git clone -b release --depth 10 https://github.com/lammps/lammps.git lammps-release +cmake -S lammps-release/cmake -B build-release -G Ninja -D CMAKE_INSTALL_PREFIX=$PWD/lammps-static -D CMAKE_TOOLCHAIN_FILE=/usr/musl/share/cmake/linux-musl.cmake -C lammps-release/cmake/presets/most.cmake -C lammps-release/cmake/presets/kokkos-openmp.cmake -D DOWNLOAD_POTENTIALS=OFF -D BUILD_MPI=OFF -D BUILD_TESTING=OFF -D CMAKE_BUILD_TYPE=Release -D PKG_ATC=ON -D PKG_AWPMD=ON -D PKG_MANIFOLD=ON -D PKG_MESONT=ON -D PKG_MGPT=ON -D PKG_ML-PACE=ON -D PKG_ML-RANN=ON -D PKG_MOLFILE=ON -D PKG_PTM=ON -D PKG_QTB=ON -D PKG_SMTBQ=ON +cmake --build build-release --target all +cmake --build build-release --target install +/usr/musl/bin/x86_64-linux-musl-strip lammps-static/bin/* +tar -czvvf lammps-linux-x86_64-19Nov2024.tar.gz lammps-static +exit # fedora 41 container +``` + +The resulting tar archive can be uploaded to the GitHub release page with: + +``` +gh release upload patch_19Nov2024 lammps-linux-x86_64-19Nov2024.tar.gz +``` + +Make sure you have the `flatpak` and `flatpak-builder` packages +installed locally (they cannot be used from the container) and build a +LAMMPS and LAMMPS-GUI flatpak bundle in the `release-packages` folder with: -``` -gh release upload patch_19Nov2024 ~/Downloads/lammps-linux-x86_64-19Nov2024.tar.gz +``` sh +flatpak --user remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo +flatpak-builder --force-clean --verbose --repo=$PWD/flatpak-repo --install-deps-from=flathub --state-dir=$PWD --user --ccache --default-branch=release flatpak-build lammps-release/tools/lammps-gui/org.lammps.lammps-gui.yml +flatpak build-bundle --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo --verbose $PWD/flatpak-repo LAMMPS-Linux-x86_64-GUI-19Nov2024.flatpak org.lammps.lammps-gui release ``` +The resulting flatpak bundle file can be uploaded to the GitHub release page with: + +``` +gh release upload patch_19Nov2024 LAMMPS-Linux-x86_64-GUI-19Nov2024.flatpak +``` + +Also build serial executable packages that also include LAMMPS-GUI for +Linux, macOS, and Windows, and upload them to the GitHub release. + +Clean up: + +``` sh +cd .. +rm -r release-packages +``` + +TODO: +- add detailed commands for building GUI packages on Ubuntu 20.04LTS (move to 22.04LTS?), + macOS, and Windows cross-compiler and upload to GitHub +- build all Windows cross-compiled installer packages using lammps-packages repo + +### Update download website + +Check out the LAMMPS website repo +https://github.com/lammps/lammps-website.git and edit the file +`src/download.txt` for the new release. Test translation with `make +html` and review `html/download.html` Then add and commit to git and +push the changes to GitHub. The Temple Jenkis cluster will +automatically update https://www.lammps.org/download.html accordingly. + +Notify Steve of the release so he can update `src/bug.txt` on the +website from the available release notes. ## LAMMPS Stable Release -A LAMMPS stable release is prepared about once per year in the months July, August, or September. -One (or two, if needed) feature releases before the stable release shall contain only bug fixes -or minor feature updates in optional packages. Also substantial changes to the core of the code -shall be applied rather toward the beginning of a development cycle between two stable releases -than toward the end. The intention is to stablilize significant change to the core and have -outside users and developers try them out during the development cycle; the sooner the changes -are included, the better chances for spotting peripheral bugs and issues. +A LAMMPS stable release is prepared about once per year in the months +July, August, or September. One (or two, if needed) feature releases +before the stable release shall contain only bug fixes or minor feature +updates in optional packages. Also substantial changes to the core of +the code shall be applied rather toward the beginning of a development +cycle between two stable releases than toward the end. The intention is +to stablilize significant change to the core and have outside users and +developers try them out during the development cycle; the sooner the +changes are included, the better chances for spotting peripheral bugs +and issues. ### Prerequesites -Before making a stable release all remaining backported bugfixes shall be released as a (final) -stable update release (see below). +Before making a stable release all remaining backported bugfixes shall +be released as a (final) stable update release (see below). -A LAMMPS stable release process starts like a feature release (see above), only that this feature -release is called a "Stable Release Candidate" and no assets are uploaded to GitHub. +A LAMMPS stable release process starts like a feature release (see +above), only that this feature release is called a "Stable Release +Candidate" and no assets are uploaded to GitHub. ### Synchronize 'maintenance' branch with 'release' -The state of the 'release' branch is then transferred to the 'maintenance' branch (which will -have diverged significantly from 'release' due to the selectively backported bug fixes). +The state of the 'release' branch is then transferred to the +'maintenance' branch (which will have diverged significantly from +'release' due to the selectively backported bug fixes). ### Fast-forward merge of 'maintenance' into 'stable' and apply tag -At this point it should be possible to do a fast-forward merge of 'maintenance' to 'stable' -and then apply the stable\_DMmmYYYY tag. +At this point it should be possible to do a fast-forward merge of +'maintenance' to 'stable' and then apply the stable\_DMmmYYYY tag. ### Push branches and tags diff --git a/.github/workflows/style-check.yml b/.github/workflows/style-check.yml index 7be2c4fc46..e3567140fb 100644 --- a/.github/workflows/style-check.yml +++ b/.github/workflows/style-check.yml @@ -35,3 +35,4 @@ jobs: make check-permissions make check-homepage make check-errordocs + make check-fmtlib diff --git a/.github/workflows/unittest-arm64.yml b/.github/workflows/unittest-arm64.yml new file mode 100644 index 0000000000..094c5fb0c1 --- /dev/null +++ b/.github/workflows/unittest-arm64.yml @@ -0,0 +1,81 @@ +# GitHub action to build LAMMPS on Linux with ARM64 and run standard unit tests +name: "Unittest for Linux on ARM64" + +on: + push: + branches: [develop] + + workflow_dispatch: + +concurrency: + group: ${{ github.event_name }}-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{github.event_name == 'pull_request'}} + +jobs: + build: + name: Linux ARM64 Unit Test + if: ${{ github.repository == 'lammps/lammps' }} + runs-on: ubuntu-22.04-arm + env: + CCACHE_DIR: ${{ github.workspace }}/.ccache + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 2 + + - name: Install extra packages + run: | + sudo apt-get update + sudo apt-get install -y ccache \ + libeigen3-dev \ + libcurl4-openssl-dev \ + mold \ + ninja-build \ + python3-dev + + - name: Create Build Environment + run: mkdir build + + - name: Set up ccache + uses: actions/cache@v4 + with: + path: ${{ env.CCACHE_DIR }} + key: linux-unit-ccache-${{ github.sha }} + restore-keys: linux-unit-ccache- + + - name: Building LAMMPS via CMake + shell: bash + run: | + ccache -z + python3 -m venv linuxenv + source linuxenv/bin/activate + python3 -m pip install numpy + python3 -m pip install pyyaml + cmake -S cmake -B build \ + -C cmake/presets/gcc.cmake \ + -C cmake/presets/most.cmake \ + -D CMAKE_CXX_COMPILER_LAUNCHER=ccache \ + -D CMAKE_C_COMPILER_LAUNCHER=ccache \ + -D BUILD_SHARED_LIBS=on \ + -D DOWNLOAD_POTENTIALS=off \ + -D ENABLE_TESTING=on \ + -D MLIAP_ENABLE_ACE=on \ + -D MLIAP_ENABLE_PYTHON=off \ + -D PKG_MANIFOLD=on \ + -D PKG_ML-PACE=on \ + -D PKG_ML-RANN=on \ + -D PKG_RHEO=on \ + -D PKG_PTM=on \ + -D PKG_PYTHON=on \ + -D PKG_QTB=on \ + -D PKG_SMTBQ=on \ + -G Ninja + cmake --build build + ccache -s + + - name: Run Tests + working-directory: build + shell: bash + run: ctest -V -LE unstable diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index ce7b9f30f9..ff0d69e316 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -98,21 +98,24 @@ check_for_autogen_files(${LAMMPS_SOURCE_DIR}) ##################################################################### include(CheckIncludeFileCXX) -# set required compiler flags, apply checks, and compiler/CPU arch specific optimizations +# set required compiler flags and compiler/CPU arch specific optimizations if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel") - # Intel classic compilers version 19 are broken and fail to compile the embedded fmtlib - if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 20.0) - message(ERROR "Intel classic compiler version ${CMAKE_CXX_COMPILER_VERSION} is too old") - endif() - if(CMAKE_SYSTEM_NAME STREQUAL "Windows") if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel") set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /Qrestrict") endif() - set(CMAKE_TUNE_DEFAULT "/QxHost") + if(CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.3 OR CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.4) + set(CMAKE_TUNE_DEFAULT "/QxCOMMON-AVX512") + else() + set(CMAKE_TUNE_DEFAULT "/QxHost") + endif() else() set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -restrict") - set(CMAKE_TUNE_DEFAULT "-xHost -fp-model fast=2 -no-prec-div -qoverride-limits -diag-disable=10441 -diag-disable=11074 -diag-disable=11076 -diag-disable=2196") + if(CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.3 OR CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.4) + set(CMAKE_TUNE_DEFAULT "-xCOMMON-AVX512") + else() + set(CMAKE_TUNE_DEFAULT "-xHost -fp-model fast=2 -no-prec-div -qoverride-limits -diag-disable=10441 -diag-disable=11074 -diag-disable=11076 -diag-disable=2196") + endif() endif() endif() diff --git a/cmake/Modules/Packages/INTEL.cmake b/cmake/Modules/Packages/INTEL.cmake index e6755bf23b..6fb1c57e8a 100644 --- a/cmake/Modules/Packages/INTEL.cmake +++ b/cmake/Modules/Packages/INTEL.cmake @@ -72,6 +72,10 @@ if(INTEL_ARCH STREQUAL "KNL") if(NOT CMAKE_CXX_COMPILER_ID STREQUAL "Intel") message(FATAL_ERROR "Must use Intel compiler with INTEL for KNL architecture") endif() + message(WARNING, "Support for Intel Xeon Phi accelerators and Knight's Landing CPUs " + "will be removed from LAMMPS in Summer 2025 due to lack of available machines " + "in labs and HPC centers and removed support in recent compilers " + "Please contact developers@lammps.org if you have any concerns about this step.") set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -xHost -qopenmp -qoffload") set(MIC_OPTIONS "-qoffload-option,mic,compiler,\"-fp-model fast=2 -mGLOB_default_function_attrs=\\\"gather_scatter_loop_unroll=4\\\"\"") target_compile_options(lammps PRIVATE -xMIC-AVX512 -qoffload -fno-alias -ansi-alias -restrict -qoverride-limits ${MIC_OPTIONS}) diff --git a/cmake/Modules/Packages/KOKKOS.cmake b/cmake/Modules/Packages/KOKKOS.cmake index 2fa5a449fb..2731b0df14 100644 --- a/cmake/Modules/Packages/KOKKOS.cmake +++ b/cmake/Modules/Packages/KOKKOS.cmake @@ -117,7 +117,6 @@ set(KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/atom_vec_kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/comm_kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/comm_tiled_kokkos.cpp - ${KOKKOS_PKG_SOURCES_DIR}/group_kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/min_kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/min_linesearch_kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/neighbor_kokkos.cpp diff --git a/cmake/Modules/Packages/PLUMED.cmake b/cmake/Modules/Packages/PLUMED.cmake index 8dab157a24..5e5d110626 100644 --- a/cmake/Modules/Packages/PLUMED.cmake +++ b/cmake/Modules/Packages/PLUMED.cmake @@ -32,9 +32,9 @@ endif() # Note: must also adjust check for supported API versions in # fix_plumed.cpp when version changes from v2.n.x to v2.n+1.y -set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.9.2/plumed-src-2.9.2.tgz" +set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.9.3/plumed-src-2.9.3.tgz" CACHE STRING "URL for PLUMED tarball") -set(PLUMED_MD5 "04862602a372c1013bdfee2d6d03bace" CACHE STRING "MD5 checksum of PLUMED tarball") +set(PLUMED_MD5 "ee1249805fe94bccee17d10610d3f6f1" CACHE STRING "MD5 checksum of PLUMED tarball") mark_as_advanced(PLUMED_URL) mark_as_advanced(PLUMED_MD5) diff --git a/doc/lammps.1 b/doc/lammps.1 index cb52813a4d..d6d43cc081 100644 --- a/doc/lammps.1 +++ b/doc/lammps.1 @@ -1,7 +1,7 @@ -.TH LAMMPS "1" "19 November 2024" "2024-11-19" +.TH LAMMPS "1" "4 February 2025" "2025-02-04" .SH NAME .B LAMMPS -\- Molecular Dynamics Simulator. Version 19 November 2024 +\- Molecular Dynamics Simulator. Version 4 February 2025 .SH SYNOPSIS .B lmp @@ -311,7 +311,7 @@ the chapter on errors in the manual gives some additional information about error messages, if possible. .SH COPYRIGHT -© 2003--2024 Sandia Corporation +© 2003--2025 Sandia Corporation This package is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as diff --git a/doc/src/Build_basics.rst b/doc/src/Build_basics.rst index 7014762cdc..be4b312578 100644 --- a/doc/src/Build_basics.rst +++ b/doc/src/Build_basics.rst @@ -196,13 +196,18 @@ LAMMPS. .. tab:: CMake build - By default CMake will use the compiler it finds according to + By default CMake will use the compiler it finds according to its internal preferences, and it will add optimization flags appropriate to that compiler and any :doc:`accelerator packages ` you have included in the build. CMake will check if the detected or selected compiler is compatible with the C++ support requirements of LAMMPS and stop with an error, if this - is not the case. + is not the case. A C++11 compatible compiler is currently + required, but a transition to require C++17 is in progress and + planned to be completed in Summer 2025. Currently, setting + ``-DLAMMPS_CXX11=yes`` is required when configuring with CMake while + using a C++11 compatible compiler that does not support C++17, + otherwise setting ``-DCMAKE_CXX_STANDARD=17`` is preferred. You can tell CMake to look for a specific compiler with setting CMake variables (listed below) during configuration. For a few @@ -223,6 +228,8 @@ LAMMPS. -D CMAKE_C_COMPILER=name # name of C compiler -D CMAKE_Fortran_COMPILER=name # name of Fortran compiler + -D CMAKE_CXX_STANDARD=17 # put compiler in C++17 mode + -D LAMMPS_CXX11=yes # enforce compilation in C++11 mode -D CMAKE_CXX_FLAGS=string # flags to use with C++ compiler -D CMAKE_C_FLAGS=string # flags to use with C compiler -D CMAKE_Fortran_FLAGS=string # flags to use with Fortran compiler @@ -321,15 +328,23 @@ LAMMPS. you would have to install a newer compiler that supports C++11; either as a binary package or through compiling from source. - If you build LAMMPS with any :doc:`Speed_packages` included, - there may be specific compiler or linker flags that are either - required or recommended to enable required features and to - achieve optimal performance. You need to include these in the - ``CCFLAGS`` and ``LINKFLAGS`` settings above. For details, see the - documentation for the individual packages listed on the - :doc:`Speed_packages` page. Or examine these files in the - ``src/MAKE/OPTIONS`` directory. They correspond to each of the 5 - accelerator packages and their hardware variants: + While a C++11 compatible compiler is currently sufficient to compile + LAMMPS, a transition to require C++17 is in progress and planned to + be completed in Summer 2025. Currently, setting ``-DLAMMPS_CXX11`` + in the ``LMP_INC =`` line in the machine makefile is required when + using a C++11 compatible compiler that does not support C++17. + Otherwise, to enable C++17 support (if not enabled by default) using + a compiler flag like ``-std=c++17`` in CCFLAGS may needed. + + If you build LAMMPS with any :doc:`Speed_packages` included, + there may be specific compiler or linker flags that are either + required or recommended to enable required features and to + achieve optimal performance. You need to include these in the + ``CCFLAGS`` and ``LINKFLAGS`` settings above. For details, see the + documentation for the individual packages listed on the + :doc:`Speed_packages` page. Or examine these files in the + ``src/MAKE/OPTIONS`` directory. They correspond to each of the 5 + accelerator packages and their hardware variants: .. code-block:: bash diff --git a/doc/src/Commands_all.rst b/doc/src/Commands_all.rst index 58623401f3..bfc9e8538c 100644 --- a/doc/src/Commands_all.rst +++ b/doc/src/Commands_all.rst @@ -140,6 +140,7 @@ additional letter in parenthesis: k = KOKKOS. * :doc:`plugin ` * :doc:`prd ` * :doc:`python ` + * :doc:`region2vmd ` * :doc:`tad ` * :doc:`temper ` * :doc:`temper/grem ` diff --git a/doc/src/Commands_compute.rst b/doc/src/Commands_compute.rst index fd68ce3e39..7c73583a4f 100644 --- a/doc/src/Commands_compute.rst +++ b/doc/src/Commands_compute.rst @@ -58,6 +58,7 @@ KOKKOS, o = OPENMP, t = OPT. * :doc:`fep/ta ` * :doc:`force/tally ` * :doc:`fragment/atom ` + * :doc:`gaussian/grid/local (k) ` * :doc:`global/atom ` * :doc:`group/group ` * :doc:`gyration ` @@ -140,8 +141,8 @@ KOKKOS, o = OPENMP, t = OPT. * :doc:`smd/vol ` * :doc:`snap ` * :doc:`sna/atom ` - * :doc:`sna/grid ` - * :doc:`sna/grid/local ` + * :doc:`sna/grid (k) ` + * :doc:`sna/grid/local (k) ` * :doc:`snad/atom ` * :doc:`snav/atom ` * :doc:`sph/e/atom ` diff --git a/doc/src/Commands_fix.rst b/doc/src/Commands_fix.rst index 04d1a9969a..6192029a0a 100644 --- a/doc/src/Commands_fix.rst +++ b/doc/src/Commands_fix.rst @@ -58,6 +58,7 @@ OPT. * :doc:`dt/reset (k) ` * :doc:`edpd/source ` * :doc:`efield (k) ` + * :doc:`efield/lepton ` * :doc:`efield/tip4p ` * :doc:`ehex ` * :doc:`electrode/conp (i) ` diff --git a/doc/src/Commands_pair.rst b/doc/src/Commands_pair.rst index 5f42f53bd5..048a54ed37 100644 --- a/doc/src/Commands_pair.rst +++ b/doc/src/Commands_pair.rst @@ -80,6 +80,7 @@ OPT. * :doc:`coul/tt ` * :doc:`coul/wolf (ko) ` * :doc:`coul/wolf/cs ` + * :doc:`dispersion/d3 ` * :doc:`dpd (giko) ` * :doc:`dpd/coul/slater/long (g) ` * :doc:`dpd/ext (ko) ` @@ -114,7 +115,9 @@ OPT. * :doc:`gw/zbl ` * :doc:`harmonic/cut (o) ` * :doc:`hbond/dreiding/lj (o) ` + * :doc:`hbond/dreiding/lj/angleoffset (o) ` * :doc:`hbond/dreiding/morse (o) ` + * :doc:`hbond/dreiding/morse/angleoffset (o) ` * :doc:`hdnnp ` * :doc:`hippo (g) ` * :doc:`ilp/graphene/hbn (t) ` diff --git a/doc/src/Commands_removed.rst b/doc/src/Commands_removed.rst index be775f4c19..de60d6636c 100644 --- a/doc/src/Commands_removed.rst +++ b/doc/src/Commands_removed.rst @@ -87,7 +87,7 @@ Minimize style fire/old .. deprecated:: 8Feb2023 Minimize style *fire/old* has been removed. Its functionality can be -reproduced with *fire* with specific options. Please see the +reproduced with style *fire* with specific options. Please see the :doc:`min_modify command ` documentation for details. Pair style mesont/tpm, compute style mesont, atom style mesont diff --git a/doc/src/Developer_code_design.rst b/doc/src/Developer_code_design.rst index 974266ec7f..9213efa18f 100644 --- a/doc/src/Developer_code_design.rst +++ b/doc/src/Developer_code_design.rst @@ -203,6 +203,7 @@ processed in the expected order before types are removed from dynamic dispatch. .. admonition:: Important Notes + :class: note In order to be able to detect incompatibilities at compile time and to avoid unexpected behavior, it is crucial that all member functions @@ -300,18 +301,24 @@ Formatting with the {fmt} library The LAMMPS source code includes a copy of the `{fmt} library `_, which is preferred over formatting with the -"printf()" family of functions. The primary reason is that it allows -a typesafe default format for any type of supported data. This is +"printf()" family of functions. The primary reason is that it allows a +typesafe default format for any type of supported data. This is particularly useful for formatting integers of a given size (32-bit or -64-bit) which may require different format strings depending on -compile time settings or compilers/operating systems. Furthermore, -{fmt} gives better performance, has more functionality, a familiar -formatting syntax that has similarities to ``format()`` in Python, and -provides a facility that can be used to integrate format strings and a -variable number of arguments into custom functions in a much simpler -way than the varargs mechanism of the C library. Finally, {fmt} has -been included into the C++20 language standard, so changes to adopt it -are future-proof. +64-bit) which may require different format strings depending on compile +time settings or compilers/operating systems. Furthermore, {fmt} gives +better performance, has more functionality, a familiar formatting syntax +that has similarities to ``format()`` in Python, and provides a facility +that can be used to integrate format strings and a variable number of +arguments into custom functions in a much simpler way than the varargs +mechanism of the C library. Finally, {fmt} has been included into the +C++20 language standard as ``std::format()``, so changes to adopt it are +future-proof, for as long as they are not using any extensions that are +not (yet) included into C++. + +The long-term plan is to switch to using ``std::format()`` instead of +``fmt::format()`` when the minimum C++ standard required for LAMMPS will +be set to C++20. See the :ref:`basic build instructions ` for +more details. Formatted strings are frequently created by calling the ``fmt::format()`` function, which will return a string as a @@ -319,11 +326,13 @@ Formatted strings are frequently created by calling the ``printf()``, the {fmt} library uses ``{}`` to embed format descriptors. In the simplest case, no additional characters are needed, as {fmt} will choose the default format based on the data type of the argument. -Otherwise, the ``fmt::print()`` function may be used instead of -``printf()`` or ``fprintf()``. In addition, several LAMMPS output -functions, that originally accepted a single string as argument have -been overloaded to accept a format string with optional arguments as -well (e.g., ``Error::all()``, ``Error::one()``, ``utils::logmesg()``). +Otherwise, the :cpp:func:`utils::print() ` +function may be used instead of ``printf()`` or ``fprintf()``. In +addition, several LAMMPS output functions, that originally accepted a +single string as argument have been overloaded to accept a format string +with optional arguments as well (e.g., ``Error::all()``, +``Error::one()``, :cpp:func:`utils::logmesg() +`). Summary of the {fmt} format syntax ================================== diff --git a/doc/src/Developer_flow.rst b/doc/src/Developer_flow.rst index 17d75879ca..5efbfaa51d 100644 --- a/doc/src/Developer_flow.rst +++ b/doc/src/Developer_flow.rst @@ -209,7 +209,7 @@ nve, nvt, npt. At the end of the timestep, fixes that contain an ``end_of_step()`` method are invoked. These typically perform a diagnostic calculation, -e.g. the ave/time and ave/spatial fixes. The final operation of the +e.g. the ave/time and ave/chunk fixes. The final operation of the timestep is to perform any requested output, via the ``write()`` method of the Output class. There are 3 kinds of LAMMPS output: thermodynamic output to the screen and log file, snapshots of atom data to a dump diff --git a/doc/src/Developer_notes.rst b/doc/src/Developer_notes.rst index af26b4b913..3f78f33d25 100644 --- a/doc/src/Developer_notes.rst +++ b/doc/src/Developer_notes.rst @@ -7,13 +7,7 @@ typically document what a variable stores, what a small section of code does, or what a function does and its input/outputs. The topics on this page are intended to document code functionality at a higher level. -Available topics are: - -- `Reading and parsing of text and text files`_ -- `Requesting and accessing neighbor lists`_ -- `Choosing between a custom atom style, fix property/atom, and fix STORE/ATOM`_ -- `Fix contributions to instantaneous energy, virial, and cumulative energy`_ -- `KSpace PPPM FFT grids`_ +.. contents:: ---- @@ -218,6 +212,149 @@ command: neighbor->add_request(this, "delete_atoms", NeighConst::REQ_FULL); + +Errors, warnings, and informational messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +LAMMPS has specialized functionality to handle errors (which should +terminate LAMMPS), warning messages (which should indicate possible +problems *without* terminating LAMMPS), and informational text for +messages about the progress and chosen settings. We *strongly* +encourage using these facilities and to *stay away* from using +``printf()`` or ``fprintf()`` or ``std::cout`` or ``std::cerr`` and +calling ``MPI_Abort()`` or ``exit()`` directly. Warnings and +informational messages should be printed only on MPI rank 0 to avoid +flooding the output when running in parallel with many MPI processes. + +**Errors** + +When LAMMPS encounters an error, for example a syntax error in the +input, then a suitable error message should be printed giving a brief, +one line remark about the reason and then call either ``Error::all()`` +or ``Error::one()``. ``Error::all()`` must be called when the failing +code path is executed by *all* MPI processes and the error condition +will appear for *all* MPI processes the same. If desired, each MPI +process may set a flag to either 0 or 1 and then MPI_Allreduce() +searching for the maximum can be used to determine if there was an error +on *any* of the MPI processes and make this information available to +*all*. ``Error::one()`` in contrast needs to be called when only one or +a few MPI processes execute the code path or can have the error +condition. ``Error::all()`` is generally the preferred option. + +Calling these functions does not abort LAMMPS directly, but rather +throws either a ``LAMMPSException`` (from ``Error::all()``) or a +``LAMMPSAbortException`` (from ``Error::one()``). These exceptions are +caught by the LAMMPS ``main()`` program and then handled accordingly. +The reason for this approach is to support applications, especially +graphical applications like :ref:`LAMMPS-GUI `, that are +linked to the LAMMPS library and have a mechanism to avoid that an error +in LAMMPS terminates the application. By catching the exceptions, the +application can delete the failing LAMMPS class instance and create a +new one to try again. In a similar fashion, the :doc:`LAMMPS Python +module ` checks for this and then re-throws corresponding +Python exception, which in turn can be caught by the calling Python +code. + +There are multiple "signatures" that can be called: + +- ``Error::all(FLERR, "Error message")``: this will abort LAMMPS with + the error message "Error message", followed by the last line of input + that was read and processed before the error condition happened. + +- ``Error::all(FLERR, Error::NOLASTLINE, "Error message")``: this is the + same as before but without the last line of input. This is preferred + for errors that would happen *during* a :doc:`run ` or + :doc:`minimization `, since showing the "run" or "minimize" + command would be the last line, but is unrelated to the error. + +- ``Error::all(FLERR, idx, "Error message")``: this is for argument + parsing where "idx" is the index (starting at 0) of the argument for a + LAMMPS command that is causing the failure (use -1 for the command + itself). For index 0, you need to use the constant ``Error::ARGZERO`` + to work around the inability of some compilers to disambiguate between + a NULL pointer and an integer constant 0, even with an added type cast. + The output may also include the last input line *before* and + *after*, if they differ due to substituting variables. A textual + indicator is pointing to the specific word that failed. Using the + constant ``Error::NOPOINTER`` in place of the *idx* argument will + suppress the marker and then the behavior is like the *idx* argument + is not provided. + +FLERR is a macro containing the filename and line where the Error class +is called and that information is appended to the error message. This +allows to quickly find the relevant source code causing the error. For +all three signatures, the single string "Error message" may be replaced +with a format string using '{}' placeholders and followed by a variable +number of arguments, one for each placeholder. This format string and +the arguments are then handed for formatting to the `{fmt} library +`_ (which is bundled with LAMMPS) and thus allow +processing similar to the "format()" functionality in Python. + +.. note:: + + For commands like :doc:`fix ave/time ` that accept + wildcard arguments, the :cpp:func:`utils::expand_args` function + may be passed as an optional argument where the function will provide + a map to the original arguments from the expanded argument indices. + +For complex errors, that can have multiple causes and which cannot be +explained in a single line, you can append to the error message, the +string created by :cpp:func:`utils::errorurl`, which then provides a +URL pointing to a paragraph of the :doc:`Errors_details` that +corresponds to the number provided. Example: + +.. code-block:: c++ + + error->all(FLERR, "Unknown identifier in data file: {}{}", keyword, utils::errorurl(1)); + +This will output something like this: + +.. parsed-literal:: + + ERROR: Unknown identifier in data file: Massess + For more information see https://docs.lammps.org/err0001 (src/read_data.cpp:1482) + Last input line: read_data data.peptide + +Where the URL points to the first paragraph with explanations on +the :doc:`Errors_details` page in the manual. + +**Warnings** + +To print warnings, the ``Errors::warning()`` function should be used. +It also requires the FLERR macros as first argument to easily identify +the location of the warning in the source code. Same as with the error +functions above, the function has two variants: one just taking a single +string as final argument and a second that uses the `{fmt} library +`_ to make it similar to, say, ``fprintf()``. One +motivation to use this function is that it will output warnings with +always the same capitalization of the leading "WARNING" string. A +second is that it has a built in rate limiter. After a given number (by +default 100), that can be set via the :doc:`thermo_modify command +` no more warnings are printed. Also, warnings are +written consistently to both screen and logfile or not, depending on the +settings for :ref:`screen ` or :doc:`logfile ` output. + +.. note:: + + Unlike ``Error::all()``, the warning function will produce output on + *every* MPI process, so it typically would be prefixed with an if + statement testing for ``comm->me == 0``, i.e. limiting output to MPI + rank 0. + +**Informational messages** + +Finally, for informational message LAMMPS has the +:cpp:func:`utils::logmesg() convenience function +`. It also uses the `{fmt} library +`_ to support using a format string followed by a +matching number of arguments. It will output the resulting formatted +text to both, the screen and the logfile and will honor the +corresponding settings about whether this output is active and to which +file it should be send. Same as for ``Error::warning()``, it would +produce output for every MPI process and thus should usually be called +only on MPI rank 0 to avoid flooding the output when running with many +parallel processes. + Choosing between a custom atom style, fix property/atom, and fix STORE/ATOM ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/src/Developer_utils.rst b/doc/src/Developer_utils.rst index b7f62d5364..866945fc88 100644 --- a/doc/src/Developer_utils.rst +++ b/doc/src/Developer_utils.rst @@ -133,6 +133,9 @@ and parsing files or arguments. .. doxygenfunction:: trim_comment :project: progguide +.. doxygenfunction:: strcompress + :project: progguide + .. doxygenfunction:: strip_style_suffix :project: progguide @@ -166,6 +169,9 @@ and parsing files or arguments. .. doxygenfunction:: split_lines :project: progguide +.. doxygenfunction:: strsame + :project: progguide + .. doxygenfunction:: strmatch :project: progguide @@ -232,12 +238,21 @@ Convenience functions .. doxygenfunction:: logmesg(LAMMPS *lmp, const std::string &mesg) :project: progguide +.. doxygenfunction:: print(FILE *fp, const std::string &format, Args&&... args) + :project: progguide + +.. doxygenfunction:: print(FILE *fp, const std::string &mesg) + :project: progguide + .. doxygenfunction:: errorurl :project: progguide .. doxygenfunction:: missing_cmd_args :project: progguide +.. doxygenfunction:: point_to_error + :project: progguide + .. doxygenfunction:: flush_buffers(LAMMPS *lmp) :project: progguide diff --git a/doc/src/Developer_write_fix.rst b/doc/src/Developer_write_fix.rst index afa569b05d..1b578823bd 100644 --- a/doc/src/Developer_write_fix.rst +++ b/doc/src/Developer_write_fix.rst @@ -96,8 +96,8 @@ Here the we specify which methods of the fix should be called during 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]); + utils::print(screen, "{}, {}, {}\n", + globalAvgVel[0], globalAvgVel[1], globalAvgVel[2]); } } diff --git a/doc/src/Errors_details.rst b/doc/src/Errors_details.rst index 09f3d893db..96efead1a2 100644 --- a/doc/src/Errors_details.rst +++ b/doc/src/Errors_details.rst @@ -4,9 +4,172 @@ Error and warning details Many errors or warnings are self-explanatory and thus straightforward to resolve. However, there are also cases, where there is no single cause and explanation, where LAMMPS can only detect symptoms of an error but -not the exact cause, or where the explanation needs to be more detailed than -what can be fit into a message printed by the program. The following are -discussions of such cases. +not the exact cause, or where the explanation needs to be more detailed +than what can be fit into a message printed by the program. The +following are discussions of such cases. + +- :ref:`Unknown identifier in data file ` +- :ref:`Incorrect format in ... section of data file ` +- :ref:`Illegal variable command: expected X arguments but found Y ` +- :ref:`Out of range atoms - cannot compute ... ` +- :ref:`Too many neighbor bins ` +- :ref:`Cannot use neighbor bins - box size \<\< cutoff ` +- :ref:`Domain too large for neighbor bins ` +- :ref:`Molecule topology/atom exceeds system topology/atom ` +- :ref:`Molecule topology type exceeds system topology type ` +- :ref:`Molecule attributes do not match system attributes ` + +------ + +General troubleshooting advice +------------------------------ + +Below are suggestions that can help to understand the causes of problems +with simulations leading to errors or unexpected results. + +Create a small test system +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Debugging problems often requires running a simulation many times with +small modifications, thus it can be a huge time saver to first assemble +a small test system input that has the same issue, but will take much +time until it triggers the error condition. Also, it will be easier to +see what happens. + +Visualize your trajectory +^^^^^^^^^^^^^^^^^^^^^^^^^ + +To better understand what is causing problems, it is often very useful +to visualize the system close to the point of failure. It may be +necessary to have LAMMPS output trajectory frames rather frequently. To +avoid gigantic files, you can use :doc:`dump_modify delay ` +to delay output until the critical section is reached, and you can use a +smaller test system (see above). + +Parallel versus serial +^^^^^^^^^^^^^^^^^^^^^^ + +Issues where something is "lost" or "missing" often exhibit that issue +only when running in parallel. That doesn't mean there is no problem, +only the symptoms are not triggering an error quickly. Correspondingly, +errors may be triggered faster with more processors and thus smaller +sub-domains. + +Fast moving atoms +^^^^^^^^^^^^^^^^^ + +Fast moving atoms may be "lost" or "missing" when their velocity becomes +so large that they can cross a sub-domain within one timestep. This +often happens when atoms are too close, but atoms may also "move" too +fast from sub-domain to sub-domain if the box changes rapidly, e.g. when +setting a large an initial box with :doc:`shrink-wrap boundary +conditions ` that collapses on the first step (in this case +the solution is often using 'm' instead of 's' as boundary condition). + +To reduce the impact of "close contacts", one can remove those atoms or +molecules with something like :doc:`delete_atoms overlap 0.1 all all +`. With periodic boundaries, a close contact pair of atoms +may be on opposite sides of the simulation box. Another option would be +to first run a minimization (aka quench) before starting the MD. Reducing +the time step can also help. Many times, one just needs to "ease" the +system into a balanced state and can then switch to more aggressive settings. + +The speed of atoms during an MD depends on the steepness of the +potential function and their mass. Since the positions and velocities +of atoms are computed with finite timesteps, they choice of timestep can +be too large for a stable numeric integration of the trajectory. In +those cases using (temporarily) :doc:`fix nve/limit ` or +:doc:`fix dt/reset ` can help to avoid too large updates +or adapt the timestep according to the displacements. + + +Pressure, forces, positions becoming NaN of Inf +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some potentials can overflow or have a division by zero with close contacts +or bad geometries (for the given force styles in use) leading to forces +that can no longer be represented as numbers. Those will show as "NaN" or +"Inf". On most machines, the program will continue, but there is no way +to recover from it and those NaN or Inf values will propagate. So-called +:doc:`"soft-core" potentials ` or the :doc:`"soft" repulsive-only +pair style ` are less prone for this behavior (depending on the +settings in use) and can be used at the beginning of a simulation. Also, +single precision numbers can overflow much faster, so for the GPU or INTEL +package it may be beneficial to run with double precision initially before +switching to mixed or single precision for faster execution when the system +has relaxed. + +Communication cutoff +^^^^^^^^^^^^^^^^^^^^ + +The communication cutoff determines the "overlap" between sub-domains +and atoms in these regions are referred to in LAMMPS as "ghost atoms". +This region has to be large enough to contain all atoms of a bond, +angle, dihedral or improper with just one atom in the actual sub-domain. +Typically, this cutoff is set to the largest cutoff from the :doc:`pair +style(s) ` plus the :doc:`neighbor list skin distance +` and will be more than sufficient for all bonded +interactions. But if the pair style cutoff is small this may bot be +enough. LAMMPS will print a warning in this case using some heuristic +based on the equilibrium bond length, but that may not be sufficient for +cases where the force constants are small and thus bonds may be +stretched very far. The communication cutoff can be adjusted with +:doc:`comm_modify cutoff \ `, but setting this too +large will waste CPU time and memory. + +Neighbor list settings +^^^^^^^^^^^^^^^^^^^^^^ + +Every time LAMMPS rebuilds the neighbor lists, LAMMPS will also check +for "lost" or "missing" atoms. Thus it can help to use very +conservative :doc:`neighbor list settings ` and then +examine the neighbor list statistics if the neighbor list rebuild can be +safely delayed. Rebuilding the neighbor list less frequently +(i.e. through increasing the *delay* or *every* setting has diminishing +returns and increasing risks). + +Ignoring lost atoms +^^^^^^^^^^^^^^^^^^^ + +It is tempting to use the :doc:`thermo_modify lost ignore ` +to avoid that LAMMPS stops with an error. This setting should, however, +*only* be used when atoms *should* leave the system. In general, ignoring +a problem does not solve it. + +Units +^^^^^ + +A frequent cause for a variety of problems is due to using the wrong +:doc:`units ` settings for a particular potentials, especially +when reading them from a potential file. Most of the (example) +potentials bundled with LAMMPS have a "UNITS:" tag that allows LAMMPS to +check of the units are consistent with what is intended, but potential +files from publications or potential parameter databases may lack this +metadata information and thus will not error out or warn when using the +wrong setting. Most potential files usually use "metal" units, but some +are parameterized for other settings, most notably :doc:`ReaxFF +potentials ` that use "real" units. + +Also, individual parameters for :doc:`pair_coeff ` commands +taken from publications or other MD software, may need to be converted +and sometimes in unexpected ways. Thus some careful checking is +recommended. + +No error message printed +^^^^^^^^^^^^^^^^^^^^^^^^ + +In some cases - especially when running in parallel with MPI - LAMMPS +may stop without displaying an error. But that does not mean, that +there was no error message, instead it is highly likely that the message +was written to a buffer and LAMMPS was aborted before the buffer was +output. Usually, output buffers are output for every line of output, +but sometimes, this is delayed until 4096 or 8192 bytes of output have +been accumulated. This buffering for screen and logfile output can be +disabled by using the :ref:`-nb or -nonbuf ` command-line flag. +This is most often needed when debugging crashing multi-replica +calculations. + +------ .. _err0001: @@ -77,3 +240,130 @@ Thus missing quotes or accidental extra whitespace will lead to the error shown in the header because the unquoted whitespace will result in the text being broken into more "words", i.e. the variable expression being split. + +.. _err0004: + +Out of range atoms - cannot compute ... +--------------------------------------- + +The PPPM (and also PPPMDisp and MSM) methods require to assemble a grid +of electron density data derived from the (partial) charges assigned to +the atoms. This charges are smeared out across multiple grid points +(see :doc:`kspace_modify order `). When running in +parallel with MPI, LAMMPS uses a :doc:`domain decomposition scheme +` where each processor manages a subset of atoms and +thus also a grid representing the density, which covers the actual +volume of the sub-domain and some extra space corresponding to the +:doc:`neighbor list skin `. These are then :doc:`combined and +redistributed ` for parallel processing of the +long-range component of the Coulomb interaction. + +The ``Out of range atoms`` error can happen, when atoms move too fast or +the neighbor list skin is too small or the neighbor lists are not +updated frequently enough. Then the smeared charges cannot be fully +assigned to the density grid for all atoms. LAMMPS checks for this +condition and stops with an error. Most of the time, this is an +indication of a system with very high forces, most often at the +beginning of a simulation or when boundary conditions are changed. The +error becomes more likely with more MPI processes. + +There are multiple options to explore for avoiding the error. The best +choice depends strongly on the individual system, and often a +combination of changes is required. For example, more conservative MD +parameter settings can be used (larger neighbor skin, shorter time step, +more frequent neighbor list updates). Sometimes, it helps to revisit +the system generation and avoid close contacts when building it, or use +the :doc:`delete_atoms overlap` command to delete those +close contact atoms, or run a minimization before the MD. It can also +help to temporarily use a cutoff-Coulomb pair style and no kspace style +until the system has somewhat equilibrated and then switch to the +long-range solver. + +.. _err0009: + +Too many neighbor bins +---------------------- + +The simulation box has become too large relative to the size of a +neighbor bin and LAMMPS is unable to store the needed number of +bins. This typically implies the simulation box has expanded too far. +This can happen when some atoms move rapidly apart with shrink-wrap +boundaries or when a fix (like fix deform or a barostat) excessively +grows the simulation box. + +.. _err0015: + +Cannot use neighbor bins - box size \<\< cutoff +----------------------------------------------- + +LAMMPS is unable to build neighbor bins since the size of the box is +much smaller than an interaction cutoff in at least one of its dimensions. +Typically, this error is triggered when the simulation box has one very +thin dimension. If a cubic neighbor bin had to fit exactly within +the thin dimension, then an inordinate amount of bins would be created to +fill space. This error can be avoided using the generally slower +:doc:`nsq neighbor style ` or by increasing the size of the +smallest box lengths. + +.. _err0017: + +Domain too large for neighbor bins +---------------------------------- + +The domain has become extremely large so that neighbor bins cannot +be used. Too many neighbor bins would need to be created to fill space +Most likely, one or more atoms have been blown out of the simulation +box to a great distance or a fix (like fix deform or a barostat) has +excessively grown the simulation box. + +.. _err0024: + +Molecule topology/atom exceeds system topology/atom +--------------------------------------------------- + +LAMMPS uses :doc:`domain decomposition ` to +distribute data (i.e. atoms) across the MPI processes in parallel runs. +This includes topology data, that is data about bonds, angles, +dihedrals, impropers and :doc:`"special" neighbors `. +This information is stored with either one or all atoms involved in such +a topology entry (which of the two option applies depends on the +:doc:`newton ` setting for bonds. When reading a data file, +LAMMPS analyzes the requirements for this file and then the values +are "locked in" and cannot be extended. + +So loading a molecule file that requires more of the topology per atom +storage or adding a data file with such needs will lead to an error. To +avoid the error, one or more of the `extra/XXX/per/atom` keywords are +required to extend the corresponding storage. It is no problem to +choose those numbers generously and have more storage reserved than +actually needed, but having these numbers set too small will lead to an +error. + +.. _err0025: + +Molecule topology type exceeds system topology type +--------------------------------------------------- + +The total number of atom, bond, angle, dihedral, and improper types is +"locked in" when LAMMPS creates the simulation box. This can happen +through either the :doc:`create_box `, the :doc:`read_data +`, or the :doc:`read_restart ` command. After +this it is not possible to refer to an additional type. So loading a +molecule file that uses additional types or adding a data file that +would require additional types will lead to an error. To avoid the +error, one or more of the `extra/XXX/types` keywords are required to +extend the maximum number of the individual types. + +.. _err0026: + +Molecule attributes do not match system attributes +-------------------------------------------------- + +Choosing an :doc:`atom_style ` in LAMMPS determines which +per-atom properties are available. In a :doc:`molecule file +`, however, it is possible to add sections (for example Masses +or Charges) that are not supported by the atom style. Masses for +example, are usually not a per-atom property, but defined through the +atom type. Thus it would not be required to have a Masses section and +the included data would be ignored. LAMMPS prints this warning to +inform about this case. diff --git a/doc/src/Fortran.rst b/doc/src/Fortran.rst index bc641a237f..ea0ade5cf4 100644 --- a/doc/src/Fortran.rst +++ b/doc/src/Fortran.rst @@ -323,6 +323,12 @@ of the contents of the :f:mod:`LIBLAMMPS` Fortran interface to LAMMPS. :ftype set_internal_variable: subroutine :f eval: :f:func:`eval` :ftype eval: function + :f clearstep_compute: :f:subr:`clearstep_compute` + :ftype clearstep_compute: subroutine + :f addstep_compute: :f:subr:`addstep_compute` + :ftype addstep_compute: subroutine + :f addstep_compute_all: :f:subr:`addstep_compute_all` + :ftype addstep_compute_all: subroutine :f gather_atoms: :f:subr:`gather_atoms` :ftype gather_atoms: subroutine :f gather_atoms_concat: :f:subr:`gather_atoms_concat` @@ -956,6 +962,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type :f:func:`extract_atom` between runs. .. admonition:: Array index order + :class: tip Two-dimensional arrays returned from :f:func:`extract_atom` will be **transposed** from equivalent arrays in C, and they will be indexed @@ -1068,6 +1075,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type you based on data from the :cpp:class:`Compute` class. .. admonition:: Array index order + :class: tip Two-dimensional arrays returned from :f:func:`extract_compute` will be **transposed** from equivalent arrays in C, and they will be indexed @@ -1326,6 +1334,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type :rtype data: polymorphic .. admonition:: Array index order + :class: tip Two-dimensional global, per-atom, or local array data from :f:func:`extract_fix` will be **transposed** from equivalent arrays in @@ -1450,11 +1459,62 @@ Procedures Bound to the :f:type:`lammps` Derived Type an internal-style variable, an error is generated. :p character(len=*) name: name of the variable - :p read(c_double) val: new value to assign to the variable + :p real(c_double) val: new value to assign to the variable :to: :cpp:func:`lammps_set_internal_variable` -------- +.. f:function:: eval(expr) + + This function is a wrapper around :cpp:func:`lammps_eval` that takes a + LAMMPS equal style variable string, evaluates it and returns the resulting + scalar value as a floating-point number. + + .. versionadded:: 4Feb2025 + + :p character(len=\*) expr: string to be evaluated + :to: :cpp:func:`lammps_eval` + :r value [real(c_double)]: result of the evaluated string + +-------- + +.. f:subroutine:: clearstep_compute() + + Clear whether a compute has been invoked + + .. versionadded:: 4Feb2025 + + :to: :cpp:func:`lammps_clearstep_compute` + +-------- + +.. f:subroutine:: addstep_compute(nextstep) + + Add timestep to list of future compute invocations + if the compute has been invoked on the current timestep + + .. versionadded:: 4Feb2025 + + overloaded for 32-bit and 64-bit integer arguments + + :p integer(kind=8 or kind=4) nextstep: next timestep + :to: :cpp:func:`lammps_addstep_compute` + +-------- + +.. f:subroutine:: addstep_compute_all(nextstep) + + Add timestep to list of future compute invocations + + .. versionadded:: 4Feb2025 + + overloaded for 32-bit and 64-bit integer arguments + + :p integer(kind=8 or kind=4) nextstep: next timestep + :to: :cpp:func:`lammps_addstep_compute_all` + +-------- + .. f:subroutine:: gather_atoms(name, count, data) This function calls :cpp:func:`lammps_gather_atoms` to gather the named diff --git a/doc/src/Howto_barostat.rst b/doc/src/Howto_barostat.rst index 0c25e2c53c..89ff4d183f 100644 --- a/doc/src/Howto_barostat.rst +++ b/doc/src/Howto_barostat.rst @@ -10,20 +10,21 @@ and/or pressure (P) is specified by the user, and the thermostat or barostat attempts to equilibrate the system to the requested T and/or P. -Barostatting in LAMMPS is performed by :doc:`fixes `. Two +Barostatting in LAMMPS is performed by :doc:`fixes `. Three barostatting methods are currently available: Nose-Hoover (npt and -nph) and Berendsen: +nph), Berendsen, and various linear controllers in deform/pressure: * :doc:`fix npt ` * :doc:`fix npt/sphere ` * :doc:`fix npt/asphere ` * :doc:`fix nph ` * :doc:`fix press/berendsen ` +* :doc:`fix deform/pressure ` The :doc:`fix npt ` commands include a Nose-Hoover thermostat and barostat. :doc:`Fix nph ` is just a Nose/Hoover barostat; -it does no thermostatting. Both :doc:`fix nph ` and :doc:`fix press/berendsen ` can be used in conjunction -with any of the thermostatting fixes. +it does no thermostatting. The fixes :doc:`nph `, :doc:`press/berendsen `, and :doc:`deform/pressure ` +can be used in conjunction with any of the thermostatting fixes. As with the :doc:`thermostats `, :doc:`fix npt ` and :doc:`fix nph ` only use translational motion of the @@ -44,9 +45,9 @@ a temperature or pressure compute to a barostatting fix. .. note:: As with the thermostats, the Nose/Hoover methods (:doc:`fix npt ` and :doc:`fix nph `) perform time integration. - :doc:`Fix press/berendsen ` does NOT, so it should - be used with one of the constant NVE fixes or with one of the NVT - fixes. + :doc:`Fix press/berendsen ` and :doc:`fix deform/pressure ` + do NOT, so they should be used with one of the constant NVE fixes or with + one of the NVT fixes. Thermodynamic output, which can be setup via the :doc:`thermo_style ` command, often includes pressure diff --git a/doc/src/Install_git.rst b/doc/src/Install_git.rst index 5108009a73..d01bc6a4c5 100644 --- a/doc/src/Install_git.rst +++ b/doc/src/Install_git.rst @@ -52,6 +52,7 @@ your machine and "release" is one of the 3 branches listed above. between them at any time using "git checkout ".) .. admonition:: Saving time and disk space when using ``git clone`` + :class: note The complete git history of the LAMMPS project is quite large because it contains the entire commit history of the project since fall 2006, diff --git a/doc/src/Library_objects.rst b/doc/src/Library_objects.rst index 53edfce9e6..86b6d253f0 100644 --- a/doc/src/Library_objects.rst +++ b/doc/src/Library_objects.rst @@ -13,6 +13,9 @@ fixes, or variables in LAMMPS using the following functions: - :cpp:func:`lammps_set_internal_variable` - :cpp:func:`lammps_variable_info` - :cpp:func:`lammps_eval` +- :cpp:func:`lammps_clearstep_compute` +- :cpp:func:`lammps_addstep_compute_all` +- :cpp:func:`lammps_addstep_compute` ----------------------- @@ -61,6 +64,21 @@ fixes, or variables in LAMMPS using the following functions: ----------------------- +.. doxygenfunction:: lammps_clearstep_compute + :project: progguide + +----------------------- + +.. doxygenfunction:: lammps_addstep_compute_all + :project: progguide + +----------------------- + +.. doxygenfunction:: lammps_addstep_compute + :project: progguide + +----------------------- + .. doxygenenum:: _LMP_DATATYPE_CONST .. doxygenenum:: _LMP_STYLE_CONST diff --git a/doc/src/Modify_compute.rst b/doc/src/Modify_compute.rst index bf580a6561..ea603985dd 100644 --- a/doc/src/Modify_compute.rst +++ b/doc/src/Modify_compute.rst @@ -45,6 +45,8 @@ class. See compute.h for details. +-----------------------+------------------------------------------------------------------+ | pair_tally_callback | callback function for *tally*\ -style computes (optional). | +-----------------------+------------------------------------------------------------------+ +| modify_param | called when a compute_modify request is executed (optional) | ++-----------------------+------------------------------------------------------------------+ | memory_usage | tally memory usage (optional) | +-----------------------+------------------------------------------------------------------+ diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst index 894c299299..baefee0185 100644 --- a/doc/src/Packages_details.rst +++ b/doc/src/Packages_details.rst @@ -994,6 +994,7 @@ Additional pair styles that are less commonly used. * ``src/EXTRA-PAIR``: filenames -> commands * :doc:`pair_style ` +* ``examples/PACKAGES/dispersion`` ---------- diff --git a/doc/src/Run_output.rst b/doc/src/Run_output.rst index 2025bf5321..bf8e2de407 100644 --- a/doc/src/Run_output.rst +++ b/doc/src/Run_output.rst @@ -117,14 +117,19 @@ number of histogram counts is equal to the number of processors. ---------- -The last section gives aggregate statistics (across all processors) -for pairwise neighbors and special neighbors that LAMMPS keeps track -of (see the :doc:`special_bonds ` command). The number -of times neighbor lists were rebuilt is tallied, as is the number of -potentially *dangerous* rebuilds. If atom movement triggered neighbor -list rebuilding (see the :doc:`neigh_modify ` command), -then dangerous reneighborings are those that were triggered on the -first timestep atom movement was checked for. If this count is +The last section gives aggregate statistics (across all processors) for +pairwise neighbors and special neighbors that LAMMPS keeps track of (see +the :doc:`special_bonds ` command). This section will +not always contain data, for example when there has not been a neighbor +rebuild, or the neighbor list was constructed on the GPU or when a +hybrid pair style was used and LAMMPS cannot determine a suitable (base) +neighbor list to draw the statistics from. + +The number of times neighbor lists were rebuilt is tallied, as is the +number of potentially *dangerous* rebuilds. If atom movement triggered +neighbor list rebuilding (see the :doc:`neigh_modify ` +command), then dangerous reneighborings are those that were triggered on +the first timestep atom movement was checked for. If this count is non-zero you may wish to reduce the delay factor to ensure no force interactions are missed by atoms moving beyond the neighbor skin distance before a rebuild takes place. @@ -178,3 +183,64 @@ with and without the communication and a Gflop rate is computed. The 3d rate is with communication; the 1d rate is without (just the 1d FFTs). Thus you can estimate what fraction of your FFT time was spent in communication, roughly 75% in the example above. + +Error message output +==================== + +Depending on the error function arguments when it is called in the +source code, there will be one to four lines of error output. + +A single line +^^^^^^^^^^^^^ + +The line starts with "ERROR: ", followed by the error message and +information about the location in the source where the error function +was called in parenthesis on the right (here: line 131 of the file +src/fix_print.cpp). Example: + +.. parsed-literal:: + + ERROR: Fix print timestep variable nevery returned a bad timestep: 9900 (src/fix_print.cpp:131) + +Two lines +^^^^^^^^^ + +In addition to the single line output, also the last line of the input +will be repeated. If a command is spread over multiple lines in the +input using the continuation character '&', then the error will print +the entire concatenated line. For readability all whitespace is +compressed to single blanks. Example: + +.. parsed-literal:: + + ERROR: Unrecognized fix style 'printf' (src/modify.cpp:924) + Last input line: fix 0 all printf v_nevery "Step: $(step) ${step}" + +Three lines +^^^^^^^^^^^ + +In addition to the two line output from above, a third line is added +that uses caret character markers '^' to indicate which "word" in the +input failed. Example: + +.. parsed-literal:: + + ERROR: Illegal fix print nevery value -100; must be > 0 (src/fix_print.cpp:41) + Last input line: fix 0 all print -100 "Step: $(step) ${stepx}" + ^^^^ + +Four lines +^^^^^^^^^^ + +The three line output is expanded to four lines, if the the input is +modified through input pre-processing, e.g. when substituting +variables. Now the last command is printed once in the original form and +a second time after substitutions are applied. The caret character +markers '^' are applied to the second version. Example: + +.. parsed-literal:: + + ERROR: Illegal fix print nevery value -100; must be > 0 (src/fix_print.cpp:41) + Last input line: fix 0 all print ${nevery} 'Step: $(step) ${step}' + --> parsed line: fix 0 all print -100 "Step: $(step) ${step}" + ^^^^ diff --git a/doc/src/Speed_kokkos.rst b/doc/src/Speed_kokkos.rst index 9f8dcf8340..f8379949a4 100644 --- a/doc/src/Speed_kokkos.rst +++ b/doc/src/Speed_kokkos.rst @@ -67,6 +67,14 @@ version 23 November 2023 and Kokkos version 4.2. To build with Kokkos support for AMD GPUs, the AMD ROCm toolkit software version 5.2.0 or later must be installed on your system. +.. admonition:: Intel Data Center GPU support + :class: note + + Support for Kokkos with Intel Data Center GPU accelerators (formerly + known under the code name "Ponte Vecchio") in LAMMPS is still a work + in progress. Only a subset of the functionality works correctly. + Please contact the LAMMPS developers if you run into problems. + .. admonition:: CUDA and MPI library compatibility :class: note @@ -80,13 +88,15 @@ version 23 November 2023 and Kokkos version 4.2. LAMMPS command-line or by using the command :doc:`package kokkos gpu/aware off ` in the input file. -.. admonition:: Intel Data Center GPU support +.. admonition:: Using multiple MPI ranks per GPU :class: note - Support for Kokkos with Intel Data Center GPU accelerators (formerly - known under the code name "Ponte Vecchio") in LAMMPS is still a work - in progress. Only a subset of the functionality works correctly. - Please contact the LAMMPS developers if you run into problems. + Unlike with the GPU package, there are limited benefits from using + multiple MPI processes per GPU with KOKKOS. But when doing this it + is **required** to enable CUDA MPS (`Multi-Process Service :: GPU + Deployment and Management Documentation + `_ ) to get acceptable + performance. Building LAMMPS with the KOKKOS package """"""""""""""""""""""""""""""""""""""" @@ -365,13 +375,13 @@ one or more nodes, each with two GPUs: .. note:: - When using a GPU, you will achieve the best performance if your - input script does not use fix or compute styles which are not yet + When using a GPU, you will achieve the best performance if your input + script does not use fix or compute styles which are not yet Kokkos-enabled. This allows data to stay on the GPU for multiple timesteps, without being copied back to the host CPU. Invoking a - non-Kokkos fix or compute, or performing I/O for - :doc:`thermo ` or :doc:`dump ` output will cause data - to be copied back to the CPU incurring a performance penalty. + non-Kokkos fix or compute, or performing I/O for :doc:`thermo + ` or :doc:`dump ` output will cause data to be + copied back to the CPU incurring a performance penalty. .. note:: @@ -379,6 +389,56 @@ one or more nodes, each with two GPUs: kspace, etc., you must set the environment variable ``CUDA_LAUNCH_BLOCKING=1``. However, this will reduce performance and is not recommended for production runs. +Troubleshooting segmentation faults on GPUs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As noted above, KOKKOS by default assumes that the MPI library is +GPU-aware. This is not always the case and can lead to segmentation +faults when using more than one MPI process. Normally, LAMMPS will +print a warning like "*Turning off GPU-aware MPI since it is not +detected*", or an error message like "*Kokkos with GPU-enabled backend +assumes GPU-aware MPI is available*", OR a **segmentation fault**. To +confirm that a segmentation fault is caused by this, you can turn off +the GPU-aware assumption via the :doc:`package kokkos command ` +or the corresponding command-line flag. + +If you still get a segmentation fault, despite running with only one MPI +process or using the command-line flag to turn off expecting a GPU-aware +MPI library, then using the CMake compile setting +``-DKokkos_ENABLE_DEBUG=on`` or adding ``KOKKOS_DEBUG=yes`` to your +machine makefile for building with traditional make will generate useful +output that can be passed to the LAMMPS developers for further +debugging. + +Troubleshooting memory allocation on GPUs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`Kokkos Tools `_ provides a set +of lightweight profiling and debugging utilities, which interface with +instrumentation hooks (eg. `space-time-stack +`_) +built directly into the Kokkos runtime. After compiling a dynamic LAMMPS +library, you then have to set the environment variable ``KOKKOS_TOOLS_LIBS`` +before executing your LAMMPS Kokkos run. Example: + +.. code-block:: bash + + export KOKKOS_TOOLS_LIBS=${HOME}/kokkos-tools/src/tools/memory-events/kp_memory_event.so + mpirun -np 4 lmp_kokkos_cuda_openmpi -in in.lj -k on g 4 -sf kk + +Starting with the NVIDIA Pascal GPU architecture, CUDA supports +`"Unified Virtual Memory" (UVM) +`_ +which enables allocating more memory than a GPU possesses by also using +memory on the host CPU and then CUDA will transparently move data +between CPU and GPU as needed. The resulting LAMMPS performance depends +on `memory access pattern, data residency, and GPU memory +oversubscription +`_ +. The CMake option ``-DKokkos_ENABLE_CUDA_UVM=on`` or the makefile +setting ``KOKKOS_CUDA_OPTIONS=enable_lambda,force_uvm`` enables using +:ref:`UVM with Kokkos ` when compiling LAMMPS. + Run with the KOKKOS package by editing an input script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/src/angle_mwlc.rst b/doc/src/angle_mwlc.rst index 9fa4171a63..587afb8009 100644 --- a/doc/src/angle_mwlc.rst +++ b/doc/src/angle_mwlc.rst @@ -21,7 +21,7 @@ Examples Description """"""""""" -.. versionadded:: TBD +.. versionadded:: 4Feb2025 The *mwlc* angle style models a meltable wormlike chain and can be used to model non-linear bending elasticity of polymers, e.g. DNA. *mwlc* diff --git a/doc/src/bond_bpm_spring.rst b/doc/src/bond_bpm_spring.rst index 0a43a62159..88d63c901d 100644 --- a/doc/src/bond_bpm_spring.rst +++ b/doc/src/bond_bpm_spring.rst @@ -123,7 +123,7 @@ heuristic maximum strain used by typical non-bpm bond styles. Similar behavior to *break no* can also be attained by setting an arbitrarily high value of :math:`\epsilon_c`. One cannot use *break no* with *smooth yes*. -.. versionadded:: TBD +.. versionadded:: 4Feb2025 The *volume/factor* keyword toggles whether an additional multibody contribution is added to he force using the formulation in diff --git a/doc/src/comm_modify.rst b/doc/src/comm_modify.rst index c416ca21ea..f7c5c17159 100644 --- a/doc/src/comm_modify.rst +++ b/doc/src/comm_modify.rst @@ -15,15 +15,12 @@ Syntax .. parsed-literal:: - *mode* value = *single*, *multi*, or *multi/old* = communicate atoms within a single or multiple distances + *mode* value = *single* or *multi* = communicate atoms within a single or multiple distances *cutoff* value = Rcut (distance units) = communicate atoms from this far away *cutoff/multi* collection value collection = atom collection or collection range (supports asterisk notation) value = Rcut (distance units) = communicate atoms for selected types from this far away *reduce/multi* arg = none = reduce number of communicated ghost atoms for multi style - *cutoff/multi/old* type value - type = atom type or type range (supports asterisk notation) - value = Rcut (distance units) = communicate atoms for selected types from this far away *group* value = group-ID = only communicate atoms in the group *vel* value = *yes* or *no* = do or do not communicate velocity info with ghost atoms @@ -66,19 +63,16 @@ subdomain. The distance is by default the maximum of the neighbor cutoff across all atom type pairs. 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 -are grouped by atom type. See the :doc:`neighbor multi ` and -:doc:`neighbor multi/old ` commands for +widely varying cutoffs for different type pairs, the *multi* 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. See the :doc:`neighbor multi ` command for neighbor list construction options that may also be beneficial for -simulations of this kind. The *multi* communication mode is only compatible -with the *multi* neighbor style. The *multi/old* communication mode is comparable -with both the *multi* and *multi/old* neighbor styles. +simulations of this kind. The *multi* communication mode is only +compatible with the *multi* neighbor style. The *cutoff* keyword allows you to extend the ghost cutoff distance for communication mode *single*, which is the distance from the borders @@ -108,14 +102,12 @@ simulation to account for potential changes in the number of collections. Custom cutoffs are preserved between runs but if collections are redefined, one may want to re-specify the communication cutoffs. For granular pair styles,the default cutoff is set to the sum -of the current maximum atomic radii for each collection. The -*cutoff/multi/old* option is similar to *cutoff/multi* except it -operates on atom types as opposed to collections. +of the current maximum atomic radii for each collection. The *reduce/multi* option applies to *multi* and sets the communication -cutoff for a particle equal to the maximum interaction distance between particles -in the same collection. This reduces the number of -ghost atoms that need to be communicated. This method is only compatible with the +cutoff for a particle equal to the maximum interaction distance between +particles in the same collection. This reduces the number of ghost atoms +that need to be communicated. This method is only compatible with the *multi* neighbor style and requires a half neighbor list and Newton on. See the :doc:`neighbor multi ` command for more information. diff --git a/doc/src/commands_list.rst b/doc/src/commands_list.rst index dc5731f579..acfdfd9df0 100644 --- a/doc/src/commands_list.rst +++ b/doc/src/commands_list.rst @@ -82,6 +82,7 @@ Commands read_dump read_restart region + region2vmd replicate rerun reset_atoms diff --git a/doc/src/compute.rst b/doc/src/compute.rst index 082f93a6c4..9a8a1734fb 100644 --- a/doc/src/compute.rst +++ b/doc/src/compute.rst @@ -236,6 +236,7 @@ The individual style names on the :doc:`Commands compute ` pag * :doc:`fep/ta ` - compute free energies for a test area perturbation * :doc:`force/tally ` - force between two groups of atoms via the tally callback mechanism * :doc:`fragment/atom ` - fragment ID for each atom +* :doc:`gaussian/grid/local ` - local array of Gaussian atomic contributions on a regular grid * :doc:`global/atom ` - assign global values to each atom from arrays of global values * :doc:`group/group ` - energy/force between two groups of atoms * :doc:`gyration ` - radius of gyration of group of atoms diff --git a/doc/src/compute_gaussian_grid_local.rst b/doc/src/compute_gaussian_grid_local.rst new file mode 100644 index 0000000000..37dc0954f7 --- /dev/null +++ b/doc/src/compute_gaussian_grid_local.rst @@ -0,0 +1,99 @@ +.. index:: compute gaussian/grid/local +.. index:: compute gaussian/grid/local/kk + +compute gaussian/grid/local command +=================================== + +Accelerator Variants: *gaussian/grid/local/kk* + +Syntax +"""""" + +.. code-block:: LAMMPS + + compute ID group-ID gaussian/grid/local grid nx ny nz rcutfac R_1 R_2 ... sigma_1 sigma_2 + +* ID, group-ID are documented in :doc:`compute ` command +* gaussian/grid/local = style name of this compute command +* *grid* values = nx, ny, nz, number of grid points in x, y, and z directions (positive integer) +* *rcutfac* = scale factor applied to all cutoff radii (positive real) +* *R_1, R_2,...* = list of cutoff radii, one for each type (distance units) +* *sigma_1, sigma_2,...* = Gaussian widths, one for each type (distance units) + +Examples +"""""""" + +.. code-block:: LAMMPS + + compute mygrid all gaussian/grid/local grid 40 40 40 4.0 0.5 0.5 0.4 0.4 + +Description +""""""""""" + +.. versionadded:: 4Feb2025 + +Define a computation that calculates a Gaussian representation of the ionic +structure. This representation is used for the efficient evaluation +of quantities related to the structure factor in a grid-based workflow, +such as the ML-DFT workflow MALA :ref:`(Ellis) `, for which it was originally +implemented. Usage of the workflow is described in a separate publication :ref:`(Fiedler) `. + +For each LAMMPS type, a separate sum of Gaussians is calculated, using +a separate Gaussian broadening per type. The computation +is always performed on the numerical grid, no atom-based version of this +compute exists. The Gaussian representation can only be executed in a local +fashion, thus the output array only contains rows for grid points +that are local to the processor subdomain. The layout of the grid is the same +as for the see :doc:`sna/grid/local ` command. + +Namely, the array contains one row for each of the +local grid points, looping over the global index *ix* fastest, +then *iy*, and *iz* slowest. Each row of the array contains +the global indexes *ix*, *iy*, and *iz* first, followed by the *x*, *y*, +and *z* coordinates of the grid point, followed by the values of the Gaussians +(one floating point number per type per grid point). + +---------- + + +.. include:: accel_styles.rst + + + +---------- + +Output info +""""""""""" + +Compute *gaussian/grid/local* evaluates a local array. +The array contains one row for each of the +local grid points, looping over the global index *ix* fastest, +then *iy*, and *iz* slowest. The array contains math :math:`ntypes+6` columns, +where *ntypes* is the number of LAMMPS types. The first three columns are +the global indexes *ix*, *iy*, and *iz*, followed by the *x*, *y*, +and *z* coordinates of the grid point, followed by the *ntypes* columns +containing the values of the Gaussians for each type. + +Restrictions +"""""""""""" + +These computes are part of the ML-SNAP package. They are only enabled +if LAMMPS was built with that package. See the :doc:`Build package +` page for more info. + +Related commands +"""""""""""""""" + +:doc:`compute sna/grid/local ` + +---------- + +.. _Ellis2021b: + +**(Ellis)** Ellis, Fiedler, Popoola, Modine, Stephens, Thompson, Cangi, Rajamanickam, `Phys. Rev. B, 104, 035120, (2021) `_ + +.. _Fiedler2023: + +**(Fiedler)** Fiedler, Modine, Schmerler, Vogel, Popoola, Thompson, Rajamanickam, and Cangi, +`npj Comp. Mater., 9, 115 (2023) `_ + diff --git a/doc/src/compute_sna_atom.rst b/doc/src/compute_sna_atom.rst index 179c362dc6..2572093499 100644 --- a/doc/src/compute_sna_atom.rst +++ b/doc/src/compute_sna_atom.rst @@ -3,7 +3,9 @@ .. index:: compute snav/atom .. index:: compute snap .. index:: compute sna/grid +.. index:: compute sna/grid/kk .. index:: compute sna/grid/local +.. index:: compute sna/grid/local/kk compute sna/atom command ======================== @@ -20,9 +22,14 @@ compute snap command compute sna/grid command ======================== +compute sna/grid/kk command +=========================== + compute sna/grid/local command ============================== +Accelerator Variants: *sna/grid/local/kk* + Syntax """""" @@ -33,17 +40,17 @@ Syntax compute ID group-ID snav/atom rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... compute ID group-ID snap rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... compute ID group-ID snap rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... - compute ID group-ID sna/grid nx ny nz rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... - compute ID group-ID sna/grid/local nx ny nz rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... + compute ID group-ID sna/grid grid nx ny nz rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... + compute ID group-ID sna/grid/local grid nx ny nz rcutfac rfac0 twojmax R_1 R_2 ... w_1 w_2 ... keyword values ... * ID, group-ID are documented in :doc:`compute ` command * sna/atom = style name of this compute command -* rcutfac = scale factor applied to all cutoff radii (positive real) -* rfac0 = parameter in distance to angle conversion (0 < rcutfac < 1) -* twojmax = band limit for bispectrum components (non-negative integer) -* R_1, R_2,... = list of cutoff radii, one for each type (distance units) -* w_1, w_2,... = list of neighbor weights, one for each type -* nx, ny, nz = number of grid points in x, y, and z directions (positive integer) +* *rcutfac* = scale factor applied to all cutoff radii (positive real) +* *rfac0* = parameter in distance to angle conversion (0 < rcutfac < 1) +* *twojmax* = band limit for bispectrum components (non-negative integer) +* *R_1, R_2,...* = list of cutoff radii, one for each type (distance units) +* *w_1, w_2,...* = list of neighbor weights, one for each type +* *grid* values = nx, ny, nz, number of grid points in x, y, and z directions (positive integer) * zero or more keyword/value pairs may be appended * keyword = *rmin0* or *switchflag* or *bzeroflag* or *quadraticflag* or *chem* or *bnormflag* or *wselfallflag* or *bikflag* or *switchinnerflag* or *sinner* or *dinner* or *dgradflag* or *nnn* or *wmode* or *delta* @@ -103,7 +110,7 @@ Examples compute snap all snap 1.4 0.95 6 2.0 1.0 compute snap all snap 1.0 0.99363 6 3.81 3.83 1.0 0.93 chem 2 0 1 compute snap all snap 1.0 0.99363 6 3.81 3.83 1.0 0.93 switchinnerflag 1 sinner 1.35 1.6 dinner 0.25 0.3 - compute bgrid all sna/grid/local 200 200 200 1.4 0.95 6 2.0 1.0 + compute bgrid all sna/grid/local grid 200 200 200 1.4 0.95 6 2.0 1.0 compute bnnn all sna/atom 9.0 0.99363 8 0.5 1.0 rmin0 0.0 nnn 24 wmode 1 delta 0.2 Description @@ -252,7 +259,8 @@ for finite-temperature Kohn-Sham density functional theory (:ref:`Ellis et al. `) Neighbor atoms not in the group do not contribute to the bispectrum components of the grid points. The distance cutoff :math:`R_{ii'}` assumes that *i* has the same type as the neighbor atom -*i'*. +*i'*. Both computes can be hardware accelerated with Kokkos by using the +*sna/grid/kk* and *sna/grid/local/kk* commands, respectively. Compute *sna/grid* calculates a global array containing bispectrum components for a regular grid of points. @@ -463,6 +471,12 @@ fluctuations in the resulting local atomic environment fingerprint. The detailed formalism is given in the paper by Lafourcade et al. :ref:`(Lafourcade) `. +---------- + + +.. include:: accel_styles.rst + + ---------- Output info @@ -654,7 +668,7 @@ of Angular Momentum, World Scientific, Singapore (1987). .. _Ellis2021: -**(Ellis)** Ellis, Fiedler, Popoola, Modine, Stephens, Thompson, Cangi, Rajamanickam, Phys Rev B, 104, 035120, (2021) +**(Ellis)** Ellis, Fiedler, Popoola, Modine, Stephens, Thompson, Cangi, Rajamanickam, `Phys. Rev. B, 104, 035120, (2021) `_ .. _Lafourcade2023_2: diff --git a/doc/src/delete_bonds.rst b/doc/src/delete_bonds.rst index e03c4b3ac7..e6825ded33 100644 --- a/doc/src/delete_bonds.rst +++ b/doc/src/delete_bonds.rst @@ -62,6 +62,18 @@ For all styles, by default, an interaction is only turned off (or on) if all the atoms involved are in the specified group. See the *any* keyword to change the behavior. +.. admonition:: Possible errors caused by using *delete_bonds* + :class: warning + + Since this command by default only *turns off* bonded interactions, + their definitions are still present and subject to the limitations + due to LAMMPS' domain decomposition based parallelization. That is, + when a bond is turned off, the two constituent atoms may move apart + and may reach a distance where they can lead to a "bond atoms missing" + error and crash the simulation. Adding the *remove* keyword (see + below) is required to fully remove those interactions and prevent + the error. + Several of the styles (\ *atom*, *bond*, *angle*, *dihedral*, *improper*\ ) take a *type* as an argument. The specified *type* can be a :doc:`type label `. Otherwise, the type should be an @@ -98,15 +110,18 @@ of all interactions in the specified group is simply reported. This is useful for diagnostic purposes if bonds have been turned off by a bond-breaking potential during a previous run. -The default behavior of the delete_bonds command is to turn off -interactions by toggling their type to a negative value, but not to -permanently remove the interaction. For example, a bond_type of 2 is set to -:math:`-2.` The neighbor list creation routines will not include such an -interaction in their interaction lists. The default is also to not -alter the list of 1--2, 1--3, or 1--4 neighbors computed by the -:doc:`special_bonds ` command and used to weight pairwise -force and energy calculations. This means that pairwise computations -will proceed as if the bond (or angle, etc.) were still turned on. +.. admonition:: Impact on special_bonds processing and exclusions + :class: note + + The default behavior of the delete_bonds command is to turn off + interactions by toggling their type to a negative value, but not to + permanently remove the interaction. For example, a bond_type of 2 is set to + :math:`-2.` The neighbor list creation routines will not include such an + interaction in their interaction lists. The default is also to not + alter the list of 1--2, 1--3, or 1--4 neighbors computed by the + :doc:`special_bonds ` command and used to weight pairwise + force and energy calculations. This means that pairwise computations + will proceed as if the bond (or angle, etc.) were still turned on. Several keywords can be appended to the argument list to alter the default behaviors. @@ -138,9 +153,11 @@ operation, after (optional) removal. It re-computes the pairwise 1--2, turned-off bonds the same as turned-on. Thus, turned-off bonds must be removed if you wish to change the weighting list. -Note that the choice of *remove* and *special* options affects how -1--2, 1--3, 1--4 pairwise interactions will be computed across bonds that -have been modified by the delete_bonds command. +.. note:: + + The choice of *remove* and *special* options affects how 1--2, + 1--3, 1--4 pairwise interactions will be computed across bonds + that have been modified by the delete_bonds command. Restrictions """""""""""" diff --git a/doc/src/fix.rst b/doc/src/fix.rst index 9af607601b..49fbb72726 100644 --- a/doc/src/fix.rst +++ b/doc/src/fix.rst @@ -237,6 +237,7 @@ accelerated styles exist. * :doc:`dt/reset ` - reset the timestep based on velocity, forces * :doc:`edpd/source ` - add heat source to eDPD simulations * :doc:`efield ` - impose electric field on system +* :doc:`efield/lepton ` - impose electric field on system using a Lepton expression for the potential * :doc:`efield/tip4p ` - impose electric field on system with TIP4P molecules * :doc:`ehex ` - enhanced heat exchange algorithm * :doc:`electrode/conp ` - impose electric potential diff --git a/doc/src/fix_efield.rst b/doc/src/fix_efield.rst index a870590856..ecdb25fca5 100644 --- a/doc/src/fix_efield.rst +++ b/doc/src/fix_efield.rst @@ -45,8 +45,9 @@ Description Add a force :math:`\vec{F} = q\vec{E}` to each charged atom in the group due to an 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. +contains point-dipoles, also add a torque :math:`\vec{T} = \vec{p} \times \vec{E}` on the dipoles due to the +external electric field. This fix does not compute the dipole force :math:`\vec{F} = (\vec{p} \cdot \nabla) \vec{E}`, +and the :doc:`fix efield/lepton ` command should be used instead. .. versionadded:: 28Mar2023 @@ -68,6 +69,7 @@ For point-dipoles, equal-style variables can be used, but atom-style variables are not currently supported, since they imply a spatial gradient in the electric field which means additional terms with gradients of the field are required for the force and torque on dipoles. +The :doc:`fix efield/lepton ` command should be used instead. Equal-style variables can specify formulas with various mathematical functions, and include :doc:`thermo_style ` command @@ -229,7 +231,7 @@ Fix style *efield/tip4p* can only be used with tip4p pair styles. Related commands """""""""""""""" -:doc:`fix addforce ` +:doc:`fix addforce `, :doc:`fix efield/lepton ` Default """"""" diff --git a/doc/src/fix_efield_lepton.rst b/doc/src/fix_efield_lepton.rst new file mode 100644 index 0000000000..84fdd2f83f --- /dev/null +++ b/doc/src/fix_efield_lepton.rst @@ -0,0 +1,143 @@ +.. index:: fix efield/lepton + +fix efield/lepton command +========================= + +Syntax +"""""" + +.. code-block:: LAMMPS + + fix ID group-ID efield/lepton V ... + +* ID, group-ID are documented in the :doc:`fix ` command +* style = *efield/lepton* +* V = electric potential (electric field * distance units) +* V must be a Lepton expression (see below) +* zero or more keyword/value pairs may be appended to args +* keyword = *region* or *step* + + .. parsed-literal:: + + *region* value = region-ID + region-ID = ID of region atoms must be in to have effect + *step* value = h + h = step size for numerical differentiation (distance units) + +Examples +"""""""" + +.. code-block:: LAMMPS + + fix ex all efield/lepton "-E*x; E=1" + fix dexx all efield/lepton "-0.5*x^2" step 1 + fix yukawa all efield/lepton "A*exp(-B*r)/r; r=abs(sqrt(x^2+y^2+z^2)); A=1; B=1" step 1e-6 + fix infp all efield/lepton "-abs(x)" step 1 + + variable th equal 2*PI*ramp(0,1) + fix erot all efield/lepton "-(x*cos(v_th)+y*sin(v_th))" + +Description +""""""""""" + +.. versionadded:: 4Feb2025 + +Add an electric potential :math:`V` that applies to a group of charged atoms a force :math:`\vec{F} = q \vec{E}`, +and to dipoles a force :math:`\vec{F} = (\vec{p} \cdot \nabla) \vec{E}` and torque :math:`\vec{T} = \vec{p} \times \vec{E}`, +where :math:`\vec{E} = - \nabla V`. The fix also evaluates the electrostatic energy (:math:`U_{q} = q V` and :math:`U_{p} = - \vec{p} \cdot \vec{E}`) +due to this potential when the :doc:`fix_modify energy yes ` command is specified (see below). + +.. note:: + + This command should be used instead of :doc:`fix efield ` if you want to impose a non-uniform electric field on a system with dipoles + since the latter does not include the dipole force term. If you only have charges or if the electric field gradient is negligible, + :doc:`fix efield ` should be used since it is faster. + +The `Lepton library `_, that the *efield/lepton* fix style interfaces with, evaluates +the expression string at run time to compute the energy, forces, and torques. It creates an analytical representation +of :math:`V` and :math:`\vec{E}`, while the gradient force is computed using a central difference scheme + +.. math:: + + \vec{F} = \frac{|\vec{p}|}{2h} \left[ \vec{E}(\vec{x} + h \hat{p}) - \vec{E}(\vec{x} - h \hat{p}) \right] . + +The Lepton expression must be either enclosed in quotes or must not contain any whitespace so that LAMMPS +recognizes it as a single keyword. More on valid Lepton expressions below. The final Lepton expression must +be a function of only :math:`x, y, z`, which refer to the current *unwrapped* coordinates of the atoms to ensure continuity. +Special care must be taken when using this fix with periodic boundary conditions or box-changing commands. + +---------- + +.. include:: lepton_expression.rst + +---------- + +If the *region* keyword is used, the atom must also be in the specified +geometric :doc:`region ` in order to be affected by the potential. + +The *step* keyword is required when :doc:`atom_style dipole ` is used and the electric field is non-uniform. + +---------- + +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 defined above 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 no `. + +The :doc:`fix_modify ` *virial* option is supported by this +fix to add the contribution due to the added ***forces*** on charges and dipoles +to both the global pressure and per-atom stress of the system via the +:doc:`compute pressure ` and :doc:`compute stress/atom +` commands. The former can be accessed by +:doc:`thermodynamic output `. The default setting for +this fix is :doc:`fix_modify virial no `. + +The :doc:`fix_modify ` *respa* option is supported by this +fix. This allows to set at which level of the :doc:`r-RESPA ` +integrator the fix adding its forces. Default is the outermost level. + +This fix computes a global scalar and a global 3-vector of forces, +which can be accessed by various :doc:`output commands `. +The scalar is the potential energy discussed above. +The vector is the total force added to the group of atoms. +The scalar and vector values calculated by this fix are "extensive". + +This fix cannot be used with the *start/stop* keywords of +the :doc:`run ` command. + +The forces due to this fix are imposed during an energy minimization, +invoked by the :doc:`minimize ` command. You should not +specify force components with a variable that has time-dependence for +use with a minimizer, since the minimizer increments the timestep as +the iteration count during the minimization. + +.. note:: + + If you want the electric potential energy to be included in the + total potential energy of the system (the quantity being minimized), + you MUST enable the :doc:`fix_modify ` *energy* option for this fix. + +---------- + +Restrictions +"""""""""""" + +Fix style *efield/lepton* is part of the LEPTON package. It is only enabled if LAMMPS was built with that package. +See the :doc:`Build package ` page for more info. + + +Related commands +"""""""""""""""" + +:doc:`fix efield ` + +Default +""""""" + +none diff --git a/doc/src/fix_imd.rst b/doc/src/fix_imd.rst index a4d7d9d387..d85ebc8d34 100644 --- a/doc/src/fix_imd.rst +++ b/doc/src/fix_imd.rst @@ -120,7 +120,7 @@ with different units or as a measure to tweak the forces generated by the manipulation of the IMD client, this option allows to make adjustments. -.. versionadded:: TBD +.. versionadded:: 4Feb2025 In `IMDv3 `_, the IMD protocol has been extended to allow for the transmission of simulation time, box dimensions, atomic coordinates, diff --git a/doc/src/fix_python_invoke.rst b/doc/src/fix_python_invoke.rst index ad55882270..4f33f5483b 100644 --- a/doc/src/fix_python_invoke.rst +++ b/doc/src/fix_python_invoke.rst @@ -66,6 +66,15 @@ gives access to the LAMMPS state from Python. from these callbacks, trying to execute input script commands will in the best case not work or in the worst case result in undefined behavior. +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 `. + Restrictions """""""""""" diff --git a/doc/src/fix_reaxff_species.rst b/doc/src/fix_reaxff_species.rst index 107695f0f6..068d1de995 100644 --- a/doc/src/fix_reaxff_species.rst +++ b/doc/src/fix_reaxff_species.rst @@ -200,8 +200,8 @@ The 2 values in the global vector are as follows: The per-atom vector stores the molecule ID for each atom as identified by the fix. If an atom is not in a molecule, its ID will be 0. For atoms in the same molecule, the molecule ID for all of them -will be the same and will be equal to the smallest atom ID of -any atom in the molecule. +will be the same, and molecule IDs will range from 1 to the number +of molecules. No parameter of this fix can be used with the *start/stop* keywords of the :doc:`run ` command. diff --git a/doc/src/fix_wall_gran.rst b/doc/src/fix_wall_gran.rst index 25d659241c..81a411ffc8 100644 --- a/doc/src/fix_wall_gran.rst +++ b/doc/src/fix_wall_gran.rst @@ -222,10 +222,10 @@ restart file, so that the operation of the fix continues in an uninterrupted fashion. If the :code:`contacts` option is used, this fix generates a per-atom array -with 8 columns as output, containing the contact information for owned +with at least 8 columns as output, containing the contact information for owned particles (nlocal on each processor). All columns in this per-atom array will -be zero if no contact has occurred. The values of these columns are listed in -the following table: +be zero if no contact has occurred. The first 8 values of these columns are +listed in the following table. +-------+----------------------------------------------------+----------------+ | Index | Value | Units | @@ -248,6 +248,14 @@ the following table: | 8 | Radius :math:`r` of atom | distance units | +-------+----------------------------------------------------+----------------+ +If a granular sub-model calculates additional contact information (e.g. the +heat sub-models calculate the amount of heat exchanged), these quantities +are appended to the end of this array. First, any extra values from the +normal sub-model are appended followed by the damping, tangential, rolling, +twisting, then heat models. See the descriptions of granular sub-models in +the :doc:`pair granular ` page for information on any extra +quantities. + 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 diff --git a/doc/src/fix_wall_gran_region.rst b/doc/src/fix_wall_gran_region.rst index 0a4343493b..4ad3b9d6c5 100644 --- a/doc/src/fix_wall_gran_region.rst +++ b/doc/src/fix_wall_gran_region.rst @@ -243,10 +243,10 @@ uninterrupted fashion. with a different region ID. If the :code:`contacts` option is used, this fix generates a per-atom array -with 8 columns as output, containing the contact information for owned +with at least 8 columns as output, containing the contact information for owned particles (nlocal on each processor). All columns in this per-atom array will -be zero if no contact has occurred. The values of these columns are listed in -the following table: +be zero if no contact has occurred. The first 8 values of these columns are +listed in the following table. +-------+----------------------------------------------------+----------------+ | Index | Value | Units | @@ -269,6 +269,14 @@ the following table: | 8 | Radius :math:`r` of atom | distance units | +-------+----------------------------------------------------+----------------+ +If a granular sub-model calculates additional contact information (e.g. the +heat sub-models calculate the amount of heat exchanged), these quantities +are appended to the end of this array. First, any extra values from the +normal sub-model are appended followed by the damping, tangential, rolling, +twisting, then heat models. See the descriptions of granular sub-models in +the :doc:`pair granular ` page for information on any extra +quantities. + 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 diff --git a/doc/src/kspace_modify.rst b/doc/src/kspace_modify.rst index c40ba70ef0..b300213a3b 100644 --- a/doc/src/kspace_modify.rst +++ b/doc/src/kspace_modify.rst @@ -412,11 +412,9 @@ slab correction has also been extended to point dipole interactions .. note:: If you wish to apply an electric field in the Z-direction, in - conjunction with the *slab* keyword, you should do it by adding - explicit charged particles to the +/- Z surfaces. If you do it via - the :doc:`fix efield ` command, it will not give the correct - dielectric constant due to the Yeh/Berkowitz :ref:`(Yeh) ` correction - not being compatible with how :doc:`fix efield ` works. + conjunction with the *slab* keyword, you can do it either by + adding explicit oppositely charged particles to the +/- Z surfaces, + or by using the :doc:`fix efield ` command. ---------- diff --git a/doc/src/min_modify.rst b/doc/src/min_modify.rst index f4a706e75c..d36f19b0d5 100644 --- a/doc/src/min_modify.rst +++ b/doc/src/min_modify.rst @@ -84,10 +84,10 @@ energy after) and that difference may be smaller than machine epsilon even if atoms could move in the gradient direction to reduce forces further. -The choice of a norm can be modified for the min styles *cg*, *sd*\ -, *quickmin*, *fire*, *fire/old*, *spin*, *spin/cg* and -*spin/lbfgs* using the *norm* keyword. The default *two* norm computes -the 2-norm (Euclidean length) of the global force vector: +The choice of a norm can be modified for the min styles *cg*, *sd*, +*quickmin*, *fire*, *spin*, *spin/cg*, and *spin/lbfgs* using the +*norm* keyword. The default *two* norm computes the 2-norm +(Euclidean length) of the global force vector: .. math:: || \vec{F} ||_{2} = \sqrt{\vec{F}_1^2+ \cdots + \vec{F}_N^2} @@ -160,9 +160,9 @@ that modifies the bias and scaling of the velocities of the atoms during the mixing step :ref:`(Echeverri Restrepo) `. This can lead to faster convergence of the minimizer. -The :doc:`min_style ` *fire* is an optimized implementation of -:doc:`min_style ` *fire/old*. It can however behave similarly -to the *fire/old* style by using the following set of parameters: +The :doc:`min_style ` *fire* is an optimized implementation. +It can behave similarly to the previous version by using the following +set of parameters: .. code-block:: LAMMPS diff --git a/doc/src/minimize.rst b/doc/src/minimize.rst index 56efa12f44..c201e53340 100644 --- a/doc/src/minimize.rst +++ b/doc/src/minimize.rst @@ -89,8 +89,8 @@ be more robust than previous line searches we have tried. The backtracking method is described in Nocedal and Wright's Numerical Optimization (Procedure 3.1 on p 41). -The :doc:`minimization styles ` *quickmin*, *fire* and -*fire/old* perform damped dynamics using an Euler integration step. Thus +The :doc:`minimization styles ` *quickmin* and *fire* +perform damped dynamics using an Euler integration step. Thus they require a :doc:`timestep ` be defined. .. note:: diff --git a/doc/src/neighbor.rst b/doc/src/neighbor.rst index 12d6d91fde..8ccd1fb50d 100644 --- a/doc/src/neighbor.rst +++ b/doc/src/neighbor.rst @@ -11,7 +11,7 @@ Syntax neighbor skin style * skin = extra distance beyond force cutoff (distance units) -* style = *bin* or *nsq* or *multi* or *multi/old* +* style = *bin* or *nsq* or *multi* Examples """""""" @@ -83,16 +83,6 @@ is customized or not, also see the :doc:`comm_modify mode multi ` command for communication options that further improve performance in a manner consistent with neighbor style multi. -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 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:: If there are multiple sub-styles in a :doc:`hybrid/overlay pair style diff --git a/doc/src/pair_bpm_spring.rst b/doc/src/pair_bpm_spring.rst index 068efff577..53375d86b8 100644 --- a/doc/src/pair_bpm_spring.rst +++ b/doc/src/pair_bpm_spring.rst @@ -85,7 +85,7 @@ commands, or by mixing as described below: * :math:`r_c` (distance units) * :math:`\gamma` (force/velocity units) -.. versionadded:: TBD +.. versionadded:: 4Feb2025 Additionally, if *anharmonic* is set to *yes*, a fourth coefficient must be provided: diff --git a/doc/src/pair_dispersion_d3.rst b/doc/src/pair_dispersion_d3.rst new file mode 100644 index 0000000000..d6a548e01f --- /dev/null +++ b/doc/src/pair_dispersion_d3.rst @@ -0,0 +1,158 @@ +.. index:: pair_style dispersion/d3 + +pair_style dispersion/d3 command +================================ + +Syntax +"""""" + +.. code-block:: LAMMPS + + pair_style dispersion/d3 damping functional cutoff cn_cutoff + +* damping = damping function: *zero*, *zerom*, *bj*, or *bjm* +* functional = XC functional form: *pbe*, *pbe0*, ... (see list below) +* cutoff = global cutoff (distance units) +* cn_cutoff = coordination number cutoff (distance units) + +Examples +"""""""" + +.. code-block:: LAMMPS + + pair_style dispersion/d3 zero pbe 30.0 20.0 + pair_coeff * * C + +Description +""""""""""" + +.. versionadded:: 4Feb2025 + +Style *dispersion/d3* computes the dispersion energy-correction used in +the DFT-D3 method of Grimme :ref:`(Grimme1) `. It would +typically be used with a machine learning (ML) potential that was +trained with results from plain DFT calculations without the dispersion +correction through pair_style hybrid/overlay. ML potentials are often +combined *a posteriori* with dispersion energy-correction schemes (see +*e.g.* :ref:`(Qamar) ` and :ref:`(Batatia) `). + +The energy contribution :math:`E_i` for an atom :math:`i` is given by: + +.. math:: + + E_i = \frac{1}{2} \sum_{j \neq i} \big( + s_6 \frac{C_{6,ij}}{r^6_{ij}} f_6^{damp}(r_{ij}) + + s_8 \frac{C_{8,ij}}{r^8_{ij}} f_8^{damp}(r_{ij}) \big) + +where :math:`C_n` is the averaged, geometry-dependent nth-order +dispersion coefficient for atom pair :math:`ij`, :math:`r_{ij}` their +inter-nuclear distance, :math:`s_n` are XC functional-dependent scaling +factor, and :math:`f_n^{damp}` are damping functions. + +.. note:: + + It is currently *not* possible to calculate three-body dispersion + contributions, according to, for example, the Axilrod-Teller-Muto + model. + +Available damping functions are the original "zero-damping" +:ref:`(Grimme1) `, Becke-Johnson damping :ref:`(Grimme2) +`, and their revised forms :ref:`(Sherrill) `. + +Available XC functional scaling factors are listed in the table below, +and depend on the selected damping function. + ++------------------+--------------------------------------------------------------------------------+ +| Damping function | XC functional | ++==================+================================================================================+ +| | | | slater-dirac-exchange, b-lyp, b-p, b97-d, revpbe, pbe, pbesol, rpw86-pbe, | +| | | | rpbe, tpss, b3-lyp, pbe0, hse06, revpbe38, pw6b95, tpss0, b2-plyp, pwpb95, | +| | zero | | b2gp-plyp, ptpss, hf, mpwlyp, bpbe, bh-lyp, tpssh, pwb6k, b1b95, bop, o-lyp, | +| | | | o-pbe, ssb, revssb, otpss, b3pw91, revpbe0, pbe38, mpw1b95, mpwb1k, bmk, | +| | | | cam-b3lyp, lc-wpbe, m05, m052x, m06l, m06, m062x, m06hf, hcth120 | ++------------------+--------------------------------------------------------------------------------+ +| zerom | b2-plyp, b3-lyp, b97-d, b-lyp, b-p, pbe, pbe0, lc-wpbe | ++------------------+--------------------------------------------------------------------------------+ +| | | | b-p, b-lyp, revpbe, rpbe, b97-d, pbe, rpw86-pbe, b3-lyp, tpss, hf, tpss0, | +| | | | pbe0, hse06, revpbe38, pw6b95, b2-plyp, dsd-blyp, dsd-blyp-fc, bop, mpwlyp, | +| | bj | | o-lyp, pbesol, bpbe, opbe, ssb, revssb, otpss, b3pw91, bh-lyp, revpbe0, | +| | | | tpssh, mpw1b95, pwb6k, b1b95, bmk, cam-b3lyp, lc-wpbe, b2gp-plyp, ptpss, | +| | | | pwpb95, hf/mixed, hf/sv, hf/minis, b3lyp/6-31gd, hcth120, pw1pw, pwgga, | +| | | | hsesol, hf3c, hf3cv, pbeh3c, pbeh-3c | ++------------------+--------------------------------------------------------------------------------+ +| bjm | b2-plyp, b3-lyp, b97-d, b-lyp, b-p, pbe, pbe0, lc-wpbe | ++------------------+--------------------------------------------------------------------------------+ + + +This style is primarily supposed to be used combined with a +machine-learned interatomic potential trained on a DFT dataset (the +selected XC functional should be chosen accordingly) via the +:doc:`pair_style hybrid ` command. + +Coefficients +"""""""""""" + +All the required coefficients are already stored internally (in the +``src/EXTRA-PAIR/d3_parameters.h`` file). The only information to +provide are the chemical symbols of the atoms. The number of chemical +symbols given must be equal to the number of atom types used and must +match their ordering as atom types. + + +Mixing, shift, table, tail correction, restart, rRESPA info +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +This pair style does not support mixing since all parameters are +explicit for each pair of atom types. + +This pair style does not support the :doc:`pair_modify` shift, table, +and tail options. + +This pair style does not write its information to :doc:`binary restart +files `. + +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 +"""""""""""" + +Style *dispersion/d3* is part of the EXTRA-PAIR package. It is only +enabled if LAMMPS was built with that package. See the :doc:`Build +package ` page for more info. + +It is currently *not* possible to calculate three-body dispersion +contributions according to, for example, the Axilrod-Teller-Muto model. + +Related commands +"""""""""""""""" + +:doc:`pair_coeff ` + +Default +""""""" + +none + +---------- + +.. _Grimme1: + +**(Grimme1)** S. Grimme, J. Antony, S. Ehrlich, and H. Krieg, J. Chem. Phys. 132, 154104 (2010). + +.. _Qamar: + +**(Qamar)** M. Qamar, M. Mrovec, T. Lysogorskiy, A. Bochkarev, and R. Drautz, J. Chem. Theory Comput. 19, 5151 (2023). + +.. _Batatia: + +**(Batatia)** I. Batatia, *et al.*, arXiv:2401.0096 (2023). + +.. _Grimme2: + +**(Grimme2)** S. Grimme, S. Ehrlich and L. Goerigk, J. Comput. Chem. 32, 1456 (2011). + +.. _Sherrill: + +**(Sherrill)** D. G. A. Smith, L. A. Burns, K. Patkowski, and C. D. Sherrill, J. Phys. Chem. Lett., 7, 2197, (2016). diff --git a/doc/src/pair_granular.rst b/doc/src/pair_granular.rst index 2ff1bde270..4ae59a587f 100644 --- a/doc/src/pair_granular.rst +++ b/doc/src/pair_granular.rst @@ -43,6 +43,9 @@ Examples pair_style granular pair_coeff * * hertz 1000.0 50.0 tangential mindlin 1000.0 1.0 0.4 heat area 0.1 + pair_style granular + pair_coeff * * mdr 5e6 0.4 1.9e5 2.0 0.5 0.5 tangential linear_history 940.0 0.0 0.7 rolling sds 2.7e5 0.0 0.6 damping none + Description """"""""""" @@ -85,6 +88,7 @@ and their required arguments are: 3. *hertz/material* : E, :math:`\eta_{n0}` (or :math:`e`), :math:`\nu` 4. *dmt* : E, :math:`\eta_{n0}` (or :math:`e`), :math:`\nu`, :math:`\gamma` 5. *jkr* : E, :math:`\eta_{n0}` (or :math:`e`), :math:`\nu`, :math:`\gamma` +6. *mdr* : :math:`E`, :math:`\nu`, :math:`Y`, :math:`\Delta\gamma`, :math:`\psi_b`, :math:`e` Here, :math:`k_n` is spring stiffness (with units that depend on model choice, see below); :math:`\eta_{n0}` is a damping prefactor (or, in its @@ -166,6 +170,144 @@ initially will not experience force until they come into contact experience a tensile force up to :math:`3\pi\gamma R`, at which point they lose contact. +The *mdr* model is a mechanically-derived contact model designed to capture the +contact response between adhesive elastic-plastic particles into large deformation. +The theoretical foundations of the *mdr* model are detailed in the +two-part series :ref:`Zunker and Kamrin Part I ` and +:ref:`Zunker and Kamrin Part II `. Further development +and demonstrations of its application to industrially relevant powder +compaction processes are presented in :ref:`Zunker et al. `. + +The model requires the following inputs: + + 1. *Young's modulus* :math:`E > 0` : The Young's modulus is commonly reported + for various powders. + + 2. *Poisson's ratio* :math:`0 \le \nu \le 0.5` : The Poisson's ratio is commonly + reported for various powders. + + 3. *Yield stress* :math:`Y \ge 0` : The yield stress is often known for powders + composed of materials such as metals but may be unreported for ductile organic + materials, in which case it can be treated as a free parameter. + + 4. *Effective surface energy* :math:`\Delta\gamma \ge 0` : The effective surface + energy for powder compaction applications is most easily determined through its + relation to the more commonly reported critical stress intensity factor + :math:`K_{Ic} = \sqrt{2\Delta\gamma E/(1-\nu^2)}`. + + 5. *Critical confinement ratio* :math:`0 \le \psi_b \le 1` : The critical confinement + ratio is a tunable parameter that determines when the bulk elastic response is + triggered. Lower values of :math:`\psi_b` delay the onset of the bulk elastic + response. + + 6. *Coefficient of restitution* :math:`0 \le e \le 1` : The coefficient of + restitution is a tunable parameter that controls damping in the normal direction. + +.. note:: + + The values for :math:`E`, :math:`\nu`, :math:`Y`, and :math:`\Delta\gamma` (i.e., + :math:`K_{Ic}`) should be selected for zero porosity to reflect the intrinsic + material property rather than the bulk powder property. + +The *mdr* model produces a nonlinear force-displacement response, therefore the +critical timestep :math:`\Delta t` depends on the inputs and level of +deformation. As a conservative starting point the timestep can be assumed to be +dictated by the bulk elastic response such that +:math:`\Delta t = 0.35\sqrt{m/k_\textrm{bulk}}`, where :math:`m` is the mass of +the smallest particle and :math:`k_\textrm{bulk} = \kappa R_\textrm{min}` is an +effective stiffness related to the bulk elastic response. +Here, :math:`\kappa = E/(3(1-2\nu))` is the bulk modulus and +:math:`R_\textrm{min}` is the radius of the smallest particle. + +.. note:: + + The *mdr* model requires some specific settings to function properly, + please read the following text carefully to ensure all requirements are + followed. + +The *atom_style* must be set to *sphere 1* to enable dynamic particle +radii. The *mdr* model is designed to respect the incompressibility of +plastic deformation and inherently tracks free surface displacements +induced by all particle contacts. In practice, this means that all particles +begin with an initial radius, however as compaction occurs and plastic +deformation is accumulated, a new enlarged apparent radius is defined to +ensure that that volume change due to plastic deformation is not lost. +This apparent radius is stored as the *atom radius* meaning it is used +for subsequent neighbor list builds and contact detection checks. The +advantage of this is that multi-neighbor dependent effects such as +formation of secondary contacts caused by radial expansion are captured +by the *mdr* model. Setting *atom_style sphere 1* ensures that updates to +the particle radii are properly reflected throughout the simulation. + +.. code-block:: LAMMPS + + atom_style sphere 1 + +Newton's third law must be set to *off*. This ensures that the neighbor lists +are constructed properly for the topological penalty algorithm used to screen +for non-physical contacts occurring through obstructing particles, an issue +prevalent under large deformation conditions. For more information on this +algorithm see :ref:`Zunker et al. `. + +.. code-block:: LAMMPS + + newton off + +The damping model must be set to *none*. The *mdr* model already has a built +in damping model. + +.. code-block:: LAMMPS + + pair_coeff * * mdr 5e6 0.4 1.9e5 2 0.5 0.5 damping none + +The definition of multiple *mdr* models in the *pair_style* is currently not +supported. Similarly, the *mdr* model cannot be combined with a different normal +model in the *pair_style*. Physically this means that only one homogeneous +collection of particles governed by a single *mdr* model is allowed. + +The *mdr* model currently only supports *fix wall/gran/region*, not +*fix wall/gran*. If the *mdr* model is specified for the *pair_style* +any *fix wall/gran/region* commands must also use the *mdr* model. +Additionally, the following *mdr* inputs must match between the +*pair_style* and *fix wall/gran/region* definitions: :math:`E`, +:math:`\nu`, :math:`Y`, :math:`\psi_b`, and :math:`e`. The exception +is :math:`\Delta\gamma`, which may vary, permitting different +adhesive behaviors between particle-particle and particle-wall interactions. + +.. note:: + + The *mdr* model has a number of custom *property/atom* and *pair/local* definitions that + can be called in the input file. The useful properties for visualization + and analysis are described below. + +In addition to contact forces the *mdr* model also tracks the following +quantities for each particle: elastic volume change, average normal +stress components, total surface area involved in +contact, and individual contact areas. In the input script, these quantities are +initialized by calling *run 0* and can then be accessed using subsequent *compute* +commands. The last *compute* command uses *pair/local p13* to calculate the pairwise +contact areas for each active contact in the *group-ID*. Due to the use of an apparent +radius in the *mdr* model, the keyword/arg pair *cutoff radius* must be specified for +*pair/local* to properly detect existing contacts. + +.. code-block:: LAMMPS + + run 0 + compute ID group-ID property/atom d_Velas + compute ID group-ID property/atom d_sigmaxx + compute ID group-ID property/atom d_sigmayy + compute ID group-ID property/atom d_sigmazz + compute ID group-ID property/atom d_Acon1 + compute ID group-ID pair/local p13 cutoff radius + +.. note:: + + The *mdr* model has two example input scripts within the + *examples/granular* directory. The first is a die compaction + simulation involving 200 particles named *in.tableting.200*. + The second is a triaxial compaction simulation involving 12 + particles named *in.triaxial.compaction.12*. + ---------- In addition, the normal force is augmented by a damping term of the @@ -695,7 +837,10 @@ supported are: 2. *radius* : :math:`k_{s}` 3. *area* : :math:`h_{s}` -If the *heat* keyword is not specified, the model defaults to *none*. +If the *heat* keyword is not specified, the model defaults to *none*. All +heat models calculate an additional pairwise quantity accessible by the +single() function (described below) which is the heat conducted between the +two particles. For *heat* *radius*, the heat :math:`Q` conducted between two particles is given by @@ -811,7 +956,7 @@ The single() function of these pair styles returns 0.0 for the energy of a pairwise interaction, since energy is not conserved in these dissipative potentials. It also returns only the normal component of the pairwise interaction force. However, the single() function also -calculates 13 extra pairwise quantities. The first 3 are the +calculates at least 13 extra pairwise quantities. The first 3 are the components of the tangential force between particles I and J, acting on particle I. The fourth is the magnitude of this tangential force. The next 3 (5-7) are the components of the rolling torque acting on @@ -819,9 +964,17 @@ particle I. The next entry (8) is the magnitude of the rolling torque. The next entry (9) is the magnitude of the twisting torque acting about the vector connecting the two particle centers. The next 3 (10-12) are the components of the vector connecting -the centers of the two particles (x_I - x_J). The last quantity (13) -is the heat flow between the two particles, set to 0 if no heat model -is active. +the centers of the two particles (x_I - x_J). If a granular sub-model +calculates additional contact information (e.g. the heat sub-models +calculate the amount of heat exchanged), these quantities are appended +to the end of this list. First, any extra values from the normal sub-model +are appended followed by the damping, tangential, rolling, twisting, then +heat models. See the descriptions of specific granular sub-models above +for information on any extra quantities. If two or more models are +defined by pair coefficients, the size of the array is set by the +maximum number of extra quantities in a model but the order of quantities +is determined by each model's specific set of sub-models. Any unused +quantities are zeroed. These extra quantities can be accessed by the :doc:`compute pair/local ` command, as *p1*, *p2*, ..., *p12*\ . @@ -892,10 +1045,32 @@ solids. Proc. R. Soc. Lond. A, 324(1558), 301-313. .. _DMT1975: -**Derjaguin et al, 1975)** Derjaguin, B. V., Muller, V. M., & Toporov, +**(Derjaguin et al, 1975)** Derjaguin, B. V., Muller, V. M., & Toporov, Y. P. (1975). Effect of contact deformations on the adhesion of particles. Journal of Colloid and interface science, 53(2), 314-326. +.. _Zunker2024I: + +**(Zunker and Kamrin, 2024)** Zunker, W., & Kamrin, K. (2024). +A mechanically-derived contact model for adhesive elastic-perfectly +plastic particles, Part I: Utilizing the method of dimensionality +reduction. Journal of the Mechanics and Physics of Solids, 183, 105492. + +.. _Zunker2024II: + +**(Zunker and Kamrin, 2024)** Zunker, W., & Kamrin, K. (2024). +A mechanically-derived contact model for adhesive elastic-perfectly +plastic particles, Part II: Contact under high compaction-modeling +a bulk elastic response. Journal of the Mechanics and Physics of Solids, +183, 105493. + +.. _Zunker2025: + +**(Zunker et al, 2025)** Zunker, W., Dunatunga, S., Thakur, S., +Tang, P., & Kamrin, K. (2025). Experimentally validated DEM for large +deformation powder compaction: mechanically-derived contact model and +screening of non-physical contacts. + .. _Luding2008: **(Luding, 2008)** Luding, S. (2008). Cohesive, frictional powders: diff --git a/doc/src/pair_hbond_dreiding.rst b/doc/src/pair_hbond_dreiding.rst index ce19ff9e38..a122fc5ea2 100644 --- a/doc/src/pair_hbond_dreiding.rst +++ b/doc/src/pair_hbond_dreiding.rst @@ -1,30 +1,46 @@ .. index:: pair_style hbond/dreiding/lj .. index:: pair_style hbond/dreiding/lj/omp +.. index:: pair_style hbond/dreiding/lj/angleoffset +.. index:: pair_style hbond/dreiding/lj/angleoffset/omp .. index:: pair_style hbond/dreiding/morse .. index:: pair_style hbond/dreiding/morse/omp +.. index:: pair_style hbond/dreiding/morse/angleoffset +.. index:: pair_style hbond/dreiding/morse/angleoffset/omp pair_style hbond/dreiding/lj command ==================================== Accelerator Variants: *hbond/dreiding/lj/omp* +pair_style hbond/dreiding/lj/angleoffset command +================================================ + +Accelerator Variants: *hbond/dreiding/lj/angleoffset/omp* + pair_style hbond/dreiding/morse command ======================================= Accelerator Variants: *hbond/dreiding/morse/omp* +pair_style hbond/dreiding/morse/angleoffset command +=================================================== + +Accelerator Variants: *hbond/dreiding/morse/angleoffset/omp* + + Syntax """""" .. code-block:: LAMMPS - pair_style style N inner_distance_cutoff outer_distance_cutoff angle_cutoff + pair_style style N inner_distance_cutoff outer_distance_cutoff angle_cutoff equilibrium_angle -* style = *hbond/dreiding/lj* or *hbond/dreiding/morse* +* style = *hbond/dreiding/lj* or *hbond/dreiding/morse* or *hbond/dreiding/lj/angleoffset* or *hbond/dreiding/morse/angleoffset* * N = power of cosine of angle theta (integer) * inner_distance_cutoff = global inner cutoff for Donor-Acceptor interactions (distance units) * outer_distance_cutoff = global cutoff for Donor-Acceptor interactions (distance units) * angle_cutoff = global angle cutoff for Acceptor-Hydrogen-Donor interactions (degrees) +* (with style angleoffset) equilibrium_angle = global equilibrium angle for Acceptor-Hydrogen-Donor interactions (degrees) Examples """""""" @@ -40,6 +56,9 @@ Examples labelmap atom 1 C 2 O 3 H pair_coeff C O hbond/dreiding/morse H i 3.88 1.7241379 2.9 2 9.0 11.0 90.0 + pair_style hybrid/overlay lj/cut 10.0 hbond/dreiding/lj 4 9.0 11.0 90 170.0 + pair_coeff 1 2 hbond/dreiding/lj 3 i 9.5 2.75 4 9.0 11.0 90.0 + Description """"""""""" @@ -74,42 +93,53 @@ hydrogen (H) and the donor atoms: .. image:: JPG/dreiding_hbond.jpg :align: center -These 3-body interactions can be defined for pairs of acceptor and -donor atoms, based on atom types. For each donor/acceptor atom pair, -the third atom in the interaction is a hydrogen permanently bonded to -the donor atom, e.g. in a bond list read in from a data file via the +These 3-body interactions can be defined for pairs of acceptor and donor +atoms, based on atom types. For each donor/acceptor atom pair, the +third atom in the interaction is a hydrogen permanently bonded to the +donor atom, e.g. in a bond list read in from a data file via the :doc:`read_data ` command. The atom types of possible hydrogen atoms for each donor/acceptor type pair are specified by the :doc:`pair_coeff ` command (see below). Style *hbond/dreiding/lj* is the original DREIDING potential of -:ref:`(Mayo) `. It uses a LJ 12/10 functional for the Donor-Acceptor -interactions. To match the results in the original paper, use n = 4. +:ref:`(Mayo) `. It uses a LJ 12/10 functional for the +Donor-Acceptor interactions. To match the results in the original paper, +use n = 4. Style *hbond/dreiding/morse* is an improved version using a Morse potential for the Donor-Acceptor interactions. :ref:`(Liu) ` showed that the Morse form gives improved results for Dendrimer simulations, when n = 2. +.. versionadded:: 4Feb2025 + +The style variants *hbond/dreiding/lj/angleoffset* and +*hbond/dreiding/lj/angleoffset* take the equilibrium angle of the AHD as +input, allowing it to reach 180 degrees. This variant option was added +to account for cases (especially in some coarse-grained models) in which +the equilibrium state of the bonds may equal the minimum energy state. + See the :doc:`Howto bioFF ` page for more information on the DREIDING force field. .. note:: - Because the Dreiding hydrogen bond potential is only one portion - of an overall force field which typically includes other pairwise - interactions, it is common to use it as a sub-style in a :doc:`pair_style hybrid/overlay ` command, where another pair style - provides the repulsive core interaction between pairs of atoms, e.g. a - 1/r\^12 Lennard-Jones repulsion. + Because the Dreiding hydrogen bond potential is only one portion of + an overall force field which typically includes other pairwise + interactions, it is common to use it as a sub-style in a + :doc:`pair_style hybrid/overlay ` command, where another + pair style provides the repulsive core interaction between pairs of + atoms, e.g. a 1/r\^12 Lennard-Jones repulsion. .. note:: - When using the hbond/dreiding pair styles with :doc:`pair_style hybrid/overlay `, you should explicitly define pair + When using the hbond/dreiding pair styles with :doc:`pair_style + hybrid/overlay `, you should explicitly define pair interactions between the donor atom and acceptor atoms, (as well as between these atoms and ALL other atoms in your system). Whenever - :doc:`pair_style hybrid/overlay ` is used, ordinary mixing - rules are not applied to atoms like the donor and acceptor atoms - because they are typically referenced in multiple pair styles. + :doc:`pair_style hybrid/overlay ` is used, ordinary + mixing rules are not applied to atoms like the donor and acceptor + atoms because they are typically referenced in multiple pair styles. Neglecting to do this can cause difficult-to-detect physics problems. .. note:: @@ -119,6 +149,13 @@ on the DREIDING force field. special_bonds command (e.g. "special_bonds lj 0.0 0.0 1.0") to turn these interactions on. +.. note:: + + For the *angleoffset* variants, the referenced angle offset is the + supplementary angle of the equilibrium angle parameter. It means if + the equilibrium angle is 166.6 degrees, the calculated angle offset + is 13.4 degrees. + ---------- The following coefficients must be defined for pairs of eligible @@ -169,7 +206,10 @@ follows: * distance cutoff :math:`r_{out}` (distance units) * angle cutoff (degrees) -A single hydrogen atom type K can be specified, or a wild-card asterisk +For both the *hbond/dreiding/lj/angleoffset* and *hbond/dreiding/morse/angleoffset* styles an additional parameter is added: +* equilibrium angle (degrees) + +For all styles, a single hydrogen atom type K can be specified, or a wild-card asterisk can be used in place of or in conjunction with the K arguments to select multiple types as hydrogen atoms. This takes the form "\*" or "\*n" or "n\*" or "m\*n". See the :doc:`pair_coeff ` @@ -245,8 +285,7 @@ heading) the following commands could be included in an input script: Restrictions """""""""""" -This pair style can only be used if LAMMPS was built with the -MOLECULE package. See the :doc:`Build package ` doc page +The base pair styles can only be used if LAMMPS was built with the MOLECULE package. The *angleoffset* variant also requires the EXTRA-MOLECULE package. See the :doc:`Build package ` doc page for more info. Related commands diff --git a/doc/src/pair_hybrid.rst b/doc/src/pair_hybrid.rst index 617b0c4372..93e5621736 100644 --- a/doc/src/pair_hybrid.rst +++ b/doc/src/pair_hybrid.rst @@ -70,6 +70,12 @@ Examples pair_coeff 1 1 lj/cut 1.0 1.0 2.5 pair_coeff 1 1 morse 1.0 1.0 1.0 2.5 + variable peratom1 atom 1/(1+exp(-$k*vx^2) + variable peratom2 atom 1-v_peratom1 + pair_style hybrid/scaled v_peratom1 lj/cut 2.5 v_peratom2 morse 2.5 + pair_coeff 1 1 lj/cut 1.0 1.0 2.5 + pair_coeff 1 1 morse 1.0 1.0 1.0 2.5 + Description """"""""""" @@ -78,7 +84,7 @@ styles enable the use of multiple pair styles in one simulation. With the *hybrid* style, exactly one pair style is assigned to each pair of atom types. With the *hybrid/overlay* and *hybrid/scaled* styles, one or more pair styles can be assigned to each pair of atom types. With -the hybrid/molecular style, pair styles are assigned to either intra- +the *hybrid/molecular* style, pair styles are assigned to either intra- or inter-molecular interactions. The assignment of pair styles to type pairs is made via the @@ -114,16 +120,26 @@ restrictions discussed below. If the *hybrid/scaled* style is used instead of *hybrid/overlay*, contributions from sub-styles are weighted by their scale factors, which -may be fractional or even negative. Furthermore the scale factors may -be variables that may change during a simulation. This enables +may be fractional or even negative. Furthermore the scale factor for +each sub-style may a constant, an *equal* style variable, or an *atom* +style variable. Variable scale factors may change during the simulation. +Different sub-styles may use different scale factor styles. +In the case of a sub-style scale factor that is an *atom* style variable, +the force contribution to each atom from that sub-style is weighted +by the value of the variable for that atom, while the contribution +from that sub-style to the global potential energy is zero. +All other contributions to the per-atom energy, per-atom +virial, and global virial (if not obtained from forces) +from that sub-style are zero. +This enables switching smoothly between two different pair styles or two different parameter sets during a run in a similar fashion as could be done with :doc:`fix adapt ` or :doc:`fix alchemy `. - All pair styles that will be used are listed as "sub-styles" following the *hybrid* or *hybrid/overlay* keyword, in any order. In case of the *hybrid/scaled* pair style, each sub-style is prefixed with a scale -factor. The scale factor is either a floating point number or an equal +factor. The scale factor is either a floating point number or an +*equal* or *atom* style (or equivalent) variable. Each sub-style's name is followed by its usual arguments, as illustrated in the examples above. See the doc pages of the individual pair styles for a listing and explanation of the @@ -374,7 +390,7 @@ between all atoms of types 1,3,4 will be computed by that potential. Pair_style hybrid allows interactions between type pairs 2-2, 1-2, 2-3, 2-4 to be specified for computation by other pair styles. You could even add a second interaction for 1-1 to be computed by another -pair style, assuming pair_style hybrid/overlay is used. +pair style, assuming pair_style *hybrid/overlay* is used. But you should not, as a general rule, attempt to exclude the many-body interactions for some subset of the type pairs within the set of 1,3,4 @@ -414,7 +430,7 @@ passed to the Tersoff potential, which means it would compute no 3-body interactions containing both type 1 and 2 atoms. Here is another example to use 2 many-body potentials together in an -overlapping manner using hybrid/overlay. Imagine you have CNT (C atoms) +overlapping manner using *hybrid/overlay*. Imagine you have CNT (C atoms) on a Si surface. You want to use Tersoff for Si/Si and Si/C interactions, and AIREBO for C/C interactions. Si atoms are type 1; C atoms are type 2. Something like this will work: diff --git a/doc/src/pair_mliap.rst b/doc/src/pair_mliap.rst index e325de0aa6..7f8b36bb83 100644 --- a/doc/src/pair_mliap.rst +++ b/doc/src/pair_mliap.rst @@ -145,6 +145,7 @@ per line. The detail of *nn* module implementation can be found at :ref:`(Yanxon) `. .. admonition:: Notes on mliappy models + :class: note When the *model* keyword is *mliappy*, if the filename ends in '.pt', or '.pth', it will be loaded using pytorch; otherwise, it will be diff --git a/doc/src/pair_reaxff.rst b/doc/src/pair_reaxff.rst index 495572dc0e..45532bc2a6 100644 --- a/doc/src/pair_reaxff.rst +++ b/doc/src/pair_reaxff.rst @@ -158,11 +158,36 @@ drops to zero. Optional keywords *safezone*, *mincap*, and *minhbonds* are used for allocating reaxff arrays. Increasing these values can avoid memory problems, such as segmentation faults and bondchk failed errors, that -could occur under certain conditions. These keywords are not used by +could occur under certain conditions. These keywords are **not** used by the Kokkos version, which instead uses a more robust memory allocation scheme that checks if the sizes of the arrays have been exceeded and automatically allocates more memory. +.. admonition:: Memory management problems with ReaxFF + :class: tip + + The LAMMPS implementation of ReaxFF is adapted from a standalone MD + program written in C called `PuReMD + `_. It inherits from this code + a heuristic memory management that is different from what the rest of + LAMMPS uses. It assumes that a system is dense and already well + equilibrated, so that there are no large changes in how many and what + types of neighbors atoms have. However, not all systems are like + that, and thus there can be errors or segmentation faults if the + system changes too much. If you run into problems, here are three + options to avoid them: + + - Use the KOKKOS version of ReaxFF (KOKKOS is not only for GPUs, + but can also be compiled for serial or OpenMP execution) which + uses a different memory management approach. + - Break down a run command during which memory related errors happen + into multiple smaller segments so that the memory management + heuristics are re-initialized for each segment before they become + invalid. + - Increase the values for *safezone*, *mincap*, and *minhbonds* as + needed. This can lead to significant increase of memory consumption + through. + The keyword *tabulate* controls the size of interpolation table for Lennard-Jones and Coulomb interactions. Tabulation may also be set in the control file (see below). If tabulation is set in both the input script and the diff --git a/doc/src/pair_style.rst b/doc/src/pair_style.rst index fc2ed2b9a9..bdf06d6b66 100644 --- a/doc/src/pair_style.rst +++ b/doc/src/pair_style.rst @@ -172,6 +172,7 @@ accelerated styles exist. * :doc:`coul/tt ` - damped charge-dipole Coulomb for Drude dipoles * :doc:`coul/wolf ` - Coulomb via Wolf potential * :doc:`coul/wolf/cs ` - Coulomb via Wolf potential with core/shell adjustments +* :doc:`dispersion/d3 ` - Dispersion correction for potentials derived from DFT functionals * :doc:`dpd ` - dissipative particle dynamics (DPD) * :doc:`dpd/coul/slater/long ` - dissipative particle dynamics (DPD) with electrostatic interactions * :doc:`dpd/ext ` - generalized force field for DPD @@ -206,7 +207,9 @@ accelerated styles exist. * :doc:`gw/zbl ` - Gao-Weber potential with a repulsive ZBL core * :doc:`harmonic/cut ` - repulsive-only harmonic potential * :doc:`hbond/dreiding/lj ` - DREIDING hydrogen bonding LJ potential +* :doc:`hbond/dreiding/lj/angleoffset ` - DREIDING hydrogen bonding LJ potential with offset for hbond angle * :doc:`hbond/dreiding/morse ` - DREIDING hydrogen bonding Morse potential +* :doc:`hbond/dreiding/morse/angleoffset ` - DREIDING hydrogen bonding Morse potential with offset for hbond angle * :doc:`hdnnp ` - High-dimensional neural network potential * :doc:`hippo ` - * :doc:`ilp/graphene/hbn ` - registry-dependent interlayer potential (ILP) diff --git a/doc/src/region.rst b/doc/src/region.rst index 94feee6ad4..6d4bbaca4b 100644 --- a/doc/src/region.rst +++ b/doc/src/region.rst @@ -46,6 +46,7 @@ Syntax xy = distance to tilt y in x direction (distance units) xz = distance to tilt z in x direction (distance units) yz = distance to tilt z in y direction (distance units) + xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz can be a variable (see below) *sphere* args = x y z radius x,y,z = center of sphere (distance units) radius = radius of sphere (distance units) @@ -211,7 +212,7 @@ and *ellipsoid* the x-, y-, and z- coordinates of the center of the sphere/ellipsoid can be specified as an equal-style variable. And for style *cylinder* the two center positions c1 and c2 for the location of the cylinder axes can be specified as a equal-style variable. For style -*cone* all properties can be defined via equal-style variables. For +*cone* and *prism* all properties can be defined via equal-style variables. For style *plane* the point can be defined via equal-style variables. If the value is a variable, it should be specified as v_name, where diff --git a/doc/src/region2vmd.rst b/doc/src/region2vmd.rst new file mode 100644 index 0000000000..6cea199760 --- /dev/null +++ b/doc/src/region2vmd.rst @@ -0,0 +1,183 @@ +.. index:: region2vmd + +region2vmd command +================== + +Syntax +"""""" + +.. code-block:: LAMMPS + + region2vmd file keyword arg ... + +* filename = name of file to write VMD script commands to +* zero or more keyword/arg pairs may be appended +* keyword = *region* or *color* or *material* or *command* + + .. parsed-literal:: + + *region* region-ID = name of region to translate to VMD graphics + *color* color-name = set color for following visualized objects + *material* material-name = set material for following visualized objects + *command* string = string with custom VMD script command (in quotes) + +Examples +"""""""" + +.. code-block:: LAMMPS + + region2vmd regions.vmd material Opaque color red region c1 color green region c2 + region2vmd vizbox.vmd command "mol new system.lammpstrj waitfor all" region box + region2vmd regdefs.vmd region upper region lower region hole + +Description +""""""""""" + +.. versionadded:: TBD + +Write a `VMD `_ Tcl script file with +commands that aim to create a visualization of :doc:`regions `. +There may be multiple region visualizations stored in a single file. + +The visualization is implemented by creating a new (and empty) "VMD +molecule" and then assigning a sequence of VMD graphics primitives to +represent the region in VMD. Each region will be stored in a separate +"VMD molecule" with the name "LAMMPS region ". + +The *region2vmd* command is following by the filename for the resulting +VMD script and an arbitrary number of keyword argument pairs to either +write out a new *region* visualization, change the *color* or *material* +setting, or to insert arbitrary VMD script *command*\ s. The keywords +and arguments are processed in sequence. + +The *region* keyword must be followed by a previously defined LAMMPS +:doc:`region `. Only a limited set region styles and region +settings are currently supported. See **Restrictions** below. +Unsupported region styles or regions with unsupported settings will be +skipped and a corresponding message is printed. + +The *color* keyword must be followed by a color name that is defined in +VMD. This color will be used by all following region visualizations. +The default setting is 'silver'. VMD has the following colors +pre-defined: + +.. table_from_list:: + :columns: 11 + + * blue + * red + * gray + * orange + * yellow + * tan + * silver + * green + * white + * pink + * cyan + * purple + * lime + * mauve + * ochre + * iceblue + * black + * yellow2 + * yellow3 + * green2 + * green3 + * cyan2 + * cyan3 + * blue2 + * blue3 + * violet + * violet2 + * magenta + * magenta2 + * red2 + * red3 + * orange2 + * orange3 + +The *material* keyword must be followed by a material name that is defined in +VMD. This material will be used by all following visualizations. The +default setting is 'Transparent'. VMD has the following materials +pre-defined: + +.. table_from_list:: + :columns: 8 + + * Opaque + * Transparent + * BrushedMetal + * Diffuse + * Ghost + * Glass1 + * Glass2 + * Glass3 + * Glossy + * HardPlastic + * MetallicPastel + * Steel + * Translucent + * Edgy + * EdgyShiny + * EdgyGlass + * Goodsell + * AOShiny + * AOChalky + * AOEdgy + * BlownGlass + * GlassBubble + * RTChrome + +The *command* keyword must be followed by a VMD script command as a +single string in quotes. This VMD command will be directly inserted +into the created VMD script. + +The created file can be loaded into VMD either from the command line +with the '-e' flag, or from the command prompt with 'play