Update built-in timer documentation

.readthedocs.yml

@@ -5,6 +5,7 @@ build:
   tools:
     python: "3.10"
   apt_packages:
+    - graphviz
     - default-jre-headless
   jobs:
     pre_install:

doc/htmldoc/_ext/make_diagram.py

@@ -0,0 +1,189 @@
+# -*- coding: utf-8 -*-
+#
+# make_diagram.py
+#
+# This file is part of NEST.
+#
+# Copyright (C) 2004 The NEST Initiative
+#
+# NEST is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# NEST is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with NEST.  If not, see <http://www.gnu.org/licenses/>.
+"""
+Create an archtictural DOT diagram from YAML input.
+"""
+
+import yaml
+from graphviz import Digraph
+from sphinx.application import Sphinx
+
+
+def add_subgraph(graph, data):
+    """
+    Recursively add subgraphs and nodes to the graph,
+    preserving the hierarchy and attributes from the YAML.
+    """
+    if isinstance(data, list):
+        i = 0
+        while i < len(data):
+            item = data[i]
+            if "name" in item:
+                name = item["name"]
+                # Gather all subsequent dicts without 'name' as attributes
+                j = i + 1
+                attrs = {}
+                # Collect all attributes for this subgraph
+                while j < len(data) and "name" not in data[j]:
+                    attrs.update(data[j])
+                    j += 1
+                # Create subgraph
+                with graph.subgraph(name=f"cluster_{name}") as sg:
+                    sg.attr(label=name)
+                    # Here we define some attributes for all subgraphs
+                    sg.attr(fontname="Helvetica,Arial,sans-serif", fontcolor="white", style="filled")
+                    # Apply all collected attributes to the subgraph
+                    for key, value in attrs.items():
+                        if key != "node" and key != "subgraph":
+                            sg.attr(**{key: value})
+                        # Add nodes
+                    nodes = attrs.get("node", [])
+                    if isinstance(nodes, str):
+                        nodes = [nodes]
+                    for n in nodes:
+                        sg.node(n)
+                    # Recurse into nested subgraphs
+                    if "subgraph" in attrs:
+                        add_subgraph(sg, attrs["subgraph"])
+                i = j
+            else:
+                i += 1
+
+
+def yaml_to_graphviz(yaml_str):
+    """
+    Convert a YAML string to a Graphviz Digraph.
+
+    Parameters:
+    yaml_str (str): The YAML string to convert.
+
+    Returns:
+    Digraph: The generated Graphviz Digraph.
+    """
+    try:
+        data = yaml.safe_load(yaml_str)
+    except yaml.YAMLError as e:
+        raise ValueError(f"Error parsing YAML: {e}") from e
+    if not isinstance(data, dict):
+        raise ValueError("YAML data must be a dictionary")
+
+    dot = Digraph(
+        "G",
+        node_attr={
+            "fontname": "Helvetica,Arial,sans-serif",
+            "shape": "box",
+            "fontcolor": "black",
+            "style": "filled",
+            "fillcolor": "white",
+        },
+    )
+    dot.attr(
+        rankdir="LR",
+        bgcolor="#ff6633",
+        label="Simulation Run",
+        labelloc="t",
+        fontcolor="white",
+        fontname="Helvetica,Arial,sans-serif",
+    )
+    for main_section in data.values():
+        add_subgraph(dot, main_section["subgraph"])
+    # dot.render(output_file, format='svg', cleanup=True)
+    return dot
+
+
+# --- Use the full YAML ---
+GRAPH_YAML = """
+simulation_run:
+  subgraph:
+    - name: simulate_timer
+    - fillcolor: '#072f42'
+      subgraph:
+        - name: OMP_Parallel
+        - fillcolor: '#0E6A93'
+          subgraph:
+            - name: time_driven_loop
+            - fillcolor: '#4b210c'
+              subgraph:
+                - name: deliver_spike_data_timer
+                - fillcolor: '#072f42'
+                  node: deliver_events
+                - name: if_detailed_timers_enabled
+                - fillcolor: 'darkgrey'
+                  node: OMP_Barrier
+                - name: update_timer
+                - fillcolor: 'darkgrey'
+                  node:
+                    - node_update
+                    - OMP_Barrier
+            - node: OMP_barrier
+            - name: OMP_Master
+            - fillcolor: '#0E6A93'
+              subgraph:
+                - name: gather_spike_data_timer
+                - fillcolor: '#072f42'
+                  subgraph:
+                    - name: gather_spike_data
+                    - fillcolor: '#4b210c'
+                      subgraph:
+                        - name: do_once_repeat_if_failed
+                        - fillcolor: 'darkgrey'
+                          subgraph:
+                          - name: if_buffers_can_shrink
+                            node: shrink_MPI_buffer_size
+                          - name: collocate_spike_data_timer
+                          - fillcolor: '#072f42'
+                            node:
+                              - reset_MPI_buffer_markers
+                              - collocate_spike_data
+                              - set_end_markers_in_MPI_buffer
+                          - name: communicate_spike_data_timer
+                          - fillcolor: '#072f42'
+                            node: communicate_spike_data
+            - node: advance_time
+"""
+
+
+def yaml2dot(app, env, docnames):
+    """
+    Sphinx event handler to convert YAML data to a Graphviz DOT file.
+    """
+
+    dot = yaml_to_graphviz(GRAPH_YAML)
+    with open("simulation_run.dot", "w", encoding="UTF-8") as f:
+        f.write(dot.source)
+
+
+def setup(app):
+    """
+    Setup function for the Sphinx extension.
+
+    This function connects the `yaml2dot` event handler to the
+    `env-before-read-docs` event, which is triggered before Sphinx reads
+    the documentation files.
+    """
+
+    app.connect("env-before-read-docs", yaml2dot)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

