Merge pull request #2162 from akohlmey/collected-small-changes

# compiler tests

# these need ot be done early (before further tests).

#####################################################################

include(CheckCCompilerFlag)

include(CheckIncludeFileCXX)

# set required compiler flags and compiler/CPU arch specific optimizations

set(CMAKE_CXX_STANDARD_REQUIRED ON)

set(CMAKE_CXX_EXTENSIONS OFF)

# GNU compiler specific features for testing

if (${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")

  option(ENABLE_COVERAGE "Enable collecting code coverage data" OFF)

  mark_as_advanced(ENABLE_COVERAGE)

  if(ENABLE_COVERAGE)

    set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} --coverage")

  endif()

endif()

########################################################################

# User input options                                                   #

########################################################################

  target_link_libraries(lammps PRIVATE OpenMP::OpenMP_CXX)

endif()

# Compiler specific features for testing

if(${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")

  option(ENABLE_COVERAGE "Enable collecting code coverage data" OFF)

  mark_as_advanced(ENABLE_COVERAGE)

  if(ENABLE_COVERAGE)

    if(CMAKE_VERSION VERSION_LESS 3.13)

      if(CMAKE_CXX_FLAGS)

        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} --coverage")

      else()

        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_${CMAKE_BUILD_TYPE}_FLAGS} --coverage")

      endif()

    else()

      target_compile_options(lammps PUBLIC --coverage)

      target_link_options(lammps PUBLIC --coverage)

    endif()

  endif()

endif()

set(ENABLE_SANITIZER "none" CACHE STRING "Select a code sanitizer option (none (default), address, thread, undefined)")

mark_as_advanced(ENABLE_SANITIZER)

set(ENABLE_SANITIZER_VALUES none address thread undefined)

set_property(CACHE ENABLE_SANITIZER PROPERTY STRINGS ${ENABLE_SANITIZER_VALUES})

validate_option(ENABLE_SANITIZER ENABLE_SANITIZER_VALUES)

string(TOLOWER ${ENABLE_SANITIZER} ENABLE_SANITIZER)

if(NOT ENABLE_SANITIZER STREQUAL "none")

  if((${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU") OR (${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang"))

    if(CMAKE_VERSION VERSION_LESS 3.13)

      if(CMAKE_CXX_FLAGS)

        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=${ENABLE_SANITIZER}")

      else()

        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_${CMAKE_BUILD_TYPE}_FLAGS} -fsanitize=${ENABLE_SANITIZER}")

      endif()

    else()

      target_compile_options(lammps PUBLIC -fsanitize=${ENABLE_SANITIZER})

      target_link_options(lammps PUBLIC -fsanitize=${ENABLE_SANITIZER})

    endif()

  else()

    message(WARNING "ENABLE_SANITIZER option not supported by ${CMAKE_CXX_COMPILER_ID} compilers. Ignoring.")

    set(ENABLE_SANITIZER "none")

  endif()

endif()

if(PKG_MSCG OR PKG_USER-ATC OR PKG_USER-AWPMD OR PKG_USER-QUIP OR PKG_LATTE)

  enable_language(C)

  find_package(LAPACK)

set(CMAKE_TUNE_FLAGS "${CMAKE_TUNE_DEFAULT}" CACHE STRING "Compiler specific optimization or instrumentation")

separate_arguments(CMAKE_TUNE_FLAGS)

include(CheckCXXCompilerFlag)

foreach(_FLAG ${CMAKE_TUNE_FLAGS})

  string(REGEX REPLACE "[=\"]" "" _FLAGX ${_FLAG})

  check_cxx_compiler_flag("${_FLAG}" COMPILER_SUPPORTS${_FLAGX})

  if(COMPILER_SUPPORTS${_FLAGX})

  target_compile_options(lammps PRIVATE ${_FLAG})

  else()

    message(WARNING "${_FLAG} found in CMAKE_TUNE_FLAGS, but not supported by the compiler, skipping")

  endif()

endforeach()

########################################################################

# Basic system tests (standard libraries, headers, functions, types)   #

option(DOWNLOAD_SCAFACOS "Download ScaFaCoS library instead of using an already installed one" ${DOWNLOAD_SCAFACOS_DEFAULT})

if(DOWNLOAD_SCAFACOS)

  message(STATUS "ScaFaCoS download requested - we will build our own")

  # create variables to pass our compiler flags along to the subsystem compile

  # need to apply -fallow-argument-mismatch, if the fortran compiler supports it

  include(CheckFortranCompilerFlag)

  check_fortran_compiler_flag("-fallow-argument-mismatch" GNUFortran_ARGUMENT_MISMATCH_FLAG)

  if(GNUFortran_ARGUMENT_MISMATCH_FLAG)

    set(APPEND_Fortran_FLAG "-fallow-argument-mismatch")

  endif()

  if(CMAKE_Fortran_FLAGS)

    set(SCAFACOS_Fortran_FLAGS "${CMAKE_Fortran_FLAGS} ${APPEND_Fortran_FLAG}")

  else()

    set(SCAFACOS_Fortran_FLAGS "${CMAKE_Fortran_${CMAKE_BUILD_TYPE}_FLAGS} ${APPEND_Fortran_FLAG}")

  endif()

  if(CMAKE_CXX_FLAGS)

      set(SCAFACOS_CXX_FLAGS "${CMAKE_CXX_FLAGS}")

    else()

      set(SCAFACOS_CXX_FLAGS "${CMAKE_CXX_${CMAKE_BUILD_TYPE}_FLAGS}")

  endif()

  if(CMAKE_C_FLAGS)

      set(SCAFACOS_C_FLAGS "${CMAKE_C_FLAGS}")

    else()

      set(SCAFACOS_C_FLAGS "${CMAKE_C_${CMAKE_BUILD_TYPE}_FLAGS}")

  endif()

  # version 1.0.1 needs a patch to compile and linke cleanly with GCC 10 and later.

  file(DOWNLOAD https://download.lammps.org/thirdparty/scafacos-1.0.1-fix.diff ${CMAKE_CURRENT_BINARY_DIR}/scafacos-1.0.1.fix.diff

          EXPECTED_HASH MD5=4baa1333bb28fcce102d505e1992d032)

  include(ExternalProject)

  ExternalProject_Add(scafacos_build

    URL https://github.com/scafacos/scafacos/releases/download/v1.0.1/scafacos-1.0.1.tar.gz

    URL_MD5 bd46d74e3296bd8a444d731bb10c1738

    PATCH_COMMAND patch -p1 < ${CMAKE_CURRENT_BINARY_DIR}/scafacos-1.0.1.fix.diff

    CONFIGURE_COMMAND <SOURCE_DIR>/configure --prefix=<INSTALL_DIR> --disable-doc

                                             --enable-fcs-solvers=fmm,p2nfft,direct,ewald,p3m

                                             --with-internal-fftw --with-internal-pfft

                                             --with-internal-pnfft ${CONFIGURE_REQUEST_PIC}

                                             FC=${CMAKE_MPI_Fortran_COMPILER} FCFLAGS=${SCAFACOS_Fortran_FLAGS}

                                             CXX=${CMAKE_MPI_CXX_COMPILER} CXXFLAGS=${SCAFACOS_CXX_FLAGS}

                                             CC=${CMAKE_MPI_C_COMPILER} CFLAGS=${SCAFACOS_C_FLAGS}

                                             FC=${CMAKE_MPI_Fortran_COMPILER}

                                             CXX=${CMAKE_MPI_CXX_COMPILER}

                                             CC=${CMAKE_MPI_C_COMPILER}

                                             F77=

    BUILD_BYPRODUCTS

      <INSTALL_DIR>/lib/libfcs.a

.. _compilation:

Verify compilation flags

------------------------

Monitor compilation flags

-------------------------

Sometimes it is necessary to verify the complete sequence of compilation flags

generated by the CMake build. To enable a more verbose output during

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

Another way of doing this without reconfiguration is calling make with

variable VERBOSE set to 1:

.. code-block:: bash

---------------------------------------------------------

Compilers such as GCC and Clang support generating instrumented binaries

which use different sanitizer libraries to detect problems in code

which use different sanitizer libraries to detect problems in the code

during run-time. They can detect issues like:

 - `memory leaks <https://clang.llvm.org/docs/AddressSanitizer.html>`_

 - `undefined behavior <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html>`_

 - `data races <https://clang.llvm.org/docs/ThreadSanitizer.html>`_

Please note that this kind of instrumentation usually comes with a small

performance hit (much less than using tools like `Valgrind

<https://valgrind.org>`_).  The to enable these features additional

compiler flags need to be added to the compilation and linking stages.

This is most easily done through setting the ``CMAKE_TUNE_FLAGS``

variable during configuration. Examples:

Please note that this kind of instrumentation usually comes with a

performance hit (but much less than using tools like `Valgrind

<https://valgrind.org>`_ with a more low level approach).  The 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:

.. code-block:: bash

   -D CMAKE_TUNE_FLAGS=-fsanitize=address    # enable address sanitizer / memory leak checker

   -D CMAKE_TUNE_FLAGS=-fsanitize=undefined  # enable undefined behavior sanitizer

   -D CMAKE_TUNE_FLAGS=-fsanitize=thread     # enable thread sanitizer

   -D ENABLE_SANITIZER=none       # no sanitizer active (default)

   -D ENABLE_SANITIZER=address    # enable address sanitizer / memory leak checker

   -D ENABLE_SANITIZER=undefined  # enable undefined behavior sanitizer

   -D ENABLE_SANITIZER=thread     # enable thread sanitizer

----------

   [...]$ ctest

   Test project /home/akohlmey/compile/lammps/build-testing

         Start  1: MolPairStyle:hybrid-overlay

    1/26 Test  #1: MolPairStyle:hybrid-overlay .........   Passed    0.02 sec

   1/109 Test  #1: MolPairStyle:hybrid-overlay .........   Passed    0.02 sec

         Start  2: MolPairStyle:hybrid

    2/26 Test  #2: MolPairStyle:hybrid .................   Passed    0.01 sec

   2/109 Test  #2: MolPairStyle:hybrid .................   Passed    0.01 sec

         Start  3: MolPairStyle:lj_class2

    [...]

         Start 25: AngleStyle:harmonic

   25/26 Test #25: AngleStyle:harmonic .................   Passed    0.01 sec

         Start 26: AngleStyle:zero

   26/26 Test #26: AngleStyle:zero .....................   Passed    0.01 sec

         Start 107: PotentialFileReader

 107/109 Test #107: PotentialFileReader ................   Passed    0.04 sec

         Start 108: EIMPotentialFileReader

 108/109 Test #108: EIMPotentialFileReader .............   Passed    0.03 sec

         Start 109: TestSimpleCommands

 109/109 Test #109: TestSimpleCommands .................   Passed    0.02 sec

   100% tests passed, 0 tests failed out of 26

   Total Test time (real) =   0.27 sec

   Total Test time (real) =  25.57 sec

The ``ctest`` command has many options, the most important ones are:

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 individual

source files.

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:

   * - -v

     - verbose output: also print the executed LAMMPS commands

The ``ctest`` tool has no mechanism to directly pass flags to the individual

test programs, but a workaround has been implmented where these flags can be

set in an environment variable ``TEST_ARGS``. Example:

.. code-block:: bash

   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

     of mis-compiled code (or an undesired large loss of precision due

     to significant reordering of operations and thus less error cancellation).

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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

             :target: JPG/coverage-file-branches.png

          Source page with branches

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.

The following options are available.

.. code-block:: bash

   make check-whitespace    # generate coverage report in HTML format

   make fix-whitespace      # generate coverage report in XML format

   make check-permissions   # delete folder with HTML format coverage report

   make fix-permissions     # delete all collected coverage data and HTML output

For the code in the ``unittest`` tree we are using the `clang-format`

tool (Clang version 8.0 or later is required). If available, the source

code files in the ``unittest`` tree can be updated to conform to the

formatting settings using ``make format-tests``.

.. math::

   E(r) = 4\epsilon\biggl[\bigl(\frac{\sigma}{r}\bigr)^{12} - \bigl(\frac{\sigma}{r}\bigr)^6\biggr]

   E(r) = 4 \epsilon \left[ \left(\frac{\sigma}{r}\right)^{12} -

                            \left(\frac{\sigma}{r}\right)^6 \right]

Either the first two or all of the following coefficients must be

defined for each pair of atoms types via the pair_coeff command as in

**Mixing, shift, table, tail correction, restart, rRESPA info**\ :

For atom type pairs I,J and I != J, the :math:`\epsilon` and

:math:`sigma` coefficients and cutoff distances for the lj/mdf pair

:math:`\sigma` coefficients and cutoff distances for the lj/mdf pair

style can be mixed.  The default mix value is *geometric*\ .  See the

"pair_modify" command for details. The other two pair styles buck/mdf

and lennard/mdf do not support mixing, so all I,J pairs of coefficients

# Run MD

velocity all create 300.0 4928459

velocity all create 300.0 4928459 loop geom

fix 1 all nve

run             ${nsteps}