\(\renewcommand{\AA}{\text{Å}}\)

3.3. Requirements for contributions to LAMMPS

The following is a summary of the current requirements and recommendations for including contributed source code or documentation into the LAMMPS software distribution.

3.3.1. Motivation

The LAMMPS developers are committed to provide 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 who may not be professionally trained programmers or 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 is necessary to follow established guidelines when accepting new contributions while also working at the same time to improve the existing code.

The following requirements and recommendations are provided as a guide. They indicate which individual 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 you need assistance in implementing the (strict) requirements for your contributions. Requirements include:

3.3.2. 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. We also have a version of LAMMPS under LGPL 2.1 terms which is available on request; this will usually be the latest available or a previous stable version with a few LGPL 2.1 incompatible files removed. More details are found on the LAMMPS open-source license page.

Your new source files should have the LAMMPS copyright and GPL notice, followed by your name and email address at the top, like other user-contributed LAMMPS source files.

Contributions may be under a different license as 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 licensing mode may complicate including the contribution in binary packages.

3.3.3. Integration testing (strict)

Where possible we use available continuous integration tools to search for common programming mistakes, portability limitations, incompatible formatting, and undesired side effects. Contributed code must pass the 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. The translation of the documentation to HTML and PDF is also tested.

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.

3.3.4. Documentation (strict)

Contributions that add new styles or commands or augment existing ones must include the corresponding new or modified documentation in ReStructuredText format (.rst files in the doc/src/ folder). The documentation should be written in American English and the .rst file must only use ASCII characters, so it can be cleanly translated to PDF files (via sphinx and PDFLaTeX). Special characters may be included via embedded math expression typeset in a LaTeX subset.

When adding new commands, they need to be integrated into the sphinx documentation system, and the corresponding command tables and lists updated. When translating the documentation into html files there should be no warnings. When adding a new package, some lists describing packages must also be updated as well as a package specific description added. Likewise, if necessary, some package specific build instructions should be included.

As appropriate, the text files with the documentation can include inline mathematical expressions or figures (see doc/JPG for examples). Additional PDF files with further details may also be included; see doc/PDF for examples. 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 package. See other command doc files for examples of how to do this.

Please run at least “make html” and “make spelling” from within the doc/src directory, 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 to 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.

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 Howto document providing some more background information and some tutorial material. This can also be used to provide more in-depth explanations of models that require use of multiple commands.

As a 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 language standards (strict)

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 improve the readability and reliability of the code, e.g. when using the std::string class instead of manipulating pointers and calling the string functions of the C library. In addition, a collection of convenient utility functions and classes for recurring tasks and a collection of platform neutral functions for improved portability are provided. Contributions with code requiring more recent C++ standards are only accepted as packages with the post C++11 standard code confined to the package so that it is optional.

Included Fortran code has to be compatible with the Fortran 2003 standard. Since not all platforms supported by LAMMPS provide good support for compiling Fortran files, it should be considered to rewrite these parts as C++ code, if possible, and thus allow for a wider adoption of the contribution. As of January 2023, all previously included Fortran code for the LAMMPS executable has been replaced by equivalent C++ code.

Python code must be compatible with Python 3.5 and later. Large parts of LAMMPS (including the PYTHON package) are also compatible with Python 2.7. Compatibility with Python 2.7 is desirable, but compatibility with Python 3.5 is required.

Compatibility with older programming language standards is very important to maintain portability and availability of LAMMPS on many platforms. This applies especially to HPC cluster environments, which tend to be running older software stacks and where LAMMPS users may be required to use those older tools for access to advanced hardware features or not have the option to install newer compilers or libraries.

3.3.5. Build system (strict)

LAMMPS currently supports two build systems: one that is based on traditional Makefiles and one that is based on CMake. Therefore, your contribution must be compatible with and support both build systems.

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.

