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

Merge branch 'lammps:master' into type-labels

Browse Source
This commit is contained in:
Jacob Gissinger
2021-09-30 09:44:18 -04:00
committed by GitHub
parent f7bd07b3e6 4d84ceb822
commit 67ae6eb7b6
1396 changed files with 36153 additions and 25022 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/CODEOWNERS vendored
View File

@ -129,7 +129,7 @@ src/math_eigen_impl.h @jewettaij
tools/msi2lmp/* @akohlmey
tools/emacs/* @HaoZeke
tools/singularity/* @akohlmey @rbberger
tools/code_standard/* @rbberger
tools/coding_standard/* @rbberger
tools/valgrind/* @akohlmey
tools/swig/* @akohlmey
tools/offline/* @rbberger

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.

10
cmake/.coveragerc.in Normal file
View File

@ -0,0 +1,10 @@
[run]
source = @LAMMPS_PYTHON_DIR@
parallel=True
branch=True
omit=*/install.py
*/setup.py
[paths]
sources = python
@LAMMPS_PYTHON_DIR@

15
cmake/CMakeLists.txt
View File

@ -36,7 +36,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)
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
@ -90,6 +94,10 @@ endif()
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF CACHE BOOL "Use compiler extensions")
# ugly hack for MSVC which by default always reports an old C++ standard in the __cplusplus macro
if(MSVC)
add_compile_options(/Zc:__cplusplus)
endif()
# export all symbols when building a .dll file on windows
if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND BUILD_SHARED_LIBS)
@ -769,6 +777,13 @@ endif()
include(Testing)
include(CodeCoverage)
include(CodingStandard)
find_package(ClangFormat 8.0)
if(ClangFormat_FOUND)
add_custom_target(format-src
COMMAND ${ClangFormat_EXECUTABLE} --verbose -i -style=file *.cpp *.h */*.cpp */*.h
WORKING_DIRECTORY ${LAMMPS_SOURCE_DIR})
endif()
get_target_property(DEFINES lammps COMPILE_DEFINITIONS)
include(FeatureSummary)

10
cmake/Modules/CodeCoverage.cmake
View File

@ -54,6 +54,8 @@ if(ENABLE_COVERAGE)
if(COVERAGE_FOUND)
set(PYTHON_COVERAGE_HTML_DIR ${CMAKE_BINARY_DIR}/python_coverage_html)
configure_file(.coveragerc.in ${CMAKE_BINARY_DIR}/.coveragerc @ONLY)
add_custom_command(
OUTPUT ${CMAKE_BINARY_DIR}/unittest/python/.coverage
COMMAND ${COVERAGE_BINARY} combine
@ -63,16 +65,16 @@ if(ENABLE_COVERAGE)
add_custom_target(
gen_python_coverage_html
COMMAND ${COVERAGE_BINARY} html -d ${PYTHON_COVERAGE_HTML_DIR}
DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage
COMMAND ${COVERAGE_BINARY} html --rcfile=${CMAKE_BINARY_DIR}/.coveragerc -d ${PYTHON_COVERAGE_HTML_DIR}
DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage ${CMAKE_BINARY_DIR}/.coveragerc
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python
COMMENT "Generating HTML Python coverage report..."
)
add_custom_target(
gen_python_coverage_xml
COMMAND ${COVERAGE_BINARY} xml -o ${CMAKE_BINARY_DIR}/python_coverage.xml
DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage
COMMAND ${COVERAGE_BINARY} xml --rcfile=${CMAKE_BINARY_DIR}/.coveragerc -o ${CMAKE_BINARY_DIR}/python_coverage.xml
DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage ${CMAKE_BINARY_DIR}/.coveragerc
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python
COMMENT "Generating XML Python coverage report..."
)

4
cmake/Modules/OpenCLLoader.cmake
View File

@ -1,6 +1,6 @@
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-2021.09.18.tar.gz" CACHE STRING "URL for OpenCL loader tarball")
set(OPENCL_LOADER_MD5 "3b3882627964bd02e5c3b02065daac3c" CACHE STRING "MD5 checksum of OpenCL loader tarball")
mark_as_advanced(OPENCL_LOADER_URL)
mark_as_advanced(OPENCL_LOADER_MD5)

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

@ -71,6 +71,11 @@ 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}")
# apply the following to build "fat" CUDA binaries only for known CUDA toolkits
if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
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] ")
@ -107,8 +112,6 @@ if(GPU_API STREQUAL "CUDA")
if(CUDA_VERSION VERSION_GREATER_EQUAL "11.1")
string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_86,code=[sm_86,compute_86]")
endif()
if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
message(WARNING "Unsupported CUDA version. Use at your own risk.")
endif()
cuda_compile_fatbin(GPU_GEN_OBJS ${GPU_LIB_CU} OPTIONS ${CUDA_REQUEST_PIC}
@ -214,13 +217,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)
@ -322,10 +332,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 +385,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__)

4
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)
set(CMAKE_CXX_STANDARD 14)
endif()
########################################################################
# consistency checks and Kokkos options/settings required by LAMMPS
if(Kokkos_ENABLE_CUDA)

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}

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

@ -45,12 +45,12 @@ 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(N2P2_PROJECT_OPTIONS "-I${N2P2_MPI_INCLUDE}")
set(MPI_CXX_COMPILER ${CMAKE_CXX_COMPILER})
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(N2P2_PROJECT_OPTIONS "-I${N2P2_MPI_INCLUDE}")
set(MPI_CXX_COMPILER ${CMAKE_CXX_COMPILER})
endif()
endif()
@ -69,6 +69,12 @@ if(DOWNLOAD_N2P2)
# 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

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

@ -38,7 +38,7 @@ if(DOWNLOAD_QUIP)
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 +50,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 ""

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

