added docu to concepts files (#61)

Author: tonibohnlein

include/osp/concepts/computational_dag_concept.hpp

@@ -22,9 +22,36 @@ limitations under the License.
 
 #include "directed_graph_edge_desc_concept.hpp"
 
+/**
+ * @file computational_dag_concept.hpp
+ * @brief Concepts for Computational Directed Acyclic Graphs (cDAGs).
+ *
+ * This file defines concepts that validate whether a graph type satisfies the requirements
+ * of a computational DAG.
+ *
+ * A Computational DAG combines:
+ * - The `directed_graph_concept`.
+ * - Mandatory vertex weights: work, communication, and memory.
+ *
+ * Optional extensions include:
+ * - Vertex types (for heterogeneous systems).
+ * - Edge weights (communication).
+ *
+ * A computational DAG serves as an input to scheduling algorithms.
+ */
+
 namespace osp {
 
-// weighted vertices
+/**
+ * @brief Concept to check if a graph has vertex weights.
+ *
+ * Requires validation of:
+ * - `vertex_work_weight(v)`: Returns arithmetic type.
+ * - `vertex_comm_weight(v)`: Returns arithmetic type.
+ * - `vertex_mem_weight(v)`: Returns arithmetic type.
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct has_vertex_weights : std::false_type {};
 
@@ -41,7 +68,18 @@ struct has_vertex_weights<T,
 template<typename T>
 inline constexpr bool has_vertex_weights_v = has_vertex_weights<T>::value;
 
-// typed vertices concept
+/**
+ * @brief Concept to check if a graph has typed vertices.
+ *
+ * Requires validation of:
+ * - `vertex_type(v)`: Returns an integral type representing the type of vertex `v`.
+ * - `num_vertex_types()`: Returns the total number of distinct vertex types.
+ *
+ * This is useful for scheduling on heterogeneous resources where tasks (vertices)
+ * may be compatible only with certain processor types.
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct has_typed_vertices : std::false_type {};
 
@@ -54,7 +92,15 @@ struct has_typed_vertices<T, std::void_t<decltype(std::declval<T>().vertex_type(
 template<typename T>
 inline constexpr bool has_typed_vertices_v = has_typed_vertices<T>::value;
 
-// weighted edges concept
+/**
+ * @brief Concept to check if edges have communication weights.
+ *
+ * Requires:
+ * - The graph must satisfy `is_directed_graph_edge_desc` (supports edge descriptors).
+ * - `edge_comm_weight(e)`: Returns an arithmetic type for a given edge descriptor `e`.
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct has_edge_weights : std::false_type {};
 
@@ -69,7 +115,15 @@ struct has_edge_weights<T,
 template<typename T>
 inline constexpr bool has_edge_weights_v = has_edge_weights<T>::value;
 
-// computational dag concept without explicit edges
+/**
+ * @brief Concept for a basic computational DAG.
+ *
+ * A computational DAG must:
+ * - Be a directed graph (`is_directed_graph`).
+ * - Have mandatory vertex weights (`has_vertex_weights`): work, communication, and memory.
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_computational_dag : std::false_type {};
 
@@ -79,8 +133,13 @@ struct is_computational_dag<T, std::void_t<>> : std::conjunction<is_directed_gra
 template<typename T>
 inline constexpr bool is_computational_dag_v = is_computational_dag<T>::value;
 
-
-// computational dag with typed vertices concept
+/**
+ * @brief Concept for a computational DAG with typed vertices.
+ *
+ * Extends `is_computational_dag` by also requiring `has_typed_vertices`.
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_computational_dag_typed_vertices : std::false_type {};
 
@@ -91,9 +150,14 @@ struct is_computational_dag_typed_vertices<T, std::void_t<>>
 template<typename T>
 inline constexpr bool is_computational_dag_typed_vertices_v = is_computational_dag_typed_vertices<T>::value;
 
-
-
-// computational dag with explicit edges concept
+/**
+ * @brief Concept for a computational DAG that supports explicit edge descriptors.
+ *
+ * Extends `is_computational_dag` by requiring `is_directed_graph_edge_desc`,
+ * allowing iteration over edges using explicit descriptors.
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_computational_dag_edge_desc : std::false_type {};
 
@@ -104,7 +168,13 @@ struct is_computational_dag_edge_desc<T, std::void_t<>>
 template<typename T>
 inline constexpr bool is_computational_dag_edge_desc_v = is_computational_dag_edge_desc<T>::value;
 
-// computational_dag_typed_vertices_edge_idx concept
+/**
+ * @brief Concept for a computational DAG with both typed vertices and edge descriptors.
+ *
+ * Combines `is_directed_graph_edge_desc` and `is_computational_dag_typed_vertices`.
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_computational_dag_typed_vertices_edge_desc : std::false_type {};
 

include/osp/concepts/constructable_computational_dag_concept.hpp

@@ -22,10 +22,32 @@ limitations under the License.
 
 #include "computational_dag_concept.hpp"
 
+/**
+ * @file constructable_computational_dag_concept.hpp
+ * @brief Concepts for Constructable and Modifiable Computational DAGs.
+ *
+ * This file defines concepts that validate whether a graph type supports dynamic construction
+ * and modification of its structure and properties. This includes adding vertices and edges,
+ * as well as setting weights and types for existing elements.
+ *
+ * These concepts are useful for algorithms that need to build or transform graphs,
+ * such as graph generators or coarsening algorithms.
+ */
 
 namespace osp {
 
-// modify vertices
+/**
+ * @brief Concept to check if vertex weights are modifiable.
+ *
+ * Requires:
+ * - `set_vertex_work_weight(v, w)`
+ * - `set_vertex_comm_weight(v, w)`
+ * - `set_vertex_mem_weight(v, w)`
+ *
+ * Also requires the graph to be default constructible, copy/move constructible, and assignable.
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_modifiable_cdag_vertex : std::false_type {};
 
@@ -36,54 +58,83 @@ struct is_modifiable_cdag_vertex<
                    decltype(std::declval<T>().set_vertex_mem_weight(std::declval<vertex_idx_t<T>>(), std::declval<v_memw_t<T>>()))>>
     : std::conjunction<is_computational_dag<T>,
                        std::is_default_constructible<T>,
-                       std::is_copy_constructible<T>, 
-                       std::is_move_constructible<T>, 
+                       std::is_copy_constructible<T>,
+                       std::is_move_constructible<T>,
                        std::is_copy_assignable<T>,
                        std::is_move_assignable<T>> {};
 
 template<typename T>
 inline constexpr bool is_modifiable_cdag_vertex_v = is_modifiable_cdag_vertex<T>::value;
 
-// add vertices
+/**
+ * @brief Concept to check if vertices can be added to the graph.
+ *
+ * Requires:
+ * - `add_vertex(work_weight, comm_weight, mem_weight)`
+ * - Constructibility from `vertex_idx_t` (for reserving size).
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_constructable_cdag_vertex : std::false_type {};
 
 template<typename T>
 struct is_constructable_cdag_vertex<
     T, std::void_t<decltype(std::declval<T>().add_vertex(std::declval<v_workw_t<T>>(), std::declval<v_commw_t<T>>(), std::declval<v_memw_t<T>>()))>>
-    : std::conjunction<is_modifiable_cdag_vertex<T>, 
+    : std::conjunction<is_modifiable_cdag_vertex<T>,
                        std::is_constructible<T, vertex_idx_t<T>>> {};
 
 template<typename T>
 inline constexpr bool is_constructable_cdag_vertex_v = is_constructable_cdag_vertex<T>::value;
 
-// modify vertices types
+/**
+ * @brief Concept to check if vertex types are modifiable.
+ *
+ * Requires:
+ * - `set_vertex_type(v, type)`
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_modifiable_cdag_typed_vertex : std::false_type {};
 
 template<typename T>
 struct is_modifiable_cdag_typed_vertex<
     T, std::void_t<decltype(std::declval<T>().set_vertex_type(std::declval<vertex_idx_t<T>>(), std::declval<v_type_t<T>>()))>>
-    : std::conjunction<is_modifiable_cdag_vertex<T>, 
+    : std::conjunction<is_modifiable_cdag_vertex<T>,
                        is_computational_dag_typed_vertices<T>> {}; // for default node type
 
 template<typename T>
 inline constexpr bool is_modifiable_cdag_typed_vertex_v = is_modifiable_cdag_typed_vertex<T>::value;
 
-// add vertices with types
+/**
+ * @brief Concept to check if typed vertices can be added.
+ *
+ * Requires:
+ * - `add_vertex(work, comm, mem, type)`
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_constructable_cdag_typed_vertex : std::false_type {};
 
 template<typename T>
 struct is_constructable_cdag_typed_vertex<
     T, std::void_t<decltype(std::declval<T>().add_vertex(std::declval<v_workw_t<T>>(), std::declval<v_commw_t<T>>(), std::declval<v_memw_t<T>>(), std::declval<v_type_t<T>>()))>>
-    : std::conjunction<is_constructable_cdag_vertex<T>, 
+    : std::conjunction<is_constructable_cdag_vertex<T>,
                        is_modifiable_cdag_typed_vertex<T>> {}; // for default node type
 
 template<typename T>
 inline constexpr bool is_constructable_cdag_typed_vertex_v = is_constructable_cdag_typed_vertex<T>::value;
 
-// add edges
+/**
+ * @brief Concept to check if edges can be added (unweighted).
+ *
+ * Requires:
+ * - `add_edge(source, target)`
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_constructable_cdag_edge : std::false_type {};
 
@@ -95,7 +146,14 @@ struct is_constructable_cdag_edge<T, std::void_t<decltype(std::declval<T>().add_
 template<typename T>
 inline constexpr bool is_constructable_cdag_edge_v = is_constructable_cdag_edge<T>::value;
 
-// modify edges with comm costs
+/**
+ * @brief Concept to check if edge communication weights are modifiable.
+ *
+ * Requires:
+ * - `set_edge_comm_weight(edge, weight)`
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_modifiable_cdag_comm_edge : std::false_type {};
 
@@ -107,20 +165,34 @@ struct is_modifiable_cdag_comm_edge<
 template<typename T>
 inline constexpr bool is_modifiable_cdag_comm_edge_v = is_modifiable_cdag_comm_edge<T>::value;
 
-// add edges with comm costs
+/**
+ * @brief Concept to check if weighted edges can be added.
+ *
+ * Requires:
+ * - `add_edge(source, target, weight)`
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_constructable_cdag_comm_edge : std::false_type {};
 
 template<typename T>
 struct is_constructable_cdag_comm_edge<
     T, std::void_t<decltype(std::declval<T>().add_edge(std::declval<vertex_idx_t<T>>(), std::declval<vertex_idx_t<T>>(), std::declval<e_commw_t<T>>()))>>
-    : std::conjunction<is_constructable_cdag_edge<T>, 
+    : std::conjunction<is_constructable_cdag_edge<T>,
                        is_computational_dag_edge_desc<T>,
                        is_modifiable_cdag_comm_edge<T>> {}; // for default edge weight
 
 template<typename T>
 inline constexpr bool is_constructable_cdag_comm_edge_v = is_constructable_cdag_comm_edge<T>::value;
 
+/**
+ * @brief Concept for a fully constructable computational DAG.
+ *
+ * Combines `is_constructable_cdag_vertex` and `is_constructable_cdag_edge`.
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_constructable_cdag : std::false_type {};
 
@@ -131,6 +203,9 @@ struct is_constructable_cdag<T, std::void_t<>>
 template<typename T>
 inline constexpr bool is_constructable_cdag_v = is_constructable_cdag<T>::value;
 
+/**
+ * @brief Helper trait to check if a graph can be directly constructed from a vertex count and a set of edges.
+ */
 template<typename T>
 inline constexpr bool is_direct_constructable_cdag_v = std::is_constructible<T, vertex_idx_t<T>, std::set<std::pair<vertex_idx_t<T>, vertex_idx_t<T>>>>::value;