From bbf051125901925aa77deb9bf94c04860bb70879 Mon Sep 17 00:00:00 2001
From: romintomasetti <romin.tomasetti@gmail.com>
Date: Tue, 1 Apr 2025 16:11:01 +0000
Subject: [PATCH] core(graph): placeholder

---
 .github/workflows/deploy_docs.yml      |  6 +-
 docs/source/ProgrammingGuide/Graph.rst | 93 ++++++++++++++++++++++++++
 docs/source/conf.py                    |  1 +
 docs/source/programmingguide.rst       |  1 +
 4 files changed, 98 insertions(+), 3 deletions(-)
 create mode 100644 docs/source/ProgrammingGuide/Graph.rst

diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml
index 17efcb6f2..d94d6c241 100644
--- a/.github/workflows/deploy_docs.yml
+++ b/.github/workflows/deploy_docs.yml
@@ -10,12 +10,12 @@ jobs:
     runs-on: ubuntu-latest
     env:
       docs-directory: /home/runner/work/kokkos-core-wiki/kokkos-core-wiki/docs
+    container:
+      image: python:3.10
     steps:
       - uses: actions/checkout@v4.2.2
-      - uses: actions/setup-python@v5.4.0
-        with:
-          python-version: '3.10'
       - run: pip install -r build_requirements.txt
+      - run: apt update && apt --yes --no-install-recommends install graphviz
       - name: Build documentation
         working-directory: ${{ env.docs-directory }}
         run: |
diff --git a/docs/source/ProgrammingGuide/Graph.rst b/docs/source/ProgrammingGuide/Graph.rst
new file mode 100644
index 000000000..d384f8464
--- /dev/null
+++ b/docs/source/ProgrammingGuide/Graph.rst
@@ -0,0 +1,93 @@
+16. Graphs
+==========
+
+Usage
+-----
+
+:cppkokkos:`Kokkos::Graph` is an abstraction that describes
+asynchronous workloads organised as a direct acyclic graph (DAG).
+
+Once defined, the graph can be executed many times.
+
+:cppkokkos:`Kokkos::Graph` is specialized for some backends:
+
+* :cppkokkos:`Cuda`
+* :cppkokkos:`HIP`
+* :cppkokkos:`SYCL`
+
+On these backends, the :cppkokkos:`Kokkos::Graph` specialisations map to the native graph API, namely, the CUDA Graph API, the HIP Graph API, and the SYCL (command) Graph API, respectively.
+
+For other backends, :cppkokkos:`Kokkos::Graph` provides a defaulted implementation.
+
+Execution space instance versus graph
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Workloads submitted on :cppkokkos:`Kokkos` execution space instances execute *eagerly*, *i.e.*,
+once the :cppkokkos:`Kokkos::parallel_` function is called, the workload is immediately launched on the device.
+
+By contrast, the :cppkokkos:`Kokkos::Graph` abstraction follows *lazy* execution,
+*i.e*, workloads added to a :cppkokkos:`Kokkos::Graph` are **not** executed *until*
+the whole graph is ready and submitted.
+
+Always in 3 phases
+~~~~~~~~~~~~~~~~~~
+
+Typically, 3 phases are needed:
+
+1. definition
+2. instantiation
+3. submission
+
+The *definition* phase consists in describing the workloads: what they do, as well as their dependencies.
+In other words, this phase creates a *topological* graph of workloads.
+
+The *instantiation* phase **locks** the topology, *i.e.*, it cannot be changed anymore.
+During this phase, the graph will be checked for flaws.
+The backend creates an *executable* graph.
+
+The last phase is *submission*. It will execute the workloads, observing their dependencies.
+This phase can be run multiple times.
+
+Advantages
+~~~~~~~~~~
+
+There are many advantages. Here are a few:
+
+* Since the workloads are described ahead of execution,
+  the backend driver and/or compiler can leverage optimization opportunities.
+* Launch overhead is reduced, benefitting DAGs consisting of small workloads.
+
+Examples
+--------
+
+Diamond DAG
+~~~~~~~~~~~
+
+Consider a diamond-like DAG.
+
+.. graphviz::
+
+    digraph diamond {
+        A -> B;
+        A -> C;
+        B -> D;
+        C -> D;
+    }
+
+The following snippet defines, instantiates and submits a :cppkokkos:`Kokkos::Graph`
+for this DAG.
+
+.. code-block:: c++
+
+    auto graph = Kokkos::create_graph([&](auto root) {
+        auto node_A = root.then_parallel_for("workload A", ...policy..., ...functor...);
+
+        auto node_B = node_A.then_parallel_for("workload B", ...policy..., ...functor...);
+        auto node_C = node_A.then_parallel_for("workload C", ...policy..., ...functor...);
+
+        auto node_D = Kokkos::when_all(node_B, node_C).then_parallel_for("workload D", ...policy..., ...functor...);
+    });
+
+    graph.instantiate();
+
+    graph.submit();
diff --git a/docs/source/conf.py b/docs/source/conf.py
index f410971d4..d9b043f71 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -36,6 +36,7 @@
 # ones.
 extensions = ["myst_parser",
               "sphinx.ext.autodoc",
+              "sphinx.ext.graphviz",
               "sphinx.ext.viewcode",
               "sphinx.ext.intersphinx",
               "sphinx_copybutton",
diff --git a/docs/source/programmingguide.rst b/docs/source/programmingguide.rst
index a87c9b31f..3c71c4eac 100644
--- a/docs/source/programmingguide.rst
+++ b/docs/source/programmingguide.rst
@@ -19,3 +19,4 @@ Programming Guide
    ./ProgrammingGuide/Interoperability
    ./ProgrammingGuide/Kokkos-and-Virtual-Functions
    ./ProgrammingGuide/SIMD
+   ./ProgrammingGuide/Graph