diff --git a/.github/release_steps.md b/.github/release_steps.md index 71388e115a..857acfdb85 100644 --- a/.github/release_steps.md +++ b/.github/release_steps.md @@ -28,14 +28,14 @@ Create a 'next\_release' branch off 'develop' and make the following changes: ..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). +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 bugfix pull +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 @@ -56,7 +56,7 @@ 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 ``` @@ -77,7 +77,7 @@ 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" dropdown list. Go to the bottom of the list and select the "Set +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. @@ -87,12 +87,18 @@ you can return to edit the release page and publish it. ### Prepare pre-compiled packages, update packages to GitHub -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. A suitable build environment is provided with the -https://download.lammps.org/static/fedora37_musl.sif container image. +https://download.lammps.org/static/fedora41_musl_mingw.sif container +image. The corresponding container build definition file is maintained +in the tools/singularity folder of the LAMMPS source distribution. + +#### Fully portable static Linux x86_64 non-MPI binaries + +The following commands use the Fedora container to build a fully static +LAMMPS installation using a musl-libc cross-compiler, install it into a +`lammps-static` folder, and create a tarball called +`lammps-linux-x86_64-4Feb2025.tar.gz` (or using a corresponding date +with a future release) from the `lammps-static` folder. ``` sh rm -rf release-packages @@ -105,49 +111,173 @@ cmake -S lammps-release/cmake -B build-release -G Ninja -D CMAKE_INSTALL_PREFIX= 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-19Nov2024.tar.gz lammps-static +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: -``` -gh release upload patch_19Nov2024 lammps-linux-x86_64-19Nov2024.tar.gz +``` 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 cannot be used from the container) and build a +installed locally (they require binaries that run with elevated +privileges and thus cannot be used from the container) and build a LAMMPS and LAMMPS-GUI flatpak bundle in the `release-packages` folder with: ``` sh +cd release-packages flatpak --user remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo flatpak-builder --force-clean --verbose --repo=$PWD/flatpak-repo --install-deps-from=flathub --state-dir=$PWD --user --ccache --default-branch=release flatpak-build lammps-release/tools/lammps-gui/org.lammps.lammps-gui.yml -flatpak build-bundle --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo --verbose $PWD/flatpak-repo LAMMPS-Linux-x86_64-GUI-19Nov2024.flatpak org.lammps.lammps-gui release +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: -``` -gh release upload patch_19Nov2024 LAMMPS-Linux-x86_64-GUI-19Nov2024.flatpak +``` sh +gh release upload patch_4Feb2025 LAMMPS-Linux-x86_64-GUI-4Feb2025.flatpak ``` -Also build serial executable packages that also include LAMMPS-GUI for -Linux, macOS, and Windows, and upload them to the GitHub release. +#### LAMMPS Source tarball -Clean up: +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 ``` -TODO: -- add detailed commands for building GUI packages on Ubuntu 20.04LTS (move to 22.04LTS?), - macOS, and Windows cross-compiler and upload to GitHub -- build all Windows cross-compiled installer packages using lammps-packages repo +#### Build Multi-arch App-bundle for macOS -### Update download website +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 @@ -156,7 +286,7 @@ 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. -Notify Steve of the release so he can update `src/bug.txt` on the +Also notify Steve of the release so he can update `src/bug.txt` on the website from the available release notes. ## LAMMPS Stable Release 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/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/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/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/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