doc/htmldoc/benchmark_results.rst

@@ -7,6 +7,7 @@ NEST performance benchmarks
 NEST performance is continuously monitored and improved across various network sizes.
 Here we show benchmarking results for NEST version 3.8 on Jureca-DC [1]_.
 The benchmarking framework and the structure of the graphs is described in [2]_.
+For details on `State Propagation` (i.e., `Simulation Run`), see the guides :ref:`built_in_timers` and :ref:`run_simulations`
 
 Strong scaling experiment of the Microcircuit model [3]_
 ---------------------------------------------------------
@@ -45,11 +46,11 @@ Strong scaling experiment of the Multi-area-model [5]_
        :columns: 10
 
        Dynamical regime: Ground state
-       
+
        .. image:: /static/img/mam_ground-state_benchmark.png
 
        Dynamical regime: Metastable state
-       
+
        .. image:: /static/img/mam_metastable-state_benchmark.png
 
 
@@ -96,6 +97,8 @@ Weak scaling experiment of the HPC benchmark model [6]_
 
 .. seealso::
 
+   * Guide to :ref:`Built-in timers <built_in_timers>` and :ref:`run_simulations`.
+
    Example networks:
 
    * :doc:`/auto_examples/Potjans_2014/index`

doc/htmldoc/conf.py

@@ -22,6 +22,8 @@
 
 import json
 import os
+
+# import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -44,6 +46,7 @@
 extensions = [
     "sphinx_gallery.gen_gallery",
     "list_examples",
+    "sphinx.ext.graphviz",
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.autosummary",
@@ -55,6 +58,7 @@
     "sphinxcontrib.plantuml",
     "add_button_notebook",
     "IPython.sphinxext.ipython_console_highlighting",
+    "make_diagram",
     "model_tag_setup",
     "nbsphinx",
     "extract_api_functions",
@@ -101,7 +105,8 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-
+graphviz_output_format = "svg"
+graphviz_dot = "dot"
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #

doc/htmldoc/hpc/benchmarking.rst

@@ -33,18 +33,20 @@ For more details on the conceptual ideas behind beNNch, refer to Albers et al. (
     The left graph shows the absolute wall-clock time measured with Python-level timers for both network construction and state propagation.
     Error bars indicate variability across three simulation repeats with different random seeds.
     The top right graph displays the real-time factor defined as wall-clock time normalized by the model time.
-    Built-in timers resolve four different phases of the state propagation: update, collocation, communication, and delivery.
+    :ref:`Built-in timers <built_in_timers>` resolve four different phases of the state propagation: update, collocation, communication, and delivery.
     Pink error bars show the same variability of state propagation as the left graph.
     The lower right graph shows the relative contribution of these phases to the state-propagation time.
 
 
 .. 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>`_.
+    * For further details, see the accompanying `beNNch GitHub Page <https://inm-6.github.io/beNNch>`_.
 
-    Example PyNEST script: :doc:`../auto_examples/hpc_benchmark`
+    * For a detailed step-by-step walk though see `Walk through guide <https://inm-6.github.io/beNNch/walk-through.html>`_.
 
+    * Example PyNEST script: :doc:`../auto_examples/hpc_benchmark`
+
+    * Guide to :ref:`built_in_timers` and :ref:`running simulations <run_simulations>`.
 
 References
 ----------