Build system improvements (espressomd#4608)

Description of changes:
- use modern CMake and enable ccache for CUDA files
- document all CMake options of the ESPResSo project
- fix regressions in the python documentation that will become errors in future Sphinx and autopep versions

.clang-tidy

@@ -9,6 +9,7 @@ Checks: |
    -bugprone-easily-swappable-parameters,
    -bugprone-implicit-widening-of-multiplication-result,
    -bugprone-macro-parentheses,
+   -bugprone-reserved-identifier,
    clang-analyzer-alpha.*,
    modernize-deprecated-headers,
    modernize-make-shared,

CMakeLists.txt

@@ -108,14 +108,13 @@ set(TEST_TIMEOUT "300" CACHE STRING
                              "Timeout in seconds for each testsuite test")
 
 if(WITH_CCACHE)
-  find_program(CCACHE ccache)
-  if(CCACHE)
-    message(STATUS "Found ccache ${CCACHE}")
-    set(CMAKE_CXX_COMPILER_LAUNCHER ${CCACHE} CACHE STRING "ccache executable")
-  else()
-    message(FATAL_ERROR "ccache not found.")
-  endif(CCACHE)
-endif(WITH_CCACHE)
+  find_program(CCACHE_PROGRAM ccache REQUIRED)
+  if(CCACHE_PROGRAM)
+    message(STATUS "Found ccache: ${CCACHE_PROGRAM}")
+    set(CMAKE_CXX_COMPILER_LAUNCHER ${CCACHE_PROGRAM})
+    set(CMAKE_CUDA_COMPILER_LAUNCHER ${CCACHE_PROGRAM})
+  endif()
+endif()
 
 # Write compile commands to file, for various tools...
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

cmake/FindCUDACompilerNVCC.cmake

@@ -77,7 +77,7 @@ find_gpu_library(VARNAME CUDA_CUFFT_LIBRARIES NAMES cufft REQUIRED)
 function(add_gpu_library)
   cuda_add_library(${ARGV})
   set(GPU_TARGET_NAME ${ARGV0})
-  set_property(TARGET ${GPU_TARGET_NAME} PROPERTY CUDA_SEPARABLE_COMPILATION ON)
+  set_target_properties(${GPU_TARGET_NAME} PROPERTIES CUDA_SEPARABLE_COMPILATION ON)
   target_link_libraries(${GPU_TARGET_NAME} PRIVATE
     ${CUDA_LIBRARY} ${CUDART_LIBRARY} ${CUDA_CUFFT_LIBRARIES})
 endfunction()

cmake/cmake_config.cmakein

@@ -3,8 +3,6 @@
 
 #cmakedefine CUDA
 
-#cmakedefine HIP
-
 #cmakedefine FFTW
 
 #cmakedefine H5MD
@@ -13,10 +11,6 @@
 
 #cmakedefine GSL
 
-#cmakedefine BLAS
-
-#cmakedefine LAPACK
-
 #cmakedefine STOKESIAN_DYNAMICS
 
 #cmakedefine VALGRIND_INSTRUMENTATION

doc/sphinx/installation.rst

@@ -713,37 +713,56 @@ Options and Variables
 ~~~~~~~~~~~~~~~~~~~~~
 
 The behavior of |es| can be controlled by means of options and variables
-in the :file:`CMakeLists.txt` file. Also options are defined there.
-The following options are available:
-
-* ``WITH_CUDA``: Build with GPU support
-
-* ``WITH_HDF5``: Build with HDF5
-
-* ``WITH_TESTS``: Enable tests
-
-* ``WITH_SCAFACOS``: Build with ScaFaCoS support
-
-* ``WITH_STOKESIAN_DYNAMICS`` Build with Stokesian Dynamics support
-
-* ``WITH_VALGRIND_INSTRUMENTATION``: Build with valgrind instrumentation
-  markers
-
+in the :file:`CMakeLists.txt` file. Most options are boolean values
+(``ON`` or ``OFF``). A few options are strings or semicolon-delimited lists.
+
+The following options control features from external libraries:
+
+* ``WITH_CUDA``: Build with GPU support.
+* ``WITH_HDF5``: Build with HDF5 support.
+* ``WITH_SCAFACOS``: Build with ScaFaCoS support.
+* ``WITH_GSL``: Build with GSL support.
+* ``WITH_STOKESIAN_DYNAMICS`` Build with Stokesian Dynamics support.
+
+The following options control code instrumentation:
+
+* ``WITH_VALGRIND_INSTRUMENTATION``: Build with valgrind instrumentation markers
+* ``WITH_PROFILER``: Build with Caliper profiler annotations
+* ``WITH_MSAN``: Compile C++ code with memory sanitizer
+* ``WITH_ASAN``: Compile C++ code with address sanitizer
+* ``WITH_UBSAN``: Compile C++ code with undefined behavior sanitizer
+* ``WITH_COVERAGE``: Generate C++ code coverage reports when running |es|
+* ``WITH_COVERAGE_PYTHON``: Generate Python code coverage reports when running |es|
+
+The following options control how the project is built and tested:
+
+* ``WITH_CLANG_TIDY``: Run Clang-Tidy during compilation.
+* ``WITH_CPPCHECK``: Run Cppcheck during compilation.
+* ``WITH_CCACHE``: Enable compiler cache for faster rebuilds.
+* ``WITH_TESTS``: Enable C++ and Python tests.
+* ``WITH_CUDA_COMPILER`` (string): Select the CUDA compiler.
+* ``CTEST_ARGS`` (string): Arguments passed to the ``ctest`` command.
+* ``TEST_TIMEOUT``: Test timeout.
 * ``ESPRESSO_ADD_OMPI_SINGLETON_WARNING``: Add a runtime warning in the
   pypresso and ipypresso scripts that is triggered in singleton mode
   with Open MPI version 4.x on unsupported NUMA environments
   (see :term:`MPI installation requirements <MPI>` for details).
-
-When the value in the :file:`CMakeLists.txt` file is set to ON, the
-corresponding option is created; if the value of the option is set to OFF,
-the corresponding option is not created. These options can also be modified
+* ``MYCONFIG_NAME`` (string): Filename of the user-provided config file
+* ``MPIEXEC_PREFLAGS``, ``MPIEXEC_POSTFLAGS`` (strings): Flags passed to the
+  ``mpiexec`` command in MPI-parallel tests and benchmarks.
+* ``CMAKE_CXX_FLAGS`` (string): Flags passed to the compilers.
+* ``CMAKE_BUILD_TYPE`` (string): Build type. Default is ``Release``.
+* ``CUDA_TOOLKIT_ROOT_DIR`` (string): Path to the CUDA toolkit directory.
+
+Most of these options are opt-in, meaning their default value is set to
+``OFF`` in the :file:`CMakeLists.txt` file. These options can be modified
 by calling ``cmake`` with the command line argument ``-D``:
 
 .. code-block:: bash
 
     cmake -D WITH_HDF5=OFF ..
 
-When an option is activated, additional options may become available.
+When an option is enabled, additional options may become available.
 For example with ``-D WITH_CUDA=ON``, one can choose the CUDA compiler with
 ``-D WITH_CUDA_COMPILER=<compiler_id>``, where ``<compiler_id>`` can be
 ``nvcc`` (default) or ``clang``.

doc/sphinx/inter_non-bonded.rst

@@ -40,7 +40,7 @@ the subsection :ref:`Capping the force during warmup` for more details.
 Tabulated interaction
 ~~~~~~~~~~~~~~~~~~~~~
 
-.. note ::
+.. note::
 
     Feature ``TABULATED`` required.
 
@@ -209,17 +209,17 @@ Lennard-Jones cosine interaction
 
    Feature ``LJCOS`` and/or ``LJCOS2`` required.
 
-.. code::
+:class:`espressomd.interactions.LennardJonesCosInteraction` and
+:class:`espressomd.interactions.LennardJonesCos2Interaction` specify
+a Lennard-Jones interaction with cosine tail :cite:`soddemann01a`
+between particles of the types ``type1`` and ``type2``. They
+are configured via the syntax::
 
    system.non_bonded_inter[type1, type2].lennard_jones_cos.set_params(**kwargs)
    system.non_bonded_inter[type1, type2].lennard_jones_cos2.set_params(**kwargs)
 
-:class:`espressomd.interactions.LennardJonesCosInteraction` and
-:class:`espressomd.interactions.LennardJonesCos2Interaction` specifies
-a Lennard-Jones interaction with cosine tail :cite:`soddemann01a`
-between particles of the types ``type1`` and ``type2``. The first variant
-behaves as follows: Until the minimum of the Lennard-Jones potential
-at :math:`r_\mathrm{min} = r_\mathrm{off} + 2^{\frac{1}{6}}\sigma`, it
+The first variant behaves as follows: until the minimum of the Lennard-Jones
+potential at :math:`r_\mathrm{min} = r_\mathrm{off} + 2^{\frac{1}{6}}\sigma`, it
 behaves identical to the unshifted Lennard-Jones potential
 (:math:`c_\mathrm{shift}=0`). Between :math:`r_\mathrm{min}` and :math:`r_\mathrm{cut}`, a cosine is used to
 smoothly connect the potential to 0, i.e.,

doc/sphinx/io.rst

@@ -167,7 +167,7 @@ To write data in a hdf5-file according to the H5MD proposal
 :class:`espressomd.io.writer.h5md.H5md` has to be created and linked to the
 respective hdf5-file. This may, for example, look like:
 
-.. code:: python
+.. code-block:: python
 
     import espressomd.io.writer.h5md
     system = espressomd.System(box_l=[100.0, 100.0, 100.0])
@@ -254,7 +254,7 @@ To read from the command line with
 `h5dump <https://support.hdfgroup.org/HDF5/doc/RM/Tools/h5dump.htm>`__
 (Ubuntu package ``hdf5-tools``):
 
-.. code:: sh
+.. code-block:: sh
 
     # show metadata only
     h5dump --header sample.h5 | less
@@ -280,7 +280,7 @@ data is easily accessible. In contrast to H5MD, the MPI-IO functionality
 outputs data in a *machine-dependent format*, but has write and read
 capabilities. The usage is quite simple:
 
-.. code:: python
+.. code-block:: python
 
     import espressomd
     import espressomd.io
@@ -356,7 +356,7 @@ to generate a timeframe of the simulation state. For example:
 
 A standalone VTF file can simply be
 
-.. code:: python
+.. code-block:: python
 
     import espressomd
     import espressomd.io.writer.vtf
@@ -404,7 +404,7 @@ timesteps. This is a restriction of VMD itself, not of the format.
 
 Writes a structure block describing the system's structure to the given channel, for example:
 
-.. code:: python
+.. code-block:: python
 
     import espressomd
     import espressomd.io.writer.vtf
@@ -426,7 +426,7 @@ contains a trajectory of a whole simulation.
 Writes a coordinate (or timestep) block that contains all coordinates of
 the system's particles.
 
-.. code:: python
+.. code-block:: python
 
     import espressomd
     import espressomd.io.writer.vtf
@@ -445,7 +445,7 @@ Generates a dictionary which maps |es| particle ``id`` to VTF indices.
 This is motivated by the fact that the list of |es| particle ``id`` is allowed to contain *holes* but VMD
 requires increasing and continuous indexing. The |es| ``id`` can be used as *key* to obtain the VTF index as the *value*, for example:
 
-.. code:: python
+.. code-block:: python
 
     import espressomd
     import espressomd.io.writer.vtf

doc/tutorials/convert.py

@@ -56,8 +56,8 @@ def add_cell_from_script(nb, filepath):
     with open(filepath, encoding='utf-8') as f:
         code = f.read()
     # remove ESPResSo copyright header
-    m = re.search('# Copyright \(C\) [\d\-,]+ The ESPResSo project\n.+?'
-                  'If not, see <http://www\.gnu\.org/licenses/>\.\n', code, re.DOTALL)
+    m = re.search('# Copyright \\(C\\) [\\d\\-,]+ The ESPResSo project\n.+?'
+                  'If not, see <http://www\\.gnu\\.org/licenses/>\\.\n', code, re.DOTALL)
     if m and all(x.startswith('#') for x in m.group(0).strip().split('\n')):
         code = re.sub('^(#\n)+', '', code.replace(m.group(0), ''), re.M)
     # strip first component in relative paths

maintainer/configs/maxset.hpp

@@ -17,40 +17,38 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 /* maximal set of features usable at the same time */
-#define ELECTROSTATICS
-#define DIPOLES
-#ifdef SCAFACOS
-#define SCAFACOS_DIPOLES
-#endif
 #define ROTATION
 #define ROTATIONAL_INERTIA
+#define MASS
 #define PARTICLE_ANISOTROPY
 #define EXTERNAL_FORCES
-
-#define MASS
-#define EXCLUSIONS
-
-#define BOND_CONSTRAINT
-#define COLLISION_DETECTION
 #define THERMOSTAT_PER_PARTICLE
-
+#define BOND_CONSTRAINT
 #define NPT
-
 #define DPD
 
-#define LB_BOUNDARIES
-#define LB_ELECTROHYDRODYNAMICS
+#define ELECTROSTATICS
+#ifdef CUDA
+#define MMM1D_GPU
+#endif
+#define DIPOLES
+#ifdef SCAFACOS
+#define SCAFACOS_DIPOLES
+#endif
 
 #define ENGINE
 
+#define LB_ELECTROHYDRODYNAMICS
+#define LB_BOUNDARIES
 #ifdef CUDA
 #define LB_BOUNDARIES_GPU
 #define ELECTROKINETICS
 #define EK_BOUNDARIES
 #define EK_DEBUG
-#define MMM1D_GPU
 #endif
 
+#define EXCLUSIONS
+
 #define TABULATED
 #define LENNARD_JONES
 #define LENNARD_JONES_GENERIC
@@ -67,9 +65,13 @@
 #define BUCKINGHAM
 #define SOFT_SPHERE
 #define WCA
+
+#ifdef P3M
 #define THOLE
+#endif
 
 #define VIRTUAL_SITES_RELATIVE
 #define VIRTUAL_SITES_INERTIALESS_TRACERS
+#define COLLISION_DETECTION
 
 #define ADDITIONAL_CHECKS

src/config/myconfig-default.hpp

@@ -48,14 +48,10 @@
 // Active matter
 #define ENGINE
 
-// Hydrodynamics
+// Hydrodynamics, Electrokinetics
 #define LB_BOUNDARIES
 #ifdef CUDA
 #define LB_BOUNDARIES_GPU
-#endif
-
-// Electrokinetics
-#ifdef CUDA
 #define ELECTROKINETICS
 #define EK_BOUNDARIES
 #endif

src/python/espressomd/analyze.pxd

@@ -111,7 +111,7 @@ cdef inline get_obs_contribs(Span[double] contributions,
     ----------
     contributions : (N,) array_like of :obj:`float`
         Flattened array of energy/pressure contributions from an observable.
-    size : :obj:`int`, \{1, 9\}
+    size : :obj:`int`, {1, 9}
         Dimensionality of the data.
     calc_scalar_pressure : :obj:`bool`
         Whether to calculate a scalar pressure (only relevant when

src/python/espressomd/bond_breakage.py

@@ -30,7 +30,7 @@ class BreakageSpec(ScriptInterfaceHelper):
     ----------
     breakage_length: :obj:`float`
         Maximal bond extension until the bond breaks.
-    action_type: :obj:`str`, \{'delete_bond', 'revert_bind_at_point_of_collision', 'none'\}
+    action_type: :obj:`str`, {'delete_bond', 'revert_bind_at_point_of_collision', 'none'}
         Action triggered when the bond reaches its maximal extension.
 
     """

src/python/espressomd/collision_detection.py

@@ -60,7 +60,7 @@ def set_params(self, **kwargs):
 
         Parameters
         ----------
-        mode : :obj:`str`, \{"off", "bind_centers", "bind_at_point_of_collision", "bind_three_particles", "glue_to_surface"\}
+        mode : :obj:`str`, {"off", "bind_centers", "bind_at_point_of_collision", "bind_three_particles", "glue_to_surface"}
             Collision detection mode
 
         distance : :obj:`float`

src/python/espressomd/constraints.py

@@ -38,7 +38,7 @@ def add(self, *args, **kwargs):
         ----------
         constraint: :class:`espressomd.constraints.Constraint`
             Either a constraint object...
-        \*\*kwargs : any
+        **kwargs
             ... or parameters to construct an
             :class:`espressomd.constraints.ShapeBasedConstraint`
 

src/python/espressomd/integrate.pyx

@@ -230,10 +230,10 @@ cdef class SteepestDescent(Integrator):
     Steepest descent algorithm for energy minimization.
 
     Particles located at :math:`\\vec{r}_i` at integration step :math:`i` and
-    experiencing a potential :math:`\mathcal{H}(\\vec{r}_i)` are displaced
+    experiencing a potential :math:`\\mathcal{H}(\\vec{r}_i)` are displaced
     according to the equation:
 
-    :math:`\\vec{r}_{i+1} = \\vec{r}_i - \\gamma\\nabla\mathcal{H}(\\vec{r}_i)`
+    :math:`\\vec{r}_{i+1} = \\vec{r}_i - \\gamma\\nabla\\mathcal{H}(\\vec{r}_i)`
 
     Parameters
     ----------
@@ -437,7 +437,7 @@ IF STOKESIAN_DYNAMICS:
             Bulk viscosity.
         radii : :obj:`dict`
             Dictionary that maps particle types to radii.
-        approximation_method : :obj:`str`, optional, \{'ft', 'fts'\}
+        approximation_method : :obj:`str`, optional, {'ft', 'fts'}
             Chooses the method of the mobility approximation.
             ``'fts'`` is more accurate. Default is ``'fts'``.
         self_mobility : :obj:`bool`, optional