diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 86418574ce..5016d9a644 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -72,6 +72,8 @@ src/EXTRA-COMMAND/ndx_group.* @akohlmey src/EXTRA-COMPUTE/compute_stress_mop*.* @RomainVermorel src/EXTRA-COMPUTE/compute_born_matrix.* @Bibobu @athomps src/EXTRA-FIX/fix_deform_pressure.* @jtclemm +src/EXTRA-PAIR/pair_dispersion_d3.* @soniasolomoni @arthurfl +src/EXTRA-PAIR/d3_parameters.h @soniasolomoni @arthurfl src/MISC/*_tracker.* @jtclemm src/MC/fix_gcmc.* @athomps src/MC/fix_sgcmc.* @athomps diff --git a/.github/release_steps.md b/.github/release_steps.md index 15ddd59768..1ffd3cb291 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. 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 bug-fix 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 @@ -44,65 +56,315 @@ git pull git checkout release git pull git merge --ff-only develop -git tag -s -m "LAMMPS feature release 19 November 2024" patch_19Nov2024 +git tag -s -m "LAMMPS feature release 4 February 2025" patch_4Feb2025 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" drop-down 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). +A suitable build environment is provided with the +https://download.lammps.org/static/fedora41_musl_mingw.sif container +image. The corresponding container build definition file is maintained +in the tools/singularity folder of the LAMMPS source distribution. -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 +#### Fully portable static Linux x86_64 non-MPI binaries + +The following commands use the Fedora container to build a fully static +LAMMPS installation using a musl-libc cross-compiler, install it into a +`lammps-static` folder, and create a tarball called +`lammps-linux-x86_64-4Feb2025.tar.gz` (or using a corresponding date +with a future release) from the `lammps-static` folder. + +``` 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-4Feb2025.tar.gz lammps-static +exit # fedora 41 container +cd .. +``` + +The resulting tar archive can be uploaded to the GitHub release page with: + +``` sh +gh release upload patch_4Feb2025 lammps-linux-x86_64-4Feb2025.tar.gz +``` + +#### Linux x86_64 Flatpak bundle with GUI included + +Make sure you have the `flatpak` and `flatpak-builder` packages +installed locally (they require binaries that run with elevated +privileges and thus 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 +cd release-packages +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-4Feb2025.flatpak org.lammps.lammps-gui release +cd .. ``` +The resulting flatpak bundle file can be uploaded to the GitHub release page with: + +``` sh +gh release upload patch_4Feb2025 LAMMPS-Linux-x86_64-GUI-4Feb2025.flatpak +``` + +#### LAMMPS Source tarball + +The container for the static binary can also be used to prepare the source +tarball including the HTML and PDF manual (this is currently done automatically +when the releases is created and the tarball uploaded to https://download.lammps.org/tars/). +The steps are as follows: + +``` sh +cd release-packages +apptainer shell fedora41_musl_mingw.sif +cd lammps-release +rm -f ../release.tar* +git archive --output=../release.tar --prefix=lammps-4Feb2025/ HEAD +cd doc +make clean-all +make html pdf +tar -rf ../../release.tar --transform 's,^,lammps-4Feb2025/doc/,' html Manual.pdf +gzip -9v ../../release.tar +mv ../../release.tar.gz ../../lammps-src-4Feb2025.tar.gz +exit # fedora41 container +cd .. +``` + +The resulting source tarball can be uploaded to the GitHub release page with: + +``` sh +gh release upload patch_4Feb2025 lammps-src-4Feb2025.tar.gz +``` + +#### Build Windows Installer Packages with MinGW Linux-to-Windows Cross-compiler + +The various Windows installer packages can also be built with +apptainer container image. + +``` sh +cd release-packages +apptainer shell fedora41_musl_mingw.sif +git clone --depth 10 https://github.com/lammps/lammps-packages.git lammps-packages +cd lammps-packages/mingw-cross +ln -sf ../../lammps-release lammps +./buildall.sh release >& mk.log & less +F mk.log +``` + +The installer with the GUI included can be uploaded to the GitHub release page with: + +``` sh +ln -sf LAMMPS-64bit-GUI-4Feb2025.exe LAMMPS-Win10-64bit-GUI-4Feb2025.exe +gh release upload patch_4Feb2025 LAMMPS-Win10-64bit-GUI-4Feb2025.exe +``` + +The symbolic link is used to have a consistent naming scheme for the packages +attached to the GitHub release page. + +#### Clean up: + +``` sh +cd .. +rm -r release-packages +``` + +#### Build Multi-arch App-bundle for macOS + +Building app-bundles for macOS is not as easily automated and portable +as some of the other steps. It requires a machine actually running +macOS. In that machine the Xcode compiler package needs to be +installed. This also includes tools for building and manipulating disk +images. This compiler supports building executables for both, the +x86_64 and the arm64 architectures. This requires building with CMake +and using the CMake settings: + +``` sh +-D CMAKE_OSX_ARCHITECTURES=arm64;x86_64 +-D CMAKE_OSX_DEPLOYMENT_TARGET=11.0 +``` + +This will add the compiler flags `-arch arm64 -arch x86_64 +-mmacosx-version-min=11.0` and thus produce object for both +architectures and support for macOS versions back to version 11 (aka Big +Sur). With these settings the following libraries should be compiled +and installed (e.g. to `$HOME/.local`) as static libraries only: +- libomp taken from the LLVM/Clang source distribution (to support OpenMP) +- jpeg +- zlib +- png +- Qt (for LAMMPS-GUI) + +When configuring LAMMPS the `cmake/presets/clang.cmake` should be used +and as many packages as possible enabled. For LAMMPS-GUI, MPI should be +disabled with `-D BUILD_MPI=OFF` and LAMMPS-GUI enabled with +`-D BUILD_LAMMPS_GUI=ON`. If the CMake configuration is successful, +settings for building a macOS app-bundle are enabled and with `cmake +--build build --target dmg` extra steps will be executed that will build +a macOS application installer image under the name +`LAMMPS_GUI-macOS-multiarch-4Feb2025.dmg` + +The application image can be uploaded to the GitHub release page with: + +``` sh +ln -sf LAMMPS_GUI-macOS-multiarch-4Feb2025.dmg LAMMPS-macOS-multiarch-GUI-4Feb2025.dmg +gh release upload patch_4Feb2025 LAMMPS-macOS-multiarch-GUI-4Feb2025.dmg +``` + +The symbolic link is used to have a consistent naming scheme for the packages +attached to the GitHub release page. + +We are currently building the application images on macOS 12 (aka Monterey). + +#### Build Linux x86_64 binary tarball on Ubuntu 20.04LTS + +While the flatpak Linux version uses portable runtime libraries provided +by the flatpak environment, we also build regular Linux executables that +use a wrapper script and matching shared libraries in a tarball. To be +compatible with many Linux distributions, one has to build this on a +very old Linux distribution, since most Linux system libraries are +usually backward compatible but not forward compatible. This is +currently done on an Ubuntu 20.04LTS system. Once LAMMPS moves to +require CMake 3.20 and C++17, we will have to move to Ubuntu 22.04LTS. +This installation (either on a real or a virtual machine) should have +the packages installed that are indicated in +`tools/singularity/ubuntu20.04.def` plus Qt version 5.x with development +headers, so that LAMMPS-GUI can be compiled. + +Also the building of the binary tarball and setup of the bundled +libraries and wrapper scripts is automated and can executed with `cmake +--build build --target tgz`. This should produce a file +`LAMMPS_GUI-Linux-amd64-4Feb2025.tar.gz` which can be uploaded to the +GitHub release page with: + +``` sh +ln -sf LAMMPS_GUI-Linux-amd64-4Feb2025.tar.gz LAMMPS-Linux-x86_64-GUI-4Feb2025.tar.gz +gh release upload patch_4Feb2025 LAMMPS-Linux-x86_64-GUI-4Feb2025.tar.gz +``` + +### Update download page on LAMMPS 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. + +Also 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 - - ## LAMMPS Stable Update Release + +After making a stable release, bugfixes from the 'develop' branch +are selectively backported to the 'maintenance' branch. This is +done with "git cherry-pick \' wherever possible. +The LAMMPS\_UPDATE define in "src/version.h" is set to "Maintenance". + +### Prerequesites + +When a sufficient number of bugfixes has accumulated or an urgent +or important bugfix needs to be distributed a new stable update +release is made. To make this publicly visible a pull request +is submitted that will merge 'maintenance' into 'stable'. Before +merging, set LAMMPS\_UPDATE in "src/version.h" to "Update #" with +"#" indicating the update count (1, 2, and so on). +Also draft suitable release notes under https://github.com/lammps/lammps/releases + +### Fast-forward merge of 'maintenance' into 'stable', apply tag, and publish + +Do a fast-forward merge of 'maintenance' to 'stable' and then +apply the stable\_DMmmYYYY\_update# tag and push branch and tag +to GitHub. The corresponding pull request will be automatically +closed. Example: + +``` +git checkout maintenance +git pull +git checkout stable +git pull +git merge --ff-only maintenance +git tag -s -m 'Update 2 for Stable LAMMPS version 29 August 2024' stable_29Aug2024_update2 +git push git@github.com:lammps/lammps.git --tags maintenance stable +``` + +Associate draft release notes with new tag and publish as "latest release". + +On https://ci.lammps.org/ go to "dev", "stable" and manually execute +the "update\_release" task. This will update https://docs.lammps.org/stable +and prepare a stable tarball. + +### Build and upload binary packages and source tarball to GitHub + +The build procedure is the same as for the feature releases, only +that packages are built from the 'stable' branch. diff --git a/.github/workflows/check-vla.yml b/.github/workflows/check-vla.yml index ab89018a3d..94e367be33 100644 --- a/.github/workflows/check-vla.yml +++ b/.github/workflows/check-vla.yml @@ -77,7 +77,7 @@ jobs: -D PKG_MDI=on \ -D PKG_MANIFOLD=on \ -D PKG_ML-PACE=on \ - -D PKG_ML-RANN=off \ + -D PKG_ML-RANN=on \ -D PKG_MOLFILE=on \ -D PKG_RHEO=on \ -D PKG_PTM=on \ diff --git a/.github/workflows/coverity.yml b/.github/workflows/coverity.yml index c0c3e3f89a..2691b9e895 100644 --- a/.github/workflows/coverity.yml +++ b/.github/workflows/coverity.yml @@ -67,7 +67,6 @@ jobs: -D PKG_MANIFOLD=on \ -D PKG_MDI=on \ -D PKG_MGPT=on \ - -D PKG_ML-PACE=on \ -D PKG_ML-RANN=on \ -D PKG_MOLFILE=on \ -D PKG_NETCDF=on \ diff --git a/.github/workflows/lammps-gui-flatpak.yml b/.github/workflows/lammps-gui-flatpak.yml new file mode 100644 index 0000000000..d7dc602476 --- /dev/null +++ b/.github/workflows/lammps-gui-flatpak.yml @@ -0,0 +1,53 @@ +# GitHub action to build LAMMPS-GUI as a flatpak bundle +name: "Build LAMMPS-GUI as flatpak bundle" + +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: LAMMPS-GUI flatpak build + if: ${{ github.repository == 'lammps/lammps' }} + runs-on: ubuntu-latest + + 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 \ + flatpak \ + flatpak-builder + + - name: Set up access to flatpak repo + run: flatpak --user remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo + + - name: Build flatpak + run: | + mkdir flatpack-state + sed -i -e 's/branch:.*/branch: develop/' tools/lammps-gui/org.lammps.lammps-gui.yml + flatpak-builder --force-clean --verbose --repo=flatpak-repo \ + --install-deps-from=flathub --state-dir=flatpak-state \ + --user --ccache --default-branch=${{ github.ref_name }} \ + flatpak-build tools/lammps-gui/org.lammps.lammps-gui.yml + flatpak build-bundle --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo \ + --verbose flatpak-repo LAMMPS-Linux-x86_64-GUI.flatpak \ + org.lammps.lammps-gui ${{ github.ref_name }} + flatpak install -y -v --user LAMMPS-Linux-x86_64-GUI.flatpak 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/README b/README index c25506e2c0..6477eb41d3 100644 --- a/README +++ b/README @@ -23,17 +23,20 @@ more information about the code and its uses. The LAMMPS distribution includes the following files and directories: README this file -LICENSE the GNU General Public License (GPL) -bench benchmark problems +LICENSE the GNU General Public License (GPLv2) +CITATION.cff Citation information for LAMMPS in CFF format +bench benchmark inputs cmake CMake build files doc documentation -examples simple test problems -fortran Fortran wrapper for LAMMPS +examples example inputs for many LAMMPS commands +fortran Fortran 2003 module for LAMMPS lib additional provided or external libraries potentials interatomic potential files -python Python wrappers for LAMMPS +python Python module for LAMMPS src source files tools pre- and post-processing tools +unittest test programs for use with CTest +.github Git and GitHub related files and tools Point your browser at any of these files to get started: @@ -42,6 +45,8 @@ https://docs.lammps.org/Intro.html hi-level introduction https://docs.lammps.org/Build.html how to build LAMMPS https://docs.lammps.org/Run_head.html how to run LAMMPS https://docs.lammps.org/Commands_all.html Table of available commands +https://docs.lammps.org/Howto.html Short tutorials and HowTo discussions +https://docs.lammps.org/Errors.html How to interpret and debug errors https://docs.lammps.org/Library.html LAMMPS library interfaces https://docs.lammps.org/Modify.html how to modify and extend LAMMPS https://docs.lammps.org/Developer.html LAMMPS developer info diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index 38431e3bb5..f22fa401a2 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -3,6 +3,9 @@ # CMake build system # This file is part of LAMMPS cmake_minimum_required(VERSION 3.16) +if(CMAKE_VERSION VERSION_LESS 3.20) + message(WARNING "LAMMPS is planning to require at least CMake version 3.20 by Summer 2025. Please upgrade!") +endif() ######################################## # set policy to silence warnings about ignoring _ROOT but use it if(POLICY CMP0074) @@ -144,16 +147,28 @@ if((PKG_KOKKOS) AND (Kokkos_ENABLE_CUDA) AND NOT (CMAKE_CXX_COMPILER_ID STREQUAL set(CMAKE_TUNE_DEFAULT "${CMAKE_TUNE_DEFAULT}" "-Xcudafe --diag_suppress=unrecognized_pragma,--diag_suppress=128") endif() -# we require C++11 without extensions. Kokkos requires at least C++17 (currently) +# we *require* C++11 without extensions but prefer C++17. +# Kokkos requires at least C++17 (currently) if(NOT CMAKE_CXX_STANDARD) - set(CMAKE_CXX_STANDARD 11) + if(cxx_std_17 IN_LIST CMAKE_CXX_COMPILE_FEATURES) + set(CMAKE_CXX_STANDARD 17) + else() + set(CMAKE_CXX_STANDARD 11) + endif() endif() if(CMAKE_CXX_STANDARD LESS 11) message(FATAL_ERROR "C++ standard must be set to at least 11") endif() +if(CMAKE_CXX_STANDARD LESS 17) + message(WARNING "Selecting C++17 standard is preferred over C++${CMAKE_CXX_STANDARD}") +endif() if(PKG_KOKKOS AND (CMAKE_CXX_STANDARD LESS 17)) set(CMAKE_CXX_STANDARD 17) endif() +# turn off C++17 check in lmptype.h +if(LAMMPS_CXX11) + add_compile_definitions(LAMMPS_CXX11) +endif() set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_EXTENSIONS OFF CACHE BOOL "Use compiler extensions") # ugly hacks for MSVC which by default always reports an old C++ standard in the __cplusplus macro @@ -194,7 +209,7 @@ endif() ######################################################################## # User input options # ######################################################################## -# backward compatibility with CMake before 3.12 and older LAMMPS documentation +# backward compatibility with older LAMMPS documentation if (PYTHON_EXECUTABLE) set(Python_EXECUTABLE "${PYTHON_EXECUTABLE}") endif() @@ -210,6 +225,12 @@ if(DEFINED ENV{VIRTUAL_ENV} AND NOT Python_EXECUTABLE) " Setting Python interpreter to: ${Python_EXECUTABLE}") endif() +find_package(Python COMPONENTS Interpreter QUIET) +# NOTE: RHEL 8.0 and Ubuntu 18.04LTS ship with Python 3.6, Python 3.8 was EOL in 2024 +if(Python_VERSION VERSION_LESS 3.6) + message(FATAL_ERROR "LAMMPS requires Python 3.6 or later") +endif() + set(LAMMPS_MACHINE "" CACHE STRING "Suffix to append to lmp binary (WON'T enable any features automatically") mark_as_advanced(LAMMPS_MACHINE) if(LAMMPS_MACHINE) @@ -347,6 +368,17 @@ foreach(PKG ${STANDARD_PACKAGES} ${SUFFIX_PACKAGES}) option(PKG_${PKG} "Build ${PKG} Package" OFF) endforeach() +set(DEPRECATED_PACKAGES AWPMD ATC POEMS) +foreach(PKG ${DEPRECATED_PACKAGES}) + if(PKG_${PKG}) + message(WARNING + "The ${PKG} package will be removed from LAMMPS in Summer 2025 due to lack of " + "maintenance and use of code constructs that conflict with modern C++ compilers " + "and standards. Please contact developers@lammps.org if you have any concerns " + "about this step.") + endif() +endforeach() + ###################################################### # packages with special compiler needs or external libs ###################################################### @@ -399,8 +431,8 @@ else() target_link_libraries(lammps PUBLIC mpi_stubs) endif() -set(LAMMPS_SIZES "smallbig" CACHE STRING "LAMMPS integer sizes (smallsmall: all 32-bit, smallbig: 64-bit #atoms #timesteps, bigbig: also 64-bit imageint, 64-bit atom ids)") -set(LAMMPS_SIZES_VALUES smallbig bigbig smallsmall) +set(LAMMPS_SIZES "smallbig" CACHE STRING "LAMMPS integer sizes (smallbig: 64-bit #atoms #timesteps, bigbig: also 64-bit imageint, 64-bit atom ids)") +set(LAMMPS_SIZES_VALUES smallbig bigbig) set_property(CACHE LAMMPS_SIZES PROPERTY STRINGS ${LAMMPS_SIZES_VALUES}) validate_option(LAMMPS_SIZES LAMMPS_SIZES_VALUES) string(TOUPPER ${LAMMPS_SIZES} LAMMPS_SIZES) @@ -579,6 +611,16 @@ foreach(PKG_WITH_INCL KSPACE PYTHON ML-IAP VORONOI COLVARS ML-HDNNP MDI MOLFILE endif() endforeach() +# settings for misc packages and styles +if(PKG_MISC) + option(LAMMPS_ASYNC_IMD "Asynchronous IMD processing" OFF) + mark_as_advanced(LAMMPS_ASYNC_IMD) + if(LAMMPS_ASYNC_IMD) + target_compile_definitions(lammps PRIVATE -DLAMMPS_ASYNC_IMD) + message(STATUS "Using IMD in asynchronous mode") + endif() +endif() + # optionally enable building script wrappers using swig option(WITH_SWIG "Build scripting language wrappers with SWIG" OFF) if(WITH_SWIG) @@ -894,7 +936,7 @@ endif() include(Testing) include(CodeCoverage) include(CodingStandard) -find_package(ClangFormat 11.0) +find_package(ClangFormat 11.0 QUIET) if(ClangFormat_FOUND) add_custom_target(format-src diff --git a/cmake/Modules/CodeCoverage.cmake b/cmake/Modules/CodeCoverage.cmake index 21a651e519..885b5cba6d 100644 --- a/cmake/Modules/CodeCoverage.cmake +++ b/cmake/Modules/CodeCoverage.cmake @@ -7,76 +7,76 @@ # For Python coverage the coverage package needs to be installed ############################################################################### if(ENABLE_COVERAGE) - find_program(GCOVR_BINARY gcovr) - find_package_handle_standard_args(GCOVR DEFAULT_MSG GCOVR_BINARY) + find_program(GCOVR_BINARY gcovr) + find_package_handle_standard_args(GCOVR DEFAULT_MSG GCOVR_BINARY) - find_program(COVERAGE_BINARY coverage) - find_package_handle_standard_args(COVERAGE DEFAULT_MSG COVERAGE_BINARY) + find_program(COVERAGE_BINARY coverage) + find_package_handle_standard_args(COVERAGE DEFAULT_MSG COVERAGE_BINARY) - if(GCOVR_FOUND) - get_filename_component(ABSOLUTE_LAMMPS_SOURCE_DIR ${LAMMPS_SOURCE_DIR} ABSOLUTE) + if(GCOVR_FOUND) + get_filename_component(ABSOLUTE_LAMMPS_SOURCE_DIR ${LAMMPS_SOURCE_DIR} ABSOLUTE) - add_custom_target( - gen_coverage_xml - COMMAND ${GCOVR_BINARY} -s -x -r ${ABSOLUTE_LAMMPS_SOURCE_DIR} --object-directory=${CMAKE_BINARY_DIR} -o coverage.xml - WORKING_DIRECTORY ${CMAKE_BINARY_DIR} - COMMENT "Generating XML coverage report..." - ) + add_custom_target( + gen_coverage_xml + COMMAND ${GCOVR_BINARY} -s -x -r ${ABSOLUTE_LAMMPS_SOURCE_DIR} --object-directory=${CMAKE_BINARY_DIR} -o coverage.xml + WORKING_DIRECTORY ${CMAKE_BINARY_DIR} + COMMENT "Generating XML coverage report..." + ) - set(COVERAGE_HTML_DIR ${CMAKE_BINARY_DIR}/coverage_html) + set(COVERAGE_HTML_DIR ${CMAKE_BINARY_DIR}/coverage_html) - add_custom_target(coverage_html_folder - COMMAND ${CMAKE_COMMAND} -E make_directory ${COVERAGE_HTML_DIR}) + add_custom_target(coverage_html_folder + COMMAND ${CMAKE_COMMAND} -E make_directory ${COVERAGE_HTML_DIR}) - add_custom_target( - gen_coverage_html - COMMAND ${GCOVR_BINARY} -s --html --html-details -r ${ABSOLUTE_LAMMPS_SOURCE_DIR} --object-directory=${CMAKE_BINARY_DIR} -o ${COVERAGE_HTML_DIR}/index.html - WORKING_DIRECTORY ${CMAKE_BINARY_DIR} - COMMENT "Generating HTML coverage report..." - ) - add_dependencies(gen_coverage_html coverage_html_folder) + add_custom_target( + gen_coverage_html + COMMAND ${GCOVR_BINARY} -s --html --html-details -r ${ABSOLUTE_LAMMPS_SOURCE_DIR} --object-directory=${CMAKE_BINARY_DIR} -o ${COVERAGE_HTML_DIR}/index.html + WORKING_DIRECTORY ${CMAKE_BINARY_DIR} + COMMENT "Generating HTML coverage report..." + ) + add_dependencies(gen_coverage_html coverage_html_folder) - add_custom_target(clean_coverage_html - ${CMAKE_COMMAND} -E remove_directory ${COVERAGE_HTML_DIR} - COMMENT "Deleting HTML coverage report..." - ) + add_custom_target(clean_coverage_html + ${CMAKE_COMMAND} -E remove_directory ${COVERAGE_HTML_DIR} + COMMENT "Deleting HTML coverage report..." + ) - add_custom_target(reset_coverage - ${CMAKE_COMMAND} -E remove -f */*.gcda */*/*.gcda */*/*/*.gcda - */*/*/*/*.gcda */*/*/*/*/*.gcda */*/*/*/*/*/*.gcda - */*/*/*/*/*/*/*.gcda */*/*/*/*/*/*/*/*.gcda - */*/*/*/*/*/*/*/*/*.gcda */*/*/*/*/*/*/*/*/*/*.gcda - WORKIND_DIRECTORY ${CMAKE_BINARY_DIR} - COMMENT "Deleting coverage data files..." - ) - add_dependencies(reset_coverage clean_coverage_html) - endif() + add_custom_target(reset_coverage + ${CMAKE_COMMAND} -E remove -f */*.gcda */*/*.gcda */*/*/*.gcda + */*/*/*/*.gcda */*/*/*/*/*.gcda */*/*/*/*/*/*.gcda + */*/*/*/*/*/*/*.gcda */*/*/*/*/*/*/*/*.gcda + */*/*/*/*/*/*/*/*/*.gcda */*/*/*/*/*/*/*/*/*/*.gcda + WORKIND_DIRECTORY ${CMAKE_BINARY_DIR} + COMMENT "Deleting coverage data files..." + ) + add_dependencies(reset_coverage clean_coverage_html) + endif() - if(COVERAGE_FOUND) - set(PYTHON_COVERAGE_HTML_DIR ${CMAKE_BINARY_DIR}/python_coverage_html) - configure_file(.coveragerc.in ${CMAKE_BINARY_DIR}/.coveragerc @ONLY) + if(COVERAGE_FOUND) + set(PYTHON_COVERAGE_HTML_DIR ${CMAKE_BINARY_DIR}/python_coverage_html) + configure_file(.coveragerc.in ${CMAKE_BINARY_DIR}/.coveragerc @ONLY) - add_custom_command( - OUTPUT ${CMAKE_BINARY_DIR}/unittest/python/.coverage - COMMAND ${COVERAGE_BINARY} combine - WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python - COMMENT "Combine Python coverage files..." - ) + add_custom_command( + OUTPUT ${CMAKE_BINARY_DIR}/unittest/python/.coverage + COMMAND ${COVERAGE_BINARY} combine + WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python + COMMENT "Combine Python coverage files..." + ) - add_custom_target( - gen_python_coverage_html - COMMAND ${COVERAGE_BINARY} html --rcfile=${CMAKE_BINARY_DIR}/.coveragerc -d ${PYTHON_COVERAGE_HTML_DIR} - DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage ${CMAKE_BINARY_DIR}/.coveragerc - WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python - COMMENT "Generating HTML Python coverage report..." - ) + add_custom_target( + gen_python_coverage_html + COMMAND ${COVERAGE_BINARY} html --rcfile=${CMAKE_BINARY_DIR}/.coveragerc -d ${PYTHON_COVERAGE_HTML_DIR} + DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage ${CMAKE_BINARY_DIR}/.coveragerc + WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python + COMMENT "Generating HTML Python coverage report..." + ) - add_custom_target( - gen_python_coverage_xml - COMMAND ${COVERAGE_BINARY} xml --rcfile=${CMAKE_BINARY_DIR}/.coveragerc -o ${CMAKE_BINARY_DIR}/python_coverage.xml - DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage ${CMAKE_BINARY_DIR}/.coveragerc - WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python - COMMENT "Generating XML Python coverage report..." - ) - endif() + add_custom_target( + gen_python_coverage_xml + COMMAND ${COVERAGE_BINARY} xml --rcfile=${CMAKE_BINARY_DIR}/.coveragerc -o ${CMAKE_BINARY_DIR}/python_coverage.xml + DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage ${CMAKE_BINARY_DIR}/.coveragerc + WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python + COMMENT "Generating XML Python coverage report..." + ) + endif() endif() diff --git a/cmake/Modules/CodingStandard.cmake b/cmake/Modules/CodingStandard.cmake index 94639c7771..4e99c2e39c 100644 --- a/cmake/Modules/CodingStandard.cmake +++ b/cmake/Modules/CodingStandard.cmake @@ -1,40 +1,39 @@ -# use default (or custom) Python executable, if version is sufficient -if(Python_VERSION VERSION_GREATER_EQUAL 3.6) +# use default (or custom) Python executable. +# Python version check is in main CMakeLists.txt file +if(Python_EXECUTABLE) set(Python3_EXECUTABLE ${Python_EXECUTABLE}) endif() find_package(Python3 COMPONENTS Interpreter) if(Python3_EXECUTABLE) - if(Python3_VERSION VERSION_GREATER_EQUAL 3.6) - add_custom_target( - check-whitespace - ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/whitespace.py . - WORKING_DIRECTORY ${LAMMPS_DIR} - COMMENT "Check for whitespace errors") - add_custom_target( - check-homepage - ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/homepage.py . - WORKING_DIRECTORY ${LAMMPS_DIR} - COMMENT "Check for homepage URL errors") - add_custom_target( - check-permissions - ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/permissions.py . - WORKING_DIRECTORY ${LAMMPS_DIR} - COMMENT "Check for permission errors") - add_custom_target( - fix-whitespace - ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/whitespace.py -f . - WORKING_DIRECTORY ${LAMMPS_DIR} - COMMENT "Fix whitespace errors") - add_custom_target( - fix-homepage - ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/homepage.py -f . - WORKING_DIRECTORY ${LAMMPS_DIR} - COMMENT "Fix homepage URL errors") - add_custom_target( - fix-permissions - ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/permissions.py -f . - WORKING_DIRECTORY ${LAMMPS_DIR} - COMMENT "Fix permission errors") - endif() + add_custom_target( + check-whitespace + ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/whitespace.py . + WORKING_DIRECTORY ${LAMMPS_DIR} + COMMENT "Check for whitespace errors") + add_custom_target( + check-homepage + ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/homepage.py . + WORKING_DIRECTORY ${LAMMPS_DIR} + COMMENT "Check for homepage URL errors") + add_custom_target( + check-permissions + ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/permissions.py . + WORKING_DIRECTORY ${LAMMPS_DIR} + COMMENT "Check for permission errors") + add_custom_target( + fix-whitespace + ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/whitespace.py -f . + WORKING_DIRECTORY ${LAMMPS_DIR} + COMMENT "Fix whitespace errors") + add_custom_target( + fix-homepage + ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/homepage.py -f . + WORKING_DIRECTORY ${LAMMPS_DIR} + COMMENT "Fix homepage URL errors") + add_custom_target( + fix-permissions + ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/permissions.py -f . + WORKING_DIRECTORY ${LAMMPS_DIR} + COMMENT "Fix permission errors") endif() diff --git a/cmake/Modules/Documentation.cmake b/cmake/Modules/Documentation.cmake index dfaf7bdb39..511d54114c 100644 --- a/cmake/Modules/Documentation.cmake +++ b/cmake/Modules/Documentation.cmake @@ -13,7 +13,7 @@ if(BUILD_DOC) endif() find_package(Python3 REQUIRED COMPONENTS Interpreter) if(Python3_VERSION VERSION_LESS 3.8) - message(FATAL_ERROR "Python 3.8 and up is required to build the HTML documentation") + message(FATAL_ERROR "Python 3.8 and up is required to build the LAMMPS HTML documentation") endif() set(VIRTUALENV ${Python3_EXECUTABLE} -m venv) @@ -65,8 +65,8 @@ if(BUILD_DOC) find_package(Sphinx) endif() - set(MATHJAX_URL "https://github.com/mathjax/MathJax/archive/3.1.3.tar.gz" CACHE STRING "URL for MathJax tarball") - set(MATHJAX_MD5 "b81661c6e6ba06278e6ae37b30b0c492" CACHE STRING "MD5 checksum of MathJax tarball") + set(MATHJAX_URL "https://github.com/mathjax/MathJax/archive/3.2.2.tar.gz" CACHE STRING "URL for MathJax tarball") + set(MATHJAX_MD5 "08dd6ef33ca08870220d9aade2a62845" CACHE STRING "MD5 checksum of MathJax tarball") mark_as_advanced(MATHJAX_URL) GetFallbackURL(MATHJAX_URL MATHJAX_FALLBACK) diff --git a/cmake/Modules/LAMMPSInterfacePlugin.cmake b/cmake/Modules/LAMMPSInterfacePlugin.cmake index 151e0a04f7..5b7444f62c 100644 --- a/cmake/Modules/LAMMPSInterfacePlugin.cmake +++ b/cmake/Modules/LAMMPSInterfacePlugin.cmake @@ -34,8 +34,26 @@ if(MSVC) add_compile_definitions(_CRT_SECURE_NO_WARNINGS) endif() -# C++11 is required -set(CMAKE_CXX_STANDARD 11) +if(NOT CMAKE_CXX_STANDARD) + if(cxx_std_17 IN_LIST CMAKE_CXX_COMPILE_FEATURES) + set(CMAKE_CXX_STANDARD 17) + else() + set(CMAKE_CXX_STANDARD 11) + endif() +endif() +if(CMAKE_CXX_STANDARD LESS 11) + message(FATAL_ERROR "C++ standard must be set to at least 11") +endif() +if(CMAKE_CXX_STANDARD LESS 17) + message(WARNING "Selecting C++17 standard is preferred over C++${CMAKE_CXX_STANDARD}") +endif() +if(PKG_KOKKOS AND (CMAKE_CXX_STANDARD LESS 17)) + set(CMAKE_CXX_STANDARD 17) +endif() +# turn off C++17 check in lmptype.h +if(LAMMPS_CXX11) + add_compile_definitions(LAMMPS_CXX11) +endif() set(CMAKE_CXX_STANDARD_REQUIRED ON) # Need -restrict with Intel compilers @@ -242,8 +260,8 @@ endif() ################ # integer size selection -set(LAMMPS_SIZES "smallbig" CACHE STRING "LAMMPS integer sizes (smallsmall: all 32-bit, smallbig: 64-bit #atoms #timesteps, bigbig: also 64-bit imageint, 64-bit atom ids)") -set(LAMMPS_SIZES_VALUES smallbig bigbig smallsmall) +set(LAMMPS_SIZES "smallbig" CACHE STRING "LAMMPS integer sizes (smallbig: 64-bit #atoms #timesteps, bigbig: also 64-bit imageint, 64-bit atom ids)") +set(LAMMPS_SIZES_VALUES smallbig bigbig) set_property(CACHE LAMMPS_SIZES PROPERTY STRINGS ${LAMMPS_SIZES_VALUES}) validate_option(LAMMPS_SIZES LAMMPS_SIZES_VALUES) string(TOUPPER ${LAMMPS_SIZES} LAMMPS_SIZES) 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 ddd2daefcd..2731b0df14 100644 --- a/cmake/Modules/Packages/KOKKOS.cmake +++ b/cmake/Modules/Packages/KOKKOS.cmake @@ -7,26 +7,13 @@ endif() ######################################################################## # consistency checks and Kokkos options/settings required by LAMMPS -if(Kokkos_ENABLE_CUDA) - option(Kokkos_ENABLE_IMPL_CUDA_MALLOC_ASYNC "CUDA asynchronous malloc support" OFF) - mark_as_advanced(Kokkos_ENABLE_IMPL_CUDA_MALLOC_ASYNC) - if(Kokkos_ENABLE_IMPL_CUDA_MALLOC_ASYNC) - message(STATUS "KOKKOS: CUDA malloc async support enabled") - else() - message(STATUS "KOKKOS: CUDA malloc async support disabled") - endif() -endif() if(Kokkos_ENABLE_HIP) option(Kokkos_ENABLE_HIP_MULTIPLE_KERNEL_INSTANTIATIONS "Enable multiple kernel instantiations with HIP" ON) mark_as_advanced(Kokkos_ENABLE_HIP_MULTIPLE_KERNEL_INSTANTIATIONS) option(Kokkos_ENABLE_ROCTHRUST "Use RoCThrust library" ON) mark_as_advanced(Kokkos_ENABLE_ROCTHRUST) - - if(Kokkos_ARCH_AMD_GFX942 OR Kokkos_ARCH_AMD_GFX940) - option(Kokkos_ENABLE_IMPL_HIP_UNIFIED_MEMORY "Enable unified memory with HIP" ON) - mark_as_advanced(Kokkos_ENABLE_IMPL_HIP_UNIFIED_MEMORY) - endif() endif() + # Adding OpenMP compiler flags without the checks done for # BUILD_OMP can result in compile failures. Enforce consistency. if(Kokkos_ENABLE_OPENMP) @@ -70,8 +57,8 @@ if(DOWNLOAD_KOKKOS) list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_CXX_EXTENSIONS=${CMAKE_CXX_EXTENSIONS}") list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}") include(ExternalProject) - set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/4.4.01.tar.gz" CACHE STRING "URL for KOKKOS tarball") - set(KOKKOS_MD5 "de6ee80d00b6212b02bfb7f1e71a8392" CACHE STRING "MD5 checksum of KOKKOS tarball") + set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/4.5.01.tar.gz" CACHE STRING "URL for KOKKOS tarball") + set(KOKKOS_MD5 "4d832aa0284169d9e3fbae3165286bc6" CACHE STRING "MD5 checksum of KOKKOS tarball") mark_as_advanced(KOKKOS_URL) mark_as_advanced(KOKKOS_MD5) GetFallbackURL(KOKKOS_URL KOKKOS_FALLBACK) @@ -96,7 +83,7 @@ if(DOWNLOAD_KOKKOS) add_dependencies(LAMMPS::KOKKOSCORE kokkos_build) add_dependencies(LAMMPS::KOKKOSCONTAINERS kokkos_build) elseif(EXTERNAL_KOKKOS) - find_package(Kokkos 4.4.01 REQUIRED CONFIG) + find_package(Kokkos 4.5.01 REQUIRED CONFIG) target_link_libraries(lammps PRIVATE Kokkos::kokkos) else() set(LAMMPS_LIB_KOKKOS_SRC_DIR ${LAMMPS_LIB_SOURCE_DIR}/kokkos) @@ -130,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/ML-IAP.cmake b/cmake/Modules/Packages/ML-IAP.cmake index 91b772efb5..1691af8d95 100644 --- a/cmake/Modules/Packages/ML-IAP.cmake +++ b/cmake/Modules/Packages/ML-IAP.cmake @@ -24,9 +24,7 @@ if(MLIAP_ENABLE_PYTHON) if(NOT PKG_PYTHON) message(FATAL_ERROR "Must enable PYTHON package for including Python support in ML-IAP") endif() - if(Python_VERSION VERSION_LESS 3.6) - message(FATAL_ERROR "Python support in ML-IAP requires Python 3.6 or later") - endif() + # Python version check is in main CMakeLists.txt file set(MLIAP_BINARY_DIR ${CMAKE_BINARY_DIR}/cython) file(GLOB MLIAP_CYTHON_SRC CONFIGURE_DEPENDS ${LAMMPS_SOURCE_DIR}/ML-IAP/*.pyx) diff --git a/cmake/Modules/Packages/ML-PACE.cmake b/cmake/Modules/Packages/ML-PACE.cmake index 8660898138..b30c61b8e4 100644 --- a/cmake/Modules/Packages/ML-PACE.cmake +++ b/cmake/Modules/Packages/ML-PACE.cmake @@ -1,50 +1,62 @@ # PACE library support for ML-PACE package +find_package(pace QUIET) -# set policy to silence warnings about timestamps of downloaded files. review occasionally if it may be set to NEW -if(POLICY CMP0135) - cmake_policy(SET CMP0135 OLD) -endif() - -set(PACELIB_URL "https://github.com/ICAMS/lammps-user-pace/archive/refs/tags/v.2023.11.25.fix.tar.gz" CACHE STRING "URL for PACE evaluator library sources") -set(PACELIB_MD5 "b45de9a633f42ed65422567e3ce56f9f" CACHE STRING "MD5 checksum of PACE evaluator library tarball") -mark_as_advanced(PACELIB_URL) -mark_as_advanced(PACELIB_MD5) -GetFallbackURL(PACELIB_URL PACELIB_FALLBACK) - -# LOCAL_ML-PACE points to top-level dir with local lammps-user-pace repo, -# to make it easier to check local build without going through the public github releases -if(LOCAL_ML-PACE) - set(lib-pace "${LOCAL_ML-PACE}") +if(pace_FOUND) + find_package(pace) + target_link_libraries(lammps PRIVATE pace::pace) else() - # download library sources to build folder - if(EXISTS ${CMAKE_BINARY_DIR}/libpace.tar.gz) - file(MD5 ${CMAKE_BINARY_DIR}/libpace.tar.gz DL_MD5) - endif() - if(NOT "${DL_MD5}" STREQUAL "${PACELIB_MD5}") - message(STATUS "Downloading ${PACELIB_URL}") - file(DOWNLOAD ${PACELIB_URL} ${CMAKE_BINARY_DIR}/libpace.tar.gz STATUS DL_STATUS SHOW_PROGRESS) - file(MD5 ${CMAKE_BINARY_DIR}/libpace.tar.gz DL_MD5) - if((NOT DL_STATUS EQUAL 0) OR (NOT "${DL_MD5}" STREQUAL "${PACELIB_MD5}")) - message(WARNING "Download from primary URL ${PACELIB_URL} failed\nTrying fallback URL ${PACELIB_FALLBACK}") - file(DOWNLOAD ${PACELIB_FALLBACK} ${CMAKE_BINARY_DIR}/libpace.tar.gz EXPECTED_HASH MD5=${PACELIB_MD5} SHOW_PROGRESS) + # set policy to silence warnings about timestamps of downloaded files. review occasionally if it may be set to NEW + if(POLICY CMP0135) + cmake_policy(SET CMP0135 OLD) endif() - else() - message(STATUS "Using already downloaded archive ${CMAKE_BINARY_DIR}/libpace.tar.gz") - endif() + + set(PACELIB_URL "https://github.com/ICAMS/lammps-user-pace/archive/refs/tags/v.2023.11.25.fix2.tar.gz" CACHE STRING "URL for PACE evaluator library sources") + set(PACELIB_MD5 "a53bd87cfee8b07d9f44bc17aad69c3f" CACHE STRING "MD5 checksum of PACE evaluator library tarball") + mark_as_advanced(PACELIB_URL) + mark_as_advanced(PACELIB_MD5) + GetFallbackURL(PACELIB_URL PACELIB_FALLBACK) + + # LOCAL_ML-PACE points to top-level dir with local lammps-user-pace repo, + # to make it easier to check local build without going through the public github releases + if(LOCAL_ML-PACE) + set(lib-pace "${LOCAL_ML-PACE}") + else() + # download library sources to build folder + if(EXISTS ${CMAKE_BINARY_DIR}/libpace.tar.gz) + file(MD5 ${CMAKE_BINARY_DIR}/libpace.tar.gz DL_MD5) + endif() + if(NOT "${DL_MD5}" STREQUAL "${PACELIB_MD5}") + message(STATUS "Downloading ${PACELIB_URL}") + file(DOWNLOAD ${PACELIB_URL} ${CMAKE_BINARY_DIR}/libpace.tar.gz STATUS DL_STATUS SHOW_PROGRESS) + file(MD5 ${CMAKE_BINARY_DIR}/libpace.tar.gz DL_MD5) + if((NOT DL_STATUS EQUAL 0) OR (NOT "${DL_MD5}" STREQUAL "${PACELIB_MD5}")) + message(WARNING "Download from primary URL ${PACELIB_URL} failed\nTrying fallback URL ${PACELIB_FALLBACK}") + file(DOWNLOAD ${PACELIB_FALLBACK} ${CMAKE_BINARY_DIR}/libpace.tar.gz EXPECTED_HASH MD5=${PACELIB_MD5} SHOW_PROGRESS) + endif() + else() + message(STATUS "Using already downloaded archive ${CMAKE_BINARY_DIR}/libpace.tar.gz") + endif() - # uncompress downloaded sources - execute_process( - COMMAND ${CMAKE_COMMAND} -E remove_directory lammps-user-pace* - COMMAND ${CMAKE_COMMAND} -E tar xzf libpace.tar.gz - WORKING_DIRECTORY ${CMAKE_BINARY_DIR} - ) - get_newest_file(${CMAKE_BINARY_DIR}/lammps-user-pace-* lib-pace) -endif() - -add_subdirectory(${lib-pace} build-pace) -set_target_properties(pace PROPERTIES CXX_EXTENSIONS ON OUTPUT_NAME lammps_pace${LAMMPS_MACHINE}) - -if(CMAKE_PROJECT_NAME STREQUAL "lammps") - target_link_libraries(lammps PRIVATE pace) + # uncompress downloaded sources + execute_process( + COMMAND ${CMAKE_COMMAND} -E remove_directory lammps-user-pace* + COMMAND ${CMAKE_COMMAND} -E tar xzf libpace.tar.gz + WORKING_DIRECTORY ${CMAKE_BINARY_DIR} + ) + get_newest_file(${CMAKE_BINARY_DIR}/lammps-user-pace-* lib-pace) + endif() + + # some preinstalled yaml-cpp versions don't provide a namespaced target + find_package(yaml-cpp QUIET) + if(TARGET yaml-cpp AND NOT TARGET yaml-cpp::yaml-cpp) + add_library(yaml-cpp::yaml-cpp ALIAS yaml-cpp) + endif() + + add_subdirectory(${lib-pace} build-pace) + set_target_properties(pace PROPERTIES CXX_EXTENSIONS ON OUTPUT_NAME lammps_pace${LAMMPS_MACHINE}) + + if(CMAKE_PROJECT_NAME STREQUAL "lammps") + target_link_libraries(lammps PRIVATE pace) + endif() endif() diff --git a/cmake/Modules/Packages/ML-QUIP.cmake b/cmake/Modules/Packages/ML-QUIP.cmake index 9106ff54ef..aad6ee5e34 100644 --- a/cmake/Modules/Packages/ML-QUIP.cmake +++ b/cmake/Modules/Packages/ML-QUIP.cmake @@ -37,7 +37,7 @@ if(DOWNLOAD_QUIP) endforeach() # Fix cmake crashing when MATH_LINKOPTS not set, required for e.g. recent Cray Programming Environment set(temp "${temp} -L/_DUMMY_PATH_\n") - set(temp "${temp}PYTHON=python\nPIP=pip\nEXTRA_LINKOPTS=\n") + set(temp "${temp}PYTHON=${Python_EXECUTABLE}\nPIP=pip\nEXTRA_LINKOPTS=\n") set(temp "${temp}HAVE_CP2K=0\nHAVE_VASP=0\nHAVE_TB=0\nHAVE_PRECON=1\nHAVE_LOTF=0\nHAVE_ONIOM=0\n") set(temp "${temp}HAVE_LOCAL_E_MIX=0\nHAVE_QC=0\nHAVE_GAP=1\nHAVE_DESCRIPTORS_NONCOMMERCIAL=1\n") set(temp "${temp}HAVE_TURBOGAP=0\nHAVE_QR=1\nHAVE_THIRDPARTY=0\nHAVE_FX=0\nHAVE_SCME=0\nHAVE_MTP=0\n") diff --git a/cmake/Modules/Packages/PLUMED.cmake b/cmake/Modules/Packages/PLUMED.cmake index 8dab157a24..1b4845d259 100644 --- a/cmake/Modules/Packages/PLUMED.cmake +++ b/cmake/Modules/Packages/PLUMED.cmake @@ -32,14 +32,21 @@ 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) GetFallbackURL(PLUMED_URL PLUMED_FALLBACK) +# adjust C++ standard support for self-compiled Plumed2 +if(CMAKE_CXX_STANDARD GREATER 11) + set(PLUMED_CXX_STANDARD 14) +else() + set(PLUMED_CXX_STANDARD 11) +endif() + if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND (CMAKE_CROSSCOMPILING)) if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64") set(CROSS_CONFIGURE mingw64-configure) @@ -55,7 +62,7 @@ if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND (CMAKE_CROSSCOMPILING)) URL_MD5 ${PLUMED_MD5} BUILD_IN_SOURCE 1 CONFIGURE_COMMAND ${CROSS_CONFIGURE} --disable-shared --disable-bsymbolic - --disable-python --enable-cxx=11 + --disable-python --enable-cxx=${PLUMED_CXX_STANDARD} --enable-modules=-adjmat:+crystallization:-dimred:+drr:+eds:-fisst:+funnel:+logmfd:+manyrestraints:+maze:+opes:+multicolvar:-pamm:-piv:+s2cm:-sasa:-ves ${PLUMED_CONFIG_OMP} ${PLUMED_CONFIG_MPI} @@ -142,7 +149,7 @@ else() CONFIGURE_COMMAND /configure --prefix= ${CONFIGURE_REQUEST_PIC} --enable-modules=all - --enable-cxx=11 + --enable-cxx=${PLUMED_CXX_STANDARD} --disable-python ${PLUMED_CONFIG_MPI} ${PLUMED_CONFIG_OMP} diff --git a/cmake/Modules/Packages/PYTHON.cmake b/cmake/Modules/Packages/PYTHON.cmake index e05edadbf3..0879382ed7 100644 --- a/cmake/Modules/Packages/PYTHON.cmake +++ b/cmake/Modules/Packages/PYTHON.cmake @@ -1,6 +1,6 @@ if(NOT Python_INTERPRETER) - # backward compatibility with CMake before 3.12 and older LAMMPS documentation + # backward compatibility with older LAMMPS documentation if(PYTHON_EXECUTABLE) set(Python_EXECUTABLE ${PYTHON_EXECUTABLE}) endif() diff --git a/cmake/presets/kokkos-cuda.cmake b/cmake/presets/kokkos-cuda.cmake index 878ce0c566..31942b8fae 100644 --- a/cmake/presets/kokkos-cuda.cmake +++ b/cmake/presets/kokkos-cuda.cmake @@ -1,6 +1,5 @@ # preset that enables KOKKOS and selects CUDA compilation with OpenMP -# enabled as well. This preselects CC 5.0 as default GPU arch, since -# that is compatible with all higher CC, but not the default CC 3.5 +# enabled as well. The GPU architecture *must* match your hardware set(PKG_KOKKOS ON CACHE BOOL "" FORCE) set(Kokkos_ENABLE_SERIAL ON CACHE BOOL "" FORCE) set(Kokkos_ENABLE_CUDA ON CACHE BOOL "" FORCE) diff --git a/doc/Makefile b/doc/Makefile index d26e6020a6..703a55cc3d 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -17,9 +17,11 @@ MATHJAXTAG = 3.2.2 PYTHON = $(word 3,$(shell type python3)) DOXYGEN = $(word 3,$(shell type doxygen)) +PANDOC = $(word 3,$(shell type pandoc)) HAS_PYTHON3 = NO HAS_DOXYGEN = NO HAS_PDFLATEX = NO +HAS_PANDOC = NO ifeq ($(shell type python3 >/dev/null 2>&1; echo $$?), 0) HAS_PYTHON3 = YES @@ -31,10 +33,14 @@ endif ifeq ($(shell type pdflatex >/dev/null 2>&1; echo $$?), 0) ifeq ($(shell type latexmk >/dev/null 2>&1; echo $$?), 0) -HAS_PDFLATEX = YES +HAS_PDFLATEX = YES endif endif +ifeq ($(shell type pandoc >/dev/null 2>&1; echo $$?), 0) +HAS_PANDOC = YES +endif + # override settings for PIP commands # PIP_OPTIONS = --cert /etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt --proxy http://proxy.mydomain.org @@ -45,8 +51,9 @@ SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocess # we only want to use explicitly listed files. DOXYFILES = $(shell sed -n -e 's/\#.*$$//' -e '/^ *INPUT \+=/,/^[A-Z_]\+ \+=/p' doxygen/Doxyfile.in | sed -e 's/@LAMMPS_SOURCE_DIR@/..\/src/g' -e 's/\\//g' -e 's/ \+/ /' -e 's/[A-Z_]\+ \+= *\(YES\|NO\|\)//') -.PHONY: help clean-all clean clean-spelling epub mobi html pdf spelling anchor_check style_check char_check role_check xmlgen fasthtml +.PHONY: help clean-all clean clean-spelling epub mobi html pdf spelling anchor_check style_check char_check role_check xmlgen fasthtml fasthtml-init +FASTHTMLFILES = $(patsubst $(RSTDIR)/%.rst,fasthtml/%.html,$(wildcard $(RSTDIR)/*rst)) # ------------------------------------------ help: @@ -116,25 +123,23 @@ html: xmlgen globbed-tocs $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJ @rm -rf html/PDF/.[sg]* @echo "Build finished. The HTML pages are in doc/html." -fasthtml: xmlgen globbed-tocs $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX) - @if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi - @$(MAKE) $(MFLAGS) -C graphviz all - @mkdir -p fasthtml - @(\ - . $(VENV)/bin/activate ; env PYTHONWARNINGS= PYTHONDONTWRITEBYTECODE=1 \ - sphinx-build $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/fasthtml/doctrees $(RSTDIR) fasthtml ;\ - touch $(RSTDIR)/Fortran.rst ; env PYTHONWARNINGS= PYTHONDONTWRITEBYTECODE=1 \ - sphinx-build $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/fasthtml/doctrees $(RSTDIR) fasthtml ;\ - deactivate ;\ - ) - @rm -rf fasthtml/_sources - @rm -rf fasthtml/PDF - @rm -rf fasthtml/USER - @rm -rf fasthtml/JPG - @cp -r src/PDF fasthtml/PDF - @rm -rf fasthtml/PDF/.[sg]* +fasthtml: fasthtml-init $(FASTHTMLFILES) @echo "Fast HTML build finished. The HTML pages are in doc/fasthtml." +fasthtml-init: + @mkdir -p fasthtml/JPG + @cp src/JPG/*.* fasthtml/JPG + @cp $(RSTDIR)/accel_styles.rst $(RSTDIR)/lepton_expression.rst fasthtml/ + @cp $(BUILDDIR)/utils/pandoc.css fasthtml/ + +fasthtml/%.html: $(RSTDIR)/%.rst + @if [ "$(HAS_PANDOC)" == "NO" ] ; then echo "Make 'fasthtml' requires the 'pandoc' software" 1>&2; exit 1; fi + @mkdir -p fasthtml + @echo converting $< to $@ + @sed -e 's/\\AA/\\mathring{\\mathrm{A}}/g' $< > fasthtml/$*.temp.rst + @pandoc -s --mathml --css="pandoc.css" --template=$(BUILDDIR)/utils/pandoc.html --metadata title="$@" -o $@ fasthtml/$*.temp.rst + @rm -f fasthtml/$*.temp.rst + spelling: xmlgen globbed-tocs $(SPHINXCONFIG)/conf.py $(VENV) $(SPHINXCONFIG)/false_positives.txt @if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi @(\ diff --git a/doc/README b/doc/README index de956a96bb..f96e0b14da 100644 --- a/doc/README +++ b/doc/README @@ -22,12 +22,12 @@ doxygen-warn.log logfile with warnings from running doxygen and: github-development-workflow.md notes on the LAMMPS development workflow -include-file-conventions.md notes on LAMMPS' include file conventions documentation_conventions.md notes on writing documentation for LAMMPS If you downloaded a LAMMPS tarball from www.lammps.org, then the html folder and the PDF manual should be included. If you downloaded LAMMPS -from GitHub then you either need to build them. +using GitHub then you either need to build them yourself or read the +online version at https://docs.lammps.org/ You can build the HTML and PDF files yourself, by typing "make html" or by "make pdf", respectively. This requires various tools and files. @@ -39,10 +39,10 @@ environment and local folders. Installing prerequisites for the documentation build -To run the HTML documention build toolchain, python 3.x, doxygen, git, -and the venv python module have to be installed if not already available. -Also internet access is initially required to download external files -and tools. +To run the HTML documention build toolchain, python 3.8 or later, +doxygen 1.8.10 or later, git, and the venv python module have to be +installed if not already available. Also internet access is initially +required to download external files and tools. Building the PDF format manual requires in addition a compatible LaTeX installation with support for PDFLaTeX and several add-on LaTeX packages @@ -52,16 +52,24 @@ installed. This includes: - babel - capt-of - cmap +- dvipng +- ellipse - fncychap +- fontawesom - framed - geometry +- gyre - hyperref - hypcap - needspace +- pict2e - times - tabulary +- titlesec - upquote - wrapfig +- xindy + Also the latexmk script is required to run PDFLaTeX and related tools. the required number of times to have self-consistent output and include updated bibliography and indices. 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.rst b/doc/src/Build.rst index 7cf2a01992..ff09ee5678 100644 --- a/doc/src/Build.rst +++ b/doc/src/Build.rst @@ -1,15 +1,42 @@ Build LAMMPS ============ -LAMMPS is built as a library and an executable from source code using -either traditional makefiles for use with GNU make (which may require -manual editing), or using a build environment generated by CMake (Unix -Makefiles, Ninja, Xcode, Visual Studio, KDevelop, CodeBlocks and more). +LAMMPS is built as a library and an executable from source code using a +build environment generated by CMake (Unix Makefiles, Ninja, Xcode, +Visual Studio, KDevelop, CodeBlocks and more depending on the platform). +Using CMake is the preferred way to build LAMMPS. In addition, LAMMPS +can be compiled using the legacy build system based on traditional +makefiles for use with GNU make (which may require manual editing). +Support for the legacy build system is slowly being phased out and may +not be available for all optional features. As an alternative, you can download a package with pre-built executables or automated build trees, as described in the :doc:`Install ` section of the manual. +Prerequisites +------------- + +Which software you need to compile and use LAMMPS strongly depends on +which :doc:`features and settings ` and which +:doc:`optional packages ` you are trying to include. +Common to all is that you need a C++ and C compiler, where the C++ +compiler has to support at least the C++11 standard (note that some +compilers require command-line flag to activate C++11 support). +Furthermore, if you are building with CMake, you need at least CMake +version 3.20 and a compatible build tool (make or ninja-build); if you +are building the the legacy GNU make based build system you need GNU +make (other make variants are not going to work since the build system +uses features unique to GNU make) and a Unix-like build environment with +a Bourne shell, and shell tools like "sed", "grep", "touch", "test", +"tr", "cp", "mv", "rm", "ln", "diff" and so on. Parts of LAMMPS +interface with or use Python version 3.6 or later. + +The LAMMPS developers aim to keep LAMMPS very portable and usable - +at least in parts - on most operating systems commonly used for +running MD simulations. Please see the :doc:`section on portablility +` for more details. + .. toctree:: :maxdepth: 1 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/Build_cmake.rst b/doc/src/Build_cmake.rst index c8c74c5182..2349eebf62 100644 --- a/doc/src/Build_cmake.rst +++ b/doc/src/Build_cmake.rst @@ -16,7 +16,7 @@ environments is on a :doc:`separate page `. .. note:: - LAMMPS currently requires that CMake version 3.16 or later is available. + LAMMPS currently requires that CMake version 3.20 or later is available. .. warning:: @@ -32,11 +32,11 @@ environments is on a :doc:`separate page `. Advantages of using CMake ^^^^^^^^^^^^^^^^^^^^^^^^^ -CMake is an alternative to compiling LAMMPS in the traditional way -through :doc:`(manually customized) makefiles `. Using -CMake has multiple advantages that are specifically helpful for -people with limited experience in compiling software or for people -that want to modify or extend LAMMPS. +CMake is the preferred way of compiling LAMMPS in contrast to the legacy +build system based on GNU make and through :doc:`(manually customized) +makefiles `. Using CMake has multiple advantages that are +specifically helpful for people with limited experience in compiling +software or for people that want to modify or extend LAMMPS. - CMake can detect available hardware, tools, features, and libraries and adapt the LAMMPS default build configuration accordingly. @@ -47,14 +47,14 @@ that want to modify or extend LAMMPS. knowledge of file formats or complex command-line syntax is required. - All enabled components are compiled in a single build operation. - Automated dependency tracking for all files and configuration options. -- Support for true out-of-source compilation. Multiple configurations +- Support for true out-of-source compilation. Multiple configurations and settings with different choices of LAMMPS packages, settings, or compilers can be configured and built concurrently from the same source tree. - Simplified packaging of LAMMPS for Linux distributions, environment - modules, or automated build tools like `Homebrew `_. -- Integration of automated unit and regression testing (the LAMMPS side - of this is still under active development). + modules, or automated build tools like `Spack `_ + or `Homebrew `_. +- Integration of automated unit and regression testing. .. _cmake_build: @@ -119,6 +119,13 @@ configured) and additional files like LAMMPS API headers, manpages, potential and force field files. The location of the installation tree defaults to ``${HOME}/.local``. +.. note:: + + If you have set `-D CMAKE_INSTALL_PREFIX` to install LAMMPS into a + system location on a Linux machine , you may also have to run (as + root) the `ldconfig` program to update the cache file for fast lookup + of system shared libraries. + .. _cmake_options: Configuration and build options diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index 08e4cdbb7a..ca64ffbe2e 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -48,6 +48,7 @@ This is the list of packages that may require additional steps. * :ref:`LEPTON ` * :ref:`MACHDYN ` * :ref:`MDI ` + * :ref:`MISC ` * :ref:`ML-HDNNP ` * :ref:`ML-IAP ` * :ref:`ML-PACE ` @@ -254,11 +255,10 @@ Traditional make Before building LAMMPS, you must build the GPU library in ``lib/gpu``\ . You can do this manually if you prefer; follow the instructions in -``lib/gpu/README``. Note that the GPU library uses MPI calls, so you must -use the same MPI library (or the STUBS library) settings as the main -LAMMPS code. This also applies to the ``-DLAMMPS_BIGBIG``\ , -``-DLAMMPS_SMALLBIG``\ , or ``-DLAMMPS_SMALLSMALL`` settings in whichever -Makefile you use. +``lib/gpu/README``. Note that the GPU library uses MPI calls, so you +must use the same MPI library (or the STUBS library) settings as the +main LAMMPS code. This also applies to the ``-DLAMMPS_BIGBIG`` or +``-DLAMMPS_SMALLBIG`` settings in whichever Makefile you use. You can also build the library in one step from the ``lammps/src`` dir, using a command like these, which simply invokes the ``lib/gpu/Install.py`` @@ -547,16 +547,7 @@ They must be specified in uppercase. - Local machine * - AMDAVX - HOST - - AMD 64-bit x86 CPU (AVX 1) - * - ZEN - - HOST - - AMD Zen class CPU (AVX 2) - * - ZEN2 - - HOST - - AMD Zen2 class CPU (AVX 2) - * - ZEN3 - - HOST - - AMD Zen3 class CPU (AVX 2) + - AMD chip * - ARMV80 - HOST - ARMv8.0 Compatible CPU @@ -572,105 +563,126 @@ They must be specified in uppercase. * - A64FX - HOST - ARMv8.2 with SVE Support + * - ARMV9_GRACE + - HOST + - ARMv9 NVIDIA Grace CPU * - SNB - HOST - - Intel Sandy/Ivy Bridge CPU (AVX 1) + - Intel Sandy/Ivy Bridge CPUs * - HSW - HOST - - Intel Haswell CPU (AVX 2) + - Intel Haswell CPUs * - BDW - HOST - - Intel Broadwell Xeon E-class CPU (AVX 2 + transactional mem) - * - SKL - - HOST - - Intel Skylake Client CPU - * - SKX - - HOST - - Intel Skylake Xeon Server CPU (AVX512) + - Intel Broadwell Xeon E-class CPUs * - ICL - HOST - - Intel Ice Lake Client CPU (AVX512) + - Intel Ice Lake Client CPUs (AVX512) * - ICX - HOST - - Intel Ice Lake Xeon Server CPU (AVX512) - * - SPR + - Intel Ice Lake Xeon Server CPUs (AVX512) + * - SKL - HOST - - Intel Sapphire Rapids Xeon Server CPU (AVX512) + - Intel Skylake Client CPUs + * - SKX + - HOST + - Intel Skylake Xeon Server CPUs (AVX512) * - KNC - HOST - Intel Knights Corner Xeon Phi * - KNL - HOST - Intel Knights Landing Xeon Phi + * - SPR + - HOST + - Intel Sapphire Rapids Xeon Server CPUs (AVX512) * - POWER8 - HOST - - IBM POWER8 CPU + - IBM POWER8 CPUs * - POWER9 - HOST - - IBM POWER9 CPU + - IBM POWER9 CPUs + * - ZEN + - HOST + - AMD Zen architecture + * - ZEN2 + - HOST + - AMD Zen2 architecture + * - ZEN3 + - HOST + - AMD Zen3 architecture * - RISCV_SG2042 - HOST - - SG2042 (RISC-V) CPU + - SG2042 (RISC-V) CPUs + * - RISCV_RVA22V + - HOST + - RVA22V (RISC-V) CPUs * - KEPLER30 - GPU - - NVIDIA Kepler generation CC 3.0 GPU + - NVIDIA Kepler generation CC 3.0 * - KEPLER32 - GPU - - NVIDIA Kepler generation CC 3.2 GPU + - NVIDIA Kepler generation CC 3.2 * - KEPLER35 - GPU - - NVIDIA Kepler generation CC 3.5 GPU + - NVIDIA Kepler generation CC 3.5 * - KEPLER37 - GPU - - NVIDIA Kepler generation CC 3.7 GPU + - NVIDIA Kepler generation CC 3.7 * - MAXWELL50 - GPU - - NVIDIA Maxwell generation CC 5.0 GPU + - NVIDIA Maxwell generation CC 5.0 * - MAXWELL52 - GPU - - NVIDIA Maxwell generation CC 5.2 GPU + - NVIDIA Maxwell generation CC 5.2 * - MAXWELL53 - GPU - - NVIDIA Maxwell generation CC 5.3 GPU + - NVIDIA Maxwell generation CC 5.3 * - PASCAL60 - GPU - - NVIDIA Pascal generation CC 6.0 GPU + - NVIDIA Pascal generation CC 6.0 * - PASCAL61 - GPU - - NVIDIA Pascal generation CC 6.1 GPU + - NVIDIA Pascal generation CC 6.1 * - VOLTA70 - GPU - - NVIDIA Volta generation CC 7.0 GPU + - NVIDIA Volta generation CC 7.0 * - VOLTA72 - GPU - - NVIDIA Volta generation CC 7.2 GPU + - NVIDIA Volta generation CC 7.2 * - TURING75 - GPU - - NVIDIA Turing generation CC 7.5 GPU + - NVIDIA Turing generation CC 7.5 * - AMPERE80 - GPU - - NVIDIA Ampere generation CC 8.0 GPU + - NVIDIA Ampere generation CC 8.0 * - AMPERE86 - GPU - - NVIDIA Ampere generation CC 8.6 GPU + - NVIDIA Ampere generation CC 8.6 * - ADA89 - GPU - - NVIDIA Ada Lovelace generation CC 8.9 GPU + - NVIDIA Ada generation CC 8.9 * - HOPPER90 - GPU - - NVIDIA Hopper generation CC 9.0 GPU + - NVIDIA Hopper generation CC 9.0 * - AMD_GFX906 - GPU - - AMD GPU MI50/MI60 + - AMD GPU MI50/60 * - AMD_GFX908 - GPU - AMD GPU MI100 * - AMD_GFX90A - GPU - AMD GPU MI200 + * - AMD_GFX940 + - GPU + - AMD GPU MI300 * - AMD_GFX942 - GPU - AMD GPU MI300 + * - AMD_GFX942_APU + - GPU + - AMD APU MI300A * - AMD_GFX1030 - GPU - AMD GPU V620/W6800 @@ -679,7 +691,7 @@ They must be specified in uppercase. - AMD GPU RX7900XTX * - AMD_GFX1103 - GPU - - AMD Phoenix APU with Radeon 740M/760M/780M/880M/890M + - AMD APU Phoenix * - INTEL_GEN - GPU - SPIR64-based devices, e.g. Intel GPUs, using JIT @@ -702,7 +714,7 @@ They must be specified in uppercase. - GPU - Intel GPU Ponte Vecchio -This list was last updated for version 4.3.0 of the Kokkos library. +This list was last updated for version 4.5.1 of the Kokkos library. .. tabs:: @@ -1126,11 +1138,10 @@ POEMS package PYTHON package --------------------------- -Building with the PYTHON package requires you have a the Python development -headers and library available on your system, which needs to be a Python 2.7 -version or a Python 3.x version. Since support for Python 2.x has ended, -using Python 3.x is strongly recommended. See ``lib/python/README`` for -additional details. +Building with the PYTHON package requires you have a the Python +development headers and library available on your system, which +needs to be Python version 3.6 or later. See ``lib/python/README`` +for additional details. .. tabs:: @@ -1146,7 +1157,7 @@ additional details. set the Python_EXECUTABLE variable to specify which Python interpreter should be used. Note note that you will also need to have the development headers installed for this version, - e.g. python2-devel. + e.g. python3-devel. .. tab:: Traditional make @@ -2019,7 +2030,7 @@ TBB and MKL. .. _mdi: MDI package ------------------------------ +----------- .. tabs:: @@ -2046,6 +2057,37 @@ MDI package ---------- +.. _misc: + +MISC package +------------ + +The :doc:`fix imd ` style in this package can be run either +synchronously (communication with IMD clients is done in the main +process) or asynchronously (the fix spawns a separate thread that can +communicate with IMD clients concurrently to the LAMMPS execution). + +.. tabs:: + + .. tab:: CMake build + + .. code-block:: bash + + -D LAMMPS_ASYNC_IMD=value # Run IMD server asynchronously + # value = no (default) or yes + + .. tab:: Traditional make + + To enable asynchronous mode the ``-DLAMMPS_ASYNC_IMD`` define + needs to be added to the ``LMP_INC`` variable in the + ``Makefile.machine`` you are using. For example: + + .. code-block:: make + + LMP_INC = -DLAMMPS_ASYNC_IMD -DLAMMPS_MEMALIGN=64 + +---------- + .. _molfile: MOLFILE package diff --git a/doc/src/Build_make.rst b/doc/src/Build_make.rst index 932050d410..477c1c6e34 100644 --- a/doc/src/Build_make.rst +++ b/doc/src/Build_make.rst @@ -8,6 +8,10 @@ Building LAMMPS with traditional makefiles requires that you have a for customizing your LAMMPS build with a number of global compilation options and features. +This build system is slowly being phased out and may not support all +optional features and packages in LAMMPS. It is recommended to switch +to the :doc:`CMake based build system `. + Requirements ^^^^^^^^^^^^ @@ -26,9 +30,9 @@ additional tools to be available and functioning. * A Bourne shell compatible "Unix" shell program (frequently this is ``bash``) * A few shell utilities: ``ls``, ``mv``, ``ln``, ``rm``, ``grep``, ``sed``, ``tr``, ``cat``, ``touch``, ``diff``, ``dirname`` * Python (optional, required for ``make lib-`` in the ``src`` - folder). Python scripts are currently tested with python 2.7 and - 3.6 to 3.11. The procedure for :doc:`building the documentation - ` *requires* Python 3.5 or later. + folder). Python scripts are currently tested with 3.6 to 3.11. + The procedure for :doc:`building the documentation ` + *requires* Python 3.8 or later. Getting started ^^^^^^^^^^^^^^^ diff --git a/doc/src/Build_manual.rst b/doc/src/Build_manual.rst index 4b4bfa5a45..2fc29f584b 100644 --- a/doc/src/Build_manual.rst +++ b/doc/src/Build_manual.rst @@ -78,8 +78,7 @@ folder. The following ``make`` commands are available: make epub # generate LAMMPS.epub in ePUB format using Sphinx make mobi # generate LAMMPS.mobi in MOBI format using ebook-convert - make fasthtml # generate approximate HTML in fasthtml dir using Sphinx - # some Sphinx extensions do not work correctly with this + make fasthtml # generate approximate HTML in fasthtml dir using pandoc make clean # remove intermediate RST files created by HTML build make clean-all # remove entire build folder and any cached data @@ -116,9 +115,9 @@ environment variable. Prerequisites for HTML ---------------------- -To run the HTML documentation build toolchain, python 3, git, doxygen, -and virtualenv have to be installed locally. Here are instructions for -common setups: +To run the HTML documentation build toolchain, Python 3.8 or later, git, +doxygen, and virtualenv have to be installed locally. Here are +instructions for common setups: .. tabs:: @@ -128,13 +127,7 @@ common setups: sudo apt-get install git doxygen - .. tab:: RHEL or CentOS (Version 7.x) - - .. code-block:: bash - - sudo yum install git doxygen - - .. tab:: Fedora or RHEL/CentOS (8.x or later) + .. tab:: Fedora or RHEL/AlmaLinux/RockyLinux (8.x or later) .. code-block:: bash @@ -154,7 +147,36 @@ Prerequisites for PDF In addition to the tools needed for building the HTML format manual, a working LaTeX installation with support for PDFLaTeX and a selection -of LaTeX styles/packages are required. To run the PDFLaTeX translation +of LaTeX styles/packages are required. Apart from LaTeX packages that +are usually installed by default, the following packages are required: + +.. table_from_list:: + :columns: 11 + + - amsmath + - anysize + - babel + - capt-of + - cmap + - dvipng + - ellipse + - fncychap + - fontawesome + - framed + - geometry + - gyre + - hyperref + - hypcap + - needspace + - pict2e + - times + - tabulary + - titlesec + - upquote + - wrapfig + - xindy + +To run the PDFLaTeX translation the ``latexmk`` script needs to be installed as well. Prerequisites for ePUB and MOBI @@ -182,12 +204,42 @@ documentation is required and either existing files in the ``src`` folder need to be updated or new files added. These files are written in `reStructuredText `_ markup for translation with the Sphinx tool. +Testing your contribution +^^^^^^^^^^^^^^^^^^^^^^^^^ + Before contributing any documentation, please check that both the HTML -and the PDF format documentation can translate without errors. During -testing the html translation, you may use the ``make fasthtml`` command -which does an approximate translation (i.e. not all Sphinx features and -extensions will work), but runs very fast because it will only translate -files that have been changed since the last ``make fasthtml`` command. +and the PDF format documentation can translate without errors and that +there are no spelling issues. This is done with ``make html``, ``make pdf``, +and ``make spelling``, respectively. + +Fast and approximate translation to HTML +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Translating the full manual to HTML or PDF can take a long time. Thus +there is a fast and approximate way to translate the reStructuredText to +HTML as a quick-n-dirty way of checking your manual page. + +This translation uses `Pandoc `_ instead of Sphinx +and thus all special Sphinx features (cross-references, advanced tables, +embedding of Python docstrings or doxygen documentation, and so on) will +not render correctly. Most embedded math should render correctly. This +is a **very fast** way to check the syntax and layout of a documentation +file translated to HTML while writing or updating it. + +To translate **all** manual pages, you can type ``make fasthtml`` at the +command line. The translated HTML files are then in the ``fasthtml`` +folder. All subsequent ``make fasthtml`` commands will only translate +``.rst`` files that have been changed. The ``make fasthtml`` command +can be parallelized with make using the `-j` flag. You can also +directly translate only individual pages: e.g. to translate only the +``doc/src/pair_lj.rst`` page type ``make fasthtml/pair_lj.html`` + +After writing the documentation is completed, you will still need +to verify with ``make html`` and ``make pdf`` that it translates +correctly in both formats. + +Tests for consistency, completeness, and other known issues +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Please also check the output to the console for any warnings or problems. There will be multiple tests run automatically: diff --git a/doc/src/Build_package.rst b/doc/src/Build_package.rst index 8b2da8ad30..c4c4889806 100644 --- a/doc/src/Build_package.rst +++ b/doc/src/Build_package.rst @@ -49,6 +49,7 @@ packages: * :ref:`LEPTON ` * :ref:`MACHDYN ` * :ref:`MDI ` + * :ref:`MISC ` * :ref:`ML-HDNNP ` * :ref:`ML-IAP ` * :ref:`ML-PACE ` diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst index e4a53ddee7..226e19bfc3 100644 --- a/doc/src/Build_settings.rst +++ b/doc/src/Build_settings.rst @@ -8,12 +8,13 @@ Optional build settings LAMMPS can be built with several optional settings. Each subsection explains how to do this for building both with CMake and make. -* `C++11 standard compliance`_ when building all of LAMMPS +* `C++11 and C++17 standard compliance`_ when building all of LAMMPS * `FFT library`_ for use with the :doc:`kspace_style pppm ` command * `Size of LAMMPS integer types and size limits`_ * `Read or write compressed files`_ * `Output of JPEG, PNG, and movie files`_ via the :doc:`dump image ` or :doc:`dump movie ` commands -* `Support for downloading files`_ +* `Support for downloading files from the input`_ +* `Prevent download of large potential files`_ * `Memory allocation alignment`_ * `Workaround for long long integers`_ * `Exception handling when using LAMMPS as a library`_ to capture errors @@ -23,14 +24,15 @@ explains how to do this for building both with CMake and make. .. _cxx11: -C++11 standard compliance -------------------------- +C++11 and C++17 standard compliance +----------------------------------- -A C++11 standard compatible compiler is a requirement for compiling LAMMPS. -LAMMPS version 3 March 2020 is the last version compatible with the previous -C++98 standard for the core code and most packages. Most currently used -C++ compilers are compatible with C++11, but some older ones may need extra -flags to enable C++11 compliance. Example for GNU c++ 4.8.x: +A C++11 standard compatible compiler is currently the minimum +requirement for compiling LAMMPS. LAMMPS version 3 March 2020 is the +last version compatible with the previous C++98 standard for the core +code and most packages. Most currently used C++ compilers are compatible +with C++11, but some older ones may need extra flags to enable C++11 +compliance. Example for GNU c++ 4.8.x: .. code-block:: make @@ -40,6 +42,17 @@ Individual packages may require compliance with a later C++ standard like C++14 or C++17. These requirements will be documented with the :doc:`individual packages `. +.. versionchanged:: 4Feb2025 + +Starting with LAMMPS version 4 February 2025 we are starting a +transition to require the C++17 standard. Most current compilers are +compatible and if the C++17 standard is available by default, LAMMPS +will enable C++17 and will compile normally. If the chosen compiler is +not compatible with C++17, but only supports C++11, then the define +-DLAMMPS_CXX11 is required to fall back to compiling with a C++11 +compiler. After the next stable release of LAMMPS in summer 2025, the +LAMMPS development branch and future releases will require C++17. + ---------- .. _fft: @@ -303,7 +316,7 @@ large counters can become before "rolling over". The default setting of .. code-block:: bash - -D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall + -D LAMMPS_SIZES=value # smallbig (default) or bigbig If the variable is not set explicitly, "smallbig" is used. @@ -314,7 +327,7 @@ large counters can become before "rolling over". The default setting of .. code-block:: make - LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL + LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG The default setting is ``-DLAMMPS_SMALLBIG`` if nothing is specified @@ -323,34 +336,27 @@ LAMMPS system size restrictions .. list-table:: :header-rows: 1 - :widths: 18 27 28 27 + :widths: 27 36 37 :align: center * - - smallbig - bigbig - - smallsmall * - Total atom count - :math:`2^{63}` atoms (= :math:`9.223 \cdot 10^{18}`) - :math:`2^{63}` atoms (= :math:`9.223 \cdot 10^{18}`) - - :math:`2^{31}` atoms (= :math:`2.147 \cdot 10^9`) * - Total timesteps - :math:`2^{63}` steps (= :math:`9.223 \cdot 10^{18}`) - :math:`2^{63}` steps (= :math:`9.223 \cdot 10^{18}`) - - :math:`2^{31}` steps (= :math:`2.147 \cdot 10^9`) * - Atom ID values - :math:`1 \le i \le 2^{31} (= 2.147 \cdot 10^9)` - :math:`1 \le i \le 2^{63} (= 9.223 \cdot 10^{18})` - - :math:`1 \le i \le 2^{31} (= 2.147 \cdot 10^9)` * - Image flag values - :math:`-512 \le i \le 511` - :math:`- 1\,048\,576 \le i \le 1\,048\,575` - - :math:`-512 \le i \le 511` The "bigbig" setting increases the size of image flags and atom IDs over -"smallbig" and the "smallsmall" setting is only needed if your machine -does not support 64-bit integers or incurs performance penalties when -using them. +the default "smallbig" setting. These are limits for the core of the LAMMPS code, specific features or some styles may impose additional limits. The :ref:`ATC @@ -504,8 +510,8 @@ during a run. .. _libcurl: -Support for downloading files ------------------------------ +Support for downloading files from the input +-------------------------------------------- .. versionadded:: 29Aug2024 @@ -548,6 +554,25 @@ LAMMPS is compiled accordingly which needs the following settings: ---------- +.. _download_pot: + +Prevent download of large potential files +----------------------------------------- + +.. versionadded:: 8Feb2023 + +LAMMPS bundles a selection of potential files in the ``potentials`` +folder as examples of how those kinds of potential files look like and +for use with the provided input examples in the ``examples`` tree. To +keep the size of the distributed LAMMPS source package small, very large +potential files (> 5 MBytes) are not bundled, but only downloaded on +demand when the :doc:`corresponding package ` is +installed. This automatic download can be prevented when :doc:`building +LAMMPS with CMake ` by adding the setting `-D +DOWNLOAD_POTENTIALS=off` when configuring. + +---------- + .. _align: Memory allocation alignment 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_bond.rst b/doc/src/Commands_bond.rst index 3be40a6158..05c505b5ee 100644 --- a/doc/src/Commands_bond.rst +++ b/doc/src/Commands_bond.rst @@ -23,6 +23,7 @@ OPT. * * :doc:`bpm/rotational ` * :doc:`bpm/spring ` + * :doc:`bpm/spring/plastic ` * :doc:`class2 (ko) ` * :doc:`fene (iko) ` * :doc:`fene/expand (o) ` @@ -90,6 +91,7 @@ OPT. * :doc:`lepton (o) ` * :doc:`mesocnt ` * :doc:`mm3 ` + * :doc:`mwlc ` * :doc:`quartic (o) ` * :doc:`spica (ko) ` * :doc:`table (o) ` diff --git a/doc/src/Commands_compute.rst b/doc/src/Commands_compute.rst index fd68ce3e39..b53d9d6820 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 ` @@ -177,6 +178,7 @@ KOKKOS, o = OPENMP, t = OPT. * :doc:`ti ` * :doc:`torque/chunk ` * :doc:`vacf ` + * :doc:`vacf/chunk ` * :doc:`vcm/chunk ` * :doc:`viscosity/cos ` * :doc:`voronoi/atom ` diff --git a/doc/src/Commands_fix.rst b/doc/src/Commands_fix.rst index 04d1a9969a..ed9bf6429b 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) ` @@ -161,6 +162,8 @@ OPT. * :doc:`phonon ` * :doc:`pimd/langevin ` * :doc:`pimd/nvt ` + * :doc:`pimd/langevin/bosonic ` + * :doc:`pimd/nvt/bosonic ` * :doc:`planeforce ` * :doc:`plumed ` * :doc:`poems ` 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 777be3bf16..cb67a3d07d 100644 --- a/doc/src/Commands_removed.rst +++ b/doc/src/Commands_removed.rst @@ -1,6 +1,10 @@ Removed commands and packages ============================= +.. contents:: + +------ + This page lists LAMMPS commands and packages that have been removed from the distribution and provides suggestions for alternatives or replacements. LAMMPS has special dummy styles implemented, that will @@ -8,94 +12,32 @@ stop LAMMPS and print a suitable error message in most cases, when a style/command is used that has been removed or will replace the command with the direct alternative (if available) and print a warning. -restart2data tool ------------------ - -.. versionchanged:: 23Nov2013 - -The functionality of the restart2data tool has been folded into the -LAMMPS executable directly instead of having a separate tool. A -combination of the commands :doc:`read_restart ` and -:doc:`write_data ` can be used to the same effect. For -added convenience this conversion can also be triggered by -:doc:`command-line flags ` - -Fix ave/spatial and fix ave/spatial/sphere ------------------------------------------- - -.. deprecated:: 11Dec2015 - -The fixes ave/spatial and ave/spatial/sphere have been removed from LAMMPS -since they were superseded by the more general and extensible "chunk -infrastructure". Here the system is partitioned in one of many possible -ways through the :doc:`compute chunk/atom ` command -and then averaging is done using :doc:`fix ave/chunk `. -Please refer to the :doc:`chunk HOWTO ` section for an overview. - -Box command ------------ - -.. deprecated:: 22Dec2022 - -The *box* command has been removed and the LAMMPS code changed so it won't -be needed. If present, LAMMPS will ignore the command and print a warning. - -Reset_ids, reset_atom_ids, reset_mol_ids commands -------------------------------------------------- - -.. deprecated:: 22Dec2022 - -The *reset_ids*, *reset_atom_ids*, and *reset_mol_ids* commands have -been folded into the :doc:`reset_atoms ` command. If -present, LAMMPS will replace the commands accordingly and print a -warning. - -LATTE package -------------- - -.. deprecated:: 15Jun2023 - -The LATTE package with the fix latte command was removed from LAMMPS. -This functionality has been superseded by :doc:`fix mdi/qm ` -and :doc:`fix mdi/qmmm ` from the :ref:`MDI package -`. These fixes are compatible with several quantum software -packages, including LATTE. See the ``examples/QUANTUM`` dir and the -:doc:`MDI coupling HOWTO ` page. MDI supports running LAMMPS -with LATTE as a plugin library (similar to the way fix latte worked), as -well as on a different set of MPI processors. - -MEAM package +LAMMPS shell ------------ -The MEAM package in Fortran has been replaced by a C++ implementation. -The code in the :ref:`MEAM package ` is a translation of the -Fortran code of MEAM into C++, which removes several restrictions -(e.g. there can be multiple instances in hybrid pair styles) and allows -for some optimizations leading to better performance. The pair style -:doc:`meam ` has the exact same syntax. For a transition -period the C++ version of MEAM was called USER-MEAMC so it could -coexist with the Fortran version. +.. versionchanged:: 29Aug2024 -Minimize style fire/old ------------------------ +The LAMMPS shell has been removed from the LAMMPS distribution. Users +are encouraged to use the :ref:`LAMMPS-GUI ` tool instead. -.. deprecated:: 8Feb2023 +i-PI tool +--------- -Minimize style *fire/old* has been removed. Its functionality can be -reproduced with *fire* with specific options. Please see the -:doc:`min_modify command ` documentation for details. +.. versionchanged:: 27Jun2024 -Pair style mesont/tpm, compute style mesont, atom style mesont --------------------------------------------------------------- +The i-PI tool has been removed from the LAMMPS distribution. Instead, +instructions to install i-PI from PyPI via pip are provided. -.. deprecated:: 8Feb2023 +USER-REAXC package +------------------ -Pair style *mesont/tpm*, compute style *mesont*, and atom style -*mesont* have been removed from the :ref:`MESONT package `. -The same functionality is available through -:doc:`pair style mesocnt `, -:doc:`bond style mesocnt ` and -:doc:`angle style mesocnt `. +.. deprecated:: 7Feb2024 + +The USER-REAXC package has been renamed to :ref:`REAXFF `. +In the process also the pair style and related fixes were renamed to use +the "reaxff" string instead of "reax/c". For a while LAMMPS was maintaining +backward compatibility by providing aliases for the styles. These have +been removed, so using "reaxff" is now *required*. MPIIO package ------------- @@ -115,7 +57,6 @@ Similarly, the "nfile" and "fileper" keywords exist for restarts: see :doc:`restart `, :doc:`read_restart `, :doc:`write_restart `. - MSCG package ------------ @@ -126,9 +67,73 @@ for many years and instead superseded by the `OpenMSCG software `_ of the Voth group at the University of Chicago, which can be used independent from LAMMPS. +LATTE package +------------- + +.. deprecated:: 15Jun2023 + +The LATTE package with the fix latte command was removed from LAMMPS. +This functionality has been superseded by :doc:`fix mdi/qm ` +and :doc:`fix mdi/qmmm ` from the :ref:`MDI package +`. These fixes are compatible with several quantum software +packages, including LATTE. See the ``examples/QUANTUM`` dir and the +:doc:`MDI coupling HOWTO ` page. MDI supports running LAMMPS +with LATTE as a plugin library (similar to the way fix latte worked), as +well as on a different set of MPI processors. + +Minimize style fire/old +----------------------- + +.. deprecated:: 8Feb2023 + +Minimize style *fire/old* has been removed. Its functionality can be +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 +-------------------------------------------------------------- + +.. deprecated:: 8Feb2023 + +Pair style *mesont/tpm*, compute style *mesont*, and atom style +*mesont* have been removed from the :ref:`MESONT package `. +The same functionality is available through +:doc:`pair style mesocnt `, +:doc:`bond style mesocnt ` and +:doc:`angle style mesocnt `. + +Box command +----------- + +.. deprecated:: 22Dec2022 + +The *box* command has been removed and the LAMMPS code changed so it won't +be needed. If present, LAMMPS will ignore the command and print a warning. + +Reset_ids, reset_atom_ids, reset_mol_ids commands +------------------------------------------------- + +.. deprecated:: 22Dec2022 + +The *reset_ids*, *reset_atom_ids*, and *reset_mol_ids* commands have +been folded into the :doc:`reset_atoms ` command. If +present, LAMMPS will replace the commands accordingly and print a +warning. + +MESSAGE package +--------------- + +.. deprecated:: 4May2022 + +The MESSAGE package has been removed since it was superseded by the +:ref:`MDI package `. MDI implements the same functionality +and in a more general way with direct support for more applications. + REAX package ------------ +.. deprecated:: 4Jan2019 + The REAX package has been removed since it was superseded by the :ref:`REAXFF package `. The REAXFF package has been tested to yield equivalent results to the REAX package, offers better @@ -138,20 +143,25 @@ syntax compatible with the removed reax pair style, so input files will have to be adapted. The REAXFF package was originally called USER-REAXC. -USER-REAXC package ------------------- +MEAM package +------------ -.. deprecated:: 7Feb2024 +.. deprecated:: 4Jan2019 -The USER-REAXC package has been renamed to :ref:`REAXFF `. -In the process also the pair style and related fixes were renamed to use -the "reaxff" string instead of "reax/c". For a while LAMMPS was maintaining -backward compatibility by providing aliases for the styles. These have -been removed, so using "reaxff" is now *required*. +The MEAM package in Fortran has been replaced by a C++ implementation. +The code in the :ref:`MEAM package ` is a translation of the +Fortran code of MEAM into C++, which removes several restrictions +(e.g. there can be multiple instances in hybrid pair styles) and allows +for some optimizations leading to better performance. The pair style +:doc:`meam ` has the exact same syntax. For a transition +period the C++ version of MEAM was called USER-MEAMC so it could +coexist with the Fortran version. USER-CUDA package ----------------- +.. deprecated:: 31May2016 + The USER-CUDA package had been removed, since it had been unmaintained for a long time and had known bugs and problems. Significant parts of the design were transferred to the @@ -160,19 +170,39 @@ performance characteristics on NVIDIA GPUs. Both, the KOKKOS and the :ref:`GPU package ` are maintained and allow running LAMMPS with GPU acceleration. -i-PI tool ---------- +Compute atom/molecule +_____________________ -.. versionchanged:: 27Jun2024 +.. deprecated:: 11 Dec2015 -The i-PI tool has been removed from the LAMMPS distribution. Instead, -instructions to install i-PI from PyPI via pip are provided. +The atom/molecule command has been removed from LAMMPS since it was superseded +by the more general and extensible "chunk infrastructure". Here the system is +partitioned in one of many possible ways - including using molecule IDs - +through the :doc:`compute chunk/atom ` command and then +summing is done using :doc:`compute reduce/chunk ` Please +refer to the :doc:`chunk HOWTO ` section for an overview. -LAMMPS shell ------------- +Fix ave/spatial and fix ave/spatial/sphere +------------------------------------------ -.. versionchanged:: 29Aug2024 +.. deprecated:: 11Dec2015 -The LAMMPS shell has been removed from the LAMMPS distribution. Users -are encouraged to use the :ref:`LAMMPS-GUI ` tool instead. +The fixes ave/spatial and ave/spatial/sphere have been removed from LAMMPS +since they were superseded by the more general and extensible "chunk +infrastructure". Here the system is partitioned in one of many possible +ways through the :doc:`compute chunk/atom ` command +and then averaging is done using :doc:`fix ave/chunk `. +Please refer to the :doc:`chunk HOWTO ` section for an overview. + +restart2data tool +----------------- + +.. deprecated:: 23Nov2013 + +The functionality of the restart2data tool has been folded into the +LAMMPS executable directly instead of having a separate tool. A +combination of the commands :doc:`read_restart ` and +:doc:`write_data ` can be used to the same effect. For +added convenience this conversion can also be triggered by +:doc:`command-line flags ` diff --git a/doc/src/Developer.rst b/doc/src/Developer.rst index b0cfcc14fc..d4afd6f298 100644 --- a/doc/src/Developer.rst +++ b/doc/src/Developer.rst @@ -24,4 +24,5 @@ of time and requests from the LAMMPS user community. Classes Developer_platform Developer_utils + Developer_internal Developer_grid 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_internal.rst b/doc/src/Developer_internal.rst new file mode 100644 index 0000000000..739422d8b7 --- /dev/null +++ b/doc/src/Developer_internal.rst @@ -0,0 +1,113 @@ + +Internal Styles +--------------- + +LAMMPS has a number of styles that are not meant to be used in an input +file and thus are not documented in the :doc:`LAMMPS command +documentation `. The differentiation between user +commands and internal commands is through the case of the command name: +user commands and styles are all lower case, internal styles are all +upper case. Internal styles are not called from the input file, but +their classes are instantiated by other styles. Often they are +created by other styles to store internal data or to perform actions +regularly at specific steps of the simulation. + +The paragraphs below document some of those styles that have general +utility and may be used to avoid redundant implementation. + +DEPRECATED Styles +^^^^^^^^^^^^^^^^^ + +The styles called DEPRECATED (e.g. pair, bond, fix, compute, region, etc.) +have the purpose to inform users that a specific style has been removed +or renamed. This is achieved by creating an alias for the deprecated +style to the corresponding class. For example, the fix style DEPRECATED +is aliased to fix style ave/spatial and fix style ave/spatial/sphere with +the following code: + +.. code-block:: c++ + + FixStyle(DEPRECATED,FixDeprecated); + FixStyle(ave/spatial,FixDeprecated); + FixStyle(ave/spatial/sphere,FixDeprecated); + +The individual class will then determine based on the style name +what action to perform: + +- inform that the style has been removed and what style replaces it, if any, and then error out +- inform that the style has been renamed and then either execute the replacement or error out +- inform that the style is no longer required, and it is thus ignored and continue + +There is also a section in the user's guide for :doc:`removed commands +and packages ` with additional explanations. + +Internal fix styles +^^^^^^^^^^^^^^^^^^^ + +fix DUMMY +""""""""" + +Most fix classes cannot be instantiated before the simulation box has +been created since they access data that is only available then. +However, in some cases it is required that a fix must be at or close to +the top of the list of all fixes. In those cases an instance of the +DUMMY fix style may be created by calling ``Modify::add_fix()`` and then +later replaced by calling ``Modify::replace_fix()``. + +fix STORE/ATOM +"""""""""""""" + +Fix STORE/ATOM can be used as persistent storage of per-atom data. + +**Syntax** + +.. code-block:: LAMMPS + + fix ID group-ID STORE/ATOM N1 N2 gflag rflag + +* ID, group-ID are documented in :doc:`fix ` command +* STORE/ATOM = style name of this fix command +* N1 = 1, N2 = 0 : data is per-atom vector = single value per atom +* N1 > 1, N2 = 0 : data is per-atom array = N1 values per atom +* N1 > 0, N2 > 0 : data is per-atom tensor = N1xN2 values per atom +* gflag = 1 communicate per-atom values with ghost atoms, 0 do not update ghost atom data +* rflag = 1 store per-atom value in restart file, 0 do not store data in restart + +Similar functionality is also available through using custom per-atom +properties with :doc:`fix property/atom `. The +choice between the two fixes should be based on whether the user should +be able to access this per-atom data: if yes, then fix property/atom is +preferred, otherwise fix STORE/ATOM. + +fix STORE/GLOBAL +"""""""""""""""" + +Fix STORE/GLOBAL can be used as persistent storage of global data with support for restarts + +**Syntax** + +.. code-block:: LAMMPS + + fix ID group-ID STORE/GLOBAL N1 N2 + +* ID, group-ID are documented in :doc:`fix ` command +* STORE/GLOBAL = style name of this fix command +* N1 >=1 : number of global items to store +* N2 = 1 : data is global vector of length N1 +* N2 > 1 : data is global N1xN2 array + +fix STORE/LOCAL +""""""""""""""" + +Fix STORE/LOCAL can be used as persistent storage for local data + +**Syntax** + +.. code-block:: LAMMPS + + fix ID group-ID STORE/LOCAL Nreset Nvalues + +* ID, group-ID are documented in :doc:`fix ` command +* STORE/LOCAL = style name of this fix command +* Nreset = frequency at which local data is available +* Nvalues = number of values per local item, that is the number of columns 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_unittest.rst b/doc/src/Developer_unittest.rst index 86526b19de..bee0c45480 100644 --- a/doc/src/Developer_unittest.rst +++ b/doc/src/Developer_unittest.rst @@ -227,12 +227,12 @@ Tests for the C-style library interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Tests for validating the LAMMPS C-style library interface are in the -``unittest/c-library`` folder. They are implemented either to be used -for utility functions or for LAMMPS commands, but use the functions -implemented in the ``src/library.cpp`` file as much as possible. There -may be some overlap with other tests, but only in as much as is required -to test the C-style library API. The tests are distributed over -multiple test programs which try to match the grouping of the +``unittest/c-library`` folder. They text either utility functions or +LAMMPS commands, but use the functions implemented in +``src/library.cpp`` as much as possible. There may be some overlap with +other tests as far as the LAMMPS functionality is concerned, but the +focus is on testing the C-style library API. The tests are distributed +over multiple test programs which try to match the grouping of the functions in the source code and :ref:`in the manual `. This group of tests also includes tests invoking LAMMPS in parallel @@ -258,7 +258,7 @@ Tests for the Python module and package The ``unittest/python`` folder contains primarily tests for classes and functions in the LAMMPS python module but also for commands in the -PYTHON package. These tests are only enabled if the necessary +PYTHON package. These tests are only enabled, if the necessary prerequisites are detected or enabled during configuration and compilation of LAMMPS (shared library build enabled, Python interpreter found, Python development files found). @@ -272,29 +272,30 @@ Tests for the Fortran interface Tests for using the Fortran module are in the ``unittest/fortran`` folder. Since they are also using the GoogleTest library, they require -implementing test wrappers in C++ that will call fortran functions -which provide a C function interface through ISO_C_BINDINGS that will in -turn call the functions in the LAMMPS Fortran module. +test wrappers written in C++ that will call fortran functions with a C +function interface through ISO_C_BINDINGS which will in turn call the +functions in the LAMMPS Fortran module. Tests for the C++-style library interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The tests in the ``unittest/cplusplus`` folder are somewhat similar to the tests for the C-style library interface, but do not need to test the -several convenience and utility functions that are only available through -the C-style interface. Instead it can focus on the more generic features -that are used internally. This part of the unit tests is currently still -mostly in the planning stage. +convenience and utility functions that are only available through the +C-style library interface. Instead they focus on the more generic +features that are used in LAMMPS internally. This part of the unit +tests is currently still mostly in the planning stage. Tests for reading and writing file formats ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``unittest/formats`` folder contains test programs for reading and -writing files like data files, restart files, potential files or dump files. -This covers simple things like the file i/o convenience functions in the -``utils::`` namespace to complex tests of atom styles where creating and -deleting atoms with different properties is tested in different ways -and through script commands or reading and writing of data or restart files. +writing files like data files, restart files, potential files or dump +files. This covers simple things like the file i/o convenience +functions in the ``utils::`` namespace to complex tests of atom styles +where creating and deleting of atoms with different properties is tested +in different ways and through script commands or reading and writing of +data or restart files. Tests for styles computing or modifying forces ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -443,7 +444,7 @@ file for a style that is similar to one to be tested. The file name should follow the naming conventions described above and after copying the file, the first step is to replace the style names where needed. The coefficient values do not have to be meaningful, just in a reasonable range for the -given system. It does not matter if some forces are large, as long as +given system. It does not matter if some forces are large, for as long as they do not diverge. The template input files define a large number of index variables at the top @@ -531,19 +532,20 @@ Python module. Troubleshooting failed unit tests ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The are by default no unit tests for newly added features (e.g. pair, fix, -or compute styles) unless your pull request also includes tests for the -added features. If you are modifying some features, you may see failures -for existing tests, if your modifications have some unexpected side effects -or your changes render the existing test invalid. If you are adding an -accelerated version of an existing style, then only tests for INTEL, -KOKKOS (with OpenMP only), OPENMP, and OPT will be run automatically. -Tests for the GPU package are time consuming and thus are only run -*after* a merge, or when a special label, ``gpu_unit_tests`` is added -to the pull request. After the test has started, it is often best to -remove the label since every PR activity will re-trigger the test (that -is a limitation of triggering a test with a label). Support for unit -tests when using KOKKOS with GPU acceleration is currently not supported. +There are by default no unit tests for newly added features (e.g. pair, +fix, or compute styles) unless your pull request also includes tests for +these added features. If you are modifying some existing LAMMPS +features, you may see failures for existing tests, if your modifications +have some unexpected side effects or your changes render the existing +test invalid. If you are adding an accelerated version of an existing +style, then only tests for INTEL, KOKKOS (with OpenMP only), OPENMP, and +OPT will be run automatically. Tests for the GPU package are time +consuming and thus are only run *after* a merge, or when a special +label, ``gpu_unit_tests`` is added to the pull request. After the test +has started, it is often best to remove the label since every PR +activity will re-trigger the test (that is a limitation of triggering a +test with a label). Support for unit tests using KOKKOS with GPU +acceleration is currently not supported. When you see a failed build on GitHub, click on ``Details`` to be taken to the corresponding LAMMPS Jenkins CI web page. Click on the "Exit" @@ -588,7 +590,7 @@ While the epsilon (relative precision) for a single, `IEEE 754 compliant `_, double precision floating point operation is at about 2.2e-16, the achievable precision for the tests is lower due to most numbers being sums over intermediate results -and the non-associativity of floating point math leading to larger +for which the non-associativity of floating point math leads to larger errors. As a rule of thumb, the test epsilon can often be in the range 5.0e-14 to 1.0e-13. But for "noisy" force kernels, e.g. those a larger amount of arithmetic operations involving `exp()`, `log()` or `sin()` @@ -602,7 +604,7 @@ of floating point operations or that some or most intermediate operations may be done using approximations or with single precision floating point math. -To rerun the failed unit test individually, change to the ``build`` directory +To rerun a failed unit test individually, change to the ``build`` directory and run the test with verbose output. For example, .. code-block:: bash 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_debug.rst b/doc/src/Errors_debug.rst index cc28273aa3..61fb1f7525 100644 --- a/doc/src/Errors_debug.rst +++ b/doc/src/Errors_debug.rst @@ -235,3 +235,53 @@ from GDB. In addition you get a more specific hint about what cause the segmentation fault, i.e. that it is a NULL pointer dereference. To find out which pointer exactly was NULL, you need to use the debugger, though. +Debugging when LAMMPS appears to be stuck +========================================= + +Sometimes the LAMMPS calculation appears to be stuck, that is the LAMMPS +process or processes are active, but there is no visible progress. This +can have multiple reasons: + +- The selected styles are slow and require a lot of CPU time and the + system is large. When extrapolating the expected speed from smaller + systems, one has to factor in that not all models scale linearly with + system size, e.g. :doc:`kspace styles like ewald or pppm + `. There is very little that can be done in this case. +- The output interval is not set or set to a large value with the + :doc:`thermo ` command. I the first case, there will be output + only at the first and last step. +- The output is block-buffered and instead of line-buffered. The output + will only be written to the screen after 4096 or 8192 characters of + output have accumulated. This most often happens for files but also + with MPI parallel executables for output to the screen, since the + output to the screen is handled by the MPI library so that output from + all processes can be shown. This can be suppressed by using the + ``-nonblock`` or ``-nb`` command-line flag, which turns off buffering + for screen and logfile output. +- An MPI parallel calculation has a bug where a collective MPI function + is called (e.g. ``MPI_Barrier()``, ``MPI_Bcast()``, + ``MPI_Allreduce()`` and so on) before pending point-to-point + communications are completed or when the collective function is only + called from a subset of the MPI processes. This also applies to some + internal LAMMPS functions like ``Error::all()`` which uses + ``MPI_Barrier()`` and thus ``Error::one()`` must be called, if the + error condition does not happen on all MPI processes simultaneously. +- Some function in LAMMPS has a bug where a ``for`` or ``while`` loop + does not trigger the exit condition and thus will loop forever. This + can happen when the wrong variable is incremented or when one value in + a comparison becomes ``NaN`` due to an overflow. + +In the latter two cases, further information and stack traces (see above) +can be obtain by attaching a debugger to a running process. For that the +process ID (PID) is needed; this can be found on Linux machines with the +``top``, ``htop``, ``ps``, or ``pstree`` commands. + +Then running the (GNU) debugger ``gdb`` with the ``-p`` flag followed by +the process id will attach the process to the debugger and stop +execution of that specific process. From there on it is possible to +issue all debugger commands in the same way as when LAMMPS was started +from the debugger (see above). Most importantly it is possible to +obtain a stack trace with the ``where`` command and thus determine where +in the execution of a timestep this process is. Also internal data can +be printed and execution single stepped or continued. When the debugger +is exited, the calculation will resume normally. diff --git a/doc/src/Errors_details.rst b/doc/src/Errors_details.rst index 09f3d893db..c94d96b405 100644 --- a/doc/src/Errors_details.rst +++ b/doc/src/Errors_details.rst @@ -1,12 +1,244 @@ -Error and warning details -========================= +Errors and warnings 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. +Many errors and warnings that LAMMPS outputs are self-explanatory and +thus straightforward to resolve. However, there are also cases where +there is no single cause or simple explanation that can be provided in a +short message printed by LAMMPS. Therefore, more detailed discussions +of such scenarios are provided here; first on a more general level and +then for specific errors. In the latter cases, LAMMPS will output a +short message and then provide a URL that links to a specific section on +this page. + +.. contents:: + +------ + +General troubleshooting advice +------------------------------ + +Below are suggestions that can help to understand the causes of problems +with simulations leading to errors or unexpected results. + +.. _hint01: + +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. + +.. _hint02: + +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). + +.. _hint03: + +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. + +.. _hint04: + +Segmentation Fault +^^^^^^^^^^^^^^^^^^ + +A segmentation fault is an error reported by the **operating system** +and not LAMMPS itself. It happens when a process tries to access a +memory address that is not available. This can have **many** reasons: +memory has not been allocated, a memory buffer is not large enough, a +memory address is computed from an incorrect index, a memory buffer is +used after it has been freed, some general memory corruption. When +investigating a segmentation fault (aka segfault), it is important to +determine which process is causing it; it may not always be LAMMPS. For +example, some MPI library implementations report a segmentation fault +from their "mpirun" or "mpiexec" command when the application has been +terminated unexpectedly. + +While a segmentation fault is likely an indication of a bug in LAMMPS, +it need not always be; it can also be the consequence of too aggressive +simulation settings. For time critical code paths, LAMMPS will assume +the user has chosen the settings carefully and will not make any checks +to avoid to avoid performance penalties. + +A crucial step in resolving a segmentation fault is to identify the +exact location in the code where it happens. Please see `Errors_debug` +for a couple of examples showing how to do this on a Linux machine. +With this information -- a simple way to reproduce the segmentation +fault and the exact :doc:`LAMMPS version ` and platform +you are running on -- you can contact the LAMMPS developers or post in +the LAMMPS forum to get assistance. + +.. _hint05: + +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 a 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 run depends on the steepness of the +potential function and their mass. Since the positions and velocities +of atoms are computed with finite timesteps, the timestep needs to be +small enough for stable numeric integration of the trajectory. If the +timestep is too large during initialization (or other instances of +extreme dynamics), using :doc:`fix nve/limit ` or +:doc:`fix dt/reset ` temporarily can help to avoid too +large updates or adapt the timestep according to the displacements. + +.. _hint06: + +Ignoring lost atoms +^^^^^^^^^^^^^^^^^^^ + +It is tempting to use the :doc:`thermo_modify lost ignore +` to avoid LAMMPS aborting with an error on lost atoms. +This setting should, however, *only* be used when atoms *should* leave +the system. In general, ignoring a problem does not solve it. + +.. _hint07: + +Pressure, forces, positions becoming NaN or 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. + +.. _hint08: + +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 typically be sufficient for all bonded +interactions. But if the pair style cutoff is small, this may not be +enough. LAMMPS will print a warning in this case using some heuristic +based on the equilibrium bond length, but that still 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. + +.. _hint09: + +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. + +.. _hint10: + +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. + +.. _hint11: + +No error message printed +^^^^^^^^^^^^^^^^^^^^^^^^ + +In some cases -- especially when running in parallel with MPI -- LAMMPS +may stop without displaying an error. But the fact that nothing was +displayed does not mean there was not an 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. + +.. _hint12: + +Errors before or after the simulation box is created +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As critical step in a LAMMPS input is when the simulation box is +defined, either with a :doc:`create_box command `, a +:doc:`read_data command `, or a :doc:`read_restart command +`. After this step, certain settings are locked in (e.g. +units, or number of atom, bond, angle, dihedral, improper types) and +cannot be changed after that. Consequently, commands that change such +settings (e.g. :doc:`units `) are only allowed before the box is +defined. Very few commands can be used before and after, like +:doc:`pair_style ` (but not :doc:`pair_coeff `). +Most LAMMPS commands must be used after the simulation box is created. + +Consequently, LAMMPS will stop with an error, if a command is used in +the wrong place. This is not always obvious. So index or string style +:doc:`variables ` can be expanded anywhere in the input, but +equal style (or similar) variables can only be expanded before the box +is defined if they do not reference anything that cannot be defined +before the box (e.g. a compute or fix reference or a thermo keyword). + +------ .. _err0001: @@ -23,19 +255,20 @@ The header section informs LAMMPS how many entries or lines are expected in the various sections (like Atoms, Masses, Pair Coeffs, *etc.*\ ) of the data file. If there is a mismatch, LAMMPS will either keep reading beyond the end of a section or stop reading before the section has -ended. In that case the next line will not contain a recognized keyword. +ended. In that case the next line will not contain a recognized +keyword. -Such a mismatch can also happen when the first line of the data -is *not* a comment as required by the format, but a line with a valid -header keyword. That would result in LAMMPS expecting, for instance, -0 atoms because the "atoms" header line is the first line and thus -treated as a comment. +Such a mismatch can also happen when the first line of the data is *not* +a comment as required by the format, but a line with a valid header +keyword. That would result in LAMMPS expecting, for instance, 0 atoms +because the "atoms" header line is the first line and thus treated as a +comment. Another possibility to trigger this error is to have a keyword in the data file that corresponds to a fix (e.g. :doc:`fix cmap `) but the :doc:`read_data ` command is missing the (optional) -arguments that identify the fix and the header keyword and section -keyword or those arguments are inconsistent with the keywords in the +arguments that identify the fix and its header and section keywords. +Alternatively, those arguments are inconsistent with the keywords in the data file. .. _err0002: @@ -45,35 +278,676 @@ Incorrect format in ... section of data file This error happens when LAMMPS reads the contents of a section of a :doc:`data file ` and the number of parameters in the line -differs from what is expected. This most commonly happens, when the -atom style is different from what is expected for a specific data file -since changing the atom style usually changes the format of the line. +differs from what is expected. This most commonly happens when the atom +style is different from what is expected for a specific data file since +changing the atom style usually changes the format of the line. -This error can also happen when the number of entries indicated in the +This error can also occur when the number of entries indicated in the header of a data file (e.g. the number of atoms) is larger than the number of lines provided (e.g. in the corresponding Atoms section) -and then LAMMPS will continue reading into the next section and that -would have a completely different format. +causing LAMMPS to continue reading into the next section which has a +completely different format. .. _err0003: Illegal variable command: expected X arguments but found Y ---------------------------------------------------------- -This error indicates that there are the wrong number of arguments for a -specific variable command, but a common reason for that is a variable -expression that has whitespace but is not enclosed in single or double -quotes. +This error indicates that a variable command has the wrong number of +arguments. A common reason for this is that the variable expression has +whitespace, but is not enclosed in single or double quotes. To explain, the LAMMPS input parser reads and processes lines. The resulting line is broken down into "words". Those are usually -individual commands, labels, names, values separated by whitespace (a -space or tab character). For "words" that may contain whitespace, they -have to be enclosed in single (') or double (") quotes. The parser will -then remove the outermost pair of quotes and then pass that string as +individual commands, labels, names, and values separated by whitespace +(a space or tab character). For "words" that may contain whitespace, +they have to be enclosed in single (') or double (") quotes. The parser +will then remove the outermost pair of quotes and pass that string as "word" to the variable command. -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. +Thus missing quotes or accidental extra whitespace will trigger this +error 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 need to assemble a grid of +electron density data derived from the (partial) charges assigned to the +atoms. These 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. The processor's grid 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, +the neighbor list skin is too small, or the neighbor lists are not +updated frequently enough. The smeared charges cannot then 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, 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. +Otherwise one can 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. + +.. _err0005: + +Bond (or angle, dihedral, improper, cmap, or shake) atoms missing +----------------------------------------------------------------- + +The second atom needed to compute a particular bond (or the third or +fourth atom for angle, dihedral, or improper) is missing on the +indicated timestep and processor. Typically, this is because the two +bonded atoms have become too far apart relative to the communication +cutoff distance for ghost atoms. By default, the communication cutoff +is set by the pair cutoff. However, to accommodate larger distances +between topologically connected atoms, it can be manually adjusted using +:doc:`comm_modify ` at the cost of increased communication +and more ghost atoms. However, missing bond atoms may also indicate +that there are unstable dynamics which caused the atoms to blow apart. +In this scenario, increasing the communication distance will not solve +the underlying issue. Rather, see :ref:`Fast moving atoms ` and +:ref:`Neighbor list settings ` in the general troubleshooting +section above for ideas to fix unstable dynamics. + +If atoms are intended to be lost during a simulation (e.g. due to open +boundary conditions or :doc:`fix evaporate `) such that +two bonded atoms may be lost at different times from each other, this +error can be converted to a warning or turned off using the *lost/bond* +keyword in the :doc:`thermo_modify ` command. + +.. _err0006: + +Non-numeric atom coords or pressure or box dimensions - simulation unstable +--------------------------------------------------------------------------- + +This error usually occurs due to overly aggressive simulation settings +or issues with the system geometry or the potential. See +:ref:`Pressure, forces, positions becoming NaN or Inf ` above in +the general troubleshooting section. This error is more likely to +happen during equilibration, so it can help to do a minimization before +or even add a second or third minimization after running a few +equilibration MD steps. It also is more likely when directly using a +Nose-Hoover (or other) barostat, and thus it may be advisable to run +with only a thermostat for a bit until the potential energy has +stabilized. + +.. _err007: + +Fix used in ... not computed at compatible time +----------------------------------------------- + +Many fix styles are invoked only every *nevery* timesteps, which means +their data is only valid on those steps. When data from a fix is used +as input for a compute, a dump, another fix, or thermo output, it must +read that data at timesteps when the fix in question was invoked, i.e. +on timesteps that are multiples of its *nevery* setting. If this is not +the case, LAMMPS will stop with an error. To remedy this, it may be +required to change the output frequency or the *nevery* setting of the +fix. + +.. _err0008: + +Lost atoms ... +-------------- + +A simulation stopping with an error due to lost atoms can have multiple +causes. By default, LAMMPS checks for whether the total number of atoms +is consistent with the sum of atoms "owned" by MPI processors every time +that thermodynamic output is written. In the majority of cases, lost +atoms are unexpected and a result of extremely high velocities causing +instabilities in the system. Such velocities can result from a variety +of issues. For ideas on how to track down issues with unexpected lost +atoms, see :ref:`Fast moving atoms ` and :ref:`Neighbor list +settings ` in the general troubleshooting section above. In +specific situations however, losing atoms is expected material behavior +(e.g. with sputtering and surface evaporation simulations), and an +unwanted crash can be avoided by changing the :doc:`thermo_modify lost +` keyword from the default 'error' to 'warn' or 'ignore' +(though heed the advice in :ref:`Ignoring lost atoms ` above!). + +.. _err0009: + +Too many neighbor bins +---------------------- + +The simulation box is or has become too large relative to the size of a +neighbor bin (which in turn depends on the largest pair-wise cutoff by +default) such that LAMMPS is unable to store the needed number of bins. +This typically implies the simulation box has expanded too far. That +can occur 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. This can also happen if the largest pair-wise cutoff is +small. In this case, the error can be avoided by using the +:doc:`neigh_modify command ` to set the bin width to a +suitably large value. + +.. _err0010: + +Unrecognized ... style ... is part of ... package which is not enabled in this LAMMPS binary +-------------------------------------------------------------------------------------------- + +The LAMMPS executable (binary) being used was not compiled with a +package containing the specified style. This indicates that the +executable needs to be re-built after enabling the correct package in +the relevant Makefile or CMake build directory. See +:doc:`Section 3. Build LAMMPS ` for more details. One can check +if the expected package and pair style is present in the executable by +running it with the ``-help`` (or ``-h``) flag on the command line. One +common oversight, especially for beginner LAMMPS users, is enabling the +package but forgetting to run commands to rebuild (e.g., to run the +final ``make`` or ``cmake`` command). + +If this error occurs with an executable that the user does not control +(e.g., through a module on HPC clusters), the user will need to get in +contact with the relevant person or people who can update the +executable. + +.. _err011: + +Energy or stress was not tallied by pair style +---------------------------------------------- + +This warning can be printed by computes from the :ref:`TALLY package +`. Those use a callback mechanism that only work for regular +pair-wise additive pair styles like :doc:`Lennard-Jones `, +:doc:`Morse `, :doc:`Born-Meyer-Huggins `, and +similar. Such required callbacks have not been implemented for +many-body potentials so one would have to implement them to add +compatibility with these computes (which may be difficult to do in a +generic fashion). Whether this warning indicates that contributions to +the computed properties are missing depends on the groups used. At any +rate, careful testing of the results is advised when this warning +appears. + +.. _err0012: + +fmt::format_error +----------------- + +LAMMPS uses the `{fmt} library `_ for advanced string +formatting tasks. This is similar to the ``printf()`` family of +functions from the standard C library, but more flexible. If there is a +bug in the LAMMPS code and the format string does not match the list of +arguments or has some other error, this error message will be shown. +You should contact the LAMMPS developers and report the bug as a `GitHub +Bug Report Issue `_ along with +sufficient information to easily reproduce it. + + +.. _err0013: + +Substitution for illegal variable +--------------------------------- + +A variable in an input script or a variable expression was not found in +the list of valid variables. The most common reason for this is a typo +somewhere in the input file such that the expression uses an invalid +variable name. The second most common reason is omitting the curly +braces for a direct variable with a name that is not a single letter. +For example: + +.. code-block:: LAMMPS + + variable cutoff index 10.0 + pair_style lj/cut ${cutoff} # this is correct + pair_style lj/cut $cutoff # this is incorrect, LAMMPS looks for 'c' instead of 'cutoff' + variable c index 5.0 # if $c is defined, LAMMPS subsitutes only '$c' and reads: 5utoff + +Another potential source of this error may be invalid command line +variables (-var or -v argument) used when launching LAMMPS from an +interactive shell or shell scripts. An uncommon source for this error +is using the :doc:`next command ` to advance through a list of +values provided by an index style variable. If there is no remaining +element in the list, LAMMPS will delete the variable and any following +expansion or reference attempt will trigger the error. + +Users with harder-to-track variable errors might also find reading the +:doc:`Parsing rules for input scripts ` helpful. + +.. _err0014: + +Bond atom missing in image check or box size check +-------------------------------------------------- + +This can be either an error or a warning depending on your +:doc:`thermo_modify settings `. It is flagged in a part +of the LAMMPS code where it updates the domain decomposition and before +it builds the neighbor lists. It checks that both atoms of a bond are +within the communication cutoff of a subdomain. It is usually caused by +atoms moving too fast (see the :ref:`paragraph on fast moving atoms +`), or by the :doc:`communication cutoff being too small +`, or by waiting too long between :doc:`sub-domain and +neighbor list updates `. + +.. _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. + +.. _err0016: + +Did not assign all atoms correctly +---------------------------------- + +This error happens most commonly when :doc:`reading a data file +` under :doc:`non-periodic boundary conditions`. +Only atoms with positions **inside** the simulation box will be read and +thus any atoms outside the box will be skipped and the total atom count +will not match, which triggers the error. This does not happen with +periodic boundary conditions where atoms outside the principal box will +be "wrapped" into the principal box and their image flags set +accordingly. + +Similar errors can happen with the :doc:`replicate command` +or the :doc:`read_restart command`. In these cases the +cause may be a problematic geometry, an insufficient communication +cutoff, or a bug in the LAMMPS source code. In these cases it is +advisable to set up :ref:`small test case ` for testing and +debugging. This will be required in case you need to get help from a +LAMMPS developer. + +.. _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 a great distance out of +the simulation box or a fix (like fix deform or a barostat) has +excessively grown the simulation box. + +.. _err0018: + +Step X: (h)bondchk failed +------------------------- + +This error is a consequence of the heuristic memory allocations for +buffers of the regular ReaxFF version. In ReaxFF simulations, the lists +of bonds and hydrogen bonds can change due to chemical reactions. The +default approach, however, assumes that these changes are not very +large, so it allocates buffers for the current system setup plus a +safety margin. This can be adjusted with the :doc:`safezone, mincap, +and minhbonds settings of the pair style `, but only to +some extent. When equilibrating a new system, or simulating a sparse +system in parallel, this can be difficult to control and become +wasteful. A simple workaround is often to break a simulation down in +multiple chunks. A better approach, however, is to compile and use the +KOKKOS package version of ReaxFF (you do not need a GPU for that, but +can also compile it in serial or OpenMP mode), which uses a more robust +memory allocation approach. + +.. _err0019: + +Numeric index X is out of bounds +-------------------------------- + +This error most commonly happens when setting force field coefficients +with either the :doc:`pair_coeff `, the :doc:`bond_coeff +`, the :doc:`angle_coeff `, the +:doc:`dihedral_coeff `, or the :doc:`improper_coeff +` command. These commands accept type labels, explicit +numbers, and wildcards for ranges of numbers. If the numeric value of +any of these is outside the valid range (defined by the number of +corresponding types), LAMMPS will stop with this error. A few other +commands and styles also allow ranges of numbers and check using the +same method and thus print the same kind of error. + +The cause is almost always a typo in the input or a logic error when +defining the values or ranges. So one needs to carefully review the +input. Along with the error, LAMMPS will print the valid range as a +hint. + +.. _err0020: + +Compute, fix, or variable vector or array is accessed out-of-range +------------------------------------------------------------------ + +When accessing an individual element of a global vector or array or a +per-atom vector or array provided by a compute or fix or atom-style or +vector-style variable or data from a specific atom, an index in square +brackets ("[ ]") (or two indices) must be provided to determine which +element to access and it must be in a valid range or else LAMMPS would +access invalid data or crash with a segmentation fault. In the two most +common cases, where this data is accessed, :doc:`variable expressions +` and :doc:`thermodynamic output `, LAMMPS will +check for valid indices and stop with an error otherwise. + +While LAMMPS is written in C++ (which uses 0 based indexing) these +indices start at 1 (i.e. similar to Fortran). Any index smaller than 1 +or larger than the maximum allowed value should trigger this error. +Since this kind of error frequently happens with rather complex +expressions, it is recommended to test these with small test systems, +where the values can be tracked with output files for all relevant +properties at every step. + +.. _err0021: + +Incorrect args for pair coefficients (also bond/angle/dihedral/improper coefficients) +------------------------------------------------------------------------------------- + +The parameters in the :doc:`pair_coeff ` command for a +specified :doc:`pair_style ` have a missing or erroneous +argument. The same applies when seeing this error for :doc:`bond_coeff +`, :doc:`angle_coeff `, :doc:`dihedral_coeff +`, or :doc:`improper_coeff ` and their +respective style commands when using the MOLECULE or EXTRA-MOLECULE +packages. The cases below describe some ways to approach pair +coefficient errors, but the same strategies apply to bonded systems as +well. + +Outside of normal typos, this error can have several sources. In all +cases, the first step is to compare the command arguments to the +expected format found in the corresponding :doc:`pair_style +` page. This can reveal cases where, for example, a pair +style was changed, but the pair coefficients were not updated. This can +happen especially with pair style variants such as :doc:`pair_style eam +` vs. :doc:`pair_style eam/alloy ` that look very +similar but accept different parameters (the latter 'eam/alloy' variant +takes element type names while 'eam' does not). + +Another common source of coefficient errors is when using multiple pair +styles with commands such as :doc:`pair_style hybrid `. +Using hybrid pair styles requires adding an extra "label" argument in +the coefficient commands that designates which pair style the command +line refers to. Moreover, if the same pair style is used multiple +times, this label must be followed by an additional numeric argument. +Also, different pair styles may require different arguments. + +This error message might also require a close look at other LAMMPS input +files that are read in by the input script, such as data files or +restart files. + +.. _err0022: + +Energy was not tallied on needed timestep (also virial, per-atom energy, per-atom virial) +----------------------------------------------------------------------------------------- + +This error is generated when LAMMPS attempts to access an out-of-date or +non-existent energy, pressure, or virial. For efficiency reasons, +LAMMPS does *not* calculate these quantities when the forces are +calculated on every timestep or iteration. Global quantities are only +calculated when they are needed for :doc:`thermo ` output +(at the beginning, end, and at regular intervals specified by the +:doc:`thermo ` command). Similarly, per-atom quantities are +only calculated if they are needed to write per-atom energy or virial to +a dump file. This system works fine for simple input scripts. However, +the many user-specified `variable`, `fix`, and `compute` commands that +LAMMPS provides make it difficult to anticipate when a quantity will be +requested. In some use cases, LAMMPS will figure out that a quantity is +needed and arrange for it to be calculated on that timestep e.g. if it +is requested by :doc:`fix ave/time ` or similar commands. +If that fails, it can be detected by a mismatch between the current +timestep and when a quantity was last calculated, in which case an error +message of this type is generated. + +The most common cause of this type of error is requesting a quantity +before the start of the simulation. + +.. code-block:: LAMMPS + + # run 0 post no # this will fix the error + variable e equal pe # requesting energy compute + print "Potential energy = $e" # this will generate the error + run 1000 # start of simulation + +This situation can be avoided by adding in a "run 0" command, as +explained in more detail in the "Variable Accuracy" section of the +:doc:`variable ` doc page. + +Another cause is requesting a quantity on a timestep that is not a +thermo or dump output timestep. This can often be remedied by +increasing the frequency of thermo or dump output. + +.. _err0023: + +Molecule auto special bond generation overflow +---------------------------------------------- + +In order to correctly apply the :doc:`special_bonds ` +settings (also known as "exclusions"), LAMMPS needs to maintain for each +atom a list of atoms that are connected to this atom, either directly +with a bond or indirectly through bonding with an intermediate atom(s). +The purpose is to either remove or tag those pairs of atoms in the +neighbor list. This information is stored with individual atoms and +thus the maximum number of such "special" neighbors is set when the +simulation box is created. When reading (relative) geometry and +topology of a 'molecule' from a :doc:`molecule file `, LAMMPS +will build the list of such "special" neighbors for the molecule atom +(if not given in the molecule file explicitly). The error is triggered +when the resulting list is too long for the space reserved when creating +the simulation box. The solution is to increase the corresponding +setting. Overestimating this value will only consume more memory, and +is thus a safe choice. + +.. _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 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. + +.. _err0027: + +Inconsistent image flags +------------------------ + +This warning happens when the distance between the *unwrapped* x-, y-, +or z-components of the coordinates of a bond is larger than half the box +with periodic boundaries or larger than the box with non-periodic +boundaries. It means that the positions and image flags have become +inconsistent. LAMMPS will still compute bonded interactions based on +the closest periodic images of the atoms and thus in most cases the +results will be correct. However they can cause problems when such +atoms are used with the fix rigid or replicate commands. Thus, it is +good practice to update the system so that the message does not appear. +It will help with future manipulations of the system. + +There is one case where this warning *must* appear: when you have a +chain of connected bonds that pass through the entire box and connect +back to the first atom in the chain through periodic boundaries, +i.e. some kind of "infinite polymer". In that case, the bond image +flags *must* be inconsistent for the one bond that reaches back to the +beginning of the chain. + + +.. _err0028: + +No fixes with time integration, atoms won't move +------------------------------------------------ + +This warning will be issued if LAMMPS encounters a :doc:`run ` +command that does not have a preceding :doc:`fix ` command that +updates atom/object positions and velocities per step. In other words, +there are no fixes detected that perform velocity-Verlet time +integration, such as :doc:`fix nve `. Note that this alert +does not mean that there are no active fixes. LAMMPS has a very wide +variety of fixes, many of which do not move objects but also operate +through steps, such as printing outputs (e.g. :doc:`fix print +`), performing calculations (e.g. :doc:`fix ave/time +`), or changing other system parameters (e.g. :doc:`fix +dt/reset `). It is up to the user to determine whether +the lack of a time-integrating fix is intentional or not. + + +.. _err0029: + +System is not charge neutral, net charge = ... +---------------------------------------------- + +the sum of charges in the system is not zero. When a system is not +charge-neutral, methods that evolve/manipulate per-atom charges, +evaluate Coulomb interactions, evaluate Coulomb forces, or +evaluate/manipulate other properties relying on per-atom charges may +raise this warning. A non-zero net charge most commonly arises after +setting per-atom charges :doc:`set ` such that the sum is non-zero +or by reading in a system through :doc:`read_data ` where the +per-atom charges do not sum to zero. However, a loss of charge +neutrality may occur in other less common ways, like when charge +equilibration methods (e.g., :doc:`fix qeq `) fail. + +A similar warning/error may be raised when using certain charge +equilibration methods: :doc:`fix qeq `, :doc:`fix qeq/comb +`, :doc:`fix qeq/reaxff `, and :doc:`fix +qtpie/reaxff `. In such cases, this warning/error +will be raised for the fix :doc:`group ` when the group has a +non-zero net charge. + +When the system is expected to be charge-neutral, this warning often +arises due to an error in the lammps input (e.g., an incorrect :doc:`set +` command, error in the data file read by :doc:`read_data +`, incorrectly grouping atoms with charge, etc.). If the +system is NOT expected to be charge-neutral, the user should make sure +that the method(s) used are appropriate for systems with a non-zero net +charge. Some commonly used fixes for charge equilibration :doc:`fix qeq +`, pair styles that include charge interactions +:doc:`pair_style coul/XXX `, and kspace methods +:doc:`kspace_style ` can, in theory, support systems with +non-zero net charge. However, non-zero net charge can lead to spurious +artifacts. The severity of these artifacts depends on the magnitude of +total charge, system size, and methods used. Before running simulations +or calculations for systems with non-zero net charge, users should test +for artifacts and convergence of properties. + +.. _err0030: + +Variable evaluation before simulation box is defined +---------------------------------------------------- + +This error happens, when trying to expand or use an equal- or atom-style +variable (or an equivalent style), where the expression contains a +reference to something (e.g. a compute reference, a property of an atom, +or a thermo keyword) that is not allowed to be used before the +simulation box is defined. See the paragraph on :ref:`errors before or +after the simulation box is created ` for additional +information. + +.. _err0031: + +Invalid thermo keyword 'X' in variable formula +---------------------------------------------- + +This error message is often misleading. It is caused when evaluating a +:doc:`variable command ` expression and LAMMPS comes across a +string that it does not recognize. LAMMPS first checks if a string is a +reference to a compute, fix, custom property, or another variable by +looking at the first 2-3 characters (and if it is, it checks whether the +referenced item exists). Next LAMMPS checks if the string matches one +of the available functions or constants. If that fails, LAMMPS will +assume that this string is a :doc:`thermo keyword ` and +let the code for printing thermodynamic output return the corresponding +value. However, if this fails too, since the string is not a thermo +keyword, LAMMPS stops with the 'Invalid thermo keyword' error. But it +is also possible, that there is just a typo in the name of a valid +variable function. Thus it is recommended to check the failing variable +expression very carefully. + +.. _err0032: + +One or more atoms are time integrated more than once +---------------------------------------------------- + +This is probably an error since you typically do not want to advance the +positions or velocities of an atom more than once per timestep. This +typically happens when there are multiple fix commands that advance atom +positions with overlapping groups. Also, for some fix styles it is not +immediately obvious that they include time integration. Please check +the documentation carefully. + +.. _err0033: + +XXX command before simulation box is defined +-------------------------------------------- + +This error occurs when trying to execute a LAMMPS command that requires +information about the system dimensions, or the number atom, bond, +angle, dihedral, or improper types, or the number of atoms or similar +data that is only available *after* the simulation box has been created. +See the paragraph on :ref:`errors before or after the simulation box is +created ` for additional information. + +.. _err0034: + +XXX command after simulation box is defined +-------------------------------------------- + +This error occurs when trying to execute a LAMMPS command that changes a +global setting *after* it is locked in when the simulation box is +created (for instance defining the :doc:`atom style `, +:doc:`dimension `, :doc:`newton `, or :doc:`units +` setting). These settings may only be changed *before* the +simulation box has been created. See the paragraph on :ref:`errors +before or after the simulation box is created ` for additional +information. diff --git a/doc/src/Errors_messages.rst b/doc/src/Errors_messages.rst index bfc395067a..d1318ceffe 100644 --- a/doc/src/Errors_messages.rst +++ b/doc/src/Errors_messages.rst @@ -1,11 +1,15 @@ Error messages ============== -This is an alphabetic list of the ERROR messages LAMMPS prints out and -the reason why. If the explanation here is not sufficient, the -documentation for the offending command may help. Error messages also -list the source file and line number where the error was generated. -For example, a message like this: +This is an alphabetic list of some of the ERROR messages LAMMPS prints +out and the reason why. If the explanation here is not sufficient, the +documentation for the offending command may help. This is a historic +list and no longer updated. Instead the LAMMPS developers are trying +to provide more details right with the error message or link to a +paragraph with :doc:`detailed explanations `. + +Error messages also list the source file and line number where the error +was generated. For example, a message like this: .. parsed-literal:: @@ -14,20 +18,10 @@ For example, a message like this: means that line #78 in the file src/velocity.cpp generated the error. Looking in the source code may help you figure out what went wrong. -Doc page with :doc:`WARNING messages ` +Please also see the page with :doc:`Warning messages `. ---------- -*1-3 bond count is inconsistent* - An inconsistency was detected when computing the number of 1-3 - neighbors for each atom. This likely means something is wrong with - the bond topologies you have defined. - -*1-4 bond count is inconsistent* - An inconsistency was detected when computing the number of 1-4 - neighbors for each atom. This likely means something is wrong with - the bond topologies you have defined. - *Accelerator sharing is not currently supported on system* Multiple MPI processes cannot share the accelerator on your system. For NVIDIA GPUs, see the nvidia-smi command to change this @@ -37,15 +31,6 @@ Doc page with :doc:`WARNING messages ` All angle coefficients must be set in the data file or by the angle_coeff command before running a simulation. -*All atom IDs = 0 but atom_modify id = yes* - Self-explanatory. - -*All atoms of a swapped type must have same charge.* - Self-explanatory. - -*All atoms of a swapped type must have the same charge.* - Self-explanatory. - *All bond coeffs are not set* All bond coefficients must be set in the data file or by the bond_coeff command before running a simulation. @@ -79,12 +64,6 @@ Doc page with :doc:`WARNING messages ` the x,y,z fields, else LAMMPS cannot reconstruct the unscaled coordinates. -*All universe/uloop variables must have same # of values* - Self-explanatory. - -*All variables in next command must be same style* - Self-explanatory. - *Angle atom missing in delete_bonds* The delete_bonds command cannot find one or more atoms in a particular angle on a particular processor. The pairwise cutoff is too short or @@ -95,18 +74,6 @@ Doc page with :doc:`WARNING messages ` a particular processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid angle. -*Angle atoms %d %d %d missing on proc %d at step %ld* - One or more of three atoms needed to compute a particular angle are - missing on this processor. Typically this is because the pairwise - cutoff is set too short or the angle has blown apart and an atom is - too far away. - -*Angle atoms missing on proc %d at step %ld* - One or more of three atoms needed to compute a particular angle are - missing on this processor. Typically this is because the pairwise - cutoff is set too short or the angle has blown apart and an atom is - too far away. - *Angle coeff for hybrid has invalid style* Angle style hybrid uses another angle style as one of its coefficients. The angle style used in the angle_coeff command or read @@ -124,18 +91,6 @@ Doc page with :doc:`WARNING messages ` *Angle potential must be defined for SHAKE* When shaking angles, an angle_style potential must be used. -*Angle style hybrid cannot have hybrid as an argument* - Self-explanatory. - -*Angle style hybrid cannot have none as an argument* - Self-explanatory. - -*Angle style hybrid cannot use same angle style twice* - Self-explanatory. - -*Angle table must range from 0 to 180 degrees* - Self-explanatory. - *Angle table parameters did not set N* List of angle table parameters must include N setting. @@ -171,27 +126,6 @@ Doc page with :doc:`WARNING messages ` *Arcsin of invalid value in variable formula* Argument of arcsin() must be between -1 and 1. -*Assigning body parameters to non-body atom* - Self-explanatory. - -*Assigning ellipsoid parameters to non-ellipsoid atom* - Self-explanatory. - -*Assigning line parameters to non-line atom* - Self-explanatory. - -*Assigning quat to non-body atom* - Self-explanatory. - -*Assigning tri parameters to non-tri atom* - Self-explanatory. - -*At least one atom of each swapped type must be present to define charges.* - Self-explanatory. - -*Atom IDs must be consecutive for velocity create loop all* - Self-explanatory. - *Atom IDs must be used for molecular systems* Atom IDs are used to identify and find partner atoms in bonds. @@ -215,21 +149,12 @@ Doc page with :doc:`WARNING messages ` This is an internal LAMMPS error. Please report it to the developers. -*Atom style hybrid cannot have hybrid as an argument* - Self-explanatory. - -*Atom style hybrid cannot use same atom style twice* - Self-explanatory. - *Atom style template molecule must have atom types* The defined molecule(s) does not specify atom types. *Atom style was redefined after using fix property/atom* This is not allowed. -*Atom type must be zero in fix gcmc mol command* - Self-explanatory. - *Atom vector in equal-style variable formula* Atom vectors generate one value per atom which is not allowed in an equal-style variable. @@ -246,28 +171,13 @@ Doc page with :doc:`WARNING messages ` The atom_modify map command cannot be used after a read_data, read_restart, or create_box command. -*Atom_modify sort and first options cannot be used together* - Self-explanatory. - *Atom_style command after simulation box is defined* The atom_style command cannot be used after a read_data, read_restart, or create_box command. -*Atom_style line can only be used in 2d simulations* - Self-explanatory. - -*Atom_style tri can only be used in 3d simulations* - Self-explanatory. - *Atomfile variable could not read values* Check the file assigned to the variable. -*Atomfile variable in equal-style variable formula* - Self-explanatory. - -*Atomfile-style variable in equal-style variable formula* - Self-explanatory. - *Attempt to pop empty stack in fix box/relax* Internal LAMMPS error. Please report it to the developers. @@ -277,9 +187,6 @@ Doc page with :doc:`WARNING messages ` *Attempting to rescale a 0.0 temperature* Cannot rescale a temperature that is already 0.0. -*Attempting to insert more particles than available lattice points* - Self-explanatory. - *Bad FENE bond* Two atoms in a FENE bond have become so far apart that the bond cannot be computed. @@ -386,26 +293,11 @@ Doc page with :doc:`WARNING messages ` bond on a particular processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid bond. -*Bond atom missing in image check* - The second atom in a particular bond is missing on this processor. - Typically this is because the pairwise cutoff is set too short or the - bond has blown apart and an atom is too far away. - *Bond atom missing in set command* The set command cannot find one or more atoms in a particular bond on a particular processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid bond. -*Bond atoms %d %d missing on proc %d at step %ld* - The second atom needed to compute a particular bond is missing on this - processor. Typically this is because the pairwise cutoff is set too - short or the bond has blown apart and an atom is too far away. - -*Bond atoms missing on proc %d at step %ld* - The second atom needed to compute a particular bond is missing on this - processor. Typically this is because the pairwise cutoff is set too - short or the bond has blown apart and an atom is too far away. - *Bond coeff for hybrid has invalid style* Bond style hybrid uses another bond style as one of its coefficients. The bond style used in the bond_coeff command or read from a restart @@ -423,15 +315,6 @@ Doc page with :doc:`WARNING messages ` *Bond potential must be defined for SHAKE* Cannot use fix shake unless bond potential is defined. -*Bond style hybrid cannot have hybrid as an argument* - Self-explanatory. - -*Bond style hybrid cannot have none as an argument* - Self-explanatory. - -*Bond style hybrid cannot use same bond style twice* - Self-explanatory. - *Bond style quartic cannot be used with 3,4-body interactions* No angle, dihedral, or improper styles can be defined when using bond style quartic. @@ -476,12 +359,6 @@ Doc page with :doc:`WARNING messages ` *Bonds defined but no bond types* The data file header lists bonds but no bond types. -*Both restart files must use % or neither* - Self-explanatory. - -*Both restart files must use MPI-IO or neither* - Self-explanatory. - *Both sides of boundary must be periodic* Cannot specify a boundary as periodic only on the lo or hi side. Must be periodic on both sides. @@ -510,21 +387,6 @@ Doc page with :doc:`WARNING messages ` Only triclinic boxes can be used with off-diagonal pressure components. See the region prism command for details. -*Can only use -plog with multiple partitions* - Self-explanatory. See page discussion of command-line switches. - -*Can only use -pscreen with multiple partitions* - Self-explanatory. See page discussion of command-line switches. - -*Can only use Kokkos supported regions with Kokkos package* - Self-explanatory. - -*Can only use NEB with 1-processor replicas* - This is current restriction for NEB as implemented in LAMMPS. - -*Can only use TAD with 1-processor replicas for NEB* - This is current restriction for NEB as implemented in LAMMPS. - *Cannot (yet) do analytic differentiation with pppm/gpu* This is a current restriction of this command. @@ -561,18 +423,6 @@ Doc page with :doc:`WARNING messages ` *Cannot (yet) use kspace_style pppm/stagger with triclinic systems* This feature is not yet supported. -*Cannot (yet) use molecular templates with Kokkos* - Self-explanatory. - -*Cannot (yet) use respa with Kokkos* - Self-explanatory. - -*Cannot (yet) use rigid bodies with fix deform and Kokkos* - Self-explanatory. - -*Cannot (yet) use rigid bodies with fix nh and Kokkos* - Self-explanatory. - *Cannot (yet) use single precision with MSM (remove -DFFT_SINGLE from Makefile and re-compile)* Single precision cannot be used with MSM. @@ -583,9 +433,6 @@ Doc page with :doc:`WARNING messages ` The simulation box must be defined with edges aligned with the Cartesian axes. -*Cannot balance in z dimension for 2d simulation* - Self-explanatory. - *Cannot change box ortho/triclinic with certain fixes defined* This is because those fixes store the shape of the box. You need to use unfix to discard the fix, change the box, then redefine a new @@ -599,12 +446,6 @@ Doc page with :doc:`WARNING messages ` *Cannot change box tilt factors for orthogonal box* Cannot use tilt factors unless the simulation box is non-orthogonal. -*Cannot change box to orthogonal when tilt is non-zero* - Self-explanatory. - -*Cannot change box z boundary to non-periodic for a 2d simulation* - Self-explanatory. - *Cannot change dump_modify every for dump dcd* The frequency of writing dump dcd snapshots cannot be changed. @@ -619,20 +460,11 @@ Doc page with :doc:`WARNING messages ` This is because fix pour pre-computes the time delay for particles to fall out of the insertion volume due to gravity. -*Cannot change to comm_style brick from tiled layout* - Self-explanatory. - *Cannot change_box after reading restart file with per-atom info* This is because the restart file info cannot be migrated with the atoms. You can get around this by performing a 0-timestep run which will assign the restart file info to actual atoms. -*Cannot change_box in xz or yz for 2d simulation* - Self-explanatory. - -*Cannot change_box in z dimension for 2d simulation* - Self-explanatory. - *Cannot clear group all* This operation is not allowed. @@ -668,27 +500,6 @@ Doc page with :doc:`WARNING messages ` *Cannot currently use pair reax with pair hybrid* This is not yet supported. -*Cannot currently use pppm/gpu with fix balance.* - Self-explanatory. - -*Cannot delete group all* - Self-explanatory. - -*Cannot delete group currently used by a compute* - Self-explanatory. - -*Cannot delete group currently used by a dump* - Self-explanatory. - -*Cannot delete group currently used by a fix* - Self-explanatory. - -*Cannot delete group currently used by atom_modify first* - Self-explanatory. - -*Cannot delete_atoms bond yes for non-molecular systems* - Self-explanatory. - *Cannot displace_atoms after reading restart file with per-atom info* This is because the restart file info cannot be migrated with the atoms. You can get around this by performing a 0-timestep run which @@ -702,9 +513,6 @@ Doc page with :doc:`WARNING messages ` This is a restriction due to the way atoms are organized in a list to enable the atom_modify first command. -*Cannot dump sort on atom IDs with no atom IDs defined* - Self-explanatory. - *Cannot dump sort when multiple dump files are written* In this mode, each processor dumps its atoms to a file, so no sorting is allowed. @@ -717,30 +525,15 @@ Doc page with :doc:`WARNING messages ` This is a restriction due to the way atoms are organized in a list to enable the atom_modify first command. -*Cannot find create_bonds group ID* - Self-explanatory. - *Cannot find delete_bonds group ID* Group ID used in the delete_bonds command does not exist. -*Cannot find specified group ID for core particles* - Self-explanatory. - -*Cannot find specified group ID for shell particles* - Self-explanatory. - *Cannot have both pair_modify shift and tail set to yes* These 2 options are contradictory. *Cannot intersect groups using a dynamic group* This operation is not allowed. -*Cannot mix molecular and molecule template atom styles* - Self-explanatory. - -*Cannot open -reorder file* - Self-explanatory. - *Cannot open ADP potential file %s* The specified ADP potential file cannot be opened. Check that the path and name are correct. @@ -801,16 +594,10 @@ Doc page with :doc:`WARNING messages ` The specified Vashishta potential file cannot be opened. Check that the path and name are correct. -*Cannot open balance output file* - Self-explanatory. - *Cannot open coul/streitz potential file %s* The specified coul/streitz potential file cannot be opened. Check that the path and name are correct. -*Cannot open custom file* - Self-explanatory. - *Cannot open data file %s* The specified file cannot be opened. Check that the path and name are correct. @@ -819,9 +606,6 @@ Doc page with :doc:`WARNING messages ` Using a "\*" in the name of the restart file will open the current directory to search for matching file names. -*Cannot open dump file* - Self-explanatory. - *Cannot open dump file %s* The output file for the dump command cannot be opened. Check that the path and name are correct. @@ -851,9 +635,6 @@ Doc page with :doc:`WARNING messages ` The specified file cannot be opened. Check that the path and name are correct. -*Cannot open fix balance output file* - Self-explanatory. - *Cannot open fix poems file %s* The specified file cannot be opened. Check that the path and name are correct. @@ -897,9 +678,6 @@ Doc page with :doc:`WARNING messages ` LAMMPS was compiled without support for reading and writing gzipped files through a pipeline to the gzip program with -DLAMMPS_GZIP. -*Cannot open input script %s* - Self-explanatory. - *Cannot open log.cite file* This file is created when you use some LAMMPS features, to indicate what paper you should cite on behalf of those who implemented @@ -934,15 +712,6 @@ Doc page with :doc:`WARNING messages ` The specified polymorphic potential file cannot be opened. Check that the path and name are correct. -*Cannot open print file %s* - Self-explanatory. - -*Cannot open processors output file* - Self-explanatory. - -*Cannot open restart file %s* - Self-explanatory. - *Cannot open restart file for reading - MPI error: %s* This error was generated by MPI when reading/writing an MPI-IO restart file. @@ -956,9 +725,6 @@ Doc page with :doc:`WARNING messages ` opened. Check that the directory you are running in allows for files to be created. -*Cannot open temporary file for world counter.* - Self-explanatory. - *Cannot open universe log file* For a multi-partition run, the master log file cannot be opened. Check that the directory you are running in allows for files to be @@ -973,9 +739,6 @@ Doc page with :doc:`WARNING messages ` This error was generated by MPI when reading/writing an MPI-IO restart file. -*Cannot read_data without add keyword after simulation box is defined* - Self-explanatory. - *Cannot read_restart after simulation box is defined* The read_restart command cannot be used after a read_data, read_restart, or create_box command. @@ -1017,40 +780,10 @@ Doc page with :doc:`WARNING messages ` all together (pair), or in pieces (inner/middle/outer). You can't do both. -*Cannot set cutoff/multi before simulation box is defined* - Self-explanatory. - -*Cannot set dpd/theta for this atom style* - Self-explanatory. - -*Cannot set dump_modify flush for dump xtc* - Self-explanatory. - *Cannot set mass for this atom style* This atom style does not support mass settings for each atom type. Instead they are defined on a per-atom basis in the data file. -*Cannot set meso/cv for this atom style* - Self-explanatory. - -*Cannot set meso/e for this atom style* - Self-explanatory. - -*Cannot set meso/rho for this atom style* - Self-explanatory. - -*Cannot set non-zero image flag for non-periodic dimension* - Self-explanatory. - -*Cannot set non-zero z velocity for 2d simulation* - Self-explanatory. - -*Cannot set quaternion for atom that has none* - Self-explanatory. - -*Cannot set quaternion with xy components for 2d system* - Self-explanatory. - *Cannot set respa hybrid and any of pair/inner/middle/outer* In the rRESPA integrator, you must compute pairwise potentials either all together (pair), with different cutoff regions (inner/middle/outer), @@ -1064,39 +797,18 @@ Doc page with :doc:`WARNING messages ` This error was generated by MPI when reading/writing an MPI-IO restart file. -*Cannot set smd/contact/radius for this atom style* - Self-explanatory. - -*Cannot set smd/mass/density for this atom style* - Self-explanatory. - *Cannot set temperature for fix rigid/nph* The temp keyword cannot be specified. -*Cannot set theta for atom that is not a line* - Self-explanatory. - *Cannot set this attribute for this atom style* The attribute being set does not exist for the defined atom style. -*Cannot set variable z velocity for 2d simulation* - Self-explanatory. - -*Cannot skew triclinic box in z for 2d simulation* - Self-explanatory. - *Cannot subtract groups using a dynamic group* This operation is not allowed. *Cannot union groups using a dynamic group* This operation is not allowed. -*Cannot use -kokkos on without KOKKOS installed* - Self-explanatory. - -*Cannot use -reorder after -partition* - Self-explanatory. See page discussion of command-line switches. - *Cannot use Ewald with 2d simulation* The kspace style ewald cannot be used in 2d simulations. You can use 2d Ewald in a 3d simulation; see the kspace_modify command. @@ -1109,15 +821,9 @@ Doc page with :doc:`WARNING messages ` *Cannot use EwaldDisp with 2d simulation* This is a current restriction of this command. -*Cannot use Kokkos pair style with rRESPA inner/middle* - Self-explanatory. - *Cannot use NEB unless atom map exists* Use the atom_modify command to create an atom map. -*Cannot use NEB with a single replica* - Self-explanatory. - *Cannot use NEB with atom_modify sort enabled* This is current restriction for NEB implemented in LAMMPS. @@ -1166,109 +872,40 @@ Doc page with :doc:`WARNING messages ` The boundary style of the face where atoms are added can not be of type p (periodic). -*Cannot use atomfile-style variable unless atom map exists* - Self-explanatory. See the atom_modify command to create a map. - -*Cannot use both com and bias with compute temp/chunk* - Self-explanatory. - -*Cannot use chosen neighbor list style with buck/coul/cut/kk* - Self-explanatory. - -*Cannot use chosen neighbor list style with buck/coul/long/kk* - Self-explanatory. - *Cannot use chosen neighbor list style with buck/kk* That style is not supported by Kokkos. *Cannot use chosen neighbor list style with coul/cut/kk* That style is not supported by Kokkos. -*Cannot use chosen neighbor list style with coul/debye/kk* - Self-explanatory. - *Cannot use chosen neighbor list style with coul/dsf/kk* That style is not supported by Kokkos. *Cannot use chosen neighbor list style with coul/wolf/kk* That style is not supported by Kokkos. -*Cannot use chosen neighbor list style with lj/charmm/coul/charmm/implicit/kk* - Self-explanatory. - -*Cannot use chosen neighbor list style with lj/charmm/coul/charmm/kk* - Self-explanatory. - -*Cannot use chosen neighbor list style with lj/charmm/coul/long/kk* - Self-explanatory. - -*Cannot use chosen neighbor list style with lj/class2/coul/cut/kk* - Self-explanatory. - -*Cannot use chosen neighbor list style with lj/class2/coul/long/kk* - Self-explanatory. - -*Cannot use chosen neighbor list style with lj/class2/kk* - Self-explanatory. - *Cannot use chosen neighbor list style with lj/cut/coul/cut/kk* That style is not supported by Kokkos. -*Cannot use chosen neighbor list style with lj/cut/coul/debye/kk* - Self-explanatory. - *Cannot use chosen neighbor list style with lj/cut/coul/long/kk* That style is not supported by Kokkos. *Cannot use chosen neighbor list style with lj/cut/kk* That style is not supported by Kokkos. -*Cannot use chosen neighbor list style with lj/expand/kk* - Self-explanatory. - -*Cannot use chosen neighbor list style with lj/gromacs/coul/gromacs/kk* - Self-explanatory. - -*Cannot use chosen neighbor list style with lj/gromacs/kk* - Self-explanatory. - *Cannot use chosen neighbor list style with lj/spica/kk* That style is not supported by Kokkos. *Cannot use chosen neighbor list style with pair eam/kk* That style is not supported by Kokkos. -*Cannot use chosen neighbor list style with pair eam/kk/alloy* - Self-explanatory. - -*Cannot use chosen neighbor list style with pair eam/kk/fs* - Self-explanatory. - -*Cannot use chosen neighbor list style with pair sw/kk* - Self-explanatory. - -*Cannot use chosen neighbor list style with tersoff/kk* - Self-explanatory. - -*Cannot use chosen neighbor list style with tersoff/zbl/kk* - Self-explanatory. - -*Cannot use compute chunk/atom bin z for 2d model* - Self-explanatory. - *Cannot use compute cluster/atom unless atoms have IDs* Atom IDs are used to identify clusters. -*Cannot use create_atoms rotate unless single style* - Self-explanatory. - *Cannot use create_bonds unless atoms have IDs* This command requires a mapping from global atom IDs to local atoms, but the atoms that have been defined have no IDs. -*Cannot use create_bonds with non-molecular system* - Self-explanatory. - *Cannot use cwiggle in variable formula between runs* This is a function of elapsed time. @@ -1283,12 +920,6 @@ Doc page with :doc:`WARNING messages ` *Cannot use delete_bonds with non-molecular system* Your choice of atom style does not have bonds. -*Cannot use dump_modify fileper without % in dump file name* - Self-explanatory. - -*Cannot use dump_modify nfile without % in dump file name* - Self-explanatory. - *Cannot use dynamic group with fix adapt atom* This is not yet supported. @@ -1340,28 +971,13 @@ Doc page with :doc:`WARNING messages ` *Cannot use fix deform trate on a box with zero tilt* The trate style alters the current strain. -*Cannot use fix deposit rigid and not molecule* - Self-explanatory. - *Cannot use fix deposit rigid and shake* These two attributes are conflicting. -*Cannot use fix deposit shake and not molecule* - Self-explanatory. - -*Cannot use fix enforce2d with 3d simulation* - Self-explanatory. - *Cannot use fix gcmc in a 2d simulation* Fix gcmc is set up to run in 3d only. No 2d simulations with fix gcmc are allowed. -*Cannot use fix gcmc shake and not molecule* - Self-explanatory. - -*Cannot use fix msst without per-type mass defined* - Self-explanatory. - *Cannot use fix npt and fix deform on same component of stress tensor* This would be changing the same box dimension twice. @@ -1374,15 +990,6 @@ Doc page with :doc:`WARNING messages ` When specifying a diagonal pressure component, the dimension must be periodic. -*Cannot use fix nvt/npt/nph with both xy dynamics and xy scaling* - Self-explanatory. - -*Cannot use fix nvt/npt/nph with both xz dynamics and xz scaling* - Self-explanatory. - -*Cannot use fix nvt/npt/nph with both yz dynamics and yz scaling* - Self-explanatory. - *Cannot use fix nvt/npt/nph with xy scaling when y is non-periodic dimension* The second dimension in the barostatted tilt factor must be periodic. @@ -1392,15 +999,9 @@ Doc page with :doc:`WARNING messages ` *Cannot use fix nvt/npt/nph with yz scaling when z is non-periodic dimension* The second dimension in the barostatted tilt factor must be periodic. -*Cannot use fix pour rigid and not molecule* - Self-explanatory. - *Cannot use fix pour rigid and shake* These two attributes are conflicting. -*Cannot use fix pour shake and not molecule* - Self-explanatory. - *Cannot use fix pour with triclinic box* This option is not yet supported. @@ -1408,15 +1009,6 @@ Doc page with :doc:`WARNING messages ` These commands both change the box size/shape, so you cannot use both together. -*Cannot use fix press/berendsen on a non-periodic dimension* - Self-explanatory. - -*Cannot use fix press/berendsen with triclinic box* - Self-explanatory. - -*Cannot use fix reax/bonds without pair_style reax* - Self-explanatory. - *Cannot use fix rigid npt/nph and fix deform on same component of stress tensor* This would be changing the same box dimension twice. @@ -1437,202 +1029,20 @@ Doc page with :doc:`WARNING messages ` *Cannot use fix ttm with triclinic box* This is a current restriction of this fix due to the grid it creates. -*Cannot use fix tune/kspace without a kspace style* - Self-explanatory. - *Cannot use fix tune/kspace without a pair style* This fix (tune/kspace) can only be used when a pair style has been specified. -*Cannot use fix wall in periodic dimension* - Self-explanatory. - -*Cannot use fix wall zlo/zhi for a 2d simulation* - Self-explanatory. - -*Cannot use fix wall/reflect in periodic dimension* - Self-explanatory. - -*Cannot use fix wall/reflect zlo/zhi for a 2d simulation* - Self-explanatory. - -*Cannot use fix wall/srd in periodic dimension* - Self-explanatory. - *Cannot use fix wall/srd more than once* Nor is their a need to since multiple walls can be specified in one command. -*Cannot use fix wall/srd without fix srd* - Self-explanatory. - -*Cannot use fix wall/srd zlo/zhi for a 2d simulation* - Self-explanatory. - -*Cannot use fix_deposit unless atoms have IDs* - Self-explanatory. - -*Cannot use fix_pour unless atoms have IDs* - Self-explanatory. - -*Cannot use include command within an if command* - Self-explanatory. - *Cannot use lines with fix srd unless overlap is set* This is because line segments are connected to each other. -*Cannot use multiple fix wall commands with pair brownian* - Self-explanatory. - -*Cannot use multiple fix wall commands with pair lubricate* - Self-explanatory. - -*Cannot use multiple fix wall commands with pair lubricate/poly* - Self-explanatory. - -*Cannot use multiple fix wall commands with pair lubricateU* - Self-explanatory. - *Cannot use neigh_modify exclude with GPU neighbor builds* This is a current limitation of the GPU implementation in LAMMPS. -*Cannot use neighbor bins - box size << cutoff* - Too many neighbor bins will be created. This typically happens when - the simulation box is very small in some dimension, compared to the - neighbor cutoff. Use the "nsq" style instead of "bin" style. - -*Cannot use newton pair with beck/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with born/coul/long/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with born/coul/wolf/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with born/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with buck/coul/cut/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with buck/coul/long/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with buck/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with colloid/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with coul/cut/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with coul/debye/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with coul/dsf/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with coul/long/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with dipole/cut/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with dipole/sf/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with dpd/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with dpd/tstat/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with eam/alloy/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with eam/fs/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with eam/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with gauss/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with gayberne/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/charmm/coul/long/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/class2/coul/long/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/class2/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/cubic/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/cut/coul/cut/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/cut/coul/debye/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/cut/coul/dsf/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/cut/coul/long/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/cut/coul/msm/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/cut/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/expand/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/gromacs/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/spica/coul/long/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj/spica/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with lj96/cut/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with mie/cut/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with morse/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with resquared/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with soft/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with table/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with yukawa/colloid/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with yukawa/gpu pair style* - Self-explanatory. - -*Cannot use newton pair with zbl/gpu pair style* - Self-explanatory. - *Cannot use non-zero forces in an energy minimization* Fix setforce cannot be used in this manner. Use fix addforce instead. @@ -1660,9 +1070,6 @@ Doc page with :doc:`WARNING messages ` boundaries unless you use the kspace_modify command to define a 2d slab with a non-periodic z dimension. -*Cannot use order greater than 8 with pppm/gpu.* - Self-explanatory. - *Cannot use package gpu neigh yes with triclinic box* This is a current restriction in LAMMPS. @@ -1675,18 +1082,6 @@ Doc page with :doc:`WARNING messages ` *Cannot use ramp in variable formula between runs* This is because the ramp() function is time dependent. -*Cannot use read_data add before simulation box is defined* - Self-explanatory. - -*Cannot use read_data extra with add flag* - Self-explanatory. - -*Cannot use read_data offset without add flag* - Self-explanatory. - -*Cannot use read_data shift without add flag* - Self-explanatory. - *Cannot use region INF or EDGE when box does not exist* Regions that extend to the box boundaries can only be used after the create_box command has been used. @@ -1694,18 +1089,12 @@ Doc page with :doc:`WARNING messages ` *Cannot use set atom with no atom IDs defined* Atom IDs are not defined, so they cannot be used to identify an atom. -*Cannot use set mol with no molecule IDs defined* - Self-explanatory. - *Cannot use swiggle in variable formula between runs* This is a function of elapsed time. *Cannot use tris with fix srd unless overlap is set* This is because triangles are connected to each other. -*Cannot use variable energy with constant efield in fix efield* - LAMMPS computes the energy itself when the E-field is constant. - *Cannot use variable energy with constant force in fix addforce* This is because for constant force, LAMMPS can compute the change in energy directly. @@ -1720,22 +1109,10 @@ Doc page with :doc:`WARNING messages ` *Cannot use vdisplace in variable formula between runs* This is a function of elapsed time. -*Cannot use velocity bias command without temp keyword* - Self-explanatory. - *Cannot use velocity create loop all unless atoms have IDs* Atoms in the simulation to do not have IDs, so this style of velocity creation cannot be performed. -*Cannot use wall in periodic dimension* - Self-explanatory. - -*Cannot use write_restart fileper without % in restart file name* - Self-explanatory. - -*Cannot use write_restart nfile without % in restart file name* - Self-explanatory. - *Cannot wiggle and shear fix wall/gran* Cannot specify both options at the same time. @@ -1746,12 +1123,6 @@ Doc page with :doc:`WARNING messages ` *Cannot yet use KSpace solver with grid with comm style tiled* This is current restriction in LAMMPS. -*Cannot yet use comm_style tiled with multi-mode comm* - Self-explanatory. - -*Cannot yet use comm_style tiled with triclinic box* - Self-explanatory. - *Cannot yet use compute tally with Kokkos* This feature is not yet supported. @@ -1774,50 +1145,11 @@ Doc page with :doc:`WARNING messages ` *Cannot zero gld force for zero atoms* There are no atoms currently in the group. -*Cannot zero momentum of no atoms* - Self-explanatory. - -*Change_box command before simulation box is defined* - Self-explanatory. - *Change_box volume used incorrectly* The "dim volume" option must be used immediately following one or two settings for "dim1 ..." (and optionally "dim2 ...") and must be for a different dimension, i.e. dim != dim1 and dim != dim2. -*Chunk/atom compute does not exist for compute angmom/chunk* - Self-explanatory. - -*Chunk/atom compute does not exist for compute com/chunk* - Self-explanatory. - -*Chunk/atom compute does not exist for compute gyration/chunk* - Self-explanatory. - -*Chunk/atom compute does not exist for compute inertia/chunk* - Self-explanatory. - -*Chunk/atom compute does not exist for compute msd/chunk* - Self-explanatory. - -*Chunk/atom compute does not exist for compute omega/chunk* - Self-explanatory. - -*Chunk/atom compute does not exist for compute property/chunk* - Self-explanatory. - -*Chunk/atom compute does not exist for compute temp/chunk* - Self-explanatory. - -*Chunk/atom compute does not exist for compute torque/chunk* - Self-explanatory. - -*Chunk/atom compute does not exist for compute vcm/chunk* - Self-explanatory. - -*Chunk/atom compute does not exist for fix ave/chunk* - Self-explanatory. - *Comm tiled invalid index in box drop brick* Internal error check in comm_style tiled which should not occur. Contact the developers. @@ -1826,12 +1158,6 @@ Doc page with :doc:`WARNING messages ` Internal error check in comm_style tiled which should not occur. Contact the developers. -*Comm_modify group != atom_modify first group* - Self-explanatory. - -*Communication cutoff for comm_style tiled cannot exceed periodic box length* - Self-explanatory. - *Communication cutoff too small for SNAP micro load balancing* This can happen if you change the neighbor skin after your pair_style command or if your box dimensions grow during a run. You can set the @@ -1840,69 +1166,12 @@ Doc page with :doc:`WARNING messages ` *Compute %s does not allow use of dynamic group* Dynamic groups have not yet been enabled for this compute. -*Compute for fix pafi does not calculate a local array* - Self-explanatory. - -*Compute for fix pafi must have 9 fields per atom* - Self-explanatory. - -*Compute ID for compute chunk /atom does not exist* - Self-explanatory. - -*Compute ID for compute chunk/atom does not exist* - Self-explanatory. - -*Compute gyration ID does not exist for compute gyration/shape* - Self-explanatory. Provide a valid compute ID. - -*Compute gyration/shape compute ID does not point to a gyration compute* - Self-explanatory. Provide and ID of a compute gyration command. - -*Compute ID for compute reduce does not exist* - Self-explanatory. - -*Compute ID for compute slice does not exist* - Self-explanatory. - -*Compute ID for fix ave/atom does not exist* - Self-explanatory. - -*Compute ID for fix ave/chunk does not exist* - Self-explanatory. - -*Compute ID for fix ave/correlate does not exist* - Self-explanatory. - -*Compute ID for fix ave/histo does not exist* - Self-explanatory. - -*Compute ID for fix ave/time does not exist* - Self-explanatory. - -*Compute ID for fix numdiff does not exist* - Self-explanatory. - -*Compute ID for fix numdiff/virial does not exist* - Self-explanatory. - -*Compute ID for fix store/state does not exist* - Self-explanatory. - -*Compute ID for fix vector does not exist* - Self-explanatory. - -*Compute ID must be alphanumeric or underscore characters* - Self-explanatory. - *Compute angle/local used when angles are not allowed* The atom style does not support angles. *Compute angmom/chunk does not use chunk/atom compute* The style of the specified compute is not chunk/atom. -*Compute body/local requires atom style body* - Self-explanatory. - *Compute bond/local used when bonds are not allowed* The atom style does not support bonds. @@ -1916,46 +1185,10 @@ Doc page with :doc:`WARNING messages ` *Compute chunk/atom bin/sphere radius is too large for periodic box* Radius cannot be bigger than 1/2 of any periodic dimension. -*Compute chunk/atom compute array is accessed out-of-range* - The index for the array is out of bounds. - -*Compute chunk/atom compute does not calculate a per-atom array* - Self-explanatory. - -*Compute chunk/atom compute does not calculate a per-atom vector* - Self-explanatory. - -*Compute chunk/atom compute does not calculate per-atom values* - Self-explanatory. - -*Compute chunk/atom cylinder axis must be z for 2d* - Self-explanatory. - -*Compute chunk/atom fix array is accessed out-of-range* - The index for the array is out of bounds. - -*Compute chunk/atom fix does not calculate a per-atom array* - Self-explanatory. - -*Compute chunk/atom fix does not calculate a per-atom vector* - Self-explanatory. - -*Compute chunk/atom fix does not calculate per-atom values* - Self-explanatory. - -*Compute chunk/atom for triclinic boxes requires units reduced* - Self-explanatory. - *Compute chunk/atom ids once but nchunk is not once* You cannot assign chunks IDs to atom permanently if the number of chunks may change. -*Compute chunk/atom molecule for non-molecular system* - Self-explanatory. - -*Compute chunk/atom sphere z origin must be 0.0 for 2d* - Self-explanatory. - *Compute chunk/atom stores no IDs for compute property/chunk* It will only store IDs if its compress option is enabled. @@ -1968,9 +1201,6 @@ Doc page with :doc:`WARNING messages ` *Compute chunk/atom stores no coord3 for compute property/chunk* Only certain binning options for compute chunk/atom store coordinates. -*Compute chunk/atom variable is not atom-style variable* - Self-explanatory. - *Compute chunk/atom without bins cannot use discard mixed* That discard option only applies to the binning styles. @@ -1981,28 +1211,13 @@ Doc page with :doc:`WARNING messages ` This is so that the pair style defines a cutoff distance which is used to find clusters. -*Compute cna/atom cutoff is longer than pairwise cutoff* - Self-explanatory. - -*Compute cna/atom requires a pair style be defined* - Self-explanatory. - *Compute com/chunk does not use chunk/atom compute* The style of the specified compute is not chunk/atom. -*Compute contact/atom requires a pair style be defined* - Self-explanatory. - -*Compute contact/atom requires atom style sphere* - Self-explanatory. - *Compute coord/atom cutoff is longer than pairwise cutoff* Cannot compute coordination at distances longer than the pair cutoff, since those atoms are not in the neighbor list. -*Compute coord/atom requires a pair style be defined* - Self-explanatory. - *Compute damage/atom requires peridynamic potential* Damage is a Peridynamic-specific metric. It requires you to be running a Peridynamics simulation. @@ -2010,65 +1225,29 @@ Doc page with :doc:`WARNING messages ` *Compute dihedral/local used when dihedrals are not allowed* The atom style does not support dihedrals. -*Compute dilatation/atom cannot be used with this pair style* - Self-explanatory. - -*Compute dilatation/atom requires Peridynamic pair style* - Self-explanatory. - *Compute does not allow an extra compute or fix to be reset* This is an internal LAMMPS error. Please report it to the developers. -*Compute erotate/asphere requires atom style ellipsoid or line or tri* - Self-explanatory. - *Compute erotate/asphere requires extended particles* This compute cannot be used with point particles. -*Compute erotate/rigid with non-rigid fix-ID* - Self-explanatory. - -*Compute erotate/sphere requires atom style sphere* - Self-explanatory. - -*Compute erotate/sphere/atom requires atom style sphere* - Self-explanatory. - *Compute event/displace has invalid fix event assigned* This is an internal LAMMPS error. Please report it to the developers. -*Compute group/group group ID does not exist* - Self-explanatory. - *Compute gyration/chunk does not use chunk/atom compute* The style of the specified compute is not chunk/atom. -*Compute heat/flux compute ID does not compute ke/atom* - Self-explanatory. - -*Compute heat/flux compute ID does not compute pe/atom* - Self-explanatory. - -*Compute heat/flux compute ID does not compute stress/atom* - Self-explanatory. - *Compute hexorder/atom cutoff is longer than pairwise cutoff* Cannot compute order parameter beyond cutoff. -*Compute hexorder/atom requires a pair style be defined* - Self-explanatory. - *Compute improper/local used when impropers are not allowed* The atom style does not support impropers. *Compute inertia/chunk does not use chunk/atom compute* The style of the specified compute is not chunk/atom. -*Compute ke/rigid with non-rigid fix-ID* - Self-explanatory. - *Compute msd/chunk does not use chunk/atom compute* The style of the specified compute is not chunk/atom. @@ -2077,24 +1256,12 @@ Doc page with :doc:`WARNING messages ` the number of chunks is changing. Compute chunk/atom allows setting nchunk to be static. -*Compute nve/asphere requires atom style ellipsoid* - Self-explanatory. - -*Compute nvt/nph/npt asphere requires atom style ellipsoid* - Self-explanatory. - -*Compute nvt/nph/npt body requires atom style body* - Self-explanatory. - *Compute omega/chunk does not use chunk/atom compute* The style of the specified compute is not chunk/atom. *Compute orientorder/atom cutoff is longer than pairwise cutoff* Cannot compute order parameter beyond cutoff. -*Compute orientorder/atom requires a pair style be defined* - Self-explanatory. - *Compute pair must use group all* Pair styles accumulate energy on all atoms. @@ -2102,12 +1269,6 @@ Doc page with :doc:`WARNING messages ` Energies computed by potentials (pair, bond, etc) are computed on all atoms. -*Compute plasticity/atom cannot be used with this pair style* - Self-explanatory. - -*Compute plasticity/atom requires Peridynamic pair style* - Self-explanatory. - *Compute pressure must use group all* Virial contributions computed by potentials (pair, bond, etc) are computed on all atoms. @@ -2123,9 +1284,6 @@ Doc page with :doc:`WARNING messages ` The command is accessing a vector added by the fix property/atom command, that does not exist. -*Compute property/atom for atom property that is not allocated* - Self-explanatory. - *Compute property/atom integer vector does not exist* The command is accessing a vector added by the fix property/atom command, that does not exist. @@ -2137,117 +1295,18 @@ Doc page with :doc:`WARNING messages ` Only inputs that generate the same number of datums can be used together. E.g. bond and angle quantities cannot be mixed. -*Compute property/local does not (yet) work with atom_style template* - Self-explanatory. - -*Compute property/local for property that is not allocated* - Self-explanatory. - -*Compute rdf requires a pair style be defined* - Self-explanatory. - -*Compute reduce compute array is accessed out-of-range* - An index for the array is out of bounds. - *Compute reduce compute calculates global values* A compute that calculates peratom or local values is required. -*Compute reduce compute does not calculate a local array* - Self-explanatory. - -*Compute reduce compute does not calculate a local vector* - Self-explanatory. - -*Compute reduce compute does not calculate a per-atom array* - Self-explanatory. - -*Compute reduce compute does not calculate a per-atom vector* - Self-explanatory. - -*Compute reduce fix array is accessed out-of-range* - An index for the array is out of bounds. - *Compute reduce fix calculates global values* A fix that calculates peratom or local values is required. -*Compute reduce fix does not calculate a local array* - Self-explanatory. - -*Compute reduce fix does not calculate a local vector* - Self-explanatory. - -*Compute reduce fix does not calculate a per-atom array* - Self-explanatory. - -*Compute reduce fix does not calculate a per-atom vector* - Self-explanatory. - -*Compute reduce replace requires min or max mode* - Self-explanatory. - -*Compute reduce variable is not atom-style variable* - Self-explanatory. - -*Compute slice compute array is accessed out-of-range* - An index for the array is out of bounds. - -*Compute slice compute does not calculate a global array* - Self-explanatory. - -*Compute slice compute does not calculate a global vector* - Self-explanatory. - -*Compute slice compute does not calculate global vector or array* - Self-explanatory. - -*Compute slice compute vector is accessed out-of-range* - The index for the vector is out of bounds. - -*Compute slice fix array is accessed out-of-range* - An index for the array is out of bounds. - -*Compute slice fix does not calculate a global array* - Self-explanatory. - -*Compute slice fix does not calculate a global vector* - Self-explanatory. - -*Compute slice fix does not calculate global vector or array* - Self-explanatory. - -*Compute slice fix vector is accessed out-of-range* - The index for the vector is out of bounds. - -*Compute sna/atom cutoff is longer than pairwise cutoff* - Self-explanatory. - -*Compute sna/atom requires a pair style be defined* - Self-explanatory. - -*Compute snad/atom cutoff is longer than pairwise cutoff* - Self-explanatory. - -*Compute snad/atom requires a pair style be defined* - Self-explanatory. - -*Compute snav/atom cutoff is longer than pairwise cutoff* - Self-explanatory. - -*Compute snav/atom requires a pair style be defined* - Self-explanatory. - *Compute stress/atom temperature ID does not compute temperature* The specified compute must compute temperature. -*Compute temp/asphere requires atom style ellipsoid* - Self-explanatory. - *Compute temp/asphere requires extended particles* This compute cannot be used with point particles. -*Compute temp/body requires atom style body* - Self-explanatory. - *Compute temp/body requires bodies* This compute can only be applied to body particles. @@ -2260,27 +1319,6 @@ Doc page with :doc:`WARNING messages ` *Compute temp/cs used when bonds are not allowed* This compute only works on pairs of bonded particles. -*Compute temp/partial cannot use vz for 2d systemx* - Self-explanatory. - -*Compute temp/profile cannot bin z for 2d systems* - Self-explanatory. - -*Compute temp/profile cannot use vz for 2d systemx* - Self-explanatory. - -*Compute temp/sphere requires atom style sphere* - Self-explanatory. - -*Compute ti kspace style does not exist* - Self-explanatory. - -*Compute ti pair style does not exist* - Self-explanatory. - -*Compute ti tail when pair style does not compute tail corrections* - Self-explanatory. - *Compute torque/chunk does not use chunk/atom compute* The style of the specified compute is not chunk/atom. @@ -2304,9 +1342,6 @@ Doc page with :doc:`WARNING messages ` *Compute vcm/chunk does not use chunk/atom compute* The style of the specified compute is not chunk/atom. -*Computed temperature for fix temp/berendsen cannot be 0.0* - Self-explanatory. - *Computed temperature for fix temp/rescale cannot be 0.0* Cannot rescale the temperature to a new value if the current temperature is 0.0. @@ -2368,67 +1403,19 @@ Doc page with :doc:`WARNING messages ` The specified constraints did not allow this style of grid to be created. -*Could not evaluate Python function input variable* - Self-explanatory. - *Could not find Python function* The provided Python code was run successfully, but it not define a callable function with the required name. -*Could not find atom_modify first group ID* - Self-explanatory. - *Could not find change_box group ID* Group ID used in the change_box command does not exist. -*Could not find compute ID for PRD* - Self-explanatory. - -*Could not find compute ID for TAD* - Self-explanatory. - -*Could not find compute ID for temperature bias* - Self-explanatory. - -*Could not find compute ID to delete* - Self-explanatory. - -*Could not find compute displace/atom fix ID* - Self-explanatory. - -*Could not find compute event/displace fix ID* - Self-explanatory. - -*Could not find compute group ID* - Self-explanatory. - -*Could not find compute heat/flux compute ID* - Self-explanatory. - -*Could not find compute msd fix ID* - Self-explanatory. - *Could not find compute msd/chunk fix ID* The compute creates an internal fix, which has been deleted. *Could not find compute pressure temperature ID* The compute ID for calculating temperature does not exist. -*Could not find compute stress/atom temperature ID* - Self-explanatory. - -*Could not find compute vacf fix ID* - Self-explanatory. - -*Could not find compute/voronoi surface group ID* - Self-explanatory. - -*Could not find compute_modify ID* - Self-explanatory. - -*Could not find custom per-atom property ID* - Self-explanatory. - *Could not find delete_atoms group ID* Group ID used in the delete_atoms command does not exist. @@ -2438,61 +1425,16 @@ Doc page with :doc:`WARNING messages ` *Could not find displace_atoms group ID* Group ID used in the displace_atoms command does not exist. -*Could not find dump custom compute ID* - Self-explanatory. - -*Could not find dump custom fix ID* - Self-explanatory. - -*Could not find dump custom variable name* - Self-explanatory. - *Could not find dump group ID* A group ID used in the dump command does not exist. -*Could not find dump local compute ID* - Self-explanatory. - -*Could not find dump local fix ID* - Self-explanatory. - -*Could not find dump modify compute ID* - Self-explanatory. - -*Could not find dump modify custom atom floating point property ID* - Self-explanatory. - -*Could not find dump modify custom atom integer property ID* - Self-explanatory. - -*Could not find dump modify fix ID* - Self-explanatory. - -*Could not find dump modify variable name* - Self-explanatory. - -*Could not find fix ID to delete* - Self-explanatory. - *Could not find fix adapt storage fix ID* This should not happen unless you explicitly deleted a secondary fix that fix adapt created internally. -*Could not find fix halt variable name* - Self-explanatory. - -*Could not find fix gcmc exclusion group ID* - Self-explanatory. - -*Could not find fix gcmc rotation group ID* - Self-explanatory. - *Could not find fix group ID* A group ID used in the fix command does not exist. -*Could not find fix msst compute ID* - Self-explanatory. - *Could not find fix poems group ID* A group ID used in the fix poems command does not exist. @@ -2502,9 +1444,6 @@ Doc page with :doc:`WARNING messages ` *Could not find fix rigid group ID* A group ID used in the fix rigid command does not exist. -*Could not find fix srd group ID* - Self-explanatory. - *Could not find fix_modify ID* A fix ID used in the fix_modify command does not exist. @@ -2514,12 +1453,6 @@ Doc page with :doc:`WARNING messages ` *Could not find fix_modify temperature ID* The compute ID for computing temperature does not exist. -*Could not find group clear group ID* - Self-explanatory. - -*Could not find group delete group ID* - Self-explanatory. - *Could not find pair fix ID* A fix is created internally by the pair style to store shear history information. You cannot delete it. @@ -2527,9 +1460,6 @@ Doc page with :doc:`WARNING messages ` *Could not find set group ID* Group ID specified in set command does not exist. -*Could not find specified fix gcmc group ID* - Self-explanatory. - *Could not find thermo compute ID* Compute ID specified in thermo_style command does not exist. @@ -2541,15 +1471,9 @@ Doc page with :doc:`WARNING messages ` The fix ID needed by thermo style custom to compute a requested quantity does not exist. -*Could not find thermo custom variable name* - Self-explanatory. - *Could not find thermo fix ID* Fix ID specified in thermo_style command does not exist. -*Could not find thermo variable name* - Self-explanatory. - *Could not find thermo_modify pressure ID* The compute ID needed by thermo style custom to compute pressure does not exist. @@ -2572,15 +1496,6 @@ Doc page with :doc:`WARNING messages ` Could not initialize at least one of the devices specified for the gpu package -*Could not grab element entry from EIM potential file* - Self-explanatory - -*Could not grab global entry from EIM potential file* - Self-explanatory. - -*Could not grab pair entry from EIM potential file* - Self-explanatory. - *Could not initialize embedded Python* The main module in Python was not accessible. @@ -2616,9 +1531,6 @@ Doc page with :doc:`WARNING messages ` *Coulombic cut not supported in pair_style lj/long/dipole/long* Must use long-range Coulombic interactions. -*Cound not find dump_modify ID* - Self-explanatory. - *Create_atoms command before simulation box is defined* The create_atoms command cannot be used before a read_data, read_restart, or create_box command. @@ -2635,9 +1547,6 @@ Doc page with :doc:`WARNING messages ` *Create_atoms region ID does not exist* A region ID used in the create_atoms command does not exist. -*Create_bonds command before simulation box is defined* - Self-explanatory. - *Create_bonds command requires no kspace_style be defined* This is so that atom pairs that are already bonded to not appear in the neighbor list. @@ -2649,12 +1558,6 @@ Doc page with :doc:`WARNING messages ` *Create_bonds max distance > neighbor cutoff* Can only create bonds for atom pairs that will be in neighbor list. -*Create_bonds requires a pair style be defined* - Self-explanatory. - -*Create_box region ID does not exist* - Self-explanatory. - *Create_box region does not support a bounding box* Not all regions represent bounded volumes. You cannot use such a region with the create_box command. @@ -2667,21 +1570,6 @@ Doc page with :doc:`WARNING messages ` The command is accessing a vector added by the fix property/atom command, that does not exist. -*Custom per-atom property ID is not floating point* - Self-explanatory. - -*Custom per-atom property ID is not integer* - Self-explanatory. - -*Cut-offs missing in pair_style lj/long/dipole/long* - Self-explanatory. - -*Cutoffs missing in pair_style buck/long/coul/long* - Self-explanatory. - -*Cutoffs missing in pair_style lj/long/coul/long* - Self-explanatory. - *Cyclic loop in joint connections* Fix poems cannot (yet) work with coupled bodies whose joints connect the bodies in a ring (or cycle). @@ -2689,9 +1577,6 @@ Doc page with :doc:`WARNING messages ` *Degenerate lattice primitive vectors* Invalid set of 3 lattice vectors for lattice command. -*Delete region ID does not exist* - Self-explanatory. - *Delete_atoms command before simulation box is defined* The delete_atoms command cannot be used before a read_data, read_restart, or create_box command. @@ -2713,14 +1598,6 @@ Doc page with :doc:`WARNING messages ` *Delete_bonds command with no atoms existing* No atoms are yet defined so the delete_bonds command cannot be used. -*Deposition region extends outside simulation box* - Self-explanatory. - -*Did not assign all atoms correctly* - Atoms read in from a data file were not assigned correctly to - processors. This is likely due to some atom coordinates being - outside a non-periodic simulation box. - *Did not assign all restart atoms correctly* Atoms read in from the restart file were not assigned correctly to processors. This is likely due to some atom coordinates being outside @@ -2743,12 +1620,6 @@ Doc page with :doc:`WARNING messages ` *Did not set pressure for fix rigid/nph* The press keyword must be specified. -*Did not set temp for fix rigid/nvt/small* - Self-explanatory. - -*Did not set temp or press for fix rigid/npt/small* - Self-explanatory. - *Did not set temperature for fix rigid/nvt* The temp keyword must be specified. @@ -2765,18 +1636,6 @@ Doc page with :doc:`WARNING messages ` on a particular processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid dihedral. -*Dihedral atoms %d %d %d %d missing on proc %d at step %ld* - One or more of 4 atoms needed to compute a particular dihedral are - missing on this processor. Typically this is because the pairwise - cutoff is set too short or the dihedral has blown apart and an atom is - too far away. - -*Dihedral atoms missing on proc %d at step %ld* - One or more of 4 atoms needed to compute a particular dihedral are - missing on this processor. Typically this is because the pairwise - cutoff is set too short or the dihedral has blown apart and an atom is - too far away. - *Dihedral charmm is incompatible with Pair style* Dihedral style charmm must be used with a pair style charmm in order for the 1-4 epsilon/sigma parameters to be defined. @@ -2790,15 +1649,6 @@ Doc page with :doc:`WARNING messages ` No dihedral coefficients have been assigned in the data file or via the dihedral_coeff command. -*Dihedral style hybrid cannot have hybrid as an argument* - Self-explanatory. - -*Dihedral style hybrid cannot have none as an argument* - Self-explanatory. - -*Dihedral style hybrid cannot use same dihedral style twice* - Self-explanatory. - *Dihedral/improper extent > half of periodic box length* This error was detected by the neigh_modify check yes setting. It is an error because the dihedral atoms are so far apart it is ambiguous @@ -2830,9 +1680,6 @@ Doc page with :doc:`WARNING messages ` The dimension command cannot be used after a read_data, read_restart, or create_box command. -*Disk limit not supported by OS or illegal path* - Self-explanatory. - *Dispersion PPPMDisp order has been reduced below minorder* The default minimum order is 2. This can be reset by the kspace_modify minorder command. @@ -2841,9 +1688,6 @@ Doc page with :doc:`WARNING messages ` The displace_atoms command cannot be used before a read_data, read_restart, or create_box command. -*Distance must be > 0 for compute event/displace* - Self-explanatory. - *Divide by 0 in influence function* This should not normally occur. It is likely a problem with your model. @@ -2852,23 +1696,9 @@ Doc page with :doc:`WARNING messages ` This should not normally occur. It is likely a problem with your model. -*Divide by 0 in variable formula* - Self-explanatory. - -*Domain too large for neighbor bins* - The domain has become extremely large so that neighbor bins cannot be - used. Most likely, one or more atoms have been blown out of the - simulation box to a great distance. - -*Double precision is not supported on this accelerator* - Self-explanatory - *Dump atom/gz only writes compressed files* The dump atom/gz output file name must have a .gz suffix. -*Dump cfg arguments can not mix xs\|ys\|zs with xsu\|ysu\|zsu* - Self-explanatory. - *Dump cfg arguments must start with 'mass type xs ys zs' or 'mass type xsu ysu zsu'* This is a requirement of the CFG output format. See the dump cfg doc page for more details. @@ -2883,30 +1713,6 @@ Doc page with :doc:`WARNING messages ` The fix must produce per-atom quantities on timesteps that dump custom needs them. -*Dump custom compute does not calculate per-atom array* - Self-explanatory. - -*Dump custom compute does not calculate per-atom vector* - Self-explanatory. - -*Dump custom compute does not compute per-atom info* - Self-explanatory. - -*Dump custom compute vector is accessed out-of-range* - Self-explanatory. - -*Dump custom fix does not compute per-atom array* - Self-explanatory. - -*Dump custom fix does not compute per-atom info* - Self-explanatory. - -*Dump custom fix does not compute per-atom vector* - Self-explanatory. - -*Dump custom fix vector is accessed out-of-range* - Self-explanatory. - *Dump custom variable is not atom-style variable* Only atom-style variables generate per-atom quantities, needed for dump output. @@ -2927,132 +1733,36 @@ Doc page with :doc:`WARNING messages ` This is because a % signifies one file per processor and MPI-IO creates one large file for all processors. -*Dump file does not contain requested snapshot* - Self-explanatory. - -*Dump file is incorrectly formatted* - Self-explanatory. - -*Dump image body yes requires atom style body* - Self-explanatory. - -*Dump image bond not allowed with no bond types* - Self-explanatory. - -*Dump image cannot perform sorting* - Self-explanatory. - -*Dump image line requires atom style line* - Self-explanatory. - *Dump image requires one snapshot per file* Use a "\*" in the filename. -*Dump image tri requires atom style tri* - Self-explanatory. - *Dump local and fix not computed at compatible times* The fix must produce per-atom quantities on timesteps that dump local needs them. -*Dump local attributes contain no compute or fix* - Self-explanatory. - *Dump local cannot sort by atom ID* This is because dump local does not really dump per-atom info. -*Dump local compute does not calculate local array* - Self-explanatory. - -*Dump local compute does not calculate local vector* - Self-explanatory. - -*Dump local compute does not compute local info* - Self-explanatory. - -*Dump local compute vector is accessed out-of-range* - Self-explanatory. - *Dump local count is not consistent across input fields* Every column of output must be the same length. -*Dump local fix does not compute local array* - Self-explanatory. - -*Dump local fix does not compute local info* - Self-explanatory. - -*Dump local fix does not compute local vector* - Self-explanatory. - -*Dump local fix vector is accessed out-of-range* - Self-explanatory. - -*Dump modify bcolor not allowed with no bond types* - Self-explanatory. - -*Dump modify bdiam not allowed with no bond types* - Self-explanatory. - -*Dump modify compute ID does not compute per-atom array* - Self-explanatory. - -*Dump modify compute ID does not compute per-atom info* - Self-explanatory. - -*Dump modify compute ID does not compute per-atom vector* - Self-explanatory. - -*Dump modify compute ID vector is not large enough* - Self-explanatory. - *Dump modify element names do not match atom types* Number of element names must equal number of atom types. -*Dump modify fix ID does not compute per-atom array* - Self-explanatory. - -*Dump modify fix ID does not compute per-atom info* - Self-explanatory. - -*Dump modify fix ID does not compute per-atom vector* - Self-explanatory. - -*Dump modify fix ID vector is not large enough* - Self-explanatory. - -*Dump modify variable is not atom-style variable* - Self-explanatory. - -*Dump sort column is invalid* - Self-explanatory. - *Dump xtc requires sorting by atom ID* Use the dump_modify sort command to enable this. *Dump xyz/gz only writes compressed files* The dump xyz/gz output file name must have a .gz suffix. -*Dump_modify buffer yes not allowed for this style* - Self-explanatory. - *Dump_modify format string is too short* There are more fields to be dumped in a line of output than your format string specifies. -*Dump_modify region ID does not exist* - Self-explanatory. - *Dumping an atom property that is not allocated* The chosen atom style does not define the per-atom quantity being dumped. -*Duplicate atom IDs exist* - Self-explanatory. - -*Duplicate fields in read_dump command* - Self-explanatory. - *Duplicate particle in PeriDynamic bond - simulation box is too small* This is likely because your box length is shorter than 2 times the bond length. @@ -3067,20 +1777,9 @@ Doc page with :doc:`WARNING messages ` There is no variable syntax that uses empty brackets. Check the variable doc page. -*Energy was not tallied on needed timestep* - You are using a thermo keyword that requires potentials to - have tallied energy, but they did not on this timestep. See the - variable page for ideas on how to make this work. - -*Epsilon or sigma reference not set by pair style in PPPMDisp* - Self-explanatory. - *Epsilon or sigma reference not set by pair style in ewald/n* The pair style is not providing the needed epsilon or sigma values. -*Error in MEAM parameter file: keyword %s (further information)* - Self-explanatory. Check the parameter file. - *Error in vdw spline: inner radius > outer radius* A pre-tabulated spline is invalid. Likely a problem with the potential parameters. @@ -3118,57 +1817,9 @@ Doc page with :doc:`WARNING messages ` *File variable could not read value* Check the file assigned to the variable. -*Final box dimension due to fix deform is < 0.0* - Self-explanatory. - *Fix %s does not allow use of dynamic group* Dynamic groups have not yet been enabled for this fix. -*Fix ID for compute chunk/atom does not exist* - Self-explanatory. - -*Fix ID for compute erotate/rigid does not exist* - Self-explanatory. - -*Fix ID for compute ke/rigid does not exist* - Self-explanatory. - -*Fix ID for compute reduce does not exist* - Self-explanatory. - -*Fix ID for compute slice does not exist* - Self-explanatory. - -*Fix ID for fix ave/atom does not exist* - Self-explanatory. - -*Fix ID for fix ave/chunk does not exist* - Self-explanatory. - -*Fix ID for fix ave/correlate does not exist* - Self-explanatory. - -*Fix ID for fix ave/histo does not exist* - Self-explanatory. - -*Fix ID for fix ave/time does not exist* - Self-explanatory. - -*Fix ID for fix store/state does not exist* - Self-explanatory - -*Fix ID for fix vector does not exist* - Self-explanatory. - -*Fix ID for read_data does not exist* - Self-explanatory. - -*Fix ID for velocity does not exist* - Self-explanatory. - -*Fix ID must be alphanumeric or underscore characters* - Self-explanatory. - *Fix SRD: bad bin assignment for SRD advection* Something has gone wrong in your SRD model; try using more conservative settings. @@ -3191,12 +1842,6 @@ Doc page with :doc:`WARNING messages ` *Fix adapt interface to this pair style not supported* New coding for the pair style would need to be done. -*Fix adapt kspace style does not exist* - Self-explanatory. - -*Fix adapt pair style does not exist* - Self-explanatory - *Fix adapt pair style param not supported* The pair style does not know about the parameter you specified. @@ -3206,30 +1851,15 @@ Doc page with :doc:`WARNING messages ` *Fix adapt requires atom attribute diameter* The atom style being used does not specify an atom diameter. -*Fix adapt type pair range is not valid for pair hybrid sub-style* - Self-explanatory. - *Fix append/atoms requires a lattice be defined* Use the lattice command for this purpose. -*Fix ave/atom compute array is accessed out-of-range* - Self-explanatory. - -*Fix ave/atom compute does not calculate a per-atom array* - Self-explanatory. - *Fix ave/atom compute does not calculate a per-atom vector* A compute used by fix ave/atom must generate per-atom values. *Fix ave/atom compute does not calculate per-atom values* A compute used by fix ave/atom must generate per-atom values. -*Fix ave/atom fix array is accessed out-of-range* - Self-explanatory. - -*Fix ave/atom fix does not calculate a per-atom array* - Self-explanatory. - *Fix ave/atom fix does not calculate a per-atom vector* A fix used by fix ave/atom must generate per-atom values. @@ -3239,145 +1869,13 @@ Doc page with :doc:`WARNING messages ` *Fix ave/atom variable is not atom-style variable* A variable used by fix ave/atom must generate per-atom values. -*Fix ave/chunk compute does not calculate a per-atom array* - Self-explanatory. - -*Fix ave/chunk compute does not calculate a per-atom vector* - Self-explanatory. - -*Fix ave/chunk compute does not calculate per-atom values* - Self-explanatory. - -*Fix ave/chunk compute vector is accessed out-of-range* - Self-explanatory. - *Fix ave/chunk does not use chunk/atom compute* The specified compute is not for a compute chunk/atom command. -*Fix ave/chunk fix does not calculate a per-atom array* - Self-explanatory. - -*Fix ave/chunk fix does not calculate a per-atom vector* - Self-explanatory. - -*Fix ave/chunk fix does not calculate per-atom values* - Self-explanatory. - -*Fix ave/chunk fix vector is accessed out-of-range* - Self-explanatory. - -*Fix ave/chunk variable is not atom-style variable* - Self-explanatory. - -*Fix ave/correlate compute does not calculate a scalar* - Self-explanatory. - -*Fix ave/correlate compute does not calculate a vector* - Self-explanatory. - -*Fix ave/correlate compute vector is accessed out-of-range* - The index for the vector is out of bounds. - -*Fix ave/correlate fix does not calculate a scalar* - Self-explanatory. - -*Fix ave/correlate fix does not calculate a vector* - Self-explanatory. - -*Fix ave/correlate fix vector is accessed out-of-range* - The index for the vector is out of bounds. - -*Fix ave/correlate variable is not equal-style variable* - Self-explanatory. - -*Fix ave/histo cannot input local values in scalar mode* - Self-explanatory. - -*Fix ave/histo cannot input per-atom values in scalar mode* - Self-explanatory. - -*Fix ave/histo compute array is accessed out-of-range* - Self-explanatory. - -*Fix ave/histo compute does not calculate a global array* - Self-explanatory. - -*Fix ave/histo compute does not calculate a global scalar* - Self-explanatory. - -*Fix ave/histo compute does not calculate a global vector* - Self-explanatory. - -*Fix ave/histo compute does not calculate a local array* - Self-explanatory. - -*Fix ave/histo compute does not calculate a local vector* - Self-explanatory. - -*Fix ave/histo compute does not calculate a per-atom array* - Self-explanatory. - -*Fix ave/histo compute does not calculate a per-atom vector* - Self-explanatory. - -*Fix ave/histo compute does not calculate local values* - Self-explanatory. - -*Fix ave/histo compute does not calculate per-atom values* - Self-explanatory. - -*Fix ave/histo compute vector is accessed out-of-range* - Self-explanatory. - -*Fix ave/histo fix array is accessed out-of-range* - Self-explanatory. - -*Fix ave/histo fix does not calculate a global array* - Self-explanatory. - -*Fix ave/histo fix does not calculate a global scalar* - Self-explanatory. - -*Fix ave/histo fix does not calculate a global vector* - Self-explanatory. - -*Fix ave/histo fix does not calculate a local array* - Self-explanatory. - -*Fix ave/histo fix does not calculate a local vector* - Self-explanatory. - -*Fix ave/histo fix does not calculate a per-atom array* - Self-explanatory. - -*Fix ave/histo fix does not calculate a per-atom vector* - Self-explanatory. - -*Fix ave/histo fix does not calculate local values* - Self-explanatory. - -*Fix ave/histo fix does not calculate per-atom values* - Self-explanatory. - -*Fix ave/histo fix vector is accessed out-of-range* - Self-explanatory. - -*Fix ave/histo input is invalid compute* - Self-explanatory. - -*Fix ave/histo input is invalid fix* - Self-explanatory. - -*Fix ave/histo input is invalid variable* - Self-explanatory. - *Fix ave/histo inputs are not all global, peratom, or local* All inputs in a single fix ave/histo command must be of the same style. -*Fix ave/histo/weight value and weight vector lengths do not match* - Self-explanatory. - *Fix ave/time cannot set output array intensive/extensive from these inputs* One of more of the vector inputs has individual elements which are flagged as intensive or extensive. Such an input cannot be flagged as @@ -3386,48 +1884,6 @@ Doc page with :doc:`WARNING messages ` *Fix ave/time cannot use variable with vector mode* Variables produce scalar values. -*Fix ave/time columns are inconsistent lengths* - Self-explanatory. - -*Fix ave/time compute array is accessed out-of-range* - An index for the array is out of bounds. - -*Fix ave/time compute does not calculate a scalar* - Self-explanatory. - -*Fix ave/time compute does not calculate a vector* - Self-explanatory. - -*Fix ave/time compute does not calculate an array* - Self-explanatory. - -*Fix ave/time compute vector is accessed out-of-range* - The index for the vector is out of bounds. - -*Fix ave/time fix array cannot be variable length* - Self-explanatory. - -*Fix ave/time fix array is accessed out-of-range* - An index for the array is out of bounds. - -*Fix ave/time fix does not calculate a scalar* - Self-explanatory. - -*Fix ave/time fix does not calculate a vector* - Self-explanatory. - -*Fix ave/time fix does not calculate an array* - Self-explanatory. - -*Fix ave/time fix vector cannot be variable length* - Self-explanatory. - -*Fix ave/time fix vector is accessed out-of-range* - The index for the vector is out of bounds. - -*Fix ave/time variable is not equal-style variable* - Self-explanatory. - *Fix balance rcb cannot be used with comm_style brick* Comm_style tiled must be used instead. @@ -3439,19 +1895,10 @@ Doc page with :doc:`WARNING messages ` acquire needed info, The comm_modify cutoff command can be used to extend the communication range. -*Fix bond/create angle type is invalid* - Self-explanatory. - *Fix bond/create cutoff is longer than pairwise cutoff* This is not allowed because bond creation is done using the pairwise neighbor list. -*Fix bond/create dihedral type is invalid* - Self-explanatory. - -*Fix bond/create improper type is invalid* - Self-explanatory. - *Fix bond/create induced too many angles/dihedrals/impropers per atom* See the read_data command for info on using the "extra/angle/per/atom", (or dihedral, improper) keywords to allow for additional @@ -3498,15 +1945,6 @@ Doc page with :doc:`WARNING messages ` comm_modify cutoff command can be used to extend the communication range. -*Fix bond/react: A deleted atom cannot remain bonded to an atom that is not deleted* - Self-explanatory. - -*Fix bond/react: First neighbors of chiral atoms must be of mutually different types* - Self-explanatory. - -*Fix bond/react: Chiral atoms must have exactly four first neighbors* - Self-explanatory. - *Fix bond/react: Molecule template 'Coords' section required for chiralIDs keyword* The coordinates of atoms in the pre-reacted template are used to determine chirality. @@ -3524,12 +1962,6 @@ Doc page with :doc:`WARNING messages ` *Fix bond/swap cannot use dihedral or improper styles* These styles cannot be defined when using this fix. -*Fix bond/swap requires pair and bond styles* - Self-explanatory. - -*Fix bond/swap requires special_bonds = 0,1,1* - Self-explanatory. - *Fix box/relax generated negative box length* The pressure being applied is likely too large. Try applying it incrementally, to build to the high pressure. @@ -3555,12 +1987,6 @@ Doc page with :doc:`WARNING messages ` *Fix deform volume setting is invalid* Cannot use volume style unless other dimensions are being controlled. -*Fix deposit and fix rigid/small not using same molecule template ID* - Self-explanatory. - -*Fix deposit and fix shake not using same molecule template ID* - Self-explanatory. - *Fix deposit molecule must have atom types* The defined molecule does not specify atom types. @@ -3578,9 +2004,6 @@ Doc page with :doc:`WARNING messages ` Not all regions represent bounded volumes. You cannot use such a region with the fix deposit command. -*Fix deposit shake fix does not exist* - Self-explanatory. - *Fix efield requires atom attribute q or mu* The atom style defined does not have this attribute. @@ -3628,28 +2051,16 @@ Doc page with :doc:`WARNING messages ` *Fix freeze requires atom attribute torque* The atom style defined does not have this attribute. -*Fix gcmc and fix shake not using same molecule template ID* - Self-explanatory. - -*Fix gcmc atom has charge, but atom style does not* - Self-explanatory. - *Fix gcmc cannot exchange individual atoms belonging to a molecule* This is an error since you should not delete only one atom of a molecule. The user has specified atomic (non-molecular) gas exchanges, but an atom belonging to a molecule could be deleted. -*Fix gcmc does not (yet) work with atom_style template* - Self-explanatory. - *Fix gcmc molecule command requires that atoms have molecule attributes* Should not choose the gcmc molecule feature if no molecules are being simulated. The general molecule flag is off, but gcmc's molecule flag is on. -*Fix gcmc molecule has charges, but atom style does not* - Self-explanatory. - *Fix gcmc molecule must have atom types* The defined molecule does not specify atom types. @@ -3676,39 +2087,6 @@ Doc page with :doc:`WARNING messages ` Not all regions represent bounded volumes. You cannot use such a region with the fix gcmc command. -*Fix gcmc region extends outside simulation box* - Self-explanatory. - -*Fix gcmc shake fix does not exist* - Self-explanatory. - -*Fix gld c coefficients must be >= 0* - Self-explanatory. - -*Fix gld needs more prony series coefficients* - Self-explanatory. - -*Fix gld prony terms must be > 0* - Self-explanatory. - -*Fix gld series type must be pprony for now* - Self-explanatory. - -*Fix gld start temperature must be >= 0* - Self-explanatory. - -*Fix gld stop temperature must be >= 0* - Self-explanatory. - -*Fix gld tau coefficients must be > 0* - Self-explanatory. - -*Fix halt variable is not equal-style variable* - Self-explanatory. - -*Fix heat group has no atoms* - Self-explanatory. - *Fix heat kinetic energy of an atom went negative* This will cause the velocity rescaling about to be performed by fix heat to be invalid. @@ -3724,69 +2102,24 @@ Doc page with :doc:`WARNING messages ` *Fix langevin angmom is not yet implemented with kokkos* This option is not yet available. -*Fix langevin angmom requires atom style ellipsoid* - Self-explanatory. - *Fix langevin angmom requires extended particles* This fix option cannot be used with point particles. -*Fix langevin gjf and respa are not compatible* - Self-explanatory. - *Fix langevin gjf cannot have period equal to dt/2* If the period is equal to dt/2 then division by zero will happen. -*Fix langevin gjf should come before fix nve* - Self-explanatory. - *Fix langevin gjf with tbias is not yet implemented with kokkos* This option is not yet available. *Fix langevin omega is not yet implemented with kokkos* This option is not yet available. -*Fix langevin omega requires atom style sphere* - Self-explanatory. - *Fix langevin omega requires extended particles* One of the particles has radius 0.0. *Fix langevin period must be > 0.0* The time window for temperature relaxation must be > 0 -*Fix langevin variable returned negative temperature* - Self-explanatory. - -*Fix momentum group has no atoms* - Self-explanatory. - -*Fix move cannot define z or vz variable for 2d problem* - Self-explanatory. - -*Fix move cannot rotate aroung non z-axis for 2d problem* - Self-explanatory. - -*Fix move cannot set linear z motion for 2d problem* - Self-explanatory. - -*Fix move cannot set wiggle z motion for 2d problem* - Self-explanatory. - -*Fix msst compute ID does not compute potential energy* - Self-explanatory. - -*Fix msst compute ID does not compute pressure* - Self-explanatory. - -*Fix msst compute ID does not compute temperature* - Self-explanatory. - -*Fix msst requires a periodic box* - Self-explanatory. - -*Fix msst tscale must satisfy 0 <= tscale < 1* - Self-explanatory. - *Fix npt/nph has tilted box too far in one step - periodic cell is too far from equilibrium state* Self-explanatory. The change in the box tilt is too extreme on a short timescale. @@ -3806,61 +2139,22 @@ Doc page with :doc:`WARNING messages ` *Fix nve/asphere requires extended particles* This fix can only be used for particles with a shape setting. -*Fix nve/asphere/noforce requires atom style ellipsoid* - Self-explanatory. - *Fix nve/asphere/noforce requires extended particles* One of the particles is not an ellipsoid. -*Fix nve/body requires atom style body* - Self-explanatory. - *Fix nve/body requires bodies* This fix can only be used for particles that are bodies. -*Fix nve/line can only be used for 2d simulations* - Self-explanatory. - -*Fix nve/line requires atom style line* - Self-explanatory. - -*Fix nve/line requires line particles* - Self-explanatory. - *Fix nve/sphere dipole requires atom attribute mu* An atom style with this attribute is needed. -*Fix nve/sphere requires atom style sphere* - Self-explanatory. - *Fix nve/sphere requires extended particles* This fix can only be used for particles of a finite size. -*Fix nve/tri can only be used for 3d simulations* - Self-explanatory. - -*Fix nve/tri requires atom style tri* - Self-explanatory. - -*Fix nve/tri requires tri particles* - Self-explanatory. - *Fix nvt/nph/npt asphere requires extended particles* The shape setting for a particle in the fix group has shape = 0.0, which means it is a point particle. -*Fix nvt/nph/npt body requires bodies* - Self-explanatory. - -*Fix nvt/nph/npt sphere requires atom style sphere* - Self-explanatory. - -*Fix nvt/npt/nph damping parameters must be > 0.0* - Self-explanatory. - -*Fix nvt/npt/nph dilate group ID does not exist* - Self-explanatory. - *Fix nvt/sphere requires extended particles* This fix can only be used for particles of a finite size. @@ -3879,15 +2173,6 @@ Doc page with :doc:`WARNING messages ` *Fix peri neigh does not exist* Somehow a fix that the pair style defines has been deleted. -*Fix pour and fix rigid/small not using same molecule template ID* - Self-explanatory. - -*Fix pour and fix shake not using same molecule template ID* - Self-explanatory. - -*Fix pour insertion count per timestep is 0* - Self-explanatory. - *Fix pour molecule must have atom types* The defined molecule does not specify atom types. @@ -3898,12 +2183,6 @@ Doc page with :doc:`WARNING messages ` When using atom_style template, you cannot pour molecules that are not in that template. -*Fix pour polydisperse fractions do not sum to 1.0* - Self-explanatory. - -*Fix pour region ID does not exist* - Self-explanatory. - *Fix pour region cannot be dynamic* Only static regions can be used with fix pour. @@ -3914,187 +2193,49 @@ Doc page with :doc:`WARNING messages ` *Fix pour requires atom attributes radius, rmass* The atom style defined does not have these attributes. -*Fix pour rigid fix does not exist* - Self-explanatory. - -*Fix pour shake fix does not exist* - Self-explanatory. - -*Fix press/berendsen damping parameters must be > 0.0* - Self-explanatory. - -*Fix property/atom cannot specify mol twice* - Self-explanatory. - -*Fix property/atom cannot specify q twice* - Self-explanatory. - -*Fix property/atom mol when atom_style already has molecule attribute* - Self-explanatory. - -*Fix property/atom q when atom_style already has charge attribute* - Self-explanatory. - *Fix property/atom vector name already exists* The name for an integer or floating-point vector must be unique. -*Fix qeq has negative upper Taper radius cutoff* - Self-explanatory. - -*Fix qeq/comb group has no atoms* - Self-explanatory. - *Fix qeq/comb requires atom attribute q* An atom style with charge must be used to perform charge equilibration. -*Fix qeq/dynamic group has no atoms* - Self-explanatory. - -*Fix qeq/dynamic requires atom attribute q* - Self-explanatory. - -*Fix qeq/fire group has no atoms* - Self-explanatory. - -*Fix qeq/fire requires atom attribute q* - Self-explanatory. - -*Fix qeq/point group has no atoms* - Self-explanatory. - *Fix qeq/point has insufficient QEq matrix size* Occurs when number of neighbor atoms for an atom increased too much during a run. Increase SAFE_ZONE and MIN_CAP in fix_qeq.h and re-compile. -*Fix qeq/point requires atom attribute q* - Self-explanatory. - -*Fix qeq/shielded group has no atoms* - Self-explanatory. - *Fix qeq/shielded has insufficient QEq matrix size* Occurs when number of neighbor atoms for an atom increased too much during a run. Increase SAFE_ZONE and MIN_CAP in fix_qeq.h and re-compile. -*Fix qeq/shielded requires atom attribute q* - Self-explanatory. - *Fix qeq/slater could not extract params from pair coul/streitz* This should not happen unless pair coul/streitz has been altered. -*Fix qeq/slater group has no atoms* - Self-explanatory. - *Fix qeq/slater has insufficient QEq matrix size* Occurs when number of neighbor atoms for an atom increased too much during a run. Increase SAFE_ZONE and MIN_CAP in fix_qeq.h and re-compile. -*Fix qeq/slater requires atom attribute q* - Self-explanatory. - *Fix reax/bonds numbonds > nsbmax_most* The limit of the number of bonds expected by the ReaxFF force field was exceeded. -*Fix recenter group has no atoms* - Self-explanatory. - -*Fix restrain requires an atom map, see atom_modify* - Self-explanatory. - *Fix rigid atom has non-zero image flag in a non-periodic dimension* Image flags for non-periodic dimensions should not be set. -*Fix rigid file has no lines* - Self-explanatory. - -*Fix rigid langevin period must be > 0.0* - Self-explanatory. - -*Fix rigid molecule requires atom attribute molecule* - Self-explanatory. - -*Fix rigid npt/nph dilate group ID does not exist* - Self-explanatory. - *Fix rigid npt/nph does not yet allow triclinic box* This is a current restriction in LAMMPS. -*Fix rigid npt/nph period must be > 0.0* - Self-explanatory. - -*Fix rigid npt/small t_chain should not be less than 1* - Self-explanatory. - -*Fix rigid npt/small t_order must be 3 or 5* - Self-explanatory. - -*Fix rigid nvt/npt/nph damping parameters must be > 0.0* - Self-explanatory. - -*Fix rigid nvt/small t_chain should not be less than 1* - Self-explanatory. - -*Fix rigid nvt/small t_iter should not be less than 1* - Self-explanatory. - -*Fix rigid nvt/small t_order must be 3 or 5* - Self-explanatory. - -*Fix rigid xy torque cannot be on for 2d simulation* - Self-explanatory. - -*Fix rigid z force cannot be on for 2d simulation* - Self-explanatory. - -*Fix rigid/npt period must be > 0.0* - Self-explanatory. - -*Fix rigid/npt temperature order must be 3 or 5* - Self-explanatory. - -*Fix rigid/npt/small period must be > 0.0* - Self-explanatory. - -*Fix rigid/nvt period must be > 0.0* - Self-explanatory. - -*Fix rigid/nvt temperature order must be 3 or 5* - Self-explanatory. - -*Fix rigid/nvt/small period must be > 0.0* - Self-explanatory. - *Fix rigid/small atom has non-zero image flag in a non-periodic dimension* Image flags for non-periodic dimensions should not be set. -*Fix rigid/small langevin period must be > 0.0* - Self-explanatory. - *Fix rigid/small molecule must have atom types* The defined molecule does not specify atom types. *Fix rigid/small molecule must have coordinates* The defined molecule does not specify coordinates. -*Fix rigid/small npt/nph period must be > 0.0* - Self-explanatory. - -*Fix rigid/small nvt/npt/nph damping parameters must be > 0.0* - Self-explanatory. - -*Fix rigid/small nvt/npt/nph dilate group ID does not exist* - Self-explanatory. - -*Fix rigid/small requires an atom map, see atom_modify* - Self-explanatory. - -*Fix rigid/small requires atom attribute molecule* - Self-explanatory. - *Fix rigid: Bad principal moments* The principal moments of inertia computed for a rigid body are not within the required tolerances. @@ -4106,9 +2247,6 @@ Doc page with :doc:`WARNING messages ` *Fix shake molecule template must have shake info* The defined molecule does not specify SHAKE information. -*Fix spring couple group ID does not exist* - Self-explanatory. - *Fix srd can only currently be used with comm_style brick* This is a current restriction in LAMMPS. @@ -4119,18 +2257,9 @@ Doc page with :doc:`WARNING messages ` This is because the SRD collisions will impart torque to the solute particles. -*Fix srd requires SRD particles all have same mass* - Self-explanatory. - *Fix srd requires ghost atoms store velocity* Use the comm_modify vel yes command to enable this. -*Fix srd requires newton pair on* - Self-explanatory. - -*Fix store/state compute array is accessed out-of-range* - Self-explanatory. - *Fix store/state compute does not calculate a per-atom array* The compute calculates a per-atom vector. @@ -4141,9 +2270,6 @@ Doc page with :doc:`WARNING messages ` Computes that calculate global or local quantities cannot be used with fix store/state. -*Fix store/state fix array is accessed out-of-range* - Self-explanatory. - *Fix store/state fix does not calculate a per-atom array* The fix calculates a per-atom vector. @@ -4154,71 +2280,20 @@ Doc page with :doc:`WARNING messages ` Fixes that calculate global or local quantities cannot be used with fix store/state. -*Fix store/state for atom property that is not allocated* - Self-explanatory. - *Fix store/state variable is not atom-style variable* Only atom-style variables calculate per-atom quantities. -*Fix temp/berendsen period must be > 0.0* - Self-explanatory. - -*Fix temp/berendsen variable returned negative temperature* - Self-explanatory. - *Fix temp/csld is not compatible with fix rattle or fix shake* These two commands cannot currently be used together with fix temp/csld. -*Fix temp/csld variable returned negative temperature* - Self-explanatory. - -*Fix temp/csvr variable returned negative temperature* - Self-explanatory. - -*Fix temp/rescale variable returned negative temperature* - Self-explanatory. - -*Fix tfmc displacement length must be > 0* - Self-explanatory. - *Fix tfmc is not compatible with fix shake* These two commands cannot currently be used together. -*Fix tfmc temperature must be > 0* - Self-explanatory. - -*Fix thermal/conductivity swap value must be positive* - Self-explanatory. - *Fix tmd must come after integration fixes* Any fix tmd command must appear in the input script after all time integration fixes (nve, nvt, npt). See the fix tmd documentation for details. -*Fix ttm electron temperatures must be > 0.0* - Self-explanatory. - -*Fix ttm electronic_density must be > 0.0* - Self-explanatory. - -*Fix ttm electronic_specific_heat must be > 0.0* - Self-explanatory. - -*Fix ttm electronic_thermal_conductivity must be >= 0.0* - Self-explanatory. - -*Fix ttm gamma_p must be > 0.0* - Self-explanatory. - -*Fix ttm gamma_s must be >= 0.0* - Self-explanatory. - -*Fix ttm number of nodes must be > 0* - Self-explanatory. - -*Fix ttm v_0 must be >= 0.0* - Self-explanatory. - *Fix used in compute chunk/atom not computed at compatible time* The chunk/atom compute cannot query the output of the fix on a timestep it is needed. @@ -4235,39 +2310,6 @@ Doc page with :doc:`WARNING messages ` The inputs to the command have conflicting intensive/extensive attributes. You need to use more than one fix vector command. -*Fix vector compute does not calculate a scalar* - Self-explanatory. - -*Fix vector compute does not calculate a vector* - Self-explanatory. - -*Fix vector compute vector is accessed out-of-range* - Self-explanatory. - -*Fix vector fix does not calculate a scalar* - Self-explanatory. - -*Fix vector fix does not calculate a vector* - Self-explanatory. - -*Fix vector fix vector is accessed out-of-range* - Self-explanatory. - -*Fix vector variable is not equal-style variable* - Self-explanatory. - -*Fix viscosity swap value must be positive* - Self-explanatory. - -*Fix viscosity vtarget value must be positive* - Self-explanatory. - -*Fix wall cutoff <= 0.0* - Self-explanatory. - -*Fix wall/colloid requires atom style sphere* - Self-explanatory. - *Fix wall/colloid requires extended particles* One of the particles has radius 0.0. @@ -4275,21 +2317,12 @@ Doc page with :doc:`WARNING messages ` Must use a granular pair style to define the parameters needed for this fix. -*Fix wall/gran requires atom style sphere* - Self-explanatory. - *Fix wall/piston command only available at zlo* The face keyword must be zlo. -*Fix wall/region colloid requires atom style sphere* - Self-explanatory. - *Fix wall/region colloid requires extended particles* One of the particles has radius 0.0. -*Fix wall/region cutoff <= 0.0* - Self-explanatory. - *Fix_modify pressure ID does not compute pressure* The compute ID assigned to the fix must compute pressure. @@ -4303,12 +2336,6 @@ Doc page with :doc:`WARNING messages ` *Found no restart file matching pattern* When using a "\*" in the restart file name, no matching file was found. -*GPU library not compiled for this accelerator* - Self-explanatory. - -*GPU package does not (yet) work with atom_style template* - Self-explanatory. - *GPU particle split must be set to 1 for this pair style.* For this pair style, you cannot run part of the force calculation on the host. See the package command. @@ -4325,21 +2352,12 @@ Doc page with :doc:`WARNING messages ` *Gravity changed since fix pour was created* The gravity vector defined by fix gravity must be static. -*Gravity must point in -y to use with fix pour in 2d* - Self-explanatory. - -*Gravity must point in -z to use with fix pour in 3d* - Self-explanatory. - *Grmask function in equal-style variable formula* Grmask is per-atom operation. *Group ID does not exist* A group ID used in the group command does not exist. -*Group ID in variable formula does not exist* - Self-explanatory. - *Group all cannot be made dynamic* This operation is not allowed. @@ -4347,15 +2365,6 @@ Doc page with :doc:`WARNING messages ` The group command cannot be used before a read_data, read_restart, or create_box command. -*Group dynamic cannot reference itself* - Self-explanatory. - -*Group dynamic parent group cannot be dynamic* - Self-explanatory. - -*Group dynamic parent group does not exist* - Self-explanatory. - *Group region ID does not exist* A region ID used in the group command does not exist. @@ -4388,19 +2397,10 @@ Doc page with :doc:`WARNING messages ` One or more of the coefficients defined in the potential file is invalid. -*Illegal compute voronoi/atom command (occupation and (surface or edges))* - Self-explanatory. - *Illegal coul/streitz parameter* One or more of the coefficients defined in the potential file is invalid. -*Illegal dump_modify sfactor value (must be > 0.0)* - Self-explanatory. - -*Illegal dump_modify tfactor value (must be > 0.0)* - Self-explanatory. - *Illegal fix gcmc gas mass <= 0* The computed mass of the designated gas molecule or atom type was less than or equal to zero. @@ -4411,9 +2411,6 @@ Doc page with :doc:`WARNING messages ` *Illegal fix wall/piston velocity* The piston velocity must be positive. -*Illegal integrate style* - Self-explanatory. - *Illegal nb3b/harmonic parameter* One or more of the coefficients defined in the potential file is invalid. @@ -4462,18 +2459,6 @@ Doc page with :doc:`WARNING messages ` on a particular processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid improper. -*Improper atoms %d %d %d %d missing on proc %d at step %ld* - One or more of 4 atoms needed to compute a particular improper are - missing on this processor. Typically this is because the pairwise - cutoff is set too short or the improper has blown apart and an atom is - too far away. - -*Improper atoms missing on proc %d at step %ld* - One or more of 4 atoms needed to compute a particular improper are - missing on this processor. Typically this is because the pairwise - cutoff is set too short or the improper has blown apart and an atom is - too far away. - *Improper coeff for hybrid has invalid style* Improper style hybrid uses another improper style as one of its coefficients. The improper style used in the improper_coeff command @@ -4483,15 +2468,6 @@ Doc page with :doc:`WARNING messages ` No improper coefficients have been assigned in the data file or via the improper_coeff command. -*Improper style hybrid cannot have hybrid as an argument* - Self-explanatory. - -*Improper style hybrid cannot have none as an argument* - Self-explanatory. - -*Improper style hybrid cannot use same improper style twice* - Self-explanatory. - *Improper_coeff command before improper_style is defined* Coefficients cannot be set in the data file or via the improper_coeff command until an improper_style has been assigned. @@ -4554,24 +2530,6 @@ Doc page with :doc:`WARNING messages ` *Incorrect SNAP parameter file* The file cannot be parsed correctly, check its internal syntax. -*Incorrect args for angle coefficients* - Self-explanatory. Check the input script or data file. - -*Incorrect args for bond coefficients* - Self-explanatory. Check the input script or data file. - -*Incorrect args for dihedral coefficients* - Self-explanatory. Check the input script or data file. - -*Incorrect args for improper coefficients* - Self-explanatory. Check the input script or data file. - -*Incorrect args for pair coefficients* - Self-explanatory. Check the input script or data file. - -*Incorrect args in pair_style command* - Self-explanatory. - *Incorrect atom format in data file* Number of values per atom line in the data file is not consistent with the atom style. @@ -4610,10 +2568,6 @@ Doc page with :doc:`WARNING messages ` *Incorrect element names in EAM potential file* The element names in the EAM file do not match those requested. -*Incorrect format of ... section in data file* - Number or type of values per line in the given section of the data file - is not consistent with the requirements for this section. - *Incorrect format in COMB potential file* Incorrect number of words per line in the potential file. @@ -4650,49 +2604,25 @@ Doc page with :doc:`WARNING messages ` *Incorrect integer value in Bodies section of data file* See page for body style. -*Incorrect multiplicity arg for dihedral coefficients* - Self-explanatory. Check the input script or data file. - -*Incorrect number of elements in potential file* - Self-explanatory. - *Incorrect rigid body format in fix rigid file* The number of fields per line is not what expected. *Incorrect rigid body format in fix rigid/small file* The number of fields per line is not what expected. -*Incorrect sign arg for dihedral coefficients* - Self-explanatory. Check the input script or data file. - -*Incorrect table format check for element types* - Self-explanatory. - *Incorrect velocity format in data file* Each atom style defines a format for the Velocity section of the data file. The read-in lines do not match. -*Incorrect weight arg for dihedral coefficients* - Self-explanatory. Check the input script or data file. - -*Index between variable brackets must be positive* - Self-explanatory. - *Indexed per-atom vector in variable formula without atom map* Accessing a value from an atom vector requires the ability to lookup an atom index, which is provided by an atom map. An atom map does not exist (by default) for non-molecular problems. Using the atom_modify map command will force an atom map to be created. -*Initial temperatures not all set in fix ttm* - Self-explanatory. - *Input line quote not followed by white-space* An end quote must be followed by white-space. -*Insertion region extends outside simulation box* - Self-explanatory. - *Insufficient Jacobi rotations for POEMS body* Eigensolve for rigid body was not sufficiently accurate. @@ -4716,62 +2646,17 @@ Doc page with :doc:`WARNING messages ` *Internal error in atom_style body* This error should not occur. Contact the developers. -*Invalid -reorder N value* - Self-explanatory. - -*Invalid Angles section in molecule file* - Self-explanatory. - -*Invalid Bonds section in molecule file* - Self-explanatory. - -*Invalid Boolean syntax in if command* - Self-explanatory. - -*Invalid Charges section in molecule file* - Self-explanatory. - -*Invalid Coords section in molecule file* - Self-explanatory. - -*Invalid Diameters section in molecule file* - Self-explanatory. - -*Invalid Dihedrals section in molecule file* - Self-explanatory. - -*Invalid Impropers section in molecule file* - Self-explanatory. - -*Invalid Kokkos command-line args* - Self-explanatory. See Section 2.7 of the manual for details. - *Invalid LAMMPS restart file* The file does not appear to be a LAMMPS restart file since it does not contain the correct magic string at the beginning. -*Invalid Masses section in molecule file* - Self-explanatory. - *Invalid molecule ID in molecule file* Molecule ID must be a non-zero positive integer. -*Invalid Molecules section in molecule file* - Self-explanatory. - *Invalid REAX atom type* There is a mis-match between LAMMPS atom types and the elements listed in the ReaxFF force field file. -*Invalid Special Bond Counts section in molecule file* - Self-explanatory. - -*Invalid Types section in molecule file* - Self-explanatory. - -*Invalid angle count in molecule file* - Self-explanatory. - *Invalid angle table length* Length must be 2 or greater. @@ -4779,12 +2664,6 @@ Doc page with :doc:`WARNING messages ` Angle type must be positive integer and within range of specified angle types. -*Invalid angle type in Angles section of molecule file* - Self-explanatory. - -*Invalid angle type index for fix shake* - Self-explanatory. - *Invalid args for non-hybrid pair coefficients* "NULL" is only supported in pair_coeff calls when using pair hybrid @@ -4800,9 +2679,6 @@ Doc page with :doc:`WARNING messages ` Atom IDs must be positive integers and within range of defined atoms. -*Invalid atom ID in Angles section of molecule file* - Self-explanatory. - *Invalid atom ID in Atoms section of data file* Atom IDs must be positive integers. @@ -4814,9 +2690,6 @@ Doc page with :doc:`WARNING messages ` Atom IDs must be positive integers and within range of defined atoms. -*Invalid atom ID in Bonds section of molecule file* - Self-explanatory. - *Invalid atom ID in Bonus section of data file* Atom IDs must be positive integers and within range of defined atoms. @@ -4825,9 +2698,6 @@ Doc page with :doc:`WARNING messages ` Atom IDs must be positive integers and within range of defined atoms. -*Invalid atom ID in Fragments section of molecule file* - Self-explanatory. - *Invalid atom ID in Impropers section of data file* Atom IDs must be positive integers and within range of defined atoms. @@ -4836,15 +2706,6 @@ Doc page with :doc:`WARNING messages ` Atom IDs must be positive integers and within range of defined atoms. -*Invalid atom ID in dihedrals section of molecule file* - Self-explanatory. - -*Invalid atom ID in impropers section of molecule file* - Self-explanatory. - -*Invalid atom ID in variable file* - Self-explanatory. - *Invalid atom IDs in neb file* An ID in the file was not found in the system. @@ -4873,12 +2734,6 @@ Doc page with :doc:`WARNING messages ` *Invalid atom type in fix atom/swap command* The atom type specified in the atom/swap command does not exist. -*Invalid atom type in fix bond/create command* - Self-explanatory. - -*Invalid atom type in fix deposit command* - Self-explanatory. - *Invalid atom type in fix deposit mol command* The atom types in the defined molecule are added to the value specified in the create_atoms command, as an offset. The final value @@ -4888,9 +2743,6 @@ Doc page with :doc:`WARNING messages ` *Invalid atom type in fix gcmc command* The atom type specified in the gcmc command does not exist. -*Invalid atom type in fix pour command* - Self-explanatory. - *Invalid atom type in fix pour mol command* The atom types in the defined molecule are added to the value specified in the create_atoms command, as an offset. The final value @@ -4915,18 +2767,6 @@ Doc page with :doc:`WARNING messages ` *Invalid atom_style body command* No body style argument was provided. -*Invalid atom_style command* - Self-explanatory. - -*Invalid attribute in dump custom command* - Self-explanatory. - -*Invalid attribute in dump local command* - Self-explanatory. - -*Invalid attribute in dump modify command* - Self-explanatory. - *Invalid basis setting in create_atoms command* The basis index must be between 1 to N where N is the number of basis atoms in the lattice. The type index must be between 1 to N where N @@ -4946,9 +2786,6 @@ Doc page with :doc:`WARNING messages ` *Invalid body nparticle command* Arguments in atom-style command are not correct. -*Invalid bond count in molecule file* - Self-explanatory. - *Invalid bond table length* Length must be 2 or greater. @@ -4956,21 +2793,6 @@ Doc page with :doc:`WARNING messages ` Bond type must be positive integer and within range of specified bond types. -*Invalid bond type in Bonds section of molecule file* - Self-explanatory. - -*Invalid bond type in create_bonds command* - Self-explanatory. - -*Invalid bond type in fix bond/break command* - Self-explanatory. - -*Invalid bond type in fix bond/create command* - Self-explanatory. - -*Invalid bond type index for fix shake* - Self-explanatory. Check the fix shake command in the input script. - *Invalid coeffs for this dihedral style* Cannot set class 2 coeffs in data file for this dihedral style. @@ -5074,22 +2896,10 @@ Doc page with :doc:`WARNING messages ` *Invalid density in set command* Density must be > 0.0. -*Invalid diameter in set command* - Self-explanatory. - -*Invalid dihedral count in molecule file* - Self-explanatory. - *Invalid dihedral type in Dihedrals section of data file* Dihedral type must be positive integer and within range of specified dihedral types. -*Invalid dihedral type in dihedrals section of molecule file* - Self-explanatory. - -*Invalid dipole length in set command* - Self-explanatory. - *Invalid displace_atoms rotate axis for 2d* Axis must be in z direction. @@ -5129,15 +2939,9 @@ Doc page with :doc:`WARNING messages ` *Invalid dump_modify threshold operator* Operator keyword used for threshold specification in not recognized. -*Invalid entry in -reorder file* - Self-explanatory. - *Invalid fix ID in variable formula* The fix is not recognized. -*Invalid fix ave/time off column* - Self-explanatory. - *Invalid fix box/relax command for a 2d simulation* Fix box/relax styles involving the z dimension cannot be used in a 2d simulation. @@ -5148,12 +2952,6 @@ Doc page with :doc:`WARNING messages ` *Invalid fix box/relax pressure settings* Settings for coupled dimensions must be the same. -*Invalid fix halt attribute* - Self-explanatory. - -*Invalid fix halt operator* - Self-explanatory. - *Invalid fix nvt/npt/nph command for a 2d simulation* Cannot control z dimension in a 2d model. @@ -5208,94 +3006,22 @@ Doc page with :doc:`WARNING messages ` *Invalid group function in variable formula* Group function is not recognized. -*Invalid group in comm_modify command* - Self-explanatory. - *Invalid image up vector* Up vector cannot be (0,0,0). *Invalid immediate variable* Syntax of immediate value is incorrect. -*Invalid improper count in molecule file* - Self-explanatory. - *Invalid improper type in Impropers section of data file* Improper type must be positive integer and within range of specified improper types. -*Invalid improper type in impropers section of molecule file* - Self-explanatory. - *Invalid index for non-body particles in compute body/local command* Only indices 1,2,3 can be used for non-body particles. -*Invalid index in compute body/local command* - Self-explanatory. - -*Invalid is_active() function in variable formula* - Self-explanatory. - -*Invalid is_available() function in variable formula* - Self-explanatory. - -*Invalid is_defined() function in variable formula* - Self-explanatory. - -*Invalid keyword in angle table parameters* - Self-explanatory. - -*Invalid keyword in bond table parameters* - Self-explanatory. - -*Invalid keyword in compute angle/local command* - Self-explanatory. - -*Invalid keyword in compute bond/local command* - Self-explanatory. - -*Invalid keyword in compute dihedral/local command* - Self-explanatory. - -*Invalid keyword in compute improper/local command* - Self-explanatory. - -*Invalid keyword in compute pair/local command* - Self-explanatory. - -*Invalid keyword in compute property/atom command* - Self-explanatory. - -*Invalid keyword in compute property/chunk command* - Self-explanatory. - -*Invalid keyword in compute property/local command* - Self-explanatory. - -*Invalid keyword in dump cfg command* - Self-explanatory. - *Invalid keyword in pair table parameters* Keyword used in list of table parameters is not recognized. -*Invalid length in set command* - Self-explanatory. - -*Invalid mass in set command* - Self-explanatory. - -*Invalid mass line in data file* - Self-explanatory. - -*Invalid mass value* - Self-explanatory. - -*Invalid math function in variable formula* - Self-explanatory. - -*Invalid math/group/special function in variable formula* - Self-explanatory. - *Invalid option in lattice command for non-custom style* Certain lattice keywords are not supported unless the lattice style is "custom". @@ -5336,9 +3062,6 @@ Doc page with :doc:`WARNING messages ` *Invalid random number seed in set command* Random number seed must be > 0. -*Invalid replace values in compute reduce* - Self-explanatory. - *Invalid rigid body ID in fix rigid file* The ID does not match the number of an existing ID of rigid bodies that are defined by the fix rigid command. @@ -5351,12 +3074,6 @@ Doc page with :doc:`WARNING messages ` The number of timesteps must fit in a 32-bit integer. If you want to run for more steps than this, perform multiple shorter runs. -*Invalid run command start/stop value* - Self-explanatory. - -*Invalid run command upto value* - Self-explanatory. - *Invalid seed for Marsaglia random # generator* The initial seed for this random number generator must be a positive integer less than or equal to 900 million. @@ -5365,45 +3082,9 @@ Doc page with :doc:`WARNING messages ` The initial seed for this random number generator must be a positive integer. -*Invalid shake angle type in molecule file* - Self-explanatory. - -*Invalid shake atom in molecule file* - Self-explanatory. - -*Invalid shake bond type in molecule file* - Self-explanatory. - -*Invalid shake flag in molecule file* - Self-explanatory. - -*Invalid shape in Ellipsoids section of data file* - Self-explanatory. - *Invalid shape in Triangles section of data file* Two or more of the triangle corners are duplicate points. -*Invalid shape in set command* - Self-explanatory. - -*Invalid shear direction for fix wall/gran* - Self-explanatory. - -*Invalid special atom index in molecule file* - Self-explanatory. - -*Invalid special function in variable formula* - Self-explanatory. - -*Invalid style in pair_write command* - Self-explanatory. Check the input script. - -*Invalid syntax in variable formula* - Self-explanatory. - -*Invalid t_event in prd command* - Self-explanatory. - *Invalid t_event in tad command* The value must be greater than 0. @@ -5415,9 +3096,6 @@ Doc page with :doc:`WARNING messages ` The template indices must be between 1 to N, where N is the number of molecules in the template. -*Invalid thermo keyword in variable formula* - The keyword is not recognized. - *Invalid threads_per_atom specified.* For 3-body potentials on the GPU, the threads_per_atom setting cannot be greater than 4 for NVIDIA GPUs. @@ -5469,9 +3147,6 @@ Doc page with :doc:`WARNING messages ` *Invalid variable evaluation in variable formula* A variable used in a formula could not be evaluated. -*Invalid variable in next command* - Self-explanatory. - *Invalid variable name* Variable name used in an input script line is invalid. @@ -5488,21 +3163,6 @@ Doc page with :doc:`WARNING messages ` *Invalid volume in set command* Volume must be > 0.0. -*Invalid wiggle direction for fix wall/gran* - Self-explanatory. - -*Invoked angle equil angle on angle style none* - Self-explanatory. - -*Invoked angle single on angle style none* - Self-explanatory. - -*Invoked bond equil distance on bond style none* - Self-explanatory. - -*Invoked bond single on bond style none* - Self-explanatory. - *Invoked pair single on pair style none* A command (e.g. a dump) attempted to invoke the single() function on a pair style none, which is illegal. You are probably attempting to @@ -5519,12 +3179,6 @@ Doc page with :doc:`WARNING messages ` Model. Please contact the OpenKIM database maintainers to verify and potentially correct this. -*KOKKOS package does not yet support comm_style tiled* - Self-explanatory. - -*KOKKOS package requires a kokkos enabled atom_style* - Self-explanatory. - *KSpace accuracy must be > 0* The kspace accuracy designated in the input must be greater than zero. @@ -5549,9 +3203,6 @@ Doc page with :doc:`WARNING messages ` Setting a kspace style requires that a pair style with matching long-range Coulombic or dispersion components be used. -*Keyword %s in MEAM parameter file not recognized* - Self-explanatory. - *Kokkos has been compiled for CUDA but no GPUs are requested* One or more GPUs must be used when Kokkos is compiled for CUDA. @@ -5565,39 +3216,18 @@ Doc page with :doc:`WARNING messages ` the required accuracy via *force/disp/real* as well as *force/disp/kspace* is set. -*Kspace style does not support compute group/group* - Self-explanatory. - -*Kspace style pppm/disp/tip4p requires newton on* - Self-explanatory. - -*Kspace style pppm/tip4p requires newton on* - Self-explanatory. - *Kspace style requires atom attribute q* The atom style defined does not have these attributes. -*Kspace_modify eigtol must be smaller than one* - Self-explanatory. - *LAMMPS is not built with Python embedded* This is done by including the PYTHON package before LAMMPS is built. This is required to use python-style variables. -*LAMMPS unit_style lj not supported by KIM models* - Self-explanatory. Check the input script or data file. - -*LJ6 off not supported in pair_style buck/long/coul/long* - Self-explanatory. - *Label map is incomplete: all types must be assigned a unique type label* For a given type-kind (atom types, bond types, etc.) to be written to the data file, all associated types must be assigned a type label, and each type label can be assigned to only one numeric type. -*Label wasn't found in input script* - Self-explanatory. - *Labelmap command before simulation box is defined* The labelmap command cannot be used before a read_data, read_restart, or create_box command. @@ -5625,19 +3255,9 @@ Doc page with :doc:`WARNING messages ` 2d simulation can use sq, sq2, or hex lattice. 3d simulation can use sc, bcc, or fcc lattice. -*Log of zero/negative value in variable formula* - Self-explanatory. - *Lost atoms via balance: original %ld current %ld* This should not occur. Report the problem to the developers. -*Lost atoms: original %ld current %ld* - Lost atoms are checked for each time thermo output is done. See the - thermo_modify lost command for options. Lost atoms usually indicate - bad dynamics, e.g. atoms have been blown far out of the simulation - box, or moved further than one processor's subdomain away before - reneighboring. - *MEAM library error %d* A call to the MEAM Fortran library returned an error. @@ -5678,9 +3298,6 @@ Doc page with :doc:`WARNING messages ` The minimize command cannot be used before a read_data, read_restart, or create_box command. -*Mismatched brackets in variable* - Self-explanatory. - *Mismatched compute in variable formula* A compute is referenced incorrectly or a compute that produces per-atom values is used in an equal-style variable formula. @@ -5697,52 +3314,10 @@ Doc page with :doc:`WARNING messages ` produces per-atom values is used in an equal-style variable formula. -*Modulo 0 in variable formula* - Self-explanatory. - *Molecule IDs too large for compute chunk/atom* The IDs must not be larger than can be stored in a 32-bit integer since chunk IDs are 32-bit integers. -*Molecule auto special bond generation overflow* - Counts exceed maxspecial setting for other atoms in system. - -*Molecule file has angles but no nangles setting* - Self-explanatory. - -*Molecule file has body params but no setting for them* - Self-explanatory. - -*Molecule file has bonds but no nbonds setting* - Self-explanatory. - -*Molecule file has dihedrals but no ndihedrals setting* - Self-explanatory. - -*Molecule file has fragments but no nfragments setting* - Self-explanatory. - -*Molecule file has impropers but no nimpropers setting* - Self-explanatory. - -*Molecule file has no Body Doubles section* - Self-explanatory. - -*Molecule file has no Body Integers section* - Self-explanatory. - -*Molecule file has no Fragments section* - Self-explanatory. - -*Molecule file has special flags but no bonds* - Self-explanatory. - -*Molecule file needs both Special Bond sections* - Self-explanatory. - -*Molecule file requires atom style body* - Self-explanatory. - *Molecule file shake flags not before shake atoms* The order of the two sections is important. @@ -5755,52 +3330,6 @@ Doc page with :doc:`WARNING messages ` *Molecule file special list does not match special count* The number of values in an atom's special list does not match count. -*Molecule file z center-of-mass must be 0.0 for 2d* - Self-explanatory. - -*Molecule file z coord must be 0.0 for 2d* - Self-explanatory. - -*Molecule natoms must be 1 for body particle* - Self-explanatory. - -*Molecule sizescale must be 1.0 for body particle* - Self-explanatory. - -*Molecule template ID for atom_style template does not exist* - Self-explanatory. - -*Molecule template ID for create_atoms does not exist* - Self-explanatory. - -*Molecule template ID for fix deposit does not exist* - Self-explanatory. - -*Molecule template ID for fix gcmc does not exist* - Self-explanatory. - -*Molecule template ID for fix pour does not exist* - Self-explanatory. - -*Molecule template ID for fix rigid/small does not exist* - Self-explanatory. - -*Molecule template ID for fix shake does not exist* - Self-explanatory. - -*Molecule template ID must be alphanumeric or underscore characters* - Self-explanatory. - -*Molecule topology/atom exceeds system topology/atom* - The number of bonds, angles, etc per-atom in the molecule exceeds the - system setting. See the create_box command for how to specify these - values. - -*Molecule topology type exceeds system topology type* - The number of bond, angle, etc types in the molecule exceeds the - system setting. See the create_box command for how to specify these - values. - *More than one fix deform* Only one fix deform can be defined at a time. @@ -5811,9 +3340,6 @@ Doc page with :doc:`WARNING messages ` *More than one fix shake* Only one fix shake can be defined. -*Mu not allowed when not using semi-grand in fix atom/swap command* - Self-explanatory. - *Must define angle_style before Angle Coeffs* Must use an angle_style command before reading a data file that defines Angle Coeffs. @@ -5874,9 +3400,6 @@ Doc page with :doc:`WARNING messages ` Cannot use the temper command with only one processor partition. Use the -partition command-line option. -*Must not have multiple fixes change box parameter ...* - Self-explanatory. - *Must read Angle Type Labels before Angles* An Angle Type Labels section of a data file must come before the Angles section. @@ -5941,21 +3464,6 @@ Doc page with :doc:`WARNING messages ` *Must specify a region in fix deposit* The region keyword must be specified with this fix. -*Must specify a region in fix pour* - Self-explanatory. - -*Must specify at least 2 types in fix atom/swap command* - Self-explanatory. - -*Must use 'kim_style init' command before simulation box is defined* - Self-explanatory. - -*Must use 'kim_style define' command after simulation box is defined* - Self-explanatory. - -*Must use 'kim_style init' command before 'kim_style define'* - Self-explanatory. - *Must use 'kspace_modify pressure/scalar no' for rRESPA with kspace_style MSM* The kspace scalar pressure option cannot (yet) be used with rRESPA. @@ -5979,22 +3487,10 @@ Doc page with :doc:`WARNING messages ` *Must use Kokkos half/thread or full neighbor list with threads or GPUs* Using Kokkos half-neighbor lists with threading is not allowed. -*Must use a block or cylinder region with fix pour* - Self-explanatory. - -*Must use a block region with fix pour for 2d simulations* - Self-explanatory. - *Must use a bond style with TIP4P potential* TIP4P potentials assume bond lengths in water are constrained by a fix shake command. -*Must use a molecular atom style with fix poems molecule* - Self-explanatory. - -*Must use a z-axis cylinder region with fix pour* - Self-explanatory. - *Must use an angle style with TIP4P potential* TIP4P potentials assume angles in water are constrained by a fix shake command. @@ -6002,12 +3498,6 @@ Doc page with :doc:`WARNING messages ` *Must use atom map style array with Kokkos* See the atom_modify map command. -*Must use atom style with molecule IDs with fix bond/swap* - Self-explanatory. - -*Must use pair_style comb or comb3 with fix qeq/comb* - Self-explanatory. - *Must use variable energy with fix addforce* Must define an energy variable when applying a dynamic force during minimization. @@ -6016,21 +3506,12 @@ Doc page with :doc:`WARNING messages ` You must define an energy when performing a minimization with a variable E-field. -*NEB command before simulation box is defined* - Self-explanatory. - *NEB requires damped dynamics minimizer* Use a different minimization style. -*NEB requires use of fix neb* - Self-explanatory. - *NL ramp in wall/piston only implemented in zlo for now* The ramp keyword can only be used for piston applied to face zlo. -*Need nswaptypes mu values in fix atom/swap command* - Self-explanatory. - *Needed bonus data not in data file* Some atom styles require bonus data. See the read_data page for details. @@ -6039,12 +3520,6 @@ Doc page with :doc:`WARNING messages ` The header of the data file indicated bonds, angles, etc would be included, but they are not present. -*Neigh_modify exclude molecule requires atom attribute molecule* - Self-explanatory. - -*Neigh_modify include group != atom_modify first group* - Self-explanatory. - *Neighbor delay must be 0 or multiple of every setting* The delay and every parameters set via the neigh_modify command are inconsistent. If the delay setting is non-zero, then it must be a @@ -6061,12 +3536,6 @@ Doc page with :doc:`WARNING messages ` *Neighbor multi not yet enabled for ghost neighbors* This is a current restriction within LAMMPS. -*Neighbor multi not yet enabled for granular* - Self-explanatory. - -*Neighbor multi not yet enabled for rRESPA* - Self-explanatory. - *Neighbor page size must be >= 10x the one atom setting* This is required to prevent wasting too much memory. @@ -6094,19 +3563,10 @@ Doc page with :doc:`WARNING messages ` *Next command must list all universe and uloop variables* This is to ensure they stay in sync. -*No Kspace style defined for compute group/group* - Self-explanatory. - *No OpenMP support compiled in* An OpenMP flag is set, but LAMMPS was not built with OpenMP support. -*No angle style is defined for compute angle/local* - Self-explanatory. - -*No angles allowed with this atom style* - Self-explanatory. - *No atoms in data file* The header of the data file indicated that atoms would be included, but they are not present. @@ -6114,52 +3574,16 @@ Doc page with :doc:`WARNING messages ` *No basis atoms in lattice* Basis atoms must be defined for lattice style user. -*No bodies allowed with this atom style* - Self-explanatory. Check data file. - -*No bond style is defined for compute bond/local* - Self-explanatory. - -*No bonds allowed with this atom style* - Self-explanatory. - -*No box information in dump. You have to use 'box no'* - Self-explanatory. - *No count or invalid atom count in molecule file* The number of atoms must be specified. -*No dihedral style is defined for compute dihedral/local* - Self-explanatory. - -*No dihedrals allowed with this atom style* - Self-explanatory. - *No dump custom arguments specified* The dump custom command requires that atom quantities be specified to output to dump file. -*No dump local arguments specified* - Self-explanatory. - -*No ellipsoids allowed with this atom style* - Self-explanatory. Check data file. - *No fix gravity defined for fix pour* Gravity is required to use fix pour. -*No improper style is defined for compute improper/local* - Self-explanatory. - -*No impropers allowed with this atom style* - Self-explanatory. - -*No input values for fix ave/spatial* - Self-explanatory. - -*No lines allowed with this atom style* - Self-explanatory. Check data file. - *No matching element in ADP potential file* The ADP potential file does not contain elements that match the requested elements. @@ -6172,69 +3596,29 @@ Doc page with :doc:`WARNING messages ` The data file cannot specify the number of bonds, angles, etc, because this info if inferred from the molecule templates. -*No overlap of box and region for create_atoms* - Self-explanatory. - *No pair coul/streitz for fix qeq/slater* These commands must be used together. -*No pair hbond/dreiding coefficients set* - Self-explanatory. - *No pair style defined for compute group/group* Cannot calculate group interactions without a pair style defined. -*No pair style is defined for compute pair/local* - Self-explanatory. - -*No pair style is defined for compute property/local* - Self-explanatory. - *No rigid bodies defined* The fix specification did not end up defining any rigid bodies. -*No triangles allowed with this atom style* - Self-explanatory. Check data file. - -*No values in fix ave/chunk command* - Self-explanatory. - -*No values in fix ave/time command* - Self-explanatory. - -*Non digit character between brackets in variable* - Self-explanatory. - *Non integer # of swaps in temper command* Swap frequency in temper command must evenly divide the total # of timesteps. -*Non-numeric box dimensions - simulation unstable* - The box size has apparently blown up. - -*Non-zero atom IDs with atom_modify id = no* - Self-explanatory. - -*Non-zero read_data shift z value for 2d simulation* - Self-explanatory. - -*Nprocs not a multiple of N for -reorder* - Self-explanatory. - *Number of core atoms != number of shell atoms* There must be a one-to-one pairing of core and shell atoms. -*Numeric index is out of bounds* - A command with an argument that specifies an integer or range of - integers is using a value that is less than 1 or greater than the - maximum allowed limit. - *One or more Atom IDs is negative* Atom IDs must be positive integers. *One or more atom IDs is too big* - The limit on atom IDs is set by the SMALLBIG, BIGBIG, SMALLSMALL - setting in your LAMMPS build. See the :doc:`Build settings ` page for more info. + The limit on atom IDs is set by the SMALLBIG, BIGBIG + setting in your LAMMPS build. See the + :doc:`Build settings ` page for more info. *One or more atom IDs is zero* Either all atoms IDs must be zero or none of them. @@ -6243,70 +3627,10 @@ Doc page with :doc:`WARNING messages ` Two or more rigid bodies defined by the fix rigid command cannot contain the same atom. -*One or more rigid bodies are a single particle* - Self-explanatory. - *One or zero atoms in rigid body* Any rigid body defined by the fix rigid command must contain 2 or more atoms. -*Only 2 types allowed when not using semi-grand in fix atom/swap command* - Self-explanatory. - -*Only one cut-off allowed when requesting all long* - Self-explanatory. - -*Only one cutoff allowed when requesting all long* - Self-explanatory. - -*Only zhi currently implemented for fix append/atoms* - Self-explanatory. - -*Out of range atoms - cannot compute MSM* - One or more atoms are attempting to map their charge to a MSM grid point - that is not owned by a processor. This is likely for one of two - reasons, both of them bad. First, it may mean that an atom near the - boundary of a processor's subdomain has moved more than 1/2 the - :doc:`neighbor skin distance ` without neighbor lists being - rebuilt and atoms being migrated to new processors. This also means - you may be missing pairwise interactions that need to be computed. - The solution is to change the re-neighboring criteria via the - :doc:`neigh_modify ` command. The safest settings are - "delay 0 every 1 check yes". Second, it may mean that an atom has - moved far outside a processor's subdomain or even the entire - simulation box. This indicates bad physics, e.g. due to highly - overlapping atoms, too large a timestep, etc. - -*Out of range atoms - cannot compute PPPM* - One or more atoms are attempting to map their charge to a PPPM grid - point that is not owned by a processor. This is likely for one of two - reasons, both of them bad. First, it may mean that an atom near the - boundary of a processor's subdomain has moved more than 1/2 the - :doc:`neighbor skin distance ` without neighbor lists being - rebuilt and atoms being migrated to new processors. This also means - you may be missing pairwise interactions that need to be computed. - The solution is to change the re-neighboring criteria via the - :doc:`neigh_modify ` command. The safest settings are - "delay 0 every 1 check yes". Second, it may mean that an atom has - moved far outside a processor's subdomain or even the entire - simulation box. This indicates bad physics, e.g. due to highly - overlapping atoms, too large a timestep, etc. - -*Out of range atoms - cannot compute PPPMDisp* - One or more atoms are attempting to map their charge to a PPPM grid - point that is not owned by a processor. This is likely for one of two - reasons, both of them bad. First, it may mean that an atom near the - boundary of a processor's subdomain has moved more than 1/2 the - :doc:`neighbor skin distance ` without neighbor lists being - rebuilt and atoms being migrated to new processors. This also means - you may be missing pairwise interactions that need to be computed. - The solution is to change the re-neighboring criteria via the - :doc:`neigh_modify ` command. The safest settings are - "delay 0 every 1 check yes". Second, it may mean that an atom has - moved far outside a processor's subdomain or even the entire - simulation box. This indicates bad physics, e.g. due to highly - overlapping atoms, too large a timestep, etc. - *Overflow of allocated fix vector storage* This should not normally happen if the fix correctly calculated how long the vector will grow to. Contact the developers. @@ -6362,12 +3686,6 @@ Doc page with :doc:`WARNING messages ` The prd command cannot be used before a read_data, read_restart, or create_box command. -*PRD nsteps must be multiple of t_event* - Self-explanatory. - -*PRD t_corr must be multiple of t_event* - Self-explanatory. - *Package command after simulation box is defined* The package command cannot be used after a read_data, read_restart, or create_box command. @@ -6388,30 +3706,18 @@ Doc page with :doc:`WARNING messages ` The OPENMP package must be installed via "make yes-openmp" before LAMMPS is built. -*Pair body requires atom style body* - Self-explanatory. - *Pair body requires body style nparticle* This pair style is specific to the nparticle body style. -*Pair brownian requires atom style sphere* - Self-explanatory. - *Pair brownian requires extended particles* One of the particles has radius 0.0. *Pair brownian requires monodisperse particles* All particles must be the same finite size. -*Pair brownian/poly requires atom style sphere* - Self-explanatory. - *Pair brownian/poly requires extended particles* One of the particles has radius 0.0. -*Pair brownian/poly requires newton pair off* - Self-explanatory. - *Pair coeff for hybrid has invalid style* Style in pair coeff must have been listed in pair_style command. @@ -6447,18 +3753,6 @@ Doc page with :doc:`WARNING messages ` Each atom type involved in pair_style gayberne must have these 3 coefficients set at least once. -*Pair gayberne requires atom style ellipsoid* - Self-explanatory. - -*Pair gayberne requires atoms with same type have same shape* - Self-explanatory. - -*Pair gayberne/gpu requires atom style ellipsoid* - Self-explanatory. - -*Pair gayberne/gpu requires atoms with same type have same shape* - Self-explanatory. - *Pair granular requires atom attributes radius, rmass* The atom style defined does not have these attributes. @@ -6469,9 +3763,6 @@ Doc page with :doc:`WARNING messages ` This is a current restriction of the implementation of pair granular styles with history. -*Pair hybrid single calls do not support per sub-style special bond values* - Self-explanatory. - *Pair hybrid sub-style does not support single call* You are attempting to invoke a single() call on a pair style that does not support it. @@ -6487,36 +3778,21 @@ Doc page with :doc:`WARNING messages ` *Pair inner cutoff >= Pair outer cutoff* The specified cutoffs for the pair style are inconsistent. -*Pair line/lj requires atom style line* - Self-explanatory. - *Pair lj/long/dipole/long requires atom attributes mu, torque* The atom style defined does not have these attributes. -*Pair lubricate requires atom style sphere* - Self-explanatory. - *Pair lubricate requires ghost atoms store velocity* Use the comm_modify vel yes command to enable this. *Pair lubricate requires monodisperse particles* All particles must be the same finite size. -*Pair lubricate/poly requires atom style sphere* - Self-explanatory. - *Pair lubricate/poly requires extended particles* One of the particles has radius 0.0. *Pair lubricate/poly requires ghost atoms store velocity* Use the comm_modify vel yes command to enable this. -*Pair lubricate/poly requires newton pair off* - Self-explanatory. - -*Pair lubricateU requires atom style sphere* - Self-explanatory. - *Pair lubricateU requires ghost atoms store velocity* Use the comm_modify vel yes command to enable this. @@ -6526,9 +3802,6 @@ Doc page with :doc:`WARNING messages ` *Pair lubricateU/poly requires ghost atoms store velocity* Use the comm_modify vel yes command to enable this. -*Pair lubricateU/poly requires newton pair off* - Self-explanatory. - *Pair peri lattice is not identical in x, y, and z* The lattice defined by the lattice command must be cubic. @@ -6539,24 +3812,6 @@ Doc page with :doc:`WARNING messages ` Even for atomic systems, an atom map is required to find Peridynamic bonds. Use the atom_modify command to define one. -*Pair resquared epsilon a,b,c coeffs are not all set* - Self-explanatory. - -*Pair resquared epsilon and sigma coeffs are not all set* - Self-explanatory. - -*Pair resquared requires atom style ellipsoid* - Self-explanatory. - -*Pair resquared requires atoms with same type have same shape* - Self-explanatory. - -*Pair resquared/gpu requires atom style ellipsoid* - Self-explanatory. - -*Pair resquared/gpu requires atoms with same type have same shape* - Self-explanatory. - *Pair style AIREBO requires atom IDs* This is a requirement to use the AIREBO potential. @@ -6574,9 +3829,6 @@ Doc page with :doc:`WARNING messages ` *Pair style COMB requires atom IDs* This is a requirement to use the AIREBO potential. -*Pair style COMB requires atom attribute q* - Self-explanatory. - *Pair style COMB requires newton pair on* See the newton command. This is a restriction to use the COMB potential. @@ -6584,9 +3836,6 @@ Doc page with :doc:`WARNING messages ` *Pair style COMB3 requires atom IDs* This is a requirement to use the COMB3 potential. -*Pair style COMB3 requires atom attribute q* - Self-explanatory. - *Pair style COMB3 requires newton pair on* See the newton command. This is a restriction to use the COMB3 potential. @@ -6670,9 +3919,6 @@ Doc page with :doc:`WARNING messages ` *Pair style coul/long/gpu requires atom attribute q* The atom style defined does not have these attributes. -*Pair style coul/streitz requires atom attribute q* - Self-explanatory. - *Pair style does not have extra field requested by compute pair/local* The pair style does not support the pN value requested by the compute pair/local command. @@ -6709,24 +3955,9 @@ Doc page with :doc:`WARNING messages ` Atoms in the simulation do not have IDs, so history effects cannot be tracked by the granular pair potential. -*Pair style hbond/dreiding requires an atom map, see atom_modify* - Self-explanatory. - -*Pair style hbond/dreiding requires atom IDs* - Self-explanatory. - -*Pair style hbond/dreiding requires molecular system* - Self-explanatory. - *Pair style hbond/dreiding requires newton pair on* See the newton command for details. -*Pair style hybrid cannot have hybrid as an argument* - Self-explanatory. - -*Pair style hybrid cannot have none as an argument* - Self-explanatory. - *Pair style is incompatible with KSpace style* If a pair style with a long-range Coulombic component is selected, then a kspace style must also be used. @@ -6826,9 +4057,6 @@ Doc page with :doc:`WARNING messages ` *Pair style nm/cut/coul/long requires atom attribute q* The atom style defined does not have this attribute. -*Pair style peri requires atom style peri* - Self-explanatory. - *Pair style polymorphic requires atom IDs* This is a requirement to use the polymorphic potential. @@ -6848,9 +4076,6 @@ Doc page with :doc:`WARNING messages ` *Pair style requires a KSpace style* No kspace style is defined. -*Pair style requires use of kspace_style ewald/disp* - Self-explanatory. - *Pair style sw/gpu requires atom IDs* This is a requirement to use this potential. @@ -6903,38 +4128,17 @@ Doc page with :doc:`WARNING messages ` *Pair tersoff/zbl/kk requires metal or real units* This is a current restriction of this pair potential. -*Pair tri/lj requires atom style tri* - Self-explanatory. - -*Pair yukawa/colloid requires atom style sphere* - Self-explanatory. - -*Pair yukawa/colloid requires atoms with same type have same radius* - Self-explanatory. - -*Pair yukawa/colloid/gpu requires atom style sphere* - Self-explanatory. - *PairKIM only works with 3D problems* This is a current limitation. -*Pair_coeff command before pair_style is defined* - Self-explanatory. - *Pair_coeff command before simulation box is defined* The pair_coeff command cannot be used before a read_data, read_restart, or create_box command. -*Pair_modify command before pair_style is defined* - Self-explanatory. - *Pair_modify special setting for pair hybrid incompatible with global special_bonds setting* Cannot override a setting of 0.0 or 1.0 or change a setting between 0.0 and 1.0. -*Pair_write command before pair_style is defined* - Self-explanatory. - *Particle on or inside fix wall surface* Particles must be "exterior" to the wall in order for energy/force to be calculated. @@ -6946,26 +4150,13 @@ Doc page with :doc:`WARNING messages ` *Per-atom compute in equal-style variable formula* Equal-style variables cannot use per-atom quantities. -*Per-atom energy was not tallied on needed timestep* - You are using a thermo keyword that requires potentials to - have tallied energy, but they did not on this timestep. See the - variable page for ideas on how to make this work. - *Per-atom fix in equal-style variable formula* Equal-style variables cannot use per-atom quantities. -*Per-atom virial was not tallied on needed timestep* - You are using a thermo keyword that requires potentials to have - tallied the virial, but they did not on this timestep. See the - variable page for ideas on how to make this work. - *Per-processor system is too big* The number of owned atoms plus ghost atoms on a single processor must fit in 32-bit integer. -*Potential energy ID for fix neb does not exist* - Self-explanatory. - *Potential energy ID for fix nvt/nph/npt does not exist* A compute for potential energy must be defined. @@ -6975,79 +4166,22 @@ Doc page with :doc:`WARNING messages ` *Potential file is missing an entry* The potential file does not have a needed entry. -*Power by 0 in variable formula* - Self-explanatory. - *Pressure ID for fix box/relax does not exist* The compute ID needed to compute pressure for the fix does not exist. -*Pressure ID for fix modify does not exist* - Self-explanatory. - -*Pressure ID for fix npt/nph does not exist* - Self-explanatory. - *Pressure ID for fix press/berendsen does not exist* The compute ID needed to compute pressure for the fix does not exist. -*Pressure ID for fix rigid npt/nph does not exist* - Self-explanatory. - *Pressure ID for thermo does not exist* The compute ID needed to compute pressure for thermodynamics does not exist. -*Pressure control can not be used with fix nvt* - Self-explanatory. - -*Pressure control can not be used with fix nvt/asphere* - Self-explanatory. - -*Pressure control can not be used with fix nvt/body* - Self-explanatory. - -*Pressure control can not be used with fix nvt/sllod* - Self-explanatory. - -*Pressure control can not be used with fix nvt/sphere* - Self-explanatory. - -*Pressure control must be used with fix nph* - Self-explanatory. - -*Pressure control must be used with fix nph/asphere* - Self-explanatory. - -*Pressure control must be used with fix nph/body* - Self-explanatory. - -*Pressure control must be used with fix nph/small* - Self-explanatory. - -*Pressure control must be used with fix nph/sphere* - Self-explanatory. - *Pressure control must be used with fix nphug* A pressure control keyword (iso, aniso, tri, x, y, or z) must be provided. -*Pressure control must be used with fix npt* - Self-explanatory. - -*Pressure control must be used with fix npt/asphere* - Self-explanatory. - -*Pressure control must be used with fix npt/body* - Self-explanatory. - -*Pressure control must be used with fix npt/sphere* - Self-explanatory. - -*Processor count in z must be 1 for 2d simulation* - Self-explanatory. - *Processor partitions do not match number of allocated processors* The total number of processors in all partitions must match the number of processors LAMMPS is running on. @@ -7068,12 +4202,6 @@ Doc page with :doc:`WARNING messages ` *Processors part option and grid style are incompatible* Cannot use gstyle numa or custom with the part option. -*Processors twogrid requires proc count be a multiple of core count* - Self-explanatory. - -*Pstart and Pstop must have the same value* - Self-explanatory. - *Python function evaluation failed* The Python function did not run successfully and/or did not return a value (if it is supposed to return a value). This is probably due to @@ -7100,9 +4228,6 @@ Doc page with :doc:`WARNING messages ` *R0 < 0 for fix spring command* Equilibrium spring length is invalid. -*RATTLE coordinate constraints are not satisfied up to desired tolerance* - Self-explanatory. - *RATTLE determinant = 0.0* The determinant of the matrix being solved for a single cluster specified by the fix rattle command is numerically invalid. @@ -7110,19 +4235,10 @@ Doc page with :doc:`WARNING messages ` *RATTLE failed* Certain constraints were not satisfied. -*RATTLE velocity constraints are not satisfied up to desired tolerance* - Self-explanatory. - *Read data add offset is too big* It cannot be larger than the size of atom IDs, e.g. the maximum 32-bit integer. -*Read dump of atom property that is not allocated* - Self-explanatory. - -*Read rerun dump file timestep > specified stop* - Self-explanatory. - *Read restart MPI-IO input not allowed with % in filename* This is because a % signifies one file per processor and MPI-IO creates one large file for all processors. @@ -7138,16 +4254,10 @@ Doc page with :doc:`WARNING messages ` The read_dump command cannot be used before a read_data, read_restart, or create_box command. -*Read_dump field not found in dump file* - Self-explanatory. - *Read_dump triclinic status does not match simulation* Both the dump snapshot and the current LAMMPS simulation must be using either an orthogonal or triclinic box. -*Read_dump xyz fields do not have consistent scaling/wrapping* - Self-explanatory. - *Reax_defs.h setting for NATDEF is too small* Edit the setting in the ReaxFF library and re-compile the library and re-build LAMMPS. @@ -7159,66 +4269,6 @@ Doc page with :doc:`WARNING messages ` *Receiving partition in processors part command is already a receiver* Cannot specify a partition to be a receiver twice. -*Region ID for compute chunk/atom does not exist* - Self-explanatory. - -*Region ID for compute reduce/region does not exist* - Self-explanatory. - -*Region ID for compute temp/region does not exist* - Self-explanatory. - -*Region ID for dump custom does not exist* - Self-explanatory. - -*Region ID for fix addforce does not exist* - Self-explanatory. - -*Region ID for fix atom/swap does not exist* - Self-explanatory. - -*Region ID for fix ave/spatial does not exist* - Self-explanatory. - -*Region ID for fix aveforce does not exist* - Self-explanatory. - -*Region ID for fix deposit does not exist* - Self-explanatory. - -*Region ID for fix efield does not exist* - Self-explanatory. - -*Region ID for fix evaporate does not exist* - Self-explanatory. - -*Region ID for fix gcmc does not exist* - Self-explanatory. - -*Region ID for fix heat does not exist* - Self-explanatory. - -*Region ID for fix setforce does not exist* - Self-explanatory. - -*Region ID for fix wall/region does not exist* - Self-explanatory. - -*Region ID for group dynamic does not exist* - Self-explanatory. - -*Region ID in variable formula does not exist* - Self-explanatory. - -*Region cannot have 0 length rotation vector* - Self-explanatory. - -*Region for fix oneway does not exist* - Self-explanatory. - -*Region intersect region ID does not exist* - Self-explanatory. - *Region union or intersect cannot be dynamic* The sub-regions can be dynamic, but not the combined region. @@ -7255,18 +4305,12 @@ Doc page with :doc:`WARNING messages ` The rerun command cannot be used before a read_data, read_restart, or create_box command. -*Rerun dump file does not contain requested snapshot* - Self-explanatory. - *Resetting timestep size is not allowed with fix move* This is because fix move is moving atoms based on elapsed time. *Respa inner cutoffs are invalid* The first cutoff must be <= the second cutoff. -*Respa levels must be >= 1* - Self-explanatory. - *Respa middle cutoffs are invalid* The first cutoff must be <= the second cutoff. @@ -7355,12 +4399,6 @@ Doc page with :doc:`WARNING messages ` The run command cannot be used before a read_data, read_restart, or create_box command. -*Run command start value is after start of run* - Self-explanatory. - -*Run command stop value is before end of run* - Self-explanatory. - *Run_style command before simulation box is defined* The run_style command cannot be used before a read_data, read_restart, or create_box command. @@ -7381,9 +4419,6 @@ Doc page with :doc:`WARNING messages ` See the inside keyword if you want this message to be an error vs warning. -*Same dimension twice in fix ave/spatial* - Self-explanatory. - *Sending partition in processors part command is already a sender* Cannot specify a partition to be a sender twice. @@ -7391,12 +4426,6 @@ Doc page with :doc:`WARNING messages ` The set command cannot be used before a read_data, read_restart, or create_box command. -*Set command floating point vector does not exist* - Self-explanatory. - -*Set command integer vector does not exist* - Self-explanatory. - *Set command with no atoms existing* No atoms are yet defined so the set command cannot be used. @@ -7470,12 +4499,6 @@ Doc page with :doc:`WARNING messages ` The 3d grid of processors defined by the processors command does not match the number of processors LAMMPS is being run on. -*Specified target stress must be uniaxial or hydrostatic* - Self-explanatory. - -*Sqrt of negative value in variable formula* - Self-explanatory. - *Subsequent read data induced too many angles per atom* See the extra/angle/per/atom keyword for the create_box or the read_data command to set this limit larger @@ -7492,10 +4515,6 @@ Doc page with :doc:`WARNING messages ` See the extra/improper/per/atom keyword for the create_box or the read_data command to set this limit larger -*Substitution for illegal variable* - Input script line contained a variable that could not be substituted - for. - *Support for writing images in JPEG format not included* LAMMPS was not built with the -DLAMMPS_JPEG switch in the Makefile. @@ -7512,9 +4531,6 @@ Doc page with :doc:`WARNING messages ` The total charge on all atoms on the system is not 0.0. For some KSpace solvers this is an error. -*TAD nsteps must be multiple of t_event* - Self-explanatory. - *TIP4P hydrogen has incorrect atom type* The TIP4P pairwise computation found an H atom whose type does not agree with the specified H type. @@ -7527,9 +4543,6 @@ Doc page with :doc:`WARNING messages ` The target file for the fix tmd command did not list all atoms in the fix group. -*Tad command before simulation box is defined* - Self-explanatory. - *Tagint setting in lmptype.h is invalid* Tagint must be as large or larger than smallint. @@ -7537,107 +4550,17 @@ Doc page with :doc:`WARNING messages ` Format of tagint stored in restart file is not consistent with LAMMPS version you are running. See the settings in src/lmptype.h -*Target pressure for fix rigid/nph cannot be < 0.0* - Self-explanatory. - -*Target pressure for fix rigid/npt/small cannot be < 0.0* - Self-explanatory. - -*Target temperature for fix nvt/npt/nph cannot be 0.0* - Self-explanatory. - -*Target temperature for fix rigid/npt cannot be 0.0* - Self-explanatory. - -*Target temperature for fix rigid/npt/small cannot be 0.0* - Self-explanatory. - -*Target temperature for fix rigid/nvt cannot be 0.0* - Self-explanatory. - -*Target temperature for fix rigid/nvt/small cannot be 0.0* - Self-explanatory. - *Temper command before simulation box is defined* The temper command cannot be used before a read_data, read_restart, or create_box command. -*Temperature ID for fix bond/swap does not exist* - Self-explanatory. - -*Temperature ID for fix box/relax does not exist* - Self-explanatory. - -*Temperature ID for fix nvt/npt does not exist* - Self-explanatory. - -*Temperature ID for fix press/berendsen does not exist* - Self-explanatory. - -*Temperature ID for fix rigid nvt/npt/nph does not exist* - Self-explanatory. - -*Temperature ID for fix temp/berendsen does not exist* - Self-explanatory. - -*Temperature ID for fix temp/csld does not exist* - Self-explanatory. - -*Temperature ID for fix temp/csvr does not exist* - Self-explanatory. - -*Temperature ID for fix temp/rescale does not exist* - Self-explanatory. - *Temperature compute degrees of freedom < 0* This should not happen if you are calculating the temperature on a valid set of atoms. -*Temperature control can not be used with fix nph* - Self-explanatory. - -*Temperature control can not be used with fix nph/asphere* - Self-explanatory. - -*Temperature control can not be used with fix nph/body* - Self-explanatory. - -*Temperature control can not be used with fix nph/sphere* - Self-explanatory. - *Temperature control must be used with fix nphug* The temp keyword must be provided. -*Temperature control must be used with fix npt* - Self-explanatory. - -*Temperature control must be used with fix npt/asphere* - Self-explanatory. - -*Temperature control must be used with fix npt/body* - Self-explanatory. - -*Temperature control must be used with fix npt/sphere* - Self-explanatory. - -*Temperature control must be used with fix nvt* - Self-explanatory. - -*Temperature control must be used with fix nvt/asphere* - Self-explanatory. - -*Temperature control must be used with fix nvt/body* - Self-explanatory. - -*Temperature control must be used with fix nvt/sllod* - Self-explanatory. - -*Temperature control must be used with fix nvt/sphere* - Self-explanatory. - -*Temperature control must not be used with fix nph/small* - Self-explanatory. - *Temperature for fix nvt/sllod does not have a bias* The specified compute must compute temperature with a bias. @@ -7655,31 +4578,10 @@ Doc page with :doc:`WARNING messages ` *Test_descriptor_string already allocated* This is an internal error. Contact the developers. -*The package gpu command is required for gpu styles* - Self-explanatory. - *Thermo and fix not computed at compatible times* Fixes generate values on specific timesteps. The thermo output does not match these timesteps. -*Thermo compute array is accessed out-of-range* - Self-explanatory. - -*Thermo compute does not compute array* - Self-explanatory. - -*Thermo compute does not compute scalar* - Self-explanatory. - -*Thermo compute does not compute vector* - Self-explanatory. - -*Thermo compute vector is accessed out-of-range* - Self-explanatory. - -*Thermo custom variable cannot be indexed* - Self-explanatory. - *Thermo custom variable is not equal-style variable* Only equal-style variables can be output with thermodynamics, not atom-style variables. @@ -7687,21 +4589,6 @@ Doc page with :doc:`WARNING messages ` *Thermo every variable returned a bad timestep* The variable must return a timestep greater than the current timestep. -*Thermo fix array is accessed out-of-range* - Self-explanatory. - -*Thermo fix does not compute array* - Self-explanatory. - -*Thermo fix does not compute scalar* - Self-explanatory. - -*Thermo fix does not compute vector* - Self-explanatory. - -*Thermo fix vector is accessed out-of-range* - Self-explanatory. - *Thermo keyword in variable requires thermo to use/init pe* You are using a thermo keyword in a variable that requires potential energy to be calculated, but your thermo output @@ -7728,9 +4615,6 @@ Doc page with :doc:`WARNING messages ` *Thermo_modify every variable returned a bad timestep* The returned timestep is less than or equal to the current timestep. -*Thermo_modify int format does not contain d character* - Self-explanatory. - *Thermo_modify pressure ID does not compute pressure* The specified compute ID does not compute pressure. @@ -7765,15 +4649,6 @@ Doc page with :doc:`WARNING messages ` Table size specified via pair_modify command does not work with your machine's floating point representation. -*Too few lines in %s section of data file* - Self-explanatory. - -*Too few values in body lines in data file* - Self-explanatory. - -*Too few values in body section of molecule file* - Self-explanatory. - *Too many -pk arguments in command-line* The string formed by concatenating the arguments is too long. Use a package command in the input script instead. @@ -7843,10 +4718,6 @@ Doc page with :doc:`WARNING messages ` *Too many molecules for fix rigid* The limit is 2\^31 = ~2 billion molecules. -*Too many neighbor bins* - This is likely due to an immense simulation box that has blown up - to a large size. - *Too many timesteps* The cumulative timesteps must fit in a 64-bit integer. @@ -7861,12 +4732,6 @@ Doc page with :doc:`WARNING messages ` Table size specified via pair_modify command is too large. Note that a value of N generates a 2\^N size table. -*Too many values in body lines in data file* - Self-explanatory. - -*Too many values in body section of molecule file* - Self-explanatory. - *Too much buffered per-proc info for dump* The size of the buffered string must fit in a 32-bit integer for a dump. @@ -7883,9 +4748,6 @@ Doc page with :doc:`WARNING messages ` Fix poems cannot (yet) work with coupled bodies whose joints connect the bodies in a tree structure. -*Tried to convert a double to int, but input_double > INT_MAX* - Self-explanatory. - *Trying to build an occasional neighbor list before initialization completed* This is not allowed. Source code caller needs to be modified. @@ -7894,9 +4756,6 @@ Doc page with :doc:`WARNING messages ` chunk assignments persist for some number of timesteps, but are doing it in different ways. -*Two groups cannot be the same in fix spring couple* - Self-explanatory. - *The %s type label %s is already in use for type %s* For a given type-kind (atom types, bond types, etc.), a given type label can be assigned to only one numeric type. @@ -7911,9 +4770,6 @@ Doc page with :doc:`WARNING messages ` No matching end double quote was found following a leading double quote. -*Unexpected end of -reorder file* - Self-explanatory. - *Unexpected empty line in Angle Coeffs section* Read a blank line where there should be coefficient data. @@ -7929,9 +4785,6 @@ Doc page with :doc:`WARNING messages ` *Unexpected empty line in Pair Coeffs section* Read a blank line where there should be coefficient data. -*Unexpected end of custom file* - Self-explanatory. - *Unexpected end of data file* LAMMPS hit the end of the data file while attempting to read a section. Something is wrong with the format of the data file. @@ -7945,9 +4798,6 @@ Doc page with :doc:`WARNING messages ` *Unexpected end of fix rigid/small file* A read operation from the file failed. -*Unexpected end of molecule file* - Self-explanatory. - *Unexpected end of neb file* A read operation from the file failed. @@ -7959,93 +4809,15 @@ Doc page with :doc:`WARNING messages ` A universe or uloop style variable must specify a number of values >= to the number of processor partitions. -*Unrecognized angle style* - The choice of angle style is unknown. - -*Unrecognized atom style* - The choice of atom style is unknown. - -*Unrecognized body style* - The choice of body style is unknown. - -*Unrecognized bond style* - The choice of bond style is unknown. - -*Unknown category for info is_active()* - Self-explanatory. - -*Unknown category for info is_available()* - Self-explanatory. - -*Unknown category for info is_defined()* - Self-explanatory. - -*Unrecognized command: %s* - The command is not known to LAMMPS. Check the input script. - -*Unrecognized compute style* - The choice of compute style is unknown. - -*Unrecognized dihedral style* - The choice of dihedral style is unknown. - -*Unrecognized dump reader style* - The choice of dump reader style via the format keyword is unknown. - -*Unrecognized dump style* - The choice of dump style is unknown. - -*Unknown error in GPU library* - Self-explanatory. - -*Unrecognized fix style* - The choice of fix style is unknown. - -*Unknown identifier in data file: %s* - A section of the data file cannot be read by LAMMPS. - -*Unrecognized improper style* - The choice of improper style is unknown. - *Unknown keyword in thermo_style custom command* One or more specified keywords are not recognized. -*Unrecognized kspace style* - The choice of kspace style is unknown. - -*Unknown name for info newton category* - Self-explanatory. - -*Unknown name for info package category* - Self-explanatory. - -*Unknown name for info pair category* - Self-explanatory. - -*Unrecognized pair style* - The choice of pair style is unknown. - *Unknown pair_modify hybrid sub-style* The choice of sub-style is unknown. -*Unrecognized region style* - The choice of region style is unknown. - -*Unknown section in molecule file* - Self-explanatory. - -*Unknown table style in angle style table* - Self-explanatory. - -*Unknown table style in bond style table* - Self-explanatory. - *Unknown table style in pair_style command* Style of table is invalid for use with pair_style table command. -*Unknown unit_style* - Self-explanatory. Check the input script or data file. - *Unrecognized lattice type in MEAM library file* The lattice type in an entry of the MEAM library file is not valid. @@ -8054,9 +4826,6 @@ Doc page with :doc:`WARNING messages ` The lattice type in an entry of the MEAM parameter file is not valid. -*Unrecognized pair style in compute pair command* - Self-explanatory. - *Unsupported mixing rule in kspace_style ewald/disp* Only geometric mixing is supported. @@ -8066,9 +4835,6 @@ Doc page with :doc:`WARNING messages ` *Unsupported order in kspace_style pppm/disp, pair_style %s* Only pair styles with 1/r and 1/r\^6 dependence are currently supported. -*Unsupported parameter in MEAM library file* - Self-explanatory. - *Use cutoff keyword to set cutoff in single mode* Mode is single so cutoff/multi keyword cannot be used. @@ -8079,9 +4845,6 @@ Doc page with :doc:`WARNING messages ` Fix nvt/sllod requires that deforming atoms have a velocity profile provided by "remap v" as a fix deform option. -*Using fix nvt/sllod with no fix deform defined* - Self-explanatory. - *Using fix srd with inconsistent fix deform remap option* When shearing the box in an SRD simulation, the remap v option for fix deform needs to be used. @@ -8092,27 +4855,6 @@ Doc page with :doc:`WARNING messages ` *Using pair lubricate/poly with inconsistent fix deform remap option* If fix deform is used, the remap v option is required. -*Using suffix gpu without GPU package installed* - Self-explanatory. - -*Using suffix intel without INTEL package installed* - Self-explanatory. - -*Using suffix kk without KOKKOS package enabled* - Self-explanatory. - -*Using suffix omp without OPENMP package installed* - Self-explanatory. - -*Using update dipole flag requires atom attribute mu* - Self-explanatory. - -*Using update dipole flag requires atom style sphere* - Self-explanatory. - -*Variable ID in variable formula does not exist* - Self-explanatory. - *Variable atom ID is too large* Specified ID is larger than the maximum allowed atom ID. @@ -8126,9 +4868,6 @@ Doc page with :doc:`WARNING messages ` *Variable evaluation in region gave bad value* Variable returned a radius < 0.0. -*Variable for compute ti is invalid style* - Self-explanatory. - *Variable for create_atoms is invalid style* The variables must be equal-style variables. @@ -8153,9 +4892,6 @@ Doc page with :doc:`WARNING messages ` *Variable for fix adapt is invalid style* Only equal-style variables can be used. -*Variable for fix addforce is invalid style* - Self-explanatory. - *Variable for fix aveforce is invalid style* Only equal-style variables can be used. @@ -8219,9 +4955,6 @@ Doc page with :doc:`WARNING messages ` *Variable for region is invalid style* Only equal-style variables can be used. -*Variable for region is not equal style* - Self-explanatory. - *Variable for region sphere is invalid style* Only equal-style variables are allowed. @@ -8237,173 +4970,11 @@ Doc page with :doc:`WARNING messages ` *Variable for velocity set is invalid style* Only atom-style variables can be used. -*Variable for voronoi radius is not atom style* - Self-explanatory. - -*Variable formula compute array is accessed out-of-range* - Self-explanatory. - -*Variable formula compute vector is accessed out-of-range* - Self-explanatory. - -*Variable formula fix array is accessed out-of-range* - Self-explanatory. - -*Variable formula fix vector is accessed out-of-range* - Self-explanatory. - *Variable has circular dependency* A circular dependency is when variable "a" in used by variable "b" and variable "b" is also used by variable "a". Circular dependencies with longer chains of dependence are also not allowed. -*Variable name between brackets must be alphanumeric or underscore characters* - Self-explanatory. - -*Variable name for compute chunk/atom does not exist* - Self-explanatory. - -*Variable name for compute reduce does not exist* - Self-explanatory. - -*Variable name for compute ti does not exist* - Self-explanatory. - -*Variable name for create_atoms does not exist* - Self-explanatory. - -*Variable name for displace_atoms does not exist* - Self-explanatory. - -*Variable name for dump every does not exist* - Self-explanatory. - -*Variable name for dump image center does not exist* - Self-explanatory. - -*Variable name for dump image phi does not exist* - Self-explanatory. - -*Variable name for dump image theta does not exist* - Self-explanatory. - -*Variable name for dump image zoom does not exist* - Self-explanatory. - -*Variable name for fix adapt does not exist* - Self-explanatory. - -*Variable name for fix addforce does not exist* - Self-explanatory. - -*Variable name for fix ave/atom does not exist* - Self-explanatory. - -*Variable name for fix ave/chunk does not exist* - Self-explanatory. - -*Variable name for fix ave/correlate does not exist* - Self-explanatory. - -*Variable name for fix ave/histo does not exist* - Self-explanatory. - -*Variable name for fix ave/spatial does not exist* - Self-explanatory. - -*Variable name for fix ave/time does not exist* - Self-explanatory. - -*Variable name for fix aveforce does not exist* - Self-explanatory. - -*Variable name for fix deform does not exist* - Self-explanatory. - -*Variable name for fix efield does not exist* - Self-explanatory. - -*Variable name for fix gravity does not exist* - Self-explanatory. - -*Variable name for fix heat does not exist* - Self-explanatory. - -*Variable name for fix indent does not exist* - Self-explanatory. - -*Variable name for fix langevin does not exist* - Self-explanatory. - -*Variable name for fix move does not exist* - Self-explanatory. - -*Variable name for fix setforce does not exist* - Self-explanatory. - -*Variable name for fix store/state does not exist* - Self-explanatory. - -*Variable name for fix temp/berendsen does not exist* - Self-explanatory. - -*Variable name for fix temp/csld does not exist* - Self-explanatory. - -*Variable name for fix temp/csvr does not exist* - Self-explanatory. - -*Variable name for fix temp/rescale does not exist* - Self-explanatory. - -*Variable name for fix vector does not exist* - Self-explanatory. - -*Variable name for fix wall does not exist* - Self-explanatory. - -*Variable name for fix wall/reflect does not exist* - Self-explanatory. - -*Variable name for fix wall/srd does not exist* - Self-explanatory. - -*Variable name for group does not exist* - Self-explanatory. - -*Variable name for group dynamic does not exist* - Self-explanatory. - -*Variable name for region cylinder does not exist* - Self-explanatory. - -*Variable name for region does not exist* - Self-explanatory. - -*Variable name for region sphere does not exist* - Self-explanatory. - -*Variable name for restart does not exist* - Self-explanatory. - -*Variable name for set command does not exist* - Self-explanatory. - -*Variable name for thermo every does not exist* - Self-explanatory. - -*Variable name for velocity set does not exist* - Self-explanatory. - -*Variable name for voronoi radius does not exist* - Self-explanatory. - -*Variable name must be alphanumeric or underscore characters* - Self-explanatory. - -*Variable uses atom property that is not allocated* - Self-explanatory. - *Velocity command before simulation box is defined* The velocity command cannot be used before a read_data, read_restart, or create_box command. @@ -8411,12 +4982,6 @@ Doc page with :doc:`WARNING messages ` *Velocity command with no atoms existing* A velocity command has been used, but no atoms yet exist. -*Velocity ramp in z for a 2d problem* - Self-explanatory. - -*Velocity rigid used with non-rigid fix-ID* - Self-explanatory. - *Velocity temperature ID does calculate a velocity bias* The specified compute must compute a bias for temperature. @@ -8440,23 +5005,9 @@ Doc page with :doc:`WARNING messages ` This is so there is an equal number of Rspace processors for every Kspace processor. -*Virial was not tallied on needed timestep* - You are using a thermo keyword that requires potentials to - have tallied the virial, but they did not on this timestep. See the - variable page for ideas on how to make this work. - *Voro++ error: narea and neigh have a different size* This error is returned by the Voro++ library. -*Wall defined twice in fix wall command* - Self-explanatory. - -*Wall defined twice in fix wall/reflect command* - Self-explanatory. - -*Wall defined twice in fix wall/srd command* - Self-explanatory. - *Water H epsilon must be 0.0 for pair style lj/cut/tip4p/cut* This is because LAMMPS does not compute the Lennard-Jones interactions with these particles for efficiency reasons. @@ -8473,18 +5024,6 @@ Doc page with :doc:`WARNING messages ` A world-style variable must specify a number of values equal to the number of processor partitions. -*Write_data command before simulation box is defined* - Self-explanatory. - *Write_restart command before simulation box is defined* The write_restart command cannot be used before a read_data, read_restart, or create_box command. - -*Zero length rotation vector with displace_atoms* - Self-explanatory. - -*Zero length rotation vector with fix move* - Self-explanatory. - -*Zero-length lattice orient vector* - Self-explanatory. diff --git a/doc/src/Errors_warnings.rst b/doc/src/Errors_warnings.rst index 25aa87f162..3f18ddd2ca 100644 --- a/doc/src/Errors_warnings.rst +++ b/doc/src/Errors_warnings.rst @@ -1,11 +1,15 @@ Warning messages ================ -This is an alphabetic list of the WARNING messages LAMMPS prints out -and the reason why. If the explanation here is not sufficient, the -documentation for the offending command may help. Warning messages -also list the source file and line number where the warning was -generated. For example, a message like this: +This is an alphabetic list of some of the WARNING messages LAMMPS prints +out and the reason why. If the explanation here is not sufficient, the +documentation for the offending command may help. This is a historic +list and no longer updated. Instead the LAMMPS developers are trying +to provide more details right with the error message or link to a +paragraph with :doc:`detailed explanations `. + +Warning messages also list the source file and line number where the +warning was generated. For example, a message like this: .. parsed-literal:: @@ -14,7 +18,7 @@ generated. For example, a message like this: means that line #187 in the file src/domain.cpp generated the error. Looking in the source code may help you figure out what went wrong. -Doc page with :doc:`ERROR messages ` +Please also see the page with :doc:`Error messages ` ---------- @@ -28,16 +32,10 @@ Doc page with :doc:`ERROR messages ` cutoff is set too short or the angle has blown apart and an atom is too far away. -*Angle style in data file differs from currently defined angle style* - Self-explanatory. - *Angles are defined but no angle style is set* The topology contains angles, but there are no angle forces computed since there was no angle_style command. -*Atom style in data file differs from currently defined atom style* - Self-explanatory. - *Bond atom missing in box size check* The second atom needed to compute a particular bond is missing on this processor. Typically this is because the pairwise cutoff is set too @@ -53,9 +51,6 @@ Doc page with :doc:`ERROR messages ` processor. Typically this is because the pairwise cutoff is set too short or the bond has blown apart and an atom is too far away. -*Bond style in data file differs from currently defined bond style* - Self-explanatory. - *Bonds are defined but no bond style is set* The topology contains bonds, but there are no bond forces computed since there was no bond_style command. @@ -68,9 +63,6 @@ Doc page with :doc:`ERROR messages ` length, multiplying by the number of bonds in the interaction (e.g. 3 for a dihedral) and adding a small amount of stretch. -*Both groups in compute group/group have a net charge; the Kspace boundary correction to energy will be non-zero* - Self-explanatory. - *Calling write_dump before a full system init.* The write_dump command is used before the system has been fully initialized as part of a 'run' or 'minimize' command. Not all dump @@ -86,18 +78,6 @@ Doc page with :doc:`ERROR messages ` This means the temperature associated with the rigid bodies may be incorrect on this timestep. -*Cannot include log terms without 1/r terms; setting flagHI to 1* - Self-explanatory. - -*Cannot include log terms without 1/r terms; setting flagHI to 1.* - Self-explanatory. - -*Charges are set, but coulombic solver is not used* - Self-explanatory. - -*Charges did not converge at step %ld: %lg* - Self-explanatory. - *Communication cutoff is 0.0. No ghost atoms will be generated. Atoms may get lost* The communication cutoff defaults to the maximum of what is inferred from pair and bond styles (will be zero, if none are defined) and what is specified @@ -123,9 +103,6 @@ Doc page with :doc:`ERROR messages ` is not changed automatically and the warning may be ignored depending on the specific system being simulated. -*Communication cutoff is too small for SNAP micro load balancing, increased to %lf* - Self-explanatory. - *Compute cna/atom cutoff may be too large to find ghost atom neighbors* The neighbor cutoff used may not encompass enough ghost atoms to perform this operation correctly. @@ -158,9 +135,6 @@ Doc page with :doc:`ERROR messages ` Conformation of the 4 listed dihedral atoms is extreme; you may want to check your simulation geometry. -*Dihedral style in data file differs from currently defined dihedral style* - Self-explanatory. - *Dihedrals are defined but no dihedral style is set* The topology contains dihedrals, but there are no dihedral forces computed since there was no dihedral_style command. @@ -177,9 +151,6 @@ Doc page with :doc:`ERROR messages ` *Estimated error in splitting of dispersion coeffs is %g* Error is greater than 0.0001 percent. -*Ewald/disp Newton solver failed, using old method to estimate g_ewald* - Self-explanatory. Choosing a different cutoff value may help. - *FENE bond too long* A FENE bond has stretched dangerously far. It's interaction strength will be truncated to attempt to prevent the bond from blowing up. @@ -192,9 +163,6 @@ Doc page with :doc:`ERROR messages ` A FENE bond has stretched dangerously far. It's interaction strength will be truncated to attempt to prevent the bond from blowing up. -*Fix halt condition for fix-id %s met on step %ld with value %g* - Self explanatory. - *Fix SRD walls overlap but fix srd overlap not set* You likely want to set this in your input script. @@ -238,21 +206,12 @@ Doc page with :doc:`ERROR messages ` *Fix property/atom mol or charge w/out ghost communication* A model typically needs these properties defined for ghost atoms. -*Fix qeq CG convergence failed (%g) after %d iterations at %ld step* - Self-explanatory. - *Fix qeq has non-zero lower Taper radius cutoff* Absolute value must be <= 0.01. *Fix qeq has very low Taper radius cutoff* Value should typically be >= 5.0. -*Fix qeq/dynamic tolerance may be too small for damped dynamics* - Self-explanatory. - -*Fix qeq/fire tolerance may be too small for damped fires* - Self-explanatory. - *Fix rattle should come after all other integration fixes* This fix is designed to work after all other integration fixes change atom positions. Thus it should be the last integration fix specified. @@ -285,9 +244,6 @@ Doc page with :doc:`ERROR messages ` The user-specified force accuracy cannot be achieved unless the table feature is disabled by using 'pair_modify table 0'. -*Geometric mixing assumed for 1/r\^6 coefficients* - Self-explanatory. - *Group for fix_modify temp != fix group* The fix_modify command is specifying a temperature computation that computes a temperature on a different group of atoms than the fix @@ -310,46 +266,14 @@ Doc page with :doc:`ERROR messages ` Conformation of the 4 listed improper atoms is extreme; you may want to check your simulation geometry. -*Improper style in data file differs from currently defined improper style* - Self-explanatory. - *Impropers are defined but no improper style is set* The topology contains impropers, but there are no improper forces computed since there was no improper_style command. -*Inconsistent image flags* - The image flags for a pair on bonded atoms appear to be inconsistent. - Inconsistent means that when the coordinates of the two atoms are - unwrapped using the image flags, the two atoms are far apart. - Specifically they are further apart than half a periodic box length. - Or they are more than a box length apart in a non-periodic dimension. - This is usually due to the initial data file not having correct image - flags for the two atoms in a bond that straddles a periodic boundary. - They should be different by 1 in that case. This is a warning because - inconsistent image flags will not cause problems for dynamics or most - LAMMPS simulations. However they can cause problems when such atoms - are used with the fix rigid or replicate commands. Note that if you - have an infinite periodic crystal with bonds then it is impossible to - have fully consistent image flags, since some bonds will cross - periodic boundaries and connect two atoms with the same image - flag. - *Increasing communication cutoff for GPU style* The pair style has increased the communication cutoff to be consistent with the communication cutoff requirements for this pair style when run on the GPU. -*KIM Model does not provide 'energy'; Potential energy will be zero* - Self-explanatory. - -*KIM Model does not provide 'forces'; Forces will be zero* - Self-explanatory. - -*KIM Model does not provide 'particleEnergy'; energy per atom will be zero* - Self-explanatory. - -*KIM Model does not provide 'particleVirial'; virial per atom will be zero* - Self-explanatory. - *Kspace_modify slab param < 2.0 may cause unphysical behavior* The kspace_modify slab parameter should be larger to ensure periodic grids padded with empty space do not overlap. @@ -401,20 +325,10 @@ Doc page with :doc:`ERROR messages ` box, or moved further than one processor's subdomain away before reneighboring. -*MSM mesh too small, increasing to 2 points in each direction* - Self-explanatory. - *Mismatch between velocity and compute groups* The temperature computation used by the velocity command will not be on the same group of atoms that velocities are being set for. -*Mixing forced for lj coefficients* - Self-explanatory. - -*Molecule attributes do not match system attributes* - An attribute is specified (e.g. diameter, charge) that is - not defined for the specified atom style. - *Molecule has bond topology but no special bond settings* This means the bonded atoms will not be excluded in pairwise interactions. @@ -449,9 +363,6 @@ Doc page with :doc:`ERROR messages ` *More than one compute damage/atom* It is not efficient to use compute ke/atom more than once. -*More than one compute dilatation/atom* - Self-explanatory. - *More than one compute erotate/sphere/atom* It is not efficient to use compute erorate/sphere/atom more than once. @@ -464,24 +375,6 @@ Doc page with :doc:`ERROR messages ` *More than one compute orientorder/atom* It is not efficient to use compute orientorder/atom more than once. -*More than one compute plasticity/atom* - Self-explanatory. - -*More than one compute sna/atom* - Self-explanatory. - -*More than one compute sna/grid* - Self-explanatory. - -*More than one compute sna/grid/local* - Self-explanatory. - -*More than one compute snad/atom* - Self-explanatory. - -*More than one compute snav/atom* - Self-explanatory. - *More than one fix poems* It is not efficient to use fix poems more than once. @@ -557,21 +450,12 @@ Doc page with :doc:`ERROR messages ` *Pair COMB charge %.10f with force %.10f hit min barrier* Something is possibly wrong with your model. -*Pair brownian needs newton pair on for momentum conservation* - Self-explanatory. - -*Pair dpd needs newton pair on for momentum conservation* - Self-explanatory. - *Pair dsmc: num_of_collisions > number_of_A* Collision model in DSMC is breaking down. *Pair dsmc: num_of_collisions > number_of_B* Collision model in DSMC is breaking down. -*Pair style in data file differs from currently defined pair style* - Self-explanatory. - *Pair style restartinfo set but has no restart support* This pair style has a bug, where it does not support reading and writing information to a restart file, but does not set the member @@ -681,9 +565,6 @@ Doc page with :doc:`ERROR messages ` cluster specified by the fix shake command is numerically suspect. LAMMPS will set it to 0.0 and continue. -*Shell command '%s' failed with error '%s'* - Self-explanatory. - *Shell command returned with non-zero status* This may indicate the shell command did not operate as expected. @@ -694,15 +575,9 @@ Doc page with :doc:`ERROR messages ` This will lead to invalid constraint forces in the SHAKE/RATTLE computation. -*Simulations might be very slow because of large number of structure factors* - Self-explanatory. - *Slab correction not needed for MSM* Slab correction is intended to be used with Ewald or PPPM and is not needed by MSM. -*Specifying an 'subset' value of '0' is equivalent to no 'subset' keyword* - Self-explanatory. - *System is not charge neutral, net charge = %g* The total charge on all atoms on the system is not 0.0. For some KSpace solvers this is only a warning. @@ -734,9 +609,6 @@ Doc page with :doc:`ERROR messages ` assumed to also be for all atoms. Thus the pressure printed by thermo could be inaccurate. -*The fix ave/spatial command has been replaced by the more flexible fix ave/chunk and compute chunk/atom commands -- fix ave/spatial will be removed in the summer of 2015* - Self-explanatory. - *The minimizer does not re-orient dipoles when using fix efield* This means that only the atom coordinates will be minimized, not the orientation of the dipoles. @@ -745,9 +617,6 @@ Doc page with :doc:`ERROR messages ` More than the maximum # of neighbors was found multiple times. This was unexpected. -*Too many inner timesteps in fix ttm* - Self-explanatory. - *Too many neighbors in CNA for %d atoms* More than the maximum # of neighbors was found multiple times. This was unexpected. @@ -775,24 +644,6 @@ Doc page with :doc:`ERROR messages ` The deformation will heat the SRD particles so this can be dangerous. -*Using kspace solver on system with no charge* - Self-explanatory. - -*Using largest cut-off for lj/long/dipole/long long long* - Self-explanatory. - -*Using largest cutoff for buck/long/coul/long* - Self-explanatory. - -*Using largest cutoff for lj/long/coul/long* - Self-explanatory. - -*Using largest cutoff for pair_style lj/long/tip4p/long* - Self-explanatory. - -*Using package gpu without any pair style defined* - Self-explanatory. - *Using pair potential shift with pair_modify compute no* The shift effects will thus not be computed. diff --git a/doc/src/Examples.rst b/doc/src/Examples.rst index 3d2103fd6f..d80fc8aa4c 100644 --- a/doc/src/Examples.rst +++ b/doc/src/Examples.rst @@ -54,7 +54,7 @@ Lowercase directories +-------------+------------------------------------------------------------------+ | body | body particles, 2d system | +-------------+------------------------------------------------------------------+ -| bpm | BPM simulations of pouring elastic grains and plate impact | +| bpm | simulations of solid elastic/plastic deformation and fracture | +-------------+------------------------------------------------------------------+ | cmap | CMAP 5-body contributions to CHARMM force field | +-------------+------------------------------------------------------------------+ @@ -146,6 +146,8 @@ Lowercase directories +-------------+------------------------------------------------------------------+ | streitz | use of Streitz/Mintmire potential with charge equilibration | +-------------+------------------------------------------------------------------+ +| stress_vcm | removing binned rigid body motion from binned stress profile | ++-------------+------------------------------------------------------------------+ | tad | temperature-accelerated dynamics of vacancy diffusion in bulk Si | +-------------+------------------------------------------------------------------+ | threebody | regression test input for a variety of manybody potentials | diff --git a/doc/src/Fortran.rst b/doc/src/Fortran.rst index d50c7bdcf3..0a8434f63d 100644 --- a/doc/src/Fortran.rst +++ b/doc/src/Fortran.rst @@ -321,6 +321,14 @@ of the contents of the :f:mod:`LIBLAMMPS` Fortran interface to LAMMPS. :ftype set_string_variable: subroutine :f set_internal_variable: :f:subr:`set_internal_variable` :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` @@ -954,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 @@ -1066,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 @@ -1324,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 @@ -1448,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 @@ -2711,8 +2773,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type END SUBROUTINE external_callback END INTERFACE - where ``c_bigint`` is ``c_int`` if ``-DLAMMPS_SMALLSMALL`` was used and - ``c_int64_t`` otherwise; and ``c_tagint`` is ``c_int64_t`` if + where ``c_bigint`` is ``c_int64_t`` and ``c_tagint`` is ``c_int64_t`` if ``-DLAMMPS_BIGBIG`` was used and ``c_int`` otherwise. The argument *caller* to :f:subr:`set_fix_external_callback` is unlimited diff --git a/doc/src/Howto.rst b/doc/src/Howto.rst index 5a63e2b1c4..ec90472c27 100644 --- a/doc/src/Howto.rst +++ b/doc/src/Howto.rst @@ -40,6 +40,7 @@ Settings howto Howto_walls Howto_nemd Howto_dispersion + Howto_bulk2slab Analysis howto ============== @@ -103,6 +104,7 @@ Tutorials howto Howto_github Howto_lammps_gui Howto_moltemplate + Howto_python Howto_pylammps Howto_wsl 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/Howto_bpm.rst b/doc/src/Howto_bpm.rst index f2aa1fc0a3..f632ee6172 100644 --- a/doc/src/Howto_bpm.rst +++ b/doc/src/Howto_bpm.rst @@ -42,12 +42,14 @@ such as those created by pouring grains using :doc:`fix pour ---------- -Currently, there are two types of bonds included in the BPM package. The +Currently, there are three types of bonds included in the BPM package. The first bond style, :doc:`bond bpm/spring `, only applies pairwise, central body forces. Point particles must have :doc:`bond atom style ` and may be thought of as nodes in a spring network. An optional multibody term can be used to adjust the network's -Poisson's ratio. Alternatively, the second bond style, :doc:`bond bpm/rotational +Poisson's ratio. The :doc:`bpm/spring/plastic ` +bond style is similar except it adds a plastic yield strain. +Alternatively, the third bond style, :doc:`bond bpm/rotational `, resolves tangential forces and torques arising with the shearing, bending, and twisting of the bond due to rotation or displacement of particles. Particles are similar to those used in the diff --git a/doc/src/Howto_bulk2slab.rst b/doc/src/Howto_bulk2slab.rst new file mode 100644 index 0000000000..2c26961522 --- /dev/null +++ b/doc/src/Howto_bulk2slab.rst @@ -0,0 +1,160 @@ +=========================== +Convert bulk system to slab +=========================== + +A regularly encountered simulation problem is how to convert a bulk +system that has been run for a while to equilibrate into a slab system +with some vacuum space and free surfaces. The challenge here is that +one cannot just change the box dimensions with the :doc:`change_box +command ` or edit the box boundaries in a data file because +some atoms will have non-zero image flags from diffusing around. + +Changing the box dimensions results in an undesired displacement of +those atoms, since the image flags indicate how many times the box +length in x-, y-, or z-direction needs to be added or subtracted to get +the "unwrapped" coordinates. By changing the box dimension this +distance is changed and thus those atoms move unphysically relative to +their neighbors with zero image flags. Setting image flags forcibly to +zero creates problems because that could break apart molecules by having +one atom of a bond on the top of the system and the other at the bottom. + +.. _bulk2slab: +.. figure:: JPG/rhodo-both.jpg + :figwidth: 80% + :figclass: align-center + + Snapshots of the bulk Rhodopsin in lipid layer and water system (right) + and the generated slab geometry (left) + +.. admonition:: Disclaimer + :class: note + + The following workflow will work for many bulk systems, but not all. + Some systems cannot be converted (e.g. polymers with bonds to the + same molecule across periodic boundaries, sometimes called "infinite + polymers"). The amount of vacuum that needs to be added depends on + the length of the molecules where the system is split (the example + here splits where there is water with short molecules). In some + cases, the system may need to be re-centered in the box first using + the :doc:`displace_atoms command `. Also, the time + spent on strong thermalization and equilibration will depend on the + specific system and its thermodynamic conditions. + +Below is a suggested workflow using the :doc:`Rhodopsin benchmark input +` for demonstration. The figure shows the state *before* +the procedure on the left (with unwrapped atoms that have diffused out +of the box) and *after* on the right (with the vacuum added above and +below). The procedure is implemented by modifying a copy of the +``in.rhodo`` input file. The first lines up to and including the +:doc:`read_data command ` remain unchanged. Then we insert +the following lines to add vacuum to the z direction above and below the +system: + +.. code-block:: LAMMPS + + variable delta index 10.0 + reset_atoms image all + write_dump all custom rhodo-unwrap.lammpstrj id xu yu zu + change_box all z final $(zlo-2.0*v_delta) $(zhi+2.0*v_delta) & + boundary p p f + read_dump rhodo-unwrap.lammpstrj 0 x y z box no replace yes + kspace_modify slab 3.0 + +Specifically, the :doc:`variable delta ` (set to 10.0) +represents a distance that determines the amount of vacuum added: we add +twice its value in each direction to the z-dimension; thus in total +:math:`40 \AA` get added. The :doc:`reset_atoms image all +` command shall reset any image flags to become either 0 or +:math:`\pm 1` and thus have the minimum distance from the center of the +simulation box, but the correct relative distance for bonded atoms. + +The :doc:`write_dump command ` then writes out the resulting +*unwrapped* coordinates of the system. After expanding the box, +coordinates that were outside the box should now be inside and the +unwrapped coordinates will become "wrapped", while atoms outside the +periodic boundaries will be wrapped back into the box and their image +flags in those directions restored. + +The :doc:`change_box command ` adds the desired +distance to the low and high box boundary in z-direction and then changes +the :doc:`boundary to "p p f" ` which will force the image +flags in z-direction to zero and create an undesired displacement for +the atoms with non-zero image flags. + +With the :doc:`read_dump command ` we read back and replace +partially incorrect coordinates with the previously saved, unwrapped +coordinates. It is important to ignore the box dimensions stored in the +dump file. We want to preserve the expanded box. Finally, we turn on +the slab correction for the PPPM long-range solver with the +:doc:`kspace_modify command ` as required when using a +long range Coulomb solver for non-periodic z-dimension. + +Next we replace the :doc:`fix npt command ` with: + +.. code-block:: LAMMPS + + fix 2 nvt temp 300.0 300.0 10.0 + +We now have an open system and thus the adjustment of the cell in +z-direction is no longer required. Since splitting the bulk water +region where the vacuum is inserted, creates surface atoms with high +potential energy, we reduce the thermostat time constant from 100.0 to +10.0 to remove excess kinetic energy resulting from that change faster. + +Also the high potential energy of the surface atoms can cause that some +of them are ejected from the slab. In order to suppress that, we add +soft harmonic walls to push back any atoms that want to leave the slab. +To determine the position of the wall, we first need to to determine the +extent of the atoms in z-direction and then place the harmonic walls +based on that information: + +.. code-block:: LAMMPS + + compute zmin all reduce min z + compute zmax all reduce max z + thermo_style custom zlo c_zmin zhi c_zmax + run 0 post no + fix 3 all wall/harmonic zhi $(c_zmax+v_delta) 10.0 0.0 ${delta} & + zlo $(c_zmin-v_delta) 10.0 0.0 ${delta} + +The two :doc:`compute reduce ` command determine the +minimum and maximum z-coordinate across all atoms. In order to trigger +the execution of the compute commands we need to "consume" them. This +is done with the :doc:`thermo_style custom ` command +followed by the :doc:`run 0 ` command. This avoids and error +accessing the min/max values determined by the compute commands to +compute the location of the wall in lower and upper direction. This +uses the previously defined *delta* variable to determine the distance +of the wall from the extent of the system and the cutoff for the wall +interaction. This way only atoms that move beyond the min/max values in +z-direction will experience a restoring force, nudging them back to the +slab. The force constant of :math:`10.0 \frac{\mathrm{kcal/mol}}{\AA}` +was determined empirically. + +Adding these "restoring" soft walls assist in making the free surfaces +above and below the slab flat, instead of having rugged or ondulated +surfaces. The impact of the walls can be changed by adjusting the force +constant, cutoff, and position of the wall. + +Finally, we replace the :doc:`run 100 ` of the original input with: + +.. code-block:: LAMMPS + + run 1000 post no + + unfix 3 + fix 2 all nvt temp 300.0 300.0 100.0 + run 1000 post no + + write_data data.rhodo-slab + +This runs the system converted to a slab first for 1000 MD steps using +the walls and stronger Nose-Hoover thermostat. Then the walls are +removed with :doc:`unfix 3 ` and the thermostat time constant +reset to 100.0 and the system run for another 1000 steps. Finally the +resulting slab geometry is written to a new data file +``data.rhodo-slab`` with a :doc:`write_data command `. The +number of MD steps required to reach a proper equilibrium state is very +likely larger. The number of 1000 steps (corresponding to 2 +picoseconds) was chosen for demonstration purposes, so that the +procedure can be easily and quickly tested. diff --git a/doc/src/Howto_github.rst b/doc/src/Howto_github.rst index 78a05f113c..b53a2edbc7 100644 --- a/doc/src/Howto_github.rst +++ b/doc/src/Howto_github.rst @@ -487,10 +487,10 @@ updates are back-ported from the *develop* branch to the *maintenance* branch and occasionally merged to *stable* as an update release. Furthermore, the naming of the release tags now follow the pattern -"patch_" to simplify comparisons between releases. -For stable releases additional "stable_" tags are +"patch\_" to simplify comparisons between releases. +For stable releases additional "stable\_" tags are applied and update releases are tagged with -"stable__update", Finally, all releases and +"stable\_\_update", Finally, all releases and submissions are subject to automatic testing and code checks to make sure they compile with a variety of compilers and popular operating systems. Some unit and regression testing is applied as well. diff --git a/doc/src/Howto_lammps_gui.rst b/doc/src/Howto_lammps_gui.rst index 08be9fb00c..63cf859c57 100644 --- a/doc/src/Howto_lammps_gui.rst +++ b/doc/src/Howto_lammps_gui.rst @@ -64,13 +64,18 @@ simple LAMMPS simulations. It is very suitable for tutorials on LAMMPS since you only need to learn how to use a single program for most tasks and thus time can be saved and people can focus on learning LAMMPS. The tutorials at https://lammpstutorials.github.io/ are specifically -updated for use with LAMMPS-GUI. +updated for use with LAMMPS-GUI and can their tutorial materials can +be downloaded and loaded directly from the GUI. Another design goal is to keep the barrier low when replacing part of the functionality of LAMMPS-GUI with external tools. That said, LAMMPS-GUI has some unique functionality that is not found elsewhere: - auto-adapting to features available in the integrated LAMMPS library +- auto-completion for LAMMPS commands and options +- context-sensitive online help +- start and stop of simulations via mouse or keyboard +- monitoring of simulation progress - interactive visualization using the :doc:`dump image ` command with the option to copy-paste the resulting settings - automatic slide show generation from dump image out at runtime diff --git a/doc/src/Howto_moltemplate.rst b/doc/src/Howto_moltemplate.rst index 1b34169a4f..c4f89a4e26 100644 --- a/doc/src/Howto_moltemplate.rst +++ b/doc/src/Howto_moltemplate.rst @@ -2,14 +2,18 @@ Moltemplate Tutorial ==================== In this tutorial, we are going to use the tool :ref:`Moltemplate -` to set up a classical molecular dynamic simulation using -the :ref:`OPLS-AA force field `. The first -task is to describe an organic compound and create a complete input deck -for LAMMPS. The second task is to map the OPLS-AA force field to a -molecular sample created with an external tool, e.g. PACKMOL, and -exported as a PDB file. The files used in this tutorial can be found -in the ``tools/moltemplate/tutorial-files`` folder of the LAMMPS -source code distribution. +` from https://moltemplate.org/ to set up a classical +molecular dynamic simulation using the :ref:`OPLS-AA force field +`. The first task is to describe an organic compound and +create a complete input deck for LAMMPS. The second task is to use +moltemplate to build a polymer. The third task is to map the OPLS-AA +force field to a molecular sample created with an external tool, +e.g. PACKMOL, and exported as a PDB file. The files used in this +tutorial can be found in the ``tools/moltemplate/tutorial-files`` folder +of the LAMMPS source code distribution. + +Many more examples can be found here: https://moltemplate.org/examples.html + Simulating an organic solvent """"""""""""""""""""""""""""" @@ -17,14 +21,13 @@ Simulating an organic solvent This example aims to create a cubic box of the organic solvent formamide. -The first step is to create a molecular topology in the -LAMMPS-template (LT) file format representing a single molecule, which -will be stored in a Moltemplate object called ``_FAM inherits OPLSAA {}``. +The first step is to create a molecular topology in the LAMMPS-template +(LT) file format representing a single molecule, which will be +stored in a Moltemplate object called ``_FAM inherits OPLSAA {}``. This command states that the object ``_FAM`` is based on an existing object called ``OPLSAA``, which contains OPLS-AA parameters, atom type definitions, partial charges, masses and bond-angle rules for many organic and biological compounds. - The atomic structure is the starting point to populate the command ``write('Data Atoms') {}``, which will write the ``Atoms`` section in the LAMMPS data file. The OPLS-AA force field uses the ``atom_style full``, @@ -36,21 +39,23 @@ to the ``molID``, except that the same variable is used for the whole molecule. The atom types are assigned using ``@``-type variables. The assignment of atom types (e.g. ``@atom:177``, ``@atom:178``) is done using the OPLS-AA atom types defined in the "In Charges" section of the file -``oplsaa.lt``, looking for a reasonable match with the description of the atom. +``oplsaa2024.lt``, looking for a reasonable match with the description of the atom. The resulting file (``formamide.lt``) follows: .. code-block:: bash + import /usr/local/moltemplate/moltemplate/force_fields/oplsaa2024.lt # defines OPLSAA + _FAM inherits OPLSAA { # atomID molID atomType charge coordX coordY coordZ write('Data Atoms') { - $atom:C00 $mol @atom:177 0.00 0.100 0.490 0.0 - $atom:O01 $mol @atom:178 0.00 1.091 -0.250 0.0 - $atom:N02 $mol @atom:179 0.00 -1.121 -0.181 0.0 - $atom:H03 $mol @atom:182 0.00 -2.013 0.272 0.0 - $atom:H04 $mol @atom:182 0.00 -1.056 -1.190 0.0 - $atom:H05 $mol @atom:221 0.00 0.144 1.570 0.0 + $atom:C00 $mol @atom:235 0.00 0.100 0.490 0.0 + $atom:O01 $mol @atom:236 0.00 1.091 -0.250 0.0 + $atom:N02 $mol @atom:237 0.00 -1.121 -0.181 0.0 + $atom:H03 $mol @atom:240 0.00 -2.013 0.272 0.0 + $atom:H04 $mol @atom:240 0.00 -1.056 -1.190 0.0 + $atom:H05 $mol @atom:279 0.00 0.144 1.570 0.0 } # A list of the bonds in the molecule: @@ -64,16 +69,17 @@ The resulting file (``formamide.lt``) follows: } } -You don't have to specify the charge in this example because they will -be assigned according to the atom type. Analogously, only a -"Data Bond List" section is needed as the atom type will determine the -bond type. The other bonded interactions (e.g. angles, -dihedrals, and impropers) will be automatically generated by +You don't have to specify the charge in this example because the OPLSAA +force-field assigns charge according to the atom type. (This is not true +when using other force fields.) A "Data Bond List" section is needed as +the atom type will determine the bond type. The other bonded interactions +(e.g. angles, dihedrals, and impropers) will be automatically generated by Moltemplate. -If the simulation is non-neutral, or Moltemplate complains that you have -missing bond, angle, or dihedral types, this means at least one of your -atom types is incorrect. +If the simulation is not charge-neutral, or Moltemplate complains that +you have missing bond, angle, or dihedral types, this probably means that +at least one of your atom types is incorrect (or that perhaps there is no +suitable atom type currently defined in the ``oplsaa2024.lt`` file). The second step is to create a master file with instructions to build a starting structure and the LAMMPS commands to run an NPT simulation. The @@ -81,11 +87,9 @@ master file (``solv_01.lt``) follows: .. code-block:: bash - # Import the force field. - import /usr/local/moltemplate/moltemplate/force_fields/oplsaa.lt - import formamide.lt # after oplsaa.lt, as it depends on it. + import formamide.lt # Defines "_FAM" and OPLSAA - # Create the input sample. + # Distribute the molecules on a 5x5x5 cubic grid with spacing 4.6 solv = new _FAM [5].move( 4.6, 0, 0) [5].move( 0, 4.6, 0) [5].move( 0, 0, 4.6) @@ -98,8 +102,11 @@ master file (``solv_01.lt``) follows: -11.5 11.5 zlo zhi } - # Create an input deck for LAMMPS. - write_once("In Init"){ + # Note: The lines below in the "In Run" section are often omitted. + + write_once("In Run"){ + # Create an input deck for LAMMPS. + # Run an NPT simulation. # Input variables. variable run string solv_01 # output name variable ts equal 1 # timestep @@ -109,12 +116,6 @@ master file (``solv_01.lt``) follows: variable equi equal 5000 # Equilibration steps variable prod equal 30000 # Production steps - # PBC (set them before the creation of the box). - boundary p p p - } - - # Run an NPT simulation. - write_once("In Run"){ # Derived variables. variable tcouple equal \$\{ts\}*100 variable pcouple equal \$\{ts\}*1000 @@ -143,7 +144,7 @@ master file (``solv_01.lt``) follows: unfix NPT } -The first two commands insert the content of files ``oplsaa.lt`` and +The first two commands insert the content of files ``oplsaa2024.lt`` and ``formamide.lt`` into the master file. At this point, we can use the command ``solv = new _FAM [N]`` to create N copies of a molecule of type ``_FAM``. In this case, we create an array of 5*5*5 molecules on a cubic @@ -153,21 +154,37 @@ the sample was created from scratch, we also specify the simulation box size in the "Data Boundary" section. The LAMMPS setting for the force field are specified in the file -``oplsaa.lt`` and are written automatically in the input deck. We also +``oplsaa2024.lt`` and are written automatically in the input deck. We also specify the boundary conditions and a set of variables in -the "In Init" section. The remaining commands to run an NPT simulation +the "In Init" section. + +The remaining commands to run an NPT simulation are written in the "In Run" section. Note that in this script, LAMMPS variables are protected with the escape character ``\`` to distinguish them from Moltemplate variables, e.g. ``\$\{run\}`` is a LAMMPS variable that is written in the input deck as ``${run}``. +(Note: Moltemplate can be slow to run, so you need to change you run +settings frequently, I recommended moving those commands (from "In Run") +out of your .lt files and into a separate file. Moltemplate creates a +file named ``run.in.EXAMPLE`` for this purpose. You can put your run +settings and fixes that file and then invoke LAMMPS using +``mpirun -np 4 lmp -in run.in.EXAMPLE`` instead.) + + Compile the master file with: .. code-block:: bash - moltemplate.sh -overlay-all solv_01.lt + moltemplate.sh solv_01.lt + cleanup_moltemplate.sh # <-- optional: see below -And execute the simulation with the following: +(Note: The optional "cleanup_moltemplate.sh" command deletes +unused atom types, which sometimes makes LAMMPS run faster. +But it does not work with many-body pair styles or dreiding-style h-bonds. +Fortunately most force fields, including OPLSAA, don't use those features.) + +Then execute the simulation with the following: .. code-block:: bash @@ -180,15 +197,116 @@ And execute the simulation with the following: Snapshot of the sample at the beginning and end of the simulation. Rendered with Ovito. + +Building a simple polymer +""""""""""""""""""""""""" +Moltemplate is particularly useful for building polymers (and other molecules +with sub-units). As an simple example, consider butane: + +.. figure:: JPG/butane.jpg + +The ``butane.lt`` file below defines Butane as a polymer containing +4 monomers (of type ``CH3``, ``CH2``, ``CH2``, ``CH3``). + +.. code-block:: bash + + import /usr/local/moltemplate/moltemplate/force_fields/oplsaa2024.lt # defines OPLSAA + + CH3 inherits OPLSAA { + + # atomID molID atomType charge coordX coordY coordZ + write("Data Atoms") { + $atom:c $mol:... @atom:54 0.0 0.000000 0.4431163 0.000000 + $atom:h1 $mol:... @atom:60 0.0 0.000000 1.0741603 0.892431 + $atom:h2 $mol:... @atom:60 0.0 0.000000 1.0741603 -0.892431 + $atom:h3 $mol:... @atom:60 0.0 -0.892431 -0.1879277 0.000000 + } + # (Using "$mol:..." indicates this object ("CH3") is part of a larger + # molecule. Moltemplate will share the molecule-ID with that molecule.) + + # A list of the bonds within the "CH3" molecular sub-unit: + # BondID AtomID1 AtomID2 + write('Data Bond List') { + $bond:ch1 $atom:c $atom:h1 + $bond:ch2 $atom:c $atom:h2 + $bond:ch3 $atom:c $atom:h3 + } + } + + CH2 inherits OPLSAA { + + # atomID molID atomType charge coordX coordY coordZ + write("Data Atoms") { + $atom:c $mol:... @atom:57 0.0 0.000000 0.4431163 0.000000 + $atom:h1 $mol:... @atom:60 0.0 0.000000 1.0741603 0.892431 + $atom:h2 $mol:... @atom:60 0.0 0.000000 1.0741603 -0.892431 + } + + # A list of the bonds within the "CH2" molecular sub-unit: + # BondID AtomID1 AtomID2 + write('Data Bond List') { + $bond:ch1 $atom:c $atom:h1 + $bond:ch2 $atom:c $atom:h2 + } + } + + Butane inherits OPLSAA { + + create_var {$mol} # optional:force all monomers to share the same molecule-ID + + # - Create 4 monomers + # - Move them along the X axis using ".move()", + # - Rotate them 180 degrees with respect to the previous monomer + monomer1 = new CH3 + monomer2 = new CH2.rot(180,1,0,0).move(1.2533223,0,0) + monomer3 = new CH2.move(2.5066446,0,0) + monomer4 = new CH3.rot(180,0,0,1).move(3.7599669,0,0) + + # A list of the bonds connecting different monomers together: + write('Data Bond List') { + $bond:b1 $atom:monomer1/c $atom:monomer2/c + $bond:b2 $atom:monomer2/c $atom:monomer3/c + $bond:b3 $atom:monomer3/c $atom:monomer4/c + } + } + +Again, you don't have to specify the charge in this example because OPLSAA +assigns charges according to the atom type. + +This ``Butane`` object is a molecule which can be used anywhere other molecules +can be used. (You can arrange ``Butane`` molecules on a lattice, as we did previously. +You can also modify individual butane molecules by adding or deleting atoms or bonds. +You can add bonds between specific butane molecules or use ``Butane`` as a +subunit to define even larger molecules. See the moltemplate manual for details.) + + + + + + +How to build a complex polymer +"""""""""""""""""""""""""""""""""""""""""" +A similar procedure can be used to create more complicated polymers, +such as the NIPAM polymer example shown below. For details, see: + +https://github.com/jewettaij/moltemplate/tree/master/examples/all_atom/force_field_OPLSAA/NIPAM_polymer+water+ions + + + + Mapping an existing structure """"""""""""""""""""""""""""" Another helpful way to use Moltemplate is mapping an existing molecular -sample to a force field. This is useful when a complex sample is -assembled from different simulations or created with specialized -software (e.g. PACKMOL). As in the previous example, all molecular -species in the sample must be defined using single-molecule Moltemplate -objects. For this example, we use a short polymer in a box containing +sample to a force field. This is useful when a complex sample is assembled +from different simulations or created with specialized software (e.g. PACKMOL). +(Note: The previous link shows how to build this entire system from scratch +using only moltemplate. However here we will assume instead that we obtained +a PDB file for this system using PACKMOL.) + +As in the previous examples, all molecular species in the sample +are defined using single-molecule Moltemplate objects. +For this example, we use a short polymer in a box containing water molecules and ions in the PDB file ``model.pdb``. It is essential to understand that the order of atoms in the PDB file @@ -246,25 +364,25 @@ The resulting master LT file defining short annealing at a fixed volume .. code-block:: bash # Use the OPLS-AA force field for all species. - import /usr/local/moltemplate/moltemplate/force_fields/oplsaa.lt + import /usr/local/moltemplate/moltemplate/force_fields/oplsaa2024.lt import PolyNIPAM.lt # Define the SPC water and ions as in the OPLS-AA Ca inherits OPLSAA { write("Data Atoms"){ - $atom:a1 $mol:. @atom:354 0.0 0.00000 0.00000 0.000000 + $atom:a1 $mol:. @atom:412 0.0 0.00000 0.00000 0.000000 } } Cl inherits OPLSAA { write("Data Atoms"){ - $atom:a1 $mol:. @atom:344 0.0 0.00000 0.00000 0.000000 + $atom:a1 $mol:. @atom:401 0.0 0.00000 0.00000 0.000000 } } SPC inherits OPLSAA { write("Data Atoms"){ - $atom:O $mol:. @atom:76 0. 0.0000000 0.00000 0.000000 - $atom:H1 $mol:. @atom:77 0. 0.8164904 0.00000 0.5773590 - $atom:H2 $mol:. @atom:77 0. -0.8164904 0.00000 0.5773590 + $atom:O $mol:. @atom:9991 0. 0.0000000 0.00000 0.0000000 + $atom:H1 $mol:. @atom:9990 0. 0.8164904 0.00000 0.5773590 + $atom:H2 $mol:. @atom:9990 0. -0.8164904 0.00000 0.5773590 } write("Data Bond List") { $bond:OH1 $atom:O $atom:H1 @@ -285,8 +403,15 @@ The resulting master LT file defining short annealing at a fixed volume 0 26 zlo zhi } - # Define the input variables. write_once("In Init"){ + boundary p p p # "p p p" is the default. This line is optional. + neighbor 3 bin # (This line is also optional in this example.) + } + + # Note: The lines below in the "In Run" section are often omitted. + + # Run an NVT simulation. + write_once("In Run"){ # Input variables. variable run string sample01 # output name variable ts equal 2 # timestep @@ -294,13 +419,6 @@ The resulting master LT file defining short annealing at a fixed volume variable p equal 1. # equilibrium pressure variable equi equal 30000 # equilibration steps - # PBC (set them before the creation of the box). - boundary p p p - neighbor 3 bin - } - - # Run an NVT simulation. - write_once("In Run"){ # Set the output. thermo 1000 thermo_style custom step etotal evdwl ecoul elong ebond eangle & @@ -314,8 +432,8 @@ The resulting master LT file defining short annealing at a fixed volume write_data \$\{run\}.min # Set the constrains. - group watergroup type @atom:76 @atom:77 - fix 0 watergroup shake 0.0001 10 0 b @bond:042_043 a @angle:043_042_043 + group watergroup type @atom:9991 @atom:9990 + fix 0 watergroup shake 0.0001 10 0 b @bond:spcO_spcH a @angle:spcH_spcO_spcH # Short annealing. timestep \$\{ts\} @@ -327,7 +445,7 @@ The resulting master LT file defining short annealing at a fixed volume In this example, the water model is SPC and it is defined in the -``oplsaa.lt`` file with atom types ``@atom:76`` and ``@atom:77``. For +``oplsaa2024.lt`` file with atom types ``@atom:9991`` and ``@atom:9990``. For water we also use the ``group`` and ``fix shake`` commands with Moltemplate ``@``-type variables, to ensure consistency with the numerical values assigned during compilation. To identify the bond and @@ -336,19 +454,20 @@ are: .. code-block:: bash - replace{ @atom:76 @atom:76_b042_a042_d042_i042 } - replace{ @atom:77 @atom:77_b043_a043_d043_i043 } + replace{ @atom:9991 @atom:9991_bspcO_aspcO_dspcO_ispcO } + replace{ @atom:9990 @atom:9990_bspcH_aspcH_dspcH_ispcH } From which we can identify the following "Data Bonds By Type": -``@bond:042_043 @atom:*_b042*_a*_d*_i* @atom:*_b043*_a*_d*_i*`` and -"Data Angles By Type": ``@angle:043_042_043 @atom:*_b*_a043*_d*_i* -@atom:*_b*_a042*_d*_i* @atom:*_b*_a043*_d*_i*`` +``@bond:spcO_spcH @atom:*_bspcO*_a*_d*_i* @atom:*_bspcH*_a*_d*_i*`` +and "Data Angles By Type": +``@angle:spcH_spcO_spcH @atom:*_b*_aspcH*_d*_i* @atom:*_b*_aspcO*_d*_i* @atom:*_b*_aspcH*_d*_i*`` Compile the master file with: .. code-block:: bash - moltemplate.sh -overlay-all -pdb model.pdb sample01.lt + moltemplate.sh -pdb model.pdb sample01.lt + cleanup_moltemplate.sh And execute the simulation with the following: @@ -363,8 +482,13 @@ And execute the simulation with the following: Sample visualized with Ovito loading the trajectory into the DATA file written after minimization. + ------------ -.. _OPLSAA96: +.. _oplsaa2024: -**(OPLS-AA)** Jorgensen, Maxwell, Tirado-Rives, J Am Chem Soc, 118(45), 11225-11236 (1996). +**(OPLS-AA)** Jorgensen, W.L., Ghahremanpour, M.M., Saar, A., Tirado-Rives, J., J. Phys. Chem. B, 128(1), 250-262 (2024). + +.. _Moltemplate1: + +**(Moltemplate)** Jewett et al., J. Mol. Biol., 433(11), 166841 (2021) diff --git a/doc/src/Howto_peri.rst b/doc/src/Howto_peri.rst index 29eb685c81..fa299e7f84 100644 --- a/doc/src/Howto_peri.rst +++ b/doc/src/Howto_peri.rst @@ -197,7 +197,7 @@ The LPS model has a force scalar state .. math:: \underline{t} = \frac{3K\theta}{m}\underline{\omega}\,\underline{x} + - \alpha \underline{\omega}\,\underline{e}^{\rm d}, \qquad\qquad\textrm{(3)} + \alpha \underline{\omega}\,\underline{e}^\mathrm{d}, \qquad\qquad\textrm{(3)} with :math:`K` the bulk modulus and :math:`\alpha` related to the shear modulus :math:`G` as @@ -242,14 +242,14 @@ scalar state are defined, respectively, as .. math:: - \underline{e}^{\rm i}=\frac{\theta \underline{x}}{3}, \qquad - \underline{e}^{\rm d} = \underline{e}- \underline{e}^{\rm i}, + \underline{e}^\mathrm{i}=\frac{\theta \underline{x}}{3}, \qquad + \underline{e}^\mathrm{d} = \underline{e}- \underline{e}^\mathrm{i}, where the arguments of the state functions and the vectors on which they operate are omitted for simplicity. We note that the LPS model is linear in the dilatation :math:`\theta`, and in the deviatoric part of the -extension :math:`\underline{e}^{\rm d}`. +extension :math:`\underline{e}^\mathrm{d}`. .. note:: diff --git a/doc/src/Howto_pylammps.rst b/doc/src/Howto_pylammps.rst index 645434bbab..4a9b985bf6 100644 --- a/doc/src/Howto_pylammps.rst +++ b/doc/src/Howto_pylammps.rst @@ -1,564 +1,6 @@ PyLammps Tutorial ================= -.. contents:: - -Overview --------- - -:py:class:`PyLammps ` is a Python wrapper class for -LAMMPS which can be created on its own or use an existing -:py:class:`lammps Python ` object. It creates a simpler, -more "pythonic" interface to common LAMMPS functionality, in contrast to -the :py:class:`lammps ` wrapper for the LAMMPS :ref:`C -language library interface API ` which is written using -`Python ctypes `_. The :py:class:`lammps ` -wrapper is discussed on the :doc:`Python_head` doc page. - -Unlike the flat `ctypes `_ interface, PyLammps exposes a -discoverable API. It no longer requires knowledge of the underlying C++ -code implementation. Finally, the :py:class:`IPyLammps -` wrapper builds on top of :py:class:`PyLammps -` and adds some additional features for `IPython -integration `_ into `Jupyter notebooks `_, e.g. for -embedded visualization output from :doc:`dump style image `. - -.. _ctypes: https://docs.python.org/3/library/ctypes.html -.. _ipython: https://ipython.org/ -.. _jupyter: https://jupyter.org/ - -Comparison of lammps and PyLammps interfaces -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -lammps.lammps -""""""""""""" - -* uses `ctypes `_ -* direct memory access to native C++ data with optional support for NumPy arrays -* provides functions to send and receive data to LAMMPS -* interface modeled after the LAMMPS :ref:`C language library interface API ` -* requires knowledge of how LAMMPS internally works (C pointers, etc) -* full support for running Python with MPI using `mpi4py `_ -* no overhead from creating a more Python-like interface - -lammps.PyLammps -""""""""""""""" - -* higher-level abstraction built on *top* of the original :py:class:`ctypes based interface ` -* manipulation of Python objects -* communication with LAMMPS is hidden from API user -* shorter, more concise Python -* better IPython integration, designed for quick prototyping -* designed for serial execution -* additional overhead from capturing and parsing the LAMMPS screen output - -Quick Start ------------ - -System-wide Installation -^^^^^^^^^^^^^^^^^^^^^^^^ - -Step 1: Building LAMMPS as a shared library -""""""""""""""""""""""""""""""""""""""""""" - -To use LAMMPS inside of Python it has to be compiled as shared -library. This library is then loaded by the Python interface. In this -example we enable the MOLECULE package and compile LAMMPS with PNG, JPEG -and FFMPEG output support enabled. - -Step 1a: For the CMake based build system, the steps are: - -.. code-block:: bash - - mkdir $LAMMPS_DIR/build-shared - cd $LAMMPS_DIR/build-shared - - # MPI, PNG, Jpeg, FFMPEG are auto-detected - cmake ../cmake -DPKG_MOLECULE=yes -DBUILD_LIB=yes -DBUILD_SHARED_LIBS=yes - make - -Step 1b: For the legacy, make based build system, the steps are: - -.. code-block:: bash - - cd $LAMMPS_DIR/src - - # add packages if necessary - make yes-MOLECULE - - # compile shared library using Makefile - make mpi mode=shlib LMP_INC="-DLAMMPS_PNG -DLAMMPS_JPEG -DLAMMPS_FFMPEG" JPG_LIB="-lpng -ljpeg" - -Step 2: Installing the LAMMPS Python package -"""""""""""""""""""""""""""""""""""""""""""" - -PyLammps is part of the lammps Python package. To install it simply install -that package into your current Python installation with: - -.. code-block:: bash - - make install-python - -.. note:: - - Recompiling the shared library requires re-installing the Python package - -Installation inside of a virtualenv -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can use virtualenv to create a custom Python environment specifically tuned -for your workflow. - -Benefits of using a virtualenv -"""""""""""""""""""""""""""""" - -* isolation of your system Python installation from your development installation -* installation can happen in your user directory without root access (useful for HPC clusters) -* installing packages through pip allows you to get newer versions of packages than e.g., through apt-get or yum package managers (and without root access) -* you can even install specific old versions of a package if necessary - -**Prerequisite (e.g. on Ubuntu)** - -.. code-block:: bash - - apt-get install python-virtualenv - -Creating a virtualenv with lammps installed -""""""""""""""""""""""""""""""""""""""""""" - -.. code-block:: bash - - # create virtualenv named 'testing' - virtualenv $HOME/python/testing - - # activate 'testing' environment - source $HOME/python/testing/bin/activate - -Now configure and compile the LAMMPS shared library as outlined above. -When using CMake and the shared library has already been build, you -need to re-run CMake to update the location of the python executable -to the location in the virtual environment with: - -.. code-block:: bash - - cmake . -DPython_EXECUTABLE=$(which python) - - # install LAMMPS package in virtualenv - (testing) make install-python - - # install other useful packages - (testing) pip install matplotlib jupyter mpi4py - - ... - - # return to original shell - (testing) deactivate - -Creating a new instance of PyLammps ------------------------------------ - -To create a PyLammps object you need to first import the class from the lammps -module. By using the default constructor, a new *lammps* instance is created. - -.. code-block:: python - - from lammps import PyLammps - L = PyLammps() - -You can also initialize PyLammps on top of this existing *lammps* object: - -.. code-block:: python - - from lammps import lammps, PyLammps - lmp = lammps() - L = PyLammps(ptr=lmp) - -Commands --------- - -Sending a LAMMPS command with the existing library interfaces is done using -the command method of the lammps object instance. - -For instance, let's take the following LAMMPS command: - -.. code-block:: LAMMPS - - region box block 0 10 0 5 -0.5 0.5 - -In the original interface this command can be executed with the following -Python code if *L* was a lammps instance: - -.. code-block:: python - - L.command("region box block 0 10 0 5 -0.5 0.5") - -With the PyLammps interface, any command can be split up into arbitrary parts -separated by white-space, passed as individual arguments to a region method. - -.. code-block:: python - - L.region("box block", 0, 10, 0, 5, -0.5, 0.5) - -Note that each parameter is set as Python literal floating-point number. In the -PyLammps interface, each command takes an arbitrary parameter list and transparently -merges it to a single command string, separating individual parameters by white-space. - -The benefit of this approach is avoiding redundant command calls and easier -parameterization. In the original interface parameterization needed to be done -manually by creating formatted strings. - -.. code-block:: python - - L.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi)) - -In contrast, methods of PyLammps accept parameters directly and will convert -them automatically to a final command string. - -.. code-block:: python - - L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi) - -System state ------------- - -In addition to dispatching commands directly through the PyLammps object, it -also provides several properties which allow you to query the system state. - -L.system - Is a dictionary describing the system such as the bounding box or number of atoms - -L.system.xlo, L.system.xhi - bounding box limits along x-axis - -L.system.ylo, L.system.yhi - bounding box limits along y-axis - -L.system.zlo, L.system.zhi - bounding box limits along z-axis - -L.communication - configuration of communication subsystem, such as the number of threads or processors - -L.communication.nthreads - number of threads used by each LAMMPS process - -L.communication.nprocs - number of MPI processes used by LAMMPS - -L.fixes - List of fixes in the current system - -L.computes - List of active computes in the current system - -L.dump - List of active dumps in the current system - -L.groups - List of groups present in the current system - -Working with LAMMPS variables ------------------------------ - -LAMMPS variables can be both defined and accessed via the PyLammps interface. - -To define a variable you can use the :doc:`variable ` command: - -.. code-block:: python - - L.variable("a index 2") - -A dictionary of all variables is returned by L.variables - -you can access an individual variable by retrieving a variable object from the -L.variables dictionary by name - -.. code-block:: python - - a = L.variables['a'] - -The variable value can then be easily read and written by accessing the value -property of this object. - -.. code-block:: python - - print(a.value) - a.value = 4 - -Retrieving the value of an arbitrary LAMMPS expressions -------------------------------------------------------- - -LAMMPS expressions can be immediately evaluated by using the eval method. The -passed string parameter can be any expression containing global thermo values, -variables, compute or fix data. - -.. code-block:: python - - result = L.eval("ke") # kinetic energy - result = L.eval("pe") # potential energy - - result = L.eval("v_t/2.0") - -Accessing atom data -------------------- - -All atoms in the current simulation can be accessed by using the L.atoms list. -Each element of this list is an object which exposes its properties (id, type, -position, velocity, force, etc.). - -.. code-block:: python - - # access first atom - L.atoms[0].id - L.atoms[0].type - - # access second atom - L.atoms[1].position - L.atoms[1].velocity - L.atoms[1].force - -Some properties can also be used to set: - -.. code-block:: python - - # set position in 2D simulation - L.atoms[0].position = (1.0, 0.0) - - # set position in 3D simulation - L.atoms[0].position = (1.0, 0.0, 1.) - -Evaluating thermo data ----------------------- - -Each simulation run usually produces thermo output based on system state, -computes, fixes or variables. The trajectories of these values can be queried -after a run via the L.runs list. This list contains a growing list of run data. -The first element is the output of the first run, the second element that of -the second run. - -.. code-block:: python - - L.run(1000) - L.runs[0] # data of first 1000 time steps - - L.run(1000) - L.runs[1] # data of second 1000 time steps - -Each run contains a dictionary of all trajectories. Each trajectory is -accessible through its thermo name: - -.. code-block:: python - - L.runs[0].thermo.Step # list of time steps in first run - L.runs[0].thermo.Ke # list of kinetic energy values in first run - -Together with matplotlib plotting data out of LAMMPS becomes simple: - -.. code-block:: python - - import matplotlib.plot as plt - steps = L.runs[0].thermo.Step - ke = L.runs[0].thermo.Ke - plt.plot(steps, ke) - -Error handling with PyLammps ----------------------------- - -Using C++ exceptions in LAMMPS for errors allows capturing them on the -C++ side and rethrowing them on the Python side. This way you can handle -LAMMPS errors through the Python exception handling mechanism. - -.. warning:: - - Capturing a LAMMPS exception in Python can still mean that the - current LAMMPS process is in an illegal state and must be - terminated. It is advised to save your data and terminate the Python - instance as quickly as possible. - -Using PyLammps in IPython notebooks and Jupyter ------------------------------------------------ - -If the LAMMPS Python package is installed for the same Python interpreter as -IPython, you can use PyLammps directly inside of an IPython notebook inside of -Jupyter. Jupyter is a powerful integrated development environment (IDE) for -many dynamic languages like Python, Julia and others, which operates inside of -any web browser. Besides auto-completion and syntax highlighting it allows you -to create formatted documents using Markup, mathematical formulas, graphics and -animations intermixed with executable Python code. It is a great format for -tutorials and showcasing your latest research. - -To launch an instance of Jupyter simply run the following command inside your -Python environment (this assumes you followed the Quick Start instructions): - -.. code-block:: bash - - jupyter notebook - -IPyLammps Examples ------------------- - -Examples of IPython notebooks can be found in the python/examples/pylammps -subdirectory. To open these notebooks launch *jupyter notebook* inside this -directory and navigate to one of them. If you compiled and installed -a LAMMPS shared library with exceptions, PNG, JPEG and FFMPEG support -you should be able to rerun all of these notebooks. - -Validating a dihedral potential -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This example showcases how an IPython Notebook can be used to compare a simple -LAMMPS simulation of a harmonic dihedral potential to its analytical solution. -Four atoms are placed in the simulation and the dihedral potential is applied on -them using a datafile. Then one of the atoms is rotated along the central axis by -setting its position from Python, which changes the dihedral angle. - -.. code-block:: python - - phi = [d \* math.pi / 180 for d in range(360)] - - pos = [(1.0, math.cos(p), math.sin(p)) for p in phi] - - pe = [] - for p in pos: - L.atoms[3].position = p - L.run(0) - pe.append(L.eval("pe")) - -By evaluating the potential energy for each position we can verify that -trajectory with the analytical formula. To compare both solutions, we plot -both trajectories over each other using matplotlib, which embeds the generated -plot inside the IPython notebook. - -.. image:: JPG/pylammps_dihedral.jpg - :align: center - -Running a Monte Carlo relaxation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This second example shows how to use PyLammps to create a 2D Monte Carlo Relaxation -simulation, computing and plotting energy terms and even embedding video output. - -Initially, a 2D system is created in a state with minimal energy. - -.. image:: JPG/pylammps_mc_minimum.jpg - :align: center - -It is then disordered by moving each atom by a random delta. - -.. code-block:: python - - random.seed(27848) - deltaperturb = 0.2 - - for i in range(L.system.natoms): - x, y = L.atoms[i].position - dx = deltaperturb \* random.uniform(-1, 1) - dy = deltaperturb \* random.uniform(-1, 1) - L.atoms[i].position = (x+dx, y+dy) - - L.run(0) - -.. image:: JPG/pylammps_mc_disordered.jpg - :align: center - -Finally, the Monte Carlo algorithm is implemented in Python. It continuously -moves random atoms by a random delta and only accepts certain moves. - -.. code-block:: python - - estart = L.eval("pe") - elast = estart - - naccept = 0 - energies = [estart] - - niterations = 3000 - deltamove = 0.1 - kT = 0.05 - - natoms = L.system.natoms - - for i in range(niterations): - iatom = random.randrange(0, natoms) - current_atom = L.atoms[iatom] - - x0, y0 = current_atom.position - - dx = deltamove \* random.uniform(-1, 1) - dy = deltamove \* random.uniform(-1, 1) - - current_atom.position = (x0+dx, y0+dy) - - L.run(1, "pre no post no") - - e = L.eval("pe") - energies.append(e) - - if e <= elast: - naccept += 1 - elast = e - elif random.random() <= math.exp(natoms\*(elast-e)/kT): - naccept += 1 - elast = e - else: - current_atom.position = (x0, y0) - -The energies of each iteration are collected in a Python list and finally plotted using matplotlib. - -.. image:: JPG/pylammps_mc_energies_plot.jpg - :align: center - -The IPython notebook also shows how to use dump commands and embed video files -inside of the IPython notebook. - -Using PyLammps and mpi4py (Experimental) ----------------------------------------- - -PyLammps can be run in parallel using `mpi4py -`_. This python package can be installed -using - -.. code-block:: bash - - pip install mpi4py - -.. warning:: - - Usually, any :py:class:`PyLammps ` command must be - executed by *all* MPI processes. However, evaluations and querying - the system state is only available on MPI rank 0. Using these - functions from other MPI ranks will raise an exception. - -The following is a short example which reads in an existing LAMMPS input -file and executes it in parallel. You can find in.melt in the -examples/melt folder. Please take note that the -:py:meth:`PyLammps.eval() ` is called only from -MPI rank 0. - -.. code-block:: python - - from mpi4py import MPI - from lammps import PyLammps - - L = PyLammps() - L.file("in.melt") - - if MPI.COMM_WORLD.rank == 0: - print("Potential energy: ", L.eval("pe")) - - MPI.Finalize() - -To run this script (melt.py) in parallel using 4 MPI processes we invoke the -following mpirun command: - -.. code-block:: bash - - mpirun -np 4 python melt.py - -Feedback and Contributing -------------------------- - -If you find this Python interface useful, please feel free to provide feedback -and ideas on how to improve it to Richard Berger (richard.berger@outlook.com). We also -want to encourage people to write tutorial style IPython notebooks showcasing LAMMPS usage -and maybe their latest research results. +The PyLammps interface is deprecated and will be removed in a future release of +LAMMPS. As such, the PyLammps version of this tutorial has been removed and is +replaced by the :doc:`Python_head`. diff --git a/doc/src/Howto_python.rst b/doc/src/Howto_python.rst new file mode 100644 index 0000000000..ee919e96e7 --- /dev/null +++ b/doc/src/Howto_python.rst @@ -0,0 +1,464 @@ +LAMMPS Python Tutorial +====================== + +.. contents:: + +----- + +Overview +-------- + +The :py:class:`lammps ` Python module is a wrapper class for the +LAMMPS :ref:`C language library interface API ` which is written using +`Python ctypes `_. The design choice of this wrapper class is to +follow the C language API closely with only small changes related to Python +specific requirements and to better accommodate object oriented programming. + +In addition to this flat `ctypes `_ interface, the +:py:class:`lammps ` wrapper class exposes a discoverable +API that doesn't require as much knowledge of the underlying C language +library interface or LAMMPS C++ code implementation. + +Finally, the API exposes some additional features for `IPython integration +`_ into `Jupyter notebooks `_, e.g. for embedded +visualization output from :doc:`dump style image `. + +.. _ctypes: https://docs.python.org/3/library/ctypes.html +.. _ipython: https://ipython.org/ +.. _jupyter: https://jupyter.org/ + +----- + +Quick Start +----------- + +System-wide or User Installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Step 1: Building LAMMPS as a shared library +""""""""""""""""""""""""""""""""""""""""""" + +To use LAMMPS inside of Python it has to be compiled as shared library. +This library is then loaded by the Python interface. In this example we +enable the :ref:`MOLECULE package ` and compile LAMMPS +with :ref:`PNG, JPEG and FFMPEG output support ` enabled. + +.. tabs:: + + .. tab:: CMake build + + .. code-block:: bash + + mkdir $LAMMPS_DIR/build-shared + cd $LAMMPS_DIR/build-shared + + # MPI, PNG, Jpeg, FFMPEG are auto-detected + cmake ../cmake -DPKG_MOLECULE=yes -DPKG_PYTHON=on -DBUILD_SHARED_LIBS=yes + make + + .. tab:: Traditional make + + .. code-block:: bash + + cd $LAMMPS_DIR/src + + # add LAMMPS packages if necessary + make yes-MOLECULE + make yes-PYTHON + + # compile shared library using Makefile + make mpi mode=shlib LMP_INC="-DLAMMPS_PNG -DLAMMPS_JPEG -DLAMMPS_FFMPEG" JPG_LIB="-lpng -ljpeg" + +Step 2: Installing the LAMMPS Python module +""""""""""""""""""""""""""""""""""""""""""" + +Next install the LAMMPS Python module into your current Python installation with: + +.. code-block:: bash + + make install-python + +This will create a so-called `"wheel" +`_ +and then install the LAMMPS Python module from that "wheel" into either +into a system folder (provided the command is executed with root +privileges) or into your personal Python module folder. + +.. note:: + + Recompiling the shared library requires re-installing the Python + package. + +.. _externally_managed: + +.. admonition:: Handling an "externally-managed-environment" Error + :class: Hint + + Some Python installations made through Linux distributions + (e.g. Ubuntu 24.04LTS or later) will prevent installing the LAMMPS + Python module into a system folder or a corresponding folder of the + individual user as attempted by ``make install-python`` with an error + stating that an *externally managed* python installation must be only + managed by the same package package management tool. This is an + optional setting, so not all Linux distributions follow it currently + (Spring 2025). The reasoning and explanations for this error can be + found in the `Python Packaging User Guide + `_ + + These guidelines suggest to create a virtual environment and install + the LAMMPS Python module there (see below). This is generally a good + idea and the LAMMPS developers recommend this, too. If, however, you + want to proceed and install the LAMMPS Python module regardless, you + can install the "wheel" file (see above) manually with the ``pip`` + command by adding the ``--break-system-packages`` flag. + +Installation inside of a virtual environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can use virtual environments to create a custom Python environment +specifically tuned for your workflow. + +Benefits of using a virtualenv +"""""""""""""""""""""""""""""" + +* isolation of your system Python installation from your development installation +* installation can happen in your user directory without root access (useful for HPC clusters) +* installing packages through pip allows you to get newer versions of packages than e.g., through apt-get or yum package managers (and without root access) +* you can even install specific old versions of a package if necessary + +**Prerequisite (e.g. on Ubuntu)** + +.. code-block:: bash + + apt-get install python-venv + +Creating a virtualenv with lammps installed +""""""""""""""""""""""""""""""""""""""""""" + +.. code-block:: bash + + # create virtual envrionment named 'testing' + python3 -m venv $HOME/python/testing + + # activate 'testing' environment + source $HOME/python/testing/bin/activate + +Now configure and compile the LAMMPS shared library as outlined above. +When using CMake and the shared library has already been build, you +need to re-run CMake to update the location of the python executable +to the location in the virtual environment with: + +.. code-block:: bash + + cmake . -DPython_EXECUTABLE=$(which python) + + # install LAMMPS package in virtualenv + (testing) make install-python + + # install other useful packages + (testing) pip install matplotlib jupyter mpi4py pandas + + ... + + # return to original shell + (testing) deactivate + +------- + +Creating a new lammps instance +------------------------------ + +To create a lammps object you need to first import the class from the lammps +module. By using the default constructor, a new :py:class:`lammps +` instance is created. + +.. code-block:: python + + from lammps import lammps + L = lammps() + +See the :doc:`LAMMPS Python documentation ` for how to customize +the instance creation with optional arguments. + +----- + +Commands +-------- + +Sending a LAMMPS command with the library interface is done using +the ``command`` method of the lammps object. + +For instance, let's take the following LAMMPS command: + +.. code-block:: LAMMPS + + region box block 0 10 0 5 -0.5 0.5 + +This command can be executed with the following Python code if ``L`` is a ``lammps`` +instance: + +.. code-block:: python + + L.command("region box block 0 10 0 5 -0.5 0.5") + +For convenience, the ``lammps`` class also provides a command wrapper ``cmd`` +that turns any LAMMPS command into a regular function call: + +.. code-block:: python + + L.cmd.region("box block", 0, 10, 0, 5, -0.5, 0.5) + +Note that each parameter is set as Python number literal. With +the wrapper each command takes an arbitrary parameter list and transparently +merges it to a single command string, separating individual parameters by +white-space. + +The benefit of this approach is avoiding redundant command calls and easier +parameterization. With the ``command`` function each call needs to be assembled +manually using formatted strings. + +.. code-block:: python + + L.command(f"region box block {xlo} {xhi} {ylo} {yhi} {zlo} {zhi}") + +The wrapper accepts parameters directly and will convert +them automatically to a final command string. + +.. code-block:: python + + L.cmd.region("box block", xlo, xhi, ylo, yhi, zlo, zhi) + +.. note:: + + When running in IPython you can use Tab-completion after ``L.cmd.`` to see + all available LAMMPS commands. + +----- + +Accessing atom data +------------------- + +All per-atom properties that are part of the :doc:`atom style +` in the current simulation can be accessed using the +:py:meth:`extract_atoms() ` method. This +can be retrieved as ctypes objects or as NumPy arrays through the +lammps.numpy module. Those represent the *local* atoms of the +individual sub-domain for the current MPI process and may contain +information for the local ghost atoms or not depending on the property. +Both can be accessed as lists, but for the ctypes list object the size +is not known and hast to be retrieved first to avoid out-of-bounds +accesses. + +.. code-block:: python + + nlocal = L.extract_setting("nlocal") + nall = L.extract_setting("nall") + print("Number of local atoms ", nlocal, " Number of local and ghost atoms ", nall); + + # access via ctypes directly + atom_id = L.extract_atom("id") + print("Atom IDs", atom_id[0:nlocal]) + + # access through numpy wrapper + atom_type = L.numpy.extract_atom("type") + print("Atom types", atom_type) + + x = L.numpy.extract_atom("x") + v = L.numpy.extract_atom("v") + print("positions array shape", x.shape) + print("velocity array shape", v.shape) + # turn on communicating velocities to ghost atoms + L.cmd.comm_modify("vel", "yes") + v = L.numpy.extract_atom('v') + print("velocity array shape", v.shape) + +Some properties can also be set from Python since internally the +data of the C++ code is accessed directly: + +.. code-block:: python + + # set position in 2D simulation + x[0] = (1.0, 0.0) + + # set position in 3D simulation + x[0] = (1.0, 0.0, 1.) + +------ + +Retrieving the values of thermodynamic data and variables +--------------------------------------------------------- + +To access thermodynamic data from the last completed timestep, +you can use the :py:meth:`get_thermo() ` +method, and to extract the value of (compatible) variables, you +can use the :py:meth:`extract_variable() ` +method. + +.. code-block:: python + + result = L.get_thermo("ke") # kinetic energy + result = L.get_thermo("pe") # potential energy + + result = L.extract_variable("t") / 2.0 + +Error handling +-------------- + +We are using C++ exceptions in LAMMPS for errors and the C language +library interface captures and records them. This allows checking +whether errors have happened in Python during a call into LAMMPS and +then re-throw the error as a Python exception. This way you can handle +LAMMPS errors in the conventional way through the Python exception +handling mechanism. + +.. warning:: + + Capturing a LAMMPS exception in Python can still mean that the + current LAMMPS process is in an illegal state and must be + terminated. It is advised to save your data and terminate the Python + instance as quickly as possible. + +Using LAMMPS in IPython notebooks and Jupyter +--------------------------------------------- + +If the LAMMPS Python package is installed for the same Python +interpreter as IPython, you can use LAMMPS directly inside of an IPython +notebook inside of Jupyter. Jupyter is a powerful integrated development +environment (IDE) for many dynamic languages like Python, Julia and +others, which operates inside of any web browser. Besides +auto-completion and syntax highlighting it allows you to create +formatted documents using Markup, mathematical formulas, graphics and +animations intermixed with executable Python code. It is a great format +for tutorials and showcasing your latest research. + +To launch an instance of Jupyter simply run the following command inside your +Python environment (this assumes you followed the Quick Start instructions): + +.. code-block:: bash + + jupyter notebook + +Interactive Python Examples +--------------------------- + +Examples of IPython notebooks can be found in the ``python/examples/ipython`` +subdirectory. To open these notebooks launch ``jupyter notebook`` inside this +directory and navigate to one of them. If you compiled and installed +a LAMMPS shared library with PNG, JPEG and FFMPEG support +you should be able to rerun all of these notebooks. + +Validating a dihedral potential +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This example showcases how an IPython Notebook can be used to compare a simple +LAMMPS simulation of a harmonic dihedral potential to its analytical solution. +Four atoms are placed in the simulation and the dihedral potential is applied on +them using a datafile. Then one of the atoms is rotated along the central axis by +setting its position from Python, which changes the dihedral angle. + +.. code-block:: python + + phi = [d \* math.pi / 180 for d in range(360)] + + pos = [(1.0, math.cos(p), math.sin(p)) for p in phi] + + x = L.numpy.extract_atom("x") + + pe = [] + for p in pos: + x[3] = p + L.cmd.run(0, "post", "no") + pe.append(L.get_thermo("pe")) + +By evaluating the potential energy for each position we can verify that +trajectory with the analytical formula. To compare both solutions, we plot +both trajectories over each other using matplotlib, which embeds the generated +plot inside the IPython notebook. + +.. image:: JPG/pylammps_dihedral.jpg + :align: center + +Running a Monte Carlo relaxation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This second example shows how to use the `lammps` Python interface to create a +2D Monte Carlo Relaxation simulation, computing and plotting energy terms and +even embedding video output. + +Initially, a 2D system is created in a state with minimal energy. + +.. image:: JPG/pylammps_mc_minimum.jpg + :align: center + +It is then disordered by moving each atom by a random delta. + +.. code-block:: python + + random.seed(27848) + deltaperturb = 0.2 + x = L.numpy.extract_atom("x") + natoms = x.shape[0] + + for i in range(natoms): + dx = deltaperturb \* random.uniform(-1, 1) + dy = deltaperturb \* random.uniform(-1, 1) + x[i][0] += dx + x[i][1] += dy + + L.cmd.run(0, "post", "no") + +.. image:: JPG/pylammps_mc_disordered.jpg + :align: center + +Finally, the Monte Carlo algorithm is implemented in Python. It continuously +moves random atoms by a random delta and only accepts certain moves. + +.. code-block:: python + + estart = L.get_thermo("pe") + elast = estart + + naccept = 0 + energies = [estart] + + niterations = 3000 + deltamove = 0.1 + kT = 0.05 + + for i in range(niterations): + x = L.numpy.extract_atom("x") + natoms = x.shape[0] + iatom = random.randrange(0, natoms) + current_atom = x[iatom] + + x0 = current_atom[0] + y0 = current_atom[1] + + dx = deltamove \* random.uniform(-1, 1) + dy = deltamove \* random.uniform(-1, 1) + + current_atom[0] = x0 + dx + current_atom[1] = y0 + dy + + L.cmd.run(1, "pre no post no") + + e = L.get_thermo("pe") + energies.append(e) + + if e <= elast: + naccept += 1 + elast = e + elif random.random() <= math.exp(natoms\*(elast-e)/kT): + naccept += 1 + elast = e + else: + current_atom[0] = x0 + current_atom[1] = y0 + +The energies of each iteration are collected in a Python list and finally plotted using matplotlib. + +.. image:: JPG/pylammps_mc_energies_plot.jpg + :align: center + +The IPython notebook also shows how to use dump commands and embed video files +inside of the IPython notebook. diff --git a/doc/src/Howto_triclinic.rst b/doc/src/Howto_triclinic.rst index 3529579d65..24ac66e103 100644 --- a/doc/src/Howto_triclinic.rst +++ b/doc/src/Howto_triclinic.rst @@ -249,23 +249,23 @@ as follows: .. math:: - a = & {\rm lx} \\ - b^2 = & {\rm ly}^2 + {\rm xy}^2 \\ - c^2 = & {\rm lz}^2 + {\rm xz}^2 + {\rm yz}^2 \\ - \cos{\alpha} = & \frac{{\rm xy}*{\rm xz} + {\rm ly}*{\rm yz}}{b*c} \\ - \cos{\beta} = & \frac{\rm xz}{c} \\ - \cos{\gamma} = & \frac{\rm xy}{b} \\ + a = & \mathrm{lx} \\ + b^2 = & \mathrm{ly}^2 + \mathrm{xy}^2 \\ + c^2 = & \mathrm{lz}^2 + \mathrm{xz}^2 + \mathrm{yz}^2 \\ + \cos{\alpha} = & \frac{\mathrm{xy}*\mathrm{xz} + \mathrm{ly}*\mathrm{yz}}{b*c} \\ + \cos{\beta} = & \frac{\mathrm{xz}}{c} \\ + \cos{\gamma} = & \frac{\mathrm{xy}}{b} \\ The inverse relationship can be written as follows: .. math:: - {\rm lx} = & a \\ - {\rm xy} = & b \cos{\gamma} \\ - {\rm xz} = & c \cos{\beta}\\ - {\rm ly}^2 = & b^2 - {\rm xy}^2 \\ - {\rm yz} = & \frac{b*c \cos{\alpha} - {\rm xy}*{\rm xz}}{\rm ly} \\ - {\rm lz}^2 = & c^2 - {\rm xz}^2 - {\rm yz}^2 \\ + \mathrm{lx} = & a \\ + \mathrm{xy} = & b \cos{\gamma} \\ + \mathrm{xz} = & c \cos{\beta}\\ + \mathrm{ly}^2 = & b^2 - \mathrm{xy}^2 \\ + \mathrm{yz} = & \frac{b*c \cos{\alpha} - \mathrm{xy}*\mathrm{xz}}{\mathrm{ly}} \\ + \mathrm{lz}^2 = & c^2 - \mathrm{xz}^2 - \mathrm{yz}^2 \\ The values of *a*, *b*, *c*, :math:`\alpha` , :math:`\beta`, and :math:`\gamma` can be printed out or accessed by computes using the 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/Install_mac.rst b/doc/src/Install_mac.rst index 452a8fd460..c8e21e8cfe 100644 --- a/doc/src/Install_mac.rst +++ b/doc/src/Install_mac.rst @@ -5,8 +5,7 @@ LAMMPS can be downloaded, built, and configured for macOS with `Homebrew `_. (Alternatively, see the installation instructions for :doc:`downloading an executable via Conda `.) The following LAMMPS packages are unavailable at this time because of -additional requirements not yet met: GPU, KOKKOS, MSCG, POEMS, -VORONOI. +additional requirements not yet met: GPU, KOKKOS. After installing Homebrew, you can install LAMMPS on your system with the following commands: diff --git a/doc/src/Intro_portability.rst b/doc/src/Intro_portability.rst index 036529ff9d..8bb716833f 100644 --- a/doc/src/Intro_portability.rst +++ b/doc/src/Intro_portability.rst @@ -13,10 +13,14 @@ Programming language standards Most of the C++ code currently requires a compiler compatible with the C++11 standard, the KOKKOS package currently requires C++17. Most of -the Python code is written to be compatible with Python 3.5 or later or -Python 2.7. Some Python scripts *require* Python 3 and a few others -still need to be ported from Python 2 to Python 3. +the Python code is written to be compatible with Python 3.6 or later. +.. deprecated:: TBD + +Python 2.x is no longer supported and trying to use it, e.g. for the +LAMMPS Python module should result in an error. If you come across +some part of the LAMMPS distribution that is not (yet) compatible with +Python 3, please notify the LAMMPS developers. Build systems ^^^^^^^^^^^^^ @@ -24,8 +28,8 @@ Build systems LAMMPS can be compiled from source code using a (traditional) build system based on shell scripts, a few shell utilities (grep, sed, cat, tr) and the GNU make program. This requires running within a Bourne -shell (``/bin/sh``). Alternatively, a build system with different back ends -can be created using CMake. CMake must be at least version 3.16. +shell (``/bin/sh``). Alternatively, a build system with different back +ends can be created using CMake. CMake must be at least version 3.16. Operating systems ^^^^^^^^^^^^^^^^^ diff --git a/doc/src/JPG/PolyNIPAM.jpg b/doc/src/JPG/PolyNIPAM.jpg index 4ad3ce8274..372a712de1 100644 Binary files a/doc/src/JPG/PolyNIPAM.jpg and b/doc/src/JPG/PolyNIPAM.jpg differ diff --git a/doc/src/JPG/butane.jpg b/doc/src/JPG/butane.jpg new file mode 100644 index 0000000000..41a9a9edd1 Binary files /dev/null and b/doc/src/JPG/butane.jpg differ diff --git a/doc/src/JPG/rhodo-both.jpg b/doc/src/JPG/rhodo-both.jpg new file mode 100644 index 0000000000..47cc863d8f Binary files /dev/null and b/doc/src/JPG/rhodo-both.jpg differ diff --git a/doc/src/Library.rst b/doc/src/Library.rst index 50c28b7fcd..e2021187c2 100644 --- a/doc/src/Library.rst +++ b/doc/src/Library.rst @@ -131,16 +131,15 @@ run LAMMPS in serial mode. .. _lammps_python_api: -LAMMPS Python APIs -================== +LAMMPS Python API +================= The LAMMPS Python module enables calling the LAMMPS C library API from Python by dynamically loading functions in the LAMMPS shared library through the `Python ctypes module `_. Because of the dynamic loading, it is **required** that LAMMPS is compiled in :ref:`"shared" mode `. The Python interface is object-oriented, but -otherwise tries to be very similar to the C library API. Three different -Python classes to run LAMMPS are available and they build on each other. +otherwise tries to be very similar to the C library API. More information on this is in the :doc:`Python_head` section of the manual. Use of the LAMMPS Python module is described in :doc:`Python_module`. diff --git a/doc/src/Library_add.rst b/doc/src/Library_add.rst index 8777ebbcad..e955422984 100644 --- a/doc/src/Library_add.rst +++ b/doc/src/Library_add.rst @@ -19,9 +19,9 @@ there are now a few requirements for including new changes or extensions. be added. - New features should also be implemented and documented not just for the C interface, but also the Python and Fortran interfaces. - - All additions should work and be compatible with ``-DLAMMPS_BIGBIG``, - ``-DLAMMPS_SMALLBIG``, ``-DLAMMPS_SMALLSMALL`` as well as when - compiling with and without MPI support. + - All additions should work and be compatible with + ``-DLAMMPS_BIGBIG``, ``-DLAMMPS_SMALLBIG`` as well as when compiling + with and without MPI support. - The ``library.h`` file should be kept compatible to C code at a level similar to C89. Its interfaces may not reference any custom data types (e.g. ``bigint``, ``tagint``, and so on) that diff --git a/doc/src/Library_execute.rst b/doc/src/Library_execute.rst index 44b601ba4c..8560fbb148 100644 --- a/doc/src/Library_execute.rst +++ b/doc/src/Library_execute.rst @@ -7,6 +7,7 @@ This section documents the following functions: - :cpp:func:`lammps_command` - :cpp:func:`lammps_commands_list` - :cpp:func:`lammps_commands_string` +- :cpp:func:`lammps_expand` -------------------- @@ -79,3 +80,8 @@ Below is a short example using some of these functions. .. doxygenfunction:: lammps_commands_string :project: progguide +----------------------- + +.. doxygenfunction:: lammps_expand + :project: progguide + diff --git a/doc/src/Library_objects.rst b/doc/src/Library_objects.rst index 7c0ca824d7..86b6d253f0 100644 --- a/doc/src/Library_objects.rst +++ b/doc/src/Library_objects.rst @@ -1,5 +1,5 @@ -Compute, fixes, variables -========================= +Computes, fixes, variables +========================== This section documents accessing or modifying data stored by computes, fixes, or variables in LAMMPS using the following functions: @@ -12,6 +12,10 @@ fixes, or variables in LAMMPS using the following functions: - :cpp:func:`lammps_set_string_variable` - :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` ----------------------- @@ -55,6 +59,26 @@ fixes, or variables in LAMMPS using the following functions: ----------------------- +.. doxygenfunction:: lammps_eval + :project: progguide + +----------------------- + +.. 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/Library_utility.rst b/doc/src/Library_utility.rst index e555b79c0b..b9cd568da9 100644 --- a/doc/src/Library_utility.rst +++ b/doc/src/Library_utility.rst @@ -20,6 +20,7 @@ functions. They do not directly call the LAMMPS library. - :cpp:func:`lammps_force_timeout` - :cpp:func:`lammps_has_error` - :cpp:func:`lammps_get_last_error_message` +- :cpp:func:`lammps_set_show_error` - :cpp:func:`lammps_python_api_version` The :cpp:func:`lammps_free` function is a clean-up function to free @@ -110,6 +111,11 @@ where such memory buffers were allocated that require the use of ----------------------- +.. doxygenfunction:: lammps_set_show_error + :project: progguide + +----------------------- + .. doxygenfunction:: lammps_python_api_version :project: progguide 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/Modify_requirements.rst b/doc/src/Modify_requirements.rst index cbcb3eca13..850fbf95c1 100644 --- a/doc/src/Modify_requirements.rst +++ b/doc/src/Modify_requirements.rst @@ -189,10 +189,8 @@ of the contribution. As of January 2023, all previously included Fortran code for the LAMMPS executable has been replaced by equivalent C++ code. -Python code must be compatible with Python 3.5 and later. Large parts -of LAMMPS (including the :ref:`PYTHON package `) are also -compatible with Python 2.7. Compatibility with Python 2.7 is desirable, -but compatibility with Python 3.5 is **required**. +Python code currently must be compatible with Python 3.6. If a later +version or Python is required, it needs to be documented. Compatibility with older programming language standards is very important to maintain portability and availability of LAMMPS on many @@ -208,20 +206,21 @@ Build system (strict) LAMMPS currently supports two build systems: one that is based on :doc:`traditional Makefiles ` and one that is based on -:doc:`CMake `. Therefore, your contribution must be -compatible with and support both build systems. +:doc:`CMake `. As of fall 2024, it is no longer required +to support the traditional make build system. New packages may choose +to only support building with CMake. Additions to existing packages +must follow the requirements set by that package. For a single pair of header and implementation files that are an independent feature, it is usually only required to add them to ``src/.gitignore``. For traditional make, if your contributed files or package depend on -other LAMMPS style files or packages also being installed -(e.g. because your file is a derived class from the other LAMMPS -class), then an ``Install.sh`` file is also needed to check for those -dependencies and modifications to ``src/Depend.sh`` to trigger the checks. -See other README and Install.sh files in other directories as -examples. +other LAMMPS style files or packages also being installed (e.g. because +your file is a derived class from the other LAMMPS class), then an +``Install.sh`` file is also needed to check for those dependencies and +modifications to ``src/Depend.sh`` to trigger the checks. See other +README and Install.sh files in other directories as examples. Similarly, for CMake support, changes may need to be made to ``cmake/CMakeLists.txt``, some of the files in ``cmake/presets``, and diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst index 894c299299..870dc8fbf7 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`` ---------- @@ -2427,7 +2428,7 @@ ways to use LAMMPS and Python together. Building with the PYTHON package assumes you have a Python development environment (headers and libraries) available on your system, which needs - to be either Python version 2.7 or Python 3.5 and later. + to be Python version 3.6 or later. **Install:** diff --git a/doc/src/Python_atoms.rst b/doc/src/Python_atoms.rst index f01559a524..2d07cc2326 100644 --- a/doc/src/Python_atoms.rst +++ b/doc/src/Python_atoms.rst @@ -2,14 +2,8 @@ Per-atom properties =================== Similar to what is described in :doc:`Library_atoms`, the instances of -:py:class:`lammps `, :py:class:`PyLammps `, or -:py:class:`IPyLammps ` can be used to extract atom quantities -and modify some of them. The main difference between the interfaces is how the information -is exposed. - -While the :py:class:`lammps ` is just a thin layer that wraps C API calls, -:py:class:`PyLammps ` and :py:class:`IPyLammps ` expose -information as objects and properties. +:py:class:`lammps ` can be used to extract atom quantities +and modify some of them. In some cases the data returned is a direct reference to the original data inside LAMMPS cast to ``ctypes`` pointers. Where possible, the wrappers will @@ -25,57 +19,41 @@ against invalid accesses. accordingly. These arrays can change sizes and order at every neighbor list rebuild and atom sort event as atoms are migrating between subdomains. -.. tabs:: +.. code-block:: python - .. tab:: lammps API + from lammps import lammps - .. code-block:: python + lmp = lammps() + lmp.file("in.sysinit") - from lammps import lammps - lmp = lammps() - lmp.file("in.sysinit") + # Read/Write access via ctypes + nlocal = lmp.extract_global("nlocal") + x = lmp.extract_atom("x") - nlocal = lmp.extract_global("nlocal") - x = lmp.extract_atom("x") + for i in range(nlocal): + print("(x,y,z) = (", x[i][0], x[i][1], x[i][2], ")") - for i in range(nlocal): - print("(x,y,z) = (", x[i][0], x[i][1], x[i][2], ")") + # Read/Write access via NumPy arrays + atom_id = L.numpy.extract_atom("id") + atom_type = L.numpy.extract_atom("type") + x = L.numpy.extract_atom("x") + v = L.numpy.extract_atom("v") + f = L.numpy.extract_atom("f") - lmp.close() + # set position in 2D simulation + x[0] = (1.0, 0.0) - **Methods**: + # set position in 3D simulation + x[0] = (1.0, 0.0, 1.) - * :py:meth:`extract_atom() `: extract a per-atom quantity + lmp.close() - **Numpy Methods**: - * :py:meth:`numpy.extract_atom() `: extract a per-atom quantity as numpy array +**Methods**: - .. tab:: PyLammps/IPyLammps API +* :py:meth:`extract_atom() `: extract a per-atom quantity - All atoms in the current simulation can be accessed by using the :py:attr:`PyLammps.atoms ` property. - Each element of this list is a :py:class:`Atom ` or :py:class:`Atom2D ` object. The attributes of - these objects provide access to their data (id, type, position, velocity, force, etc.): - - .. code-block:: python - - # access first atom - L.atoms[0].id - L.atoms[0].type - - # access second atom - L.atoms[1].position - L.atoms[1].velocity - L.atoms[1].force - - Some attributes can be changed: - - .. code-block:: python - - # set position in 2D simulation - L.atoms[0].position = (1.0, 0.0) - - # set position in 3D simulation - L.atoms[0].position = (1.0, 0.0, 1.0) +**Numpy Methods**: +* :py:meth:`numpy.extract_atom() `: extract a per-atom quantity as numpy array diff --git a/doc/src/Python_create.rst b/doc/src/Python_create.rst index 939aad2f32..9301829ea9 100644 --- a/doc/src/Python_create.rst +++ b/doc/src/Python_create.rst @@ -6,11 +6,10 @@ Creating or deleting a LAMMPS object ==================================== With the Python interface the creation of a :cpp:class:`LAMMPS -` instance is included in the constructors for the -:py:class:`lammps `, :py:class:`PyLammps `, -and :py:class:`IPyLammps ` classes. -Internally it will call either :cpp:func:`lammps_open` or :cpp:func:`lammps_open_no_mpi` from the C -library API to create the class instance. +` instance is included in the constructor for the +:py:class:`lammps ` class. Internally it will call either +:cpp:func:`lammps_open` or :cpp:func:`lammps_open_no_mpi` from the C library +API to create the class instance. All arguments are optional. The *name* argument allows loading a LAMMPS shared library that is named ``liblammps_machine.so`` instead of @@ -26,108 +25,25 @@ to run the Python module like the library interface on a subset of the MPI ranks after splitting the communicator. -Here are simple examples using all three Python interfaces: +Here is a simple example using the LAMMPS Python interface: -.. tabs:: +.. code-block:: python - .. tab:: lammps API + from lammps import lammps - .. code-block:: python + # NOTE: argv[0] is set by the lammps class constructor + args = ["-log", "none"] - from lammps import lammps + # create LAMMPS instance + lmp = lammps(cmdargs=args) - # NOTE: argv[0] is set by the lammps class constructor - args = ["-log", "none"] + # get and print numerical version code + print("LAMMPS Version: ", lmp.version()) - # create LAMMPS instance - lmp = lammps(cmdargs=args) + # explicitly close and delete LAMMPS instance (optional) + lmp.close() - # get and print numerical version code - print("LAMMPS Version: ", lmp.version()) - - # explicitly close and delete LAMMPS instance (optional) - lmp.close() - - .. tab:: PyLammps API - - The :py:class:`PyLammps ` class is a wrapper around the - :py:class:`lammps ` class and all of its lower level functions. - By default, it will create a new instance of :py:class:`lammps ` passing - along all arguments to the constructor of :py:class:`lammps `. - - .. code-block:: python - - from lammps import PyLammps - - # NOTE: argv[0] is set by the lammps class constructor - args = ["-log", "none"] - - # create LAMMPS instance - L = PyLammps(cmdargs=args) - - # get and print numerical version code - print("LAMMPS Version: ", L.version()) - - # explicitly close and delete LAMMPS instance (optional) - L.close() - - :py:class:`PyLammps ` objects can also be created on top of an existing - :py:class:`lammps ` object: - - .. code-block:: python - - from lammps import lammps, PyLammps - ... - # create LAMMPS instance - lmp = lammps(cmdargs=args) - - # create PyLammps instance using previously created LAMMPS instance - L = PyLammps(ptr=lmp) - - This is useful if you have to create the :py:class:`lammps ` - instance is a specific way, but want to take advantage of the - :py:class:`PyLammps ` interface. - - .. tab:: IPyLammps API - - The :py:class:`IPyLammps ` class is an extension of the - :py:class:`PyLammps ` class. It has the same construction behavior. By - default, it will create a new instance of :py:class:`lammps` passing - along all arguments to the constructor of :py:class:`lammps`. - - .. code-block:: python - - from lammps import IPyLammps - - # NOTE: argv[0] is set by the lammps class constructor - args = ["-log", "none"] - - # create LAMMPS instance - L = IPyLammps(cmdargs=args) - - # get and print numerical version code - print("LAMMPS Version: ", L.version()) - - # explicitly close and delete LAMMPS instance (optional) - L.close() - - You can also initialize IPyLammps on top of an existing :py:class:`lammps` or :py:class:`PyLammps` object: - - .. code-block:: python - - from lammps import lammps, IPyLammps - ... - # create LAMMPS instance - lmp = lammps(cmdargs=args) - - # create PyLammps instance using previously created LAMMPS instance - L = PyLammps(ptr=lmp) - - This is useful if you have to create the :py:class:`lammps ` - instance is a specific way, but want to take advantage of the - :py:class:`IPyLammps ` interface. - -In all of the above cases, same as with the :ref:`C library API `, this will use the +Same as with the :ref:`C library API `, this will use the ``MPI_COMM_WORLD`` communicator for the MPI library that LAMMPS was compiled with. diff --git a/doc/src/Python_execute.rst b/doc/src/Python_execute.rst index 01cf0e920f..a9d65133db 100644 --- a/doc/src/Python_execute.rst +++ b/doc/src/Python_execute.rst @@ -1,127 +1,123 @@ Executing commands ================== -Once an instance of the :py:class:`lammps `, -:py:class:`PyLammps `, or -:py:class:`IPyLammps ` class is created, there are +Once an instance of the :py:class:`lammps ` class is created, there are multiple ways to "feed" it commands. In a way that is not very different from running a LAMMPS input script, except that Python has many more facilities for structured programming than the LAMMPS input script syntax. Furthermore it is possible to "compute" what the next LAMMPS command should be. -.. tabs:: +Same as in the equivalent :doc:`C library functions `, +commands can be read from a file, a single string, a list of strings and a +block of commands in a single multi-line string. They are processed under the +same boundary conditions as the C library counterparts. The example below +demonstrates the use of :py:func:`lammps.file()`, :py:func:`lammps.command()`, +:py:func:`lammps.commands_list()`, and :py:func:`lammps.commands_string()`: - .. tab:: lammps API +.. code-block:: python - Same as in the equivalent - :doc:`C library functions `, commands can be read from a file, a - single string, a list of strings and a block of commands in a single - multi-line string. They are processed under the same boundary conditions - as the C library counterparts. The example below demonstrates the use - of :py:func:`lammps.file()`, :py:func:`lammps.command()`, - :py:func:`lammps.commands_list()`, and :py:func:`lammps.commands_string()`: + from lammps import lammps + lmp = lammps() - .. code-block:: python + # read commands from file 'in.melt' + lmp.file('in.melt') - from lammps import lammps - lmp = lammps() + # issue a single command + lmp.command('variable zpos index 1.0') - # read commands from file 'in.melt' - lmp.file('in.melt') + # create 10 groups with 10 atoms each + cmds = [f"group g{i} id {10*i+1}:{10*(i+1)}" for i in range(10)] + lmp.commands_list(cmds) - # issue a single command - lmp.command('variable zpos index 1.0') + # run commands from a multi-line string + block = """ + clear + region box block 0 2 0 2 0 2 + create_box 1 box + create_atoms 1 single 1.0 1.0 ${zpos} + """ + lmp.commands_string(block) - # create 10 groups with 10 atoms each - cmds = ["group g{} id {}:{}".format(i,10*i+1,10*(i+1)) for i in range(10)] - lmp.commands_list(cmds) +For convenience, the :py:class:`lammps ` class also provides a +command wrapper ``cmd`` that turns any LAMMPS command into a regular function +call. - # run commands from a multi-line string - block = """ - clear - region box block 0 2 0 2 0 2 - create_box 1 box - create_atoms 1 single 1.0 1.0 ${zpos} - """ - lmp.commands_string(block) +For instance, the following LAMMPS command - .. tab:: PyLammps/IPyLammps API +.. code-block:: LAMMPS - Unlike the lammps API, the PyLammps/IPyLammps APIs allow running LAMMPS - commands by calling equivalent member functions of :py:class:`PyLammps ` - and :py:class:`IPyLammps ` instances. + region box block 0 10 0 5 -0.5 0.5 - For instance, the following LAMMPS command +would normally be executed with the following Python code: - .. code-block:: LAMMPS +.. code-block:: python - region box block 0 10 0 5 -0.5 0.5 + from lammps import lammps - can be executed using with the lammps API with the following Python code if ``lmp`` is an - instance of :py:class:`lammps `: + lmp = lammps() + lmp.command("region box block 0 10 0 5 -0.5 0.5") - .. code-block:: python +With the ``cmd`` wrapper, any LAMMPS command can be split up into arbitrary parts. +These parts are then passed to a member function with the name of the :doc:`command `. +For the :doc:`region ` command that means the :code:`region()` method can be called. +The arguments of the command can be passed as one string, or +individually. - from lammps import lammps +.. code-block:: python - lmp = lammps() - lmp.command("region box block 0 10 0 5 -0.5 0.5") + from lammps import lammps - With the PyLammps interface, any LAMMPS command can be split up into arbitrary parts. - These parts are then passed to a member function with the name of the :doc:`command `. - For the :doc:`region ` command that means the :code:`region()` method can be called. - The arguments of the command can be passed as one string, or - individually. + L = lammps() - .. code-block:: python + # pass command parameters as one string + L.cmd.region("box block 0 10 0 5 -0.5 0.5") - from lammps import PyLammps + # OR pass them individually + L.cmd.region("box block", 0, 10, 0, 5, -0.5, 0.5) - L = PyLammps() +In the latter example, all parameters except the first are Python floating-point literals. The +member function takes the entire parameter list and transparently merges it to a single command +string. - # pass command parameters as one string - L.region("box block 0 10 0 5 -0.5 0.5") +The benefit of this approach is avoiding redundant command calls and easier +parameterization. With `command`, `commands_list`, and `commands_string` the +parameterization needed to be done manually by creating formatted command +strings. - # OR pass them individually - L.region("box block", 0, 10, 0, 5, -0.5, 0.5) +.. code-block:: python - In the latter example, all parameters except the first are Python floating-point literals. The - member function takes the entire parameter list and transparently merges it to a single command - string. + lmp.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi)) - The benefit of this approach is avoiding redundant command calls and easier - parameterization. In the lammps API parameterization needed to be done - manually by creating formatted command strings. +In contrast, methods of the `cmd` wrapper accept parameters directly and will convert +them automatically to a final command string. - .. code-block:: python +.. code-block:: python - lmp.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi)) + L.cmd.region("box block", xlo, xhi, ylo, yhi, zlo, zhi) - In contrast, methods of PyLammps accept parameters directly and will convert - them automatically to a final command string. +.. note:: - .. code-block:: python + When running in IPython you can use Tab-completion after ``L.cmd.`` to see + all available LAMMPS commands. - L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi) +Using these facilities, the previous example shown above can be rewritten as follows: - Using these facilities, the example shown for the lammps API can be rewritten as follows: +.. code-block:: python - .. code-block:: python + from lammps import lammps + L = lammps() - from lammps import PyLammps - L = PyLammps() + # read commands from file 'in.melt' + L.file('in.melt') - # read commands from file 'in.melt' - L.file('in.melt') + # issue a single command + L.cmd.variable('zpos', 'index', 1.0) - # issue a single command - L.variable('zpos', 'index', 1.0) + # create 10 groups with 10 atoms each + for i in range(10): + L.cmd.group(f"g{i}", "id", f"{10*i+1}:{10*(i+1)}") - # create 10 groups with 10 atoms each - for i in range(10): - L.group(f"g{i}", "id", f"{10*i+1}:{10*(i+1)}") - - L.clear() - L.region("box block", 0, 2, 0, 2, 0, 2) - L.create_box(1, "box") - L.create_atoms(1, "single", 1.0, 1.0, "${zpos}") + L.cmd.clear() + L.cmd.region("box block", 0, 2, 0, 2, 0, 2) + L.cmd.create_box(1, "box") + L.cmd.create_atoms(1, "single", 1.0, 1.0, "${zpos}") diff --git a/doc/src/Python_head.rst b/doc/src/Python_head.rst index 3aab3a0d4b..28b6f3d1d4 100644 --- a/doc/src/Python_head.rst +++ b/doc/src/Python_head.rst @@ -15,6 +15,7 @@ together. Python_call Python_formats Python_examples + Python_jupyter Python_error Python_trouble diff --git a/doc/src/Python_install.rst b/doc/src/Python_install.rst index 01610b84f0..1bb0768d62 100644 --- a/doc/src/Python_install.rst +++ b/doc/src/Python_install.rst @@ -7,6 +7,10 @@ LAMMPS shared library through the Python `ctypes `_ module. Because of the dynamic loading, it is required that LAMMPS is compiled in :ref:`"shared" mode `. +.. versionchanged:: TBD + +LAMMPS currently only supports Python version 3.6 or later. + Two components are necessary for Python to be able to invoke LAMMPS code: * The LAMMPS Python Package (``lammps``) from the ``python`` folder @@ -106,13 +110,16 @@ folder that the dynamic loader searches or inside of the installed .. code-block:: bash - python install.py -p -l -v [-n] + python install.py -p -l -v [-n] [-f] * The ``-p`` flag points to the ``lammps`` Python package folder to be installed, * the ``-l`` flag points to the LAMMPS shared library file to be installed, * the ``-v`` flag points to the LAMMPS version header file to extract the version date, - * and the optional ``-n`` instructs the script to only build a wheel file - but not attempt to install it. + * the optional ``-n`` instructs the script to only build a wheel file but not attempt + to install it, + * and the optional ``-f`` argument instructs the script to force installation even if + pip would otherwise refuse installation with an + :ref:`error about externally managed environments `. .. tab:: Virtual environment @@ -136,11 +143,6 @@ folder that the dynamic loader searches or inside of the installed # create virtual environment in folder $HOME/myenv python3 -m venv $HOME/myenv - For Python versions prior 3.3 you can use `virtualenv - `_ - command instead of "python3 -m venv". This step has to be done - only once. - To activate the virtual environment type: .. code-block:: bash @@ -199,6 +201,10 @@ folder that the dynamic loader searches or inside of the installed The ``PYTHONPATH`` needs to point to the parent folder that contains the ``lammps`` package! +In case you run into an "externally-managed-environment" error when +trying to install the LAMMPS Python module, please refer to +:ref:`corresponding paragraph ` in the Python HOWTO +page to learn about options for handling this error. To verify if LAMMPS can be successfully started from Python, start the Python interpreter, load the ``lammps`` Python module and create a @@ -245,14 +251,14 @@ make MPI calls directly from Python in your script, if you desire. We have tested this with `MPI for Python `_ (aka mpi4py) and you will find installation instruction for it below. -Installation of mpi4py (version 3.0.3 as of Sep 2020) can be done as +Installation of mpi4py (version 4.0.1 as of Feb 2025) can be done as follows: - Via ``pip`` into a local user folder with: .. code-block:: bash - pip install --user mpi4py + python3 -m pip install --user mpi4py - Via ``dnf`` into a system folder for RedHat/Fedora systems: @@ -261,20 +267,20 @@ follows: # for use with OpenMPI sudo dnf install python3-mpi4py-openmpi # for use with MPICH - sudo dnf install python3-mpi4py-openmpi + sudo dnf install python3-mpi4py-mpich - Via ``pip`` into a virtual environment (see above): .. code-block:: console $ source $HOME/myenv/activate - (myenv)$ pip install mpi4py + (myenv)$ python -m pip install mpi4py - Via ``pip`` into a system folder (not recommended): .. code-block:: bash - sudo pip install mpi4py + sudo python3 -m pip install mpi4py For more detailed installation instructions and additional options, please see the `mpi4py installation `_ page. diff --git a/doc/src/Python_jupyter.rst b/doc/src/Python_jupyter.rst new file mode 100644 index 0000000000..9e9a1c917e --- /dev/null +++ b/doc/src/Python_jupyter.rst @@ -0,0 +1,45 @@ +Using LAMMPS in IPython notebooks and Jupyter +============================================= + +If the LAMMPS Python package is installed for the same Python interpreter as +`IPython `_, you can use LAMMPS directly inside of an IPython notebook inside of +Jupyter. `Jupyter `_ is a powerful integrated development environment (IDE) for +many dynamic languages like Python, Julia and others, which operates inside of +any web browser. Besides auto-completion and syntax highlighting it allows you +to create formatted documents using Markup, mathematical formulas, graphics and +animations intermixed with executable Python code. It is a great format for +tutorials and showcasing your latest research. + +The easiest way to install it is via ``pip``: + +.. code-block:: bash + + pip install --user jupyter + +To launch an instance of Jupyter simply run the following command inside your +Python environment: + +.. code-block:: bash + + jupyter notebook + +Interactive Python Examples +--------------------------- + +Examples of IPython notebooks can be found in the ``python/examples/ipython`` +subdirectory. They require LAMMPS to be compiled as shared library with PYTHON, +PNG, JPEG and FFMPEG support. + +To open these notebooks launch ``jupyter notebook index.ipynb`` inside this +directory. The opened file provides an overview of the available examples. + +- Example 1: Using LAMMPS with Python (``simple.ipynb``) +- Example 2: Analyzing LAMMPS thermodynamic data (``thermo.ipynb``) +- Example 3: Working with Per-Atom Data (``atoms.ipynb``) +- Example 4: Working with LAMMPS variables (``variables.ipynb``) +- Example 5: Validating a dihedral potential (``dihedrals/dihedral.ipynb``) +- Example 6: Running a Monte Carlo relaxation (``montecarlo/mc.ipynb``) + +.. note:: + + Typically clicking a link in Jupyter will open a new tab, which might be blocked by your pop-up blocker. diff --git a/doc/src/Python_module.rst b/doc/src/Python_module.rst index c19d4b0345..30e585d143 100644 --- a/doc/src/Python_module.rst +++ b/doc/src/Python_module.rst @@ -10,19 +10,11 @@ be installed into a Python system folder or a user folder with ``make install-python``. Components of the module can then loaded into a Python session with the ``import`` command. -There are multiple Python interface classes in the :py:mod:`lammps` module: +.. warning:: -- the :py:class:`lammps ` class. This is a wrapper around - the C-library interface and its member functions try to replicate the - :ref:`C-library API ` closely. This is the most - feature-complete Python API. -- the :py:class:`PyLammps ` class. This is a more high-level - and more Python style class implemented on top of the - :py:class:`lammps ` class. -- the :py:class:`IPyLammps ` class is derived from - :py:class:`PyLammps ` and adds embedded graphics - features to conveniently include LAMMPS into `Jupyter - `_ notebooks. + Alternative interfaces such as :py:class:`PyLammps ` and + :py:class:`IPyLammps ` classes have been deprecated and + will be removed in a future version of LAMMPS. .. _mpi4py_url: https://mpi4py.readthedocs.io @@ -49,7 +41,7 @@ The ``lammps`` class API ======================== The :py:class:`lammps ` class is the core of the LAMMPS -Python interfaces. It is a wrapper around the :ref:`LAMMPS C library +Python interface. It is a wrapper around the :ref:`LAMMPS C library API ` using the `Python ctypes module `_ and a shared library compiled from the LAMMPS sources code. The individual methods in this @@ -64,40 +56,7 @@ functions. Below is a detailed documentation of the API. .. autoclass:: lammps.numpy_wrapper::numpy_wrapper :members: ----------- - -The ``PyLammps`` class API -========================== - -The :py:class:`PyLammps ` class is a wrapper that creates a -simpler, more "Pythonic" interface to common LAMMPS functionality. LAMMPS -data structures are exposed through objects and properties. This makes Python -scripts shorter and more concise. See the :doc:`PyLammps Tutorial -` for an introduction on how to use this interface. - -.. autoclass:: lammps.PyLammps - :members: - -.. autoclass:: lammps.AtomList - :members: - -.. autoclass:: lammps.Atom - :members: - -.. autoclass:: lammps.Atom2D - :members: - ----------- - -The ``IPyLammps`` class API -=========================== - -The :py:class:`IPyLammps ` class is an extension of -:py:class:`PyLammps `, adding additional functions to -quickly display visualizations such as images and videos inside of IPython. -See the :doc:`PyLammps Tutorial ` for examples. - -.. autoclass:: lammps.IPyLammps +.. autoclass:: lammps.ipython::wrapper :members: ---------- diff --git a/doc/src/Python_objects.rst b/doc/src/Python_objects.rst index 6e3a329a27..c3002ec5e6 100644 --- a/doc/src/Python_objects.rst +++ b/doc/src/Python_objects.rst @@ -4,95 +4,52 @@ Compute, fixes, variables This section documents accessing or modifying data from objects like computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module. -.. tabs:: +For :py:meth:`lammps.extract_compute() ` and +:py:meth:`lammps.extract_fix() `, the global, per-atom, +or local data calculated by the compute or fix can be accessed. What is returned +depends on whether the compute or fix calculates a scalar or vector or array. +For a scalar, a single double value is returned. If the compute or fix calculates +a vector or array, a pointer to the internal LAMMPS data is returned, which you can +use via normal Python subscripting. - .. tab:: lammps API +The one exception is that for a fix that calculates a +global vector or array, a single double value from the vector or array +is returned, indexed by I (vector) or I and J (array). I,J are +zero-based indices. +See the :doc:`Howto output ` page for a discussion of +global, per-atom, and local data, and of scalar, vector, and array +data types. See the doc pages for individual :doc:`computes ` +and :doc:`fixes ` for a description of what they calculate and +store. - For :py:meth:`lammps.extract_compute() ` and - :py:meth:`lammps.extract_fix() `, the global, per-atom, - or local data calculated by the compute or fix can be accessed. What is returned - depends on whether the compute or fix calculates a scalar or vector or array. - For a scalar, a single double value is returned. If the compute or fix calculates - a vector or array, a pointer to the internal LAMMPS data is returned, which you can - use via normal Python subscripting. +For :py:meth:`lammps.extract_variable() `, +an :doc:`equal-style or atom-style variable ` is evaluated and +its result returned. - The one exception is that for a fix that calculates a - global vector or array, a single double value from the vector or array - is returned, indexed by I (vector) or I and J (array). I,J are - zero-based indices. - See the :doc:`Howto output ` page for a discussion of - global, per-atom, and local data, and of scalar, vector, and array - data types. See the doc pages for individual :doc:`computes ` - and :doc:`fixes ` for a description of what they calculate and - store. +For equal-style variables a single ``c_double`` value is returned and the +group argument is ignored. For atom-style variables, a vector of +``c_double`` is returned, one value per atom, which you can use via normal +Python subscripting. The values will be zero for atoms not in the +specified group. - For :py:meth:`lammps.extract_variable() `, - an :doc:`equal-style or atom-style variable ` is evaluated and - its result returned. +:py:meth:`lammps.numpy.extract_compute() `, +:py:meth:`lammps.numpy.extract_fix() `, and +:py:meth:`lammps.numpy.extract_variable() ` are +equivalent NumPy implementations that return NumPy arrays instead of ``ctypes`` pointers. - For equal-style variables a single ``c_double`` value is returned and the - group argument is ignored. For atom-style variables, a vector of - ``c_double`` is returned, one value per atom, which you can use via normal - Python subscripting. The values will be zero for atoms not in the - specified group. +The :py:meth:`lammps.set_variable() ` method sets an +existing string-style variable to a new string value, so that subsequent LAMMPS +commands can access the variable. - :py:meth:`lammps.numpy.extract_compute() `, - :py:meth:`lammps.numpy.extract_fix() `, and - :py:meth:`lammps.numpy.extract_variable() ` are - equivalent NumPy implementations that return NumPy arrays instead of ``ctypes`` pointers. +**Methods**: - The :py:meth:`lammps.set_variable() ` method sets an - existing string-style variable to a new string value, so that subsequent LAMMPS - commands can access the variable. +* :py:meth:`lammps.extract_compute() `: extract value(s) from a compute +* :py:meth:`lammps.extract_fix() `: extract value(s) from a fix +* :py:meth:`lammps.extract_variable() `: extract value(s) from a variable +* :py:meth:`lammps.set_variable() `: set existing named string-style variable to value - **Methods**: +**NumPy Methods**: - * :py:meth:`lammps.extract_compute() `: extract value(s) from a compute - * :py:meth:`lammps.extract_fix() `: extract value(s) from a fix - * :py:meth:`lammps.extract_variable() `: extract value(s) from a variable - * :py:meth:`lammps.set_variable() `: set existing named string-style variable to value - - **NumPy Methods**: - - * :py:meth:`lammps.numpy.extract_compute() `: extract value(s) from a compute, return arrays as numpy arrays - * :py:meth:`lammps.numpy.extract_fix() `: extract value(s) from a fix, return arrays as numpy arrays - * :py:meth:`lammps.numpy.extract_variable() `: extract value(s) from a variable, return arrays as numpy arrays - - - .. tab:: PyLammps/IPyLammps API - - PyLammps and IPyLammps classes currently do not add any additional ways of - retrieving information out of computes and fixes. This information can still be accessed by using the lammps API: - - .. code-block:: python - - L.lmp.extract_compute(...) - L.lmp.extract_fix(...) - # OR - L.lmp.numpy.extract_compute(...) - L.lmp.numpy.extract_fix(...) - - LAMMPS variables can be both defined and accessed via the :py:class:`PyLammps ` interface. - - To define a variable you can use the :doc:`variable ` command: - - .. code-block:: python - - L.variable("a index 2") - - A dictionary of all variables is returned by the :py:attr:`PyLammps.variables ` property: - - you can access an individual variable by retrieving a variable object from the - ``L.variables`` dictionary by name - - .. code-block:: python - - a = L.variables['a'] - - The variable value can then be easily read and written by accessing the value - property of this object. - - .. code-block:: python - - print(a.value) - a.value = 4 +* :py:meth:`lammps.numpy.extract_compute() `: extract value(s) from a compute, return arrays as numpy arrays +* :py:meth:`lammps.numpy.extract_fix() `: extract value(s) from a fix, return arrays as numpy arrays +* :py:meth:`lammps.numpy.extract_variable() `: extract value(s) from a variable, return arrays as numpy arrays diff --git a/doc/src/Python_overview.rst b/doc/src/Python_overview.rst index a13da0d512..57b9ee6145 100644 --- a/doc/src/Python_overview.rst +++ b/doc/src/Python_overview.rst @@ -44,19 +44,15 @@ Below is an example output for Python version 3.8.5. .. warning:: The options described in this section of the manual for using Python - with LAMMPS currently support either Python 2 or 3. Specifically - version 2.7 or later and 3.6 or later. Since the Python community no - longer maintains Python 2 (see `this notice - `_), we recommend use of - Python 3 with LAMMPS. While Python 2 code should continue to work, - that is not something we can guarantee long-term. If you notice - Python code in the LAMMPS distribution that is not compatible with - Python 3, please contact the LAMMPS developers or submit `and issue - on GitHub `_ + with LAMMPS support only Python 3.6 or later. For use with Python + 2.x you will need to use an older LAMMPS version like 29 Aug 2024 + or older. If you notice Python code in the LAMMPS distribution that + is not compatible with Python 3, please contact the LAMMPS developers + or submit `and issue on GitHub `_ --------- -LAMMPS can work together with Python in three ways. First, Python can +LAMMPS can work together with Python in two ways. First, Python can wrap LAMMPS through the its :doc:`library interface `, so that a Python script can create one or more instances of LAMMPS and launch one or more simulations. In Python terms, this is referred to as @@ -67,22 +63,7 @@ launch one or more simulations. In Python terms, this is referred to as Launching LAMMPS via Python - -Second, the lower-level Python interface in the :py:class:`lammps Python -class ` can be used indirectly through the provided -:py:class:`PyLammps ` and :py:class:`IPyLammps -` wrapper classes, also written in Python. These -wrappers try to simplify the usage of LAMMPS in Python by providing a -more object-based interface to common LAMMPS functionality. They also -reduce the amount of code necessary to parameterize LAMMPS scripts -through Python and make variables and computes directly accessible. - -.. figure:: JPG/pylammps-invoke-lammps.png - :figclass: align-center - - Using the PyLammps / IPyLammps wrappers - -Third, LAMMPS can use the Python interpreter, so that a LAMMPS input +Second, LAMMPS can use the Python interpreter, so that a LAMMPS input script or styles can invoke Python code directly, and pass information back-and-forth between the input script and Python functions you write. This Python code can also call back to LAMMPS to query or change its diff --git a/doc/src/Python_properties.rst b/doc/src/Python_properties.rst index 031461660a..25040ad5bd 100644 --- a/doc/src/Python_properties.rst +++ b/doc/src/Python_properties.rst @@ -2,14 +2,8 @@ System properties ================= Similar to what is described in :doc:`Library_properties`, the instances of -:py:class:`lammps `, :py:class:`PyLammps `, or -:py:class:`IPyLammps ` can be used to extract different kinds -of information about the active LAMMPS instance and also to modify some of it. The -main difference between the interfaces is how the information is exposed. - -While the :py:class:`lammps ` is just a thin layer that wraps C API calls, -:py:class:`PyLammps ` and :py:class:`IPyLammps ` expose -information as objects and properties. +:py:class:`lammps ` can be used to extract different kinds +of information about the active LAMMPS instance and also to modify some of it. In some cases the data returned is a direct reference to the original data inside LAMMPS cast to ``ctypes`` pointers. Where possible, the wrappers will @@ -25,113 +19,38 @@ against invalid accesses. accordingly. These arrays can change sizes and order at every neighbor list rebuild and atom sort event as atoms are migrating between subdomains. -.. tabs:: +.. code-block:: python - .. tab:: lammps API + from lammps import lammps - .. code-block:: python + lmp = lammps() + lmp.file("in.sysinit") - from lammps import lammps + natoms = lmp.get_natoms() + print(f"running simulation with {natoms} atoms") - lmp = lammps() - lmp.file("in.sysinit") + lmp.command("run 1000 post no"); - natoms = lmp.get_natoms() - print(f"running simulation with {natoms} atoms") + for i in range(10): + lmp.command("run 100 pre no post no") + pe = lmp.get_thermo("pe") + ke = lmp.get_thermo("ke") + print(f"PE = {pe}\nKE = {ke}") - lmp.command("run 1000 post no"); + lmp.close() - for i in range(10): - lmp.command("run 100 pre no post no") - pe = lmp.get_thermo("pe") - ke = lmp.get_thermo("ke") - print(f"PE = {pe}\nKE = {ke}") +**Methods**: - lmp.close() +* :py:meth:`version() `: return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902 +* :py:meth:`get_thermo() `: return current value of a thermo keyword +* :py:meth:`last_thermo() `: return a dictionary of the last thermodynamic output +* :py:meth:`get_natoms() `: total # of atoms as int +* :py:meth:`reset_box() `: reset the simulation box size +* :py:meth:`extract_setting() `: return a global setting +* :py:meth:`extract_global() `: extract a global quantity +* :py:meth:`extract_box() `: extract box info +* :py:meth:`create_atoms() `: create N atoms with IDs, types, x, v, and image flags - **Methods**: +**Properties**: - * :py:meth:`version() `: return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902 - * :py:meth:`get_thermo() `: return current value of a thermo keyword - * :py:meth:`last_thermo() `: return a dictionary of the last thermodynamic output - * :py:meth:`get_natoms() `: total # of atoms as int - * :py:meth:`reset_box() `: reset the simulation box size - * :py:meth:`extract_setting() `: return a global setting - * :py:meth:`extract_global() `: extract a global quantity - * :py:meth:`extract_box() `: extract box info - * :py:meth:`create_atoms() `: create N atoms with IDs, types, x, v, and image flags - - **Properties**: - - * :py:attr:`last_thermo_step `: the last timestep thermodynamic output was computed - - .. tab:: PyLammps/IPyLammps API - - In addition to the functions provided by :py:class:`lammps `, :py:class:`PyLammps ` objects - have several properties which allow you to query the system state: - - L.system - Is a dictionary describing the system such as the bounding box or number of atoms - - L.system.xlo, L.system.xhi - bounding box limits along x-axis - - L.system.ylo, L.system.yhi - bounding box limits along y-axis - - L.system.zlo, L.system.zhi - bounding box limits along z-axis - - L.communication - configuration of communication subsystem, such as the number of threads or processors - - L.communication.nthreads - number of threads used by each LAMMPS process - - L.communication.nprocs - number of MPI processes used by LAMMPS - - L.fixes - List of fixes in the current system - - L.computes - List of active computes in the current system - - L.dump - List of active dumps in the current system - - L.groups - List of groups present in the current system - - **Retrieving the value of an arbitrary LAMMPS expressions** - - LAMMPS expressions can be immediately evaluated by using the ``eval`` method. The - passed string parameter can be any expression containing global :doc:`thermo` values, - variables, compute or fix data (see :doc:`Howto_output`): - - - .. code-block:: python - - result = L.eval("ke") # kinetic energy - result = L.eval("pe") # potential energy - - result = L.eval("v_t/2.0") - - **Example** - - .. code-block:: python - - from lammps import PyLammps - - L = PyLammps() - L.file("in.sysinit") - - print(f"running simulation with {L.system.natoms} atoms") - - L.run(1000, "post no"); - - for i in range(10): - L.run(100, "pre no post no") - pe = L.eval("pe") - ke = L.eval("ke") - print(f"PE = {pe}\nKE = {ke}") +* :py:attr:`last_thermo_step `: the last timestep thermodynamic output was computed diff --git a/doc/src/Run_formats.rst b/doc/src/Run_formats.rst new file mode 100644 index 0000000000..d03227f091 --- /dev/null +++ b/doc/src/Run_formats.rst @@ -0,0 +1,416 @@ + +File formats used by LAMMPS +=========================== + +This page provides a general overview of the kinds of files and file +formats that LAMMPS is reading and writing. + +.. contents:: On this page + :depth: 2 + :backlinks: top + +------------------- + +Character Encoding +^^^^^^^^^^^^^^^^^^ + +For processing text files, the LAMMPS source code assumes `ASCII +character encoding `_ which +represents the digits 0 to 9, the lower and upper case letters a to z, +some common punctuation and other symbols and a few whitespace +characters including a regular "space character", "line feed", "carriage +return", "tabulator". These characters are all represented by single +bytes with a value smaller than 128 and only 95 of those 128 values +represent printable characters. This list is sufficient to represent +most English text, but misses accented characters or umlauts or Greek +symbols and more. + +Modern text often uses `UTF-8 character encoding +`_ instead. This encoding is a way +to represent many more different characters as defined by the Unicode +standard. UFT-8 is compatible with ASCII, since the first 128 values +are identical with the ASCII encoding. It is important to note, +however, that there are Unicode characters that *look* similar to ASCII +characters, but have a different binary representation. As a general +rule, these characters may not be correctly recognized by LAMMPS. For +some parts of LAMMPS' text processing, translation tables with known +"lookalike" characters are used. The tables are used to substitute +non-ASCII characters with their ASCII equivalents. Non-ASCII lookalike +characters are often used by web browsers or PDF viewers to improve the +readability of text. Thus, when using copy and paste to transfer text +from such an application to your input file, you may unintentionally +create text that is not exclusively using ASCII encoding and may cause +errors when LAMMPS is trying to read it. + +Lines with non-printable and non-ASCII characters in text files can be +detected for example with a (Linux) command like the following: + +.. code-block:: bash + + env LC_ALL=C grep -n '[^ -~]' some_file.txt + +Number Formatting +^^^^^^^^^^^^^^^^^ + +Different countries and languages have different conventions to format +numbers. While in some regions commas are used for fractions and points +to indicate thousand, million and so on, this is reversed in other +regions. Modern operating systems have facilities to adjust input and +output accordingly that are collectively referred to as "native language +support" (NLS). The exact rules are often applied according to the +value of the ``$LANG`` environment variable (e.g. "en_US.utf8" for +English text in UTF-8 encoding). + +For the sake of simplicity of the implementation and transferability of +results, LAMMPS does not support this and instead expects numbers being +formatted in the generic or "C" locale. The "C" locale has no +punctuation for thousand, million and so on and uses a decimal point for +fractions. One thousand would be represented as "1000.0" and not as +"1,000.0" nor as "1.000,0". Having native language support enabled for +a locale other than "C" will result in different behavior when +converting or formatting numbers that can trigger unexpected errors. + +LAMMPS also only accepts integer numbers when an integer is required, so +using floating point equivalents like "1.0" are not accepted; you *must* +use "1" instead. + +For floating point numbers in scientific notation, the Fortran double +precision notation "1.1d3" is not accepted; you have to use "1100", +"1100.0" or "1.1e3". + +Input file +^^^^^^^^^^ + +A LAMMPS input file is a text file with commands. It is read +line-by-line and each line is processed *immediately*. Before looking +for commands and executing them, there is a pre-processing step where +comments (non-quoted text starting with a pound sign '#') are removed, +``${variable}`` and ``$(expression)`` constructs are expanded or +evaluated, and lines that end in the ampersand character '&' are +combined with the next line (similar to Fortran 90 free-format source +code). After the pre-processing, lines are split into "words" and +evaluated. The first word must be a :doc:`command ` and +all following words are arguments. Below are some example lines: + +.. code-block:: LAMMPS + + # full line comment + + # some global settings + units lj + atom_style atomic + # ^^ command ^^ argument(s) + + variable x index 1 # may be overridden from command line with -var x + variable xx equal 20*$x # variable "xx" is always 20 times "x" + + lattice fcc 0.8442 + + # example of a command written across multiple lines + # the "region" command uses spacing from "lattice" command, unless "units box" is specified + region box block 0.0 ${xx} & + 0.0 40.0 & + 0.0 30.0 + # create simulation box and fill with atoms according to lattice setting + create_box 1 box + create_atoms 1 box + + # set force field and parameters + mass 1 1.0 + pair_style lj/cut 2.5 + pair_coeff 1 1 1.0 1.0 2.5 + + # run simulation + fix 1 all nve + run 1000 + +The pivotal command in this example input is the :doc:`create_box +command `. It defines the simulation system and many +parameters that go with it: units, atom style, number of atom types (and +other types) and more. Those settings are *locked in* after the box is +created. Commands that change these kind of settings are only allowed +**before** a simulation box is created and many other commands are only +allowed **after** the simulation box is defined (e.g. :doc:`pair_coeff +`). Very few commands (e.g. :doc:`pair_style `) +may be used in either part of the input. The :doc:`read_data +` and :doc:`read_restart ` commands also create +the system box and thus have a similar pivotal function. + +The LAMMPS input syntax has minimal support for conditionals and loops, +but if more complex operations are required, it is recommended to use +the library interface, e.g. :doc:`from Python using the LAMMPS Python +module `. + +There is a frequent misconception about the :doc:`if command `: +this is a command for conditional execution **outside** a run or +minimization. To trigger actions on specific conditions **during** +a run is a non-trivial operation that usually requires adopting one +of the available "fix" commands or creating a new "fix" command. + +LAMMPS commands change the internal state and thus the order of commands +matters and reordering them can produce different results. For example, +the region defined by the :doc:`region command ` in the example +above depends on the :doc:`lattice setting ` and thus its +dimensions will be different depending on the order of the two commands. + +Each line must have an "end-of-line" character (line feed or carriage +return plus line feed). Some text editors do not automatically insert +one which may cause LAMMPS to ignore the last command. It is thus +recommended to always have an empty line at the end of an input file. + +The specific details describing how LAMMPS input is processed and parsed +are explained in :doc:`Commands_parse`. + +Data file +^^^^^^^^^ + +A LAMMPS data file contains a description of a system suitable for +reading with the :doc:`read_data command `. Data files are +commonly used for setting up complex molecular systems that can be +difficult to achieve with the commands :doc:`create_box ` +and :doc:`create_atoms ` alone. Also, data files can be +used as a portable alternatives to a :doc:`binary restart file +`. A restart file can be converted into a data file from the +:doc:`command line `. + +Data files have a header section at the very beginning of the file and +multiple titled sections such as "Atoms", Masses", "Pair Coeffs", and so +on. Header keywords can only be used *before* the first title section. + +The data file **always** starts with a "title" line, which will be +**ignored** by LAMMPS. Omitting the title line can lead to unexpected +behavior because a line of the header with an actual setting may be +ignored. In this case, the mistakenly ignored line often contains the +"atoms" keyword, which results in LAMMPS assuming that there are no +atoms in the data file and thus throwing an error on the contents of the +"Atoms" section. The title line may contain some keywords that can be +used by external programs to convey information about the system +(included as comments), that is not required and not read by LAMMPS. + +The line following a section title is also **ignored**. An error will +occur if an empty line is not placed after a section title. The number +of lines in titled sections depends on header keywords, like the number +of atom types, the number of atoms, the number of bond types, the number +of bonds, and so on. The data in those sections has to be complete. A +special case are the "Pair Coeffs" and "PairIJ Coeffs" sections; the +former is for force fields and pair styles that use mixing of non-bonded +potential parameters, the latter for pair styles and force fields +requiring explicit coefficients. Thus with *N* being the number of atom +types, the "Pair Coeffs" section has *N* entries while "PairIJ Coeffs" +has :math:`N \cdot (N-1)` entries. Internally, these sections will be +converted to :doc:`pair_coeff ` commands. Thus the +corresponding :doc:`pair style ` must have been set *before* +the :doc:`read_data command ` reads the data file. + +Data files may contain comments, which start with the pound sign '#'. +There must be at least one blank between a valid keyword and the pound +sign. Below is a simple example case of a data file for :doc:`atom style +full `. + +.. code-block:: bash + + LAMMPS Title line (ignored) + # full line comment + + 10 atoms # comment + 4 atom types + + -36.840194 64.211560 xlo xhi + -41.013691 68.385058 ylo yhi + -29.768095 57.139462 zlo zhi + + Masses + + 1 12.0110 + 2 12.0110 + 3 15.9990 + 4 1.0080 + + Pair Coeffs # this section is optional + + 1 0.110000 3.563595 0.110000 3.563595 + 2 0.080000 3.670503 0.010000 3.385415 + 3 0.120000 3.029056 0.120000 2.494516 + 4 0.022000 2.351973 0.022000 2.351973 + + Atoms # full + + 1 1 1 0.560 43.99993 58.52678 36.78550 0 0 0 + 2 1 2 -0.270 45.10395 58.23499 35.86693 0 0 0 + 3 1 3 -0.510 43.81519 59.54928 37.43995 0 0 0 + 4 1 4 0.090 45.71714 57.34797 36.13434 0 0 0 + 5 1 4 0.090 45.72261 59.13657 35.67007 0 0 0 + 6 1 4 0.090 44.66624 58.09539 34.85538 0 0 0 + 7 1 3 -0.470 43.28193 57.47427 36.91953 0 0 0 + 8 1 4 0.070 42.07157 57.45486 37.62418 0 0 0 + 9 1 1 0.510 42.19985 57.57789 39.12163 0 0 0 + 10 1 1 0.510 41.88641 58.62251 39.70398 0 0 0 + # ^^atomID ^^molID ^^type ^^charge ^^xcoord ^^ycoord ^^ycoord ^^image^^flags (optional) + + Velocities # this section is optional + + 1 0.0050731 -0.00398928 0.00391473 + 2 -0.0175184 0.0173484 -0.00489207 + 3 0.00597225 -0.00202006 0.00166454 + 4 -0.010395 -0.0082582 0.00316419 + 5 -0.00390877 0.00470331 -0.00226911 + 6 -0.00111157 -0.00374545 -0.0169374 + 7 0.00209054 -0.00594936 -0.000124563 + 8 0.00635002 -0.0120093 -0.0110999 + 9 -0.004955 -0.0123375 0.000403422 + 10 0.00265028 -0.00189329 -0.00293198 + +The common problem is processing the "Atoms" section, since its format +depends on the :doc:`atom style ` used, and that setting +must be done in the input file *before* reading the data file. To +assist with detecting incompatible data files, a comment is appended to +the "Atoms" title indicating the atom style used (or intended) when +*writing* the data file. For example, below is an "Atoms" section for +:doc:`atom style charge `, which omits the molecule ID +column. + +.. code-block:: bash + + Atoms # charge + + 1 1 0.560 43.99993 58.52678 36.78550 + 2 2 -0.270 45.10395 58.23499 35.86693 + 3 3 -0.510 43.81519 59.54928 37.43995 + 4 4 0.090 45.71714 57.34797 36.13434 + 5 4 0.090 45.72261 59.13657 35.67007 + 6 4 0.090 44.66624 58.09539 34.85538 + 7 3 -0.470 43.28193 57.47427 36.91953 + 8 4 0.070 42.07157 57.45486 37.62418 + 9 1 0.510 42.19985 57.57789 39.12163 + 10 1 0.510 41.88641 58.62251 39.70398 + # ^^atomID ^^type ^^charge ^^xcoord ^^ycoord ^^ycoord + +Another source of confusion about the "Atoms" section format is the +ordering of columns. The three atom style variants `atom_style full`, +`atom_style hybrid charge molecular`, and `atom_style hybrid molecular +charge` all carry the same per-atom information. However, in data files, +the Atoms section has the columns 'Atom-ID Molecule-ID Atom-type Charge +X Y Z' for atom style full, but for hybrid atom styles the first columns +are always 'Atom-ID Atom-type X Y Z' followed by any *additional* data +added by the hybrid styles, for example, 'Charge Molecule-ID' for the +first hybrid style and 'Molecule-ID Charge' in the second hybrid style +variant. Finally, an alternative to a hybrid atom style is to use fix +property/atom, e.g. to add molecule IDs to atom style charge. In this +case the "Atoms" section is formatted according to atom style charge and +a new section, "Molecules" is added that contains lines with 'Atom-ID +Molecule-ID', one for each atom in the system. For adding charges to +atom style molecular with fix property/atom, the "Atoms" section is now +formatted according to the atom style and a "Charges" section is added. + +Molecule file +^^^^^^^^^^^^^ + +Molecule files for use with the :doc:`molecule command ` look +quite similar to data files but they do not have a compatible format, +i.e., one cannot use a data file as molecule file and vice versa. Below +is a simple example for a water molecule (SPC/E model). Same as a data +file, there is an ignored title line and you can use comments. However, +there is no information about the number of types or the box dimensions. +These parameters are set when the simulation box is created. Thus the +header only has the count of atoms, bonds, and so on. + +Molecule files have a header followed by sections (just as in data +files), but the section names are different than those of a data file. +There is no "Atoms" section and the section formats in molecule files is +independent of the atom style. Its information is split across multiple +sections, like "Coords", "Types", and "Charges". Note that no "Masses" +section is needed here. The atom masses are by default tied to the atom +type and set with a data file or the :doc:`mass command `. A +"Masses" section would only be required for atom styles with per-atom +masses, e.g. atom style sphere, where in data files you would provide +the density and the diameter instead of the mass. + +Since the entire file is a 'molecule', LAMMPS will assign a new +molecule-ID (if supported by the atom style) when atoms are instantiated +from a molecule file, e.g. with the :doc:`create_atoms command +`. It is possible to include a "Molecules" section to +indicate that the atoms belong to multiple 'molecules'. Atom-IDs and +molecule-IDs in the molecule file are relative for the file +(i.e. starting from 1) and will be translated into actual atom-IDs also +when the atoms from the molecule are created. + +.. code-block:: bash + + # Water molecule. SPC/E model. + + 3 atoms + 2 bonds + 1 angles + + Coords + + 1 1.12456 0.09298 1.27452 + 2 1.53683 0.75606 1.89928 + 3 0.49482 0.56390 0.65678 + + Types + + 1 1 + 2 2 + 3 2 + + Charges + + 1 -0.8472 + 2 0.4236 + 3 0.4236 + + Bonds + + 1 1 1 2 + 2 1 1 3 + + Angles + + 1 1 2 1 3 + + +There are also optional sections, e.g. about :doc:`SHAKE ` +and :doc:`special bonds `. Those sections are only needed +if the molecule command is issued *before* the simulation box is +defined. Otherwise, the molecule command can derive the required +settings internally. + +Restart file +^^^^^^^^^^^^ + +LAMMPS restart files are binary files and not available in text format. +They can be identified by the first few bytes that contain the (C-style) +string ``LammpS RestartT`` as `magic string +`_. This string is followed +by a 16-bit integer of the number 1 used for detecting whether the +computer writing the restart has the same `endianness +`_ as the computer reading it. +If not, the file cannot be read correctly. This integer is followed by +a 32-bit integer indicating the file format revision (currently 3), +which can be used to implement backward compatibility for reading older +revisions. + +This information has been added to the `Unix "file" command's +` "magic" file so that restart files +can be identified without opening them. If you have a fairly recent +version, it should already be included. If you have an older version, +the LAMMPS source package :ref:`contains a file with the necessary +additions `. + +The rest of the file is organized in sections of a 32-bit signed integer +constant indicating the kind of content and the corresponding value (or +values). If those values are arrays (including C-style strings), then +the integer constant is followed by a 32-bit integer indicating the +length of the array. This mechanism will read the data regardless of +the ordering of the sections. Symbolic names of the section constants +are in the ``lmprestart.h`` header file. + +LAMMPS restart files are not expected to be portable between platforms +or LAMMPS versions, but changes to the file format are rare. + +.. Native Dump file +.. ^^^^^^^^^^^^^^^^ +.. +.. Potential files +.. ^^^^^^^^^^^^^^^ diff --git a/doc/src/Run_head.rst b/doc/src/Run_head.rst index 5da5942d9b..6739df5cbb 100644 --- a/doc/src/Run_head.rst +++ b/doc/src/Run_head.rst @@ -1,10 +1,11 @@ Run LAMMPS ********** -These pages explain how to run LAMMPS once you have :doc:`installed an executable ` or :doc:`downloaded the source code ` -and :doc:`built an executable `. The :doc:`Commands ` -doc page describes how input scripts are structured and the commands -they can contain. +These pages explain how to run LAMMPS once you have :doc:`installed an +executable ` or :doc:`downloaded the source code ` and +:doc:`built an executable `. The :doc:`Commands ` doc +page describes how input scripts are structured and the commands they +can contain. .. toctree:: :maxdepth: 1 @@ -12,4 +13,5 @@ they can contain. Run_basics Run_options Run_output + Run_formats Run_windows 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_compare.rst b/doc/src/Speed_compare.rst index 7821214c83..3f72e5d715 100644 --- a/doc/src/Speed_compare.rst +++ b/doc/src/Speed_compare.rst @@ -44,11 +44,6 @@ section below for examples where this has been done. system the crossover (in single precision) is often about 50K-100K atoms per GPU. When performing double precision calculations the crossover point can be significantly smaller. -* Both KOKKOS and GPU package compute bonded interactions (bonds, angles, - etc) on the CPU. If the GPU package is running with several MPI processes - assigned to one GPU, the cost of computing the bonded interactions is - spread across more CPUs and hence the GPU package can run faster in these - cases. * When using LAMMPS with multiple MPI ranks assigned to the same GPU, its performance depends to some extent on the available bandwidth between the CPUs and the GPU. This can differ significantly based on the @@ -85,10 +80,10 @@ section below for examples where this has been done. code (with a performance penalty due to having data transfers between host and GPU). * The GPU package requires neighbor lists to be built on the CPU when using - exclusion lists, or a triclinic simulation box. -* The GPU package can be compiled for CUDA or OpenCL and thus supports - both, NVIDIA and AMD GPUs well. On NVIDIA hardware, using CUDA is typically - resulting in equal or better performance over OpenCL. + hybrid pair styles, exclusion lists, or a triclinic simulation box. +* The GPU package can be compiled for CUDA, HIP, or OpenCL and thus supports + NVIDIA, AMD, and Intel GPUs well. On NVIDIA hardware, using CUDA is + typically resulting in equal or better performance over OpenCL. * OpenCL in the GPU package does theoretically also support Intel CPUs or Intel Xeon Phi, but the native support for those in KOKKOS (or INTEL) is superior. 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/Tools.rst b/doc/src/Tools.rst index d13a6d384f..11468787f1 100644 --- a/doc/src/Tools.rst +++ b/doc/src/Tools.rst @@ -930,7 +930,7 @@ dependencies and redirects the download to the local cache. mkdir build cd build - cmake -D LAMMPS_DOWNLOADS_URL=${HTTP_CACHE_URL} -C "${LAMMPS_HTTP_CACHE_CONFIG}" -C ../cmake/presets/most.cmake ../cmake + cmake -D LAMMPS_DOWNLOADS_URL=${HTTP_CACHE_URL} -C "${LAMMPS_HTTP_CACHE_CONFIG}" -C ../cmake/presets/most.cmake -D DOWNLOAD_POTENTIALS=off ../cmake make -j 8 deactivate_caches diff --git a/doc/src/angle_mwlc.rst b/doc/src/angle_mwlc.rst new file mode 100644 index 0000000000..587afb8009 --- /dev/null +++ b/doc/src/angle_mwlc.rst @@ -0,0 +1,94 @@ +.. index:: angle_style mwlc + +angle_style mwlc command +========================== + +Syntax +"""""" + +.. code-block:: LAMMPS + + angle_style mwlc + +Examples +"""""""" + +.. code-block:: LAMMPS + + angle_style mwlc + angle_coeff * 25 1 10 1 + +Description +""""""""""" + +.. 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* +uses a potential that is a canonical-ensemble superposition of a +non-melted and a melted state :ref:`(Farrell) `. The potential +is + +.. math:: + + E = -k_{B}T\,\log [q + q^{m}] + E_{0}, + +where the non-melted and melted partition functions are + +.. math:: + q = \exp [-k_{1}(1+\cos{\theta})/k_{B}T]; \\ + q^{m} = \exp [-(\mu+k_{2}(1+\cos{\theta}))/k_{B}T]. + +:math:`k_1` is the bending elastic constant of the non-melted state, +:math:`k_2` is the bending elastic constant of the melted state, +:math:`\mu` is the melting energy, and +:math:`T` is the reference temperature. +The reference energy, + +.. math:: + E_{0} = -k_{B}T\,\log [1 + \exp[-\mu/k_{B}T]], + +ensures that E is zero for a fully extended chain. + +This potential is a continuous version of the two-state potential +introduced by :ref:`(Yan) `. + +The following coefficients must be defined for each angle type via the +:doc:`angle_coeff ` command as in the example above, or in +the data file or restart files read by the :doc:`read_data ` +or :doc:`read_restart ` commands: + +* :math:`k_1` (energy) +* :math:`k_2` (energy) +* :math:`\mu` (energy) +* :math:`T` (temperature) + +---------- + + +Restrictions +"""""""""""" + +This angle style can only be used if LAMMPS was built with the +EXTRA-MOLECULE package. See the :doc:`Build package ` +doc page for more info. + +Related commands +"""""""""""""""" + +:doc:`angle_coeff ` + +Default +""""""" + +none + +---------- + +.. _Farrell: + +**(Farrell)** `Farrell, Dobnikar, Podgornik, Curk, Phys Rev Lett, 133, 148101 (2024). `_ + +.. _Yan: + +**(Yan)** `Yan, Marko, Phys Rev Lett, 93, 108108 (2004). `_ diff --git a/doc/src/angle_style.rst b/doc/src/angle_style.rst index dc16a3fbaa..ab7671c75d 100644 --- a/doc/src/angle_style.rst +++ b/doc/src/angle_style.rst @@ -94,6 +94,7 @@ of (g,i,k,o,t) to indicate which accelerated styles exist. * :doc:`lepton ` - angle potential from evaluating a string * :doc:`mesocnt ` - piecewise harmonic and linear angle for bending-buckling of nanotubes * :doc:`mm3 ` - anharmonic angle +* :doc:`mwlc ` - meltable wormlike chain * :doc:`quartic ` - angle with cubic and quartic terms * :doc:`spica ` - harmonic angle with repulsive SPICA pair style between 1-3 atoms * :doc:`table ` - tabulated by angle diff --git a/doc/src/bond_bpm_spring.rst b/doc/src/bond_bpm_spring.rst index 0a43a62159..27962c81a1 100644 --- a/doc/src/bond_bpm_spring.rst +++ b/doc/src/bond_bpm_spring.rst @@ -10,7 +10,7 @@ Syntax bond_style bpm/spring keyword value attribute1 attribute2 ... -* optional keyword = *overlay/pair* or *store/local* or *smooth* or *break* or *volume/factor* +* optional keyword = *overlay/pair* or *store/local* or *smooth* or *normalize* or *break* or *volume/factor* .. parsed-literal:: @@ -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 @@ -141,7 +141,8 @@ calculated using bond lengths squared and the cube root in the above equation is accordingly replaced with a square root. This approximation assumes bonds are evenly distributed on a spherical surface and neglects constant prefactors which are irrelevant since only the ratio of volumes matters. This term may be -used to adjust the Poisson's ratio. +used to adjust the Poisson's ratio. See the simulation in the +``examples/bpm/poissons_ratio`` directory for a demonstration of this effect. If a bond is broken (or created), :math:`V_{0,i}` is updated by subtracting (or adding) that bond's contribution. @@ -152,7 +153,7 @@ the data file or restart files read by the :doc:`read_data ` or :doc:`read_restart ` commands: * :math:`k` (force/distance units) -* :math:`\epsilon_c` (unit less) +* :math:`\epsilon_c` (unitless) * :math:`\gamma` (force/velocity units) Additionally, if *volume/factor* is set to *yes*, a fourth coefficient @@ -214,11 +215,11 @@ for an overview of LAMMPS output options. The vector or array will be floating point values that correspond to the specified attribute. -The single() function of this bond style returns 0.0 for the energy -of a bonded interaction, since energy is not conserved in these -dissipative potentials. The single() function also calculates an -extra bond quantity, the initial distance :math:`r_0`. This -extra quantity can be accessed by the +The potential energy and the single() function of this bond style return +:math:`k (r - r_0)^2 / 2` as a proxy of the energy of a bonded interaction, +ignoring any volumetric/smoothing factors or dissipative forces. The single() +function also calculates an extra bond quantity, the initial distance +:math:`r_0`. This extra quantity can be accessed by the :doc:`compute bond/local ` command as *b1*\ . Restrictions diff --git a/doc/src/bond_bpm_spring_plastic.rst b/doc/src/bond_bpm_spring_plastic.rst new file mode 100644 index 0000000000..3bc2c4ee46 --- /dev/null +++ b/doc/src/bond_bpm_spring_plastic.rst @@ -0,0 +1,184 @@ +.. index:: bond_style bpm/spring/plastic + +bond_style bpm/spring/plastic command +===================================== + +Syntax +"""""" + +.. code-block:: LAMMPS + + bond_style bpm/spring/plastic keyword value attribute1 attribute2 ... + +* optional keyword = *overlay/pair* or *store/local* or *smooth* or *normalize* or *break* + + .. parsed-literal:: + + *store/local* values = fix_ID N attributes ... + * fix_ID = ID of associated internal fix to store data + * N = prepare data for output every this many timesteps + * attributes = zero or more of the below attributes may be appended + + *id1, id2* = IDs of two atoms in the bond + *time* = the timestep the bond broke + *x, y, z* = the center of mass position of the two atoms when the bond broke (distance units) + *x/ref, y/ref, z/ref* = the initial center of mass position of the two atoms (distance units) + + *overlay/pair* value = *yes* or *no* + bonded particles will still interact with pair forces + + *smooth* value = *yes* or *no* + smooths bond forces near the breaking point + + *normalize* value = *yes* or *no* + normalizes bond forces by the reference length + + *break* value = *yes* or *no* + indicates whether bonds break during a run + +Examples +"""""""" + +.. code-block:: LAMMPS + + bond_style bpm/spring/plastic + bond_coeff 1 1.0 0.05 0.1 0.02 + + bond_style bpm/spring/plastic myfix 1000 time id1 id2 + dump 1 all local 1000 dump.broken f_myfix[1] f_myfix[2] f_myfix[3] + dump_modify 1 write_header no + +Description +""""""""""" + +.. versionadded:: TBD + +The *bpm/spring/plastic* bond style computes forces based on +deviations from the initial reference state of the two atoms and the +strain history. The reference length of the bond :math:`r_0` is stored +by each bond when it is first computed in the setup of a run. Initially, +the equilibrium length of each bond :math:`r_\mathrm{eq}` is set equal +to :math:`r_0` but can evolve. data is then preserved across run commands +and is written to :doc:`binary restart files ` such that restarting +the system will not modify either of these quantities. + +This bond style only applies central-body forces which conserve the +translational and rotational degrees of freedom of a bonded set of +particles. The force has a magnitude of + +.. math:: + + F = -k (r_\mathrm{eq} - r) w + +where :math:`k` is a stiffness, :math:`r` is the current distance between +the two particles, and :math:`w` is an optional smoothing factor discussed +below. If the bond stretches beyond a strain of :math:`\epsilon_p` in compression +or extension, it will plastically activate and :math:`r_\mathrm{eq}` will evolve +to ensure :math:`|(r-r_\mathrm{eq})/r_\mathrm{eq}|` never exceeds :math:`\epsilon_p`. +Therefore, if a bond is continually loaded in either tension or compression, the +force will initially grow elastically before plateauing. See +:ref:`(Clemmer) ` for more details on these mechanics. + +Bonds will break at a strain of :math:`\epsilon_c`. This is done by setting +the bond type to 0 such that forces are no longer computed. + +An additional damping force is applied to the bonded +particles. This forces is proportional to the difference in the +normal velocity of particles: + +.. math:: + + F_D = - \gamma w (\hat{r} \bullet \vec{v}) + +where :math:`\gamma` is the damping strength, :math:`\hat{r}` is the +radial normal vector, and :math:`\vec{v}` is the velocity difference +between the two particles. + +The smoothing factor :math:`w` is constructed such that forces smoothly +go to zero, avoiding discontinuities, as bonds approach the critical +breaking strain + +.. math:: + + w = 1.0 - \left( \frac{r - r_0}{r_0 \epsilon_c} \right)^8 . + +The following coefficients must be defined for each bond type via the +:doc:`bond_coeff ` command as in the example above, or in +the data file or restart files read by the :doc:`read_data +` or :doc:`read_restart ` commands: + +* :math:`k` (force/distance units) +* :math:`\epsilon_c` (unitless) +* :math:`\gamma` (force/velocity units) +* :math:`\epsilon_p` (unitless) + +See the :doc:`bpm/spring doc page ` for information on +the *smooth*, *normalize*, *break*, *overlay/pair*, and *store/local* +keywords. + +Note that when unbroken bonds are dumped to a file via the +:doc:`dump local ` command, bonds with type 0 (broken bonds) +are not included. +The :doc:`delete_bonds ` command can also be used to +query the status of broken bonds or permanently delete them, e.g.: + +.. code-block:: LAMMPS + + delete_bonds all stats + delete_bonds all bond 0 remove + +---------- + +Restart and other info +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +This bond style writes the reference state and plastic history of each +bond to :doc:`binary restart files `. Loading a restart file +will properly restore bonds. However, the reference state is NOT written +to data files. Therefore reading a data file will not restore bonds and +will cause their reference states to be redefined. + +The potential energy and the single() function of this bond style +returns zero. The single() function also calculates two extra bond +quantities, the initial distance :math:`r_0` and the current equilibrium +length :math:`r_eq`. These extra quantities can be accessed by the +:doc:`compute bond/local ` command as *b1* and *b2*, +respectively. + +Restrictions +"""""""""""" + +This bond style is part of the BPM package. It is only enabled if +LAMMPS was built with that package. See the :doc:`Build package +` page for more info. + +By default if pair interactions between bonded atoms are to be disabled, +this bond style requires setting + +.. code-block:: LAMMPS + + special_bonds lj 0 1 1 coul 1 1 1 + +and :doc:`newton ` must be set to bond off. If the *overlay/pair* +keyword is set to *yes*, this bond style alternatively requires setting + +.. code-block:: LAMMPS + + special_bonds lj/coul 1 1 1 + +Related commands +"""""""""""""""" + +:doc:`bond_coeff `, :doc:`bond bpm/spring ` + +Default +""""""" + +The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *no*, and *break* = *yes* + +---------- + +.. _plastic-Clemmer: + +**(Clemmer)** Clemmer and Lechman, Powder Technology (2025). + diff --git a/doc/src/bond_harmonic.rst b/doc/src/bond_harmonic.rst index a76cc54746..70e652bb4a 100644 --- a/doc/src/bond_harmonic.rst +++ b/doc/src/bond_harmonic.rst @@ -60,6 +60,8 @@ Related commands """""""""""""""" :doc:`bond_coeff `, :doc:`delete_bonds ` +:doc:`bond style harmonic/shift `, +:doc:`bond style harmonic/shift/cut ` Default """"""" diff --git a/doc/src/bond_harmonic_shift.rst b/doc/src/bond_harmonic_shift.rst index 43e10bde00..e57d464af8 100644 --- a/doc/src/bond_harmonic_shift.rst +++ b/doc/src/bond_harmonic_shift.rst @@ -31,9 +31,15 @@ the potential E = \frac{U_{\text{min}}}{(r_0-r_c)^2} \left[ (r-r_0)^2-(r_c-r_0)^2 \right] -where :math:`r_0` is the equilibrium bond distance, and :math:`r_c` the critical distance. -The potential is :math:`-U_{\text{min}}` at :math:`r0` and zero at :math:`r_c`. The spring constant is -:math:`k = U_{\text{min}} / [ 2 (r_0-r_c)^2]`. +where :math:`r_0` is the equilibrium bond distance, and :math:`r_c` the +critical distance. The potential energy has the value +:math:`-U_{\text{min}}` at :math:`r_0` and zero at :math:`r_c`. This +bond style differs from :doc:`bond_style harmonic ` +by the value of the potential energy. + +The equivalent spring constant value *K* for use with :doc:`bond_style +harmonic ` can be computed using :math:`K = +U_{\text{min}} / [(r_0-r_c)^2]`. The following coefficients must be defined for each bond type via the :doc:`bond_coeff ` command as in the example above, or in @@ -41,9 +47,7 @@ the data file or restart files read by the :doc:`read_data ` or :doc:`read_restart ` commands: * :math:`U_{\text{min}}` (energy) - * :math:`r_0` (distance) - * :math:`r_c` (distance) ---------- @@ -63,7 +67,8 @@ Related commands """""""""""""""" :doc:`bond_coeff `, :doc:`delete_bonds `, -:doc:`bond_harmonic ` +:doc:`bond style harmonic `, +:doc:`bond style harmonic/shift/cut ` Default """"""" diff --git a/doc/src/bond_harmonic_shift_cut.rst b/doc/src/bond_harmonic_shift_cut.rst index d8d4a792b7..964ae4b9ba 100644 --- a/doc/src/bond_harmonic_shift_cut.rst +++ b/doc/src/bond_harmonic_shift_cut.rst @@ -31,9 +31,14 @@ uses the potential E = \frac{U_{\text{min}}}{(r_0-r_c)^2} \left[ (r-r_0)^2-(r_c-r_0)^2 \right] -where :math:`r_0` is the equilibrium bond distance, and rc the critical distance. -The bond potential is zero for distances :math:`r > r_c`. The potential is :math:`-U_{\text{min}}` -at :math:`r_0` and zero at :math:`r_c`. The spring constant is :math:`k = U_{\text{min}} / [ 2 (r_0-r_c)^2]`. +where :math:`r_0` is the equilibrium bond distance, and :math:`r_c` the +critical distance. The bond potential is zero and thus its force also +zero for distances :math:`r > r_c`. The potential energy has the value +:math:`-U_{\text{min}}` at :math:`r_0` and zero at :math:`r_c`. + +The equivalent spring constant value *K* for use with :doc:`bond_style +harmonic ` for :math:`r <= r_c`, can be computed using +:math:`K = U_{\text{min}} / [(r_0-r_c)^2]` The following coefficients must be defined for each bond type via the :doc:`bond_coeff ` command as in the example above, or in diff --git a/doc/src/bond_rheo_shell.rst b/doc/src/bond_rheo_shell.rst index 090f5ab7aa..ef8d7d4249 100644 --- a/doc/src/bond_rheo_shell.rst +++ b/doc/src/bond_rheo_shell.rst @@ -94,7 +94,7 @@ the data file or restart files read by the :doc:`read_data ` or :doc:`read_restart ` commands: * :math:`k` (force/distance units) -* :math:`\epsilon_c` (unit less) +* :math:`\epsilon_c` (unitless) * :math:`\gamma` (force/velocity units) Unlike other BPM-style bonds, this bond style does not update special diff --git a/doc/src/bond_style.rst b/doc/src/bond_style.rst index 590f7c8cba..a30fb9e812 100644 --- a/doc/src/bond_style.rst +++ b/doc/src/bond_style.rst @@ -10,7 +10,7 @@ Syntax bond_style style args -* style = *none* or *zero* or *hybrid* or *bpm/rotational* or *bpm/spring* or *class2* or *fene* or *fene/expand* or *fene/nm* or *gaussian* or *gromos* or *harmonic* or *harmonic/restrain* *harmonic/shift* or *harmonic/shift/cut* or *lepton* or *morse* or *nonlinear* or *oxdna/fene* or *oxdena2/fene* or *oxrna2/fene* or *quartic* or *special* or *table* +* style = *none* or *zero* or *hybrid* or *bpm/rotational* or *bpm/spring* or *bpm/spring/plastic* or *class2* or *fene* or *fene/expand* or *fene/nm* or *gaussian* or *gromos* or *harmonic* or *harmonic/restrain* *harmonic/shift* or *harmonic/shift/cut* or *lepton* or *morse* or *nonlinear* or *oxdna/fene* or *oxdena2/fene* or *oxrna2/fene* or *quartic* or *special* or *table* * args = none for any style except *hybrid* @@ -86,6 +86,7 @@ accelerated styles exist. * :doc:`bpm/rotational ` - breakable bond with forces and torques based on deviation from reference state * :doc:`bpm/spring ` - breakable bond with forces based on deviation from reference length +* :doc:`bpm/spring/plastic ` - a similar breakable bond with plastic yield * :doc:`class2 ` - COMPASS (class 2) bond * :doc:`fene ` - FENE (finite-extensible non-linear elastic) bond * :doc:`fene/expand ` - FENE bonds with variable size particles 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..323f3ed3e5 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 @@ -355,6 +356,7 @@ The individual style names on the :doc:`Commands compute ` pag * :doc:`ti ` - thermodynamic integration free energy values * :doc:`torque/chunk ` - torque applied on each chunk * :doc:`vacf ` - velocity auto-correlation function of group of atoms +* :doc:`vacf/chunk ` - velocity auto-correlation for the center of mass velocities of chunks of atoms * :doc:`vcm/chunk ` - velocity of center-of-mass for each chunk * :doc:`viscosity/cos ` - velocity profile under cosine-shaped acceleration * :doc:`voronoi/atom ` - Voronoi volume and neighbors for each atom diff --git a/doc/src/compute_chunk_atom.rst b/doc/src/compute_chunk_atom.rst index 9bca1e26d1..24c2e2e47c 100644 --- a/doc/src/compute_chunk_atom.rst +++ b/doc/src/compute_chunk_atom.rst @@ -217,13 +217,16 @@ scaled differently in the two different dimensions to transform them into ellipses). The created bins (and hence the chunk IDs) are numbered consecutively -from 1 to the number of bins = *Nchunk*\ . For *bin2d* and *bin3d*, the -numbering varies most rapidly in the first dimension (which could be -*x*, *y*, or *z*), next rapidly in the second dimension, and most slowly in the -third dimension. For *bin/sphere*, the bin with smallest radii is chunk -1 and the bin with largest radii is chunk Nchunk = *ncbin*\ . For -*bin/cylinder*, the numbering varies most rapidly in the dimension -along the cylinder axis and most slowly in the radial direction. +from 1 to the number of bins = *Nchunk*\ . For *bin2d* and *bin3d*, the +numbering varies fastest in the last dimension (which could be +*x*, *y*, or *z*), slower in the second dimension, and slowest in the +first dimension. For *bin/sphere*, the bin with smallest radius is chunk +1 and the bin with largest radius is chunk Nchunk = *ncbin*\ . For +*bin/cylinder*, the numbering varies faster in the dimension +along the cylinder axis and slower in the radial direction. +In all cases, for a given dimension, the numbering increases +with increasing value of the coordinate (Cartesian coordinate, +sphere or cylinder radius, axial position). Each time this compute is invoked, each atom is mapped to a bin based on its current position. Note that between reneighboring timesteps, diff --git a/doc/src/compute_cna_atom.rst b/doc/src/compute_cna_atom.rst index 925159951c..33329d88d6 100644 --- a/doc/src/compute_cna_atom.rst +++ b/doc/src/compute_cna_atom.rst @@ -67,7 +67,7 @@ following relation should also be satisfied: .. math:: - r_c + r_s > 2*{\rm cutoff} + r_c + r_s > 2*\mathrm{cutoff} where :math:`r_c` is the cutoff distance of the potential, :math:`r_s` is the skin diff --git a/doc/src/compute_cnp_atom.rst b/doc/src/compute_cnp_atom.rst index 41fdb8324e..94dec390f4 100644 --- a/doc/src/compute_cnp_atom.rst +++ b/doc/src/compute_cnp_atom.rst @@ -74,7 +74,7 @@ following relation should also be satisfied: .. math:: - r_c + r_s > 2*{\rm cutoff} + r_c + r_s > 2*\mathrm{cutoff} where :math:`r_c` is the cutoff distance of the potential, :math:`r_s` is the skin diff --git a/doc/src/compute_efield_wolf_atom.rst b/doc/src/compute_efield_wolf_atom.rst index 93bfa55151..572ca59ab4 100644 --- a/doc/src/compute_efield_wolf_atom.rst +++ b/doc/src/compute_efield_wolf_atom.rst @@ -50,9 +50,9 @@ the potential energy using the Wolf summation method, described in .. math:: E_i = \frac{1}{2} \sum_{j \neq i} - \frac{q_i q_j {\rm erfc}(\alpha r_{ij})}{r_{ij}} + + \frac{q_i q_j \mathrm{erfc}(\alpha r_{ij})}{r_{ij}} + \frac{1}{2} \sum_{j \neq i} - \frac{q_i q_j {\rm erf}(\alpha r_{ij})}{r_{ij}} \qquad r < r_c + \frac{q_i q_j \mathrm{erf}(\alpha r_{ij})}{r_{ij}} \qquad r < r_c where :math:`\alpha` is the damping parameter, and *erf()* and *erfc()* are error-function and complementary error-function terms. This 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_hexorder_atom.rst b/doc/src/compute_hexorder_atom.rst index 1fb8113a89..ea937f2e00 100644 --- a/doc/src/compute_hexorder_atom.rst +++ b/doc/src/compute_hexorder_atom.rst @@ -40,7 +40,7 @@ is a complex number (stored as two real numbers) defined as follows: .. math:: - q_n = \frac{1}{nnn}\sum_{j = 1}^{nnn} e^{n i \theta({\bf r}_{ij})} + q_n = \frac{1}{nnn}\sum_{j = 1}^{nnn} e^{n i \theta({\textbf{r}}_{ij})} where the sum is over the *nnn* nearest neighbors of the central atom. The angle :math:`\theta` diff --git a/doc/src/compute_msd.rst b/doc/src/compute_msd.rst index bc16a3de6f..8f2726e8a3 100644 --- a/doc/src/compute_msd.rst +++ b/doc/src/compute_msd.rst @@ -116,7 +116,9 @@ Compute *msd* cannot be used with a dynamic group. Related commands """""""""""""""" -:doc:`compute msd/nongauss `, :doc:`compute displace_atom `, :doc:`fix store/state `, :doc:`compute msd/chunk ` +:doc:`compute msd/nongauss `, +:doc:`compute displace_atom `, :doc:`fix store/state `, +:doc:`compute msd/chunk ` Default """"""" diff --git a/doc/src/compute_msd_chunk.rst b/doc/src/compute_msd_chunk.rst index db6e1e6fc2..863be4db35 100644 --- a/doc/src/compute_msd_chunk.rst +++ b/doc/src/compute_msd_chunk.rst @@ -131,7 +131,7 @@ Restrictions Related commands """""""""""""""" -:doc:`compute msd ` +:doc:`compute msd `, :doc:`compute vacf/chunk ` Default """"""" diff --git a/doc/src/compute_orientorder_atom.rst b/doc/src/compute_orientorder_atom.rst index 01535aa880..08153fe496 100644 --- a/doc/src/compute_orientorder_atom.rst +++ b/doc/src/compute_orientorder_atom.rst @@ -49,7 +49,7 @@ For each atom, :math:`Q_\ell` is a real number defined as follows: .. math:: - \bar{Y}_{\ell m} = & \frac{1}{nnn}\sum_{j = 1}^{nnn} Y_{\ell m}\bigl( \theta( {\bf r}_{ij} ), \phi( {\bf r}_{ij} ) \bigr) \\ + \bar{Y}_{\ell m} = & \frac{1}{nnn}\sum_{j = 1}^{nnn} Y_{\ell m}\bigl( \theta( \mathbf{r}_{ij} ), \phi( \mathbf{r}_{ij} ) \bigr) \\ Q_\ell = & \sqrt{\frac{4 \pi}{2 \ell + 1} \sum_{m = -\ell }^{m = \ell } \bar{Y}_{\ell m} \bar{Y}^*_{\ell m}} The first equation defines the local order parameters as averages diff --git a/doc/src/compute_reduce.rst b/doc/src/compute_reduce.rst index e5c99a478f..d9aa7e1821 100644 --- a/doc/src/compute_reduce.rst +++ b/doc/src/compute_reduce.rst @@ -87,7 +87,7 @@ values in the vector. The *sumsq* option sums the square of the values in the vector into a global total. The *avesq* setting does the same as *sumsq*, then divides the sum of squares by the number of values. The last two options can be useful for calculating the -variance of some quantity (e.g., variance = sumsq :math:`-` ave\ +variance of some quantity (e.g., variance = *avesq* :math:`-` *ave*\ :math:`^2`). The *sumabs* option sums the absolute values in the vector into a global total. The *aveabs* setting does the same as *sumabs*, then divides the sum of absolute values by the number of diff --git a/doc/src/compute_sna_atom.rst b/doc/src/compute_sna_atom.rst index 179c362dc6..2f8c4c4f5d 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 @@ -132,11 +139,11 @@ mapped on to a third polar angle :math:`\theta_0` defined by, .. math:: - \theta_0 = {\sf rfac0} \frac{r-r_{min0}}{R_{ii'}-r_{min0}} \pi + \theta_0 = \mathsf{rfac0} \frac{r-r_{min0}}{R_{ii'}-r_{min0}} \pi In this way, all possible neighbor positions are mapped on to a subset -of the 3-sphere. Points south of the latitude :math:`\theta_0` = -*rfac0* :math:`\pi` are excluded. +of the 3-sphere. Points south of the latitude +:math:`\theta_0 = \mathsf{rfac0} \pi` are excluded. The natural basis for functions on the 3-sphere is formed by the representatives of *SU(2)*, the matrices :math:`U^j_{m,m'}(\theta, \phi, @@ -197,7 +204,7 @@ components summed separately for each LAMMPS atom type: .. math:: - -\sum_{i' \in I} \frac{\partial {B^{i'}_{j_1,j_2,j} }}{\partial {\bf r}_i} + -\sum_{i' \in I} \frac{\partial {B^{i'}_{j_1,j_2,j} }}{\partial \mathbf{r}_i} The sum is over all atoms *i'* of atom type *I*\ . For each atom *i*, this compute evaluates the above expression for each direction, each @@ -209,7 +216,7 @@ derivatives: .. math:: - -{\bf r}_i \otimes \sum_{i' \in I} \frac{\partial {B^{i'}_{j_1,j_2,j}}}{\partial {\bf r}_i} + -\mathbf{r}_i \otimes \sum_{i' \in I} \frac{\partial {B^{i'}_{j_1,j_2,j}}}{\partial \mathbf{r}_i} Again, the sum is over all atoms *i'* of atom type *I*\ . For each atom *i*, this compute evaluates the above expression for each of the six @@ -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/compute_stress_atom.rst b/doc/src/compute_stress_atom.rst index e047423640..6c4e0b690c 100644 --- a/doc/src/compute_stress_atom.rst +++ b/doc/src/compute_stress_atom.rst @@ -65,7 +65,7 @@ In case of compute *stress/atom*, the virial contribution is: W_{ab} & = \frac{1}{2} \sum_{n = 1}^{N_p} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b}) + \frac{1}{2} \sum_{n = 1}^{N_b} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b}) \\ & + \frac{1}{3} \sum_{n = 1}^{N_a} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b} + r_{3_a} F_{3_b}) + \frac{1}{4} \sum_{n = 1}^{N_d} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b} + r_{3_a} F_{3_b} + r_{4_a} F_{4_b}) \\ - & + \frac{1}{4} \sum_{n = 1}^{N_i} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b} + r_{3_a} F_{3_b} + r_{4_a} F_{4_b}) + {\rm Kspace}(r_{i_a},F_{i_b}) + \sum_{n = 1}^{N_f} r_{i_a} F_{i_b} + & + \frac{1}{4} \sum_{n = 1}^{N_i} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b} + r_{3_a} F_{3_b} + r_{4_a} F_{4_b}) + \mathrm{Kspace}(r_{i_a},F_{i_b}) + \sum_{n = 1}^{N_f} r_{i_a} F_{i_b} The first term is a pairwise energy contribution where :math:`n` loops over the :math:`N_p` neighbors of atom :math:`I`, :math:`\mathbf{r}_1` @@ -97,7 +97,7 @@ In case of compute *centroid/stress/atom*, the virial contribution is: .. math:: W_{ab} & = \sum_{n = 1}^{N_p} r_{I0_a} F_{I_b} + \sum_{n = 1}^{N_b} r_{I0_a} F_{I_b} + \sum_{n = 1}^{N_a} r_{I0_a} F_{I_b} + \sum_{n = 1}^{N_d} r_{I0_a} F_{I_b} + \sum_{n = 1}^{N_i} r_{I0_a} F_{I_b} \\ - & + {\rm Kspace}(r_{i_a},F_{i_b}) + \sum_{n = 1}^{N_f} r_{i_a} F_{i_b} + & + \mathrm{Kspace}(r_{i_a},F_{i_b}) + \sum_{n = 1}^{N_f} r_{i_a} F_{i_b} As with compute *stress/atom*, the first, second, third, fourth and fifth terms are pairwise, bond, angle, dihedral and improper diff --git a/doc/src/compute_temp_chunk.rst b/doc/src/compute_temp_chunk.rst index 33eab04343..3d97ad1699 100644 --- a/doc/src/compute_temp_chunk.rst +++ b/doc/src/compute_temp_chunk.rst @@ -184,11 +184,24 @@ temp/chunk calculation to a file is to use the The keyword/value option pairs are used in the following ways. The *com* keyword can be used with a value of *yes* to subtract the -velocity of the center-of-mass for each chunk from the velocity of the -atoms in that chunk, before calculating either the global or per-chunk -temperature. This can be useful if the atoms are streaming or +velocity of the center-of-mass (VCM) for each chunk from the velocity of +the atoms in that chunk, before calculating either the global or per-chunk +temperature. This can be useful if the atoms are streaming or otherwise moving collectively, and you wish to calculate only the -thermal temperature. +thermal temperature. This per-chunk VCM bias can be used in other fixes and +computes that can incorporate a temperature bias. If this compute is used +as a temperature bias in other commands then this bias is subtracted from +each atom, the command runs with the remaining thermal velocities, and +then the bias is added back in. This includes thermostatting +fixes like :doc:`fix nvt `, +:doc:`fix temp/rescale `, +:doc:`fix temp/berendsen `, and +:doc:`fix langevin `, and computes like +:doc:`compute stress/atom ` and +:doc:`compute pressure `. See the input script in +examples/stress_vcm for an example of how to use the *com* keyword in +conjunction with compute stress/atom to create a stress profile of a rigid +body while removing the overall motion of the rigid body. For the *bias* keyword, *bias-ID* refers to the ID of a temperature compute that removes a "bias" velocity from each atom. This also diff --git a/doc/src/compute_vacf.rst b/doc/src/compute_vacf.rst index 704e597e18..72f675360c 100644 --- a/doc/src/compute_vacf.rst +++ b/doc/src/compute_vacf.rst @@ -76,7 +76,7 @@ Restrictions Related commands """""""""""""""" -:doc:`compute msd ` +:doc:`compute msd `, :doc:`compute vacf/chunk ` Default """"""" diff --git a/doc/src/compute_vacf_chunk.rst b/doc/src/compute_vacf_chunk.rst new file mode 100644 index 0000000000..f9d22e22a1 --- /dev/null +++ b/doc/src/compute_vacf_chunk.rst @@ -0,0 +1,124 @@ +.. index:: compute vacf/chunk + +compute vacf/chunk command +========================== + +Syntax +"""""" + +.. code-block:: LAMMPS + + compute ID group-ID vacf/chunk chunkID + +* ID, group-ID are documented in :doc:`compute ` command +* vacf/chunk = style name of this compute command +* chunkID = ID of :doc:`compute chunk/atom ` command + +Examples +"""""""" + +.. code-block:: LAMMPS + + compute 1 all vacf/chunk molchunk + +Description +""""""""""" + +.. versionadded:: TBD + +Define a computation that calculates the velocity auto-correlation +function (VACF) for multiple chunks of atoms. + +In LAMMPS, chunks are collections of atoms defined by a :doc:`compute +chunk/atom ` command, which assigns each atom to a +single chunk (or no chunk). The ID for this command is specified as +chunkID. For example, a single chunk could be the atoms in a molecule +or atoms in a spatial bin. See the :doc:`compute chunk/atom +` and :doc:`Howto chunk ` doc pages for +details of how chunks can be defined and examples of how they can be +used to measure properties of a system. + +Four quantities are calculated by this compute for each chunk. The +first 3 quantities are the product of the initial center of mass +velocity (VCM) for each chunk in *x*, *y*, and *z* direction with the +current center of mass velocity in the same direction. The fourth +component is the total VACF, i.e. the sum of the three components. + +Note that only atoms in the specified group contribute to the +calculation. The :doc:`compute chunk/atom ` command +defines its own group; atoms will have a chunk ID = 0 if they are not in +that group, signifying they are not assigned to a chunk, and will thus +also not contribute to this calculation. You can specify the "all" +group for this command if you simply want to include atoms with non-zero +chunk IDs. + +The integral of the VACF versus time is proportional to the diffusion +coefficient of the diffusing chunks. + +.. note:: + + The number of chunks *Nchunk* calculated by the + :doc:`compute chunk/atom ` command must remain constant + each time this compute is invoked, so that the dot product for each chunk + from its original position can be computed consistently. If *Nchunk* + does not remain constant, an error will be generated. If needed, you + can enforce a constant *Nchunk* by using the *nchunk once* or *ids once* + options when specifying the :doc:`compute chunk/atom ` + command. + +.. note:: + + This compute stores the original center-of-mass velocities of each + chunk. When a VACF is calculated on a later timestep, it is assumed + that the same atoms are assigned to the same chunk ID. However + LAMMPS has no simple way to ensure this is the case, though you can + use the *ids once* option when specifying the :doc:`compute + chunk/atom ` command. Note that if this is not + the case, the VACF calculation does not have a sensible meaning. + +.. note:: + + If you want the quantities calculated by this compute to be + continuous when running from a :doc:`restart file `, then + you should use the same ID for this compute, as in the original run. + This is so that the fix this compute creates to store per-chunk + quantities will also have the same ID, and thus be initialized + correctly with chunk reference positions from the restart file. + +The simplest way to output the results of the compute vacf/chunk +calculation to a file is to use the :doc:`fix ave/time ` +command, for example: + +.. code-block:: LAMMPS + + compute cc1 all chunk/atom molecule + compute myChunk all vacf/chunk cc1 + fix 1 all ave/time 100 1 100 c_myChunk[*] file tmp.out mode vector + +Output info +""""""""""" + +This compute calculates a global array where the number of rows = the +number of chunks *Nchunk* as calculated by the specified :doc:`compute +chunk/atom ` command. The number of columns = 4 for +the *x*, *y*, *z*, component and the total VACF. These values can be +accessed by any command that uses global array values from a compute as +input. See the :doc:`Howto output ` page for an overview +of LAMMPS output options. + +The array values are "intensive". The array values will be in +distance\ :math:`^2` divided by time\ :math:`^2` :doc:`units `. + +Restrictions +"""""""""""" + none + +Related commands +"""""""""""""""" + +:doc:`compute vacf `, :doc:`compute msd/chunk ` + +Default +""""""" + +none 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/fitpod_command.rst b/doc/src/fitpod_command.rst index de52e0545b..e1f2c47c60 100644 --- a/doc/src/fitpod_command.rst +++ b/doc/src/fitpod_command.rst @@ -263,10 +263,10 @@ then the globally defined weights from the ``fitting_weight_energy`` and POD Potential """"""""""""" -We consider a multi-element system of *N* atoms with :math:`N_{\rm e}` +We consider a multi-element system of *N* atoms with :math:`N_\mathrm{e}` unique elements. We denote by :math:`\boldsymbol r_n` and :math:`Z_n` position vector and type of an atom *n* in the system, -respectively. Note that we have :math:`Z_n \in \{1, \ldots, N_{\rm e} +respectively. Note that we have :math:`Z_n \in \{1, \ldots, N_\mathrm{e} \}`, :math:`\boldsymbol R = (\boldsymbol r_1, \boldsymbol r_2, \ldots, \boldsymbol r_N) \in \mathbb{R}^{3N}`, and :math:`\boldsymbol Z = (Z_1, Z_2, \ldots, Z_N) \in \mathbb{N}^{N}`. The total energy of the diff --git a/doc/src/fix.rst b/doc/src/fix.rst index 9af607601b..f024fc6974 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 @@ -340,6 +341,8 @@ accelerated styles exist. * :doc:`phonon ` - calculate dynamical matrix from MD simulations * :doc:`pimd/langevin ` - Feynman path-integral molecular dynamics with stochastic thermostat * :doc:`pimd/nvt ` - Feynman path-integral molecular dynamics with Nose-Hoover thermostat +* :doc:`pimd/langevin/bosonic ` - Bosonic Feynman path-integral molecular dynamics for with stochastic thermostat +* :doc:`pimd/nvt/bosonic ` - Bosonic Feynman path-integral molecular dynamics with Nose-Hoover thermostat * :doc:`planeforce ` - constrain atoms to move in a plane * :doc:`plumed ` - wrapper on PLUMED free energy library * :doc:`poems ` - constrain clusters of atoms to move as coupled rigid bodies diff --git a/doc/src/fix_adapt.rst b/doc/src/fix_adapt.rst index 1ddf80cbdb..34e3e450f6 100644 --- a/doc/src/fix_adapt.rst +++ b/doc/src/fix_adapt.rst @@ -236,6 +236,8 @@ formulas for the meaning of these parameters: +------------------------------------------------------------------------------+--------------------------------------------------+-------------+ | :doc:`wf/cut ` | epsilon,sigma,nu,mu | type pairs | +------------------------------------------------------------------------------+--------------------------------------------------+-------------+ +| :doc:`yukawa ` | alpha | type pairs | ++------------------------------------------------------------------------------+--------------------------------------------------+-------------+ .. note:: @@ -406,6 +408,8 @@ sub-style name. The angle styles that currently work with fix adapt are: +--------------------------------------------------------------------+--------------------+-------------+ | :doc:`mm3 ` | k,theta0 | type angles | +--------------------------------------------------------------------+--------------------+-------------+ +| :doc:`mwlc ` | k1,k2,mu,T | type angles | ++--------------------------------------------------------------------+--------------------+-------------+ | :doc:`quartic ` | k2,k3,k4,theta0 | type angles | +--------------------------------------------------------------------+--------------------+-------------+ | :doc:`spica ` | k,theta0 | type angles | diff --git a/doc/src/fix_ave_chunk.rst b/doc/src/fix_ave_chunk.rst index 76c7ec4cfc..704019d46a 100644 --- a/doc/src/fix_ave_chunk.rst +++ b/doc/src/fix_ave_chunk.rst @@ -459,8 +459,8 @@ output. This option can only be used with the *ave running* setting. The *format* keyword sets the numeric format of each value when it is printed to a file via the *file* keyword. Note that all values are -floating point quantities. The default format is %g. You can specify -a higher precision if desired (e.g., %20.16g). +floating point quantities. The default format is " %g". You can specify +a higher precision if desired (e.g., " %20.16g"). The *title1* and *title2* and *title3* keywords allow specification of the strings that will be printed as the first three lines of the output diff --git a/doc/src/fix_ave_correlate.rst b/doc/src/fix_ave_correlate.rst index 659e15105c..91f5c701aa 100644 --- a/doc/src/fix_ave_correlate.rst +++ b/doc/src/fix_ave_correlate.rst @@ -32,13 +32,14 @@ Syntax .. parsed-literal:: - *type* arg = *auto* or *upper* or *lower* or *auto/upper* or *auto/lower* or *full* + *type* arg = *auto* or *upper* or *lower* or *auto/upper* or *auto/lower* or *full* or *first* auto = correlate each value with itself upper = correlate each value with each succeeding value lower = correlate each value with each preceding value auto/upper = auto + upper auto/lower = auto + lower full = correlate each value with every other value, including itself = auto + upper + lower + first = correlate each value with the first value *ave* args = *one* or *running* one = zero the correlation accumulation every Nfreq steps running = accumulate correlations continuously @@ -257,6 +258,9 @@ time. * If *type* is set to *full* then each input value is correlated with itself and every other value (i.e., :math:`C_{ij} = V_i V_j` for :math:`\{i,j\} = \{1,N\}`, so :math:`N_\text{pair} = N^2`). +* If *type* is set to *first* then each input value is correlated with + the first input value (i.e., :math:`C_{ij} = V_1 V_j` for + :math:`\{j\} = \{1,N\}`, so :math:`N_\text{pair} = N`). The *ave* keyword determines what happens to the accumulation of correlation samples every :math:`N_\text{freq}` timesteps. If the *ave* setting is *one*, @@ -369,6 +373,8 @@ above. * For *type* = *full*, the :math:`N_\text{pair} = N^2` columns are ordered: :math:`C_{11}, C_{12}, \dotsc, C_{1N}, C_{21}, C_{22}, \dotsc, C_{2N}, C_{31}, \dotsc, C_{3N}, \dotsc, C_{N1}, \dotsc, C_{N,N-1}, C_{NN}` +* For *type* = *first*, the :math:`N_\text{pair} = N` columns are ordered: + :math:`C_{11}, C_{12}, \dotsc, C_{1N}` The array values calculated by this fix are treated as extensive. If you need to divide them by the number of atoms, you must do this in a diff --git a/doc/src/fix_ave_correlate_long.rst b/doc/src/fix_ave_correlate_long.rst index 003bdf897d..22fac89706 100644 --- a/doc/src/fix_ave_correlate_long.rst +++ b/doc/src/fix_ave_correlate_long.rst @@ -31,13 +31,14 @@ Syntax .. parsed-literal:: - *type* arg = *auto* or *upper* or *lower* or *auto/upper* or *auto/lower* or *full* + *type* arg = *auto* or *upper* or *lower* or *auto/upper* or *auto/lower* or *full* or *first* auto = correlate each value with itself upper = correlate each value with each succeeding value lower = correlate each value with each preceding value auto/upper = auto + upper auto/lower = auto + lower full = correlate each value with every other value, including itself = auto + upper + lower + first = correlate each value with the first value *start* args = Nstart Nstart = start accumulating correlations on this time step *file* arg = filename diff --git a/doc/src/fix_ave_time.rst b/doc/src/fix_ave_time.rst index 00771a1422..661ea2d466 100644 --- a/doc/src/fix_ave_time.rst +++ b/doc/src/fix_ave_time.rst @@ -304,8 +304,8 @@ output. This option can only be used with the *ave running* setting. The *format* keyword sets the numeric format of each value when it is printed to a file via the *file* keyword. Note that all values are -floating point quantities. The default format is %g. You can specify -a higher precision if desired (e.g., %20.16g). +floating point quantities. The default format is " %g". You can specify +a higher precision if desired (e.g., " %20.16g"). The *title1* and *title2* and *title3* keywords allow specification of the strings that will be printed as the first 2 or 3 lines of the 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_eos_table_rx.rst b/doc/src/fix_eos_table_rx.rst index 104fa79c20..df95b736df 100644 --- a/doc/src/fix_eos_table_rx.rst +++ b/doc/src/fix_eos_table_rx.rst @@ -49,7 +49,7 @@ computed according to the following relation: where *m* is the number of species, :math:`c_{i,j}` is the concentration of species *j* in particle *i*, :math:`u_j` is the -internal energy of species j, :math:`\Delta H_{f,j} is the heat of +internal energy of species j, :math:`\Delta H_{f,j}` is the heat of formation of species *j*, N is the number of molecules represented by the coarse-grained particle, :math:`k_B` is the Boltzmann constant, and :math:`T` is the temperature of the system. Additionally, it is diff --git a/doc/src/fix_gld.rst b/doc/src/fix_gld.rst index ba26f7a51b..8c24275cb4 100644 --- a/doc/src/fix_gld.rst +++ b/doc/src/fix_gld.rst @@ -60,9 +60,9 @@ With this fix active, the force on the *j*\ th atom is given as .. math:: - {\bf F}_{j}(t) = & {\bf F}^C_j(t)-\int \limits_{0}^{t} \Gamma_j(t-s) {\bf v}_j(s)~\text{d}s + {\bf F}^R_j(t) \\ + \mathbf{F}_{j}(t) = & \mathbf{F}^C_j(t)-\int \limits_{0}^{t} \Gamma_j(t-s) \mathbf{v}_j(s)~\text{d}s + \mathbf{F}^R_j(t) \\ \Gamma_j(t-s) = & \sum \limits_{k=1}^{N_k} \frac{c_k}{\tau_k} e^{-(t-s)/\tau_k} \\ - \langle{\bf F}^R_j(t),{\bf F}^R_j(s)\rangle = & \text{k$_\text{B}$T} ~\Gamma_j(t-s) + \langle\mathbf{F}^R_j(t),\mathbf{F}^R_j(s)\rangle = & \text{k$_\text{B}$T} ~\Gamma_j(t-s) Here, the first term is representative of all conservative (pairwise, bonded, etc) forces external to this fix, the second is the temporally diff --git a/doc/src/fix_halt.rst b/doc/src/fix_halt.rst index 0bcf2fb5ea..e2f74eae77 100644 --- a/doc/src/fix_halt.rst +++ b/doc/src/fix_halt.rst @@ -25,13 +25,14 @@ Syntax * operator = "<" or "<=" or ">" or ">=" or "==" or "!=" or "\|\^" * avalue = numeric value to compare attribute to * zero or more keyword/value pairs may be appended -* keyword = *error* or *message* or *path* +* keyword = *error* or *message* or *path* or *universe* .. parsed-literal:: *error* value = *hard* or *soft* or *continue* *message* value = *yes* or *no* *path* value = path to check for free space (may be in quotes) + *universe* value = *yes* or *no* Examples @@ -40,8 +41,10 @@ Examples .. code-block:: LAMMPS fix 10 all halt 1 bondmax > 1.5 - fix 10 all halt 10 v_myCheck != 0 error soft + fix 10 all halt 10 v_myCheck != 0 error soft message no fix 10 all halt 100 diskfree < 100000.0 path "dump storage/." + fix 2 all halt 100 v_curtime > ${maxtime} universe yes + Description """"""""""" @@ -141,33 +144,52 @@ The optional *error* keyword determines how the current run is halted. If its value is *hard*, then LAMMPS will stop with an error message. If its value is *soft*, LAMMPS will exit the current run, but continue -to execute subsequent commands in the input script. However, -additional :doc:`run ` or :doc:`minimize ` commands will be -skipped. For example, this allows a script to output the current -state of the system, e.g. via a :doc:`write_dump ` or -:doc:`write_restart ` command. +to execute subsequent commands in the input script. However, additional +:doc:`run ` or :doc:`minimize ` commands will be skipped. +For example, this allows a script to output the current state of the +system, e.g. via a :doc:`write_dump ` or :doc:`write_restart +` command. To re-enable regular runs after *fix halt* +stopped a run, you need to issue a :doc:`timer timeout unlimited +` command. If its value is *continue*, the behavior is the same as for *soft*, except subsequent :doc:`run ` or :doc:`minimize ` commands are executed. This allows your script to remedy the condition that -triggered the halt, if necessary. Note that you may wish use the -:doc:`unfix ` command on the fix halt ID, so that the same -condition is not immediately triggered in a subsequent run. +triggered the halt, if necessary. This is the equivalent of stopping +with *error soft* and followed by :doc:`timer timeout unlimited +` command. This can have undesired consequences, when a +:doc:`run command ` uses the *every* keyword, so using *error soft* +and resetting the timer manually may be the preferred option. + +You may wish use the :doc:`unfix ` command on the *fix halt* ID +before starting a subsequent run, so that the same condition is not +immediately triggered again. The optional *message* keyword determines whether a message is printed to the screen and logfile when the halt condition is triggered. If *message* is set to yes, a one line message with the values that -triggered the halt is printed. If *message* is set to no, no message -is printed; the run simply exits. The latter may be desirable for +triggered the halt is printed. If *message* is set to no, no message is +printed; the run simply exits. The latter may be desirable for post-processing tools that extract thermodynamic information from log files. +.. versionadded:: TBD + +The optional *universe* keyword determines whether the halt request +should be synchronized across the partitions of a :doc:`multi-partition +run `. If *universe* is set to yes, fix halt will check if +there is a specific message received from any of the other partitions +requesting to stop the run on this partition as well. Consequently, if +fix halt determines to halt the simulation, the fix will send messages +to all other partitions so they stop their runs, too. + 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 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. @@ -183,4 +205,4 @@ Related commands Default """"""" -The option defaults are error = soft, message = yes, and path = ".". +The option defaults are error = soft, message = yes, path = ".", and universe = no. diff --git a/doc/src/fix_hyper_global.rst b/doc/src/fix_hyper_global.rst index f58c4780b0..9eae426098 100644 --- a/doc/src/fix_hyper_global.rst +++ b/doc/src/fix_hyper_global.rst @@ -131,14 +131,15 @@ timesteps is simply t_{hyper} = \sum_{i=1,N} B-i \cdot dt where *dt* is the timestep size defined by the :doc:`timestep ` -command. The effective time acceleration due to GHD is thus t_hyper / -N\*dt, where N\*dt is elapsed time for a normal MD run of N timesteps. +command. The effective time acceleration due to GHD is thus +:math:`t_{hyper} / N * dt`, where N\*dt is elapsed time for a normal MD run +of N timesteps. -Note that in GHD, the boost factor varies from timestep to timestep. -Likewise, which bond has :math:`E^{max}` strain and thus which pair of -atoms the bias potential is added to, will also vary from timestep to timestep. -This is in contrast to local hyperdynamics (LHD) where the boost -factor is an input parameter; see the :doc:`fix hyper/local ` page for details. +Note that in GHD, the boost factor varies from timestep to timestep. Likewise, +which bond has :math:`E^{max}` strain and thus which pair of atoms the bias +potential is added to, will also vary from timestep to timestep. This is in +contrast to local hyperdynamics (LHD) where the boost factor is an input +parameter; see the :doc:`fix hyper/local ` page for details. ---------- @@ -178,7 +179,7 @@ time-accurate trajectory of the system. Note that if *Vmax* is set too small, the GHD simulation will run correctly. There will just be fewer events because the hyper time -(t_hyper equation above) will be shorter. +(:math:`t_{hyper}` equation above) will be shorter. .. note:: diff --git a/doc/src/fix_hyper_local.rst b/doc/src/fix_hyper_local.rst index 499a12b9bc..46d73daa66 100644 --- a/doc/src/fix_hyper_local.rst +++ b/doc/src/fix_hyper_local.rst @@ -111,7 +111,7 @@ requirement, and thus a bias potential :math:`V^{max}_{ij}` will be applied to many bonds on the same timestep. In LHD, all bonds store a :math:`C_{ij}` prefactor which appears in -the :math:`V^{max}_{ij}` and :math:`F^{max}_{ij}equations above. Note +the :math:`V^{max}_{ij}` and :math:`F^{max}_{ij}` equations above. Note that the :math:`C_{ij}` factor scales the strength of the bias energy and forces whenever bond *ij* is the maximum strain bond in its neighborhood. @@ -269,7 +269,7 @@ inverse of the alpha parameter discussed in The *Btarget* argument is the desired time boost factor (a value > 1) that all the atoms in the system will experience. The elapsed time -t_hyper for an LHD simulation running for *N* timesteps is simply +:math:`t_{hyper}` for an LHD simulation running for *N* timesteps is simply .. math:: @@ -294,7 +294,7 @@ is the specified temperature of the system Note that if *Btarget* is set smaller than this, the LHD simulation will run correctly. There will just be fewer events because the hyper -time (t_hyper equation above) will be shorter. +time (:math:`t_{hyper}` equation above) will be shorter. .. note:: diff --git a/doc/src/fix_imd.rst b/doc/src/fix_imd.rst index 2974262c81..d85ebc8d34 100644 --- a/doc/src/fix_imd.rst +++ b/doc/src/fix_imd.rst @@ -26,6 +26,29 @@ Syntax *nowait* arg = *on* or *off* off = LAMMPS waits to be connected to an IMD client before continuing (default) on = LAMMPS listens for an IMD client, but continues with the run + *version* arg = *2* or *3* + 2 = use IMD protocol version 2 (default) + 3 = use IMD protocol version 3. + + The following keywords are only supported for IMD protocol version 3. + + .. parsed-literal:: + + *time* arg = *on* or *off* + off = simulation time is not transmitted (default) + on = simulation time is transmitted. + *box* arg = *on* or *off* + off = simulation box data is not transmitted (default) + on = simulation box data is transmitted. + *coordinates* arg = *on* or *off* + off = atomic coordinates are not transmitted (default) + on = atomic coordinates are transmitted. + *velocities* arg = *on* or *off* + off = atomic velocities are not transmitted (default) + on = atomic velocities are transmitted. + *forces* arg = *on* or *off* + off = atomic forces are not transmitted (default) + on = atomic forces are transmitted. Examples """""""" @@ -40,16 +63,19 @@ Description This fix implements the "Interactive MD" (IMD) protocol which allows realtime visualization and manipulation of MD simulations through the -IMD protocol, as initially implemented in VMD and NAMD. Specifically -it allows LAMMPS to connect an IMD client, for example the `VMD visualization program `_, so that it can monitor the progress of the -simulation and interactively apply forces to selected atoms. +IMD protocol, as initially implemented in VMD and NAMD. Specifically it +allows LAMMPS to connect an IMD client, for example the `VMD +visualization program `_ (currently only supports IMDv2) or the +`Python IMDClient `_ (supports both IMDv2 and IMDv3), so +that it can monitor the progress of the simulation and interactively +apply forces to selected atoms. -If LAMMPS is compiled with the pre-processor flag -DLAMMPS_ASYNC_IMD -then fix imd will use POSIX threads to spawn a IMD communication -thread on MPI rank 0 in order to offload data reading and writing -from the main execution thread and potentially lower the inferred -latencies for slow communication links. This feature has only been -tested under linux. +If LAMMPS is compiled with the pre-processor flag +:ref:`-DLAMMPS_ASYNC_IMD ` then fix imd will use POSIX threads to +spawn an IMD communication thread on MPI rank 0 in order to offload data +exchange with the IMD client from the main execution thread and +potentially lower the inferred latencies for slow communication +links. This feature has only been tested under linux. The source code for this fix includes code developed by the Theoretical and Computational Biophysics Group in the Beckman Institute for Advanced @@ -94,6 +120,15 @@ 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:: 4Feb2025 + +In `IMDv3 `_, the IMD protocol has been extended to allow for +the transmission of simulation time, box dimensions, atomic coordinates, +velocities, and forces. The *version* keyword allows to select the +version of the protocol to be used. The *time*, *box*, *coordinates*, +*velocities*, and *forces* keywords allow to select which data is +transmitted to the IMD client. The default is to transmit all data. + To connect VMD to a listening LAMMPS simulation on the same machine with fix imd enabled, one needs to start VMD and load a coordinate or topology file that matches the fix group. When the VMD command @@ -129,6 +164,10 @@ screen output is active. .. _imdvmd: https://www.ks.uiuc.edu/Research/vmd/imd/ +.. _IMDClient: https://github.com/Becksteinlab/imdclient/tree/main/imdclient + +.. _IMDv3: https://imdclient.readthedocs.io/en/latest/protocol_v3.html + Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -147,14 +186,14 @@ This fix is part of the MISC package. It is only enabled if LAMMPS was built with that package. See the :doc:`Build package ` page for more info. -When used in combination with VMD, a topology or coordinate file has -to be loaded, which matches (in number and ordering of atoms) the -group the fix is applied to. The fix internally sorts atom IDs by -ascending integer value; in VMD (and thus the IMD protocol) those will -be assigned 0-based consecutive index numbers. +When used in combination with VMD, a topology or coordinate file has to +be loaded, which matches (in number and ordering of atoms) the group the +fix is applied to. The fix internally sorts atom IDs by ascending +integer value; in VMD (and thus the IMD protocol) those will be assigned +0-based consecutive index numbers. When using multiple active IMD connections at the same time, each -needs to use a different port number. +fix instance needs to use a different port number. Related commands """""""""""""""" diff --git a/doc/src/fix_lb_fluid.rst b/doc/src/fix_lb_fluid.rst index a461175f71..e49831986b 100644 --- a/doc/src/fix_lb_fluid.rst +++ b/doc/src/fix_lb_fluid.rst @@ -130,7 +130,7 @@ calculated as: .. math:: - {\bf F}_{j \alpha} = \gamma \left({\bf v}_n - {\bf u}_f \right) \zeta_{j\alpha} + \mathbf{F}_{j \alpha} = \gamma \left(\mathbf{v}_n - \mathbf{u}_f \right) \zeta_{j\alpha} where :math:`\mathbf{v}_n` is the velocity of the MD particle, :math:`\mathbf{u}_f` is the fluid velocity interpolated to the particle diff --git a/doc/src/fix_move.rst b/doc/src/fix_move.rst index 3fde5f0861..bce6f7046e 100644 --- a/doc/src/fix_move.rst +++ b/doc/src/fix_move.rst @@ -35,11 +35,12 @@ Syntax v_vx,v_vy,v_vz = 3 variable names that calculate x,y,z velocity as function of time, any component can be specified as NULL * zero or more keyword/value pairs may be appended -* keyword = *units* +* keyword = *units* or *update* .. parsed-literal:: *units* value = *box* or *lattice* + *update* value = *dipole* Examples """""""" @@ -49,7 +50,7 @@ Examples fix 1 boundary move wiggle 3.0 0.0 0.0 1.0 units box fix 2 boundary move rotate 0.0 0.0 0.0 0.0 0.0 1.0 5.0 fix 2 boundary move variable v_myx v_myy NULL v_VX v_VY NULL - fix 3 boundary move transrot 0.1 0.1 0.0 0.0 0.0 0.0 0.0 0.0 1.0 5.0 units box + fix 3 boundary move transrot 0.1 0.1 0.0 0.0 0.0 0.0 0.0 0.0 1.0 5.0 units box update dipole Description """"""""""" @@ -217,6 +218,15 @@ been previously used to define the lattice spacing. Each of these 3 quantities may be dependent on the x,y,z dimension, since the lattice spacings can be different in x,y,z. +.. versionadded:: TBD + +If the *update dipole* keyword/value pair is used together with the +*rotate* or *transrot* style, then the orientation of the dipole moment +of each particle is also updated appropriately to correspond with the rotation. +This option should be used for models where a dipole moment is assigned to +finite-size particles, e.g. spheroids via use of the :doc:`atom_style hybrid +sphere dipole ` command. + ---------- Restart, fix_modify, output, run start/stop, minimize info diff --git a/doc/src/fix_neb.rst b/doc/src/fix_neb.rst index 51066675b8..0dbf4f5a18 100644 --- a/doc/src/fix_neb.rst +++ b/doc/src/fix_neb.rst @@ -180,7 +180,7 @@ force is added. By default, no additional forces act on the first and last replicas during the NEB relaxation, so these replicas simply relax toward their -respective local minima. By using the key word *end*, additional forces +respective local minima. By using the keyword *end*, additional forces can be applied to the first and/or last replicas, to enable them to relax toward a MEP while constraining their energy E to the target energy ETarget. diff --git a/doc/src/fix_nh.rst b/doc/src/fix_nh.rst index 0cfbc8f921..0a4076364c 100644 --- a/doc/src/fix_nh.rst +++ b/doc/src/fix_nh.rst @@ -208,19 +208,19 @@ The relaxation rate of the barostat is set by its inertia :math:`W`: .. math:: - W = (N + 1) k_B T_{\rm target} P_{\rm damp}^2 + W = (N + 1) k_B T_\mathrm{target} P_\mathrm{damp}^2 where :math:`N` is the number of atoms, :math:`k_B` is the Boltzmann constant, -and :math:`T_{\rm target}` is the target temperature of the barostat :ref:`(Martyna) `. -If a thermostat is defined, :math:`T_{\rm target}` is the target temperature -of the thermostat. If a thermostat is not defined, :math:`T_{\rm target}` +and :math:`T_\mathrm{target}` is the target temperature of the barostat :ref:`(Martyna) `. +If a thermostat is defined, :math:`T_\mathrm{target}` is the target temperature +of the thermostat. If a thermostat is not defined, :math:`T_\mathrm{target}` is set to the current temperature of the system when the barostat is initialized. If this temperature is too low the simulation will quit with an error. -Note: in previous versions of LAMMPS, :math:`T_{\rm target}` would default to +Note: in previous versions of LAMMPS, :math:`T_\mathrm{target}` would default to a value of 1.0 for *lj* units and 300.0 otherwise if the system had a temperature of exactly zero. -If a thermostat is not specified by this fix, :math:`T_{\rm target}` can be +If a thermostat is not specified by this fix, :math:`T_\mathrm{target}` can be manually specified using the *Ptemp* parameter. This may be useful if the barostat is initialized when the current temperature does not reflect the steady state temperature of the system. This keyword may also be useful in @@ -512,8 +512,8 @@ according to the following factorization of the Liouville propagator .. math:: \exp \left(\mathrm{i} L \Delta t \right) = & \hat{E} - \exp \left(\mathrm{i} L_{\rm T\textrm{-}baro} \frac{\Delta t}{2} \right) - \exp \left(\mathrm{i} L_{\rm T\textrm{-}part} \frac{\Delta t}{2} \right) + \exp \left(\mathrm{i} L_\mathrm{T\textrm{-}baro} \frac{\Delta t}{2} \right) + \exp \left(\mathrm{i} L_\mathrm{T\textrm{-}part} \frac{\Delta t}{2} \right) \exp \left(\mathrm{i} L_{\epsilon , 2} \frac{\Delta t}{2} \right) \exp \left(\mathrm{i} L_{2}^{(2)} \frac{\Delta t}{2} \right) \\ &\times \left[ @@ -526,8 +526,8 @@ according to the following factorization of the Liouville propagator &\times \exp \left(\mathrm{i} L_{2}^{(2)} \frac{\Delta t}{2} \right) \exp \left(\mathrm{i} L_{\epsilon , 2} \frac{\Delta t}{2} \right) - \exp \left(\mathrm{i} L_{\rm T\textrm{-}part} \frac{\Delta t}{2} \right) - \exp \left(\mathrm{i} L_{\rm T\textrm{-}baro} \frac{\Delta t}{2} \right) \\ + \exp \left(\mathrm{i} L_\mathrm{T\textrm{-}part} \frac{\Delta t}{2} \right) + \exp \left(\mathrm{i} L_\mathrm{T\textrm{-}baro} \frac{\Delta t}{2} \right) \\ &+ \mathcal{O} \left(\Delta t^3 \right) This factorization differs somewhat from that of Tuckerman et al, in diff --git a/doc/src/fix_npt_cauchy.rst b/doc/src/fix_npt_cauchy.rst index 6764f88eee..862a0b546e 100644 --- a/doc/src/fix_npt_cauchy.rst +++ b/doc/src/fix_npt_cauchy.rst @@ -426,8 +426,8 @@ according to the following factorization of the Liouville propagator .. math:: \exp \left(\mathrm{i} L \Delta t \right) = & \hat{E} - \exp \left(\mathrm{i} L_{\rm T\textrm{-}baro} \frac{\Delta t}{2} \right) - \exp \left(\mathrm{i} L_{\rm T\textrm{-}part} \frac{\Delta t}{2} \right) + \exp \left(\mathrm{i} L_\mathrm{T\textrm{-}baro} \frac{\Delta t}{2} \right) + \exp \left(\mathrm{i} L_\mathrm{T\textrm{-}part} \frac{\Delta t}{2} \right) \exp \left(\mathrm{i} L_{\epsilon , 2} \frac{\Delta t}{2} \right) \exp \left(\mathrm{i} L_{2}^{(2)} \frac{\Delta t}{2} \right) \\ &\times \left[ @@ -440,8 +440,8 @@ according to the following factorization of the Liouville propagator &\times \exp \left(\mathrm{i} L_{2}^{(2)} \frac{\Delta t}{2} \right) \exp \left(\mathrm{i} L_{\epsilon , 2} \frac{\Delta t}{2} \right) - \exp \left(\mathrm{i} L_{\rm T\textrm{-}part} \frac{\Delta t}{2} \right) - \exp \left(\mathrm{i} L_{\rm T\textrm{-}baro} \frac{\Delta t}{2} \right) \\ + \exp \left(\mathrm{i} L_\mathrm{T\textrm{-}part} \frac{\Delta t}{2} \right) + \exp \left(\mathrm{i} L_\mathrm{T\textrm{-}baro} \frac{\Delta t}{2} \right) \\ &+ \mathcal{O} \left(\Delta t^3 \right) This factorization differs somewhat from that of Tuckerman et al, in diff --git a/doc/src/fix_orient.rst b/doc/src/fix_orient.rst index 7e30b7bb01..881ae6c45c 100644 --- a/doc/src/fix_orient.rst +++ b/doc/src/fix_orient.rst @@ -62,19 +62,19 @@ The potential energy added to atom I is given by these formulas .. math:: - \xi_{i} = & \sum_{j=1}^{12} \left| \mathbf{r}_{j} - \mathbf{r}_{j}^{\rm I} \right| \qquad\qquad\left(1\right) \\ + \xi_{i} = & \sum_{j=1}^{12} \left| \mathbf{r}_{j} - \mathbf{r}_{j}^\mathrm{I} \right| \qquad\qquad\left(1\right) \\ \\ - \xi_{\rm IJ} = & \sum_{j=1}^{12} \left| \mathbf{r}_{j}^{\rm J} - \mathbf{r}_{j}^{\rm I} \right| \qquad\qquad\left(2\right)\\ + \xi_\mathrm{IJ} = & \sum_{j=1}^{12} \left| \mathbf{r}_{j}^\mathrm{J} - \mathbf{r}_{j}^\mathrm{I} \right| \qquad\qquad\left(2\right)\\ \\ - \xi_{\rm low} = & {\rm cutlo} \, \xi_{\rm IJ} \qquad\qquad\qquad\left(3\right)\\ - \xi_{\rm high} = & {\rm cuthi} \, \xi_{\rm IJ} \qquad\qquad\qquad\left(4\right) \\ + \xi_\mathrm{low} = & \mathrm{cutlo} \, \xi_\mathrm{IJ} \qquad\qquad\qquad\left(3\right)\\ + \xi_\mathrm{high} = & \mathrm{cuthi} \, \xi_\mathrm{IJ} \qquad\qquad\qquad\left(4\right) \\ \\ - \omega_{i} = & \frac{\pi}{2} \frac{\xi_{i} - \xi_{\rm low}}{\xi_{\rm high} - \xi_{\rm low}} \qquad\qquad\left(5\right)\\ + \omega_{i} = & \frac{\pi}{2} \frac{\xi_{i} - \xi_\mathrm{low}}{\xi_\mathrm{high} - \xi_\mathrm{low}} \qquad\qquad\left(5\right)\\ \\ - u_{i} = & 0 \quad\quad\qquad\qquad\qquad \textrm{ for } \qquad \xi_{i} < \xi_{\rm low}\\ - = & {\rm dE}\,\frac{1 - \cos(2 \omega_{i})}{2} - \qquad \mathrm{ for }\qquad \xi_{\rm low} < \xi_{i} < \xi_{\rm high} \quad \left(6\right) \\ - = & {\rm dE} \quad\qquad\qquad\qquad\textrm{ for } \qquad \xi_{\rm high} < \xi_{i} + u_{i} = & 0 \quad\quad\qquad\qquad\qquad \textrm{ for } \qquad \xi_{i} < \xi_\mathrm{low}\\ + = & \mathrm{dE}\,\frac{1 - \cos(2 \omega_{i})}{2} + \qquad \mathrm{for }\qquad \xi_\mathrm{low} < \xi_{i} < \xi_\mathrm{high} \quad \left(6\right) \\ + = & \mathrm{dE} \quad\qquad\qquad\qquad\textrm{ for } \qquad \xi_\mathrm{high} < \xi_{i} which are fully explained in :ref:`(Janssens) `. For fcc crystals this order parameter Xi for atom I in equation (1) is a sum over the diff --git a/doc/src/fix_pimd.rst b/doc/src/fix_pimd.rst index 0c7f763ced..2ba0d384fd 100644 --- a/doc/src/fix_pimd.rst +++ b/doc/src/fix_pimd.rst @@ -1,5 +1,7 @@ .. index:: fix pimd/langevin .. index:: fix pimd/nvt +.. index:: fix pimd/langevin/bosonic +.. index:: fix pimd/nvt/bosonic fix pimd/langevin command ========================= @@ -7,6 +9,12 @@ fix pimd/langevin command fix pimd/nvt command ==================== +fix pimd/langevin/bosonic command +================================= + +fix pimd/nvt/bosonic command +============================ + Syntax """""" @@ -15,39 +23,42 @@ Syntax fix ID group-ID style keyword value ... * ID, group-ID are documented in :doc:`fix ` command -* style = *pimd/langevin* or *pimd/nvt* = style name of this fix command +* style = *pimd/langevin* or *pimd/nvt* or *pimd/langevin/bosonic* or *pimd/nvt/bosonic* = style name of this fix command * zero or more keyword/value pairs may be appended * keywords for style *pimd/nvt* .. parsed-literal:: - *keywords* = *method* or *fmass* or *sp* or *temp* or *nhc* - *method* value = *pimd* or *nmpimd* or *cmd* - *fmass* value = scaling factor on mass - *sp* value = scaling factor on Planck constant - *temp* value = temperature (temperature units) - *nhc* value = Nc = number of chains in Nose-Hoover thermostat + + *keywords* = *method* or *fmass* or *sp* or *temp* or *nhc* + *method* value = *pimd* or *nmpimd* or *cmd* + *fmass* value = scaling factor on mass + *sp* value = scaling factor on Planck constant + *temp* value = temperature (temperature units) + *nhc* value = Nc = number of chains in Nose-Hoover thermostat * keywords for style *pimd/langevin* .. parsed-literal:: - *keywords* = *method* or *integrator* or *ensemble* or *fmmode* or *fmass* or *scale* or *temp* or *thermostat* or *tau* or *iso* or *aniso* or *barostat* or *taup* or *fixcom* or *lj* - *method* value = *nmpimd* (default) or *pimd* - *integrator* value = *obabo* or *baoab* - *fmmode* value = *physical* or *normal* - *fmass* value = scaling factor on mass - *temp* value = temperature (temperature unit) + + *keywords* = *method* or *integrator* or *ensemble* or *fmmode* or *fmass* or *scale* or *temp* or *thermostat* or *tau* or *iso* or *aniso* or *barostat* or *taup* or *fixcom* or *lj* + *method* value = *nmpimd* (default) or *pimd* + *integrator* value = *obabo* or *baoab* + *ensemble* value = *nvt* or *nve* or *nph* or *npt* + *fmmode* value = *physical* or *normal* + *fmass* value = scaling factor on mass + *temp* value = temperature (temperature unit) temperature = target temperature of the thermostat - *thermostat* values = style seed + *thermostat* values = style seed style value = *PILE_L* seed = random number generator seed - *tau* value = thermostat damping parameter (time unit) - *scale* value = scaling factor of the damping times of non-centroid modes of PILE_L thermostat - *iso* or *aniso* values = pressure (pressure unit) + *tau* value = thermostat damping parameter (time unit) + *scale* value = scaling factor of the damping times of non-centroid modes of PILE_L thermostat + *iso* or *aniso* values = pressure (pressure unit) pressure = scalar external pressure of the barostat - *barostat* value = *BZP* or *MTTK* - *taup* value = barostat damping parameter (time unit) - *fixcom* value = *yes* or *no* - *lj* values = epsilon sigma mass planck mvv2e + *barostat* value = *BZP* or *MTTK* + *taup* value = barostat damping parameter (time unit) + *fixcom* value = *yes* or *no* + *lj* values = epsilon sigma mass planck mvv2e epsilon = energy scale for reduced units (energy units) sigma = length scale for reduced units (length units) mass = mass scale for reduced units (mass units) @@ -62,6 +73,8 @@ Examples fix 1 all pimd/nvt method nmpimd fmass 1.0 sp 2.0 temp 300.0 nhc 4 fix 1 all pimd/langevin ensemble npt integrator obabo temp 113.15 thermostat PILE_L 1234 tau 1.0 iso 1.0 barostat BZP taup 1.0 +Example input files are provided in the examples/PACKAGES/pimd directory. + Description """"""""""" @@ -76,12 +89,20 @@ partition function for the original system to a classical partition function for a ring-polymer system is exploited, to efficiently sample configurations from the canonical ensemble :ref:`(Feynman) `. -The classical partition function and its components are given +.. versionadded:: TBD + + Fix *pimd/langevin/bosonic* and *pimd/nvt/bosonic* were added. + +Fix *pimd/nvt* and fix *pimd/langevin* simulate *distinguishable* quantum particles. +Simulations of bosons, including exchange effects, are supported with the +fix *pimd/langevin/bosonic* and the *pimd/nvt/bosonic* commands. + +For distinguishable particles, the isomorphic classical partition function and its components are given by the following equations: .. math:: - Z = & \int d{\bf q} d{\bf p} \cdot \textrm{exp} [ -\beta H_{eff} ] \\ + Z = & \int d\mathbf{q} d\mathbf{p} \cdot \textrm{exp} [ -\beta H_{eff} ] \\ H_{eff} = & \bigg(\sum_{i=1}^P \frac{p_i^2}{2M_i}\bigg) + V_{eff} \\ V_{eff} = & \sum_{i=1}^P \bigg[ \frac{mP}{2\beta^2 \hbar^2} (q_i - q_{i+1})^2 + \frac{1}{P} V(q_i)\bigg] @@ -153,15 +174,17 @@ normal-mode PIMD. A value of *cmd* is for centroid molecular dynamics Mode *pimd* added to fix pimd/langevin. -Fix pimd/langevin supports the *method* values *nmpimd* and *pimd*. The default value is *nmpimd*. -If *method* is *nmpimd*, the normal mode representation is used to integrate the equations of motion. -The exact solution of harmonic oscillator is used to propagate the free ring polymer part of the Hamiltonian. -If *method* is *pimd*, the Cartesian representation is used to integrate the equations of motion. -The harmonic force is added to the total force of the system, and the numerical integrator is used to propagate the Hamiltonian. +Fix pimd/langevin supports the *method* values *nmpimd* and *pimd*. The default +value is *nmpimd*. If *method* is *nmpimd*, the normal mode representation is +used to integrate the equations of motion. The exact solution of harmonic +oscillator is used to propagate the free ring polymer part of the Hamiltonian. +If *method* is *pimd*, the Cartesian representation is used to integrate the +equations of motion. The harmonic force is added to the total force of the +system, and the numerical integrator is used to propagate the Hamiltonian. -The keyword *integrator* specifies the Trotter splitting method used by *fix pimd/langevin*. -See :ref:`(Liu) ` for a discussion on the OBABO and BAOAB splitting schemes. Typically -either of the two should work fine. +The keyword *integrator* specifies the Trotter splitting method used by *fix +pimd/langevin*. See :ref:`(Liu) ` for a discussion on the OBABO and BAOAB +splitting schemes. Typically either of the two should work fine. The keyword *fmass* sets a further scaling factor for the fictitious masses of beads, which can be used for the Partial Adiabatic CMD @@ -211,8 +234,8 @@ a positive floating-point number. For pimd simulations, a temperature values should be specified even for nve ensemble. Temperature will make a difference for nve pimd, since the spring elastic frequency between the beads will be affected by the temperature. -The keyword *thermostat* reads *style* and *seed* of thermostat for fix style *pimd/langevin*. *style* can only -be *PILE_L* (path integral Langevin equation local thermostat, as described in :ref:`Ceriotti `), and *seed* should a positive integer number, which serves as the seed of the pseudo random number generator. +The keyword *thermostat* reads *style* and *seed* of thermostat for fix style *pimd/langevin*. +*style* can only be *PILE_L* (path integral Langevin equation local thermostat, as described in :ref:`Ceriotti `), and *seed* should a positive integer number, which serves as the seed of the pseudo random number generator. .. note:: @@ -222,7 +245,7 @@ be *PILE_L* (path integral Langevin equation local thermostat, as described in : The keyword *tau* specifies the thermostat damping time parameter for fix style *pimd/langevin*. It is in time unit. It only works on the centroid mode. The keyword *scale* specifies a scaling parameter for the damping times of the non-centroid modes for fix style *pimd/langevin*. The default -damping time of the non-centroid mode :math:`i` is :math:`\frac{P}{\beta\hbar}\sqrt{\lambda_i\times\mathrm{fmass}}` (*fmmode* is *physical*) or :math:`\frac{P}{\beta\hbar}\sqrt{\mathrm{fmass}}` (*fmmode* is *normal*). The damping times of all non-centroid modes are the default values divided by *scale*. +damping time of the non-centroid mode :math:`i` is :math:`\frac{P}{\beta\hbar}\sqrt{\lambda_i\times\mathrm{fmass}}` (*fmmode* is *physical*) or :math:`\frac{P}{\beta\hbar}\sqrt{\mathrm{fmass}}` (*fmmode* is *normal*). The damping times of all non-centroid modes are the default values divided by *scale*. This keyword should be used only with *method*=*nmpimd*. The barostat parameters for fix style *pimd/langevin* with *npt* or *nph* ensemble is specified using one of *iso* and *aniso* keywords. A *pressure* value should be given with pressure unit. The keyword *iso* means couple all 3 diagonal components together when pressure is computed (hydrostatic pressure), and dilate/contract the dimensions together. The keyword *aniso* means x, y, and z dimensions are controlled independently using the Pxx, Pyy, and Pzz components of the stress tensor as the driving forces, and the specified scalar external pressure. @@ -334,8 +357,8 @@ it outputs multiple log files, and different log files contain information about different beads or modes (see detailed explanations below). If *ensemble* is *nve* or *nvt*, the vector has 10 values: - #. kinetic energy of the normal mode - #. spring elastic energy of the normal mode + #. kinetic energy of the bead (if *method*=*pimd*) or normal mode (if *method*=*nmpimd*) + #. spring elastic energy of the bead (if *method*=*pimd*) or normal mode (if *method*=*nmpimd*) #. potential energy of the bead #. total energy of all beads (conserved if *ensemble* is *nve*) #. primitive kinetic energy estimator @@ -398,7 +421,12 @@ LAMMPS was built with that package. See the :doc:`Build package ` page for more info. Fix *pimd/nvt* cannot be used with :doc:`lj units `. -Fix *pimd/langevin* can be used with :doc:`lj units `. See the above part for how to use it. +Fix *pimd/langevin* can be used with :doc:`lj units `. +See the documentation above for how to use it. + +Only some combinations of fix styles and their options support +partitions with multiple processors. LAMMPS will stop with an +error if multi-processor partitions are not supported. A PIMD simulation can be initialized with a single data file read via the :doc:`read_data ` command. However, this means all @@ -412,12 +440,20 @@ variable, e.g. velocity all create 300.0 1234${ibead} rot yes dist gaussian +Related commands +"""""""""""""""" + +:doc:`fix ipi ` + Default """"""" The keyword defaults for fix *pimd/nvt* are method = pimd, fmass = 1.0, sp = 1.0, temp = 300.0, and nhc = 2. +The keyword defaults for fix *pimd/langevin* are integrator = obabo, method = nmpimd, ensemble = nvt, fmmode = physical, fmass = 1.0, +scale = 1, temp = 298.15, thermostat = PILE_L, tau = 1.0, iso = 1.0, taup = 1.0, barostat = BZP, fixcom = yes, and lj = 1 for all its arguments. + ---------- .. _Feynman: diff --git a/doc/src/fix_press_langevin.rst b/doc/src/fix_press_langevin.rst index 8438d72192..02437bd731 100644 --- a/doc/src/fix_press_langevin.rst +++ b/doc/src/fix_press_langevin.rst @@ -54,7 +54,7 @@ the Langevin equation such as: f_P = & \frac{N k_B T_{target}}{V} + \frac{1}{V d}\sum_{i=1}^{N} \vec r_i \cdot \vec f_i - P_{target} \\ Q\ddot{L} + \alpha{}\dot{L} = & f_P + \beta(t)\\ - L^{n+1} = & L^{n} + bdt\dot{L}^{n} \frac{bdt^{2}}{2Q} \\ + L^{n+1} = & L^{n} + bdt\dot{L}^{n} + \frac{bdt^{2}}{2Q} f^{n}_{P} + \frac{bdt}{2Q} \beta^{n+1} \\ \dot{L}^{n+1} = & \alpha\dot{L}^{n} + \frac{dt}{2Q}\left(a f^{n}_{P} + f^{n+1}_{P}\right) + \frac{b}{Q}\beta^{n+1} \\ a = & \frac{1-\frac{\alpha{}dt}{2Q}}{1+\frac{\alpha{}dt}{2Q}} \\ b = & \frac{1}{1+\frac{\alpha{}dt}{2Q}} \\ 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_qeq.rst b/doc/src/fix_qeq.rst index 06a1f98375..ac0bca84f1 100644 --- a/doc/src/fix_qeq.rst +++ b/doc/src/fix_qeq.rst @@ -304,7 +304,7 @@ Chemistry, 95, 3358-3363 (1991). .. _CTIP1: **(CTIP)** G. Plummer, J. P. Tavenner, M. I. Mendelev, Z. Wu, J. W. Lawson, -in preparation +J Chemical Physics, 162, 054709 (2025) .. _vanDuin: diff --git a/doc/src/fix_reaxff_species.rst b/doc/src/fix_reaxff_species.rst index 107695f0f6..badcf72a56 100644 --- a/doc/src/fix_reaxff_species.rst +++ b/doc/src/fix_reaxff_species.rst @@ -200,13 +200,16 @@ 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. This fix is not invoked during :doc:`energy minimization `. +This fix supports dynamic groups only if the *Nrepeat* setting is 1, +i.e. there is no averaging. + ---------- .. include:: accel_styles.rst 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/fix_wall_piston.rst b/doc/src/fix_wall_piston.rst index d60d8cb731..9102cc579e 100644 --- a/doc/src/fix_wall_piston.rst +++ b/doc/src/fix_wall_piston.rst @@ -33,7 +33,7 @@ Syntax *box* = the wall position is defined in simulation box units .. - FIXME: There are several "undocumented" key words for this fix: *rough*, + FIXME: There are several "undocumented" keywords for this fix: *rough*, *rampNL1*, *rampNL2*, *rampNL3*, *rampNL4*, and *rampNL5*. Examples 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..9e4cb4fbc6 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} @@ -98,14 +98,14 @@ all atoms .. math:: - || \vec{F} ||_{max} = {\rm max}\left(||\vec{F}_1||, \cdots, ||\vec{F}_N||\right) + || \vec{F} ||_{max} = \mathrm{max}\left(||\vec{F}_1||, \cdots, ||\vec{F}_N||\right) The *inf* norm takes the maximum component across the forces of all atoms in the system: .. math:: - || \vec{F} ||_{inf} = {\rm max}\left(|F_1^1|, |F_1^2|, |F_1^3| \cdots, |F_N^1|, |F_N^2|, |F_N^3|\right) + || \vec{F} ||_{inf} = \mathrm{max}\left(|F_1^1|, |F_1^2|, |F_1^3| \cdots, |F_N^1|, |F_N^2|, |F_N^3|\right) For the min styles *spin*, *spin/cg* and *spin/lbfgs*, the force norm is replaced by the spin-torque norm. @@ -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/min_spin.rst b/doc/src/min_spin.rst index 9b6841ae8c..c6ae2f26b1 100644 --- a/doc/src/min_spin.rst +++ b/doc/src/min_spin.rst @@ -50,9 +50,9 @@ system: .. math:: - {\Delta t}_{\rm max} = \frac{2\pi}{\kappa \left|\vec{\omega}_{\rm max} \right|} + {\Delta t}_\mathrm{max} = \frac{2\pi}{\kappa \left|\vec{\omega}_\mathrm{max} \right|} -with :math:`\left|\vec{\omega}_{\rm max}\right|` the norm of the largest precession +with :math:`\left|\vec{\omega}_\mathrm{max}\right|` the norm of the largest precession frequency in the system (across all processes, and across all replicas if a spin/neb calculation is performed). diff --git a/doc/src/minimize.rst b/doc/src/minimize.rst index 56efa12f44..84ee4b99fc 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:: @@ -108,12 +108,12 @@ potential energy of the system as a function of the N atom coordinates: .. math:: - E(r_1,r_2, \ldots ,r_N) = & \sum_{i,j} E_{\it pair}(r_i,r_j) + - \sum_{ij} E_{\it bond}(r_i,r_j) + - \sum_{ijk} E_{\it angle}(r_i,r_j,r_k) + \\ - & \sum_{ijkl} E_{\it dihedral}(r_i,r_j,r_k,r_l) + - \sum_{ijkl} E_{\it improper}(r_i,r_j,r_k,r_l) + - \sum_i E_{\it fix}(r_i) + E(r_1,r_2, \ldots ,r_N) = & \sum_{i,j} E_{pair}(r_i,r_j) + + \sum_{ij} E_{bond}(r_i,r_j) + + \sum_{ijk} E_{angle}(r_i,r_j,r_k) + \\ + & \sum_{ijkl} E_{dihedral}(r_i,r_j,r_k,r_l) + + \sum_{ijkl} E_{improper}(r_i,r_j,r_k,r_l) + + \sum_i E_{fix}(r_i) where the first term is the sum of all non-bonded :doc:`pairwise interactions ` including :doc:`long-range Coulombic diff --git a/doc/src/neb_spin.rst b/doc/src/neb_spin.rst index 62ca9f32cb..ba8ea3a7cd 100644 --- a/doc/src/neb_spin.rst +++ b/doc/src/neb_spin.rst @@ -148,7 +148,7 @@ spin i, :math:`\omega_i^{\nu}` is a rotation angle defined as: .. math:: - \omega_i^{\nu} = (\nu - 1) \Delta \omega_i {\rm ~~and~~} \Delta \omega_i = \frac{\omega_i}{Q-1} + \omega_i^{\nu} = (\nu - 1) \Delta \omega_i \mathrm{~~and~~} \Delta \omega_i = \frac{\omega_i}{Q-1} with :math:`\nu` the image number, Q the total number of images, and :math:`\omega_i` the total rotation between the initial and final spins. 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/package.rst b/doc/src/package.rst index ddb3656027..cde9855c5f 100644 --- a/doc/src/package.rst +++ b/doc/src/package.rst @@ -15,115 +15,115 @@ Syntax .. parsed-literal:: - *gpu* args = Ngpu keyword value ... - Ngpu = # of GPUs per node - zero or more keyword/value pairs may be appended - keywords = *neigh* or *newton* or *pair/only* or *binsize* or *split* or *gpuID* or *tpa* or *blocksize* or *omp* or *platform* or *device_type* or *ocl_args* - *neigh* value = *yes* or *no* - *yes* = neighbor list build on GPU (default) - *no* = neighbor list build on CPU - *newton* = *off* or *on* - *off* = set Newton pairwise flag off (default and required) - *on* = set Newton pairwise flag on (currently not allowed) - *pair/only* = *off* or *on* - *off* = apply "gpu" suffix to all available styles in the GPU package (default) - *on* = apply "gpu" suffix only pair styles - *binsize* value = size - size = bin size for neighbor list construction (distance units) - *split* = fraction - fraction = fraction of atoms assigned to GPU (default = 1.0) - *tpa* value = Nlanes - Nlanes = # of GPU vector lanes (CUDA threads) used per atom - *blocksize* value = size - size = thread block size for pair force computation - *omp* value = Nthreads - Nthreads = number of OpenMP threads to use on CPU (default = 0) - *platform* value = id - id = For OpenCL, platform ID for the GPU or accelerator - *gpuID* values = id - id = ID of first GPU to be used on each node - *device_type* value = *intelgpu* or *nvidiagpu* or *amdgpu* or *applegpu* or *generic* or *custom*,val1,val2,... - val1,val2,... = custom OpenCL accelerator configuration parameters (see below for details) - *ocl_args* value = args - args = List of additional OpenCL compiler arguments delimited by colons - *intel* args = NPhi keyword value ... - Nphi = # of co-processors per node - zero or more keyword/value pairs may be appended - keywords = *mode* or *omp* or *lrt* or *balance* or *ghost* or *tpc* or *tptask* or *pppm_table* or *no_affinity* - *mode* value = *single* or *mixed* or *double* - single = perform force calculations in single precision - mixed = perform force calculations in mixed precision - double = perform force calculations in double precision - *omp* value = Nthreads - Nthreads = number of OpenMP threads to use on CPU (default = 0) - *lrt* value = *yes* or *no* - *yes* = use additional thread dedicated for some PPPM calculations - *no* = do not dedicate an extra thread for some PPPM calculations - *balance* value = split - split = fraction of work to offload to co-processor, -1 for dynamic - *ghost* value = *yes* or *no* - *yes* = include ghost atoms for offload - *no* = do not include ghost atoms for offload - *tpc* value = Ntpc - Ntpc = max number of co-processor threads per co-processor core (default = 4) - *tptask* value = Ntptask - Ntptask = max number of co-processor threads per MPI task (default = 240) - *pppm_table* value = *yes* or *no* - *yes* = Precompute pppm values in table (doesn't change accuracy) - *no* = Compute pppm values on the fly - *no_affinity* values = none - *kokkos* args = keyword value ... - zero or more keyword/value pairs may be appended - keywords = *neigh* or *neigh/qeq* or *neigh/thread* or *neigh/transpose* or *newton* or *binsize* or *comm* or *comm/exchange* or *comm/forward* or *comm/pair/forward* or *comm/fix/forward* or *comm/reverse* or *comm/pair/reverse* or *sort* or *atom/map* or *gpu/aware* or *pair/only* - *neigh* value = *full* or *half* - full = full neighbor list - half = half neighbor list built in thread-safe manner - *neigh/qeq* value = *full* or *half* - full = full neighbor list - half = half neighbor list built in thread-safe manner - *neigh/thread* value = *off* or *on* - *off* = thread only over atoms - *on* = thread over both atoms and neighbors - *neigh/transpose* value = *off* or *on* - *off* = use same memory layout for GPU neigh list build as pair style - *on* = use transposed memory layout for GPU neigh list build - *newton* = *off* or *on* - *off* = set Newton pairwise and bonded flags off - *on* = set Newton pairwise and bonded flags on - *binsize* value = size - size = bin size for neighbor list construction (distance units) - *comm* value = *no* or *host* or *device* - use value for comm/exchange and comm/forward and comm/pair/forward and comm/fix/forward and comm/reverse - *comm/exchange* value = *no* or *host* or *device* - *comm/forward* value = *no* or *host* or *device* - *comm/pair/forward* value = *no* or *device* - *comm/fix/forward* value = *no* or *device* - *comm/reverse* value = *no* or *host* or *device* - *no* = perform communication pack/unpack in non-KOKKOS mode - *host* = perform pack/unpack on host (e.g. with OpenMP threading) - *device* = perform pack/unpack on device (e.g. on GPU) - *comm/pair/reverse* value = *no* or *device* - *no* = perform communication pack/unpack in non-KOKKOS mode - *device* = perform pack/unpack on device (e.g. on GPU) - *sort* value = *no* or *device* - *no* = perform atom sorting in non-KOKKOS mode - *device* = perform atom sorting on device (e.g. on GPU) - *atom/map* value = *no* or *device* - *no* = build atom map in non-KOKKOS mode - *device* = build atom map on device (e.g. on GPU) - *gpu/aware* = *off* or *on* - *off* = do not use GPU-aware MPI - *on* = use GPU-aware MPI (default) - *pair/only* = *off* or *on* - *off* = use device acceleration (e.g. GPU) for all available styles in the KOKKOS package (default) - *on* = use device acceleration only for pair styles (and host acceleration for others) - *omp* args = Nthreads keyword value ... - Nthreads = # of OpenMP threads to associate with each MPI process - zero or more keyword/value pairs may be appended - keywords = *neigh* - *neigh* value = *yes* or *no* - *yes* = threaded neighbor list build (default) - *no* = non-threaded neighbor list build + *gpu* args = Ngpu keyword value ... + Ngpu = # of GPUs per node + zero or more keyword/value pairs may be appended + keywords = *neigh* or *newton* or *pair/only* or *binsize* or *split* or *gpuID* or *tpa* or *blocksize* or *omp* or *platform* or *device_type* or *ocl_args* + *neigh* value = *yes* or *no* + *yes* = neighbor list build on GPU (default) + *no* = neighbor list build on CPU + *newton* = *off* or *on* + *off* = set Newton pairwise flag off (default and required) + *on* = set Newton pairwise flag on (currently not allowed) + *pair/only* = *off* or *on* + *off* = apply "gpu" suffix to all available styles in the GPU package (default) + *on* = apply "gpu" suffix only pair styles + *binsize* value = size + size = bin size for neighbor list construction (distance units) + *split* = fraction + fraction = fraction of atoms assigned to GPU (default = 1.0) + *tpa* value = Nlanes + Nlanes = # of GPU vector lanes (CUDA threads) used per atom + *blocksize* value = size + size = thread block size for pair force computation + *omp* value = Nthreads + Nthreads = number of OpenMP threads to use on CPU (default = 0) + *platform* value = id + id = For OpenCL, platform ID for the GPU or accelerator + *gpuID* values = id + id = ID of first GPU to be used on each node + *device_type* value = *intelgpu* or *nvidiagpu* or *amdgpu* or *applegpu* or *generic* or *custom*,val1,val2,... + val1,val2,... = custom OpenCL accelerator configuration parameters (see below for details) + *ocl_args* value = args + args = List of additional OpenCL compiler arguments delimited by colons + *intel* args = NPhi keyword value ... + Nphi = # of co-processors per node + zero or more keyword/value pairs may be appended + keywords = *mode* or *omp* or *lrt* or *balance* or *ghost* or *tpc* or *tptask* or *pppm_table* or *no_affinity* + *mode* value = *single* or *mixed* or *double* + single = perform force calculations in single precision + mixed = perform force calculations in mixed precision + double = perform force calculations in double precision + *omp* value = Nthreads + Nthreads = number of OpenMP threads to use on CPU (default = 0) + *lrt* value = *yes* or *no* + *yes* = use additional thread dedicated for some PPPM calculations + *no* = do not dedicate an extra thread for some PPPM calculations + *balance* value = split + split = fraction of work to offload to co-processor, -1 for dynamic + *ghost* value = *yes* or *no* + *yes* = include ghost atoms for offload + *no* = do not include ghost atoms for offload + *tpc* value = Ntpc + Ntpc = max number of co-processor threads per co-processor core (default = 4) + *tptask* value = Ntptask + Ntptask = max number of co-processor threads per MPI task (default = 240) + *pppm_table* value = *yes* or *no* + *yes* = Precompute pppm values in table (doesn't change accuracy) + *no* = Compute pppm values on the fly + *no_affinity* values = none + *kokkos* args = keyword value ... + zero or more keyword/value pairs may be appended + keywords = *neigh* or *neigh/qeq* or *neigh/thread* or *neigh/transpose* or *newton* or *binsize* or *comm* or *comm/exchange* or *comm/forward* or *comm/pair/forward* or *comm/fix/forward* or *comm/reverse* or *comm/pair/reverse* or *sort* or *atom/map* or *gpu/aware* or *pair/only* + *neigh* value = *full* or *half* + full = full neighbor list + half = half neighbor list built in thread-safe manner + *neigh/qeq* value = *full* or *half* + full = full neighbor list + half = half neighbor list built in thread-safe manner + *neigh/thread* value = *off* or *on* + *off* = thread only over atoms + *on* = thread over both atoms and neighbors + *neigh/transpose* value = *off* or *on* + *off* = use same memory layout for GPU neigh list build as pair style + *on* = use transposed memory layout for GPU neigh list build + *newton* = *off* or *on* + *off* = set Newton pairwise and bonded flags off + *on* = set Newton pairwise and bonded flags on + *binsize* value = size + size = bin size for neighbor list construction (distance units) + *comm* value = *no* or *host* or *device* + use value for comm/exchange and comm/forward and comm/pair/forward and comm/fix/forward and comm/reverse + *comm/exchange* value = *no* or *host* or *device* + *comm/forward* value = *no* or *host* or *device* + *comm/pair/forward* value = *no* or *device* + *comm/fix/forward* value = *no* or *device* + *comm/reverse* value = *no* or *host* or *device* + *no* = perform communication pack/unpack in non-KOKKOS mode + *host* = perform pack/unpack on host (e.g. with OpenMP threading) + *device* = perform pack/unpack on device (e.g. on GPU) + *comm/pair/reverse* value = *no* or *device* + *no* = perform communication pack/unpack in non-KOKKOS mode + *device* = perform pack/unpack on device (e.g. on GPU) + *sort* value = *no* or *device* + *no* = perform atom sorting in non-KOKKOS mode + *device* = perform atom sorting on device (e.g. on GPU) + *atom/map* value = *no* or *device* + *no* = build atom map in non-KOKKOS mode + *device* = build atom map on device (e.g. on GPU) + *gpu/aware* = *off* or *on* + *off* = do not use GPU-aware MPI + *on* = use GPU-aware MPI (default) + *pair/only* = *off* or *on* + *off* = use device acceleration (e.g. GPU) for all available styles in the KOKKOS package (default) + *on* = use device acceleration only for pair styles (and host acceleration for others) + *omp* args = Nthreads keyword value ... + Nthreads = # of OpenMP threads to associate with each MPI process + zero or more keyword/value pairs may be appended + keywords = *neigh* + *neigh* value = *yes* or *no* + *yes* = threaded neighbor list build (default) + *no* = non-threaded neighbor list build Examples """""""" @@ -200,7 +200,7 @@ number of compute cores. If there are more devices than MPI tasks, the additional devices will be unused. The auto-selection of GPUs/ accelerator devices and platforms can be restricted by specifying a non-zero value for *Ngpu* and / or using the *gpuID*, *platform*, -and *device_type* keywords as described below. If there are more MPI +and *device\_type* keywords as described below. If there are more MPI tasks (per node) than GPUs, multiple MPI tasks will share each GPU. Optional keyword/value pairs can also be specified. Each has a @@ -274,8 +274,8 @@ the other particles. The *gpuID* keyword is used to specify the first ID for the GPU or other accelerator that LAMMPS will use. For example, if the ID is 1 and *Ngpu* is 3, GPUs 1-3 will be used. Device IDs should be -determined from the output of nvc_get_devices, ocl_get_devices, -or hip_get_devices +determined from the output of nvc\_get\_devices, ocl\_get\_devices, +or hip\_get\_devices as provided in the lib/gpu directory. When using OpenCL with accelerators that have main memory NUMA, the accelerators can be split into smaller virtual accelerators for more efficient use @@ -308,15 +308,15 @@ The meaning of *Nthreads* is exactly the same for the GPU, INTEL, and GPU packages. The *platform* keyword is only used with OpenCL to specify the ID for -an OpenCL platform. See the output from ocl_get_devices in the lib/gpu +an OpenCL platform. See the output from ocl\_get\_devices in the lib/gpu directory. In LAMMPS only one platform can be active at a time and by default (id=-1) the platform is auto-selected to find the GPU with the most compute cores. When *Ngpu* or other keywords are specified, the auto-selection is appropriately restricted. For example, if *Ngpu* is 3, only platforms with at least 3 accelerators are considered. Similar -restrictions can be enforced by the *gpuID* and *device_type* keywords. +restrictions can be enforced by the *gpuID* and *device\_type* keywords. -The *device_type* keyword can be used for OpenCL to specify the type of +The *device\_type* keyword can be used for OpenCL to specify the type of GPU to use or specify a custom configuration for an accelerator. In most cases this selection will be automatic and there is no need to use the keyword. The *applegpu* type is not specific to a particular GPU vendor, @@ -324,25 +324,25 @@ but is separate due to the more restrictive Apple OpenCL implementation. For expert users, to specify a custom configuration, the *custom* keyword followed by the next parameters can be specified: -CONFIG_ID, SIMD_SIZE, MEM_THREADS, SHUFFLE_AVAIL, FAST_MATH, -THREADS_PER_ATOM, THREADS_PER_CHARGE, THREADS_PER_THREE, BLOCK_PAIR, -BLOCK_BIO_PAIR, BLOCK_ELLIPSE, PPPM_BLOCK_1D, BLOCK_NBOR_BUILD, -BLOCK_CELL_2D, BLOCK_CELL_ID, MAX_SHARED_TYPES, MAX_BIO_SHARED_TYPES, -PPPM_MAX_SPLINE, NBOR_PREFETCH. +CONFIG\_ID, SIMD\_SIZE, MEM\_THREADS, SHUFFLE\_AVAIL, FAST\_MATH, +THREADS\_PER\_ATOM, THREADS\_PER\_CHARGE, THREADS\_PER\_THREE, BLOCK\_PAIR, +BLOCK\_BIO\_PAIR, BLOCK\_ELLIPSE, PPPM\_BLOCK\_1D, BLOCK\_NBOR\_BUILD, +BLOCK\_CELL\_2D, BLOCK\_CELL\_ID, MAX\_SHARED\_TYPES, MAX\_BIO\_SHARED\_TYPES, +PPPM\_MAX\_SPLINE, NBOR\_PREFETCH. -CONFIG_ID can be 0. SHUFFLE_AVAIL in {0,1} indicates that inline-PTX +CONFIG\_ID can be 0. SHUFFLE\_AVAIL in {0,1} indicates that inline-PTX (NVIDIA) or OpenCL extensions (Intel) should be used for horizontal -vector operations. FAST_MATH in {0,1} indicates that OpenCL fast math +vector operations. FAST\_MATH in {0,1} indicates that OpenCL fast math optimizations are used during the build and hardware-accelerated -transcendental functions are used when available. THREADS_PER_* give the +transcendental functions are used when available. THREADS\_PER\_\* give the default *tpa* values for ellipsoidal models, styles using charge, and -any other styles. The BLOCK_* parameters specify the block sizes for -various kernel calls and the MAX_*SHARED*_ parameters are used to +any other styles. The BLOCK\_\* parameters specify the block sizes for +various kernel calls and the MAX\_\*SHARED\_\* parameters are used to determine the amount of local shared memory to use for storing model parameters. For OpenCL, the routines are compiled at runtime for the specified GPU -or accelerator architecture. The *ocl_args* keyword can be used to +or accelerator architecture. The *ocl\_args* keyword can be used to specify additional flags for the runtime build. ---------- @@ -381,7 +381,7 @@ force calculation. The *lrt* keyword can be used to enable "Long Range Thread (LRT)" mode. It can take a value of *yes* to enable and *no* to disable. LRT mode generates an extra thread (in addition to any OpenMP threads -specified with the OMP_NUM_THREADS environment variable or the *omp* +specified with the OMP\_NUM\_THREADS environment variable or the *omp* keyword). The extra thread is dedicated for performing part of the :doc:`PPPM solver ` computations and communications. This can improve parallel performance on processors supporting diff --git a/doc/src/pair_aip_water_2dm.rst b/doc/src/pair_aip_water_2dm.rst index b84202e69e..b7c33e9c86 100644 --- a/doc/src/pair_aip_water_2dm.rst +++ b/doc/src/pair_aip_water_2dm.rst @@ -53,14 +53,14 @@ materials as described in :ref:`(Feng1) ` and :ref:`(Feng2) `. .. math:: E = & \frac{1}{2} \sum_i \sum_{j \neq i} V_{ij} \\ - V_{ij} = & {\rm Tap}(r_{ij})\left \{ e^{-\alpha (r_{ij}/\beta -1)} + V_{ij} = & \mathrm{Tap}(r_{ij})\left \{ e^{-\alpha (r_{ij}/\beta -1)} \left [ \epsilon + f(\rho_{ij}) + f(\rho_{ji})\right ] - \frac{1}{1+e^{-d\left [ \left ( r_{ij}/\left (s_R \cdot r^{eff} \right ) \right )-1 \right ]}} \cdot \frac{C_6}{r^6_{ij}} \right \}\\ - \rho_{ij}^2 = & r_{ij}^2 - ({\bf r}_{ij} \cdot {\bf n}_i)^2 \\ - \rho_{ji}^2 = & r_{ij}^2 - ({\bf r}_{ij} \cdot {\bf n}_j)^2 \\ + \rho_{ij}^2 = & r_{ij}^2 - (\mathbf{r}_{ij} \cdot \mathbf{n}_i)^2 \\ + \rho_{ji}^2 = & r_{ij}^2 - (\mathbf{r}_{ij} \cdot \mathbf{n}_j)^2 \\ f(\rho) = & C e^{ -( \rho / \delta )^2 } \\ - {\rm Tap}(r_{ij}) = & 20\left ( \frac{r_{ij}}{R_{cut}} \right )^7 - + \mathrm{Tap}(r_{ij}) = & 20\left ( \frac{r_{ij}}{R_{cut}} \right )^7 - 70\left ( \frac{r_{ij}}{R_{cut}} \right )^6 + 84\left ( \frac{r_{ij}}{R_{cut}} \right )^5 - 35\left ( \frac{r_{ij}}{R_{cut}} \right )^4 + 1 diff --git a/doc/src/pair_bop.rst b/doc/src/pair_bop.rst index 42b9c54406..013dcbc46b 100644 --- a/doc/src/pair_bop.rst +++ b/doc/src/pair_bop.rst @@ -32,20 +32,20 @@ Description """"""""""" The *bop* pair style computes Bond-Order Potentials (BOP) based on -quantum mechanical theory incorporating both :math:`\sigma` and :math:`\pi` bonding. -By analytically deriving the BOP from quantum mechanical theory its -transferability to different phases can approach that of quantum -mechanical methods. This potential is similar to the original BOP -developed by Pettifor (:ref:`Pettifor_1 `, -:ref:`Pettifor_2 `, :ref:`Pettifor_3 `) and later updated -by Murdick, Zhou, and Ward (:ref:`Murdick `, :ref:`Ward `). -Currently, BOP potential files for these systems are provided with -LAMMPS: AlCu, CCu, CdTe, CdTeSe, CdZnTe, CuH, GaAs. A system with -only a subset of these elements, including a single element (e.g. C or -Cu or Al or Ga or Zn or CdZn), can also be modeled by using the -appropriate alloy file and assigning all atom types to the -single element or subset of elements via the pair_coeff command, as -discussed below. +quantum mechanical theory incorporating both :math:`\sigma` and +:math:`\pi` bonding. By analytically deriving the BOP from quantum +mechanical theory its transferability to different phases can approach +that of quantum mechanical methods. This potential is similar to the +original BOP developed by Pettifor (:ref:`Pettifor_1 `, +:ref:`Pettifor_2 `, :ref:`Pettifor_3 `) and +later updated by Murdick, Zhou, and Ward (:ref:`Murdick `, +:ref:`Ward `). Currently, BOP potential files for these systems +are provided with LAMMPS: AlCu, CCu, CdTe, CdTeSe, CdZnTe, CuH, GaAs. A +system with only a subset of these elements, including a single element +(e.g. C or Cu or Al or Ga or Zn or CdZn), can also be modeled by using +the appropriate alloy file and assigning all atom types to the single +element or subset of elements via the :doc:`pair_coeff command +`, as discussed below. The BOP potential consists of three terms: @@ -58,7 +58,7 @@ representing the repulsion between a pair of ion cores, :math:`\beta_{\sigma,ij}(r_{ij})` and :math:`\beta_{\sigma,ij}(r_{ij})` are respectively sigma and :math:`\pi` bond integrals, :math:`\Theta_{\sigma,ij}` and :math:`\Theta_{\pi,ij}` are :math:`\sigma` and :math:`\pi` -bond-orders, and U_prom is the promotion energy for sp-valent systems. +bond-orders, and U\_prom is the promotion energy for sp-valent systems. The detailed formulas for this potential are given in Ward (:ref:`Ward `); here we provide only a brief description. @@ -96,7 +96,7 @@ length 4. This enables the incorporation of dihedral angles effects. .. note:: Note that unlike for other potentials, cutoffs for BOP - potentials are not set in the pair_style or pair_coeff command; they + potentials are not set in the pair\_style or pair\_coeff command; they are specified in the BOP potential files themselves. Likewise, the BOP potential files list atomic masses; thus you do not need to use the :doc:`mass ` command to specify them. Note that for BOP @@ -106,7 +106,7 @@ length 4. This enables the incorporation of dihedral angles effects. :doc:`pair_coeff ` command to read the BOP potential file. -One option can be specified as a keyword with the pair_style command. +One option can be specified as a keyword with the pair\_style command. The *save* keyword gives you the option to calculate in advance and store a set of distances, angles, and derivatives of angles. The @@ -118,10 +118,10 @@ system configuration. ---------- -Only a single pair_coeff command is used with the *bop* style which +Only a single pair\_coeff command is used with the *bop* style which specifies a BOP potential file, with parameters for all needed elements. These are mapped to LAMMPS atom types by specifying -N additional arguments after the filename in the pair_coeff command, +N additional arguments after the filename in the pair\_coeff command, where N is the number of LAMMPS atom types: * filename @@ -130,7 +130,7 @@ where N is the number of LAMMPS atom types: As an example, imagine the CdTe.bop file has BOP values for Cd and Te. If your LAMMPS simulation has 4 atoms types and you want the first 3 to be Cd, and the fourth to be Te, you would use the following -pair_coeff command: +pair\_coeff command: .. code-block:: LAMMPS @@ -143,8 +143,8 @@ element in the BOP file. The final Te argument maps LAMMPS atom type BOP files in the *potentials* directory of the LAMMPS distribution have a ".bop" suffix. The potentials are in tabulated form containing -pre-tabulated pair functions for phi_ij(r_ij), beta_(sigma,ij)(r_ij), -and beta_pi,ij)(r_ij). +pre-tabulated pair functions for phi\_ij(r\_ij), beta\_(sigma,ij)(r\_ij), +and beta\_pi,ij)(r\_ij). The parameters/coefficients format for the different kinds of BOP files are given below with variables matching the formulation of Ward @@ -170,89 +170,89 @@ the tabulated functions are given. * Line 1: nr, nBOt (nr is the number of divisions the radius is broken into for function tables and MUST be a factor of 5; nBOt is the number - of divisions for the tabulated values of THETA_(S,ij) -* Line 2: delta_1-delta_7 (if all are not used in the particular + of divisions for the tabulated values of THETA\_(S,ij) +* Line 2: delta\_1-delta\_7 (if all are not used in the particular * formulation, set unused values to 0.0) -Following this N lines for e_1-e_N containing p_pi. +Following this N lines for e\_1-e\_N containing p\_pi. -* Line 3: p_pi (for e_1) -* Line 4: p_pi (for e_2 and continues to e_N) +* Line 3: p\_pi (for e\_1) +* Line 4: p\_pi (for e\_2 and continues to e\_N) The next section contains several pair constants for the number of -interaction types e_i-e_j, with i=1->N, j=i->N +interaction types e\_i-e\_j, with i=1->N, j=i->N -* Line 1: r_cut (for e_1-e_1 interactions) -* Line 2: c_sigma, a_sigma, c_pi, a_pi -* Line 3: delta_sigma, delta_pi -* Line 4: f_sigma, k_sigma, delta_3 (This delta_3 is similar to that of +* Line 1: r\_cut (for e\_1-e\_1 interactions) +* Line 2: c\_sigma, a\_sigma, c\_pi, a\_pi +* Line 3: delta\_sigma, delta\_pi +* Line 4: f\_sigma, k\_sigma, delta\_3 (This delta\_3 is similar to that of the previous section but is interaction type dependent) The next section contains a line for each three body interaction type -e_j-e_i-e_k with i=0->N, j=0->N, k=j->N +e\_j-e\_i-e\_k with i=0->N, j=0->N, k=j->N -* Line 1: g_(sigma0), g_(sigma1), g_(sigma2) (These are coefficients for - g_(sigma,jik)(THETA_ijk) for e_1-e_1-e_1 interaction. :ref:`Ward ` +* Line 1: g\_(sigma0), g\_(sigma1), g\_(sigma2) (These are coefficients for + g\_(sigma,jik)(THETA\_ijk) for e\_1-e\_1-e\_1 interaction. :ref:`Ward ` contains the full expressions for the constants as functions of - b_(sigma,ijk), p_(sigma,ijk), u_(sigma,ijk)) -* Line 2: g_(sigma0), g_(sigma1), g_(sigma2) (for e_1-e_1-e_2) + b\_(sigma,ijk), p\_(sigma,ijk), u\_(sigma,ijk)) +* Line 2: g\_(sigma0), g\_(sigma1), g\_(sigma2) (for e\_1-e\_1-e\_2) The next section contains a block for each interaction type for the -phi_ij(r_ij). Each block has nr entries with 5 entries per line. +phi\_ij(r\_ij). Each block has nr entries with 5 entries per line. -* Line 1: phi(r1), phi(r2), phi(r3), phi(r4), phi(r5) (for the e_1-e_1 +* Line 1: phi(r1), phi(r2), phi(r3), phi(r4), phi(r5) (for the e\_1-e\_1 interaction type) * Line 2: phi(r6), phi(r7), phi(r8), phi(r9), phi(r10) (this continues until nr) * ... -* Line nr/5_1: phi(r1), phi(r2), phi(r3), phi(r4), phi(r5), (for the - e_1-e_1 interaction type) +* Line nr/5\_1: phi(r1), phi(r2), phi(r3), phi(r4), phi(r5), (for the + e\_1-e\_1 interaction type) The next section contains a block for each interaction type for the -beta_(sigma,ij)(r_ij). Each block has nr entries with 5 entries per +beta\_(sigma,ij)(r\_ij). Each block has nr entries with 5 entries per line. -* Line 1: beta_sigma(r1), beta_sigma(r2), beta_sigma(r3), beta_sigma(r4), - beta_sigma(r5) (for the e_1-e_1 interaction type) -* Line 2: beta_sigma(r6), beta_sigma(r7), beta_sigma(r8), beta_sigma(r9), - beta_sigma(r10) (this continues until nr) +* Line 1: beta\_sigma(r1), beta\_sigma(r2), beta\_sigma(r3), beta\_sigma(r4), + beta\_sigma(r5) (for the e\_1-e\_1 interaction type) +* Line 2: beta\_sigma(r6), beta\_sigma(r7), beta\_sigma(r8), beta\_sigma(r9), + beta\_sigma(r10) (this continues until nr) * ... -* Line nr/5+1: beta_sigma(r1), beta_sigma(r2), beta_sigma(r3), - beta_sigma(r4), beta_sigma(r5) (for the e_1-e_2 interaction type) +* Line nr/5+1: beta\_sigma(r1), beta\_sigma(r2), beta\_sigma(r3), + beta\_sigma(r4), beta\_sigma(r5) (for the e\_1-e\_2 interaction type) The next section contains a block for each interaction type for -beta_(pi,ij)(r_ij). Each block has nr entries with 5 entries per line. +beta\_(pi,ij)(r\_ij). Each block has nr entries with 5 entries per line. -* Line 1: beta_pi(r1), beta_pi(r2), beta_pi(r3), beta_pi(r4), beta_pi(r5) - (for the e_1-e_1 interaction type) -* Line 2: beta_pi(r6), beta_pi(r7), beta_pi(r8), beta_pi(r9), - beta_pi(r10) (this continues until nr) +* Line 1: beta\_pi(r1), beta\_pi(r2), beta\_pi(r3), beta\_pi(r4), beta\_pi(r5) + (for the e\_1-e\_1 interaction type) +* Line 2: beta\_pi(r6), beta\_pi(r7), beta\_pi(r8), beta\_pi(r9), + beta\_pi(r10) (this continues until nr) * ... -* Line nr/5+1: beta_pi(r1), beta_pi(r2), beta_pi(r3), beta_pi(r4), - beta_pi(r5) (for the e_1-e_2 interaction type) +* Line nr/5+1: beta\_pi(r1), beta\_pi(r2), beta\_pi(r3), beta\_pi(r4), + beta\_pi(r5) (for the e\_1-e\_2 interaction type) The next section contains a block for each interaction type for the -THETA_(S,ij)((THETA_(sigma,ij))\^(1/2), f_(sigma,ij)). Each block has +THETA\_(S,ij)((THETA\_(sigma,ij))\^(1/2), f\_(sigma,ij)). Each block has nBOt entries with 5 entries per line. -* Line 1: THETA_(S,ij)(r1), THETA_(S,ij)(r2), THETA_(S,ij)(r3), - THETA_(S,ij)(r4), THETA_(S,ij)(r5) (for the e_1-e_2 interaction type) -* Line 2: THETA_(S,ij)(r6), THETA_(S,ij)(r7), THETA_(S,ij)(r8), - THETA_(S,ij)(r9), THETA_(S,ij)(r10) (this continues until nBOt) +* Line 1: THETA\_(S,ij)(r1), THETA\_(S,ij)(r2), THETA\_(S,ij)(r3), + THETA\_(S,ij)(r4), THETA\_(S,ij)(r5) (for the e\_1-e\_2 interaction type) +* Line 2: THETA\_(S,ij)(r6), THETA\_(S,ij)(r7), THETA\_(S,ij)(r8), + THETA\_(S,ij)(r9), THETA\_(S,ij)(r10) (this continues until nBOt) * ... -* Line nBOt/5+1: THETA_(S,ij)(r1), THETA_(S,ij)(r2), THETA_(S,ij)(r3), - THETA_(S,ij)(r4), THETA_(S,ij)(r5) (for the e_1-e_2 interaction type) +* Line nBOt/5+1: THETA\_(S,ij)(r1), THETA\_(S,ij)(r2), THETA\_(S,ij)(r3), + THETA\_(S,ij)(r4), THETA\_(S,ij)(r5) (for the e\_1-e\_2 interaction type) -The next section contains a block of N lines for e_1-e_N +The next section contains a block of N lines for e\_1-e\_N -* Line 1: delta\^mu (for e_1) -* Line 2: delta\^mu (for e_2 and repeats to e_N) +* Line 1: delta\^mu (for e\_1) +* Line 2: delta\^mu (for e\_2 and repeats to e\_N) -The last section contains more constants for e_i-e_j interactions with +The last section contains more constants for e\_i-e\_j interactions with i=0->N, j=i->N -* Line 1: (A_ij)\^(mu\*nu) (for e1-e1) -* Line 2: (A_ij)\^(mu\*nu) (for e1-e2 and repeats as above) +* Line 1: (A\_ij)\^(mu\*nu) (for e1-e1) +* Line 2: (A\_ij)\^(mu\*nu) (for e1-e2 and repeats as above) ---------- @@ -274,34 +274,34 @@ the tabulated functions are given. * Line 1: nr, ntheta, nBOt (nr is the number of divisions the radius is broken into for function tables and MUST be a factor of 5; ntheta is the power of the power of the spline used to fit the angular function; nBOt is the number - of divisions for the tabulated values of THETA_(S,ij) -* Line 2: delta_1-delta_7 (if all are not used in the particular + of divisions for the tabulated values of THETA\_(S,ij) +* Line 2: delta\_1-delta\_7 (if all are not used in the particular * formulation, set unused values to 0.0) -Following this N lines for e_1-e_N containing p_pi. +Following this N lines for e\_1-e\_N containing p\_pi. -* Line 3: p_pi (for e_1) -* Line 4: p_pi (for e_2 and continues to e_N) +* Line 3: p\_pi (for e\_1) +* Line 4: p\_pi (for e\_2 and continues to e\_N) The next section contains several pair constants for the number of -interaction types e_i-e_j, with i=1->N, j=i->N +interaction types e\_i-e\_j, with i=1->N, j=i->N -* Line 1: r_cut (for e_1-e_1 interactions) -* Line 2: c_sigma, a_sigma, c_pi, a_pi -* Line 3: delta_sigma, delta_pi -* Line 4: f_sigma, k_sigma, delta_3 (This delta_3 is similar to that of +* Line 1: r\_cut (for e\_1-e\_1 interactions) +* Line 2: c\_sigma, a\_sigma, c\_pi, a\_pi +* Line 3: delta\_sigma, delta\_pi +* Line 4: f\_sigma, k\_sigma, delta\_3 (This delta\_3 is similar to that of the previous section but is interaction type dependent) The next section contains a line for each three body interaction type -e_j-e_i-e_k with i=0->N, j=0->N, k=j->N +e\_j-e\_i-e\_k with i=0->N, j=0->N, k=j->N * Line 1: g0, g1, g2... (These are coefficients for the angular spline - of the g_(sigma,jik)(THETA_ijk) for e_1-e_1-e_1 interaction. The + of the g\_(sigma,jik)(THETA\_ijk) for e\_1-e\_1-e\_1 interaction. The function can contain up to 10 term thus 10 constants. The first line can contain up to five constants. If the spline has more than five terms the second line will contain the remaining constants The following lines will then contain the constants for the remaining g0, - g1, g2... (for e_1-e_1-e_2) and the other three body + g1, g2... (for e\_1-e\_1-e\_2) and the other three body interactions The rest of the table has the same structure as the previous section @@ -327,34 +327,34 @@ the tabulated functions are given. * Line 1: nr, ntheta, nBOt (nr is the number of divisions the radius is broken into for function tables and MUST be a factor of 5; ntheta is the number of divisions for the tabulated values of the g angular function; nBOt is the number - of divisions for the tabulated values of THETA_(S,ij) -* Line 2: delta_1-delta_7 (if all are not used in the particular + of divisions for the tabulated values of THETA\_(S,ij) +* Line 2: delta\_1-delta\_7 (if all are not used in the particular * formulation, set unused values to 0.0) -Following this N lines for e_1-e_N containing p_pi. +Following this N lines for e\_1-e\_N containing p\_pi. -* Line 3: p_pi (for e_1) -* Line 4: p_pi (for e_2 and continues to e_N) +* Line 3: p\_pi (for e\_1) +* Line 4: p\_pi (for e\_2 and continues to e\_N) The next section contains several pair constants for the number of -interaction types e_i-e_j, with i=1->N, j=i->N +interaction types e\_i-e\_j, with i=1->N, j=i->N -* Line 1: r_cut (for e_1-e_1 interactions) -* Line 2: c_sigma, a_sigma, c_pi, a_pi -* Line 3: delta_sigma, delta_pi -* Line 4: f_sigma, k_sigma, delta_3 (This delta_3 is similar to that of +* Line 1: r\_cut (for e\_1-e\_1 interactions) +* Line 2: c\_sigma, a\_sigma, c\_pi, a\_pi +* Line 3: delta\_sigma, delta\_pi +* Line 4: f\_sigma, k\_sigma, delta\_3 (This delta\_3 is similar to that of the previous section but is interaction type dependent) The next section contains a line for each three body interaction type -e_j-e_i-e_k with i=0->N, j=0->N, k=j->N +e\_j-e\_i-e\_k with i=0->N, j=0->N, k=j->N -* Line 1: g(theta1), g(theta2), g(theta3), g(theta4), g(theta5) (for the e_1-e_1-e_1 +* Line 1: g(theta1), g(theta2), g(theta3), g(theta4), g(theta5) (for the e\_1-e\_1-e\_1 interaction type) * Line 2: g(theta6), g(theta7), g(theta8), g(theta9), g(theta10) (this continues until ntheta) * ... * Line ntheta/5+1: g(theta1), g(theta2), g(theta3), g(theta4), g(theta5), (for the - e_1-e_1-e_2 interaction type) + e\_1-e\_1-e\_2 interaction type) The rest of the table has the same structure as the previous section (see above). diff --git a/doc/src/pair_bpm_spring.rst b/doc/src/pair_bpm_spring.rst index 068efff577..19ba4cdbec 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: @@ -117,6 +117,10 @@ 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. +The potential energy and the single() function of this pair style returns +:math:`k (r - r_c)^2 / 2 + k_a (r - r_c)^4 / 4` for a proxy +of the energy of a pair interaction, ignoring any smoothing or dissipative forces. + ---------- Restrictions diff --git a/doc/src/pair_coul.rst b/doc/src/pair_coul.rst index 77c0e0b18b..c673561237 100644 --- a/doc/src/pair_coul.rst +++ b/doc/src/pair_coul.rst @@ -241,9 +241,9 @@ summation method, described in :ref:`Wolf `, given by: .. math:: E_i = \frac{1}{2} \sum_{j \neq i} - \frac{q_i q_j {\rm erfc}(\alpha r_{ij})}{r_{ij}} + + \frac{q_i q_j \mathrm{erfc}(\alpha r_{ij})}{r_{ij}} + \frac{1}{2} \sum_{j \neq i} - \frac{q_i q_j {\rm erf}(\alpha r_{ij})}{r_{ij}} \qquad r < r_c + \frac{q_i q_j \mathrm{erf}(\alpha r_{ij})}{r_{ij}} \qquad r < r_c where :math:`\alpha` is the damping parameter, and *erf()* and *erfc()* are error-function and complementary error-function terms. This @@ -471,7 +471,7 @@ Phys, 110, 8254 (1999). .. _Plummer1: **(Plummer)** G. Plummer, J. P. Tavenner, M. I. Mendelev, Z. Wu, J. W. Lawson, -in preparation +J Chemical Physics, 162, 054709 (2025). .. _Jorgensen3: diff --git a/doc/src/pair_coul_shield.rst b/doc/src/pair_coul_shield.rst index a7f99500f5..5f580f9037 100644 --- a/doc/src/pair_coul_shield.rst +++ b/doc/src/pair_coul_shield.rst @@ -40,8 +40,8 @@ the pair style :doc:`ilp/graphene/hbn ` .. math:: E = & \frac{1}{2} \sum_i \sum_{j \neq i} V_{ij} \\ - V_{ij} = & {\rm Tap}(r_{ij})\frac{\kappa q_i q_j}{\sqrt[3]{r_{ij}^3+(1/\lambda_{ij})^3}}\\ - {\rm Tap}(r_{ij}) = & 20\left ( \frac{r_{ij}}{R_{cut}} \right )^7 - + V_{ij} = & \mathrm{Tap}(r_{ij})\frac{\kappa q_i q_j}{\sqrt[3]{r_{ij}^3+(1/\lambda_{ij})^3}}\\ + \mathrm{Tap}(r_{ij}) = & 20\left ( \frac{r_{ij}}{R_{cut}} \right )^7 - 70\left ( \frac{r_{ij}}{R_{cut}} \right )^6 + 84\left ( \frac{r_{ij}}{R_{cut}} \right )^5 - 35\left ( \frac{r_{ij}}{R_{cut}} \right )^4 + 1 diff --git a/doc/src/pair_dispersion_d3.rst b/doc/src/pair_dispersion_d3.rst new file mode 100644 index 0000000000..a9249299d0 --- /dev/null +++ b/doc/src/pair_dispersion_d3.rst @@ -0,0 +1,167 @@ +.. 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: *original*, *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 original 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. + +.. versionchanged:: TBD + + renamed *zero* keyword to *original* to avoid conflicts with + :doc:`pair style zero ` when used as :doc:`hybrid + sub-style `. + +Available damping functions are the original "zero-damping" (*original*) +:ref:`(Grimme1) `, Becke-Johnson damping (*bj*) :ref:`(Grimme2) +`, and their revised forms (*zerom* and *bjm*, respectively) +: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, | +| | original | | 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. + +The compiled in parameters require the use of :doc:`metal units `. + +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_dpd_ext.rst b/doc/src/pair_dpd_ext.rst index 1caed4689b..e84001235a 100644 --- a/doc/src/pair_dpd_ext.rst +++ b/doc/src/pair_dpd_ext.rst @@ -62,8 +62,8 @@ a sum of 3 terms \mathbf{f} = & f^C + f^D + f^R \qquad \qquad r < r_c \\ f^C = & A_{ij} w(r) \hat{\mathbf{r}}_{ij} \\ - f^D = & - \gamma_{\parallel} w_{\parallel}^2(r) (\hat{\mathbf{r}}_{ij} \cdot \mathbf{v}_{ij}) \hat{\mathbf{r}}_{ij} - \gamma_{\perp} w_{\perp}^2 (r) ( \mathbf{I} - \hat{\mathbf{r}}_{ij} \hat{\mathbf{r}}_{ij}^{\rm T} ) \mathbf{v}_{ij} \\ - f^R = & \sigma_{\parallel} w_{\parallel}(r) \frac{\alpha}{\sqrt{\Delta t}} \hat{\mathbf{r}}_{ij} + \sigma_{\perp} w_{\perp} (r) ( \mathbf{I} - \hat{\mathbf{r}}_{ij} \hat{\mathbf{r}}_{ij}^{\rm T} ) \frac{\mathbf{\xi}_{ij}}{\sqrt{\Delta t}}\\ + f^D = & - \gamma_{\parallel} w_{\parallel}^2(r) (\hat{\mathbf{r}}_{ij} \cdot \mathbf{v}_{ij}) \hat{\mathbf{r}}_{ij} - \gamma_{\perp} w_{\perp}^2 (r) ( \mathbf{I} - \hat{\mathbf{r}}_{ij} \hat{\mathbf{r}}_{ij}^\mathrm{T} ) \mathbf{v}_{ij} \\ + f^R = & \sigma_{\parallel} w_{\parallel}(r) \frac{\alpha}{\sqrt{\Delta t}} \hat{\mathbf{r}}_{ij} + \sigma_{\perp} w_{\perp} (r) ( \mathbf{I} - \hat{\mathbf{r}}_{ij} \hat{\mathbf{r}}_{ij}^\mathrm{T} ) \frac{\mathbf{\xi}_{ij}}{\sqrt{\Delta t}}\\ w(r) = & 1 - r/r_c \\ where :math:`\mathbf{f}^C` is a conservative force, :math:`\mathbf{f}^D` diff --git a/doc/src/pair_eim.rst b/doc/src/pair_eim.rst index c84bce9d53..2de2a124e2 100644 --- a/doc/src/pair_eim.rst +++ b/doc/src/pair_eim.rst @@ -37,10 +37,11 @@ energy of the system E is given by E = \frac{1}{2} \sum_{i=1}^{N} \sum_{j=i_1}^{i_N} \phi_{ij} \left(r_{ij}\right) + \sum_{i=1}^{N}E_i\left(q_i,\sigma_i\right) The first term is a double pairwise sum over the J neighbors of all I -atoms, where :math:`\phi_{ij}` is a pair potential. The second term sums over -the embedding energy E_i of atom I, which is a function of its charge -q_i and the electrical potential :math:`\sigma_i` at its location. E_i, q_i, -and :math:`sigma_i` are calculated as +atoms, where :math:`\phi_{ij}` is a pair potential. The second term +sums over the embedding energy :math:`E_i` of atom I, which is a +function of its charge :math:`q_i` and the electrical potential +:math:`\sigma_i` at its location. :math:`E_i`, :math:`q_i`, and +:math:`\sigma_i` are calculated as .. math:: @@ -77,7 +78,7 @@ atoms in the atomic pair. charge on each atom and thus requires you to assign a charge to each atom, e.g. the *charge* or *full* atom styles. This is because the EIM potential infers the charge on an atom from the equation above for - q_i; you do not assign charges explicitly. + :math:`q_i`; you do not assign charges explicitly. ---------- @@ -90,15 +91,15 @@ A system with any combination of these elements can be modeled. This file is parameterized in terms of LAMMPS :doc:`metal units `. Note that unlike other potentials, cutoffs for EIM potentials are not -set in the pair_style or pair_coeff command; they are specified in the +set in the pair\_style or pair\_coeff command; they are specified in the EIM potential file itself. Likewise, the EIM potential file lists atomic masses; thus you do not need to use the :doc:`mass ` command to specify them. -Only a single pair_coeff command is used with the *eim* style which +Only a single pair\_coeff command is used with the *eim* style which specifies an EIM potential file and the element(s) to extract information for. The EIM elements are mapped to LAMMPS atom types by -specifying N additional arguments after the filename in the pair_coeff +specifying N additional arguments after the filename in the pair\_coeff command, where N is the number of LAMMPS atom types: * Elem1, Elem2, ... @@ -111,7 +112,7 @@ to specify the path for the potential file. As an example like one of those above, suppose you want to model a system with Na and Cl atoms. If your LAMMPS simulation has 4 atoms types and you want the first 3 to be Na, and the fourth to be Cl, you would -use the following pair_coeff command: +use the following pair\_coeff command: .. code-block:: LAMMPS @@ -147,9 +148,9 @@ radius (LAMMPS ignores it), ionic radius (LAMMPS ignores it), cohesive energy (LAMMPS ignores it), and q0 (must be 0). Lines starting with "pair:" are entered as: element 1, element 2, -r_(c,phi), r_(c,phi) (redundant for historical reasons), E_b, r_e, -alpha, beta, r_(c,eta), A_(eta), r_(s,eta), r_(c,psi), A_(psi), zeta, -r_(s,psi), and p. +r\_(c,phi), r\_(c,phi) (redundant for historical reasons), E\_b, r\_e, +alpha, beta, r\_(c,eta), A\_(eta), r\_(s,eta), r\_(c,psi), A\_(psi), zeta, +r\_(s,psi), and p. The lines in the file can be in any order; LAMMPS extracts the info it needs. diff --git a/doc/src/pair_granular.rst b/doc/src/pair_granular.rst index 11a460e9ca..4ae59a587f 100644 --- a/doc/src/pair_granular.rst +++ b/doc/src/pair_granular.rst @@ -29,6 +29,9 @@ Examples pair_style granular pair_coeff * * hertz/material 1e8 0.3 0.3 tangential mindlin_rescale NULL 1.0 0.4 damping tsuji + pair_style granular + pair_coeff * * hertz/material 1e8 0.3 0.3 tangential mindlin_rescale NULL 1.0 0.4 damping coeff_restitution synchronized_verlet + pair_style granular pair_coeff 1 * jkr 1000.0 500.0 0.3 10 tangential mindlin 800.0 1.0 0.5 rolling sds 500.0 200.0 0.5 twisting marshall pair_coeff 2 2 hertz 200.0 100.0 tangential linear_history 300.0 1.0 0.1 rolling sds 200.0 100.0 0.1 twisting marshall @@ -40,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 """"""""""" @@ -82,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 @@ -99,11 +106,12 @@ on particle *i* due to contact with particle *j* is given by: \mathbf{F}_{ne, Hooke} = k_n \delta_{ij} \mathbf{n} Where :math:`\delta_{ij} = R_i + R_j - \|\mathbf{r}_{ij}\|` is the particle -overlap, :math:`R_i, R_j` are the particle radii, :math:`\mathbf{r}_{ij} = \mathbf{r}_i - \mathbf{r}_j` is the vector separating the two -particle centers (note the i-j ordering so that :math:`\mathbf{F}_{ne}` is -positive for repulsion), and :math:`\mathbf{n} = \frac{\mathbf{r}_{ij}}{\|\mathbf{r}_{ij}\|}`. Therefore, -for *hooke*, the units of the spring constant :math:`k_n` are -*force*\ /\ *distance*, or equivalently *mass*\ /*time\^2*. +overlap, :math:`R_i, R_j` are the particle radii, :math:`\mathbf{r}_{ij} = +\mathbf{r}_i - \mathbf{r}_j` is the vector separating the two particle centers +(note the i-j ordering so that :math:`\mathbf{F}_{ne}` is positive for repulsion), +and :math:`\mathbf{n} = \frac{\mathbf{r}_{ij}}{\|\mathbf{r}_{ij}\|}`. Therefore, +for *hooke*, the units of the spring constant :math:`k_n` are *force*\ /\ +*distance*, or equivalently *mass*\ /*time\^2*. For the *hertz* model, the normal component of force is given by: @@ -162,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 @@ -171,7 +317,8 @@ following general form: \mathbf{F}_{n,damp} = -\eta_n \mathbf{v}_{n,rel} -Here, :math:`\mathbf{v}_{n,rel} = (\mathbf{v}_j - \mathbf{v}_i) \cdot \mathbf{n}\ \mathbf{n}` is the component of relative velocity along +Here, :math:`\mathbf{v}_{n,rel} = (\mathbf{v}_j - \mathbf{v}_i) \cdot +\mathbf{n}\ \mathbf{n}` is the component of relative velocity along :math:`\mathbf{n}`. The optional *damping* keyword to the *pair_coeff* command followed by @@ -346,7 +493,8 @@ the normal force: F_{n0} = \|\mathbf{F}_n\| For cohesive models such as *jkr* and *dmt*, the critical force is -adjusted so that the critical tangential force approaches :math:`\mu_t F_{pulloff}`, see :ref:`Marshall `, equation 43, and +adjusted so that the critical tangential force approaches +:math:`\mu_t F_{pulloff}`, see :ref:`Marshall `, equation 43, and :ref:`Thornton `. For both models, :math:`F_{n0}` takes the form: @@ -436,7 +584,6 @@ of :math:`a`, the radius of the contact region. The tangential force is given by \mathbf{F}_t = -\min(\mu_t F_{n0}, \|-k_t a \mathbf{\xi} + \mathbf{F}_\mathrm{t,damp}\|) \mathbf{t} - Here, :math:`a` is the radius of the contact region, given by :math:`a =\sqrt{R\delta}` for all normal contact models, except for *jkr*, where it is given implicitly by :math:`\delta = a^2/R - 2\sqrt{\pi \gamma a/E}`, see @@ -552,9 +699,11 @@ the tangential force: \mathbf{F}_{roll,0} = k_{roll} \mathbf{\xi}_{roll} - \gamma_{roll} \mathbf{v}_{roll} -Here, :math:`\mathbf{v}_{roll} = -R(\boldsymbol{\Omega}_i - \boldsymbol{\Omega}_j) \times \mathbf{n}` is the relative rolling -velocity, as given in :ref:`Wang et al ` and -:ref:`Luding `. This differs from the expressions given by :ref:`Kuhn and Bagi ` and used in :ref:`Marshall `; see :ref:`Wang et al ` for details. The rolling displacement is given by: +Here, :math:`\mathbf{v}_{roll} = -R(\boldsymbol{\Omega}_i - \boldsymbol{\Omega}_j) +\times \mathbf{n}` is the relative rolling velocity, as given in +:ref:`Wang et al ` and :ref:`Luding `. This differs from the +expressions given by :ref:`Kuhn and Bagi ` and used in :ref:`Marshall `; +see :ref:`Wang et al ` for details. The rolling displacement is given by: .. math:: @@ -611,9 +760,10 @@ the most straightforward treatment: \tau_{twist,0} = -k_{twist}\xi_{twist} - \gamma_{twist}\Omega_{twist} -Here :math:`\xi_{twist} = \int_{t_0}^t \Omega_{twist} (\tau) \mathrm{d}\tau` is the twisting angular displacement, and -:math:`\Omega_{twist} = (\mathbf{\Omega}_i - \mathbf{\Omega}_j) \cdot \mathbf{n}` is the relative twisting angular velocity. The torque -is then truncated according to: +Here :math:`\xi_{twist} = \int_{t_0}^t \Omega_{twist} (\tau) \mathrm{d}\tau` is +the twisting angular displacement, and +:math:`\Omega_{twist} = (\mathbf{\Omega}_i - \mathbf{\Omega}_j) \cdot \mathbf{n}` +is the relative twisting angular velocity. The torque is then truncated according to: .. math:: @@ -667,6 +817,19 @@ attractive force. This keyword cannot be used with the JKR or DMT models. ---------- +The standard velocity-Verlet integration scheme's half-step staggering of +position and velocity can introduce inaccuracies in frictional tangential +force calculations, resulting in unphysical kinematics in certain systems. +These effects are particularly pronounced in polydisperse frictional flows +characterized by large-to-small size ratios exceeding three. The +*synchronized_verlet* flag implements an alternate Velocity-Verlet integration +scheme, as detailed in :ref:`Vyas et al `, that synchronizes position +and velocity updates for force evaluation. By refining tangential force +calculations, the *synchronized_verlet* method ensures physically consistent +results without significantly impacting computational cost. + +---------- + The optional *heat* keyword enables heat conduction. The options currently supported are: @@ -674,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 @@ -778,8 +944,9 @@ or E_{eff,ij} = \frac{E_{ij}}{2(1-\nu_{ij}^2)} -These pair styles write their information to :doc:`binary restart files `, so a pair_style command does not need to be -specified in an input script that reads a restart file. +These pair styles write their information to :doc:`binary restart files `, +so a pair_style command does not need to be specified in an input script that reads +a restart file. These pair styles can only be used via the *pair* keyword of the :doc:`run_style respa ` command. They do not support the @@ -789,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 @@ -797,12 +964,20 @@ 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*\ . +These extra quantities can be accessed by the :doc:`compute pair/local +` command, as *p1*, *p2*, ..., *p12*\ . ---------- @@ -870,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: @@ -943,3 +1140,8 @@ I. Assembling process, geometry, and contact networks. Phys. Rev. E, 76, 061302. Heat conduction in granular materials. AIChE Journal, 47(5), 1052-1059. +.. _Vyas2025: + +**(Vyas et al, 2025)** Vyas D. R., Ottino J. M., Lueptow R. M., & Umbanhowar P. B. (2025). +Improved Velocity-Verlet Algorithm for the Discrete Element Method. +Computer Physics Communications, 109524. diff --git a/doc/src/pair_hbond_dreiding.rst b/doc/src/pair_hbond_dreiding.rst index ce19ff9e38..2c5059ffa9 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 """"""""""" @@ -49,21 +68,21 @@ force field, given by: .. math:: - E = & \left[LJ(r) | Morse(r) \right] \qquad \qquad \qquad r < r_{\rm in} \\ - = & S(r) * \left[LJ(r) | Morse(r) \right] \qquad \qquad r_{\rm in} < r < r_{\rm out} \\ - = & 0 \qquad \qquad \qquad \qquad \qquad \qquad \qquad r > r_{\rm out} \\ + E = & \left[LJ(r) | Morse(r) \right] \qquad \qquad \qquad r < r_\mathrm{in} \\ + = & S(r) * \left[LJ(r) | Morse(r) \right] \qquad \qquad r_\mathrm{in} < r < r_\mathrm{out} \\ + = & 0 \qquad \qquad \qquad \qquad \qquad \qquad \qquad r > r_\mathrm{out} \\ LJ(r) = & AR^{-12}-BR^{-10}cos^n\theta= \epsilon\left\lbrace 5\left[ \frac{\sigma}{r}\right]^{12}- 6\left[ \frac{\sigma}{r}\right]^{10} \right\rbrace cos^n\theta\\ Morse(r) = & D_0\left\lbrace \chi^2 - 2\chi\right\rbrace cos^n\theta= D_{0}\left\lbrace e^{- 2 \alpha (r - r_0)} - 2 e^{- \alpha (r - r_0)} \right\rbrace cos^n\theta \\ - S(r) = & \frac{ \left[r_{\rm out}^2 - r^2\right]^2 - \left[r_{\rm out}^2 + 2r^2 - 3{r_{\rm in}^2}\right]} - { \left[r_{\rm out}^2 - {r_{\rm in}}^2\right]^3 } + S(r) = & \frac{ \left[r_\mathrm{out}^2 - r^2\right]^2 + \left[r_\mathrm{out}^2 + 2r^2 - 3{r_\mathrm{in}^2}\right]} + { \left[r_\mathrm{out}^2 - {r_\mathrm{in}}^2\right]^3 } -where :math:`r_{\rm in}` is the inner spline distance cutoff, -:math:`r_{\rm out}` is the outer distance cutoff, :math:`\theta_c` is +where :math:`r_\mathrm{in}` is the inner spline distance cutoff, +:math:`r_\mathrm{out}` is the outer distance cutoff, :math:`\theta_c` is the angle cutoff, and :math:`n` is the power of the cosine of the angle :math:`\theta`. @@ -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 @@ -152,8 +189,8 @@ follows: * :math:`\epsilon` (energy units) * :math:`\sigma` (distance units) * *n* = exponent in formula above -* distance cutoff :math:`r_{\rm in}` (distance units) -* distance cutoff :math:`r_{\rm out}` (distance units) +* distance cutoff :math:`r_\mathrm{in}` (distance units) +* distance cutoff :math:`r_\mathrm{out}` (distance units) * angle cutoff (degrees) For the *hbond/dreiding/morse* style the list of coefficients is as @@ -165,11 +202,14 @@ follows: * :math:`\alpha` (1/distance units) * :math:`r_0` (distance units) * *n* = exponent in formula above -* distance cutoff :math:`r_{\rm in}` (distance units) +* distance cutoff :math:`r_\mathrm{in}` (distance units) * 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_ilp_graphene_hbn.rst b/doc/src/pair_ilp_graphene_hbn.rst index 36e971ef62..e50509497f 100644 --- a/doc/src/pair_ilp_graphene_hbn.rst +++ b/doc/src/pair_ilp_graphene_hbn.rst @@ -44,14 +44,14 @@ in :ref:`(Kolmogorov) `. .. math:: E = & \frac{1}{2} \sum_i \sum_{j \neq i} V_{ij} \\ - V_{ij} = & {\rm Tap}(r_{ij})\left \{ e^{-\alpha (r_{ij}/\beta -1)} + V_{ij} = & \mathrm{Tap}(r_{ij})\left \{ e^{-\alpha (r_{ij}/\beta -1)} \left [ \epsilon + f(\rho_{ij}) + f(\rho_{ji})\right ] - \frac{1}{1+e^{-d\left [ \left ( r_{ij}/\left (s_R \cdot r^{eff} \right ) \right )-1 \right ]}} \cdot \frac{C_6}{r^6_{ij}} \right \}\\ - \rho_{ij}^2 = & r_{ij}^2 - ({\bf r}_{ij} \cdot {\bf n}_i)^2 \\ - \rho_{ji}^2 = & r_{ij}^2 - ({\bf r}_{ij} \cdot {\bf n}_j)^2 \\ + \rho_{ij}^2 = & r_{ij}^2 - (\mathbf{r}_{ij} \cdot \mathbf{n}_i)^2 \\ + \rho_{ji}^2 = & r_{ij}^2 - (\mathbf{r}_{ij} \cdot \mathbf{n}_j)^2 \\ f(\rho) = & C e^{ -( \rho / \delta )^2 } \\ - {\rm Tap}(r_{ij}) = & 20\left ( \frac{r_{ij}}{R_{cut}} \right )^7 - + \mathrm{Tap}(r_{ij}) = & 20\left ( \frac{r_{ij}}{R_{cut}} \right )^7 - 70\left ( \frac{r_{ij}}{R_{cut}} \right )^6 + 84\left ( \frac{r_{ij}}{R_{cut}} \right )^5 - 35\left ( \frac{r_{ij}}{R_{cut}} \right )^4 + 1 diff --git a/doc/src/pair_ilp_tmd.rst b/doc/src/pair_ilp_tmd.rst index 575bafdc91..f486f73c69 100644 --- a/doc/src/pair_ilp_tmd.rst +++ b/doc/src/pair_ilp_tmd.rst @@ -41,14 +41,14 @@ as described in :ref:`(Ouyang7) ` and :ref:`(Jiang) `. .. math:: E = & \frac{1}{2} \sum_i \sum_{j \neq i} V_{ij} \\ - V_{ij} = & {\rm Tap}(r_{ij})\left \{ e^{-\alpha (r_{ij}/\beta -1)} + V_{ij} = & \mathrm{Tap}(r_{ij})\left \{ e^{-\alpha (r_{ij}/\beta -1)} \left [ \epsilon + f(\rho_{ij}) + f(\rho_{ji})\right ] - \frac{1}{1+e^{-d\left [ \left ( r_{ij}/\left (s_R \cdot r^{eff} \right ) \right )-1 \right ]}} \cdot \frac{C_6}{r^6_{ij}} \right \}\\ - \rho_{ij}^2 = & r_{ij}^2 - ({\bf r}_{ij} \cdot {\bf n}_i)^2 \\ - \rho_{ji}^2 = & r_{ij}^2 - ({\bf r}_{ij} \cdot {\bf n}_j)^2 \\ + \rho_{ij}^2 = & r_{ij}^2 - (\mathbf{r}_{ij} \cdot \mathbf{n}_i)^2 \\ + \rho_{ji}^2 = & r_{ij}^2 - (\mathbf{r}_{ij} \cdot \mathbf{n}_j)^2 \\ f(\rho) = & C e^{ -( \rho / \delta )^2 } \\ - {\rm Tap}(r_{ij}) = & 20\left ( \frac{r_{ij}}{R_{cut}} \right )^7 - + \mathrm{Tap}(r_{ij}) = & 20\left ( \frac{r_{ij}}{R_{cut}} \right )^7 - 70\left ( \frac{r_{ij}}{R_{cut}} \right )^6 + 84\left ( \frac{r_{ij}}{R_{cut}} \right )^5 - 35\left ( \frac{r_{ij}}{R_{cut}} \right )^4 + 1 @@ -67,7 +67,7 @@ calculating the normals. normal vectors used for graphene and h-BN is no longer valid for TMDs. In :ref:`(Ouyang7) `, a new definition is proposed, where for each atom `i`, its six nearest neighboring atoms belonging to the same - sub-layer are chosen to define the normal vector `{\bf n}_i`. + sub-layer are chosen to define the normal vector `\mathbf{n}_i`. The parameter file (e.g. TMD.ILP), is intended for use with *metal* :doc:`units `, with energies in meV. Two additional parameters, diff --git a/doc/src/pair_kolmogorov_crespi_full.rst b/doc/src/pair_kolmogorov_crespi_full.rst index 1a4706dd6f..2af56cbf9b 100644 --- a/doc/src/pair_kolmogorov_crespi_full.rst +++ b/doc/src/pair_kolmogorov_crespi_full.rst @@ -37,8 +37,8 @@ No simplification is made, E = & \frac{1}{2} \sum_i \sum_{j \neq i} V_{ij} \\ V_{ij} = & e^{-\lambda (r_{ij} -z_0)} \left [ C + f(\rho_{ij}) + f(\rho_{ji}) \right ] - A \left ( \frac{r_{ij}}{z_0}\right )^{-6} \\ - \rho_{ij}^2 = & r_{ij}^2 - ({\bf r}_{ij}\cdot {\bf n}_{i})^2 \\ - \rho_{ji}^2 = & r_{ij}^2 - ({\bf r}_{ij}\cdot {\bf n}_{j})^2 \\ + \rho_{ij}^2 = & r_{ij}^2 - (\mathbf{r}_{ij}\cdot \mathbf{n}_{i})^2 \\ + \rho_{ji}^2 = & r_{ij}^2 - (\mathbf{r}_{ij}\cdot \mathbf{n}_{j})^2 \\ f(\rho) & = e^{-(\rho/\delta)^2} \sum_{n=0}^2 C_{2n} { (\rho/\delta) }^{2n} It is important to have a sufficiently large cutoff to ensure smooth diff --git a/doc/src/pair_lj.rst b/doc/src/pair_lj.rst index 1a099e009b..b1e25cfc9f 100644 --- a/doc/src/pair_lj.rst +++ b/doc/src/pair_lj.rst @@ -68,7 +68,7 @@ LJ cutoff specified in the pair_style command is used. Note that :math:`\sigma` is defined in the LJ formula as the zero-crossing distance for the potential, *not* as the energy minimum at -:math:`r_0 = 2^{\frac{1}{6}} \sigma`. The _same_ potential function becomes: +:math:`r_0 = 2^{\frac{1}{6}} \sigma`. The *same* potential function becomes: .. math:: diff --git a/doc/src/pair_lj_cut_coul.rst b/doc/src/pair_lj_cut_coul.rst index aa5f7a2620..da39ac1645 100644 --- a/doc/src/pair_lj_cut_coul.rst +++ b/doc/src/pair_lj_cut_coul.rst @@ -194,9 +194,9 @@ summation method, described in :ref:`Wolf `, given by: .. math:: E_i = \frac{1}{2} \sum_{j \neq i} - \frac{q_i q_j {\rm erfc}(\alpha r_{ij})}{r_{ij}} + + \frac{q_i q_j \mathrm{erfc}(\alpha r_{ij})}{r_{ij}} + \frac{1}{2} \sum_{j \neq i} - \frac{q_i q_j {\rm erf}(\alpha r_{ij})}{r_{ij}} \qquad r < r_c + \frac{q_i q_j \mathrm{erf}(\alpha r_{ij})}{r_{ij}} \qquad r < r_c where :math:`\alpha` is the damping parameter, and erfc() is the complementary error-function terms. This potential is essentially a diff --git a/doc/src/pair_mesodpd.rst b/doc/src/pair_mesodpd.rst index 6674b013ba..269701ee27 100644 --- a/doc/src/pair_mesodpd.rst +++ b/doc/src/pair_mesodpd.rst @@ -200,7 +200,7 @@ force :math:`F_{ij}^C` are expressed as \mathbf{F}_{ij}^{D} & = -\gamma {\omega_{D}}(r_{ij})(\mathbf{e}_{ij} \cdot \mathbf{v}_{ij})\mathbf{e}_{ij} \\ \mathbf{F}_{ij}^{R} & = \sigma {\omega_{R}}(r_{ij}){\xi_{ij}}\Delta t^{-1/2} \mathbf{e}_{ij} \\ \omega_{C}(r) & = 1 - r/r_c \\ - \omega_{D}(r) & = \omega^2_{R}(r) = (1-r/r_c)^{\rm power_f} \\ + \omega_{D}(r) & = \omega^2_{R}(r) = (1-r/r_c)^\mathrm{power_f} \\ \sigma^2 = 2\gamma k_B T The concentration flux between two tDPD particles includes the Fickian @@ -211,7 +211,7 @@ by Q_{ij}^D & = -\kappa_{ij} w_{DC}(r_{ij}) \left( C_i - C_j \right) \\ Q_{ij}^R & = \epsilon_{ij}\left( C_i + C_j \right) w_{RC}(r_{ij}) \xi_{ij} \\ - w_{DC}(r_{ij}) & =w^2_{RC}(r_{ij}) = (1 - r/r_{cc})^{\rm power_{cc}} \\ + w_{DC}(r_{ij}) & =w^2_{RC}(r_{ij}) = (1 - r/r_{cc})^\mathrm{power_{cc}} \\ \epsilon_{ij}^2 & = m_s^2\kappa_{ij}\rho where the parameters kappa and epsilon determine the strength of the diff --git a/doc/src/pair_mgpt.rst b/doc/src/pair_mgpt.rst index 92bf9cd738..e492e555ac 100644 --- a/doc/src/pair_mgpt.rst +++ b/doc/src/pair_mgpt.rst @@ -33,7 +33,7 @@ elemental bulk material in the form .. math:: - E_{\rm tot}({\bf R}_1 \ldots {\bf R}_N) = NE_{\rm vol}(\Omega ) + E_\mathrm{tot}(\mathbf{R}_1 \ldots \mathbf{R}_N) = NE_\mathrm{vol}(\Omega ) + \frac{1}{2} \sum _{i,j} \mbox{}^\prime \ v_2(ij;\Omega ) + \frac{1}{6} \sum _{i,j,k} \mbox{}^\prime \ v_3(ijk;\Omega ) + \frac{1}{24} \sum _{i,j,k,l} \mbox{}^\prime \ v_4(ijkl;\Omega ) 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_saip_metal.rst b/doc/src/pair_saip_metal.rst index ed011894c9..211e5e9359 100644 --- a/doc/src/pair_saip_metal.rst +++ b/doc/src/pair_saip_metal.rst @@ -41,14 +41,14 @@ potential (ILP) potential for hetero-junctions formed with hexagonal .. math:: E = & \frac{1}{2} \sum_i \sum_{j \neq i} V_{ij} \\ - V_{ij} = & {\rm Tap}(r_{ij})\left \{ e^{-\alpha (r_{ij}/\beta -1)} + V_{ij} = & \mathrm{Tap}(r_{ij})\left \{ e^{-\alpha (r_{ij}/\beta -1)} \left [ \epsilon + f(\rho_{ij}) + f(\rho_{ji})\right ] - \frac{1}{1+e^{-d\left [ \left ( r_{ij}/\left (s_R \cdot r^{eff} \right ) \right )-1 \right ]}} \cdot \frac{C_6}{r^6_{ij}} \right \}\\ - \rho_{ij}^2 = & r_{ij}^2 - ({\bf r}_{ij} \cdot {\bf n}_i)^2 \\ - \rho_{ji}^2 = & r_{ij}^2 - ({\bf r}_{ij} \cdot {\bf n}_j)^2 \\ + \rho_{ij}^2 = & r_{ij}^2 - (\mathbf{r}_{ij} \cdot \mathbf{n}_i)^2 \\ + \rho_{ji}^2 = & r_{ij}^2 - (\mathbf{r}_{ij} \cdot \mathbf{n}_j)^2 \\ f(\rho) = & C e^{ -( \rho / \delta )^2 } \\ - {\rm Tap}(r_{ij}) = & 20\left ( \frac{r_{ij}}{R_{cut}} \right )^7 - + \mathrm{Tap}(r_{ij}) = & 20\left ( \frac{r_{ij}}{R_{cut}} \right )^7 - 70\left ( \frac{r_{ij}}{R_{cut}} \right )^6 + 84\left ( \frac{r_{ij}}{R_{cut}} \right )^5 - 35\left ( \frac{r_{ij}}{R_{cut}} \right )^4 + 1 @@ -63,8 +63,8 @@ calculating the normals. .. note:: To account for the isotropic nature of the isolated gold atom - electron cloud, their corresponding normal vectors (`{\bf n}_i`) are - assumed to lie along the interatomic vector `{\bf r}_ij`. Notably, this + electron cloud, their corresponding normal vectors (`\mathbf{n}_i`) are + assumed to lie along the interatomic vector `\mathbf{r}_ij`. Notably, this assumption is suitable for many bulk material surfaces, for example, for systems possessing s-type valence orbitals or metallic surfaces, whose valence electrons are mostly diff --git a/doc/src/pair_spin_dipole.rst b/doc/src/pair_spin_dipole.rst index c38bba03ae..faa2bc7461 100644 --- a/doc/src/pair_spin_dipole.rst +++ b/doc/src/pair_spin_dipole.rst @@ -43,7 +43,7 @@ vector omega and mechanical force between particles I and J. .. math:: - \mathcal{H}_{\rm long} & = + \mathcal{H}_\mathrm{long} & = -\frac{\mu_{0} \left( \mu_B\right)^2}{4\pi} \sum_{i,j,i\neq j}^{N} \frac{g_i g_j}{r_{ij}^3} diff --git a/doc/src/pair_spin_dmi.rst b/doc/src/pair_spin_dmi.rst index 282da39ff7..bb98c72d84 100644 --- a/doc/src/pair_spin_dmi.rst +++ b/doc/src/pair_spin_dmi.rst @@ -52,7 +52,7 @@ particle i: .. math:: \vec{\omega}_i = -\frac{1}{\hbar} \sum_{j}^{Neighb} \vec{s}_{j}\times \left(\vec{e}_{ij}\times \vec{D} \right) - ~~{\rm and}~~ + ~~\mathrm{and}~~ \vec{F}_i = -\sum_{j}^{Neighb} \frac{1}{r_{ij}} \vec{D} \times \left( \vec{s}_{i}\times \vec{s}_{j} \right) More details about the derivation of these torques/forces are reported in diff --git a/doc/src/pair_spin_exchange.rst b/doc/src/pair_spin_exchange.rst index 553af72983..a922c45a8d 100644 --- a/doc/src/pair_spin_exchange.rst +++ b/doc/src/pair_spin_exchange.rst @@ -94,7 +94,7 @@ submitted to a force :math:`\vec{F}_{i}` for spin-lattice calculations (see \vec{\omega}_{i} = \frac{1}{\hbar} \sum_{j}^{Neighb} {J} \left(r_{ij} \right)\,\vec{s}_{j} - ~~{\rm and}~~ + ~~\mathrm{and}~~ \vec{F}_{i} = \sum_{j}^{Neighb} \frac{\partial {J} \left(r_{ij} \right)}{ \partial r_{ij}} \left( \vec{s}_{i}\cdot \vec{s}_{j} \right) \vec{e}_{ij} 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..dbe14360ff 100644 --- a/doc/src/region.rst +++ b/doc/src/region.rst @@ -40,12 +40,13 @@ Syntax *plane* args = px py pz nx ny nz px,py,pz = point on the plane (distance units) nx,ny,nz = direction normal to plane (distance units) - px,py,pz can be a variable (see below) + px,py,pz,nx,ny,nz can be a variable (see below) *prism* args = xlo xhi ylo yhi zlo zhi xy xz yz xlo,xhi,ylo,yhi,zlo,zhi = bounds of untilted prism (distance units) 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) @@ -210,9 +211,11 @@ equal-style :doc:`variable `. Likewise, for style *sphere* 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 -style *plane* the point can be defined via equal-style variables. +the cylinder axes can be specified as a equal-style variable. For styles +*block*, *cone*, *prism*, and *plane* all properties can be defined via +equal-style variables. For style *plane*, the components of the direction +vector normal to plane should be either all constants or all defined by +equal-style variables. If the value is a variable, it should be specified as v_name, where name is the variable name. In this case, the variable will be @@ -225,6 +228,21 @@ keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent radius or have a time dependent position of the sphere or cylinder region. +.. note:: + + Whenever a region property, such as a coordinate or an upper/lower + bound, is defined via an equal-style variable, the variable should + not cause any of the region boundaries to move + too far within a single timestep. Otherwise, bad dynamics will occur. + "Too far" means a small fraction of the approximate distance of + closest approach between two particles, which for the case of Lennard-Jones + particles is the distance of the energy minimum while for granular + particles it is their diameter. An example is a rapidly varying direction + vector in region plane since a small change in the normal to plane will + shift the region surface far away from the region point by a large displacement. + Similarly, bad dynamics can also occur for fast changing variables employed + in the move/rotate options. + See the :doc:`Howto tricilinc ` page for a geometric description of triclinic boxes, as defined by LAMMPS, and how to transform these parameters to and from other commonly used diff --git a/doc/src/region2vmd.rst b/doc/src/region2vmd.rst new file mode 100644 index 0000000000..760facf06f --- /dev/null +++ b/doc/src/region2vmd.rst @@ -0,0 +1,179 @@ +.. 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