Merge branch 'master' into doc-updates

  endif()

endif()

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

# add custom target for IWYU analysis

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

set(ENABLE_IWYU OFF CACHE BOOL "Add 'iwyu' build target to call the include-what-you-use tool")

mark_as_advanced(ENABLE_IWYU)

if(ENABLE_IWYU)

  find_program(IWYU_EXE NAMES include-what-you-use iwyu)

  find_program(IWYU_TOOL NAMES iwyu_tool iwyu-tool iwyu_tool.py)

  if (IWYU_EXE AND IWYU_TOOL)

    add_custom_target(

      iwyu

      ${IWYU_TOOL} -o clang -p ${CMAKE_CURRENT_BINARY_DIR} -- -Xiwyu --mapping_file=${CMAKE_CURRENT_SOURCE_DIR}/iwyu/iwyu-extra-map.imp

      COMMENT "Running IWYU")

    add_dependencies(iwyu lammps)

  else()

    message(FATAL_ERROR "To use IWYU you need the include-what-you-use/iwyu executable"

      "and the iwyu-tool/iwyu_tool script installed in your PATH")

  endif()

endif()

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

mark_as_advanced(ENABLE_SANITIZER)

set(ENABLE_SANITIZER_VALUES none address leak thread undefined)

  endif()

endif()

find_package(JPEG QUIET)

option(WITH_JPEG "Enable JPEG support" ${JPEG_FOUND})

if(WITH_JPEG)

[

  { 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 files should be included in this order:

* the header matching the implementation (`some_class.h` for file `some_class.cpp`)

* mpi.h

* system and library headers (anything that is using angular brackets; C-library headers first, then C++)

* 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 `cstdio`, `cstddef`,

`string`, `lmptype.h`, and `utils.h` (and through those indirectly

 `stdint.h`, `intttypes.h`, cstdlib, and `climits`).

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, they may freely use std::string

and functions from the utils namespace without including the

corresponding header files.

`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.  There are some limitations and the IWYU tool

may give incorrect advice.  The tools is activated by setting the

CMake variable `CMAKE_CXX_INCLUDE_WHAT_YOU_USE` variable to the

path of the `include-what-you-use` command.  When activated, the

tool will be run after each compilation and provide suggestions for

which include files should be added or removed.

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

----------

.. _iwyu_processing:

Report missing and unneeded '#include' statements

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

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

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

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.

The necessary steps to generate the report can be enabled via a

CMake variable:

.. code-block:: bash

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

.. code-block:: bash

   make iwyu

This may first run some compilation, as the analysis is dependent

on recording all commands required to do the compilation.

----------

.. _sanitizer:

Address, Undefined Behavior, and Thread Sanitizer Support

.. index:: angle_style charmm

.. index:: angle_style charmm/intel

.. index:: angle_style charmm/kk

.. index:: angle_style charmm/omp

angle_style charmm command

==========================

angle_style charmm/intel command

================================

angle_style charmm/kk command

=============================

angle_style charmm/omp command

==============================

Accelerator Variants: *charmm/intel*, *charmm/kk*, *charmm/omp*

Syntax

""""""