3.11. Development build options¶
The build procedures in LAMMPS offers a few extra options which are useful during development, testing or debugging.
3.11.1. 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 compilation you can use the following option.
-D CMAKE_VERBOSE_MAKEFILE=value # value = no (default) or yes
Another way of doing this without reconfiguration is calling make with variable VERBOSE set to 1:
3.11.2. Enable static code analysis with clang-tidy (CMake only)¶
The clang-tidy tool is a static code analysis tool to diagnose (and potentially fix) typical programming errors or coding style violations. It has a modular framework of tests that can be adjusted to help identifying problems before they become bugs and also assist in modernizing large code bases (like LAMMPS). It can be enabled for all C++ code with the following CMake flag
-D ENABLE_CLANG_TIDY=value # value = no (default) or yes
With this flag enabled all source files will be processed twice, first to be compiled and then to be analyzed. Please note that the analysis can be significantly more time-consuming than the compilation itself.
3.11.3. 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 LAMMPS programming style and requirements for contributions. To assist with following these conventions one can use the Include What You Use tool. 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.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 during CMake configuration.
-D ENABLE_IWYU=value # value = no (default) or yes
This will check if the required binary (include-what-you-use or iwyu) and python script script (iwyu-tool or iwyu_tool or iwyu_tool.py) can be found in the path. The analysis can then be started with:
This may first run some compilation, as the analysis is dependent on recording all commands required to do the compilation.
3.11.4. 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 during run-time. They can detect issues like:
Please note that this kind of instrumentation usually comes with a
performance hit (but much less than using tools like Valgrind with a more low level approach). To enable
these features, additional compiler flags need to be added to the
compilation and linking stages. This is done through setting the
ENABLE_SANITIZER variable during configuration. Examples:
-D ENABLE_SANITIZER=none # no sanitizer active (default) -D ENABLE_SANITIZER=address # enable address sanitizer / memory leak checker -D ENABLE_SANITIZER=leak # enable memory leak checker (only) -D ENABLE_SANITIZER=undefined # enable undefined behavior sanitizer -D ENABLE_SANITIZER=thread # enable thread sanitizer
3.11.5. 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 on various platforms and with a variety of settings), unit testing (i.e. whether certain individual parts of the code produce the expected results for given inputs), run testing (whether selected complete input decks run without crashing for multiple configurations), and regression testing (i.e. whether selected input examples reproduce the same results over a given number of steps and operations within a given error margin). The status of this automated testing can be viewed on https://ci.lammps.org.
The scripts and inputs for integration, run, and regression testing are maintained in a separate repository of the LAMMPS project on GitHub.
The unit testing facility is integrated into the CMake build process
of the LAMMPS source code distribution itself. It can be enabled by
-D ENABLE_TESTING=on during the CMake configuration step.
It requires the YAML library and development
headers (if those are not found locally a recent version will be
downloaded and compiled along with LAMMPS and the test program) to
compile and will download and compile a specific recent version of the
Googletest C++ test framework
for implementing the tests.
Software version requirements for testing
The compiler and library version requirements for the testing framework are more strict than for the main part of LAMMPS. For example the default GNU C++ and Fortran compilers of RHEL/CentOS 7.x (version 4.8.x) are not sufficient. The CMake configuration will try to detect incompatible versions and either skip incompatible tests or stop with an error. Also the number of tests will depend on installed LAMMPS packages, development environment, operating system, and configuration settings.
After compilation is complete, the unit testing is started in the build
folder using the
ctest command, which is part of the CMake software.
The output of this command will be looking something like this:
$ ctest Test project /home/akohlmey/compile/lammps/build-testing Start 1: RunLammps 1/563 Test #1: RunLammps .......................................... Passed 0.28 sec Start 2: HelpMessage 2/563 Test #2: HelpMessage ........................................ Passed 0.06 sec Start 3: InvalidFlag 3/563 Test #3: InvalidFlag ........................................ Passed 0.06 sec Start 4: Tokenizer 4/563 Test #4: Tokenizer .......................................... Passed 0.05 sec Start 5: MemPool 5/563 Test #5: MemPool ............................................ Passed 0.05 sec Start 6: ArgUtils 6/563 Test #6: ArgUtils ........................................... Passed 0.05 sec [...] Start 561: ImproperStyle:zero 561/563 Test #561: ImproperStyle:zero ................................. Passed 0.07 sec Start 562: TestMliapPyUnified 562/563 Test #562: TestMliapPyUnified ................................. Passed 0.16 sec Start 563: TestPairList 563/563 Test #563: TestPairList ....................................... Passed 0.06 sec 100% tests passed, 0 tests failed out of 563 Label Time Summary: generated = 0.85 sec*proc (3 tests) noWindows = 4.16 sec*proc (2 tests) slow = 78.33 sec*proc (67 tests) unstable = 28.23 sec*proc (34 tests) Total Test time (real) = 132.34 sec
ctest command has many options, the most important ones are:
verbose output: display output of individual test runs
parallel run: run <num> tests in parallel
run subset of tests matching the regular expression <regex>
exclude subset of tests matching the regular expression <regex>
run subset of tests with a label matching the regular expression <regex>
exclude subset of tests with a label matching the regular expression <regex>
dry-run: display list of tests without running them
run tests with valgrind memory checker (if available)
In its full implementation, the unit test framework will consist of multiple kinds of tests implemented in different programming languages (C++, C, Python, Fortran) and testing different aspects of the LAMMPS software and its features. The tests will adapt to the compilation settings of LAMMPS, so that tests will be skipped if prerequisite features are not available in LAMMPS.
Work in Progress
The unit test framework was added in spring 2020 and is under active development. The coverage is not complete and will be expanded over time. Preference is given to parts of the code base that are easy to test or commonly used.
Tests for styles of the same kind of style (e.g. pair styles or bond styles) are performed with the same test executable using different input files in YAML format. So to add a test for another style of the same kind it may be sufficient to add a suitable YAML file. Detailed instructions for adding tests are provided in the Programmer Guide part of the manual.
Unit tests for force styles¶
A large part of LAMMPS are different “styles” for computing non-bonded
and bonded interactions selected through the pair_style command,
bond_style command, angle_style command, dihedral_style command,
improper_style command, and kspace_style command. Since these all share
common interfaces, it is possible to write generic test programs that
will call those common interfaces for small test systems with less than
100 atoms and compare the results with pre-recorded reference results.
A test run is then a a collection multiple individual test runs each
with many comparisons to reference results based on template input
files, individual command settings, relative error margins, and
reference data stored in a YAML format file with
suffix. Currently the programs
test_angle_style are implemented. They will compare forces, energies and
(global) stress for all atoms after a
run 0 calculation and after a
few steps of MD with fix nve, each in multiple variants
with different settings and also for multiple accelerated styles. If a
prerequisite style or package is missing, the individual tests are
skipped. All tests will be executed on a single MPI process, so using
the CMake option
-D BUILD_MPI=off can significantly speed up testing,
since this will skip the MPI initialization for each test run.
Below is an example command and output:
$ test_pair_style mol-pair-lj_cut.yaml [==========] Running 6 tests from 1 test suite. [----------] Global test environment set-up. [----------] 6 tests from PairStyle [ RUN ] PairStyle.plain [ OK ] PairStyle.plain (24 ms) [ RUN ] PairStyle.omp [ OK ] PairStyle.omp (18 ms) [ RUN ] PairStyle.intel [ OK ] PairStyle.intel (6 ms) [ RUN ] PairStyle.opt [ SKIPPED ] PairStyle.opt (0 ms) [ RUN ] PairStyle.single [ OK ] PairStyle.single (7 ms) [ RUN ] PairStyle.extract [ OK ] PairStyle.extract (6 ms) [----------] 6 tests from PairStyle (62 ms total) [----------] Global test environment tear-down [==========] 6 tests from 1 test suite ran. (63 ms total) [ PASSED ] 5 tests. [ SKIPPED ] 1 test, listed below: [ SKIPPED ] PairStyle.opt
In this particular case, 5 out of 6 sets of tests were conducted, the
tests for the
lj/cut/opt pair style was skipped, since the tests
executable did not include it. To learn what individual tests are performed,
you (currently) need to read the source code. You can use code coverage
recording (see next section) to confirm how well the tests cover the code
paths in the individual source files.
The force style test programs have a common set of options:
regenerate reference data in new YAML file
update reference data in the original YAML file
print error statistics for each group of comparisons
verbose output: also print the executed LAMMPS commands
ctest tool has no mechanism to directly pass flags to the individual
test programs, but a workaround has been implemented where these flags can be
set in an environment variable
env TEST_ARGS=-s ctest -V -R BondStyle
To add a test for a style that is not yet covered, it is usually best to copy a YAML file for a similar style to a new file, edit the details of the style (how to call it, how to set its coefficients) and then run test command with either the -g and the replace the initial test file with the regenerated one or the -u option. The -u option will destroy the original file, if the generation run does not complete, so using -g is recommended unless the YAML file is fully tested and working.
Some of the force style tests are rather slow to run and some are very
sensitive to small differences like CPU architecture, compiler
toolchain, compiler optimization. Those tests are flagged with a “slow”
and/or “unstable” label, and thus those tests can be selectively
excluded with the
-LE flag or selected with the
Recommendations and notes for YAML files
The reference results should be recorded without any code optimization or related compiler flags enabled.
epsilonparameter defines the relative precision with which the reference results must be met. The test geometries often have high and low energy parts and thus a significant impact from floating-point math truncation errors is to be expected. Some functional forms and potentials are more noisy than others, so this parameter needs to be adjusted. Typically a value around 1.0e-13 can be used, but it may need to be as large as 1.0e-8 in some cases.
The tests for pair styles from OPT, OPENMP and INTEL are performed with automatically rescaled epsilon to account for additional loss of precision from code optimizations and different summation orders.
When compiling with (aggressive) compiler optimization, some tests are likely to fail. It is recommended to inspect the individual tests in detail to decide, whether the specific error for a specific property is acceptable (it often is), or this may be an indication of mis-compiled code (or an undesired large loss of precision due to significant reordering of operations and thus less error cancellation).
Use custom linker for faster link times when ENABLE_TESTING is active¶
When compiling LAMMPS with enabled tests, most test executables will
need to be linked against the LAMMPS library. Since this can be a very
large library with many C++ objects when many packages are enabled, link
times can become very long on machines that use the GNU BFD linker (e.g.
Linux systems). Alternatives like the
lld linker of the LLVM project
gold linker available with GNU binutils can speed up this step
substantially. CMake will by default test if any of the two can be
enabled and use it when
ENABLE_TESTING is active. It can also be
selected manually through the
CMAKE_CUSTOM_LINKER CMake variable.
Allowed values are
default option will use the system default linker otherwise, the
linker is chosen explicitly. This option is only available for the
GNU or Clang C++ compiler.
Tests for other components and utility functions¶
Additional tests that validate utility functions or specific components
of LAMMPS are implemented as standalone executable which may, or may not
require creating a suitable LAMMPS instance. These tests are more specific
and do not require YAML format input files. To add a test, either an
existing source file needs to be extended or a new file added, which in turn
requires additions to the
CMakeLists.txt file in the source folder.
Collect and visualize code coverage metrics¶
You can also collect code coverage metrics while running LAMMPS or the tests by enabling code coverage support during the CMake configuration:
-D ENABLE_COVERAGE=on # enable coverage measurements (off by default)
This will instrument all object files to write information about which lines of code were accessed during execution in files next to the corresponding object files. These can be post-processed to visually show the degree of coverage and which code paths are accessed and which are not taken. When working on unit tests (see above), this can be extremely helpful to determine which parts of the code are not executed and thus what kind of tests are still missing. The coverage data is cumulative, i.e. new data is added with each new run.
Enabling code coverage will also add the following build targets to generate coverage reports after running the LAMMPS executable or the unit tests:
make gen_coverage_html # generate coverage report in HTML format make gen_coverage_xml # generate coverage report in XML format make clean_coverage_html # delete folder with HTML format coverage report make reset_coverage # delete all collected coverage data and HTML output
These reports require GCOVR to be installed. The easiest way to do this to install it via pip:
pip install git+https://github.com/gcovr/gcovr.git
After post-processing with
gen_coverage_html the results are in
coverage_html and can be viewed with a web browser.
The images below illustrate how the data is presented.
Top of the overview page
Styles with good coverage
Top of individual source page
Source page with branches
3.11.6. 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 properly on Unix-like operating and file systems.
The following options are available.
make check-whitespace # search for files with whitespace issues make fix-whitespace # correct whitespace issues in files make check-homepage # search for files with old LAMMPS homepage URLs make fix-homepage # correct LAMMPS homepage URLs in files make check-errordocs # search for deprecated error docs in header files make fix-errordocs # remove error docs in header files make check-permissions # search for files with permissions issues make fix-permissions # correct permissions issues in files make check # run all check targets from above
These should help to make source and documentation files conforming to some the coding style preferences of the LAMMPS developers.
3.11.7. Clang-format support¶
For the code in the
src trees we are transitioning
to use the clang-format tool to assist with having a consistent source
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.
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:
clang-format -i some_file.cpp
The following target are available for both, GNU make and CMake:
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
3.11.8. GitHub command line interface¶
GitHub is developing a tool for the command line that interacts with the GitHub website via a
gh. This can be extremely convenient when working
with a Git repository hosted on GitHub (like LAMMPS). It is thus highly
recommended to install it when doing LAMMPS development.
The capabilities of the
gh command is continually expanding, so
please see the documentation at https://cli.github.com/manual/