3.3.6. Command or style names, file names, and keywords (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” in the header file would then be LMP_COMPUTE_SOME_NAME_H and the class name ComputeSomeName.

3.3.7. Programming style requirements (varied)

To maintain source code consistency across contributions from many people, there are various programming style requirements for contributions to LAMMPS. Some of these requirements are strict and must be followed, while others are only preferred and thus may be skipped. An in-depth discussion of the style guidelines is provided in the programming style doc page.

3.3.8. Examples (preferred)

For many new features, it is preferred that example scripts (simple, small, fast to complete on 1 CPU) are included that demonstrate the use of new or extended functionality. These are typically include under the examples or examples/PACKAGES directory and are further described on the examples page. Guidelines for input scripts include:

  • 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 log, echo, package, processors, 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 it complicates comparisons between different runs

  • 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

3.3.9. Error or warning messages and explanations (preferred)

Changed in version 4May2022.

Starting with LAMMPS version 4 May 2022, the LAMMPS developers have agreed on a new policy for error and warning messages.

Previously, all error and warning strings were supposed to be listed in the class header files with an explanation. Those would then be regularly “harvested” and transferred to alphabetically sorted lists in the manual. To avoid excessively long lists and to reduce effort, this came with a requirement to have rather generic error messages (e.g. “Illegal … command”). To identify the specific cause, the name of the source file and the line number of the error location would be printed, so that one could look up the cause by reading the source code.

The new policy encourages more specific error messages that ideally indicate the cause directly, and requiring no further lookup. This is aided by the {fmt} library enabling Error class methods that take a variable number of arguments and an error text that will be treated like a {fmt} syntax format string. Error messages should still preferably be kept to a single line or two lines at most.

For more complex explanations or errors that have multiple possible reasons, a paragraph should be added to the Error_details page with an error code reference (e.g. .. _err0001:) then the utility function utils::errorurl() can be used to generate a URL that will directly lead to that paragraph. An error for missing arguments can be easily generated using the utils::missing_cmd_args() convenience function. An example for this approach would be the src/read_data.cpp and src/atom.cpp files that implement the read_data and atom_modify commands and that may create “Unknown identifier in data file” errors that may have multiple possible reasons which complicates debugging, and thus require some additional explanation.

The transformation of existing LAMMPS code to this new scheme is ongoing. Given the size of the LAMMPS code base, it will take a significant amount of time to complete. For new code, however, following the new approach is strongly preferred. The expectation is that the new scheme will make understanding errors easier for LAMMPS users, developers, and maintainers.

3.3.10. Citation reminder (optional)

If there is a paper of yours describing your feature (either the algorithm/science behind the feature itself, or its initial usage, or its implementation in LAMMPS), you can add the citation to the *.cpp source file. See src/DIFFRACTION/compute_saed.cpp for an example. A BibTeX format citation is stored in a string variable at the top of the file, and a single line of code registering this variable is added to the constructor of the class. When your feature is used, then LAMMPS (by default) will print the brief info and the DOI in the first line to the screen and the full citation to the log file.

If there is additional functionality (which may have been added later) described in a different publication, additional citation descriptions may be added so long as they are only registered when the corresponding keyword activating this functionality is used.

With these options, it is possible to have LAMMPS output a specific citation reminder whenever a user invokes your feature from their input script. Please note that you should only use this for the most relevant paper for a feature and a publication that you or your group authored. E.g. adding a citation in the source code for a paper by Nose and Hoover if you write a fix that implements their integrator is not the intended usage. That kind of citation should just be included in the documentation page you provide describing your contribution. If you are not sure what the best option would be, please contact the LAMMPS developers for advice.

3.3.11. Testing (optional)

If your contribution contains new utility functions or a supporting class (i.e. anything that does not depend on a LAMMPS object), new unit tests should be added to a suitable folder in the unittest tree. When adding a new LAMMPS style computing forces or selected fixes, a .yaml file with a test configuration and reference data should be added for the styles where a suitable tester program already exists (e.g. pair styles, bond styles, etc.). Please see this section in the manual for more information on how to enable, run, and expand testing.