Merge pull request #3140 from jessica-mitchell/docs-cmake-benchmark

Add CMAKE option for optimizing performance of benchmarks

doc/htmldoc/hpc/benchmarking.rst

@@ -3,22 +3,25 @@
 Benchmarking NEST
 =================
 
+.. seealso::
+
+   When compiling NEST to perform benchmarks, see :ref:`our cmake options <performance_cmake>` for improved performance and energy saving.
 
 beNNch
 ~~~~~~
 
 Computational efficiency is essential to simulate complex neuronal networks and study long-term effects such as learning.
 The scaling performance of neuronal network simulators on high-performance computing systems can be assessed with benchmark simulations.
-However, maintaining comparability of benchmark results across different systems, software environments, network models, and researchers from potentially different labs poses a challenge.  
+However, maintaining comparability of benchmark results across different systems, software environments, network models, and researchers from potentially different labs poses a challenge.
 
-The software framework `beNNch <https://github.com/INM-6/beNNch>`_ tackles this challenge by implementing a unified, modular workflow for configuring, executing, and analyzing such benchmarks.  
+The software framework `beNNch <https://github.com/INM-6/beNNch>`_ tackles this challenge by implementing a unified, modular workflow for configuring, executing, and analyzing such benchmarks.
 beNNch builds around the `JUBE Benchmarking Environment <https://www.fz-juelich.de/ias/jsc/EN/Expertise/Support/Software/JUBE/_node.html>`_, installs simulation software, provides an interface to benchmark models, automates data and metadata annotation, and accounts for storage and presentation of results.
 
 For more details on the conceptual ideas behind beNNch, refer to Albers et al. (2022) [1]_.
 
 .. figure:: ../static/img/multi-area-model_5faa0e9c.png
 
-    Example ``beNNch`` output (Figure 5C of [1]_) 
+    Example ``beNNch`` output (Figure 5C of [1]_)
 
     Strong-scaling performance of the `multi-area model <https://github.com/INM-6/multi-area-model>`_ simulated with NEST on JURECA-DC.
     The left graph shows the absolute wall-clock time measured with Python-level timers for both network construction and state propagation.
@@ -29,7 +32,7 @@ For more details on the conceptual ideas behind beNNch, refer to Albers et al. (
     The lower right graph shows the relative contribution of these phases to the state-propagation time.
 
 
-.. seealso:: 
+.. seealso::
 
     For further details, see the accompanying `beNNch GitHub Page <https://inm-6.github.io/beNNch>`_.
     And for a detailed step-by-step walk though see `Walk through guide <https://inm-6.github.io/beNNch/walk-through.html>`_.
@@ -43,6 +46,3 @@ References
 
 .. [1] Albers J., et al (2022). A Modular Workflow for Performance Benchmarking of Neuronal Network Simulations.
        Frontiers in Neuroinformatics(16):837549. https://doi.org/10.3389/fninf.2022.837549
-
-
-

doc/htmldoc/installation/cmake_options.rst

@@ -99,6 +99,37 @@ Use Python to build PyNEST
 
 For more details, see the :ref:`Python binding <compile_with_python>` section below.
 
+.. _performance_cmake:
+
+Maximize performance, reduce energy consumption
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
+
+The following options help to optimize NEST for maximal performance and thus reduced energy consumption.
+
++------------------------------------------+-----------------------------------------------+
+| ``-Dwith-optimize="-O3 -march=native"``  | Activate most compiler options that do not    |
+|                                          | affect compliance with IEEE754 numerics and   |
+|                                          | optimize for CPU type used                    |
++------------------------------------------+-----------------------------------------------+
+| ``-Dwith-defines=-DNDEBUG``              | Disable all ``assert()`` statements in NEST   |
++------------------------------------------+-----------------------------------------------+
+
+.. note::
+
+   * In our experience, gains from these optimizations are not very large. It can still be sensible to test them,
+     especially if you are going to perform a large number of simulations.
+   * Your particular use case may contain edge cases during NEST execution that our extensive test suite has
+     not covered. Internal consistency tests in NEST in the form of ``assert()`` statements can help to detect such
+     edge cases. Using the optimization options above removes these internal checks and thus increases the
+     risk that NEST will produce incorrect results. Therefore, use these options *only after you have performed
+     multiple simulations of your specific model with default optimization settings* (i.e., ``-O2``), which leaves the assertions
+     in place.
+   * Using ``-march=native`` requires that you build NEST on the same CPU architecture as you will use to run it.
+   * For the technically minded: Even just using ``-O3`` removes some ``assert()`` statements from NEST since we
+     have wrapped some of them in functions, which get eliminated due to interprocedural optimization. 
+
+
+
 Select parallelization scheme
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~