diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a920a25f1d5..c3b3ddbce19 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -3,191 +3,179 @@ # Order matters, the last match has the highest precedence # library folders -lib/colvars/* @giacomofiorin -lib/compress/* @akohlmey -lib/kokkos/* @stanmoore1 -lib/molfile/* @akohlmey -lib/qmmm/* @akohlmey -lib/vtk/* @rbberger -lib/kim/* @ellio167 -lib/mesont/* @iafoss +/lib/colvars/ @giacomofiorin +/lib/gpu/ @ndtrung81 +/lib/kokkos/ @stanmoore1 +/lib/linalg/ @akohlmey +/lib/molfile/ @akohlmey +/lib/qmmm/ @akohlmey # whole packages -src/ADIOS/* @pnorbert -src/AMOEBA/* @sjplimp -src/BPM/* @jtclemm -src/BROWNIAN/* @samueljmcameron -src/CG-DNA/* @ohenrich -src/CG-SPICA/* @yskmiyazaki -src/COLVARS/* @giacomofiorin -src/COMPRESS/* @rbberger -src/DIELECTRIC/* @ndtrung81 -src/ELECTRODE/* @ludwig-ahrens -src/FEP/* @agiliopadua -src/GPU/* @ndtrung81 -src/GRANULAR/* @jtclemm @dsbolin -src/INTEL/* @wmbrownintel -src/KIM/* @ellio167 -src/KOKKOS/* @stanmoore1 -src/LATTE/* @cnegre -src/MANIFOLD/* @Pakketeretet2 -src/MDI/* @taylor-a-barnes @sjplimp -src/MEAM/* @martok -src/MESONT/* @iafoss -src/ML-HDNNP/* @singraber -src/ML-IAP/* @athomps -src/ML-PACE/* @yury-lysogorskiy -src/ML-POD/* @exapde -src/ML-UF3/* @monk-04 -src/MOFFF/* @hheenen -src/MOLFILE/* @akohlmey -src/NETCDF/* @pastewka -src/OPENMP/* @akohlmey -src/PHONON/* @lingtikong -src/PLUGIN/* @akohlmey -src/PLUMED/* @gtribello -src/PTM/* @pmla -src/QMMM/* @akohlmey -src/REACTION/* @jrgissing -src/REAXFF/* @hasanmetin @stanmoore1 -src/RHEO/* @jtclemm -src/SCAFACOS/* @rhalver -src/SNAP/* @athomps -src/SPIN/* @julient31 -src/TALLY/* @akohlmey -src/UEF/* @danicholson -src/VTK/* @rbberger +/src/ADIOS/ @pnorbert +/src/AMOEBA/ @sjplimp +/src/BPM/ @jtclemm +/src/BROWNIAN/ @samueljmcameron +/src/CG-DNA/ @ohenrich +/src/CG-SPICA/ @yskmiyazaki +/src/COLVARS/ @giacomofiorin +/src/DIELECTRIC/ @ndtrung81 +/src/ELECTRODE/ @ludwig-ahrens @srtee +/src/FEP/ @agiliopadua +/src/GPU/ @ndtrung81 +/src/GRANULAR/ @jtclemm @dsbolin +/src/INTEL/ @wmbrownintel +/src/KIM/ @ellio167 +/src/KOKKOS/ @stanmoore1 +/src/MANIFOLD/ @Pakketeretet2 +/src/MDI/ @taylor-a-barnes @sjplimp +/src/MEAM/ @martok +/src/MESONT/ @iafoss +/src/ML-HDNNP/ @singraber +/src/ML-IAP/ @athomps +/src/ML-PACE/ @yury-lysogorskiy +/src/ML-POD/ @exapde +/src/ML-UF3/ @monk-04 +/src/MOFFF/ @hheenen +/src/MOLFILE/ @akohlmey +/src/NETCDF/ @pastewka +/src/OPENMP/ @akohlmey +/src/PHONON/ @lingtikong +/src/PLUGIN/ @akohlmey +/src/PLUMED/ @gtribello +/src/PTM/ @pmla +/src/QMMM/ @akohlmey +/src/REACTION/ @jrgissing +/src/REAXFF/ @hasanmetin @stanmoore1 +/src/RHEO/ @jtclemm +/src/SCAFACOS/ @rhalver +/src/SNAP/ @athomps +/src/SPIN/ @julient31 +/src/TALLY/ @akohlmey +/src/UEF/ @danicholson # individual files in packages -src/GPU/pair_vashishta_gpu.* @andeplane -src/KOKKOS/pair_vashishta_kokkos.* @andeplane @stanmoore1 -src/KOSSOS/pair_pod_kokkos.* @exapde @stanmoore1 -src/MANYBODY/pair_vashishta_table.* @andeplane -src/MANYBODY/pair_atm.* @sergeylishchuk -src/MANYBODY/pair_nb3b_screened.* @flodesani -src/REPLICA/*_grem.* @dstelter92 -src/EXTRA-COMMAND/geturl.* @akohlmey -src/EXTRA-COMMAND/group_ndx.* @akohlmey -src/EXTRA-COMMAND/ndx_group.* @akohlmey -src/EXTRA-COMPUTE/compute_stress_mop*.* @RomainVermorel -src/EXTRA-COMPUTE/compute_born_matrix.* @Bibobu @athomps -src/EXTRA-DUMP/dump_extxyz.* @fxcoudert -src/EXTRA-FIX/fix_deform_pressure.* @jtclemm -src/EXTRA-PAIR/pair_dispersion_d3.* @soniasalomoni @arthurfl -src/EXTRA-PAIR/d3_parameters.h @soniasalomoni @arthurfl -src/MISC/*_tracker.* @jtclemm -src/MC/fix_gcmc.* @athomps -src/MC/fix_sgcmc.* @athomps -src/REAXFF/compute_reaxff_atom.* @rbberger -src/KOKKOS/compute_reaxff_atom_kokkos.* @rbberger -src/REPLICA/fix_pimd_langevin.* @Yi-FanLi -src/DPD-BASIC/pair_dpd_coul_slater_long.* @Eddy-Barraud -src/GPU/pair_dpd_coul_slater_long.* @Eddy-Barraud +/src/GPU/pair_vashishta_gpu.* @andeplane +/src/KOKKOS/pair_vashishta_kokkos.* @andeplane @stanmoore1 +/src/KOSSOS/pair_pod_kokkos.* @exapde @stanmoore1 +/src/MANYBODY/pair_vashishta_table.* @andeplane +/src/MANYBODY/pair_atm.* @sergeylishchuk +/src/MANYBODY/pair_nb3b_screened.* @flodesani +/src/REPLICA/*_grem.* @dstelter92 +/src/EXTRA-COMMAND/geturl.* @akohlmey +/src/EXTRA-COMMAND/group_ndx.* @akohlmey +/src/EXTRA-COMMAND/ndx_group.* @akohlmey +/src/EXTRA-COMPUTE/compute_stress_mop*.* @RomainVermorel +/src/EXTRA-COMPUTE/compute_born_matrix.* @Bibobu @athomps +/src/EXTRA-DUMP/dump_extxyz.* @fxcoudert @akohlmey +/src/EXTRA-FIX/fix_deform_pressure.* @jtclemm +/src/EXTRA-PAIR/pair_dispersion_d3.* @soniasalomoni @arthurfl +/src/EXTRA-PAIR/d3_parameters.h @soniasalomoni @arthurfl +/src/MISC/*_tracker.* @jtclemm +/src/MC/fix_gcmc.* @athomps +/src/MC/fix_sgcmc.* @athomps +/src/REAXFF/compute_reaxff_atom.* @rbberger +/src/KOKKOS/compute_reaxff_atom_kokkos.* @rbberger +/src/REPLICA/fix_pimd_langevin.* @Yi-FanLi +/src/DPD-BASIC/pair_dpd_coul_slater_long.* @Eddy-Barraud +/src/GPU/pair_dpd_coul_slater_long.* @Eddy-Barraud # core LAMMPS classes -src/lammps.* @sjplimp -src/pointers.h @sjplimp -src/atom.* @sjplimp -src/atom_vec.* @sjplimp -src/angle.* @sjplimp -src/bond.* @sjplimp -src/comm*.* @sjplimp -src/compute.* @sjplimp -src/dihedral.* @sjplimp -src/domain.* @sjplimp @stanmoore1 -src/dump*.* @sjplimp -src/error.* @sjplimp -src/finish.* @sjplimp -src/fix.* @sjplimp -src/force.* @sjplimp -src/group.* @sjplimp -src/improper.* @sjplimp -src/info.* @akohlmey -src/kspace.* @sjplimp -src/lmptype.h @sjplimp -src/label_map.* @jrgissing @akohlmey -src/library.* @sjplimp @akohlmey -src/main.cpp @sjplimp -src/min_*.* @sjplimp -src/memory.* @sjplimp -src/modify.* @sjplimp @stanmoore1 -src/molecule.* @sjplimp @akohlmey -src/my_page.h @sjplimp -src/my_pool_chunk.h @sjplimp -src/npair*.* @sjplimp @jtclemm -src/ntopo*.* @sjplimp @jtclemm -src/nstencil*.* @sjplimp @jtclemm -src/neighbor.* @sjplimp @jtclemm -src/nbin*.* @sjplimp @jtclemm -src/neigh_*.* @sjplimp @jtclemm -src/output.* @sjplimp -src/pair.* @sjplimp -src/rcb.* @sjplimp -src/random_*.* @sjplimp -src/region*.* @sjplimp -src/rcb.* @sjplimp -src/read*.* @sjplimp -src/rerun.* @sjplimp -src/run.* @sjplimp -src/respa.* @sjplimp -src/set.* @sjplimp -src/special.* @sjplimp -src/suffix.h @sjplimp -src/thermo.* @sjplimp -src/universe.* @sjplimp -src/update.* @sjplimp -src/variable.* @sjplimp -src/velocity.* @sjplimp -src/write_data.* @sjplimp -src/write_restart.* @sjplimp -src/write_molecule.* @akohlmey +/src/lammps.* @sjplimp +/src/pointers.h @sjplimp +/src/atom.* @sjplimp +/src/atom_vec.* @sjplimp +/src/angle.* @sjplimp +/src/bond.* @sjplimp +/src/comm*.* @sjplimp +/src/compute.* @sjplimp +/src/dihedral.* @sjplimp +/src/domain.* @sjplimp @stanmoore1 +/src/dump*.* @sjplimp +/src/error.* @sjplimp +/src/finish.* @sjplimp +/src/fix.* @sjplimp +/src/force.* @sjplimp +/src/group.* @sjplimp +/src/improper.* @sjplimp +/src/info.* @akohlmey +/src/kspace.* @sjplimp +/src/lmptype.h @sjplimp +/src/label_map.* @jrgissing @akohlmey +/src/library.* @sjplimp @akohlmey +/src/main.cpp @sjplimp +/src/min_*.* @sjplimp +/src/memory.* @sjplimp +/src/modify.* @sjplimp @stanmoore1 +/src/molecule.* @sjplimp @akohlmey +/src/my_page.h @sjplimp +/src/my_pool_chunk.h @sjplimp +/src/npair*.* @sjplimp @jtclemm +/src/ntopo*.* @sjplimp @jtclemm +/src/nstencil*.* @sjplimp @jtclemm +/src/neighbor.* @sjplimp @jtclemm +/src/nbin*.* @sjplimp @jtclemm +/src/neigh_*.* @sjplimp @jtclemm +/src/output.* @sjplimp +/src/pair.* @sjplimp +/src/rcb.* @sjplimp +/src/random_*.* @sjplimp +/src/region*.* @sjplimp +/src/rcb.* @sjplimp +/src/read*.* @sjplimp +/src/rerun.* @sjplimp +/src/run.* @sjplimp +/src/respa.* @sjplimp +/src/set.* @sjplimp +/src/special.* @sjplimp +/src/suffix.h @sjplimp +/src/thermo.* @sjplimp +/src/universe.* @sjplimp +/src/update.* @sjplimp +/src/variable.* @sjplimp +/src/velocity.* @sjplimp +/src/write_data.* @sjplimp +/src/write_restart.* @sjplimp +/src/write_molecule.* @akohlmey # overrides for specific files -src/dump_movie.* @akohlmey -src/exceptions.h @rbberger -src/fix_nh.* @athomps -src/info.* @akohlmey @rbberger -src/min* @sjplimp @stanmoore1 -src/platform.* @akohlmey -src/timer.* @akohlmey -src/utils.* @akohlmey @rbberger -src/verlet.* @sjplimp @stanmoore1 -src/math_eigen_impl.h @jewettaij -src/fix_press_langevin.* @Bibobu +/src/dump_movie.* @akohlmey +/src/fix_nh.* @athomps +/src/info.* @akohlmey +/src/min* @sjplimp @stanmoore1 +/src/platform.* @akohlmey +/src/timer.* @akohlmey +/src/utils.* @akohlmey +/src/verlet.* @sjplimp @stanmoore1 +/src/math_eigen_impl.h @jewettaij +/src/fix_press_langevin.* @Bibobu # tools -tools/coding_standard/* @akohlmey @rbberger -tools/emacs/* @HaoZeke -tools/lammps-shell/* @akohlmey -tools/msi2lmp/* @akohlmey -tools/offline/* @rbberger -tools/singularity/* @akohlmey @rbberger -tools/swig/* @akohlmey -tools/valgrind/* @akohlmey -tools/vim/* @hammondkd +/tools/coding_standard/ @akohlmey +/tools/emacs/ @HaoZeke +/tools/singularity/ @akohlmey +/tools/swig/ @akohlmey +/tools/valgrind/ @akohlmey +/tools/vim/ @hammondkd # tests -unittest/* @akohlmey +/unittest/ @akohlmey # cmake -cmake/* @akohlmey -cmake/Modules/LAMMPSInterfacePlugin.cmake @akohlmey -cmake/Modules/MPI4WIN.cmake @akohlmey -cmake/Modules/OpenCLLoader.cmake @akohlmey -cmake/Modules/Packages/COLVARS.cmake @giacomofiorin -cmake/Modules/Packages/KIM.cmake @ellio167 -cmake/presets/*.cmake @akohlmey +/cmake/ @akohlmey +/cmake/Modules/Packages/COLVARS.cmake @giacomofiorin +/cmake/Modules/Packages/KIM.cmake @ellio167 # python -python/* @rbberger +/python/ @akohlmey +/python/ipython/ @rbberger # fortran -fortran/* @akohlmey @hammondkd +/fortran/ @akohlmey @hammondkd # docs -doc/* @akohlmey -examples/plugin/* @akohlmey -examples/PACKAGES/pace/plugin/* @akohlmey +/doc/* @akohlmey +/examples/plugin/ @akohlmey +/examples/PACKAGES/pace/plugin/ @akohlmey # for releases -src/version.h @sjplimp +/src/version.h @sjplimp diff --git a/.github/build_tarball.sh b/.github/build_tarball.sh new file mode 100644 index 00000000000..3a5e67f684c --- /dev/null +++ b/.github/build_tarball.sh @@ -0,0 +1,35 @@ +#!/bin/bash + +if [ $# -ne 1 ] +then + echo "usage: $0 " + exit 1 +fi + +# check out desired LAMMPS version +git checkout $1 + +# make sure we are in the LAMMPS root directory +if [ ! -e README ] || [ ! -e LICENSE ] || [ ! -e SECURITY.md ] || [ ! -e CITATION.cff ] +then + echo "Must be in the LAMMPS root folder to run this script" + exit 2 +fi + +# get version for filename +lammps_release_tag=$(git describe --tags --abbrev=0 | cut -d_ -f2) + +# update docenv +make -C doc clean-all +make -C doc html || exit 3 +make -C doc pdf || exit 4 + +# extract initial release tarball from git sources +tarball=lammps-src-${lammps_release_tag}.tar +rm -vf ${tarball} ${tarball}.gz +git archive --output=${tarball} --prefix=lammps-${lammps_release_tag}/ HEAD +mkdir -p lammps-${lammps_release_tag}/doc +mv -v doc/html doc/Manual.pdf lammps-${lammps_release_tag}/doc +tar -rf ${tarball} lammps-${lammps_release_tag}/doc +gzip -9v ${tarball} +rm -r lammps-${lammps_release_tag} diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index d3b7b8e6a1d..f0326c685e9 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -314,16 +314,140 @@ to LAMMPS in https://docs.lammps.org/Modify_requirements.html When performing a code review, apply the programming style instructions for LAMMPS in https://docs.lammps.org/Modify_style.html -When performing a code review, check any changes to the documentation (in the -`doc/src/` folder) to be written in American English and with plain ASCII characters. +When performing a code review, check any changes to the documentation +(in the `doc/src/` folder) to be written in American English and with +plain ASCII characters. When performing a code review, ensure that the documentation for any new -commands or added keywords to existing commands contains a `.. versionadded:: TBD` -directive. For any modified commands or keywords a `.. versionchanged:: TBD` -directive should be included in the documentation. Check if any examples use -the new or modified commands and check if they need updating. Ensure that -building the documentation with "make html", "make pdf", and "make spelling" -can complete and does *NOT* produce any *NEW* warnings or errors. +commands or added keywords to existing commands contains a +`.. versionadded:: TBD` directive. For any modified commands or +keywords a `.. versionchanged:: TBD` directive should be included in the +documentation. Check if any examples use the new or modified commands +and check if they need updating. + +When reviewing C++ code, ensure that no alternative tokens are used for +logical operators. That is, use `&&` instead of `and`, `||` instead of +`or`, `!` instead of 'not', `^` instead of `xor` and so on. These +alternative tokens are only required for ASCII text in some non +US-English characters sets, but the LAMMPS sources code are *supposed* +be in US-English 7-bit ASCII. Using alternative tokens causes +compilation failures with some compilers by default, most prominently +Microsoft Visual C++. + +When new files are added to package directories in `src`, make sure +they are added to the `src/.gitignore` file, so that the copies in +`src` make by the traditional make build system are not accidentally +added to the git repository. + +Whe files are renamed or removed from package directories in `src`, +make sure the old file names are added the `src/Purge.list` file so +their copies from the traditional make build system are properly +removed with "make purge". + +## Documentation Changes + +When modifying documentation files in `doc/src/`: + +**Build and validate documentation:** +```bash +cd doc +make html # Build HTML, check for warnings +make pdf # Build PDF (requires pdflatex) +make spelling # Check spelling +make anchor_check # Check for duplicate anchors +make style_check # Verify style lists are complete +``` + +Ensure that building the documentation with "make html" and "make pdf" +can complete and does *NOT* produce any errors or warnings about sphinx +or docutils syntax issues or incorrect references. + +Also make certain that "make spelling" does not report in any spelling +issues; those need to be either remedied or exceptions (e.g. for code +examples or author names of cited references) should be added to the +file "doc/utils/sphinx-config/false-positives.txt". + +**Documentation conventions:** +- Use reStructuredText format (`.rst` files) +- Use American English spelling +- Use ASCII characters only +- Wrap code examples in `.. code-block::` with appropriate language (LAMMPS, bash, c++, python) +- Use `.. note::` for important remarks and `.. warning::` for critical warnings +- New commands require `.. versionadded:: TBD` +- Modified commands require `.. versionchanged:: TBD` + +## Debugging CI Failures + +When a CI check fails, diagnose using these steps: + +**1. Style check failures (`style-check.yml`):** +```bash +cd src +make check-whitespace # Most common - fix with: make fix-whitespace +make check-permissions # Fix with: make fix-permissions +make check-homepage # Verify https://www.lammps.org URLs +make check-errordocs # Check error documentation +make check-fmtlib # Verify fmtlib formatting +``` + +**2. Build failures:** +- Check CMake output for missing dependencies +- Ensure `-S cmake` (not `-S .`) is used +- Verify package dependencies are met +- Check for VLA (variable-length array) usage - not allowed + +**3. Unit test failures:** +- Run specific failing test: `cd build && ctest -V -R ` +- Check if test requires specific packages to be enabled +- Verify the executable was built before running tests + +**4. Regression test failures:** +- Ensure Python environment has numpy, pyyaml, junit_xml +- Check if example inputs were modified correctly + +## Short-Circuit Instructions + +**STOP and check these common mistakes:** + +1. **Wrong CMake source directory:** + - WRONG: `cmake -S . -B build` + - CORRECT: `cmake -S cmake -B build` + +2. **Building in source tree:** + - NEVER run cmake or make in the repository root + - ALWAYS create a separate `build/` directory + +3. **Mixed build systems:** + - If switching from Make to CMake: run `make -C src purge` first + - If switching from CMake to Make: run `make -C src clean-all` first + +4. **Unicode in source files:** + - All source code must be ASCII only + - Unicode characters will cause CI to fail + +5. **Missing whitespace fixes:** + - Always run `cd src && make fix-whitespace` before committing + +6. **Incorrect file permissions:** + - `.cpp` and `.h` files must NOT be executable + - `.sh` and `.py` scripts SHOULD be executable + +## Sample Prompts + +**Adding a new pair style:** +> "Create a new pair style called `pair_example` that implements [description]. Follow the pattern in `src/pair_lj_cut.cpp` and add documentation in `doc/src/pair_example.rst`." + +**Fixing a bug in a compute:** +> "Fix bug in `compute_temp.cpp` where [description]. Add a unit test in `unittest/` to prevent regression." + +**Adding a new package:** +> "Create a new package called MYPACKAGE with [features]. Include CMakeLists.txt entries, documentation, and example inputs." + +**Updating documentation:** +> "Update the documentation for `fix_nve.rst` to include the new `keyword` option. Use `.. versionchanged:: TBD` directive." + +**Debugging build failure:** +> "The CI build is failing with [error]. Diagnose and fix the issue." ## Trust These Instructions diff --git a/.github/release_steps.md b/.github/release_steps.md index 4ecd05d0433..6a3bda821cf 100644 --- a/.github/release_steps.md +++ b/.github/release_steps.md @@ -33,10 +33,14 @@ 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. +and cleared. We currently use automated tests with GitHub workflows. +There is also a Coverity Scan run with static code analysis done every +thursday evening or when triggered manually. That output should be +checked for any significant issues before a release, too. In addition +there is a nightly static code analysis run that can be checked at +https://downloads.lammps.org/analysis/ +If needed, a bug-fix pull request should be created and merged to clear +pending issues. ### Create release on GitHub @@ -45,9 +49,9 @@ cleared testing, the 'next\_release' branch is merged into 'develop'. Check out or update the 'develop' branch locally, pull the latest changes, merge them into 'release' with a fast forward(!) merge, and -apply a suitable release tag (for historical reasons the tag starts with -"patch_" followed by the date, and finally push everything back to -GitHub. There should be no commits made to 'release' but only +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: ``` @@ -60,17 +64,20 @@ git tag -s -m "LAMMPS feature release 4 February 2025" patch_4Feb2025 git push git@github.com:lammps/lammps.git --tags develop release ``` -Applying this tag will trigger two actions on the Temple Jenkins cluster: -- The online manual at https://docs.lammps.org/ will be updated to the +After applying this tag two steps will need to be executed manually +(they used to be run automatically, but this is currently not available). +- The online manual at https://docs.lammps.org/ needs to 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 + html format documentation and a PDF of the manual needs to 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. + so it is not yet publicly visible. The index file is updated manually + with a local script after symlinks and SHASUM files have been updated + as well. 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 @@ -81,9 +88,17 @@ 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. +Releases are now "immutable", so neither the tag hash nor any uploaded +assets can be changed after the release is published. Only the +release notes text may be changed, e.g. to document issues with the +uploaded assets. + +Thus only when *everything* is in order *and* all required assets (source, +binary packages for different platforms, manual PDF) are uploaded in +a suitable version, 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, update assets, and publish it when +it is ready. ### Prepare pre-compiled packages, update packages to GitHub diff --git a/.github/update_release_docs.sh b/.github/update_release_docs.sh new file mode 100644 index 00000000000..0ef93404229 --- /dev/null +++ b/.github/update_release_docs.sh @@ -0,0 +1,27 @@ +#!/bin/bash + +# check out LAMMPS release version +git checkout release || exit 1 + +# make sure we are in the LAMMPS root directory +if [ ! -e README ] || [ ! -e LICENSE ] || [ ! -e SECURITY.md ] || [ ! -e CITATION.cff ] +then + echo "Must be in the LAMMPS root folder to run this script" + exit 2 +fi + +export LC_ALL=C +export webserver=publish@www.lammps.org +export webroot=/var/www/lammps/download +export docroot=/var/www/lammps/docs + +# build documentation using its own virtual environment +export LAMMPS_WEBSITE_BUILD=1 +export LAMMPS_WEBSITE_BUILD_VERSION=release +export LAMMPS_WEBSITE_BASEURL="https://docs.lammps.org/release/" +make -C doc clean +make -C doc upgrade +make -C doc html WEB_SEARCH=YES +make -C doc pdf +rsync -arp doc/html/* ${webserver}:${docroot}/release/ +rsync -p doc/Manual.pdf ${webserver}:${docroot}/release/ diff --git a/.github/workflows/check-cpp23.yml b/.github/workflows/check-cpp23.yml index dfda1a4da83..e1ef0a0fc02 100644 --- a/.github/workflows/check-cpp23.yml +++ b/.github/workflows/check-cpp23.yml @@ -5,6 +5,7 @@ on: push: branches: - develop + - maintenance pull_request: branches: - develop @@ -29,7 +30,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 2 @@ -61,7 +62,7 @@ jobs: - name: Building LAMMPS via CMake shell: bash run: | - ccache -z + ccache -z -M 3 python3 -m venv linuxenv source linuxenv/bin/activate python3 -m pip install numpy diff --git a/.github/workflows/check-gnu-make.yml b/.github/workflows/check-gnu-make.yml new file mode 100644 index 00000000000..a6727f02003 --- /dev/null +++ b/.github/workflows/check-gnu-make.yml @@ -0,0 +1,66 @@ +# GitHub action to build LAMMPS on Linux with traditional build system +name: "Check legacy GNU Make build" + +on: + push: + branches: + - develop + - maintenance + pull_request: + branches: + - develop + + workflow_dispatch: + +jobs: + build: + name: Build with GNU Make + if: ${{ github.repository == 'lammps/lammps' }} + runs-on: ubuntu-latest + env: + CCACHE_DIR: ${{ github.workspace }}/.ccache + + steps: + - name: Checkout repository + uses: actions/checkout@v6 + with: + fetch-depth: 2 + + - name: Install extra Linux packages + run: | + sudo apt-get update + sudo apt-get install -y ccache \ + libeigen3-dev \ + libcurl4-openssl-dev \ + mpi-default-bin \ + mpi-default-dev + + - name: Set up ccache + uses: actions/cache@v4 + with: + path: ${{ env.CCACHE_DIR }} + key: linux-gnu-ccache-${{ github.sha }} + restore-keys: linux-gnu-ccache- + + - name: Install optional LAMMPS packages + shell: bash + working-directory: src + run: make yes-most + + - name: Building LAMMPS with GNU Make + shell: bash + working-directory: src + run: | + ccache -z -M 3 + make -j2 CC="ccache g++" serial + make -j2 CC="ccache mpicxx" mpi + ccache -s + + - name: Running serial LAMMPS + shell: bash + run: ./src/lmp_serial -in bench/in.lj -log none -nocite + + - name: Running parallel LAMMPS + shell: bash + run: mpirun -np 2 ./src/lmp_mpi -in bench/in.lj -log none -nocite + diff --git a/.github/workflows/check-vla.yml b/.github/workflows/check-vla.yml index b08985442f6..6efe93ccfaf 100644 --- a/.github/workflows/check-vla.yml +++ b/.github/workflows/check-vla.yml @@ -5,6 +5,7 @@ on: push: branches: - develop + - maintenance pull_request: branches: - develop @@ -21,7 +22,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 2 @@ -50,7 +51,7 @@ jobs: - name: Building LAMMPS via CMake shell: bash run: | - ccache -z + ccache -z -M 3 python3 -m venv linuxenv source linuxenv/bin/activate python3 -m pip install numpy diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index dfa9bb159fc..66668e4a5df 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -25,7 +25,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 2 diff --git a/.github/workflows/compile-msvc.yml b/.github/workflows/compile-msvc.yml index 5e525678acc..3895dd8b578 100644 --- a/.github/workflows/compile-msvc.yml +++ b/.github/workflows/compile-msvc.yml @@ -5,6 +5,7 @@ on: push: branches: - develop + - maintenance pull_request: branches: - develop @@ -25,7 +26,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 2 @@ -52,7 +53,7 @@ jobs: - name: Building LAMMPS via CMake run: | - ccache -z + ccache -z -M 3 python3 -m pip install numpy python3 -m pip install pyyaml cmake -C cmake\presets\windows.cmake -D CMAKE_CXX_COMPILER=cl -D CMAKE_CXX_COMPILER_LAUNCHER=ccache -D CMAKE_C_COMPILER=cl -D CMAKE_C_COMPILER_LAUNCHER=ccache -D CMAKE_Fortran_COMPILER="" -D DOWNLOAD_POTENTIALS=off -D PKG_PYTHON=on -D WITH_PNG=off -D WITH_JPEG=off -S cmake -B build -D BUILD_SHARED_LIBS=on -D ENABLE_TESTING=on -D CMAKE_BUILD_TYPE=Release -G Ninja diff --git a/.github/workflows/coverity.yml b/.github/workflows/coverity.yml index 86a881094d6..27242a59940 100644 --- a/.github/workflows/coverity.yml +++ b/.github/workflows/coverity.yml @@ -16,7 +16,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 2 diff --git a/.github/workflows/full-regression.yml b/.github/workflows/full-regression.yml index 317b716377a..24218ec788f 100644 --- a/.github/workflows/full-regression.yml +++ b/.github/workflows/full-regression.yml @@ -23,7 +23,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 2 show-progress: false @@ -48,7 +48,7 @@ jobs: - name: Building LAMMPS via CMake shell: bash run: | - ccache -z + ccache -z -M 3 python3 -m venv linuxenv source linuxenv/bin/activate python3 -m pip install --upgrade pip diff --git a/.github/workflows/lammps-gui-flatpak.yml b/.github/workflows/lammps-gui-flatpak.yml index 8fe50f170ba..f250726b354 100644 --- a/.github/workflows/lammps-gui-flatpak.yml +++ b/.github/workflows/lammps-gui-flatpak.yml @@ -20,7 +20,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 2 diff --git a/.github/workflows/quick-regression.yml b/.github/workflows/quick-regression.yml index a640b5d8c07..c48102c96ec 100644 --- a/.github/workflows/quick-regression.yml +++ b/.github/workflows/quick-regression.yml @@ -27,7 +27,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 0 show-progress: false @@ -52,7 +52,7 @@ jobs: - name: Building LAMMPS via CMake shell: bash run: | - ccache -z + ccache -z -M 3 python3 -m venv linuxenv source linuxenv/bin/activate python3 -m pip install --upgrade pip diff --git a/.github/workflows/style-check.yml b/.github/workflows/style-check.yml index 12b4c6e2ab7..a34f1aabfd8 100644 --- a/.github/workflows/style-check.yml +++ b/.github/workflows/style-check.yml @@ -5,6 +5,7 @@ on: push: branches: - develop + - maintenance pull_request: branches: - develop @@ -23,7 +24,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 1 diff --git a/.github/workflows/unittest-arm64.yml b/.github/workflows/unittest-arm64.yml index d0038d73c87..7d331fd1f86 100644 --- a/.github/workflows/unittest-arm64.yml +++ b/.github/workflows/unittest-arm64.yml @@ -21,7 +21,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 2 @@ -48,7 +48,7 @@ jobs: - name: Building LAMMPS via CMake shell: bash run: | - ccache -z + ccache -z -M 3 python3 -m venv linuxenv source linuxenv/bin/activate python3 -m pip install numpy diff --git a/.github/workflows/unittest-linux.yml b/.github/workflows/unittest-linux.yml index e79c715d130..aa8e33e587d 100644 --- a/.github/workflows/unittest-linux.yml +++ b/.github/workflows/unittest-linux.yml @@ -5,6 +5,7 @@ on: push: branches: - develop + - maintenance pull_request: branches: - develop @@ -25,7 +26,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 2 @@ -52,7 +53,7 @@ jobs: - name: Building LAMMPS via CMake shell: bash run: | - ccache -z + ccache -z -M 3 python3 -m venv linuxenv source linuxenv/bin/activate python3 -m pip install numpy diff --git a/.github/workflows/unittest-macos.yml b/.github/workflows/unittest-macos.yml index e11c4e6ba4f..4ec010c35b4 100644 --- a/.github/workflows/unittest-macos.yml +++ b/.github/workflows/unittest-macos.yml @@ -5,6 +5,7 @@ on: push: branches: - develop + - maintenance pull_request: branches: - develop @@ -19,13 +20,13 @@ jobs: build: name: MacOS Unit Test if: ${{ github.repository == 'lammps/lammps' }} - runs-on: macos-13 + runs-on: macos-15-intel env: CCACHE_DIR: ${{ github.workspace }}/.ccache steps: - name: Checkout repository - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: fetch-depth: 2 @@ -46,7 +47,7 @@ jobs: shell: bash working-directory: build run: | - ccache -z + ccache -z -M 3 python3 -m venv macosenv source macosenv/bin/activate python3 -m pip install numpy diff --git a/.github/workflows/unittest-single.yml b/.github/workflows/unittest-single.yml new file mode 100644 index 00000000000..50baf51b474 --- /dev/null +++ b/.github/workflows/unittest-single.yml @@ -0,0 +1,80 @@ +# GitHub action to build LAMMPS on Linux and run standard unit tests +name: "Unittest for Linux /w -DFFT_SINGLE=ON" + +on: + push: + branches: + - develop + - maintenance + pull_request: + branches: + - develop + + workflow_dispatch: + +concurrency: + group: ${{ github.event_name }}-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{github.event_name == 'pull_request'}} + +jobs: + build: + name: Linux Unit Test + if: ${{ github.repository == 'lammps/lammps' }} + runs-on: ubuntu-latest + env: + CCACHE_DIR: ${{ github.workspace }}/.ccache + + steps: + - name: Checkout repository + uses: actions/checkout@v6 + with: + fetch-depth: 2 + + - name: Install extra packages + run: | + sudo apt-get update + sudo apt-get install -y ccache \ + libeigen3-dev \ + libcurl4-openssl-dev \ + mold \ + ninja-build \ + python3-dev + + - name: Create Build Environment + run: mkdir build + + - name: Set up ccache + uses: actions/cache@v4 + with: + path: ${{ env.CCACHE_DIR }} + key: linux-unit-ccache-${{ github.sha }} + restore-keys: linux-unit-ccache- + + - name: Building LAMMPS via CMake + shell: bash + run: | + ccache -z -M 3 + python3 -m venv linuxenv + source linuxenv/bin/activate + python3 -m pip install numpy + python3 -m pip install pyyaml + cmake -S cmake -B build \ + -C cmake/presets/gcc.cmake \ + -C cmake/presets/most.cmake \ + -C cmake/presets/nolib.cmake \ + -D CMAKE_CXX_COMPILER_LAUNCHER=ccache \ + -D CMAKE_C_COMPILER_LAUNCHER=ccache \ + -D BUILD_SHARED_LIBS=on \ + -D FFT=kiss \ + -D FFT_SINGLE=on \ + -D DOWNLOAD_POTENTIALS=off \ + -D ENABLE_TESTING=on \ + -D MLIAP_ENABLE_PYTHON=off \ + -G Ninja + cmake --build build + ccache -s + + - name: Run Tests + working-directory: build + shell: bash + run: ctest -V diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index c721487ea65..708c6d6a8b1 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -140,8 +140,8 @@ if((PKG_KOKKOS) AND (Kokkos_ENABLE_CUDA) AND (LAMMPS_CXX_COMPILER_NAME STREQUAL set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Xcudafe --diag_suppress=unrecognized_pragma,--diag_suppress=128,--diag_suppress=186") endif() -# We *require* C++17 without extensions -# Kokkos also requires at least C++17 (currently) +# we *require* C++17 without extensions +# Kokkos also requires at least C++20 (currently) if(NOT CMAKE_CXX_STANDARD) # uncomment in case we plan to switch to C++20 as minimum standard # if(cxx_std_20 IN_LIST CMAKE_CXX_COMPILE_FEATURES) @@ -153,8 +153,8 @@ endif() if(CMAKE_CXX_STANDARD LESS 17) message(FATAL_ERROR "C++ standard must be set to at least 17") endif() -if(PKG_KOKKOS AND (CMAKE_CXX_STANDARD LESS 17)) - set(CMAKE_CXX_STANDARD 17) +if(PKG_KOKKOS AND (CMAKE_CXX_STANDARD LESS 20)) + set(CMAKE_CXX_STANDARD 20) endif() # turn off C++20 check in lmptype.h #if(LAMMPS_CXX17) @@ -181,7 +181,7 @@ if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU") if (CMAKE_CXX_STANDARD GREATER_EQUAL 17) if (CMAKE_CXX_COMPILER_VERSION VERSION_LESS 9.3) message(WARNING "Using the GNU compilers version ${CMAKE_CXX_COMPILER_VERSION} with C++17 " - "or later is not recommended. Please use the GNU compilers version 9.3 or later") + "or later is not recommended. Please use GNU compilers version 9.3 or later") endif() endif() endif() @@ -514,12 +514,14 @@ if((CMAKE_CXX_COMPILER_ID STREQUAL "Intel") AND (CMAKE_CXX_STANDARD GREATER_EQUA PROPERTIES COMPILE_OPTIONS "-std=c++14") endif() +option(USE_INTERNAL_LINALG "Prefer internal library with BLAS/LAPACK subset over system BLAS/LAPACK" OFF) if(PKG_ML-QUIP OR PKG_ML-POD OR PKG_ELECTRODE OR PKG_RHEO OR BUILD_TOOLS) - if (NOT USE_INTERNAL_LINALG) + if(NOT USE_INTERNAL_LINALG) find_package(LAPACK) find_package(BLAS) endif() - if(NOT LAPACK_FOUND OR NOT BLAS_FOUND OR USE_INTERNAL_LINALG) + if((NOT LAPACK_FOUND) OR (NOT BLAS_FOUND) OR USE_INTERNAL_LINALG) + set(USE_INTERNAL_LINALG ON) file(GLOB LINALG_SOURCES CONFIGURE_DEPENDS ${LAMMPS_LIB_SOURCE_DIR}/linalg/[^.]*.cpp) add_library(linalg STATIC ${LINALG_SOURCES}) set_target_properties(linalg PROPERTIES OUTPUT_NAME lammps_linalg${LAMMPS_MACHINE}) @@ -777,16 +779,17 @@ if(_index GREATER -1) target_link_libraries(lammps PRIVATE ${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES}) endif() set(LAMMPS_CXX_HEADERS angle.h atom.h bond.h citeme.h comm.h command.h compute.h dihedral.h domain.h - error.h exceptions.h fix.h force.h group.h improper.h input.h info.h kspace.h lammps.h lattice.h - library.h lmppython.h lmptype.h memory.h modify.h neighbor.h neigh_list.h output.h pair.h - platform.h pointers.h region.h timer.h universe.h update.h utils.h variable.h) + error.h exceptions.h fix.h force.h group.h improper.h input.h info.h json.h json_fwd.h kspace.h + lammps.h lattice.h library.h lmppython.h lmptype.h memory.h modify.h neighbor.h neigh_list.h + output.h pair.h platform.h pointers.h region.h timer.h universe.h update.h utils.h variable.h) set(LAMMPS_FMT_HEADERS core.h format.h) +set(LAMMPS_JSON_HEADERS json_fwd.hpp json.hpp) set_target_properties(lammps PROPERTIES OUTPUT_NAME lammps${LAMMPS_MACHINE}) set_target_properties(lammps PROPERTIES SOVERSION ${SOVERSION}) set_target_properties(lammps PROPERTIES PREFIX "lib") -target_include_directories(lammps PUBLIC $) -file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/fmt) +target_include_directories(lammps PUBLIC $) +file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/fmt ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/nlohmann) foreach(_HEADER ${LAMMPS_CXX_HEADERS}) add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/${_HEADER} COMMAND ${CMAKE_COMMAND} -E copy_if_different ${LAMMPS_SOURCE_DIR}/${_HEADER} ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/${_HEADER} DEPENDS ${LAMMPS_SOURCE_DIR}/${_HEADER}) add_custom_target(${_HEADER} DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/${_HEADER}) @@ -803,6 +806,14 @@ foreach(_HEADER ${LAMMPS_FMT_HEADERS}) install(FILES ${LAMMPS_SOURCE_DIR}/fmt/${_HEADER} DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/lammps/fmt) endif() endforeach() +foreach(_HEADER ${LAMMPS_JSON_HEADERS}) + add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/nlohmann/${_HEADER} COMMAND ${CMAKE_COMMAND} -E copy_if_different ${LAMMPS_SOURCE_DIR}/nlohmann/${_HEADER} ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/nlohmann/${_HEADER} DEPENDS ${LAMMPS_SOURCE_DIR}/nlohmann/${_HEADER}) + add_custom_target(json_${_HEADER} DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/nlohmann/${_HEADER}) + add_dependencies(lammps json_${_HEADER}) + if(BUILD_SHARED_LIBS) + install(FILES ${LAMMPS_SOURCE_DIR}/nlohmann/${_HEADER} DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/lammps/nlohmann) + endif() +endforeach() target_include_directories(lammps INTERFACE $) add_library(LAMMPS::lammps ALIAS lammps) get_target_property(LAMMPS_DEFINES lammps INTERFACE_COMPILE_DEFINITIONS) @@ -825,7 +836,7 @@ if(BUILD_SHARED_LIBS) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/liblammps${LAMMPS_MACHINE}.pc DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig) install(EXPORT LAMMPS_Targets FILE LAMMPS_Targets.cmake NAMESPACE LAMMPS:: DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/LAMMPS) include(CMakePackageConfigHelpers) - configure_file(LAMMPSConfig.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/LAMMPSConfig.cmake @ONLY) + configure_file(LAMMPSConfig.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/LAMMPSConfig.cmake" @ONLY) write_basic_package_version_file("LAMMPSConfigVersion.cmake" VERSION ${PROJECT_VERSION} COMPATIBILITY ExactVersion) install(FILES "${CMAKE_CURRENT_BINARY_DIR}/LAMMPSConfig.cmake" "${CMAKE_CURRENT_BINARY_DIR}/LAMMPSConfigVersion.cmake" DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/LAMMPS) endif() diff --git a/cmake/LAMMPSConfig.cmake.in b/cmake/LAMMPSConfig.cmake.in index 0dacfc20896..70e2233deca 100644 --- a/cmake/LAMMPSConfig.cmake.in +++ b/cmake/LAMMPSConfig.cmake.in @@ -1,5 +1,22 @@ +# created by cmake version @CMAKE_VERSION@ for LAMMPS version @PROJECT_VERSION@ + include(CMakeFindDependencyMacro) if(@BUILD_MPI@) find_dependency(MPI REQUIRED CXX) endif() +if(@BUILD_OMP@) + find_dependency(OpenMP REQUIRED CXX) +endif() include("${CMAKE_CURRENT_LIST_DIR}/LAMMPS_Targets.cmake") +add_library(LAMMPS::LAMMPS ALIAS LAMMPS::lammps) + +get_target_property(LAMMPS_CONFIG LAMMPS::lammps IMPORTED_CONFIGURATIONS) +get_target_property(LAMMPS_LIBRARY LAMMPS::lammps IMPORTED_LOCATION_${LAMMPS_CONFIG}) +get_target_property(LAMMPS_INCLUDE_DIR LAMMPS::lammps INTERFACE_INCLUDE_DIRECTORIES) + +include(FindPackageHandleStandardArgs) +find_package_handle_standard_args(LAMMPS + REQUIRED_VARS LAMMPS_LIBRARY LAMMPS_INCLUDE_DIR + VERSION_VAR PACKAGE_VERSION + HANDLE_VERSION_RANGE +) diff --git a/cmake/Modules/Packages/GPU.cmake b/cmake/Modules/Packages/GPU.cmake index 592b7eff2a0..a9ae551df0d 100644 --- a/cmake/Modules/Packages/GPU.cmake +++ b/cmake/Modules/Packages/GPU.cmake @@ -154,8 +154,11 @@ if(GPU_API STREQUAL "CUDA") endif() endif() - cuda_compile_fatbin(GPU_GEN_OBJS ${GPU_LIB_CU} OPTIONS ${CUDA_REQUEST_PIC} - -DUNIX -O3 --use_fast_math -Wno-deprecated-gpu-targets -allow-unsupported-compiler -DNV_KERNEL -DUCL_CUDADR ${GPU_CUDA_GENCODE} -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES}) + set(NVCC_FLAGS -DUNIX -O3 --use_fast_math -Wno-deprecated-gpu-targets -allow-unsupported-compiler -DNV_KERNEL -DUCL_CUDADR ${GPU_CUDA_GENCODE} -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES}) + if(CUDPP_OPT) + string(APPEND NVCC_FLAGS " -DUSE_CUDPP") + endif() + cuda_compile_fatbin(GPU_GEN_OBJS ${GPU_LIB_CU} OPTIONS ${CUDA_REQUEST_PIC} ${NVCC_FLAGS}) cuda_compile(GPU_OBJS ${GPU_LIB_CUDPP_CU} OPTIONS ${CUDA_REQUEST_PIC} -DUNIX -O3 --use_fast_math -Wno-deprecated-gpu-targets -allow-unsupported-compiler -DUCL_CUDADR ${GPU_CUDA_GENCODE} -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES}) @@ -253,9 +256,9 @@ elseif(GPU_API STREQUAL "OPENCL") target_include_directories(gpu PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/gpu) target_compile_definitions(gpu PRIVATE -DUSE_OPENCL -D_${GPU_PREC_SETTING}) if(GPU_DEBUG) - target_compile_definitions(gpu PRIVATE -DUCL_DEBUG -DGERYON_KERNEL_DUMP) + target_compile_definitions(gpu PRIVATE -DUCL_DEBUG -DGERYON_KERNEL_DUMP -DLAL_SERIALIZE_INIT) else() - target_compile_definitions(gpu PRIVATE -DMPI_GERYON -DGERYON_NUMA_FISSION -DUCL_NO_EXIT) + target_compile_definitions(gpu PRIVATE -DMPI_GERYON -DGERYON_NUMA_FISSION -DUCL_NO_EXIT -DLAL_SERIALIZE_INIT) endif() add_executable(ocl_get_devices ${LAMMPS_LIB_SOURCE_DIR}/gpu/geryon/ucl_get_devices.cpp) diff --git a/cmake/Modules/Packages/KOKKOS.cmake b/cmake/Modules/Packages/KOKKOS.cmake index 6c27ede3da8..d55a1879150 100644 --- a/cmake/Modules/Packages/KOKKOS.cmake +++ b/cmake/Modules/Packages/KOKKOS.cmake @@ -1,8 +1,8 @@ ######################################################################## -# As of version 4.0.0 Kokkos requires C++17 -if(CMAKE_CXX_STANDARD LESS 17) +# As of version 5.0.0 Kokkos requires C++20 +if(CMAKE_CXX_STANDARD LESS 20) message(FATAL_ERROR "The KOKKOS package requires the C++ standard to -be set to at least C++17") +be set to at least C++20") endif() # Set Kokkos Precision @@ -88,8 +88,8 @@ if(DOWNLOAD_KOKKOS) list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_CXX_EXTENSIONS=${CMAKE_CXX_EXTENSIONS}") list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}") include(ExternalProject) - set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/4.7.01.tar.gz" CACHE STRING "URL for KOKKOS tarball") - set(KOKKOS_MD5 "06bc2f6f9804f9d16228059e87c85239" CACHE STRING "MD5 checksum of KOKKOS tarball") + set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/5.0.0.tar.gz" CACHE STRING "URL for KOKKOS tarball") + set(KOKKOS_MD5 "968754bce9cddd26f31b2439bc0d338f" CACHE STRING "MD5 checksum of KOKKOS tarball") mark_as_advanced(KOKKOS_URL) mark_as_advanced(KOKKOS_MD5) GetFallbackURL(KOKKOS_URL KOKKOS_FALLBACK) @@ -114,7 +114,7 @@ if(DOWNLOAD_KOKKOS) add_dependencies(LAMMPS::KOKKOSCORE kokkos_build) add_dependencies(LAMMPS::KOKKOSCONTAINERS kokkos_build) elseif(EXTERNAL_KOKKOS) - find_package(Kokkos 4.7.01 REQUIRED CONFIG) + find_package(Kokkos 5.0.0 REQUIRED CONFIG) target_link_libraries(lammps PRIVATE Kokkos::kokkos) else() set(LAMMPS_LIB_KOKKOS_SRC_DIR ${LAMMPS_LIB_SOURCE_DIR}/kokkos) diff --git a/cmake/Modules/Packages/PLUMED.cmake b/cmake/Modules/Packages/PLUMED.cmake index 606fe2174bd..fabac718eb6 100644 --- a/cmake/Modules/Packages/PLUMED.cmake +++ b/cmake/Modules/Packages/PLUMED.cmake @@ -61,7 +61,7 @@ if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND (CMAKE_CROSSCOMPILING)) URL ${PLUMED_URL} ${PLUMED_FALLBACK} URL_MD5 ${PLUMED_MD5} BUILD_IN_SOURCE 1 - CONFIGURE_COMMAND ${CROSS_CONFIGURE} --disable-shared --disable-bsymbolic + CONFIGURE_COMMAND ${CROSS_CONFIGURE} --disable-shared --disable-bsymbolic --disable-dlopen --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} diff --git a/cmake/Modules/Testing.cmake b/cmake/Modules/Testing.cmake index 7aa35066427..732613605ea 100644 --- a/cmake/Modules/Testing.cmake +++ b/cmake/Modules/Testing.cmake @@ -24,7 +24,7 @@ if(ENABLE_TESTING) if(((CMAKE_LINUX_DISTRO STREQUAL "Ubuntu") AND (CMAKE_DISTRO_VERSION VERSION_GREATER_EQUAL 22.04)) OR ((CMAKE_LINUX_DISTRO STREQUAL "Fedora") AND (CMAKE_DISTRO_VERSION VERSION_GREATER 30))) include(CheckCXXCompilerFlag) - set(CMAKE_CUSTOM_LINKER_DEFAULT default) + set(LAMMPS_CUSTOM_LINKER_DEFAULT default) check_cxx_compiler_flag(--ld-path=${CMAKE_LINKER} HAVE_LD_PATH_FLAG) check_cxx_compiler_flag(-fuse-ld=mold HAVE_MOLD_LINKER_FLAG) check_cxx_compiler_flag(-fuse-ld=lld HAVE_LLD_LINKER_FLAG) @@ -35,29 +35,29 @@ if(ENABLE_TESTING) find_program(HAVE_GOLD_LINKER_BIN ld.gold) find_program(HAVE_BFD_LINKER_BIN ld.bfd) if(HAVE_MOLD_LINKER_FLAG AND HAVE_MOLD_LINKER_BIN) - set(CMAKE_CUSTOM_LINKER_DEFAULT mold) + set(LAMMPS_CUSTOM_LINKER_DEFAULT mold) elseif(HAVE_LLD_LINKER_FLAG AND HAVE_LLD_LINKER_BIN) - set(CMAKE_CUSTOM_LINKER_DEFAULT lld) + set(LAMMPS_CUSTOM_LINKER_DEFAULT lld) elseif(HAVE_GOLD_LINKER_FLAG AND HAVE_GOLD_LINKER_BIN) - set(CMAKE_CUSTOM_LINKER_DEFAULT gold) + set(LAMMPS_CUSTOM_LINKER_DEFAULT gold) elseif(HAVE_BFD_LINKER_FLAG AND HAVE_BFD_LINKER_BIN) - set(CMAKE_CUSTOM_LINKER_DEFAULT bfd) + set(LAMMPS_CUSTOM_LINKER_DEFAULT bfd) endif() - set(CMAKE_CUSTOM_LINKER_VALUES mold lld gold bfd default) - set(CMAKE_CUSTOM_LINKER ${CMAKE_CUSTOM_LINKER_DEFAULT} CACHE STRING "Choose a custom linker for faster linking (mold, lld, gold, bfd, default)") - validate_option(CMAKE_CUSTOM_LINKER CMAKE_CUSTOM_LINKER_VALUES) - mark_as_advanced(CMAKE_CUSTOM_LINKER) - if(NOT "${CMAKE_CUSTOM_LINKER}" STREQUAL "default") - target_link_options(lammps PUBLIC -fuse-ld=${CMAKE_CUSTOM_LINKER}) + set(LAMMPS_CUSTOM_LINKER_VALUES mold lld gold bfd default) + set(LAMMPS_CUSTOM_LINKER ${LAMMPS_CUSTOM_LINKER_DEFAULT} CACHE STRING "Choose a custom linker for faster linking (mold, lld, gold, bfd, default)") + validate_option(LAMMPS_CUSTOM_LINKER LAMMPS_CUSTOM_LINKER_VALUES) + mark_as_advanced(LAMMPS_CUSTOM_LINKER) + if(NOT "${LAMMPS_CUSTOM_LINKER}" STREQUAL "default") + target_link_options(lammps PUBLIC -fuse-ld=${LAMMPS_CUSTOM_LINKER}) endif() if(HAVE_LD_PATH_FLAG) - if("${CMAKE_CUSTOM_LINKER}" STREQUAL "mold") + if("${LAMMPS_CUSTOM_LINKER}" STREQUAL "mold") target_link_options(lammps PUBLIC --ld-path=${HAVE_MOLD_LINKER_BIN}) - elseif("${CMAKE_CUSTOM_LINKER}" STREQUAL "lld") + elseif("${LAMMPS_CUSTOM_LINKER}" STREQUAL "lld") target_link_options(lammps PUBLIC --ld-path=${HAVE_LLD_LINKER_BIN}) - elseif("${CMAKE_CUSTOM_LINKER}" STREQUAL "gold") + elseif("${LAMMPS_CUSTOM_LINKER}" STREQUAL "gold") target_link_options(lammps PUBLIC --ld-path=${HAVE_GOLD_LINKER_BIN}) - elseif("${CMAKE_CUSTOM_LINKER}" STREQUAL "bfd") + elseif("${LAMMPS_CUSTOM_LINKER}" STREQUAL "bfd") target_link_options(lammps PUBLIC --ld-path=${HAVE_BFD_LINKER_BIN}) endif() endif() diff --git a/cmake/Modules/Tools.cmake b/cmake/Modules/Tools.cmake index 4dfa09c6f5b..dd497895c52 100644 --- a/cmake/Modules/Tools.cmake +++ b/cmake/Modules/Tools.cmake @@ -10,6 +10,9 @@ if(BUILD_TOOLS) target_include_directories(reformat-json PRIVATE ${LAMMPS_SOURCE_DIR}) install(TARGETS reformat-json DESTINATION ${CMAKE_INSTALL_BINDIR}) + add_custom_target(tools ALL COMMENT "Building tools") + add_dependencies(tools binary2txt stl_bin2txt reformat-json) + include(CheckGeneratorSupport) if(CMAKE_GENERATOR_SUPPORT_FORTRAN) include(CheckLanguage) @@ -21,6 +24,7 @@ if(BUILD_TOOLS) add_executable(micelle2d.x ${LAMMPS_TOOLS_DIR}/micelle2d.f90) target_link_libraries(micelle2d.x PRIVATE ${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES}) install(TARGETS chain.x micelle2d.x DESTINATION ${CMAKE_INSTALL_BINDIR}) + add_dependencies(tools chain.x micelle2d.x) else() message(WARNING "No suitable Fortran compiler found, skipping build of 'chain.x' and 'micelle2d.x'") endif() @@ -39,6 +43,7 @@ if(BUILD_TOOLS) install(FILES ${LAMMPS_DOC_DIR}/msi2lmp.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1) add_subdirectory(${LAMMPS_TOOLS_DIR}/phonon ${CMAKE_BINARY_DIR}/phana_build) + add_dependencies(tools msi2lmp phana) endif() if(BUILD_LAMMPS_GUI) @@ -170,7 +175,7 @@ if(BUILD_LAMMPS_GUI) COMMAND ${CMAKE_COMMAND} -E copy_if_different ${LAMMPS_DIR}/doc/lammps.1 ${APP_CONTENTS}/share/lammps/man/man1/ COMMAND ${CMAKE_COMMAND} -E create_symlink lammps.1 ${APP_CONTENTS}/share/lammps/man/man1/lmp.1 COMMAND ${CMAKE_COMMAND} -E copy_if_different ${LAMMPS_DIR}/doc/msi2lmp.1 ${APP_CONTENTS}/share/lammps/man/man1 - DEPENDS lammps lmp binary2txt stl_bin2txt msi2lmp phana lammps-gui_build + DEPENDS lammps lmp tools lammps-gui_build COMMENT "Copying additional files into macOS app bundle tree" WORKING_DIRECTORY ${CMAKE_BINARY_DIR} ) @@ -265,12 +270,22 @@ if(BUILD_LAMMPS_GUI) endif() ]] ) - add_custom_target(tgz - COMMAND ${LAMMPS_DIR}/cmake/packaging/build_linux_tgz.sh ${LAMMPS_RELEASE} - DEPENDS lmp lammps-gui_build ${WHAM_EXE} - COMMENT "Create compressed tar file of LAMMPS-GUI with dependent libraries and wrapper" - BYPRODUCT LAMMPS-Linux-x86_64-GUI-${LAMMPS_RELEASE}.tar.gz - WORKING_DIRECTORY ${CMAKE_BINARY_DIR} - ) + if(USE_INTERNAL_LINALG AND (NOT DOWNLOAD_POTENTIALS)) + add_custom_target(tgz + COMMAND ${LAMMPS_DIR}/cmake/packaging/build_linux_tgz.sh ${LAMMPS_RELEASE} + DEPENDS lmp tools lammps-gui_build ${WHAM_EXE} + COMMENT "Create compressed tar file of LAMMPS-GUI with dependent libraries and wrapper" + BYPRODUCT LAMMPS-Linux-x86_64-GUI-${LAMMPS_RELEASE}.tar.gz + WORKING_DIRECTORY ${CMAKE_BINARY_DIR} + ) + else() + if(DOWNLOAD_POTENTIALS) + add_custom_target(tgz + COMMAND ${CMAKE_COMMAND} -E echo "Must use -D DOWLOAD_POTENTIALS=OFF for building Linux tgz package") + else() + add_custom_target(tgz + COMMAND ${CMAKE_COMMAND} -E echo "Must use -D USE_INTERNAL_LINALG=ON for building Linux tgz package") + endif() + endif() endif() endif() diff --git a/cmake/packaging/build_linux_tgz.sh b/cmake/packaging/build_linux_tgz.sh index 97320fe51f9..f79ceaa35fb 100755 --- a/cmake/packaging/build_linux_tgz.sh +++ b/cmake/packaging/build_linux_tgz.sh @@ -14,7 +14,20 @@ cp lammps-gui_build-prefix/bin/lammps-gui ${DESTDIR}/bin/ echo "Remove debug info" for s in ${DESTDIR}/bin/* ${DESTDIR}/lib/liblammps* do \ - test -f $s && strip --strip-debug $s + test -f $s && strip --strip-debug $s +done + +echo "Move LAMMPS shared library to its own folder" +mkdir -p ${DESTDIR}/libexec/lammps +mv -v ${DESTDIR}/lib/liblammps* ${DESTDIR}/libexec/lammps/ +chmod +x ${DESTDIR}/libexec/lammps/liblammps.so.* + +# add certain LAMMPS library dependencies +LIBDEPS=$(LD_LIBRARY_PATH=${DESTDIR}/lib ldd ${DESTDIR}/libexec/lammps/liblammps.so | grep -v ${DESTDIR} | grep -E '(libz\.so\.|libpng|libjpeg)' | sed -e 's/^.*=> *//' -e 's/\(lib.*.so.*\) .*$/\1/') +for dep in ${LIBDEPS} +do \ + cp ${dep} ${DESTDIR}/lib + chmod +x ${DESTDIR}/lib/${dep} done echo "Remove libc, gcc, and X11 related shared libs" @@ -24,29 +37,42 @@ rm -f ${DESTDIR}/lib/lib{c,dl,rt,m,pthread}-[0-9].[0-9]*.so rm -f ${DESTDIR}/lib/libX* ${DESTDIR}/lib/libxcb* rm -f ${DESTDIR}/lib/libgcc_s* rm -f ${DESTDIR}/lib/libstdc++* +echo "Remove oversize potential files" +rm -f ${DESTDIR}/share/lammps/potentials/C_10_10.mesocnt -# get qt dir +# get Qt dir QTDIR=$(ldd ${DESTDIR}/bin/lammps-gui | grep libQt.Core | sed -e 's/^.*=> *//' -e 's/libQt\(.\)Core.so.*$/qt\1/') + +# configure some settings files for Qt cat > ${DESTDIR}/bin/qt.conf < ${DESTDIR}/bin/qtlogging.ini < *//' -e 's/\(libQt[56].*.so.*\) .*$/\1/') for dep in ${QTDEPS} do \ cp ${dep} ${DESTDIR}/lib + chmod +x ${DESTDIR}/lib/${dep} done echo "Add additional plugins for Qt" for dir in styles imageformats do \ cp -r ${QTDIR}/plugins/${dir} ${DESTDIR}/qtplugins/ + chmod +x ${DESTDIR}/qtplugins/*/*.so done # get imageplugin dependencies @@ -56,6 +82,7 @@ do \ for dep in ${QTDEPS} do \ cp ${dep} ${DESTDIR}/lib + chmod +x ${DESTDIR}/lib/${dep} done done @@ -63,11 +90,13 @@ echo "Set up wrapper script" MYDIR=$(dirname "$0") cp ${MYDIR}/xdg-open ${DESTDIR}/bin cp ${MYDIR}/linux_wrapper.sh ${DESTDIR}/bin +chmod 0755 ${DESTDIR}/bin/linux_wrapper.sh for s in ${DESTDIR}/bin/* do \ EXE=$(basename $s) test ${EXE} = linux_wrapper.sh && continue test ${EXE} = qt.conf && continue + test ${EXE} = qtlogging.ini && continue test ${EXE} = xdg-open && continue ln -s bin/linux_wrapper.sh ${DESTDIR}/${EXE} done diff --git a/cmake/packaging/linux_wrapper.sh b/cmake/packaging/linux_wrapper.sh index 44c9f814273..f2949a97e2d 100755 --- a/cmake/packaging/linux_wrapper.sh +++ b/cmake/packaging/linux_wrapper.sh @@ -15,7 +15,9 @@ OLDLDLIB="${LD_LIBRARY_PATH}" PATH="${BASEDIR}/bin:${PATH}" # append to LD_LIBRARY_PATH to prefer local (newer) libs -LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:${BASEDIR}/lib" +# however the LAMMPS shared library must always come first +# so that it does not get overridden by other installed versions +LD_LIBRARY_PATH="${BASEDIR}/libexec/lammps:${LD_LIBRARY_PATH}:${BASEDIR}/lib" # set some environment variables for LAMMPS etc. LAMMPS_POTENTIALS="${BASEDIR}/share/lammps/potentials" @@ -24,4 +26,16 @@ MSI2LMP_LIBRARY="${BASEDIR}/share/lammps/frc_files" # export everything export LD_LIBRARY_PATH LAMMPS_POTENTIALS MSI2LMP_LIBRARY PATH OLDPATH OLDLDLIB +# check for missing X11 libraries for the Qt platform of LAMMPS-GUI +if [ "${EXENAME}" = "lammps-gui" ] && [ -f "${BASEDIR}/qtplugins/platforms/libqxcb.so" ] +then \ + MISSINGLIBS=$(ldd "${BASEDIR}/qtplugins/platforms/libqxcb.so" | sed -n -e '/not found/s/^[ \t]*\(.*\)=> *.*/\1/p' | tr '\n' ' ') + if [ -n "${MISSINGLIBS}" ] + then + echo "Cannot launch LAMMPS-GUI because of missing X11 libraries: ${MISSINGLIBS}" + echo "Please install the corresponding package(s)." + exit 1 + fi +fi + exec "${BASEDIR}/bin/${EXENAME}" "$@" diff --git a/cmake/packaging/org.lammps.lammps-gui.yml b/cmake/packaging/org.lammps.lammps-gui.yml index 01aedc416b7..b63b2403873 100644 --- a/cmake/packaging/org.lammps.lammps-gui.yml +++ b/cmake/packaging/org.lammps.lammps-gui.yml @@ -33,7 +33,6 @@ modules: - -D DOWNLOAD_POTENTIALS=no - -D PKG_AMOEBA=yes - -D PKG_ASPHERE=yes - - -D PKG_AWPMD=yes - -D PKG_BOCS=yes - -D PKG_BODY=yes - -D PKG_BPM=yes @@ -90,7 +89,6 @@ modules: - -D PKG_PERI=yes - -D PKG_PHONON=yes - -D PKG_PLUGIN=yes - - -D PKG_POEMS=yes - -D PKG_PTM=yes - -D PKG_PYTHON=yes - -D PKG_QEQ=yes diff --git a/cmake/presets/elcapitan_kokkos.cmake b/cmake/presets/elcapitan_kokkos.cmake new file mode 100644 index 00000000000..c5fb2414711 --- /dev/null +++ b/cmake/presets/elcapitan_kokkos.cmake @@ -0,0 +1,17 @@ +# elcapitan_kokkos = KOKKOS/HIP, AMD MI300A APU, Cray MPICH, hipcc compiler, hipFFT +set(PKG_KOKKOS ON CACHE BOOL "" FORCE) +set(Kokkos_ENABLE_SERIAL ON CACHE BOOL "" FORCE) +set(Kokkos_ENABLE_OPENMP OFF CACHE BOOL "" FORCE) +set(Kokkos_ENABLE_CUDA OFF CACHE BOOL "" FORCE) +set(Kokkos_ENABLE_HIP ON CACHE BOOL "" FORCE) +set(Kokkos_ARCH_AMD_GFX942_APU on CACHE BOOL "" FORCE) +set(BUILD_OMP OFF CACHE BOOL "" FORCE) + +set(CMAKE_CXX_COMPILER "hipcc" CACHE STRING "" FORCE) +set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fdenormal-fp-math=ieee -fgpu-flush-denormals-to-zero" CACHE STRING "" FORCE) + +set(MPI_CXX_INCLUDE_PATH "$ENV{MPICH_DIR}/include" CACHE STRING "" FORCE) +set(CMAKE_EXE_LINKER_FLAGS "-L$ENV{MPICH_DIR}/lib -lmpi -L$ENV{CRAY_MPICH_ROOTDIR}/gtl/lib -lmpi_gtl_hsa -Wl,-rpath,$ENV{CRAY_MPICH_ROOTDIR}/gtl/lib -lmpi_gtl_hsa -lxpmem -lhugetlbfs" CACHE STRING "" FORCE) + +# If KSPACE is also enabled, use HIPFFT for FFTs +set(FFT_KOKKOS "HIPFFT" CACHE STRING "" FORCE) diff --git a/cmake/presets/hip_amd.cmake b/cmake/presets/hip_amd.cmake index 2cf28c05c41..858d6c066a7 100644 --- a/cmake/presets/hip_amd.cmake +++ b/cmake/presets/hip_amd.cmake @@ -24,6 +24,8 @@ set(MPI_C_COMPILER "mpicc" CACHE STRING "" FORCE) # change as needed. This is for Fedora Linux 41 and 42 set(_libomp_root "/usr/lib/clang/18") +# This is for Fedora Linux 43 +# set(_libomp_root "/usr/lib/clang/19") # we need to explicitly specify the include dir, since hipcc will # compile each file twice and doesn't find omp.h the second time diff --git a/cmake/presets/kokkos-hip.cmake b/cmake/presets/kokkos-hip.cmake index 58b09020fb2..7b1d8988f6f 100644 --- a/cmake/presets/kokkos-hip.cmake +++ b/cmake/presets/kokkos-hip.cmake @@ -6,7 +6,6 @@ set(Kokkos_ENABLE_OPENMP OFF CACHE BOOL "" FORCE) set(Kokkos_ENABLE_CUDA OFF CACHE BOOL "" FORCE) set(Kokkos_ENABLE_HIP ON CACHE BOOL "" FORCE) set(Kokkos_ARCH_VEGA90A on CACHE BOOL "" FORCE) -set(Kokkos_ENABLE_HIP_MULTIPLE_KERNEL_INSTANTIATIONS ON CACHE BOOL "" FORCE) set(BUILD_OMP ON CACHE BOOL "" FORCE) set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -munsafe-fp-atomics" CACHE STRING "" FORCE) diff --git a/doc/Makefile b/doc/Makefile index 727edcdfa54..4aa573b4612 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -52,7 +52,7 @@ SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocess # we only want to use explicitly listed files. DOXYFILES = $(shell sed -n -e 's/\#.*$$//' -e '/^ *INPUT \+=/,/^[A-Z_]\+ \+=/p' doxygen/Doxyfile.in | sed -e 's/@LAMMPS_SOURCE_DIR@/..\/src/g' -e 's/\\//g' -e 's/ \+/ /' -e 's/[A-Z_]\+ \+= *\(YES\|NO\|\)//') -.PHONY: help clean-all clean clean-spelling epub mobi html pdf spelling anchor_check style_check char_check link_check role_check xmlgen fasthtml fasthtml-init +.PHONY: help clean-all clean clean-spelling epub mobi html pdf spelling anchor_check style_check char_check link_check role_check xmlgen fasthtml fasthtml-init FASTHTMLFILES = $(patsubst $(RSTDIR)/%.rst,fasthtml/%.html,$(wildcard $(RSTDIR)/*rst)) # ------------------------------------------ diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in index e3a5415b207..33c73fad0de 100644 --- a/doc/doxygen/Doxyfile.in +++ b/doc/doxygen/Doxyfile.in @@ -2,7 +2,7 @@ DOXYFILE_ENCODING = UTF-8 PROJECT_NAME = "LAMMPS Programmer's Guide" -PROJECT_NUMBER = "19 November 2024" +PROJECT_NUMBER = "10 December 2025" PROJECT_BRIEF = "Documentation of the LAMMPS library interface and Python wrapper" PROJECT_LOGO = lammps-logo.png CREATE_SUBDIRS = NO @@ -420,6 +420,8 @@ INPUT = @LAMMPS_SOURCE_DIR@/utils.cpp \ @LAMMPS_SOURCE_DIR@/lmptype.h \ @LAMMPS_SOURCE_DIR@/atom.cpp \ @LAMMPS_SOURCE_DIR@/atom.h \ + @LAMMPS_SOURCE_DIR@/citeme.cpp \ + @LAMMPS_SOURCE_DIR@/citeme.h \ @LAMMPS_SOURCE_DIR@/input.cpp \ @LAMMPS_SOURCE_DIR@/input.h \ @LAMMPS_SOURCE_DIR@/tokenizer.cpp \ diff --git a/doc/lammps.1 b/doc/lammps.1 index 28f639362b3..3d2dfd8d8ab 100644 --- a/doc/lammps.1 +++ b/doc/lammps.1 @@ -1,7 +1,7 @@ -.TH LAMMPS "1" "10 September 2025" "2025-09-10" +.TH LAMMPS "1" "10 December 2025" "2025-12-10" .SH NAME .B LAMMPS -\- Molecular Dynamics Simulator. Version 10 September 2025 +\- Molecular Dynamics Simulator. Version 10 Decmber 2025 .SH SYNOPSIS .B lmp diff --git a/doc/src/Build_basics.rst b/doc/src/Build_basics.rst index 3747b704a3c..34f4a0c2b38 100644 --- a/doc/src/Build_basics.rst +++ b/doc/src/Build_basics.rst @@ -330,9 +330,6 @@ LAMMPS. Makefile.intel_cpu # INTEL package for CPUs Makefile.intel_coprocessor # INTEL package for KNLs Makefile.gpu # GPU package - Makefile.kokkos_cuda_mpi # KOKKOS package for GPUs - Makefile.kokkos_omp # KOKKOS package for CPUs (OpenMP) - Makefile.kokkos_phi # KOKKOS package for KNLs (OpenMP) ---------- diff --git a/doc/src/Build_cmake.rst b/doc/src/Build_cmake.rst index 05fe976e80b..9eed484db38 100644 --- a/doc/src/Build_cmake.rst +++ b/doc/src/Build_cmake.rst @@ -16,11 +16,11 @@ environments is on a :doc:`separate page `. .. note:: - LAMMPS currently requires that CMake version 3.20 or later is available. + LAMMPS currently requires CMake version 3.20 or later. .. warning:: - You must not mix the :doc:`traditional make based ` + You **must not** mix the :doc:`traditional make based ` LAMMPS build procedure with using CMake. No packages may be installed or a build been previously attempted in the LAMMPS source directory by using ``make ``. CMake will detect if this is @@ -73,46 +73,47 @@ with no add-on packages enabled and no customization: .. code-block:: bash - cd lammps # change to the LAMMPS distribution directory - mkdir build; cd build # create and use a build directory - cmake ../cmake # configuration reading CMake scripts from ../cmake - cmake --build . # compilation (or type "make") - -This will create and change into a folder called ``build``, then run the -configuration step to generate build files for the default build command -and then launch that build command to compile LAMMPS. During the -configuration step CMake will try to detect whether support for MPI, -OpenMP, FFTW, gzip, JPEG, PNG, and ffmpeg are available and enable the -corresponding configuration settings. The progress of this -configuration can be followed on the screen and a summary of selected -options and settings will be printed at the end. The ``cmake --build -.`` command will launch the compilation, which, if successful, will -ultimately produce a library ``liblammps.a`` and the LAMMPS executable -``lmp`` inside the ``build`` folder. + cd lammps # change to the LAMMPS source distribution directory + cmake -S cmake -B build # configure the "build" folder with CMake scripts from "cmake" + cmake --build build # compilation (or type "make -C build") + +This will create a folder called ``build``, then run the configuration +step to generate build files for the default build command and then +launch that build command to compile LAMMPS. During the configuration +step CMake will try to detect whether support for MPI, OpenMP, FFTW, +gzip, JPEG, PNG, and ffmpeg are available and enable the corresponding +configuration settings. The progress of this configuration can be +followed on the screen and a summary of selected options and settings +will be printed at the end. The ``cmake --build build`` command will +launch the compilation, which, if successful, will ultimately produce a +library ``liblammps.a`` and the LAMMPS executable ``lmp`` inside the +``build`` folder. Compilation can take a long time, since LAMMPS is a large project with many features. If your machine has multiple CPU cores (most do these days), you can speed this up by compiling sources in parallel with -``make -j N`` (with N being the maximum number of concurrently executed -tasks). Installation of the `ccache `_ (= Compiler -Cache) software may speed up repeated compilation even more, e.g. during -code development, especially when repeatedly switching between branches. +adding ``--parallel N`` to the ``cmake`` command line (with *N* being +the maximum number of concurrently executed tasks). Installation of the +`ccache `_ (= Compiler Cache) software may speed up +repeated compilation even more, e.g. during code development, especially +when repeatedly switching between branches. After the initial build, whenever you edit LAMMPS source files, enable or disable packages, change compiler flags or build options, you must -re-compile and relink the LAMMPS executable with ``cmake --build .`` (or -``make``). If the compilation fails for some reason, try running -``cmake .`` and then compile again. The included dependency tracking -should make certain that only the necessary subset of files is +re-compile and relink the LAMMPS executable with ``cmake --build build`` +(or ``make -C build``). If the compilation fails for some reason, try +running ``cmake build`` and then compile again. The included dependency +tracking should make certain that only the necessary subset of files is re-compiled. You can also delete compiled objects, libraries, and -executables with ``cmake --build . --target clean`` (or ``make clean``). +executables with ``cmake --build build --target clean`` (or ``make -C +build clean``). After compilation, you may optionally install the LAMMPS executable into your system with: .. code-block:: bash - make install # optional, copy compiled files into installation location + cmake --install build # optional, copy compiled files into installation location This will install the LAMMPS executable and library, some tools (if configured) and additional files like LAMMPS API headers, manpages, @@ -122,9 +123,81 @@ defaults to ``${HOME}/.local``. .. note:: If you have set `-D CMAKE_INSTALL_PREFIX` to install LAMMPS into a - system location on a Linux machine , you may also have to run (as - root) the `ldconfig` program to update the cache file for fast lookup - of system shared libraries. + system location on a Linux machine, you also have to run (as root) + the `ldconfig` program to update the cache file for fast lookup of + system shared libraries. + +.. admonition:: Using the installed library + :class: Hint + + The CMake installation functionality is an experimental work in + progress and thus not without problems, especially when writing your + own program that is trying to use the LAMMPS C++ classes directly. + + While there is a well-defined :ref:`C-language interface + ` with the ``library.h`` header file, there is no + equivalent for the C++ interface yet. When installing LAMMPS, + only the core header files are copied into the installation folder + and thus only high-level access to C++ features is available. + + The following is a minimal CMake example file for using the installed + LAMMPS package which represents the current state of development: + + .. code-block:: cmake + + cmake_minimum_required(VERSION 3.20) + project(simpleCC CXX) + # set this to the LAMMPS installation location + if(NOT CMAKE_PREFIX_PATH) + set(CMAKE_PREFIX_PATH $ENV{HOME}/.local) + endif() + find_package(LAMMPS REQUIRED) + add_executable(simpleCC simple.cpp) + target_link_libraries(simpleCC PRIVATE LAMMPS::LAMMPS) + + The ``CMAKE_PREFIX_PATH`` setting tells CMake where to find the + generated CMake configuration files for the `find_package() + `_ + CMake command. You can also specify a required minimal version or + version range. For that a numeric representation in the "YYYY.MM.DD" + format has to be used: the 10 September 2025 release thus becomes + version 2025.09.10. The include statements in the ``simple.cpp`` + source file have to be prefixed with ``lammps/`` as follows: + + .. code-block:: C++ + + #include + #include + #include + #include + + Using the ``LAMMPS::LAMMPS`` target imported from the installed + LAMMPS CMake configuration files should set up the include and linker + flags and folders automatically. Below is the output for an example + session (note how it checks for and includes MPI and OpenMP support + since that specific LAMMPS library was set up this way): + + .. code-block:: console + + $ cmake -S . -B build -D CMAKE_PREFIX_PATH=$HOME/Downloads/test-install + -- The CXX compiler identification is GNU 15.2.1 + -- Detecting CXX compiler ABI info + -- Detecting CXX compiler ABI info - done + -- Check for working CXX compiler: /usr/lib64/ccache/c++ - skipped + -- Detecting CXX compile features + -- Detecting CXX compile features - done + -- Found MPI_CXX: /usr/lib64/mpich/lib/libmpicxx.so (found version "4.1") + -- Found MPI: TRUE (found version "4.1") found components: CXX + -- Found OpenMP_CXX: -fopenmp (found version "4.5") + -- Found OpenMP: TRUE (found version "4.5") found components: CXX + -- Found LAMMPS: /home/akohlmey/Downloads/test-install/lib64/liblammps.so.0 + -- Configuring done (0.9s) + -- Generating done (0.0s) + -- Build files have been written to: /home/akohlmey/Downloads/test-simple/build + $ cmake --build build + [ 50%] Building CXX object CMakeFiles/simpleCC.dir/simple.cpp.o + [100%] Linking CXX executable simpleCC + [100%] Built target simpleCC .. _cmake_options: @@ -133,9 +206,14 @@ Configuration and build options The CMake commands have one mandatory argument: a folder containing a file called ``CMakeLists.txt`` (for LAMMPS it is located in the -``cmake`` folder) or a build folder containing a file called +``cmake`` folder, in that case the current working directory becomes +the build folder) or a build folder containing a file called ``CMakeCache.txt``, which is generated at the end of the CMake configuration step. The cache file contains all current CMake settings. +This is a "legacy mode" or running CMake and thus often found +when searching the web. We recommend to use the ``-S`` and ``-B`` +folders to explicitly set the path to the folder containing the +``CMakeLists.txt`` file and the build folder, respectively. To modify settings, enable or disable features, you need to set *variables* with either the ``-D`` command-line flag (``-D diff --git a/doc/src/Build_development.rst b/doc/src/Build_development.rst index 6845079f8fe..9cf7d7b9c60 100644 --- a/doc/src/Build_development.rst +++ b/doc/src/Build_development.rst @@ -4,6 +4,8 @@ Development build options The build procedures in LAMMPS offers a few extra options which are useful during development, testing or debugging. +.. contents:: + ---------- .. _compilation: @@ -100,11 +102,13 @@ compilation and linking stages. This is done through setting the Code Coverage and Unit Testing (CMake only) ------------------------------------------- -The LAMMPS code is subject to multiple levels of automated testing -during development: +The LAMMPS code is subject to multiple levels of automated testing when +pull requests are submitted to `the LAMMPS repository on GitHub +`_: -- Integration testing (i.e. whether the code compiles - on various platforms and with a variety of compilers and settings), +- Coding style compliance (see :ref:`Coding style utilities `) +- Integration testing (i.e. whether the code compiles on multiple + platforms and with a variety of compilers and settings), - Unit testing (i.e. whether certain functions or classes of the code produce the expected results for given inputs), - Run testing (i.e. whether selected input decks can run to completion @@ -113,30 +117,30 @@ during development: same results over a given number of steps and operations within a given error margin). -The status of this automated testing can be viewed on `https://ci.lammps.org -`_. +The tests are currently run as GitHub Actions and their configuration +files are in the ``.github/workflows/`` folder of the LAMMPS git tree. +The test status of these tests is reported with the corresponding pull +request and the pull request *cannot* be merged without all tests passing. -The scripts and inputs for integration, run, and legacy regression -testing are maintained in a `separate repository -`_ of the LAMMPS project on -GitHub. A few tests are also run as GitHub Actions and their -configuration files are in the ``.github/workflows/`` folder of the -LAMMPS git tree. +In addition, there is a nightly test run using the ``develop`` branch to +generate code coverage data for the included tests (see below), provided +there have been changes to that tree. The results of this test run can +be currently viewed at https://download.lammps.org/coverage/tests.html Regression tests can also be performed locally with the :ref:`regression -tester tool `. The tool checks if a given LAMMPS binary run -with selected input examples produces thermo output that is consistent -with the provided log files. The script can be run in one pass over all -available input files, but it can also first create multiple lists of -inputs or folders that can then be run with multiple workers -concurrently to speed things up. Another mode allows to do a quick -check of inputs that contain commands that have changes in the current -checkout branch relative to a git branch. This works similar to the two -pass mode, but will select only shorter runs and no more than 100 inputs -that are chosen randomly. This ensures that this test runs -significantly faster compared to the full test run. These test runs can -also be performed with instrumented LAMMPS binaries (see previous -section). +tester tool `. The tool checks if a given LAMMPS binary, +when run with selected input examples produces, thermo output that is +consistent with the provided log files. The script can be run in one +pass over all available input files, but it can also first create +multiple lists of inputs or folders that can then be run with multiple +workers concurrently to speed things up. Another mode allows to do a +quick check of inputs that contain commands that have changes in the +current checkout branch relative to a git branch. This works similar to +the two pass mode, but will select only shorter runs and no more than +100 inputs that are chosen randomly. This ensures that the quick test +runs significantly faster compared to the full test run. These test +runs can also be performed with instrumented LAMMPS binaries (see +previous section). The unit testing facility is integrated into the CMake build process of the LAMMPS source code distribution itself. It can be enabled by @@ -147,27 +151,19 @@ version of that library will be downloaded and compiled along with LAMMPS and the test programs) and will download and compile a specific version of the `GoogleTest `_ C++ test framework that is used to implement the tests. Those unit tests -may be combined with memory access and leak checking with valgrind -(see below for how to enable it). In that case, running so-called -death tests will create a lot of false positives and thus they can be -disabled by configuring compilation with the additional setting -``-D SKIP_DEATH_TESTS=on``. - -.. admonition:: Software version and LAMMPS configuration requirements - :class: note - - The compiler and library version requirements for the testing - framework are more strict than for the main part of LAMMPS. For - example the default GNU C++ and Fortran compilers of RHEL/CentOS 7.x - (version 4.8.x) are not sufficient. The CMake configuration will try - to detect incompatible versions and either skip incompatible tests or - stop with an error. Also the number of available tests will depend on - installed LAMMPS packages, development environment, operating system, - and configuration settings. +may be combined with memory access and leak checking with valgrind (see +below for how to enable it). In that case, running so-called death +tests will create a lot of false positives and thus they can be disabled +by configuring compilation with the additional setting ``-D +SKIP_DEATH_TESTS=on``. After compilation is complete, the unit testing is started in the build folder using the ``ctest`` command, which is part of the CMake software. -The output of this command will be looking something like this: +The number of available tests will depend on the LAMMPS versions, +installed LAMMPS packages, configuration settings, development +environment, and operating system. + +The output of the plain ``ctest`` command looks something like the following: .. code-block:: console @@ -214,14 +210,16 @@ The ``ctest`` command has many options, the most important ones are: - verbose output: display output of individual test runs * - ``-j `` - parallel run: run tests in parallel + * - ``--test-dir `` + - provide path to the CMake build folder. By default ``ctest`` uses ``.`` * - ``-R `` - - run subset of tests matching the regular expression + - run subset of tests matching the regular expression ```` * - ``-E `` - - exclude subset of tests matching the regular expression + - exclude subset of tests matching the regular expression ```` * - ``-L `` - - run subset of tests with a label matching the regular expression + - run subset of tests with a label matching the regular expression ```` * - ``-LE `` - - exclude subset of tests with a label matching the regular expression + - exclude subset of tests with a label matching the regular expression ```` * - ``-N`` - dry-run: display list of tests without running them * - ``-T memcheck`` @@ -238,8 +236,8 @@ will be skipped if prerequisite features are not available in LAMMPS. The unit test framework was added in spring 2020 and is under active development. The coverage is not complete and will be expanded over - time. Preference is given to parts of the code base that are easy to - test or commonly used. + time. Preference was given to test parts of the code base that are + easy to test or commonly used. Tests as shown by the ``ctest`` program are commands defined in the ``CMakeLists.txt`` files in the ``unittest`` directory tree. A few @@ -256,16 +254,16 @@ These special test programs are structured to perform multiple individual tests internally and each of those contains several checks (aka assertions) for internal data being changed as expected. -Tests for force computing or modifying styles (e.g. styles for non-bonded -and bonded interactions and selected fixes) are run by using a more generic -test program that reads its input from files in YAML format. The YAML file -provides the information on how to customized the test program to test -a specific style and - if needed - with specific settings. -To add a test for another, similar style (e.g. a new pair style) it is -usually sufficient to add a suitable YAML file. :doc:`Detailed -instructions for adding tests ` are provided in the -Programmer Guide part of the manual. A description of what happens -during the tests is given below. +Tests for force computing or modifying styles (e.g. styles for +non-bonded and bonded interactions and selected fixes) are run by using +a more generic test program that reads its input from files in YAML +format. The YAML file provides the information on how to customized the +test program to test a specific style and - if needed - with specific +settings. To add a test for another, similar style (e.g. a new pair +style) it is usually sufficient to add a suitable YAML file. +:doc:`Detailed instructions for adding tests ` are +provided in the Programmer Guide part of the manual. A description of +what happens during these tests is given below. Unit tests for force styles ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -273,59 +271,97 @@ Unit tests for force styles A large part of LAMMPS are different "styles" for computing non-bonded and bonded interactions selected through the :doc:`pair_style`, :doc:`bond_style`, :doc:`angle_style`, :doc:`dihedral_style`, -:doc:`improper_style`, and :doc:`kspace_style`. Since these all share -common interfaces, it is possible to write generic test programs that -will call those common interfaces for small test systems with less than -100 atoms and compare the results with pre-recorded reference results. -A test run is then a a collection multiple individual test runs each -with many comparisons to reference results based on template input -files, individual command settings, relative error margins, and -reference data stored in a YAML format file with ``.yaml`` -suffix. Currently the programs ``test_pair_style``, ``test_bond_style``, +:doc:`improper_style`, and :doc:`kspace_style` commands. Since these +styles all share common interfaces, it is possible to write generic test +programs that will assemble LAMMPS inputs from templates with different +settings and call those common interfaces for small test systems with +less than 100 atoms and compare the results with pre-recorded reference +results. A test run is then a collection of multiple individual test +runs, each with many comparisons to reference results based on template +input files, individual command settings, relative error margins, and +reference data stored in a YAML format file with ``.yaml`` suffix. +Currently the programs ``test_pair_style``, ``test_bond_style``, ``test_angle_style``, ``test_dihedral_style``, and ``test_improper_style`` are implemented. They will compare forces, energies and (global) stress for all atoms after a ``run 0`` calculation and after a few steps of MD with :doc:`fix nve `, each in multiple variants with different settings and also for multiple -accelerated styles. If a prerequisite style or package is missing, the +accelerated styles. If a prerequisite style or package is missing, the individual tests are skipped. All force style tests will be executed on a single MPI process, so using the CMake option ``-D BUILD_MPI=off`` can significantly speed up testing, since this will skip the MPI -initialization for each test run. Below is an example command and -output: +initialization for each test run. + +Below is an example command and output for running a single test named +``MolPairStyle:lj_cut`` (argument to the ``-R`` option which selects +tests by regular expression) and printing detailed output (the ``-V`` flag): .. code-block:: console - $ test_pair_style mol-pair-lj_cut.yaml - [==========] Running 6 tests from 1 test suite. - [----------] Global test environment set-up. - [----------] 6 tests from PairStyle - [ RUN ] PairStyle.plain - [ OK ] PairStyle.plain (24 ms) - [ RUN ] PairStyle.omp - [ OK ] PairStyle.omp (18 ms) - [ RUN ] PairStyle.intel - [ OK ] PairStyle.intel (6 ms) - [ RUN ] PairStyle.opt - [ SKIPPED ] PairStyle.opt (0 ms) - [ RUN ] PairStyle.single - [ OK ] PairStyle.single (7 ms) - [ RUN ] PairStyle.extract - [ OK ] PairStyle.extract (6 ms) - [----------] 6 tests from PairStyle (62 ms total) - - [----------] Global test environment tear-down - [==========] 6 tests from 1 test suite ran. (63 ms total) - [ PASSED ] 5 tests. - [ SKIPPED ] 1 test, listed below: - [ SKIPPED ] PairStyle.opt - -In this particular case, 5 out of 6 sets of tests were conducted, the -tests for the ``lj/cut/opt`` pair style was skipped, since the tests -executable did not include it. To learn what individual tests are performed, -you (currently) need to read the source code. You can use code coverage -recording (see next section) to confirm how well the tests cover the code -paths in the individual source files. + $ ctest -R MolPairStyle:lj_cut$ -V + + [...] + + Start 199: MolPairStyle:lj_cut + + 199: Test command: /home/akohlmey/compile/lammps/build-test/test_pair_style "/home/akohlmey/compile/lammps/unittest/force-styles/tests/mol-pair-lj_cut.yaml" + 199: Working Directory: /home/akohlmey/compile/lammps/build-test/unittest/force-styles + 199: Environment variables: + 199: PYTHONPATH=/home/akohlmey/compile/lammps/unittest/force-styles/tests:/home/akohlmey/compile/lammps/python: + 199: PYTHONUNBUFFERED=1 + 199: PYTHONDONTWRITEBYTECODE=1 + 199: OMP_PROC_BIND=false + 199: OMP_NUM_THREADS=4 + 199: LAMMPS_POTENTIALS=/home/akohlmey/compile/lammps/potentials + 199: LD_LIBRARY_PATH=/home/akohlmey/compile/lammps/build-test:/usr/lib64/mpich/lib:/home/akohlmey/.local/lib:: + 199: Test timeout computed to be: 1500 + 199: [==========] Running 9 tests from 1 test suite. + 199: [----------] Global test environment set-up. + 199: [----------] 9 tests from PairStyle + 199: [ RUN ] PairStyle.plain + 199: [ OK ] PairStyle.plain (17 ms) + 199: [ RUN ] PairStyle.omp + 199: [ OK ] PairStyle.omp (3 ms) + 199: [ RUN ] PairStyle.kokkos_omp + 199: [ OK ] PairStyle.kokkos_omp (6 ms) + 199: [ RUN ] PairStyle.gpu + 199: /home/akohlmey/compile/lammps/unittest/force-styles/test_pair_style.cpp:793: Skipped + 199: + 199: + 199: [ SKIPPED ] PairStyle.gpu (0 ms) + 199: [ RUN ] PairStyle.intel + 199: [ OK ] PairStyle.intel (2 ms) + 199: [ RUN ] PairStyle.opt + 199: [ OK ] PairStyle.opt (2 ms) + 199: [ RUN ] PairStyle.single + 199: [ OK ] PairStyle.single (2 ms) + 199: [ RUN ] PairStyle.extract + 199: [ OK ] PairStyle.extract (1 ms) + 199: [ RUN ] PairStyle.extract_omp + 199: [ OK ] PairStyle.extract_omp (1 ms) + 199: [----------] 9 tests from PairStyle (37 ms total) + 199: + 199: [----------] Global test environment tear-down + 199: [==========] 9 tests from 1 test suite ran. (37 ms total) + 199: [ PASSED ] 8 tests. + 199: [ SKIPPED ] 1 test, listed below: + 199: [ SKIPPED ] PairStyle.gpu + 1/1 Test #199: MolPairStyle:lj_cut .............. Passed 0.75 sec + + The following tests passed: + MolPairStyle:lj_cut + + 100% tests passed, 0 tests failed out of 1 + + Total Test time (real) = 0.76 sec + +In this particular case, 8 out of 9 sets of tests were conducted, the +tests for the ``lj/cut/gpu`` pair style were skipped, since the LAMMPS +library linked to the test executable did not include the GPU package. +To learn what individual tests are performed, you (currently) need to +read the source code. You can use code coverage recording (see next +section) to confirm how well the tests cover the code paths in the +individual source files. The force style test programs have a common set of options: @@ -343,14 +379,17 @@ The force style test programs have a common set of options: * - ``-v`` - verbose output: also print the executed LAMMPS commands -The ``ctest`` tool has no mechanism to directly pass flags to the individual -test programs, but a workaround has been implemented where these flags can be -set in an environment variable ``TEST_ARGS``. Example: +Since the ``ctest`` tool has no mechanism to directly pass flags to the +individual test programs, a workaround has been implemented where these +flags can be set in an environment variable ``TEST_ARGS``. Example: .. code-block:: bash env TEST_ARGS=-s ctest -V -R BondStyle +This adds output with statistics for the computed error of the various +tests relative to the reference (e.g. the per-atom force components). + To add a test for a style that is not yet covered, it is usually best to copy a YAML file for a similar style to a new file, edit the details of the style (how to call it, how to set its coefficients) and then @@ -358,13 +397,17 @@ run test command with either the ``-g`` and the replace the initial test file with the regenerated one or the ``-u`` option. The ``-u`` option will destroy the original file, if the generation run does not complete, so using ``-g`` is recommended unless the YAML file is fully tested -and working. +and working. To have the new test file recognized by ``ctest``, you +need to re-run cmake. You can verify that the new test is available +by checking the output of ``ctest -N``. Some of the force style tests are rather slow to run and some are very sensitive to small differences like CPU architecture, compiler -toolchain, compiler optimization. Those tests are flagged with a "slow" +toolchain, compiler optimization. Those tests are flagged with a "slow" and/or "unstable" label, and thus those tests can be selectively -excluded with the ``-LE`` flag or selected with the ``-L`` flag. +excluded with the ``-LE`` flag to ``ctest`` (see description of the most +commonly used ``ctest`` flags) or specifically selected using the ``-L`` +flag. .. admonition:: Recommendations and notes for YAML files :class: note @@ -441,20 +484,27 @@ YAML format test inputs. Use custom linker for faster link times when ENABLE_TESTING is active ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When compiling LAMMPS with enabled tests, most test executables will -need to be linked against the LAMMPS library. Since this can be a very -large library with many C++ objects when many packages are enabled, link -times can become very long on machines that use the GNU BFD linker (e.g. -Linux systems). Alternatives like the ``mold`` linker, the ``lld`` -linker of the LLVM project, or the ``gold`` linker available with GNU -binutils can speed up this step substantially (in this order). CMake -will by default test if any of the three can be enabled and use it when -``ENABLE_TESTING`` is active. It can also be selected manually through -the ``CMAKE_CUSTOM_LINKER`` CMake variable. Allowed values are -``mold``, ``lld``, ``gold``, ``bfd``, or ``default``. The ``default`` -option will use the system default linker otherwise, the linker is -chosen explicitly. This option is only available for the GNU or Clang -C++ compilers. +When compiling LAMMPS with testing enabled, most test executables will +need to be linked against the LAMMPS library and re-linked whenever +there is a change to LAMMPS. Since this can be a very large library +with many C++ objects when many packages are enabled, link times can +become very long on machines that use the GNU BFD linker (e.g. Linux +systems). Alternative linker programs like the ``mold`` linker, the +``lld`` linker of the LLVM project, or the ``gold`` linker available +with GNU binutils can speed up this step substantially (in this order). +CMake will by default test if any of the three can be enabled and use it +when ``ENABLE_TESTING`` is active. The linker can also be selected +manually through the ``LAMMPS_CUSTOM_LINKER`` CMake variable. Allowed +values are ``mold``, ``lld``, ``gold``, ``bfd``, or ``default``. The +``default`` option will use the system default linker otherwise, the +linker is chosen explicitly. This option is only available for the GNU +or Clang C++ compilers. + +A small additional improvement can be obtained by building LAMMPS as a +shared library with ``-D BUILD_SHARED_LIBS=on``. But this is a small +improvement due to reducing file I/O. Using an alternate linker has an +algorithmic improvement through using symbol resolution algorithms with +lower algorithmic complexity. Tests for other components and utility functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -505,7 +555,9 @@ to do this to install it via pip: After post-processing with ``gen_coverage_html`` the results are in a folder ``coverage_html`` and can be viewed with a web browser. -The images below illustrate how the data is presented. +The images below illustrate how the data is presented. The coverage +data for testing the current ``develop`` branch is generated nightly +and currently available at: https://download.lammps.org/coverage/ .. only:: not latex @@ -553,6 +605,8 @@ The images below illustrate how the data is presented. Source page with branches +.. _coding-style: + Coding style utilities ---------------------- diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index ed7b00b0043..b8c18625bc4 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -243,7 +243,7 @@ necessary for ``hipcc`` and the linker to work correctly. When compiling for HIP ROCm, GPU sorting with ``-D HIP_USE_DEVICE_SORT=on`` requires installing the ``hipcub`` library (https://github.com/ROCmSoftwarePlatform/hipCUB). The HIP CUDA-backend -additionally requires cub (https://nvidia.github.io/cccl/cub/). Setting +additionally requires CUB (https://nvidia.github.io/cccl/cub/). Setting ``-DDOWNLOAD_CUB=yes`` will download and compile CUB. The GPU library has some multi-thread support using OpenMP. If LAMMPS @@ -756,77 +756,10 @@ This list was last updated for version 4.7.1 of the Kokkos library. .. tab:: Basic traditional make settings: - Choose which hardware to support in ``Makefile.machine`` via - ``KOKKOS_DEVICES`` and ``KOKKOS_ARCH`` settings. See the - ``src/MAKE/OPTIONS/Makefile.kokkos*`` files for examples. + .. versionchanged:: TBD - For multicore CPUs using OpenMP: - - .. code-block:: make - - KOKKOS_DEVICES = OpenMP - KOKKOS_ARCH = HOSTARCH # HOSTARCH = HOST from list above - - For Intel KNLs using OpenMP: - - .. code-block:: make - - KOKKOS_DEVICES = OpenMP - KOKKOS_ARCH = KNL - - For NVIDIA GPUs using CUDA: - - .. code-block:: make - - KOKKOS_DEVICES = Cuda - KOKKOS_ARCH = HOSTARCH,GPUARCH # HOSTARCH = HOST from list above that is - # hosting the GPU - # GPUARCH = GPU from list above - KOKKOS_CUDA_OPTIONS = "enable_lambda" - FFT_INC = -DFFT_CUFFT # enable use of cuFFT (optional) - FFT_LIB = -lcufft # link to cuFFT library - - For GPUs, you also need the following lines in your - ``Makefile.machine`` before the CC line is defined. They tell - ``mpicxx`` to use an ``nvcc`` compiler wrapper, which will use - ``nvcc`` for compiling CUDA files and a C++ compiler for - non-Kokkos, non-CUDA files. - - .. code-block:: make - - # For OpenMPI - KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd) - export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper - CC = mpicxx - - .. code-block:: make - - # For MPICH and derivatives - KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd) - CC = mpicxx -cxx=$(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper - - For AMD or NVIDIA GPUs using HIP: - - .. code-block:: make - - KOKKOS_DEVICES = HIP - KOKKOS_ARCH = HOSTARCH,GPUARCH # HOSTARCH = HOST from list above that is - # hosting the GPU - # GPUARCH = GPU from list above - FFT_INC = -DFFT_HIPFFT # enable use of hipFFT (optional) - FFT_LIB = -lhipfft # link to hipFFT library - - For Intel GPUs using SYCL: - - .. code-block:: make - - KOKKOS_DEVICES = SYCL - KOKKOS_ARCH = HOSTARCH,GPUARCH # HOSTARCH = HOST from list above that is - # hosting the GPU - # GPUARCH = GPU from list above - FFT_INC = -DFFT_KOKKOS_MKL_GPU # enable use of oneMKL for Intel GPUs (optional) - # link to oneMKL FFT library - FFT_LIB = -lmkl_sycl_dft -lmkl_intel_ilp64 -lmkl_tbb_thread -mkl_core -ltbb + The KOKKOS package no longer supports the the traditional make build. + You need to build LAMMPS with CMake. Advanced KOKKOS compilation settings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -838,54 +771,43 @@ the full list (which keeps changing as the Kokkos package itself evolves), please consult the Kokkos library documentation. As alternative to using multi-threading via OpenMP -(``-DKokkos_ENABLE_OPENMP=on`` or ``KOKKOS_DEVICES=OpenMP``) it is also -possible to use Posix threads directly (``-DKokkos_ENABLE_PTHREAD=on`` -or ``KOKKOS_DEVICES=Pthread``). While binding of threads to individual -or groups of CPU cores is managed in OpenMP with environment variables, -you need assistance from either the "hwloc" or "libnuma" library for the -Pthread thread parallelization option. To enable use with CMake: -``-DKokkos_ENABLE_HWLOC=on`` or ``-DKokkos_ENABLE_LIBNUMA=on``; and with -conventional make: ``KOKKOS_USE_TPLS=hwloc`` or -``KOKKOS_USE_TPLS=libnuma``. - -The CMake option ``-DKokkos_ENABLE_LIBRT=on`` or the makefile setting -``KOKKOS_USE_TPLS=librt`` enables the use of a more accurate timer -mechanism on many Unix-like platforms for internal profiling. - -The CMake option ``-DKokkos_ENABLE_DEBUG=on`` or the makefile setting -``KOKKOS_DEBUG=yes`` enables printing of run-time -debugging information that can be useful. It also enables runtime -bounds checking on Kokkos data structures. As to be expected, enabling -this option will negatively impact the performance and thus is only -recommended when developing a Kokkos-enabled style in LAMMPS. - -The CMake option ``-DKokkos_ENABLE_CUDA_UVM=on`` or the makefile -setting ``KOKKOS_CUDA_OPTIONS=enable_lambda,force_uvm`` enables the -use of CUDA "Unified Virtual Memory" (UVM) in Kokkos. UVM allows to -transparently use RAM on the host to supplement the memory used on the -GPU (with some performance penalty) and thus enables running larger -problems that would otherwise not fit into the RAM on the GPU. +(``-DKokkos_ENABLE_OPENMP=on``) it is also possible to use Posix threads +directly (``-DKokkos_ENABLE_PTHREAD=on``). While binding of threads to +individual or groups of CPU cores is managed in OpenMP with environment +variables, you need assistance from either the "hwloc" or "libnuma" +library for the Pthread thread parallelization option. To enable use +with CMake: ``-DKokkos_ENABLE_HWLOC=on`` or +``-DKokkos_ENABLE_LIBNUMA=on``. + +The CMake option ``-DKokkos_ENABLE_LIBRT=on`` enables the use of a more +accurate timer mechanism on many Unix-like platforms for internal +profiling. + +The CMake option ``-DKokkos_ENABLE_DEBUG=on`` enables printing of +run-time debugging information that can be useful. It also enables +runtime bounds checking on Kokkos data structures. As to be expected, +enabling this option will negatively impact the performance and thus is +only recommended when developing a Kokkos-enabled style in LAMMPS. + +The CMake option ``-DKokkos_ENABLE_CUDA_UVM=on`` enables the use of CUDA +"Unified Virtual Memory" (UVM) in Kokkos. UVM allows to transparently +use RAM on the host to supplement the memory used on the GPU (with some +performance penalty) and thus enables running larger problems that would +otherwise not fit into the RAM on the GPU. The CMake option ``-D KOKKOS_PREC=value`` sets the floating point -precision of the calculations, where ``value`` can be one of: -``double`` (FP64, default) or ``mixed`` (FP64 for accumulation of -forces, energy, and virial, FP32 otherwise) or ``single`` (FP32). -Similarly the makefile settings ``-DLMP_KOKKOS_DOUBLE_DOUBLE`` -(default), ``-DLMP_KOKKOS_SINGLE_DOUBLE``, and -``-DLMP_KOKKOS_SINGLE_SINGLE`` set double, mixed, single precision -respectively. When using reduced precision (single or mixed), the -simulation should be carefully checked to ensure it is stable and that -energy is acceptably conserved. +precision of the calculations, where ``value`` can be one of: ``double`` +(FP64, default) or ``mixed`` (FP64 for accumulation of forces, energy, +and virial, FP32 otherwise) or ``single`` (FP32). When using reduced +precision (single or mixed), the simulation should be carefully checked +to ensure it is stable and that energy is acceptably conserved. The CMake option ``-D KOKKOS_LAYOUT=value`` sets the array layout of Kokkos views (e.g. forces, velocities, etc.) on GPUs, where ``value`` can be one of: ``legacy`` (mostly LayoutRight, default) or ``default`` -(mostly LayoutLeft). Similarly the makefile settings -``-DLMP_KOKKOS_LAYOUT_LEGACY`` (default) and -``-DLMP_KOKKOS_LAYOUT_DEFAULT`` set legacy or default layouts -respectively. Using the default layout (LayoutLeft) can give speedup -on GPUs for some models, but a slowdown for others. LayoutRight is -always used for positions on GPUs since it has been found to be +(mostly LayoutLeft). Using the default layout (LayoutLeft) can give +speedup on GPUs for some models, but a slowdown for others. LayoutRight +is always used for positions on GPUs since it has been found to be faster, and when compiling exclusively for CPUs. ---------- diff --git a/doc/src/Build_make.rst b/doc/src/Build_make.rst index 34d696cafbf..036beaf4d8b 100644 --- a/doc/src/Build_make.rst +++ b/doc/src/Build_make.rst @@ -127,6 +127,3 @@ their settings may become outdated, too: make knl # build with the INTEL package optimized for KNLs make opt # build with the OPT package optimized for CPUs make omp # build with the OPENMP package optimized for OpenMP - make kokkos_omp # build with the KOKKOS package for OpenMP - make kokkos_cuda_mpi # build with the KOKKOS package for GPUs - make kokkos_phi # build with the KOKKOS package for KNLs diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst index d9bd2cbc95c..f057d218250 100644 --- a/doc/src/Build_settings.rst +++ b/doc/src/Build_settings.rst @@ -459,11 +459,21 @@ supports the "popen" function in the standard runtime library. Read or write compressed files ----------------------------------------- +.. versionchanged:: TBD + + Added support for ``brotli`` and ``7-zip`` + If this option is enabled, large files can be read or written with compression by ``gzip`` or similar tools by several LAMMPS commands, -including :doc:`read_data `, :doc:`rerun `, and -:doc:`dump `. Supported compression tools and algorithms are currently -``gzip``, ``bzip2``, ``zstd``, ``xz``, ``lz4``, and ``lzma`` (via xz). +including :doc:`read_data `, :doc:`write_data `, +:doc:`rerun `, :doc:`dump `, and :doc:`write_dump +`. Supported compression tools and algorithms are currently +``gzip``, ``bzip2``, ``zstd``, ``xz``, ``lz4``, ``lzma`` (via xz), +``brotli``, and ``7-zip (via 7z)``. LAMMPS checks at runtime, which +compression commands are available and adjusts the check for supported +suffixes accordingly. The list of available compression formats and +suffixes is shown when running LAMMPS with the :doc:`-help or -h +command_line flag `. .. tabs:: diff --git a/doc/src/Classes.rst b/doc/src/Classes.rst index 6bcc30971bd..2cf82eddf16 100644 --- a/doc/src/Classes.rst +++ b/doc/src/Classes.rst @@ -36,3 +36,11 @@ some selected examples for derived classes of specific models. Classes_lammps Classes_atom Classes_input + +----------------------------------- + +.. toctree:: + :caption: Individual Utility Classes + :name: lammpsutils + + Classes_cite diff --git a/doc/src/Classes_cite.rst b/doc/src/Classes_cite.rst new file mode 100644 index 00000000000..d297ec3c62a --- /dev/null +++ b/doc/src/Classes_cite.rst @@ -0,0 +1,103 @@ +Citation management for contributed features +-------------------------------------------- + +LAMMPS provides a built-in mechanism to remind users to cite publications +that describe the implementation of contributed features. This is +implemented through the :cpp:class:`CiteMe ` class. + +Overview +^^^^^^^^ + +When users use specific features in LAMMPS, a citation reminder +can be configured in the contributed source code to remind users +which publications they should cite. +Citations are output in three ways: + +* To the screen (with configurable verbosity) +* To the log file (with configurable verbosity) +* To an optional BibTeX file for easy integration with bibliography managers + +The system automatically deduplicates citations, so each publication is +listed only once even if multiple features reference it or they are used +multiple times. + +Adding a citation reminder to contributed code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you are contributing a new feature to LAMMPS you can add a reminder +for citing a publication describing the implementation of that feature. +This is a simple two-step process: + +**Step 1: Define the citation string** + +At the top of your implementation file (typically a ``.cpp`` file), +define a static string containing the citation in BibTeX format. The +string should start with a single line description including a DOI URL, +followed by a complete BibTeX entry. Example: + +.. code-block:: c++ + + static const char cite_my_feature[] = + "my_feature command: https://doi.org/10.1234/example.doi\n\n" + "@Article{AuthorYear,\n" + " author = {First Author and Second Author},\n" + " title = {Title of the Paper},\n" + " journal = {Journal Name},\n" + " year = 2024,\n" + " volume = 100,\n" + " pages = {1-10}\n" + "}\n\n"; + +**Step 2: Register the citation** + +In your style's constructor, add a call to register the citation. Always +check that the ``citeme`` pointer instance in the LAMMPS is available +before calling, since the pointer will be NULL when citation tracking is +disabled via a command line option: + +.. code-block:: c++ + + MyStyle::MyStyle(LAMMPS *lmp) : Parent(lmp) + { + if (lmp->citeme) lmp->citeme->add(cite_my_feature); + // ... rest of constructor code + } + +**Output:** + +The example from above will produce by default the following output: + +.. parsed-literal:: + + CITE-CITE-CITE-CITE-CITE-CITE-CITE-CITE-CITE-CITE-CITE-CITE-CITE + + Your simulation uses code contributions which should be cited: + + - my_feature command: https://doi.org/10.1234/example.doi + + The file log.cite lists these citations in BibTeX format. + + CITE-CITE-CITE-CITE-CITE-CITE-CITE-CITE-CITE-CITE-CITE-CITE-CITE + +Implementation details +^^^^^^^^^^^^^^^^^^^^^^ + +The :cpp:class:`CiteMe ` class uses hash-based +deduplication to ensure each citation is shown only once, even if multiple +features in a simulation reference the same publication. Only MPI rank 0 +performs citation output to avoid flooding the output in parallel runs. + +Citations added with :cpp:func:`CiteMe::add() ` are: + +1. Written immediately to the BibTeX file (if enabled) +2. Buffered for screen and log file output +3. Flushed to screen and log file at appropriate times (typically at the + end of the run or when LAMMPS has reached the end of the input file). + +For the complete API documentation see the class reference below: + +------------- + +.. doxygenclass:: LAMMPS_NS::CiteMe + :project: progguide + :members: diff --git a/doc/src/Commands_bond.rst b/doc/src/Commands_bond.rst index 3ac828670cc..b127227cdc5 100644 --- a/doc/src/Commands_bond.rst +++ b/doc/src/Commands_bond.rst @@ -124,7 +124,7 @@ OPT. * :doc:`class2 (ko) ` * :doc:`cosine/shift/exp (o) ` * :doc:`cosine/squared/restricted ` - * :doc:`fourier (io) ` + * :doc:`fourier (iko) ` * :doc:`harmonic (iko) ` * :doc:`helix (o) ` * :doc:`lepton (o) ` @@ -162,7 +162,7 @@ OPT. * :doc:`amoeba ` * :doc:`class2 (ko) ` * :doc:`cossq (o) ` - * :doc:`cvff (io) ` + * :doc:`cvff (iko) ` * :doc:`distance ` * :doc:`distharm ` * :doc:`fourier (o) ` diff --git a/doc/src/Commands_compute.rst b/doc/src/Commands_compute.rst index c61501e693f..62cb2b219ac 100644 --- a/doc/src/Commands_compute.rst +++ b/doc/src/Commands_compute.rst @@ -161,7 +161,7 @@ KOKKOS, o = OPENMP, t = OPT. * :doc:`temp/asphere ` * :doc:`temp/body ` * :doc:`temp/chunk ` - * :doc:`temp/com ` + * :doc:`temp/com (k) ` * :doc:`temp/cs ` * :doc:`temp/deform (k) ` * :doc:`temp/deform/eff ` diff --git a/doc/src/Commands_fix.rst b/doc/src/Commands_fix.rst index 628fde85499..c810d5b0334 100644 --- a/doc/src/Commands_fix.rst +++ b/doc/src/Commands_fix.rst @@ -13,10 +13,12 @@ OPT. * :doc:`acks2/reaxff (k) ` * :doc:`adapt ` * :doc:`adapt/fep ` - * :doc:`addforce ` + * :doc:`addforce (k) ` * :doc:`add/heat ` - * :doc:`addtorque ` + * :doc:`addtorque/atom ` + * :doc:`addtorque/group ` * :doc:`alchemy ` + * :doc:`align/self ` * :doc:`amoeba/bitorsion ` * :doc:`amoeba/pitorsion ` * :doc:`append/atoms ` @@ -72,7 +74,7 @@ OPT. * :doc:`eos/table ` * :doc:`eos/table/rx (k) ` * :doc:`evaporate ` - * :doc:`external ` + * :doc:`external (k) ` * :doc:`ffl ` * :doc:`filter/corotate ` * :doc:`flow/gauss ` @@ -81,6 +83,7 @@ OPT. * :doc:`gjf ` * :doc:`gld ` * :doc:`gle ` + * :doc:`graphics ` * :doc:`gravity (ko) ` * :doc:`grem ` * :doc:`halt ` @@ -222,6 +225,7 @@ OPT. * :doc:`saed/vtk ` * :doc:`set ` * :doc:`setforce (k) ` + * :doc:`settorque/atom ` * :doc:`setforce/spin ` * :doc:`sgcmc ` * :doc:`shake (k) ` @@ -257,6 +261,7 @@ OPT. * :doc:`ttm ` * :doc:`ttm/grid ` * :doc:`ttm/mod ` + * :doc:`ttm/thermal ` * :doc:`tune/kspace ` * :doc:`vector ` * :doc:`viscosity ` @@ -270,6 +275,7 @@ OPT. * :doc:`wall/gran (k) ` * :doc:`wall/gran/region ` * :doc:`wall/harmonic ` + * :doc:`wall/harmonic/outside ` * :doc:`wall/lj1043 ` * :doc:`wall/lj126 ` * :doc:`wall/lj93 (k) ` diff --git a/doc/src/Commands_pair.rst b/doc/src/Commands_pair.rst index 0e2eb490039..73d3d9c4554 100644 --- a/doc/src/Commands_pair.rst +++ b/doc/src/Commands_pair.rst @@ -14,7 +14,7 @@ OPT. * :doc:`hybrid (ko) ` * :doc:`hybrid/molecular (o) ` * :doc:`hybrid/overlay (ko) ` - * :doc:`hybrid/scaled (o) ` + * :doc:`hybrid/scaled (ko) ` * :doc:`kim ` * :doc:`list ` * :doc:`tracker ` @@ -192,7 +192,7 @@ OPT. * :doc:`lj/smooth (go) ` * :doc:`lj/smooth/linear (o) ` * :doc:`lj/switch3/coulgauss/long ` - * :doc:`lj96/cut (go) ` + * :doc:`lj96/cut (gko) ` * :doc:`local/density ` * :doc:`lubricate (o) ` * :doc:`lubricate/poly (o) ` @@ -261,6 +261,7 @@ OPT. * :doc:`rheo ` * :doc:`rheo/solid ` * :doc:`saip/metal (t) ` + * :doc:`saip/metal/tmd (t) ` * :doc:`sdpd/taitwater/isothermal ` * :doc:`smatb ` * :doc:`smatb/single ` diff --git a/doc/src/Commands_removed.rst b/doc/src/Commands_removed.rst index e48078ce9b0..ad5e1596045 100644 --- a/doc/src/Commands_removed.rst +++ b/doc/src/Commands_removed.rst @@ -24,6 +24,13 @@ started to create problems with modern C++ compilers. LAMMPS version download and compile this version, if you want to use any of these packages. +.. toctree:: + :maxdepth: 0 + :hidden: + :glob: + + atc_* + Neighbor style and comm mode multi/old -------------------------------------- diff --git a/doc/src/Developer.rst b/doc/src/Developer.rst index d4afd6f2980..30d0f20dade 100644 --- a/doc/src/Developer.rst +++ b/doc/src/Developer.rst @@ -6,6 +6,12 @@ of the LAMMPS code. This is a work in progress and additional information will be added incrementally depending on availability of time and requests from the LAMMPS user community. +A discussion of software engineering methods applied to LAMMPS over time +and a general outline of the design and maintenance approach by the +LAMMPS developers can be found in the paper `LAMMPS: A Case Study For +Applying Modern Software Engineering to an Established Research Software +Package, ` in USRSE'25 +conference proceedings. .. toctree:: :maxdepth: 1 diff --git a/doc/src/Developer_notes.rst b/doc/src/Developer_notes.rst index 9a1b3899f60..8dc01331554 100644 --- a/doc/src/Developer_notes.rst +++ b/doc/src/Developer_notes.rst @@ -212,6 +212,7 @@ command: neighbor->add_request(this, "delete_atoms", NeighConst::REQ_FULL); +.. _error-messages: Errors, warnings, and informational messages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -251,9 +252,9 @@ linked to the LAMMPS library and have a mechanism to avoid that an error in LAMMPS terminates the application. By catching the exceptions, the application can delete the failing LAMMPS class instance and create a new one to try again. In a similar fashion, the :doc:`LAMMPS Python -module ` checks for this and then re-throws corresponding -Python exception, which in turn can be caught by the calling Python -code. +module ` checks for this and then re-throws a +corresponding Python exception, which in turn can be caught by the +calling Python code. There are multiple "signatures" that can be called: @@ -264,21 +265,22 @@ There are multiple "signatures" that can be called: - ``Error::all(FLERR, Error::NOLASTLINE, "Error message")``: this is the same as before but without the last line of input. This is preferred for errors that would happen *during* a :doc:`run ` or - :doc:`minimization `, since showing the "run" or "minimize" - command would be the last line, but is unrelated to the error. + :doc:`minimization `, since the last line would be showing + the "run" or "minimize" command yet those are unrelated to the command + *causing* the error. - ``Error::all(FLERR, idx, "Error message")``: this is for argument parsing where "idx" is the index (starting at 0) of the argument for a - LAMMPS command that is causing the failure (use -1 for the command - itself). For index 0, you need to use the constant ``Error::ARGZERO`` - to work around the inability of some compilers to disambiguate between - a NULL pointer and an integer constant 0, even with an added type cast. - The output may also include the last input line *before* and - *after*, if they differ due to substituting variables. A textual - indicator is pointing to the specific word that failed. Using the - constant ``Error::NOPOINTER`` in place of the *idx* argument will - suppress the marker and then the behavior is like the *idx* argument - is not provided. + LAMMPS command that is causing the failure (use ``Error::COMMAND`` for + the command itself). For index 0, i.e. the first command argument, + 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* substituting + variables, if they differ. A textual indicator is pointing to the + specific word that failed. Using the constant ``Error::NOPOINTER`` in + place of the *idx* argument will suppress the marker and then the + behavior is like the *idx* argument is not provided. FLERR is a macro containing the filename and line where the Error class is called and that information is appended to the error message. This diff --git a/doc/src/Developer_unittest.rst b/doc/src/Developer_unittest.rst index a925d20c5e9..2b0cdab3bb5 100644 --- a/doc/src/Developer_unittest.rst +++ b/doc/src/Developer_unittest.rst @@ -147,7 +147,7 @@ additional tests. FFT Testing Infrastructure """""""""""""""""""""""""" -.. versionadded:: TBD +.. versionadded:: 10Dec2025 The FFT tests (``test_fft3d.cpp`` and ``test_fft3d_kokkos.cpp``) validate the LAMMPS FFT wrapper implementations for both standard (CPU) diff --git a/doc/src/Errors_details.rst b/doc/src/Errors_details.rst index 11e09a62080..04a4f19a3aa 100644 --- a/doc/src/Errors_details.rst +++ b/doc/src/Errors_details.rst @@ -471,24 +471,41 @@ suitably large value. .. _err0010: -Unrecognized ... style ... is part of ... package which is not enabled in this LAMMPS binary --------------------------------------------------------------------------------------------- - -The LAMMPS executable (binary) being used was not compiled with a -package containing the specified style. This indicates that the -executable needs to be re-built after enabling the correct package in -the relevant Makefile or CMake build directory. See -:doc:`Section 3. Build LAMMPS ` for more details. One can check -if the expected package and pair style is present in the executable by -running it with the ``-help`` (or ``-h``) flag on the command line. One -common oversight, especially for beginner LAMMPS users, is enabling the -package but forgetting to run commands to rebuild (e.g., to run the -final ``make`` or ``cmake`` command). +Unrecognized ... style ... +-------------------------- + +There are multiple variants of this error message. The most common +case is that there is a typo or syntax error in the input file and +the style name of a command was not found in the LAMMPS executable. + +Another case is that the input is using the correct style command, but +the LAMMPS executable in use was not compiled with the package +containing that specific style. LAMMPS executables include tables of +all available packages and styles in the distribution, and thus will +print in this case a message indicating which package is missing. This +indicates that the executable needs to be re-built after enabling the +correct package. See the :doc:`LAMMPS build instructions ` for +more details on including packages. One can check if the expected +package and style is present in the executable by running it with the +``-help`` (or ``-h``) flag on the command line. One common oversight, +especially for LAMMPS users with limited experience in compiling +software from source, is enabling the package but forgetting to rebuild +or install the executable. One can also check the documentation for the +style in question for a "Restrictions" section, which should indicate +which requirements apply to a given command. + +Finally, there is the case that the necessary package is included, but +the missing style depends also on *another* style from a *different* +package and *this* package is missing. In that case, LAMMPS does not +know which package is missing, and it is necessary to check the +documentation for the missing style in the manual. If this error occurs with an executable that the user does not control (e.g., through a module on HPC clusters), the user will need to get in contact with the relevant person or people who can update the -executable. +executable. In rare cases, there may be licensing or portability issues +that prevent including a package in publicly accessible binaries or in a +specific environment. .. _err011: @@ -1087,3 +1104,15 @@ a specific atom, one has to use a reference with a lower case 'c' (e.g. 'c_name') for the former and upper case 'C' (e.g. 'C_name') for the latter. The same applies to fix styles. The full details are in the documentation for the :doc:`variable command `. + +.. _err0038: + +The ... style ... is no longer available +---------------------------------------- + +While the LAMMPS developers try to keep the software backward compatible +as far as input files and file formats are concerned, this is not always +desired and changes are made and commands renamed or removed. In that +case an error message is printed describing why the command cannot be +executed. More details can be found on the manual page +:doc:`Commands_removed`. diff --git a/doc/src/Errors_messages.rst b/doc/src/Errors_messages.rst index 008ee26ae02..526c74fa66e 100644 --- a/doc/src/Errors_messages.rst +++ b/doc/src/Errors_messages.rst @@ -1123,12 +1123,6 @@ Please also see the page with :doc:`Warning messages `. *Cannot yet use fix bond/create with this improper style* This is a current restriction in LAMMPS. -*Cannot yet use minimize with Kokkos* - This feature is not yet supported. - -*Cannot yet use pair hybrid with Kokkos* - This feature is not yet supported. - *Cannot zero Langevin force of 0 atoms* The group has zero atoms, so you cannot request its force be zeroed. @@ -2092,9 +2086,6 @@ Please also see the page with :doc:`Warning messages `. *Fix langevin gjf cannot have period equal to dt/2* If the period is equal to dt/2 then division by zero will happen. -*Fix langevin gjf with tbias is not yet implemented with kokkos* - This option is not yet available. - *Fix langevin omega is not yet implemented with kokkos* This option is not yet available. @@ -2224,10 +2215,6 @@ Please also see the page with :doc:`Warning messages `. The principal moments of inertia computed for a rigid body are not within the required tolerances. -*Fix shake cannot be used with minimization* - Cannot use fix shake while doing an energy minimization since - it turns off bonds that should contribute to the energy. - *Fix shake molecule template must have shake info* The defined molecule does not specify SHAKE information. diff --git a/doc/src/Howto_chunk.rst b/doc/src/Howto_chunk.rst index ea000eb22ff..d1ee7621dc3 100644 --- a/doc/src/Howto_chunk.rst +++ b/doc/src/Howto_chunk.rst @@ -96,7 +96,7 @@ category: * :doc:`compute msd/chunk ` * :doc:`compute property/chunk ` * :doc:`compute temp/chunk ` -* :doc:`compute torque/chunk ` +* :doc:`compute torque/chunk ` * :doc:`compute vcm/chunk ` They each take the ID of a :doc:`compute chunk/atom diff --git a/doc/src/Intro_portability.rst b/doc/src/Intro_portability.rst index 27093bd060e..b505578be49 100644 --- a/doc/src/Intro_portability.rst +++ b/doc/src/Intro_portability.rst @@ -2,11 +2,10 @@ LAMMPS portability and compatibility ------------------------------------ The primary form of distributing LAMMPS is through highly portable -source code. But also several ways of obtaining LAMMPS as :doc:`precompiled -packages or through automated build mechanisms ` exist. Most -of LAMMPS is written in C++, some support tools are written in Fortran -or Python or MATLAB. - +source code. But also several ways of obtaining LAMMPS as +:doc:`precompiled packages or through automated build mechanisms +` exist. Most of LAMMPS is written in C++, some support tools +are written in Fortran or Python or MATLAB. Programming language standards ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -14,10 +13,11 @@ Programming language standards .. versionchanged:: 10Sep2025 The C++ code in LAMMPS currently requires a compiler that is compatible -with the C++17 standard. The Kokkos library used for the KOKKOS -package currently also requires at least C++17. If your compilers are not -compatible and you cannot upgrade, please use LAMMPS version 22 July 2025, -which requires only C++11 as the minimum C++ standard. +with the C++17 standard. The Kokkos library used for the KOKKOS package +currently also requires at least C++17. If your compilers are not +compatible *and* you cannot upgrade to a compatible version, please use +LAMMPS version 22 July 2025, which requires only C++11 as the minimum +C++ standard. Most of the Python code in LAMMPS is written to be compatible with Python 3.6 and later. @@ -27,7 +27,7 @@ Most of the Python code in LAMMPS is written to be compatible with Python 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. +Python 3, please notify :doc:`the LAMMPS developers `. Build systems ^^^^^^^^^^^^^ @@ -92,14 +92,44 @@ by Linux distributions that bundle LAMMPS. Portability compliance ^^^^^^^^^^^^^^^^^^^^^^ -Only a subset of the LAMMPS source code is *fully* compliant to *all* -of the above mentioned standards. This is rather typical for projects -like LAMMPS that largely depend on contributions from the user community. -Not all contributors are trained as programmers and not all of them have -access to multiple platforms for testing. As part of the continuous -integration process, however, all contributions are automatically tested -to compile, link, and pass some runtime tests on a selection of Linux -flavors, macOS, and Windows, and on Linux with different compilers. -Thus portability issues are often found before a pull request is merged. -Other platforms may be checked occasionally or when portability bugs are -reported. +Only a subset of the LAMMPS source code is *fully* compliant to *all* of +the above mentioned standards. There is also the case that the source +code bundled with LAMMPS *is* compliant and portable, but an external +library it depends on is not. + +This is rather typical for projects like LAMMPS that largely depend on +contributions from the user community. Not all contributors are trained +as programmers and not all of them have access to multiple platforms for +testing or are familiar with requirement of different C++ standards. As +part of the continuous integration process, however, all contributions +are automatically tested to compile, link, and pass *some* runtime tests +on a selection of Linux flavors, macOS, and Windows, and on Linux with +different compilers. Thus portability issues are often found *before* a +pull request is merged or a release is made. Other platforms may be +checked occasionally or when portability bugs are reported. + +Code review and static code analysis +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In addition to using automated tests, code contributed to LAMMPS is +subject to a code review by core LAMMPS developers (that includes +contributions by the core LAMMPS developers themselves). + +we also make use of a number static code analysis tools for maintaining +and improving the quality of the LAMMPS source code through tools like +`Coverity SCAN `_, `CodeQL +`_, `Clang Static Analyzer +`_, `Clang-Tidy +`_ and simply looking at +compiler warnings. + +CodeQL alerts for the ``develop`` branch of LAMMPS can be seen at +https://github.com/lammps/lammps/security/code-scanning and static code +analysis reports for the ``develop`` branch from the clang tools are +available at https://download.lammps.org/analysis/ + +A discussion of software engineering methods applied to LAMMPS over time +can be found in the paper `LAMMPS: A Case Study For Applying Modern +Software Engineering to an Established Research Software Package, +` in USRSE'25 conference +proceedings. diff --git a/doc/src/JPG/fix-graphics-example.png b/doc/src/JPG/fix-graphics-example.png new file mode 100644 index 00000000000..d9b1d4a5cbf Binary files /dev/null and b/doc/src/JPG/fix-graphics-example.png differ diff --git a/doc/src/Modify_fix.rst b/doc/src/Modify_fix.rst index 18b51d6e137..fd089efa5db 100644 --- a/doc/src/Modify_fix.rst +++ b/doc/src/Modify_fix.rst @@ -129,6 +129,8 @@ derived class. See ``src/fix.h`` for additional details. +---------------------------+--------------------------------------------------------------------------------------------+ | thermo | compute quantities for thermodynamic output (optional) | +---------------------------+--------------------------------------------------------------------------------------------+ +| image | pass lists of graphics objects and their parameters to :doc:`dump image fix ` | ++---------------------------+--------------------------------------------------------------------------------------------+ Typically, only a small fraction of these methods are defined for a particular fix. Setmask is mandatory, as it determines when the fix diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst index e807bd185ae..9495c9cb3aa 100644 --- a/doc/src/Modify_requirements.rst +++ b/doc/src/Modify_requirements.rst @@ -78,9 +78,9 @@ Integration testing (strict) Where possible we use available continuous integration tools to search for common programming mistakes, portability limitations, incompatible -formatting, and undesired side effects. Contributed code must pass the +formatting, and undesired side effects. Contributed code must pass the automated tests on GitHub before it can be merged with the LAMMPS -distribution. These tests compile LAMMPS in a variety of environments +distribution. These tests compile LAMMPS in a variety of environments and settings and run the bundled unit tests. At the discretion of the LAMMPS developer managing the pull request, additional tests may be activated that test for "side effects" on running a collection of @@ -105,7 +105,7 @@ Documentation (strict) Contributions that add new styles or commands or augment existing ones must include the corresponding new or modified documentation in `ReStructuredText format `_ (.rst files in the ``doc/src/`` -folder). The documentation should be written in American English and the +folder). The documentation should be written in American English and the .rst file must only use ASCII characters, so it can be cleanly translated to PDF files (via `sphinx `_ and PDFLaTeX). Special characters may be included via embedded math @@ -115,8 +115,8 @@ expression typeset in a LaTeX subset. When adding new commands, they need to be integrated into the sphinx documentation system, and the corresponding command tables and lists -updated. When translating the documentation into html files there -should be no warnings. When adding a new package, some lists +updated. When translating the documentation into html files there +should be no warnings. When adding a new package, some lists describing packages must also be updated as well as a package specific description added. Likewise, if necessary, some package specific build instructions should be included. @@ -209,10 +209,11 @@ Build system (strict) LAMMPS currently supports two build systems: one that is based on :doc:`traditional Makefiles ` and one that is based on -:doc:`CMake `. As of fall 2024, it is no longer required -to support the traditional make build system. New packages may choose -to only support building with CMake. Additions to existing packages -must follow the requirements set by that package. +:doc:`CMake `. As of fall 2025, it is no longer required +to support the traditional :doc:`traditional GNU make build system +`. New packages may choose to only support :doc:`building +with CMake `. Additions to existing packages must follow +the requirements set by that package. For a single pair of header and implementation files that are an independent feature, it is usually only required to add them to @@ -241,7 +242,7 @@ should only use letters, numbers, or forward slashes. They should be descriptive and initialisms should be avoided unless they are well established (e.g. lj for Lennard-Jones). For a compute style "some/name" the source files must be called ``compute_some_name.h`` and -``compute_some_name.cpp``. The "include guard" in the header file would +``compute_some_name.cpp``. The "include guard" in the header file would then be ``LMP_COMPUTE_SOME_NAME_H`` and the class name ``ComputeSomeName``. @@ -264,7 +265,7 @@ Examples (preferred) For many new features, it is preferred that example scripts (simple, small, fast to complete on 1 CPU) are included that demonstrate the -use of new or extended functionality. These are typically include +use of new or extended functionality. These are typically include under the examples or examples/PACKAGES directory and are further described on the :doc:`examples page `. Guidelines for input scripts include: @@ -314,7 +315,7 @@ The new policy encourages more specific error messages that ideally indicate the cause directly, and requiring no further lookup. This is aided by the `{fmt} library `_ enabling Error class methods that take a variable number of arguments and an error text that -will be treated like a {fmt} syntax format string. Error messages should +will be treated like a {fmt} syntax format string. Error messages should still preferably be kept to a single line or two lines at most. For more complex explanations or errors that have multiple possible @@ -346,29 +347,25 @@ Citation reminder (optional) If there is a paper of yours describing your feature (either the algorithm/science behind the feature itself, or its initial usage, or -its implementation in LAMMPS), you can add the citation to the \*.cpp -source file. See ``src/DIFFRACTION/compute_saed.cpp`` for an example. -A BibTeX format citation is stored in a string variable at the top of -the file, and a single line of code registering this variable is added -to the constructor of the class. When your feature is used, then -LAMMPS (by default) will print the brief info and the DOI in the first -line to the screen and the full citation to the log file. +its implementation in LAMMPS), you can add the citation to the ``.cpp`` +source file. A description of how to add the reminder is +:doc:`available elsewhere in this manual `. If there is additional functionality (which may have been added later) described in a different publication, additional citation descriptions -may be added so long as they are only registered when the -corresponding keyword activating this functionality is used. +may be added so long as they are only registered when the corresponding +keyword activating this functionality is used. With these options, it is possible to have LAMMPS output a specific -citation reminder whenever a user invokes your feature from their -input script. Please note that you should *only* use this for the -*most* relevant paper for a feature and a publication that you or your -group authored. E.g. adding a citation in the source code for a paper -by Nose and Hoover if you write a fix that implements their integrator -is not the intended usage. That kind of citation should just be -included in the documentation page you provide describing your -contribution. If you are not sure what the best option would be, -please contact the LAMMPS developers for advice. +citation reminder whenever a user invokes your feature from their input +script. Please note that you should *only* use this for the *most* +relevant paper for a feature and a publication that you or your group +authored. E.g. adding a citation in the source code for a paper by Nose +and Hoover if you write a fix that implements their integrator is not +the intended usage. That kind of citation should just be included in +the documentation page you provide describing your contribution. If you +are not sure what the best option would be, please contact the LAMMPS +developers for advice. .. _ReqUnitTesting: @@ -376,11 +373,11 @@ Testing (optional) ------------------ If your contribution contains new utility functions or a supporting -class (i.e. anything that does not depend on a LAMMPS object), new -unit tests should be added to a suitable folder in the ``unittest`` -tree. When adding a new LAMMPS style computing forces or selected -fixes, a ``.yaml`` file with a test configuration and reference data -should be added for the styles where a suitable tester program already -exists (e.g. pair styles, bond styles, etc.). Please see :ref:`this -section in the manual ` for more information on how to -enable, run, and expand testing. +class (i.e. anything that does not depend on a LAMMPS object), new unit +tests should be added to a suitable folder in the ``unittest`` tree. +When adding a new LAMMPS style computing forces or selected fixes, a +``.yaml`` file with a test configuration and reference data should be +added for the styles where a suitable tester program already exists +(e.g. pair styles, bond styles, etc.). Please see :ref:`this section in +the manual ` for more information on how to enable, run, and +expand testing. diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst index 1a66545054f..0da940565ce 100644 --- a/doc/src/Packages_details.rst +++ b/doc/src/Packages_details.rst @@ -1054,8 +1054,8 @@ This package has :ref:`specific installation instructions ` on the * ``lib/gpu/README`` * :doc:`Accelerator packages ` * :doc:`GPU package ` -* :doc:`Section 2.6 -sf gpu ` -* :doc:`Section 2.6 -pk gpu ` +* :doc:`Section 4.2 -sf gpu ` +* :doc:`Section 4.2 -pk gpu ` * :doc:`package gpu ` * :doc:`Commands ` pages (:doc:`pair `, :doc:`kspace `) for styles followed by (g) @@ -1165,8 +1165,8 @@ This package has :ref:`specific installation instructions ` on the :doc:` * ``src/INTEL/README`` * :doc:`Accelerator packages ` * :doc:`INTEL package ` -* :doc:`Section 2.6 -sf intel ` -* :doc:`Section 2.6 -pk intel ` +* :doc:`Section 4.2 -sf intel ` +* :doc:`Section 4.2 -pk intel ` * :doc:`package intel ` * Search the :doc:`commands ` pages (:doc:`fix `, :doc:`compute `, :doc:`pair `, :doc:`bond, angle, dihedral, improper `, :doc:`kspace `) for styles followed by (i) @@ -1302,9 +1302,9 @@ This package has :ref:`specific installation instructions ` on the :doc: * ``lib/kokkos/README`` * :doc:`Accelerator packages ` * :doc:`KOKKOS package ` -* :doc:`Section 2.6 -k on ... ` -* :doc:`Section 2.6 -sf kk ` -* :doc:`Section 2.6 -pk kokkos ` +* :doc:`Section 4.2 -k on ... ` +* :doc:`Section 4.2 -sf kk ` +* :doc:`Section 4.2 -pk kokkos ` * :doc:`package kokkos ` * Search the :doc:`commands ` pages (:doc:`fix `, :doc:`compute `, :doc:`pair `, :doc:`bond, angle, dihedral, improper `, @@ -2203,7 +2203,7 @@ This package has :ref:`specific installation instructions ` on the :doc:`Bu * ``src/OPT``: filenames -> commands * :doc:`Accelerator packages ` * :doc:`OPT package ` -* :doc:`Section 2.6 -sf opt ` +* :doc:`Section 4.2 -sf opt ` * Search the :doc:`pair style ` page for styles followed by (t) * `Benchmarks page `_ of website diff --git a/doc/src/Run_formats.rst b/doc/src/Run_formats.rst index d03227f091a..e2bd86f37d4 100644 --- a/doc/src/Run_formats.rst +++ b/doc/src/Run_formats.rst @@ -78,7 +78,7 @@ For floating point numbers in scientific notation, the Fortran double precision notation "1.1d3" is not accepted; you have to use "1100", "1100.0" or "1.1e3". -Input file +Input File ^^^^^^^^^^ A LAMMPS input file is a text file with commands. It is read @@ -161,7 +161,7 @@ recommended to always have an empty line at the end of an input file. The specific details describing how LAMMPS input is processed and parsed are explained in :doc:`Commands_parse`. -Data file +Data File ^^^^^^^^^ A LAMMPS data file contains a description of a system suitable for @@ -302,7 +302,7 @@ Molecule-ID', one for each atom in the system. For adding charges to atom style molecular with fix property/atom, the "Atoms" section is now formatted according to the atom style and a "Charges" section is added. -Molecule file +Molecule File ^^^^^^^^^^^^^ Molecule files for use with the :doc:`molecule command ` look @@ -376,7 +376,7 @@ if the molecule command is issued *before* the simulation box is defined. Otherwise, the molecule command can derive the required settings internally. -Restart file +Restart File ^^^^^^^^^^^^ LAMMPS restart files are binary files and not available in text format. @@ -409,6 +409,69 @@ are in the ``lmprestart.h`` header file. LAMMPS restart files are not expected to be portable between platforms or LAMMPS versions, but changes to the file format are rare. +.. _json-dump-files: + +JSON Dump Files +^^^^^^^^^^^^^^^ + +LAMMPS can print information about molecules and other sets of atoms during +a run, in JSON format. Several fixes currently support dumping JSON files +in the 'molecules' style, including :doc:`fix bond/react ` +and the *delete* keyword of :doc:`fix reaxff/species `. +The JSON 'dump molecules' format lists sets of atoms in the style of the +:doc:`JSON molecule file `, where more discussion of JSON schema +can be found. Here is an generic example of a JSON output file that dumped +one water molecule on the first timestep: + +.. code-block:: json + + { + "application": "LAMMPS", + "units": "real", + "format": "dump", + "style": "molecules", + "revision": 1, + "timesteps": [ + { + "timestep": 1, + "molecules": [ + { + "types": { + "format": ["atom-id", "type"], + "data": [ + [1368, "H"], + [1366, "O"], + [1367, "H"] + ] + }, + "coords": { + "format": ["atom-id", "x", "y", "z"], + "data": [ + [1368, 26.787767440427466, 29.785528640296768, 25.85197353660144], + [1366, 26.641801222582824, 29.868106247702887, 24.91285138212243], + [1367, 25.69611192416744, 30.093425787807448, 24.914380215672846] + ] + } + } + ] + } + ] + } + +The required first-level keys of the JSON format output are "application", +"format", "style", "revision", and "timesteps", and optional keys are +"units" and "title". The value of the "timesteps" key is an array of +objects that contain data for each timestep on which a molecule was dumped, +and the other first-level keys identify this JSON schema. The objects in +"timesteps" contains two mandatory keys, "timestep" and "molecules". The +"molecules" key is an array of :doc:`LAMMPS molecule JSON ` +objects, and may contain other keys that contain metadata for each +molecule. The "format" keys within molecule JSON objects are only printed +once per output file, for brevity. The "atom-id" values are atom IDs from +the simulation, and the "type" values are atom types. In the above +example, the types were reported as strings corresponding to elements using +:doc:`type labels `. + .. Native Dump file .. ^^^^^^^^^^^^^^^^ .. diff --git a/doc/src/Speed_kokkos.rst b/doc/src/Speed_kokkos.rst index 286b8a058b7..7e5014faba4 100644 --- a/doc/src/Speed_kokkos.rst +++ b/doc/src/Speed_kokkos.rst @@ -162,10 +162,10 @@ below. .. note:: - When using a single OpenMP thread, the Kokkos Serial back end (i.e. - ``Makefile.kokkos_mpi_only``) will give better performance than the OpenMP - back end (i.e. ``Makefile.kokkos_omp``) because some of the overhead to make - the code thread-safe is removed. + When using ONLY a single OpenMP thread, the Kokkos Serial back end + (i.e. ``-D Kokkos_ENABLE_SERIAL=yes``) will give better performance + than the OpenMP back end (i.e. ``-D Kokkos_ENABLE_OPENMP=yes``) + because some of the overhead to make the code thread-safe is removed. .. note:: @@ -405,10 +405,8 @@ or the corresponding command-line flag. If you still get a segmentation fault, despite running with only one MPI process or using the command-line flag to turn off expecting a GPU-aware MPI library, then using the CMake compile setting -``-DKokkos_ENABLE_DEBUG=on`` or adding ``KOKKOS_DEBUG=yes`` to your -machine makefile for building with traditional make will generate useful -output that can be passed to the LAMMPS developers for further -debugging. +``-DKokkos_ENABLE_DEBUG=on`` will generate useful output that can be +passed to the LAMMPS developers for further debugging. Troubleshooting memory allocation on GPUs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -435,8 +433,7 @@ between CPU and GPU as needed. The resulting LAMMPS performance depends on `memory access pattern, data residency, and GPU memory oversubscription `_ -. The CMake option ``-DKokkos_ENABLE_CUDA_UVM=on`` or the makefile -setting ``KOKKOS_CUDA_OPTIONS=enable_lambda,force_uvm`` enables using +. The CMake option ``-DKokkos_ENABLE_CUDA_UVM=on`` enables using :ref:`UVM with Kokkos ` when compiling LAMMPS. Run with the KOKKOS package by editing an input script @@ -467,16 +464,9 @@ wish to change any of its option defaults, as set by the "-k on" **Using OpenMP threading and CUDA together:** With the KOKKOS package, both OpenMP multi-threading and GPUs can be -compiled and used together in a few special cases. In the makefile for -the conventional build, the ``KOKKOS_DEVICES`` variable must include both, -"Cuda" and "OpenMP", as is the case for ``/src/MAKE/OPTIONS/Makefile.kokkos_cuda_mpi``. - -.. code-block:: bash - - KOKKOS_DEVICES=Cuda,OpenMP - -When building with CMake you need to enable both features as it is done -in the ``kokkos-cuda.cmake`` CMake preset file. +compiled and used together in a few special cases. You need to enable +both features as it is done in the ``kokkos-cuda.cmake`` CMake preset +file. .. code-block:: bash @@ -507,13 +497,13 @@ execution of the CPU and GPU styles will NOT overlap, except for a special case: A kspace style and/or molecular topology (bonds, angles, etc.) running -on the host CPU can overlap with a pair style running on the -GPU. First compile with ``--default-stream per-thread`` added to ``CCFLAGS`` -in the Kokkos CUDA Makefile. Then explicitly use the "/kk/host" -suffix for kspace and bonds, angles, etc. in the input file and the -"kk" suffix (equal to "kk/device") on the command-line. Also make -sure the environment variable ``CUDA_LAUNCH_BLOCKING`` is not set to "1" -so CPU/GPU overlap can occur. +on the host CPU can overlap with a pair style running on the GPU. First +compile with ``--default-stream per-thread`` added to ``-D +CMAKE_CXX_FLAGS`` when configuring with CMake. Then explicitly use the +"/kk/host" suffix for kspace and bonds, angles, etc. in the input file +and the "kk" suffix (equal to "kk/device") on the command-line. Also +make sure the environment variable ``CUDA_LAUNCH_BLOCKING`` is not set +to "1" so CPU/GPU overlap can occur. Performance to expect """"""""""""""""""""" @@ -555,3 +545,11 @@ Advanced Kokkos options There are other allowed options when building with the KOKKOS package that can improve performance or assist in debugging or profiling. They are explained on the :ref:`KOKKOS section of the build extras ` doc page, + +References +"""""""""" + +**(Johansson)** A. Johansson, E. Weinberg, C. Trott, M. McCarthy, and S. Moore. +LAMMPS-KOKKOS: Performance portable molecular dynamics across exascale architectures. +In Proceedings of the SC '25 Workshops of the International Conference for High +Performance Computing, Networking, Storage and Analysis, page 1217-1232, 2025. diff --git a/doc/src/Speed_packages.rst b/doc/src/Speed_packages.rst index 7d3e17ad1d0..898644626df 100644 --- a/doc/src/Speed_packages.rst +++ b/doc/src/Speed_packages.rst @@ -78,20 +78,15 @@ any accelerated variants available for that style. To use an accelerator package in LAMMPS, and one or more of the styles it provides, follow these general steps. Details vary from package to package and are explained in the individual accelerator doc pages, -listed above: +listed above. +-----------------------------------------------------------+---------------------------------------------+ -| build the accelerator library | only for GPU package | +| Configure LAMMPS to include the accelerator package | :doc:`Build_cmake` or :doc:`Build_make` | +-----------------------------------------------------------+---------------------------------------------+ -| install the accelerator package | ``make yes-opt``, ``make yes-intel``, etc | +| (Re-)Compile LAMMPS | :doc:`Build` | +-----------------------------------------------------------+---------------------------------------------+ -| add compile/link flags to ``Makefile.machine`` | only for INTEL, KOKKOS, OPENMP, | -| in ``src/MAKE`` | OPT packages | -+-----------------------------------------------------------+---------------------------------------------+ -| re-build LAMMPS | ``make machine`` | -+-----------------------------------------------------------+---------------------------------------------+ -| prepare and test a regular LAMMPS simulation | ``lmp_machine -in in.script;`` | -| | ``mpirun -np 32 lmp_machine -in in.script`` | +| prepare and test a regular LAMMPS simulation | ``lmp -in in.script;`` | +| | ``mpirun -np 32 lmp -in in.script`` | +-----------------------------------------------------------+---------------------------------------------+ | enable specific accelerator support via ``-k on`` | only needed for KOKKOS package | | :doc:`command-line switch ` | | @@ -105,38 +100,27 @@ listed above: | :doc:`suffix ` command | | +-----------------------------------------------------------+---------------------------------------------+ -Note that the first 4 steps can be done as a single command with -suitable make command invocations. This is discussed on the -:doc:`Packages ` doc pages, and its use is illustrated in the -individual accelerator sections. Typically these steps only need to -be done once, to create an executable that uses one or more -accelerator packages. - -The last 4 steps can all be done from the command-line when LAMMPS is -launched, without changing your input script, as illustrated in the -individual accelerator sections. Or you can add -:doc:`package ` and :doc:`suffix ` commands to your input -script. +This is discussed on the :doc:`Packages ` and :doc:`extra +Build info ` doc pages, and its use is illustrated in the +individual accelerator sections. Typically these steps only need to be +done once, to create an executable that uses one or more accelerator +packages. .. note:: - With a few exceptions, you can build a single LAMMPS executable - with all its accelerator packages installed. Note however that the - INTEL and KOKKOS packages require you to choose one of their - hardware options when building for a specific platform. I.e. CPU or - Phi option for the INTEL package. Or the OpenMP, CUDA, HIP, SYCL, - or Phi option for the KOKKOS package. Or the OpenCL, HIP, or CUDA - option for the GPU package. - -These are the exceptions. You cannot build a single executable with: - -* both the INTEL Phi and KOKKOS Phi options -* the INTEL Phi or Kokkos Phi option, and the GPU package - -As mentioned above, the `Benchmark page `_ of the LAMMPS website gives -performance results for the various accelerator packages for several -of the standard LAMMPS benchmark problems, as a function of problem -size and number of compute nodes, on different hardware platforms. + With a few exceptions, you can build a single LAMMPS executable with + all its accelerator packages installed. Note however that the INTEL + and KOKKOS packages require you to choose one of their hardware + options when building for a specific platform. I.e. CPU or Phi + option for the INTEL package. Or the OpenMP, CUDA, HIP, SYCL, or Phi + option for the KOKKOS package. Or the OpenCL, HIP, or CUDA option + for the GPU package. + +As mentioned above, the `Benchmark page +`_ of the LAMMPS website gives +performance results for the various accelerator packages for several of +the standard LAMMPS benchmark problems, as a function of problem size +and number of compute nodes, on different hardware platforms. Here is a brief summary of what the various packages provide. Details are in the individual accelerator sections. diff --git a/doc/src/angle_zero.rst b/doc/src/angle_zero.rst index c87f686bcb2..d6d4618c20e 100644 --- a/doc/src/angle_zero.rst +++ b/doc/src/angle_zero.rst @@ -47,7 +47,7 @@ going to be used to assign an equilibrium angle, e.g. for use with Restrictions """""""""""" - none +none Related commands """""""""""""""" diff --git a/doc/src/atc_add_molecule.rst b/doc/src/atc_add_molecule.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_add_molecule.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_add_species.rst b/doc/src/atc_add_species.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_add_species.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_atom_element_map.rst b/doc/src/atc_atom_element_map.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_atom_element_map.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_atom_weight.rst b/doc/src/atc_atom_weight.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_atom_weight.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_atomic_charge.rst b/doc/src/atc_atomic_charge.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_atomic_charge.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_boundary_dynamics.rst b/doc/src/atc_boundary_dynamics.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_boundary_dynamics.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_boundary_faceset.rst b/doc/src/atc_boundary_faceset.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_boundary_faceset.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_boundary_type.rst b/doc/src/atc_boundary_type.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_boundary_type.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_consistent_fe_initialization.rst b/doc/src/atc_consistent_fe_initialization.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_consistent_fe_initialization.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_control_localized_lambda.rst b/doc/src/atc_control_localized_lambda.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_control_localized_lambda.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_control_momentum.rst b/doc/src/atc_control_momentum.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_control_momentum.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_control_thermal.rst b/doc/src/atc_control_thermal.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_control_thermal.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_decomposition.rst b/doc/src/atc_decomposition.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_decomposition.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_electron_integration.rst b/doc/src/atc_electron_integration.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_electron_integration.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_equilibrium_start.rst b/doc/src/atc_equilibrium_start.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_equilibrium_start.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_extrinsic_exchange.rst b/doc/src/atc_extrinsic_exchange.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_extrinsic_exchange.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_fe_md_boundary.rst b/doc/src/atc_fe_md_boundary.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_fe_md_boundary.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_filter_scale.rst b/doc/src/atc_filter_scale.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_filter_scale.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_filter_type.rst b/doc/src/atc_filter_type.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_filter_type.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_fix.rst b/doc/src/atc_fix.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_fix.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_fix_flux.rst b/doc/src/atc_fix_flux.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_fix_flux.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_hardy_computes.rst b/doc/src/atc_hardy_computes.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_hardy_computes.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_hardy_fields.rst b/doc/src/atc_hardy_fields.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_hardy_fields.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_hardy_gradients.rst b/doc/src/atc_hardy_gradients.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_hardy_gradients.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_hardy_kernel.rst b/doc/src/atc_hardy_kernel.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_hardy_kernel.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_hardy_on_the_fly.rst b/doc/src/atc_hardy_on_the_fly.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_hardy_on_the_fly.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_hardy_rates.rst b/doc/src/atc_hardy_rates.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_hardy_rates.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_initial.rst b/doc/src/atc_initial.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_initial.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_internal_element_set.rst b/doc/src/atc_internal_element_set.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_internal_element_set.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_internal_quadrature.rst b/doc/src/atc_internal_quadrature.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_internal_quadrature.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_kernel_bandwidth.rst b/doc/src/atc_kernel_bandwidth.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_kernel_bandwidth.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_lumped_lambda_solve.rst b/doc/src/atc_lumped_lambda_solve.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_lumped_lambda_solve.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mask_direction.rst b/doc/src/atc_mask_direction.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mask_direction.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mass_matrix.rst b/doc/src/atc_mass_matrix.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mass_matrix.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_material.rst b/doc/src/atc_material.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_material.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mesh_add_to_nodeset.rst b/doc/src/atc_mesh_add_to_nodeset.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mesh_add_to_nodeset.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mesh_create.rst b/doc/src/atc_mesh_create.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mesh_create.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mesh_create_elementset.rst b/doc/src/atc_mesh_create_elementset.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mesh_create_elementset.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mesh_create_faceset_box.rst b/doc/src/atc_mesh_create_faceset_box.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mesh_create_faceset_box.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mesh_create_faceset_plane.rst b/doc/src/atc_mesh_create_faceset_plane.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mesh_create_faceset_plane.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mesh_create_nodeset.rst b/doc/src/atc_mesh_create_nodeset.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mesh_create_nodeset.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mesh_delete_elements.rst b/doc/src/atc_mesh_delete_elements.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mesh_delete_elements.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mesh_nodeset_to_elementset.rst b/doc/src/atc_mesh_nodeset_to_elementset.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mesh_nodeset_to_elementset.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mesh_output.rst b/doc/src/atc_mesh_output.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mesh_output.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mesh_quadrature.rst b/doc/src/atc_mesh_quadrature.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mesh_quadrature.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mesh_read.rst b/doc/src/atc_mesh_read.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mesh_read.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_mesh_write.rst b/doc/src/atc_mesh_write.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_mesh_write.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_output.rst b/doc/src/atc_output.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_output.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_output_boundary_integral.rst b/doc/src/atc_output_boundary_integral.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_output_boundary_integral.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_output_contour_integral.rst b/doc/src/atc_output_contour_integral.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_output_contour_integral.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_output_nodeset.rst b/doc/src/atc_output_nodeset.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_output_nodeset.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_output_volume_integral.rst b/doc/src/atc_output_volume_integral.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_output_volume_integral.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_pair_interactions.rst b/doc/src/atc_pair_interactions.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_pair_interactions.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_poisson_solver.rst b/doc/src/atc_poisson_solver.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_poisson_solver.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_read_restart.rst b/doc/src/atc_read_restart.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_read_restart.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_remove_molecule.rst b/doc/src/atc_remove_molecule.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_remove_molecule.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_remove_source.rst b/doc/src/atc_remove_source.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_remove_source.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_remove_species.rst b/doc/src/atc_remove_species.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_remove_species.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_reset_atomic_reference.rst b/doc/src/atc_reset_atomic_reference.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_reset_atomic_reference.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_reset_time.rst b/doc/src/atc_reset_time.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_reset_time.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_sample_frequency.rst b/doc/src/atc_sample_frequency.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_sample_frequency.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_set_reference_pe.rst b/doc/src/atc_set_reference_pe.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_set_reference_pe.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_source.rst b/doc/src/atc_source.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_source.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_source_integration.rst b/doc/src/atc_source_integration.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_source_integration.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_temperature_definition.rst b/doc/src/atc_temperature_definition.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_temperature_definition.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_time_filter.rst b/doc/src/atc_time_filter.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_time_filter.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_time_integration.rst b/doc/src/atc_time_integration.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_time_integration.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_track_displacement.rst b/doc/src/atc_track_displacement.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_track_displacement.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_unfix.rst b/doc/src/atc_unfix.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_unfix.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_unfix_flux.rst b/doc/src/atc_unfix_flux.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_unfix_flux.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_write_atom_weights.rst b/doc/src/atc_write_atom_weights.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_write_atom_weights.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/atc_write_restart.rst b/doc/src/atc_write_restart.rst new file mode 120000 index 00000000000..4c4215ea4e4 --- /dev/null +++ b/doc/src/atc_write_restart.rst @@ -0,0 +1 @@ +fix_atc.rst \ No newline at end of file diff --git a/doc/src/bond_bpm_spring_plastic.rst b/doc/src/bond_bpm_spring_plastic.rst index 7077ef07c42..e287247a6bc 100644 --- a/doc/src/bond_bpm_spring_plastic.rst +++ b/doc/src/bond_bpm_spring_plastic.rst @@ -141,7 +141,7 @@ will cause their reference states to be redefined. The potential energy and the single() function of this bond style returns zero. The single() function also calculates two extra bond quantities, the initial distance :math:`r_0` and the current equilibrium -length :math:`r_eq`. These extra quantities can be accessed by the +length :math:`r_{eq}`. These extra quantities can be accessed by the :doc:`compute bond/local ` command as *b1* and *b2*, respectively. diff --git a/doc/src/bond_none.rst b/doc/src/bond_none.rst index b418f5c5034..939b9c3b0bb 100644 --- a/doc/src/bond_none.rst +++ b/doc/src/bond_none.rst @@ -29,7 +29,7 @@ calculate bond statistics, but compute no bond interactions. Restrictions """""""""""" - none +none Related commands """""""""""""""" diff --git a/doc/src/bond_zero.rst b/doc/src/bond_zero.rst index cd18e857ef9..d102042295d 100644 --- a/doc/src/bond_zero.rst +++ b/doc/src/bond_zero.rst @@ -46,7 +46,7 @@ going to be used to assign an equilibrium distance, e.g. for use with Restrictions """""""""""" - none +none Related commands """""""""""""""" diff --git a/doc/src/clear.rst b/doc/src/clear.rst index a362a621090..adc70a535c2 100644 --- a/doc/src/clear.rst +++ b/doc/src/clear.rst @@ -24,15 +24,16 @@ Description This command deletes all atoms, restores all settings to their default values, and frees all memory allocated by LAMMPS. Once a clear command -has been executed, it is almost as if LAMMPS were starting over, with -only the exceptions noted below. This command enables multiple jobs to -be run sequentially from one input script. +has been executed, it is almost as if LAMMPS is completely reset, with +some exceptions noted below. The command thus allows to run multiple +jobs sequentially from a single input script, often with a loop. -These settings are not affected by a clear command: the working -directory (:doc:`shell ` command), log file status (:doc:`log -` command), echo status (:doc:`echo ` command), and input -script variables except for *atomfile* style variables (:doc:`variable -` command). +The following settings are not affected by a clear command: + + - working directory (:doc:`shell ` command) + - log file status (:doc:`log ` command) + - echo status (:doc:`echo ` command) + - input script variables except for *atomfile* style variables (:doc:`variable ` command). Restrictions """""""""""" @@ -42,8 +43,7 @@ none Related commands """""""""""""""" -none - +:doc:`label