more docu

Author: tonibohnlein

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;
 

include/osp/concepts/specific_graph_impl.hpp

@@ -18,21 +18,37 @@ limitations under the License.
 
 #pragma once
 
+/**
+ * @file specific_graph_impl.hpp
+ * @brief Type traits for specific graph implementations used in OneStopParallel.
+ *
+ * This file contains trait checks for specific graph implementations, such as
+ * Compact Sparse Graphs (CSR-like structures), which may require specialized
+ * handling or offer optimizations in certain algorithms.
+ */
+
 namespace osp {
 
-// Compact Sparse Graph concept
+/**
+ * @brief Trait to check if a graph type is a `Compact_Sparse_Graph`.
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_Compact_Sparse_Graph : std::false_type {};
 
 template<typename T>
 inline constexpr bool is_Compact_Sparse_Graph_v = is_Compact_Sparse_Graph<T>::value;
 
-// Compact Sparse Graph concept with reorder
+/**
+ * @brief Trait to check if a graph type is a `Compact_Sparse_Graph` that supports reordering.
+ *
+ * @tparam T The graph type.
+ */
 template<typename T, typename = void>
 struct is_Compact_Sparse_Graph_reorder : std::false_type {};
 
 template<typename T>
 inline constexpr bool is_Compact_Sparse_Graph_reorder_v = is_Compact_Sparse_Graph_reorder<T>::value;
 
-
 } // namespace osp