@ -12,6 +12,13 @@ if(DOWNLOAD_MSCG)
mark_as_advanced(MSCG_URL)
mark_as_advanced(MSCG_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 MSCG library due to a technical limitation")
endif()
include(ExternalProject)
ExternalProject_Add(mscg_build
URL ${MSCG_URL}

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}

10
cmake/Modules/Tools.cmake
View File

@ -9,14 +9,16 @@ if(BUILD_TOOLS)
check_language(Fortran)
if(CMAKE_Fortran_COMPILER)
enable_language(Fortran)
add_executable(chain.x ${LAMMPS_TOOLS_DIR}/chain.f)
add_executable(chain.x ${LAMMPS_TOOLS_DIR}/chain.f90)
target_link_libraries(chain.x PRIVATE ${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES})
install(TARGETS chain.x DESTINATION ${CMAKE_INSTALL_BINDIR})
add_executable(micelle2d.x ${LAMMPS_TOOLS_DIR}/micelle2d.f90)
target_link_libraries(micelle2d.x PRIVATE ${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES})
install(TARGETS chain.x micelle2d.x DESTINATION ${CMAKE_INSTALL_BINDIR})
else()
message(WARNING "No suitable Fortran compiler found, skipping build of 'chain.x'")
message(WARNING "No suitable Fortran compiler found, skipping build of 'chain.x' and 'micelle2d.x'")
endif()
else()
message(WARNING "CMake build doesn't support fortran, skipping build of 'chain.x'")
message(WARNING "CMake build doesn't support Fortran, skipping build of 'chain.x' and 'micelle2d.x'")
endif()
enable_language(C)

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

@ -1,7 +1,28 @@
[
{ 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: [ "@\"nstenci_.*.h\"", public, "\"style_nstencil.h\"", public ] },
{ include: [ "@\"ntopo_.*.h\"", public, "\"style_ntopo.h\"", public ] },
{ include: [ "<float.h>", public, "<cfloat>", public ] },
{ include: [ "<limits.h>", public, "<climits>", public ] },
{ include: [ "<bits/types/struct_tm.h>", private, "<ctime>", public ] },
]

6
cmake/presets/clang.cmake
View File

@ -10,9 +10,9 @@ 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=f95" CACHE STRING "" FORCE)
set(CMAKE_Fortran_FLAGS_RELWITHDEBINFO "-Wall -Wextra -g -O2 -DNDEBUG -std=f95" CACHE STRING "" FORCE)
set(CMAKE_Fortran_FLAGS_RELEASE "-O3 -DNDEBUG -std=f95" 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)

8
cmake/presets/gcc.cmake
View File

@ -1,4 +1,4 @@
# preset that will restore gcc/g++ with support for MPI and OpenMP (on Linux boxes)
# preset that will explicitly request gcc/g++ compilers with support for MPI and OpenMP
set(CMAKE_CXX_COMPILER "g++" CACHE STRING "" FORCE)
set(CMAKE_C_COMPILER "gcc" CACHE STRING "" FORCE)
@ -15,9 +15,9 @@ 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" CACHE STRING "" FORCE)
set(CMAKE_Fortran_FLAGS_RELWITHDEBINFO "-g -O2 -DNDEBUG" CACHE STRING "" FORCE)
set(CMAKE_Fortran_FLAGS_RELEASE "-O3 -DNDEBUG" CACHE STRING "" FORCE)
set(CMAKE_Fortran_FLAGS_DEBUG "-Wall -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)
set(OpenMP_C "gcc" CACHE STRING "" FORCE)

20
cmake/presets/hip.cmake
View File

@ -1,12 +1,26 @@
# preset that will enable hipcc plus gcc with support for MPI and OpenMP (on Linux boxes)
# preset that will enable hipcc plus gcc/gfortran with support for MPI and OpenMP (on Linux boxes)
set(CMAKE_CXX_COMPILER "hipcc" 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 -Wextra -g" CACHE STRING "" FORCE)
set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "-Wall -Wextra -g -O2 -DNDEBUG" CACHE STRING "" FORCE)
unset(HAVE_OMP_H_INCLUDE CACHE)
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(OpenMP_CXX "hipcc" 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 "gcc" CACHE STRING "" FORCE)
set(OpenMP_C_FLAGS "-fopenmp" CACHE STRING "" FORCE)
set(OpenMP_C_LIB_NAMES "gomp" CACHE STRING "" FORCE)
set(OpenMP_CXX_FLAGS "-fopenmp" CACHE STRING "" FORCE)
set(OpenMP_CXX "hipcc" CACHE STRING "" FORCE)
set(OpenMP_CXX_LIB_NAMES "omp" CACHE STRING "" FORCE)
set(OpenMP_omp_LIBRARY "libomp.so" CACHE PATH "" FORCE)

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)

1
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

137
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,10 +23,10 @@ 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.
@ -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 "master" 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 "master" 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 "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.
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.

53
doc/lammps.1
View File

@ -1,4 +1,4 @@
.TH LAMMPS "30 July 2021" "2021-07-30"
.TH LAMMPS "29 September 2021" "2021-09-29"
.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
@ -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

2
doc/msi2lmp.1
View File

@ -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

1
doc/src/Build.rst
View File

@ -22,4 +22,5 @@ page.
Build_extras
Build_manual
Build_windows
Build_diskspace
Build_development

93
doc/src/Build_development.rst
View File

@ -1,15 +1,15 @@
Development build options (CMake only)
======================================
Development build options
=========================
The CMake build procedure of LAMMPS offers a few extra options which are
The build procedures in LAMMPS offers a few extra options which are
useful during development, testing or debugging.
----------
.. _compilation:
Monitor compilation flags
-------------------------
Monitor compilation flags (CMake only)
--------------------------------------
Sometimes it is necessary to verify the complete sequence of compilation flags
generated by the CMake build. To enable a more verbose output during
@ -30,8 +30,8 @@ variable VERBOSE set to 1:
.. _clang-tidy:
Enable static code analysis with clang-tidy
-------------------------------------------
Enable static code analysis with clang-tidy (CMake only)
--------------------------------------------------------
The `clang-tidy tool <https://clang.llvm.org/extra/clang-tidy/>`_ is a
static code analysis tool to diagnose (and potentially fix) typical
@ -52,20 +52,22 @@ significantly more time consuming than the compilation itself.
.. _iwyu_processing:
Report missing and unneeded '#include' statements
-------------------------------------------------
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
@ -86,8 +88,8 @@ on recording all commands required to do the compilation.
.. _sanitizer:
Address, Undefined Behavior, and Thread Sanitizer Support
---------------------------------------------------------
Address, Undefined Behavior, and Thread Sanitizer Support (CMake only)
----------------------------------------------------------------------
Compilers such as GCC and Clang support generating instrumented binaries
which use different sanitizer libraries to detect problems in the code
@ -116,8 +118,8 @@ compilation and linking stages. This is done through setting the
.. _testing:
Code Coverage and Unit Testing
------------------------------
Code Coverage and Unit Testing (CMake only)
-------------------------------------------
The LAMMPS code is subject to multiple levels of automated testing
during development: integration testing (i.e. whether the code compiles
@ -464,7 +466,8 @@ Coding style utilities
To aid with enforcing some of the coding style conventions in LAMMPS
some additional build targets have been added. These require Python 3.5
or later and will only work on Unix-like operating and file systems.
or later and will only work properly on Unix-like operating and file systems.
The following options are available.
.. code-block:: bash
@ -476,17 +479,43 @@ The following options are available.
make check-permissions # search for files with permissions issues
make fix-permissions # correct permissions issues in files
These should help to replace all TAB characters with blanks and remove
any trailing whitespace. Also all LAMMPS homepage URL references can be
updated to the location change from Sandia to the lammps.org domain.
And the permission check can remove executable permissions from non-executable
files (like source code).
Clang-format support
--------------------
For the code in the ``unittest`` and ``src`` trees we are transitioning
to use the `clang-format` tool to assist with having a consistent source
code style. The `clang-format` command bundled with Clang version 8.0
or later is required. The configuration is in files ``.clang-format``
in the respective folders. Since the modifications from `clang-format`
can be significant and - especially for "legacy style code" - also is
not always improving readability, a large number of files currently have
a ``// clang-format off`` at the top, which will disable the processing.
Over time, files will be refactored and updated to that `clang-format`
may be applied to them (at least in part).
code formatting style. The `clang-format` command bundled with Clang
version 8.0 or later is required. The configuration is in files called
``.clang-format`` in the respective folders. Since the modifications
from `clang-format` can be significant and - especially for "legacy
style code" - they are not always improving readability, a large number
of files currently have a ``// clang-format off`` at the top, which will
disable the processing. As of fall 2021 all files have been either
"protected" this way or are enabled for full or partial `clang-format`
processing. Over time, the "protected" files will be refactored and
updated so that `clang-format` may be applied to them as well.
If `clang-format` is available, the source code files in the ``unittest``
tree can be updated to conform to the formatting settings using
``make format-tests`` and the files in ``src`` with ``make format-src``.
It is recommended for all newly contributed files to use the clang-format
processing while writing the code or do the coding style processing
(including the scripts mentioned in the previous paragraph)
If `clang-format` is available, files can be updated individually with
commands like the following:
.. code-block:: bash
$ clang-format -i some_file.cpp
The following target are available for both, GNU make and CMake:
.. code-block:: bash
make format-src # apply clang-format to all files in src and the package folders
make format-tests # apply clang-format to all files in the unittest tree

45
doc/src/Build_diskspace.rst Normal file
View File

@ -0,0 +1,45 @@
Notes for saving disk space when building LAMMPS from source
------------------------------------------------------------
LAMMPS is a large software project with a large number of source files,
extensive documentation, and a large collection of example files.
When downloading LAMMPS by cloning the
`git repository from GitHub <https://github.com/lammps/lammps>`_ this
will by default also download the entire commit history since September 2006.
Compiling LAMMPS will add the storage requirements of the compiled object
files and libraries to the tally.
In a user account on an HPC cluster with filesystem quotas or in other
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``.
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).
- Download a tar archive from either the `download section on the LAMMPS homepage <https://www.lammps.org/download.html>`_
or from the `LAMMPS releases page on GitHub <https://github.com/lammps/lammps/releases>`_ these will not
contain the git history at all.
- Build LAMMPS without the debug flag (remove ``-g`` from the machine makefile or use ``-DCMAKE_BUILD_TYPE=Release``)
or use the ``strip`` command on the LAMMPS executable when no more debugging would be needed. The strip command
may also be applied to the LAMMPS shared library. The static library may be deleted entirely.
- Delete compiled object files and libraries after copying the LAMMPS executable to a permanent location.
When using the traditional build process, one may use ``make clean-<machine>`` or ``make clean-all``
to delete object files in the src folder. For CMake based builds, one may use ``make clean`` or just
delete the entire build folder.
- The folders containing the documentation tree (doc), the examples (examples) are not needed to build and
run LAMMPS and can be safely deleted. Some files in the potentials folder are large and may be deleted,
if not needed. The largest of those files (occupying about 120 MBytes combined) will only be downloaded on
demand, when the corresponding package is installed.
- When using the CMake build procedure, the compilation can be done on a (local) scratch storage that will not
count toward the quota. A local scratch file system may offer the additional benefit of speeding up creating
object files and linking with libraries compared to a networked file system. Also with CMake (and unlike with
the traditional make) it is possible to compile LAMMPS executables with different settings and packages included
from the same source tree since all the configuration information is stored in the build folder. So it is
not necessary to have multiple copies of LAMMPS.

5
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.
@ -75,8 +74,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

3
doc/src/Build_settings.rst
View File

@ -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

2
doc/src/Commands_compute.rst
View File

@ -152,7 +152,7 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`temp/chunk <compute_temp_chunk>`
* :doc:`temp/com <compute_temp_com>`
* :doc:`temp/cs <compute_temp_cs>`
* :doc:`temp/deform <compute_temp_deform>`
* :doc:`temp/deform (k) <compute_temp_deform>`
* :doc:`temp/deform/eff <compute_temp_deform_eff>`
* :doc:`temp/drude <compute_temp_drude>`
* :doc:`temp/eff <compute_temp_eff>`

3
doc/src/Commands_fix.rst
View File

@ -148,7 +148,7 @@ OPT.
* :doc:`nvt/body <fix_nvt_body>`
* :doc:`nvt/eff <fix_nh_eff>`
* :doc:`nvt/manifold/rattle <fix_nvt_manifold_rattle>`
* :doc:`nvt/sllod (io) <fix_nvt_sllod>`
* :doc:`nvt/sllod (iko) <fix_nvt_sllod>`
* :doc:`nvt/sllod/eff <fix_nvt_sllod_eff>`
* :doc:`nvt/sphere (o) <fix_nvt_sphere>`
* :doc:`nvt/uef <fix_nh_uef>`
@ -236,6 +236,7 @@ OPT.
* :doc:`ti/spring <fix_ti_spring>`
* :doc:`tmd <fix_tmd>`
* :doc:`ttm <fix_ttm>`
* :doc:`ttm/grid <fix_ttm>`
* :doc:`ttm/mod <fix_ttm>`
* :doc:`tune/kspace <fix_tune_kspace>`
* :doc:`vector <fix_vector>`

74
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
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
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.

1
doc/src/Commands_kspace.rst
View File

@ -24,6 +24,7 @@ OPT.
* :doc:`ewald (o) <kspace_style>`
* :doc:`ewald/disp <kspace_style>`
* :doc:`ewald/disp/dipole <kspace_style>`
* :doc:`ewald/dipole <kspace_style>`
* :doc:`ewald/dipole/spin <kspace_style>`
* :doc:`msm (o) <kspace_style>`

1
doc/src/Developer.rst
View File

@ -11,6 +11,7 @@ of time and requests from the LAMMPS user community.
:maxdepth: 1
Developer_org
Developer_parallel
Developer_flow
Developer_write
Developer_notes

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

12
doc/src/Developer_utils.rst
View File

@ -60,6 +60,9 @@ 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.
Similarly the :cpp:func:`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()``
@ -83,6 +86,9 @@ strings for compliance without conversion.
.. doxygenfunction:: tnumeric
:project: progguide
.. doxygenfunction:: logical
:project: progguide
String processing
^^^^^^^^^^^^^^^^^
@ -203,9 +209,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

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)

12
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
@ -7894,19 +7894,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*

4
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
@ -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

1
doc/src/Howto.rst
View File

@ -54,6 +54,7 @@ Analysis howto
Howto_kappa
Howto_viscosity
Howto_diffusion
Howto_structured_data
Force fields howto
==================

154
doc/src/Howto_structured_data.rst Normal file
View File

@ -0,0 +1,154 @@
Output structured data from LAMMPS
##################################
LAMMPS can output structured data with the :doc:`print <print>` and :doc:`fix
print <fix_print>` command. This gives you flexibility since you can build
custom data formats that contain system properties, thermo data, and variables
values. This output can be directed to the screen and/or to a file for post
processing.
Writing the current system state, thermo data, variable values
==============================================================
Use the :doc:`print <print>` command to output the current system state, which
can include system properties, thermo data and variable values.
YAML
----
.. code-block:: LAMMPS
print """---
timestep: $(step)
pe: $(pe)
ke: $(ke)""" file current_state.yaml screen no
.. code-block:: yaml
:caption: current_state.yaml
---
timestep: 250
pe: -4.7774327356321810711
ke: 2.4962152903997174569
JSON
----
.. code-block:: LAMMPS
print """{
"timestep": $(step),
"pe": $(pe),
"ke": $(ke)
}""" file current_state.json screen no
.. code-block:: JSON
:caption: current_state.json
{
"timestep": 250,
"pe": -4.7774327356321810711,
"ke": 2.4962152903997174569
}
Writing continuous data during a simulation
===========================================
The :doc:`fix print <fix_print>` command allows you to output an arbitrary string at defined times during a simulation run.
YAML
----
.. code-block:: LAMMPS
fix extra all print 50 """
- timestep: $(step)
pe: $(pe)
ke: $(ke)""" file output.yaml screen no
.. code-block:: yaml
:caption: output.yaml
# Fix print output for fix extra
- timestep: 0
pe: -6.77336805325924729
ke: 4.4988750000000026219
- timestep: 50
pe: -4.8082494418323200591
ke: 2.5257981827119797558
- timestep: 100
pe: -4.7875608875581505686
ke: 2.5062598821985102582
- timestep: 150
pe: -4.7471033686005483787
ke: 2.466095925545450207
- timestep: 200
pe: -4.7509052858544134068
ke: 2.4701136792591693592
- timestep: 250
pe: -4.7774327356321810711
ke: 2.4962152903997174569
Post-processing of YAML files can be easily be done with Python and other
scripting languages. In case of Python the `yaml` package allows you to load the
data files and obtain a list of dictionaries.
.. code-block:: python
import yaml
with open("output.yaml") as f:
data = yaml.load(f, Loader=yaml.FullLoader)
print(data)
.. code-block::
[{'timestep': 0, 'pe': -6.773368053259247, 'ke': 4.498875000000003}, {'timestep': 50, 'pe': -4.80824944183232, 'ke': 2.5257981827119798}, {'timestep': 100, 'pe': -4.787560887558151, 'ke': 2.5062598821985103}, {'timestep': 150, 'pe': -4.747103368600548, 'ke': 2.46609592554545}, {'timestep': 200, 'pe': -4.750905285854413, 'ke': 2.4701136792591694}, {'timestep': 250, 'pe': -4.777432735632181, 'ke': 2.4962152903997175}]
Line Delimited JSON (LD-JSON)
-----------------------------
The JSON format itself is very strict when it comes to delimiters. For continuous
output/streaming data it is beneficial use the *line delimited JSON* format.
Each line represents one JSON object.
.. code-block:: LAMMPS
fix extra all print 50 """{"timestep": $(step), "pe": $(pe), "ke": $(ke)}""" title "" file output.json screen no
.. code-block:: json
:caption: output.json
{"timestep": 0, "pe": -6.77336805325924729, "ke": 4.4988750000000026219}
{"timestep": 50, "pe": -4.8082494418323200591, "ke": 2.5257981827119797558}
{"timestep": 100, "pe": -4.7875608875581505686, "ke": 2.5062598821985102582}
{"timestep": 150, "pe": -4.7471033686005483787, "ke": 2.466095925545450207}
{"timestep": 200, "pe": -4.7509052858544134068, "ke": 2.4701136792591693592}
{"timestep": 250, "pe": -4.7774327356321810711, "ke": 2.4962152903997174569}
One simple way to load this data into a Python script is to use the `pandas`
package. It can directly load these files into a data frame:
.. code-block:: python
import pandas as pd
data = pd.read_json('output.json', lines=True)
print(data)
.. code-block:: bash
timestep pe ke
0 0 -6.773368 4.498875
1 50 -4.808249 2.525798
2 100 -4.787561 2.506260
3 150 -4.747103 2.466096
4 200 -4.750905 2.470114
5 250 -4.777433 2.496215

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.

5
doc/src/Intro_authors.rst
View File

@ -29,7 +29,7 @@ The following folks deserve special recognition. Many of the packages
they have written are unique for an MD code and LAMMPS would not be as
general-purpose as it is without their expertise and efforts.
* Metin Aktulga (MSU), REAXFF package for C version of ReaxFF
* Metin Aktulga (MSU), REAXFF package for C/C++ version of ReaxFF
* Mike Brown (Intel), GPU and INTEL packages
* Colin Denniston (U Western Ontario), LATBOLTZ package
* Georg Ganzenmuller (EMI), MACHDYN and SPH packages
@ -37,9 +37,10 @@ general-purpose as it is without their expertise and efforts.
* Reese Jones (Sandia) and colleagues, ATC package for atom/continuum coupling
* Christoph Kloss (DCS Computing), LIGGGHTS code for granular materials, built on top of LAMMPS
* Rudra Mukherjee (JPL), POEMS package for articulated rigid body motion
* Trung Ngyuen (Northwestern U), GPU and RIGID and BODY packages
* Trung Ngyuen (Northwestern U), GPU, RIGID, BODY, and DIELECTRIC packages
* Mike Parks (Sandia), PERI package for Peridynamics
* Roy Pollock (LLNL), Ewald and PPPM solvers
* Julien Tranchida (Sandia), SPIN package
* Christian Trott (Sandia), CUDA and KOKKOS packages
* Ilya Valuev (JIHT), AWPMD package for wave packet MD
* Greg Wagner (Northwestern U), MEAM package for MEAM potential

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.
.. _lammps_paper:
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. (accepted 09/2021), DOI:10.1016/j.cpc.2021.108171 <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>`_
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.
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.

52
doc/src/Intro_features.rst
View File

@ -27,19 +27,19 @@ General features
* distributed memory message-passing parallelism (MPI)
* shared memory multi-threading parallelism (OpenMP)
* spatial decomposition of simulation domain for MPI parallelism
* particle decomposition inside of spatial decomposition for OpenMP parallelism
* particle decomposition inside of spatial decomposition for OpenMP and GPU parallelism
* GPLv2 licensed open-source distribution
* highly portable C++-11
* modular code with most functionality in optional packages
* only depends on MPI library for basic parallel functionality
* only depends on MPI library for basic parallel functionality, MPI stub for serial compilation
* other libraries are optional and only required for specific packages
* GPU (CUDA and OpenCL), Intel Xeon Phi, and OpenMP support for many code features
* GPU (CUDA, OpenCL, HIP, SYCL), Intel Xeon Phi, and OpenMP support for many code features
* easy to extend with new features and functionality
* runs from an input script
* syntax for defining and using variables and formulas
* syntax for looping over runs and breaking out of loops
* run one or multiple simulations simultaneously (in parallel) from one script
* build as library, invoke LAMMPS through library interface or provided Python wrapper
* build as library, invoke LAMMPS through library interface or provided Python wrapper or SWIG based wrappers
* couple with other codes: LAMMPS calls other code, other code calls LAMMPS, umbrella code calls both
.. _particle:
@ -58,8 +58,10 @@ Particle and model types
* coarse-grained mesoscale models
* finite-size spherical and ellipsoidal particles
* finite-size line segment (2d) and triangle (3d) particles
* finite-size rounded polygons (2d) and polyhedra (3d) particles
* point dipole particles
* rigid collections of particles
* particles with magnetic spin
* rigid collections of n particles
* hybrid combinations of these
.. _ff:
@ -74,24 +76,28 @@ commands)
* pairwise potentials: Lennard-Jones, Buckingham, Morse, Born-Mayer-Huggins, Yukawa, soft, class 2 (COMPASS), hydrogen bond, tabulated
* charged pairwise potentials: Coulombic, point-dipole
* many-body potentials: EAM, Finnis/Sinclair EAM, modified EAM (MEAM), embedded ion method (EIM), EDIP, ADP, Stillinger-Weber, Tersoff, REBO, AIREBO, ReaxFF, COMB, SNAP, Streitz-Mintmire, 3-body polymorphic
* long-range interactions for charge, point-dipoles, and LJ dispersion: Ewald, Wolf, PPPM (similar to particle-mesh Ewald)
* many-body potentials: EAM, Finnis/Sinclair EAM, modified EAM (MEAM), embedded ion method (EIM), EDIP, ADP, Stillinger-Weber, Tersoff, REBO, AIREBO, ReaxFF, COMB, Streitz-Mintmire, 3-body polymorphic, BOP, Vashishta
* machine learning potentials: SNAP, GAP, ACE, N2P2, RANN, AGNI
* long-range interactions for charge, point-dipoles, and LJ dispersion: Ewald, Wolf, PPPM (similar to particle-mesh Ewald), MSM
* polarization models: :doc:`QEq <fix_qeq>`, :doc:`core/shell model <Howto_coreshell>`, :doc:`Drude dipole model <Howto_drude>`
* charge equilibration (QEq via dynamic, point, shielded, Slater methods)
* coarse-grained potentials: DPD, GayBerne, REsquared, colloidal, DLVO
* mesoscopic potentials: granular, Peridynamics, SPH
* mesoscopic potentials: granular, Peridynamics, SPH, mesoscopic tubular potential (MESONT)
* semi-empirical potentials: multi-ion generalized pseudopotential theory (MGPT), second moment tight binding + QEq (SMTB-Q), density functional tight-binding (LATTE)
* electron force field (eFF, AWPMD)
* bond potentials: harmonic, FENE, Morse, nonlinear, class 2, quartic (breakable)
* angle potentials: harmonic, CHARMM, cosine, cosine/squared, cosine/periodic, class 2 (COMPASS)
* dihedral potentials: harmonic, CHARMM, multi-harmonic, helix, class 2 (COMPASS), OPLS
* improper potentials: harmonic, cvff, umbrella, class 2 (COMPASS)
* bond potentials: harmonic, FENE, Morse, nonlinear, class 2, quartic (breakable), tabulated
* angle potentials: harmonic, CHARMM, cosine, cosine/squared, cosine/periodic, class 2 (COMPASS), tabulated
* dihedral potentials: harmonic, CHARMM, multi-harmonic, helix, class 2 (COMPASS), OPLS, tabulated
* improper potentials: harmonic, cvff, umbrella, class 2 (COMPASS), tabulated
* polymer potentials: all-atom, united-atom, bead-spring, breakable
* water potentials: TIP3P, TIP4P, SPC
* water potentials: TIP3P, TIP4P, SPC, SPC/E and variants
* interlayer potentials for graphene and analogues
* metal-organic framework potentials (QuickFF, MO-FF)
* implicit solvent potentials: hydrodynamic lubrication, Debye
* force-field compatibility with common CHARMM, AMBER, DREIDING, OPLS, GROMACS, COMPASS options
* access to the `OpenKIM Repository <http://openkim.org>`_ of potentials via :doc:`kim command <kim_commands>`
* hybrid potentials: multiple pair, bond, angle, dihedral, improper potentials can be used in one simulation
* overlaid potentials: superposition of multiple pair potentials
* overlaid potentials: superposition of multiple pair potentials (including many-body) with optional scale factor
.. _create:
@ -124,9 +130,10 @@ Ensembles, constraints, and boundary conditions
* harmonic (umbrella) constraint forces
* rigid body constraints
* SHAKE bond and angle constraints
* Monte Carlo bond breaking, formation, swapping
* motion constraints to manifold surfaces
* Monte Carlo bond breaking, formation, swapping, template based reaction modeling
* atom/molecule insertion and deletion
* walls of various kinds
* walls of various kinds, static and moving
* non-equilibrium molecular dynamics (NEMD)
* variety of additional boundary conditions and constraints
@ -150,6 +157,7 @@ Diagnostics
^^^^^^^^^^^
* see various flavors of the :doc:`fix <fix>` and :doc:`compute <compute>` commands
* introspection command for system, simulation, and compile time settings and configurations
.. _output:
@ -164,8 +172,9 @@ Output
* parallel I/O of dump and restart files
* per-atom quantities (energy, stress, centro-symmetry parameter, CNA, etc)
* user-defined system-wide (log file) or per-atom (dump file) calculations
* spatial and time averaging of per-atom quantities
* time averaging of system-wide quantities
* custom partitioning (chunks) for binning, and static or dynamic grouping of atoms for analysis
* spatial, time, and per-chunk averaging of per-atom quantities
* time averaging and histogramming of system-wide quantities
* atom snapshots in native, XYZ, XTC, DCD, CFG formats
.. _replica1:
@ -178,7 +187,7 @@ Multi-replica models
* :doc:`parallel replica dynamics <prd>`
* :doc:`temperature accelerated dynamics <tad>`
* :doc:`parallel tempering <temper>`
* :doc:`path-integral MD <fix_pimd>`
* path-integral MD: `first variant <fix_pimd>`, `second variant <fix_ipi>`
* multi-walker collective variables with :doc:`Colvars <fix_colvars>` and :doc:`Plumed <fix_plumed>`
.. _prepost:
@ -210,11 +219,12 @@ page for details.
These are LAMMPS capabilities which you may not think of as typical
classical MD options:
* :doc:`static <balance>` and :doc:`dynamic load-balancing <fix_balance>`
* :doc:`static <balance>` and :doc:`dynamic load-balancing <fix_balance>`, optional with recursive bisectioning decomposition
* :doc:`generalized aspherical particles <Howto_body>`
* :doc:`stochastic rotation dynamics (SRD) <fix_srd>`
* :doc:`real-time visualization and interactive MD <fix_imd>`
* :doc:`real-time visualization and interactive MD <fix_imd>`, :doc:`built-in renderer for images and movies <dump_image>`
* calculate :doc:`virtual diffraction patterns <compute_xrd>`
* calculate :doc:`finite temperature phonon dispersion <fix_phonon>` and the :doc:`dynamical matrix of minimized structures <dynamical_matrix>`
* :doc:`atom-to-continuum coupling <fix_atc>` with finite elements
* coupled rigid body integration via the :doc:`POEMS <fix_poems>` library
* :doc:`QM/MM coupling <fix_qmmm>`

