ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

merge in current develop

Browse Source
This commit is contained in:
Steve Plimpton
2022-03-11 10:01:25 -07:00
parent 8ba4e7e897 9b989b1860
commit 1a04eabb5e
3529 changed files with 108434 additions and 51454 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/CODEOWNERS vendored
View File

@ -83,7 +83,7 @@ src/library.* @sjplimp
src/main.cpp @sjplimp
src/min_*.* @sjplimp
src/memory.* @sjplimp
src/modify.* @sjplimp
src/modify.* @sjplimp @stanmoore1
src/molecule.* @sjplimp
src/my_page.h @sjplimp
src/my_pool_chunk.h @sjplimp

58
.github/CONTRIBUTING.md vendored
View File

@ -5,8 +5,9 @@ Thank your for considering to contribute to the LAMMPS software project.
The following is a set of guidelines as well as explanations of policies and work flows for contributing to the LAMMPS molecular dynamics software project. These guidelines focus on submitting issues or pull requests on the LAMMPS GitHub project.
Thus please also have a look at:
* [The Section on submitting new features for inclusion in LAMMPS of the Manual](https://lammps.sandia.gov/doc/Modify_contribute.html)
* [The LAMMPS GitHub Tutorial in the Manual](http://lammps.sandia.gov/doc/Howto_github.html)
* [The guide for submitting new features in the LAMMPS manual](https://lammps.sandia.gov/doc/Modify_contribute.html)
* [The guide on programming style and requirement in the LAMMPS manual](https://lammps.sandia.gov/doc/Modify_contribute.html)
* [The GitHub tutorial in the LAMMPS manual](http://lammps.sandia.gov/doc/Howto_github.html)
## Table of Contents
@ -26,11 +27,11 @@ __
## I don't want to read this whole thing I just have a question!
> **Note:** Please do not file an issue to ask a general question about LAMMPS, its features, how to use specific commands, or how perform simulations or analysis in LAMMPS. Instead post your question to either the ['lammps-users' mailing list](https://lammps.sandia.gov/mail.html) or the [LAMMPS Material Science Discourse forum](https://matsci.org/lammps). You do not need to be subscribed to post to the list (but a mailing list subscription avoids having your post delayed until it is approved by a mailing list moderator). Most posts to the mailing list receive a response within less than 24 hours. Before posting to the mailing list, please read the [mailing list guidelines](https://lammps.sandia.gov/guidelines.html). Following those guidelines will help greatly to get a helpful response. Always mention which LAMMPS version you are using. The LAMMPS forum was recently created as part of a larger effort to build a materials science community and have discussions not just about using LAMMPS. Thus the forum may be also used for discussions that would be off-topic for the mailing list. Those will just have to be moved to a more general category.
> **Note:** Please do not file an issue to ask a general question about LAMMPS, its features, how to use specific commands, or how perform simulations or analysis in LAMMPS. Instead post your question to either the ['lammps-users' mailing list](https://lammps.sandia.gov/mail.html) or the [LAMMPS Material Science Discourse forum](https://matsci.org/lammps). You do not need to be subscribed to post to the list (but a mailing list subscription avoids having your post delayed until it is approved by a mailing list moderator). Most posts to the mailing list receive a response within less than 24 hours. Before posting to the mailing list, please read the [mailing list guidelines](https://lammps.sandia.gov/guidelines.html). Following those guidelines will help greatly to get a helpful response. Always mention which LAMMPS version you are using. The LAMMPS forum was recently created as part of a larger effort to build a materials science community and have discussions not just about using LAMMPS. Thus the forum may be also used for discussions that would be off-topic for the mailing list. Those will just have to be posted to a more general category.
## How Can I Contribute?
There are several ways how you can actively contribute to the LAMMPS project: you can discuss compiling and using LAMMPS, and solving LAMMPS related problems with other LAMMPS users on the lammps-users mailing list, you can report bugs or suggest enhancements by creating issues on GitHub (or posting them to the lammps-users mailing list or posting in the LAMMPS Materials Science Discourse forum), and you can contribute by submitting pull requests on GitHub or e-mail your code
There are several ways how you can actively contribute to the LAMMPS project: you can discuss compiling and using LAMMPS, and solving LAMMPS related problems with other LAMMPS users on the lammps-users mailing list or the forum, you can report bugs or suggest enhancements by creating issues on GitHub (or posting them to the lammps-users mailing list or posting in the LAMMPS Materials Science Discourse forum), and you can contribute by submitting pull requests on GitHub or e-mail your code
to one of the [LAMMPS core developers](https://lammps.sandia.gov/authors.html). As you may see from the aforementioned developer page, the LAMMPS software package includes the efforts of a very large number of contributors beyond the principal authors and maintainers.
### Discussing How To Use LAMMPS
@ -62,37 +63,12 @@ To be able to submit an issue on GitHub, you have to register for an account (fo
### Contributing Code
We encourage users to submit new features or modifications for LAMMPS to the core developers so they can be added to the LAMMPS distribution. The preferred way to manage and coordinate this is by submitting a pull request at the LAMMPS project on GitHub. For any larger modifications or programming project, you are encouraged to contact the LAMMPS developers ahead of time, in order to discuss implementation strategies and coding guidelines, that will make it easier to integrate your contribution and result in less work for everybody involved. You are also encouraged to search through the list of open issues on GitHub and submit a new issue for a planned feature, so you would not duplicate the work of others (and possibly get scooped by them) or have your work duplicated by others.
We encourage users to submit new features or modifications for LAMMPS. Instructions, guidelines, requirements,
and recommendations are in the following sections of the LAMMPS manual:
* [The guide for submitting new features in the LAMMPS manual](https://lammps.sandia.gov/doc/Modify_contribute.html)
* [The guide on programming style and requirement in the LAMMPS manual](https://lammps.sandia.gov/doc/Modify_contribute.html)
* [The GitHub tutorial in the LAMMPS manual](http://lammps.sandia.gov/doc/Howto_github.html)
How quickly your contribution will be integrated depends largely on how much effort it will cause to integrate and test it, how much it requires changes to the core code base, and of how much interest it is to the larger LAMMPS community. Please see below for a checklist of typical requirements. Once you have prepared everything, see [this tutorial](https://lammps.sandia.gov/doc/Howto_github.html)
for instructions on how to submit your changes or new files through a GitHub pull request
Here is a checklist of steps you need to follow to submit a single file or user package for our consideration. Following these steps will save both you and us time. See existing files in packages in the source directory for examples. If you are uncertain, please ask on the lammps-users mailing list.
* C++ source code must be compatible with the C++-11 standard. Packages may require a later standard, if justified.
* All source files you provide must compile with the most current version of LAMMPS with multiple configurations. In particular you need to test compiling LAMMPS from scratch with `-DLAMMPS_BIGBIG` set in addition to the default `-DLAMMPS_SMALLBIG` setting. Your code will need to work correctly in serial and in parallel using MPI.
* For consistency with the rest of LAMMPS and especially, if you want your contribution(s) to be added to main LAMMPS code or one of its standard packages, it needs to be written in a style compatible with other LAMMPS source files. This means: 2-character indentation per level, no tabs, no trailing whitespace, no lines over 80 characters. I/O is done via the C-style stdio library, style class header files should not import any system headers, STL containers should be avoided in headers, and forward declarations used where possible or needed. All added code should be placed into the LAMMPS_NS namespace or a sub-namespace; global or static variables should be avoided, as they conflict with the modular nature of LAMMPS and the C++ class structure. There MUST NOT be any "using namespace XXX;" statements in headers. In the implementation file (<name>.cpp) system includes should be placed in angular brackets (<>) and for c-library functions the C++ style header files should be included (<cstdio> instead of <stdio.h>, or <cstring> instead of <string.h>). This all is so the developers can more easily understand, integrate, and maintain your contribution and reduce conflicts with other parts of LAMMPS. This basically means that the code accesses data structures, performs its operations, and is formatted similar to other LAMMPS source files, including the use of the error class for error and warning messages.
* Source, style name, and documentation file should follow the following naming convention: style names should be lowercase and words separated by a forward slash; for a new fix style 'foo/bar', the class should be named FixFooBar, the name of the source files should be 'fix_foo_bar.h' and 'fix_foo_bar.cpp' and the corresponding documentation should be in a file 'fix_foo_bar.rst'.
* If you want your contribution to be added as a user-contributed feature, and it is a single file (actually a `<name>.cpp` and `<name>.h` file) it can be rapidly added to the USER-MISC directory. Include the one-line entry to add to the USER-MISC/README file in that directory, along with the 2 source files. You can do this multiple times if you wish to contribute several individual features.
* If you want your contribution to be added as a user-contribution and it is several related features, it is probably best to make it a user package directory with a name like FOO. In addition to your new files, the directory should contain a README text file. The README should contain your name and contact information and a brief description of what your new package does. If your files depend on other LAMMPS style files also being installed (e.g. because your file is a derived class from the other LAMMPS class), then an Install.sh file is also needed to check for those dependencies. See other README and Install.sh files in other USER directories as examples. Send us a tarball of this FOO directory.
* Your new source files need to have the LAMMPS copyright, GPL notice, and your name and email address at the top, like other user-contributed LAMMPS source files. They need to create a class that is inside the LAMMPS namespace. If the file is for one of the USER packages, including USER-MISC, then we are not as picky about the coding style (see above). I.e. the files do not need to be in the same stylistic format and syntax as other LAMMPS files, though that would be nice for developers as well as users who try to read your code.
* You **must** also create or extend a documentation file for each new command or style you are adding to LAMMPS. For simplicity and convenience, the documentation of groups of closely related commands or styles may be combined into a single file. This will be one file for a single-file feature. For a package, it might be several files. These are files in the [reStructuredText](https://docutils.sourceforge.io/rst.html) markup language, that are then converted to HTML and PDF. The tools for this conversion are included in the source distribution, and the translation can be as simple as doing "make html pdf" in the doc folder. Thus the documentation source files must be in the same format and style as other `<name>.rst` files in the lammps/doc/src directory for similar commands and styles; use one or more of them as a starting point. An introduction to reStructuredText can be found at [https://docutils.sourceforge.io/docs/user/rst/quickstart.html](https://docutils.sourceforge.io/docs/user/rst/quickstart.html). The text files can include mathematical expressions and symbol in ".. math::" sections or ":math:" expressions or figures (see doc/JPG for examples), or even additional PDF files with further details (see doc/PDF for examples). The doc page should also include literature citations as appropriate; see the bottom of doc/fix_nh.rst for examples and the earlier part of the same file for how to format the cite itself. The "Restrictions" section of the doc page should indicate that your command is only available if LAMMPS is built with the appropriate USER-MISC or FOO package. See other user package doc files for examples of how to do this. The prerequisite for building the HTML format files are Python 3.x and virtualenv. Please run at least `make html`, `make pdf` and `make spelling` and carefully inspect and proofread the resulting HTML format doc page as well as the output produced to the screen. Make sure that all spelling errors are fixed or the necessary false positives are added to the `doc/utils/sphinx-config/false_positives.txt` file. For new styles, those usually also need to be added to lists on the respective overview pages. This can be checked for also with `make style_check`.
* For a new package (or even a single command) you should include one or more example scripts demonstrating its use. These should run in no more than a couple minutes, even on a single processor, and not require large data files as input. See directories under examples/PACKAGES for examples of input scripts other users provided for their packages. These example inputs are also required for validating memory accesses and testing for memory leaks with valgrind
* For new utility functions or class (i.e. anything that does not depend on a LAMMPS object), new unit tests should be added to the unittest tree.
* When adding a new LAMMPS style, 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.).
* 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 <name>.cpp source file. See src/EFF/atom_vec_electron.cpp for an example. A LaTeX citation is stored in a variable at the top of the file and a single line of code that references the variable is added to the constructor of the class. Whenever a user invokes your feature from their input script, this will cause LAMMPS to output the citation to a log.cite file and prompt the user to examine the file. Note that you should only use this for a paper you or your group authored. E.g. adding a cite in the 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 in the doc page you provide.
Finally, as a general rule-of-thumb, the more clear and self-explanatory you make your documentation and README files, and the easier you make it for people to get started, e.g. by providing example scripts, the more likely it is that users will try out your new feature.
If the new features/files are broadly useful we may add them as core files to LAMMPS or as part of a standard package. Else we will add them as a user-contributed file or package. Examples of user packages are in src sub-directories that start with USER. The USER-MISC package is simply a collection of (mostly) unrelated single files, which is the simplest way to have your contribution quickly added to the LAMMPS distribution. You can see a list of the both standard and user packages by typing "make package" in the LAMMPS src directory.
Note that by providing us files to release, you are agreeing to make them open-source, i.e. we can release them under the terms of the GPL, used as a license for the rest of LAMMPS. See Section 1.4 for details.
With user packages and files, all we are really providing (aside from the fame and fortune that accompanies having your name in the source code and on the Authors page of the LAMMPS WWW site), is a means for you to distribute your work to the LAMMPS user community, and a mechanism for others to easily try out your new feature. This may help you find bugs or make contact with new collaborators. Note that you are also implicitly agreeing to support your code which means answer questions, fix bugs, and maintain it if LAMMPS changes in some way that breaks it (an unusual event).
To be able to submit an issue on GitHub, you have to register for an account (for GitHub in general). If you do not want to do that, or have other reservations or difficulties to submit a pull request, you can - as an alternative - contact one or more of the core LAMMPS developers and ask if one of them would be interested in manually merging your code into LAMMPS and send them your source code. Since the effort to merge a pull request is a small fraction of the effort of integrating source code manually (which would usually be done by converting the contribution into a pull request), your chances to have your new code included quickly are the best with a pull request.
If you prefer to submit patches or full files, you should first make certain, that your code works correctly with the latest patch-level version of LAMMPS and contains all bug fixes from it. Then create a gzipped tar file of all changed or added files or a corresponding patch file using 'diff -u' or 'diff -c' and compress it with gzip. Please only use gzip compression, as this works well on all platforms.
## GitHub Workflows
@ -102,17 +78,17 @@ This section briefly summarizes the steps that will happen **after** you have su
After submitting an issue, one or more of the LAMMPS developers will review it and categorize it by assigning labels. Confirmed bug reports will be labeled `bug`; if the bug report also contains a suggestion for how to fix it, it will be labeled `bugfix`; if the issue is a feature request, it will be labeled `enhancement`. Other labels may be attached as well, depending on which parts of the LAMMPS code are affected. If the assessment is, that the issue does not warrant any changes, the `wontfix` label will be applied and if the submission is incorrect or something that should not be submitted as an issue, the `invalid` label will be applied. In both of the last two cases, the issue will then be closed without further action.
For feature requests, what happens next is that developers may comment on the viability or relevance of the request, discuss and make suggestions for how to implement it. If a LAMMPS developer or user is planning to implement the feature, the issue will be assigned to that developer. For developers, that are not yet listed as LAMMPS project collaborators, they will receive an invitation to be added to the LAMMPS project as a collaborator so they can get assigned. If the requested feature or enhancement is implemented, it will usually be submitted as a pull request, which will contain a reference to the issue number. And once the pull request is reviewed and accepted for inclusion into LAMMPS, the issue will be closed. For details on how pull requests are processed, please see below.
For feature requests, what happens next is that developers may comment on the viability or relevance of the request, discuss and make suggestions for how to implement it. If a LAMMPS developer or user is planning to implement the feature, the issue will be assigned to that developer. For developers, that are not yet listed as LAMMPS project collaborators, they will receive an invitation to be added to the LAMMPS project as a collaborator so they can get assigned. If the requested feature or enhancement is implemented, it will be submitted as a pull request, which will contain a reference to the issue number. And once the pull request is reviewed and accepted for inclusion into LAMMPS, the issue will be closed. For details on how pull requests are processed, please see below. Feature requests may be labeled with `volunteer_needed` if none of the LAMMPS developers has the time and the required knowledge implement the feature.
For bug reports, the next step is that one of the core LAMMPS developers will self-assign to the issue and try to confirm the bug. If confirmed, the `bug` label and potentially other labels are added to classify the issue and its impact to LAMMPS. Before confirming, further questions may be asked or requests for providing additional input files or details about the steps required to reproduce the issue. Any bugfix is likely to be submitted as a pull request (more about that below) and since most bugs require only local changes, the bugfix may be included in a pull request specifically set up to collect such local bugfixes or small enhancements. Once the bugfix is included in the master branch, the issue will be closed.
For bug reports, the next step is that one of the core LAMMPS developers will self-assign to the issue and try to confirm the bug. If confirmed, the `bug` label and potentially other labels are added to classify the issue and its impact to LAMMPS. Otherwise the `unconfirmed` label will be applied and some comment about what was tried to confirm the bug added. Before confirming, further questions may be asked or requests for providing additional input files or details about the steps required to reproduce the issue. Any bugfix will be submitted as a pull request (more about that below) and since most bugs require only local changes, the bugfix may be included in a pull request specifically set up to collect such local bugfixes or small enhancements. Once the bugfix is included in the master branch, the issue will be closed.
### Pull Requests
For submitting pull requests, there is a [detailed tutorial](https://lammps.sandia.gov/doc/Howto_github.html) in the LAMMPS manual. Thus only a brief breakdown of the steps is presented here. Please note, that the LAMMPS developers are still reviewing and trying to improve the process. If you are unsure about something, do not hesitate to post a question on the lammps-users mailing list or contact one fo the core LAMMPS developers.
Immediately after the submission, the LAMMPS continuing integration server at ci.lammps.org will download your submitted branch and perform a simple compilation test, i.e. will test whether your submitted code can be compiled under various conditions. It will also do a check on whether your included documentation translates cleanly. Whether these tests are successful or fail will be recorded. If a test fails, please inspect the corresponding output on the CI server and take the necessary steps, if needed, so that the code can compile cleanly again. The test will be re-run each the pull request is updated with a push to the remote branch on GitHub.
Next a LAMMPS core developer will self-assign and do an overall technical assessment of the submission. If you are not yet registered as a LAMMPS collaborator, you will receive an invitation for that. As part of the assessment, the pull request will be categorized with labels. There are two special labels: `needs_work` (indicates that work from the submitter of the pull request is needed) and `work_in_progress` (indicates, that the assigned LAMMPS developer will make changes, if not done by the contributor who made the submit).
Pull requests are the **only** way that changes get made to the LAMMPS distribution. So also the LAMMPS core developers will submit pull requests for their own changes and discuss them on GitHub. Thus if you submit a pull request it will be treated in a similar fashion. When you submit a pull request you may opt to submit a "Draft" pull request. That means your changes are visible and will be subject to testing, but reviewers will not be (auto-)assigned and comments will take into account that this is not complete. On the other hand, this is a perfect way to ask the LAMMPS developers for comments on non-obvious changes and get feedback and possible suggestions for improvements or recommendations about what to avoid.
Immediately after the submission, the LAMMPS continuing integration server at ci.lammps.org will download your submitted branch and perform a number of tests: it will tests whether it compiles cleanly under various conditions, it will also do a check on whether your included documentation translates cleanly and run some unit tests and other checks. Whether these tests are successful or fail will be recorded. If a test fails, please inspect the corresponding output on the CI server and take the necessary steps, if needed, so that the code can compile cleanly again. The test will be re-run each time the pull request is updated with a push to the remote branch on GitHub. If you are unsure about what you need to change, ask a question in the discussion area of the pull request.
Next a LAMMPS core developer will self-assign and do an overall technical assessment of the submission. If you submitted a draft pull request, this will not happen unless you mark it "ready for review". If you are not yet invited as a LAMMPS collaborator, and your contribution seems significant, you may also receive an invitation for collaboration on the LAMMPS repository. As part of the assessment, the pull request will be categorized with labels. There are two special labels: `needs_work` (indicates that work from the submitter of the pull request is needed) and `work_in_progress` (indicates, that the assigned LAMMPS developer will make changes, if not done by the contributor who made the submit).
You may also receive comments and suggestions on the overall submission or specific details and on occasion specific requests for changes as part of the review. If permitted, also additional changes may be pushed into your pull request branch or a pull request may be filed in your LAMMPS fork on GitHub to include those changes.
The LAMMPS developer may then decide to assign the pull request to another developer (e.g. when that developer is more knowledgeable about the submitted feature or enhancement or has written the modified code). It may also happen, that additional developers are requested to provide a review and approve the changes. For submissions, that may change the general behavior of LAMMPS, or where a possibility of unwanted side effects exists, additional tests may be requested by the assigned developer.
If the assigned developer is satisfied and considers the submission ready for inclusion into LAMMPS, the pull request will receive approvals and be merged into the master branch by one of the core LAMMPS developers. After the pull request is merged, you may delete the feature branch used for the pull request in your personal LAMMPS fork.
Since the learning curve for git is quite steep for efficiently managing remote repositories, local and remote branches, pull requests and more, do not hesitate to ask questions, if you are not sure about how to do certain steps that are asked of you. Even if the changes asked of you do not make sense to you, they may be important for the LAMMPS developers. Please also note, that these all are guidelines and nothing set in stone. So depending on the nature of the contribution, the workflow may be adjusted.
If the assigned developer is satisfied and considers the submission ready for inclusion into LAMMPS, the pull request will receive approvals and be merged into the master branch by one of the core LAMMPS developers. After the pull request is merged, you may delete the feature branch used for the pull request in your personal LAMMPS fork. The minimum requirement to merge a pull request is that all automated tests have to pass and at least one LAMMPS developer has approved integrating the submitted code. Since the approver will not be the person merging a pull request, you will have at least two LAMMPS developers that looked at your contribution.
Since the learning curve for git is quite steep for efficiently managing remote repositories, local and remote branches, pull requests and more, do not hesitate to ask questions, if you are not sure about how to do certain steps that are asked of you. Even if the changes asked of you do not make sense to you, they may be important for the LAMMPS developers. Please also note, that these all are guidelines and nothing set in stone. So depending on the nature of the contribution, the work flow may be adjusted.

2
.github/workflows/codeql-analysis.yml vendored
View File

@ -3,7 +3,7 @@ name: "CodeQL Code Analysis"
on:
push:
branches: [master]
branches: [develop]
jobs:
analyze:

46
.github/workflows/compile-msvc.yml vendored Normal file
View File

@ -0,0 +1,46 @@
# GitHub action to build LAMMPS on Windows with Visual C++
name: "Native Windows Compilation and Unit Tests"
on:
push:
branches: [develop]
jobs:
build:
name: Windows Compilation Test
if: ${{ github.repository == 'lammps/lammps' }}
runs-on: windows-latest
steps:
- name: Checkout repository
uses: actions/checkout@v2
with:
fetch-depth: 2
- name: Select Python version
uses: actions/setup-python@v2
with:
python-version: '3.10'
- name: Building LAMMPS via CMake
shell: bash
run: |
python3 -m pip install numpy
cmake -C cmake/presets/windows.cmake \
-D PKG_PYTHON=on \
-S cmake -B build \
-D BUILD_SHARED_LIBS=on \
-D LAMMPS_EXCEPTIONS=on \
-D ENABLE_TESTING=on
cmake --build build --config Release
- name: Run LAMMPS executable
shell: bash
run: |
./build/Release/lmp.exe -h
./build/Release/lmp.exe -in bench/in.lj
- name: Run Unit Tests
working-directory: build
shell: bash
run: ctest -V -C Release

2
.github/workflows/unittest-macos.yml vendored
View File

@ -3,7 +3,7 @@ name: "Unittest for MacOS"
on:
push:
branches: [master]
branches: [develop]
jobs:
build:

8
.gitignore vendored
View File

@ -12,6 +12,7 @@
*.sif
*.dll
*.pyc
*.whl
a.out
__pycache__
@ -37,8 +38,8 @@ vgcore.*
.Trashes
ehthumbs.db
Thumbs.db
.clang-format
.lammps_history
.vs
#cmake
/build*
@ -49,3 +50,8 @@ Thumbs.db
/Testing
/cmake_install.cmake
/lmp
out/Debug
out/RelWithDebInfo
out/Release
out/x86
out/x64

4
SECURITY.md
View File

@ -23,6 +23,10 @@ either a user mistake or a bug in the code. Bugs can be reported in
the LAMMPS project
[issue tracker on GitHub](https://github.com/lammps/lammps/issues).
To mitigate issues with using homoglyphs or bidirectional reordering in
unicode, which have been demonstrated as a vector to obfuscate and hide
malicious changes to the source code, all LAMMPS submissions are checked
for unicode characters and only all-ASCII source code is accepted.
# Version Updates

131
cmake/CMakeLists.txt
View File

@ -16,9 +16,13 @@ endif()
project(lammps CXX)
set(SOVERSION 0)
get_property(BUILD_IS_MULTI_CONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
get_filename_component(LAMMPS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/.. ABSOLUTE)
get_filename_component(LAMMPS_LIB_BINARY_DIR ${CMAKE_BINARY_DIR}/lib ABSOLUTE)
# collect all executables and shared libs in the top level build folder
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
set(LAMMPS_SOURCE_DIR ${LAMMPS_DIR}/src)
set(LAMMPS_LIB_SOURCE_DIR ${LAMMPS_DIR}/lib)
@ -36,7 +40,11 @@ find_package(Git)
# by default, install into $HOME/.local (not /usr/local), so that no root access (and sudo!!) is needed
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
set(CMAKE_INSTALL_PREFIX "$ENV{HOME}/.local" CACHE PATH "Default install path" FORCE)
if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND (NOT CMAKE_CROSSCOMPILING))
set(CMAKE_INSTALL_PREFIX "$ENV{USERPROFILE}/LAMMPS" CACHE PATH "Default install path" FORCE)
else()
set(CMAKE_INSTALL_PREFIX "$ENV{HOME}/.local" CACHE PATH "Default install path" FORCE)
endif()
endif()
# If enabled, no need to use LD_LIBRARY_PATH / DYLD_LIBRARY_PATH when installed
@ -77,19 +85,41 @@ check_for_autogen_files(${LAMMPS_SOURCE_DIR})
include(CheckIncludeFileCXX)
# set required compiler flags and compiler/CPU arch specific optimizations
if((CMAKE_CXX_COMPILER_ID STREQUAL "Intel") OR (CMAKE_CXX_COMPILER_ID STREQUAL "IntelLLVM"))
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -restrict")
if(CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.3 OR CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.4)
set(CMAKE_TUNE_DEFAULT "-xCOMMON-AVX512")
if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
if(CMAKE_SYSTEM_NAME STREQUAL "Windows")
if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /Qrestrict")
endif()
if(CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.3 OR CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.4)
set(CMAKE_TUNE_DEFAULT "/QxCOMMON-AVX512")
else()
set(CMAKE_TUNE_DEFAULT "/QxHost")
endif()
else()
set(CMAKE_TUNE_DEFAULT "-xHost")
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -restrict")
if(CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.3 OR CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.4)
set(CMAKE_TUNE_DEFAULT "-xCOMMON-AVX512")
else()
set(CMAKE_TUNE_DEFAULT "-xHost")
endif()
endif()
endif()
# we require C++11 without extensions
# we require C++11 without extensions. Kokkos requires at least C++14 (currently)
set(CMAKE_CXX_STANDARD 11)
if(PKG_KOKKOS AND (CMAKE_CXX_STANDARD LESS 14))
set(CMAKE_CXX_STANDARD 14)
endif()
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF CACHE BOOL "Use compiler extensions")
# ugly hacks for MSVC which by default always reports an old C++ standard in the __cplusplus macro
# and prints lots of pointless warnings about "unsafe" functions
if(MSVC)
add_compile_options(/Zc:__cplusplus)
add_compile_options(/wd4244)
add_compile_options(/wd4267)
add_compile_definitions(_CRT_SECURE_NO_WARNINGS)
endif()
# export all symbols when building a .dll file on windows
if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND BUILD_SHARED_LIBS)
@ -107,10 +137,7 @@ endif()
set(LAMMPS_BINARY lmp${LAMMPS_MACHINE})
option(BUILD_SHARED_LIBS "Build shared library" OFF)
if(BUILD_SHARED_LIBS) # for all pkg libs, mpi_stubs and linalg
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
endif()
option(CMAKE_POSITION_INDEPENDENT_CODE "Create object compatible with shared libraries" ON)
option(BUILD_TOOLS "Build and install LAMMPS tools (msi2lmp, binary2txt, chain)" OFF)
option(BUILD_LAMMPS_SHELL "Build and install the LAMMPS shell" OFF)
@ -257,28 +284,19 @@ if(BUILD_MPI)
# We use a non-standard procedure to cross-compile with MPI on Windows
if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND CMAKE_CROSSCOMPILING)
include(MPI4WIN)
target_link_libraries(lammps PUBLIC MPI::MPI_CXX)
else()
find_package(MPI REQUIRED)
target_link_libraries(lammps PUBLIC MPI::MPI_CXX)
option(LAMMPS_LONGLONG_TO_LONG "Workaround if your system or MPI version does not recognize 'long long' data types" OFF)
if(LAMMPS_LONGLONG_TO_LONG)
target_compile_definitions(lammps PRIVATE -DLAMMPS_LONGLONG_TO_LONG)
endif()
endif()
target_link_libraries(lammps PUBLIC MPI::MPI_CXX)
else()
file(GLOB MPI_SOURCES ${LAMMPS_SOURCE_DIR}/STUBS/mpi.cpp)
add_library(mpi_stubs STATIC ${MPI_SOURCES})
set_target_properties(mpi_stubs PROPERTIES OUTPUT_NAME lammps_mpi_stubs${LAMMPS_MACHINE})
target_include_directories(mpi_stubs PUBLIC $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
if(BUILD_SHARED_LIBS)
target_link_libraries(lammps PRIVATE mpi_stubs)
target_include_directories(lammps INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
target_compile_definitions(lammps INTERFACE $<INSTALL_INTERFACE:LAMMPS_LIB_NO_MPI>)
else()
target_link_libraries(lammps PUBLIC mpi_stubs)
endif()
add_library(MPI::MPI_CXX ALIAS mpi_stubs)
target_sources(lammps PRIVATE ${LAMMPS_SOURCE_DIR}/STUBS/mpi.cpp)
add_library(mpi_stubs INTERFACE)
target_include_directories(mpi_stubs INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
target_link_libraries(lammps PUBLIC mpi_stubs)
endif()
set(LAMMPS_SIZES "smallbig" CACHE STRING "LAMMPS integer sizes (smallsmall: all 32-bit, smallbig: 64-bit #atoms #timesteps, bigbig: also 64-bit imageint, 64-bit atom ids)")
@ -309,7 +327,6 @@ pkg_depends(ML-IAP ML-SNAP)
pkg_depends(MPIIO MPI)
pkg_depends(ATC MANYBODY)
pkg_depends(LATBOLTZ MPI)
pkg_depends(PHONON KSPACE)
pkg_depends(SCAFACOS MPI)
pkg_depends(DIELECTRIC KSPACE)
pkg_depends(DIELECTRIC EXTRA-PAIR)
@ -343,11 +360,13 @@ if(BUILD_OMP)
((CMAKE_CXX_COMPILER_ID STREQUAL "Intel") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 19.0)))
# GCC 9.x and later plus Clang 10.x and later implement strict OpenMP 4.0 semantics for consts.
# Intel 18.0 was tested to support both, so we switch to OpenMP 4+ from 19.x onward to be safe.
target_compile_definitions(lammps PRIVATE -DLAMMPS_OMP_COMPAT=4)
set(LAMMPS_OMP_COMPAT_LEVEL 4)
else()
target_compile_definitions(lammps PRIVATE -DLAMMPS_OMP_COMPAT=3)
set(LAMMPS_OMP_COMPAT_LEVEL 3)
endif()
target_compile_definitions(lammps PRIVATE -DLAMMPS_OMP_COMPAT=${LAMMPS_OMP_COMPAT_LEVEL})
target_link_libraries(lammps PRIVATE OpenMP::OpenMP_CXX)
target_link_libraries(lmp PRIVATE OpenMP::OpenMP_CXX)
endif()
if(PKG_MSCG OR PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_LATTE)
@ -460,9 +479,12 @@ foreach(HEADER cmath)
endif(NOT FOUND_${HEADER})
endforeach(HEADER)
set(MATH_LIBRARIES "m" CACHE STRING "math library")
mark_as_advanced( MATH_LIBRARIES )
target_link_libraries(lammps PRIVATE ${MATH_LIBRARIES})
# make the standard math library overrideable and autodetected (for systems that don't have it)
find_library(STANDARD_MATH_LIB m DOC "Standard Math library")
mark_as_advanced(STANDARD_MATH_LIB)
if(STANDARD_MATH_LIB)
target_link_libraries(lammps PRIVATE ${STANDARD_MATH_LIB})
endif()
######################################
# Generate Basic Style files
@ -558,11 +580,10 @@ if(PKG_ATC)
if(LAMMPS_SIZES STREQUAL "BIGBIG")
message(FATAL_ERROR "The ATC Package is not compatible with -DLAMMPS_BIGBIG")
endif()
target_link_libraries(atc PRIVATE ${LAPACK_LIBRARIES})
if(BUILD_MPI)
target_link_libraries(atc PRIVATE MPI::MPI_CXX)
target_link_libraries(atc PRIVATE ${LAPACK_LIBRARIES} MPI::MPI_CXX)
else()
target_link_libraries(atc PRIVATE mpi_stubs)
target_link_libraries(atc PRIVATE ${LAPACK_LIBRARIES} mpi_stubs)
endif()
target_include_directories(atc PRIVATE ${LAMMPS_SOURCE_DIR})
target_compile_definitions(atc PRIVATE -DLAMMPS_${LAMMPS_SIZES})
@ -576,22 +597,19 @@ endif()
# packages which selectively include variants based on enabled styles
# e.g. accelerator packages
######################################################################
foreach(PKG_WITH_INCL CORESHELL QEQ OPENMP DPD-SMOOTH KOKKOS OPT INTEL GPU)
foreach(PKG_WITH_INCL CORESHELL DPD-SMOOTH PHONON QEQ OPENMP KOKKOS OPT INTEL GPU)
if(PKG_${PKG_WITH_INCL})
include(Packages/${PKG_WITH_INCL})
endif()
endforeach()
if(PKG_PLUGIN)
if(BUILD_SHARED_LIBS)
target_compile_definitions(lammps PRIVATE -DLMP_PLUGIN)
else()
message(WARNING "Plugin loading will not work unless BUILD_SHARED_LIBS is enabled")
endif()
# link with -ldl or equivalent for plugin loading; except on Windows
if(NOT ${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
target_link_libraries(lammps PRIVATE ${CMAKE_DL_LIBS})
endif()
target_compile_definitions(lammps PRIVATE -DLMP_PLUGIN)
endif()
# link with -ldl or equivalent for plugin loading; except on Windows
if(NOT ${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
target_link_libraries(lammps PRIVATE ${CMAKE_DL_LIBS})
endif()
######################################################################
@ -600,7 +618,7 @@ endif()
# and after everything else that is compiled locally
######################################################################
if(CMAKE_SYSTEM_NAME STREQUAL "Windows")
target_link_libraries(lammps PRIVATE -lwsock32 -lpsapi)
target_link_libraries(lammps PRIVATE "wsock32;psapi")
endif()
######################################################
@ -661,6 +679,7 @@ endif()
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 $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/lammps>)
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps)
foreach(_HEADER ${LAMMPS_CXX_HEADERS})
@ -680,6 +699,9 @@ foreach(_DEF ${LAMMPS_DEFINES})
endforeach()
if(BUILD_SHARED_LIBS)
install(TARGETS lammps EXPORT LAMMPS_Targets LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
if(NOT BUILD_MPI)
install(TARGETS mpi_stubs EXPORT LAMMPS_Targets LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
endif()
configure_file(pkgconfig/liblammps.pc.in ${CMAKE_CURRENT_BINARY_DIR}/liblammps${LAMMPS_MACHINE}.pc @ONLY)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/liblammps${LAMMPS_MACHINE}.pc DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig)
install(EXPORT LAMMPS_Targets FILE LAMMPS_Targets.cmake NAMESPACE LAMMPS:: DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/LAMMPS)
@ -719,7 +741,7 @@ install(
if(BUILD_SHARED_LIBS)
if(CMAKE_VERSION VERSION_LESS 3.12)
# adjust so we find Python 3 versions before Python 2 on old systems with old CMake
set(Python_ADDITIONAL_VERSIONS 3.9 3.8 3.7 3.6 3.5)
set(Python_ADDITIONAL_VERSIONS 3.12 3.11 3.10 3.9 3.8 3.7 3.6)
find_package(PythonInterp) # Deprecated since version 3.12
if(PYTHONINTERP_FOUND)
set(Python_EXECUTABLE ${PYTHON_EXECUTABLE})
@ -727,13 +749,15 @@ if(BUILD_SHARED_LIBS)
else()
find_package(Python COMPONENTS Interpreter)
endif()
if(BUILD_IS_MULTI_CONFIG)
set(LIBLAMMPS_SHARED_BINARY ${CMAKE_BINARY_DIR}/$<CONFIG>/liblammps${LAMMPS_MACHINE}${CMAKE_SHARED_LIBRARY_SUFFIX})
else()
set(LIBLAMMPS_SHARED_BINARY ${CMAKE_BINARY_DIR}/liblammps${LAMMPS_MACHINE}${CMAKE_SHARED_LIBRARY_SUFFIX})
endif()
if(Python_EXECUTABLE)
add_custom_target(
install-python ${CMAKE_COMMAND} -E remove_directory build
COMMAND ${Python_EXECUTABLE} install.py -v ${LAMMPS_SOURCE_DIR}/version.h
-p ${LAMMPS_PYTHON_DIR}/lammps
-l ${CMAKE_BINARY_DIR}/liblammps${LAMMPS_MACHINE}${CMAKE_SHARED_LIBRARY_SUFFIX}
WORKING_DIRECTORY ${LAMMPS_PYTHON_DIR}
COMMAND ${Python_EXECUTABLE} ${LAMMPS_PYTHON_DIR}/install.py -p ${LAMMPS_PYTHON_DIR}/lammps -l ${LIBLAMMPS_SHARED_BINARY}
COMMENT "Installing LAMMPS Python module")
else()
add_custom_target(
@ -778,11 +802,16 @@ if(ClangFormat_FOUND)
endif()
get_target_property(DEFINES lammps COMPILE_DEFINITIONS)
if(BUILD_IS_MULTI_CONFIG)
set(LAMMPS_BUILD_TYPE "Multi-Config")
else()
set(LAMMPS_BUILD_TYPE ${CMAKE_BUILD_TYPE})
endif()
include(FeatureSummary)
feature_summary(DESCRIPTION "The following tools and libraries have been found and configured:" WHAT PACKAGES_FOUND)
message(STATUS "<<< Build configuration >>>
Operating System: ${CMAKE_SYSTEM_NAME} ${CMAKE_LINUX_DISTRO} ${CMAKE_DISTRO_VERSION}
Build type: ${CMAKE_BUILD_TYPE}
Build type: ${LAMMPS_BUILD_TYPE}
Install path: ${CMAKE_INSTALL_PREFIX}
Generator: ${CMAKE_GENERATOR} using ${CMAKE_MAKE_PROGRAM}")
###############################################################################

156
cmake/CMakeSettings.json Normal file
View File

@ -0,0 +1,156 @@
{
"configurations": [
{
"name": "x64-Debug-MSVC",
"generator": "Ninja",
"configurationType": "Debug",
"buildRoot": "${workspaceRoot}\\build\\${name}",
"installRoot": "${workspaceRoot}\\install\\${name}",
"cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake",
"buildCommandArgs": "",
"ctestCommandArgs": "",
"inheritEnvironments": [ "msvc_x64_x64" ],
"variables": [
{
"name": "BUILD_SHARED_LIBS",
"value": "True",
"type": "BOOL"
},
{
"name": "BUILD_TOOLS",
"value": "True",
"type": "BOOL"
},
{
"name": "LAMMPS_EXCEPTIONS",
"value": "True",
"type": "BOOL"
},
{
"name": "PKG_PYTHON",
"value": "True",
"type": "BOOL"
},
{
"name": "ENABLE_TESTING",
"value": "True",
"type": "BOOL"
}
]
},
{
"name": "x64-Release-MSVC",
"generator": "Ninja",
"configurationType": "Release",
"buildRoot": "${workspaceRoot}\\build\\${name}",
"installRoot": "${workspaceRoot}\\install\\${name}",
"cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake",
"buildCommandArgs": "",
"ctestCommandArgs": "",
"inheritEnvironments": [ "msvc_x64_x64" ],
"variables": [
{
"name": "BUILD_SHARED_LIBS",
"value": "True",
"type": "BOOL"
},
{
"name": "BUILD_TOOLS",
"value": "True",
"type": "BOOL"
},
{
"name": "LAMMPS_EXCEPTIONS",
"value": "True",
"type": "BOOL"
},
{
"name": "PKG_PYTHON",
"value": "True",
"type": "BOOL"
},
{
"name": "ENABLE_TESTING",
"value": "True",
"type": "BOOL"
}
]
},
{
"name": "x64-Debug-Clang",
"generator": "Ninja",
"configurationType": "Debug",
"buildRoot": "${workspaceRoot}\\build\\${name}",
"installRoot": "${workspaceRoot}\\install\\${name}",
"cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DCMAKE_C_COMPILER=clang-cl.exe -DCMAKE_CXX_COMPILER=clang-cl.exe",
"buildCommandArgs": "",
"ctestCommandArgs": "",
"inheritEnvironments": [ "clang_cl_x64" ],
"variables": [
{
"name": "BUILD_SHARED_LIBS",
"value": "True",
"type": "BOOL"
},
{
"name": "BUILD_TOOLS",
"value": "True",
"type": "BOOL"
},
{
"name": "LAMMPS_EXCEPTIONS",
"value": "True",
"type": "BOOL"
},
{
"name": "PKG_PYTHON",
"value": "True",
"type": "BOOL"
},
{
"name": "ENABLE_TESTING",
"value": "True",
"type": "BOOL"
}
]
},
{
"name": "x64-Release-Clang",
"generator": "Ninja",
"configurationType": "Release",
"buildRoot": "${workspaceRoot}\\build\\${name}",
"installRoot": "${workspaceRoot}\\install\\${name}",
"cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DCMAKE_C_COMPILER=clang-cl.exe -DCMAKE_CXX_COMPILER=clang-cl.exe",
"buildCommandArgs": "",
"ctestCommandArgs": "",
"inheritEnvironments": [ "clang_cl_x64" ],
"variables": [
{
"name": "BUILD_SHARED_LIBS",
"value": "True",
"type": "BOOL"
},
{
"name": "BUILD_TOOLS",
"value": "True",
"type": "BOOL"
},
{
"name": "LAMMPS_EXCEPTIONS",
"value": "True",
"type": "BOOL"
},
{
"name": "PKG_PYTHON",
"value": "True",
"type": "BOOL"
},
{
"name": "ENABLE_TESTING",
"value": "True",
"type": "BOOL"
}
]
}
]
}

33
cmake/Modules/ExternalCMakeProject.cmake Normal file
View File

@ -0,0 +1,33 @@
# Build a CMake based external library as subdirectory.
# The sources will be unpacked to ${CMAKE_BINARY_DIR}/_deps/${target}-src
# The binaries will be built in ${CMAKE_BINARY_DIR}/_deps/${target}-build
#
function(ExternalCMakeProject target url hash basedir cmakedir cmakefile)
# change settings locally
set(BUILD_SHARED_LIBS OFF)
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
get_filename_component(archive ${url} NAME)
file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/_deps/src)
message(STATUS "Downloading ${url}")
file(DOWNLOAD ${url} ${CMAKE_BINARY_DIR}/_deps/${archive} EXPECTED_HASH MD5=${hash} SHOW_PROGRESS)
message(STATUS "Unpacking and configuring ${archive}")
execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf ${CMAKE_BINARY_DIR}/_deps/${archive}
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/_deps/src)
file(GLOB TARGET_SOURCE "${CMAKE_BINARY_DIR}/_deps/src/${basedir}*")
list(LENGTH TARGET_SOURCE _num)
if(_num GREATER 1)
message(FATAL_ERROR "Inconsistent ${target} library sources. "
"Please delete ${CMAKE_BINARY_DIR}/_deps/src and re-run cmake")
endif()
file(REMOVE_RECURSE ${CMAKE_BINARY_DIR}/_deps/${target}-src)
file(RENAME ${TARGET_SOURCE} ${CMAKE_BINARY_DIR}/_deps/${target}-src)
if(NOT (cmakefile STREQUAL ""))
file(COPY ${cmakefile} DESTINATION ${CMAKE_BINARY_DIR}/_deps/${target}-src/${cmakedir}/)
get_filename_component(_cmakefile ${cmakefile} NAME)
file(RENAME "${CMAKE_BINARY_DIR}/_deps/${target}-src/${cmakedir}/${_cmakefile}"
"${CMAKE_BINARY_DIR}/_deps/${target}-src/${cmakedir}/CMakeLists.txt")
endif()
add_subdirectory("${CMAKE_BINARY_DIR}/_deps/${target}-src/${cmakedir}"
"${CMAKE_BINARY_DIR}/_deps/${target}-build")
endfunction(ExternalCMakeProject)

9
cmake/Modules/FindCythonize.cmake
View File

@ -8,18 +8,19 @@
#=============================================================================
if(CMAKE_VERSION VERSION_LESS 3.12)
set(Python_ADDITIONAL_VERSIONS 3.12 3.11 3.10 3.9 3.8 3.7 3.6)
find_package(PythonInterp 3.6 QUIET) # Deprecated since version 3.12
if(PYTHONINTERP_FOUND)
set(Python3_EXECUTABLE ${PYTHON_EXECUTABLE})
set(Python_EXECUTABLE ${PYTHON_EXECUTABLE})
endif()
else()
find_package(Python3 3.6 COMPONENTS Interpreter QUIET)
find_package(Python 3.6 COMPONENTS Interpreter QUIET)
endif()
# Use the Cython executable that lives next to the Python executable
# if it is a local installation.
if(Python3_EXECUTABLE)
get_filename_component(_python_path ${Python3_EXECUTABLE} PATH)
if(Python_EXECUTABLE)
get_filename_component(_python_path ${Python_EXECUTABLE} PATH)
find_program(Cythonize_EXECUTABLE
NAMES cythonize3 cythonize cythonize.bat
HINTS ${_python_path})

81
cmake/Modules/GTest.cmake
View File

@ -1,81 +0,0 @@
message(STATUS "Downloading and building Google Test library")
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
set(GTEST_LIB_POSTFIX d)
else()
set(GTEST_LIB_POSTFIX)
endif()
include(ExternalProject)
set(GTEST_URL "https://github.com/google/googletest/archive/release-1.10.0.tar.gz" CACHE STRING "URL for GTest tarball")
set(GTEST_MD5 "ecd1fa65e7de707cd5c00bdac56022cd" CACHE STRING "MD5 checksum of GTest tarball")
mark_as_advanced(GTEST_URL)
mark_as_advanced(GTEST_MD5)
ExternalProject_Add(googletest
URL ${GTEST_URL}
URL_MD5 ${GTEST_MD5}
SOURCE_DIR "${CMAKE_BINARY_DIR}/gtest-src"
BINARY_DIR "${CMAKE_BINARY_DIR}/gtest-build"
CMAKE_ARGS ${CMAKE_REQUEST_PIC} ${CMAKE_EXTRA_GTEST_OPTS}
-DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
-DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>
-DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
-DCMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM}
-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
BUILD_BYPRODUCTS <BINARY_DIR>/lib/libgtest${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
<BINARY_DIR>/lib/libgmock${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
<BINARY_DIR>/lib/libgtest_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
<BINARY_DIR>/lib/libgmock_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
LOG_DOWNLOAD ON
LOG_CONFIGURE ON
LOG_BUILD ON
INSTALL_COMMAND ""
TEST_COMMAND "")
ExternalProject_Get_Property(googletest SOURCE_DIR)
set(GTEST_INCLUDE_DIR ${SOURCE_DIR}/googletest/include)
set(GMOCK_INCLUDE_DIR ${SOURCE_DIR}/googlemock/include)
# workaround for CMake 3.10 on ubuntu 18.04
file(MAKE_DIRECTORY ${GTEST_INCLUDE_DIR})
file(MAKE_DIRECTORY ${GMOCK_INCLUDE_DIR})
ExternalProject_Get_Property(googletest BINARY_DIR)
set(GTEST_LIBRARY_PATH ${BINARY_DIR}/lib/libgtest${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
set(GMOCK_LIBRARY_PATH ${BINARY_DIR}/lib/libgmock${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
set(GTEST_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/libgtest_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
set(GMOCK_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/libgmock_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
# Prevent GoogleTest from overriding our compiler/linker options
# when building with Visual Studio
set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
find_package(Threads QUIET)
add_library(GTest::GTest UNKNOWN IMPORTED)
set_target_properties(GTest::GTest PROPERTIES
IMPORTED_LOCATION ${GTEST_LIBRARY_PATH}
INTERFACE_INCLUDE_DIRECTORIES ${GTEST_INCLUDE_DIR}
INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
add_dependencies(GTest::GTest googletest)
add_library(GTest::GMock UNKNOWN IMPORTED)
set_target_properties(GTest::GMock PROPERTIES
IMPORTED_LOCATION ${GMOCK_LIBRARY_PATH}
INTERFACE_INCLUDE_DIRECTORIES ${GMOCK_INCLUDE_DIR}
INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
add_dependencies(GTest::GMock googletest)
add_library(GTest::GTestMain UNKNOWN IMPORTED)
set_target_properties(GTest::GTestMain PROPERTIES
IMPORTED_LOCATION ${GTEST_MAIN_LIBRARY_PATH}
INTERFACE_INCLUDE_DIRECTORIES ${GTEST_INCLUDE_DIR}
INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
add_dependencies(GTest::GTestMain googletest)
add_library(GTest::GMockMain UNKNOWN IMPORTED)
set_target_properties(GTest::GMockMain PROPERTIES
IMPORTED_LOCATION ${GMOCK_MAIN_LIBRARY_PATH}
INTERFACE_INCLUDE_DIRECTORIES ${GMOCK_INCLUDE_DIR}
INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
add_dependencies(GTest::GMockMain googletest)

4
cmake/Modules/LAMMPSUtils.cmake
View File

@ -25,7 +25,7 @@ function(validate_option name values)
endfunction(validate_option)
function(get_lammps_version version_header variable)
file(READ ${version_header} line)
file(STRINGS ${version_header} line REGEX LAMMPS_VERSION)
set(MONTHS x Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)
string(REGEX REPLACE "#define LAMMPS_VERSION \"([0-9]+) ([A-Za-z]+) ([0-9]+)\"" "\\1" day "${line}")
string(REGEX REPLACE "#define LAMMPS_VERSION \"([0-9]+) ([A-Za-z]+) ([0-9]+)\"" "\\2" month "${line}")
@ -85,7 +85,7 @@ endfunction(GenerateBinaryHeader)
# fetch missing potential files
function(FetchPotentials pkgfolder potfolder)
if (EXISTS "${pkgfolder}/potentials.txt")
if(EXISTS "${pkgfolder}/potentials.txt")
file(STRINGS "${pkgfolder}/potentials.txt" linelist REGEX "^[^#].")
foreach(line ${linelist})
string(FIND ${line} " " blank)

51
cmake/Modules/OpenCLLoader.cmake
View File

@ -1,50 +1,11 @@
message(STATUS "Downloading and building OpenCL loader library")
set(OPENCL_LOADER_URL "${LAMMPS_THIRDPARTY_URL}/opencl-loader-2021.06.30.tar.gz" CACHE STRING "URL for OpenCL loader tarball")
set(OPENCL_LOADER_MD5 "f9e55dd550cfbf77f46507adf7cb8fd2" CACHE STRING "MD5 checksum of OpenCL loader tarball")
set(OPENCL_LOADER_URL "${LAMMPS_THIRDPARTY_URL}/opencl-loader-2022.01.04.tar.gz" CACHE STRING "URL for OpenCL loader tarball")
set(OPENCL_LOADER_MD5 "8d3a801e87a2c6653bf0e27707063914" CACHE STRING "MD5 checksum of OpenCL loader tarball")
mark_as_advanced(OPENCL_LOADER_URL)
mark_as_advanced(OPENCL_LOADER_MD5)
include(ExternalProject)
ExternalProject_Add(opencl_loader
URL ${OPENCL_LOADER_URL}
URL_MD5 ${OPENCL_LOADER_MD5}
SOURCE_DIR "${CMAKE_BINARY_DIR}/opencl_loader-src"
BINARY_DIR "${CMAKE_BINARY_DIR}/opencl_loader-build"
CMAKE_ARGS ${CMAKE_REQUEST_PIC} ${CMAKE_EXTRA_OPENCL_LOADER_OPTS}
-DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
-DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>
-DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
-DCMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM}
-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
BUILD_BYPRODUCTS <BINARY_DIR>/libOpenCL${CMAKE_STATIC_LIBRARY_SUFFIX}
LOG_DOWNLOAD ON
LOG_CONFIGURE ON
LOG_BUILD ON
INSTALL_COMMAND ""
TEST_COMMAND "")
ExternalProject_Get_Property(opencl_loader SOURCE_DIR)
set(OPENCL_LOADER_INCLUDE_DIR ${SOURCE_DIR}/inc)
# workaround for CMake 3.10 on ubuntu 18.04
file(MAKE_DIRECTORY ${OPENCL_LOADER_INCLUDE_DIR})
ExternalProject_Get_Property(opencl_loader BINARY_DIR)
set(OPENCL_LOADER_LIBRARY_PATH "${BINARY_DIR}/libOpenCL${CMAKE_STATIC_LIBRARY_SUFFIX}")
find_package(Threads QUIET)
if(NOT WIN32)
set(OPENCL_LOADER_DEP_LIBS "Threads::Threads;${CMAKE_DL_LIBS}")
else()
set(OPENCL_LOADER_DEP_LIBS "cfgmgr32;runtimeobject")
endif()
add_library(OpenCL::OpenCL UNKNOWN IMPORTED)
add_dependencies(OpenCL::OpenCL opencl_loader)
set_target_properties(OpenCL::OpenCL PROPERTIES
IMPORTED_LOCATION ${OPENCL_LOADER_LIBRARY_PATH}
INTERFACE_INCLUDE_DIRECTORIES ${OPENCL_LOADER_INCLUDE_DIR}
INTERFACE_LINK_LIBRARIES "${OPENCL_LOADER_DEP_LIBS}")
set(INSTALL_LIBOPENCL OFF CACHE BOOL "" FORCE)
include(ExternalCMakeProject)
ExternalCMakeProject(opencl_loader ${OPENCL_LOADER_URL} ${OPENCL_LOADER_MD5} opencl-loader . "")
add_library(OpenCL::OpenCL ALIAS OpenCL)

9
cmake/Modules/Packages/COMPRESS.cmake
View File

@ -1,10 +1,11 @@
find_package(ZLIB REQUIRED)
target_link_libraries(lammps PRIVATE ZLIB::ZLIB)
find_package(PkgConfig REQUIRED)
pkg_check_modules(Zstd IMPORTED_TARGET libzstd>=1.4)
if(Zstd_FOUND)
find_package(PkgConfig QUIET)
if(PkgConfig_FOUND)
pkg_check_modules(Zstd IMPORTED_TARGET libzstd>=1.4)
if(Zstd_FOUND)
target_compile_definitions(lammps PRIVATE -DLAMMPS_ZSTD)
target_link_libraries(lammps PRIVATE PkgConfig::Zstd)
endif()
endif()

121
cmake/Modules/Packages/GPU.cmake
View File

@ -30,7 +30,15 @@ file(GLOB GPU_LIB_SOURCES ${LAMMPS_LIB_SOURCE_DIR}/gpu/[^.]*.cpp)
file(MAKE_DIRECTORY ${LAMMPS_LIB_BINARY_DIR}/gpu)
if(GPU_API STREQUAL "CUDA")
find_package(CUDA REQUIRED)
find_package(CUDA QUIET)
# augment search path for CUDA toolkit libraries to include the stub versions. Needed to find libcuda.so on machines without a CUDA driver installation
if(CUDA_FOUND)
set(CMAKE_LIBRARY_PATH "${CUDA_TOOLKIT_ROOT_DIR}/lib64/stubs;${CUDA_TOOLKIT_ROOT_DIR}/lib/stubs;${CUDA_TOOLKIT_ROOT_DIR}/lib64;${CUDA_TOOLKIT_ROOT_DIR}/lib;${CMAKE_LIBRARY_PATH}")
find_package(CUDA REQUIRED)
else()
message(FATAL_ERROR "CUDA Toolkit not found")
endif()
find_program(BIN2C bin2c)
if(NOT BIN2C)
message(FATAL_ERROR "Could not find bin2c, use -DBIN2C=/path/to/bin2c to help cmake finding it.")
@ -71,44 +79,47 @@ if(GPU_API STREQUAL "CUDA")
# build arch/gencode commands for nvcc based on CUDA toolkit version and use choice
# --arch translates directly instead of JIT, so this should be for the preferred or most common architecture
set(GPU_CUDA_GENCODE "-arch=${GPU_ARCH}")
# Fermi (GPU Arch 2.x) is supported by CUDA 3.2 to CUDA 8.0
if((CUDA_VERSION VERSION_GREATER_EQUAL "3.2") AND (CUDA_VERSION VERSION_LESS "9.0"))
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_20,code=[sm_20,compute_20] ")
endif()
# Kepler (GPU Arch 3.0) is supported by CUDA 5 to CUDA 10.2
if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "11.0"))
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30] ")
endif()
# Kepler (GPU Arch 3.5) is supported by CUDA 5 to CUDA 11
if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "12.0"))
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_35,code=[sm_35,compute_35]")
endif()
# Maxwell (GPU Arch 5.x) is supported by CUDA 6 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "6.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52]")
endif()
# Pascal (GPU Arch 6.x) is supported by CUDA 8 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "8.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61]")
endif()
# Volta (GPU Arch 7.0) is supported by CUDA 9 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "9.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_70,code=[sm_70,compute_70]")
endif()
# Turing (GPU Arch 7.5) is supported by CUDA 10 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "10.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_75,code=[sm_75,compute_75]")
endif()
# Ampere (GPU Arch 8.0) is supported by CUDA 11 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_80,code=[sm_80,compute_80]")
endif()
# Ampere (GPU Arch 8.6) is supported by CUDA 11.1 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.1")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_86,code=[sm_86,compute_86]")
endif()
# apply the following to build "fat" CUDA binaries only for known CUDA toolkits
if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
message(WARNING "Unsupported CUDA version. Use at your own risk.")
message(WARNING "Untested CUDA Toolkit version. Use at your own risk")
else()
# Fermi (GPU Arch 2.x) is supported by CUDA 3.2 to CUDA 8.0
if((CUDA_VERSION VERSION_GREATER_EQUAL "3.2") AND (CUDA_VERSION VERSION_LESS "9.0"))
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_20,code=[sm_20,compute_20] ")
endif()
# Kepler (GPU Arch 3.0) is supported by CUDA 5 to CUDA 10.2
if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "11.0"))
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30] ")
endif()
# Kepler (GPU Arch 3.5) is supported by CUDA 5 to CUDA 11
if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "12.0"))
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_35,code=[sm_35,compute_35]")
endif()
# Maxwell (GPU Arch 5.x) is supported by CUDA 6 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "6.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52]")
endif()
# Pascal (GPU Arch 6.x) is supported by CUDA 8 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "8.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61]")
endif()
# Volta (GPU Arch 7.0) is supported by CUDA 9 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "9.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_70,code=[sm_70,compute_70]")
endif()
# Turing (GPU Arch 7.5) is supported by CUDA 10 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "10.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_75,code=[sm_75,compute_75]")
endif()
# Ampere (GPU Arch 8.0) is supported by CUDA 11 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.0")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_80,code=[sm_80,compute_80]")
endif()
# Ampere (GPU Arch 8.6) is supported by CUDA 11.1 and later
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.1")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_86,code=[sm_86,compute_86]")
endif()
endif()
cuda_compile_fatbin(GPU_GEN_OBJS ${GPU_LIB_CU} OPTIONS ${CUDA_REQUEST_PIC}
@ -214,13 +225,20 @@ elseif(GPU_API STREQUAL "OPENCL")
elseif(GPU_API STREQUAL "HIP")
if(NOT DEFINED HIP_PATH)
if(NOT DEFINED ENV{HIP_PATH})
set(HIP_PATH "/opt/rocm/hip" CACHE PATH "Path to which HIP has been installed")
set(HIP_PATH "/opt/rocm/hip" CACHE PATH "Path to HIP installation")
else()
set(HIP_PATH $ENV{HIP_PATH} CACHE PATH "Path to which HIP has been installed")
set(HIP_PATH $ENV{HIP_PATH} CACHE PATH "Path to HIP installation")
endif()
endif()
set(CMAKE_MODULE_PATH "${HIP_PATH}/cmake" ${CMAKE_MODULE_PATH})
find_package(HIP REQUIRED)
if(NOT DEFINED ROCM_PATH)
if(NOT DEFINED ENV{ROCM_PATH})
set(ROCM_PATH "/opt/rocm" CACHE PATH "Path to ROCm installation")
else()
set(ROCM_PATH $ENV{ROCM_PATH} CACHE PATH "Path to ROCm installation")
endif()
endif()
list(APPEND CMAKE_PREFIX_PATH ${HIP_PATH} ${ROCM_PATH})
find_package(hip REQUIRED)
option(HIP_USE_DEVICE_SORT "Use GPU sorting" ON)
if(NOT DEFINED HIP_PLATFORM)
@ -296,12 +314,12 @@ elseif(GPU_API STREQUAL "HIP")
if(HIP_COMPILER STREQUAL "clang")
add_custom_command(OUTPUT ${CUBIN_FILE}
VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco --offload-arch=${HIP_ARCH} -O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_CPP_FILE}
VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco --offload-arch=${HIP_ARCH} -O3 -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_CPP_FILE}
DEPENDS ${CU_CPP_FILE}
COMMENT "Generating ${CU_NAME}.cubin")
else()
add_custom_command(OUTPUT ${CUBIN_FILE}
VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco -t="${HIP_ARCH}" -f=\"-O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu\" -o ${CUBIN_FILE} ${CU_CPP_FILE}
VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco -t="${HIP_ARCH}" -f=\"-O3 -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu\" -o ${CUBIN_FILE} ${CU_CPP_FILE}
DEPENDS ${CU_CPP_FILE}
COMMENT "Generating ${CU_NAME}.cubin")
endif()
@ -322,10 +340,11 @@ elseif(GPU_API STREQUAL "HIP")
set_directory_properties(PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES "${LAMMPS_LIB_BINARY_DIR}/gpu/*_cubin.h ${LAMMPS_LIB_BINARY_DIR}/gpu/*.cu.cpp")
hip_add_library(gpu STATIC ${GPU_LIB_SOURCES})
add_library(gpu STATIC ${GPU_LIB_SOURCES})
target_include_directories(gpu PRIVATE ${LAMMPS_LIB_BINARY_DIR}/gpu)
target_compile_definitions(gpu PRIVATE -D_${GPU_PREC_SETTING} -DMPI_GERYON -DUCL_NO_EXIT)
target_compile_definitions(gpu PRIVATE -DUSE_HIP)
target_link_libraries(gpu PRIVATE hip::host)
if(HIP_USE_DEVICE_SORT)
# add hipCUB
@ -374,8 +393,9 @@ elseif(GPU_API STREQUAL "HIP")
endif()
endif()
hip_add_executable(hip_get_devices ${LAMMPS_LIB_SOURCE_DIR}/gpu/geryon/ucl_get_devices.cpp)
add_executable(hip_get_devices ${LAMMPS_LIB_SOURCE_DIR}/gpu/geryon/ucl_get_devices.cpp)
target_compile_definitions(hip_get_devices PRIVATE -DUCL_HIP)
target_link_libraries(hip_get_devices hip::host)
if(HIP_PLATFORM STREQUAL "nvcc")
target_compile_definitions(gpu PRIVATE -D__HIP_PLATFORM_NVCC__)
@ -410,13 +430,12 @@ RegisterStylesExt(${GPU_SOURCES_DIR} gpu GPU_SOURCES)
RegisterFixStyle(${GPU_SOURCES_DIR}/fix_gpu.h)
get_property(GPU_SOURCES GLOBAL PROPERTY GPU_SOURCES)
if(NOT BUILD_MPI)
# mpistubs is aliased to MPI::MPI_CXX, but older versions of cmake won't work forward the include path
target_link_libraries(gpu PRIVATE mpi_stubs)
else()
if(BUILD_MPI)
target_link_libraries(gpu PRIVATE MPI::MPI_CXX)
else()
target_link_libraries(gpu PRIVATE mpi_stubs)
endif()
target_compile_definitions(gpu PRIVATE -DLAMMPS_${LAMMPS_SIZES})
set_target_properties(gpu PROPERTIES OUTPUT_NAME lammps_gpu${LAMMPS_MACHINE})
target_sources(lammps PRIVATE ${GPU_SOURCES})

56
cmake/Modules/Packages/KOKKOS.cmake
View File

@ -1,6 +1,8 @@
########################################################################
# As of version 3.3.0 Kokkos requires C++14
set(CMAKE_CXX_STANDARD 14)
if(CMAKE_CXX_STANDARD LESS 14)
message(FATAL_ERROR "The KOKKOS package requires the C++ standard to be set to at least C++14")
endif()
########################################################################
# consistency checks and Kokkos options/settings required by LAMMPS
if(Kokkos_ENABLE_CUDA)
@ -9,8 +11,14 @@ if(Kokkos_ENABLE_CUDA)
endif()
# Adding OpenMP compiler flags without the checks done for
# BUILD_OMP can result in compile failures. Enforce consistency.
if(Kokkos_ENABLE_OPENMP AND NOT BUILD_OMP)
message(FATAL_ERROR "Must enable BUILD_OMP with Kokkos_ENABLE_OPENMP")
if(Kokkos_ENABLE_OPENMP)
if(NOT BUILD_OMP)
message(FATAL_ERROR "Must enable BUILD_OMP with Kokkos_ENABLE_OPENMP")
else()
if(LAMMPS_OMP_COMPAT_LEVEL LESS 4)
message(FATAL_ERROR "Compiler must support OpenMP 4.0 or later with Kokkos_ENABLE_OPENMP")
endif()
endif()
endif()
########################################################################
@ -25,6 +33,8 @@ if(DOWNLOAD_KOKKOS)
endforeach()
message(STATUS "KOKKOS download requested - we will build our own")
list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>")
# build KOKKOS downloaded libraries as static libraries but with PIC, if needed
list(APPEND KOKKOS_LIB_BUILD_ARGS "-DBUILD_SHARED_LIBS=OFF")
if(CMAKE_REQUEST_PIC)
list(APPEND KOKKOS_LIB_BUILD_ARGS ${CMAKE_REQUEST_PIC})
endif()
@ -37,35 +47,48 @@ 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/3.4.01.tar.gz" CACHE STRING "URL for KOKKOS tarball")
set(KOKKOS_MD5 "4c84698917c93a18985b311bb6caf84f" CACHE STRING "MD5 checksum of KOKKOS tarball")
set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/3.5.00.tar.gz" CACHE STRING "URL for KOKKOS tarball")
set(KOKKOS_MD5 "079323d973ae0e1c38c0a54a150c674e" CACHE STRING "MD5 checksum of KOKKOS tarball")
mark_as_advanced(KOKKOS_URL)
mark_as_advanced(KOKKOS_MD5)
ExternalProject_Add(kokkos_build
URL ${KOKKOS_URL}
URL_MD5 ${KOKKOS_MD5}
CMAKE_ARGS ${KOKKOS_LIB_BUILD_ARGS}
BUILD_BYPRODUCTS <INSTALL_DIR>/lib/libkokkoscore.a
BUILD_BYPRODUCTS <INSTALL_DIR>/lib/libkokkoscore.a <INSTALL_DIR>/lib/libkokkoscontainers.a
)
ExternalProject_get_property(kokkos_build INSTALL_DIR)
file(MAKE_DIRECTORY ${INSTALL_DIR}/include)
add_library(LAMMPS::KOKKOS UNKNOWN IMPORTED)
set_target_properties(LAMMPS::KOKKOS PROPERTIES
add_library(LAMMPS::KOKKOSCORE UNKNOWN IMPORTED)
add_library(LAMMPS::KOKKOSCONTAINERS UNKNOWN IMPORTED)
set_target_properties(LAMMPS::KOKKOSCORE PROPERTIES
IMPORTED_LOCATION "${INSTALL_DIR}/lib/libkokkoscore.a"
INTERFACE_INCLUDE_DIRECTORIES "${INSTALL_DIR}/include"
INTERFACE_LINK_LIBRARIES ${CMAKE_DL_LIBS})
target_link_libraries(lammps PRIVATE LAMMPS::KOKKOS)
target_link_libraries(lmp PRIVATE LAMMPS::KOKKOS)
add_dependencies(LAMMPS::KOKKOS kokkos_build)
set_target_properties(LAMMPS::KOKKOSCONTAINERS PROPERTIES
IMPORTED_LOCATION "${INSTALL_DIR}/lib/libkokkoscontainers.a")
target_link_libraries(lammps PRIVATE LAMMPS::KOKKOSCORE LAMMPS::KOKKOSCONTAINERS)
target_link_libraries(lmp PRIVATE LAMMPS::KOKKOSCORE LAMMPS::KOKKOSCONTAINERS)
add_dependencies(LAMMPS::KOKKOSCORE kokkos_build)
add_dependencies(LAMMPS::KOKKOSCONTAINERS kokkos_build)
elseif(EXTERNAL_KOKKOS)
find_package(Kokkos 3.4.01 REQUIRED CONFIG)
find_package(Kokkos 3.5.00 REQUIRED CONFIG)
target_link_libraries(lammps PRIVATE Kokkos::kokkos)
target_link_libraries(lmp PRIVATE Kokkos::kokkos)
else()
set(LAMMPS_LIB_KOKKOS_SRC_DIR ${LAMMPS_LIB_SOURCE_DIR}/kokkos)
set(LAMMPS_LIB_KOKKOS_BIN_DIR ${LAMMPS_LIB_BINARY_DIR}/kokkos)
# build KOKKOS internal libraries as static libraries but with PIC, if needed
if(BUILD_SHARED_LIBS)
set(BUILD_SHARED_LIBS_WAS_ON YES)
set(BUILD_SHARED_LIBS OFF)
endif()
if(CMAKE_REQUEST_PIC)
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
endif()
add_subdirectory(${LAMMPS_LIB_KOKKOS_SRC_DIR} ${LAMMPS_LIB_KOKKOS_BIN_DIR})
set(Kokkos_INCLUDE_DIRS ${LAMMPS_LIB_KOKKOS_SRC_DIR}/core/src
${LAMMPS_LIB_KOKKOS_SRC_DIR}/containers/src
${LAMMPS_LIB_KOKKOS_SRC_DIR}/algorithms/src
@ -73,6 +96,9 @@ else()
target_include_directories(lammps PRIVATE ${Kokkos_INCLUDE_DIRS})
target_link_libraries(lammps PRIVATE kokkos)
target_link_libraries(lmp PRIVATE kokkos)
if(BUILD_SHARED_LIBS_WAS_ON)
set(BUILD_SHARED_LIBS ON)
endif()
endif()
target_compile_definitions(lammps PUBLIC $<BUILD_INTERFACE:LMP_KOKKOS>)
@ -107,6 +133,12 @@ if(PKG_KSPACE)
endif()
endif()
if(PKG_PHONON)
list(APPEND KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/dynamical_matrix_kokkos.cpp)
list(APPEND KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/third_order_kokkos.cpp)
endif()
set_property(GLOBAL PROPERTY "KOKKOS_PKG_SOURCES" "${KOKKOS_PKG_SOURCES}")
# detects styles which have KOKKOS version

8
cmake/Modules/Packages/LATTE.cmake
View File

@ -19,6 +19,14 @@ if(DOWNLOAD_LATTE)
set(LATTE_MD5 "820e73a457ced178c08c71389a385de7" CACHE STRING "MD5 checksum of LATTE tarball")
mark_as_advanced(LATTE_URL)
mark_as_advanced(LATTE_MD5)
# CMake cannot pass BLAS or LAPACK library variable to external project if they are a list
list(LENGTH BLAS_LIBRARIES} NUM_BLAS)
list(LENGTH LAPACK_LIBRARIES NUM_LAPACK)
if((NUM_BLAS GREATER 1) OR (NUM_LAPACK GREATER 1))
message(FATAL_ERROR "Cannot compile downloaded LATTE library due to a technical limitation")
endif()
include(ExternalProject)
ExternalProject_Add(latte_build
URL ${LATTE_URL}

5
cmake/Modules/Packages/MACHDYN.cmake
View File

@ -7,8 +7,9 @@ endif()
option(DOWNLOAD_EIGEN3 "Download Eigen3 instead of using an already installed one)" ${DOWNLOAD_EIGEN3_DEFAULT})
if(DOWNLOAD_EIGEN3)
message(STATUS "Eigen3 download requested - we will build our own")
set(EIGEN3_URL "https://gitlab.com/libeigen/eigen/-/archive/3.3.9/eigen-3.3.9.tar.gz" CACHE STRING "URL for Eigen3 tarball")
set(EIGEN3_MD5 "609286804b0f79be622ccf7f9ff2b660" CACHE STRING "MD5 checksum of Eigen3 tarball")
set(EIGEN3_URL "${LAMMPS_THIRDPARTY_URL}/eigen-3.4.0.tar.gz" CACHE STRING "URL for Eigen3 tarball")
set(EIGEN3_MD5 "4c527a9171d71a72a9d4186e65bea559" CACHE STRING "MD5 checksum of Eigen3 tarball")
mark_as_advanced(EIGEN3_URL)
mark_as_advanced(EIGEN3_MD5)
include(ExternalProject)

16
cmake/Modules/Packages/ML-HDNNP.cmake
View File

@ -45,13 +45,11 @@ if(DOWNLOAD_N2P2)
# get path to MPI include directory when cross-compiling to windows
if((CMAKE_SYSTEM_NAME STREQUAL Windows) AND CMAKE_CROSSCOMPILING)
get_target_property(N2P2_MPI_INCLUDE MPI::MPI_CXX INTERFACE_INCLUDE_DIRECTORIES)
set(N2P2_PROJECT_OPTIONS "-I ${N2P2_MPI_INCLUDE} -DMPICH_SKIP_MPICXX=1")
set(MPI_CXX_COMPILER ${CMAKE_CXX_COMPILER})
set(N2P2_PROJECT_OPTIONS "-I${N2P2_MPI_INCLUDE}")
endif()
if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
get_target_property(N2P2_MPI_INCLUDE MPI::MPI_CXX INTERFACE_INCLUDE_DIRECTORIES)
set(N2P2_PROJECT_OPTIONS "-I ${N2P2_MPI_INCLUDE} -DMPICH_SKIP_MPICXX=1")
set(MPI_CXX_COMPILER ${CMAKE_CXX_COMPILER})
set(N2P2_PROJECT_OPTIONS "-I${N2P2_MPI_INCLUDE}")
endif()
endif()
@ -64,11 +62,17 @@ if(DOWNLOAD_N2P2)
string(TOUPPER "${CMAKE_BUILD_TYPE}" BTYPE)
set(N2P2_BUILD_FLAGS "${CMAKE_SHARED_LIBRARY_CXX_FLAGS} ${CMAKE_CXX_FLAGS} ${CMAKE_CXX_FLAGS_${BTYPE}} ${N2P2_CXX_STD}")
set(N2P2_BUILD_OPTIONS INTERFACES=LAMMPS COMP=${N2P2_COMP} "PROJECT_OPTIONS=${N2P2_PROJECT_OPTIONS}" "PROJECT_DEBUG="
"PROJECT_CC=${CMAKE_CXX_COMPILER}" "PROJECT_MPICC=${MPI_CXX_COMPILER}" "PROJECT_CFLAGS=${N2P2_BUILD_FLAGS}"
"PROJECT_AR=${N2P2_AR}")
"PROJECT_CC=${CMAKE_CXX_COMPILER}" "PROJECT_MPICC=${CMAKE_CXX_COMPILER}" "PROJECT_CFLAGS=${N2P2_BUILD_FLAGS}"
"PROJECT_AR=${N2P2_AR}" "APP_CORE=nnp-convert" "APP_TRAIN=nnp-train" "APP=nnp-convert")
# echo final flag for debugging
message(STATUS "N2P2 BUILD OPTIONS: ${N2P2_BUILD_OPTIONS}")
# must have "sed" command to compile n2p2 library (for now)
find_program(HAVE_SED sed)
if(NOT HAVE_SED)
message(FATAL_ERROR "Must have 'sed' program installed to compile 'n2p2' library for ML-HDNNP package")
endif()
# download compile n2p2 library. much patch MPI calls in LAMMPS interface to accommodate MPI-2 (e.g. for cross-compiling)
include(ExternalProject)
ExternalProject_Add(n2p2_build

21
cmake/Modules/Packages/ML-PACE.cmake
View File

@ -1,11 +1,11 @@
set(PACELIB_URL "https://github.com/ICAMS/lammps-user-pace/archive/refs/tags/v.2021.10.25.tar.gz" CACHE STRING "URL for PACE evaluator library sources")
set(PACELIB_URL "https://github.com/ICAMS/lammps-user-pace/archive/refs/tags/v.2021.4.9.tar.gz" CACHE STRING "URL for PACE evaluator library sources")
set(PACELIB_MD5 "4db54962fbd6adcf8c18d46e1798ceb5" CACHE STRING "MD5 checksum of PACE evaluator library tarball")
set(PACELIB_MD5 "a2ac3315c41a1a4a5c912bcb1bc9c5cc" CACHE STRING "MD5 checksum of PACE evaluator library tarball")
mark_as_advanced(PACELIB_URL)
mark_as_advanced(PACELIB_MD5)
# download library sources to build folder
file(DOWNLOAD ${PACELIB_URL} ${CMAKE_BINARY_DIR}/libpace.tar.gz SHOW_PROGRESS EXPECTED_HASH MD5=${PACELIB_MD5})
file(DOWNLOAD ${PACELIB_URL} ${CMAKE_BINARY_DIR}/libpace.tar.gz EXPECTED_HASH MD5=${PACELIB_MD5}) #SHOW_PROGRESS
# uncompress downloaded sources
execute_process(
@ -14,12 +14,19 @@ execute_process(
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
)
file(GLOB PACE_EVALUATOR_INCLUDE_DIR ${CMAKE_BINARY_DIR}/lammps-user-pace-*/USER-PACE)
file(GLOB PACE_EVALUATOR_SOURCES ${CMAKE_BINARY_DIR}/lammps-user-pace-*/USER-PACE/*.cpp)
file(GLOB lib-pace ${CMAKE_BINARY_DIR}/lammps-user-pace-*)
add_subdirectory(${lib-pace}/yaml-cpp build-yaml-cpp)
set(YAML_CPP_INCLUDE_DIR ${lib-pace}/yaml-cpp/include)
file(GLOB PACE_EVALUATOR_INCLUDE_DIR ${lib-pace}/ML-PACE)
file(GLOB PACE_EVALUATOR_SOURCES ${lib-pace}/ML-PACE/*.cpp)
list(FILTER PACE_EVALUATOR_SOURCES EXCLUDE REGEX pair_pace.cpp)
add_library(pace STATIC ${PACE_EVALUATOR_SOURCES})
set_target_properties(pace PROPERTIES CXX_EXTENSIONS ON OUTPUT_NAME lammps_pace${LAMMPS_MACHINE})
target_include_directories(pace PUBLIC ${PACE_EVALUATOR_INCLUDE_DIR})
target_link_libraries(lammps PRIVATE pace)
target_include_directories(pace PUBLIC ${PACE_EVALUATOR_INCLUDE_DIR} ${YAML_CPP_INCLUDE_DIR})
target_link_libraries(pace PRIVATE yaml-cpp-pace)
target_link_libraries(lammps PRIVATE pace)

7
cmake/Modules/Packages/ML-QUIP.cmake
View File

@ -32,13 +32,14 @@ if(DOWNLOAD_QUIP)
foreach(flag ${LAPACK_LIBRARIES})
set(temp "${temp} ${flag}")
endforeach()
set(temp "${temp}\n")
# Fix cmake crashing when MATH_LINKOPTS not set, required for e.g. recent Cray Programming Environment
set(temp "${temp} -L/_DUMMY_PATH_\n")
set(temp "${temp}PYTHON=python\nPIP=pip\nEXTRA_LINKOPTS=\n")
set(temp "${temp}HAVE_CP2K=0\nHAVE_VASP=0\nHAVE_TB=0\nHAVE_PRECON=1\nHAVE_LOTF=0\nHAVE_ONIOM=0\n")
set(temp "${temp}HAVE_LOCAL_E_MIX=0\nHAVE_QC=0\nHAVE_GAP=1\nHAVE_DESCRIPTORS_NONCOMMERCIAL=1\n")
set(temp "${temp}HAVE_TURBOGAP=0\nHAVE_QR=1\nHAVE_THIRDPARTY=0\nHAVE_FX=0\nHAVE_SCME=0\nHAVE_MTP=0\n")
set(temp "${temp}HAVE_MBD=0\nHAVE_TTM_NF=0\nHAVE_CH4=0\nHAVE_NETCDF4=0\nHAVE_MDCORE=0\nHAVE_ASAP=0\n")
set(temp "${temp}HAVE_CGAL=0\nHAVE_METIS=0\nHAVE_LMTO_TBE=0\n")
set(temp "${temp}HAVE_CGAL=0\nHAVE_METIS=0\nHAVE_LMTO_TBE=0\nHAVE_SCALAPACK=0\n")
file(WRITE ${CMAKE_BINARY_DIR}/quip.config "${temp}")
message(STATUS "QUIP download via git requested - we will build our own")
@ -50,7 +51,7 @@ if(DOWNLOAD_QUIP)
GIT_TAG origin/public
GIT_SHALLOW YES
GIT_PROGRESS YES
PATCH_COMMAND cp ${CMAKE_BINARY_DIR}/quip.config <SOURCE_DIR>/arch/Makefile.lammps
PATCH_COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_BINARY_DIR}/quip.config <SOURCE_DIR>/arch/Makefile.lammps
CONFIGURE_COMMAND env QUIP_ARCH=lammps make config
BUILD_COMMAND env QUIP_ARCH=lammps make libquip
INSTALL_COMMAND ""

34
cmake/Modules/Packages/MSCG.cmake
View File

@ -12,34 +12,12 @@ if(DOWNLOAD_MSCG)
mark_as_advanced(MSCG_URL)
mark_as_advanced(MSCG_MD5)
include(ExternalProject)
ExternalProject_Add(mscg_build
URL ${MSCG_URL}
URL_MD5 ${MSCG_MD5}
SOURCE_SUBDIR src/CMake
CMAKE_ARGS ${CMAKE_REQUEST_PIC} ${EXTRA_MSCG_OPTS}
-DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}
-DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
-DCMAKE_Fortran_COMPILER=${CMAKE_Fortran_COMPILER}
-DBLAS_LIBRARIES=${BLAS_LIBRARIES} -DLAPACK_LIBRARIES=${LAPACK_LIBRARIES}
-DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>
-DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
-DCMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM}
-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
BUILD_COMMAND ${CMAKE_COMMAND} --build . --target mscg
INSTALL_COMMAND ""
BUILD_BYPRODUCTS <BINARY_DIR>/libmscg.a
)
ExternalProject_get_property(mscg_build BINARY_DIR)
ExternalProject_get_property(mscg_build SOURCE_DIR)
file(MAKE_DIRECTORY ${SOURCE_DIR}/src)
add_library(LAMMPS::MSCG UNKNOWN IMPORTED)
set_target_properties(LAMMPS::MSCG PROPERTIES
IMPORTED_LOCATION "${BINARY_DIR}/libmscg.a"
INTERFACE_INCLUDE_DIRECTORIES "${SOURCE_DIR}/src"
INTERFACE_LINK_LIBRARIES "${LAPACK_LIBRARIES}")
target_link_libraries(lammps PRIVATE LAMMPS::MSCG)
add_dependencies(LAMMPS::MSCG mscg_build)
include(ExternalCMakeProject)
ExternalCMakeProject(mscg ${MSCG_URL} ${MSCG_MD5} MSCG-release src/CMake "")
# set include and link library
target_include_directories(lammps PRIVATE "${CMAKE_BINARY_DIR}/_deps/mscg-src/src")
target_link_libraries(lammps PRIVATE mscg)
else()
find_package(MSCG)
if(NOT MSCG_FOUND)

9
cmake/Modules/Packages/PHONON.cmake Normal file
View File

@ -0,0 +1,9 @@
# fix phonon may only be installed if also the FFT wrappers from KSPACE are installed
if(NOT PKG_KSPACE)
get_property(LAMMPS_FIX_HEADERS GLOBAL PROPERTY FIX)
list(REMOVE_ITEM LAMMPS_FIX_HEADERS ${LAMMPS_SOURCE_DIR}/PHONON/fix_phonon.h)
set_property(GLOBAL PROPERTY FIX "${LAMMPS_FIX_HEADERS}")
get_target_property(LAMMPS_SOURCES lammps SOURCES)
list(REMOVE_ITEM LAMMPS_SOURCES ${LAMMPS_SOURCE_DIR}/PHONON/fix_phonon.cpp)
set_property(TARGET lammps PROPERTY SOURCES "${LAMMPS_SOURCES}")
endif()

4
cmake/Modules/Packages/PLUMED.cmake
View File

@ -54,8 +54,8 @@ if(DOWNLOAD_PLUMED)
set(PLUMED_BUILD_BYPRODUCTS "<INSTALL_DIR>/lib/libplumedWrapper.a")
endif()
set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.7.2/plumed-src-2.7.2.tgz" CACHE STRING "URL for PLUMED tarball")
set(PLUMED_MD5 "cfa0b4dd90a81c25d3302e8d97bfeaea" CACHE STRING "MD5 checksum of PLUMED tarball")
set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.7.4/plumed-src-2.7.4.tgz" CACHE STRING "URL for PLUMED tarball")
set(PLUMED_MD5 "858e0b6aed173748fc85b6bc8a9dcb3e" CACHE STRING "MD5 checksum of PLUMED tarball")
mark_as_advanced(PLUMED_URL)
mark_as_advanced(PLUMED_MD5)

2
cmake/Modules/Packages/PYTHON.cmake
View File

@ -3,7 +3,7 @@ if(CMAKE_VERSION VERSION_LESS 3.12)
target_include_directories(lammps PRIVATE ${PYTHON_INCLUDE_DIRS})
target_link_libraries(lammps PRIVATE ${PYTHON_LIBRARIES})
else()
find_package(Python REQUIRED COMPONENTS Development)
find_package(Python REQUIRED COMPONENTS Interpreter Development)
target_link_libraries(lammps PRIVATE Python::Python)
endif()
target_compile_definitions(lammps PRIVATE -DLMP_PYTHON)

5
cmake/Modules/Packages/SCAFACOS.cmake
View File

@ -23,6 +23,11 @@ if(DOWNLOAD_SCAFACOS)
file(DOWNLOAD ${LAMMPS_THIRDPARTY_URL}/scafacos-1.0.1-fix.diff ${CMAKE_CURRENT_BINARY_DIR}/scafacos-1.0.1.fix.diff
EXPECTED_HASH MD5=4baa1333bb28fcce102d505e1992d032)
find_program(HAVE_PATCH patch)
if(NOT HAVE_PATCH)
message(FATAL_ERROR "The 'patch' program is required to build the ScaFaCoS library")
endif()
include(ExternalProject)
ExternalProject_Add(scafacos_build
URL ${SCAFACOS_URL}

5
cmake/Modules/Packages/VORONOI.cmake
View File

@ -26,6 +26,11 @@ if(DOWNLOAD_VORO)
set(VORO_BUILD_OPTIONS CXX=${CMAKE_CXX_COMPILER} CFLAGS=${VORO_BUILD_CFLAGS})
endif()
find_program(HAVE_PATCH patch)
if(NOT HAVE_PATCH)
message(FATAL_ERROR "The 'patch' program is required to build the voro++ library")
endif()
ExternalProject_Add(voro_build
URL ${VORO_URL}
URL_MD5 ${VORO_MD5}

4
cmake/Modules/Tools.cmake
View File

@ -25,7 +25,9 @@ if(BUILD_TOOLS)
get_filename_component(MSI2LMP_SOURCE_DIR ${LAMMPS_TOOLS_DIR}/msi2lmp/src ABSOLUTE)
file(GLOB MSI2LMP_SOURCES ${MSI2LMP_SOURCE_DIR}/[^.]*.c)
add_executable(msi2lmp ${MSI2LMP_SOURCES})
target_link_libraries(msi2lmp PRIVATE ${MATH_LIBRARIES})
if(STANDARD_MATH_LIB)
target_link_libraries(msi2lmp PRIVATE ${STANDARD_MATH_LIB})
endif()
install(TARGETS msi2lmp DESTINATION ${CMAKE_INSTALL_BINDIR})
install(FILES ${LAMMPS_DOC_DIR}/msi2lmp.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
endif()

47
cmake/Modules/YAML.cmake
View File

@ -1,47 +0,0 @@
message(STATUS "Downloading and building YAML library")
include(ExternalProject)
set(YAML_URL "https://pyyaml.org/download/libyaml/yaml-0.2.5.tar.gz" CACHE STRING "URL for libyaml tarball")
set(YAML_MD5 "bb15429d8fb787e7d3f1c83ae129a999" CACHE STRING "MD5 checksum of libyaml tarball")
mark_as_advanced(YAML_URL)
mark_as_advanced(YAML_MD5)
# support cross-compilation to windows
if(CMAKE_CROSSCOMPILING AND (CMAKE_SYSTEM_NAME STREQUAL "Windows"))
if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86")
set(YAML_CROSS_HOST --host=i686-mingw64)
elseif(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
set(YAML_CROSS_HOST --host=x86_64-mingw64)
else()
message(FATAL_ERROR "Unsupported cross-compilation "
" for ${CMAKE_SYSTEM_NAME}/${CMAKE_SYSTEM_PROCESSOR}"
" on ${CMAKE_HOST_SYSTEM}/${CMAKE_HOST_SYSTEM_PROCESSOR}")
endif()
endif()
ExternalProject_Add(libyaml
URL ${YAML_URL}
URL_MD5 ${YAML_MD5}
SOURCE_DIR "${CMAKE_BINARY_DIR}/yaml-src"
BINARY_DIR "${CMAKE_BINARY_DIR}/yaml-build"
CONFIGURE_COMMAND <SOURCE_DIR>/configure ${CONFIGURE_REQUEST_PIC}
CXX=${CMAKE_CXX_COMPILER} CC=${CMAKE_C_COMPILER}
--prefix=<INSTALL_DIR> --disable-shared ${YAML_CROSS_HOST}
BUILD_BYPRODUCTS <INSTALL_DIR>/lib/libyaml${CMAKE_STATIC_LIBRARY_SUFFIX}
TEST_COMMAND "")
ExternalProject_Get_Property(libyaml INSTALL_DIR)
set(YAML_INCLUDE_DIR ${INSTALL_DIR}/include)
set(YAML_LIBRARY_DIR ${INSTALL_DIR}/lib)
# workaround for CMake 3.10 on ubuntu 18.04
file(MAKE_DIRECTORY ${YAML_INCLUDE_DIR})
file(MAKE_DIRECTORY ${YAML_LIBRARY_DIR})
set(YAML_LIBRARY_PATH ${INSTALL_DIR}/lib/libyaml${CMAKE_STATIC_LIBRARY_SUFFIX})
add_library(Yaml::Yaml UNKNOWN IMPORTED)
set_target_properties(Yaml::Yaml PROPERTIES
IMPORTED_LOCATION ${YAML_LIBRARY_PATH}
INTERFACE_INCLUDE_DIRECTORIES ${YAML_INCLUDE_DIR})
add_dependencies(Yaml::Yaml libyaml)

8
cmake/Modules/generate_lmpgitversion.cmake
View File

@ -24,10 +24,10 @@ if(GIT_FOUND AND EXISTS ${LAMMPS_DIR}/.git)
OUTPUT_STRIP_TRAILING_WHITESPACE)
endif()
set(temp "${temp}const bool LAMMPS_NS::LAMMPS::has_git_info = ${temp_git_info};\n")
set(temp "${temp}const char LAMMPS_NS::LAMMPS::git_commit[] = \"${temp_git_commit}\";\n")
set(temp "${temp}const char LAMMPS_NS::LAMMPS::git_branch[] = \"${temp_git_branch}\";\n")
set(temp "${temp}const char LAMMPS_NS::LAMMPS::git_descriptor[] = \"${temp_git_describe}\";\n")
set(temp "${temp}bool LAMMPS_NS::LAMMPS::has_git_info() { return ${temp_git_info}; }\n")
set(temp "${temp}const char *LAMMPS_NS::LAMMPS::git_commit() { return \"${temp_git_commit}\"; }\n")
set(temp "${temp}const char *LAMMPS_NS::LAMMPS::git_branch() { return \"${temp_git_branch}\"; }\n")
set(temp "${temp}const char *LAMMPS_NS::LAMMPS::git_descriptor() { return \"${temp_git_describe}\"; }\n")
set(temp "${temp}#endif\n\n")
message(STATUS "Generating lmpgitversion.h...")

30
cmake/iwyu/iwyu-extra-map.imp
View File

@ -1,7 +1,33 @@
[
{ include: [ "<bits/types/struct_rusage.h>", private, "<sys/resource.h>", public ] },
{ include: [ "<bits/exception.h>", public, "<exception>", public ] },
{ include: [ "@<Eigen/.*>", private, "<Eigen/Eigen>", public ] },
{ include: [ "@<gtest/.*>", private, "\"gtest/gtest.h\"", public ] },
{ include: [ "@<gmock/.*>", private, "\"gmock/gmock.h\"", public ] },
{ include: [ "@<gmock/.*>", private, "\"gmock/gmock.h\"", public ] },
{ include: [ "@<(cell|c_loops|container).hh>", private, "<voro++.hh>", public ] },
{ include: [ "@\"atom_vec_.*.h\"", public, "\"style_atom.h\"", public ] },
{ include: [ "@\"body_.*.h\"", public, "\"style_body.h\"", public ] },
{ include: [ "@\"compute_.*.h\"", public, "\"style_compute.h\"", public ] },
{ include: [ "@\"fix_.*.h\"", public, "\"style_fix.h\"", public ] },
{ include: [ "@\"dump_.*.h\"", public, "\"style_dump.h\"", public ] },
{ include: [ "@\"min_.*.h\"", public, "\"style_minimize.h\"", public ] },
{ include: [ "@\"reader_.*.h\"", public, "\"style_reader.h\"", public ] },
{ include: [ "@\"region_.*.h\"", public, "\"style_region.h\"", public ] },
{ include: [ "@\"pair_.*.h\"", public, "\"style_pair.h\"", public ] },
{ include: [ "@\"angle_.*.h\"", public, "\"style_angle.h\"", public ] },
{ include: [ "@\"bond_.*.h\"", public, "\"style_bond.h\"", public ] },
{ include: [ "@\"dihedral_.*.h\"", public, "\"style_dihedral.h\"", public ] },
{ include: [ "@\"improper_.*.h\"", public, "\"style_improper.h\"", public ] },
{ include: [ "@\"kspace_.*.h\"", public, "\"style_kspace.h\"", public ] },
{ include: [ "@\"nbin_.*.h\"", public, "\"style_nbin.h\"", public ] },
{ include: [ "@\"npair_.*.h\"", public, "\"style_npair.h\"", public ] },
{ include: [ "@\"nstencil_.*.h\"", public, "\"style_nstencil.h\"", public ] },
{ include: [ "@\"ntopo_.*.h\"", public, "\"style_ntopo.h\"", public ] },
{ include: [ "\"fmt/core.h\"", private, "\"fmt/format.h\"", public ] },
{ include: [ "<float.h>", public, "<cfloat>", public ] },
{ include: [ "\"float.h\"", public, "<cfloat>", public ] },
{ include: [ "<limits.h>", public, "<climits>", public ] },
{ include: [ "\"limits.h\"", public, "<climits>", public ] },
{ include: [ "<stdio.h>", public, "<cstdio>", public ] },
{ include: [ "<bits/types/struct_rusage.h>", private, "<sys/types.h>", public ] },
{ include: [ "<bits/types/struct_tm.h>", private, "<ctime>", public ] },
]

6
cmake/presets/gcc.cmake
View File

@ -3,19 +3,19 @@
set(CMAKE_CXX_COMPILER "g++" CACHE STRING "" FORCE)
set(CMAKE_C_COMPILER "gcc" CACHE STRING "" FORCE)
set(CMAKE_Fortran_COMPILER "gfortran" CACHE STRING "" FORCE)
set(CMAKE_CXX_FLAGS_DEBUG "-Wall -g" CACHE STRING "" FORCE)
set(CMAKE_CXX_FLAGS_DEBUG "-Wall -Og -g" CACHE STRING "" FORCE)
set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "-g -O2 -DNDEBUG" CACHE STRING "" FORCE)
set(CMAKE_CXX_FLAGS_RELEASE "-O3 -DNDEBUG" CACHE STRING "" FORCE)
set(MPI_CXX "g++" CACHE STRING "" FORCE)
set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
set(MPI_C "gcc" CACHE STRING "" FORCE)
set(MPI_C_COMPILER "mpicc" CACHE STRING "" FORCE)
set(CMAKE_C_FLAGS_DEBUG "-Wall -g" CACHE STRING "" FORCE)
set(CMAKE_C_FLAGS_DEBUG "-Wall -Og -g" CACHE STRING "" FORCE)
set(CMAKE_C_FLAGS_RELWITHDEBINFO "-g -O2 -DNDEBUG" CACHE STRING "" FORCE)
set(CMAKE_C_FLAGS_RELEASE "-O3 -DNDEBUG" CACHE STRING "" FORCE)
set(MPI_Fortran "gfortran" CACHE STRING "" FORCE)
set(MPI_Fortran_COMPILER "mpifort" CACHE STRING "" FORCE)
set(CMAKE_Fortran_FLAGS_DEBUG "-Wall -g -std=f2003" CACHE STRING "" FORCE)
set(CMAKE_Fortran_FLAGS_DEBUG "-Wall -Og -g -std=f2003" CACHE STRING "" FORCE)
set(CMAKE_Fortran_FLAGS_RELWITHDEBINFO "-g -O2 -DNDEBUG -std=f2003" CACHE STRING "" FORCE)
set(CMAKE_Fortran_FLAGS_RELEASE "-O3 -DNDEBUG -std=f2003" CACHE STRING "" FORCE)
unset(HAVE_OMP_H_INCLUDE CACHE)

30
cmake/presets/hip_amd.cmake Normal file
View File

@ -0,0 +1,30 @@
# preset that will enable hip (clang/clang++) with support for MPI and OpenMP (on Linux boxes)
# prefer flang over gfortran, if available
find_program(CLANG_FORTRAN NAMES flang gfortran f95)
set(ENV{OMPI_FC} ${CLANG_FORTRAN})
set(CMAKE_CXX_COMPILER "hipcc" CACHE STRING "" FORCE)
set(CMAKE_C_COMPILER "hipcc" CACHE STRING "" FORCE)
set(CMAKE_Fortran_COMPILER ${CLANG_FORTRAN} CACHE STRING "" FORCE)
set(CMAKE_CXX_FLAGS_DEBUG "-Wall -Wextra -g" CACHE STRING "" FORCE)
set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "-Wall -Wextra -g -O2 -DNDEBUG" CACHE STRING "" FORCE)
set(CMAKE_CXX_FLAGS_RELEASE "-O3 -DNDEBUG" CACHE STRING "" FORCE)
set(CMAKE_Fortran_FLAGS_DEBUG "-Wall -Wextra -g -std=f2003" CACHE STRING "" FORCE)
set(CMAKE_Fortran_FLAGS_RELWITHDEBINFO "-Wall -Wextra -g -O2 -DNDEBUG -std=f2003" CACHE STRING "" FORCE)
set(CMAKE_Fortran_FLAGS_RELEASE "-O3 -DNDEBUG -std=f2003" CACHE STRING "" FORCE)
set(CMAKE_C_FLAGS_DEBUG "-Wall -Wextra -g" CACHE STRING "" FORCE)
set(CMAKE_C_FLAGS_RELWITHDEBINFO "-Wall -Wextra -g -O2 -DNDEBUG" CACHE STRING "" FORCE)
set(CMAKE_C_FLAGS_RELEASE "-O3 -DNDEBUG" CACHE STRING "" FORCE)
set(MPI_CXX "hipcc" CACHE STRING "" FORCE)
set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
unset(HAVE_OMP_H_INCLUDE CACHE)
set(OpenMP_C "hipcc" CACHE STRING "" FORCE)
set(OpenMP_C_FLAGS "-fopenmp" CACHE STRING "" FORCE)
set(OpenMP_C_LIB_NAMES "omp" CACHE STRING "" FORCE)
set(OpenMP_CXX "hipcc" CACHE STRING "" FORCE)
set(OpenMP_CXX_FLAGS "-fopenmp" CACHE STRING "" FORCE)
set(OpenMP_CXX_LIB_NAMES "omp" CACHE STRING "" FORCE)
set(OpenMP_omp_LIBRARY "libomp.so" CACHE PATH "" FORCE)

2
cmake/presets/most.cmake
View File

@ -24,6 +24,7 @@ set(ALL_PACKAGES
DRUDE
EFF
EXTRA-COMPUTE
EXTRA-DUMP
EXTRA-FIX
EXTRA-MOLECULE
EXTRA-PAIR
@ -47,7 +48,6 @@ set(ALL_PACKAGES
PHONON
PLUGIN
POEMS
PYTHON
QEQ
REACTION
REAXFF

64
cmake/presets/windows.cmake Normal file
View File

@ -0,0 +1,64 @@
set(WIN_PACKAGES
ASPHERE
BOCS
BODY
BROWNIAN
CG-DNA
CG-SDK
CLASS2
COLLOID
COLVARS
CORESHELL
DIELECTRIC
DIFFRACTION
DIPOLE
DPD-BASIC
DPD-MESO
DPD-REACT
DPD-SMOOTH
DRUDE
EFF
EXTRA-COMPUTE
EXTRA-DUMP
EXTRA-FIX
EXTRA-MOLECULE
EXTRA-PAIR
FEP
GRANULAR
INTERLAYER
KSPACE
MANIFOLD
MANYBODY
MC
MEAM
MISC
ML-IAP
ML-SNAP
MOFFF
MOLECULE
MOLFILE
OPENMP
ORIENT
PERI
PHONON
POEMS
PTM
QEQ
QTB
REACTION
REAXFF
REPLICA
RIGID
SHOCK
SMTBQ
SPH
SPIN
SRD
TALLY
UEF
YAFF)
foreach(PKG ${WIN_PACKAGES})
set(PKG_${PKG} ON CACHE BOOL "" FORCE)
endforeach()

2
doc/Makefile
View File

@ -230,7 +230,7 @@ $(VENV):
)
$(MATHJAX):
@git clone -b 3.2.0 -c advice.detachedHead=0 --depth 1 git://github.com/mathjax/MathJax.git $@
@git clone -b 3.2.0 -c advice.detachedHead=0 --depth 1 https://github.com/mathjax/MathJax.git $@
$(ANCHORCHECK): $(VENV)
@( \

2
doc/doxygen/Doxyfile.in
View File

@ -435,6 +435,8 @@ INPUT = @LAMMPS_SOURCE_DIR@/utils.cpp \
@LAMMPS_SOURCE_DIR@/my_pool_chunk.cpp \
@LAMMPS_SOURCE_DIR@/my_pool_chunk.h \
@LAMMPS_SOURCE_DIR@/math_eigen.h \
@LAMMPS_SOURCE_DIR@/platform.h \
@LAMMPS_SOURCE_DIR@/platform.cpp \
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded

141
doc/github-development-workflow.md
View File

@ -6,7 +6,7 @@ choices the LAMMPS developers have agreed on. Git and GitHub provide the
tools, but do not set policies, so it is up to the developers to come to
an agreement as to how to define and interpret policies. This document
is likely to change as our experiences and needs change and we try to
adapt accordingly. Last change 2018-12-19.
adapt accordingly. Last change 2021-09-02.
## Table of Contents
@ -23,19 +23,19 @@ adapt accordingly. Last change 2018-12-19.
In the interest of consistency, ONLY ONE of the core LAMMPS developers
should doing the merging itself. This is currently
[@akohlmey](https://github.com/akohlmey) (Axel Kohlmeyer).
If this assignment needs to be changed, it shall be done right after a
stable release. If the currently assigned developer cannot merge outstanding pull
requests in a timely manner, or in other extenuating circumstances,
[@akohlmey](https://github.com/akohlmey) (Axel Kohlmeyer). If this
assignment needs to be changed, it shall be done right after a stable
release. If the currently assigned developer cannot merge outstanding
pull requests in a timely manner, or in other extenuating circumstances,
other core LAMMPS developers with merge rights can merge pull requests,
when necessary.
## Pull Requests
ALL changes to the LAMMPS code and documentation, however trivial, MUST
be submitted as a pull request to GitHub. All changes to the "master"
be submitted as a pull request to GitHub. All changes to the "develop"
branch must be made exclusively through merging pull requests. The
"unstable" and "stable" branches, respectively are only to be updated
"release" and "stable" branches, respectively are only to be updated
upon patch or stable releases with fast-forward merges based on the
associated tags. Pull requests may also be submitted to (long-running)
feature branches created by LAMMPS developers inside the LAMMPS project,
@ -55,13 +55,14 @@ the required changes or ask the submitter of the pull request to implement
them. Even though, all LAMMPS developers may have write access to pull
requests (if enabled by the submitter, which is the default), only the
submitter or the assignee of a pull request may do so. During this
period the `work_in_progress` label shall be applied to the pull
period the `work_in_progress` label may be applied to the pull
request. The assignee gets to decide what happens to the pull request
next, e.g. whether it should be assigned to a different developer for
additional checks and changes, or is recommended to be merged. Removing
the `work_in_progress` label and assigning the pull request to the
developer tasked with merging signals that a pull request is ready to be
merged.
merged. In addition, a `ready_for_merge` label may also be assigned
to signal urgency to merge this pull request quickly.
### Pull Request Reviews
@ -97,108 +98,50 @@ rationale behind choices made. Exceptions to this policy are technical
discussions, that are centered on tools or policies themselves
(git, GitHub, c++) rather than on the content of the pull request.
### Checklist for Pull Requests
Here are some items to check:
* source and text files should not have CR/LF line endings (use dos2unix to remove)
* every new command or style should have documentation. The names of
source files (c++ and manual) should follow the name of the style.
(example: `src/fix_nve.cpp`, `src/fix_nve.h` for `fix nve` command,
implementing the class `FixNVE`, documented in `doc/src/fix_nve.rst`)
* all new style names should be lower case, the must be no dashes,
blanks, or underscores separating words, only forward slashes.
* new style docs should be added to the "overview" files in
`doc/src/Commands_*.rst`, `doc/src/{fixes,computes,pairs,bonds,...}.rst`
* check whether manual cleanly translates with `make html` and `make pdf`
* if documentation is (still) provided as a .txt file, convert to .rst
and remove the .txt file. For files in doc/txt the conversion is automatic.
* remove all .txt files in `doc/txt` that are out of sync with their .rst counterparts in `doc/src`
* check spelling of manual with `make spelling` in doc folder
* check style tables and command lists with `make style_check`
* new source files in packages should be added to `src/.gitignore`
* removed or renamed files in packages should be added to `src/Purge.list`
* C++ source files should use C++ style include files for accessing
C-library APIs, e.g. `#include <cstdlib>` instead of `#include <stdlib.h>`.
And they should use angular brackets instead of double quotes. Full list:
* assert.h -> cassert
* ctype.h -> cctype
* errno.h -> cerrno
* float.h -> cfloat
* limits.h -> climits
* math.h -> cmath
* complex.h -> complex
* setjmp.h -> csetjmp
* signal.h -> csignal
* stddef.h -> cstddef
* stdint.h -> cstdint
* stdio.h -> cstdio
* stdlib.h -> cstdlib
* string.h -> cstring
* time.h -> ctime
* Do NOT replace (as they are C++-11): `inttypes.h` and `stdint.h`.
* Code must follow the C++-11 standard. C++98-only is no longer accepted
* Code should use `nullptr` instead of `NULL` where applicable.
in individual special purpose packages
* indentation is 2 spaces per level
* there should be NO tabs and no trailing whitespace (review the "checkstyle" test on pull requests)
* header files, especially of new styles, should not include any
other headers, except the header with the base class or cstdio.
Forward declarations should be used instead when possible.
* iostreams should be avoided. LAMMPS uses stdio from the C-library.
* use of STL in headers and class definitions should be avoided.
exception is <string>, but it won't need to be explicitly included
since pointers.h already includes it. so std::string can be used directly.
* there MUST NOT be any "using namespace XXX;" statements in headers.
* static class members should be avoided at all cost.
* anything storing atom IDs should be using `tagint` and not `int`.
This can be flagged by the compiler only for pointers and only when
compiling LAMMPS with `-DLAMMPS_BIGBIG`.
* when including both `lmptype.h` (and using defines or macros from it)
and `mpi.h`, `lmptype.h` must be included first.
* see https://github.com/lammps/lammps/blob/master/doc/include-file-conventions.md
for general include file conventions and best practices
* when pair styles are added, check if settings for flags like
`single_enable`, `writedata`, `reinitflag`, `manybody_flag`
and others are correctly set and supported.
## GitHub Issues
The GitHub issue tracker is the location where the LAMMPS developers
and other contributors or LAMMPS users can report issues or bugs with
the LAMMPS code or request new features to be added. Feature requests
are usually indicated by a `[Feature Request]` marker in the subject.
Issues are assigned to a person, if this person is working on this
feature or working to resolve an issue. Issues that have nobody working
on them at the moment, have the label `volunteer needed` attached.
the LAMMPS code or request new features to be added. Bug reports have
a `[Bug]` marker in the subject line; suggestions for changes or
adding new functionality are indicated by a `[Feature Request]`
marker in the subject. This is automatically done when using the
corresponding template for submitting an issue. Issues may be assigned
to one or more developers, if they are working on this feature or
working to resolve an issue. Issues that have nobody working
on them at the moment or in the near future, have the label
`volunteer needed` attached.
When an issue, say `#125` is resolved by a specific pull request,
the comment for the pull request shall contain the text `closes #125`
or `fixes #125`, so that the issue is automatically deleted when
the pull request is merged.
the pull request is merged. The template for pull requests includes
a header where connections between pull requests and issues can be listed
and thus were this comment should be placed.
## Milestones and Release Planning
LAMMPS uses a continuous release development model with incremental
changes, i.e. significant effort is made - including automated pre-merge
testing - that the code in the branch "master" does not get broken.
More extensive testing (including regression testing) is performed after
code is merged to the "master" branch. There are patch releases of
LAMMPS every 1-3 weeks at a point, when the LAMMPS developers feel, that
a sufficient amount of changes have happened, and the post-merge testing
has been successful. These patch releases are marked with a
`patch_<version date>` tag and the "unstable" branch follows only these
versions (and thus is always supposed to be of production quality,
unlike "master", which may be temporary broken, in the case of larger
change sets or unexpected incompatibilities or side effects.
testing - that the code in the branch "develop" does not get easily
broken. These tests are run after every update to a pull request. More
extensive and time consuming tests (including regression testing) are
performed after code is merged to the "develop" branch. There are patch
releases of LAMMPS every 3-5 weeks at a point, when the LAMMPS
developers feel, that a sufficient amount of changes have happened, and
the post-merge testing has been successful. These patch releases are
marked with a `patch_<version date>` tag and the "release" branch
follows only these versions (and thus is always supposed to be of
production quality, unlike "develop", which may be temporary broken, in
the case of larger change sets or unexpected incompatibilities or side
effects.
About 3-4 times each year, there are going to be "stable" releases
of LAMMPS. These have seen additional, manual testing and review of
About 1-2 times each year, there are going to be "stable" releases of
LAMMPS. These have seen additional, manual testing and review of
results from testing with instrumented code and static code analysis.
Also, in the last 2-3 patch releases before a stable release are
"release candidate" versions which only contain bugfixes and
documentation updates. For release planning and the information of
code contributors, issues and pull requests being actively worked on
are assigned a "milestone", which corresponds to the next stable
release or the stable release after that, with a tentative release
date.
Also, the last 1-3 patch releases before a stable release are "release
candidate" versions which only contain bugfixes and documentation
updates. For release planning and the information of code contributors,
issues and pull requests being actively worked on are assigned a
"milestone", which corresponds to the next stable release or the stable
release after that, with a tentative release date.

128
doc/include-file-conventions.md
View File

@ -1,128 +0,0 @@
# Outline of include file conventions in LAMMPS
This purpose of this document is to provide a point of reference
for LAMMPS developers and contributors as to what include files
and definitions to put where into LAMMPS source.
Last change 2020-08-31
## Table of Contents
* [Motivation](#motivation)
* [Rules](#rules)
* [Tools](#tools)
* [Legacy Code](#legacy-code)
## Motivation
The conventions outlined in this document are supposed to help make
maintenance of the LAMMPS software easier. By trying to achieve
consistency across files contributed by different developers, it will
become easier for the code maintainers to modify and adjust files and,
overall, the chance for errors or portability issues will be reduced.
The rules employed are supposed to minimize naming conflicts and
simplify dependencies between files and thus speed up compilation. They
may, as well, make otherwise hidden dependencies visible.
## Rules
Below are the various rules that are applied. Not all are enforced
strictly and automatically. If there are no significant side effects,
exceptions may be possible for cases where a full compliance to the
rules may require a large effort compared to the benefit.
### Core Files Versus Package Files
All rules listed below are most strictly observed for core LAMMPS files,
which are the files that are not part of a package, and the files of the
packages MOLECULE, MANYBODY, KSPACE, and RIGID. On the other end of
the spectrum are USER packages and legacy packages that predate these
rules and thus may not be fully compliant. Also, new contributions
will be checked more closely, while existing code will be incrementally
adapted to the rules as time and required effort permits.
### System Versus Local Header Files
All system- or library-provided include files are included with angular
brackets (examples: `#include <cstring>` or `#include <mpi.h>`) while
include files provided with LAMMPS are included with double quotes
(examples: `#include "pointers.h"` or `#include "compute_temp.h"`).
For headers declaring functions of the C-library, the corresponding
C++ versions should be included (examples: `#include <cstdlib>` or
`#include <cctypes>` instead of `#include <stdlib.h>` or
`#include<ctypes.h>` ).
### C++ Standard Compliance
LAMMPS core files use standard conforming C++ compatible with the
C++11 standard, unless explicitly noted. Also, LAMMPS uses the C-style
stdio library for I/O instead of iostreams. Since using both at the
same time can cause problems, iostreams should be avoided where possible.
### Lean Header Files
Header files will typically contain the definition of a (single) class.
These header files should have as few include statements as possible.
This is particularly important for classes that implement a "style" and
thus use a macro of the kind `SomeStyle(some/name,SomeName)`. These will
all be included in the auto-generated `"some_style.h"` files which
results in a high potential for direct or indirect symbol name clashes.
In the ideal case, the header would only include one file defining the
parent class. That would typically be either `#include "pointers.h"` for
the `Pointers` class, or a header of a class derived from it like
`#include "pair.h"` for the `Pair` class and so on. References to other
classes inside the class should be make through pointers, for which forward
declarations (inside the `LAMMPS_NS` or the new class' namespace) can
be employed. The full definition will then be included into the corresponding
implementation file. In the given example from above, the header file
would be called `some_name.h` and the implementation `some_name.cpp` (all
lower case with underscores, while the class itself would be in camel case
and no underscores `SomeName`, and the style name with lower case names separated by
a forward slash).
### Implementation Files
In the implementation files (typically, those would have the same base name
as the corresponding header with a .cpp extension instead of .h) include
statements should follow the "include what you use" principle.
### Order of Include Statements
Include files should be included in this order:
* the header matching the implementation (`some_class.h` for file `some_class.cpp`)
* mpi.h (only if needed)
* LAMMPS local headers (preferably in alphabetical order)
* system and library headers (anything that is using angular brackets; preferably in alphabetical order)
* conditional include statements (i.e. anything bracketed with ifdefs)
### Special Cases and Exceptions
#### pointers.h
The `pointer.h` header file also includes (in this order) `lmptype.h`,
`mpi.h`, `cstddef`, `cstdio`, `string`, `utils.h`, and `fmt/format.h`
and through `lmptype.h` indirectly also `climits`, `cstdlib`, `cinttypes`.
This means any header including `pointers.h` can assume that `FILE`,
`NULL`, `INT_MAX` are defined, and the may freely use the std::string
for arguments. Corresponding implementation files do not need to include
those headers.
## Tools
The [Include What You Use tool](https://include-what-you-use.org/)
can be used to provide supporting information about compliance with
the rules listed here. Through setting `-DENABLE_IWYU=on` when running
CMake, a custom build target is added that will enable recording
the compilation commands and then run the `iwyu_tool` using the
recorded compilation commands information when typing `make iwyu`.
## Legacy Code
A lot of code predates the application of the rules in this document
and the rules themselves are a moving target. So there are going to be
significant chunks of code that do not fully comply. This applies
for example to the REAXFF, or the ATC package. The LAMMPS
developers are dedicated to make an effort to improve the compliance
and welcome volunteers wanting to help with the process.

55
doc/lammps.1
View File

@ -1,4 +1,4 @@
.TH LAMMPS "31 August 2021" "2021-08-31"
.TH LAMMPS "1" "17 February 2022" "2022-2-17"
.SH NAME
.B LAMMPS
\- Molecular Dynamics Simulator.
@ -54,7 +54,7 @@ using
this <machine name> parameter can be chosen arbitrarily at configuration
time, but more common is to just use
.B lmp
without a suffix. In this manpage we will use
without a suffix. In this man page we will use
.B lmp
to represent any of those names.
@ -94,7 +94,7 @@ Enable or disable general KOKKOS support, as provided by the KOKKOS
package. Even if LAMMPS is built with this package, this switch must
be set to \fBon\fR to enable running with KOKKOS-enabled styles. More
details on this switch and its optional keyword value pairs are discussed
at: https://lammps.sandia.gov/doc/Run_options.html
at: https://docs.lammps.org/Run_options.html
.TP
\fB\-l <log file>\fR or \fB\-log <log file>\fR
Specify a log file for LAMMPS to write status information to.
@ -122,6 +122,38 @@ to perform client/server messaging with another application.
.B LAMMPS
can act as either a client or server (or both).
.TP
\fB\-mdi '<mdi_flags>'\fR
This flag is only recognized and used when
.B LAMMPS
has support for the MolSSI
Driver Interface (MDI) included as part of the MDI package. This flag is
specific to the MDI library and controls how
.B LAMMPS
interacts with MDI. There are usually multiple flags that have to follow it
and those have to be placed in quotation marks. For more information about
how to launch LAMMPS in MDI client/server mode please refer to the
MDI How-to at https://docs.lammps.org/Howto_mdi.html
.TP
\fB\-c\fR or \fB\-cite <style or filename>\fR
Select how and where to output a reminder about citing contributions
to the
.B LAMMPS
code that were used during the run. Available keywords
for styles are "both", "none", "screen", or "log". Any other keyword
will be considered a file name to write the detailed citation info to
instead of logfile or screen. Default is the "log" style where there
is a short summary in the screen output and detailed citations
in BibTeX format in the logfile. The option "both" selects the detailed
output for both, "none", the short output for both, and "screen" will
write the detailed info to the screen and the short version to the log
file. If a dedicated citation info file is requested, the screen and
log file output will be in the short format (same as with "none").
See https://docs.lammps.org/Intro_citing.html for more details on
how to correctly reference and cite
.B LAMMPS
.
.TP
\fB\-nc\fR or \fB\-nocite\fR
Disable writing the "log.cite" file which is normally written to
list references for specific cite-able features used during a
@ -202,7 +234,7 @@ the standard output. If <file name> is "none", (most) screen
output will be suppressed. In multi-partition mode only
some high-level all-partition information is written to the
screen or "<file name>" file, the remainder is written in a
per-partition file "screen.N" or "<file name>.N"
per-partition file "screen.N" or "<file name>.N"
with "N" being the respective partition number, and unless
overridden by the \-pscreen flag (see above).
.TP
@ -218,8 +250,19 @@ and then "omp") and thus requires two arguments. Along with the
"-package" command-line switch, this is a convenient mechanism for
invoking styles from accelerator packages and setting their options
without having to edit an input script.
.TP
\fB\-sr\fR or \fB\-skiprun\fR
Insert the command "timer timeout 0 every 1" at the
beginning of an input file or after a "clear" command.
This has the effect that the entire
.B LAMMPS
input script is processed without executing actual
"run" or "minimize" or similar commands (their main loops are skipped).
This can be helpful and convenient to test input scripts of long running
calculations for correctness to avoid having them crash after a
long time due to a typo or syntax error in the middle or at the end.
See https://lammps.sandia.gov/doc/Run_options.html for additional
See https://docs.lammps.org/Run_options.html for additional
details and discussions on command-line options.
.SH LAMMPS BASICS
@ -254,7 +297,7 @@ the chapter on errors in the
manual gives some additional information about error messages, if possible.
.SH COPYRIGHT
© 2003--2020 Sandia Corporation
© 2003--2021 Sandia Corporation
This package is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as

4
doc/msi2lmp.1
View File

@ -1,4 +1,4 @@
.TH MSI2LMP "v3.9.9" "2018-11-05"
.TH MSI2LMP "1" "v3.9.9" "2018-11-05"
.SH NAME
.B MSI2LMP
\- Converter for Materials Studio files to LAMMPS
@ -98,7 +98,7 @@ msi2lmp decane -c 0 -f oplsaa
.SH COPYRIGHT
© 2003--2019 Sandia Corporation
© 2003--2021 Sandia Corporation
This package is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as

5
doc/src/Bibliography.rst
View File

@ -1123,9 +1123,12 @@ Bibliography
**(Sun)**
Sun, J. Phys. Chem. B, 102, 7338-7364 (1998).
**(Surblys)**
**(Surblys2019)**
Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019).
**(Surblys2021)**
Surblys, Matsubara, Kikugawa, Ohara, J Appl Phys 130, 215104 (2021).
**(Sutmann)**
Sutmann, Arnold, Fahrenberger, et. al., Physical review / E 88(6), 063308 (2013)

36
doc/src/Build_cmake.rst
View File

@ -150,6 +150,42 @@ for IDEs like Eclipse, CodeBlocks, or Kate can be selected using the *-G*
command line flag. A list of available generator settings for your
specific CMake version is given when running ``cmake --help``.
.. _cmake_multiconfig:
Multi-configuration build systems
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Throughout this manual it is mostly assumed that LAMMPS is being built
on a Unix-like operating system with "make" as the underlying "builder",
since this is the most common case. In this case the build "configuration"
is chose using ``-D CMAKE_BUILD_TYPE=<configuration>`` with ``<configuration>``
being one of "Release", "Debug", "RelWithDebInfo", or "MinSizeRel".
Some build tools, however, can also use or even require to have a so-called
multi-configuration build system setup. For those the built type (or
configuration) is chosen at compile time using the same build files. E.g.
with:
.. code-block:: bash
cmake --build build-multi --config Release
In that case the resulting binaries are not in the build folder directly
but in sub-directories corresponding to the build type (i.e. Release in
the example from above). Similarly, for running unit tests the
configuration is selected with the *-C* flag:
.. code-block:: bash
ctest -C Debug
The CMake scripts in LAMMPS have basic support for being compiled using a
multi-config build system, but not all of it has been ported. This is in
particular applicable to compiling packages that require additional libraries
that would be downloaded and compiled by CMake. The "windows" preset file
tries to keep track of which packages can be compiled natively with the
MSVC compilers out-of-the box. Not all of those external libraries are
portable to Windows either.
Installing CMake
^^^^^^^^^^^^^^^^

26
doc/src/Build_development.rst
View File

@ -56,16 +56,18 @@ Report missing and unneeded '#include' statements (CMake only)
--------------------------------------------------------------
The conventions for how and when to use and order include statements in
LAMMPS are `documented in a separate file <https://github.com/lammps/lammps/blob/master/doc/include-file-conventions.md>`_
(also included in the source code distribution). To assist with following
LAMMPS are documented in :doc:`Modify_style`. To assist with following
these conventions one can use the `Include What You Use tool <https://include-what-you-use.org/>`_.
This is still under development and for large and complex projects like LAMMPS
This tool is still under development and for large and complex projects like LAMMPS
there are some false positives, so suggested changes need to be verified manually.
It is recommended to use at least version 0.14, which has much fewer incorrect
reports than earlier versions.
It is recommended to use at least version 0.16, which has much fewer incorrect
reports than earlier versions. To install the IWYU toolkit, you need to have
the clang compiler **and** its development package installed. Download the IWYU
version that matches the version of the clang compiler, configure, build, and
install it.
The necessary steps to generate the report can be enabled via a
CMake variable:
The necessary steps to generate the report can be enabled via a CMake variable
during CMake configuration.
.. code-block:: bash
@ -183,6 +185,10 @@ The ``ctest`` command has many options, the most important ones are:
- run subset of tests matching the regular expression <regex>
* - -E <regex>
- exclude subset of tests matching the regular expression <regex>
* - -L <regex>
- run subset of tests with a label matching the regular expression <regex>
* - -LE <regex>
- exclude subset of tests with a label matching the regular expression <regex>
* - -N
- dry-run: display list of tests without running them
* - -T memcheck
@ -297,6 +303,12 @@ 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.
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"
and/or "unstable" label, and thus those tests can be selectively
excluded with the ``-LE`` flag or selected with the ``-L`` flag.
.. admonition:: Recommendations and notes for YAML files
:class: note

2
doc/src/Build_diskspace.rst
View File

@ -14,7 +14,7 @@ environments with restricted disk space capacity it may be needed to
reduce the storage requirements. Here are some suggestions:
- Create a so-called shallow repository by cloning only the last commit
instead of the full project history by using ``git clone git@github.com:lammps/lammps --depth=1 --branch=master``.
instead of the full project history by using ``git clone git@github.com:lammps/lammps --depth=1 --branch=develop``.
This reduces the downloaded size to about half. With ``--depth=1`` it is not possible to check out different
versions/branches of LAMMPS, using ``--depth=1000`` will make multiple recent versions available at little
extra storage needs (the entire git history had nearly 30,000 commits in fall 2021).

33
doc/src/Build_extras.rst
View File

@ -341,6 +341,18 @@ minutes to hours) to build. Of course you only need to do that once.)
$ make lib-kim args="-p /usr/local" # use an existing KIM API installation at the provided location
$ make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver
When using the "-b " option, the KIM library is built using its native
cmake build system. The ``lib/kim/Install.py`` script supports a
``CMAKE`` environment variable if the cmake executable is named other
than ``cmake`` on your system. Additional environment variables may be
provided on the command line for use by cmake. For example, to use the
``cmake3`` executable and tell it to use the gnu version 11 compilers
to build KIM, one could use the following command line.
.. code-block:: bash
$ CMAKE=cmake3 CXX=g++-11 CC=gcc-11 FC=gfortran-11 make lib-kim args="-b " # (re-)install KIM API lib using cmake3 and gnu v11 compilers with only example models
Settings for debugging OpenKIM web queries discussed below need to
be applied by adding them to the ``LMP_INC`` variable through
editing the ``Makefile.machine`` you are using. For example:
@ -560,11 +572,26 @@ They must be specified in uppercase.
* - VEGA908
- GPU
- AMD GPU MI100 GFX908
* - INTEL_GEN
* - VEGA90A
- GPU
- Intel GPUs Gen9+
- AMD GPU
* - INTEL_DG1
- GPU
- Intel Iris XeMAX GPU
* - INTEL_GEN9
- GPU
- Intel GPU Gen9
* - INTEL_GEN11
- GPU
- Intel GPU Gen11
* - INTEL_GEN12LP
- GPU
- Intel GPU Gen12LP
* - INTEL_XEHP
- GPU
- Intel GPUs Xe-HP
This list was last updated for version 3.4.1 of the Kokkos library.
This list was last updated for version 3.5.0 of the Kokkos library.
.. tabs::

20
doc/src/Build_manual.rst
View File

@ -22,7 +22,6 @@ files. Here is a list with descriptions:
.gitignore # list of files and folders to be ignored by git
doxygen-warn.log # logfile with warnings from running doxygen
github-development-workflow.md # notes on the LAMMPS development workflow
include-file-conventions.md # notes on LAMMPS' include file conventions
If you downloaded LAMMPS as a tarball from `the LAMMPS website <lws_>`_,
the html folder and the PDF files should be included.
@ -34,12 +33,15 @@ various tools and files. Some of them have to be installed (see below). For
the rest the build process will attempt to download and install them into
a python virtual environment and local folders.
A current version of the manual (latest patch release, aka unstable
branch) is is available online at:
`https://docs.lammps.org/Manual.html <https://docs.lammps.org/Manual.html>`_.
A version of the manual corresponding to the ongoing development (aka master branch)
is available online at: `https://docs.lammps.org/latest/
<https://docs.lammps.org/latest/>`_
A current version of the manual (latest patch release, that is the state
of the *release* branch) is is available online at:
`https://docs.lammps.org/ <https://docs.lammps.org/>`_.
A version of the manual corresponding to the ongoing development (that is
the state of the *develop* branch) is available online at:
`https://docs.lammps.org/latest/ <https://docs.lammps.org/latest/>`_
A version of the manual corresponding to the latest stable LAMMPS release
(that is the state of the *stable* branch) is available online at:
`https://docs.lammps.org/stable/ <https://docs.lammps.org/stable/>`_
Build using GNU make
--------------------
@ -75,8 +77,8 @@ folder. The following ``make`` commands are available:
.. code-block:: bash
make html # generate HTML in html dir using Sphinx
make pdf # generate PDF as Manual.pdf using Sphinx and pdflatex
make fetch # fetch HTML pages and PDF files from LAMMPS web site
make pdf # generate PDF as Manual.pdf using Sphinx and PDFLaTeX
make fetch # fetch HTML pages and PDF files from LAMMPS website
# and unpack into the html_www folder and Manual_www.pdf
make epub # generate LAMMPS.epub in ePUB format using Sphinx
make mobi # generate LAMMPS.mobi in MOBI format using ebook-convert

53
doc/src/Build_settings.rst
View File

@ -4,15 +4,15 @@ Optional build settings
LAMMPS can be built with several optional settings. Each sub-section
explain how to do this for building both with CMake and make.
* :ref:`C++11 standard compliance <cxx11>` when building all of LAMMPS
* :ref:`FFT library <fft>` for use with the :doc:`kspace_style pppm <kspace_style>` command
* :ref:`Size of LAMMPS integer types <size>`
* :ref:`Read or write compressed files <gzip>`
* :ref:`Output of JPG and PNG files <graphics>` via the :doc:`dump image <dump_image>` command
* :ref:`Output of movie files <graphics>` via the :doc:`dump_movie <dump_image>` command
* :ref:`Memory allocation alignment <align>`
* :ref:`Workaround for long long integers <longlong>`
* :ref:`Error handling exceptions <exceptions>` when using LAMMPS as a library
* `C++11 standard compliance`_ when building all of LAMMPS
* `FFT library`_ for use with the :doc:`kspace_style pppm <kspace_style>` command
* `Size of LAMMPS integer types and size limits`_
* `Read or write compressed files`_
* `Output of JPG, PNG, and move files` via the :doc:`dump image <dump_image>` or :doc:`dump movie <dump_image>` commands
* `Memory allocation alignment`_
* `Workaround for long long integers`_
* `Exception handling when using LAMMPS as a library`_ to capture errors
* `Trigger selected floating-point exceptions`_
----------
@ -71,7 +71,8 @@ LAMMPS can use them if they are available on your system.
-D FFTW3_INCLUDE_DIR=path # path to FFTW3 include files
-D FFTW3_LIBRARY=path # path to FFTW3 libraries
-D FFT_FFTW_THREADS=on # enable using threaded FFTW3 libraries
-D FFTW3_OMP_LIBRARY=path # path to FFTW3 OpenMP wrapper libraries
-D FFT_FFTW_THREADS=on # enable using OpenMP threaded FFTW3 libraries
-D MKL_INCLUDE_DIR=path # ditto for Intel MKL library
-D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries
-D MKL_LIBRARY=path # path to MKL libraries
@ -320,9 +321,7 @@ following settings:
.. code-block:: make
LMP_INC = -DLAMMPS_JPEG
LMP_INC = -DLAMMPS_PNG
LMP_INC = -DLAMMPS_FFMPEG
LMP_INC = -DLAMMPS_JPEG -DLAMMPS_PNG -DLAMMPS_FFMPEG <other LMP_INC settings>
JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header files if make cannot find them
JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them
@ -353,8 +352,10 @@ Read or write compressed files
-----------------------------------------
If this option is enabled, large files can be read or written with
gzip compression by several LAMMPS commands, including
:doc:`read_data <read_data>`, :doc:`rerun <rerun>`, and :doc:`dump <dump>`.
compression by ``gzip`` or similar tools by several LAMMPS commands,
including :doc:`read_data <read_data>`, :doc:`rerun <rerun>`, and
:doc:`dump <dump>`. Currently supported compression tools are:
``gzip``, ``bzip2``, ``zstd``, and ``lzma``.
.. tabs::
@ -363,23 +364,23 @@ gzip compression by several LAMMPS commands, including
.. code-block:: bash
-D WITH_GZIP=value # yes or no
# default is yes if CMake can find gzip, else no
-D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it
# default is yes if CMake can find the gzip program, else no
.. tab:: Traditional make
.. code-block:: make
LMP_INC = -DLAMMPS_GZIP
LMP_INC = -DLAMMPS_GZIP <other LMP_INC settings>
This option requires that your operating system fully supports the "popen()"
function in the standard runtime library and that a ``gzip`` executable can be
found by LAMMPS during a run.
This option requires that your operating system fully supports the
"popen()" function in the standard runtime library and that a ``gzip``
or other executable can be found by LAMMPS in the standard search path
during a run.
.. note::
On some clusters with high-speed networks, using the "fork()" library
call (required by "popen()") can interfere with the fast communication
On clusters with high-speed networks, using the "fork()" library call
(required by "popen()") can interfere with the fast communication
library and lead to simulations using compressed output or input to
hang or crash. For selected operations, compressed file I/O is also
available using a compression library instead, which is what the
@ -451,7 +452,7 @@ those systems:
.. code-block:: make
LMP_INC = -DLAMMPS_LONGLONG_TO_LONG
LMP_INC = -DLAMMPS_LONGLONG_TO_LONG <other LMP_INC settings>
----------
@ -478,7 +479,7 @@ e.g. to Python. Of course, the calling code has to be set up to
.. code-block:: make
LMP_INC = -DLAMMPS_EXCEPTIONS
LMP_INC = -DLAMMPS_EXCEPTIONS <other LMP_INC settings>
.. note::
@ -519,7 +520,7 @@ executable, not the library.
.. code-block:: make
LMP_INC = -DLAMMPS_TRAP_FPE
LMP_INC = -DLAMMPS_TRAP_FPE <other LMP_INC settings>
After compilation with this flag set, the LAMMPS executable will stop
and produce a core dump when a division by zero, overflow, illegal math

101
doc/src/Build_windows.rst
View File

@ -4,6 +4,7 @@ Notes for building LAMMPS on Windows
* :ref:`General remarks <generic>`
* :ref:`Running Linux on Windows <linux>`
* :ref:`Using GNU GCC ported to Windows <gnu>`
* :ref:`Using Visual Studio <msvc>`
* :ref:`Using a cross-compiler <cross>`
----------
@ -15,44 +16,52 @@ General remarks
LAMMPS is developed and tested primarily on Linux machines. The vast
majority of HPC clusters and supercomputers today run on Linux as well.
While portability to other platforms is desired, it is not always achieved.
The LAMMPS developers are dependent on LAMMPS users giving feedback and
providing assistance in resolving portability issues. This is particularly
true for compiling LAMMPS on Windows, since this platform has significant
differences in some low-level functionality.
While portability to other platforms is desired, it is not always
achieved. That is sometimes due to non-portable code in LAMMPS itself,
but more often due to portability limitations of external libraries and
tools required to build a specific feature or package. The LAMMPS
developers are dependent on LAMMPS users giving feedback and providing
assistance in resolving portability issues. This is particularly true
for compiling LAMMPS on Windows, since this platform has significant
differences in some low-level functionality. As of LAMMPS version 14
December 2021, large parts of LAMMPS can be compiled natively with the
Microsoft Visual C++ Compilers. This is largely facilitated by using
the :doc:`Developer_platform` in the ``platform`` namespace.
Before trying to build LAMMPS on Windows yourself, please consider the
`pre-compiled Windows installer packages <https://packages.lammps.org/windows.html>`_
and see if they are sufficient for your needs.
.. _linux:
Running Linux on Windows
^^^^^^^^^^^^^^^^^^^^^^^^
Before trying to build LAMMPS on Windows, please consider if the
pre-compiled Windows binary packages are sufficient for your needs. If
it is necessary for you to compile LAMMPS on a Windows machine
If it is necessary for you to compile LAMMPS on a Windows machine
(e.g. because it is your main desktop), please also consider using a
virtual machine software and compile and run LAMMPS in a Linux virtual
machine, or - if you have a sufficiently up-to-date Windows 10
installation - consider using the Windows subsystem for Linux. This
optional Windows feature allows you to run the bash shell from Ubuntu
from within Windows and from there on, you can pretty much use that
shell like you are running on an Ubuntu Linux machine (e.g. installing
software via apt-get and more). For more details on that, please see
:doc:`this tutorial <Howto_wsl>`.
machine, or - if you have a sufficiently up-to-date Windows 10 or
Windows 11 installation - consider using the Windows subsystem for
Linux. This optional Windows feature allows you to run the bash shell
of a Linux system (Ubuntu by default) from within Windows and from there
on, you can pretty much use that shell like you are running on a regular
Ubuntu Linux machine (e.g. installing software via apt-get and more).
For more details on that, please see :doc:`this tutorial <Howto_wsl>`.
.. _gnu:
Using a GNU GCC ported to Windows
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
One option for compiling LAMMPS on Windows natively that has been known
to work in the past is to install a bash shell, unix shell utilities,
perl, GNU make, and a GNU compiler ported to Windows. The Cygwin
package provides a unix/linux interface to low-level Windows functions,
so LAMMPS can be compiled on Windows. The necessary (minor)
modifications to LAMMPS are included, but may not always up-to-date for
recently added functionality and the corresponding new code. A machine
makefile for using cygwin for the old build system is provided. Using
CMake for this mode of compilation is untested and not likely to work.
One option for compiling LAMMPS on Windows natively is to install a Bash
shell, Unix shell utilities, Perl, Python, GNU make, and a GNU compiler
ported to Windows. The Cygwin package provides a unix/linux interface
to low-level Windows functions, so LAMMPS can be compiled on Windows.
The necessary (minor) modifications to LAMMPS are included, but may not
always up-to-date for recently added functionality and the corresponding
new code. A machine makefile for using cygwin for the old build system
is provided. Using CMake for this mode of compilation is untested and
not likely to work.
When compiling for Windows do **not** set the ``-DLAMMPS_MEMALIGN``
define in the LMP_INC makefile variable and add ``-lwsock32 -lpsapi`` to
@ -67,6 +76,50 @@ requiring changes to the LAMMPS source code, or figure out corrections
yourself, please report them on the lammps-users mailing list, or file
them as an issue or pull request on the LAMMPS GitHub project.
.. _msvc:
Using Microsoft Visual Studio
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Following the integration of the :doc:`platform namespace
<Developer_platform>` into the LAMMPS code base, portability of LAMMPS
for native compilation on Windows using Visual Studio has been
significantly improved. This has been tested with Visual Studio 2019
(aka version 16) and Visual Studio 2022 (aka version 17). We strongly
recommend using Visual Studio 2022 version 17.1 or later. Not all
features and packages in LAMMPS are currently supported out of the box,
but a preset ``cmake/presets/windows.cmake`` is provided that contains
the packages that have been compiled successfully so far. You **must**
use the CMake based build procedure, since there is no support for GNU
make or the Unix shell utilities required for the GNU make build
procedure.
It is possible to use both the integrated CMake support of the Visual
Studio IDE or use an external CMake installation (e.g. downloaded from
cmake.org) to create build files and compile LAMMPS from the command line.
.. note::
Versions of Visual Studio before version 17.1 may scan the entire
LAMMPS source tree and likely miss the correct master
``CMakeLists.txt`` and get confused since there are multiple files
of that name in different folders but none in top level folder.
Please note, that for either approach CMake will create a so-called
:ref:`"multi-configuration" build environment <cmake_multiconfig>`, and
the command lines for building and testing LAMMPS must be adjusted
accordingly.
To support running in parallel you can compile with OpenMP enabled using
the OPENMP package or install Microsoft MPI (including the SDK) and compile
LAMMPS with MPI enabled.
.. note::
This is work in progress and you should contact the LAMMPS developers
via GitHub, the forum, or the mailing list, if you have questions or
LAMMPS specific problems.
.. _cross:
Using a cross-compiler

4
doc/src/Commands_all.rst
View File

@ -47,7 +47,7 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`displace_atoms <displace_atoms>`
* :doc:`dump <dump>`
* :doc:`dump_modify <dump_modify>`
* :doc:`dynamical_matrix <dynamical_matrix>`
* :doc:`dynamical_matrix (k) <dynamical_matrix>`
* :doc:`echo <echo>`
* :doc:`fix <fix>`
* :doc:`fix_modify <fix_modify>`
@ -117,7 +117,7 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`thermo <thermo>`
* :doc:`thermo_modify <thermo_modify>`
* :doc:`thermo_style <thermo_style>`
* :doc:`third_order <third_order>`
* :doc:`third_order (k) <third_order>`
* :doc:`timer <timer>`
* :doc:`timestep <timestep>`
* :doc:`uncompute <uncompute>`

1
doc/src/Commands_bond.rst
View File

@ -35,6 +35,7 @@ OPT.
* :doc:`class2 (ko) <bond_class2>`
* :doc:`fene (iko) <bond_fene>`
* :doc:`fene/expand (o) <bond_fene_expand>`
* :doc:`fene/nm <bond_fene>`
* :doc:`gaussian <bond_gaussian>`
* :doc:`gromos (o) <bond_gromos>`
* :doc:`harmonic (iko) <bond_harmonic>`

5
doc/src/Commands_compute.rst
View File

@ -28,6 +28,7 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`angle <compute_angle>`
* :doc:`angle/local <compute_angle_local>`
* :doc:`angmom/chunk <compute_angmom_chunk>`
* :doc:`ave/sphere/atom (k) <compute_ave_sphere_atom>`
* :doc:`basal/atom <compute_basal_atom>`
* :doc:`body/local <compute_body_local>`
* :doc:`bond <compute_bond>`
@ -99,7 +100,6 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`pe/tally <compute_tally>`
* :doc:`plasticity/atom <compute_plasticity_atom>`
* :doc:`pressure <compute_pressure>`
* :doc:`pressure/cylinder <compute_pressure_cylinder>`
* :doc:`pressure/uef <compute_pressure_uef>`
* :doc:`property/atom <compute_property_atom>`
* :doc:`property/chunk <compute_property_chunk>`
@ -142,8 +142,11 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`sph/t/atom <compute_sph_t_atom>`
* :doc:`spin <compute_spin>`
* :doc:`stress/atom <compute_stress_atom>`
* :doc:`stress/cartesian <compute_stress_profile>`
* :doc:`stress/cylinder <compute_stress_profile>`
* :doc:`stress/mop <compute_stress_mop>`
* :doc:`stress/mop/profile <compute_stress_mop>`
* :doc:`stress/spherical <compute_stress_profile>`
* :doc:`stress/tally <compute_tally>`
* :doc:`tdpd/cc/atom <compute_tdpd_cc_atom>`
* :doc:`temp (k) <compute_temp>`

3
doc/src/Commands_fix.rst
View File

@ -23,6 +23,7 @@ OPT.
:columns: 5
* :doc:`accelerate/cos <fix_accelerate_cos>`
* :doc:`acks2/reaxff (k) <fix_acks2_reaxff>`
* :doc:`adapt <fix_adapt>`
* :doc:`adapt/fep <fix_adapt_fep>`
* :doc:`addforce <fix_addforce>`
@ -103,6 +104,7 @@ OPT.
* :doc:`manifoldforce <fix_manifoldforce>`
* :doc:`mdi/engine <fix_mdi_engine>`
* :doc:`meso/move <fix_meso_move>`
* :doc:`mol/swap <fix_mol_swap>`
* :doc:`momentum (k) <fix_momentum>`
* :doc:`momentum/chunk <fix_momentum>`
* :doc:`move <fix_move>`
@ -127,6 +129,7 @@ OPT.
* :doc:`npt/sphere (o) <fix_npt_sphere>`
* :doc:`npt/uef <fix_nh_uef>`
* :doc:`numdiff <fix_numdiff>`
* :doc:`numdiff/virial <fix_numdiff_virial>`
* :doc:`nve (giko) <fix_nve>`
* :doc:`nve/asphere (gi) <fix_nve_asphere>`
* :doc:`nve/asphere/noforce <fix_nve_asphere_noforce>`

86
doc/src/Commands_input.rst
View File

@ -1,55 +1,75 @@
LAMMPS input scripts
====================
LAMMPS executes by reading commands from a input script (text file),
one line at a time. When the input script ends, LAMMPS exits. Each
command causes LAMMPS to take some action. It may set an internal
variable, read in a file, or run a simulation. Most commands have
default settings, which means you only need to use the command if you
wish to change the default.
LAMMPS executes calculations by reading commands from a input script (text file), one
line at a time. When the input script ends, LAMMPS exits. This is different
from programs that read and process the entire input before starting a calculation.
Each command causes LAMMPS to take some immediate action without regard
for any commands that may be processed later. Commands may set an
internal variable, read in a file, or run a simulation. These actions
can be grouped into three categories:
a) commands that change a global setting (examples: timestep, newton,
echo, log, thermo, restart),
b) commands that add, modify, remove, or replace "styles" that are
executed during a "run" (examples: pair_style, fix, compute, dump,
thermo_style, pair_modify), and
c) commands that execute a "run" or perform some other computation or
operation (examples: print, run, minimize, temper, write_dump, rerun,
read_data, read_restart)
Commands in category a) have default settings, which means you only
need to use the command if you wish to change the defaults.
In many cases, the ordering of commands in an input script is not
important. However the following rules apply:
important, but can have consequences when the global state is changed
between commands in the c) category. The following rules apply:
(1) LAMMPS does not read your entire input script and then perform a
simulation with all the settings. Rather, the input script is read
one line at a time and each command takes effect when it is read.
Thus this sequence of commands:
simulation with all the settings. Rather, the input script is read
one line at a time and each command takes effect when it is read.
Thus this sequence of commands:
.. code-block:: LAMMPS
.. code-block:: LAMMPS
timestep 0.5
run 100
run 100
timestep 0.5
run 100
run 100
does something different than this sequence:
does something different than this sequence:
.. code-block:: LAMMPS
.. code-block:: LAMMPS
run 100
timestep 0.5
run 100
run 100
timestep 0.5
run 100
In the first case, the specified timestep (0.5 fs) is used for two
simulations of 100 timesteps each. In the second case, the default
timestep (1.0 fs) is used for the first 100 step simulation and a 0.5 fs
timestep is used for the second one.
In the first case, the specified timestep (0.5 fs) is used for two
simulations of 100 timesteps each. In the second case, the default
timestep (1.0 fs) is used for the first 100 step simulation and a
0.5 fs timestep is used for the second one.
(2) Some commands are only valid when they follow other commands. For
example you cannot set the temperature of a group of atoms until atoms
have been defined and a group command is used to define which atoms
belong to the group.
example you cannot set the temperature of a group of atoms until
atoms have been defined and a group command is used to define which
atoms belong to the group.
(3) Sometimes command B will use values that can be set by command A.
This means command A must precede command B in the input script if it
is to have the desired effect. For example, the
:doc:`read_data <read_data>` command initializes the system by setting
up the simulation box and assigning atoms to processors. If default
values are not desired, the :doc:`processors <processors>` and
:doc:`boundary <boundary>` commands need to be used before read_data to
tell LAMMPS how to map processors to the simulation box.
This means command A must precede command B in the input script if
it is to have the desired effect. For example, the :doc:`read_data
<read_data>` command initializes the system by setting up the
simulation box and assigning atoms to processors. If default values
are not desired, the :doc:`processors <processors>` and
:doc:`boundary <boundary>` commands need to be used before read_data
to tell LAMMPS how to map processors to the simulation box.
Many input script errors are detected by LAMMPS and an ERROR or
WARNING message is printed. The :doc:`Errors <Errors>` page gives
more information on what errors mean. The documentation for each
command lists restrictions on how the command can be used.
You can use the :ref:`-skiprun <skiprun>` command line flag
to have LAMMPS skip the execution of any "run", "minimize", or similar
commands to check the entire input for correct syntax to avoid crashes
on typos or syntax errors in long runs.

5
doc/src/Commands_pair.rst
View File

@ -119,10 +119,12 @@ OPT.
* :doc:`granular <pair_granular>`
* :doc:`gw <pair_gw>`
* :doc:`gw/zbl <pair_gw>`
* :doc:`harmonic/cut (o) <pair_harmonic_cut>`
* :doc:`hbond/dreiding/lj (o) <pair_hbond_dreiding>`
* :doc:`hbond/dreiding/morse (o) <pair_hbond_dreiding>`
* :doc:`hdnnp <pair_hdnnp>`
* :doc:`ilp/graphene/hbn <pair_ilp_graphene_hbn>`
* :doc:`ilp/tmd <pair_ilp_tmd>`
* :doc:`kolmogorov/crespi/full <pair_kolmogorov_crespi_full>`
* :doc:`kolmogorov/crespi/z <pair_kolmogorov_crespi_z>`
* :doc:`lcbop <pair_lcbop>`
@ -210,6 +212,7 @@ OPT.
* :doc:`nm/cut (o) <pair_nm>`
* :doc:`nm/cut/coul/cut (o) <pair_nm>`
* :doc:`nm/cut/coul/long (o) <pair_nm>`
* :doc:`nm/cut/split <pair_nm>`
* :doc:`oxdna/coaxstk <pair_oxdna>`
* :doc:`oxdna/excv <pair_oxdna>`
* :doc:`oxdna/hbond <pair_oxdna>`
@ -239,6 +242,7 @@ OPT.
* :doc:`reaxff (ko) <pair_reaxff>`
* :doc:`rebo (io) <pair_airebo>`
* :doc:`resquared (go) <pair_resquared>`
* :doc:`saip/metal <pair_saip_metal>`
* :doc:`sdpd/taitwater/isothermal <pair_sdpd_taitwater_isothermal>`
* :doc:`smd/hertz <pair_smd_hertz>`
* :doc:`smd/tlsph <pair_smd_tlsph>`
@ -262,6 +266,7 @@ OPT.
* :doc:`spin/neel <pair_spin_neel>`
* :doc:`srp <pair_srp>`
* :doc:`sw (giko) <pair_sw>`
* :doc:`sw/mod (o) <pair_sw>`
* :doc:`table (gko) <pair_table>`
* :doc:`table/rx (k) <pair_table_rx>`
* :doc:`tdpd <pair_mesodpd>`

4
doc/src/Developer.rst
View File

@ -11,10 +11,14 @@ of time and requests from the LAMMPS user community.
:maxdepth: 1
Developer_org
Developer_code_design
Developer_parallel
Developer_comm_ops
Developer_flow
Developer_write
Developer_notes
Developer_plugins
Developer_unittest
Classes
Developer_platform
Developer_utils

433
doc/src/Developer_code_design.rst Normal file
View File

@ -0,0 +1,433 @@
Code design
-----------
This section explains some of the code design choices in LAMMPS with
the goal of helping developers write new code similar to the existing
code. Please see the section on :doc:`Requirements for contributed
code <Modify_style>` for more specific recommendations and guidelines.
While that section is organized more in the form of a checklist for
code contributors, the focus here is on overall code design strategy,
choices made between possible alternatives, and discussing some
relevant C++ programming language constructs.
Historically, the basic design philosophy of the LAMMPS C++ code was a
"C with classes" style. The motivation was to make it easy to modify
LAMMPS for people without significant training in C++ programming.
Data structures and code constructs were used that resemble the
previous implementation(s) in Fortran. A contributing factor to this
choice also was that at the time, C++ compilers were often not mature
and some of the advanced features contained bugs or did not function
as the standard required. There were also disagreements between
compiler vendors as to how to interpret the C++ standard documents.
However, C++ compilers have now advanced significantly. In 2020 we
decided to to require the C++11 standard as the minimum C++ language
standard for LAMMPS. Since then we have begun to also replace some of
the C-style constructs with equivalent C++ functionality, either from
the C++ standard library or as custom classes or functions, in order
to improve readability of the code and to increase code reuse through
abstraction of commonly used functionality.
.. note::
Please note that as of spring 2022 there is still a sizable chunk
of legacy code in LAMMPS that has not yet been refactored to
reflect these style conventions in full. LAMMPS has a large code
base and many different contributors and there also is a hierarchy
of precedence in which the code is adapted. Highest priority has
been the code in the ``src`` folder, followed by code in packages
in order of their popularity and complexity (simpler code is
adapted sooner), followed by code in the ``lib`` folder. Source
code that is downloaded from external packages or libraries during
compilation is not subject to the conventions discussed here.
Object oriented code
^^^^^^^^^^^^^^^^^^^^
LAMMPS is designed to be an object oriented code. Each simulation is
represented by an instance of the LAMMPS class. When running in
parallel each MPI process creates such an instance. This can be seen
in the ``main.cpp`` file where the core steps of running a LAMMPS
simulation are the following 3 lines of code:
.. code-block:: C++
LAMMPS *lammps = new LAMMPS(argc, argv, lammps_comm);
lammps->input->file();
delete lammps;
The first line creates a LAMMPS class instance and passes the command
line arguments and the global communicator to its constructor. The
second line triggers the LAMMPS instance to process the input (either
from standard input or a provided input file) until the simulation
ends. The third line deletes the LAMMPS instance. The remainder of
the main.cpp file has code for error handling, MPI configuration, and
other special features.
The basic LAMMPS class hierarchy which is created by the LAMMPS class
constructor is shown in :ref:`class-topology`. When input commands
are processed, additional class instances are created, or deleted, or
replaced. Likewise specific member functions of specific classes are
called to trigger actions such creating atoms, computing forces,
computing properties, time-propagating the system, or writing output.
Compositing and Inheritance
===========================
LAMMPS makes extensive use of the object oriented programming (OOP)
principles of *compositing* and *inheritance*. Classes like the
``LAMMPS`` class are a **composite** containing pointers to instances
of other classes like ``Atom``, ``Comm``, ``Force``, ``Neighbor``,
``Modify``, and so on. Each of these classes implement certain
functionality by storing and manipulating data related to the
simulation and providing member functions that trigger certain
actions. Some of those classes like ``Force`` are themselves
composites, containing instances of classes describing different force
interactions. Similarly the ``Modify`` class contains a list of
``Fix`` and ``Compute`` classes. If the input commands that
correspond to these classes include the word *style*, then LAMMPS
stores only a single instance of that class. E.g. *atom_style*,
*comm_style*, *pair_style*, *bond_style*. It the input command does
not include the word *style*, there can be many instances of that
class defined. E.g. *region*, *fix*, *compute*, *dump*.
**Inheritance** enables creation of *derived* classes that can share
common functionality in their base class while providing a consistent
interface. The derived classes replace (dummy or pure) functions in
the base class. The higher level classes can then call those methods
of the instantiated classes without having to know which specific
derived class variant was instantiated. In LAMMPS these derived
classes are often referred to as "styles", e.g. pair styles, fix
styles, atom styles and so on.
This is the origin of the flexibility of LAMMPS. For example pair
styles implement a variety of different non-bonded interatomic
potentials functions. All details for the implementation of a
potential are stored and executed in a single class.
As mentioned above, there can be multiple instances of classes derived
from the ``Fix`` or ``Compute`` base classes. They represent a
different facet of LAMMPS flexibility as they provide methods which
can be called at different points in time within a timestep, as
explained in `Developer_flow`. This allows the input script to tailor
how a specific simulation is run, what diagnostic computations are
performed, and how the output of those computations is further
processed or output.
Additional code sharing is possible by creating derived classes from the
derived classes (e.g., to implement an accelerated version of a pair
style) where only a subset of the derived class methods are replaced
with accelerated versions.
Polymorphism
============
Polymorphism and dynamic dispatch are another OOP feature that play an
important role in how LAMMPS selects what code to execute. In a
nutshell, this is a mechanism where the decision of which member
function to call from a class is determined at runtime and not when
the code is compiled. To enable it, the function has to be declared
as ``virtual`` and all corresponding functions in derived classes
should use the ``override`` property. Below is a brief example.
.. code-block:: c++
class Base {
public:
virtual ~Base() = default;
void call();
void normal();
virtual void poly();
};
void Base::call() {
normal();
poly();
}
class Derived : public Base {
public:
~Derived() override = default;
void normal();
void poly() override;
};
// [....]
Base *base1 = new Base();
Base *base2 = new Derived();
base1->call();
base2->call();
The difference in behavior of the ``normal()`` and the ``poly()`` member
functions is which of the two member functions is called when executing
`base1->call()` versus `base2->call()`. Without polymorphism, a
function within the base class can only call member functions within the
same scope, that is ``Base::call()`` will always call
``Base::normal()``. But for the `base2->call()` case the call of the
virtual member function will be dispatched to ``Derived::poly()``
instead. This mechanism means that functions are called within the
scope of the class type that was used to *create* the class instance are
invoked; even if they are assigned to a pointer using the type of a base
class. This is the desired behavior and this way LAMMPS can even use
styles that are loaded at runtime from a shared object file with the
:doc:`plugin command <plugin>`.
A special case of virtual functions are so-called pure functions. These
are virtual functions that are initialized to 0 in the class declaration
(see example below).
.. code-block:: c++
class Base {
public:
virtual void pure() = 0;
};
This has the effect that an instance of the base class cannot be
created and that derived classes **must** implement these functions.
Many of the functions listed with the various class styles in the
section :doc:`Modify` are pure functions. The motivation for this is
to define the interface or API of the functions but defer their
implementation to the derived classes.
However, there are downsides to this. For example, calls to virtual
functions from within a constructor, will not be in the scope of the
derived class and thus it is good practice to either avoid calling them
or to provide an explicit scope such as ``Base::poly()`` or
``Derived::poly()``. Furthermore, any destructors in classes containing
virtual functions should be declared virtual too, so they will be
processed in the expected order before types are removed from dynamic
dispatch.
.. admonition:: Important Notes
In order to be able to detect incompatibilities at compile time and
to avoid unexpected behavior, it is crucial that all member functions
that are intended to replace a virtual or pure function use the
``override`` property keyword. For the same reason, the use of
overloads or default arguments for virtual functions should be
avoided as they lead to confusion over which function is supposed to
override which and which arguments need to be declared.
Style Factories
===============
In order to create class instances for different styles, LAMMPS often
uses a programming pattern called `Factory`. Those are functions that
create an instance of a specific derived class, say ``PairLJCut`` and
return a pointer to the type of the common base class of that style,
``Pair`` in this case. To associate the factory function with the
style keyword, an ``std::map`` class is used with function pointers
indexed by their keyword (for example "lj/cut" for ``PairLJCut`` and
"morse" for ``PairMorse``). A couple of typedefs help keep the code
readable and a template function is used to implement the actual
factory functions for the individual classes. Below is an example
of such a factory function from the ``Force`` class as declared in
``force.h`` and implemented in ``force.cpp``. The file ``style_pair.h``
is generated during compilation and includes all main header files
(i.e. those starting with ``pair_``) of pair styles and then the
macro ``PairStyle()`` will associate the style name "lj/cut"
with a factory function creating an instance of the ``PairLJCut``
class.
.. code-block:: C++
// from force.h
typedef Pair *(*PairCreator)(LAMMPS *);
typedef std::map<std::string, PairCreator> PairCreatorMap;
PairCreatorMap *pair_map;
// from force.cpp
template <typename S, typename T> static S *style_creator(LAMMPS *lmp)
{
return new T(lmp);
}
// [...]
pair_map = new PairCreatorMap();
#define PAIR_CLASS
#define PairStyle(key, Class) (*pair_map)[#key] = &style_creator<Pair, Class>;
#include "style_pair.h"
#undef PairStyle
#undef PAIR_CLASS
// from pair_lj_cut.h
#ifdef PAIR_CLASS
PairStyle(lj/cut,PairLJCut);
#else
// [...]
Similar code constructs are present in other files like ``modify.cpp`` and
``modify.h`` or ``neighbor.cpp`` and ``neighbor.h``. Those contain
similar macros and include ``style_*.h`` files for creating class instances
of styles they manage.
I/O and output formatting
^^^^^^^^^^^^^^^^^^^^^^^^^
C-style stdio versus C++ style iostreams
========================================
LAMMPS uses the "stdio" library of the standard C library for reading
from and writing to files and console instead of C++ "iostreams".
This is mainly motivated by better performance, better control over
formatting, and less effort to achieve specific formatting.
Since mixing "stdio" and "iostreams" can lead to unexpected
behavior. use of the latter is strongly discouraged. Also output to
the screen should not use the predefined ``stdout`` FILE pointer, but
rather the ``screen`` and ``logfile`` FILE pointers managed by the
LAMMPS class. Furthermore, output should generally only be done by
MPI rank 0 (``comm->me == 0``). Output that is sent to both
``screen`` and ``logfile`` should use the :cpp:func:`utils::logmesg()
convenience function <LAMMPS_NS::utils::logmesg>`.
We also discourage the use of stringstreams because the bundled {fmt}
library and the customized tokenizer classes can provide the same
functionality in a cleaner way with better performance. This also
helps maintain a consistent programming syntax with code from many
different contributors.
Formatting with the {fmt} library
===================================
The LAMMPS source code includes a copy of the `{fmt} library
<https://fmt.dev>`_ which is preferred over formatting with the
"printf()" family of functions. The primary reason is that it allows
a typesafe default format for any type of supported data. This is
particularly useful for formatting integers of a given size (32-bit or
64-bit) which may require different format strings depending on
compile time settings or compilers/operating systems. Furthermore,
{fmt} gives better performance, has more functionality, a familiar
formatting syntax that has similarities to ``format()`` in Python, and
provides a facility that can be used to integrate format strings and a
variable number of arguments into custom functions in a much simpler
way than the varargs mechanism of the C library. Finally, {fmt} has
been included into the C++20 language standard, so changes to adopt it
are future-proof.
Formatted strings are frequently created by calling the
``fmt::format()`` function which will return a string as a
``std::string`` class instance. In contrast to the ``%`` placeholder
in ``printf()``, the {fmt} library uses ``{}`` to embed format
descriptors. In the simplest case, no additional characters are
needed as {fmt} will choose the default format based on the data type
of the argument. Otherwise the ``fmt::print()`` function may be
used instead of ``printf()`` or ``fprintf()``. In addition, several
LAMMPS output functions, that originally accepted a single string as
argument have been overloaded to accept a format string with optional
arguments as well (e.g., ``Error::all()``, ``Error::one()``,
``utils::logmesg()``).
Summary of the {fmt} format syntax
==================================
The syntax of the format string is "{[<argument id>][:<format spec>]}",
where either the argument id or the format spec (separated by a colon
':') is optional. The argument id is usually a number starting from 0
that is the index to the arguments following the format string. By
default these are assigned in order (i.e. 0, 1, 2, 3, 4 etc.). The most
common case for using argument id would be to use the same argument in
multiple places in the format string without having to provide it as an
argument multiple times. In LAMMPS the argument id is rarely used.
More common is the use of a format specifier, which starts with a colon.
This may optionally be followed by a fill character (default is ' '). If
provided, the fill character **must** be followed by an alignment
character ('<', '^', '>' for left, centered, or right alignment
(default)). The alignment character may be used without a fill
character. The next important format parameter would be the minimum
width, which may be followed by a dot '.' and a precision for floating
point numbers. The final character in the format string would be an
indicator for the "presentation", i.e. 'd' for decimal presentation of
integers, 'x' for hexadecimal, 'o' for octal, 'c' for character etc.
This mostly follows the "printf()" scheme but without requiring an
additional length parameter to distinguish between different integer
widths. The {fmt} library will detect those and adapt the formatting
accordingly. For floating point numbers there are correspondingly, 'g'
for generic presentation, 'e' for exponential presentation, and 'f' for
fixed point presentation.
Thus "{:8}" would represent *any* type argument using at least 8
characters; "{:<8}" would do this as left aligned, "{:^8}" as centered,
"{:>8}" as right aligned. If a specific presentation is selected, the
argument type must be compatible or else the {fmt} formatting code will
throw an exception. Some format string examples are given below:
.. code-block:: C
auto mesg = fmt::format(" CPU time: {:4d}:{:02d}:{:02d}\n", cpuh, cpum, cpus);
mesg = fmt::format("{:<8s}| {:<10.5g} | {:<10.5g} | {:<10.5g} |{:6.1f} |{:6.2f}\n",
label, time_min, time, time_max, time_sq, tmp);
utils::logmesg(lmp,"{:>6} = max # of 1-2 neighbors\n",maxall);
utils::logmesg(lmp,"Lattice spacing in x,y,z = {:.8} {:.8} {:.8}\n",
xlattice,ylattice,zlattice);
which will create the following output lines:
.. parsed-literal::
CPU time: 0:02:16
Pair | 2.0133 | 2.0133 | 2.0133 | 0.0 | 84.21
4 = max # of 1-2 neighbors
Lattice spacing in x,y,z = 1.6795962 1.6795962 1.6795962
Finally, a special feature of the {fmt} library is that format
parameters like the width or the precision may be also provided as
arguments. In that case a nested format is used where a pair of curly
braces (with an optional argument id) "{}" are used instead of the
value, for example "{:{}d}" will consume two integer arguments, the
first will be the value shown and the second the minimum width.
For more details and examples, please consult the `{fmt} syntax
documentation <https://fmt.dev/latest/syntax.html>`_ website.
Memory management
^^^^^^^^^^^^^^^^^
Dynamical allocation of small data and objects can be done with the
the C++ commands "new" and "delete/delete[]. Large data should use
the member functions of the ``Memory`` class, most commonly,
``Memory::create()``, ``Memory::grow()``, and ``Memory::destroy()``,
which provide variants for vectors, 2d arrays, 3d arrays, etc.
These can also be used for small data.
The use of ``malloc()``, ``calloc()``, ``realloc()`` and ``free()``
directly is strongly discouraged. To simplify adapting legacy code
into the LAMMPS code base the member functions ``Memory::smalloc()``,
``Memory::srealloc()``, and ``Memory::sfree()`` are available, which
perform additional error checks for safety.
Use of these custom memory allocation functions is motivated by the
following considerations:
- memory allocation failures on *any* MPI rank during a parallel run
will trigger an immediate abort of the entire parallel calculation
instead of stalling it
- a failing "new" will trigger an exception which is also captured by
LAMMPS and triggers a global abort
- allocation of multi-dimensional arrays will be done in a C compatible
fashion but so that the storage of the actual data is stored in one
large contiguous block. Thus when MPI communication is needed,
the data can be communicated directly (similar to Fortran arrays).
- the "destroy()" and "sfree()" functions may safely be called on NULL
pointers
- the "destroy()" functions will nullify the pointer variables making
"use after free" errors easy to detect
- it is possible to use a larger than default memory alignment (not on
all operating systems, since the allocated storage pointers must be
compatible with ``free()`` for technical reasons)
In the practical implementation of code this means that any pointer
variables that are class members should be initialized to a
``nullptr`` value in their respective constructors. That way it is
safe to call ``Memory::destroy()`` or ``delete[]`` on them before
*any* allocation outside the constructor. This helps prevent memory
leaks.

235
doc/src/Developer_comm_ops.rst Normal file
View File

@ -0,0 +1,235 @@
Communication patterns
----------------------
This page describes various inter-processor communication operations
provided by LAMMPS, mostly in the core *Comm* class. These are operations
for common tasks implemented using MPI library calls. They are used by
other classes to perform communication of different kinds. These
operations are useful to know about when writing new code for LAMMPS
that needs to communicate data between processors.
Owned and ghost atoms
^^^^^^^^^^^^^^^^^^^^^
As described on the :doc:`parallel partitioning algorithms
<Developer_par_part>` page, LAMMPS spatially decomposes the simulation
domain, either in a *brick* or *tiled* manner. Each processor (MPI
task) owns atoms within its sub-domain and additionally stores ghost
atoms within a cutoff distance of its sub-domain.
Forward and reverse communication
=================================
As described on the :doc:`parallel communication algorithms
<Developer_par_comm>` page, the most common communication operations are
first, *forward communication* which sends owned atom information from
each processor to nearby processors to store with their ghost atoms.
The need to do this communication arises when data from the owned atoms
is updated (e.g. their positions) and this updated information needs to
be **copied** to the corresponding ghost atoms.
And second, *reverse communication* which sends ghost atom information
from each processor to the owning processor to **accumulate** (sum)
the values with the corresponding owned atoms. The need for this
arises when data is computed and also stored with ghost atoms
(e.g. forces when using a "half" neighbor list) and thus those terms
need to be added to their corresponding atoms on the process where
they are "owned" atoms. Please note, that with the :doc:`newton off
<newton>` setting this does not happen and the neighbor lists are
constructed so that these interactions are computed on both MPI
processes containing one of the atoms and only the data pertaining to
the local atom is stored.
The time-integration classes in LAMMPS invoke these operations each
timestep via the *forward_comm()* and *reverse_comm()* methods in the
*Comm* class. Which per-atom data is communicated depends on the
currently used :doc:`atom style <atom_style>` and whether
:doc:`comm_modify vel <comm_modify>` setting is "no" (default) or
"yes".
Similarly, *Pair* style classes can invoke the *forward_comm(this)*
and *reverse_comm(this)* methods in the *Comm* class to perform the
same operations on per-atom data that is generated and stored within
the pair style class. Note that this function requires passing the
``this`` pointer as the first argument to enable the *Comm* class to
call the "pack" and "unpack" functions discussed below. An example of
the use of these functions are many-body pair styles like the
embedded-atom method (EAM) which compute intermediate values in the
first part of the compute() function that need to be stored by both
owned and ghost atoms for the second part of the force computation.
The *Comm* class methods perform the MPI communication for buffers of
per-atom data. They "call back" to the *Pair* class so it can *pack*
or *unpack* the buffer with data the *Pair* class owns. There are 4
such methods that the *Pair* class must define, assuming it uses both
forward and reverse communication:
* pack_forward_comm()
* unpack_forward_comm()
* pack_reverse_comm()
* unpack_reverse_comm()
The arguments to these methods include the buffer and a list of atoms
to pack or unpack. The *Pair* class also must set the *comm_forward*
and *comm_reverse* variables which store the number of values stored
in the communication buffers for each operation. This means, if
desired, it can choose to store multiple per-atom values in the
buffer, and they will be communicated together to minimize
communication overhead. The communication buffers are defined vectors
containing ``double`` values. To correctly store integers that may be
64-bit (bigint, tagint, imageint) in the buffer, you need to use the
`ubuf union <Communication buffer coding with ubuf>`_ construct.
The *Fix*, *Compute*, and *Dump* classes can also invoke the same kind
of forward and reverse communication operations using the same *Comm*
class methods. Likewise the same pack/unpack methods and
comm_forward/comm_reverse variables must be defined by the calling
*Fix*, *Compute*, or *Dump* class.
For *Fix* classes there is an optional second argument to the
*forward_comm()* and *reverse_comm()* call which can be used when the
fix performs multiple modes of communication, with different numbers
of values per atom. The fix should set the *comm_forward* and
*comm_reverse* variables to the maximum value, but can invoke the
communication for a particular mode with a smaller value. For this
to work, the *pack_forward_comm()*, etc methods typically use a class
member variable to choose which values to pack/unpack into/from the
buffer.
Finally, for reverse communications in *Fix* classes there is also the
*reverse_comm_variable()* method that allows the communication to have
a different amount of data per-atom. It invokes these corresponding
callback methods:
* pack_reverse_comm_size()
* unpack_reverse_comm_size()
which have extra arguments to specify the amount of data stored
in the buffer for each atom.
Higher level communication
^^^^^^^^^^^^^^^^^^^^^^^^^^
There are also several higher-level communication operations provided
in LAMMPS which work for either *brick* or *tiled* decompositions.
They may be useful for a new class to invoke if it requires more
sophisticated communication than the *forward* and *reverse* methods
provide. The 3 communication operations described here are
* ring
* irregular
* rendezvous
You can invoke these *grep* command in the LAMMPS src directory, to
see a list of classes that invoke the 3 operations.
* ``grep "\->ring" *.cpp */*.cpp``
* ``grep "irregular\->" *.cpp``
* ``grep "\->rendezvous" *.cpp */*.cpp``
Ring operation
==============
The *ring* operation is invoked via the *ring()* method in the *Comm*
class.
Each processor first creates a buffer with a list of values, typically
associated with a subset of the atoms it owns. Now think of the *P*
processors as connected to each other in a *ring*. Each processor *M*
sends data to the next *M+1* processor. It receives data from the
preceding *M-1* processor. The ring is periodic so that the last
processor sends to the first processor, and the first processor
receives from the last processor.
Invoking the *ring()* method passes each processor's buffer in *P*
steps around the ring. At each step a *callback* method, provided as
an argument to ring(), in the caller is invoked. This allows each
processor to examine the data buffer provided by every other
processor. It may extract values needed by its atoms from the
buffers, or it may alter placeholder values in the buffer. In the
latter case, when the *ring* operation is complete, each processor can
examine its original buffer to extract modified values.
Note that the *ring* operation is similar to an MPI_Alltoall()
operation where every processor effectively sends and receives data to
every other processor. The difference is that the *ring* operation
does it one step at a time, so the total volume of data does not need
to be stored by every processor. However, the *ring* operation is
also less efficient than MPI_Alltoall() because of the *P* stages
required. So it is typically only suitable for small data buffers and
occasional operations that are not time-critical.
Irregular operation
===================
The *irregular* operation is provided by the *Irregular* class. What
LAMMPS terms irregular communication is when each processor knows what
data it needs to send to what processor, but does not know what
processors are sending it data. An example is when load-balancing is
performed and each processor needs to send some of its atoms to new
processors.
The *Irregular* class provides 5 high-level methods useful in this
context:
* create_data()
* exchange_data()
* create_atom()
* exchange_atom()
* migrate_atoms()
For the *create_data()* method, each processor specifies a list of *N*
datums to send, each to a specified processor. Internally, the method
creates efficient data structures for performing the communication.
The *exchange_data()* method triggers the communication to be
performed. Each processor provides the vector of *N* datums to send,
and the size of each datum. All datums must be the same size.
The *create_atom()* and *exchange_atom()* methods are similar except
that the size of each datum can be different. Typically this is used
to communicate atoms, each with a variable amount of per-atom data, to
other processors.
The *migrate_atoms()* method is a convenience wrapper on the
*create_atom()* and *exchange_atom()* methods to simplify
communication of all the per-atom data associated with an atom so that
the atom can effectively migrate to a new owning processor. It is
similar to the *exchange()* method in the *Comm* class invoked when
atoms move to neighboring processors (in the regular or tiled
decomposition) during timestepping, except that it allows atoms to
have moved arbitrarily long distances and still be properly
communicated to a new owning processor.
Rendezvous operation
====================
Finally, the *rendezvous* operation is invoked via the *rendezvous()*
method in the *Comm* class. Depending on how much communication is
needed and how many processors a LAMMPS simulation is running on, it
can be a much more efficient choice than the *ring()* method. It uses
the *irregular* operation internally once or twice to do its
communication. The rendezvous algorithm is described in detail in
:ref:`(Plimpton) <Plimpton>`, including some LAMMPS use cases.
For the *rendezvous()* method, each processor specifies a list of *N*
datums to send and which processor to send each of them to.
Internally, this communication is performed as an irregular operation.
The received datums are returned to the caller via invocation of
*callback* function, provided as an argument to *rendezvous()*. The
caller can then process the received datums and (optionally) assemble
a new list of datums to communicate to a new list of specific
processors. When the callback function exits, the *rendezvous()*
method performs a second irregular communication on the new list of
datums.
Examples in LAMMPS of use of the *rendezvous* operation are the
:doc:`fix rigid/small <fix_rigid>` and :doc:`fix shake
<fix_shake>` commands (for one-time identification of the rigid body
atom clusters) and the identification of special_bond 1-2, 1-3 and 1-4
neighbors within molecules. See the :doc:`special_bonds <special_bonds>`
command for context.
----------
.. _Plimpton:
**(Plimpton)** Plimpton and Knight, JPDC, 147, 184-195 (2021).

57
doc/src/Developer_notes.rst
View File

@ -7,6 +7,63 @@ typically document what a variable stores, what a small section of
code does, or what a function does and its input/outputs. The topics
on this page are intended to document code functionality at a higher level.
Reading and parsing of text and text files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is frequently required for a class in LAMMPS to read in additional
data from a file, e.g. potential parameters from a potential file for
manybody potentials. LAMMPS provides several custom classes and
convenience functions to simplify the process. They offer the
following benefits:
- better code reuse and fewer lines of code needed to implement reading
and parsing data from a file
- better detection of format errors, incompatible data, and better error messages
- exit with an error message instead of silently converting only part of the
text to a number or returning a 0 on unrecognized text and thus reading incorrect values
- re-entrant code through avoiding global static variables (as used by ``strtok()``)
- transparent support for translating unsupported UTF-8 characters to their ASCII equivalents
(the text-to-value conversion functions **only** accept ASCII characters)
In most cases (e.g. potential files) the same data is needed on all MPI
ranks. Then it is best to do the reading and parsing only on MPI rank
0, and communicate the data later with one or more ``MPI_Bcast()``
calls. For reading generic text and potential parameter files the
custom classes :cpp:class:`TextFileReader <LAMMPS_NS::TextFileReader>`
and :cpp:class:`PotentialFileReader <LAMMPS_NS::PotentialFileReader>`
are available. They allow reading the file as individual lines for which
they can return a tokenizer class (see below) for parsing the line. Or
they can return blocks of numbers as a vector directly. The
documentation on :ref:`File reader classes <file-reader-classes>`
contains an example for a typical case.
When reading per-atom data, the data on each line of the file usually
needs to include an atom ID so it can be associated with a particular
atom. In that case the data can be read in multi-line chunks and
broadcast to all MPI ranks with
:cpp:func:`utils::read_lines_from_file()
<LAMMPS_NS::utils::read_lines_from_file>`. Those chunks are then
split into lines, parsed, and applied only to atoms the MPI rank
"owns".
For splitting a string (incrementally) into words and optionally
converting those to numbers, the :cpp:class:`Tokenizer
<LAMMPS_NS::Tokenizer>` and :cpp:class:`ValueTokenizer
<LAMMPS_NS::ValueTokenizer>` can be used. Those provide a superset of
the functionality of ``strtok()`` from the C-library and the latter
also includes conversion to different types. Any errors while
processing the string in those classes will result in an exception,
which can be caught and the error processed as needed. Unlike the
C-library functions ``atoi()``, ``atof()``, ``strtol()``, or
``strtod()`` the conversion will check if the converted text is a
valid integer or floating point number and will not silently return an
unexpected or incorrect value. For example, ``atoi()`` will return 12
when converting "12.5", while the ValueTokenizer class will throw an
:cpp:class:`InvalidIntegerException
<LAMMPS_NS::InvalidIntegerException>` if
:cpp:func:`ValueTokenizer::next_int()
<LAMMPS_NS::ValueTokenizer::next_int>` is called on the same string.
Fix contributions to instantaneous energy, virial, and cumulative energy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

8
doc/src/Developer_org.rst
View File

@ -225,7 +225,7 @@ follows:
commands in an input script.
- The Force class computes various forces between atoms. The Pair
parent class is for non-bonded or pair-wise forces, which in LAMMPS
parent class is for non-bonded or pairwise forces, which in LAMMPS
also includes many-body forces such as the Tersoff 3-body potential if
those are computed by walking pairwise neighbor lists. The Bond,
Angle, Dihedral, Improper parent classes are styles for bonded
@ -252,12 +252,6 @@ follows:
- The Timer class logs timing information, output at the end
of a run.
.. TODO section on "Spatial decomposition and parallel operations"
.. diagram of 3d processor grid, brick vs. tiled. local vs. ghost
.. atoms, 6-way communication with pack/unpack functions,
.. PBC as part of the communication, forward and reverse communication
.. rendezvous communication, ring communication.
.. TODO section on "Fixes, Computes, and Variables"
.. how and when data is computed and provided and how it is
.. referenced. flags in Fix/Compute/Variable classes tell

120
doc/src/Developer_par_comm.rst Normal file
View File

@ -0,0 +1,120 @@
Communication
^^^^^^^^^^^^^
Following the partitioning scheme in use all per-atom data is
distributed across the MPI processes, which allows LAMMPS to handle very
large systems provided it uses a correspondingly large number of MPI
processes. Since The per-atom data (atom IDs, positions, velocities,
types, etc.) To be able to compute the short-range interactions MPI
processes need not only access to data of atoms they "own" but also
information about atoms from neighboring sub-domains, in LAMMPS referred
to as "ghost" atoms. These are copies of atoms storing required
per-atom data for up to the communication cutoff distance. The green
dashed-line boxes in the :ref:`domain-decomposition` figure illustrate
the extended ghost-atom sub-domain for one processor.
This approach is also used to implement periodic boundary
conditions: atoms that lie within the cutoff distance across a periodic
boundary are also stored as ghost atoms and taken from the periodic
replication of the sub-domain, which may be the same sub-domain, e.g. if
running in serial. As a consequence of this, force computation in
LAMMPS is not subject to minimum image conventions and thus cutoffs may
be larger than half the simulation domain.
.. _ghost-atom-comm:
.. figure:: img/ghost-comm.png
:align: center
ghost atom communication
This figure shows the ghost atom communication patterns between
sub-domains for "brick" (left) and "tiled" communication styles for
2d simulations. The numbers indicate MPI process ranks. Here the
sub-domains are drawn spatially separated for clarity. The
dashed-line box is the extended sub-domain of processor 0 which
includes its ghost atoms. The red- and blue-shaded boxes are the
regions of communicated ghost atoms.
Efficient communication patterns are needed to update the "ghost" atom
data, since that needs to be done at every MD time step or minimization
step. The diagrams of the `ghost-atom-comm` figure illustrate how ghost
atom communication is performed in two stages for a 2d simulation (three
in 3d) for both a regular and irregular partitioning of the simulation
box. For the regular case (left) atoms are exchanged first in the
*x*-direction, then in *y*, with four neighbors in the grid of processor
sub-domains.
In the *x* stage, processor ranks 1 and 2 send owned atoms in their
red-shaded regions to rank 0 (and vice versa). Then in the *y* stage,
ranks 3 and 4 send atoms in their blue-shaded regions to rank 0, which
includes ghost atoms they received in the *x* stage. Rank 0 thus
acquires all its ghost atoms; atoms in the solid blue corner regions
are communicated twice before rank 0 receives them.
For the irregular case (right) the two stages are similar, but a
processor can have more than one neighbor in each direction. In the
*x* stage, MPI ranks 1,2,3 send owned atoms in their red-shaded regions to
rank 0 (and vice versa). These include only atoms between the lower
and upper *y*-boundary of rank 0's sub-domain. In the *y* stage, ranks
4,5,6 send atoms in their blue-shaded regions to rank 0. This may
include ghost atoms they received in the *x* stage, but only if they
are needed by rank 0 to fill its extended ghost atom regions in the
+/-*y* directions (blue rectangles). Thus in this case, ranks 5 and
6 do not include ghost atoms they received from each other (in the *x*
stage) in the atoms they send to rank 0. The key point is that while
the pattern of communication is more complex in the irregular
partitioning case, it can still proceed in two stages (three in 3d)
via atom exchanges with only neighboring processors.
When attributes of owned atoms are sent to neighboring processors to
become attributes of their ghost atoms, LAMMPS calls this a "forward"
communication. On timesteps when atoms migrate to new owning processors
and neighbor lists are rebuilt, each processor creates a list of its
owned atoms which are ghost atoms in each of its neighbor processors.
These lists are used to pack per-atom coordinates (for example) into
message buffers in subsequent steps until the next reneighboring.
A "reverse" communication is when computed ghost atom attributes are
sent back to the processor who owns the atom. This is used (for
example) to sum partial forces on ghost atoms to the complete force on
owned atoms. The order of the two stages described in the
:ref:`ghost-atom-comm` figure is inverted and the same lists of atoms
are used to pack and unpack message buffers with per-atom forces. When
a received buffer is unpacked, the ghost forces are summed to owned atom
forces. As in forward communication, forces on atoms in the four blue
corners of the diagrams are sent, received, and summed twice (once at
each stage) before owning processors have the full force.
These two operations are used many places within LAMMPS aside from
exchange of coordinates and forces, for example by manybody potentials
to share intermediate per-atom values, or by rigid-body integrators to
enable each atom in a body to access body properties. Here are
additional details about how these communication operations are
performed in LAMMPS:
- When exchanging data with different processors, forward and reverse
communication is done using ``MPI_Send()`` and ``MPI_IRecv()`` calls.
If a processor is "exchanging" atoms with itself, only the pack and
unpack operations are performed, e.g. to create ghost atoms across
periodic boundaries when running on a single processor.
- For forward communication of owned atom coordinates, periodic box
lengths are added and subtracted when the receiving processor is
across a periodic boundary from the sender. There is then no need to
apply a minimum image convention when calculating distances between
atom pairs when building neighbor lists or computing forces.
- The cutoff distance for exchanging ghost atoms is typically equal to
the neighbor cutoff. But it can also chosen to be longer if needed,
e.g. half the diameter of a rigid body composed of multiple atoms or
over 3x the length of a stretched bond for dihedral interactions. It
can also exceed the periodic box size. For the regular communication
pattern (left), if the cutoff distance extends beyond a neighbor
processor's sub-domain, then multiple exchanges are performed in the
same direction. Each exchange is with the same neighbor processor,
but buffers are packed/unpacked using a different list of atoms. For
forward communication, in the first exchange a processor sends only
owned atoms. In subsequent exchanges, it sends ghost atoms received
in previous exchanges. For the irregular pattern (right) overlaps of
a processor's extended ghost-atom sub-domain with all other processors
in each dimension are detected.

188
doc/src/Developer_par_long.rst Normal file
View File

@ -0,0 +1,188 @@
Long-range interactions
^^^^^^^^^^^^^^^^^^^^^^^
For charged systems, LAMMPS can compute long-range Coulombic
interactions via the FFT-based particle-particle/particle-mesh (PPPM)
method implemented in :doc:`kspace style pppm and its variants
<kspace_style>`. For that Coulombic interactions are partitioned into
short- and long-range components. The short-ranged portion is computed
in real space as a loop over pairs of charges within a cutoff distance,
using neighbor lists. The long-range portion is computed in reciprocal
space using a kspace style. For the PPPM implementation the simulation
cell is overlaid with a regular FFT grid in 3d. It proceeds in several stages:
a) each atom's point charge is interpolated to nearby FFT grid points,
b) a forward 3d FFT is performed,
c) a convolution operation is performed in reciprocal space,
d) one or more inverse 3d FFTs are performed, and
e) electric field values from grid points near each atom are interpolated to compute
its forces.
For any of the spatial-decomposition partitioning schemes each processor
owns the brick-shaped portion of FFT grid points contained within its
sub-domain. The two interpolation operations use a stencil of grid
points surrounding each atom. To accommodate the stencil size, each
processor also stores a few layers of ghost grid points surrounding its
brick. Forward and reverse communication of grid point values is
performed similar to the corresponding :doc:`atom data communication
<Developer_par_comm>`. In this case, electric field values on owned
grid points are sent to neighboring processors to become ghost point
values. Likewise charge values on ghost points are sent and summed to
values on owned points.
For triclinic simulation boxes, the FFT grid planes are parallel to
the box faces, but the mapping of charge and electric field values
to/from grid points is done in reduced coordinates where the tilted
box is conceptually a unit cube, so that the stencil and FFT
operations are unchanged. However the FFT grid size required for a
given accuracy is larger for triclinic domains than it is for
orthogonal boxes.
.. _fft-parallel:
.. figure:: img/fft-decomp-parallel.png
:align: center
parallel FFT in PPPM
Stages of a parallel FFT for a simulation domain overlaid
with an 8x8x8 3d FFT grid, partitioned across 64 processors.
Within each of the 4 diagrams, grid cells of the same color are
owned by a single processor; for simplicity only cells owned by 4
or 8 of the 64 processors are colored. The two images on the left
illustrate brick-to-pencil communication. The two images on the
right illustrate pencil-to-pencil communication, which in this
case transposes the *y* and *z* dimensions of the grid.
Parallel 3d FFTs require substantial communication relative to their
computational cost. A 3d FFT is implemented by a series of 1d FFTs
along the *x-*, *y-*, and *z-*\ direction of the FFT grid. Thus the FFT
grid cannot be decomposed like atoms into 3 dimensions for parallel
processing of the FFTs but only in 1 (as planes) or 2 (as pencils)
dimensions and in between the steps the grid needs to be transposed to
have the FFT grid portion "owned" by each MPI process complete in the
direction of the 1d FFTs it has to perform. LAMMPS uses the
pencil-decomposition algorithm as shown in the :ref:`fft-parallel` figure.
Initially (far left), each processor owns a brick of same-color grid
cells (actually grid points) contained within in its sub-domain. A
brick-to-pencil communication operation converts this layout to 1d
pencils in the *x*-dimension (center left). Again, cells of the same
color are owned by the same processor. Each processor can then compute
a 1d FFT on each pencil of data it wholly owns using a call to the
configured FFT library. A pencil-to-pencil communication then converts
this layout to pencils in the *y* dimension (center right) which
effectively transposes the *x* and *y* dimensions of the grid, followed
by 1d FFTs in *y*. A final transpose of pencils from *y* to *z* (far
right) followed by 1d FFTs in *z* completes the forward FFT. The data
is left in a *z*-pencil layout for the convolution operation. One or
more inverse FFTs then perform the sequence of 1d FFTs and communication
steps in reverse order; the final layout of resulting grid values is the
same as the initial brick layout.
Each communication operation within the FFT (brick-to-pencil or
pencil-to-pencil or pencil-to-brick) converts one tiling of the 3d grid
to another, where a tiling in this context means an assignment of a
small brick-shaped subset of grid points to each processor, the union of
which comprise the entire grid. The parallel `fftMPI library
<https://lammps.github.io/fftmpi/>`_ written for LAMMPS allows arbitrary
definitions of the tiling so that an irregular partitioning of the
simulation domain can use it directly. Transforming data from one
tiling to another is implemented in `fftMPI` using point-to-point
communication, where each processor sends data to a few other
processors, since each tile in the initial tiling overlaps with a
handful of tiles in the final tiling.
The transformations could also be done using collective communication
across all $P$ processors with a single call to ``MPI_Alltoall()``, but
this is typically much slower. However, for the specialized brick and
pencil tiling illustrated in :ref:`fft-parallel` figure, collective
communication across the entire MPI communicator is not required. In
the example an :math:`8^3` grid with 512 grid cells is partitioned
across 64 processors; each processor owns a 2x2x2 3d brick of grid
cells. The initial brick-to-pencil communication (upper left to upper
right) only requires collective communication within subgroups of 4
processors, as illustrated by the 4 colors. More generally, a
brick-to-pencil communication can be performed by partitioning *P*
processors into :math:`P^{\frac{2}{3}}` subgroups of
:math:`P^{\frac{1}{3}}` processors each. Each subgroup performs
collective communication only within its subgroup. Similarly,
pencil-to-pencil communication can be performed by partitioning *P*
processors into :math:`P^{\frac{1}{2}}` subgroups of
:math:`P^{\frac{1}{2}}` processors each. This is illustrated in the
figure for the :math:`y \Rightarrow z` communication (center). An
eight-processor subgroup owns the front *yz* plane of data and performs
collective communication within the subgroup to transpose from a
*y*-pencil to *z*-pencil layout.
LAMMPS invokes point-to-point communication by default, but also
provides the option of partitioned collective communication when using a
:doc:`kspace_modify collective yes <kspace_modify>` command to switch to
that mode. In the latter case, the code detects the size of the
disjoint subgroups and partitions the single *P*-size communicator into
multiple smaller communicators, each of which invokes collective
communication. Testing on a large IBM Blue Gene/Q machine at Argonne
National Labs showed a significant improvement in FFT performance for
large processor counts; partitioned collective communication was faster
than point-to-point communication or global collective communication
involving all *P* processors.
Here are some additional details about FFTs for long-range and related
grid/particle operations that LAMMPS supports:
- The fftMPI library allows each grid dimension to be a multiple of
small prime factors (2,3,5), and allows any number of processors to
perform the FFT. The resulting brick and pencil decompositions are
thus not always as well-aligned but the size of subgroups of
processors for the two modes of communication (brick/pencil and
pencil/pencil) still scale as :math:`O(P^{\frac{1}{3}})` and
:math:`O(P^{\frac{1}{2}})`.
- For efficiency in performing 1d FFTs, the grid transpose
operations illustrated in Figure \ref{fig:fft} also involve
reordering the 3d data so that a different dimension is contiguous
in memory. This reordering can be done during the packing or
unpacking of buffers for MPI communication.
- For large systems and particularly a large number of MPI processes,
the dominant cost for parallel FFTs is often the communication, not
the computation of 1d FFTs, even though the latter scales as :math:`N
\log(N)` in the number of grid points *N* per grid direction. This is
due to the fact that only a 2d decomposition into pencils is possible
while atom data (and their corresponding short-range force and energy
computations) can be decomposed efficiently in 3d.
This can be addressed by reducing the number of MPI processes involved
in the MPI communication by using :doc:`hybrid MPI + OpenMP
parallelization <Speed_omp>`. This will use OpenMP parallelization
inside the MPI domains and while that may have a lower parallel
efficiency, it reduces the communication overhead.
As an alternative it is also possible to start a :ref:`multi-partition
<partition>` calculation and then use the :doc:`verlet/split
integrator <run_style>` to perform the PPPM computation on a
dedicated, separate partition of MPI processes. This uses an integer
"1:*p*" mapping of *p* sub-domains of the atom decomposition to one
sub-domain of the FFT grid decomposition and where pairwise non-bonded
and bonded forces and energies are computed on the larger partition
and the PPPM kspace computation concurrently on the smaller partition.
- LAMMPS also implements PPPM-based solvers for other long-range
interactions, dipole and dispersion (Lennard-Jones), which can be used
in conjunction with long-range Coulombics for point charges.
- LAMMPS implements a ``GridComm`` class which overlays the simulation
domain with a regular grid, partitions it across processors in a
manner consistent with processor sub-domains, and provides methods for
forward and reverse communication of owned and ghost grid point
values. It is used for PPPM as an FFT grid (as outlined above) and
also for the MSM algorithm which uses a cascade of grid sizes from
fine to coarse to compute long-range Coulombic forces. The GridComm
class is also useful for models where continuum fields interact with
particles. For example, the two-temperature model (TTM) defines heat
transfer between atoms (particles) and electrons (continuum gas) where
spatial variations in the electron temperature are computed by finite
differences of a discretized heat equation on a regular grid. The
:doc:`fix ttm/grid <fix_ttm>` command uses the ``GridComm`` class
internally to perform its grid operations on a distributed grid
instead of the original :doc:`fix ttm <fix_ttm>` which uses a
replicated grid.

159
doc/src/Developer_par_neigh.rst Normal file
View File

@ -0,0 +1,159 @@
Neighbor lists
^^^^^^^^^^^^^^
To compute forces efficiently, each processor creates a Verlet-style
neighbor list which enumerates all pairs of atoms *i,j* (*i* = owned,
*j* = owned or ghost) with separation less than the applicable
neighbor list cutoff distance. In LAMMPS the neighbor lists are stored
in a multiple-page data structure; each page is a contiguous chunk of
memory which stores vectors of neighbor atoms *j* for many *i* atoms.
This allows pages to be incrementally allocated or deallocated in blocks
as needed. Neighbor lists typically consume the most memory of any data
structure in LAMMPS. The neighbor list is rebuilt (from scratch) once
every few timesteps, then used repeatedly each step for force or other
computations. The neighbor cutoff distance is :math:`R_n = R_f +
\Delta_s`, where :math:`R_f` is the (largest) force cutoff defined by
the interatomic potential for computing short-range pairwise or manybody
forces and :math:`\Delta_s` is a "skin" distance that allows the list to
be used for multiple steps assuming that atoms do not move very far
between consecutive time steps. Typically the code triggers
reneighboring when any atom has moved half the skin distance since the
last reneighboring; this and other options of the neighbor list rebuild
can be adjusted with the :doc:`neigh_modify <neigh_modify>` command.
On steps when reneighboring is performed, atoms which have moved outside
their owning processor's sub-domain are first migrated to new processors
via communication. Periodic boundary conditions are also (only)
enforced on these steps to ensure each atom is re-assigned to the
correct processor. After migration, the atoms owned by each processor
are stored in a contiguous vector. Periodically each processor
spatially sorts owned atoms within its vector to reorder it for improved
cache efficiency in force computations and neighbor list building. For
that atoms are spatially binned and then reordered so that atoms in the
same bin are adjacent in the vector. Atom sorting can be disabled or
its settings modified with the :doc:`atom_modify <atom_modify>` command.
.. _neighbor-stencil:
.. figure:: img/neigh-stencil.png
:align: center
neighbor list stencils
A 2d simulation sub-domain (thick black line) and the corresponding
ghost atom cutoff region (dashed blue line) for both orthogonal
(left) and triclinic (right) domains. A regular grid of neighbor
bins (thin lines) overlays the entire simulation domain and need not
align with sub-domain boundaries; only the portion overlapping the
augmented sub-domain is shown. In the triclinic case it overlaps the
bounding box of the tilted rectangle. The blue- and red-shaded bins
represent a stencil of bins searched to find neighbors of a particular
atom (black dot).
To build a local neighbor list in linear time, the simulation domain is
overlaid (conceptually) with a regular 3d (or 2d) grid of neighbor bins,
as shown in the :ref:`neighbor-stencil` figure for 2d models and a
single MPI processor's sub-domain. Each processor stores a set of
neighbor bins which overlap its sub-domain extended by the neighbor
cutoff distance :math:`R_n`. As illustrated, the bins need not align
with processor boundaries; an integer number in each dimension is fit to
the size of the entire simulation box.
Most often LAMMPS builds what it calls a "half" neighbor list where
each *i,j* neighbor pair is stored only once, with either atom *i* or
*j* as the central atom. The build can be done efficiently by using a
pre-computed "stencil" of bins around a central origin bin which
contains the atom whose neighbors are being searched for. A stencil
is simply a list of integer offsets in *x,y,z* of nearby bins
surrounding the origin bin which are close enough to contain any
neighbor atom *j* within a distance :math:`R_n` from any atom *i* in the
origin bin. Note that for a half neighbor list, the stencil can be
asymmetric since each atom only need store half its nearby neighbors.
These stencils are illustrated in the figure for a half list and a bin
size of :math:`\frac{1}{2} R_n`. There are 13 red+blue stencil bins in
2d (for the orthogonal case, 15 for triclinic). In 3d there would be
63, 13 in the plane of bins that contain the origin bin and 25 in each
of the two planes above it in the *z* direction (75 for triclinic). The
reason the triclinic stencil has extra bins is because the bins tile the
bounding box of the entire triclinic domain and thus are not periodic
with respect to the simulation box itself. The stencil and logic for
determining which *i,j* pairs to include in the neighbor list are
altered slightly to account for this.
To build a neighbor list, a processor first loops over its "owned" plus
"ghost" atoms and assigns each to a neighbor bin. This uses an integer
vector to create a linked list of atom indices within each bin. It then
performs a triply-nested loop over its owned atoms *i*, the stencil of
bins surrounding atom *i*'s bin, and the *j* atoms in each stencil bin
(including ghost atoms). If the distance :math:`r_{ij} < R_n`, then
atom *j* is added to the vector of atom *i*'s neighbors.
Here are additional details about neighbor list build options LAMMPS
supports:
- The choice of bin size is an option; a size half of :math:`R_n` has
been found to be optimal for many typical cases. Smaller bins incur
additional overhead to loop over; larger bins require more distance
calculations. Note that for smaller bin sizes, the 2d stencil in the
figure would be more semi-circular in shape (hemispherical in 3d),
with bins near the corners of the square eliminated due to their
distance from the origin bin.
- Depending on the interatomic potential(s) and other commands used in
an input script, multiple neighbor lists and stencils with different
attributes may be needed. This includes lists with different cutoff
distances, e.g. for force computation versus occasional diagnostic
computations such as a radial distribution function, or for the
r-RESPA time integrator which can partition pairwise forces by
distance into subsets computed at different time intervals. It
includes "full" lists (as opposed to half lists) where each *i,j* pair
appears twice, stored once with *i* and *j*, and which use a larger
symmetric stencil. It also includes lists with partial enumeration of
ghost atom neighbors. The full and ghost-atom lists are used by
various manybody interatomic potentials. Lists may also use different
criteria for inclusion of a pair interaction. Typically this simply
depends only on the distance between two atoms and the cutoff
distance. But for finite-size coarse-grained particles with
individual diameters (e.g. polydisperse granular particles), it can
also depend on the diameters of the two particles.
- When using :doc:`pair style hybrid <pair_hybrid>` multiple sub-lists
of the master neighbor list for the full system need to be generated,
one for each sub-style, which contains only the *i,j* pairs needed to
compute interactions between subsets of atoms for the corresponding
potential. This means not all *i* or *j* atoms owned by a processor
are included in a particular sub-list.
- Some models use different cutoff lengths for pairwise interactions
between different kinds of particles which are stored in a single
neighbor list. One example is a solvated colloidal system with large
colloidal particles where colloid/colloid, colloid/solvent, and
solvent/solvent interaction cutoffs can be dramatically different.
Another is a model of polydisperse finite-size granular particles;
pairs of particles interact only when they are in contact with each
other. Mixtures with particle size ratios as high as 10-100x may be
used to model realistic systems. Efficient neighbor list building
algorithms for these kinds of systems are available in LAMMPS. They
include a method which uses different stencils for different cutoff
lengths and trims the stencil to only include bins that straddle the
cutoff sphere surface. More recently a method which uses both
multiple stencils and multiple bin sizes was developed; it builds
neighbor lists efficiently for systems with particles of any size
ratio, though other considerations (timestep size, force computations)
may limit the ability to model systems with huge polydispersity.
- For small and sparse systems and as a fallback method, LAMMPS also
supports neighbor list construction without binning by using a full
:math:`O(N^2)` loop over all *i,j* atom pairs in a sub-domain when
using the :doc:`neighbor nsq <neighbor>` command.
- Dependent on the "pair" setting of the :doc:`newton <newton>` command,
the "half" neighbor lists may contain **all** pairs of atoms where
atom *j* is a ghost atom (i.e. when the newton pair setting is *off*)
For the newton pair *on* setting the atom *j* is only added to the
list if its *z* coordinate is larger, or if equal the *y* coordinate
is larger, and that is equal, too, the *x* coordinate is larger. For
homogeneously dense systems that will result in picking neighbors from
a same size sector in always the same direction relative to the
"owned" atom and thus it should lead to similar length neighbor lists
and thus reduce the chance of a load imbalance.

114
doc/src/Developer_par_openmp.rst Normal file
View File

@ -0,0 +1,114 @@
OpenMP Parallelism
^^^^^^^^^^^^^^^^^^
The styles in the INTEL, KOKKOS, and OPENMP package offer to use OpenMP
thread parallelism to predominantly distribute loops over local data
and thus follow an orthogonal parallelization strategy to the
decomposition into spatial domains used by the :doc:`MPI partitioning
<Developer_par_part>`. For clarity, this section discusses only the
implementation in the OPENMP package as it is the simplest. The INTEL
and KOKKOS package offer additional options and are more complex since
they support more features and different hardware like co-processors
or GPUs.
One of the key decisions when implementing the OPENMP package was to
keep the changes to the source code small, so that it would be easier to
maintain the code and keep it in sync with the non-threaded standard
implementation. this is achieved by a) making the OPENMP version a
derived class from the regular version (e.g. ``PairLJCutOMP`` from
``PairLJCut``) and overriding only methods that are multi-threaded or
need to be modified to support multi-threading (similar to what was done
in the OPT package), b) keeping the structure in the modified code very
similar so that side-by-side comparisons are still useful, and c)
offloading additional functionality and multi-thread support functions
into three separate classes ``ThrOMP``, ``ThrData``, and ``FixOMP``.
``ThrOMP`` provides additional, multi-thread aware functionality not
available in the corresponding base class (e.g. ``Pair`` for
``PairLJCutOMP``) like multi-thread aware variants of the "tally"
functions. Those functions are made available through multiple
inheritance so those new functions have to have unique names to avoid
ambiguities; typically ``_thr`` is appended to the name of the function.
``ThrData`` is a classes that manages per-thread data structures.
It is used instead of extending the corresponding storage to per-thread
arrays to avoid slowdowns due to "false sharing" when multiple threads
update adjacent elements in an array and thus force the CPU cache lines
to be reset and re-fetched. ``FixOMP`` finally manages the "multi-thread
state" like settings and access to per-thread storage, it is activated
by the :doc:`package omp <package>` command.
Avoiding data races
"""""""""""""""""""
A key problem when implementing thread parallelism in an MD code is
to avoid data races when updating accumulated properties like forces,
energies, and stresses. When interactions are computed, they always
involve multiple atoms and thus there are race conditions when multiple
threads want to update per-atom data of the same atoms. Five possible
strategies have been considered to avoid this:
1) restructure the code so that there is no overlapping access possible
when computing in parallel, e.g. by breaking lists into multiple
parts and synchronizing threads in between.
2) have each thread be "responsible" for a specific group of atoms and
compute these interactions multiple times, once on each thread that
is responsible for a given atom and then have each thread only update
the properties of this atom.
3) use mutexes around functions and regions of code where the data race
could happen
4) use atomic operations when updating per-atom properties
5) use replicated per-thread data structures to accumulate data without
conflicts and then use a reduction to combine those results into the
data structures used by the regular style.
Option 5 was chosen for the OPENMP package because it would retain the
performance for the case of 1 thread and the code would be more
maintainable. Option 1 would require extensive code changes,
particularly to the neighbor list code; options 2 would have incurred a
2x or more performance penalty for the serial case; option 3 causes
significant overhead and would enforce serialization of operations in
inner loops and thus defeat the purpose of multi-threading; option 4
slows down the serial case although not quite as bad as option 2. The
downside of option 5 is that the overhead of the reduction operations
grows with the number of threads used, so there would be a crossover
point where options 2 or 4 would result in faster executing. That is
why option 2 for example is used in the GPU package because a GPU is a
processor with a massive number of threads. However, since the MPI
parallelization is generally more effective for typical MD systems, the
expectation is that thread parallelism is only used for a smaller number
of threads (2-8). At the time of its implementation, that number was
equivalent to the number of CPU cores per CPU socket on high-end
supercomputers.
Thus arrays like the force array are dimensioned to the number of atoms
times the number of threads when enabling OpenMP support and inside the
compute functions a pointer to a different chunk is obtained by each thread.
Similarly, accumulators like potential energy or virial are kept in
per-thread instances of the ``ThrData`` class and then only reduced and
stored in their global counterparts at the end of the force computation.
Loop scheduling
"""""""""""""""
Multi-thread parallelization is applied by distributing (outer) loops
statically across threads. Typically this would be the loop over local
atoms *i* when processing *i,j* pairs of atoms from a neighbor list.
The design of the neighbor list code results in atoms having a similar
number of neighbors for homogeneous systems and thus load imbalances
across threads are not common and typically happen for systems where
also the MPI parallelization would be unbalanced, which would typically
have a more pronounced impact on the performance. This same loop
scheduling scheme can also be applied to the reduction operations on
per-atom data to try and reduce the overhead of the reduction operation.
Neighbor list parallelization
"""""""""""""""""""""""""""""
In addition to the parallelization of force computations, also the
generation of the neighbor lists is parallelized. As explained
previously, neighbor lists are built by looping over "owned" atoms and
storing the neighbors in "pages". In the OPENMP variants of the
neighbor list code, each thread operates on a different chunk of "owned"
atoms and allocates and fills its own set of pages with neighbor list
data. This is achieved by each thread keeping its own instance of the
:cpp:class:`MyPage <LAMMPS_NS::MyPage>` page allocator class.

89
doc/src/Developer_par_part.rst Normal file
View File

@ -0,0 +1,89 @@
Partitioning
^^^^^^^^^^^^
The underlying spatial decomposition strategy used by LAMMPS for
distributed-memory parallelism is set with the :doc:`comm_style command
<comm_style>` and can be either "brick" (a regular grid) or "tiled".
.. _domain-decomposition:
.. figure:: img/domain-decomp.png
:align: center
domain decomposition
This figure shows the different kinds of domain decomposition used
for MPI parallelization: "brick" on the left with an orthogonal
(left) and a triclinic (middle) simulation domain, and a "tiled"
decomposition (right). The black lines show the division into
sub-domains and the contained atoms are "owned" by the corresponding
MPI process. The green dashed lines indicate how sub-domains are
extended with "ghost" atoms up to the communication cutoff distance.
The LAMMPS simulation box is a 3d or 2d volume, which can be orthogonal
or triclinic in shape, as illustrated in the :ref:`domain-decomposition`
figure for the 2d case. Orthogonal means the box edges are aligned with
the *x*, *y*, *z* Cartesian axes, and the box faces are thus all
rectangular. Triclinic allows for a more general parallelepiped shape
in which edges are aligned with three arbitrary vectors and the box
faces are parallelograms. In each dimension box faces can be periodic,
or non-periodic with fixed or shrink-wrapped boundaries. In the fixed
case, atoms which move outside the face are deleted; shrink-wrapped
means the position of the box face adjusts continuously to enclose all
the atoms.
For distributed-memory MPI parallelism, the simulation box is spatially
decomposed (partitioned) into non-overlapping sub-domains which fill the
box. The default partitioning, "brick", is most suitable when atom
density is roughly uniform, as shown in the left-side images of the
:ref:`domain-decomposition` figure. The sub-domains comprise a regular
grid and all sub-domains are identical in size and shape. Both the
orthogonal and triclinic boxes can deform continuously during a
simulation, e.g. to compress a solid or shear a liquid, in which case
the processor sub-domains likewise deform.
For models with non-uniform density, the number of particles per
processor can be load-imbalanced with the default partitioning. This
reduces parallel efficiency, as the overall simulation rate is limited
by the slowest processor, i.e. the one with the largest computational
load. For such models, LAMMPS supports multiple strategies to reduce
the load imbalance:
- The processor grid decomposition is by default based on the simulation
cell volume and tries to optimize the volume to surface ratio for the sub-domains.
This can be changed with the :doc:`processors command <processors>`.
- The parallel planes defining the size of the sub-domains can be shifted
with the :doc:`balance command <balance>`. Which can be done in addition
to choosing a more optimal processor grid.
- The recursive bisectioning algorithm in combination with the "tiled"
communication style can produce a partitioning with equal numbers of
particles in each sub-domain.
.. |decomp1| image:: img/decomp-regular.png
:width: 24%
.. |decomp2| image:: img/decomp-processors.png
:width: 24%
.. |decomp3| image:: img/decomp-balance.png
:width: 24%
.. |decomp4| image:: img/decomp-rcb.png
:width: 24%
|decomp1| |decomp2| |decomp3| |decomp4|
The pictures above demonstrate different decompositions for a 2d system
with 12 MPI ranks. The atom colors indicate the load imbalance of each
sub-domain with green being optimal and red the least optimal.
Due to the vacuum in the system, the default decomposition is unbalanced
with several MPI ranks without atoms (left). By forcing a 1x12x1
processor grid, every MPI rank does computations now, but number of
atoms per sub-domain is still uneven and the thin slice shape increases
the amount of communication between sub-domains (center left). With a
2x6x1 processor grid and shifting the sub-domain divisions, the load
imbalance is further reduced and the amount of communication required
between sub-domains is less (center right). And using the recursive
bisectioning leads to further improved decomposition (right).

28
doc/src/Developer_parallel.rst Normal file
View File

@ -0,0 +1,28 @@
Parallel algorithms
-------------------
LAMMPS is designed to enable running simulations in parallel using the
MPI parallel communication standard with distributed data via domain
decomposition. The parallelization aims to be efficient result in good
strong scaling (= good speedup for the same system) and good weak
scaling (= the computational cost of enlarging the system is
proportional to the system size). Additional parallelization using GPUs
or OpenMP can also be applied within the sub-domain assigned to an MPI
process. For clarity, most of the following illustrations show the 2d
simulation case. The underlying algorithms in those cases, however,
apply to both 2d and 3d cases equally well.
.. note::
The text and most of the figures in this chapter were adapted
for the manual from the section on parallel algorithms in the
:ref:`new LAMMPS paper <lammps_paper>`.
.. toctree::
:maxdepth: 1
Developer_par_part
Developer_par_comm
Developer_par_neigh
Developer_par_long
Developer_par_openmp

155
doc/src/Developer_platform.rst Normal file
View File

@ -0,0 +1,155 @@
Platform abstraction functions
------------------------------
The ``platform`` sub-namespace inside the ``LAMMPS_NS`` namespace
provides a collection of wrapper and convenience functions and utilities
that perform common tasks for which platform specific code would be
required or for which a more high-level abstraction would be convenient
and reduce duplicated code. This reduces redundant implementations and
encourages consistent behavior and thus has some overlap with the
:doc:`"utils" sub-namespace <Developer_utils>`.
Time functions
^^^^^^^^^^^^^^
.. doxygenfunction:: cputime
:project: progguide
.. doxygenfunction:: walltime
:project: progguide
.. doxygenfunction:: usleep
:project: progguide
Platform information functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: os_info
:project: progguide
.. doxygenfunction:: compiler_info
:project: progguide
.. doxygenfunction:: cxx_standard
:project: progguide
.. doxygenfunction:: openmp_standard
:project: progguide
.. doxygenfunction:: mpi_vendor
:project: progguide
.. doxygenfunction:: mpi_info
:project: progguide
.. doxygenfunction:: compress_info
:project: progguide
File and path functions and global constants
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenvariable:: filepathsep
:project: progguide
.. doxygenvariable:: pathvarsep
:project: progguide
.. doxygenfunction:: guesspath
:project: progguide
.. doxygenfunction:: path_basename
:project: progguide
.. doxygenfunction:: path_join
:project: progguide
.. doxygenfunction:: file_is_readable
:project: progguide
.. doxygenfunction:: is_console
:project: progguide
.. doxygenfunction:: path_is_directory
:project: progguide
.. doxygenfunction:: current_directory
:project: progguide
.. doxygenfunction:: list_directory
:project: progguide
.. doxygenfunction:: chdir
:project: progguide
.. doxygenfunction:: mkdir
:project: progguide
.. doxygenfunction:: rmdir
:project: progguide
.. doxygenfunction:: unlink
:project: progguide
Standard I/O function wrappers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenvariable:: END_OF_FILE
:project: progguide
.. doxygenfunction:: ftell
:project: progguide
.. doxygenfunction:: fseek
:project: progguide
.. doxygenfunction:: ftruncate
:project: progguide
.. doxygenfunction:: popen
:project: progguide
.. doxygenfunction:: pclose
:project: progguide
Environment variable functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: putenv
:project: progguide
.. doxygenfunction:: unsetenv
:project: progguide
.. doxygenfunction:: list_pathenv
:project: progguide
.. doxygenfunction:: find_exe_path
:project: progguide
Dynamically loaded object or library functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: dlopen
:project: progguide
.. doxygenfunction:: dlclose
:project: progguide
.. doxygenfunction:: dlsym
:project: progguide
.. doxygenfunction:: dlerror
:project: progguide
Compressed file I/O functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: has_compress_extension
:project: progguide
.. doxygenfunction:: compressed_read
:project: progguide
.. doxygenfunction:: compressed_write
:project: progguide

134
doc/src/Developer_utils.rst
View File

@ -7,7 +7,9 @@ a collection of convenience functions and utilities that perform common
tasks that are required repeatedly throughout the LAMMPS code like
reading or writing to files with error checking or translation of
strings into specific types of numbers with checking for validity. This
reduces redundant implementations and encourages consistent behavior.
reduces redundant implementations and encourages consistent behavior and
thus has some overlap with the :doc:`"platform" sub-namespace
<Developer_platform>`.
I/O with status check and similar functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -19,18 +21,21 @@ In that case, the functions will stop with an error message, indicating
the name of the problematic file, if possible unless the *error* argument
is a NULL pointer.
The :cpp:func:`fgets_trunc` function will work similar for ``fgets()``
but it will read in a whole line (i.e. until the end of line or end
of file), but store only as many characters as will fit into the buffer
including a final newline character and the terminating NULL byte.
If the line in the file is longer it will thus be truncated in the buffer.
This function is used by :cpp:func:`read_lines_from_file` to read individual
lines but make certain they follow the size constraints.
The :cpp:func:`utils::fgets_trunc() <LAMMPS_NS::utils::fgets_trunc>`
function will work similar for ``fgets()`` but it will read in a whole
line (i.e. until the end of line or end of file), but store only as many
characters as will fit into the buffer including a final newline
character and the terminating NULL byte. If the line in the file is
longer it will thus be truncated in the buffer. This function is used
by :cpp:func:`utils::read_lines_from_file()
<LAMMPS_NS::utils::read_lines_from_file>` to read individual lines but
make certain they follow the size constraints.
The :cpp:func:`read_lines_from_file` function will read the requested
number of lines of a maximum length into a buffer and will return 0
if successful or 1 if not. It also guarantees that all lines are
terminated with a newline character and the entire buffer with a
The :cpp:func:`utils::read_lines_from_file()
<LAMMPS_NS::utils::read_lines_from_file>` function will read the
requested number of lines of a maximum length into a buffer and will
return 0 if successful or 1 if not. It also guarantees that all lines
are terminated with a newline character and the entire buffer with a
NULL character.
----------
@ -54,33 +59,54 @@ String to number conversions with validity check
These functions should be used to convert strings to numbers. They are
are strongly preferred over C library calls like ``atoi()`` or
``atof()`` since they check if the **entire** provided string is a valid
``atof()`` since they check if the **entire** string is a valid
(floating-point or integer) number, and will error out instead of
silently returning the result of a partial conversion or zero in cases
where the string is not a valid number. This behavior allows to more
easily detect typos or issues when processing input files.
where the string is not a valid number. This behavior improves
detecting typos or issues when processing input files.
Similarly the :cpp:func:`utils::logical() <LAMMPS_NS::utils::logical>` function
will convert a string into a boolean and will only accept certain words.
The *do_abort* flag should be set to ``true`` in case this function
is called only on a single MPI rank, as that will then trigger the
a call to ``Error::one()`` for errors instead of ``Error::all()``
and avoids a "hanging" calculation when run in parallel.
Please also see :cpp:func:`is_integer() <LAMMPS_NS::utils::is_integer>`
and :cpp:func:`is_double() <LAMMPS_NS::utils::is_double>` for testing
Please also see :cpp:func:`utils::is_integer() <LAMMPS_NS::utils::is_integer>`
and :cpp:func:`utils::is_double() <LAMMPS_NS::utils::is_double>` for testing
strings for compliance without conversion.
----------
.. doxygenfunction:: numeric
.. doxygenfunction:: numeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: inumeric
.. doxygenfunction:: numeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: bnumeric
.. doxygenfunction:: inumeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: tnumeric
.. doxygenfunction:: inumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: bnumeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: bnumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: tnumeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: tnumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: logical(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: logical(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
:project: progguide
@ -95,6 +121,12 @@ and parsing files or arguments.
.. doxygenfunction:: strdup
:project: progguide
.. doxygenfunction:: lowercase
:project: progguide
.. doxygenfunction:: uppercase
:project: progguide
.. doxygenfunction:: trim
:project: progguide
@ -137,21 +169,6 @@ and parsing files or arguments.
.. doxygenfunction:: is_double
:project: progguide
File and path functions
^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: guesspath
:project: progguide
.. doxygenfunction:: path_basename
:project: progguide
.. doxygenfunction:: path_join
:project: progguide
.. doxygenfunction:: file_is_readable
:project: progguide
Potential file functions
^^^^^^^^^^^^^^^^^^^^^^^^
@ -191,6 +208,9 @@ Convenience functions
.. doxygenfunction:: logmesg(LAMMPS *lmp, const std::string &mesg)
:project: progguide
.. doxygenfunction:: flush_buffers(LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: getsyserror
:project: progguide
@ -203,9 +223,15 @@ Convenience functions
.. doxygenfunction:: date2num
:project: progguide
.. doxygenfunction:: current_date
:project: progguide
Customized standard functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: binary_search
:project: progguide
.. doxygenfunction:: merge_sort
:project: progguide
@ -317,11 +343,11 @@ This code example should produce the following output:
.. doxygenclass:: LAMMPS_NS::InvalidIntegerException
:project: progguide
:members: what
:members:
.. doxygenclass:: LAMMPS_NS::InvalidFloatException
:project: progguide
:members: what
:members:
----------
@ -370,21 +396,26 @@ A typical code segment would look like this:
----------
.. _file-reader-classes:
File reader classes
-------------------
The purpose of the file reader classes is to simplify the recurring task
of reading and parsing files. They can use the
:cpp:class:`LAMMPS_NS::ValueTokenizer` class to process the read in
text. The :cpp:class:`LAMMPS_NS::TextFileReader` is a more general
version while :cpp:class:`LAMMPS_NS::PotentialFileReader` is specialized
to implement the behavior expected for looking up and reading/parsing
files with potential parameters in LAMMPS. The potential file reader
class requires a LAMMPS instance, requires to be run on MPI rank 0 only,
will use the :cpp:func:`LAMMPS_NS::utils::get_potential_file_path`
function to look up and open the file, and will call the
:cpp:class:`LAMMPS_NS::Error` class in case of failures to read or to
convert numbers, so that LAMMPS will be aborted.
:cpp:class:`ValueTokenizer <LAMMPS_NS::ValueTokenizer>` class to process
the read in text. The :cpp:class:`TextFileReader
<LAMMPS_NS::TextFileReader>` is a more general version while
:cpp:class:`PotentialFileReader <LAMMPS_NS::PotentialFileReader>` is
specialized to implement the behavior expected for looking up and
reading/parsing files with potential parameters in LAMMPS. The
potential file reader class requires a LAMMPS instance, requires to be
run on MPI rank 0 only, will use the
:cpp:func:`utils::get_potential_file_path
<LAMMPS_NS::utils::get_potential_file_path>` function to look up and
open the file, and will call the :cpp:class:`LAMMPS_NS::Error` class in
case of failures to read or to convert numbers, so that LAMMPS will be
aborted.
.. code-block:: C++
:caption: Use of PotentialFileReader class in pair style coul/streitz
@ -459,10 +490,10 @@ provided, as that is used to determine whether a new page of memory
must be used.
The :cpp:class:`MyPage <LAMMPS_NS::MyPage>` class offers two ways to
reserve a chunk: 1) with :cpp:func:`get() <LAMMPS_NS::MyPage::get>` the
chunk size needs to be known in advance, 2) with :cpp:func:`vget()
reserve a chunk: 1) with :cpp:func:`MyPage::get() <LAMMPS_NS::MyPage::get>` the
chunk size needs to be known in advance, 2) with :cpp:func:`MyPage::vget()
<LAMMPS_NS::MyPage::vget>` a pointer to the next chunk is returned, but
its size is registered later with :cpp:func:`vgot()
its size is registered later with :cpp:func:`MyPage::vgot()
<LAMMPS_NS::MyPage::vgot>`.
.. code-block:: C++
@ -565,4 +596,3 @@ the communication buffers.
.. doxygenunion:: LAMMPS_NS::ubuf
:project: progguide

6
doc/src/Developer_write.rst
View File

@ -29,7 +29,9 @@ of code in the header before include guards:
.. code-block:: c
#ifdef FIX_CLASS
FixStyle(print/vel,FixPrintVel)
// clang-format off
FixStyle(print/vel,FixPrintVel);
// clang-format on
#else
/* the definition of the FixPrintVel class comes here */
...
@ -53,7 +55,7 @@ of each timestep. First of all, implement a constructor:
if (narg < 4)
error->all(FLERR,"Illegal fix print/vel command");
nevery = force->inumeric(FLERR,arg[3]);
nevery = utils::inumeric(FLERR,arg[3],false,lmp);
if (nevery <= 0)
error->all(FLERR,"Illegal fix print/vel command");
}

3
doc/src/Errors_debug.rst
View File

@ -40,11 +40,10 @@ We use it to show how to identify the origin of a segmentation fault.
After recompiling LAMMPS and running the input you should get something like this:
.. code-block:
.. code-block::
$ ./lmp -in in.melt
LAMMPS (19 Mar 2020)
OMP_NUM_THREADS environment is not set. Defaulting to 1 thread. (src/comm.cpp:94)
using 1 OpenMP thread(s) per MPI task
Lattice spacing in x,y,z = 1.6796 1.6796 1.6796
Created orthogonal box = (0 0 0) to (16.796 16.796 16.796)

22
doc/src/Errors_messages.rst
View File

@ -714,7 +714,7 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
*Cannot create/grow a vector/array of pointers for %s*
LAMMPS code is making an illegal call to the templated memory
allocaters, to create a vector or array of pointers.
allocators, to create a vector or array of pointers.
*Cannot create_atoms after reading restart file with per-atom info*
The per-atom info was stored to be used when by a fix that you may
@ -1941,6 +1941,9 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
*Compute ID for fix numdiff does not exist*
Self-explanatory.
*Compute ID for fix numdiff/virial does not exist*
Self-explanatory.
*Compute ID for fix store/state does not exist*
Self-explanatory.
@ -3796,6 +3799,10 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
Self-explanatory. Efficient loop over all atoms for numerical
difference requires consecutive atom IDs.
*Fix numdiff/virial must use group all*
Virial contributions computed by this fix are
computed on all atoms.
*Fix nve/asphere requires extended particles*
This fix can only be used for particles with a shape setting.
@ -7772,9 +7779,6 @@ keyword to allow for additional bonds to be formed
The system size must fit in a 32-bit integer to use this dump
style.
*Too many atoms to dump sort*
Cannot sort when running with more than 2\^31 atoms.
*Too many elements extracted from MEAM library.*
Increase 'maxelt' in meam.h and recompile.
@ -7879,19 +7883,19 @@ keyword to allow for additional bonds to be formed
*Unexpected end of -reorder file*
Self-explanatory.
*Unexpected empty line in AngleCoeffs section*
*Unexpected empty line in Angle Coeffs section*
Read a blank line where there should be coefficient data.
*Unexpected empty line in BondCoeffs section*
*Unexpected empty line in Bond Coeffs section*
Read a blank line where there should be coefficient data.
*Unexpected empty line in DihedralCoeffs section*
*Unexpected empty line in Dihedral Coeffs section*
Read a blank line where there should be coefficient data.
*Unexpected empty line in ImproperCoeffs section*
*Unexpected empty line in Improper Coeffs section*
Read a blank line where there should be coefficient data.
*Unexpected empty line in PairCoeffs section*
*Unexpected empty line in Pair Coeffs section*
Read a blank line where there should be coefficient data.
*Unexpected end of custom file*

2
doc/src/Errors_warnings.rst
View File

@ -416,7 +416,7 @@ This will most likely cause errors in kinetic fluctuations.
not defined for the specified atom style.
*Molecule has bond topology but no special bond settings*
This means the bonded atoms will not be excluded in pair-wise
This means the bonded atoms will not be excluded in pairwise
interactions.
*Molecule template for create_atoms has multiple molecules*

8
doc/src/Examples.rst
View File

@ -27,7 +27,7 @@ be quickly post-processed into a movie using commands described on the
:doc:`dump image <dump_image>` doc page.
Animations of many of the examples can be viewed on the Movies section
of the `LAMMPS web site <https://www.lammps.org/movies.html>`_.
of the `LAMMPS website <https://www.lammps.org/movies.html>`_.
There are two kinds of sub-directories in the examples folder. Lower
case named directories contain one or a few simple, quick-to-run
@ -80,7 +80,7 @@ Lowercase directories
+-------------+------------------------------------------------------------------+
| friction | frictional contact of spherical asperities between 2d surfaces |
+-------------+------------------------------------------------------------------+
| gcmc | Grand Canonical Monte Carlo (GCMC) via the fix gcmc command |
| mc | Monte Carlo features via fix gcmc, widom and other commands |
+-------------+------------------------------------------------------------------+
| granregion | use of fix wall/region/gran as boundary on granular particles |
+-------------+------------------------------------------------------------------+
@ -169,7 +169,7 @@ Running the simulation produces the files *dump.indent* and
*log.lammps*\ . You can visualize the dump file of snapshots with a
variety of third-party tools highlighted on the
`Visualization <https://www.lammps.org/viz.html>`_ page of the LAMMPS
web site.
website.
If you uncomment the :doc:`dump image <dump_image>` line(s) in the input
script a series of JPG images will be produced by the run (assuming
@ -205,7 +205,7 @@ Uppercase directories
+------------+--------------------------------------------------------------------------------------------------+
| KAPPA | compute thermal conductivity via several methods |
+------------+--------------------------------------------------------------------------------------------------+
| MC | using LAMMPS in a Monte Carlo mode to relax the energy of a system |
| MC-LOOP | using LAMMPS in a Monte Carlo mode to relax the energy of a system in a input script loop |
+------------+--------------------------------------------------------------------------------------------------+
| PACKAGES | examples for specific packages and contributed commands |
+------------+--------------------------------------------------------------------------------------------------+

5
doc/src/Howto_drude2.rst
View File

@ -491,11 +491,6 @@ NPT ensemble using Nose-Hoover thermostat:
**(Schroeder)** Schroeder and Steinhauser, J Chem Phys, 133,
154511 (2010).
.. _Jiang2:
**(Jiang)** Jiang, Hardy, Phillips, MacKerell, Schulten, and Roux,
J Phys Chem Lett, 2, 87-92 (2011).
.. _Thole2:
**(Thole)** Chem Phys, 59, 341 (1981).

134
doc/src/Howto_github.rst
View File

@ -7,11 +7,11 @@ LAMMPS GitHub tutorial
This document describes the process of how to use GitHub to integrate
changes or additions you have made to LAMMPS into the official LAMMPS
distribution. It uses the process of updating this very tutorial as
an example to describe the individual steps and options. You need to
be familiar with git and you may want to have a look at the
`git book <http://git-scm.com/book/>`_ to reacquaint yourself with some
of the more advanced git features used below.
distribution. It uses the process of updating this very tutorial as an
example to describe the individual steps and options. You need to be
familiar with git and you may want to have a look at the `git book
<http://git-scm.com/book/>`_ to familiarize yourself with some of the
more advanced git features used below.
As of fall 2016, submitting contributions to LAMMPS via pull requests
on GitHub is the preferred option for integrating contributed features
@ -37,15 +37,15 @@ username or e-mail address and password.
**Forking the repository**
To get changes into LAMMPS, you need to first fork the `lammps/lammps`
repository on GitHub. At the time of writing, *master* is the preferred
repository on GitHub. At the time of writing, *develop* is the preferred
target branch. Thus go to `LAMMPS on GitHub <https://github.com/lammps/lammps>`_
and make sure branch is set to "master", as shown in the figure below.
and make sure branch is set to "develop", as shown in the figure below.
.. image:: JPG/tutorial_branch.png
:align: center
If it is not, use the button to change it to *master*\ . Once it is, use the
fork button to create a fork.
If it is not, use the button to change it to *develop*. Once it is, use
the fork button to create a fork.
.. image:: JPG/tutorial_fork.png
:align: center
@ -64,11 +64,12 @@ LAMMPS development.
**Adding changes to your own fork**
Additions to the upstream version of LAMMPS are handled using *feature
branches*\ . For every new feature, a so-called feature branch is
branches*. For every new feature, a so-called feature branch is
created, which contains only those modification relevant to one specific
feature. For example, adding a single fix would consist of creating a
branch with only the fix header and source file and nothing else. It is
explained in more detail here: `feature branch workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow>`_.
explained in more detail here: `feature branch workflow
<https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow>`_.
**Feature branches**
@ -94,8 +95,8 @@ The above command copies ("clones") the git repository to your local
machine to a directory with the name you chose. If none is given, it will
default to "lammps". Typical names are "mylammps" or something similar.
You can use this local clone to make changes and
test them without interfering with the repository on GitHub.
You can use this local clone to make changes and test them without
interfering with the repository on GitHub.
To pull changes from upstream into this copy, you can go to the directory
and use git pull:
@ -103,28 +104,46 @@ and use git pull:
.. code-block:: bash
$ cd mylammps
$ git checkout master
$ git pull https://github.com/lammps/lammps
$ git checkout develop
$ git pull https://github.com/lammps/lammps develop
You can also add this URL as a remote:
.. code-block:: bash
$ git remote add lammps_upstream https://www.github.com/lammps/lammps
$ git remote add upstream https://www.github.com/lammps/lammps
At this point, you typically make a feature branch from the updated master
From then on you can update your upstream branches with:
.. code-block:: bash
$ git fetch upstream
and then refer to the upstream repository branches with
`upstream/develop` or `upstream/release` and so on.
At this point, you typically make a feature branch from the updated
branch for the feature you want to work on. This tutorial contains the
workflow that updated this tutorial, and hence we will call the branch
"github-tutorial-update":
.. code-block:: bash
$ git checkout -b github-tutorial-update master
$ git fetch upstream
$ git checkout -b github-tutorial-update upstream/develop
Now that we have changed branches, we can make our changes to our local
repository. Just remember that if you want to start working on another,
unrelated feature, you should switch branches!
.. note::
Committing changes to the *develop*, *release*, or *stable* branches
is strongly discouraged. While it may be convenient initially, it
will create more work in the long run. Various texts and tutorials
on using git effectively discuss the motivation for using feature
branches instead.
**After changes are made**
After everything is done, add the files to the branch and commit them:
@ -287,28 +306,32 @@ After each push, the automated checks are run again.
LAMMPS developers may add labels to your pull request to assign it to
categories (mostly for bookkeeping purposes), but a few of them are
important: needs_work, work_in_progress, test-for-regression, and
full-regression-test. The first two indicate, that your pull request
is not considered to be complete. With "needs_work" the burden is on
exclusively on you; while "work_in_progress" can also mean, that a
LAMMPS developer may want to add changes. Please watch the comments
to the pull requests. The two "test" labels are used to trigger
extended tests before the code is merged. This is sometimes done by
LAMMPS developers, if they suspect that there may be some subtle
side effects from your changes. It is not done by default, because
those tests are very time consuming.
important: *needs_work*, *work_in_progress*, *run_tests*,
*test_for_regression*, and *ready_for_merge*. The first two indicate,
that your pull request is not considered to be complete. With
"needs_work" the burden is on exclusively on you; while
"work_in_progress" can also mean, that a LAMMPS developer may want to
add changes. Please watch the comments to the pull requests. The two
"test" labels are used to trigger extended tests before the code is
merged. This is sometimes done by LAMMPS developers, if they suspect
that there may be some subtle side effects from your changes. It is not
done by default, because those tests are very time consuming. The
*ready_for_merge* label is usually attached when the LAMMPS developer
assigned to the pull request considers this request complete and to
trigger a final full test evaluation.
**Reviews**
As of Summer 2018, a pull request needs at least 1 approving review
from a LAMMPS developer with write access to the repository.
In case your changes touch code that certain developers are associated
with, they are auto-requested by the GitHub software. Those associations
are set in the file
`.github/CODEOWNERS <https://github.com/lammps/lammps/blob/master/.github/CODEOWNERS>`_
Thus if you want to be automatically notified to review when anybody
changes files or packages, that you have contributed to LAMMPS, you can
add suitable patterns to that file, or a LAMMPS developer may add you.
As of Fall 2021, a pull request needs to pass all automatic tests and at
least 1 approving review from a LAMMPS developer with write access to
the repository before it is eligible for merging. In case your changes
touch code that certain developers are associated with, they are
auto-requested by the GitHub software. Those associations are set in
the file `.github/CODEOWNERS
<https://github.com/lammps/lammps/blob/develop/.github/CODEOWNERS>`_ Thus
if you want to be automatically notified to review when anybody changes
files or packages, that **you** have contributed to LAMMPS, you can add
suitable patterns to that file, or a LAMMPS developer may add you.
Otherwise, you can also manually request reviews from specific developers,
or LAMMPS developers - in their assessment of your pull request - may
@ -329,7 +352,7 @@ LAMMPS developer (including him/herself) or c) Axel Kohlmeyer (akohlmey).
After the review, the developer can choose to implement changes directly
or suggest them to you.
* Case c) means that the pull request has been assigned to the developer
overseeing the merging of pull requests into the master branch.
overseeing the merging of pull requests into the *develop* branch.
In this case, Axel assigned the tutorial to Steve:
@ -351,11 +374,11 @@ Sometimes, however, you might not feel comfortable having other people
push changes into your own branch, or maybe the maintainers are not sure
their idea was the right one. In such a case, they can make changes,
reassign you as the assignee, and file a "reverse pull request", i.e.
file a pull request in your GitHub repository to include changes in the
branch, that you have submitted as a pull request yourself. In that
case, you can choose to merge their changes back into your branch,
possibly make additional changes or corrections and proceed from there.
It looks something like this:
file a pull request in **your** forked GitHub repository to include
changes in the branch, that you have submitted as a pull request
yourself. In that case, you can choose to merge their changes back into
your branch, possibly make additional changes or corrections and proceed
from there. It looks something like this:
.. image:: JPG/tutorial_reverse_pull_request.png
:align: center
@ -419,7 +442,7 @@ This merge also shows up on the lammps GitHub page:
**After a merge**
When everything is fine, the feature branch is merged into the master branch:
When everything is fine, the feature branch is merged into the *develop* branch:
.. image:: JPG/tutorial_merged.png
:align: center
@ -433,8 +456,8 @@ branch!
.. code-block:: bash
$ git checkout master
$ git pull master
$ git checkout develop
$ git pull https://github.com/lammps/lammps develop
$ git branch -d github-tutorial-update
If you do not pull first, it is not really a problem but git will warn
@ -442,6 +465,7 @@ you at the next statement that you are deleting a local branch that
was not yet fully merged into HEAD. This is because git does not yet
know your branch just got merged into LAMMPS upstream. If you
first delete and then pull, everything should still be fine.
You can display all branches that are fully merged by:
Finally, if you delete the branch locally, you might want to push this
to your remote(s) as well:
@ -453,14 +477,14 @@ to your remote(s) as well:
**Recent changes in the workflow**
Some changes to the workflow are not captured in this tutorial. For
example, in addition to the master branch, to which all new features
should be submitted, there is now also an "unstable" and a "stable"
branch; these have the same content as "master", but are only updated
after a patch release or stable release was made.
Furthermore, the naming of the patches now follow the pattern
"patch_<Day><Month><Year>" to simplify comparisons between releases.
Finally, all patches and submissions are subject to automatic testing
and code checks to make sure they at the very least compile.
example, in addition to the *develop* branch, to which all new features
should be submitted, there is also a *release* and a *stable* branch;
these have the same content as *develop*, but are only updated after a
patch release or stable release was made. Furthermore, the naming of
the patches now follow the pattern "patch_<Day><Month><Year>" to
simplify comparisons between releases. Finally, all patches and
submissions are subject to automatic testing and code checks to make
sure they at the very least compile.
A discussion of the LAMMPS developer GitHub workflow can be found in the file
`doc/github-development-workflow.md <https://github.com/lammps/lammps/blob/master/doc/github-development-workflow.md>`_
`doc/github-development-workflow.md <https://github.com/lammps/lammps/blob/develop/doc/github-development-workflow.md>`_

2
doc/src/Howto_pylammps.rst
View File

@ -545,6 +545,6 @@ Feedback and Contributing
-------------------------
If you find this Python interface useful, please feel free to provide feedback
and ideas on how to improve it to Richard Berger (richard.berger@temple.edu). We also
and ideas on how to improve it to Richard Berger (richard.berger@outlook.com). We also
want to encourage people to write tutorial style IPython notebooks showcasing LAMMPS usage
and maybe their latest research results.

80
doc/src/Howto_thermostat.rst
View File

@ -2,8 +2,8 @@ Thermostats
===========
Thermostatting means controlling the temperature of particles in an MD
simulation. :doc:`Barostatting <Howto_barostat>` means controlling the
pressure. Since the pressure includes a kinetic component due to
simulation. :doc:`Barostatting <Howto_barostat>` means controlling
the pressure. Since the pressure includes a kinetic component due to
particle velocities, both these operations require calculation of the
temperature. Typically a target temperature (T) and/or pressure (P)
is specified by the user, and the thermostat or barostat attempts to
@ -26,11 +26,13 @@ can be invoked via the *dpd/tstat* pair style:
* :doc:`pair_style dpd/tstat <pair_dpd>`
:doc:`Fix nvt <fix_nh>` only thermostats the translational velocity of
particles. :doc:`Fix nvt/sllod <fix_nvt_sllod>` also does this, except
that it subtracts out a velocity bias due to a deforming box and
integrates the SLLOD equations of motion. See the :doc:`Howto nemd <Howto_nemd>` page for further details. :doc:`Fix nvt/sphere <fix_nvt_sphere>` and :doc:`fix nvt/asphere <fix_nvt_asphere>` thermostat not only translation
velocities but also rotational velocities for spherical and aspherical
particles.
particles. :doc:`Fix nvt/sllod <fix_nvt_sllod>` also does this,
except that it subtracts out a velocity bias due to a deforming box
and integrates the SLLOD equations of motion. See the :doc:`Howto
nemd <Howto_nemd>` page for further details. :doc:`Fix nvt/sphere
<fix_nvt_sphere>` and :doc:`fix nvt/asphere <fix_nvt_asphere>`
thermostat not only translation velocities but also rotational
velocities for spherical and aspherical particles.
.. note::
@ -40,25 +42,31 @@ particles.
e.g. molecular systems. The latter can be tricky to do correctly.
DPD thermostatting alters pairwise interactions in a manner analogous
to the per-particle thermostatting of :doc:`fix langevin <fix_langevin>`.
to the per-particle thermostatting of :doc:`fix langevin
<fix_langevin>`.
Any of the thermostatting fixes can be instructed to use custom temperature
computes that remove bias which has two effects: first, the current
calculated temperature, which is compared to the requested target temperature,
is calculated with the velocity bias removed; second, the thermostat adjusts
only the thermal temperature component of the particle's velocities, which are
the velocities with the bias removed. The removed bias is then added back
to the adjusted velocities. See the doc pages for the individual
fixes and for the :doc:`fix_modify <fix_modify>` command for
instructions on how to assign a temperature compute to a
thermostatting fix. For example, you can apply a thermostat to only
the x and z components of velocity by using it in conjunction with
:doc:`compute temp/partial <compute_temp_partial>`. Of you could
thermostat only the thermal temperature of a streaming flow of
particles without affecting the streaming velocity, by using
:doc:`compute temp/profile <compute_temp_profile>`.
Any of the thermostatting fixes can be instructed to use custom
temperature computes that remove bias which has two effects: first,
the current calculated temperature, which is compared to the requested
target temperature, is calculated with the velocity bias removed;
second, the thermostat adjusts only the thermal temperature component
of the particle's velocities, which are the velocities with the bias
removed. The removed bias is then added back to the adjusted
velocities. See the doc pages for the individual fixes and for the
:doc:`fix_modify <fix_modify>` command for instructions on how to
assign a temperature compute to a thermostatting fix.
Below is a list of some custom temperature computes that can be used like that:
For example, you can apply a thermostat only to atoms in a spatial
region by using it in conjunction with :doc:`compute temp/region
<compute_temp_region>`. Or you can apply a thermostat to only the x
and z components of velocity by using it with :doc:`compute
temp/partial <compute_temp_partial>`. Of you could thermostat only
the thermal temperature of a streaming flow of particles without
affecting the streaming velocity, by using :doc:`compute temp/profile
<compute_temp_profile>`.
Below is a list of custom temperature computes that can be used like
that:
* :doc:`compute_temp_asphere`
* :doc:`compute_temp_body`
@ -72,8 +80,6 @@ Below is a list of some custom temperature computes that can be used like that:
* :doc:`compute_temp_rotate`
* :doc:`compute_temp_sphere`
.. note::
Only the nvt fixes perform time integration, meaning they update
@ -86,17 +92,17 @@ Below is a list of some custom temperature computes that can be used like that:
* :doc:`fix nve/sphere <fix_nve_sphere>`
* :doc:`fix nve/asphere <fix_nve_asphere>`
Thermodynamic output, which can be setup via the
:doc:`thermo_style <thermo_style>` command, often includes temperature
values. As explained on the page for the
:doc:`thermo_style <thermo_style>` command, the default temperature is
setup by the thermo command itself. It is NOT the temperature
associated with any thermostatting fix you have defined or with any
compute you have defined that calculates a temperature. The doc pages
for the thermostatting fixes explain the ID of the temperature compute
they create. Thus if you want to view these temperatures, you need to
specify them explicitly via the :doc:`thermo_style custom <thermo_style>` command. Or you can use the
:doc:`thermo_modify <thermo_modify>` command to re-define what
Thermodynamic output, which can be setup via the :doc:`thermo_style
<thermo_style>` command, often includes temperature values. As
explained on the page for the :doc:`thermo_style <thermo_style>`
command, the default temperature is setup by the thermo command
itself. It is NOT the temperature associated with any thermostatting
fix you have defined or with any compute you have defined that
calculates a temperature. The doc pages for the thermostatting fixes
explain the ID of the temperature compute they create. Thus if you
want to view these temperatures, you need to specify them explicitly
via the :doc:`thermo_style custom <thermo_style>` command. Or you can
use the :doc:`thermo_modify <thermo_modify>` command to re-define what
temperature compute is used for default thermodynamic output.
----------

56
doc/src/Install_git.rst
View File

@ -9,7 +9,8 @@ has several advantages:
command.
* You can create your own development branches to add code to LAMMPS.
* You can submit your new features back to GitHub for inclusion in
LAMMPS.
LAMMPS. For that you should first create your own :doc:`fork on
GitHub <Howto_github>`.
You must have `git <git_>`_ installed on your system to use the
commands explained below to communicate with the git servers on
@ -20,35 +21,56 @@ provides `limited support for subversion clients <svn_>`_.
As of October 2016, the official home of public LAMMPS development is
on GitHub. The previously advertised LAMMPS git repositories on
git.lammps.org and bitbucket.org are now deprecated or offline.
git.lammps.org and bitbucket.org are now offline or deprecated.
.. _git: https://git-scm.com
.. _svn: https://help.github.com/en/github/importing-your-projects-to-github/working-with-subversion-on-github
You can follow LAMMPS development on 3 different git branches:
You can follow the LAMMPS development on 3 different git branches:
* **stable** : this branch is updated with every stable release
* **unstable** : this branch is updated with every patch release
* **master** : this branch continuously follows ongoing development
* **stable** : this branch is updated from the *release* branch with
every stable release version and also has selected bug fixes and updates
back-ported from the *develop* branch
* **release** : this branch is updated with every patch release;
updates are always "fast forward" merges from *develop*
* **develop** : this branch follows the ongoing development and
is updated with every merge commit of a pull request
To access the git repositories on your box, use the clone command to
create a local copy of the LAMMPS repository with a command like:
.. code-block:: bash
$ git clone -b unstable https://github.com/lammps/lammps.git mylammps
$ git clone -b release https://github.com/lammps/lammps.git mylammps
where "mylammps" is the name of the directory you wish to create on
your machine and "unstable" is one of the 3 branches listed above.
your machine and "release" is one of the 3 branches listed above.
(Note that you actually download all 3 branches; you can switch
between them at any time using "git checkout <branch name>".)
.. admonition:: Saving time and disk space when using ``git clone``
The complete git history of the LAMMPS project is quite large because
it contains the entire commit history of the project since fall 2006,
which includes the time when LAMMPS was managed with subversion.
This includes a few commits that have added and removed some large
files (mostly by accident). If you do not need access to the entire
commit history (most people don't), you can speed up the "cloning"
process and reduce local disk space requirements by using the
*--depth* git command line flag. That will create a "shallow clone"
of the repository containing only a subset of the git history. Using
a depth of 1000 is usually sufficient to include the head commits of
the *develop* and the *release* branches. To include the head commit
of the *stable* branch you may need a depth of up to 10000. If you
later need more of the git history, you can always convert the
shallow clone into a "full clone".
Once the command completes, your directory will contain the same files
as if you unpacked a current LAMMPS tarball, with the exception, that
the HTML documentation files are not included. They can be fetched
from the LAMMPS website by typing ``make fetch`` in the doc directory.
Or they can be generated from the content provided in doc/src by
typing ``make html`` from the doc directory.
Or they can be generated from the content provided in ``doc/src`` by
typing ``make html`` from the ``doc`` directory.
After initial cloning, as bug fixes and new features are added to
LAMMPS you can stay up-to-date by typing the following git commands
@ -56,9 +78,9 @@ from within the "mylammps" directory:
.. code-block:: bash
$ git checkout unstable # not needed if you always stay in this branch
$ git checkout stable # use one of these 3 checkout commands
$ git checkout master # to choose the branch to follow
$ git checkout release # not needed if you always stay in this branch
$ git checkout stable # use one of these 3 checkout commands
$ git checkout develop # to choose the branch to follow
$ git pull
Doing a "pull" will not change any files you have added to the LAMMPS
@ -81,7 +103,7 @@ Stable versions and what tagID to use for a particular stable version
are discussed on `this page <https://www.lammps.org/bug.html#version>`_.
Note that this command will print some warnings, because in order to get
back to the latest revision and to be able to update with ``git pull``
again, you will need to do ``git checkout unstable`` (or
again, you will need to do ``git checkout release`` (or
check out any other desired branch) first.
Once you have updated your local files with a ``git pull`` (or ``git
@ -137,9 +159,9 @@ changed. How to do this depends on the build system you are using.
.. admonition:: Git protocols
:class: note
The servers at github.com support the "git://" and "https://" access
protocols for anonymous, read-only access. If you have a suitably
configured GitHub account, you may also use SSH protocol with the
The servers at github.com support the "https://" access protocol for
anonymous, read-only access. If you have a suitably configured GitHub
account, you may also use SSH protocol with the
URL "git@github.com:lammps/lammps.git".
The LAMMPS GitHub project is currently managed by Axel Kohlmeyer

2
doc/src/Install_windows.rst
View File

@ -12,7 +12,7 @@ Note that each installer package has a date in its name, which
corresponds to the LAMMPS version of the same date. Installers for
current and older versions of LAMMPS are available. 32-bit and 64-bit
installers are available, and each installer contains both a serial
and parallel executable. The installer web site also explains how to
and parallel executable. The installer website also explains how to
install the Windows MPI package (MPICH2 from Argonne National Labs),
needed to run in parallel with MPI.

2
doc/src/Intro_authors.rst
View File

@ -8,7 +8,7 @@ University:
* Aidan Thompson, athomps at sandia.gov
* Stan Moore, stamoor at sandia.gov
* Axel Kohlmeyer, akohlmey at gmail.com
* Richard Berger, richard.berger at temple.edu
* Richard Berger, richard.berger at outlook.com
.. _sjp: http://www.cs.sandia.gov/~sjplimp
.. _lws: https://www.lammps.org

59
doc/src/Intro_citing.rst
View File

@ -4,28 +4,41 @@ Citing LAMMPS
Core Algorithms
^^^^^^^^^^^^^^^
Since LAMMPS is a community project, there is not a single one
publication or reference that describes **all** of LAMMPS.
The canonical publication that describes the foundation, that is
the basic spatial decomposition approach, the neighbor finding,
and basic communications algorithms used in LAMMPS is:
The paper mentioned below is the best overview of LAMMPS, but there are
also publications describing particular models or algorithms implemented
in LAMMPS or complementary software that is has interfaces to. Please
see below for how to cite contributions to LAMMPS.
`S. Plimpton, Fast Parallel Algorithms for Short-Range Molecular Dynamics, J Comp Phys, 117, 1-19 (1995). <http://www.sandia.gov/~sjplimp/papers/jcompphys95.pdf>`_
.. _lammps_paper:
So any project using LAMMPS (or a derivative application using LAMMPS as
a simulation engine) should cite this paper. A new publication
describing the developments and improvements of LAMMPS in the 25 years
since then is currently in preparation.
The latest canonical publication that describes the basic features, the
source code design, the program structure, the spatial decomposition
approach, the neighbor finding, basic communications algorithms, and how
users and developers have contributed to LAMMPS is:
`LAMMPS - A flexible simulation tool for particle-based materials modeling at the atomic, meso, and continuum scales, Comp. Phys. Comm. 271, 108171 (2022) <https://doi.org/10.1016/j.cpc.2021.108171>`_
So a project using LAMMPS or a derivative application that uses LAMMPS
as a simulation engine should cite this paper. The paper is expected to
be published in its final form under the same DOI in the first half
of 2022. Please also give the URL of the LAMMPS website in your paper,
namely https://www.lammps.org.
The original publication describing the parallel algorithms used in the
initial versions of LAMMPS is:
`S. Plimpton, Fast Parallel Algorithms for Short-Range Molecular Dynamics, J Comp Phys, 117, 1-19 (1995). <http://www.sandia.gov/~sjplimp/papers/jcompphys95.pdf>`_
DOI for the LAMMPS code
^^^^^^^^^^^^^^^^^^^^^^^
LAMMPS developers use the `Zenodo service at CERN
<https://zenodo.org/>`_ to create digital object identifies (DOI) for
stable releases of the LAMMPS code. There are two types of DOIs for the
LAMMPS source code: the canonical DOI for **all** versions of LAMMPS,
which will always point to the **latest** stable release version is:
LAMMPS developers use the `Zenodo service at CERN <https://zenodo.org/>`_
to create digital object identifies (DOI) for stable releases of the
LAMMPS source code. There are two types of DOIs for the LAMMPS source code.
The canonical DOI for **all** versions of LAMMPS, which will always
point to the **latest** stable release version is:
- DOI: `10.5281/zenodo.3726416 <https://dx.doi.org/10.5281/zenodo.3726416>`_
@ -45,11 +58,13 @@ about LAMMPS and its features.
Citing contributions
^^^^^^^^^^^^^^^^^^^^
LAMMPS has many features and that use either previously published
methods and algorithms or novel features. It also includes potential
parameter filed for specific models. Where available, a reminder about
references for optional features used in a specific run is printed to
the screen and log file. Style and output location can be selected with
the :ref:`-cite command-line switch <cite>`. Additional references are
LAMMPS has many features that use either previously published methods
and algorithms or novel features. It also includes potential parameter
files for specific models. Where available, a reminder about references
for optional features used in a specific run is printed to the screen
and log file. Style and output location can be selected with the
:ref:`-cite command-line switch <cite>`. Additional references are
given in the documentation of the :doc:`corresponding commands
<Commands_all>` or in the :doc:`Howto tutorials <Howto>`.
<Commands_all>` or in the :doc:`Howto tutorials <Howto>`. So please
make certain, that you provide the proper acknowledgments and citations
in any published works using LAMMPS.

2
doc/src/Intro_opensource.rst
View File

@ -19,7 +19,7 @@ software and open-source distribution, see `www.gnu.org <gnuorg_>`_
or `www.opensource.org <opensource_>`_. The legal text of the GPL as it
applies to LAMMPS is in the LICENSE file included in the LAMMPS distribution.
.. _gpl: https://github.com/lammps/lammps/blob/master/LICENSE
.. _gpl: https://github.com/lammps/lammps/blob/develop/LICENSE
.. _lgpl: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html

2
doc/src/Intro_website.rst
View File

@ -26,7 +26,7 @@ available online are listed below.
* `Tutorials <https://www.lammps.org/tutorials.html>`_
* `Pre- and post-processing tools for LAMMPS <https://www.lammps.org/prepost.html>`_
* `Other software usable with LAMMPS <https://www.lammps.org/offsite.html>`_
* `Other software usable with LAMMPS <https://www.lammps.org/external.html>`_
* `Viz tools usable with LAMMPS <https://www.lammps.org/viz.html>`_
* `Benchmark performance <https://www.lammps.org/bench.html>`_

13
doc/src/Library_create.rst
View File

@ -10,6 +10,7 @@ This section documents the following functions:
- :cpp:func:`lammps_mpi_init`
- :cpp:func:`lammps_mpi_finalize`
- :cpp:func:`lammps_kokkos_finalize`
- :cpp:func:`lammps_python_finalize`
--------------------
@ -33,7 +34,7 @@ simple example demonstrating its use:
int lmpargc = sizeof(lmpargv)/sizeof(const char *);
/* create LAMMPS instance */
handle = lammps_open_no_mpi(lmpargc, lmpargv, NULL);
handle = lammps_open_no_mpi(lmpargc, (char **)lmpargv, NULL);
if (handle == NULL) {
printf("LAMMPS initialization failed");
lammps_mpi_finalize();
@ -104,3 +105,13 @@ calling program.
.. doxygenfunction:: lammps_mpi_finalize
:project: progguide
-----------------------
.. doxygenfunction:: lammps_kokkos_finalize
:project: progguide
-----------------------
.. doxygenfunction:: lammps_python_finalize
:project: progguide

6
doc/src/Library_utility.rst
View File

@ -13,6 +13,7 @@ functions. They do not directly call the LAMMPS library.
- :cpp:func:`lammps_fix_external_set_virial_peratom`
- :cpp:func:`lammps_fix_external_set_vector_length`
- :cpp:func:`lammps_fix_external_set_vector`
- :cpp:func:`lammps_flush_buffers`
- :cpp:func:`lammps_free`
- :cpp:func:`lammps_is_running`
- :cpp:func:`lammps_force_timeout`
@ -72,6 +73,11 @@ where such memory buffers were allocated that require the use of
-----------------------
.. doxygenfunction:: lammps_flush_buffers
:project: progguide
-----------------------
.. doxygenfunction:: lammps_free
:project: progguide

26
doc/src/Manual_version.rst
View File

@ -7,26 +7,34 @@ correctly and reliably at all times. You can follow its development
in a public `git repository on GitHub <https://github.com/lammps/lammps>`_.
Whenever we fix a bug or update or add a feature, it will be merged into
the `master` branch of the git repository. When a sufficient number of
the *develop* branch of the git repository. When a sufficient number of
changes have accumulated *and* the software passes a set of automated
tests, we release it in the next *patch* release, which are made every
few weeks. Info on patch releases are on `this website page
few weeks. The *release* branch of the git repository is updated with
every such release. Info on patch releases are on `this website page
<https://www.lammps.org/bug.html>`_.
Once or twice a year, only bug fixes and small, non-intrusive changes are
included for a period of time, and the code is subjected to more detailed
Once or twice a year, we apply only bug fixes and small, non-intrusive
changes to the *develop* branch and the code is subjected to more detailed
and thorough testing than the default automated testing. The latest
patch release after such a period is then labeled as a *stable* version.
patch release after such a period is then also labeled as a *stable* version
and the *stable* branch is updated with it. Between stable releases
we occasionally release some updates to the stable release containing
only bug fixes and updates back-ported from *develop* but no new features
and update the *stable* branch accordingly.
Each version of LAMMPS contains all the features and bug-fixes up to
and including its version date.
Each version of LAMMPS contains all the documented features up to and
including its version date.
The version date is printed to the screen and logfile every time you
run LAMMPS. It is also in the file src/version.h and in the LAMMPS
directory name created when you unpack a tarball. And it is on the
first page of the :doc:`manual <Manual>`.
* If you browse the HTML pages on the LAMMPS WWW site, they always
describe the most current patch release of LAMMPS.
* If you browse the HTML pages on the LAMMPS WWW site, they will by
default describe the most current patch release version of LAMMPS.
In the navigation bar on the bottom left, there is the option to
view instead the documentation for the most recent *stable* version
or the latest version from the current development branch.
* If you browse the HTML pages included in your tarball, they
describe the version you have, which may be older.

17
doc/src/Modify.rst
View File

@ -1,21 +1,24 @@
Modifying & extending LAMMPS
****************************
LAMMPS is designed in a modular fashion so as to be easy to modify and
LAMMPS is designed in a modular fashion and to be easy to modify or
extend with new functionality. In fact, about 95% of its source code
is add-on files. These doc pages give basic instructions on how to do
this.
are optional. The following pages give basic instructions on what
is required when adding new styles of different kinds to LAMMPS.
If you add a new feature to LAMMPS and think it will be of interest to
general users, we encourage you to submit it for inclusion in LAMMPS
as a pull request on our `GitHub site <https://github.com/lammps/lammps>`_,
after reading :doc:`this page <Modify_contribute>`.
If you add a new feature to LAMMPS and think it will be of general
interest to other users, we encourage you to submit it for inclusion in
LAMMPS as a pull request on our `GitHub site
<https://github.com/lammps/lammps>`_, after reading about :doc:`how to
prepare your code for submission <Modify_contribute>` and :doc:`the
style requirements and recommendations <Modify_style>`.
.. toctree::
:maxdepth: 1
Modify_overview
Modify_contribute
Modify_style
.. toctree::
:maxdepth: 1

336
doc/src/Modify_contribute.rst
View File

@ -1,22 +1,20 @@
Submitting new features for inclusion in LAMMPS
===============================================
We encourage users to submit new features or modifications for LAMMPS to
`the core developers <https://www.lammps.org/authors.html>`_ so they
can be added to the LAMMPS distribution. The preferred way to manage and
coordinate this is via the LAMMPS project on `GitHub
<https://github.com/lammps/lammps>`_. Please see the :doc:`GitHub
Tutorial <Howto_github>` for a demonstration on how to do that. An
alternative is to contact the LAMMPS developers or the indicated
developer of a package or feature directly and send in your contribution
via e-mail, but that can add a significant delay on getting your
contribution included, depending on how busy the respective developer
is, how complex a task it would be to integrate that code, and how
many - if any - changes are required before the code can be included.
We encourage LAMMPS users to submit new features they wrote for LAMMPS
to be included into the LAMMPS distribution and thus become easily
accessible to all LAMMPS users. The LAMMPS source code is managed with
git and public development is hosted on `GitHub
<https://github.com/lammps/lammps>`_. You can monitor the repository to
be notified of releases, follow the ongoing development, and comment on
topics of interest to you.
Communication with the LAMMPS developers
----------------------------------------
For any larger modifications or programming project, you are encouraged
to contact the LAMMPS developers ahead of time in order to discuss
implementation strategies and coding guidelines. That will make it
implementation strategies and coding guidelines. That will make it
easier to integrate your contribution and results in less work for
everybody involved. You are also encouraged to search through the list
of `open issues on GitHub <https://github.com/lammps/lammps/issues>`_
@ -24,235 +22,105 @@ and submit a new issue for a planned feature, so you would not duplicate
the work of others (and possibly get scooped by them) or have your work
duplicated by others.
For informal communication with (some of) the LAMMPS developers you may
ask to join the `LAMMPS developers on Slack
<https://lammps.slack.com>`_. This slack work space is by invitation
only. Thus for access, please send an e-mail to ``slack@lammps.org``
explaining what part of LAMMPS you are working on. Only discussions
related to LAMMPS development are tolerated, so this is **NOT** for
people that look for help with compiling, installing, or using
LAMMPS. Please contact the
`lammps-users mailing list <https://www.lammps.org/mail.html>`_ or the
`LAMMPS forum <https://www.lammps.org/forum.html>`_ for those purposes
instead.
For informal communication with the LAMMPS developers you may ask to
join the `LAMMPS developers on Slack <https://lammps.slack.com>`_. This
slack work space is by invitation only. Thus for access, please send an
e-mail to ``slack@lammps.org`` explaining what part of LAMMPS you are
working on. Only discussions related to LAMMPS development are
tolerated in that work space, so this is **NOT** for people that look for
help with compiling, installing, or using LAMMPS. Please post a message
to the `lammps-users mailing list <https://www.lammps.org/mail.html>`_
or the `LAMMPS forum <https://www.lammps.org/forum.html>`_ for those
purposes.
How quickly your contribution will be integrated depends largely on how
much effort it will cause to integrate and test it, how many and what
kind of changes it requires to the core codebase, and of how much
interest it is to the larger LAMMPS community. Please see below for a
checklist of typical requirements. Once you have prepared everything,
see the :doc:`LAMMPS GitHub Tutorial <Howto_github>` page for
instructions on how to submit your changes or new files through a GitHub
pull request. If you prefer to submit patches or full files, you should
first make certain, that your code works correctly with the latest
patch-level version of LAMMPS and contains all bug fixes from it. Then
create a gzipped tar file of all changed or added files or a
corresponding patch file using 'diff -u' or 'diff -c' and compress it
with gzip. Please only use gzip compression, as this works well and is
available on all platforms.
Packages versus individual files
--------------------------------
The remainder of this chapter describes how to add new "style" files of
various kinds to LAMMPS. Packages are simply collections of one or more
such new class files which are invoked as a new style within a LAMMPS
input script. In some cases also collections of supporting functions or
classes are included as separate files in a package, especially when
they can be shared between multiple styles. If designed correctly, these
additions typically do not require any changes to the core code of
LAMMPS; they are simply add-on files that are compiled with the rest of
LAMMPS. To make those styles work, you may need some trivial changes to
the core code; an example of a trivial change is making a parent-class
method "virtual" when you derive a new child class from it.
If you think your new feature or package requires some non-trivial
changes in core LAMMPS files, you should communicate with the LAMMPS
developers `on Slack <https://lammps.org/slack.html>`_, `on GitHub
<https://github.com/lammps/lammps/issues>`_, or `via email
<https://www.lammps.org/authors.html>`_, since we may have
recommendations about what changes to do where, or may not want to
include certain changes for some reason and thus you would need to look
for alternatives.
Time and effort required
------------------------
How quickly your contribution will be integrated can vary a lot. It
depends largely on how much effort it will cause the LAMMPS developers
to integrate and test it, how many and what kind of changes to the core
code are required, how quickly you can address them and of how much
interest it is to the larger LAMMPS community. Please see the section
on :doc:`LAMMPS programming style and requirements <Modify_style>` for
instructions, recommendations, and formal requirements. A small,
modular, well written contribution may be integrated within hours, but a
complex change that will require a redesign of some core functionality
in LAMMPS for a clean integration can take many months until it is
considered ready for inclusion (though this is rare).
Submission procedure
--------------------
All changes to LAMMPS (including those from LAMMPS developers) are
integrated via pull requests on GitHub and cannot be merged without
passing the automated testing and an approving review by a LAMMPS core
developer. Thus before submitting your contribution, you should first
make certain, that your added or modified code compiles and works
correctly with the latest patch-level or development version of LAMMPS
and contains all bug fixes from it.
Once you have prepared everything, see the :doc:`LAMMPS GitHub Tutorial
<Howto_github>` page for instructions on how to submit your changes or
new files through a GitHub pull request yourself. If you are unable or
unwilling to submit via GitHub yourself, you may also submit patch files
or full files to the LAMMPS developers and ask them to submit a pull
request on GitHub on your behalf. Then create a gzipped tar file of
all changed or added files or a corresponding patch file using
'diff -u' or 'diff -c' format and compress it with gzip. Please only
use gzip compression, as this works well and is available on all platforms.
If the new features/files are broadly useful we may add them as core
files to LAMMPS or as part of a :doc:`package <Packages_list>`. All
packages are listed and described on the :doc:`Packages details
<Packages_details>` doc page.
Note that by providing us files to release, you are agreeing to make
them open-source, i.e. we can release them under the terms of the GPL
(version 2), used as a license for the rest of LAMMPS. And as part of
a LGPL (version 2.1) distribution that we make available to developers
on request only and with files that are authorized for that kind of
distribution removed (e.g. interface to FFTW). See the
Licensing
---------
Note that by providing us files to release, you agree to make them
open-source, i.e. we can release them under the terms of the GPL
(version 2) with the rest of LAMMPS. And similarly as part of a LGPL
(version 2.1) distribution of LAMMPS that we make available to
developers on request only and with files that are not authorized for
that kind of distribution removed (e.g. interface to FFTW). See the
:doc:`LAMMPS license <Intro_opensource>` page for details.
.. note::
External contributions
----------------------
If you prefer to actively develop and support your add-on feature
yourself, then you may wish to make it available for download from
your own website, as a user package that LAMMPS users can add to
their copy of LAMMPS. See the `Offsite LAMMPS packages and tools
<https://www.lammps.org/offsite.html>`_ page of the LAMMPS web site
for examples of groups that do this. We are happy to advertise your
package and web site from that page. Simply email the `developers
<https://www.lammps.org/authors.html>`_ with info about your package
and we will post it there. We recommend to name external packages
USER-\<name\> so they can be easily distinguished from bundled packages
that do not have the USER- prefix.
If you prefer to do so, you can also develop and support your add-on
feature **without** having it included in the LAMMPS distribution, for
example as a download from a website of your own. See the `External
LAMMPS packages and tools <https://www.lammps.org/external.html>`_ page
of the LAMMPS website for examples of groups that do this. We are happy
to advertise your package and website from that page. Simply email the
`developers <https://www.lammps.org/authors.html>`_ with info about your
package and we will post it there. We recommend to name external
packages USER-\<name\> so they can be easily distinguished from bundled
packages that do not have the USER- prefix.
.. _lws: https://www.lammps.org
The previous sections of this page describe how to add new "style"
files of various kinds to LAMMPS. Packages are simply collections of
one or more new class files which are invoked as a new style within a
LAMMPS input script. If designed correctly, these additions typically
do not require changes to the main core of LAMMPS; they are simply
add-on files. If you think your new feature requires non-trivial
changes in core LAMMPS files, you should `communicate with the
developers <https://www.lammps.org/authors.html>`_, since we may or
may not want to include those changes for some reason. An example of a
trivial change is making a parent-class method "virtual" when you derive
a new child class from it.
Here is a checklist of steps you need to follow to submit a single file
or package for our consideration. Following these steps will save
both you and us time. Please have a look at the existing files in
packages in the src directory for examples. If you are uncertain, please ask.
* All source files you provide must compile with the most current
version of LAMMPS with multiple configurations. In particular you
need to test compiling LAMMPS from scratch with -DLAMMPS_BIGBIG
set in addition to the default -DLAMMPS_SMALLBIG setting. Your code
will need to work correctly in serial and in parallel using MPI.
* For consistency with the rest of LAMMPS and especially, if you want
your contribution(s) to be added to main LAMMPS code or one of its
standard packages, it needs to be written in a style compatible with
other LAMMPS source files. This means: 2-character indentation per
level, **no tabs**, no lines over 100 characters. I/O is done via
the C-style stdio library (mixing of stdio and iostreams is generally
discouraged), class header files should not import any system headers
outside of <cstdio>, STL containers should be avoided in headers,
system header from the C library should use the C++-style names
(<cstdlib>, <cstdio>, or <cstring>) instead of the C-style names
<stdlib.h>, <stdio.h>, or <string.h>), and forward declarations
used where possible or needed to avoid including headers.
All added code should be placed into the LAMMPS_NS namespace or a
sub-namespace; global or static variables should be avoided, as they
conflict with the modular nature of LAMMPS and the C++ class structure.
Header files must **not** import namespaces with *using*\ .
This all is so the developers can more easily understand, integrate,
and maintain your contribution and reduce conflicts with other parts
of LAMMPS. This basically means that the code accesses data
structures, performs its operations, and is formatted similar to other
LAMMPS source files, including the use of the error class for error
and warning messages.
* To simplify reformatting contributed code in a way that is compatible
with the LAMMPS formatting styles, you can use clang-format (version 8
or later). The LAMMPS distribution includes a suitable ``.clang-format``
file which will be applied if you run ``clang-format -i some_file.cpp``
on your files inside the LAMMPS src tree. Please only reformat files
that you have contributed. For header files containing a
``SomeStyle(keyword, ClassName)`` macros it is required to have this
macro embedded with a pair of ``// clang-format off``, ``// clang-format on``
commends and the line must be terminated with a semi-colon (;).
Example:
.. code-block:: c++
#ifdef COMMAND_CLASS
// clang-format off
CommandStyle(run,Run);
// clang-format on
#else
#ifndef LMP_RUN_H
[...]
You may also use ``// clang-format on/off`` throughout your file
to protect sections of the file from being reformatted.
* Please review the list of :doc:`available Packages <Packages_details>`
to see if your contribution could be added to be added to one of them.
It should fit into the general purposed of that package. If it does not
fit well, it can be added to one of the EXTRA- packages or the MISC package.
* If your contribution has several related features that are not covered
by one of the existing packages or is dependent on a library (bundled
or external), it is best to make it a package directory with a name
like FOO. In addition to your new files, the directory should contain
a README text file. The README should contain your name and contact
information and a brief description of what your new package does. If
your files depend on other LAMMPS style files also being installed
(e.g. because your file is a derived class from the other LAMMPS
class), then an Install.sh file is also needed to check for those
dependencies and modifications to src/Depend.sh to trigger the checks.
See other README and Install.sh files in other directories as examples.
Similarly for CMake support changes need to be made to cmake/CMakeLists.txt,
the files in cmake/presets, and possibly a file to cmake/Modules/Packages/
added. Please check out how this is handled for existing packages and
ask the LAMMPS developers if you need assistance. Please submit a pull
request on GitHub or send us a tarball of this FOO directory and all
modified files. Pull requests are strongly encouraged since they greatly
reduce the effort required to integrate a contribution and simplify the
process of adjusting the contributed code to cleanly fit into the
LAMMPS distribution.
* Your new source files need to have the LAMMPS copyright, GPL notice,
and your name and email address at the top, like other
user-contributed LAMMPS source files. They need to create a class
that is inside the LAMMPS namespace. To simplify maintenance, we
may ask to adjust the programming style and formatting style to closer
match the rest of LAMMPS. We bundle a clang-format configuration file
that can help with adjusting the formatting, although this is not a
strict requirement.
* You **must** also create a **documentation** file for each new command
or style you are adding to LAMMPS. For simplicity and convenience,
the documentation of groups of closely related commands or styles may
be combined into a single file. This will be one file for a
single-file feature. For a package, it might be several files. These
are text files with a .rst extension using the `reStructuredText
<rst_>`_ markup language, that are then converted to HTML and PDF
using the `Sphinx <sphinx_>`_ documentation generator tool. Running
Sphinx with the included configuration requires Python 3.x.
Configuration settings and custom extensions for this conversion are
included in the source distribution, and missing python packages will
be transparently downloaded into a virtual environment via pip. Thus,
if your local system is missing required packages, you need access to
the internet. The translation can be as simple as doing "make html
pdf" in the doc folder. As appropriate, the text files can include
inline mathematical expression or figures (see doc/JPG for examples).
Additional PDF files with further details (see doc/PDF for examples)
may also be included. The page should also include literature
citations as appropriate; see the bottom of doc/fix_nh.rst for
examples and the earlier part of the same file for how to format the
cite itself. Citation labels must be unique across all .rst files.
The "Restrictions" section of the page should indicate if your
command is only available if LAMMPS is built with the appropriate
FOO package. See other package doc files for examples of
how to do this. Please run at least "make html" and "make spelling"
and carefully inspect and proofread the resulting HTML format doc page
before submitting your code. Upon submission of a pull request,
checks for error free completion of the HTML and PDF build will be
performed and also a spell check, a check for correct anchors and
labels, and a check for completeness of references all styles in their
corresponding tables and lists is run. In case the spell check
reports false positives they can be added to the file
doc/utils/sphinx-config/false_positives.txt
* For a new package (or even a single command) you should include one or
more example scripts demonstrating its use. These should run in no
more than a couple minutes, even on a single processor, and not require
large data files as input. See directories under examples/PACKAGES for
examples of input scripts other users provided for their packages.
These example inputs are also required for validating memory accesses
and testing for memory leaks with valgrind
* 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/EFF/atom_vec_electron.cpp for an example.
A LaTeX citation is stored in a variable at the top of the file and
a single line of code registering this variable is added to the
constructor of the class. If there is additional functionality (which
may have been added later) described in a different publication,
additional citation descriptions may be added for as 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. 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 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.
Finally, as a general rule-of-thumb, the more clear and
self-explanatory you make your documentation and README files, and the
easier you make it for people to get started, e.g. by providing example
scripts, the more likely it is that users will try out your new feature.
.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
.. _sphinx: https://sphinx-doc.org

19
doc/src/Modify_overview.rst
View File

@ -1,13 +1,14 @@
Overview
========
The best way to add a new feature to LAMMPS is to find a similar
feature and look at the corresponding source and header files to figure
out what it does. You will need some knowledge of C++ to be able to
understand the high-level structure of LAMMPS and its class
organization, but functions (class methods) that do actual
computations are written in vanilla C-style code and operate on simple
C-style data structures (vectors and arrays).
The best way to add a new feature to LAMMPS is to find a similar feature
and look at the corresponding source and header files to figure out what
it does. You will need some knowledge of C++ to be able to understand
the high-level structure of LAMMPS and its class organization, but
functions (class methods) that do actual computations are mostly written
in C-style code and operate on simple C-style data structures (vectors
and arrays). A high-level overview of the programming style choices in
LAMMPS is :doc:`given elsewhere <Developer_code_design>`.
Most of the new features described on the :doc:`Modify <Modify>` doc
page require you to write a new C++ derived class (except for exceptions
@ -40,8 +41,10 @@ then your pair_foo.h file should be structured as follows:
.. code-block:: c++
#ifdef PAIR_CLASS
PairStyle(foo,PairFoo)
// clang-format off
PairStyle(foo,PairFoo);
#else
// clanf-format on
...
(class definition for PairFoo)
...

38
doc/src/Modify_pair.rst
View File

@ -12,24 +12,24 @@ includes some optional methods to enable its use with rRESPA.
Here is a brief description of the class methods in pair.h:
+---------------------------------+-------------------------------------------------------------------+
| compute | workhorse routine that computes pairwise interactions |
+---------------------------------+-------------------------------------------------------------------+
| settings | reads the input script line with arguments you define |
+---------------------------------+-------------------------------------------------------------------+
| coeff | set coefficients for one i,j type pair |
+---------------------------------+-------------------------------------------------------------------+
| init_one | perform initialization for one i,j type pair |
+---------------------------------+-------------------------------------------------------------------+
| init_style | initialization specific to this pair style |
+---------------------------------+-------------------------------------------------------------------+
| write & read_restart | write/read i,j pair coeffs to restart files |
+---------------------------------+-------------------------------------------------------------------+
| write & read_restart_settings | write/read global settings to restart files |
+---------------------------------+-------------------------------------------------------------------+
| single | force and energy of a single pairwise interaction between 2 atoms |
+---------------------------------+-------------------------------------------------------------------+
| compute_inner/middle/outer | versions of compute used by rRESPA |
+---------------------------------+-------------------------------------------------------------------+
+---------------------------------+---------------------------------------------------------------------+
| compute | workhorse routine that computes pairwise interactions |
+---------------------------------+---------------------------------------------------------------------+
| settings | reads the input script line with arguments you define |
+---------------------------------+---------------------------------------------------------------------+
| coeff | set coefficients for one i,j type pair |
+---------------------------------+---------------------------------------------------------------------+
| init_one | perform initialization for one i,j type pair |
+---------------------------------+---------------------------------------------------------------------+
| init_style | initialization specific to this pair style |
+---------------------------------+---------------------------------------------------------------------+
| write & read_restart | write/read i,j pair coeffs to restart files |
+---------------------------------+---------------------------------------------------------------------+
| write & read_restart_settings | write/read global settings to restart files |
+---------------------------------+---------------------------------------------------------------------+
| single | force/r and energy of a single pairwise interaction between 2 atoms |
+---------------------------------+---------------------------------------------------------------------+
| compute_inner/middle/outer | versions of compute used by rRESPA |
+---------------------------------+---------------------------------------------------------------------+
The inner/middle/outer routines are optional.

476
doc/src/Modify_style.rst Normal file
View File

@ -0,0 +1,476 @@
LAMMPS programming style and requirements for contributions
===========================================================
The following is a summary of the current requirements and
recommendations for including contributed source code or documentation
into the LAMMPS software distribution.
Motivation
----------
The LAMMPS developers are committed to providing a software package that
is versatile, reliable, high-quality, efficient, portable, and easy to
maintain and modify. Achieving all of these goals is challenging since
a large part of LAMMPS consists of contributed code from many different
authors and not many of them are professionally trained programmers and
familiar with the idiosyncrasies of maintaining a large software
package. In addition, changes that interfere with the parallel
efficiency of the core code must be avoided. As LAMMPS continues to
grow and more features and functionality are added, it becomes a
necessity to be more discriminating with new contributions while also
working at the same time to improve the existing code.
The following requirements and recommendations are provided to help
maintaining or improving that status. Where possible we utilize
available continuous integration tools to search for common programming
mistakes, portability limitations, incompatible formatting, and
undesired side effects. It is indicated which requirements are strict,
and which represent a preference and thus are negotiable or optional.
Please feel free to contact the LAMMPS core developers in case you need
additional explanations or clarifications or in case you need assistance
in realizing the (strict) requirements for your contributions.
Licensing requirements (strict)
-------------------------------
Contributing authors agree when submitting a pull request that their
contributions can be distributed under the LAMMPS license
conditions. This is the GNU public license in version 2 (not 3 or later)
for the publicly distributed versions, e.g. on the LAMMPS homepage or on
GitHub. On request we also make a version of LAMMPS available under
LGPL 2.1 terms; this will usually be the latest available or a previous
stable version with a few LGPL 2.1 incompatible files removed.
Your new source files should have the LAMMPS copyright, GPL notice, and
your name and email address at the top, like other user-contributed
LAMMPS source files.
Contributions may be under a different license for long as that
license does not conflict with the aforementioned terms. Contributions
that use code with a conflicting license can be split into two parts:
1. the core parts (i.e. parts that must be in the `src` tree) that are
licensed under compatible terms and bundled with the LAMMPS sources
2. an external library that must be downloaded and compiled (either
separately or as part of the LAMMPS compilation)
Please note, that this split licensed mode may complicate including the
contribution in binary packages.
Using Pull Requests on GitHub (preferred)
-----------------------------------------
All contributions to LAMMPS are processed as pull requests on GitHub
(this also applies to the work of the core LAMMPS developers). A
:doc:`tutorial for submitting pull requests on GitHub <Howto_github>` is
provided. If this is still problematic, contributors may contact any of
the core LAMMPS developers for help or to create a pull request on their
behalf. This latter way of submission may delay the integration as it
depends on the amount of time required to prepare the pull request and
free time available by the LAMMPS developer in question to spend on this
task.
Integration Testing (strict)
----------------------------
Contributed code, like all pull requests, 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 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 input decks and create
consistent results. Also, the translation of the documentation to HTML
and PDF is tested for.
More specifically, this means that contributed source code **must**
compile with the most current version of LAMMPS with ``-DLAMMPS_BIGBIG``
in addition to the default setting of ``-DLAMMPS_SMALLBIG``. The code
needs to work correctly in both cases and also in serial and parallel
using MPI.
Some "disruptive" changes may break tests and require updates to the
testing tools or scripts or tests themselves. This is rare. If in
doubt, contact the LAMMPS developer that is assigned to the pull request
for further details and explanations and suggestions of what needs to be
done.
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>`_ (.rst files in the ``doc/src/`` folder). The
documentation shall be written in American English and the .rst file
must use only ASCII characters so it can be cleanly translated to PDF
files (via `sphinx <sphinx>`_ and PDFLaTeX). Special characters may be included via
embedded math expression typeset in a LaTeX subset.
.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
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 also some lists describing
packages must be updated as well as a package specific description added
and, if necessary, some package specific build instructions included.
As appropriate, the text files with the documentation can include inline
mathematical expression or figures (see ``doc/JPG`` for examples).
Additional PDF files with further details (see ``doc/PDF`` for examples) may
also be included. The page should also include literature citations as
appropriate; see the bottom of ``doc/fix_nh.rst`` for examples and the
earlier part of the same file for how to format the cite itself.
Citation labels must be unique across **all** .rst files. The
"Restrictions" section of the page should indicate if your command is
only available if LAMMPS is built with the appropriate FOO package. See
other package doc files for examples of how to do this.
Please run at least "make html" and "make spelling" and carefully
inspect and proofread the resulting HTML format doc page before
submitting your code. Upon submission of a pull request, checks for
error free completion of the HTML and PDF build will be performed and
also a spell check, a check for correct anchors and labels, and a check
for completeness of references all styles in their corresponding tables
and lists is run. In case the spell check reports false positives they
can be added to the file doc/utils/sphinx-config/false_positives.txt
Contributions that add or modify the library interface or "public" APIs
from the C++ code or the Fortran module must include suitable doxygen
comments in the source and corresponding changes to the documentation
sources for the "Programmer Guide" guide section of the LAMMPS manual.
Examples (preferred)
--------------------
In most cases, 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 under the examples or
examples/PACKAGES directory. A few guidelines for such example input
decks.
- commands that generate output should be commented out (except when the
output is the sole purpose or the feature, e.g. for a new compute).
- commands like :doc:`log <log>`, :doc:`echo <echo>`, :doc:`package
<package>`, :doc:`processors <processors>`, :doc:`suffix <suffix>` may
**not** be used in the input file (exception: "processors * * 1" or
similar is acceptable when used to avoid unwanted domain decomposition
of empty volumes).
- outside of the log files no generated output should be included
- custom thermo_style settings may not include output measuring CPU or other time
as that makes comparing the thermo output between different runs more complicated.
- input files should be named ``in.name``, data files should be named
``data.name`` and log files should be named ``log.version.name.<compiler>.<ncpu>``
- the total file size of all the inputs and outputs should be small
- where possible potential files from the "potentials" folder or data
file from other folders should be re-used through symbolic links
Howto document (optional)
-------------------------
If your feature requires some more complex steps and explanations to be
used correctly or some external or bundled tools or scripts, we
recommend that you also contribute a :doc:`Howto document <Howto>`
providing some more background information and some tutorial material.
This can also be used to provide more in-depth explanations for bundled
examples.
As a general rule-of-thumb, the more clear and self-explanatory you make
your documentation, README files and examples, and the easier you make
it for people to get started, the more likely it is that users will try
out your new feature.
Programming Style Requirements (varied)
---------------------------------------
The LAMMPS developers aim to employ a consistent programming style and
naming conventions across the entire code base, as this helps with
maintenance, debugging, and understanding the code, both for developers
and users.
The files `pair_lj_cut.h`, `pair_lj_cut.cpp`, `utils.h`, and `utils.cpp`
may serve as representative examples.
Command or Style names, file names, and keywords (mostly strict)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All user-visible command or style names should be all lower case and
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" would then be
`LMP_COMPUTE_SOME_NAME_H` and the class name `ComputeSomeName`.
Whitespace and permissions (preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Source files should not contain TAB characters unless required by the
syntax (e.g. in makefiles) and no trailing whitespace. Text files
should be added with Unix-style line endings (LF-only). Git will
automatically convert those in both directions when running on Windows;
use dos2unix on Linux machines to convert files. Text files should have
a line ending on the last line.
All files should have 0644 permissions, i.e writable to the user only
and readable by all and no executable permissions. Executable
permissions (0755) should only be on shell scripts or python or similar
scripts for interpreted script languages.
Indentation and Placement of Braces (strongly preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LAMMPS uses 2 characters per indentation level and lines should be
kept within 100 characters wide.
For new files added to the "src" tree, a `clang-format
<https://clang.llvm.org/docs/ClangFormat.html>`_ configuration file is
provided under the name `.clang-format`. This file is compatible with
clang-format version 8 and later. With that file present files can be
reformatted according to the configuration with a command like:
`clang-format -i new-file.cpp`. Ideally, this is done while writing the
code or before a pull request is submitted. Blocks of code where the
reformatting from clang-format yields undesirable output may be
protected with placing a pair `// clang-format off` and `// clang-format
on` comments around that block.
Programming language standards (required)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The core of LAMMPS is written in C++11 in a style that can be mostly
described as "C with classes". Advanced C++ features like operator
overloading or excessive use of templates are avoided with the intent to
keep the code readable to programmers that have limited C++ programming
experience. C++ constructs are acceptable when they help improving the
readability and reliability of the code, e.g. when using the
`std::string` class instead of manipulating pointers and calling the
string functions of the C library. In addition a collection of
convenient :doc:`utility functions and classes <Developer_utils>` for
recurring tasks and a collection of
:doc:`platform neutral functions <Developer_platform>` for improved
portability are provided.
Included Fortran code has to be compatible with the Fortran 2003
standard. Python code must be compatible with Python 3.5. Large parts
or LAMMPS (including the :ref:`PYTHON package <PKG-PYTHON>`) are also
compatible with Python 2.7. Compatibility with Python 2.7 is
desirable, but compatibility with Python 3.5 is **required**.
Compatibility with these older programming language standards is very
important to maintain portability and availability of LAMMPS on many
platforms. This applies especially to HPC cluster environments, which
tend to be running older software stacks and LAMMPS users may be
required to use those older tools for access to advanced hardware
features or not have the option to install newer compilers or libraries.
Programming conventions (varied)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following is a collection of conventions that should be applied when
writing code for LAMMPS. Following these steps will make it much easier
to integrate your contribution. Please have a look at the existing files
in packages in the src directory for examples. As a demonstration for
how can be adapted to these conventions you may compare the REAXFF
package with the what it looked like when it was called USER-REAXC. If
you are uncertain, please ask.
- system headers or from installed libraries are include with angular
brackets (example: ``#include <vector>``), while local include file
use double quotes (example: ``#include "atom.h"``).
- when including system header files from the C library use the
C++-style names (``<cstdlib>`` or ``<cstring>``) instead of the
C-style names (``<stdlib.h>`` or ``<string.h>``)
- the order of ``#include`` statements in a file ``some_name.cpp`` that
implements a class ``SomeName`` defined in a header file
``some_name.h`` should be as follows:
- ``#include "some_name.h"`` followed by an empty line
- LAMMPS include files e.g. ``#include "comm.h"`` or ``#include
"modify.h"`` in alphabetical order followed by an empty line
- system header files from the C++ or C standard library followed by
an empty line
- ``using namespace LAMMPS_NS`` or other namespace imports.
- I/O is done via the C-style stdio library and **not** iostreams.
- Output to the screen and the logfile should be using the corresponding
FILE pointers and only be done on MPI rank 0. Use the :cpp:func:`utils::logmesg`
convenience function where possible.
- Usage of C++11 `virtual`, `override`, `final` keywords: Please follow the
`C++ Core Guideline C.128 <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override>`_.
That means, you should only use `virtual` to declare a new virtual
function, `override` to indicate you are overriding an existing virtual
function, and `final` to prevent any further overriding.
- Trivial destructors: Prefer not writing destructors when they are empty and `default`.
.. code-block:: c++
// don't write destructors for A or B like this
class A : protected Pointers {
public:
A();
~A() override {}
};
class B : protected Pointers {
public:
B();
~B() override = default;
};
// instead, let the compiler create the implicit default destructor by not writing it
class A : protected Pointers {
public:
A();
};
class B : protected Pointers {
public:
B();
};
- Header files, especially those defining a "style", should only use
the absolute minimum number of include files and **must not** contain
any ``using`` statements. Typically that would be only the header for
the base class. Instead any include statements should be put into the
corresponding implementation files and forward declarations be used.
For implementation files, the "include what you use" principle should
be employed. However, there is the notable exception that when the
``pointers.h`` header is included (or one of the base classes derived
from it) certain headers will always be included and thus do not need
to be explicitly specified.
These are: `mpi.h`, `cstddef`, `cstdio`, `cstdlib`, `string`, `utils.h`,
`vector`, `fmt/format.h`, `climits`, `cinttypes`.
This also means any such file can assume that `FILE`, `NULL`, and
`INT_MAX` are defined.
- Header files that define a new LAMMPS style (i.e. that have a
``SomeStyle(some/name,SomeName);`` macro in them) should only use the
include file for the base class and otherwise use forward declarations
and pointers; when interfacing to a library use the PIMPL (pointer
to implementation) approach where you have a pointer to a struct
that contains all library specific data (and thus requires the library
header) but use a forward declaration and define the struct only in
the implementation file. This is a **strict** requirement since this
is where type clashes between packages and hard to find bugs have
regularly manifested in the past.
- Please use clang-format only to reformat files that you have
contributed. For header files containing a ``SomeStyle(keyword,
ClassName)`` macros it is required to have this macro embedded with a
pair of ``// clang-format off``, ``// clang-format on`` commends and
the line must be terminated with a semi-colon (;). Example:
.. code-block:: c++
#ifdef COMMAND_CLASS
// clang-format off
CommandStyle(run,Run);
// clang-format on
#else
#ifndef LMP_RUN_H
[...]
You may also use ``// clang-format on/off`` throughout your files
to protect individual sections from being reformatted.
- We rarely accept new styles in the core src folder. Thus please
review the list of :doc:`available Packages <Packages_details>` to see
if your contribution could be added to be added to one of them. It
should fit into the general purposed of that package. If it does not
fit well, it may be added to one of the EXTRA- packages or the MISC
package.
Contributing a package
----------------------
If your contribution has several related features that are not covered
by one of the existing packages or is dependent on a library (bundled or
external), it is best to make it a package directory with a name like
FOO. In addition to your new files, the directory should contain a
README text file. The README should contain your name and contact
information and a brief description of what your new package does.
Build system (strongly preferred)
---------------------------------
LAMMPS currently supports two build systems: one that is based on
:doc:`traditional Makefiles <Build_make>` and one that is based on
:doc:`CMake <Build_cmake>`. Thus your contribution must be compatible
with and support both.
For a single pair of header and implementation files that are an
independent feature, it is usually only required to add them to
`src/.gitignore``.
For traditional make, if your contributed files or package depend on
other LAMMPS style files or packages also being installed (e.g. because
your file is a derived class from the other LAMMPS class), then an
Install.sh file is also needed to check for those dependencies and
modifications to src/Depend.sh to trigger the checks. See other README
and Install.sh files in other directories as examples.
Similarly for CMake support, changes may need to be made to
cmake/CMakeLists.txt, some of the files in cmake/presets, and possibly a
file with specific instructions needs to be added to
cmake/Modules/Packages/. Please check out how this is handled for
existing packages and ask the LAMMPS developers if you need assistance.
Citation reminder (suggested)
-----------------------------
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,
by default, LAMMPS will print the brief info and the DOI
in the first line to the screen and the full citation to the log file.
If there is additional functionality (which may have been added later)
described in a different publication, additional citation descriptions
may be added for as 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 code for a paper by Nose and Hoover if you
write a fix that implements their integrator is not the intended usage.
That latter 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.
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 <testing>` for more information on
how to enable, run, and expand testing.

BIN
doc/src/PDF/CG-DNA.pdf
View File

Binary file not shown.

BIN
doc/src/PDF/colvars-refman-lammps.pdf
View File

Binary file not shown.

34
doc/src/Packages_details.rst
View File

@ -9,7 +9,7 @@ gives links to documentation, example scripts, and pictures/movies (if
available) that illustrate use of the package.
The majority of packages can be included in a LAMMPS build with a
single setting (``-D PGK_<NAME>=on`` for CMake) or command
single setting (``-D PKG_<NAME>=on`` for CMake) or command
(``make yes-<name>`` for make). See the :doc:`Build package <Build_package>`
page for more info. A few packages may require additional steps;
this is indicated in the descriptions below. The :doc:`Build extras <Build_extras>`
@ -915,7 +915,7 @@ This package has :ref:`specific installation instructions <gpu>` on the :doc:`Bu
* :doc:`package gpu <package>`
* :doc:`Commands <Commands_all>` pages (:doc:`pair <Commands_pair>`, :doc:`kspace <Commands_kspace>`)
for styles followed by (g)
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of website
----------
@ -1027,7 +1027,7 @@ This package has :ref:`specific installation instructions <intel>` on the :doc:`
* Search the :doc:`commands <Commands_all>` pages (:doc:`fix <Commands_fix>`, :doc:`compute <Commands_compute>`,
:doc:`pair <Commands_pair>`, :doc:`bond, angle, dihedral, improper <Commands_bond>`, :doc:`kspace <Commands_kspace>`) for styles followed by (i)
* src/INTEL/TEST
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of website
----------
@ -1164,7 +1164,7 @@ This package has :ref:`specific installation instructions <kokkos>` on the :doc:
* Search the :doc:`commands <Commands_all>` pages (:doc:`fix <Commands_fix>`, :doc:`compute <Commands_compute>`,
:doc:`pair <Commands_pair>`, :doc:`bond, angle, dihedral, improper <Commands_bond>`,
:doc:`kspace <Commands_kspace>`) for styles followed by (k)
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of website
----------
@ -1242,7 +1242,7 @@ A fix command which wraps the LATTE DFTB code, so that molecular
dynamics can be run with LAMMPS using density-functional tight-binding
quantum forces calculated by LATTE.
More information on LATTE can be found at this web site:
More information on LATTE can be found at this website:
`https://github.com/lanl/LATTE <latte-home_>`_. A brief technical
description is given with the :doc:`fix latte <fix_latte>` command.
@ -1880,6 +1880,12 @@ MPIIO library. It adds :doc:`dump styles <dump>` with a "mpiio" in
their style name. Restart files with an ".mpiio" suffix are also
written and read in parallel.
.. warning::
The MPIIO package is currently unmaintained and has become
unreliable. Use with caution.
**Install:**
The MPIIO package requires that LAMMPS is build in :ref:`MPI parallel mode <serial>`.
@ -2017,7 +2023,7 @@ the :doc:`Build extras <Build_extras>` page.
* Search the :doc:`commands <Commands_all>` pages (:doc:`fix <Commands_fix>`, :doc:`compute <Commands_compute>`,
:doc:`pair <Commands_pair>`, :doc:`bond, angle, dihedral, improper <Commands_bond>`,
:doc:`kspace <Commands_kspace>`) for styles followed by (o)
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of website
----------
@ -2051,7 +2057,7 @@ This package has :ref:`specific installation instructions <opt>` on the :doc:`Bu
* :doc:`OPT package <Speed_opt>`
* :doc:`Section 2.6 -sf opt <Run_options>`
* Search the :doc:`pair style <Commands_pair>` page for styles followed by (t)
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of website
.. _PKG-ORIENT:
@ -2248,16 +2254,16 @@ PYTHON package
A :doc:`python <python>` command which allow you to execute Python code
from a LAMMPS input script. The code can be in a separate file or
embedded in the input script itself. See the :doc:`Python call <Python_call>` page for an overview of using Python from
LAMMPS in this manner and all the :doc:`Python <Python_head>` manual pages
for other ways to use LAMMPS and Python together.
embedded in the input script itself. See the :doc:`Python call
<Python_call>` page for an overview of using Python from LAMMPS in this
manner and all the :doc:`Python <Python_head>` manual pages for other
ways to use LAMMPS and Python together.
.. note::
Building with the PYTHON package assumes you have a Python
shared library available on your system, which needs to be a Python 2
version, 2.6 or later. Python 3 is not yet supported. See the
lib/python/README for more details.
Building with the PYTHON package assumes you have a Python development
environment (headers and libraries) available on your system, which needs
to be either Python version 2.7 or Python 3.5 and later.
**Install:**

118
doc/src/Python_install.rst
View File

@ -25,11 +25,10 @@ Installing the LAMMPS Python Module and Shared Library
======================================================
Making LAMMPS usable within Python and vice versa requires putting the
LAMMPS Python package (``lammps``) into a location where the
Python interpreter can find it and installing the LAMMPS shared library
into a folder that the dynamic loader searches or inside of the installed
``lammps`` package folder. There are multiple ways to achieve
this.
LAMMPS Python package (``lammps``) into a location where the Python
interpreter can find it and installing the LAMMPS shared library into a
folder that the dynamic loader searches or inside of the installed
``lammps`` package folder. There are multiple ways to achieve this.
#. Do a full LAMMPS installation of libraries, executables, selected
headers, documentation (if enabled), and supporting files (only
@ -159,38 +158,52 @@ this.
make install-python
This will try to install (only) the shared library and the Python
package into a system folder and if that fails (due to missing
write permissions) will instead do the installation to a user
folder under ``$HOME/.local``. For a system-wide installation you
This will try to build a so-called (binary) 'wheel', a compressed
binary python package and then install it with the python package
manager 'pip'. Installation will be attempted into a system-wide
``site-packages`` folder and if that fails into the corresponding
folder in the user's home directory. For a system-wide installation you
would have to gain superuser privilege, e.g. though ``sudo``
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=================================================================+=============================================================+
| LAMMPS Python package | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+------------------------+----------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+==========================================================+=============================================================+
| LAMMPS Python package | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+----------------------------------------------------------+-------------------------------------------------------------+
For a system-wide installation those folders would then become.
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=========================================================+=============================================================+
| LAMMPS Python package | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
+------------------------+-------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=================================================+=============================================================+
| LAMMPS Python package | * ``/usr/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+-------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``/usr/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+-------------------------------------------------+-------------------------------------------------------------+
No environment variables need to be set for those, as those
folders are searched by default by Python or the LAMMPS Python
package.
.. versionchanged:: TBD
.. note::
If there is an existing installation of the LAMMPS python
module, ``make install-python`` will try to update it.
However, that will fail if the older version of the module
was installed by LAMMPS versions until 17Feb2022. Those
were using the distutils package, which does not create a
"manifest" that allows a clean uninstall. The ``make
install-python`` command will always produce a
lammps-<version>-<python>-<abi>-<os>-<arch>.whl file (the
'wheel'). And this file can be later installed directly with
``python -m pip install <wheel file>.whl`` without having to
type ``make install-python`` again and repeating the build
step, too.
For the traditional make process you can override the python
version to version x.y when calling ``make`` with
``PYTHON=pythonX.Y``. For a CMake based compilation this choice
@ -201,16 +214,12 @@ this.
.. code-block:: bash
$ python install.py -p <python package> -l <shared library> -v <version.h file> [-d <pydir>]
$ python install.py -p <python package> -l <shared library> [-n]
* The ``-p`` flag points to the ``lammps`` Python package folder to be installed,
* the ``-l`` flag points to the LAMMPS shared library file to be installed,
* the ``-v`` flag points to the ``version.h`` file in the LAMMPS source
* and the optional ``-d`` flag to a custom (legacy) installation folder
If you use a legacy installation folder, you will need to set your
``PYTHONPATH`` and ``LD_LIBRARY_PATH`` (and/or ``DYLD_LIBRARY_PATH``) environment
variables accordingly as explained in the description for "In place use".
* and the optional ``-n`` instructs the script to only build a wheel file
but not attempt to install it.
.. tab:: Virtual environment
@ -257,32 +266,29 @@ this.
package and the shared library file are installed into the
following locations:
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=================================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+========================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
If you do a full installation (CMake only) with "install", this
leads to the following installation locations:
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=================================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/`` (32bit) | Set shared loader environment variable to this path |
| | * ``$VIRTUAL_ENV/lib64/`` (64bit) | (see below for more info on this) |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``$VIRTUAL_ENV/bin/`` | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$VIRTUAL_ENV/share/lammps/potentials/`` | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+========================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/`` (32bit) | Set shared loader environment variable to this path |
| | * ``$VIRTUAL_ENV/lib64/`` (64bit) | (see below for more info on this) |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``$VIRTUAL_ENV/bin/`` | |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$VIRTUAL_ENV/share/lammps/potentials/`` | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
In that case you need to modify the ``$HOME/myenv/bin/activate``
script in a similar fashion you need to update your

16
doc/src/Run_basics.rst
View File

@ -2,17 +2,25 @@ Basics of running LAMMPS
========================
LAMMPS is run from the command line, reading commands from a file via
the -in command line flag, or from standard input.
Using the "-in in.file" variant is recommended:
the -in command line flag, or from standard input. Using the "-in
in.file" variant is recommended (see note below). The name of the
LAMMPS executable is either ``lmp`` or ``lmp_<machine>`` with
`<machine>` being the machine string used when compiling LAMMPS. This
is required when compiling LAMMPS with the traditional build system
(e.g. with ``make mpi``), but optional when using CMake to configure and
build LAMMPS:
.. code-block:: bash
$ lmp_serial -in in.file
$ lmp_serial < in.file
$ lmp -in in.file
$ lmp < in.file
$ /path/to/lammps/src/lmp_serial -i in.file
$ mpirun -np 4 lmp_mpi -in in.file
$ mpiexec -np 4 lmp -in in.file
$ mpirun -np 8 /path/to/lammps/src/lmp_mpi -in in.file
$ mpirun -np 6 /usr/local/bin/lmp -in in.file
$ mpiexec -n 6 /usr/local/bin/lmp -in in.file
You normally run the LAMMPS command in the directory where your input
script is located. That is also where output files are produced by
@ -23,7 +31,7 @@ executable itself can be placed elsewhere.
.. note::
The redirection operator "<" will not always work when running
in parallel with mpirun; for those systems the -in form is required.
in parallel with mpirun or mpiexec; for those systems the -in form is required.
As LAMMPS runs it prints info to the screen and a logfile named
*log.lammps*\ . More info about output is given on the

27
doc/src/Run_options.rst
View File

@ -2,7 +2,7 @@ Command-line options
====================
At run time, LAMMPS recognizes several optional command-line switches
which may be used in any order. Either the full word or a one-or-two
which may be used in any order. Either the full word or a one or two
letter abbreviation can be used:
* :ref:`-e or -echo <echo>`
@ -22,6 +22,7 @@ letter abbreviation can be used:
* :ref:`-r2data or -restart2data <restart2data>`
* :ref:`-r2dump or -restart2dump <restart2dump>`
* :ref:`-sc or -screen <screen>`
* :ref:`-sr or skiprun <skiprun>`
* :ref:`-sf or -suffix <suffix>`
* :ref:`-v or -var <var>`
@ -241,10 +242,11 @@ links with from the lib/message directory. See the
**-cite style** or **file name**
Select how and where to output a reminder about citing contributions
to the LAMMPS code that were used during the run. Available styles are
"both", "none", "screen", or "log". Any flag will be considered a file
name to write the detailed citation info to. Default is the "log" style
where there is a short summary in the screen output and detailed citations
to the LAMMPS code that were used during the run. Available keywords
for styles are "both", "none", "screen", or "log". Any other keyword
will be considered a file name to write the detailed citation info to
instead of logfile or screen. Default is the "log" style where there
is a short summary in the screen output and detailed citations
in BibTeX format in the logfile. The option "both" selects the detailed
output for both, "none", the short output for both, and "screen" will
write the detailed info to the screen and the short version to the log
@ -532,6 +534,21 @@ partition screen files file.N.
----------
.. _skiprun:
**-skiprun**
Insert the command :doc:`timer timeout 0 every 1 <timer>` at the
beginning of an input file or after a :doc:`clear <clear>` command.
This has the effect that the entire LAMMPS input script is processed
without executing actual :doc:`run <run>` or :doc:`minimize <minimize>`
and similar commands (their main loops are skipped). This can be
helpful and convenient to test input scripts of long running
calculations for correctness to avoid having them crash after a
long time due to a typo or syntax error in the middle or at the end.
----------
.. _suffix:
**-suffix style args**

4
doc/src/Run_output.rst
View File

@ -106,7 +106,7 @@ individual ranks. Here is an example output for this section:
----------
The third section above lists the number of owned atoms (Nlocal),
ghost atoms (Nghost), and pair-wise neighbors stored per processor.
ghost atoms (Nghost), and pairwise neighbors stored per processor.
The max and min values give the spread of these values across
processors with a 10-bin histogram showing the distribution. The total
number of histogram counts is equal to the number of processors.
@ -114,7 +114,7 @@ number of histogram counts is equal to the number of processors.
----------
The last section gives aggregate statistics (across all processors)
for pair-wise neighbors and special neighbors that LAMMPS keeps track
for pairwise neighbors and special neighbors that LAMMPS keeps track
of (see the :doc:`special_bonds <special_bonds>` command). The number
of times neighbor lists were rebuilt is tallied, as is the number of
potentially *dangerous* rebuilds. If atom movement triggered neighbor

4
doc/src/Speed.rst
View File

@ -13,8 +13,8 @@ for certain kinds of hardware, including multi-core CPUs, GPUs, and
Intel Xeon Phi co-processors.
The `Benchmark page <https://www.lammps.org/bench.html>`_ of the LAMMPS
web site gives performance results for the various accelerator
packages discussed on the :doc:`Speed packages <Speed_packages>` doc
website gives performance results for the various accelerator
packages discussed on the :doc:`Accelerator packages <Speed_packages>`
page, for several of the standard LAMMPS benchmark problems, as a
function of problem size and number of compute nodes, on different
hardware platforms.

Some files were not shown because too many files have changed in this diff Show More