diff --git a/.github/release_steps.md b/.github/release_steps.md index 15ddd59768..857acfdb85 100644 --- a/.github/release_steps.md +++ b/.github/release_steps.md @@ -1,42 +1,54 @@ # LAMMPS Release Steps -The following notes chronicle the current steps for preparing and publishing LAMMPS releases. For -definitions of LAMMPS versions and releases mean, please refer to [the corresponding section in the -LAMMPS manual](https://docs.lammps.org/Manual_version.html). +The following notes chronicle the current steps for preparing and +publishing LAMMPS releases. For definitions of LAMMPS versions and +releases, please refer to [the corresponding section in the LAMMPS +manual](https://docs.lammps.org/Manual_version.html). ## LAMMPS Feature Release -A LAMMPS feature release is currently prepared after about 500 to 750 commits to the 'develop' -branch or after a period of four weeks up to two months. This is not a fixed rule, though, since -external circumstances can cause delays in preparing a release, or pull requests that are desired to -be merged for the release are not yet completed. +A LAMMPS feature release is currently prepared after about 500 to 750 +commits to the 'develop' branch or after a period of four weeks up to +two months. This is not a fixed rule, though, since external +circumstances can cause delays in preparing a release, or pull requests +that are desired to be merged for the release are not yet completed. ### Preparing a 'next\_release' branch Create a 'next\_release' branch off 'develop' and make the following changes: -- set the LAMMPS\_VERSION define to the planned release date in src/version.h in the format - "D Mmm YYYY" or "DD Mmm YYYY" +- set the LAMMPS\_VERSION define to the planned release date in + src/version.h in the format "D Mmm YYYY" or "DD Mmm YYYY" - remove the LAMMPS\_UPDATE define in src/version.h - update the release date in doc/lammps.1 -- update all TBD arguments for ..versionadded::, ..versionchanged:: ..deprecated:: to the - planned release date in the format "DMmmYYYY" or "DDMmmYYYY" -- check release notes for merged new features and check if ..versionadded:: or ..versionchanged:: - are missing and need to be added -Submit this pull request, rebase if needed. This is the last pull request merged for the release -and should not contain any other changes. (Exceptions: this document, last minute trivial(!) changes). +- update all TBD arguments for ..versionadded::, ..versionchanged:: + ..deprecated:: to the planned release date in the format "DMmmYYYY" or + "DDMmmYYYY" +- check release notes for merged new features and check if + ..versionadded:: or ..versionchanged:: are missing and need to be + added -This PR shall not be merged before **all** pending tests have completed and cleared. If needed, a -bugfix pull request should be created and merged to clear all tests. +Submit this pull request. This is the last pull request merged for the +release and should not contain any other changes. (Exceptions: this +document, last minute trivial(!) changes). + +This PR shall not be merged before **all** pending tests have completed +and cleared. We currently use a mix of automated tests running on +either Temple's Jenkins cluster or GitHub workflows. Those include time +consuming tests not run on pull requests. If needed, a bug-fix pull +request should be created and merged to clear all tests. ### Create release on GitHub -When all pending pull requests for the release are merged and have cleared testing, the -'next\_release' branch is merged into 'develop'. +When all pending pull requests for the release are merged and have +cleared testing, the 'next\_release' branch is merged into 'develop'. -Check out 'develop' locally, pull the latest changes, merge them into 'release', apply a suitable -release tag (for historical reasons the tag starts with "patch_" followed by the date, and finally -push everything back to GitHub. Example: +Check out or update the 'develop' branch locally, pull the latest +changes, merge them into 'release' with a fast forward(!) merge, and +apply a suitable release tag (for historical reasons the tag starts with +"patch_" followed by the date, and finally push everything back to +GitHub. There should be no commits made to 'release' but only +fast forward merges. Example: ``` git checkout develop @@ -44,62 +56,271 @@ git pull git checkout release git pull git merge --ff-only develop -git tag -s -m "LAMMPS feature release 19 November 2024" patch_19Nov2024 +git tag -s -m "LAMMPS feature release 4 February 2025" patch_4Feb2025 git push git@github.com:lammps/lammps.git --tags develop release ``` -Go to https://github.com/lammps/lammps/releases and create a new (draft) release page or check the -existing draft for any necessary changes from pull requests that were merged but are not listed. -Then select the applied tag for the release in the "Choose a tag" dropdown list. Go to the bottom of -the list and select the "Set as pre-release" checkbox. The "Set as the latest release" button is +Applying this tag will trigger two actions on the Temple Jenkins cluster: +- The online manual at https://docs.lammps.org/ will be updated to the + state of the 'release' branch. Merges to the 'develop' branch will + trigger updating https://docs.lammps.org/latest/ so by reviewing the + version of the manual under the "latest" URL, it is possible to preview + what the updated release documentation will look like. +- A downloadable tar archive of the LAMMPS distribution that includes the + html format documentation and a PDF of the manual will be created and + uploaded to the download server at https://download.lammps.org/tars + Note that the file is added, but the `index.html` file is not updated, + so it is not yet publicly visible. + +Go to https://github.com/lammps/lammps/releases and create a new (draft) +release page with a summary of all the changes included and references +to the pull requests they were merged from or check the existing draft +for any necessary changes from pull requests that were merged but are +not listed. Then select the applied tag for the release in the "Choose +a tag" drop-down list. Go to the bottom of the list and select the "Set +as pre-release" checkbox. The "Set as the latest release" button is reserved for stable releases and updates to them. -If everything is in order, you can click on the "Publish release" button. Otherwise, click on "Save -draft" and finish pending tasks until you can return to edit the release page and publish it. +If everything is in order, you can click on the "Publish release" +button. Otherwise, click on "Save draft" and finish pending tasks until +you can return to edit the release page and publish it. -### Update download website, prepare pre-compiled packages, update packages to GitHub +### Prepare pre-compiled packages, update packages to GitHub -Publishing the release on GitHub will trigger the Temple Jenkins cluster to update -the https://docs.lammps.org/ website with the documentation for the new feature release -and it will create a tarball for download (which contains the translated manual). +A suitable build environment is provided with the +https://download.lammps.org/static/fedora41_musl_mingw.sif container +image. The corresponding container build definition file is maintained +in the tools/singularity folder of the LAMMPS source distribution. -Build a fully static LAMMPS installation using a musl-libc cross-compiler, install into a -lammps-static folder, and create a tarball called lammps-linux-x86_64-19Nov2024.tar.gz (or using a -corresponding date with a future release) from the lammps-static folder and upload it to GitHub +#### Fully portable static Linux x86_64 non-MPI binaries + +The following commands use the Fedora container to build a fully static +LAMMPS installation using a musl-libc cross-compiler, install it into a +`lammps-static` folder, and create a tarball called +`lammps-linux-x86_64-4Feb2025.tar.gz` (or using a corresponding date +with a future release) from the `lammps-static` folder. + +``` sh +rm -rf release-packages +mkdir release-packages +cd release-packages +wget https://download.lammps.org/static/fedora41_musl.sif +apptainer shell fedora41_musl.sif +git clone -b release --depth 10 https://github.com/lammps/lammps.git lammps-release +cmake -S lammps-release/cmake -B build-release -G Ninja -D CMAKE_INSTALL_PREFIX=$PWD/lammps-static -D CMAKE_TOOLCHAIN_FILE=/usr/musl/share/cmake/linux-musl.cmake -C lammps-release/cmake/presets/most.cmake -C lammps-release/cmake/presets/kokkos-openmp.cmake -D DOWNLOAD_POTENTIALS=OFF -D BUILD_MPI=OFF -D BUILD_TESTING=OFF -D CMAKE_BUILD_TYPE=Release -D PKG_ATC=ON -D PKG_AWPMD=ON -D PKG_MANIFOLD=ON -D PKG_MESONT=ON -D PKG_MGPT=ON -D PKG_ML-PACE=ON -D PKG_ML-RANN=ON -D PKG_MOLFILE=ON -D PKG_PTM=ON -D PKG_QTB=ON -D PKG_SMTBQ=ON +cmake --build build-release --target all +cmake --build build-release --target install +/usr/musl/bin/x86_64-linux-musl-strip lammps-static/bin/* +tar -czvvf ../lammps-linux-x86_64-4Feb2025.tar.gz lammps-static +exit # fedora 41 container +cd .. +``` + +The resulting tar archive can be uploaded to the GitHub release page with: + +``` sh +gh release upload patch_4Feb2025 lammps-linux-x86_64-4Feb2025.tar.gz +``` + +#### Linux x86_64 Flatpak bundle with GUI included + +Make sure you have the `flatpak` and `flatpak-builder` packages +installed locally (they require binaries that run with elevated +privileges and thus cannot be used from the container) and build a +LAMMPS and LAMMPS-GUI flatpak bundle in the `release-packages` folder with: -``` -gh release upload patch_19Nov2024 ~/Downloads/lammps-linux-x86_64-19Nov2024.tar.gz +``` sh +cd release-packages +flatpak --user remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo +flatpak-builder --force-clean --verbose --repo=$PWD/flatpak-repo --install-deps-from=flathub --state-dir=$PWD --user --ccache --default-branch=release flatpak-build lammps-release/tools/lammps-gui/org.lammps.lammps-gui.yml +flatpak build-bundle --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo --verbose $PWD/flatpak-repo ../LAMMPS-Linux-x86_64-GUI-4Feb2025.flatpak org.lammps.lammps-gui release +cd .. ``` +The resulting flatpak bundle file can be uploaded to the GitHub release page with: + +``` sh +gh release upload patch_4Feb2025 LAMMPS-Linux-x86_64-GUI-4Feb2025.flatpak +``` + +#### LAMMPS Source tarball + +The container for the static binary can also be used to prepare the source +tarball including the HTML and PDF manual (this is currently done automatically +when the releases is created and the tarball uploaded to https://download.lammps.org/tars/). +The steps are as follows: + +``` sh +cd release-packages +apptainer shell fedora41_musl_mingw.sif +cd lammps-release +rm -f ../release.tar* +git archive --output=../release.tar --prefix=lammps-4Feb2025/ HEAD +cd doc +make clean-all +make html pdf +tar -rf ../../release.tar --transform 's,^,lammps-4Feb2025/doc/,' html Manual.pdf +gzip -9v ../../release.tar +mv ../../release.tar.gz ../../lammps-src-4Feb2025.tar.gz +exit # fedora41 container +cd .. +``` + +The resulting source tarball can be uploaded to the GitHub release page with: + +``` sh +gh release upload patch_4Feb2025 lammps-src-4Feb2025.tar.gz +``` + +#### Build Windows Installer Packages with MinGW Linux-to-Windows Cross-compiler + +The various Windows installer packages can also be built with +apptainer container image. + +``` sh +cd release-packages +apptainer shell fedora41_musl_mingw.sif +git clone --depth 10 https://github.com/lammps/lammps-packages.git lammps-packages +cd lammps-packages/mingw-cross +ln -sf ../../lammps-release lammps +./buildall.sh release >& mk.log & less +F mk.log +``` + +The installer with the GUI included can be uploaded to the GitHub release page with: + +``` sh +ln -sf LAMMPS-64bit-GUI-4Feb2025.exe LAMMPS-Win10-64bit-GUI-4Feb2025.exe +gh release upload patch_4Feb2025 LAMMPS-Win10-64bit-GUI-4Feb2025.exe +``` + +The symbolic link is used to have a consistent naming scheme for the packages +attached to the GitHub release page. + +#### Clean up: + +``` sh +cd .. +rm -r release-packages +``` + +#### Build Multi-arch App-bundle for macOS + +Building app-bundles for macOS is not as easily automated and portable +as some of the other steps. It requires a machine actually running +macOS. In that machine the Xcode compiler package needs to be +installed. This also includes tools for building and manipulating disk +images. This compiler supports building executables for both, the +x86_64 and the arm64 architectures. This requires building with CMake +and using the CMake settings: + +``` sh +-D CMAKE_OSX_ARCHITECTURES=arm64;x86_64 +-D CMAKE_OSX_DEPLOYMENT_TARGER=11.0 +``` + +This will add the compiler flags `-arch arm64 -arch x86_64 +-mmacosx-version-min=11.0` and thus produce object for both +architectures and support for macOS versions back to version 11 (aka Big +Sur). With these settings the following libraries should be compiled +and installed (e.g. to `$HOME/.local`) as static libraries only: +- libomp taken from the LLVM/Clang source distribution (to support OpenMP) +- jpeg +- zlib +- png +- Qt (for LAMMPS-GUI) + +When configuring LAMMPS the `cmake/presets/clang.cmake` should be used +and as many packages as possible enabled. For LAMMPS-GUI, MPI should be +disabled with `-D BUILD_MPI=OFF` and LAMMPS-GUI enabled with +`-D BUILD_LAMMPS_GUI=ON`. If the CMake configuration is successful, +settings for building a macOS app-bundle are enabled and with `cmake +--build build --target dmg` extra steps will be executed that will build +a macOS application installer image under the name +`LAMMPS_GUI-macOS-multiarch-4Feb2025.dmg` + +The application image can be uploaded to the GitHub release page with: + +``` sh +ln -sf LAMMPS_GUI-macOS-multiarch-4Feb2025.dmg LAMMPS-macOS-multiarch-GUI-4Feb2025.dmg +gh release upload patch_4Feb2025 LAMMPS-macOS-multiarch-GUI-4Feb2025.dmg +``` + +The symbolic link is used to have a consistent naming scheme for the packages +attached to the GitHub release page. + +We are currently building the application images on macOS 12 (aka Monterey). + +#### Build Linux x86_64 binary tarball on Ubuntu 20.04LTS + +While the flatpak Linux version uses portable runtime libraries provided +by the flatpak environment, we also build regular Linux executables that +use a wrapper script and matching shared libraries in a tarball. To be +compatible with many Linux distributions, one has to build this on a +very old Linux distribution, since most Linux system libraries are +usually backward compatible but not forward compatible. This is +currently done on an Ubuntu 20.04LTS system. Once LAMMPS moves to +require CMake 3.20 and C++17, we will have to move to Ubuntu 22.04LTS. +This installation (either on a real or a virtual machine) should have +the packages installed that are indicated in +`tools/singularity/ubuntu20.04.def` plus Qt version 5.x with development +headers, so that LAMMPS-GUI can be compiled. + +Also the building of the binary tarball and setup of the bundled +libraries and wrapper scripts is automated and can executed with `cmake +--build build --target tgz`. This should produce a file +`LAMMPS_GUI-Linux-amd64-4Feb2025.tar.gz` which can be uploaded to the +GitHub release page with: + +``` sh +ln -sf LAMMPS_GUI-Linux-amd64-4Feb2025.tar.gz LAMMPS-Linux-x86_64-GUI-4Feb2025.tar.gz +gh release upload patch_4Feb2025 LAMMPS-Linux-x86_64-GUI-4Feb2025.tar.gz +``` + +### Update download page on LAMMPS website + +Check out the LAMMPS website repo +https://github.com/lammps/lammps-website.git and edit the file +`src/download.txt` for the new release. Test translation with `make +html` and review `html/download.html` Then add and commit to git and +push the changes to GitHub. The Temple Jenkis cluster will +automatically update https://www.lammps.org/download.html accordingly. + +Also notify Steve of the release so he can update `src/bug.txt` on the +website from the available release notes. ## LAMMPS Stable Release -A LAMMPS stable release is prepared about once per year in the months July, August, or September. -One (or two, if needed) feature releases before the stable release shall contain only bug fixes -or minor feature updates in optional packages. Also substantial changes to the core of the code -shall be applied rather toward the beginning of a development cycle between two stable releases -than toward the end. The intention is to stablilize significant change to the core and have -outside users and developers try them out during the development cycle; the sooner the changes -are included, the better chances for spotting peripheral bugs and issues. +A LAMMPS stable release is prepared about once per year in the months +July, August, or September. One (or two, if needed) feature releases +before the stable release shall contain only bug fixes or minor feature +updates in optional packages. Also substantial changes to the core of +the code shall be applied rather toward the beginning of a development +cycle between two stable releases than toward the end. The intention is +to stablilize significant change to the core and have outside users and +developers try them out during the development cycle; the sooner the +changes are included, the better chances for spotting peripheral bugs +and issues. ### Prerequesites -Before making a stable release all remaining backported bugfixes shall be released as a (final) -stable update release (see below). +Before making a stable release all remaining backported bugfixes shall +be released as a (final) stable update release (see below). -A LAMMPS stable release process starts like a feature release (see above), only that this feature -release is called a "Stable Release Candidate" and no assets are uploaded to GitHub. +A LAMMPS stable release process starts like a feature release (see +above), only that this feature release is called a "Stable Release +Candidate" and no assets are uploaded to GitHub. ### Synchronize 'maintenance' branch with 'release' -The state of the 'release' branch is then transferred to the 'maintenance' branch (which will -have diverged significantly from 'release' due to the selectively backported bug fixes). +The state of the 'release' branch is then transferred to the +'maintenance' branch (which will have diverged significantly from +'release' due to the selectively backported bug fixes). ### Fast-forward merge of 'maintenance' into 'stable' and apply tag -At this point it should be possible to do a fast-forward merge of 'maintenance' to 'stable' -and then apply the stable\_DMmmYYYY tag. +At this point it should be possible to do a fast-forward merge of +'maintenance' to 'stable' and then apply the stable\_DMmmYYYY tag. ### Push branches and tags diff --git a/.github/workflows/check-vla.yml b/.github/workflows/check-vla.yml index ab89018a3d..94e367be33 100644 --- a/.github/workflows/check-vla.yml +++ b/.github/workflows/check-vla.yml @@ -77,7 +77,7 @@ jobs: -D PKG_MDI=on \ -D PKG_MANIFOLD=on \ -D PKG_ML-PACE=on \ - -D PKG_ML-RANN=off \ + -D PKG_ML-RANN=on \ -D PKG_MOLFILE=on \ -D PKG_RHEO=on \ -D PKG_PTM=on \ diff --git a/README b/README index c25506e2c0..6477eb41d3 100644 --- a/README +++ b/README @@ -23,17 +23,20 @@ more information about the code and its uses. The LAMMPS distribution includes the following files and directories: README this file -LICENSE the GNU General Public License (GPL) -bench benchmark problems +LICENSE the GNU General Public License (GPLv2) +CITATION.cff Citation information for LAMMPS in CFF format +bench benchmark inputs cmake CMake build files doc documentation -examples simple test problems -fortran Fortran wrapper for LAMMPS +examples example inputs for many LAMMPS commands +fortran Fortran 2003 module for LAMMPS lib additional provided or external libraries potentials interatomic potential files -python Python wrappers for LAMMPS +python Python module for LAMMPS src source files tools pre- and post-processing tools +unittest test programs for use with CTest +.github Git and GitHub related files and tools Point your browser at any of these files to get started: @@ -42,6 +45,8 @@ https://docs.lammps.org/Intro.html hi-level introduction https://docs.lammps.org/Build.html how to build LAMMPS https://docs.lammps.org/Run_head.html how to run LAMMPS https://docs.lammps.org/Commands_all.html Table of available commands +https://docs.lammps.org/Howto.html Short tutorials and HowTo discussions +https://docs.lammps.org/Errors.html How to interpret and debug errors https://docs.lammps.org/Library.html LAMMPS library interfaces https://docs.lammps.org/Modify.html how to modify and extend LAMMPS https://docs.lammps.org/Developer.html LAMMPS developer info diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index ff0d69e316..c1a0875c15 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -209,7 +209,7 @@ endif() ######################################################################## # User input options # ######################################################################## -# backward compatibility with CMake before 3.12 and older LAMMPS documentation +# backward compatibility with older LAMMPS documentation if (PYTHON_EXECUTABLE) set(Python_EXECUTABLE "${PYTHON_EXECUTABLE}") endif() @@ -225,6 +225,12 @@ if(DEFINED ENV{VIRTUAL_ENV} AND NOT Python_EXECUTABLE) " Setting Python interpreter to: ${Python_EXECUTABLE}") endif() +find_package(Python COMPONENTS Interpreter QUIET) +# NOTE: RHEL 8.0 and Ubuntu 18.04LTS ship with Python 3.6, Python 3.8 was EOL in 2024 +if(Python_VERSION VERSION_LESS 3.6) + message(FATAL_ERROR "LAMMPS requires Python 3.6 or later") +endif() + set(LAMMPS_MACHINE "" CACHE STRING "Suffix to append to lmp binary (WON'T enable any features automatically") mark_as_advanced(LAMMPS_MACHINE) if(LAMMPS_MACHINE) @@ -930,7 +936,7 @@ endif() include(Testing) include(CodeCoverage) include(CodingStandard) -find_package(ClangFormat 11.0) +find_package(ClangFormat 11.0 QUIET) if(ClangFormat_FOUND) add_custom_target(format-src diff --git a/cmake/Modules/CodeCoverage.cmake b/cmake/Modules/CodeCoverage.cmake index 21a651e519..885b5cba6d 100644 --- a/cmake/Modules/CodeCoverage.cmake +++ b/cmake/Modules/CodeCoverage.cmake @@ -7,76 +7,76 @@ # For Python coverage the coverage package needs to be installed ############################################################################### if(ENABLE_COVERAGE) - find_program(GCOVR_BINARY gcovr) - find_package_handle_standard_args(GCOVR DEFAULT_MSG GCOVR_BINARY) + find_program(GCOVR_BINARY gcovr) + find_package_handle_standard_args(GCOVR DEFAULT_MSG GCOVR_BINARY) - find_program(COVERAGE_BINARY coverage) - find_package_handle_standard_args(COVERAGE DEFAULT_MSG COVERAGE_BINARY) + find_program(COVERAGE_BINARY coverage) + find_package_handle_standard_args(COVERAGE DEFAULT_MSG COVERAGE_BINARY) - if(GCOVR_FOUND) - get_filename_component(ABSOLUTE_LAMMPS_SOURCE_DIR ${LAMMPS_SOURCE_DIR} ABSOLUTE) + if(GCOVR_FOUND) + get_filename_component(ABSOLUTE_LAMMPS_SOURCE_DIR ${LAMMPS_SOURCE_DIR} ABSOLUTE) - add_custom_target( - gen_coverage_xml - COMMAND ${GCOVR_BINARY} -s -x -r ${ABSOLUTE_LAMMPS_SOURCE_DIR} --object-directory=${CMAKE_BINARY_DIR} -o coverage.xml - WORKING_DIRECTORY ${CMAKE_BINARY_DIR} - COMMENT "Generating XML coverage report..." - ) + add_custom_target( + gen_coverage_xml + COMMAND ${GCOVR_BINARY} -s -x -r ${ABSOLUTE_LAMMPS_SOURCE_DIR} --object-directory=${CMAKE_BINARY_DIR} -o coverage.xml + WORKING_DIRECTORY ${CMAKE_BINARY_DIR} + COMMENT "Generating XML coverage report..." + ) - set(COVERAGE_HTML_DIR ${CMAKE_BINARY_DIR}/coverage_html) + set(COVERAGE_HTML_DIR ${CMAKE_BINARY_DIR}/coverage_html) - add_custom_target(coverage_html_folder - COMMAND ${CMAKE_COMMAND} -E make_directory ${COVERAGE_HTML_DIR}) + add_custom_target(coverage_html_folder + COMMAND ${CMAKE_COMMAND} -E make_directory ${COVERAGE_HTML_DIR}) - add_custom_target( - gen_coverage_html - COMMAND ${GCOVR_BINARY} -s --html --html-details -r ${ABSOLUTE_LAMMPS_SOURCE_DIR} --object-directory=${CMAKE_BINARY_DIR} -o ${COVERAGE_HTML_DIR}/index.html - WORKING_DIRECTORY ${CMAKE_BINARY_DIR} - COMMENT "Generating HTML coverage report..." - ) - add_dependencies(gen_coverage_html coverage_html_folder) + add_custom_target( + gen_coverage_html + COMMAND ${GCOVR_BINARY} -s --html --html-details -r ${ABSOLUTE_LAMMPS_SOURCE_DIR} --object-directory=${CMAKE_BINARY_DIR} -o ${COVERAGE_HTML_DIR}/index.html + WORKING_DIRECTORY ${CMAKE_BINARY_DIR} + COMMENT "Generating HTML coverage report..." + ) + add_dependencies(gen_coverage_html coverage_html_folder) - add_custom_target(clean_coverage_html - ${CMAKE_COMMAND} -E remove_directory ${COVERAGE_HTML_DIR} - COMMENT "Deleting HTML coverage report..." - ) + add_custom_target(clean_coverage_html + ${CMAKE_COMMAND} -E remove_directory ${COVERAGE_HTML_DIR} + COMMENT "Deleting HTML coverage report..." + ) - add_custom_target(reset_coverage - ${CMAKE_COMMAND} -E remove -f */*.gcda */*/*.gcda */*/*/*.gcda - */*/*/*/*.gcda */*/*/*/*/*.gcda */*/*/*/*/*/*.gcda - */*/*/*/*/*/*/*.gcda */*/*/*/*/*/*/*/*.gcda - */*/*/*/*/*/*/*/*/*.gcda */*/*/*/*/*/*/*/*/*/*.gcda - WORKIND_DIRECTORY ${CMAKE_BINARY_DIR} - COMMENT "Deleting coverage data files..." - ) - add_dependencies(reset_coverage clean_coverage_html) - endif() + add_custom_target(reset_coverage + ${CMAKE_COMMAND} -E remove -f */*.gcda */*/*.gcda */*/*/*.gcda + */*/*/*/*.gcda */*/*/*/*/*.gcda */*/*/*/*/*/*.gcda + */*/*/*/*/*/*/*.gcda */*/*/*/*/*/*/*/*.gcda + */*/*/*/*/*/*/*/*/*.gcda */*/*/*/*/*/*/*/*/*/*.gcda + WORKIND_DIRECTORY ${CMAKE_BINARY_DIR} + COMMENT "Deleting coverage data files..." + ) + add_dependencies(reset_coverage clean_coverage_html) + endif() - if(COVERAGE_FOUND) - set(PYTHON_COVERAGE_HTML_DIR ${CMAKE_BINARY_DIR}/python_coverage_html) - configure_file(.coveragerc.in ${CMAKE_BINARY_DIR}/.coveragerc @ONLY) + if(COVERAGE_FOUND) + set(PYTHON_COVERAGE_HTML_DIR ${CMAKE_BINARY_DIR}/python_coverage_html) + configure_file(.coveragerc.in ${CMAKE_BINARY_DIR}/.coveragerc @ONLY) - add_custom_command( - OUTPUT ${CMAKE_BINARY_DIR}/unittest/python/.coverage - COMMAND ${COVERAGE_BINARY} combine - WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python - COMMENT "Combine Python coverage files..." - ) + add_custom_command( + OUTPUT ${CMAKE_BINARY_DIR}/unittest/python/.coverage + COMMAND ${COVERAGE_BINARY} combine + WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python + COMMENT "Combine Python coverage files..." + ) - add_custom_target( - gen_python_coverage_html - COMMAND ${COVERAGE_BINARY} html --rcfile=${CMAKE_BINARY_DIR}/.coveragerc -d ${PYTHON_COVERAGE_HTML_DIR} - DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage ${CMAKE_BINARY_DIR}/.coveragerc - WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python - COMMENT "Generating HTML Python coverage report..." - ) + add_custom_target( + gen_python_coverage_html + COMMAND ${COVERAGE_BINARY} html --rcfile=${CMAKE_BINARY_DIR}/.coveragerc -d ${PYTHON_COVERAGE_HTML_DIR} + DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage ${CMAKE_BINARY_DIR}/.coveragerc + WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python + COMMENT "Generating HTML Python coverage report..." + ) - add_custom_target( - gen_python_coverage_xml - COMMAND ${COVERAGE_BINARY} xml --rcfile=${CMAKE_BINARY_DIR}/.coveragerc -o ${CMAKE_BINARY_DIR}/python_coverage.xml - DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage ${CMAKE_BINARY_DIR}/.coveragerc - WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python - COMMENT "Generating XML Python coverage report..." - ) - endif() + add_custom_target( + gen_python_coverage_xml + COMMAND ${COVERAGE_BINARY} xml --rcfile=${CMAKE_BINARY_DIR}/.coveragerc -o ${CMAKE_BINARY_DIR}/python_coverage.xml + DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage ${CMAKE_BINARY_DIR}/.coveragerc + WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python + COMMENT "Generating XML Python coverage report..." + ) + endif() endif() diff --git a/cmake/Modules/CodingStandard.cmake b/cmake/Modules/CodingStandard.cmake index 94639c7771..4e99c2e39c 100644 --- a/cmake/Modules/CodingStandard.cmake +++ b/cmake/Modules/CodingStandard.cmake @@ -1,40 +1,39 @@ -# use default (or custom) Python executable, if version is sufficient -if(Python_VERSION VERSION_GREATER_EQUAL 3.6) +# use default (or custom) Python executable. +# Python version check is in main CMakeLists.txt file +if(Python_EXECUTABLE) set(Python3_EXECUTABLE ${Python_EXECUTABLE}) endif() find_package(Python3 COMPONENTS Interpreter) if(Python3_EXECUTABLE) - if(Python3_VERSION VERSION_GREATER_EQUAL 3.6) - add_custom_target( - check-whitespace - ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/whitespace.py . - WORKING_DIRECTORY ${LAMMPS_DIR} - COMMENT "Check for whitespace errors") - add_custom_target( - check-homepage - ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/homepage.py . - WORKING_DIRECTORY ${LAMMPS_DIR} - COMMENT "Check for homepage URL errors") - add_custom_target( - check-permissions - ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/permissions.py . - WORKING_DIRECTORY ${LAMMPS_DIR} - COMMENT "Check for permission errors") - add_custom_target( - fix-whitespace - ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/whitespace.py -f . - WORKING_DIRECTORY ${LAMMPS_DIR} - COMMENT "Fix whitespace errors") - add_custom_target( - fix-homepage - ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/homepage.py -f . - WORKING_DIRECTORY ${LAMMPS_DIR} - COMMENT "Fix homepage URL errors") - add_custom_target( - fix-permissions - ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/permissions.py -f . - WORKING_DIRECTORY ${LAMMPS_DIR} - COMMENT "Fix permission errors") - endif() + add_custom_target( + check-whitespace + ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/whitespace.py . + WORKING_DIRECTORY ${LAMMPS_DIR} + COMMENT "Check for whitespace errors") + add_custom_target( + check-homepage + ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/homepage.py . + WORKING_DIRECTORY ${LAMMPS_DIR} + COMMENT "Check for homepage URL errors") + add_custom_target( + check-permissions + ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/permissions.py . + WORKING_DIRECTORY ${LAMMPS_DIR} + COMMENT "Check for permission errors") + add_custom_target( + fix-whitespace + ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/whitespace.py -f . + WORKING_DIRECTORY ${LAMMPS_DIR} + COMMENT "Fix whitespace errors") + add_custom_target( + fix-homepage + ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/homepage.py -f . + WORKING_DIRECTORY ${LAMMPS_DIR} + COMMENT "Fix homepage URL errors") + add_custom_target( + fix-permissions + ${Python3_EXECUTABLE} ${LAMMPS_TOOLS_DIR}/coding_standard/permissions.py -f . + WORKING_DIRECTORY ${LAMMPS_DIR} + COMMENT "Fix permission errors") endif() diff --git a/cmake/Modules/Documentation.cmake b/cmake/Modules/Documentation.cmake index dfaf7bdb39..511d54114c 100644 --- a/cmake/Modules/Documentation.cmake +++ b/cmake/Modules/Documentation.cmake @@ -13,7 +13,7 @@ if(BUILD_DOC) endif() find_package(Python3 REQUIRED COMPONENTS Interpreter) if(Python3_VERSION VERSION_LESS 3.8) - message(FATAL_ERROR "Python 3.8 and up is required to build the HTML documentation") + message(FATAL_ERROR "Python 3.8 and up is required to build the LAMMPS HTML documentation") endif() set(VIRTUALENV ${Python3_EXECUTABLE} -m venv) @@ -65,8 +65,8 @@ if(BUILD_DOC) find_package(Sphinx) endif() - set(MATHJAX_URL "https://github.com/mathjax/MathJax/archive/3.1.3.tar.gz" CACHE STRING "URL for MathJax tarball") - set(MATHJAX_MD5 "b81661c6e6ba06278e6ae37b30b0c492" CACHE STRING "MD5 checksum of MathJax tarball") + set(MATHJAX_URL "https://github.com/mathjax/MathJax/archive/3.2.2.tar.gz" CACHE STRING "URL for MathJax tarball") + set(MATHJAX_MD5 "08dd6ef33ca08870220d9aade2a62845" CACHE STRING "MD5 checksum of MathJax tarball") mark_as_advanced(MATHJAX_URL) GetFallbackURL(MATHJAX_URL MATHJAX_FALLBACK) diff --git a/cmake/Modules/LAMMPSInterfacePlugin.cmake b/cmake/Modules/LAMMPSInterfacePlugin.cmake index 151e0a04f7..fcaf604778 100644 --- a/cmake/Modules/LAMMPSInterfacePlugin.cmake +++ b/cmake/Modules/LAMMPSInterfacePlugin.cmake @@ -34,8 +34,26 @@ if(MSVC) add_compile_definitions(_CRT_SECURE_NO_WARNINGS) endif() -# C++11 is required -set(CMAKE_CXX_STANDARD 11) +if(NOT CMAKE_CXX_STANDARD) + if(cxx_std_17 IN_LIST CMAKE_CXX_COMPILE_FEATURES) + set(CMAKE_CXX_STANDARD 17) + else() + set(CMAKE_CXX_STANDARD 11) + endif() +endif() +if(CMAKE_CXX_STANDARD LESS 11) + message(FATAL_ERROR "C++ standard must be set to at least 11") +endif() +if(CMAKE_CXX_STANDARD LESS 17) + message(WARNING "Selecting C++17 standard is preferred over C++${CMAKE_CXX_STANDARD}") +endif() +if(PKG_KOKKOS AND (CMAKE_CXX_STANDARD LESS 17)) + set(CMAKE_CXX_STANDARD 17) +endif() +# turn off C++17 check in lmptype.h +if(LAMMPS_CXX11) + add_compile_definitions(LAMMPS_CXX11) +endif() set(CMAKE_CXX_STANDARD_REQUIRED ON) # Need -restrict with Intel compilers diff --git a/cmake/Modules/Packages/ML-IAP.cmake b/cmake/Modules/Packages/ML-IAP.cmake index 91b772efb5..1691af8d95 100644 --- a/cmake/Modules/Packages/ML-IAP.cmake +++ b/cmake/Modules/Packages/ML-IAP.cmake @@ -24,9 +24,7 @@ if(MLIAP_ENABLE_PYTHON) if(NOT PKG_PYTHON) message(FATAL_ERROR "Must enable PYTHON package for including Python support in ML-IAP") endif() - if(Python_VERSION VERSION_LESS 3.6) - message(FATAL_ERROR "Python support in ML-IAP requires Python 3.6 or later") - endif() + # Python version check is in main CMakeLists.txt file set(MLIAP_BINARY_DIR ${CMAKE_BINARY_DIR}/cython) file(GLOB MLIAP_CYTHON_SRC CONFIGURE_DEPENDS ${LAMMPS_SOURCE_DIR}/ML-IAP/*.pyx) diff --git a/cmake/Modules/Packages/ML-QUIP.cmake b/cmake/Modules/Packages/ML-QUIP.cmake index 9106ff54ef..aad6ee5e34 100644 --- a/cmake/Modules/Packages/ML-QUIP.cmake +++ b/cmake/Modules/Packages/ML-QUIP.cmake @@ -37,7 +37,7 @@ if(DOWNLOAD_QUIP) endforeach() # Fix cmake crashing when MATH_LINKOPTS not set, required for e.g. recent Cray Programming Environment set(temp "${temp} -L/_DUMMY_PATH_\n") - set(temp "${temp}PYTHON=python\nPIP=pip\nEXTRA_LINKOPTS=\n") + set(temp "${temp}PYTHON=${Python_EXECUTABLE}\nPIP=pip\nEXTRA_LINKOPTS=\n") set(temp "${temp}HAVE_CP2K=0\nHAVE_VASP=0\nHAVE_TB=0\nHAVE_PRECON=1\nHAVE_LOTF=0\nHAVE_ONIOM=0\n") set(temp "${temp}HAVE_LOCAL_E_MIX=0\nHAVE_QC=0\nHAVE_GAP=1\nHAVE_DESCRIPTORS_NONCOMMERCIAL=1\n") set(temp "${temp}HAVE_TURBOGAP=0\nHAVE_QR=1\nHAVE_THIRDPARTY=0\nHAVE_FX=0\nHAVE_SCME=0\nHAVE_MTP=0\n") diff --git a/cmake/Modules/Packages/PLUMED.cmake b/cmake/Modules/Packages/PLUMED.cmake index 5e5d110626..1b4845d259 100644 --- a/cmake/Modules/Packages/PLUMED.cmake +++ b/cmake/Modules/Packages/PLUMED.cmake @@ -40,6 +40,13 @@ mark_as_advanced(PLUMED_URL) mark_as_advanced(PLUMED_MD5) GetFallbackURL(PLUMED_URL PLUMED_FALLBACK) +# adjust C++ standard support for self-compiled Plumed2 +if(CMAKE_CXX_STANDARD GREATER 11) + set(PLUMED_CXX_STANDARD 14) +else() + set(PLUMED_CXX_STANDARD 11) +endif() + if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND (CMAKE_CROSSCOMPILING)) if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64") set(CROSS_CONFIGURE mingw64-configure) @@ -55,7 +62,7 @@ if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND (CMAKE_CROSSCOMPILING)) URL_MD5 ${PLUMED_MD5} BUILD_IN_SOURCE 1 CONFIGURE_COMMAND ${CROSS_CONFIGURE} --disable-shared --disable-bsymbolic - --disable-python --enable-cxx=11 + --disable-python --enable-cxx=${PLUMED_CXX_STANDARD} --enable-modules=-adjmat:+crystallization:-dimred:+drr:+eds:-fisst:+funnel:+logmfd:+manyrestraints:+maze:+opes:+multicolvar:-pamm:-piv:+s2cm:-sasa:-ves ${PLUMED_CONFIG_OMP} ${PLUMED_CONFIG_MPI} @@ -142,7 +149,7 @@ else() CONFIGURE_COMMAND /configure --prefix= ${CONFIGURE_REQUEST_PIC} --enable-modules=all - --enable-cxx=11 + --enable-cxx=${PLUMED_CXX_STANDARD} --disable-python ${PLUMED_CONFIG_MPI} ${PLUMED_CONFIG_OMP} diff --git a/cmake/Modules/Packages/PYTHON.cmake b/cmake/Modules/Packages/PYTHON.cmake index e05edadbf3..0879382ed7 100644 --- a/cmake/Modules/Packages/PYTHON.cmake +++ b/cmake/Modules/Packages/PYTHON.cmake @@ -1,6 +1,6 @@ if(NOT Python_INTERPRETER) - # backward compatibility with CMake before 3.12 and older LAMMPS documentation + # backward compatibility with older LAMMPS documentation if(PYTHON_EXECUTABLE) set(Python_EXECUTABLE ${PYTHON_EXECUTABLE}) endif() diff --git a/doc/README b/doc/README index de956a96bb..f96e0b14da 100644 --- a/doc/README +++ b/doc/README @@ -22,12 +22,12 @@ doxygen-warn.log logfile with warnings from running doxygen and: github-development-workflow.md notes on the LAMMPS development workflow -include-file-conventions.md notes on LAMMPS' include file conventions documentation_conventions.md notes on writing documentation for LAMMPS If you downloaded a LAMMPS tarball from www.lammps.org, then the html folder and the PDF manual should be included. If you downloaded LAMMPS -from GitHub then you either need to build them. +using GitHub then you either need to build them yourself or read the +online version at https://docs.lammps.org/ You can build the HTML and PDF files yourself, by typing "make html" or by "make pdf", respectively. This requires various tools and files. @@ -39,10 +39,10 @@ environment and local folders. Installing prerequisites for the documentation build -To run the HTML documention build toolchain, python 3.x, doxygen, git, -and the venv python module have to be installed if not already available. -Also internet access is initially required to download external files -and tools. +To run the HTML documention build toolchain, python 3.8 or later, +doxygen 1.8.10 or later, git, and the venv python module have to be +installed if not already available. Also internet access is initially +required to download external files and tools. Building the PDF format manual requires in addition a compatible LaTeX installation with support for PDFLaTeX and several add-on LaTeX packages @@ -52,16 +52,24 @@ installed. This includes: - babel - capt-of - cmap +- dvipng +- ellipse - fncychap +- fontawesom - framed - geometry +- gyre - hyperref - hypcap - needspace +- pict2e - times - tabulary +- titlesec - upquote - wrapfig +- xindy + Also the latexmk script is required to run PDFLaTeX and related tools. the required number of times to have self-consistent output and include updated bibliography and indices. diff --git a/doc/lammps.1 b/doc/lammps.1 index cb52813a4d..d6d43cc081 100644 --- a/doc/lammps.1 +++ b/doc/lammps.1 @@ -1,7 +1,7 @@ -.TH LAMMPS "1" "19 November 2024" "2024-11-19" +.TH LAMMPS "1" "4 February 2025" "2025-02-04" .SH NAME .B LAMMPS -\- Molecular Dynamics Simulator. Version 19 November 2024 +\- Molecular Dynamics Simulator. Version 4 February 2025 .SH SYNOPSIS .B lmp @@ -311,7 +311,7 @@ the chapter on errors in the manual gives some additional information about error messages, if possible. .SH COPYRIGHT -© 2003--2024 Sandia Corporation +© 2003--2025 Sandia Corporation This package is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as diff --git a/doc/src/Build.rst b/doc/src/Build.rst index 7ca8cd428e..ff09ee5678 100644 --- a/doc/src/Build.rst +++ b/doc/src/Build.rst @@ -14,6 +14,29 @@ As an alternative, you can download a package with pre-built executables or automated build trees, as described in the :doc:`Install ` section of the manual. +Prerequisites +------------- + +Which software you need to compile and use LAMMPS strongly depends on +which :doc:`features and settings ` and which +:doc:`optional packages ` you are trying to include. +Common to all is that you need a C++ and C compiler, where the C++ +compiler has to support at least the C++11 standard (note that some +compilers require command-line flag to activate C++11 support). +Furthermore, if you are building with CMake, you need at least CMake +version 3.20 and a compatible build tool (make or ninja-build); if you +are building the the legacy GNU make based build system you need GNU +make (other make variants are not going to work since the build system +uses features unique to GNU make) and a Unix-like build environment with +a Bourne shell, and shell tools like "sed", "grep", "touch", "test", +"tr", "cp", "mv", "rm", "ln", "diff" and so on. Parts of LAMMPS +interface with or use Python version 3.6 or later. + +The LAMMPS developers aim to keep LAMMPS very portable and usable - +at least in parts - on most operating systems commonly used for +running MD simulations. Please see the :doc:`section on portablility +` for more details. + .. toctree:: :maxdepth: 1 diff --git a/doc/src/Build_cmake.rst b/doc/src/Build_cmake.rst index 56b8e450f3..a38b42b4f4 100644 --- a/doc/src/Build_cmake.rst +++ b/doc/src/Build_cmake.rst @@ -52,9 +52,9 @@ software or for people that want to modify or extend LAMMPS. compilers can be configured and built concurrently from the same source tree. - Simplified packaging of LAMMPS for Linux distributions, environment - modules, or automated build tools like `Homebrew `_. -- Integration of automated unit and regression testing (the LAMMPS side - of this is still under active development). + modules, or automated build tools like `Spack `_ + or `Homebrew `_. +- Integration of automated unit and regression testing. .. _cmake_build: diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index dab2267ee8..f57407f9c1 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -1139,11 +1139,10 @@ POEMS package PYTHON package --------------------------- -Building with the PYTHON package requires you have a the Python development -headers and library available on your system, which needs to be a Python 2.7 -version or a Python 3.x version. Since support for Python 2.x has ended, -using Python 3.x is strongly recommended. See ``lib/python/README`` for -additional details. +Building with the PYTHON package requires you have a the Python +development headers and library available on your system, which +needs to be Python version 3.6 or later. See ``lib/python/README`` +for additional details. .. tabs:: @@ -1159,7 +1158,7 @@ additional details. set the Python_EXECUTABLE variable to specify which Python interpreter should be used. Note note that you will also need to have the development headers installed for this version, - e.g. python2-devel. + e.g. python3-devel. .. tab:: Traditional make diff --git a/doc/src/Build_make.rst b/doc/src/Build_make.rst index 00f2f0b24d..477c1c6e34 100644 --- a/doc/src/Build_make.rst +++ b/doc/src/Build_make.rst @@ -30,9 +30,9 @@ additional tools to be available and functioning. * A Bourne shell compatible "Unix" shell program (frequently this is ``bash``) * A few shell utilities: ``ls``, ``mv``, ``ln``, ``rm``, ``grep``, ``sed``, ``tr``, ``cat``, ``touch``, ``diff``, ``dirname`` * Python (optional, required for ``make lib-`` in the ``src`` - folder). Python scripts are currently tested with python 2.7 and - 3.6 to 3.11. The procedure for :doc:`building the documentation - ` *requires* Python 3.5 or later. + folder). Python scripts are currently tested with 3.6 to 3.11. + The procedure for :doc:`building the documentation ` + *requires* Python 3.8 or later. Getting started ^^^^^^^^^^^^^^^ diff --git a/doc/src/Build_manual.rst b/doc/src/Build_manual.rst index 4b4bfa5a45..7a969877a1 100644 --- a/doc/src/Build_manual.rst +++ b/doc/src/Build_manual.rst @@ -116,9 +116,9 @@ environment variable. Prerequisites for HTML ---------------------- -To run the HTML documentation build toolchain, python 3, git, doxygen, -and virtualenv have to be installed locally. Here are instructions for -common setups: +To run the HTML documentation build toolchain, Python 3.8 or later, git, +doxygen, and virtualenv have to be installed locally. Here are +instructions for common setups: .. tabs:: @@ -128,13 +128,7 @@ common setups: sudo apt-get install git doxygen - .. tab:: RHEL or CentOS (Version 7.x) - - .. code-block:: bash - - sudo yum install git doxygen - - .. tab:: Fedora or RHEL/CentOS (8.x or later) + .. tab:: Fedora or RHEL/AlmaLinux/RockyLinux (8.x or later) .. code-block:: bash @@ -154,7 +148,36 @@ Prerequisites for PDF In addition to the tools needed for building the HTML format manual, a working LaTeX installation with support for PDFLaTeX and a selection -of LaTeX styles/packages are required. To run the PDFLaTeX translation +of LaTeX styles/packages are required. Apart from LaTeX packages that +are usually installed by default, the following packages are required: + +.. table_from_list:: + :columns: 11 + + - amsmath + - anysize + - babel + - capt-of + - cmap + - dvipng + - ellipse + - fncychap + - fontawesome + - framed + - geometry + - gyre + - hyperref + - hypcap + - needspace + - pict2e + - times + - tabulary + - titlesec + - upquote + - wrapfig + - xindy + +To run the PDFLaTeX translation the ``latexmk`` script needs to be installed as well. Prerequisites for ePUB and MOBI diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst index e4a53ddee7..fb3ebf4b48 100644 --- a/doc/src/Build_settings.rst +++ b/doc/src/Build_settings.rst @@ -8,7 +8,7 @@ Optional build settings LAMMPS can be built with several optional settings. Each subsection explains how to do this for building both with CMake and make. -* `C++11 standard compliance`_ when building all of LAMMPS +* `C++11 and C++17 standard compliance`_ when building all of LAMMPS * `FFT library`_ for use with the :doc:`kspace_style pppm ` command * `Size of LAMMPS integer types and size limits`_ * `Read or write compressed files`_ @@ -23,14 +23,15 @@ explains how to do this for building both with CMake and make. .. _cxx11: -C++11 standard compliance -------------------------- +C++11 and C++17 standard compliance +----------------------------------- -A C++11 standard compatible compiler is a requirement for compiling LAMMPS. -LAMMPS version 3 March 2020 is the last version compatible with the previous -C++98 standard for the core code and most packages. Most currently used -C++ compilers are compatible with C++11, but some older ones may need extra -flags to enable C++11 compliance. Example for GNU c++ 4.8.x: +A C++11 standard compatible compiler is currently the minimum +requirement for compiling LAMMPS. LAMMPS version 3 March 2020 is the +last version compatible with the previous C++98 standard for the core +code and most packages. Most currently used C++ compilers are compatible +with C++11, but some older ones may need extra flags to enable C++11 +compliance. Example for GNU c++ 4.8.x: .. code-block:: make @@ -40,6 +41,17 @@ Individual packages may require compliance with a later C++ standard like C++14 or C++17. These requirements will be documented with the :doc:`individual packages `. +.. versionchanged:: 4Feb2025 + +Starting with LAMMPS version 4 February 2025 we are starting a +transition to require the C++17 standard. Most current compilers are +compatible and if the C++17 standard is available by default, LAMMPS +will enable C++17 and will compile normally. If the chosen compiler is +not compatible with C++17, but only supports C++11, then the define +-DLAMMPS_CXX11 is required to fall back to compiling with a C++11 +compiler. After the next stable release of LAMMPS in summer 2025, the +LAMMPS development branch and future releases will require C++17. + ---------- .. _fft: diff --git a/doc/src/Commands_all.rst b/doc/src/Commands_all.rst index 58623401f3..bfc9e8538c 100644 --- a/doc/src/Commands_all.rst +++ b/doc/src/Commands_all.rst @@ -140,6 +140,7 @@ additional letter in parenthesis: k = KOKKOS. * :doc:`plugin ` * :doc:`prd ` * :doc:`python ` + * :doc:`region2vmd ` * :doc:`tad ` * :doc:`temper ` * :doc:`temper/grem ` diff --git a/doc/src/Commands_compute.rst b/doc/src/Commands_compute.rst index 7c73583a4f..b53d9d6820 100644 --- a/doc/src/Commands_compute.rst +++ b/doc/src/Commands_compute.rst @@ -178,6 +178,7 @@ KOKKOS, o = OPENMP, t = OPT. * :doc:`ti ` * :doc:`torque/chunk ` * :doc:`vacf ` + * :doc:`vacf/chunk ` * :doc:`vcm/chunk ` * :doc:`viscosity/cos ` * :doc:`voronoi/atom ` diff --git a/doc/src/Commands_removed.rst b/doc/src/Commands_removed.rst index be775f4c19..de60d6636c 100644 --- a/doc/src/Commands_removed.rst +++ b/doc/src/Commands_removed.rst @@ -87,7 +87,7 @@ Minimize style fire/old .. deprecated:: 8Feb2023 Minimize style *fire/old* has been removed. Its functionality can be -reproduced with *fire* with specific options. Please see the +reproduced with style *fire* with specific options. Please see the :doc:`min_modify command ` documentation for details. Pair style mesont/tpm, compute style mesont, atom style mesont diff --git a/doc/src/Developer_notes.rst b/doc/src/Developer_notes.rst index 2d136055a4..3f78f33d25 100644 --- a/doc/src/Developer_notes.rst +++ b/doc/src/Developer_notes.rst @@ -270,7 +270,10 @@ There are multiple "signatures" that can be called: - ``Error::all(FLERR, idx, "Error message")``: this is for argument parsing where "idx" is the index (starting at 0) of the argument for a LAMMPS command that is causing the failure (use -1 for the command - itself). The output may also include the last input line *before* and + itself). For index 0, you need to use the constant ``Error::ARGZERO`` + to work around the inability of some compilers to disambiguate between + a NULL pointer and an integer constant 0, even with an added type cast. + The output may also include the last input line *before* and *after*, if they differ due to substituting variables. A textual indicator is pointing to the specific word that failed. Using the constant ``Error::NOPOINTER`` in place of the *idx* argument will diff --git a/doc/src/Errors_details.rst b/doc/src/Errors_details.rst index ab92d16ccb..96efead1a2 100644 --- a/doc/src/Errors_details.rst +++ b/doc/src/Errors_details.rst @@ -12,9 +12,12 @@ following are discussions of such cases. - :ref:`Incorrect format in ... section of data file ` - :ref:`Illegal variable command: expected X arguments but found Y ` - :ref:`Out of range atoms - cannot compute ... ` -- :ref:`Cannot use neighbor bins - box size \<\< cutoff ` -- :ref:`Too many neighbor bins ` -- :ref:`Domain too large for neighbor bins ` +- :ref:`Too many neighbor bins ` +- :ref:`Cannot use neighbor bins - box size \<\< cutoff ` +- :ref:`Domain too large for neighbor bins ` +- :ref:`Molecule topology/atom exceeds system topology/atom ` +- :ref:`Molecule topology type exceeds system topology type ` +- :ref:`Molecule attributes do not match system attributes ` ------ @@ -276,7 +279,19 @@ help to temporarily use a cutoff-Coulomb pair style and no kspace style until the system has somewhat equilibrated and then switch to the long-range solver. -.. _err0005: +.. _err0009: + +Too many neighbor bins +---------------------- + +The simulation box has become too large relative to the size of a +neighbor bin and LAMMPS is unable to store the needed number of +bins. This typically implies the simulation box has expanded too far. +This can happen when some atoms move rapidly apart with shrink-wrap +boundaries or when a fix (like fix deform or a barostat) excessively +grows the simulation box. + +.. _err0015: Cannot use neighbor bins - box size \<\< cutoff ----------------------------------------------- @@ -290,19 +305,7 @@ fill space. This error can be avoided using the generally slower :doc:`nsq neighbor style ` or by increasing the size of the smallest box lengths. -.. _err0006: - -Too many neighbor bins ----------------------- - -The simulation box has become too large relative to the size of a -neighbor bin and LAMMPS is unable to store the needed number of -bins. This typically implies the simulation box has expanded too far. -This can happen when some atoms move rapidly apart with shrinkwrap -boundaries or when a fix (like fix deform or a barostat) excessively -grows the simulation box. - -.. _err0007: +.. _err0017: Domain too large for neighbor bins ---------------------------------- @@ -312,3 +315,55 @@ be used. Too many neighbor bins would need to be created to fill space Most likely, one or more atoms have been blown out of the simulation box to a great distance or a fix (like fix deform or a barostat) has excessively grown the simulation box. + +.. _err0024: + +Molecule topology/atom exceeds system topology/atom +--------------------------------------------------- + +LAMMPS uses :doc:`domain decomposition ` to +distribute data (i.e. atoms) across the MPI processes in parallel runs. +This includes topology data, that is data about bonds, angles, +dihedrals, impropers and :doc:`"special" neighbors `. +This information is stored with either one or all atoms involved in such +a topology entry (which of the two option applies depends on the +:doc:`newton ` setting for bonds. When reading a data file, +LAMMPS analyzes the requirements for this file and then the values +are "locked in" and cannot be extended. + +So loading a molecule file that requires more of the topology per atom +storage or adding a data file with such needs will lead to an error. To +avoid the error, one or more of the `extra/XXX/per/atom` keywords are +required to extend the corresponding storage. It is no problem to +choose those numbers generously and have more storage reserved than +actually needed, but having these numbers set too small will lead to an +error. + +.. _err0025: + +Molecule topology type exceeds system topology type +--------------------------------------------------- + +The total number of atom, bond, angle, dihedral, and improper types is +"locked in" when LAMMPS creates the simulation box. This can happen +through either the :doc:`create_box `, the :doc:`read_data +`, or the :doc:`read_restart ` command. After +this it is not possible to refer to an additional type. So loading a +molecule file that uses additional types or adding a data file that +would require additional types will lead to an error. To avoid the +error, one or more of the `extra/XXX/types` keywords are required to +extend the maximum number of the individual types. + +.. _err0026: + +Molecule attributes do not match system attributes +-------------------------------------------------- + +Choosing an :doc:`atom_style ` in LAMMPS determines which +per-atom properties are available. In a :doc:`molecule file +`, however, it is possible to add sections (for example Masses +or Charges) that are not supported by the atom style. Masses for +example, are usually not a per-atom property, but defined through the +atom type. Thus it would not be required to have a Masses section and +the included data would be ignored. LAMMPS prints this warning to +inform about this case. diff --git a/doc/src/Fortran.rst b/doc/src/Fortran.rst index 53dc5b8897..ea0ade5cf4 100644 --- a/doc/src/Fortran.rst +++ b/doc/src/Fortran.rst @@ -1470,7 +1470,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type LAMMPS equal style variable string, evaluates it and returns the resulting scalar value as a floating-point number. - .. versionadded:: TBD + .. versionadded:: 4Feb2025 :p character(len=\*) expr: string to be evaluated :to: :cpp:func:`lammps_eval` @@ -1482,7 +1482,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type Clear whether a compute has been invoked - .. versionadded:: TBD + .. versionadded:: 4Feb2025 :to: :cpp:func:`lammps_clearstep_compute` @@ -1493,7 +1493,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type Add timestep to list of future compute invocations if the compute has been invoked on the current timestep - .. versionadded:: TBD + .. versionadded:: 4Feb2025 overloaded for 32-bit and 64-bit integer arguments @@ -1506,7 +1506,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type Add timestep to list of future compute invocations - .. versionadded:: TBD + .. versionadded:: 4Feb2025 overloaded for 32-bit and 64-bit integer arguments diff --git a/doc/src/Intro_portability.rst b/doc/src/Intro_portability.rst index 036529ff9d..8bb716833f 100644 --- a/doc/src/Intro_portability.rst +++ b/doc/src/Intro_portability.rst @@ -13,10 +13,14 @@ Programming language standards Most of the C++ code currently requires a compiler compatible with the C++11 standard, the KOKKOS package currently requires C++17. Most of -the Python code is written to be compatible with Python 3.5 or later or -Python 2.7. Some Python scripts *require* Python 3 and a few others -still need to be ported from Python 2 to Python 3. +the Python code is written to be compatible with Python 3.6 or later. +.. deprecated:: TBD + +Python 2.x is no longer supported and trying to use it, e.g. for the +LAMMPS Python module should result in an error. If you come across +some part of the LAMMPS distribution that is not (yet) compatible with +Python 3, please notify the LAMMPS developers. Build systems ^^^^^^^^^^^^^ @@ -24,8 +28,8 @@ Build systems LAMMPS can be compiled from source code using a (traditional) build system based on shell scripts, a few shell utilities (grep, sed, cat, tr) and the GNU make program. This requires running within a Bourne -shell (``/bin/sh``). Alternatively, a build system with different back ends -can be created using CMake. CMake must be at least version 3.16. +shell (``/bin/sh``). Alternatively, a build system with different back +ends can be created using CMake. CMake must be at least version 3.16. Operating systems ^^^^^^^^^^^^^^^^^ diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst index c3e514a423..850fbf95c1 100644 --- a/doc/src/Modify_requirements.rst +++ b/doc/src/Modify_requirements.rst @@ -189,10 +189,8 @@ of the contribution. As of January 2023, all previously included Fortran code for the LAMMPS executable has been replaced by equivalent C++ code. -Python code must be compatible with Python 3.5 and later. Large parts -of LAMMPS (including the :ref:`PYTHON package `) are also -compatible with Python 2.7. Compatibility with Python 2.7 is desirable, -but compatibility with Python 3.5 is **required**. +Python code currently must be compatible with Python 3.6. If a later +version or Python is required, it needs to be documented. Compatibility with older programming language standards is very important to maintain portability and availability of LAMMPS on many diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst index baefee0185..870dc8fbf7 100644 --- a/doc/src/Packages_details.rst +++ b/doc/src/Packages_details.rst @@ -2428,7 +2428,7 @@ ways to use LAMMPS and Python together. Building with the PYTHON package assumes you have a Python development environment (headers and libraries) available on your system, which needs - to be either Python version 2.7 or Python 3.5 and later. + to be Python version 3.6 or later. **Install:** diff --git a/doc/src/Python_install.rst b/doc/src/Python_install.rst index 01610b84f0..1e53a99914 100644 --- a/doc/src/Python_install.rst +++ b/doc/src/Python_install.rst @@ -7,6 +7,10 @@ LAMMPS shared library through the Python `ctypes `_ module. Because of the dynamic loading, it is required that LAMMPS is compiled in :ref:`"shared" mode `. +.. versionchanged:: TBD + +LAMMPS currently only supports Python version 3.6 or later. + Two components are necessary for Python to be able to invoke LAMMPS code: * The LAMMPS Python Package (``lammps``) from the ``python`` folder @@ -136,11 +140,6 @@ folder that the dynamic loader searches or inside of the installed # create virtual environment in folder $HOME/myenv python3 -m venv $HOME/myenv - For Python versions prior 3.3 you can use `virtualenv - `_ - command instead of "python3 -m venv". This step has to be done - only once. - To activate the virtual environment type: .. code-block:: bash @@ -245,14 +244,14 @@ make MPI calls directly from Python in your script, if you desire. We have tested this with `MPI for Python `_ (aka mpi4py) and you will find installation instruction for it below. -Installation of mpi4py (version 3.0.3 as of Sep 2020) can be done as +Installation of mpi4py (version 4.0.1 as of Feb 2025) can be done as follows: - Via ``pip`` into a local user folder with: .. code-block:: bash - pip install --user mpi4py + python3 -m pip install --user mpi4py - Via ``dnf`` into a system folder for RedHat/Fedora systems: @@ -261,20 +260,20 @@ follows: # for use with OpenMPI sudo dnf install python3-mpi4py-openmpi # for use with MPICH - sudo dnf install python3-mpi4py-openmpi + sudo dnf install python3-mpi4py-mpich - Via ``pip`` into a virtual environment (see above): .. code-block:: console $ source $HOME/myenv/activate - (myenv)$ pip install mpi4py + (myenv)$ python -m pip install mpi4py - Via ``pip`` into a system folder (not recommended): .. code-block:: bash - sudo pip install mpi4py + sudo python3 -m pip install mpi4py For more detailed installation instructions and additional options, please see the `mpi4py installation `_ page. diff --git a/doc/src/Python_overview.rst b/doc/src/Python_overview.rst index 85bc0d3bfa..57b9ee6145 100644 --- a/doc/src/Python_overview.rst +++ b/doc/src/Python_overview.rst @@ -44,15 +44,11 @@ Below is an example output for Python version 3.8.5. .. warning:: The options described in this section of the manual for using Python - with LAMMPS currently support either Python 2 or 3. Specifically - version 2.7 or later and 3.6 or later. Since the Python community no - longer maintains Python 2 (see `this notice - `_), we recommend use of - Python 3 with LAMMPS. While Python 2 code should continue to work, - that is not something we can guarantee long-term. If you notice - Python code in the LAMMPS distribution that is not compatible with - Python 3, please contact the LAMMPS developers or submit `and issue - on GitHub `_ + with LAMMPS support only Python 3.6 or later. For use with Python + 2.x you will need to use an older LAMMPS version like 29 Aug 2024 + or older. If you notice Python code in the LAMMPS distribution that + is not compatible with Python 3, please contact the LAMMPS developers + or submit `and issue on GitHub `_ --------- diff --git a/doc/src/Run_output.rst b/doc/src/Run_output.rst index 28ed891765..bf8e2de407 100644 --- a/doc/src/Run_output.rst +++ b/doc/src/Run_output.rst @@ -117,14 +117,19 @@ number of histogram counts is equal to the number of processors. ---------- -The last section gives aggregate statistics (across all processors) -for pairwise neighbors and special neighbors that LAMMPS keeps track -of (see the :doc:`special_bonds ` command). The number -of times neighbor lists were rebuilt is tallied, as is the number of -potentially *dangerous* rebuilds. If atom movement triggered neighbor -list rebuilding (see the :doc:`neigh_modify ` command), -then dangerous reneighborings are those that were triggered on the -first timestep atom movement was checked for. If this count is +The last section gives aggregate statistics (across all processors) for +pairwise neighbors and special neighbors that LAMMPS keeps track of (see +the :doc:`special_bonds ` command). This section will +not always contain data, for example when there has not been a neighbor +rebuild, or the neighbor list was constructed on the GPU or when a +hybrid pair style was used and LAMMPS cannot determine a suitable (base) +neighbor list to draw the statistics from. + +The number of times neighbor lists were rebuilt is tallied, as is the +number of potentially *dangerous* rebuilds. If atom movement triggered +neighbor list rebuilding (see the :doc:`neigh_modify ` +command), then dangerous reneighborings are those that were triggered on +the first timestep atom movement was checked for. If this count is non-zero you may wish to reduce the delay factor to ensure no force interactions are missed by atoms moving beyond the neighbor skin distance before a rebuild takes place. diff --git a/doc/src/angle_mwlc.rst b/doc/src/angle_mwlc.rst index 9fa4171a63..587afb8009 100644 --- a/doc/src/angle_mwlc.rst +++ b/doc/src/angle_mwlc.rst @@ -21,7 +21,7 @@ Examples Description """"""""""" -.. versionadded:: TBD +.. versionadded:: 4Feb2025 The *mwlc* angle style models a meltable wormlike chain and can be used to model non-linear bending elasticity of polymers, e.g. DNA. *mwlc* diff --git a/doc/src/bond_bpm_spring.rst b/doc/src/bond_bpm_spring.rst index 0a43a62159..88d63c901d 100644 --- a/doc/src/bond_bpm_spring.rst +++ b/doc/src/bond_bpm_spring.rst @@ -123,7 +123,7 @@ heuristic maximum strain used by typical non-bpm bond styles. Similar behavior to *break no* can also be attained by setting an arbitrarily high value of :math:`\epsilon_c`. One cannot use *break no* with *smooth yes*. -.. versionadded:: TBD +.. versionadded:: 4Feb2025 The *volume/factor* keyword toggles whether an additional multibody contribution is added to he force using the formulation in diff --git a/doc/src/comm_modify.rst b/doc/src/comm_modify.rst index c416ca21ea..f7c5c17159 100644 --- a/doc/src/comm_modify.rst +++ b/doc/src/comm_modify.rst @@ -15,15 +15,12 @@ Syntax .. parsed-literal:: - *mode* value = *single*, *multi*, or *multi/old* = communicate atoms within a single or multiple distances + *mode* value = *single* or *multi* = communicate atoms within a single or multiple distances *cutoff* value = Rcut (distance units) = communicate atoms from this far away *cutoff/multi* collection value collection = atom collection or collection range (supports asterisk notation) value = Rcut (distance units) = communicate atoms for selected types from this far away *reduce/multi* arg = none = reduce number of communicated ghost atoms for multi style - *cutoff/multi/old* type value - type = atom type or type range (supports asterisk notation) - value = Rcut (distance units) = communicate atoms for selected types from this far away *group* value = group-ID = only communicate atoms in the group *vel* value = *yes* or *no* = do or do not communicate velocity info with ghost atoms @@ -66,19 +63,16 @@ subdomain. The distance is by default the maximum of the neighbor cutoff across all atom type pairs. For many systems this is an efficient algorithm, but for systems with -widely varying cutoffs for different type pairs, the *multi* or *multi/old* mode can -be faster. In *multi*, each atom is assigned to a collection which should -correspond to a set of atoms with similar interaction cutoffs. -See the :doc:`neighbor ` command for a detailed description of collections. -In this case, each atom collection is assigned its own distance -cutoff for communication purposes, and fewer atoms will be -communicated. in *multi/old*, a similar technique is used but atoms -are grouped by atom type. See the :doc:`neighbor multi ` and -:doc:`neighbor multi/old ` commands for +widely varying cutoffs for different type pairs, the *multi* mode can be +faster. In *multi*, each atom is assigned to a collection which should +correspond to a set of atoms with similar interaction cutoffs. See the +:doc:`neighbor ` command for a detailed description of +collections. In this case, each atom collection is assigned its own +distance cutoff for communication purposes, and fewer atoms will be +communicated. See the :doc:`neighbor multi ` command for neighbor list construction options that may also be beneficial for -simulations of this kind. The *multi* communication mode is only compatible -with the *multi* neighbor style. The *multi/old* communication mode is comparable -with both the *multi* and *multi/old* neighbor styles. +simulations of this kind. The *multi* communication mode is only +compatible with the *multi* neighbor style. The *cutoff* keyword allows you to extend the ghost cutoff distance for communication mode *single*, which is the distance from the borders @@ -108,14 +102,12 @@ simulation to account for potential changes in the number of collections. Custom cutoffs are preserved between runs but if collections are redefined, one may want to re-specify the communication cutoffs. For granular pair styles,the default cutoff is set to the sum -of the current maximum atomic radii for each collection. The -*cutoff/multi/old* option is similar to *cutoff/multi* except it -operates on atom types as opposed to collections. +of the current maximum atomic radii for each collection. The *reduce/multi* option applies to *multi* and sets the communication -cutoff for a particle equal to the maximum interaction distance between particles -in the same collection. This reduces the number of -ghost atoms that need to be communicated. This method is only compatible with the +cutoff for a particle equal to the maximum interaction distance between +particles in the same collection. This reduces the number of ghost atoms +that need to be communicated. This method is only compatible with the *multi* neighbor style and requires a half neighbor list and Newton on. See the :doc:`neighbor multi ` command for more information. diff --git a/doc/src/commands_list.rst b/doc/src/commands_list.rst index dc5731f579..acfdfd9df0 100644 --- a/doc/src/commands_list.rst +++ b/doc/src/commands_list.rst @@ -82,6 +82,7 @@ Commands read_dump read_restart region + region2vmd replicate rerun reset_atoms diff --git a/doc/src/compute.rst b/doc/src/compute.rst index 9a8a1734fb..323f3ed3e5 100644 --- a/doc/src/compute.rst +++ b/doc/src/compute.rst @@ -356,6 +356,7 @@ The individual style names on the :doc:`Commands compute ` pag * :doc:`ti ` - thermodynamic integration free energy values * :doc:`torque/chunk ` - torque applied on each chunk * :doc:`vacf ` - velocity auto-correlation function of group of atoms +* :doc:`vacf/chunk ` - velocity auto-correlation for the center of mass velocities of chunks of atoms * :doc:`vcm/chunk ` - velocity of center-of-mass for each chunk * :doc:`viscosity/cos ` - velocity profile under cosine-shaped acceleration * :doc:`voronoi/atom ` - Voronoi volume and neighbors for each atom diff --git a/doc/src/compute_gaussian_grid_local.rst b/doc/src/compute_gaussian_grid_local.rst index 46fac9fab3..37dc0954f7 100644 --- a/doc/src/compute_gaussian_grid_local.rst +++ b/doc/src/compute_gaussian_grid_local.rst @@ -30,7 +30,7 @@ Examples Description """"""""""" -.. versionadded:: TBD +.. versionadded:: 4Feb2025 Define a computation that calculates a Gaussian representation of the ionic structure. This representation is used for the efficient evaluation diff --git a/doc/src/compute_msd.rst b/doc/src/compute_msd.rst index bc16a3de6f..8f2726e8a3 100644 --- a/doc/src/compute_msd.rst +++ b/doc/src/compute_msd.rst @@ -116,7 +116,9 @@ Compute *msd* cannot be used with a dynamic group. Related commands """""""""""""""" -:doc:`compute msd/nongauss `, :doc:`compute displace_atom `, :doc:`fix store/state `, :doc:`compute msd/chunk ` +:doc:`compute msd/nongauss `, +:doc:`compute displace_atom `, :doc:`fix store/state `, +:doc:`compute msd/chunk ` Default """"""" diff --git a/doc/src/compute_msd_chunk.rst b/doc/src/compute_msd_chunk.rst index db6e1e6fc2..863be4db35 100644 --- a/doc/src/compute_msd_chunk.rst +++ b/doc/src/compute_msd_chunk.rst @@ -131,7 +131,7 @@ Restrictions Related commands """""""""""""""" -:doc:`compute msd ` +:doc:`compute msd `, :doc:`compute vacf/chunk ` Default """"""" diff --git a/doc/src/compute_reduce.rst b/doc/src/compute_reduce.rst index e5c99a478f..d9aa7e1821 100644 --- a/doc/src/compute_reduce.rst +++ b/doc/src/compute_reduce.rst @@ -87,7 +87,7 @@ values in the vector. The *sumsq* option sums the square of the values in the vector into a global total. The *avesq* setting does the same as *sumsq*, then divides the sum of squares by the number of values. The last two options can be useful for calculating the -variance of some quantity (e.g., variance = sumsq :math:`-` ave\ +variance of some quantity (e.g., variance = *avesq* :math:`-` *ave*\ :math:`^2`). The *sumabs* option sums the absolute values in the vector into a global total. The *aveabs* setting does the same as *sumabs*, then divides the sum of absolute values by the number of diff --git a/doc/src/compute_vacf.rst b/doc/src/compute_vacf.rst index 704e597e18..72f675360c 100644 --- a/doc/src/compute_vacf.rst +++ b/doc/src/compute_vacf.rst @@ -76,7 +76,7 @@ Restrictions Related commands """""""""""""""" -:doc:`compute msd ` +:doc:`compute msd `, :doc:`compute vacf/chunk ` Default """"""" diff --git a/doc/src/compute_vacf_chunk.rst b/doc/src/compute_vacf_chunk.rst new file mode 100644 index 0000000000..f9d22e22a1 --- /dev/null +++ b/doc/src/compute_vacf_chunk.rst @@ -0,0 +1,124 @@ +.. index:: compute vacf/chunk + +compute vacf/chunk command +========================== + +Syntax +"""""" + +.. code-block:: LAMMPS + + compute ID group-ID vacf/chunk chunkID + +* ID, group-ID are documented in :doc:`compute ` command +* vacf/chunk = style name of this compute command +* chunkID = ID of :doc:`compute chunk/atom ` command + +Examples +"""""""" + +.. code-block:: LAMMPS + + compute 1 all vacf/chunk molchunk + +Description +""""""""""" + +.. versionadded:: TBD + +Define a computation that calculates the velocity auto-correlation +function (VACF) for multiple chunks of atoms. + +In LAMMPS, chunks are collections of atoms defined by a :doc:`compute +chunk/atom ` command, which assigns each atom to a +single chunk (or no chunk). The ID for this command is specified as +chunkID. For example, a single chunk could be the atoms in a molecule +or atoms in a spatial bin. See the :doc:`compute chunk/atom +` and :doc:`Howto chunk ` doc pages for +details of how chunks can be defined and examples of how they can be +used to measure properties of a system. + +Four quantities are calculated by this compute for each chunk. The +first 3 quantities are the product of the initial center of mass +velocity (VCM) for each chunk in *x*, *y*, and *z* direction with the +current center of mass velocity in the same direction. The fourth +component is the total VACF, i.e. the sum of the three components. + +Note that only atoms in the specified group contribute to the +calculation. The :doc:`compute chunk/atom ` command +defines its own group; atoms will have a chunk ID = 0 if they are not in +that group, signifying they are not assigned to a chunk, and will thus +also not contribute to this calculation. You can specify the "all" +group for this command if you simply want to include atoms with non-zero +chunk IDs. + +The integral of the VACF versus time is proportional to the diffusion +coefficient of the diffusing chunks. + +.. note:: + + The number of chunks *Nchunk* calculated by the + :doc:`compute chunk/atom ` command must remain constant + each time this compute is invoked, so that the dot product for each chunk + from its original position can be computed consistently. If *Nchunk* + does not remain constant, an error will be generated. If needed, you + can enforce a constant *Nchunk* by using the *nchunk once* or *ids once* + options when specifying the :doc:`compute chunk/atom ` + command. + +.. note:: + + This compute stores the original center-of-mass velocities of each + chunk. When a VACF is calculated on a later timestep, it is assumed + that the same atoms are assigned to the same chunk ID. However + LAMMPS has no simple way to ensure this is the case, though you can + use the *ids once* option when specifying the :doc:`compute + chunk/atom ` command. Note that if this is not + the case, the VACF calculation does not have a sensible meaning. + +.. note:: + + If you want the quantities calculated by this compute to be + continuous when running from a :doc:`restart file `, then + you should use the same ID for this compute, as in the original run. + This is so that the fix this compute creates to store per-chunk + quantities will also have the same ID, and thus be initialized + correctly with chunk reference positions from the restart file. + +The simplest way to output the results of the compute vacf/chunk +calculation to a file is to use the :doc:`fix ave/time ` +command, for example: + +.. code-block:: LAMMPS + + compute cc1 all chunk/atom molecule + compute myChunk all vacf/chunk cc1 + fix 1 all ave/time 100 1 100 c_myChunk[*] file tmp.out mode vector + +Output info +""""""""""" + +This compute calculates a global array where the number of rows = the +number of chunks *Nchunk* as calculated by the specified :doc:`compute +chunk/atom ` command. The number of columns = 4 for +the *x*, *y*, *z*, component and the total VACF. These values can be +accessed by any command that uses global array values from a compute as +input. See the :doc:`Howto output ` page for an overview +of LAMMPS output options. + +The array values are "intensive". The array values will be in +distance\ :math:`^2` divided by time\ :math:`^2` :doc:`units `. + +Restrictions +"""""""""""" + none + +Related commands +"""""""""""""""" + +:doc:`compute vacf `, :doc:`compute msd/chunk ` + +Default +""""""" + +none diff --git a/doc/src/fix_efield_lepton.rst b/doc/src/fix_efield_lepton.rst index 5deec4a15e..84fdd2f83f 100644 --- a/doc/src/fix_efield_lepton.rst +++ b/doc/src/fix_efield_lepton.rst @@ -40,7 +40,7 @@ Examples Description """"""""""" -.. versionadded:: TBD +.. versionadded:: 4Feb2025 Add an electric potential :math:`V` that applies to a group of charged atoms a force :math:`\vec{F} = q \vec{E}`, and to dipoles a force :math:`\vec{F} = (\vec{p} \cdot \nabla) \vec{E}` and torque :math:`\vec{T} = \vec{p} \times \vec{E}`, diff --git a/doc/src/fix_imd.rst b/doc/src/fix_imd.rst index a4d7d9d387..d85ebc8d34 100644 --- a/doc/src/fix_imd.rst +++ b/doc/src/fix_imd.rst @@ -120,7 +120,7 @@ with different units or as a measure to tweak the forces generated by the manipulation of the IMD client, this option allows to make adjustments. -.. versionadded:: TBD +.. versionadded:: 4Feb2025 In `IMDv3 `_, the IMD protocol has been extended to allow for the transmission of simulation time, box dimensions, atomic coordinates, diff --git a/doc/src/min_modify.rst b/doc/src/min_modify.rst index f4a706e75c..d36f19b0d5 100644 --- a/doc/src/min_modify.rst +++ b/doc/src/min_modify.rst @@ -84,10 +84,10 @@ energy after) and that difference may be smaller than machine epsilon even if atoms could move in the gradient direction to reduce forces further. -The choice of a norm can be modified for the min styles *cg*, *sd*\ -, *quickmin*, *fire*, *fire/old*, *spin*, *spin/cg* and -*spin/lbfgs* using the *norm* keyword. The default *two* norm computes -the 2-norm (Euclidean length) of the global force vector: +The choice of a norm can be modified for the min styles *cg*, *sd*, +*quickmin*, *fire*, *spin*, *spin/cg*, and *spin/lbfgs* using the +*norm* keyword. The default *two* norm computes the 2-norm +(Euclidean length) of the global force vector: .. math:: || \vec{F} ||_{2} = \sqrt{\vec{F}_1^2+ \cdots + \vec{F}_N^2} @@ -160,9 +160,9 @@ that modifies the bias and scaling of the velocities of the atoms during the mixing step :ref:`(Echeverri Restrepo) `. This can lead to faster convergence of the minimizer. -The :doc:`min_style ` *fire* is an optimized implementation of -:doc:`min_style ` *fire/old*. It can however behave similarly -to the *fire/old* style by using the following set of parameters: +The :doc:`min_style ` *fire* is an optimized implementation. +It can behave similarly to the previous version by using the following +set of parameters: .. code-block:: LAMMPS diff --git a/doc/src/minimize.rst b/doc/src/minimize.rst index 56efa12f44..c201e53340 100644 --- a/doc/src/minimize.rst +++ b/doc/src/minimize.rst @@ -89,8 +89,8 @@ be more robust than previous line searches we have tried. The backtracking method is described in Nocedal and Wright's Numerical Optimization (Procedure 3.1 on p 41). -The :doc:`minimization styles ` *quickmin*, *fire* and -*fire/old* perform damped dynamics using an Euler integration step. Thus +The :doc:`minimization styles ` *quickmin* and *fire* +perform damped dynamics using an Euler integration step. Thus they require a :doc:`timestep ` be defined. .. note:: diff --git a/doc/src/neighbor.rst b/doc/src/neighbor.rst index 12d6d91fde..8ccd1fb50d 100644 --- a/doc/src/neighbor.rst +++ b/doc/src/neighbor.rst @@ -11,7 +11,7 @@ Syntax neighbor skin style * skin = extra distance beyond force cutoff (distance units) -* style = *bin* or *nsq* or *multi* or *multi/old* +* style = *bin* or *nsq* or *multi* Examples """""""" @@ -83,16 +83,6 @@ is customized or not, also see the :doc:`comm_modify mode multi ` command for communication options that further improve performance in a manner consistent with neighbor style multi. -An alternate style, *multi/old*, sets the bin size to 1/2 of the shortest -cutoff distance and multiple sets of bins are defined to search over for -different atom types. This algorithm used to be the default *multi* -algorithm in LAMMPS but was found to be significantly slower than the new -approach. For the dense binary system, computational costs still grew as -:math:`\lambda^{2d}` at large enough :math:`\lambda`. This is equivalent -to the default style, albeit with a smaller prefactor. For now we are -keeping the old option in case there are use cases where multi/old -outperforms the new multi style. - .. note:: If there are multiple sub-styles in a :doc:`hybrid/overlay pair style diff --git a/doc/src/pair_bpm_spring.rst b/doc/src/pair_bpm_spring.rst index 068efff577..53375d86b8 100644 --- a/doc/src/pair_bpm_spring.rst +++ b/doc/src/pair_bpm_spring.rst @@ -85,7 +85,7 @@ commands, or by mixing as described below: * :math:`r_c` (distance units) * :math:`\gamma` (force/velocity units) -.. versionadded:: TBD +.. versionadded:: 4Feb2025 Additionally, if *anharmonic* is set to *yes*, a fourth coefficient must be provided: diff --git a/doc/src/pair_dispersion_d3.rst b/doc/src/pair_dispersion_d3.rst index 9c8726b2a1..d6a548e01f 100644 --- a/doc/src/pair_dispersion_d3.rst +++ b/doc/src/pair_dispersion_d3.rst @@ -26,7 +26,7 @@ Examples Description """"""""""" -.. versionadded:: TBD +.. versionadded:: 4Feb2025 Style *dispersion/d3* computes the dispersion energy-correction used in the DFT-D3 method of Grimme :ref:`(Grimme1) `. It would diff --git a/doc/src/pair_hbond_dreiding.rst b/doc/src/pair_hbond_dreiding.rst index e059fdf2ba..a122fc5ea2 100644 --- a/doc/src/pair_hbond_dreiding.rst +++ b/doc/src/pair_hbond_dreiding.rst @@ -111,7 +111,7 @@ potential for the Donor-Acceptor interactions. :ref:`(Liu) ` showed that the Morse form gives improved results for Dendrimer simulations, when n = 2. -.. versionadded:: TBD +.. versionadded:: 4Feb2025 The style variants *hbond/dreiding/lj/angleoffset* and *hbond/dreiding/lj/angleoffset* take the equilibrium angle of the AHD as diff --git a/doc/src/region.rst b/doc/src/region.rst index 6f576ff9b9..fbc250ca83 100644 --- a/doc/src/region.rst +++ b/doc/src/region.rst @@ -46,6 +46,7 @@ Syntax xy = distance to tilt y in x direction (distance units) xz = distance to tilt z in x direction (distance units) yz = distance to tilt z in y direction (distance units) + xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz can be a variable (see below) *sphere* args = x y z radius x,y,z = center of sphere (distance units) radius = radius of sphere (distance units) @@ -211,9 +212,10 @@ and *ellipsoid* the x-, y-, and z- coordinates of the center of the sphere/ellipsoid can be specified as an equal-style variable. And for style *cylinder* the two center positions c1 and c2 for the location of the cylinder axes can be specified as a equal-style variable. For styles -*cone* and *plane* all properties can be defined via equal-style variables. -For style *plane*, the components of the direction vector normal to plane -should be either all constants or all defined by equal-style variables. +*cone*, *prism*, and *plane* all properties can be defined via +equal-style variables. For style *plane*, the components of the direction +vector normal to plane should be either all constants or all defined by +equal-style variables. If the value is a variable, it should be specified as v_name, where name is the variable name. In this case, the variable will be diff --git a/doc/src/region2vmd.rst b/doc/src/region2vmd.rst new file mode 100644 index 0000000000..54216bb925 --- /dev/null +++ b/doc/src/region2vmd.rst @@ -0,0 +1,179 @@ +.. index:: region2vmd + +region2vmd command +================== + +Syntax +"""""" + +.. code-block:: LAMMPS + + region2vmd file keyword arg ... + +* filename = name of file to write VMD script commands to +* zero or more keyword/arg pairs may be appended +* keyword = *region* or *color* or *material* or *command* + + .. parsed-literal:: + + *region* region-ID = name of region to translate to VMD graphics + *color* color-name = set color for following visualized objects + *material* material-name = set material for following visualized objects + *command* string = string with custom VMD script command (in quotes) + +Examples +"""""""" + +.. code-block:: LAMMPS + + region2vmd regions.vmd material Opaque color red region c1 color green region c2 + region2vmd vizbox.vmd command "mol new system.lammpstrj waitfor all" region box + region2vmd regdefs.vmd region upper region lower region hole + +Description +""""""""""" + +.. versionadded:: TBD + +Write a `VMD `_ Tcl script file with +commands that aim to create a visualization of :doc:`regions `. +There may be multiple region visualizations stored in a single file. + +The visualization is implemented by creating a new (and empty) "VMD +molecule" and then assigning a sequence of VMD graphics primitives to +represent the region in VMD. Each region will be stored in a separate +"VMD molecule" with the name "LAMMPS region ". + +The *region2vmd* command is following by the filename for the resulting +VMD script and an arbitrary number of keyword argument pairs to either +write out a new *region* visualization, change the *color* or *material* +setting, or to insert arbitrary VMD script *command*\ s. The keywords +and arguments are processed in sequence. + +The *region* keyword must be followed by a previously defined LAMMPS +:doc:`region `. Only a limited set region styles and region +settings are currently supported. See **Restrictions** below. +Unsupported region styles or regions with unsupported settings will be +skipped and a corresponding message is printed. + +The *color* keyword must be followed by a color name that is defined in +VMD. This color will be used by all following region visualizations. +The default setting is 'silver'. VMD has the following colors +pre-defined: + +.. table_from_list:: + :columns: 11 + + * blue + * red + * gray + * orange + * yellow + * tan + * silver + * green + * white + * pink + * cyan + * purple + * lime + * mauve + * ochre + * iceblue + * black + * yellow2 + * yellow3 + * green2 + * green3 + * cyan2 + * cyan3 + * blue2 + * blue3 + * violet + * violet2 + * magenta + * magenta2 + * red2 + * red3 + * orange2 + * orange3 + +The *material* keyword must be followed by a material name that is defined in +VMD. This material will be used by all following visualizations. The +default setting is 'Transparent'. VMD has the following materials +pre-defined: + +.. table_from_list:: + :columns: 8 + + * Opaque + * Transparent + * BrushedMetal + * Diffuse + * Ghost + * Glass1 + * Glass2 + * Glass3 + * Glossy + * HardPlastic + * MetallicPastel + * Steel + * Translucent + * Edgy + * EdgyShiny + * EdgyGlass + * Goodsell + * AOShiny + * AOChalky + * AOEdgy + * BlownGlass + * GlassBubble + * RTChrome + +The *command* keyword must be followed by a VMD script command as a +single string in quotes. This VMD command will be directly inserted +into the created VMD script. + +The created file can be loaded into VMD either from the command line +with the '-e' flag, or from the command prompt with 'play