55
doc/src/Intro_opensource.rst
View File

@ -1,40 +1,61 @@
LAMMPS open-source license
--------------------------
LAMMPS is a freely-available open-source code, distributed under the
terms of the `GNU Public License Version 2 <gpl_>`_, which means you can
use or modify the code however you wish for your own purposes, but have
to adhere to certain rules when redistributing it or software derived
GPL version of LAMMPS
^^^^^^^^^^^^^^^^^^^^^
LAMMPS is an open-source code, available free-of-charge, and distributed
under the terms of the `GNU Public License Version 2 <gpl_>`_ (GPLv2),
which means you can use or modify the code however you wish for your own
purposes, but have to adhere to certain rules when redistributing it -
specifically in binary form - or are distributing software derived
from it or that includes parts of it.
LAMMPS comes with no warranty of any kind. As each source file states
in its header, it is a copyrighted code that is distributed free-of-
charge, under the terms of the `GNU Public License Version 2 <gpl_>`_
(GPLv2). This is often referred to as open-source distribution - see
`www.gnu.org <gnuorg_>`_ or `www.opensource.org <opensource_>`_. The
legal text of the GPL is in the LICENSE file included in the LAMMPS
distribution.
LAMMPS comes with no warranty of any kind.
As each source file states in its header, it is a copyrighted code, and
thus not in the public domain. For more information about open-source
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
.. _lgpl: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
.. _gnuorg: http://www.gnu.org
.. _opensource: http://www.opensource.org
Here is a summary of what the GPL means for LAMMPS users:
Here is a more specific summary of what the GPL means for LAMMPS users:
(1) Anyone is free to use, modify, or extend LAMMPS in any way they
(1) Anyone is free to use, copy, modify, or extend LAMMPS in any way they
choose, including for commercial purposes.
(2) If you **distribute** a modified version of LAMMPS, it must remain
open-source, meaning you distribute **all** of it under the terms of
the GPL. You should clearly annotate such a code as a derivative version
of LAMMPS.
open-source, meaning you are required to distribute **all** of it under
the terms of the GPL. You should clearly annotate such a modified code
as a derivative version of LAMMPS.
(3) If you release any code that includes or uses LAMMPS source code,
then it must also be open-sourced, meaning you distribute it under
the terms of the GPL.
the terms of the GPL. You may write code that interfaces LAMMPS to
a differently licensed library. In that case the code that provides
the interface must be licensed GPL, but not necessarily that library
unless you are distributing binaries that require the library to run.
(4) If you give LAMMPS files to someone else, the GPL LICENSE file and
source file headers (including the copyright and GPL notices) should
remain part of the code.
LGPL version of LAMMPS
^^^^^^^^^^^^^^^^^^^^^^
We occasionally make stable LAMMPS releases available under the `GNU
Lesser Public License v2.1 <lgpl_>`_. This is on request only and with
non-LGPL compliant files removed. This allows uses linking non-GPL
compatible software with the (otherwise unmodified) LAMMPS library
or loading it dynamically at runtime. Any **modifications** to
the LAMMPS code however, even with the LGPL licensed version, must still
be made available under the same open source terms as LAMMPS itself.

