diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 1a7a35e61f..86418574ce 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -101,7 +101,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..15ddd59768 --- /dev/null +++ b/.github/release_steps.md @@ -0,0 +1,108 @@ +# LAMMPS Release Steps + +The following notes chronicle the current steps for preparing and publishing LAMMPS releases. For +definitions of LAMMPS versions and releases mean, please refer to [the corresponding section in the +LAMMPS manual](https://docs.lammps.org/Manual_version.html). + +## 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, rebase if needed. This is the last pull request merged for the release +and should not contain any other changes. (Exceptions: this document, last minute trivial(!) changes). + +This PR shall not be merged before **all** pending tests have completed and cleared. If needed, a +bugfix pull request should be created and merged to clear all tests. + +### Create release on GitHub + +When all pending pull requests for the release are merged and have cleared testing, the +'next\_release' branch is merged into 'develop'. + +Check out 'develop' locally, pull the latest changes, merge them into 'release', apply a suitable +release tag (for historical reasons the tag starts with "patch_" followed by the date, and finally +push everything back to GitHub. Example: + +``` +git checkout develop +git pull +git checkout release +git pull +git merge --ff-only develop +git tag -s -m "LAMMPS feature release 19 November 2024" patch_19Nov2024 +git push git@github.com:lammps/lammps.git --tags develop release +``` + +Go to https://github.com/lammps/lammps/releases and create a new (draft) release page or check the +existing draft for any necessary changes from pull requests that were merged but are not listed. +Then select the applied tag for the release in the "Choose a tag" dropdown list. Go to the bottom of +the list and select the "Set as pre-release" checkbox. The "Set as the latest release" button is +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. + +### Update download website, prepare pre-compiled packages, update packages to GitHub + +Publishing the release on GitHub will trigger the Temple Jenkins cluster to update +the https://docs.lammps.org/ website with the documentation for the new feature release +and it will create a tarball for download (which contains the translated manual). + +Build a fully static LAMMPS installation using a musl-libc cross-compiler, install into a +lammps-static folder, and create a tarball called lammps-linux-x86_64-19Nov2024.tar.gz (or using a +corresponding date with a future release) from the lammps-static folder and upload it to GitHub +with: + +``` +gh release upload patch_19Nov2024 ~/Downloads/lammps-linux-x86_64-19Nov2024.tar.gz +``` + + +## 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 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 26f23cc33f..ab89018a3d 100644 --- a/.github/workflows/check-vla.yml +++ b/.github/workflows/check-vla.yml @@ -27,9 +27,9 @@ jobs: - name: Install extra packages run: | + sudo apt-get update sudo apt-get install -y ccache \ libeigen3-dev \ - libgsl-dev \ libcurl4-openssl-dev \ mold \ mpi-default-bin \ diff --git a/.github/workflows/compile-msvc.yml b/.github/workflows/compile-msvc.yml index e384f191e5..7560bc0549 100644 --- a/.github/workflows/compile-msvc.yml +++ b/.github/workflows/compile-msvc.yml @@ -1,4 +1,4 @@ -# GitHub action to build LAMMPS on Windows with Visual C++ +# GitHub action to test LAMMPS on Windows with Visual C++ name: "Windows Unit Tests" on: @@ -11,6 +11,10 @@ on: workflow_dispatch: +concurrency: + group: ${{ github.event_name }}-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{github.event_name == 'pull_request'}} + jobs: build: name: Windows Compilation Test diff --git a/.github/workflows/full-regression.yml b/.github/workflows/full-regression.yml new file mode 100644 index 0000000000..a6b5353b9b --- /dev/null +++ b/.github/workflows/full-regression.yml @@ -0,0 +1,109 @@ +# GitHub action to build LAMMPS on Linux and run regression tests +name: "Full Regression Test" + +on: + push: + branches: + - develop + + workflow_dispatch: + +jobs: + build: + name: Build LAMMPS + # restrict to official LAMMPS repository + if: ${{ github.repository == 'lammps/lammps' }} + runs-on: ubuntu-latest + env: + CCACHE_DIR: ${{ github.workspace }}/.ccache + strategy: + max-parallel: 8 + matrix: + idx: [ 0, 1, 2, 3, 4, 5, 6, 7 ] + + 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-full-ccache-${{ github.sha }} + restore-keys: linux-full-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/most.cmake \ + -D CMAKE_CXX_COMPILER_LAUNCHER=ccache \ + -D CMAKE_C_COMPILER_LAUNCHER=ccache \ + -D BUILD_SHARED_LIBS=off \ + -D DOWNLOAD_POTENTIALS=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 Full Regression Tests + shell: bash + run: | + source linuxenv/bin/activate + python3 tools/regression-tests/run_tests.py \ + --lmp-bin=build/lmp \ + --config-file=tools/regression-tests/config_serial.yaml \ + --examples-top-level=examples --analyze --num-workers=8 + + python3 tools/regression-tests/run_tests.py \ + --lmp-bin=build/lmp \ + --config-file=tools/regression-tests/config_serial.yaml \ + --list-input=input-list-${{ matrix.idx }}.txt \ + --output-file=output-${{ matrix.idx }}.xml \ + --progress-file=progress-${{ matrix.idx }}.yaml \ + --log-file=run-${{ matrix.idx }}.log + + tar -cvf full-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: full-regression-test-artifact-${{ matrix.idx }} + path: full-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-full-regresssion-artifact + pattern: full-regression-test-artifact-* + 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/quick-regression.yml b/.github/workflows/quick-regression.yml new file mode 100644 index 0000000000..88794bfa0a --- /dev/null +++ b/.github/workflows/quick-regression.yml @@ -0,0 +1,118 @@ +# GitHub action to build LAMMPS on Linux and run selected regression tests +name: "Quick Regression Test" + +on: + pull_request: + branches: + - develop + + workflow_dispatch: + +concurrency: + group: ${{ github.event_name }}-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{github.event_name == 'pull_request'}} + +jobs: + build: + name: Build LAMMPS + # restrict to official LAMMPS repository + if: ${{ github.repository == 'lammps/lammps' }} + runs-on: ubuntu-latest + env: + CCACHE_DIR: ${{ github.workspace }}/.ccache + strategy: + max-parallel: 4 + matrix: + idx: [ 0, 1, 2, 3 ] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + 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-quick-ccache-${{ github.sha }} + restore-keys: linux-quick-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/most.cmake \ + -D CMAKE_CXX_COMPILER_LAUNCHER=ccache \ + -D CMAKE_C_COMPILER_LAUNCHER=ccache \ + -D BUILD_SHARED_LIBS=off \ + -D DOWNLOAD_POTENTIALS=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 Regression Tests for Modified Styles + shell: bash + run: | + source linuxenv/bin/activate + python3 tools/regression-tests/run_tests.py \ + --lmp-bin=build/lmp \ + --config-file=tools/regression-tests/config_quick.yaml \ + --examples-top-level=examples \ + --quick-reference=tools/regression-tests/reference.yaml \ + --quick --quick-branch=origin/develop --quick-max=100 --num-workers=4 + + if [ -f input-list-${{ matrix.idx }}.txt ] + then \ + python3 tools/regression-tests/run_tests.py \ + --lmp-bin=build/lmp \ + --config-file=tools/regression-tests/config_quick.yaml \ + --list-input=input-list-${{ matrix.idx }}.txt \ + --output-file=output-${{ matrix.idx }}.xml \ + --progress-file=progress-${{ matrix.idx }}.yaml \ + --log-file=run-${{ matrix.idx }}.log + fi + + tar -cvf quick-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: quick-regression-test-artifact-${{ matrix.idx }} + path: quick-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-quick-regresssion-artifact + pattern: quick-regression-test-artifact-* + diff --git a/.github/workflows/style-check.yml b/.github/workflows/style-check.yml new file mode 100644 index 0000000000..7be2c4fc46 --- /dev/null +++ b/.github/workflows/style-check.yml @@ -0,0 +1,37 @@ +# GitHub action to run checks from tools/coding_standard +name: "Check for Programming Style Conformance" + +on: + push: + branches: + - develop + pull_request: + branches: + - develop + + workflow_dispatch: + +concurrency: + group: ${{ github.event_name }}-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{github.event_name == 'pull_request'}} + +jobs: + build: + name: Programming Style Conformance + if: ${{ github.repository == 'lammps/lammps' }} + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Run Tests + working-directory: src + shell: bash + run: | + make check-whitespace + make check-permissions + make check-homepage + make check-errordocs diff --git a/.github/workflows/unittest-linux.yml b/.github/workflows/unittest-linux.yml index 366db25a99..ce98fcea35 100644 --- a/.github/workflows/unittest-linux.yml +++ b/.github/workflows/unittest-linux.yml @@ -11,6 +11,10 @@ on: workflow_dispatch: +concurrency: + group: ${{ github.event_name }}-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{github.event_name == 'pull_request'}} + jobs: build: name: Linux Unit Test @@ -27,9 +31,9 @@ jobs: - name: Install extra packages run: | + sudo apt-get update sudo apt-get install -y ccache \ libeigen3-dev \ - libgsl-dev \ libcurl4-openssl-dev \ mold \ ninja-build \ diff --git a/.github/workflows/unittest-macos.yml b/.github/workflows/unittest-macos.yml index b0bc4b2727..0d478a9d6b 100644 --- a/.github/workflows/unittest-macos.yml +++ b/.github/workflows/unittest-macos.yml @@ -11,6 +11,10 @@ on: workflow_dispatch: +concurrency: + group: ${{ github.event_name }}-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{github.event_name == 'pull_request'}} + jobs: build: name: MacOS Unit Test diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index c68a925324..38431e3bb5 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -118,7 +118,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,7 +141,7 @@ 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) @@ -165,6 +165,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() @@ -497,7 +498,7 @@ if((CMAKE_CXX_COMPILER_ID STREQUAL "Intel") AND (CMAKE_CXX_STANDARD GREATER_EQUA PROPERTIES COMPILE_OPTIONS "-std=c++14") endif() -if(PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_ML-POD OR PKG_ELECTRODE OR BUILD_TOOLS) +if(PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_ML-POD OR PKG_ELECTRODE OR PKG_RHEO OR BUILD_TOOLS) enable_language(C) if (NOT USE_INTERNAL_LINALG) find_package(LAPACK) @@ -572,7 +573,7 @@ else() endif() foreach(PKG_WITH_INCL KSPACE PYTHON ML-IAP VORONOI COLVARS ML-HDNNP MDI MOLFILE NETCDF - PLUMED QMMM ML-QUIP SCAFACOS MACHDYN VTK KIM COMPRESS ML-PACE LEPTON RHEO EXTRA-COMMAND) + PLUMED QMMM ML-QUIP SCAFACOS MACHDYN VTK KIM COMPRESS ML-PACE LEPTON EXTRA-COMMAND) if(PKG_${PKG_WITH_INCL}) include(Packages/${PKG_WITH_INCL}) endif() @@ -587,13 +588,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 +818,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) @@ -1076,12 +1078,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/Documentation.cmake b/cmake/Modules/Documentation.cmake index 400109067f..dfaf7bdb39 100644 --- a/cmake/Modules/Documentation.cmake +++ b/cmake/Modules/Documentation.cmake @@ -4,6 +4,8 @@ option(BUILD_DOC "Build LAMMPS HTML documentation" OFF) if(BUILD_DOC) + option(BUILD_DOC_VENV "Build LAMMPS documentation virtual environment" ON) + mark_as_advanced(BUILD_DOC_VENV) # Current Sphinx versions require at least Python 3.8 # use default (or custom) Python executable, if version is sufficient if(Python_VERSION VERSION_GREATER_EQUAL 3.8) @@ -18,14 +20,6 @@ if(BUILD_DOC) find_package(Doxygen 1.8.10 REQUIRED) file(GLOB DOC_SOURCES CONFIGURE_DEPENDS ${LAMMPS_DOC_DIR}/src/[^.]*.rst) - add_custom_command( - OUTPUT docenv - COMMAND ${VIRTUALENV} docenv - ) - - set(DOCENV_BINARY_DIR ${CMAKE_BINARY_DIR}/docenv/bin) - set(DOCENV_REQUIREMENTS_FILE ${LAMMPS_DOC_DIR}/utils/requirements.txt) - set(SPHINX_CONFIG_DIR ${LAMMPS_DOC_DIR}/utils/sphinx-config) set(SPHINX_CONFIG_FILE_TEMPLATE ${SPHINX_CONFIG_DIR}/conf.py.in) set(SPHINX_STATIC_DIR ${SPHINX_CONFIG_DIR}/_static) @@ -44,14 +38,32 @@ if(BUILD_DOC) # configure paths in conf.py, since relative paths change when file is copied configure_file(${SPHINX_CONFIG_FILE_TEMPLATE} ${DOC_BUILD_CONFIG_FILE}) - add_custom_command( - OUTPUT ${DOC_BUILD_DIR}/requirements.txt - DEPENDS docenv ${DOCENV_REQUIREMENTS_FILE} - COMMAND ${CMAKE_COMMAND} -E copy ${DOCENV_REQUIREMENTS_FILE} ${DOC_BUILD_DIR}/requirements.txt - COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install --upgrade pip - COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install --upgrade ${LAMMPS_DOC_DIR}/utils/converters - COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install -r ${DOC_BUILD_DIR}/requirements.txt --upgrade - ) + if(BUILD_DOC_VENV) + add_custom_command( + OUTPUT docenv + COMMAND ${VIRTUALENV} docenv + ) + + set(DOCENV_BINARY_DIR ${CMAKE_BINARY_DIR}/docenv/bin) + set(DOCENV_REQUIREMENTS_FILE ${LAMMPS_DOC_DIR}/utils/requirements.txt) + + add_custom_command( + OUTPUT ${DOC_BUILD_DIR}/requirements.txt + DEPENDS docenv ${DOCENV_REQUIREMENTS_FILE} + COMMAND ${CMAKE_COMMAND} -E copy ${DOCENV_REQUIREMENTS_FILE} ${DOC_BUILD_DIR}/requirements.txt + COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install --upgrade pip + COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install --upgrade ${LAMMPS_DOC_DIR}/utils/converters + COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install -r ${DOC_BUILD_DIR}/requirements.txt --upgrade + ) + + set(DOCENV_DEPS docenv ${DOC_BUILD_DIR}/requirements.txt) + if(NOT TARGET Sphinx::sphinx-build) + add_executable(Sphinx::sphinx-build IMPORTED GLOBAL) + set_target_properties(Sphinx::sphinx-build PROPERTIES IMPORTED_LOCATION "${DOCENV_BINARY_DIR}/sphinx-build") + endif() + else() + 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") @@ -97,8 +109,9 @@ if(BUILD_DOC) endif() add_custom_command( OUTPUT html - DEPENDS ${DOC_SOURCES} docenv ${DOC_BUILD_DIR}/requirements.txt ${DOXYGEN_XML_DIR}/index.xml ${BUILD_DOC_CONFIG_FILE} - COMMAND ${DOCENV_BINARY_DIR}/sphinx-build ${SPHINX_EXTRA_OPTS} -b html -c ${DOC_BUILD_DIR} -d ${DOC_BUILD_DIR}/doctrees ${LAMMPS_DOC_DIR}/src ${DOC_BUILD_DIR}/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 COMMAND ${CMAKE_COMMAND} -E remove -f ${DOXYGEN_XML_DIR}/run.stamp diff --git a/cmake/Modules/FindSphinx.cmake b/cmake/Modules/FindSphinx.cmake new file mode 100644 index 0000000000..3718ecc543 --- /dev/null +++ b/cmake/Modules/FindSphinx.cmake @@ -0,0 +1,29 @@ +# Find sphinx-build +find_program(Sphinx_EXECUTABLE NAMES sphinx-build + PATH_SUFFIXES bin + DOC "Sphinx documenation build executable") +mark_as_advanced(Sphinx_EXECUTABLE) + +if(Sphinx_EXECUTABLE) + execute_process(COMMAND ${Sphinx_EXECUTABLE} --version + OUTPUT_VARIABLE sphinx_version + OUTPUT_STRIP_TRAILING_WHITESPACE + RESULT_VARIABLE _sphinx_version_result) + + if(_sphinx_version_result) + message(WARNING "Unable to determine sphinx-build verison: ${_sphinx_version_result}") + else() + string(REGEX REPLACE "sphinx-build ([0-9.]+).*" + "\\1" + Sphinx_VERSION + "${sphinx_version}") + endif() + + if(NOT TARGET Sphinx::sphinx-build) + add_executable(Sphinx::sphinx-build IMPORTED GLOBAL) + set_target_properties(Sphinx::sphinx-build PROPERTIES IMPORTED_LOCATION "${Sphinx_EXECUTABLE}") + endif() +endif() + +include(FindPackageHandleStandardArgs) +find_package_handle_standard_args(Sphinx REQUIRED_VARS Sphinx_EXECUTABLE VERSION_VAR Sphinx_VERSION) 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/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/KOKKOS.cmake b/cmake/Modules/Packages/KOKKOS.cmake index bf0a18d324..2fa5a449fb 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) @@ -105,6 +117,7 @@ set(KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/atom_vec_kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/comm_kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/comm_tiled_kokkos.cpp + ${KOKKOS_PKG_SOURCES_DIR}/group_kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/min_kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/min_linesearch_kokkos.cpp ${KOKKOS_PKG_SOURCES_DIR}/neighbor_kokkos.cpp diff --git a/cmake/Modules/Packages/RHEO.cmake b/cmake/Modules/Packages/RHEO.cmake deleted file mode 100644 index 7639acd8bc..0000000000 --- a/cmake/Modules/Packages/RHEO.cmake +++ /dev/null @@ -1,2 +0,0 @@ -find_package(GSL 2.6 REQUIRED) -target_link_libraries(lammps PRIVATE GSL::gsl) 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-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/mingw-cross.cmake b/cmake/presets/mingw-cross.cmake index 100ce13632..413744b078 100644 --- a/cmake/presets/mingw-cross.cmake +++ b/cmake/presets/mingw-cross.cmake @@ -67,6 +67,7 @@ set(WIN_PACKAGES REACTION REAXFF REPLICA + RHEO RIGID SHOCK SMTBQ diff --git a/cmake/presets/most.cmake b/cmake/presets/most.cmake index d01642f94d..05282eebdd 100644 --- a/cmake/presets/most.cmake +++ b/cmake/presets/most.cmake @@ -60,6 +60,7 @@ set(ALL_PACKAGES REACTION REAXFF REPLICA + RHEO RIGID SHOCK SPH 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/cmake/presets/windows.cmake b/cmake/presets/windows.cmake index 403d40efa4..71241c559c 100644 --- a/cmake/presets/windows.cmake +++ b/cmake/presets/windows.cmake @@ -60,6 +60,7 @@ set(WIN_PACKAGES REACTION REAXFF REPLICA + RHEO RIGID SHOCK SMTBQ 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..d26e6020a6 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -83,7 +83,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,7 +116,7 @@ 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) +fasthtml: xmlgen globbed-tocs $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX) @if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi @$(MAKE) $(MFLAGS) -C graphviz all @mkdir -p fasthtml @@ -132,7 +135,7 @@ fasthtml: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX) @rm -rf fasthtml/PDF/.[sg]* @echo "Fast HTML build finished. The HTML pages are in doc/fasthtml." -spelling: xmlgen $(SPHINXCONFIG)/conf.py $(VENV) $(SPHINXCONFIG)/false_positives.txt +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 +146,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 +169,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/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..cb52813a4d 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" "19 November 2024" "2024-11-19" .SH NAME .B LAMMPS -\- Molecular Dynamics Simulator. Version 29 August 2024 +\- Molecular Dynamics Simulator. Version 19 November 2024 .SH SYNOPSIS .B lmp diff --git a/doc/src/Build_basics.rst b/doc/src/Build_basics.rst index e82832cf57..7014762cdc 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. @@ -502,6 +502,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..c8c74c5182 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 @@ -42,9 +42,9 @@ that want to modify or extend LAMMPS. 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 @@ -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 @@ -131,7 +131,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 +141,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 f315569b24..5c6475c7fa 100644 --- a/doc/src/Build_development.rst +++ b/doc/src/Build_development.rst @@ -138,12 +138,27 @@ during development: The status of this automated testing can be viewed on `https://ci.lammps.org `_. -The scripts and inputs for integration, run, and regression testing -are maintained in a -`separate repository `_ -of the LAMMPS project on GitHub. A few tests are also run as GitHub -Actions and their configuration files are in the ``.github/workflows/`` -folder of the LAMMPS git tree. +The scripts and inputs for integration, run, and legacy regression +testing are maintained in a `separate repository +`_ of the LAMMPS project on +GitHub. A few tests are also run as GitHub Actions and their +configuration files are in the ``.github/workflows/`` folder of the +LAMMPS git tree. + +Regression tests can also be performed locally with the :ref:`regression +tester tool `. The tool checks if a given LAMMPS binary run +with selected input examples produces thermo output that is consistent +with the provided log files. The script can be run in one pass over all +available input files, but it can also first create multiple lists of +inputs or folders that can then be run with multiple workers +concurrently to speed things up. Another mode allows to do a quick +check of inputs that contain commands that have changes in the current +checkout branch relative to a git branch. This works similar to the two +pass mode, but will select only shorter runs and no more than 100 inputs +that are chosen randomly. This ensures that this test runs +significantly faster compared to the full test run. These test runs can +also be performed with instrumented LAMMPS binaries (see previous +section). The unit testing facility is integrated into the CMake build process of the LAMMPS source code distribution itself. It can be enabled by @@ -248,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 @@ -405,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 @@ -627,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 ac7edc7678..1f13525f98 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -209,7 +209,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 +232,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 @@ -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:: @@ -2191,7 +2204,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 @@ -2251,28 +2264,38 @@ verified to work in February 2020 with Quantum Espresso versions 6.3 to RHEO package ------------ -To build with this package you must have the `GNU Scientific Library -(GSL) ` installed in locations that -are accessible in your environment. The GSL library should be at least -version 2.7. +This package depends on the BPM package. .. tabs:: .. tab:: CMake build - If CMake cannot find the GSL library or include files, you can set: - .. code-block:: bash - -D GSL_ROOT_DIR=path # path to root of GSL installation + -D PKG_RHEO=yes # enable the package itself + -D PKG_BPM=yes # the RHEO package requires BPM + -D USE_INTERNAL_LINALG=value # prefer internal LAPACK if true + + Some features in the RHEO package are dependent on code in the BPM + package so the latter one *must* be enabled as well. + + The RHEO package also requires LAPACK (and BLAS) and CMake + can identify their locations and pass that info to the RHEO + build script. But on some systems this may cause problems when + linking or the dependency is not desired. By using the setting + ``-D USE_INTERNAL_LINALG=yes`` when running the CMake + configuration, you will select compiling and linking the bundled + linear algebra library and work around the limitations. .. tab:: Traditional make - LAMMPS will try to auto-detect the GSL compiler and linker flags - from the corresponding ``pkg-config`` file (``gsl.pc``), otherwise - you can edit the file ``lib/rheo/Makefile.lammps`` - to specify the paths and library names where indicated by comments. - This must be done **before** the package is installed. + The RHEO package requires LAPACK (and BLAS) which can be either + a system provided library or the bundled "linalg" library. This + is a subset of LAPACK translated to C++. For that, one of the + provided ``Makefile.lammps.`` files needs to be copied + to ``Makefile.lammps`` and edited as needed. The default file + uses the bundled "linalg" library, which can be built by + ``make lib-linalg args='-m serial'`` in the ``src`` folder. ---------- diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst index 2787560be5..e4a53ddee7 100644 --- a/doc/src/Build_settings.rst +++ b/doc/src/Build_settings.rst @@ -229,8 +229,7 @@ can be used with the Intel or GNU compiler (see the ``FFT_LIB`` setting above). The NVIDIA Performance Libraries (NVPL) FFT library is optimized for NVIDIA -Grace Armv9.0 architecture. You can download it from -`https://docs.nvidia.com/nvpl/`_. +Grace Armv9.0 architecture. You can download it from https://docs.nvidia.com/nvpl/ The cuFFT and hipFFT FFT libraries are packaged with NVIDIA's CUDA and AMD's HIP installations, respectively. These FFT libraries require the 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_fix.rst b/doc/src/Commands_fix.rst index d9febcc289..04d1a9969a 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 ` @@ -134,7 +134,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 ` @@ -178,6 +178,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 +187,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 +269,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..5f42f53bd5 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) ` diff --git a/doc/src/Commands_removed.rst b/doc/src/Commands_removed.rst index ea8b3d4b03..777be3bf16 100644 --- a/doc/src/Commands_removed.rst +++ b/doc/src/Commands_removed.rst @@ -18,7 +18,7 @@ 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 ` +:doc:`command-line flags ` Fix ave/spatial and fix ave/spatial/sphere ------------------------------------------ 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_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..86526b19de 100644 --- a/doc/src/Developer_unittest.rst +++ b/doc/src/Developer_unittest.rst @@ -476,7 +476,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 @@ -609,7 +609,7 @@ and run the test with verbose output. For example, 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_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..cc28273aa3 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 diff --git a/doc/src/Errors_details.rst b/doc/src/Errors_details.rst index c798784106..09f3d893db 100644 --- a/doc/src/Errors_details.rst +++ b/doc/src/Errors_details.rst @@ -54,3 +54,26 @@ 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. + +.. _err0003: + +Illegal variable command: expected X arguments but found Y +---------------------------------------------------------- + +This error indicates that there are the wrong number of arguments for a +specific variable command, but a common reason for that is a variable +expression that has whitespace but is not enclosed in single or double +quotes. + +To explain, the LAMMPS input parser reads and processes lines. The +resulting line is broken down into "words". Those are usually +individual commands, labels, names, values separated by whitespace (a +space or tab character). For "words" that may contain whitespace, they +have to be enclosed in single (') or double (") quotes. The parser will +then remove the outermost pair of quotes and then pass that string as +"word" to the variable command. + +Thus missing quotes or accidental extra whitespace will lead to the +error shown in the header because the unquoted whitespace will result +in the text being broken into more "words", i.e. the variable expression +being split. diff --git a/doc/src/Errors_messages.rst b/doc/src/Errors_messages.rst index 2468b3c628..bfc395067a 100644 --- a/doc/src/Errors_messages.rst +++ b/doc/src/Errors_messages.rst @@ -7774,7 +7774,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..683cbd0500 100644 --- a/doc/src/Examples.rst +++ b/doc/src/Examples.rst @@ -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..d50c7bdcf3 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 @@ -448,7 +448,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`. 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..f2aa1fc0a3 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 @@ -42,7 +46,8 @@ Currently, there are two 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. Alternatively, the second 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 +60,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..78a05f113c 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 diff --git a/doc/src/Howto_lammps_gui.rst b/doc/src/Howto_lammps_gui.rst index 21e6a31ccc..08be9fb00c 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. @@ -100,10 +103,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 +121,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 +179,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 +275,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 +419,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 +796,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 +849,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_peri.rst b/doc/src/Howto_peri.rst index 8a2aa4cab6..29eb685c81 100644 --- a/doc/src/Howto_peri.rst +++ b/doc/src/Howto_peri.rst @@ -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_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_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..5108009a73 100644 --- a/doc/src/Install_git.rst +++ b/doc/src/Install_git.rst @@ -60,7 +60,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 78c8506421..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 @@ -56,7 +58,7 @@ lammps.org". General questions about LAMMPS should be posted in the - SNL - jmgoff at sandia.gov - machine learned potentials, QEq solvers, Python - * - Megan McCarthy + * - Meg McCarthy - SNL - megmcca at sandia.gov - alloys, micro-structure, machine learned potentials @@ -67,7 +69,7 @@ lammps.org". General questions about LAMMPS should be posted in the * - `Trung Nguyen `_ - U Chicago - ndactrung at gmail.com - - soft matter, GPU package + - soft matter, GPU package, DIELECTRIC package, regression testing .. _rb: https://rbberger.github.io/ .. _gc: https://enthalpiste.fr/ diff --git a/doc/src/Intro_portability.rst b/doc/src/Intro_portability.rst index 472a2bee88..036529ff9d 100644 --- a/doc/src/Intro_portability.rst +++ b/doc/src/Intro_portability.rst @@ -31,18 +31,19 @@ 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/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/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..894c299299 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 @@ -2171,8 +2171,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 `, @@ -2789,14 +2789,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 +2810,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/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_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_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..9f8dcf8340 100644 --- a/doc/src/Speed_kokkos.rst +++ b/doc/src/Speed_kokkos.rst @@ -77,7 +77,7 @@ 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 @@ -423,7 +423,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 +439,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 +451,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 9f9f63f46a..d13a6d384f 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. @@ -1022,10 +1022,10 @@ regression tests with a given LAMMPS binary. The tool launches the LAMMPS binary with any given input script under one of the `examples` subdirectories, and compares the thermo output in the generated log file with those in the provided log file with the same number of processors -ub the same subdirectory. If the differences between the actual and +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/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..0a43a62159 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 *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,48 @@ 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:: TBD + +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. + +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` (unit less) +* :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 @@ -213,7 +250,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 +261,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/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/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_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_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..e5c99a478f 100644 --- a/doc/src/compute_reduce.rst +++ b/doc/src/compute_reduce.rst @@ -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_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_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/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/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/fix.rst b/doc/src/fix.rst index 4919c226fd..9af607601b 100644 --- a/doc/src/fix.rst +++ b/doc/src/fix.rst @@ -357,6 +357,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 +366,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 03aef12a6c..1ddf80cbdb 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 @@ -319,25 +327,36 @@ all types from 1 to :math:`N`. A leading asterisk means all types from :math:`N` (inclusive). A middle asterisk means all types from m to n (inclusive). -Currently *bond* does not support bond_style hybrid nor bond_style -hybrid/overlay as bond styles. The bond styles that currently work -with fix_adapt are +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/nm ` | k,r0 | type bonds | -+------------------------------------+------------+------------+ -| :doc:`gromos ` | k,r0 | type bonds | -+------------------------------------+------------+------------+ -| :doc:`harmonic ` | 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 | ++-----------------------------------------------------+---------------------------+------------+ ---------- @@ -357,15 +376,40 @@ all types from 1 to :math:`N`. A leading asterisk means all types from :math:`N` (inclusive). A middle asterisk means all types from m to n (inclusive). -Currently *angle* does not support angle_style hybrid nor angle_style -hybrid/overlay as angle styles. The angle styles that currently work -with fix_adapt are +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:`cosine ` | k | 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:`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_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_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_halt.rst b/doc/src/fix_halt.rst index 25331804aa..0bcf2fb5ea 100644 --- a/doc/src/fix_halt.rst +++ b/doc/src/fix_halt.rst @@ -101,7 +101,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: diff --git a/doc/src/fix_imd.rst b/doc/src/fix_imd.rst index 520af505a1..2974262c81 100644 --- a/doc/src/fix_imd.rst +++ b/doc/src/fix_imd.rst @@ -97,7 +97,7 @@ adjustments. 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:: 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_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_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_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_qeq.rst b/doc/src/fix_qeq.rst index f353e9a998..06a1f98375 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, +in preparation + .. _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_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_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/group2ndx.rst b/doc/src/group2ndx.rst index 19c472e109..e1c4fd23f5 100644 --- a/doc/src/group2ndx.rst +++ b/doc/src/group2ndx.rst @@ -51,7 +51,7 @@ index file. When specifying group IDs, only those groups will be written to the index file. In order to follow the Gromacs conventions, the group *all* will be renamed to *System* in the index file. -The *ndx2group* command will create of update group definitions from +The *ndx2group* command will create or update group definitions from those stored in an index file. Without specifying any group IDs, all groups except *System* will be read from the index file and the corresponding groups recreated. If a group of the same name already 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/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_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/package.rst b/doc/src/package.rst index 8be6639e72..ddb3656027 100644 --- a/doc/src/package.rst +++ b/doc/src/package.rst @@ -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_bpm_spring.rst b/doc/src/pair_bpm_spring.rst index 7dfa9bc12c..068efff577 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:: TBD + +Additionally, if *anharmonic* is set to *yes*, a fourth coefficient +must be provided: + +* :math:`k_a` (force/distance\^3 units) ---------- @@ -117,4 +135,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..77c0e0b18b 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 @@ -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, +in preparation + .. _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_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_granular.rst b/doc/src/pair_granular.rst index f061331497..11a460e9ca 100644 --- a/doc/src/pair_granular.rst +++ b/doc/src/pair_granular.rst @@ -235,12 +235,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 +254,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*. @@ -741,10 +745,6 @@ atom types. ---------- -.. include:: accel_styles.rst - ----------- - Mixing, shift, table, tail correction, restart, rRESPA info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" diff --git a/doc/src/pair_mesodpd.rst b/doc/src/pair_mesodpd.rst index 28a398754f..6674b013ba 100644 --- a/doc/src/pair_mesodpd.rst +++ b/doc/src/pair_mesodpd.rst @@ -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..92bf9cd738 100644 --- a/doc/src/pair_mgpt.rst +++ b/doc/src/pair_mgpt.rst @@ -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_reaxff.rst b/doc/src/pair_reaxff.rst index 03d53d1ff4..495572dc0e 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, @@ -372,8 +374,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_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_style.rst b/doc/src/pair_style.rst index 51350c86a4..fc2ed2b9a9 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 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:: + +