diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 1a7a35e61f..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 @@ -101,7 +103,8 @@ src/group.* @sjplimp src/improper.* @sjplimp src/info.* @akohlmey src/kspace.* @sjplimp -src/lmptyp.h @sjplimp +src/lmptype.h @sjplimp +src/label_map.* @jrgissing @akohlmey src/library.* @sjplimp @akohlmey src/main.cpp @sjplimp src/min_*.* @sjplimp diff --git a/.github/release_steps.md b/.github/release_steps.md new file mode 100644 index 0000000000..1ffd3cb291 --- /dev/null +++ b/.github/release_steps.md @@ -0,0 +1,370 @@ +# LAMMPS Release Steps + +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. + +### 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" +- 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. 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'. + +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 +git pull +git checkout release +git pull +git merge --ff-only develop +git tag -s -m "LAMMPS feature release 4 February 2025" patch_4Feb2025 +git push git@github.com:lammps/lammps.git --tags develop release +``` + +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. + +### Prepare pre-compiled packages, update packages to GitHub + +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. + +#### 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: + +``` 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. + +### Prerequesites + +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. + +### 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). + +### 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. + +### 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-cpp23.yml b/.github/workflows/check-cpp23.yml new file mode 100644 index 0000000000..2cd53f2208 --- /dev/null +++ b/.github/workflows/check-cpp23.yml @@ -0,0 +1,92 @@ +# GitHub action to build LAMMPS on Linux with gcc and C++23 +name: "Check for C++23 Compatibility" + +on: + push: + branches: + - develop + pull_request: + branches: + - develop + + workflow_dispatch: + +jobs: + build: + name: Build with C++23 support enabled + if: ${{ github.repository == 'lammps/lammps' }} + runs-on: ubuntu-latest + 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 \ + mpi-default-bin \ + mpi-default-dev \ + 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-cpp23-ccache-${{ github.sha }} + restore-keys: linux-cpp23-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/most.cmake \ + -C cmake/presets/kokkos-openmp.cmake \ + -D CMAKE_CXX_STANDARD=23 \ + -D CMAKE_CXX_COMPILER=g++ \ + -D CMAKE_C_COMPILER=gcc \ + -D CMAKE_CXX_COMPILER_LAUNCHER=ccache \ + -D CMAKE_C_COMPILER_LAUNCHER=ccache \ + -D CMAKE_BUILD_TYPE=Debug \ + -D CMAKE_CXX_FLAGS_DEBUG="-Og -g" \ + -D DOWNLOAD_POTENTIALS=off \ + -D BUILD_MPI=on \ + -D BUILD_SHARED_LIBS=on \ + -D BUILD_TOOLS=off \ + -D ENABLE_TESTING=off \ + -D MLIAP_ENABLE_ACE=on \ + -D MLIAP_ENABLE_PYTHON=off \ + -D PKG_AWPMD=on \ + -D PKG_GPU=on \ + -D GPU_API=opencl \ + -D PKG_KOKKOS=on \ + -D PKG_LATBOLTZ=on \ + -D PKG_MDI=on \ + -D PKG_MANIFOLD=on \ + -D PKG_ML-PACE=on \ + -D PKG_ML-RANN=off \ + -D PKG_MOLFILE=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 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/kokkos-regression.yaml b/.github/workflows/kokkos-regression.yaml new file mode 100644 index 0000000000..a475c1eb7b --- /dev/null +++ b/.github/workflows/kokkos-regression.yaml @@ -0,0 +1,126 @@ +# GitHub action to build LAMMPS on Linux and run selected regression tests +name: "Kokkos OpenMP Regression Test" + +on: + push: + branches: + - develop + + workflow_dispatch: + +jobs: + build: + name: Build LAMMPS with Kokkos OpenMP + # restrict to official LAMMPS repository + if: ${{ github.repository == 'lammps/lammps' }} + runs-on: ubuntu-latest + env: + CCACHE_DIR: ${{ github.workspace }}/.ccache + strategy: + max-parallel: 6 + matrix: + idx: [ 'pair-0', 'pair-1', 'fix-0', 'fix-1', 'compute', 'misc' ] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 2 + show-progress: false + + - name: Install extra packages + run: | + sudo apt-get update + sudo apt-get install -y ccache ninja-build libeigen3-dev \ + libcurl4-openssl-dev python3-dev \ + mpi-default-bin mpi-default-dev + + - name: Create Build Environment + run: mkdir build + + - name: Set up ccache + uses: actions/cache@v4 + with: + path: ${{ env.CCACHE_DIR }} + key: linux-kokkos-ccache-${{ github.sha }} + restore-keys: linux-kokkos-ccache- + + - name: Building LAMMPS via CMake + shell: bash + run: | + ccache -z + python3 -m venv linuxenv + source linuxenv/bin/activate + python3 -m pip install --upgrade pip + python3 -m pip install numpy pyyaml junit_xml + cmake -S cmake -B build \ + -C cmake/presets/gcc.cmake \ + -C cmake/presets/basic.cmake \ + -C cmake/presets/kokkos-openmp.cmake \ + -D CMAKE_CXX_COMPILER_LAUNCHER=ccache \ + -D CMAKE_C_COMPILER_LAUNCHER=ccache \ + -D BUILD_SHARED_LIBS=off \ + -D DOWNLOAD_POTENTIALS=off \ + -D PKG_AMOEBA=on \ + -D PKG_ASPHERE=on \ + -D PKG_BROWNIAN=on \ + -D PKG_CLASS2=on \ + -D PKG_COLLOID=on \ + -D PKG_CORESHELL=on \ + -D PKG_DIPOLE=on \ + -D PKG_DPD-BASIC=on \ + -D PKG_EXTRA-COMPUTE=on \ + -D PKG_EXTRA-FIX=on \ + -D PKG_EXTRA-MOLECULE=on \ + -D PKG_EXTRA-PAIR=on \ + -D PKG_GRANULAR=on \ + -D PKG_LEPTON=on \ + -D PKG_MC=on \ + -D PKG_MEAM=on \ + -D PKG_POEMS=on \ + -D PKG_PYTHON=on \ + -D PKG_QEQ=on \ + -D PKG_REAXFF=on \ + -D PKG_REPLICA=on \ + -D PKG_SRD=on \ + -D PKG_SPH=on \ + -D PKG_VORONOI=on \ + -G Ninja + cmake --build build + ccache -s + + - name: Run Regression Tests for Selected Examples + shell: bash + run: | + source linuxenv/bin/activate + python3 tools/regression-tests/get_kokkos_input.py \ + --examples-top-level=examples --batch-size=50 \ + --filter-out="balance;fire;gcmc;granregion;hyper;mc;mdi;mliap;neb;pace;prd;pour;python;rigid;snap;streitz;shear;ttm" + + export OMP_PROC_BIND=false + python3 tools/regression-tests/run_tests.py \ + --lmp-bin=build/lmp \ + --config-file=tools/regression-tests/config_kokkos_openmp.yaml \ + --list-input=input-list-${{ matrix.idx }}-kk.txt \ + --output-file=output-${{ matrix.idx }}.xml \ + --progress-file=progress-${{ matrix.idx }}.yaml \ + --log-file=run-${{ matrix.idx }}.log \ + --quick-max=100 + + tar -cvf kokkos-regression-test-${{ matrix.idx }}.tar run-${{ matrix.idx }}.log progress-${{ matrix.idx }}.yaml output-${{ matrix.idx }}.xml + + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: kokkos-regression-test-artifact-${{ matrix.idx }} + path: kokkos-regression-test-${{ matrix.idx }}.tar + + merge: + runs-on: ubuntu-latest + needs: build + steps: + - name: Merge Artifacts + uses: actions/upload-artifact/merge@v4 + with: + name: merged-kokkos-regresssion-artifact + pattern: kokkos-regression-test-artifact-* 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 1bd387b5b9..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) @@ -118,7 +121,7 @@ endif() # silence excessive warnings for new Intel Compilers if(CMAKE_CXX_COMPILER_ID STREQUAL "IntelLLVM") - set(CMAKE_TUNE_DEFAULT "-Wno-tautological-constant-compare -Wno-unused-command-line-argument") + set(CMAKE_TUNE_DEFAULT "-fp-model precise -Wno-tautological-constant-compare -Wno-unused-command-line-argument") endif() # silence excessive warnings for PGI/NVHPC compilers @@ -141,19 +144,31 @@ endif() # silence nvcc warnings if((PKG_KOKKOS) AND (Kokkos_ENABLE_CUDA) AND NOT (CMAKE_CXX_COMPILER_ID STREQUAL "Clang")) - set(CMAKE_TUNE_DEFAULT "${CMAKE_TUNE_DEFAULT} -Xcudafe --diag_suppress=unrecognized_pragma") + 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 @@ -165,6 +180,7 @@ if(MSVC) add_compile_options(/wd4267) add_compile_options(/wd4250) add_compile_options(/EHsc) + add_compile_options(/utf-8) endif() add_compile_definitions(_CRT_SECURE_NO_WARNINGS) endif() @@ -193,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() @@ -209,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) @@ -346,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 ###################################################### @@ -398,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) @@ -578,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) @@ -587,13 +630,8 @@ endif() set(CMAKE_TUNE_FLAGS "${CMAKE_TUNE_DEFAULT}" CACHE STRING "Compiler and machine specific optimization flags (compilation only)") separate_arguments(CMAKE_TUNE_FLAGS) -foreach(_FLAG ${CMAKE_TUNE_FLAGS}) - target_compile_options(lammps PRIVATE ${_FLAG}) - # skip these flags when linking the main executable - if(NOT (("${_FLAG}" STREQUAL "-Xcudafe") OR (("${_FLAG}" STREQUAL "--diag_suppress=unrecognized_pragma")))) - target_compile_options(lmp PRIVATE ${_FLAG}) - endif() -endforeach() +target_compile_options(lammps PRIVATE ${CMAKE_TUNE_FLAGS}) +target_compile_options(lmp PRIVATE ${CMAKE_TUNE_FLAGS}) ######################################################################## # Basic system tests (standard libraries, headers, functions, types) # ######################################################################## @@ -822,9 +860,15 @@ foreach(_DEF ${LAMMPS_DEFINES}) set(LAMMPS_API_DEFINES "${LAMMPS_API_DEFINES} -D${_DEF}") endforeach() if(BUILD_SHARED_LIBS) - install(TARGETS lammps EXPORT LAMMPS_Targets LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}) + install(TARGETS lammps EXPORT LAMMPS_Targets + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}) if(NOT BUILD_MPI) - install(TARGETS mpi_stubs EXPORT LAMMPS_Targets LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}) + install(TARGETS mpi_stubs EXPORT LAMMPS_Targets + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}) endif() configure_file(pkgconfig/liblammps.pc.in ${CMAKE_CURRENT_BINARY_DIR}/liblammps${LAMMPS_MACHINE}.pc @ONLY) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/liblammps${LAMMPS_MACHINE}.pc DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig) @@ -892,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 @@ -1076,12 +1120,15 @@ if(BUILD_TOOLS) message(STATUS "<<< Building Tools >>>") endif() if(BUILD_LAMMPS_GUI) - message(STATUS "<<< Building LAMMPS GUI >>>") + message(STATUS "<<< Building LAMMPS-GUI >>>") if(LAMMPS_GUI_USE_PLUGIN) message(STATUS "Loading LAMMPS library as plugin at run time") else() message(STATUS "Linking LAMMPS library at compile time") endif() + if(BUILD_WHAM) + message(STATUS "<<< Building WHAM >>>") + endif() endif() if(ENABLE_TESTING) message(STATUS "<<< Building Unit Tests >>>") 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 7b8f4a5ba0..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) @@ -110,6 +110,7 @@ if(BUILD_DOC) add_custom_command( OUTPUT html DEPENDS ${DOC_SOURCES} ${DOCENV_DEPS} ${DOXYGEN_XML_DIR}/index.xml ${BUILD_DOC_CONFIG_FILE} + COMMAND ${Python3_EXECUTABLE} ${LAMMPS_DOC_DIR}/utils/make-globbed-tocs.py -d ${LAMMPS_DOC_DIR}/src COMMAND Sphinx::sphinx-build ${SPHINX_EXTRA_OPTS} -b html -c ${DOC_BUILD_DIR} -d ${DOC_BUILD_DIR}/doctrees ${LAMMPS_DOC_DIR}/src ${DOC_BUILD_DIR}/html COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${DOC_BUILD_DIR}/html/index.html COMMAND ${CMAKE_COMMAND} -E copy_directory ${LAMMPS_DOC_DIR}/src/PDF ${DOC_BUILD_DIR}/html/PDF diff --git a/cmake/Modules/FindVORO.cmake b/cmake/Modules/FindVORO.cmake index 3f0fe98ff1..80bcfcfb53 100644 --- a/cmake/Modules/FindVORO.cmake +++ b/cmake/Modules/FindVORO.cmake @@ -21,9 +21,9 @@ if(VORO_FOUND) set(VORO_LIBRARIES ${VORO_LIBRARY}) set(VORO_INCLUDE_DIRS ${VORO_INCLUDE_DIR}) - if(NOT TARGET VORO::VORO) - add_library(VORO::VORO UNKNOWN IMPORTED) - set_target_properties(VORO::VORO PROPERTIES + if(NOT TARGET VORO::voro++) + add_library(VORO::voro++ UNKNOWN IMPORTED) + set_target_properties(VORO::voro++ PROPERTIES IMPORTED_LOCATION "${VORO_LIBRARY}" INTERFACE_INCLUDE_DIRECTORIES "${VORO_INCLUDE_DIR}") endif() 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/H5MD.cmake b/cmake/Modules/Packages/H5MD.cmake index 6f6922f13e..1e611b94e6 100644 --- a/cmake/Modules/Packages/H5MD.cmake +++ b/cmake/Modules/Packages/H5MD.cmake @@ -3,7 +3,7 @@ enable_language(C) # we don't use the parallel i/o interface. set(HDF5_PREFER_PARALLEL FALSE) -find_package(HDF5 REQUIRED) +find_package(HDF5 COMPONENTS C REQUIRED) # parallel HDF5 will import incompatible MPI headers with a serial build if((NOT BUILD_MPI) AND HDF5_IS_PARALLEL) 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 bf0a18d324..2731b0df14 100644 --- a/cmake/Modules/Packages/KOKKOS.cmake +++ b/cmake/Modules/Packages/KOKKOS.cmake @@ -7,10 +7,13 @@ endif() ######################################################################## # consistency checks and Kokkos options/settings required by LAMMPS -if(Kokkos_ENABLE_CUDA) - message(STATUS "KOKKOS: Enabling CUDA LAMBDA function support") - set(Kokkos_ENABLE_CUDA_LAMBDA ON CACHE BOOL "" FORCE) +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) endif() + # Adding OpenMP compiler flags without the checks done for # BUILD_OMP can result in compile failures. Enforce consistency. if(Kokkos_ENABLE_OPENMP) @@ -18,6 +21,15 @@ if(Kokkos_ENABLE_OPENMP) message(FATAL_ERROR "Must enable BUILD_OMP with Kokkos_ENABLE_OPENMP") endif() endif() + +if(Kokkos_ENABLE_SERIAL) + if(NOT (Kokkos_ENABLE_OPENMP OR Kokkos_ENABLE_THREADS OR + Kokkos_ENABLE_CUDA OR Kokkos_ENABLE_HIP OR Kokkos_ENABLE_SYCL + OR Kokkos_ENABLE_OPENMPTARGET)) + option(Kokkos_ENABLE_ATOMICS_BYPASS "Disable atomics for Kokkos Serial Backend" ON) + mark_as_advanced(Kokkos_ENABLE_ATOMICS_BYPASS) + endif() +endif() ######################################################################## option(EXTERNAL_KOKKOS "Build against external kokkos library" OFF) @@ -45,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.3.01.tar.gz" CACHE STRING "URL for KOKKOS tarball") - set(KOKKOS_MD5 "243de871b3dc2cf3990c1c404032df83" 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) @@ -71,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.3.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) 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/Modules/Packages/VORONOI.cmake b/cmake/Modules/Packages/VORONOI.cmake index c010469677..cbc350340f 100644 --- a/cmake/Modules/Packages/VORONOI.cmake +++ b/cmake/Modules/Packages/VORONOI.cmake @@ -54,5 +54,5 @@ else() if(NOT VORO_FOUND) message(FATAL_ERROR "Voro++ library not found. Help CMake to find it by setting VORO_LIBRARY and VORO_INCLUDE_DIR, or set DOWNLOAD_VORO=ON to download it") endif() - target_link_libraries(lammps PRIVATE VORO::VORO) + target_link_libraries(lammps PRIVATE VORO::voro++) endif() diff --git a/cmake/Modules/Packages/VTK.cmake b/cmake/Modules/Packages/VTK.cmake index a0de1e0ff4..48b1cdba11 100644 --- a/cmake/Modules/Packages/VTK.cmake +++ b/cmake/Modules/Packages/VTK.cmake @@ -1,3 +1,5 @@ +# FindVTK requires that C support is enabled when looking for MPI support +enable_language(C) find_package(VTK REQUIRED NO_MODULE) target_compile_definitions(lammps PRIVATE -DLAMMPS_VTK) if (VTK_MAJOR_VERSION VERSION_LESS 9.0) 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/cmake/presets/kokkos-sycl-intel.cmake b/cmake/presets/kokkos-sycl-intel.cmake index 3fc75e4b2d..eba386564d 100644 --- a/cmake/presets/kokkos-sycl-intel.cmake +++ b/cmake/presets/kokkos-sycl-intel.cmake @@ -6,13 +6,24 @@ set(Kokkos_ENABLE_OPENMP ON CACHE BOOL "" FORCE) set(Kokkos_ENABLE_CUDA OFF CACHE BOOL "" FORCE) set(Kokkos_ENABLE_SYCL ON CACHE BOOL "" FORCE) +set(FFT "MKL" CACHE STRING "" FORCE) +set(FFT_KOKKOS "MKL_GPU" CACHE STRING "" FORCE) + +unset(USE_INTERNAL_LINALG) +unset(USE_INTERNAL_LINALG CACHE) +set(BLAS_VENDOR "Intel10_64_dyn") + # hide deprecation warnings temporarily for stable release set(Kokkos_ENABLE_DEPRECATION_WARNINGS OFF CACHE BOOL "" FORCE) set(CMAKE_CXX_COMPILER icpx CACHE STRING "" FORCE) +set(CMAKE_C_COMPILER icx CACHE STRING "" FORCE) +set(CMAKE_Fortran_COMPILER "" CACHE STRING "" FORCE) set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE) set(CMAKE_CXX_STANDARD 17 CACHE STRING "" FORCE) # Silence everything set(CMAKE_CXX_FLAGS "-w" CACHE STRING "" FORCE) -set(CMAKE_EXE_LINKER_FLAGS "-fsycl -flink-huge-device-code -fsycl-max-parallel-link-jobs=32 -fsycl-targets=spir64_gen -Xsycl-target-backend \"-device 12.60.7\" " CACHE STRING "" FORCE) -set(CMAKE_TUNE_FLAGS "-O3 -fsycl -fsycl-device-code-split=per_kernel -fsycl-targets=spir64_gen" CACHE STRING "" FORCE) +#set(CMAKE_EXE_LINKER_FLAGS "-fsycl -flink-huge-device-code -fsycl-targets=spir64_gen " CACHE STRING "" FORCE) +#set(CMAKE_TUNE_FLAGS "-O3 -fsycl -fsycl-device-code-split=per_kernel -fsycl-targets=spir64_gen" CACHE STRING "" FORCE) +set(CMAKE_EXE_LINKER_FLAGS "-fsycl -flink-huge-device-code " CACHE STRING "" FORCE) +set(CMAKE_TUNE_FLAGS "-O3 -fsycl -fsycl-device-code-split=per_kernel " CACHE STRING "" FORCE) diff --git a/cmake/presets/oneapi.cmake b/cmake/presets/oneapi.cmake index 393d1d9b68..d98817e4b0 100644 --- a/cmake/presets/oneapi.cmake +++ b/cmake/presets/oneapi.cmake @@ -3,26 +3,9 @@ set(CMAKE_CXX_COMPILER "icpx" CACHE STRING "" FORCE) set(CMAKE_C_COMPILER "icx" CACHE STRING "" FORCE) set(CMAKE_Fortran_COMPILER "ifx" CACHE STRING "" FORCE) -set(CMAKE_CXX_FLAGS_DEBUG "-Wall -Wextra -g" CACHE STRING "" FORCE) -set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "-Wall -Wextra -g -O2 -DNDEBUG" CACHE STRING "" FORCE) -set(CMAKE_CXX_FLAGS_RELEASE "-O3 -DNDEBUG" CACHE STRING "" FORCE) -set(CMAKE_Fortran_FLAGS_DEBUG "-Wall -Wextra -g" CACHE STRING "" FORCE) -set(CMAKE_Fortran_FLAGS_RELWITHDEBINFO "-Wall -Wextra -g -O2 -DNDEBUG" CACHE STRING "" FORCE) -set(CMAKE_Fortran_FLAGS_RELEASE "-O3 -DNDEBUG" CACHE STRING "" FORCE) -set(CMAKE_C_FLAGS_DEBUG "-Wall -Wextra -g" CACHE STRING "" FORCE) -set(CMAKE_C_FLAGS_RELWITHDEBINFO "-Wall -Wextra -g -O2 -DNDEBUG" CACHE STRING "" FORCE) -set(CMAKE_C_FLAGS_RELEASE "-O3 -DNDEBUG" CACHE STRING "" FORCE) - set(MPI_CXX "icpx" CACHE STRING "" FORCE) set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE) -unset(HAVE_OMP_H_INCLUDE CACHE) -set(OpenMP_C "icx" CACHE STRING "" FORCE) -set(OpenMP_C_FLAGS "-qopenmp;-qopenmp-simd" CACHE STRING "" FORCE) -set(OpenMP_C_LIB_NAMES "omp" CACHE STRING "" FORCE) -set(OpenMP_CXX "icpx" CACHE STRING "" FORCE) -set(OpenMP_CXX_FLAGS "-qopenmp;-qopenmp-simd" CACHE STRING "" FORCE) -set(OpenMP_CXX_LIB_NAMES "omp" CACHE STRING "" FORCE) -set(OpenMP_Fortran_FLAGS "-qopenmp;-qopenmp-simd" CACHE STRING "" FORCE) -set(OpenMP_omp_LIBRARY "libiomp5.so" CACHE PATH "" FORCE) +# force using internal BLAS/LAPCK since external ones may not be ABI compatible +set(USE_INTERNAL_LINALG ON CACHE BOOL "" FORCE) diff --git a/doc/.gitignore b/doc/.gitignore index 7c953d2432..28e583fa0b 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -17,3 +17,10 @@ *.el /utils/sphinx-config/_static/mathjax /utils/sphinx-config/_static/polyfill.js +/src/pairs.rst +/src/bonds.rst +/src/angles.rst +/src/dihedrals.rst +/src/impropers.rst +/src/computes.rst +/src/fixes.rst diff --git a/doc/Makefile b/doc/Makefile index f9f8336665..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: @@ -83,7 +90,10 @@ $(SPHINXCONFIG)/conf.py: $(SPHINXCONFIG)/conf.py.in -e 's,@LAMMPS_PYTHON_DIR@,$(BUILDDIR)/../python,g' \ -e 's,@LAMMPS_DOC_DIR@,$(BUILDDIR),g' $< > $@ -html: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX) +globbed-tocs: + $(PYTHON) $(BUILDDIR)/utils/make-globbed-tocs.py -d $(RSTDIR) + +html: 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 @(\ @@ -113,26 +123,24 @@ html: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX) @rm -rf html/PDF/.[sg]* @echo "Build finished. The HTML pages are in doc/html." -fasthtml: xmlgen $(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." -spelling: xmlgen $(SPHINXCONFIG)/conf.py $(VENV) $(SPHINXCONFIG)/false_positives.txt +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 @(\ . $(VENV)/bin/activate ; \ @@ -143,7 +151,7 @@ spelling: xmlgen $(SPHINXCONFIG)/conf.py $(VENV) $(SPHINXCONFIG)/false_positives ) @echo "Spell check finished." -epub: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) +epub: xmlgen globbed-tocs $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) @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 epub/JPG @@ -166,7 +174,7 @@ mobi: epub @ebook-convert LAMMPS.epub LAMMPS.mobi @echo "Conversion finished. The MOBI manual file is created." -pdf: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) +pdf: xmlgen globbed-tocs $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) @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 @if [ "$(HAS_PDFLATEX)" == "NO" ] ; then echo "PDFLaTeX or latexmk were not found! Please check README for further instructions" 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/documentation_conventions.md b/doc/documentation_conventions.md index c4757b85e9..e02b0c77a3 100644 --- a/doc/documentation_conventions.md +++ b/doc/documentation_conventions.md @@ -10,7 +10,7 @@ Last change: 2022-12-30 In fall 2019, the LAMMPS documentation file format has changed from a home grown markup designed to generate HTML format files only, to -[reStructuredText](https://docutils.sourceforge.io/rst.html>. For a +[reStructuredText](https://docutils.sourceforge.io/rst.html>). For a transition period all files in the old .txt format were transparently converted to .rst and then processed. The `txt2rst tool` is still included in the distribution to obtain an initial .rst file for legacy @@ -45,8 +45,7 @@ what kind of information and sections are needed. ## Formatting conventions -For headlines we try to follow the conventions posted here: -https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html#headings +For headlines we try to follow the conventions posted [here](https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html#headings). It seems to be sufficient to have this consistent only within any single file and it is not (yet) enforced strictly, but making this globally consistent makes it easier to move sections around. @@ -64,7 +63,7 @@ Groups of shell commands or LAMMPS input script or C/C++/Python source code should be typeset into a `.. code-block::` section. A syntax highlighting extension for LAMMPS input scripts is provided, so `LAMMPS` can be used to indicate the language in the code block in addition to -`bash`, `c`, `c++`, `console`, `csh`, `diff', `fortran`, `json`, `make`, +`bash`, `c`, `c++`, `console`, `csh`, `diff`, `fortran`, `json`, `make`, `perl`, `powershell`, `python`, `sh`, or `tcl`, `text`, or `yaml`. When no syntax style is indicated, no syntax highlighting is performed. When typesetting commands executed on the shell, please do not prefix @@ -84,7 +83,7 @@ block can be used, followed by multiple `.. tab::` blocks, one for each alternative. This is only used for HTML output. For other outputs, the `.. tabs::` directive is transparently removed and the individual `.. tab::` blocks will be replaced with an -`.. admonition::`` block. Thus in PDF and ePUB output those will +`.. admonition::` block. Thus in PDF and ePUB output those will be realized as sequential and plain notes. Special remarks can be highlighted with a `.. note::` block and diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in index e905d5a64d..e3a5415b20 100644 --- a/doc/doxygen/Doxyfile.in +++ b/doc/doxygen/Doxyfile.in @@ -2,7 +2,7 @@ DOXYFILE_ENCODING = UTF-8 PROJECT_NAME = "LAMMPS Programmer's Guide" -PROJECT_NUMBER = "4 May 2022" +PROJECT_NUMBER = "19 November 2024" PROJECT_BRIEF = "Documentation of the LAMMPS library interface and Python wrapper" PROJECT_LOGO = lammps-logo.png CREATE_SUBDIRS = NO diff --git a/doc/github-development-workflow.md b/doc/github-development-workflow.md index e16ae82764..69bf00b707 100644 --- a/doc/github-development-workflow.md +++ b/doc/github-development-workflow.md @@ -6,7 +6,9 @@ choices the LAMMPS developers have agreed on. Git and GitHub provide the tools, but do not set policies, so it is up to the developers to come to an agreement as to how to define and interpret policies. This document is likely to change as our experiences and needs change, and we try to -adapt it accordingly. Last change 2023-02-10. +adapt it accordingly. + +Last change: 2023-02-10 ## Table of Contents @@ -72,7 +74,7 @@ be assigned to signal urgency to merge this pull request quickly. People can be assigned to review a pull request in two ways: * They can be assigned manually to review a pull request - by the submitter or a LAMMPS developer + by the submitter or a LAMMPS developer. * They can be automatically assigned, because a developer's GitHub handle matches a file pattern in the `.github/CODEOWNERS` file, which associates developers with the code they contributed and @@ -86,9 +88,9 @@ required before merging, in addition to passing all automated compilation and unit tests. Merging counts as implicit approval, so does submission of a pull request (by a LAMMPS developer). So the person doing the merge may not also submit an approving review. The GitHub -feature, that reviews from code owners are "hard" reviews (i.e. they -must all approve before merging is allowed), is currently disabled. -It is in the discretion of the merge maintainer to assess when a +feature that reviews from code owners are "hard" reviews (i.e. they +must all approve before merging is allowed) is currently disabled. +It is at the discretion of the merge maintainer to assess when a sufficient degree of approval has been reached, especially from external collaborators. Reviews may be (automatically) dismissed, when the reviewed code has been changed. Review may be requested a second time. @@ -147,7 +149,8 @@ only contain bug fixes, feature additions to peripheral functionality, and documentation updates. In between stable releases, bug fixes and infrastructure updates are back-ported from the "develop" branch to the "maintenance" branch and occasionally merged into "stable" and published -as update releases. +as update releases. Further explanation of LAMMPS versions can be found +[in the documentation](https://docs.lammps.org/Manual_version.html). ## Project Management diff --git a/doc/lammps.1 b/doc/lammps.1 index 75581bd008..d6d43cc081 100644 --- a/doc/lammps.1 +++ b/doc/lammps.1 @@ -1,7 +1,7 @@ -.TH LAMMPS "1" "29 August 2024" "2024-08-29" +.TH LAMMPS "1" "4 February 2025" "2025-02-04" .SH NAME .B LAMMPS -\- Molecular Dynamics Simulator. Version 29 August 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 e82832cf57..be4b312578 100644 --- a/doc/src/Build_basics.rst +++ b/doc/src/Build_basics.rst @@ -160,7 +160,7 @@ with the OpenMP 3.1 semantics used in LAMMPS for maximal compatibility with compiler versions in use. If compilation with OpenMP enabled fails because of your compiler requiring strict OpenMP 4.0 semantics, you can change the behavior by adding ``-D LAMMPS_OMP_COMPAT=4`` to the -``LMP_INC`` variable in your makefile, or add it to the command line +``LMP_INC`` variable in your makefile, or add it to the command-line flags while configuring with CMake. LAMMPS will auto-detect a suitable setting for most GNU, Clang, and Intel compilers. @@ -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 @@ -502,6 +517,8 @@ using CMake or Make. # chain.x, micelle2d.x, msi2lmp, phana, # stl_bin2txt -D BUILD_LAMMPS_GUI=value # yes or no (default). Build LAMMPS-GUI + -D BUILD_WHAM=value # yes (default). Download and build WHAM; + # only available for BUILD_LAMMPS_GUI=yes The generated binaries will also become part of the LAMMPS installation (see below). diff --git a/doc/src/Build_cmake.rst b/doc/src/Build_cmake.rst index 1b2bef936e..2349eebf62 100644 --- a/doc/src/Build_cmake.rst +++ b/doc/src/Build_cmake.rst @@ -8,7 +8,7 @@ packages. Links to those pages on the :doc:`Build overview ` page. The following text assumes some familiarity with CMake and focuses on -using the command line tool ``cmake`` and what settings are supported +using the command-line tool ``cmake`` and what settings are supported for building LAMMPS. A more detailed tutorial on how to use CMake itself, the text mode or graphical user interface, to change the generated output files for different build tools and development @@ -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,29 +32,29 @@ 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. - CMake can generate files for different build tools and integrated development environments (IDE). -- CMake supports customization of settings with a command line, text +- CMake supports customization of settings with a command-line, text mode, or graphical user interface. No manual editing of files, - knowledge of file formats or complex command line syntax is required. + 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: @@ -68,7 +68,7 @@ that purpose you can use either the command-line utility ``cmake`` (or graphical utility ``cmake-gui``, or use them interchangeably. The second step is then the compilation and linking of all objects, libraries, and executables using the selected build tool. Here is a -minimal example using the command line version of CMake to build LAMMPS +minimal example using the command-line version of CMake to build LAMMPS with no add-on packages enabled and no customization: .. code-block:: bash @@ -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 @@ -131,7 +138,7 @@ file called ``CMakeLists.txt`` (for LAMMPS it is located in the configuration step. The cache file contains all current CMake settings. To modify settings, enable or disable features, you need to set -*variables* with either the ``-D`` command line flag (``-D +*variables* with either the ``-D`` command-line flag (``-D VARIABLE1_NAME=value``) or change them in the text mode of the graphical user interface. The ``-D`` flag can be used several times in one command. @@ -141,11 +148,11 @@ a different compiler tool chain. Those are loaded with the ``-C`` flag (``-C ../cmake/presets/basic.cmake``). This step would only be needed once, as the settings from the preset files are stored in the ``CMakeCache.txt`` file. It is also possible to customize the build -by adding one or more ``-D`` flags to the CMake command line. +by adding one or more ``-D`` flags to the CMake command. Generating files for alternate build tools (e.g. Ninja) and project files for IDEs like Eclipse, CodeBlocks, or Kate can be selected using the ``-G`` -command line flag. A list of available generator settings for your +command-line flag. A list of available generator settings for your specific CMake version is given when running ``cmake --help``. .. _cmake_multiconfig: diff --git a/doc/src/Build_development.rst b/doc/src/Build_development.rst index 3adec76abb..5c6475c7fa 100644 --- a/doc/src/Build_development.rst +++ b/doc/src/Build_development.rst @@ -263,9 +263,9 @@ will be skipped if prerequisite features are not available in LAMMPS. time. Preference is given to parts of the code base that are easy to test or commonly used. -Tests as shown by the ``ctest`` program are command lines defined in the +Tests as shown by the ``ctest`` program are commands defined in the ``CMakeLists.txt`` files in the ``unittest`` directory tree. A few -tests simply execute LAMMPS with specific command line flags and check +tests simply execute LAMMPS with specific command-line flags and check the output to the screen for expected content. A large number of unit tests are special tests programs using the `GoogleTest framework `_ and linked to the LAMMPS @@ -420,7 +420,7 @@ during MD timestepping and manipulate per-atom properties like positions, velocities, and forces. For those fix styles, testing can be done in a very similar fashion as for force fields and thus there is a test program `test_fix_timestep` that shares a lot of code, properties, -and command line flags with the force field style testers described in +and command-line flags with the force field style testers described in the previous section. This tester will set up a small molecular system run with verlet run @@ -642,10 +642,10 @@ The following target are available for both, GNU make and CMake: .. _gh-cli: -GitHub command line interface +GitHub command-line interface ----------------------------- -GitHub has developed a `command line tool `_ +GitHub has developed a `command-line tool `_ to interact with the GitHub website via a command called ``gh``. This is extremely convenient when working with a Git repository hosted on GitHub (like LAMMPS). It is thus highly recommended to install it diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index 8465bea829..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 ` @@ -209,7 +210,7 @@ necessary for ``hipcc`` and the linker to work correctly. Using the CHIP-SPV implementation of HIP is supported. It allows one to run HIP code on Intel GPUs via the OpenCL or Level Zero back ends. To use CHIP-SPV, you must set ``-DHIP_USE_DEVICE_SORT=OFF`` in your CMake -command line as CHIP-SPV does not yet support hipCUB. As of Summer 2022, +command-line as CHIP-SPV does not yet support hipCUB. As of Summer 2022, the use of HIP for Intel GPUs is experimental. You should only use this option in preparations to run on Aurora system at Argonne. @@ -232,7 +233,7 @@ option in preparations to run on Aurora system at Argonne. .. code:: bash - # CUDA target (not recommended, use GPU_ARCH=cuda) + # CUDA target (not recommended, use GPU_API=cuda) # !!! DO NOT set CMAKE_CXX_COMPILER !!! export HIP_PLATFORM=nvcc export HIP_PATH=/path/to/HIP/install @@ -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`` @@ -421,9 +421,10 @@ minutes to hours) to build. Of course you only need to do that once.) cmake build system. The ``lib/kim/Install.py`` script supports a ``CMAKE`` environment variable if the cmake executable is named other than ``cmake`` on your system. Additional environment variables may be - provided on the command line for use by cmake. For example, to use the - ``cmake3`` executable and tell it to use the gnu version 11 compilers - to build KIM, one could use the following command line. + set with the ``make`` command for use by cmake. For example, to use the + ``cmake3`` executable and tell it to use the GNU version 11 compilers + called ``g++-11``, ``gcc-11`` and ``gfortran-11`` to build KIM, one + could use the following command. .. code-block:: bash @@ -546,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 @@ -571,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 @@ -678,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 @@ -701,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:: @@ -1125,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:: @@ -1145,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 @@ -2018,7 +2030,7 @@ TBB and MKL. .. _mdi: MDI package ------------------------------ +----------- .. tabs:: @@ -2045,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 @@ -2191,7 +2234,7 @@ verified to work in February 2020 with Quantum Espresso versions 6.3 to from the sources in the *lib* folder (including the essential libqmmm.a) are not included in the static LAMMPS library and (currently) not installed, while their code is included in the - shared LAMMPS library. Thus a typical command line to configure + shared LAMMPS library. Thus a typical command to configure building LAMMPS for QMMM would be: .. code-block:: bash 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..73f2875a5d 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 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. + +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/Build_windows.rst b/doc/src/Build_windows.rst index d1748825eb..27562db480 100644 --- a/doc/src/Build_windows.rst +++ b/doc/src/Build_windows.rst @@ -100,9 +100,9 @@ procedure. It is possible to use both the integrated CMake support of the Visual Studio IDE or use an external CMake installation (e.g. downloaded from -cmake.org) to create build files and compile LAMMPS from the command line. +cmake.org) to create build files and compile LAMMPS from the command-line. -Compilation via command line and unit tests are checked automatically +Compilation via command-line and unit tests are checked automatically for the LAMMPS development branch through `GitHub Actions `_. @@ -115,7 +115,7 @@ for the LAMMPS development branch through Please note, that for either approach CMake will create a so-called :ref:`"multi-configuration" build environment `, and -the command lines for building and testing LAMMPS must be adjusted +the commands for building and testing LAMMPS must be adjusted accordingly. The LAMMPS cmake folder contains a ``CMakeSettings.json`` file with diff --git a/doc/src/Classes_lammps.rst b/doc/src/Classes_lammps.rst index dd6798d9a1..167a619fae 100644 --- a/doc/src/Classes_lammps.rst +++ b/doc/src/Classes_lammps.rst @@ -4,7 +4,7 @@ LAMMPS Class The LAMMPS class is encapsulating an MD simulation state and thus it is the class that needs to be created when starting a new simulation system state. The LAMMPS executable essentially creates one instance of this -class and passes the command line flags and tells it to process the +class and passes the command-line flags and tells it to process the provided input (a file or ``stdin``). It shuts the class down when control is returned to it and then exits. When using LAMMPS as a library from another code it is required to create an instance of this 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 d9febcc289..ed9bf6429b 100644 --- a/doc/src/Commands_fix.rst +++ b/doc/src/Commands_fix.rst @@ -43,7 +43,7 @@ OPT. * :doc:`brownian/asphere ` * :doc:`brownian/sphere ` * :doc:`charge/regulation ` - * :doc:`cmap ` + * :doc:`cmap (k) ` * :doc:`colvars ` * :doc:`controller ` * :doc:`damping/cundall ` @@ -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) ` @@ -134,7 +135,7 @@ OPT. * :doc:`nve/dot ` * :doc:`nve/dotc/langevin ` * :doc:`nve/eff ` - * :doc:`nve/limit ` + * :doc:`nve/limit (k) ` * :doc:`nve/line ` * :doc:`nve/manifold/rattle ` * :doc:`nve/noforce ` @@ -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 ` @@ -178,6 +181,7 @@ OPT. * :doc:`python/move ` * :doc:`qbmsst ` * :doc:`qeq/comb (o) ` + * :doc:`qeq/ctip ` * :doc:`qeq/dynamic ` * :doc:`qeq/fire ` * :doc:`qeq/point ` @@ -186,10 +190,11 @@ OPT. * :doc:`qeq/slater ` * :doc:`qmmm ` * :doc:`qtb ` + * :doc:`qtpie/reaxff ` * :doc:`rattle ` * :doc:`reaxff/bonds (k) ` * :doc:`reaxff/species (k) ` - * :doc:`recenter ` + * :doc:`recenter (k) ` * :doc:`restrain ` * :doc:`rheo ` * :doc:`rheo/oxidation ` @@ -267,7 +272,7 @@ OPT. * :doc:`wall/piston ` * :doc:`wall/reflect (k) ` * :doc:`wall/reflect/stochastic ` - * :doc:`wall/region ` + * :doc:`wall/region (k) ` * :doc:`wall/region/ees ` * :doc:`wall/srd ` * :doc:`wall/table ` diff --git a/doc/src/Commands_input.rst b/doc/src/Commands_input.rst index dc0fb72dd9..0f6e8f94a2 100644 --- a/doc/src/Commands_input.rst +++ b/doc/src/Commands_input.rst @@ -69,7 +69,7 @@ WARNING message is printed. The :doc:`Errors ` page gives more information on what errors mean. The documentation for each command lists restrictions on how the command can be used. -You can use the :ref:`-skiprun ` command line flag +You can use the :ref:`-skiprun ` command-line flag to have LAMMPS skip the execution of any ``run``, ``minimize``, or similar commands to check the entire input for correct syntax to avoid crashes on typos or syntax errors in long runs. diff --git a/doc/src/Commands_pair.rst b/doc/src/Commands_pair.rst index dfed8f7485..048a54ed37 100644 --- a/doc/src/Commands_pair.rst +++ b/doc/src/Commands_pair.rst @@ -44,7 +44,7 @@ OPT. * :doc:`born/coul/wolf/cs (g) ` * :doc:`born/gauss ` * :doc:`bpm/spring ` - * :doc:`brownian (o) ` + * :doc:`brownian (ko) ` * :doc:`brownian/poly (o) ` * :doc:`buck (giko) ` * :doc:`buck/coul/cut (giko) ` @@ -59,6 +59,7 @@ OPT. * :doc:`comb (o) ` * :doc:`comb3 ` * :doc:`cosine/squared ` + * :doc:`coul/ctip ` * :doc:`coul/cut (gko) ` * :doc:`coul/cut/dielectric ` * :doc:`coul/cut/global (o) ` @@ -79,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) ` @@ -113,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 ea8b3d4b03..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_comm_ops.rst b/doc/src/Developer_comm_ops.rst index 116b4d6ad8..66947de74f 100644 --- a/doc/src/Developer_comm_ops.rst +++ b/doc/src/Developer_comm_ops.rst @@ -79,19 +79,19 @@ containing ``double`` values. To correctly store integers that may be 64-bit (bigint, tagint, imageint) in the buffer, you need to use the :ref:`ubuf union ` construct. -The *Fix*, *Compute*, and *Dump* classes can also invoke the same kind -of forward and reverse communication operations using the same *Comm* -class methods. Likewise, the same pack/unpack methods and +The *Fix*, *Bond*, *Compute*, and *Dump* classes can also invoke the +same kind of forward and reverse communication operations using the +same *Comm* class methods. Likewise, the same pack/unpack methods and comm_forward/comm_reverse variables must be defined by the calling -*Fix*, *Compute*, or *Dump* class. +*Fix*, *Bond*, *Compute*, or *Dump* class. -For *Fix* classes, there is an optional second argument to the +For all of these classes, there is an optional second argument to the *forward_comm()* and *reverse_comm()* call which can be used when the -fix performs multiple modes of communication, with different numbers -of values per atom. The fix should set the *comm_forward* and +class performs multiple modes of communication, with different numbers +of values per atom. The class should set the *comm_forward* and *comm_reverse* variables to the maximum value, but can invoke the communication for a particular mode with a smaller value. For this -to work, the *pack_forward_comm()*, etc methods typically use a class +to work, the *pack_forward_comm()*, etc. methods typically use a class member variable to choose which values to pack/unpack into/from the buffer. 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_org.rst b/doc/src/Developer_org.rst index f1804655ae..93632ae03f 100644 --- a/doc/src/Developer_org.rst +++ b/doc/src/Developer_org.rst @@ -94,12 +94,12 @@ represents what is generally referred to as an "instance of LAMMPS". It is a composite holding pointers to instances of other core classes providing the core functionality of the MD engine in LAMMPS and through them abstractions of the required operations. The constructor of the -LAMMPS class will instantiate those instances, process the command line +LAMMPS class will instantiate those instances, process the command-line flags, initialize MPI (if not already done) and set up file pointers for input and output. The destructor will shut everything down and free all associated memory. Thus code for the standalone LAMMPS executable in ``main.cpp`` simply initializes MPI, instantiates a single instance of -LAMMPS while passing it the command line flags and input script. It +LAMMPS while passing it the command-line flags and input script. It deletes the LAMMPS instance after the method reading the input returns and shuts down the MPI environment before it exits the executable. diff --git a/doc/src/Developer_unittest.rst b/doc/src/Developer_unittest.rst index 07ffb0e2d8..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 @@ -476,7 +477,7 @@ the tabulated coulomb, to test both code paths. The reference results in the YA files then should be compared manually, if they agree well enough within the limits of those two approximations. -The ``test_pair_style`` and equivalent programs have special command line options +The ``test_pair_style`` and equivalent programs have special command-line options to update the YAML files. Running a command like .. code-block:: bash @@ -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,14 +604,14 @@ 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 env TEST_ARGS=-v ctest -R ^MolPairStyle:lj_cut_coul_long -V -``ctest`` with the ``-V`` flag also shows the exact command line +``ctest`` with the ``-V`` flag also shows the exact command of the test. One can then use ``gdb --args`` to further debug and catch exceptions with the test command, for example, 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/Developer_write_pair.rst b/doc/src/Developer_write_pair.rst index 5d5e081042..90b716d9c4 100644 --- a/doc/src/Developer_write_pair.rst +++ b/doc/src/Developer_write_pair.rst @@ -310,7 +310,7 @@ the constructor and the destructor. Pair styles are different from most classes in LAMMPS that define a "style", as their constructor only uses the LAMMPS class instance -pointer as an argument, but **not** the command line arguments of the +pointer as an argument, but **not** the arguments of the :doc:`pair_style command `. Instead, those arguments are processed in the ``Pair::settings()`` function (or rather the version in the derived class). The constructor is the place where global defaults @@ -891,7 +891,7 @@ originally created from mixing or not). These data file output functions are only useful for true pair-wise additive potentials, where the potential parameters can be entered through *multiple* :doc:`pair_coeff commands `. Pair styles -that require a single "pair_coeff \* \*" command line are not compatible +that require a single "pair_coeff \* \*" command are not compatible with reading their parameters from data files. For pair styles like *born/gauss* that do support writing to data files, the potential parameters will be read from the data file, if present, and @@ -1122,7 +1122,7 @@ once. Thus, the ``coeff()`` function has to do three tasks, each of which is delegated to a function in the ``PairTersoff`` class: #. map elements to atom types. Those follow the potential file name in the - command line arguments and are processed by the ``map_element2type()`` function. + command arguments and are processed by the ``map_element2type()`` function. #. read and parse the potential parameter file in the ``read_file()`` function. #. Build data structures where the original and derived parameters are indexed by all possible triples of atom types and thus can be looked @@ -1356,8 +1356,8 @@ either 0 or 1. The ``morseflag`` variable defaults to 0 and is set to 1 in the ``PairAIREBOMorse::settings()`` function which is called by the -:doc:`pair_style ` command. This function delegates -all command line processing and setting of other parameters to the +:doc:`pair_style ` command. This function delegates all +command argument processing and setting of other parameters to the ``PairAIREBO::settings()`` function of the base class. .. code-block:: c++ diff --git a/doc/src/Errors_debug.rst b/doc/src/Errors_debug.rst index b3f618dbf7..61fb1f7525 100644 --- a/doc/src/Errors_debug.rst +++ b/doc/src/Errors_debug.rst @@ -83,7 +83,7 @@ Run LAMMPS from within the debugger Running LAMMPS under the control of the debugger as shown below only works for a single MPI rank (for debugging a program running in parallel you usually need a parallel debugger program). A simple way to launch -GDB is to prefix the LAMMPS command line with ``gdb --args`` and then +GDB is to prefix the LAMMPS command-line with ``gdb --args`` and then type the command "run" at the GDB prompt. This will launch the debugger, load the LAMMPS executable and its debug info, and then run it. When it reaches the code causing the segmentation fault, it will @@ -180,7 +180,7 @@ inspect the behavior of a compiled program by essentially emulating a CPU and instrumenting the program while running. This slows down execution quite significantly, but can also report issues that are not resulting in a crash. The default valgrind tool is a memory checker and -you can use it by prefixing the normal command line with ``valgrind``. +you can use it by prefixing the normal command-line with ``valgrind``. Unlike GDB, this will also work for parallel execution, but it is recommended to redirect the valgrind output to a file (e.g. with ``--log-file=crash-%p.txt``, the %p will be substituted with the @@ -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 c798784106..5aa24d74c8 100644 --- a/doc/src/Errors_details.rst +++ b/doc/src/Errors_details.rst @@ -4,9 +4,237 @@ Error and warning details Many errors or warnings are self-explanatory and thus straightforward to resolve. However, there are also cases, where there is no single cause and explanation, where LAMMPS can only detect symptoms of an error but -not the exact cause, or where the explanation needs to be more detailed than -what can be fit into a message printed by the program. The following are -discussions of such cases. +not the exact cause, or where the explanation needs to be more detailed +than what can be fit into a message printed by the program. The +following are discussions of such cases. + +.. 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: @@ -34,8 +262,8 @@ 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,12 +273,589 @@ 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 +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 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, 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 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, or improper) 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 - simulation unstable +--------------------------------------------- +This error usually occurs due to issues with system geometry or the potential in +use. See :ref:`Pressure, forces, positions becoming NaN or Inf ` above in the +general troubleshooting section. + +.. _err0007: + +Non-numeric pressure - simulation unstable +------------------------------------------ +This error usually occurs due to issues with system geometry or the potential in +use. See :ref:`Pressure, forces, positions becoming NaN or Inf ` above in the +general troubleshooting section. + + +.. _err0008: + +Lost atoms ... +-------------- + +A simulation stopping with an error due to lost atoms can have multiple +causes. In the majority of cases, lost atoms are unexpected and a result +of extremely high velocities causing instabilities in the system, and +those 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 resolved +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 has become too large relative to the size of a +neighbor bin and LAMMPS is unable to store the needed number of +bins. This typically implies the simulation box has expanded too far. +This can happen when some atoms move rapidly apart with shrink-wrap boundaries +or when a fix (like fix deform or a barostat) excessively grows the simulation +box. + +.. _err0010: + +Unrecognized pair 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 pair 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 to enable +the package, but to forget to run commands to rebuild (e.g., to run the final +``make`` or ``cmake`` command). + +If this error is occurring 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. + +.. _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 +:doc:`Section 5.2. 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. Nevertheless, 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. diff --git a/doc/src/Errors_messages.rst b/doc/src/Errors_messages.rst index 2468b3c628..7be94f6fb3 100644 --- a/doc/src/Errors_messages.rst +++ b/doc/src/Errors_messages.rst @@ -6233,8 +6233,9 @@ Doc page with :doc:`WARNING messages ` 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. @@ -7774,7 +7775,7 @@ Doc page with :doc:`WARNING messages ` *Too few values in body section of molecule file* Self-explanatory. -*Too many -pk arguments in command line* +*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. 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 a1ea9a72df..0a8434f63d 100644 --- a/doc/src/Fortran.rst +++ b/doc/src/Fortran.rst @@ -16,7 +16,7 @@ compiled alongside the code using it from the source code in ``fortran/lammps.f90`` *and* with the same compiler used to build the rest of the Fortran code that interfaces to LAMMPS. When linking, you also need to :doc:`link to the LAMMPS library `. A typical -command line for a simple program using the Fortran interface would be: +command for a simple program using the Fortran interface would be: .. code-block:: bash @@ -91,12 +91,12 @@ function and triggered with the optional logical argument set to CALL lmp%close(.TRUE.) END PROGRAM testlib -It is also possible to pass command line flags from Fortran to C/C++ and +It is also possible to pass command-line flags from Fortran to C/C++ and thus make the resulting executable behave similarly to the standalone executable (it will ignore the `-in/-i` flag, though). This allows -using the command line to configure accelerator and suffix settings, +using the command-line to configure accelerator and suffix settings, configure screen and logfile output, or to set index style variables -from the command line and more. Here is a correspondingly adapted +from the command-line and more. Here is a correspondingly adapted version of the previous example: .. code-block:: fortran @@ -108,7 +108,7 @@ version of the previous example: CHARACTER(LEN=128), ALLOCATABLE :: command_args(:) INTEGER :: i, argc - ! copy command line flags to `command_args()` + ! copy command-line flags to `command_args()` argc = COMMAND_ARGUMENT_COUNT() ALLOCATE(command_args(0:argc)) DO i=0, argc @@ -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` @@ -448,7 +456,7 @@ of the contents of the :f:mod:`LIBLAMMPS` Fortran interface to LAMMPS. compiled with MPI support, it will also initialize MPI, if it has not already been initialized before. - The *args* argument with the list of command line parameters is + The *args* argument with the list of command-line parameters is optional and so it the *comm* argument with the MPI communicator. If *comm* is not provided, ``MPI_COMM_WORLD`` is assumed. For more details please see the documentation of :cpp:func:`lammps_open`. @@ -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..df42f6bd9d 100644 --- a/doc/src/Howto.rst +++ b/doc/src/Howto.rst @@ -103,6 +103,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_bioFF.rst b/doc/src/Howto_bioFF.rst index 72dcec2d31..92dd45b9b6 100644 --- a/doc/src/Howto_bioFF.rst +++ b/doc/src/Howto_bioFF.rst @@ -1,5 +1,5 @@ -CHARMM, AMBER, COMPASS, and DREIDING force fields -================================================= +CHARMM, AMBER, COMPASS, DREIDING, and OPLS force fields +======================================================= A compact summary of the concepts, definitions, and properties of force fields with explicit bonded interactions (like the ones discussed @@ -236,6 +236,40 @@ documentation for the formula it computes. * :doc:`special_bonds ` dreiding +OPLS +---- + +OPLS (Optimized Potentials for Liquid Simulations) is a general force +field for atomistic simulation of organic molecules in solvent. It was +developed by the `Jorgensen group +`_ at Purdue University and +later at Yale University. Multiple versions of the OPLS parameters +exist for united atom representations (OPLS-UA) and for all-atom +representations (OPLS-AA). + +This force field is based on atom types mapped to specific functional +groups in organic and biological molecules. Each atom includes a +static, partial atomic charge reflecting the oxidation state of the +element derived from its bonded neighbors :ref:`(Jorgensen) +` and computed based on increments determined by the +atom type of the atoms bond to it. + +The interaction styles listed below compute force field formulas that +are fully or in part consistent with the OPLS style force fields. See +each command's documentation for the formula it computes. Some are only +compatible with a subset of OPLS interactions. + +* :doc:`bond_style ` harmonic +* :doc:`angle_style ` harmonic +* :doc:`dihedral_style ` opls +* :doc:`improper_style ` cvff +* :doc:`improper_style ` fourier +* :doc:`improper_style ` harmonic +* :doc:`pair_style ` lj/cut/coul/cut +* :doc:`pair_style ` lj/cut/coul/long +* :doc:`pair_modify ` geometric +* :doc:`special_bonds ` lj/coul 0.0 0.0 0.5 + ---------- .. _Typelabel2: @@ -266,3 +300,6 @@ documentation for the formula it computes. **(Mayo)** Mayo, Olfason, Goddard III (1990). J Phys Chem, 94, 8897-8909. https://doi.org/10.1021/j100389a010 +.. _howto-Jorgensen: + +**(Jorgensen)** Jorgensen, Tirado-Rives (1988). J Am Chem Soc, 110, 1657-1666. https://doi.org/10.1021/ja00214a001 diff --git a/doc/src/Howto_bpm.rst b/doc/src/Howto_bpm.rst index 86e091fcef..f632ee6172 100644 --- a/doc/src/Howto_bpm.rst +++ b/doc/src/Howto_bpm.rst @@ -5,7 +5,11 @@ The BPM package implements bonded particle models which can be used to simulate mesoscale solids. Solids are constructed as a collection of particles, which each represent a coarse-grained region of space much larger than the atomistic scale. Particles within a solid region are -then connected by a network of bonds to provide solid elasticity. +then connected by a network of bonds to model solid elasticity. +There are many names for methods that are based on similar (or +equivalent) capabilities to those in this package, including, but not +limited to, cohesive beam models, bonded DEMs, lattice spring models, +mass spring models, and lattice particle methods. Unlike traditional bonds in molecular dynamics, the equilibrium bond length can vary between bonds. Bonds store the reference state. This @@ -38,11 +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. Alternatively, the second bond style, :doc:`bond bpm/rotational +network. An optional multibody term can be used to adjust the network's +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 @@ -55,8 +62,9 @@ orientation similar to :doc:`fix nve/asphere `. In addition to bond styles, a new pair style :doc:`pair bpm/spring ` was added to accompany the bpm/spring bond -style. This pair style is simply a hookean repulsion with similar -velocity damping as its sister bond style. +style. By default, this pair style is simply a hookean repulsion with +similar velocity damping as its sister bond style, but optional +arguments can be used to modify the force. ---------- diff --git a/doc/src/Howto_chunk.rst b/doc/src/Howto_chunk.rst index f8655b745d..ea000eb22f 100644 --- a/doc/src/Howto_chunk.rst +++ b/doc/src/Howto_chunk.rst @@ -58,28 +58,30 @@ chunk ID for an individual atom can also be static (e.g. a molecule ID), or dynamic (e.g. what spatial bin an atom is in as it moves). Note that this compute allows the per-atom output of other -:doc:`computes `, :doc:`fixes `, and -:doc:`variables ` to be used to define chunk IDs for each -atom. This means you can write your own compute or fix to output a -per-atom quantity to use as chunk ID. See the :doc:`Modify ` -doc pages for info on how to do this. You can also define a :doc:`per-atom variable ` in the input script that uses a formula to -generate a chunk ID for each atom. +:doc:`computes `, :doc:`fixes `, and :doc:`variables +` to be used to define chunk IDs for each atom. This means +you can write your own compute or fix to output a per-atom quantity to +use as chunk ID. See the :doc:`Modify ` doc pages for info on +how to do this. You can also define a :doc:`per-atom variable +` in the input script that uses a formula to generate a chunk +ID for each atom. Fix ave/chunk command: ---------------------- -This fix takes the ID of a :doc:`compute chunk/atom ` command as input. For each chunk, -it then sums one or more specified per-atom values over the atoms in -each chunk. The per-atom values can be any atom property, such as -velocity, force, charge, potential energy, kinetic energy, stress, -etc. Additional keywords are defined for per-chunk properties like -density and temperature. More generally any per-atom value generated -by other :doc:`computes `, :doc:`fixes `, and :doc:`per-atom variables `, can be summed over atoms in each chunk. +This fix takes the ID of a :doc:`compute chunk/atom +` command as input. For each chunk, it then sums +one or more specified per-atom values over the atoms in each chunk. The +per-atom values can be any atom property, such as velocity, force, +charge, potential energy, kinetic energy, stress, etc. Additional +keywords are defined for per-chunk properties like density and +temperature. More generally any per-atom value generated by other +:doc:`computes `, :doc:`fixes `, and :doc:`per-atom +variables `, can be summed over atoms in each chunk. Similar to other averaging fixes, this fix allows the summed per-chunk values to be time-averaged in various ways, and output to a file. The -fix produces a global array as output with one row of values per -chunk. +fix produces a global array as output with one row of values per chunk. Compute \*/chunk commands: -------------------------- @@ -97,17 +99,20 @@ category: * :doc:`compute torque/chunk ` * :doc:`compute vcm/chunk ` -They each take the ID of a :doc:`compute chunk/atom ` command as input. As their names -indicate, they calculate the center-of-mass, radius of gyration, -moments of inertia, mean-squared displacement, temperature, torque, -and velocity of center-of-mass for each chunk of atoms. The :doc:`compute property/chunk ` command can tally the -count of atoms in each chunk and extract other per-chunk properties. +They each take the ID of a :doc:`compute chunk/atom +` command as input. As their names indicate, they +calculate the center-of-mass, radius of gyration, moments of inertia, +mean-squared displacement, temperature, torque, and velocity of +center-of-mass for each chunk of atoms. The :doc:`compute +property/chunk ` command can tally the count of +atoms in each chunk and extract other per-chunk properties. -The reason these various calculations are not part of the :doc:`fix ave/chunk command `, is that each requires a more +The reason these various calculations are not part of the :doc:`fix +ave/chunk command `, is that each requires a more complicated operation than simply summing and averaging over per-atom -values in each chunk. For example, many of them require calculation -of a center of mass, which requires summing mass\*position over the -atoms and then dividing by summed mass. +values in each chunk. For example, many of them require calculation of +a center of mass, which requires summing mass\*position over the atoms +and then dividing by summed mass. All of these computes produce a global vector or global array as output, with one or more values per chunk. The output can be used in @@ -118,9 +123,10 @@ various ways: * As input to the :doc:`fix ave/histo ` command to histogram values across chunks. E.g. a histogram of cluster sizes or molecule diffusion rates. -* As input to special functions of :doc:`equal-style variables `, like sum() and max() and ave(). E.g. to - find the largest cluster or fastest diffusing molecule or average - radius-of-gyration of a set of molecules (chunks). +* As input to special functions of :doc:`equal-style variables + `, like sum() and max() and ave(). E.g. to find the largest + cluster or fastest diffusing molecule or average radius-of-gyration of + a set of molecules (chunks). Other chunk commands: --------------------- @@ -138,9 +144,10 @@ spatially average per-chunk values calculated by a per-chunk compute. The :doc:`compute reduce/chunk ` command reduces a peratom value across the atoms in each chunk to produce a value per -chunk. When used with the :doc:`compute chunk/spread/atom ` command it can -create peratom values that induce a new set of chunks with a second -:doc:`compute chunk/atom ` command. +chunk. When used with the :doc:`compute chunk/spread/atom +` command it can create peratom values that +induce a new set of chunks with a second :doc:`compute chunk/atom +` command. Example calculations with chunks -------------------------------- diff --git a/doc/src/Howto_cmake.rst b/doc/src/Howto_cmake.rst index 43aa519293..6b8fc82bad 100644 --- a/doc/src/Howto_cmake.rst +++ b/doc/src/Howto_cmake.rst @@ -56,7 +56,7 @@ using a shell like Bash or Zsh. Visual Studio IDE with the bundled CMake or from the Windows command prompt using a separately installed CMake package, both using the native Microsoft Visual C++ compilers and (optionally) the Microsoft MPI SDK. This tutorial, however, only - covers unix-like command line interfaces. + covers unix-like command-line interfaces. We also assume that you have downloaded and unpacked a recent LAMMPS source code package or used Git to create a clone of the LAMMPS sources on your compilation machine. @@ -277,7 +277,7 @@ Setting options --------------- Options that enable, disable or modify settings are modified by setting -the value of CMake variables. This is done on the command line with the +the value of CMake variables. This is done on the command-line with the *-D* flag in the format ``-D VARIABLE=value``, e.g. ``-D CMAKE_BUILD_TYPE=Release`` or ``-D BUILD_MPI=on``. There is one quirk: when used before the CMake directory, there may be a space between the @@ -376,7 +376,7 @@ Using presets ------------- Since LAMMPS has a lot of optional features and packages, specifying -them all on the command line can be tedious. Or when selecting a +them all on the command-line can be tedious. Or when selecting a different compiler toolchain, multiple options have to be changed consistently and that is rather error prone. Or when enabling certain packages, they require consistent settings to be operated in a @@ -384,7 +384,7 @@ particular mode. For this purpose, we are providing a selection of "preset files" for CMake in the folder ``cmake/presets``. They represent a way to pre-load or override the CMake configuration cache by setting or changing CMake variables. Preset files are loaded using the -*-C* command line flag. You can combine loading multiple preset files or +*-C* command-line flag. You can combine loading multiple preset files or change some variables later with additional *-D* flags. A few examples: .. code-block:: bash diff --git a/doc/src/Howto_github.rst b/doc/src/Howto_github.rst index b81716c09d..b53a2edbc7 100644 --- a/doc/src/Howto_github.rst +++ b/doc/src/Howto_github.rst @@ -163,7 +163,7 @@ After everything is done, add the files to the branch and commit them: *git rm*, *git mv* for adding, removing, renaming individual files, respectively, and then *git commit* to finalize the commit. Carefully check all pending changes with *git status* before - committing them. If you find doing this on the command line too + committing them. If you find doing this on the command-line too tedious, consider using a GUI, for example the one included in git distributions written in Tk, i.e. use *git gui* (on some Linux distributions it may be required to install an additional package to @@ -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 21e6a31ccc..63cf859c57 100644 --- a/doc/src/Howto_lammps_gui.rst +++ b/doc/src/Howto_lammps_gui.rst @@ -20,8 +20,11 @@ to the online LAMMPS documentation for known LAMMPS commands and styles. (Ubuntu 20.04LTS or later and compatible), macOS (version 11 aka Big Sur or later), and Windows (version 10 or later) :ref:`are available ` for download. Non-MPI LAMMPS executables (as - ``lmp``) for running LAMMPS from the command line and :doc:`some + ``lmp``) for running LAMMPS from the command-line and :doc:`some LAMMPS tools ` compiled executables are also included. + Also, the pre-compiled LAMMPS-GUI packages include the WHAM executables + from http://membrane.urmc.rochester.edu/content/wham/ for use with + LAMMPS tutorials. The source code for LAMMPS-GUI is included in the LAMMPS source code distribution and can be found in the ``tools/lammps-gui`` folder. It @@ -29,16 +32,16 @@ to the online LAMMPS documentation for known LAMMPS commands and styles. `. LAMMPS-GUI tries to provide an experience similar to what people -traditionally would have running LAMMPS using a command line window and +traditionally would have running LAMMPS using a command-line window and the console LAMMPS executable but just rolled into a single executable: - writing & editing LAMMPS input files with a text editor -- run LAMMPS on those input file with selected command line flags +- run LAMMPS on those input file with selected command-line flags - extract data from the created files and visualize it with and external software That procedure is quite effective for people proficient in using the -command line, as that allows them to use tools for the individual steps +command-line, as that allows them to use tools for the individual steps that they are most comfortable with. In fact, it is often *required* to adopt this workflow when running LAMMPS simulations on high-performance computing facilities. @@ -61,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 @@ -100,10 +108,11 @@ MacOS 11 and later ^^^^^^^^^^^^^^^^^^ After downloading the ``LAMMPS-macOS-multiarch-GUI-.dmg`` -installer package, you need to double-click it and then, in the window -that opens, drag the app bundle as indicated into the "Applications" -folder. The follow the instructions in the "README.txt" file to -get access to the other included executables. +application bundle disk image, you need to double-click it and then, in +the window that opens, drag the app bundle as indicated into the +"Applications" folder. Afterwards, the disk image can be unmounted. +Then follow the instructions in the "README.txt" file to get access to +the other included command-line executables. Linux on x86\_64 ^^^^^^^^^^^^^^^^ @@ -117,15 +126,25 @@ into the "LAMMPS_GUI" folder and execute "./lammps-gui" directly. The second variant uses `flatpak `_ and requires the flatpak management and runtime software to be installed. -After downloading the ``LAMMPS-GUI-Linux-x86_64-GUI-.tar.gz`` +After downloading the ``LAMMPS-GUI-Linux-x86_64-GUI-.flatpak`` flatpak bundle, you can install it with ``flatpak install --user -LAMMPS-GUI-Linux-x86_64-GUI-.tar.gz``. After installation, +LAMMPS-GUI-Linux-x86_64-GUI-.flatpak``. After installation, LAMMPS-GUI should be integrated into your desktop environment under "Applications > Science" but also can be launched from the console with ``flatpak run org.lammps.lammps-gui``. The flatpak bundle also includes the console LAMMPS executable ``lmp`` which can be launched to run -simulations with, for example: ``flatpak run --command=lmp -org.lammps.lammps-gui -in in.melt``. +simulations with, for example with: + +.. code-block:: sh + + flatpak run --command=lmp org.lammps.lammps-gui -in in.melt + +Other bundled command-line executables are run the same way and can be +listed with: + +.. code-block:: sh + + ls $(flatpak info --show-location org.lammps.lammps-gui )/files/bin Compiling from Source @@ -165,9 +184,9 @@ window is stored when exiting and restored when starting again. Opening Files ^^^^^^^^^^^^^ -The LAMMPS-GUI application can be launched without command line arguments +The LAMMPS-GUI application can be launched without command-line arguments and then starts with an empty buffer in the *Editor* window. If arguments -are given LAMMPS will use first command line argument as the file name for +are given LAMMPS will use first command-line argument as the file name for the *Editor* buffer and reads its contents into the buffer, if the file exists. All further arguments are ignored. Files can also be opened via the *File* menu, the `Ctrl-O` (`Command-O` on macOS) keyboard shortcut @@ -261,14 +280,21 @@ Output Window By default, when starting a run, an *Output* window opens that displays the screen output of the running LAMMPS calculation, as shown below. -This text would normally be seen in the command line window. +This text would normally be seen in the command-line window. .. image:: JPG/lammps-gui-log.png :align: center :scale: 50% LAMMPS-GUI captures the screen output from LAMMPS as it is generated and -updates the *Output* window regularly during a run. +updates the *Output* window regularly during a run. If there are any +warnings or errors in the LAMMPS output, they are highlighted by using +bold text colored in red. There is a small panel at the bottom center +of the *Output* window showing how many warnings and errors were +detected and how many lines the entire output has. By clicking on the +button on the right with the warning symbol or by using the keyboard +shortcut `Ctrl-N` (`Command-N` on macOS), you can jump to the next +line with a warning or error. By default, the *Output* window is replaced each time a run is started. The runs are counted and the run number for the current run is displayed @@ -398,7 +424,7 @@ below. Like for the *Output* and *Charts* windows, its content is continuously updated during a run. It will show "(none)" if there are no variables defined. Note that it is also possible to *set* :doc:`index style -variables `, that would normally be set via command line +variables `, that would normally be set via command-line flags, via the "Set Variables..." dialog from the *Run* menu. LAMMPS-GUI automatically defines the variable "gui_run" to the current value of the run counter. That way it is possible to automatically @@ -775,11 +801,11 @@ General Settings: - *Echo input to log:* when checked, all input commands, including variable expansions, are echoed to the *Output* window. This is - equivalent to using `-echo screen` at the command line. There is no + equivalent to using `-echo screen` at the command-line. There is no log *file* produced by default, since LAMMPS-GUI uses `-log none`. - *Include citation details:* when checked full citation info will be included to the log window. This is equivalent to using `-cite - screen` on the command line. + screen` on the command-line. - *Show log window by default:* when checked, the screen output of a LAMMPS run will be collected in a log window during the run - *Show chart window by default:* when checked, the thermodynamic @@ -828,7 +854,7 @@ Accelerators: This tab enables selection of an accelerator package for LAMMPS to use and is equivalent to using the `-suffix` and `-package` flags on the -command line. Only settings supported by the LAMMPS library and local +command-line. Only settings supported by the LAMMPS library and local hardware are available. The `Number of threads` field allows setting the maximum number of threads for the accelerator packages that use threads. 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 8a2aa4cab6..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:: @@ -738,8 +738,8 @@ command. This can be done, for example, by using the built-in visualizer of the :doc:`dump image or dump movie ` command to create snapshot -images or a movie. Below are example command lines for using dump image -with the :ref:`example listed below ` and a set of images +images or a movie. Below are example command for using dump image with +the :ref:`example listed below ` and a set of images created for steps 300, 600, and 2000 this way. .. code-block:: LAMMPS 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_rheo.rst b/doc/src/Howto_rheo.rst index 90f9ff82d0..2407fd484d 100644 --- a/doc/src/Howto_rheo.rst +++ b/doc/src/Howto_rheo.rst @@ -15,8 +15,9 @@ details of the system, or develop new capabilities. For instance, the numerics associated with calculating gradients, reproducing kernels, etc. are separated into distinct classes to simplify the development of new integration schemes which can call these calculations. Additional numerical details can be found in -:ref:`(Clemmer) `. Example movies illustrating some of these -capabilities are found at https://www.lammps.org/movies.html#rheopackage. +:ref:`(Palermo) ` and :ref:`(Clemmer) `. +Example movies illustrating some of these capabilities are found at +https://www.lammps.org/movies.html#rheopackage. Note, if you simply want to run a traditional SPH simulation, the :ref:`SPH package ` package is likely better suited for your application. It has fewer advanced @@ -70,7 +71,7 @@ particles to solid (e.g. with the :doc:`set ` command), (b) create bpm bonds between the particles (see the :doc:`bpm howto ` page for more details), and (c) use :doc:`pair rheo/solid ` to apply repulsive contact forces between distinct solid bodies. Akin to pair rheo, -pair rheo/solid considers a particles fluid/solid phase to determine whether to +pair rheo/solid considers a particle's fluid/solid phase to determine whether to apply forces. However, unlike pair rheo, pair rheo/solid does obey special bond settings such that contact forces do not have to be calculated between two bonded solid particles in the same elastic body. @@ -79,10 +80,10 @@ In systems with thermal evolution, fix rheo/thermal can optionally set a melting/solidification temperature allowing particles to dynamically swap their state between fluid and solid when the temperature exceeds or drops below the critical temperature, respectively. Using the *react* option, one can specify a maximum -bond length and a bond type. Then, when solidifying, particles will search their +bond length and a bond type. Then, when solidifying, particles search their local neighbors and automatically create bonds with any neighboring solid particles -in range. For BPM bond styles, bonds will then use the immediate position of the two -particles to calculate a reference state. When melting, particles will delete any +in range. For BPM bond styles, bonds then use the immediate position of the two +particles to calculate a reference state. When melting, particles delete any bonds of the specified type when reverting to a fluid state. Special bonds are updated as bonds are created/broken. @@ -107,6 +108,10 @@ criteria for creating/deleting a bond or altering force calculations). ---------- +.. _howto_rheo_palermo: + +**(Palermo)** Palermo, Wolf, Clemmer, O'Connor, Phys. Fluids, 36, 113337 (2024). + .. _howto_rheo_clemmer: **(Clemmer)** Clemmer, Pierce, O'Connor, Nevins, Jones, Lechman, Tencer, Appl. Math. Model., 130, 310-326 (2024). 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/Howto_wsl.rst b/doc/src/Howto_wsl.rst index fbb75d9cfd..30e4835e4c 100644 --- a/doc/src/Howto_wsl.rst +++ b/doc/src/Howto_wsl.rst @@ -260,7 +260,7 @@ Switch into the :code:`examples/melt` folder: cd ../examples/melt -To run this example in serial, use the following command line: +To run this example in serial, use the following command: .. code-block:: diff --git a/doc/src/Install_git.rst b/doc/src/Install_git.rst index 35b6429f0c..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, @@ -60,7 +61,7 @@ between them at any time using "git checkout ".) files (mostly by accident). If you do not need access to the entire commit history (most people don't), you can speed up the "cloning" process and reduce local disk space requirements by using the - ``--depth`` git command line flag. That will create a "shallow clone" + ``--depth`` git command-line flag. That will create a "shallow clone" of the repository, which contains only a subset of the git history. Using a depth of 1000 is usually sufficient to include the head commits of the *develop*, the *release*, and the *maintenance* diff --git a/doc/src/Intro_authors.rst b/doc/src/Intro_authors.rst index 84470ba3a0..38f1102595 100644 --- a/doc/src/Intro_authors.rst +++ b/doc/src/Intro_authors.rst @@ -8,6 +8,8 @@ send an email to all of them at this address: "developers at lammps.org". General questions about LAMMPS should be posted in the `LAMMPS forum on MatSci `_. +.. We need to keep this file in sync with https://www.lammps.org/authors.html + .. raw:: latex \small @@ -27,7 +29,7 @@ lammps.org". General questions about LAMMPS should be posted in the * - `Steve Plimpton `_ - SNL (retired) - sjplimp at gmail.com - - MD kernels, parallel algorithms & scalability, code structure and design + - original author, MD kernels, parallel algorithms & scalability, code structure and design * - `Aidan Thompson `_ - SNL - athomps at sandia.gov diff --git a/doc/src/Intro_portability.rst b/doc/src/Intro_portability.rst index 472a2bee88..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,25 +28,26 @@ 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 ^^^^^^^^^^^^^^^^^ The primary development platform for LAMMPS is Linux. Thus, the chances -for LAMMPS to compile without problems on Linux machines are the best. +for LAMMPS to compile without problems are the best on Linux machines. Also, compilation and correct execution on macOS and Windows (using -Microsoft Visual C++) is checked automatically for largest part of the -source code. Some (optional) features are not compatible with all +Microsoft Visual C++) is checked automatically for the largest part of +the source code. Some (optional) features are not compatible with all operating systems, either through limitations of the corresponding -LAMMPS source code or through source code or build system -incompatibilities of required libraries. +LAMMPS source code or through incompatibilities of source code or +build system of required external libraries or packages. Executables for Windows may be created natively using either Cygwin or Visual Studio or with a Linux to Windows MinGW cross-compiler. -Additionally, FreeBSD and Solaris have been tested successfully. +Additionally, FreeBSD and Solaris have been tested successfully to +run LAMMPS and produce results consistent with those on Linux. Compilers ^^^^^^^^^ 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/lammps-gui-log.png b/doc/src/JPG/lammps-gui-log.png index 894af371f0..61ab2e0601 100644 Binary files a/doc/src/JPG/lammps-gui-log.png and b/doc/src/JPG/lammps-gui-log.png 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/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/Modify_style.rst b/doc/src/Modify_style.rst index 496415237c..69b7cc9350 100644 --- a/doc/src/Modify_style.rst +++ b/doc/src/Modify_style.rst @@ -46,7 +46,7 @@ Include files (varied) but instead should be initialized either in the initializer list of the constructor or explicitly assigned in the body of the constructor. If the member variable is relevant to the functionality of a class - (for example when it stores a value from a command line argument), the + (for example when it stores a value from a command-line argument), the member variable declaration is followed by a brief comment explaining its purpose and what its values can be. Class members that are pointers should always be initialized to ``nullptr`` in the diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst index 43429feb03..870dc8fbf7 100644 --- a/doc/src/Packages_details.rst +++ b/doc/src/Packages_details.rst @@ -880,7 +880,7 @@ groups of atoms that interact with the remaining atoms as electrolyte. **Authors:** The ELECTRODE package is written and maintained by Ludwig Ahrens-Iwers (TUHH, Hamburg, Germany), Shern Tee (UQ, Brisbane, Australia) and -Robert Meissner (TUHH, Hamburg, Germany). +Robert Meissner (Helmholtz-Zentrum Hereon, Geesthacht and TUHH, Hamburg, Germany). .. versionadded:: 4May2022 @@ -994,6 +994,7 @@ Additional pair styles that are less commonly used. * ``src/EXTRA-PAIR``: filenames -> commands * :doc:`pair_style ` +* ``examples/PACKAGES/dispersion`` ---------- @@ -2171,8 +2172,8 @@ the :doc:`Build extras ` page. * ``src/OPENMP/README`` * :doc:`Accelerator packages ` * :doc:`OPENMP package ` -* :doc:`Command line option -suffix/-sf omp ` -* :doc:`Command line option -package/-pk omp ` +* :doc:`Command-line option -suffix/-sf omp ` +* :doc:`Command-line option -package/-pk omp ` * :doc:`package omp ` * Search the :doc:`commands ` pages (:doc:`fix `, :doc:`compute `, :doc:`pair `, :doc:`bond, angle, dihedral, improper `, @@ -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:** @@ -2789,14 +2790,15 @@ implements smoothed particle hydrodynamics (SPH) for liquids. See the related :ref:`MACHDYN package ` package for smooth Mach dynamics (SMD) for solids. -This package contains ideal gas, Lennard-Jones equation of states, -Tait, and full support for complete (i.e. internal-energy dependent) -equations of state. It allows for plain or Monaghans XSPH integration -of the equations of motion. It has options for density continuity or -density summation to propagate the density field. It has -:doc:`set ` command options to set the internal energy and density -of particles from the input script and allows the same quantities to -be output with thermodynamic output or to dump files via the :doc:`compute property/atom ` command. +This package contains ideal gas, Lennard-Jones equation of states, Tait, +and full support for complete (i.e. internal-energy dependent) equations +of state. It allows for plain or Monaghans XSPH integration of the +equations of motion. It has options for density continuity or density +summation to propagate the density field. It has :doc:`set ` +command options to set the internal energy and density of particles from +the input script and allows the same quantities to be output with +thermodynamic output or to dump files via the :doc:`compute +property/atom ` command. **Author:** Georg Ganzenmuller (Fraunhofer-Institute for High-Speed Dynamics, Ernst Mach Institute, Germany). @@ -2809,6 +2811,17 @@ Dynamics, Ernst Mach Institute, Germany). * ``examples/PACKAGES/sph`` * https://www.lammps.org/movies.html#sph +.. note:: + + Please note that the SPH PDF guide file has not been updated for + many years and thus does not reflect the current *syntax* of the + SPH package commands. For that please refer to the LAMMPS manual. + +.. note:: + + Please also note, that the :ref:`RHEO package ` offers + similar functionality in a more modern and flexible implementation. + ---------- .. _PKG-SPIN: 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_basics.rst b/doc/src/Run_basics.rst index 22cec5858b..f18eaff75a 100644 --- a/doc/src/Run_basics.rst +++ b/doc/src/Run_basics.rst @@ -1,8 +1,8 @@ Basics of running LAMMPS ======================== -LAMMPS is run from the command line, reading commands from a file via -the ``-in`` command line flag, or from standard input. Using the ``-in +LAMMPS is run from the command-line, reading commands from a file via +the ``-in`` command-line flag, or from standard input. Using the ``-in in.file`` variant is recommended (see note below). The name of the LAMMPS executable is either ``lmp`` or ``lmp_`` with `` being the machine string used when compiling LAMMPS. This @@ -25,7 +25,7 @@ build LAMMPS: You normally run the LAMMPS command in the directory where your input script is located. That is also where output files are produced by default, unless you provide specific other paths in your input script or -on the command line. As in some of the examples above, the LAMMPS +on the command-line. As in some of the examples above, the LAMMPS executable itself can be placed elsewhere. .. note:: diff --git a/doc/src/Run_options.rst b/doc/src/Run_options.rst index 4f7021cd53..546658a644 100644 --- a/doc/src/Run_options.rst +++ b/doc/src/Run_options.rst @@ -632,7 +632,7 @@ the ``-package omp`` command-line switch or the :doc:`package omp ` com The :doc:`suffix ` command can also be used within an input script to set a suffix, or to turn off or back on any suffix setting -made via the command line. +made via the command-line. ---------- 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/Run_windows.rst b/doc/src/Run_windows.rst index 0c0a07f4c7..a03f27c013 100644 --- a/doc/src/Run_windows.rst +++ b/doc/src/Run_windows.rst @@ -3,71 +3,70 @@ Running LAMMPS on Windows To run a serial (non-MPI) executable, follow these steps: -* Get a command prompt by going to Start->Run... , - then typing "cmd". -* Move to the directory where you have your input script, +* Install a LAMMPS installer package from https://packages.lammps.org/windows.html +* Open the "Command Prompt" or "Terminal" app. +* Change to the directory where you have your input script, (e.g. by typing: cd "Documents"). -* At the command prompt, type "lmp -in in.file", where - in.file is the name of your LAMMPS input script. +* At the command prompt, type "lmp -in in.file.lmp", where + ``in.file.lmp`` is the name of your LAMMPS input script. Note that the serial executable includes support for multi-threading -parallelization from the styles in the OPENMP packages. To run with -4 threads, you can type this: +parallelization from the styles in the OPENMP and KOKKOS packages. +To run with 4 threads, you can type this: .. code-block:: bash - lmp -in in.lj -pk omp 4 -sf omp + lmp -in in.lj.lmp -pk omp 4 -sf omp + lmp -in in.lj.lmp -k on t 4 -sf kk + +Alternately, you can also install a package with LAMMPS-GUI included and +open the LAMMPS-GUI app (the package includes the command-line version +of LAMMPS as well) and open the input file in the GUI and run it from +there. For details on LAMMPS-GUI, see :doc:`Howto_lammps_gui`. ---------- -For the MPI executable, which allows you to run LAMMPS under Windows -in parallel, follow these steps. +For the MS-MPI executables, which allow you to run LAMMPS under Windows +in parallel using MPI rather than multi-threading, follow these steps. -Download and install a compatible MPI library binary package: - -* for 32-bit Windows: `mpich2-1.4.1p1-win-ia32.msi `_ -* for 64-bit Windows: `mpich2-1.4.1p1-win-x86-64.msi `_ - -The LAMMPS Windows installer packages will automatically adjust your -path for the default location of this MPI package. After the -installation of the MPICH2 software, it needs to be integrated into -the system. For this you need to start a Command Prompt in -*Administrator Mode* (right click on the icon and select it). Change -into the MPICH2 installation directory, then into the subdirectory -**bin** and execute **smpd.exe -install**\ . Exit the command window. - -* Get a new, regular command prompt by going to Start->Run... , - then typing "cmd". -* Move to the directory where you have your input file - (e.g. by typing: cd "Documents"). +Download and install the MS-MPI runtime package ``msmpisetup.exe`` from +https://www.microsoft.com/en-us/download/details.aspx?id=105289 (Note +that the ``msmpisdk.msi`` is **only** required for **compilation** of +LAMMPS from source on Windows using Microsoft Visual Studio). After +installation of MS-MPI perform a reboot. Then you can run the executable in serial like in the example above or in parallel using MPI with one of the following commands: .. code-block:: bash - mpiexec -localonly 4 lmp -in in.file - mpiexec -np 4 lmp -in in.file + mpiexec -localonly 4 lmp -in in.file.lmp + mpiexec -np 4 lmp -in in.file.lmp -where in.file is the name of your LAMMPS input script. For the latter -case, you may be prompted to enter the password that you set during -installation of the MPI library software. +where ``in.file.lmp`` is the name of your LAMMPS input script. For the +latter case, you may be prompted to enter the password that you set +during installation of the MPI library software. In this mode, output may not immediately show up on the screen, so if your input script takes a long time to execute, you may need to be patient before the output shows up. -The parallel executable can also run on a single processor by typing -something like this: +Note that the parallel executable also includes OpenMP multi-threading +through both the OPENMP and the KOKKOS package, which can be combined +with MPI using something like: .. code-block:: bash - lmp -in in.lj + mpiexec -localonly 2 lmp -in in.lj.lmp -pk omp 2 -sf omp + mpiexec -localonly 2 lmp -in in.lj.lmp -kokkos on t 2 -sf kk -Note that the parallel executable also includes OpenMP -multi-threading, which can be combined with MPI using something like: - -.. code-block:: bash - - mpiexec -localonly 2 lmp -in in.lj -pk omp 2 -sf omp +------------- +MPI parallelization will work for *all* functionality in LAMMPS and in +many cases the MPI parallelization is more efficient than +multi-threading since LAMMPS was designed from ground up for MPI +parallelization using domain decomposition. Multi-threading is only +available for selected styles and implemented on top of the MPI +parallelization. Multi-threading is most useful for systems with large +load imbalances when using domain decomposition and a smaller number +of threads (<= 8). 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_gpu.rst b/doc/src/Speed_gpu.rst index 42bd8bf059..c90e3fcc5e 100644 --- a/doc/src/Speed_gpu.rst +++ b/doc/src/Speed_gpu.rst @@ -31,7 +31,8 @@ Coulombics. It has the following general features: (for Nvidia GPUs, AMD GPUs, Intel GPUs, and multicore CPUs). so that the same functionality is supported on a variety of hardware. -**Required hardware/software:** +Required hardware/software +"""""""""""""""""""""""""" To compile and use this package in CUDA mode, you currently need to have an NVIDIA GPU and install the corresponding NVIDIA CUDA @@ -69,12 +70,14 @@ To compile and use this package in HIP mode, you have to have the AMD ROCm software installed. Versions of ROCm older than 3.5 are currently deprecated by AMD. -**Building LAMMPS with the GPU package:** +Building LAMMPS with the GPU package +"""""""""""""""""""""""""""""""""""" See the :ref:`Build extras ` page for instructions. -**Run with the GPU package from the command line:** +Run with the GPU package from the command-line +"""""""""""""""""""""""""""""""""""""""""""""" The ``mpirun`` or ``mpiexec`` command sets the total number of MPI tasks used by LAMMPS (one or multiple per compute node) and the number of MPI @@ -133,7 +136,8 @@ affect the setting for bonded interactions (LAMMPS default is "on"). The "off" setting for pairwise interaction is currently required for GPU package pair styles. -**Or run with the GPU package by editing an input script:** +Run with the GPU package by editing an input script +""""""""""""""""""""""""""""""""""""""""""""""""""" The discussion above for the ``mpirun`` or ``mpiexec`` command, MPI tasks/node, and use of multiple MPI tasks/GPU is the same. @@ -149,7 +153,8 @@ You must also use the :doc:`package gpu ` command to enable the GPU package, unless the ``-sf gpu`` or ``-pk gpu`` :doc:`command-line switches ` were used. It specifies the number of GPUs/node to use, as well as other options. -**Speed-ups to expect:** +Speed-up to expect +"""""""""""""""""" The performance of a GPU versus a multicore CPU is a function of your hardware, which pair style is used, the number of atoms/GPU, and the @@ -176,10 +181,13 @@ better with multiple OMP threads because the inter-process communication is higher for these styles with the GPU package in order to allow deterministic results. -**Guidelines for best performance:** +Guidelines for best performance +""""""""""""""""""""""""""""""" -* Using multiple MPI tasks per GPU will often give the best performance, - as allowed my most multicore CPU/GPU configurations. +* Using multiple MPI tasks (2-10) per GPU will often give the best + performance, as allowed my most multicore CPU/GPU configurations. + Using too many MPI tasks will result in worse performance due to + growing overhead with the growing number of MPI tasks. * If the number of particles per MPI task is small (e.g. 100s of particles), it can be more efficient to run with fewer MPI tasks per GPU, even if you do not use all the cores on the compute node. @@ -199,12 +207,13 @@ deterministic results. :doc:`angle `, :doc:`dihedral `, :doc:`improper `, and :doc:`long-range ` calculations will not be included in the "Pair" time. -* Since only part of the pppm kspace style is GPU accelerated, it - may be faster to only use GPU acceleration for Pair styles with - long-range electrostatics. See the "pair/only" keyword of the - package command for a shortcut to do that. The work between kspace - on the CPU and non-bonded interactions on the GPU can be balanced - through adjusting the coulomb cutoff without loss of accuracy. +* Since only part of the pppm kspace style is GPU accelerated, it may be + faster to only use GPU acceleration for Pair styles with long-range + electrostatics. See the "pair/only" keyword of the :doc:`package + command ` for a shortcut to do that. The distribution of + work between kspace on the CPU and non-bonded interactions on the GPU + can be balanced through adjusting the coulomb cutoff without loss of + accuracy. * When the *mode* setting for the package gpu command is force/neigh, the time for neighbor list calculations on the GPU will be added into the "Pair" time, not the "Neigh" time. An additional breakdown of the @@ -220,4 +229,6 @@ deterministic results. Restrictions """""""""""" -None. +When using :doc:`hybrid pair styles `, the neighbor list +must be generated on the host instead of the GPU and thus the potential +GPU acceleration is reduced. diff --git a/doc/src/Speed_intel.rst b/doc/src/Speed_intel.rst index dd6c27b4e7..78a88f4407 100644 --- a/doc/src/Speed_intel.rst +++ b/doc/src/Speed_intel.rst @@ -1,5 +1,5 @@ INTEL package -================== +============= The INTEL package is maintained by Mike Brown at Intel Corporation. It provides two methods for accelerating simulations, @@ -13,18 +13,18 @@ twice, once on the CPU and once with an offload flag. This allows LAMMPS to run on the CPU cores and co-processor cores simultaneously. Currently Available INTEL Styles -""""""""""""""""""""""""""""""""""""" +"""""""""""""""""""""""""""""""" * Angle Styles: charmm, harmonic -* Bond Styles: fene, fourier, harmonic +* Bond Styles: fene, harmonic * Dihedral Styles: charmm, fourier, harmonic, opls -* Fixes: nve, npt, nvt, nvt/sllod, nve/asphere +* Fixes: nve, npt, nvt, nvt/sllod, nve/asphere, electrode/conp, electrode/conq, electrode/thermo * Improper Styles: cvff, harmonic * Pair Styles: airebo, airebo/morse, buck/coul/cut, buck/coul/long, buck, dpd, eam, eam/alloy, eam/fs, gayberne, lj/charmm/coul/charmm, lj/charmm/coul/long, lj/cut, lj/cut/coul/long, lj/long/coul/long, - rebo, sw, tersoff -* K-Space Styles: pppm, pppm/disp + rebo, snap, sw, tersoff +* K-Space Styles: pppm, pppm/disp, pppm/electrode .. warning:: @@ -33,7 +33,7 @@ Currently Available INTEL Styles input requires it, LAMMPS will abort with an error message. Speed-up to expect -""""""""""""""""""" +"""""""""""""""""" The speedup will depend on your simulation, the hardware, which styles are used, the number of atoms, and the floating-point @@ -312,21 +312,21 @@ almost all cases. recommended, especially when running on a machine with Intel Hyper-Threading technology disabled. -Run with the INTEL package from the command line -""""""""""""""""""""""""""""""""""""""""""""""""""""" +Run with the INTEL package from the command-line +"""""""""""""""""""""""""""""""""""""""""""""""" -To enable INTEL optimizations for all available styles used in -the input script, the ``-sf intel`` :doc:`command-line switch ` can be used without any requirement for -editing the input script. This switch will automatically append -"intel" to styles that support it. It also invokes a default command: -:doc:`package intel 1 `. This package command is used to set -options for the INTEL package. The default package command will -specify that INTEL calculations are performed in mixed precision, -that the number of OpenMP threads is specified by the OMP_NUM_THREADS -environment variable, and that if co-processors are present and the -binary was built with offload support, that 1 co-processor per node -will be used with automatic balancing of work between the CPU and the -co-processor. +To enable INTEL optimizations for all available styles used in the input +script, the ``-sf intel`` :doc:`command-line switch ` can +be used without any requirement for editing the input script. This +switch will automatically append "intel" to styles that support it. It +also invokes a default command: :doc:`package intel 1 `. This +package command is used to set options for the INTEL package. The +default package command will specify that INTEL calculations are +performed in mixed precision, that the number of OpenMP threads is +specified by the OMP_NUM_THREADS environment variable, and that if +co-processors are present and the binary was built with offload support, +that 1 co-processor per node will be used with automatic balancing of +work between the CPU and the co-processor. You can specify different options for the INTEL package by using the ``-pk intel Nphi`` :doc:`command-line switch ` with diff --git a/doc/src/Speed_kokkos.rst b/doc/src/Speed_kokkos.rst index 40e748c9fe..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 @@ -77,16 +85,18 @@ version 23 November 2023 and Kokkos version 4.2. rank. When running with multiple MPI ranks, you may see segmentation faults without GPU-aware MPI support. These can be avoided by adding the flags :doc:`-pk kokkos gpu/aware off ` to the - LAMMPS command line or by using the command :doc:`package kokkos + 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -423,7 +483,7 @@ in the ``kokkos-cuda.cmake`` CMake preset file. cmake -DKokkos_ENABLE_CUDA=yes -DKokkos_ENABLE_OPENMP=yes ../cmake The suffix "/kk" is equivalent to "/kk/device", and for Kokkos CUDA, -using the ``-sf kk`` in the command line gives the default CUDA version +using the ``-sf kk`` in the command-line gives the default CUDA version everywhere. However, if the "/kk/host" suffix is added to a specific style in the input script, the Kokkos OpenMP (CPU) version of that specific style will be used instead. Set the number of OpenMP threads @@ -439,7 +499,7 @@ For example, the command to run with 1 GPU and 8 OpenMP threads is then: mpiexec -np 1 lmp_kokkos_cuda_openmpi -in in.lj -k on g 1 t 8 -sf kk -Conversely, if the ``-sf kk/host`` is used in the command line and then +Conversely, if the ``-sf kk/host`` is used in the command-line and then the "/kk" or "/kk/device" suffix is added to a specific style in your input script, then only that specific style will run on the GPU while everything else will run on the CPU in OpenMP mode. Note that the @@ -451,7 +511,7 @@ on the host CPU can overlap with a pair style running on the GPU. First compile with ``--default-stream per-thread`` added to ``CCFLAGS`` in the Kokkos CUDA Makefile. Then explicitly use the "/kk/host" suffix for kspace and bonds, angles, etc. in the input file and the -"kk" suffix (equal to "kk/device") on the command line. Also make +"kk" suffix (equal to "kk/device") on the command-line. Also make sure the environment variable ``CUDA_LAUNCH_BLOCKING`` is not set to "1" so CPU/GPU overlap can occur. diff --git a/doc/src/Speed_omp.rst b/doc/src/Speed_omp.rst index bf0744f0f4..906acf3ce8 100644 --- a/doc/src/Speed_omp.rst +++ b/doc/src/Speed_omp.rst @@ -21,7 +21,7 @@ Building LAMMPS with the OPENMP package See the :ref:`Build extras ` page for instructions. -Run with the OPENMP package from the command line +Run with the OPENMP package from the command-line """"""""""""""""""""""""""""""""""""""""""""""""""" These examples assume one or more 16-core nodes. diff --git a/doc/src/Speed_opt.rst b/doc/src/Speed_opt.rst index e115393017..15e18dad8e 100644 --- a/doc/src/Speed_opt.rst +++ b/doc/src/Speed_opt.rst @@ -17,7 +17,7 @@ Building LAMMPS with the OPT package See the :ref:`Build extras ` page for instructions. -Run with the OPT package from the command line +Run with the OPT package from the command-line """""""""""""""""""""""""""""""""""""""""""""" .. code-block:: bash diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst index ba7cb2035a..11468787f1 100644 --- a/doc/src/Tools.rst +++ b/doc/src/Tools.rst @@ -501,7 +501,7 @@ Here are a few highlights of LAMMPS-GUI - Indicator for line that caused an error - Visualization of current state in Image Viewer (via calling :doc:`write_dump image `) - Capture of images created via :doc:`dump image ` in Slide show window -- Dialog to set variables, similar to the LAMMPS command line flag '-v' / '-var' +- Dialog to set variables, similar to the LAMMPS command-line flag '-v' / '-var' - Support for GPU, INTEL, KOKKOS/OpenMP, OPENMAP, and OPT and accelerator packages Parallelization @@ -550,7 +550,7 @@ will be found automatically. 2) you can download the `Flatpak file *flatpak* command: ``flatpak install --user LAMMPS-Linux-x86_64-GUI-.flatpak`` and run it with ``flatpak run org.lammps.lammps-gui``. The flatpak bundle also includes the -command line version of LAMMPS and some LAMMPS tools like msi2lmp. The +command-line version of LAMMPS and some LAMMPS tools like msi2lmp. The can be launched by using the ``--command`` flag. For example to run LAMMPS directly on the ``in.lj`` benchmark input you would type in the ``bench`` folder: ``flatpak run --command=lmp -in in.lj`` The flatpak @@ -608,10 +608,10 @@ would be the ``examples/COUPLE/plugin`` folder of the LAMMPS distribution. When compiling LAMMPS-GUI with plugin support, there is an additional -command line flag (``-p `` or ``--pluginpath ``) which +command-line flag (``-p `` or ``--pluginpath ``) which allows to override the path to LAMMPS shared library used by the GUI. This is usually auto-detected on the first run and can be changed in the -LAMMPS-GUI *Preferences* dialog. The command line flag allows to reset +LAMMPS-GUI *Preferences* dialog. The command-line flag allows to reset this path to a valid value in case the original setting has become invalid. An empty path ("") as argument restores the default setting. @@ -656,7 +656,7 @@ it will create a compressed ``LAMMPS-Win10-amd64.zip`` zip file with the executables and required dependent .dll files. This zip file can be uncompressed and ``lammps-gui.exe`` run directly from there. The uncompressed folder can be added to the ``PATH`` environment and LAMMPS -and LAMMPS-GUI can be launched from anywhere from the command line. +and LAMMPS-GUI can be launched from anywhere from the command-line. **MinGW64 Cross-compiler** @@ -876,7 +876,7 @@ the same ``LAMMPS_CACHING_DIR``. This script does the following: #. Start a simple local HTTP server using Python to host files for CMake Afterwards, it will print out instruction on how to modify the CMake -command line to make sure it uses the local HTTP server. +commands to make sure it uses the local HTTP server. To undo the environment changes and shutdown the local HTTP server, run the ``deactivate_caches`` command. @@ -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 @@ -1025,7 +1025,7 @@ with those in the provided log file with the same number of processors in the same subdirectory. If the differences between the actual and reference values are within specified tolerances, the test is considered passed. For each test batch, that is, a set of example input scripts, -the mpirun command, the LAMMPS command line arguments, and the +the mpirun command, the LAMMPS command-line arguments, and the tolerances for individual thermo quantities can be specified in a configuration file in YAML format. 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/angles.rst b/doc/src/angles.rst deleted file mode 100644 index c940689d4d..0000000000 --- a/doc/src/angles.rst +++ /dev/null @@ -1,8 +0,0 @@ -Angle Styles -############ - -.. toctree:: - :maxdepth: 1 - :glob: - - angle_* diff --git a/doc/src/bond_bpm_rotational.rst b/doc/src/bond_bpm_rotational.rst index 3ecd1cf950..cfbd01dd99 100644 --- a/doc/src/bond_bpm_rotational.rst +++ b/doc/src/bond_bpm_rotational.rst @@ -132,8 +132,8 @@ or :doc:`read_restart ` commands: * :math:`k_b` (force*distance/radians units) * :math:`f_{r,c}` (force units) * :math:`f_{s,c}` (force units) -* :math:`\tau_{b,c}` (force*distance units) * :math:`\tau_{t,c}` (force*distance units) +* :math:`\tau_{b,c}` (force*distance units) * :math:`\gamma_n` (force/velocity units) * :math:`\gamma_s` (force/velocity units) * :math:`\gamma_r` (force*distance/velocity units) @@ -154,8 +154,11 @@ page on BPMs. If the *break* keyword is set to *no*, LAMMPS assumes bonds should not break during a simulation run. This will prevent some unnecessary calculation. -However, if a bond reaches a damage criterion greater than one, -it will trigger an error. +The recommended bond communication distance no longer depends on bond failure +coefficients (which are ignored) but instead corresponds to the typical heuristic +maximum strain used by typical non-bpm bond styles. Similar behavior to *break no* +can also be attained by setting arbitrarily high values for all four failure +coefficients. One cannot use *break no* with *smooth yes*. If the *store/local* keyword is used, an internal fix will track bonds that break during the simulation. Whenever a bond breaks, data is processed diff --git a/doc/src/bond_bpm_spring.rst b/doc/src/bond_bpm_spring.rst index 81582bd5ea..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* +* optional keyword = *overlay/pair* or *store/local* or *smooth* or *normalize* or *break* or *volume/factor* .. parsed-literal:: @@ -36,6 +36,9 @@ Syntax *break* value = *yes* or *no* indicates whether bonds break during a run + *volume/factor* value = *yes* or *no* + indicates whether forces include the volumetric contribution + Examples """""""" @@ -44,6 +47,9 @@ Examples bond_style bpm/spring bond_coeff 1 1.0 0.05 0.1 + bond_style bpm/spring volume/factor yes + bond_coeff 1 1.0 0.05 0.1 0.5 + bond_style bpm/spring 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 @@ -97,15 +103,6 @@ approach the critical strain 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` (unit less) -* :math:`\gamma` (force/velocity units) - If the *normalize* keyword is set to *yes*, the elastic bond force will be normalized by :math:`r_0` such that :math:`k` must be given in force units. @@ -120,8 +117,49 @@ page on BPMs. If the *break* keyword is set to *no*, LAMMPS assumes bonds should not break during a simulation run. This will prevent some unnecessary calculation. -However, if a bond reaches a strain greater than :math:`\epsilon_c`, -it will trigger an error. +The recommended bond communication distance no longer depends on the value of +:math:`\epsilon_c` (which is ignored) but instead corresponds to the typical +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:: 4Feb2025 + +The *volume/factor* keyword toggles whether an additional multibody +contribution is added to he force using the formulation in +:ref:`(Clemmer2) `, + +.. math:: + + \alpha_v \left(\left[\frac{V_i + V_j}{V_{0,i} + V_{0,j}}\right]^{1/3} - \frac{r_{ij}}{r_{0,ij}}\right) + +where :math:`\alpha_v` is a user specified coefficient and :math:`V_i` +and :math:`V_{0,i}` are estimates of the current and local volume +of atom :math:`i`. These volumes are calculated as the sum of current +or initial bond lengths cubed. In 2D, the volume is replaced with an area +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. 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. + +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) + +Additionally, if *volume/factor* is set to *yes*, a fourth coefficient +must be provided: + +* :math:`a_v` (force units) If the *store/local* keyword is used, an internal fix will track bonds that break during the simulation. Whenever a bond breaks, data is processed @@ -177,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 @@ -213,7 +251,7 @@ Related commands Default """"""" -The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *no*, and *break* = *yes* +The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *no*, *break* = *yes*, and *volume/factor* = *no* ---------- @@ -224,3 +262,7 @@ The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = * .. _Groot4: **(Groot)** Groot and Warren, J Chem Phys, 107, 4423-35 (1997). + +.. _multibody-Clemmer: + +**(Clemmer2)** Clemmer, Monti, Lechman, Soft Matter, 20, 1702 (2024). 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/bonds.rst b/doc/src/bonds.rst deleted file mode 100644 index 4118e153e9..0000000000 --- a/doc/src/bonds.rst +++ /dev/null @@ -1,8 +0,0 @@ -Bond Styles -########### - -.. toctree:: - :maxdepth: 1 - :glob: - - bond_* 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_angle_local.rst b/doc/src/compute_angle_local.rst index 126dd309af..d4491c6945 100644 --- a/doc/src/compute_angle_local.rst +++ b/doc/src/compute_angle_local.rst @@ -78,7 +78,7 @@ system and output the statistics in various ways: compute 2 all angle/local eng theta v_cos v_cossq set theta t dump 1 all local 100 tmp.dump c_1[*] c_2[*] - compute 3 all reduce ave c_2[*] + compute 3 all reduce ave c_2[*] inputs local thermo_style custom step temp press c_3[*] fix 10 all ave/histo 10 10 100 -1 1 20 c_2[3] mode vector file tmp.histo diff --git a/doc/src/compute_bond_local.rst b/doc/src/compute_bond_local.rst index 5036358c8c..e070d507b1 100644 --- a/doc/src/compute_bond_local.rst +++ b/doc/src/compute_bond_local.rst @@ -139,7 +139,7 @@ output the statistics in various ways: compute 2 all bond/local engpot dist v_dsq set dist d dump 1 all local 100 tmp.dump c_1[*] c_2[*] - compute 3 all reduce ave c_2[*] + compute 3 all reduce ave c_2[*] inputs local thermo_style custom step temp press c_3[*] fix 10 all ave/histo 10 10 100 0 6 20 c_2[3] mode vector file tmp.histo 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_composition_atom.rst b/doc/src/compute_composition_atom.rst index c3e6fb7c60..4b68e7c79e 100644 --- a/doc/src/compute_composition_atom.rst +++ b/doc/src/compute_composition_atom.rst @@ -88,6 +88,10 @@ too frequently. ---------- +.. include:: accel_styles.rst + +---------- + Output info """"""""""" diff --git a/doc/src/compute_dihedral_local.rst b/doc/src/compute_dihedral_local.rst index 291b870373..d809cd39ce 100644 --- a/doc/src/compute_dihedral_local.rst +++ b/doc/src/compute_dihedral_local.rst @@ -76,7 +76,7 @@ angle in the system and output the statistics in various ways: compute 2 all dihedral/local phi v_cos v_cossq set phi p dump 1 all local 100 tmp.dump c_1[*] c_2[*] - compute 3 all reduce ave c_2[*] + compute 3 all reduce ave c_2[*] inputs local thermo_style custom step temp press c_3[*] fix 10 all ave/histo 10 10 100 -1 1 20 c_2[2] mode vector file tmp.histo 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_pressure.rst b/doc/src/compute_pressure.rst index 439f701bd4..92dcdb307a 100644 --- a/doc/src/compute_pressure.rst +++ b/doc/src/compute_pressure.rst @@ -125,10 +125,6 @@ where thermo_temp is the ID of a similarly defined compute of style ---------- -.. include:: accel_styles.rst - ----------- - Output info """"""""""" diff --git a/doc/src/compute_reduce.rst b/doc/src/compute_reduce.rst index 9eafe7cd5a..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 @@ -206,11 +206,13 @@ IDs and the bond stretch will be printed with thermodynamic output. The *inputs* keyword allows selection of whether all the inputs are per-atom or local quantities. As noted above, all the inputs must be -the same kind (per-atom or local). Per-atom is the default setting. -If a compute or fix is specified as an input, it must produce per-atom -or local data to match this setting. If it produces both, e.g. for +the same kind (per-atom or local). Per-atom is the default setting. If +a compute or fix is specified as an input, it must produce per-atom or +local data to match this setting. If it produces both, like for example the :doc:`compute voronoi/atom ` command, then -this keyword selects between them. +this keyword selects between them. If a compute *only* produces local +data, like for example the :doc:`compute bond/local command +`, the setting "inputs local" is *required*. ---------- diff --git a/doc/src/compute_reduce_chunk.rst b/doc/src/compute_reduce_chunk.rst index 8ec19ade66..eeadd50a97 100644 --- a/doc/src/compute_reduce_chunk.rst +++ b/doc/src/compute_reduce_chunk.rst @@ -37,55 +37,57 @@ Description Define a calculation that reduces one or more per-atom vectors into per-chunk values. This can be useful for diagnostic output. Or when -used in conjunction with the :doc:`compute chunk/spread/atom ` command it can be -used to create per-atom values that induce a new set of chunks with a -second :doc:`compute chunk/atom ` command. An -example is given below. +used in conjunction with the :doc:`compute chunk/spread/atom +` command it can be used to create per-atom +values that induce a new set of chunks with a second :doc:`compute +chunk/atom ` command. An example is given below. -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. +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. For each atom, this compute accesses its chunk ID from the specified -*chunkID* compute. The per-atom value from an input contributes -to a per-chunk value corresponding the the chunk ID. +*chunkID* compute. The per-atom value from an input contributes to a +per-chunk value corresponding the chunk ID. The reduction operation is specified by the *mode* setting and is performed over all the per-atom values from the atoms in each chunk. -The *sum* option adds the pre-atom values to a per-chunk total. The -*min* or *max* options find the minimum or maximum value of the -per-atom values for each chunk. +The *sum* option adds the per-atom values to a per-chunk total. The +*min* or *max* options find the minimum or maximum value of the per-atom +values for each chunk. -Note that only atoms in the specified group contribute to the -reduction operation. If the *chunkID* compute returns a 0 for the -chunk ID of an atom (i.e., the atom is not in a chunk defined by the -:doc:`compute chunk/atom ` command), that atom will -also not contribute to the reduction operation. An input that is a -compute or fix may define its own group which affects the quantities -it returns. For example, a compute with return a zero value for atoms -that are not in the group specified for that compute. +Note that only atoms in the specified group contribute to the reduction +operation. If the *chunkID* compute returns a 0 for the chunk ID of an +atom (i.e., the atom is not in a chunk defined by the :doc:`compute +chunk/atom ` command), that atom will also not +contribute to the reduction operation. An input that is a compute or +fix may define its own group which affects the quantities it returns. +For example, a compute will return a zero value for atoms that are not +in the group specified for that compute. Each listed input is operated on independently. Each input can be the -result of a :doc:`compute ` or :doc:`fix ` or the evaluation -of an atom-style :doc:`variable `. +result of a :doc:`compute ` or :doc:`fix ` or the +evaluation of an atom-style :doc:`variable `. -Note that for values from a compute or fix, the bracketed index I can -be specified using a wildcard asterisk with the index to effectively +Note that for values from a compute or fix, the bracketed index I can be +specified using a wildcard asterisk with the index to effectively specify multiple values. This takes the form "\*" or "\*n" or "m\*" or -"m\*n". If :math:`N` is the size of the vector (for *mode* = scalar) or the -number of columns in the array (for *mode* = vector), then an asterisk -with no numeric values means all indices from 1 to :math:`N`. A leading -asterisk means all indices from 1 to n (inclusive). A trailing -asterisk means all indices from n to :math:`N` (inclusive). A middle asterisk -means all indices from m to n (inclusive). +"m\*n". If :math:`N` is the size of the vector (for *mode* = scalar) or +the number of columns in the array (for *mode* = vector), then an +asterisk with no numeric values means all indices from 1 to :math:`N`. +A leading asterisk means all indices from 1 to n (inclusive). A +trailing asterisk means all indices from n to :math:`N` (inclusive). A +middle asterisk means all indices from m to n (inclusive). Using a wildcard is the same as if the individual columns of the array -had been listed one by one. For example, the following two compute reduce/chunk -commands are equivalent, since the -:doc:`compute property/chunk ` command creates a per-atom +had been listed one by one. For example, the following two compute +reduce/chunk commands are equivalent, since the :doc:`compute +property/chunk ` command creates a per-atom array with 3 columns: .. code-block:: LAMMPS @@ -164,13 +166,14 @@ Output info """"""""""" This compute calculates a global vector if a single input value is -specified, otherwise a global array is output. The number of columns -in the array is the number of inputs provided. The length of the -vector or the number of vector elements or array rows = the number of -chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom ` command. The vector or array can -be accessed by any command that uses global values from a compute as -input. See the :doc:`Howto output ` page for an -overview of LAMMPS output options. +specified, otherwise a global array is output. The number of columns in +the array is the number of inputs provided. The length of the vector or +the number of vector elements or array rows = the number of chunks +*Nchunk* as calculated by the specified :doc:`compute chunk/atom +` command. The vector or array can be accessed by +any command that uses global values from a compute as input. See the +:doc:`Howto output ` page for an overview of LAMMPS output +options. The per-atom values for the vector or each column of the array will be in whatever :doc:`units ` the corresponding input value is in. @@ -183,7 +186,9 @@ Restrictions Related commands """""""""""""""" -:doc:`compute chunk/atom `, :doc:`compute reduce `, :doc:`compute chunk/spread/atom ` +:doc:`compute chunk/atom `, +:doc:`compute reduce `, +:doc:`compute chunk/spread/atom ` Default """"""" diff --git a/doc/src/compute_rheo_property_atom.rst b/doc/src/compute_rheo_property_atom.rst index 2e905b97be..8686a0dec2 100644 --- a/doc/src/compute_rheo_property_atom.rst +++ b/doc/src/compute_rheo_property_atom.rst @@ -81,7 +81,7 @@ includes *xx*, *xy*, *yx*, and *yy*. In 3D, this includes *xx*, *xy*, *xz*, Many properties require their respective fixes, listed below in related commands, be defined. For instance, the *viscosity* attribute is the viscosity of a particle calculated by -:doc:`fix rheo/viscous `. The meaning of less obvious +:doc:`fix rheo/viscosity `. The meaning of less obvious properties is described below. The *phase* property indicates whether the particle is in a fluid state, 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_sph_e_atom.rst b/doc/src/compute_sph_e_atom.rst index d557eb7920..44ff765a6a 100644 --- a/doc/src/compute_sph_e_atom.rst +++ b/doc/src/compute_sph_e_atom.rst @@ -33,6 +33,12 @@ particle. See `this PDF guide `_ to using SPH in LAMMPS. +.. note:: + + Please note that the SPH PDF guide file has not been updated for + many years and thus does not reflect the current *syntax* of the + SPH package commands. For that please refer to the LAMMPS manual. + The value of the internal energy will be 0.0 for atoms not in the specified compute group. diff --git a/doc/src/compute_sph_rho_atom.rst b/doc/src/compute_sph_rho_atom.rst index 6e8579476a..6ed6bf70c1 100644 --- a/doc/src/compute_sph_rho_atom.rst +++ b/doc/src/compute_sph_rho_atom.rst @@ -32,6 +32,12 @@ kernel function interpolation using "pair style sph/rhosum". See `this PDF guide `_ to using SPH in LAMMPS. +.. note:: + + Please note that the SPH PDF guide file has not been updated for + many years and thus does not reflect the current *syntax* of the + SPH package commands. For that please refer to the LAMMPS manual. + The value of the SPH density will be 0.0 for atoms not in the specified compute group. diff --git a/doc/src/compute_sph_t_atom.rst b/doc/src/compute_sph_t_atom.rst index 3383c26145..8bbab4ca7d 100644 --- a/doc/src/compute_sph_t_atom.rst +++ b/doc/src/compute_sph_t_atom.rst @@ -37,6 +37,12 @@ particles, i.e. a Smooth-Particle Hydrodynamics particle. See `this PDF guide `_ to using SPH in LAMMPS. +.. note:: + + Please note that the SPH PDF guide file has not been updated for + many years and thus does not reflect the current *syntax* of the + SPH package commands. For that please refer to the LAMMPS manual. + The value of the internal energy will be 0.0 for atoms not in the specified compute group. 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_stress_curvilinear.rst b/doc/src/compute_stress_curvilinear.rst index 022a87058f..6ec3ab18bf 100644 --- a/doc/src/compute_stress_curvilinear.rst +++ b/doc/src/compute_stress_curvilinear.rst @@ -87,7 +87,7 @@ This array can be output with :doc:`fix ave/time `, .. code-block:: LAMMPS - compute 1 all stress/spherical 0 0 0 0.1 10 + compute p all stress/spherical 0 0 0 0.1 10 fix 2 all ave/time 100 1 100 c_p[*] file dump_p.out mode vector The values calculated by this compute are "intensive". The stress diff --git a/doc/src/compute_stress_mop.rst b/doc/src/compute_stress_mop.rst index b4779b8bf3..31c81b5df7 100644 --- a/doc/src/compute_stress_mop.rst +++ b/doc/src/compute_stress_mop.rst @@ -129,6 +129,9 @@ package ` doc page on for more info. The method is implemented for orthogonal simulation boxes whose size does not change in time, and axis-aligned planes. +Contributions from bonds, angles, and dihedrals are not compatible +with MPI parallel runs. + The method only works with two-body pair interactions, because it requires the class method ``Pair::single()`` to be implemented, which is not possible for manybody potentials. In particular, compute 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_temp_deform.rst b/doc/src/compute_temp_deform.rst index 1c8c2da096..abeb7041cc 100644 --- a/doc/src/compute_temp_deform.rst +++ b/doc/src/compute_temp_deform.rst @@ -128,6 +128,12 @@ See the :doc:`Howto thermostat ` page for a discussion of different ways to compute temperature and perform thermostatting. +---------- + +.. include:: accel_styles.rst + +---------- + Output info """"""""""" diff --git a/doc/src/compute_temp_partial.rst b/doc/src/compute_temp_partial.rst index d98558c159..b6803f2c9c 100644 --- a/doc/src/compute_temp_partial.rst +++ b/doc/src/compute_temp_partial.rst @@ -46,7 +46,7 @@ degrees of freedom. A symmetric tensor, stored as a six-element vector, is also calculated by this compute for use in the computation of a pressure tensor by the -:doc:`compute pressue ` command. The formula for +:doc:`compute pressure ` command. The formula for the components of the tensor is the same as the above expression for :math:`E_\mathrm{kin}`, except that the 1/2 factor is NOT included and the :math:`v_i^2` is replaced by :math:`v_{i,x} v_{i,y}` for the @@ -82,12 +82,6 @@ See the :doc:`Howto thermostat ` page for a discussion of different ways to compute temperature and perform thermostatting. ----------- - -.. include:: accel_styles.rst - ----------- - Output info """"""""""" 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/computes.rst b/doc/src/computes.rst deleted file mode 100644 index 8d53b6cf06..0000000000 --- a/doc/src/computes.rst +++ /dev/null @@ -1,8 +0,0 @@ -Computes -######## - -.. toctree:: - :maxdepth: 1 - :glob: - - compute_* 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/dihedrals.rst b/doc/src/dihedrals.rst deleted file mode 100644 index f56e323427..0000000000 --- a/doc/src/dihedrals.rst +++ /dev/null @@ -1,8 +0,0 @@ -Dihedral Styles -############### - -.. toctree:: - :maxdepth: 1 - :glob: - - dihedral_* diff --git a/doc/src/dump_image.rst b/doc/src/dump_image.rst index 2336a5889a..8313d3cccb 100644 --- a/doc/src/dump_image.rst +++ b/doc/src/dump_image.rst @@ -681,7 +681,7 @@ MPEG or other movie file you can use: * c) Use FFmpeg - FFmpeg is a command line tool that is available on many platforms and + FFmpeg is a command-line tool that is available on many platforms and allows extremely flexible encoding and decoding of movies. .. code-block:: bash 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 4919c226fd..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 @@ -357,6 +360,7 @@ accelerated styles exist. * :doc:`python/move ` - move particles using a Python function during a simulation run * :doc:`qbmsst ` - quantum bath multi-scale shock technique time integrator * :doc:`qeq/comb ` - charge equilibration for COMB potential +* :doc:`qeq/ctip ` - charge equilibration for CTIP potential * :doc:`qeq/dynamic ` - charge equilibration via dynamic method * :doc:`qeq/fire ` - charge equilibration via FIRE minimizer * :doc:`qeq/point ` - charge equilibration via point method @@ -365,6 +369,7 @@ accelerated styles exist. * :doc:`qeq/slater ` - charge equilibration via Slater method * :doc:`qmmm ` - functionality to enable a quantum mechanics/molecular mechanics coupling * :doc:`qtb ` - implement quantum thermal bath scheme +* :doc:`qtpie/reaxff ` - apply QTPIE charge equilibration * :doc:`rattle ` - RATTLE constraints on bonds and/or angles * :doc:`reaxff/bonds ` - write out ReaxFF bond information * :doc:`reaxff/species ` - write out ReaxFF molecule information diff --git a/doc/src/fix_acks2_reaxff.rst b/doc/src/fix_acks2_reaxff.rst index ebb1b48051..79a9cf8ea6 100644 --- a/doc/src/fix_acks2_reaxff.rst +++ b/doc/src/fix_acks2_reaxff.rst @@ -111,7 +111,8 @@ LAMMPS was built with that package. See the :doc:`Build package This fix does not correctly handle interactions involving multiple periodic images of the same atom. Hence, it should not be used for -periodic cell dimensions less than :math:`10~\AA`. +periodic cell dimensions smaller than the non-bonded cutoff radius, +which is typically :math:`10~\AA` for ReaxFF simulations. This fix may be used in combination with :doc:`fix efield ` and will apply the external electric field during charge equilibration, @@ -122,7 +123,8 @@ components in non-periodic directions. Related commands """""""""""""""" -:doc:`pair_style reaxff `, :doc:`fix qeq/reaxff ` +:doc:`pair_style reaxff `, :doc:`fix qeq/reaxff `, +:doc:`fix qtpi/reaxff ` Default """"""" diff --git a/doc/src/fix_adapt.rst b/doc/src/fix_adapt.rst index a44ce8e780..34e3e450f6 100644 --- a/doc/src/fix_adapt.rst +++ b/doc/src/fix_adapt.rst @@ -119,6 +119,14 @@ style supports it. Note that the :doc:`pair_style ` and to specify these parameters initially; the fix adapt command simply overrides the parameters. +.. note:: + + Pair_coeff settings must be made **explicitly** in order for fix + adapt to be able to change them. Settings inferred from mixing + are not suitable. If necessary all mixed settings can be output + to a file using the :doc:`write_coeff command ` and + then the desired mixed pair_coeff settings copied from that file. + The *pstyle* argument is the name of the pair style. If :doc:`pair_style hybrid or hybrid/overlay ` is used, *pstyle* should be a sub-style name. If there are multiple @@ -228,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:: @@ -322,29 +332,33 @@ all types from 1 to :math:`N`. A leading asterisk means all types from If :doc:`bond_style hybrid ` is used, *bstyle* should be a sub-style name. The bond styles that currently work with fix adapt are: -+---------------------------------------------------+---------------------------+------------+ -| :doc:`class2 ` | r0 | type bonds | -+---------------------------------------------------+---------------------------+------------+ -| :doc:`fene ` | k,r0 | type bonds | -+---------------------------------------------------+---------------------------+------------+ -| :doc:`fene/expand ` | k,r0,epsilon,sigma,shift | type bonds | -+---------------------------------------------------+---------------------------+------------+ -| :doc:`fene/nm ` | k,r0 | type bonds | -+---------------------------------------------------+---------------------------+------------+ -| :doc:`gromos ` | k,r0 | type bonds | -+---------------------------------------------------+---------------------------+------------+ -| :doc:`harmonic ` | k,r0 | type bonds | -+---------------------------------------------------+---------------------------+------------+ -| :doc:`harmonic/shift ` | k,r0,r1 | type bonds | -+---------------------------------------------------+---------------------------+------------+ -| :doc:`harmonic/restrain ` | k | type bonds | -+---------------------------------------------------+---------------------------+------------+ -| :doc:`mm3 ` | k,r0 | type bonds | -+---------------------------------------------------+---------------------------+------------+ -| :doc:`morse ` | r0 | type bonds | -+---------------------------------------------------+---------------------------+------------+ -| :doc:`nonlinear ` | epsilon,r0 | type bonds | -+---------------------------------------------------+---------------------------+------------+ ++-----------------------------------------------------+---------------------------+------------+ +| :doc:`class2 ` | k2,k3,k4,r0 | type bonds | ++-----------------------------------------------------+---------------------------+------------+ +| :doc:`fene ` | k,r0 | type bonds | ++-----------------------------------------------------+---------------------------+------------+ +| :doc:`fene/expand ` | k,r0,epsilon,sigma,shift | type bonds | ++-----------------------------------------------------+---------------------------+------------+ +| :doc:`fene/nm ` | k,r0 | type bonds | ++-----------------------------------------------------+---------------------------+------------+ +| :doc:`gaussian ` | alpha,width,r0 | type bonds | ++-----------------------------------------------------+---------------------------+------------+ +| :doc:`gromos ` | k,r0 | type bonds | ++-----------------------------------------------------+---------------------------+------------+ +| :doc:`harmonic ` | k,r0 | type bonds | ++-----------------------------------------------------+---------------------------+------------+ +| :doc:`harmonic/restrain ` | k | type bonds | ++-----------------------------------------------------+---------------------------+------------+ +| :doc:`harmonic/shift ` | k,r0,r1 | type bonds | ++-----------------------------------------------------+---------------------------+------------+ +| :doc:`harmonic/shift/cut ` | k,r0,r1 | type bonds | ++-----------------------------------------------------+---------------------------+------------+ +| :doc:`mm3 ` | k,r0 | type bonds | ++-----------------------------------------------------+---------------------------+------------+ +| :doc:`morse ` | d0,alpha,r0 | type bonds | ++-----------------------------------------------------+---------------------------+------------+ +| :doc:`nonlinear ` | lamda,epsilon,r0 | type bonds | ++-----------------------------------------------------+---------------------------+------------+ ---------- @@ -367,31 +381,39 @@ all types from 1 to :math:`N`. A leading asterisk means all types from If :doc:`angle_style hybrid ` is used, *astyle* should be a sub-style name. The angle styles that currently work with fix adapt are: -+--------------------------------------------------------------------+-----------------+-------------+ -| :doc:`harmonic ` | k,theta0 | type angles | -+--------------------------------------------------------------------+-----------------+-------------+ -| :doc:`charmm ` | k,theta0 | type angles | -+--------------------------------------------------------------------+-----------------+-------------+ -| :doc:`class2 ` | k2,k3,k4,theta0 | type angles | -+--------------------------------------------------------------------+-----------------+-------------+ -| :doc:`cosine ` | k | type angles | -+--------------------------------------------------------------------+-----------------+-------------+ -| :doc:`cosine/periodic ` | k,b,n | type angles | -+--------------------------------------------------------------------+-----------------+-------------+ -| :doc:`cosine/squared/restricted ` | k,theta0 | type angles | -+--------------------------------------------------------------------+-----------------+-------------+ -| :doc:`dipole ` | k,gamma0 | type angles | -+--------------------------------------------------------------------+-----------------+-------------+ -| :doc:`fourier ` | k,c0,c1,c2 | type angles | -+--------------------------------------------------------------------+-----------------+-------------+ -| :doc:`fourier/simple ` | k,c,n | type angles | -+--------------------------------------------------------------------+-----------------+-------------+ -| :doc:`mm3 ` | k,theta0 | type angles | -+--------------------------------------------------------------------+-----------------+-------------+ -| :doc:`quartic ` | k2,k3,k4,theta0 | type angles | -+--------------------------------------------------------------------+-----------------+-------------+ -| :doc:`spica ` | k,theta0 | type angles | -+--------------------------------------------------------------------+-----------------+-------------+ ++--------------------------------------------------------------------+--------------------+-------------+ +| :doc:`harmonic ` | k,theta0 | type angles | ++--------------------------------------------------------------------+--------------------+-------------+ +| :doc:`charmm ` | k,theta0 | type angles | ++--------------------------------------------------------------------+--------------------+-------------+ +| :doc:`class2 ` | k2,k3,k4,theta0 | type angles | ++--------------------------------------------------------------------+--------------------+-------------+ +| :doc:`cosine ` | k | type angles | ++--------------------------------------------------------------------+--------------------+-------------+ +| :doc:`cosine/delta ` | k | type angles | ++--------------------------------------------------------------------+--------------------+-------------+ +| :doc:`cosine/periodic ` | k,b,n | type angles | ++--------------------------------------------------------------------+--------------------+-------------+ +| :doc:`cosine/squared ` | k,theta0 | type angles | ++--------------------------------------------------------------------+--------------------+-------------+ +| :doc:`cosine/squared/restricted ` | k,theta0 | type angles | ++--------------------------------------------------------------------+--------------------+-------------+ +| :doc:`dipole ` | k,gamma0 | type angles | ++--------------------------------------------------------------------+--------------------+-------------+ +| :doc:`fourier ` | k,c0,c1,c2 | type angles | ++--------------------------------------------------------------------+--------------------+-------------+ +| :doc:`fourier/simple ` | k,c,n | type angles | ++--------------------------------------------------------------------+--------------------+-------------+ +| :doc:`gaussian ` | alpha,width,theta0 | type angles | ++--------------------------------------------------------------------+--------------------+-------------+ +| :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 | ++--------------------------------------------------------------------+--------------------+-------------+ Note that internally, theta0 is stored in radians, so the variable this fix uses to reset theta0 needs to generate values in radians. diff --git a/doc/src/fix_adapt_fep.rst b/doc/src/fix_adapt_fep.rst index 3bcdfc5035..981a1c5298 100644 --- a/doc/src/fix_adapt_fep.rst +++ b/doc/src/fix_adapt_fep.rst @@ -116,12 +116,22 @@ style supports it. Note that the :doc:`pair_style ` and to specify these parameters initially; the fix adapt command simply overrides the parameters. -The *pstyle* argument is the name of the pair style. If :doc:`pair_style hybrid or hybrid/overlay ` is used, *pstyle* should be -a sub-style name. For example, *pstyle* could be specified as "soft" -or "lubricate". The *pparam* argument is the name of the parameter to -change. This is the current list of pair styles and parameters that -can be varied by this fix. See the doc pages for individual pair -styles and their energy formulas for the meaning of these parameters: +.. note:: + + Pair_coeff settings must be made **explicitly** in order for fix + adapt/fep to be able to change them. Settings inferred from mixing + are not suitable. If necessary all mixed settings can be output + to a file using the :doc:`write_coeff command ` and + then the desired mixed pair_coeff settings copied from that file. + +The *pstyle* argument is the name of the pair style. If +:doc:`pair_style hybrid or hybrid/overlay ` is used, +*pstyle* should be a sub-style name. For example, *pstyle* could be +specified as "soft" or "lubricate". The *pparam* argument is the name +of the parameter to change. This is the current list of pair styles and +parameters that can be varied by this fix. See the doc pages for +individual pair styles and their energy formulas for the meaning of +these parameters: +------------------------------------------------------------------------------+-------------------------+------------+ | :doc:`born ` | a,b,c | type pairs | diff --git a/doc/src/fix_addforce.rst b/doc/src/fix_addforce.rst index 68a32695b7..2813270307 100644 --- a/doc/src/fix_addforce.rst +++ b/doc/src/fix_addforce.rst @@ -115,10 +115,6 @@ correctly, the minimization will not converge properly. ---------- -.. include:: accel_styles.rst - ----------- - Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/fix_atom_swap.rst b/doc/src/fix_atom_swap.rst index 48f5b33a74..fd4a2f7245 100644 --- a/doc/src/fix_atom_swap.rst +++ b/doc/src/fix_atom_swap.rst @@ -119,15 +119,14 @@ groups of atoms that have different charges, these charges will not be changed when the atom types change. Since this fix computes total potential energies before and after -proposed swaps, so even complicated potential energy calculations are -OK, including the following: +proposed swaps, even complicated potential energy calculations are +acceptable, including the following: * long-range electrostatics (:math:`k`-space) * many body pair styles -* hybrid pair styles -* eam pair styles +* hybrid pair styles (with restrictions) +* EAM pair styles * triclinic systems -* need to include potential energy contributions from other fixes Some fixes have an associated potential energy. Examples of such fixes include: :doc:`efield `, :doc:`gravity `, @@ -181,6 +180,10 @@ This fix is part of the MC package. It is only enabled if LAMMPS was built with that package. See the :doc:`Build package ` doc page for more info. +When this fix is used with a :doc:`hybrid pair style ` +system, only swaps between atom types of the same sub-style (or +combination of sub-styles) are permitted. + This fix cannot be used with systems that do not have per-type masses (e.g. atom style sphere) since the implemented algorithm pre-computes velocity rescaling factors from per-type masses and ignores any per-atom 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_aveforce.rst b/doc/src/fix_aveforce.rst index ea535697f4..36f53ef571 100644 --- a/doc/src/fix_aveforce.rst +++ b/doc/src/fix_aveforce.rst @@ -71,10 +71,6 @@ to it. ---------- -.. include:: accel_styles.rst - ----------- - Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/fix_cmap.rst b/doc/src/fix_cmap.rst index 316ad5d038..ccca88232b 100644 --- a/doc/src/fix_cmap.rst +++ b/doc/src/fix_cmap.rst @@ -1,8 +1,11 @@ .. index:: fix cmap +.. index:: fix cmap/kk fix cmap command ================ +Accelerator Variants: *cmap/kk* + Syntax """""" @@ -141,6 +144,12 @@ outermost level. MUST not disable the :doc:`fix_modify ` *energy* option for this fix. +---------- + +.. include:: accel_styles.rst + +---------- + Restrictions """""""""""" diff --git a/doc/src/fix_colvars.rst b/doc/src/fix_colvars.rst index 4730e29c67..21a9d06714 100644 --- a/doc/src/fix_colvars.rst +++ b/doc/src/fix_colvars.rst @@ -1,8 +1,11 @@ .. index:: fix colvars +.. index:: fix colvars/kk fix colvars command =================== +Accelerator Variants: *colvars/kk* + Syntax """""" @@ -118,6 +121,16 @@ thermostat target temperature. The *seed* keyword contains the seed for the random number generator that will be used in the colvars module. +---------- + +.. note:: + + Fix colvars/kk is not really ported to KOKKOS, since the colvars + library has not been ported to KOKKOS. It merely has some + optimizations to reduce the data transfers between host and device + for KOKKOS with GPUs. + +---------- Restarting """""""""" 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_external.rst b/doc/src/fix_external.rst index 44dd0929ee..fa10248a42 100644 --- a/doc/src/fix_external.rst +++ b/doc/src/fix_external.rst @@ -139,9 +139,9 @@ properties are: void set_vector_length(int n); void set_vector(int idx, double val); -These allow to set per-atom energy contributions, per-atom stress -contributions, the length and individual values of a global vector -of properties that the caller code may want to communicate to LAMMPS +These enable setting per-atom energy and per-atom stress contributions, +the length and individual values of a global vector of properties that +the caller code may want to communicate to LAMMPS (e.g. for use in :doc:`fix ave/time ` or in :doc:`equal-style variables ` or for :doc:`custom thermo output `. @@ -173,9 +173,19 @@ stress/atom ` commands. The former can be accessed by :doc:`thermodynamic output `. The default setting for this fix is :doc:`fix_modify virial yes `. -This fix computes a global scalar which can be accessed by various -:doc:`output commands `. The scalar is the potential -energy discussed above. The scalar stored by this fix is "extensive". +This fix computes a global scalar, a global vector, and a per-atom array +which can be accessed by various :doc:`output commands `. +The scalar is the potential energy discussed above. The scalar stored +by this fix is "extensive". +The global vector has a custom length and needs to be set by the external +program using the +:cpp:func:`lammps_fix_external_set_vector() ` +and :cpp:func:`lammps_fix_external_set_vector_length() +` +calls of the LAMMPS library interface or the equivalent call of the Python +or Fortran modules. +The per-atom array has 3 values for each atom and is the applied external +force. No parameter of this fix can be used with the *start/stop* keywords of the :doc:`run ` command. diff --git a/doc/src/fix_gcmc.rst b/doc/src/fix_gcmc.rst index e6037af586..beb36fbafd 100644 --- a/doc/src/fix_gcmc.rst +++ b/doc/src/fix_gcmc.rst @@ -50,8 +50,8 @@ Syntax *intra_energy* value = intramolecular energy (energy units) *tfac_insert* value = scale up/down temperature of inserted atoms (unitless) *overlap_cutoff* value = maximum pair distance for overlap rejection (distance units) - *max* value = Maximum number of molecules allowed in the system - *min* value = Minimum number of molecules allowed in the system + *max* value = Maximum number of atoms allowed in the fix group (and region) + *min* value = Minimum number of atoms allowed in the fix group (and region) Examples """""""" @@ -380,10 +380,11 @@ an infinite positive energy to all new configurations that place any pair of atoms closer than the specified overlap cutoff distance. The *max* and *min* keywords allow for the restriction of the number of -atoms in the simulation. They automatically reject all insertion or -deletion moves that would take the system beyond the set boundaries. -Should the system already be beyond the boundary, only moves that bring -the system closer to the bounds may be accepted. +atoms in the fix group (and region in case the *region* keyword is +used). They automatically reject all insertion or deletion moves that +would take the system beyond the set boundaries. Should the system +already be beyond the boundary, only moves that bring the system closer +to the bounds may be accepted. The *group* keyword adds all inserted atoms to the :doc:`group ` of the group-ID value. The *grouptype* keyword adds all inserted atoms 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 25331804aa..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 """"""""""" @@ -101,7 +104,7 @@ hstyle = bondmax option. .. code-block:: LAMMPS compute bdist all bond/local dist - compute bmax all reduce max c_bdist + compute bmax all reduce max c_bdist inputs local variable bondmax equal c_bmax Thus these two versions of a fix halt command will do the same thing: @@ -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 520af505a1..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,10 +120,19 @@ 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 -prompts appears, one types the command line: +prompts appears, one types the command: .. parsed-literal:: @@ -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_langevin.rst b/doc/src/fix_langevin.rst index e04805427e..30e4c48270 100644 --- a/doc/src/fix_langevin.rst +++ b/doc/src/fix_langevin.rst @@ -231,12 +231,6 @@ the particles. As described below, this energy can then be printed out or added to the potential energy of the system to monitor energy conservation. -.. note:: - - This accumulated energy does NOT include kinetic energy removed - by the *zero* flag. LAMMPS will print a warning when both options are - active. - The keyword *zero* can be used to eliminate drift due to the thermostat. Because the random forces on different atoms are independent, they do not sum exactly to zero. As a result, this fix 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_nonaffine_displacement.rst b/doc/src/fix_nonaffine_displacement.rst index fd9830cc48..5fdd3ae772 100644 --- a/doc/src/fix_nonaffine_displacement.rst +++ b/doc/src/fix_nonaffine_displacement.rst @@ -102,7 +102,6 @@ zeroed. The *update* reference style implies the reference state will be updated *nstep* timesteps. The *offset* reference will update the reference state *nstep* timesteps before a multiple of *nevery* timesteps. - ---------- Restart, fix_modify, output, run start/stop, minimize info @@ -129,6 +128,12 @@ This compute is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +As this fix depends on a run including specific reference timesteps, it +currently does not update peratom values if used in conjunction with the +:doc:`rerun command ` since it cannot ensure the necessary reference +timesteps are included. + + Related commands """""""""""""""" diff --git a/doc/src/fix_nph_body.rst b/doc/src/fix_nph_body.rst index 9ee0bd7669..4cc6084ad1 100644 --- a/doc/src/fix_nph_body.rst +++ b/doc/src/fix_nph_body.rst @@ -79,8 +79,6 @@ It also means that changing attributes of *thermo_temp* or ---------- -.. include:: accel_styles.rst - Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/fix_npt_body.rst b/doc/src/fix_npt_body.rst index 31ef1653b8..b1a7e56fe4 100644 --- a/doc/src/fix_npt_body.rst +++ b/doc/src/fix_npt_body.rst @@ -103,8 +103,6 @@ remaining thermal degrees of freedom, and the bias is added back in. ---------- -.. include:: accel_styles.rst - Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" 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_nve_limit.rst b/doc/src/fix_nve_limit.rst index 23517aea40..3533a63ebc 100644 --- a/doc/src/fix_nve_limit.rst +++ b/doc/src/fix_nve_limit.rst @@ -1,8 +1,11 @@ .. index:: fix nve/limit +.. index:: fix nve/limit/kk fix nve/limit command ===================== +Accelerator Variants: *nve/limit/kk* + Syntax """""" @@ -79,6 +82,12 @@ is "extensive". 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 `. +---------- + +.. include:: accel_styles.rst + +---------- + Restrictions """""""""""" none diff --git a/doc/src/fix_nvt_body.rst b/doc/src/fix_nvt_body.rst index 4397159515..c3275a0e00 100644 --- a/doc/src/fix_nvt_body.rst +++ b/doc/src/fix_nvt_body.rst @@ -85,8 +85,6 @@ remaining thermal degrees of freedom, and the bias is added back in. ---------- -.. include:: accel_styles.rst - Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" 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_pour.rst b/doc/src/fix_pour.rst index 3b4bb5c723..7986929745 100644 --- a/doc/src/fix_pour.rst +++ b/doc/src/fix_pour.rst @@ -155,6 +155,22 @@ many timesteps until the desired # of particles has been inserted. the :doc:`compute_modify dynamic/dof yes ` command for the temperature compute you are using. +.. admonition:: Implementation Notes + :class: Hint + + The exact insertion procedure depends on many factors (e.g. the range of + diameters inserted or whether molecules are being inserted). However, in + the simplest scenario of monodisperse atoms, the procedure works as + follows. First, the number of timesteps between two insertion events is + calculated as the time for a particle to fall through the insertion region, + accounting for gravity and any region motion. Next, the target number of + particles inserted per event (assuming no failed insertions due to overlaps) + is calculated as the product of the volume fraction and the volume of the + insertion region divided by the volume of a particle (or area in 2D). + Events are repeated until all N particles have been inserted, where + the final event is likely interrupted upon reaching N. Estimates of this + process are printed to the log/screen at the start of a run. + ---------- All other keywords are optional with defaults as shown below. diff --git a/doc/src/fix_precession_spin.rst b/doc/src/fix_precession_spin.rst index 7440989d7a..88325ba491 100644 --- a/doc/src/fix_precession_spin.rst +++ b/doc/src/fix_precession_spin.rst @@ -135,7 +135,7 @@ directions for the forces. Only the direction of the vector is important; its length is ignored (the entered vectors are normalized). -Those styles can be combined within one single command line. +Those styles can be combined within one single command. .. note:: 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 f353e9a998..ac0bca84f1 100644 --- a/doc/src/fix_qeq.rst +++ b/doc/src/fix_qeq.rst @@ -1,6 +1,7 @@ .. index:: fix qeq/point .. index:: fix qeq/shielded .. index:: fix qeq/slater +.. index:: fix qeq/ctip .. index:: fix qeq/dynamic .. index:: fix qeq/fire @@ -13,6 +14,9 @@ fix qeq/shielded command fix qeq/slater command ====================== +fix qeq/ctip command +==================== + fix qeq/dynamic command ======================= @@ -27,18 +31,20 @@ Syntax fix ID group-ID style Nevery cutoff tolerance maxiter qfile keyword ... * ID, group-ID are documented in :doc:`fix ` command -* style = *qeq/point* or *qeq/shielded* or *qeq/slater* or *qeq/dynamic* or *qeq/fire* +* style = *qeq/point* or *qeq/shielded* or *qeq/slater* or *qeq/ctip* or *qeq/dynamic* or *qeq/fire* * Nevery = perform charge equilibration every this many steps * cutoff = global cutoff for charge-charge interactions (distance unit) * tolerance = precision to which charges will be equilibrated * maxiter = maximum iterations to perform charge equilibration -* qfile = a filename with QEq parameters or *coul/streitz* or *reaxff* +* qfile = a filename with QEq parameters or *coul/streitz* or *coul/ctip* or *reaxff* * zero or more keyword/value pairs may be appended -* keyword = *alpha* or *qdamp* or *qstep* or *warn* +* keyword = *alpha* or *cdamp* or *maxrepeat* or *qdamp* or *qstep* or *warn* .. parsed-literal:: *alpha* value = Slater type orbital exponent (qeq/slater only) + *cdamp* value = damping parameter for Coulomb interactions (qeq/ctip only) + *maxrepeat* value = number of equilibration cycles allowed to ensure no atoms cross charge bounds (qeq/ctip only) *qdamp* value = damping factor for damped dynamics charge solver (qeq/dynamic and qeq/fire only) *qstep* value = time step size for damped dynamics charge solver (qeq/dynamic and qeq/fire only) *warn* value = do (=yes) or do not (=no) print a warning when the maximum number of iterations is reached @@ -51,6 +57,7 @@ Examples fix 1 all qeq/point 1 10 1.0e-6 200 param.qeq1 fix 1 qeq qeq/shielded 1 8 1.0e-6 100 param.qeq2 fix 1 all qeq/slater 5 10 1.0e-6 100 params alpha 0.2 + fix 1 all qeq/ctip 1 12 1.0e-8 100 coul/ctip cdamp 0.30 maxrepeat 10 fix 1 qeq qeq/dynamic 1 12 1.0e-3 100 my_qeq fix 1 all qeq/fire 1 10 1.0e-3 100 my_qeq qdamp 0.2 qstep 0.1 @@ -103,7 +110,7 @@ equalizes the derivative of energy with respect to charge of all the atoms) by adjusting the partial charge on individual atoms based on interactions with their neighbors within *cutoff*\ . It requires a few parameters in the appropriate units for each atom type which are read -from a file specified by *qfile*\ . The file has the following format +from a file specified by *qfile*\ . The file has the following format: .. parsed-literal:: @@ -112,20 +119,32 @@ from a file specified by *qfile*\ . The file has the following format ... Ntype chi eta gamma zeta qcore +except for fix style *qeq/ctip* where the format is: + +.. parsed-literal:: + + 1 chi eta gamma zeta qcore qmin qmax omega + 2 chi eta gamma zeta qcore qmin qmax omega + ... + Ntype chi eta gamma zeta qcore qmin qmax omega + There have to be parameters given for every atom type. Wildcard entries are possible using the same type range syntax as for "coeff" commands (i.e., n\*m, n\*, \*m, \*). Later entries will overwrite previous ones. -Empty lines or any text following the pound sign (#) are ignored. -Each line starts with the atom type followed by five parameters. -Only a subset of the parameters is used by each QEq style as described -below, thus the others can be set to 0.0 if desired, but all five -entries per line are required. +Empty lines or any text following the pound sign (#) are ignored. Each +line starts with the atom type followed by eight parameters. Only a +subset of the parameters is used by each QEq style as described below, +thus the others can be set to 0.0 if desired, but all eight entries per +line are required. * *chi* = electronegativity in energy units * *eta* = self-Coulomb potential in energy units * *gamma* = shielded Coulomb constant defined by :ref:`ReaxFF force field ` in distance units * *zeta* = Slater type orbital exponent defined by the :ref:`Streitz-Mintmire ` potential in reverse distance units * *qcore* = charge of the nucleus defined by the :ref:`Streitz-Mintmire potential ` potential in charge units +* *qmin* = lower bound on the allowed charge defined by the :ref:`CTIP ` potential in charge units +* *qmax* = upper bound on the allowed charge defined by the :ref:`CTIP ` potential in charge units +* *omega* = penalty parameter used to enforce charge bounds defined by the :ref:`CTIP ` potential in energy units The fix qeq styles will print a warning if the charges are not equilibrated within *tolerance* by *maxiter* steps, unless the @@ -171,6 +190,22 @@ on atoms via the matrix inversion method. A tolerance of 1.0e-6 is usually a good number. Keyword *alpha* can be used to change the Slater type orbital exponent. +.. versionadded:: 19Nov2024 + +The *qeq/ctip* style describes partial charges on atoms in the same way +as style *qeq/shielded* but also enables the definition of charge +bounds. Only the *chi*, *eta*, *gamma*, *qmin*, *qmax*, and *omega* +parameters from the *qfile* file are used. When using the string +*coul/ctip* as filename, these parameters are extracted directly from an +active *coul/ctip* pair style. This style solves partial charges on +atoms via the matrix inversion method. Keyword *cdamp* can be used to +change the damping parameter used to calculate Coulomb interactions. +Keyword *maxrepeat* can be used to adjust the number of equilibration +cycles allowed to ensure no atoms have crossed the charge bounds. A +value of 10 is usually a good choice. A tolerance between 1.0e-6 and +1.0e-8 is usually a good choice but should be checked in conjunction +with the timestep for adequate energy conservation during dynamic runs. + The *qeq/dynamic* style describes partial charges on atoms as point charges that interact through 1/r, but the extended Lagrangian method is used to solve partial charges on atoms. Only the *chi* and *eta* @@ -186,7 +221,7 @@ minimization algorithm to solve for equilibrium charges. Keyword *qdamp* can be used to change the damping factor, while keyword *qstep* can be used to change the time step size. -Note that *qeq/point*, *qeq/shielded*, and *qeq/slater* describe +Note that *qeq/point*, *qeq/shielded*, *qeq/slater*, and *qeq/ctip* describe different charge models, whereas the matrix inversion method and the extended Lagrangian method (\ *qeq/dynamic* and *qeq/fire*\ ) are different solvers. @@ -266,6 +301,11 @@ Chemistry, 95, 3358-3363 (1991). **(Streitz-Mintmire)** F. H. Streitz, J. W. Mintmire, Physical Review B, 50, 16, 11996 (1994) +.. _CTIP1: + +**(CTIP)** G. Plummer, J. P. Tavenner, M. I. Mendelev, Z. Wu, J. W. Lawson, +J Chemical Physics, 162, 054709 (2025) + .. _vanDuin: **(ReaxFF)** A. C. T. van Duin, S. Dasgupta, F. Lorant, W. A. Goddard III, J diff --git a/doc/src/fix_qeq_reaxff.rst b/doc/src/fix_qeq_reaxff.rst index e90842ea6a..e1a09c4fc3 100644 --- a/doc/src/fix_qeq_reaxff.rst +++ b/doc/src/fix_qeq_reaxff.rst @@ -124,7 +124,8 @@ LAMMPS was built with that package. See the :doc:`Build package This fix does not correctly handle interactions involving multiple periodic images of the same atom. Hence, it should not be used for -periodic cell dimensions less than 10 Angstroms. +periodic cell dimensions smaller than the non-bonded cutoff radius, +which is typically :math:`10~\AA` for ReaxFF simulations. This fix may be used in combination with :doc:`fix efield ` and will apply the external electric field during charge equilibration, @@ -138,7 +139,8 @@ as an atom-style variable using the *potential* keyword for `fix efield`. Related commands """""""""""""""" -:doc:`pair_style reaxff `, :doc:`fix qeq/shielded ` +:doc:`pair_style reaxff `, :doc:`fix qeq/shielded `, +:doc:`fix acks2/reaxff `, :doc:`fix qtpie/reaxff ` Default """"""" diff --git a/doc/src/fix_qtpie_reaxff.rst b/doc/src/fix_qtpie_reaxff.rst new file mode 100644 index 0000000000..e96cbec459 --- /dev/null +++ b/doc/src/fix_qtpie_reaxff.rst @@ -0,0 +1,200 @@ +.. index:: fix qtpie/reaxff + +fix qtpie/reaxff command +======================== + +Syntax +"""""" + +.. code-block:: LAMMPS + + fix ID group-ID qtpie/reaxff Nevery cutlo cuthi tolerance params gfile args + +* ID, group-ID are documented in :doc:`fix ` command +* qtpie/reaxff = style name of this fix command +* Nevery = perform QTPIE every this many steps +* cutlo,cuthi = lo and hi cutoff for Taper radius +* tolerance = precision to which charges will be equilibrated +* params = reaxff or a filename +* gfile = the name of a file containing Gaussian orbital exponents +* one or more keywords or keyword/value pairs may be appended + + .. parsed-literal:: + + keyword = *maxiter* + *maxiter* N = limit the number of iterations to *N* + +Examples +"""""""" + +.. code-block:: LAMMPS + + fix 1 all qtpie/reaxff 1 0.0 10.0 1.0e-6 reaxff exp.qtpie + fix 1 all qtpie/reaxff 1 0.0 10.0 1.0e-6 params.qtpie exp.qtpie maxiter 500 + +Description +""""""""""" + +.. versionadded:: 19Nov2024 + +The QTPIE charge equilibration method is an extension of the QEq charge +equilibration method. With QTPIE, the partial charges on individual atoms +are computed by minimizing the electrostatic energy of the system in the +same way as the QEq method but where the absolute electronegativity, +:math:`\chi_i`, of each atom in the QEq charge equilibration scheme +:ref:`(Rappe and Goddard) ` is replaced with an effective +electronegativity given by :ref:`(Chen) ` + +.. math:: + \chi_{\mathrm{eff},i} = \frac{\sum_{j=1}^{N} (\chi_i - \chi_j) S_{ij}} + {\sum_{m=1}^{N}S_{im}}, + +which acts to penalize long-range charge transfer seen with the QEq charge +equilibration scheme. In this equation, :math:`N` is the number of atoms in +the system and :math:`S_{ij}` is the overlap integral between atom :math:`i` +and atom :math:`j`. + +The effect of an external electric field can be incorporated into the QTPIE +method by modifying the absolute or effective electronegativities of each +atom :ref:`(Chen) `. This fix models the effect of an external +electric field by using the effective electronegativity given in +:ref:`(Gergs) `: + +.. math:: + \chi_{\mathrm{eff},i} = \frac{\sum_{j=1}^{N} (\chi_i - \chi_j + \phi_i - \phi_j) S_{ij}} + {\sum_{m=1}^{N}S_{im}}, + +where :math:`\phi_i` and :math:`\phi_j` are the electric +potentials at the positions of atom :math:`i` and :math:`j` +due to the external electric field. + +This fix is typically used in conjunction with the ReaxFF force +field model as implemented in the :doc:`pair_style reaxff ` +command, but it can be used with any potential in LAMMPS, so long as it +defines and uses charges on each atom. For more technical details about the +charge equilibration performed by `fix qtpie/reaxff`, which is the same as in +:doc:`fix qeq/reaxff ` except for the use of +:math:`\chi_{\mathrm{eff},i}`, please refer to :ref:`(Aktulga) `. +To be explicit, this fix replaces :math:`\chi_k` of eq. 3 in +:ref:`(Aktulga) ` with :math:`\chi_{\mathrm{eff},k}`. + +This fix requires the absolute electronegativity, :math:`\chi`, in eV, the +self-Coulomb potential, :math:`\eta`, in eV, and the shielded Coulomb +constant, :math:`\gamma`, in :math:`\AA^{-1}`. If the *params* setting above +is the word "reaxff", then these are extracted from the +:doc:`pair_style reaxff ` command and the ReaxFF force field +file it reads in. If a file name is specified for *params*, then the +parameters are taken from the specified file and the file must contain +one line for each atom type. The latter form must be used when performing +QTPIE with a non-ReaxFF potential. Each line should be formatted as follows, +ensuring that the parameters are given in units of eV, eV, and :math:`\AA^{-1}`, +respectively: + +.. parsed-literal:: + + itype chi eta gamma + +where *itype* is the atom type from 1 to Ntypes. Note that eta is +defined here as twice the eta value in the ReaxFF file. + +The overlap integrals in the equation for :math:`\chi_{\mathrm{eff},i}` +are computed by using normalized 1s Gaussian type orbitals. The Gaussian +orbital exponents, :math:`\alpha`, that are needed to compute the overlap +integrals are taken from the file given by *gfile*. +This file must contain one line for each atom type and provide the Gaussian +orbital exponent for each atom type in units of inverse square Bohr radius. +Each line should be formatted as follows: + +.. parsed-literal:: + + itype alpha + +Empty lines or any text following the pound sign (#) are ignored. An example +*gfile* for a system with two atom types is + +.. parsed-literal:: + + # An example gfile. Exponents are taken from Table 2.2 of Chen, J. (2009). + # Theory and applications of fluctuating-charge models. + # The units of the exponents are 1 / (Bohr radius)^2 . + 1 0.2240 # O + 2 0.5434 # H + +The optional *maxiter* keyword allows changing the max number +of iterations in the linear solver. The default value is 200. + +.. note:: + + In order to solve the self-consistent equations for electronegativity + equalization, LAMMPS imposes the additional constraint that all the + charges in the fix group must add up to zero. The initial charge + assignments should also satisfy this constraint. LAMMPS will print a + warning if that is not the case. + +Restart, fix_modify, output, run start/stop, minimize info +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +No information about this fix is written to :doc:`binary restart files +`. This fix computes a global scalar (the number of +iterations) and a per-atom vector (the effective electronegativity), which +can be accessed 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 invoked during :doc:`energy minimization `. + +Restrictions +"""""""""""" + +This fix is part of the REAXFF package. It is only enabled if +LAMMPS was built with that package. See the :doc:`Build package +` page for more info. + +This fix does not correctly handle interactions involving multiple +periodic images of the same atom. Hence, it should not be used for +periodic cell dimensions smaller than the non-bonded cutoff radius, +which is typically :math:`10~\AA` for ReaxFF simulations. + +This fix may be used in combination with :doc:`fix efield ` +and will apply the external electric field during charge equilibration, +but there may be only one fix efield instance used and the electric field +must be applied to all atoms in the system. Consequently, `fix efield` must +be used with *group-ID* all and must not be used with the keyword *region*. +Equal-style variables can be used for electric field vector +components without any further settings. Atom-style variables can be used +for spatially-varying electric field vector components, but the resulting +electric potential must be specified as an atom-style variable using +the *potential* keyword for `fix efield`. + +Related commands +"""""""""""""""" + +:doc:`pair_style reaxff `, :doc:`fix qeq/reaxff `, +:doc:`fix acks2/reaxff ` + +Default +""""""" + +maxiter 200 + +---------- + +.. _Rappe3: + +**(Rappe)** Rappe and Goddard III, Journal of Physical Chemistry, 95, +3358-3363 (1991). + +.. _qtpie-Chen: + +**(Chen)** Chen, Jiahao. Theory and applications of fluctuating-charge models. +University of Illinois at Urbana-Champaign, 2009. + +.. _Gergs: + +**(Gergs)** Gergs, Dirkmann and Mussenbrock. +Journal of Applied Physics 123.24 (2018). + +.. _qeq-Aktulga2: + +**(Aktulga)** Aktulga, Fogarty, Pandit, Grama, Parallel Computing, 38, +245-259 (2012). 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_recenter.rst b/doc/src/fix_recenter.rst index 9991904b37..60a8a674d0 100644 --- a/doc/src/fix_recenter.rst +++ b/doc/src/fix_recenter.rst @@ -1,8 +1,11 @@ .. index:: fix recenter +.. index:: fix recenter/kk fix recenter command ==================== +Accelerator Variants: *recenter/kk* + Syntax """""" @@ -113,6 +116,12 @@ The scalar and vector values calculated by this fix are "extensive". No parameter of this fix can be used with the *start/stop* keywords of the :doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. +---------- + +.. include:: accel_styles.rst + +---------- + Restrictions """""""""""" diff --git a/doc/src/fix_rheo.rst b/doc/src/fix_rheo.rst index 2977662238..ef18d19f82 100644 --- a/doc/src/fix_rheo.rst +++ b/doc/src/fix_rheo.rst @@ -16,22 +16,36 @@ Syntax * kstyle = *quintic* or *RK0* or *RK1* or *RK2* * zmin = minimal number of neighbors for reproducing kernels * zero or more keyword/value pairs may be appended to args -* keyword = *thermal* or *interface/reconstruct* or *surface/detection* or - *shift* or *rho/sum* or *density* or *self/mass* or *speed/sound* +* keyword = *thermal* or *interface/reconstruct* or *surface/detection* or *shift* or *rho/sum* or *density* or *speed/sound* .. parsed-literal:: - *thermal* values = none, turns on thermal evolution - *interface/reconstruct* values = none, reconstructs interfaces with solid particles - *surface/detection* values = *sdstyle* *limit* *limit/splash* - *sdstyle* = *coordination* or *divergence* - *limit* = threshold for surface particles - *limit/splash* = threshold for splash particles - *shift* values = none, turns on velocity shifting - *rho/sum* values = none, uses the kernel to compute the density of particles - *self/mass* values = none, a particle uses its own mass in a rho summation - *density* values = *rho01*, ... *rho0N* (density) - *speed/sound* values = *cs0*, ... *csN* (velocity) + *thermal* turns on thermal evolution + values = none + *interface/reconstruct* reconstructs interfaces with solid particles + values = none + *surface/detection* detects free-surfaces with an absence of particles + values = *sdstyle* *limit* *limit/splash* + *sdstyle* = *coordination* or *divergence* + *limit* = threshold for surface particles + *limit/splash* = threshold for splash particles (unitless) + *shift* turns on velocity shifting + values = none + optional args = *exclude/type* or *scale/cross/type* + *exclude/type* values = *types* + *types* = list of types + *scale/cross/type* values = *shiftscale* *cmin* *wmin* + *shiftscale* = fraction of shifting in normal direction to preserve (unitless) + *cmin* = minimum color function value required for scaling (unitless) + *wmin* = minimum local same-type support required for any shifting (unitless) + *rho/sum* density evolution performed by a kernel summation + values = none + optional args = *self/mass* + *self/mass* values = none, a particle uses its own mass in summation + *density* specify equilibrium densities for each atom type + values = *rho01*, ... *rho0N* (density) + *speed/sound* specify speeds of sound for each atom type + values = *cs0*, ... *csN* (velocity) Examples """""""" @@ -40,6 +54,8 @@ Examples fix 1 all rheo 3.0 quintic 0 thermal density 0.1 0.1 speed/sound 10.0 1.0 fix 1 all rheo 3.0 RK1 10 shift surface/detection coordination 40 + fix 1 all rheo 3.0 RK1 10 shift exclude/type 2*4 scale/cross/type 0.05 0.02 0.5 + fix 1 all rheo 3.0 RK1 10 rhosum self/mass Description """"""""""" @@ -47,8 +63,10 @@ Description .. versionadded:: 29Aug2024 Perform time integration for RHEO particles, updating positions, velocities, -and densities. For an overview of other features available in the RHEO package, -see :doc:`the RHEO howto `. +and densities. For a detailed breakdown of the integration timestep and +numerical details, see :ref:`(Palermo) `. For an overview +and list of other features available in the RHEO package, see +:doc:`the RHEO howto `. The type of kernel is specified using *kstyle* and the cutoff is *cut*. Four kernels are currently available. The *quintic* kernel is a standard quintic @@ -71,16 +89,51 @@ and velocity of solid particles are alternatively reconstructed for every fluid-solid interaction to ensure no-slip and pressure-balanced boundaries. This is done by estimating the location of the fluid-solid interface and extrapolating fluid particle properties across the interface to calculate a -temporary apparent density and velocity for a solid particle. +temporary apparent density and velocity for a solid particle. The numerical +details are the same as those described in +:ref:`(Palermo) ` except there is an additional +restriction that the reconstructed solid density cannot be less than the +equilibrium density. This prevents fluid particles from sticking to solid +surfaces. A modified form of Fickian particle shifting can be enabled with the *shift* keyword. This effectively shifts particle positions to generate a -more uniform spatial distribution. Shifting currently does not consider the +more uniform spatial distribution. By default, shifting does not consider the type of a particle and therefore may be inappropriate in systems consisting -of multiple fluid phases. +of multiple atom types representing multiple fluid phases. However, two +optional sub-arguments can follow the *shift* keyword, *exclude/type* and +*scale/cross/type* to adjust shifting at fluid interfaces. -In systems with free surfaces, the *surface/detection* keyword can be used -to classify the location of particles as being within the bulk fluid, on a +The *exclude/type* option lets the user specify a list of atom types which +are not shifted, *types*. A wild-card asterisk can be used in place +of or in conjunction with the *types* argument to toggle shifting for +multiple atom types. This takes the form "\*" or "\*n" or "m\*" +or "m\*n". If :math:`N` is the number of atom types, then an asterisk with +no numeric values means all types from 1 to :math:`N`. A leading asterisk +means all types from 1 to n (inclusive). A trailing asterisk means all types +from m to :math:`N` (inclusive). A middle asterisk means all types from m to n +(inclusive). + +The *scale/cross/type* option is designed to handle interfaces between fluids +made up of different atom types. Similar to the method by +:ref:`(Yang) `, a color function is calculated and used to +estimate a local interfacial normal vector. Shifting along this normal direction +is rescaled by a factor of *scaleshift*, such that a value of *scaleshift* of +zero implies there is no shifting in the normal direction and a value of +*scaleshift* of one implies no change in behavior. This scaling is only applied +to atoms with a color function value greater than *cmin*. To handle scenarios +of a small inclusion of one fluid type (e.g. a single atom) inside another, +the degree of same-type support is calculated + +.. math:: + W_{i,\mathrm{same}} = \sum_{j} W_{ij} \delta_{ij} + +where :math:`\delta_{ij}` is zero if atoms :math:`i` and :math:`j` have different +types but unity otherwise. If :math:`W_{i,\mathrm{same}}` is ever less than the +specified value of *wmin*, shifting is turned off for particle :math:`i` + +In systems with free surfaces (atom-vacuum), the *surface/detection* keyword +can classify the location of particles as being within the bulk fluid, on a free surface, or isolated from other particles in a splash or droplet. Shifting is then disabled in the normal direction away from the free surface to prevent particles from diffusing away. Surface detection can also be used @@ -102,10 +155,9 @@ threshold for this classification is set by the numerical value of By default, RHEO integrates particles' densities using a mass diffusion equation. Alternatively, one can update densities every timestep by performing a kernel summation of the masses of neighboring particles by specifying the *rho/sum* -keyword. - -The *self/mass* keyword modifies the behavior of the density summation in *rho/sum*. -Typically, the density :math:`\rho` of a particle is calculated as the sum over neighbors +keyword. Following this keyword, one may include the optional *self/mass* sub-argument +which modifies the behavior of the density summation. Typically, the density +:math:`\rho` of a particle is calculated as the sum over neighbors .. math:: \rho_i = \sum_{j} W_{ij} M_j @@ -121,7 +173,9 @@ equilibrium density *rho0*. The *speed/sound* keyword is used to specify the speed of sound of each of the N particle types. It must be followed by N numerical values specifying each type's -speed of sound *cs*. +speed of sound *cs*. These values may be ignored if the pressure equation of +state has a non-constant speed of sound, as discussed further in +:doc:`fix rheo/pressure `. Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -164,6 +218,14 @@ Default ---------- +.. _fix_rheo_palermo: + +**(Palermo)** Palermo, Wolf, Clemmer, O'Connor, Phys. Fluids, 36, 113337 (2024). + +.. _fix_rheo_yang: + +**(Yang)** Yang, Rakhsha, Hu, Negrut, J. Comp. Physics, 458, 111079 (2022). + .. _fix_rheo_hu: -**(Hu)** Hu, and Adams J. Comp. Physics, 213, 844-861 (2006). +**(Hu)** Hu, and Adams, J. Comp. Physics, 213, 844-861 (2006). diff --git a/doc/src/fix_rheo_pressure.rst b/doc/src/fix_rheo_pressure.rst index 2a714b298b..7d5d08ddd1 100644 --- a/doc/src/fix_rheo_pressure.rst +++ b/doc/src/fix_rheo_pressure.rst @@ -14,13 +14,16 @@ Syntax * rheo/pressure = style name of this fix command * one or more types and pressure styles must be appended * types = lists of types (see below) -* pstyle = *linear* or *taitwater* or *cubic* +* pstyle = *linear* or *tait/water* or *tait/general* or *cubic* or *ideal/gas* or *background* .. parsed-literal:: *linear* args = none - *taitwater* args = none + *tait/water* args = none + *tait/general* args = exponent :math:`gamma` (unitless) *cubic* args = cubic prefactor :math:`A_3` (pressure/density\^2) + *ideal/gas* args = heat capacity ratio :math:`gamma` (unitless) + *background* args = background pressure :math:`P[b]` (pressure) Examples """""""" @@ -29,6 +32,7 @@ Examples fix 1 all rheo/pressure * linear fix 1 all rheo/pressure 1 linear 2 cubic 10.0 + fix 1 all rheo/pressure * linear * background 0.1 Description """"""""""" @@ -40,13 +44,12 @@ define different equations of state for different atom types. An equation must be specified for every atom type. One first defines the atom *types*. A wild-card asterisk can be used in place -of or in conjunction with the *types* argument to set the coefficients for -multiple pairs of atom types. This takes the form "\*" or "\*n" or "m\*" -or "m\*n". If :math:`N` is the number of atom types, then an asterisk with -no numeric values means all types from 1 to :math:`N`. A leading asterisk -means all types from 1 to n (inclusive). A trailing asterisk means all types -from m to :math:`N` (inclusive). A middle asterisk means all types from m to n -(inclusive). +of or in conjunction with the *types* argument to set values for multiple atom +types. This takes the form "\*" or "\*n" or "m\*" or "m\*n". If :math:`N` is +the number of atom types, then an asterisk with no numeric values means all types +from 1 to :math:`N`. A leading asterisk means all types from 1 to n (inclusive). +A trailing asterisk means all types from m to :math:`N` (inclusive). A middle +asterisk means all types from m to n (inclusive). The *types* definition is followed by the pressure style, *pstyle*. Current options *linear*, *taitwater*, and *cubic*. Style *linear* is a linear @@ -54,7 +57,7 @@ equation of state with a particle pressure :math:`P` calculated as .. math:: - P = c (\rho - \rho_0) + P = c^2 (\rho - \rho_0) where :math:`c` is the speed of sound, :math:`\rho_0` is the equilibrium density, and :math:`\rho` is the current density of a particle. The numerical values of @@ -63,14 +66,39 @@ is a cubic equation of state which has an extra argument :math:`A_3`, .. math:: - P = c ((\rho - \rho_0) + A_3 (\rho - \rho_0)^3) . + P = c^2 ((\rho - \rho_0) + A_3 (\rho - \rho_0)^3) . -Style *taitwater* is Tait's equation of state: +Style *tait/water* is Tait's equation of state: .. math:: P = \frac{c^2 \rho_0}{7} \biggl[\left(\frac{\rho}{\rho_0}\right)^{7} - 1\biggr]. +Style *tait/general* generalizes this equation of state + +.. math:: + + P = \frac{c^2 \rho_0}{\gamma} \biggl[\left(\frac{\rho}{\rho_0}\right)^{\gamma} - 1\biggr]. + +where :math:`\gamma` is an exponent. + +Style *ideal/gas* is the ideal gas equation of state + +.. math:: + + P = (\gamma - 1) \rho e + +where :math:`\gamma` is the heat capacity ratio and :math:`e` is the internal energy of +a particle per unit mass. This style is only compatible with atom style rheo/thermal. +Note that when using this style, the speed of sound is no longer constant such that the +value of :math:`c` specified in :doc:`fix rheo ` is not used. + +The *background* style acts differently than the rest as it +only adds a constant background pressure shift :math:`P[b]` +to all atoms of the designated types. Therefore, this style +must be used in conjunction with another style that specifies +an equation of state. + Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/fix_rheo_thermal.rst b/doc/src/fix_rheo_thermal.rst index 214bc1db86..bc0e8dbfd0 100644 --- a/doc/src/fix_rheo_thermal.rst +++ b/doc/src/fix_rheo_thermal.rst @@ -70,13 +70,13 @@ of the energy is used to shift energies. This may be inappropriate in systems with multiple atom types with different specific heats. For each property, one must first define a list of atom types. A wild-card -asterisk can be used in place of or in conjunction with the *types* argument -to set the coefficients for multiple pairs of atom types. This takes the -form "\*" or "\*n" or "m\*" or "m\*n". If :math:`N` is the number of atom -types, then an asterisk with no numeric values means all types from 1 to -:math:`N`. A leading asterisk means all types from 1 to n (inclusive). -A trailing asterisk means all types from m to :math:`N` (inclusive). A -middle asterisk means all types from m to n (inclusive). +asterisk can be used in place of or in conjunction with the *types* argument to +set values for multiple atom types. This takes the form "\*" or "\*n" or "m\*" +or "m\*n". If :math:`N` is the number of atom types, then an asterisk with no +numeric values means all types from 1 to :math:`N`. A leading asterisk means +all types from 1 to n (inclusive). A trailing asterisk means all types from m +to :math:`N` (inclusive). A middle asterisk means all types from m to n +(inclusive). The *types* definition for each property is followed by the style. Currently, the only option is *constant*. Style *constant* simply applies a constant value diff --git a/doc/src/fix_rheo_viscosity.rst b/doc/src/fix_rheo_viscosity.rst index 804059e6f8..4d72d9b209 100644 --- a/doc/src/fix_rheo_viscosity.rst +++ b/doc/src/fix_rheo_viscosity.rst @@ -45,13 +45,12 @@ viscosities for different atom types, but a viscosity must be specified for every atom type. One first defines the atom *types*. A wild-card asterisk can be used in place -of or in conjunction with the *types* argument to set the coefficients for -multiple pairs of atom types. This takes the form "\*" or "\*n" or "m\*" -or "m\*n". If :math:`N` is the number of atom types, then an asterisk with -no numeric values means all types from 1 to :math:`N`. A leading asterisk -means all types from 1 to n (inclusive). A trailing asterisk means all types -from m to :math:`N` (inclusive). A middle asterisk means all types from m to n -(inclusive). +of or in conjunction with the *types* argument to set values for multiple atom +types. This takes the form "\*" or "\*n" or "m\*" or "m\*n". If :math:`N` is +the number of atom types, then an asterisk with no numeric values means all types +from 1 to :math:`N`. A leading asterisk means all types from 1 to n (inclusive). +A trailing asterisk means all types from m to :math:`N` (inclusive). A middle +asterisk means all types from m to n (inclusive). The *types* definition is followed by the viscosity style, *vstyle*. Two options are available, *constant* and *power*. Style *constant* simply diff --git a/doc/src/fix_sph.rst b/doc/src/fix_sph.rst index 4932485b03..09989d2fa0 100644 --- a/doc/src/fix_sph.rst +++ b/doc/src/fix_sph.rst @@ -32,6 +32,12 @@ Hydrodynamics. See `this PDF guide `_ to using SPH in LAMMPS. +.. note:: + + Please note that the SPH PDF guide file has not been updated for + many years and thus does not reflect the current *syntax* of the + SPH package commands. For that please refer to the LAMMPS manual. + Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/fix_sph_stationary.rst b/doc/src/fix_sph_stationary.rst index 07bedad4c3..57914d22b1 100644 --- a/doc/src/fix_sph_stationary.rst +++ b/doc/src/fix_sph_stationary.rst @@ -32,6 +32,12 @@ space. SPH stands for Smoothed Particle Hydrodynamics. See `this PDF guide `_ to using SPH in LAMMPS. +.. note:: + + Please note that the SPH PDF guide file has not been updated for + many years and thus does not reflect the current *syntax* of the + SPH package commands. For that please refer to the LAMMPS manual. + Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/fix_spring_self.rst b/doc/src/fix_spring_self.rst index 4453fd61c5..a78e7575f8 100644 --- a/doc/src/fix_spring_self.rst +++ b/doc/src/fix_spring_self.rst @@ -13,7 +13,7 @@ Syntax * ID, group-ID are documented in :doc:`fix ` command * spring/self = style name of this fix command -* K = spring constant (force/distance units) +* K = spring constant (force/distance units), can be a variable (see below) * dir = xyz, xy, xz, yz, x, y, or z (optional, default: xyz) Examples @@ -22,6 +22,7 @@ Examples .. code-block:: LAMMPS fix tether boundary-atoms spring/self 10.0 + fix var all spring/self v_kvar fix zrest move spring/self 10.0 z Description @@ -42,6 +43,22 @@ directions, but it can be limited to the xy-, xz-, yz-plane and the x-, y-, or z-direction, thus restraining the atoms to a line or a plane, respectively. +The force constant *k* can be specified as an equal-style or atom-style +:doc:`variable `. 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 evaluated each time step, and its value(s) will be used as +force constant for the spring force. + +Equal-style variables can specify formulas with various mathematical +functions and include :doc:`thermo_style ` command +keywords for the simulation box parameters, time step, and elapsed time. +Thus, it is easy to specify a time-dependent force field. + +Atom-style variables can specify the same formulas as equal-style +variables but can also include per-atom values, such as atom +coordinates. Thus, it is easy to specify a spatially-dependent force +field with optional time-dependence as well. + Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -89,7 +106,9 @@ invoked by the :doc:`minimize ` command. Restrictions """""""""""" - none + +The KOKKOS version, *fix spring/self/kk* may only be used with a constant +value of K, not a variable. Related commands """""""""""""""" diff --git a/doc/src/fix_wall_flow.rst b/doc/src/fix_wall_flow.rst index d498e57c63..ce2f204616 100644 --- a/doc/src/fix_wall_flow.rst +++ b/doc/src/fix_wall_flow.rst @@ -123,6 +123,12 @@ also be potentially mitigated by using more multiple walls. conservative as possible (every timestep if needed). Those are the default settings. +---------- + +.. include:: accel_styles.rst + +---------- + Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" 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/fix_wall_region.rst b/doc/src/fix_wall_region.rst index 466319c12e..67b9b9cdb2 100644 --- a/doc/src/fix_wall_region.rst +++ b/doc/src/fix_wall_region.rst @@ -1,8 +1,11 @@ .. index:: fix wall/region +.. index:: fix wall/region/kk fix wall/region command ======================= +Accelerator Variants: *wall/region/kk* + Syntax """""" @@ -234,6 +237,12 @@ invoked by the :doc:`minimize ` command. minimized), you MUST enable the :doc:`fix_modify ` *energy* option for this fix. +---------- + +.. include:: accel_styles.rst + +---------- + Restrictions """""""""""" none diff --git a/doc/src/fixes.rst b/doc/src/fixes.rst deleted file mode 100644 index eb0215e310..0000000000 --- a/doc/src/fixes.rst +++ /dev/null @@ -1,8 +0,0 @@ -Fixes -##### - -.. toctree:: - :maxdepth: 1 - :glob: - - fix_* diff --git a/doc/src/group.rst b/doc/src/group.rst index 15ab0c9dc8..a7a29467ff 100644 --- a/doc/src/group.rst +++ b/doc/src/group.rst @@ -162,7 +162,7 @@ potential energy is above the threshold value :math:`-3.0`. compute 1 all pe/atom compute 2 all reduce sum c_1 thermo_style custom step temp pe c_2 - run 0 + run 0 post no variable eatom atom "c_1 > -3.0" group hienergy variable eatom @@ -173,7 +173,7 @@ Note that these lines compute 2 all reduce sum c_1 thermo_style custom step temp pe c_2 - run 0 + run 0 post no are necessary to ensure that the "eatom" variable is current when the group command invokes it. Because the eatom variable computes the diff --git a/doc/src/impropers.rst b/doc/src/impropers.rst deleted file mode 100644 index a6653fde7d..0000000000 --- a/doc/src/impropers.rst +++ /dev/null @@ -1,8 +0,0 @@ -Improper Styles -############### - -.. toctree:: - :maxdepth: 1 - :glob: - - improper_* diff --git a/doc/src/kim_commands.rst b/doc/src/kim_commands.rst index ab9b4486a2..20728dee06 100644 --- a/doc/src/kim_commands.rst +++ b/doc/src/kim_commands.rst @@ -1084,10 +1084,11 @@ the form of *key_name_key*-*key_name_value* pairs). For example, kim property modify 1 key mass source-value 26.98154 kim property modify 1 key mass source-unit amu -where the special keyword "key" is followed by a *key_name* ("species" or -"mass" in the above) and one or more key-value pairs. These key-value pairs -may continue until either another "key" keyword is given or the end of the -command line is reached. Thus, the above could equivalently be written as +where the special keyword "key" is followed by a *key_name* ("species" +or "mass" in the above) and one or more key-value pairs. These +key-value pairs may continue until either another "key" keyword is given +or the end of the line is reached. Thus, the above could equivalently +be written as .. code-block:: LAMMPS 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/label.rst b/doc/src/label.rst index bf232431d7..cae1386e90 100644 --- a/doc/src/label.rst +++ b/doc/src/label.rst @@ -24,12 +24,12 @@ Description """"""""""" Label this line of the input script with the chosen ID. Unless a jump -command was used previously, this does nothing. But if a -:doc:`jump ` command was used with a label argument to begin -invoking this script file, then all command lines in the script prior -to this line will be ignored. I.e. execution of the script will begin -at this line. This is useful for looping over a section of the input -script as discussed in the :doc:`jump ` command. +command was used previously, this does nothing. But if a :doc:`jump +` command was used with a label argument to begin invoking this +script file, then all commands in the script prior to this line will be +ignored. I.e. execution of the script will begin at this line. This is +useful for looping over a section of the input script as discussed in +the :doc:`jump ` command. Restrictions """""""""""" 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/min_style.rst b/doc/src/min_style.rst index b89ae6d398..bbf5236885 100644 --- a/doc/src/min_style.rst +++ b/doc/src/min_style.rst @@ -3,6 +3,8 @@ min_style cg command ==================== +Accelerator Variant: *cg/kk* + min_style hftn command ====================== 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 8be6639e72..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 @@ -504,7 +504,7 @@ as it is for non-accelerated pair styles The *binsize* keyword sets the size of bins used to bin atoms during neighbor list builds. The same value can be set by the :doc:`neigh_modify binsize ` command. Making it an option -in the package kokkos command allows it to be set from the command line. +in the package kokkos command allows it to be set from the command-line. The default value for CPUs is 0.0, which means the LAMMPS default will be used, which is bins = 1/2 the size of the pairwise cutoff + neighbor skin distance. This is fine when neighbor lists are built on the CPU. For GPU @@ -664,7 +664,7 @@ too. Also note that if the :doc:`-sf hybrid intel omp command-line switch ` is used, it invokes a "package intel" command, followed by a "package omp" command, both with a setting of *Nthreads* = 0. Likewise for a hybrid suffix for gpu and omp. Note that KOKKOS also supports - setting the number of OpenMP threads from the command line using the + setting the number of OpenMP threads from the command-line using the "-k on" :doc:`command-line switch `. The default for KOKKOS is 1 thread per MPI task, so any other number of threads should be explicitly set using the "-k on" command-line switch (and this 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 7dfa9bc12c..19ba4cdbec 100644 --- a/doc/src/pair_bpm_spring.rst +++ b/doc/src/pair_bpm_spring.rst @@ -8,7 +8,14 @@ Syntax .. code-block:: LAMMPS - pair_style bpm/spring + pair_style bpm/spring keyword value ... + +* optional keyword = *anharmonic* + + .. parsed-literal:: + + *anharmonic* value = *yes* or *no* + whether forces include the anharmonic term Examples """""""" @@ -17,7 +24,8 @@ Examples pair_style bpm/spring pair_coeff * * 1.0 1.0 1.0 - pair_coeff 1 1 1.0 1.0 1.0 + pair_style bpm/spring anharmonic yes + pair_coeff 1 1 1.0 1.0 1.0 50.0 Description """"""""""" @@ -28,12 +36,16 @@ Style *bpm/spring* computes pairwise forces with the formula .. math:: - F = k (r - r_c) + F = k (r - r_c) + k_a (r - r_c)^3 -where :math:`k` is a stiffness and :math:`r_c` is the cutoff length. -An additional damping force is also applied to interacting -particles. The force is proportional to the difference in the -normal velocity of particles +where :math:`k` is a stiffness, :math:`r_c` is the cutoff +length, and :math:`k_a` is an optional anharmonic cubic prefactor +that can be enabled using the *anharmonic* keyword. The anharmonic +term may be useful in scenarios that need to prevent large particle overlap. + +An additional damping force is also applied to interacting particles. +The force is proportional to the difference in the normal velocity of +particles .. math:: @@ -73,6 +85,12 @@ commands, or by mixing as described below: * :math:`r_c` (distance units) * :math:`\gamma` (force/velocity units) +.. versionadded:: 4Feb2025 + +Additionally, if *anharmonic* is set to *yes*, a fourth coefficient +must be provided: + +* :math:`k_a` (force/distance\^3 units) ---------- @@ -99,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 @@ -117,4 +139,5 @@ Related commands Default """"""" -none +The option defaults are *anharmonic* = *no* + diff --git a/doc/src/pair_brownian.rst b/doc/src/pair_brownian.rst index 9fec789ba0..a740952a5c 100644 --- a/doc/src/pair_brownian.rst +++ b/doc/src/pair_brownian.rst @@ -1,12 +1,13 @@ .. index:: pair_style brownian .. index:: pair_style brownian/omp +.. index:: pair_style brownian/kk .. index:: pair_style brownian/poly .. index:: pair_style brownian/poly/omp pair_style brownian command =========================== -Accelerator Variants: *brownian/omp* +Accelerator Variants: *brownian/omp*, *brownian/kk* pair_style brownian/poly command ================================ diff --git a/doc/src/pair_coul.rst b/doc/src/pair_coul.rst index e8f09515b0..c673561237 100644 --- a/doc/src/pair_coul.rst +++ b/doc/src/pair_coul.rst @@ -4,6 +4,7 @@ .. index:: pair_style coul/cut/omp .. index:: pair_style coul/cut/global .. index:: pair_style coul/cut/global/omp +.. index:: pair_style coul/ctip .. index:: pair_style coul/debye .. index:: pair_style coul/debye/gpu .. index:: pair_style coul/debye/kk @@ -38,6 +39,9 @@ pair_style coul/cut/global command Accelerator Variants: *coul/cut/omp* +pair_style coul/ctip command +============================ + pair_style coul/debye command ============================= @@ -79,7 +83,6 @@ pair_style tip4p/long command Accelerator Variants: *tip4p/long/omp* - Syntax """""" @@ -87,6 +90,7 @@ Syntax pair_style coul/cut cutoff pair_style coul/cut/global cutoff + pair_style coul/ctip alpha cutoff pair_style coul/debye kappa cutoff pair_style coul/dsf alpha cutoff pair_style coul/exclude cutoff @@ -116,6 +120,9 @@ Examples pair_coeff * * pair_coeff 2 2 3.5 + pair_style coul/ctip 0.30 12.0 + pair_coeff * * NiO.ctip Ni O + pair_style coul/debye 1.4 3.0 pair_coeff * * pair_coeff 2 2 3.5 @@ -173,6 +180,33 @@ coulomb styles in :doc:`hybrid pair styles `. ---------- +.. versionadded:: 19Nov2024 + +Style *coul/ctip* computes the Coulomb interactions as described in +:ref:`Plummer `. It uses the the damped shifted model as in +style *coul/dsf* but is further extended to the second derivative of the +potential and incorporates empirical charge shielding meant to +approximate the more expensive Coulomb integrals used in style +*coul/streitz*. More details can be found in the referenced paper. Like +the style *coul/streitz*, style *coul/ctip* is a variable charge +potential and must be hybridized with a short-range potential via the +:doc:`pair_style hybrid/overlay ` command. Charge +equilibration must be performed with the :doc:`fix qeq/ctip ` +command. For example: + +.. code-block:: LAMMPS + + pair_style hybrid/overlay eam/fs coul/ctip 0.30 12.0 + pair_coeff * * eam/fs NiO.eam.fs Ni O + pair_coeff * * coul/ctip NiO.ctip Ni O + fix 1 all qeq/ctip 1 12.0 1.0e-8 100 coul/ctip cdamp 0.30 maxrepeat 10 + +See the examples/ctip directory for an example input script using the +CTIP potential. An Ni-O CTIP and EAM/FS parameterization are included +for use with the example. + +---------- + Style *coul/debye* adds an additional exp() damping factor to the Coulombic term, given by @@ -207,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 @@ -399,16 +433,18 @@ Restrictions """""""""""" The *coul/long*, *coul/msm*, *coul/streitz*, and *tip4p/long* styles are -part of the KSPACE package. The *coul/cut/global*, *coul/exclude* styles are -part of the EXTRA-PAIR package. The *tip4p/cut* style is part of the MOLECULE -package. A pair style is only enabled if LAMMPS was built with its -corresponding package. See the :doc:`Build package ` -doc page for more info. +part of the KSPACE package. The *coul/cut/global*, *coul/exclude*, and +*coul/ctip* styles are part of the EXTRA-PAIR package. The *tip4p/cut* +style is part of the MOLECULE package. A pair style is only enabled if +LAMMPS was built with its corresponding package. See the +:doc:`Build package ` page for more info. Related commands """""""""""""""" -:doc:`pair_coeff `, :doc:`pair_style, hybrid/overlay `, :doc:`kspace_style ` +:doc:`pair_coeff `, +:doc:`pair_style hybrid/overlay `, +:doc:`kspace_style ` Default """"""" @@ -432,6 +468,11 @@ Phys, 110, 8254 (1999). **(Streitz)** F. H. Streitz, J. W. Mintmire, Phys Rev B, 50, 11996-12003 (1994). +.. _Plummer1: + +**(Plummer)** G. Plummer, J. P. Tavenner, M. I. Mendelev, Z. Wu, J. W. Lawson, +J Chemical Physics, 162, 054709 (2025). + .. _Jorgensen3: **(Jorgensen)** Jorgensen, Chandrasekhar, Madura, Impey, Klein, J Chem diff --git a/doc/src/pair_coul_diel.rst b/doc/src/pair_coul_diel.rst index 77c00c633a..5b5b5f3501 100644 --- a/doc/src/pair_coul_diel.rst +++ b/doc/src/pair_coul_diel.rst @@ -71,6 +71,10 @@ The global cutoff (:math:`r_c`) specified in the pair_style command is used. ---------- +.. include:: accel_styles.rst + +---------- + Mixing, shift, table, tail correction, restart, rRESPA info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" 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_coul_slater.rst b/doc/src/pair_coul_slater.rst index 7abc1f8b07..7af1ec42c6 100644 --- a/doc/src/pair_coul_slater.rst +++ b/doc/src/pair_coul_slater.rst @@ -77,6 +77,10 @@ The global decay length of the charge (:math:`\lambda`) specified in the pair_st ---------- +.. include:: accel_styles.rst + +---------- + Mixing, shift, table, tail correction, restart, rRESPA info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" 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 f061331497..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 @@ -235,12 +382,15 @@ given by: .. math:: - \eta_n = \alpha (m_{eff}k_n)^{1/2} + \eta_n = \alpha (m_{eff}k_{nd})^{1/2} -For normal contact models based on material parameters, :math:`k_n = 4/3Ea`. This -damping model is not compatible with cohesive normal models such as *JKR* or *DMT*. -The parameter :math:`\alpha` is related to the restitution coefficient *e* -according to: +where :math:`k_{nd}` is an effective harmonic stiffness equal to the ratio of +the normal force to the overlap. For example, :math:`k_{nd} = 4/3Ea` for a +Hertz contact model based on material parameters with :math:`a` being +the contact radius of :math:`\sqrt{\delta R}`. For Hooke, :math:`k_{nd}` +is simply the spring constant or :math:`k_{n}`. This damping model is not +compatible with cohesive normal models such as *JKR* or *DMT*. The parameter +:math:`\alpha` is related to the restitution coefficient *e* according to: .. math:: @@ -251,25 +401,26 @@ of the normal contact model parameters should be between 0 and 1, but no error check is performed on this. The *coeff_restitution* model is useful when a specific normal coefficient of -restitution :math:`e` is required. In these models, the normal coefficient of -restitution :math:`e` is specified as an input. Following the approach of -:ref:`(Brilliantov et al) `, when using the *hooke* normal model, -*coeff_restitution* calculates the damping coefficient as: +restitution :math:`e` is required. It operates much like the *Tsuji* model +but, the normal coefficient of restitution :math:`e` is specified as an input +in place of the usual :math:`\eta_{n0}` value in the normal model. Following +the approach of :ref:`(Brilliantov et al) `, when using the *hooke* +normal model, *coeff_restitution* then calculates the damping coefficient as: .. math:: - \eta_n = \sqrt{\frac{4m_{eff}k_n}{1+\left( \frac{\pi}{\log(e)}\right)^2}} , + \eta_n = \sqrt{\frac{4m_{eff}k_{nd}}{1+\left( \frac{\pi}{\log(e)}\right)^2}} , +where :math:`k_{nd}` is the same stiffness defined in the above *Tsuji* model. For any other normal model, e.g. the *hertz* and *hertz/material* models, the damping coefficient is: .. math:: - \eta_n = -2\sqrt{\frac{5}{6}}\frac{\log(e)}{\sqrt{\pi^2+(\log(e))^2}}(R_{eff} \delta_{ij})^{\frac{1}{4}}\sqrt{\frac{3}{2}k_n m_{eff}} , + \eta_n = -2\sqrt{\frac{5}{6}}\frac{\log(e)}{\sqrt{\pi^2+(\log(e))^2}}\sqrt{\frac{3}{2}k_{nd} m_{eff}} , -where :math:`k_n = \frac{4}{3} E_{eff}` for the *hertz/material* model. Since -*coeff_restitution* accounts for the effective mass, effective radius, and -pairwise overlaps (except when used with the *hooke* normal model) when calculating +Since *coeff_restitution* accounts for the effective mass, effective radius, +and pairwise overlaps (except when used with the *hooke* normal model) when calculating the damping coefficient, it accurately reproduces the specified coefficient of restitution for both monodisperse and polydisperse particle pairs. This damping model is not compatible with cohesive normal models such as *JKR* or *DMT*. @@ -342,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: @@ -432,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 @@ -548,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:: @@ -607,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:: @@ -663,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: @@ -670,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 @@ -741,10 +911,6 @@ atom types. ---------- -.. include:: accel_styles.rst - ----------- - Mixing, shift, table, tail correction, restart, rRESPA info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -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 28a398754f..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 @@ -287,6 +287,10 @@ concentration profiles of the two chemical species as ---------- +.. include:: accel_styles.rst + +---------- + Mixing, shift, table, tail correction, restart, rRESPA info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/pair_mgpt.rst b/doc/src/pair_mgpt.rst index 6ef9f52fac..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 ) @@ -111,8 +111,8 @@ routines. For x-86 machines, there is a provided Makefile.mgptfast which enables the fast algebra routines, i.e. build LAMMPS with "make mgptfast". The user will be informed in the output files of the matrix kernels in use. To further improve speed, on x86 the option -precision single can be added to the :doc:`pair_coeff ` -command line, which improves speed (up to a factor of two) at the cost +*precision single* can be added to the :doc:`pair_coeff ` +command, which improves speed (up to a factor of two) at the cost of doing matrix calculations with 7 digit precision instead of the default 16. For consistency the default option can be specified explicitly by the option precision double. diff --git a/doc/src/pair_mie.rst b/doc/src/pair_mie.rst index 6e9eec1f5c..0a0e1d9c32 100644 --- a/doc/src/pair_mie.rst +++ b/doc/src/pair_mie.rst @@ -62,6 +62,10 @@ cutoff specified in the pair_style command is used. ---------- +.. include:: accel_styles.rst + +---------- + Mixing, shift, table, tail correction, restart, rRESPA info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" 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 03d53d1ff4..45532bc2a6 100644 --- a/doc/src/pair_reaxff.rst +++ b/doc/src/pair_reaxff.rst @@ -20,7 +20,7 @@ Syntax .. parsed-literal:: keyword = *checkqeq* or *lgvdw* or *safezone* or *mincap* or *minhbonds* or *tabulate* or *list/blocking* - *checkqeq* value = *yes* or *no* = whether or not to require qeq/reaxff or acks2/reaxff fix + *checkqeq* value = *yes* or *no* = whether or not to require one of fix qeq/reaxff, fix acks2/reaxff or fix qtpie/reaxff *enobonds* value = *yes* or *no* = whether or not to tally energy of atoms with no bonds *lgvdw* value = *yes* or *no* = whether or not to use a low gradient vdW correction *safezone* = factor used for array allocation @@ -120,20 +120,22 @@ up that process. The ReaxFF parameter files provided were created using a charge equilibration (QEq) model for handling the electrostatic interactions. -Therefore, by default, LAMMPS requires that either the -:doc:`fix qeq/reaxff ` or the -:doc:`fix qeq/shielded ` or :doc:`fix acks2/reaxff ` -command be used with -*pair_style reaxff* when simulating a ReaxFF model, to equilibrate -the charges each timestep. +Therefore, by default, LAMMPS requires that +:doc:`fix qeq/reaxff ` or :doc:`fix qeq/shielded ` +or :doc:`fix acks2/reaxff ` +or :doc:`fix qtpie/reaxff ` +is used with *pair_style reaxff* when simulating a ReaxFF model, +to equilibrate the charges at each timestep. +See the :doc:`fix qeq/reaxff ` or :doc:`fix qeq/shielded ` +or :doc:`fix acks2/reaxff ` +or :doc:`fix qtpie/reaxff ` +command documentation for more details. Using the keyword *checkqeq* with the value *no* turns off the check for the QEq fixes, allowing a simulation to be run without charge equilibration. In this case, the static charges you assign to each atom will be used for computing the electrostatic interactions in -the system. See the :doc:`fix qeq/reaxff ` or -:doc:`fix qeq/shielded ` or :doc:`fix acks2/reaxff ` -command documentation for more details. +the system. Using the optional keyword *lgvdw* with the value *yes* turns on the low-gradient correction of ReaxFF for long-range London Dispersion, @@ -156,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 @@ -372,8 +399,8 @@ Related commands """""""""""""""" :doc:`pair_coeff `, :doc:`fix qeq/reaxff `, -:doc:`fix acks2/reaxff `, :doc:`fix reaxff/bonds `, -:doc:`fix reaxff/species `, +:doc:`fix acks2/reaxff `, :doc:`fix qtpie/reaxff `, +:doc:`fix reaxff/bonds `, :doc:`fix reaxff/species `, :doc:`compute reaxff/atom ` Default 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_sph_heatconduction.rst b/doc/src/pair_sph_heatconduction.rst index e9004cb5a4..5510c546d3 100644 --- a/doc/src/pair_sph_heatconduction.rst +++ b/doc/src/pair_sph_heatconduction.rst @@ -30,6 +30,12 @@ The transport model is the diffusion equation for the internal energy. See `this PDF guide `_ to using SPH in LAMMPS. +.. note:: + + Please note that the SPH PDF guide file has not been updated for + many years and thus does not reflect the current *syntax* of the + SPH package commands. For that please refer to the LAMMPS manual. + The following coefficients must be defined for each pair of atoms types via the :doc:`pair_coeff ` command as in the examples above. @@ -39,6 +45,10 @@ above. ---------- +.. include:: accel_styles.rst + +---------- + Mixing, shift, table, tail correction, restart, rRESPA info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/pair_sph_idealgas.rst b/doc/src/pair_sph_idealgas.rst index 02949849c4..3bf357e2d2 100644 --- a/doc/src/pair_sph_idealgas.rst +++ b/doc/src/pair_sph_idealgas.rst @@ -36,6 +36,12 @@ particles from interpenetrating :ref:`(Monaghan) `. See `this PDF guide `_ to using SPH in LAMMPS. +.. note:: + + Please note that the SPH PDF guide file has not been updated for + many years and thus does not reflect the current *syntax* of the + SPH package commands. For that please refer to the LAMMPS manual. + The following coefficients must be defined for each pair of atoms types via the :doc:`pair_coeff ` command as in the examples above. diff --git a/doc/src/pair_sph_lj.rst b/doc/src/pair_sph_lj.rst index 5ac7ab9c6b..53264c609b 100644 --- a/doc/src/pair_sph_lj.rst +++ b/doc/src/pair_sph_lj.rst @@ -34,6 +34,12 @@ interpenetrating :ref:`(Monaghan) `. See `this PDF guide `_ to using SPH in LAMMPS. +.. note:: + + Please note that the SPH PDF guide file has not been updated for + many years and thus does not reflect the current *syntax* of the + SPH package commands. For that please refer to the LAMMPS manual. + The following coefficients must be defined for each pair of atoms types via the :doc:`pair_coeff ` command as in the examples above. @@ -43,6 +49,10 @@ above. ---------- +.. include:: accel_styles.rst + +---------- + Mixing, shift, table, tail correction, restart, rRESPA info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/pair_sph_rhosum.rst b/doc/src/pair_sph_rhosum.rst index ecbff98486..6194bacc09 100644 --- a/doc/src/pair_sph_rhosum.rst +++ b/doc/src/pair_sph_rhosum.rst @@ -29,6 +29,12 @@ SPH particles by kernel function interpolation, every Nstep timesteps. See `this PDF guide `_ to using SPH in LAMMPS. +.. note:: + + Please note that the SPH PDF guide file has not been updated for + many years and thus does not reflect the current *syntax* of the + SPH package commands. For that please refer to the LAMMPS manual. + The following coefficients must be defined for each pair of atoms types via the :doc:`pair_coeff ` command as in the examples above. diff --git a/doc/src/pair_sph_taitwater.rst b/doc/src/pair_sph_taitwater.rst index 79972660c4..bb88361f4b 100644 --- a/doc/src/pair_sph_taitwater.rst +++ b/doc/src/pair_sph_taitwater.rst @@ -41,6 +41,12 @@ prevent particles from interpenetrating :ref:`(Monaghan) `. See `this PDF guide `_ to using SPH in LAMMPS. +.. note:: + + Please note that the SPH PDF guide file has not been updated for + many years and thus does not reflect the current *syntax* of the + SPH package commands. For that please refer to the LAMMPS manual. + The following coefficients must be defined for each pair of atoms types via the :doc:`pair_coeff ` command as in the examples above. @@ -52,6 +58,10 @@ above. ---------- +.. include:: accel_styles.rst + +---------- + Mixing, shift, table, tail correction, restart, rRESPA info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/pair_sph_taitwater_morris.rst b/doc/src/pair_sph_taitwater_morris.rst index cd8346364b..adef2c09c2 100644 --- a/doc/src/pair_sph_taitwater_morris.rst +++ b/doc/src/pair_sph_taitwater_morris.rst @@ -37,6 +37,12 @@ This pair style also computes laminar viscosity :ref:`(Morris) `. See `this PDF guide `_ to using SPH in LAMMPS. +.. note:: + + Please note that the SPH PDF guide file has not been updated for + many years and thus does not reflect the current *syntax* of the + SPH package commands. For that please refer to the LAMMPS manual. + The following coefficients must be defined for each pair of atoms types via the :doc:`pair_coeff ` command as in the examples above. 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 51350c86a4..bdf06d6b66 100644 --- a/doc/src/pair_style.rst +++ b/doc/src/pair_style.rst @@ -151,6 +151,7 @@ accelerated styles exist. * :doc:`comb ` - charge-optimized many-body (COMB) potential * :doc:`comb3 ` - charge-optimized many-body (COMB3) potential * :doc:`cosine/squared ` - Cooke-Kremer-Deserno membrane model potential +* :doc:`coul/ctip ` - Charge Transfer Interatomic (Coulomb) Potential * :doc:`coul/cut ` - cutoff Coulomb potential * :doc:`coul/cut/dielectric ` - * :doc:`coul/cut/global ` - cutoff Coulomb potential @@ -171,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 @@ -205,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/pair_thole.rst b/doc/src/pair_thole.rst index a4e8bbb96e..5b0d5653ff 100644 --- a/doc/src/pair_thole.rst +++ b/doc/src/pair_thole.rst @@ -131,7 +131,7 @@ command. * LJ cutoff (distance units) The last two coefficients are optional and default to the global values from -the *pair_style* command line. +the *pair_style* command. ---------- diff --git a/doc/src/pairs.rst b/doc/src/pairs.rst deleted file mode 100644 index b764c74cc7..0000000000 --- a/doc/src/pairs.rst +++ /dev/null @@ -1,8 +0,0 @@ -Pair Styles -########### - -.. toctree:: - :maxdepth: 1 - :glob: - - pair_* diff --git a/doc/src/read_dump.rst b/doc/src/read_dump.rst index 59d6cca78d..7f0e5bee42 100644 --- a/doc/src/read_dump.rst +++ b/doc/src/read_dump.rst @@ -115,10 +115,11 @@ to tell LAMMPS how many parallel files exist, via its specified The format of the dump file is selected through the *format* keyword. If specified, it must be the last keyword used, since all remaining -arguments are passed on to the dump reader. The *native* format is -for native LAMMPS dump files, written with a :doc:`dump atom ` -or :doc:`dump custom ` command. The *xyz* format is for generic XYZ -formatted dump files. These formats take no additional values. +arguments are passed on to the dump reader. The *native* format is for +native LAMMPS dump files, written with a :doc:`dump atom ` or +:doc:`dump custom ` command. The *xyz* format is for generic XYZ +formatted dump files (see details below). These formats take no +additional values. The *molfile* format supports reading data through using the `VMD `_ molfile plugin interface. This dump reader format is only available, @@ -230,23 +231,39 @@ will then have a label corresponding to the fix-ID rather than "x" or "xs". The *label* keyword can also be used to specify new column labels for fields *id* and *type*\ . -For dump files in *xyz* format, only the *x*, *y*, and *z* fields are -supported. The dump file does not store atom IDs, so these are -assigned consecutively to the atoms as they appear in the dump file, -starting from 1. Thus you should ensure that order of atoms is -consistent from snapshot to snapshot in the XYZ dump file. See -the :doc:`dump_modify sort ` command if the XYZ dump file -was written by LAMMPS. +For dump files in *xyz* format, only the *type*, *x*, *y*, and *z* +fields are supported. There are many variants of the XYZ file format. +LAMMPS will read the number of atoms from the first line of each frame, +ignore the second (title) line, and then read one line for each atom in the format: + +.. parsed-literal:: + +