more docu

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/directed_graph_edge_desc_concept.hpp

@@ -19,38 +19,99 @@ limitations under the License.
 #pragma once
 
 #include "directed_graph_concept.hpp"
-#include "osp/graph_algorithms/directed_graph_edge_view.hpp"
 #include "graph_traits.hpp"
+#include "osp/graph_algorithms/directed_graph_edge_view.hpp"
+
+/**
+ * @file directed_graph_edge_desc_concept.hpp
+ * @brief Concepts and default implementations for edge descriptors in directed graphs.
+ *
+ * This file extends the basic directed graph concepts to support edge descriptors.
+ * It provides default implementations for accessing source/target vertices from edges
+ * and defines the `is_directed_graph_edge_desc` concept to check if a graph type
+ * properly supports edge descriptors and edge iteration.
+ *
+ * Note: If a graph implementation satisfies `directed_graph_concept`, OSP automatically
+ * adds the edge descriptor API on top using `directed_edge` as the default edge descriptor.
+ * The mechanics for this are implemented in `directed_graph_edge_view.hpp`.
+ */
 
 namespace osp {
 
-// default implementation to get the source of an edge
+/**
+ * @brief Default implementation to get the source vertex of an edge.
+ *
+ * @tparam Graph_t The graph type.
+ * @param edge The edge descriptor.
+ * @return The source vertex index.
+ */
 template<typename Graph_t>
 inline vertex_idx_t<Graph_t> source(const directed_edge<Graph_t> &edge, const Graph_t &) {
     return edge.source;
 }
 
-// default implementation to get the target of an edge
+/**
+ * @brief Default implementation to get the target vertex of an edge.
+ *
+ * @tparam Graph_t The graph type.
+ * @param edge The edge descriptor.
+ * @return The target vertex index.
+ */
 template<typename Graph_t>
 inline vertex_idx_t<Graph_t> target(const directed_edge<Graph_t> &edge, const Graph_t &) {
     return edge.target;
 }
 
+/**
+ * @brief Get a view of all edges in the graph.
+ *
+ * @tparam Graph_t The graph type.
+ * @param graph The graph instance.
+ * @return An `edge_view` allowing iteration over all edges.
+ */
 template<typename Graph_t>
 inline edge_view<Graph_t> edges(const Graph_t &graph) {
     return edge_view(graph);
 }
 
+/**
+ * @brief Get a view of outgoing edges from a vertex.
+ *
+ * @tparam Graph_t The graph type.
+ * @param u The source vertex index.
+ * @param graph The graph instance.
+ * @return An `out_edge_view` allowing iteration over outgoing edges from `u`.
+ */
 template<typename Graph_t>
 inline out_edge_view<Graph_t> out_edges(vertex_idx_t<Graph_t> u, const Graph_t &graph) {
     return out_edge_view(graph, u);
 }
 
+/**
+ * @brief Get a view of incoming edges to a vertex.
+ *
+ * @tparam Graph_t The graph type.
+ * @param v The target vertex index.
+ * @param graph The graph instance.
+ * @return An `in_edge_view` allowing iteration over incoming edges to `v`.
+ */
 template<typename Graph_t>
 inline in_edge_view<Graph_t> in_edges(vertex_idx_t<Graph_t> v, const Graph_t &graph) {
     return in_edge_view(graph, v);
 }
 
+/**
+ * @brief Concept check for a directed graph with edge descriptors.
+ *
+ * Checks if a type `T` satisfies the requirements of a directed graph that also
+ * supports edge descriptors, including:
+ * - Validity of `directed_graph_edge_desc_traits`.
+ * - Existence of `edges()`, `out_edges()`, and `in_edges()` functions returning input ranges of edge descriptors.
+ * - Existence of `source()` and `target()` functions mapping edge descriptors to vertex indices.
+ * - Default and copy constructibility of the edge descriptor type.
+ *
+ * @tparam T The graph type to check.
+ */
 template<typename T, typename = void>
 struct is_directed_graph_edge_desc : std::false_type {};
 
@@ -74,8 +135,13 @@ struct is_directed_graph_edge_desc<T,
 template<typename T>
 inline constexpr bool is_directed_graph_edge_desc_v = is_directed_graph_edge_desc<T>::value;
 
-// Specialization for graphs that define a directed_edge_descriptor that can be used as a key in a hash table.
-// Compatible with STL hash tables.
+/**
+ * @brief Specialization for graphs that define a directed_edge_descriptor that can be used as a key in a hash table.
+ *
+ * Compatible with STL hash tables (requires `std::hash` specialization and equality operator).
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct has_hashable_edge_desc : std::false_type {};
 
@@ -87,7 +153,6 @@ struct has_hashable_edge_desc<T,
     : std::conjunction<is_directed_graph_edge_desc<T>, std::is_default_constructible<edge_desc_t<T>>,
                        std::is_copy_constructible<edge_desc_t<T>>> {};
 
-
 template<typename T>
 inline constexpr bool has_hashable_edge_desc_v = has_hashable_edge_desc<T>::value;