27
doc/src/Intro_overview.rst
View File

@ -10,24 +10,26 @@ conditions. It can model 2d or 3d systems with only a few particles
up to millions or billions.
LAMMPS can be built and run on a laptop or desktop machine, but is
designed for parallel computers. It will run on any parallel machine
that supports the `MPI <mpi_>`_ message-passing library. This includes
shared-memory boxes and distributed-memory clusters and
supercomputers.
designed for parallel computers. It will run in serial and on any
parallel machine that supports the `MPI <mpi_>`_ message-passing
library. This includes shared-memory boxes and distributed-memory
clusters and supercomputers. Parts of LAMMPS also support
`OpenMP multi-threading <omp_>`_, vectorization and GPU acceleration.
.. _mpi: https://en.wikipedia.org/wiki/Message_Passing_Interface
.. _lws: https://www.lammps.org
.. _omp: https://www.openmp.org
LAMMPS is written in C++ and requires a compiler that is at least
compatible with the C++-11 standard.
Earlier versions were written in F77 and F90. See the `History page
compatible with the C++-11 standard. Earlier versions were written in
F77, F90, and C++-98. See the `History page
<https://www.lammps.org/history.html>`_ of the website for details. All
versions can be downloaded from the `LAMMPS website <lws_>`_.
versions can be downloaded as source code from the `LAMMPS website
<lws_>`_.
LAMMPS is designed to be easy to modify or extend with new
capabilities, such as new force fields, atom types, boundary
conditions, or diagnostics. See the :doc:`Modify <Modify>` page for
more details.
LAMMPS is designed to be easy to modify or extend with new capabilities,
such as new force fields, atom types, boundary conditions, or
diagnostics. See the :doc:`Modify <Modify>` page for more details.
In the most general sense, LAMMPS integrates Newton's equations of
motion for a collection of interacting particles. A single particle
@ -47,4 +49,5 @@ MPI parallelization to partition the simulation domain into small
sub-domains of equal computational cost, one of which is assigned to
each processor. Processors communicate and store "ghost" atom
information for atoms that border their sub-domain. Multi-threading
parallelization with with particle-decomposition can be used in addition.
parallelization and GPU acceleration with with particle-decomposition
can be used in addition.

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

