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..591958f996 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() @@ -930,7 +930,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/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-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_manual.rst b/doc/src/Build_manual.rst index 4b4bfa5a45..490594af02 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 + - fontawesom + - 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_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/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/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_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/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 94feee6ad4..6d4bbaca4b 100644 --- a/doc/src/region.rst +++ b/doc/src/region.rst @@ -46,6 +46,7 @@ Syntax xy = distance to tilt y in x direction (distance units) xz = distance to tilt z in x direction (distance units) yz = distance to tilt z in y direction (distance units) + xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz can be a variable (see below) *sphere* args = x y z radius x,y,z = center of sphere (distance units) radius = radius of sphere (distance units) @@ -211,7 +212,7 @@ and *ellipsoid* the x-, y-, and z- coordinates of the center of the sphere/ellipsoid can be specified as an equal-style variable. And for style *cylinder* the two center positions c1 and c2 for the location of the cylinder axes can be specified as a equal-style variable. For style -*cone* all properties can be defined via equal-style variables. For +*cone* and *prism* all properties can be defined via equal-style variables. For style *plane* the point can be defined via equal-style variables. If the value is a variable, it should be specified as v_name, where diff --git a/doc/src/region2vmd.rst b/doc/src/region2vmd.rst new file mode 100644 index 0000000000..6cea199760 --- /dev/null +++ b/doc/src/region2vmd.rst @@ -0,0 +1,183 @@ +.. index:: region2vmd + +region2vmd command +================== + +Syntax +"""""" + +.. code-block:: LAMMPS + + region2vmd file keyword arg ... + +* filename = name of file to write VMD script commands to +* zero or more keyword/arg pairs may be appended +* keyword = *region* or *color* or *material* or *command* + + .. parsed-literal:: + + *region* region-ID = name of region to translate to VMD graphics + *color* color-name = set color for following visualized objects + *material* material-name = set material for following visualized objects + *command* string = string with custom VMD script command (in quotes) + +Examples +"""""""" + +.. code-block:: LAMMPS + + region2vmd regions.vmd material Opaque color red region c1 color green region c2 + region2vmd vizbox.vmd command "mol new system.lammpstrj waitfor all" region box + region2vmd regdefs.vmd region upper region lower region hole + +Description +""""""""""" + +.. versionadded:: TBD + +Write a `VMD `_ Tcl script file with +commands that aim to create a visualization of :doc:`regions `. +There may be multiple region visualizations stored in a single file. + +The visualization is implemented by creating a new (and empty) "VMD +molecule" and then assigning a sequence of VMD graphics primitives to +represent the region in VMD. Each region will be stored in a separate +"VMD molecule" with the name "LAMMPS region ". + +The *region2vmd* command is following by the filename for the resulting +VMD script and an arbitrary number of keyword argument pairs to either +write out a new *region* visualization, change the *color* or *material* +setting, or to insert arbitrary VMD script *command*\ s. The keywords +and arguments are processed in sequence. + +The *region* keyword must be followed by a previously defined LAMMPS +:doc:`region `. Only a limited set region styles and region +settings are currently supported. See **Restrictions** below. +Unsupported region styles or regions with unsupported settings will be +skipped and a corresponding message is printed. + +The *color* keyword must be followed by a color name that is defined in +VMD. This color will be used by all following region visualizations. +The default setting is 'silver'. VMD has the following colors +pre-defined: + +.. table_from_list:: + :columns: 11 + + * blue + * red + * gray + * orange + * yellow + * tan + * silver + * green + * white + * pink + * cyan + * purple + * lime + * mauve + * ochre + * iceblue + * black + * yellow2 + * yellow3 + * green2 + * green3 + * cyan2 + * cyan3 + * blue2 + * blue3 + * violet + * violet2 + * magenta + * magenta2 + * red2 + * red3 + * orange2 + * orange3 + +The *material* keyword must be followed by a material name that is defined in +VMD. This material will be used by all following visualizations. The +default setting is 'Transparent'. VMD has the following materials +pre-defined: + +.. table_from_list:: + :columns: 8 + + * Opaque + * Transparent + * BrushedMetal + * Diffuse + * Ghost + * Glass1 + * Glass2 + * Glass3 + * Glossy + * HardPlastic + * MetallicPastel + * Steel + * Translucent + * Edgy + * EdgyShiny + * EdgyGlass + * Goodsell + * AOShiny + * AOChalky + * AOEdgy + * BlownGlass + * GlassBubble + * RTChrome + +The *command* keyword must be followed by a VMD script command as a +single string in quotes. This VMD command will be directly inserted +into the created VMD script. + +The created file can be loaded into VMD either from the command line +with the '-e' flag, or from the command prompt with 'play