21
doc/src/Manual_version.rst
View File

@ -2,12 +2,21 @@ What does a LAMMPS version mean
-------------------------------
The LAMMPS "version" is the date when it was released, such as 1 May
2014. LAMMPS is updated continuously. Whenever we fix a bug or add a
feature, we release it in the next *patch* release, which are
typically made every couple of weeks. Info on patch releases are on
`this website page <https://www.lammps.org/bug.html>`_. Every few
months, the latest patch release is subjected to more thorough testing
and labeled as a *stable* version.
2014. LAMMPS is updated continuously and we aim to keep it working
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
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
<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
and thorough testing than the default automated testing. The latest
patch release after such a period is then labeled as a *stable* version.
Each version of LAMMPS contains all the features and bug-fixes up to
and including its version date.

4
doc/src/Modify.rst
View File

@ -9,13 +9,15 @@ this.
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>`.
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

334
doc/src/Modify_contribute.rst
View File

@ -1,18 +1,16 @@
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
@ -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

4
doc/src/Modify_overview.rst
View File

@ -40,8 +40,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)
...

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

@ -0,0 +1,439 @@
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 and number of convenient
:doc:`utility functions and classes <Developer_utils>` for recurring
tasks 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, especially with HPC cluster
environments, which tend to be running older software stacks and LAMMPS
users may be required to use those older tools or not have the option to
install newer compilers.
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.
- 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.

26
doc/src/Packages_details.rst
View File

@ -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.
@ -2017,7 +2017,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 +2051,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 +2248,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:**

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**

2
doc/src/Speed.rst
View File

@ -13,7 +13,7 @@ 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
website gives performance results for the various accelerator
packages discussed on the :doc:`Speed packages <Speed_packages>` doc
page, for several of the standard LAMMPS benchmark problems, as a
function of problem size and number of compute nodes, on different

2
doc/src/Speed_gpu.rst
View File

@ -153,7 +153,7 @@ usually resulting in inferior performance compared to using LAMMPS' native
threading and vectorization support in the OPENMP and INTEL packages.
See the `Benchmark page <https://www.lammps.org/bench.html>`_ of the
LAMMPS web site for performance of the GPU package on various
LAMMPS website for performance of the GPU package on various
hardware, including the Titan HPC platform at ORNL.
You should also experiment with how many MPI tasks per GPU to use to

2
doc/src/Speed_kokkos.rst
View File

@ -407,7 +407,7 @@ Generally speaking, the following rules of thumb apply:
by switching to single or mixed precision mode.
See the `Benchmark page <https://www.lammps.org/bench.html>`_ of the
LAMMPS web site for performance of the KOKKOS package on different
LAMMPS website for performance of the KOKKOS package on different
hardware.
Advanced Kokkos options

2
doc/src/Speed_packages.rst
View File

@ -144,7 +144,7 @@ sub-directories with Make.py commands and input scripts for using all
the accelerator packages on various machines. See the README files in
those directories.
As mentioned above, the `Benchmark page <https://www.lammps.org/bench.html>`_ of the LAMMPS web site gives
As mentioned above, the `Benchmark page <https://www.lammps.org/bench.html>`_ of the LAMMPS website gives
performance results for the various accelerator packages for several
of the standard LAMMPS benchmark problems, as a function of problem
size and number of compute nodes, on different hardware platforms.

4
doc/src/Tools.rst
View File

@ -7,7 +7,7 @@ steps are often necessary to setup and analyze a simulation. A list
of such tools can be found on the `LAMMPS webpage <lws_>`_ at these links:
* `Pre/Post processing <https://www.lammps.org/prepost.html>`_
* `Offsite LAMMPS packages & tools <https://www.lammps.org/offsite.html>`_
* `External LAMMPS packages & tools <https://www.lammps.org/external.html>`_
* `Pizza.py toolkit <pizza_>`_
The last link for `Pizza.py <pizza_>`_ is a Python-based tool developed at
@ -172,7 +172,7 @@ Chris Lorenz (chris.lorenz at kcl.ac.uk), King's College London.
chain tool
----------------------
The file chain.f creates a LAMMPS data file containing bead-spring
The file chain.f90 creates a LAMMPS data file containing bead-spring
polymer chains and/or monomer solvent atoms. It uses a text file
containing chain definition parameters as an input. The created
chains and solvent atoms can strongly overlap, so LAMMPS needs to run

3
doc/src/angle_cosine_shift.rst
View File

@ -53,7 +53,8 @@ Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package.
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands
""""""""""""""""

2
doc/src/angle_cosine_shift_exp.rst
View File

@ -64,7 +64,7 @@ Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands

2
doc/src/angle_fourier.rst
View File

@ -50,7 +50,7 @@ Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands

2
doc/src/angle_fourier_simple.rst
View File

@ -49,7 +49,7 @@ Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands

2
doc/src/angle_gaussian.rst
View File

@ -49,7 +49,7 @@ Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands

2
doc/src/angle_quartic.rst
View File

@ -57,7 +57,7 @@ Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands

2
doc/src/bond_gaussian.rst
View File

@ -50,7 +50,7 @@ Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands

2
doc/src/bond_harmonic_shift.rst
View File

@ -56,7 +56,7 @@ Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands

2
doc/src/bond_harmonic_shift_cut.rst
View File

@ -54,7 +54,7 @@ Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands

6
doc/src/bond_oxdna.rst
View File

@ -99,10 +99,10 @@ duplexes or arrays of DNA/RNA duplexes can be found in
examples/PACKAGES/cgdna/util/.
Please cite :ref:`(Henrich) <Henrich0>` in any publication that uses
this implementation. The article contains general information
this implementation. An updated documentation that contains general information
on the model, its implementation and performance as well as the structure of
the data and input file. The preprint version of the article can be found
`here <PDF/CG-DNA.pdf>`_.
the data and input file can be found `here <PDF/CG-DNA.pdf>`_.
Please cite also the relevant oxDNA/oxRNA publications. These are
:ref:`(Ouldridge) <Ouldridge0>` and
:ref:`(Ouldridge-DPhil) <Ouldridge-DPhil0>` for oxDNA,

26
doc/src/compute_angle.rst
View File

@ -23,22 +23,23 @@ Examples
Description
"""""""""""
Define a computation that extracts the angle energy calculated by each
of the angle sub-styles used in the doc:`angle_style hybrid <angle_hybrid>`
command. These values are made accessible
for output or further processing by other commands. The group
specified for this command is ignored.
Define a computation that extracts the angle energy calculated by each of the
angle sub-styles used in the :doc:`angle_style hybrid <angle_hybrid>` command.
These values are made accessible for output or further processing by other
commands. The group specified for this command is ignored.
This compute is useful when using :doc:`angle_style hybrid <angle_hybrid>` if you want to know the portion of the total
energy contributed by one or more of the hybrid sub-styles.
This compute is useful when using :doc:`angle_style hybrid <angle_hybrid>` if
you want to know the portion of the total energy contributed by one or more of
the hybrid sub-styles.
Output info
"""""""""""
This compute calculates a global vector of length N where N is the
number of sub_styles defined by the :doc:`angle_style hybrid <angle_style>` command, which can be accessed by indices
1-N. These values can be used by any command that uses global scalar
or vector values from a compute as input. See the :doc:`Howto output <Howto_output>` page for an overview of LAMMPS output
This compute calculates a global vector of length N where N is the number of
sub_styles defined by the :doc:`angle_style hybrid <angle_style>` command,
which can be accessed by indices 1-N. These values can be used by any command
that uses global scalar or vector values from a compute as input. See the
:doc:`Howto output <Howto_output>` page for an overview of LAMMPS output
options.
The vector values are "extensive" and will be in energy
@ -46,7 +47,8 @@ The vector values are "extensive" and will be in energy
Restrictions
""""""""""""
none
none
Related commands
""""""""""""""""

3
doc/src/compute_temp_deform.rst
View File

@ -1,8 +1,11 @@
.. index:: compute temp/deform
.. index:: compute temp/deform/kk
compute temp/deform command
===========================
Accelerator Variants: *temp/deform/kk*
Syntax
""""""

4
doc/src/dihedral_fourier.rst
View File

@ -54,8 +54,8 @@ or :doc:`read_restart <read_restart>` commands:
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
This dihedral style can only be used if LAMMPS was built with the
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands

4
doc/src/dihedral_nharmonic.rst
View File

@ -50,8 +50,8 @@ or :doc:`read_restart <read_restart>` commands:
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
This dihedral style can only be used if LAMMPS was built with the
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands

4
doc/src/dihedral_quadratic.rst
View File

@ -55,8 +55,8 @@ radian\^2.
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
This dihedral style can only be used if LAMMPS was built with the
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands

2
doc/src/dihedral_spherical.rst
View File

@ -89,7 +89,7 @@ Restrictions
""""""""""""
This dihedral style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands

7
doc/src/dihedral_table.rst
View File

@ -244,9 +244,10 @@ script after reading the restart file.
Restrictions
""""""""""""
These dihedral styles can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
The *table* dihedral style can only be used if LAMMPS was built with the
MOLECULE package. The *table/cut* dihedral style can only be used if
LAMMPS was built with the EXTRA-MOLECULE package. See the
:doc:`Build package <Build_package>` doc page for more info.
Related commands
""""""""""""""""

3
doc/src/fix.rst
View File

@ -378,7 +378,8 @@ accelerated styles exist.
* :doc:`thermal/conductivity <fix_thermal_conductivity>` - Muller-Plathe kinetic energy exchange for thermal conductivity calculation
* :doc:`ti/spring <fix_ti_spring>` -
* :doc:`tmd <fix_tmd>` - guide a group of atoms to a new configuration
* :doc:`ttm <fix_ttm>` - two-temperature model for electronic/atomic coupling
* :doc:`ttm <fix_ttm>` - two-temperature model for electronic/atomic coupling (replicated grid)
* :doc:`ttm/grid <fix_ttm>` - two-temperature model for electronic/atomic coupling (distributed grid)
* :doc:`ttm/mod <fix_ttm>` - enhanced two-temperature model with additional options
* :doc:`tune/kspace <fix_tune_kspace>` - auto-tune KSpace parameters
* :doc:`vector <fix_vector>` - accumulate a global vector every N timesteps

171
doc/src/fix_bond_swap.rst
View File

@ -27,21 +27,26 @@ Examples
Description
"""""""""""
In a simulation of polymer chains, this command attempts to swap bonds
between two different chains, effectively grafting the end of one
chain onto another chain and vice versa. This is done via Monte Carlo
rules using the Boltzmann acceptance criterion. The purpose is to
equilibrate the polymer chain conformations more rapidly than dynamics
alone would do it, by enabling instantaneous large conformational
changes in a dense polymer melt. The polymer chains should thus more
rapidly converge to the proper end-to-end distances and radii of
gyration. It is designed for use with systems of
:doc:`FENE <bond_fene>` or :doc:`harmonic <bond_harmonic>` bead-spring
polymer chains where each polymer is a linear chain of monomers, but
LAMMPS does not enforce this requirement, i.e. any
:doc:`bond_style <bond_style>` can be used.
In a simulation of polymer chains this command attempts to swap a pair
of bonds, as illustrated below. This is done via Monte Carlo rules
using the Boltzmann acceptance criterion, typically with the goal of
equilibrating the polymer system more quickly. This fix is designed
for use with idealized bead-spring polymer chains where each polymer
is a linear chain of monomers, but LAMMPS does not check that is the
case for your system.
A schematic of the kinds of bond swaps that can occur is shown here:
Here are two use cases for this fix.
The first use case is for swapping bonds on two different chains,
effectively grafting the end of one chain onto the other chain and
vice versa. The purpose is to equilibrate the polymer chain
conformations more rapidly than dynamics alone would do it, by
enabling instantaneous large conformational changes in a dense polymer
melt. The polymer chains should thus more rapidly converge to the
proper end-to-end distances and radii of gyration.
A schematic of the kinds of bond swaps that can occur in this use case
is shown here:
.. image:: JPG/bondswap.jpg
:align: center
@ -53,38 +58,76 @@ attempt to delete the A1-A2 and B1-B2 bonds and replace them with
A1-B2 and B1-A2 bonds. If the swap is energetically favorable, the
two chains on the right are the result and each polymer chain has
undergone a dramatic conformational change. This reference,
:ref:`(Sides) <Sides>` provides more details on how the algorithm works and
its application:
:ref:`(Sides) <Sides>` provides more details on the algorithm's
effectiveness for this use case.
The bond swapping operation is invoked every *Nevery* timesteps. If
any bond is swapped, a re-build of the neighbor lists is triggered,
since a swap alters the list of which neighbors are considered for
pairwise interaction. At each invocation, each processor considers a
random specified *fraction* of its atoms as potential swapping
monomers for this timestep. Choosing a small *fraction* value can
reduce the likelihood of a reverse swap occurring soon after an
initial swap.
The second use case is a collection of polymer chains with some
fraction of their sites identified as "sticker" sites. Initially each
polymer chain is isolated from the others in a topological sense, and
there is an intra-chain bond between every pair of sticker sites on
the same chain. Over time, bonds swap so that inter-molecular sticker
bonds are created. This models a vitrification-style process whereby
the polymer chains all become interconnected. For this use case, if
angles are defined they should not include bonds between sticker
sites.
For each monomer A1, its neighbors are examined to find a possible B1
monomer. Both A1 and B1 must be in the fix group, their separation
must be less than the specified *cutoff*, and the molecule IDs of A1
and B1 must be the same (see below). If a suitable partner is found,
the energy change due to swapping the 2 bonds is computed. This
includes changes in pairwise, bond, and angle energies due to the
altered connectivity of the 2 chains. Dihedral and improper
interactions are not allowed to be defined when this fix is used.
----------
The bond swapping operation is invoked once every *Nevery* timesteps.
If any bond in the entire system is swapped, a re-build of the
neighbor lists is triggered, since a swap alters the list of which
neighbors are considered for pairwise interaction. At each
invocation, each processor considers a random specified *fraction* of
its atoms as potential swapping monomers for this timestep. Choosing
a small *fraction* value can reduce the likelihood of a reverse swap
occurring soon after an initial swap.
For each monomer A1, its neighbors are looped over as B1 monomers.
For each A1,B1 an additional double loop of bond partners A2 of A1,
and bond partners B2 of B1 a is performed. For each pair of A1-A2 and
B1-B2 bonds to be eligible for swapping, the following 4 criteria must
be met:
1. All 4 monomers must be in the fix group.
2. All 4 monomers must be owned by the processor (not ghost atoms).
This insures that another processor does not attempt to swap bonds
involving the same atoms on the same timestep. Note that this also
means that bond pairs which straddle processor boundaries are not
eligible for swapping on this step.
3. The distances between 4 pairs of atoms -- (A1,A2), (B1,B2), (A1,B2),
(B1,A2) -- must all be less than the specified *cutoff*.
4. The molecule IDs of A1 and B1 must be the same (see below).
If an eligible B1 partner is found, the energy change due to swapping
the 2 bonds is computed. This includes changes in pairwise, bond, and
angle energies due to the altered connectivity of the 2 chains.
Dihedral and improper interactions are not allowed to be defined when
this fix is used.
If the energy decreases due to the swap operation, the bond swap is
accepted. If the energy increases it is accepted with probability
exp(-delta/kT) where delta is the increase in energy, k is the
Boltzmann constant, and T is the current temperature of the system.
Whether the swap is accepted or rejected, no other swaps are attempted
by this processor on this timestep.
The criterion for matching molecule IDs is how bond swaps performed by
this fix conserve chain length. To use this features you must setup
the molecule IDs for your polymer chains in a certain way, typically
in the data file, read by the :doc:`read_data <read_data>` command.
.. note::
IMPORTANT: Whether the swap is accepted or rejected, no other swaps
are attempted by this processor on this timestep. No other
eligible 4-tuples of atoms are considered. This means that each
processor will perform either a single swap or none on timesteps
this fix is invoked.
----------
The criterion for matching molecule IDs is how the first use case
described above can be simulated while conserving chain lengths. This
is done by setting up the molecule IDs for the polymer chains in a
specific way, typically in the data file, read by the :doc:`read_data
<read_data>` command.
Consider a system of 6-mer chains. You have 2 choices. If the
molecule IDs for monomers on each chain are set to 1,2,3,4,5,6 then
swaps will conserve chain length. For a particular monomer there will
@ -113,6 +156,9 @@ ends of a chain swap with each other.
running dynamics, but can affect calculation of some diagnostic
quantities or the printing of unwrapped coordinates to a dump file.
For the second use case described above, the molecule IDs for all
sticker sites should be the same.
----------
This fix computes a temperature each time it is invoked for use by the
@ -129,27 +175,28 @@ appended and the group for the new compute is "all", so that the
temperature of the entire system is used.
Note that this is NOT the compute used by thermodynamic output (see
the :doc:`thermo_style <thermo_style>` command) with ID = *thermo_temp*.
This means you can change the attributes of this fix's temperature
(e.g. its degrees-of-freedom) via the
:doc:`compute_modify <compute_modify>` command or print this temperature
during thermodynamic output via the :doc:`thermo_style custom <thermo_style>` command using the appropriate compute-ID.
It also means that changing attributes of *thermo_temp* will have no
effect on this fix.
the :doc:`thermo_style <thermo_style>` command) with ID =
*thermo_temp*. This means you can change the attributes of this fix's
temperature (e.g. its degrees-of-freedom) via the :doc:`compute_modify
<compute_modify>` command or print this temperature during
thermodynamic output via the :doc:`thermo_style custom <thermo_style>`
command using the appropriate compute-ID. It also means that changing
attributes of *thermo_temp* will have no effect on this fix.
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files <restart>`. Because the state of the random number generator
is not saved in restart files, this means you cannot do "exact"
restarts with this fix, where the simulation continues on the same as
if no restart had taken place. However, in a statistical sense, a
restarted simulation should produce the same behavior. Also note that
each processor generates possible swaps independently of other
processors. Thus if you repeat the same simulation on a different number
of processors, the specific swaps performed will be different.
No information about this fix is written to :doc:`binary restart files
<restart>`. Because the state of the random number generator is not
saved in restart files, this means you cannot do "exact" restarts with
this fix, where the simulation continues on the same as if no restart
had taken place. However, in a statistical sense, a restarted
simulation should produce the same behavior. Also note that each
processor generates possible swaps independently of other processors.
Thus if you repeat the same simulation on a different number of
processors, the specific swaps performed will be different.
The :doc:`fix_modify <fix_modify>` *temp* option is supported by this
fix. You can use it to assign a :doc:`compute <compute>` you have
@ -157,16 +204,18 @@ defined to this fix which will be used to compute the temperature for
the Boltzmann criterion.
This fix computes two statistical quantities as a global 2-vector of
output, which can be accessed by various :doc:`output commands <Howto_output>`. The first component of the vector is the
cumulative number of swaps performed by all processors. The second
component of the vector is the cumulative number of swaps attempted
(whether accepted or rejected). Note that a swap "attempt" only
occurs when swap partners meeting the criteria described above are
found on a particular timestep. The vector values calculated by this
fix are "intensive".
output, which can be accessed by various :doc:`output commands
<Howto_output>`. The first component of the vector is the cumulative
number of swaps performed by all processors. The second component of
the vector is the cumulative number of swaps attempted (whether
accepted or rejected). Note that a swap "attempt" only occurs when
swap partners meeting the criteria described above are found on a
particular timestep. The vector values calculated by this fix are
"intensive".
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command. This fix is not invoked during :doc:`energy minimization <minimize>`.
the :doc:`run <run>` command. This fix is not invoked during
:doc:`energy minimization <minimize>`.
Restrictions
""""""""""""

5
doc/src/fix_brownian.rst
View File

@ -8,9 +8,8 @@ fix brownian command
fix brownian/sphere command
===========================
fix brownian/sphere command
===========================
fix brownian/asphere command
============================
Syntax
""""""

4
doc/src/fix_halt.rst
View File

@ -19,7 +19,7 @@ Syntax
bondmax = length of longest bond in the system (in length units)
tlimit = elapsed CPU time (in seconds)
diskfree = free disk space (in megabytes)
diskfree = free disk space (in MBytes)
v_name = name of :doc:`equal-style variable <variable>`
* operator = "<" or "<=" or ">" or ">=" or "==" or "!=" or "\|\^"
@ -81,7 +81,7 @@ the timer frequently across a large number of processors may be
non-negligible.
The *diskfree* attribute will check for available disk space (in
megabytes) on supported operating systems. By default it will
MBytes) on supported operating systems. By default it will
check the file system of the current working directory. This
can be changed with the optional *path* keyword, which will take
the path to a file or folder on the file system to be checked

3
doc/src/fix_nvt_sllod.rst
View File

@ -1,11 +1,12 @@
.. index:: fix nvt/sllod
.. index:: fix nvt/sllod/intel
.. index:: fix nvt/sllod/omp
.. index:: fix nvt/sllod/kk
fix nvt/sllod command
=====================
Accelerator Variants: *nvt/sllod/intel*, *nvt/sllod/omp*
Accelerator Variants: *nvt/sllod/intel*, *nvt/sllod/omp*, *nvt/sllod/kk*
Syntax
""""""

2
doc/src/fix_qtb.rst
View File

@ -128,7 +128,7 @@ spectrum while consumes more memory. With fixed *f_max* and
:math:`\gamma`, *N_f* should be big enough to converge the classical
temperature :math:`T^{cl}` as a function of target quantum bath
temperature. Memory usage per processor could be from 10 to 100
Mbytes.
MBytes.
.. note::

249
doc/src/fix_ttm.rst
View File

@ -1,9 +1,13 @@
.. index:: fix ttm
.. index:: fix ttm/grid
.. index:: fix ttm/mod
fix ttm command
===============
fix ttm/grid command
====================
fix ttm/mod command
===================
@ -12,13 +16,13 @@ Syntax
.. parsed-literal::
fix ID group-ID ttm seed C_e rho_e kappa_e gamma_p gamma_s v_0 Nx Ny Nz T_infile N T_outfile
fix ID group-ID ttm/mod seed init_file Nx Ny Nz T_infile N T_outfile
fix ID group-ID ttm seed C_e rho_e kappa_e gamma_p gamma_s v_0 Nx Ny Nz keyword value ...
fix ID group-ID ttm/mod seed init_file Nx Ny Nz keyword value ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* style = *ttm* or *ttm_mod*
* style = *ttm* or *ttm/grid* or *ttm/mod*
* seed = random number seed to use for white noise (positive integer)
* remaining arguments for fix ttm:
* remaining arguments for fix ttm or fix ttm/grid
.. parsed-literal::
@ -31,9 +35,6 @@ Syntax
Nx = number of thermal solve grid points in the x-direction (positive integer)
Ny = number of thermal solve grid points in the y-direction (positive integer)
Nz = number of thermal solve grid points in the z-direction (positive integer)
T_infile = filename to read initial electronic temperature from
N = dump TTM temperatures every this many timesteps, 0 = no dump
T_outfile = filename to write TTM temperatures to (only needed if N > 0)
* remaining arguments for fix ttm/mod:
@ -43,18 +44,29 @@ Syntax
Nx = number of thermal solve grid points in the x-direction (positive integer)
Ny = number of thermal solve grid points in the y-direction (positive integer)
Nz = number of thermal solve grid points in the z-direction (positive integer)
T_infile = filename to read initial electronic temperature from
N = dump TTM temperatures every this many timesteps, 0 = no dump
T_outfile = filename to write TTM temperatures to (only needed if N > 0)
* zero or more keyword/value(s) pairs may be appended
* keyword = *set* or *infile* or *outfile*
.. parsed-literal::
*set* value = Tinit
Tinit = initial electronic temperature at all grid points (temperature units)
*infile* value = file.in with grid values for electronic temperatures
*outfile* values = Nout file.out
Nout = dump grid temperatures every this many timesteps
file.out = filename to write grid temperatures to
Examples
""""""""
.. code-block:: LAMMPS
fix 2 all ttm 699489 1.0 1.0 10 0.1 0.0 2.0 1 12 1 initialTs 1000 T.out
fix 2 all ttm 123456 1.0 1.0 1.0 1.0 1.0 5.0 5 5 5 Te.in 1 Te.out
fix 2 all ttm/mod 34277 parameters.txt 5 5 5 T_init 10 T_out
fix 2 all ttm 699489 1.0 1.0 10 0.1 0.0 2.0 1 12 1 infile initial outfile 1000 T.out
fix 3 all ttm/grid 123456 1.0 1.0 1.0 1.0 1.0 5.0 5 5 5 infile Te.in
fix 4 all ttm/mod 34277 parameters.txt 5 5 5 infile T_init outfile 10 T_out
Example input scripts using these commands can be found in examples/ttm.
Description
"""""""""""
@ -62,36 +74,48 @@ Description
Use a two-temperature model (TTM) to represent heat transfer through
and between electronic and atomic subsystems. LAMMPS models the
atomic subsystem as usual with a molecular dynamics model and the
classical force field specified by the user, but the electronic
subsystem is modeled as a continuum, or a background "gas", on a
regular grid. Energy can be transferred spatially within the grid
representing the electrons. Energy can also be transferred between
the electronic and the atomic subsystems. The algorithm underlying
this fix was derived by D. M. Duffy and A. M. Rutherford and is
discussed in two J Physics: Condensed Matter papers: :ref:`(Duffy) <Duffy>`
and :ref:`(Rutherford) <Rutherford>`. They used this algorithm in cascade
simulations where a primary knock-on atom (PKA) was initialized with a
high velocity to simulate a radiation event.
classical force field specified by the user. The electronic subsystem
is modeled as a continuum, or a background "gas", on a regular grid
which overlays the simulation domain. Energy can be transferred
spatially within the grid representing the electrons. Energy can also
be transferred between the electronic and atomic subsystems. The
algorithm underlying this fix was derived by D. M. Duffy
and A. M. Rutherford and is discussed in two J Physics: Condensed
Matter papers: :ref:`(Duffy) <Duffy>` and :ref:`(Rutherford)
<Rutherford>`. They used this algorithm in cascade simulations where
a primary knock-on atom (PKA) was initialized with a high velocity to
simulate a radiation event.
The description in this sub-section applies to both fix ttm and fix
ttm/mod. Fix ttm/mod adds options to account for external heat
sources (e.g. at a surface) and for specifying parameters that allow
the electronic heat capacity to depend strongly on electronic
temperature. It is more expensive computationally than fix ttm
because it treats the thermal diffusion equation as non-linear. More
details on fix ttm/mod are given below.
The description in this sub-section applies to all 3 fix styles:
*ttm*, *ttm/grid*, and *ttm/mod*.
Fix *ttm/grid* distributes the regular grid across processors consistent
with the sub-domains of atoms owned by each processor, but is otherwise
identical to fix ttm. Note that fix *ttm* stores a copy of the grid on
each processor, which is acceptable when the overall grid is reasonably
small. For larger grids you should use fix *ttm/grid* instead.
Fix *ttm/mod* adds options to account for external heat sources (e.g. at
a surface) and for specifying parameters that allow the electronic
heat capacity to depend strongly on electronic temperature. It is
more expensive computationally than fix *ttm* because it treats the
thermal diffusion equation as non-linear. More details on fix *ttm/mod*
are given below.
Heat transfer between the electronic and atomic subsystems is carried
out via an inhomogeneous Langevin thermostat. This thermostat differs
from the regular Langevin thermostat (:doc:`fix langevin <fix_langevin>`) in three important ways. First, the
Langevin thermostat is applied uniformly to all atoms in the
out via an inhomogeneous Langevin thermostat. Only atoms in the fix
group contribute to and are affected by this heat transfer.
This thermostatting differs from the regular Langevin thermostat
(:doc:`fix langevin <fix_langevin>`) in three important ways. First,
the Langevin thermostat is applied uniformly to all atoms in the
user-specified group for a single target temperature, whereas the TTM
fix applies Langevin thermostatting locally to atoms within the
fixes apply Langevin thermostatting locally to atoms within the
volumes represented by the user-specified grid points with a target
temperature specific to that grid point. Second, the Langevin
thermostat couples the temperature of the atoms to an infinite heat
reservoir, whereas the heat reservoir for fix TTM is finite and
represents the local electrons. Third, the TTM fix allows users to
reservoir, whereas the heat reservoir for the TTM fixes is finite and
represents the local electrons. Third, the TTM fixes allow users to
specify not just one friction coefficient, but rather two independent
friction coefficients: one for the electron-ion interactions
(*gamma_p*), and one for electron stopping (*gamma_s*).
@ -123,29 +147,59 @@ as that in equation 6 of :ref:`(Duffy) <Duffy>`, with the exception that the
electronic density is explicitly represented, rather than being part
of the specific heat parameter.
Currently, fix ttm assumes that none of the user-supplied parameters
will vary with temperature. Note that :ref:`(Duffy) <Duffy>` used a tanh()
functional form for the temperature dependence of the electronic
specific heat, but ignored temperature dependencies of any of the
other parameters. See more discussion below for fix ttm/mod.
Currently, the TTM fixes assume that none of the user-supplied
parameters will vary with temperature. Note that :ref:`(Duffy)
<Duffy>` used a tanh() functional form for the temperature dependence
of the electronic specific heat, but ignored temperature dependencies
of any of the other parameters. See more discussion below for fix
ttm/mod.
These fixes require use of periodic boundary conditions and a 3D
simulation. Periodic boundary conditions are also used in the heat
equation solve for the electronic subsystem. This varies from the
approach of :ref:`(Rutherford) <Rutherford>` where the atomic subsystem was
..note::
These fixes do not perform time integration of the atoms in the fix
group, they only rescale their velocities. Thus a time integration
fix such as :doc:`fix nve <fix_nve>` should be used in conjunction
with these fixes. These fixes should not normally be used on atoms
that have their temperature controlled by another thermostatting
fix, e.g. :doc:`fix nvt <fix_nh>` or :doc:`fix langevin
<fix_langevin>`.
..note::
These fixes require use of an orthogonal 3d simulation box with
periodic boundary conditions in all dimensions. They also require
that the size and shape of the simulation box do not vary
dynamically, e.g. due to use of the :doc:`fix npt <fix_nh>` command.
Likewise, the size/shape of processor sub-domains cannot vary due to
dynamic load-balancing via use of the :doc:`fix balance
<fix_balance>` command. It is possible however to load balance
before the simulation starts using the :doc:`balance <balance>`
command, so that each processor has a different size sub-domain.
Periodic boundary conditions are also used in the heat equation solve
for the electronic subsystem. This varies from the approach of
:ref:`(Rutherford) <Rutherford>` where the atomic subsystem was
embedded within a larger continuum representation of the electronic
subsystem.
The initial electronic temperature input file, *T_infile*, is a text
file LAMMPS reads in with no header and with four numeric columns
(ix,iy,iz,Temp) and with a number of rows equal to the number of
user-specified grid points (Nx by Ny by Nz). The ix,iy,iz are node
indices from 0 to nxnodes-1, etc. For example, the initial electronic
temperatures on a 1 by 2 by 3 grid could be specified in a *T_infile*
as follows:
The *set* keyword specifies a *Tinit* temperature value to initialize
the value stored on all grid points.
The *infile* keyword specifies an input file of electronic temperatures
for each grid point to be read in to initialize the grid. By default
the temperatures are all zero when the grid is created. The input file
is a text file which may have comments starting with the '#' character.
Each line contains four numeric columns: ix,iy,iz,Temperature. Empty
or comment-only lines will be ignored. The
number of lines must be equal to the number of user-specified grid
points (Nx by Ny by Nz). The ix,iy,iz are grid point indices ranging
from 0 to nxnodes-1 inclusive in each dimension. The lines can appear
in any order. For example, the initial electronic temperatures on a 1
by 2 by 3 grid could be specified in the file as follows:
.. parsed-literal::
# UNITS: metal COMMENT: initial electron temperature
0 0 0 1.0
0 0 1 1.0
0 0 2 1.0
@ -155,40 +209,37 @@ as follows:
where the electronic temperatures along the y=0 plane have been set to
1.0, and the electronic temperatures along the y=1 plane have been set
to 2.0. The order of lines in this file is no important. If all the
nodal values are not specified, LAMMPS will generate an error.
to 2.0. If all the grid point values are not specified, LAMMPS will
generate an error. LAMMPS will check if a "UNITS:" tag is in the first
line and stop with an error, if there is a mismatch with the current
units used.
The temperature output file, *T_oufile*, is created and written by
this fix. Temperatures for both the electronic and atomic subsystems
at every node and every N timesteps are output. If N is specified as
zero, no output is generated, and no output filename is needed. The
format of the output is as follows. One long line is written every
output timestep. The timestep itself is given in the first column.
The next Nx\*Ny\*Nz columns contain the temperatures for the atomic
subsystem, and the final Nx\*Ny\*Nz columns contain the temperatures for
the electronic subsystem. The ordering of the Nx\*Ny\*Nz columns is
with the z index varying fastest, y the next fastest, and x the
slowest.
..note::
These fixes do not change the coordinates of their atoms; they only
scales their velocities. Thus a time integration fix (e.g. :doc:`fix nve <fix_nve>`) should still be used to time integrate the affected
atoms. The fixes should not normally be used on atoms that have their
temperature controlled by another fix - e.g. :doc:`fix nvt <fix_nh>` or
:doc:`fix langevin <fix_langevin>`.
The electronic temperature at each grid point must be a non-zero
positive value, both initially, and as the temperature evovles over
time. Thus you must use either the *set* or *infile* keyword or be
restarting a simulation that used this fix previously.
.. note::
The *outfile* keyword has 2 values. The first value *Nout* triggers
output of the electronic temperatures for each grid point every Nout
timesteps. The second value is the filename for output which will
be suffixed by the timestep. The format of each output file is exactly
the same as the input temperature file. It will contain a comment in
the first line reporting the date the file was created, the LAMMPS
units setting in use, grid size and the current timestep.
The current implementations of these fixes create a copy of the
electron grid that overlays the entire simulation domain, for each
processor. Values on the grid are summed across all processors. Thus
you should insure that this grid is not too large, else your
simulation could incur high memory and communication costs.
Note that the atomic temperature for atoms in each grid cell can also
be computed and output by the :doc:`fix ave/chunk <fix_ave_chunk>`
command using the :doc:`compute chunk/atom <compute_chunk_atom>`
command to create a 3d array of chunks consistent with the grid used
by this fix.
----------
**Additional details for fix ttm/mod**
Fix ttm/mod uses the heat diffusion equation with possible external
Fix *ttm/mod* uses the heat diffusion equation with possible external
heat sources (e.g. laser heating in ablation simulations):
.. math::
@ -222,7 +273,8 @@ acting on an ion is:
.. math::
{\vec F}_i = - \partial U / \partial {\vec r}_i + {\vec F}_{langevin} - \nabla P_e/n_{ion}
{\vec F}_i = - \partial U / \partial {\vec r}_i + {\vec
F}_{langevin} - \nabla P_e/n_{ion}
where F_langevin is a force from Langevin thermostat simulating
electron-phonon coupling, and nabla P_e/n_ion is the electron blast
@ -246,7 +298,9 @@ is calculated as
.. math::
\nabla_x P_e = \left[\frac{C_e{}T_e(x)\lambda}{(x+\lambda)^2} + \frac{x}{x+\lambda}\frac{(C_e{}T_e)_{x+\Delta x}-(C_e{}T_e)_{x}}{\Delta x} \right]
\nabla_x P_e = \left[\frac{C_e{}T_e(x)\lambda}{(x+\lambda)^2} +
\frac{x}{x+\lambda}\frac{(C_e{}T_e)_{x+\Delta
x}-(C_e{}T_e)_{x}}{\Delta x} \right]
where lambda is the electron mean free path (see :ref:`(Norman) <Norman>`,
:ref:`(Pisarev) <Pisarev>`)
@ -286,10 +340,12 @@ Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
These fixes write the state of the electronic subsystem and the energy
exchange between the subsystems to :doc:`binary restart files <restart>`. See the :doc:`read_restart <read_restart>` command
for info on how to re-specify a fix in an input script that reads a
exchange between the subsystems to :doc:`binary restart files
<restart>`. See the :doc:`read_restart <read_restart>` command for
info on how to re-specify a fix in an input script that reads a
restart file, so that the operation of the fix continues in an
uninterrupted fashion.
uninterrupted fashion. Note that the restart script must define the
same size grid as the original script.
Because the state of the random number generator is not saved in the
restart files, this means you cannot do "exact" restarts with this
@ -297,16 +353,16 @@ fix, where the simulation continues on the same as if no restart had
taken place. However, in a statistical sense, a restarted simulation
should produce the same behavior.
None of the :doc:`fix_modify <fix_modify>` options are relevant to these
fixes.
None of the :doc:`fix_modify <fix_modify>` options are relevant to
these fixes.
Both fixes compute 2 output quantities stored in a vector of length 2,
which can be accessed by various :doc:`output commands <Howto_output>`.
The first quantity is the total energy of the electronic
subsystem. The second quantity is the energy transferred from the
electronic to the atomic subsystem on that timestep. Note that the
velocity verlet integrator applies the fix ttm forces to the atomic
subsystem as two half-step velocity updates: one on the current
These fixes compute 2 output quantities stored in a vector of length
2, which can be accessed by various :doc:`output commands
<Howto_output>`. The first quantity is the total energy of the
electronic subsystem. The second quantity is the energy transferred
from the electronic to the atomic subsystem on that timestep. Note
that the velocity verlet integrator applies the fix ttm forces to the
atomic subsystem as two half-step velocity updates: one on the current
timestep and one on the subsequent timestep. Consequently, the change
in the atomic subsystem energy is lagged by half a timestep relative
to the change in the electronic subsystem energy. As a result of this,
@ -322,13 +378,12 @@ of the :doc:`run <run>` command. The fixes are not invoked during
Restrictions
""""""""""""
Fix *ttm* and *ttm/mod* are part of the EXTRA-FIX package. They are
only enabled if LAMMPS was built with that package.
See the :doc:`Build package <Build_package>` page for more info.
All these fixes are part of the EXTRA-FIX package. They are only
enabled if LAMMPS was built with that package. See the :doc:`Build
package <Build_package>` page for more info.
These fixes can only be used for 3d simulations and orthogonal
simulation boxes. You must also use periodic
:doc:`boundary <boundary>` conditions.
As mentioned above, these fixes require 3d simulations and orthogonal
simulation boxes periodic in all 3 dimensions.
Related commands
""""""""""""""""

2
doc/src/fix_wall_gran_region.rst
View File

@ -66,7 +66,7 @@ non-granular particles and simpler wall geometries, respectively.
Here are snapshots of example models using this command. Corresponding
input scripts can be found in examples/granregion. Movies of these
simulations are `here on the Movies page <https://www.lammps.org/movies.html#granregion>`_
of the LAMMPS web site.
of the LAMMPS website.
.. |wallgran1| image:: img/gran_funnel.png
:width: 48%

2
doc/src/group.rst
View File

@ -38,7 +38,7 @@ Syntax
*intersect* args = two or more group IDs
*dynamic* args = parent-ID keyword value ...
one or more keyword/value pairs may be appended
keyword = *region* or *var* or *every*
keyword = *region* or *var* or *property* or *every*
*region* value = region-ID
*var* value = name of variable
*property* value = name of custom integer or floating point vector

BIN
doc/src/img/decomp-balance.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 129 KiB

BIN
doc/src/img/decomp-processors.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 121 KiB

BIN
doc/src/img/decomp-rcb.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 121 KiB

BIN
doc/src/img/decomp-regular.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 121 KiB

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