YT-CPPHGL-31: Implement flat matrix hypergraph representation models

- Defined a new implementation tag: `flat_matrix_t`
- Aligned the implementation-tag-related constraints
- Created a new internal implementation class `flat_incidence_matrix` with specializations for each layout tag
- Aligned the implementation of `flat_matrix` and `flat_jagged_vector` to use subranges instead of spans as row/segment types to work properly with the boolean value type

Author: SpectraL519

include/gl/impl/adjacency_matrix.hpp

@@ -107,17 +107,17 @@ class adjacency_matrix final {
     }
 
     [[nodiscard]] gl_attr_force_inline bool has_edge(id_type source_id, id_type target_id) const {
-        return this->_matrix[to_idx(source_id)][to_idx(target_id)] != invalid_id;
+        return specialized_impl::get_entry(*this, source_id, target_id) != invalid_id;
     }
 
     [[nodiscard]] bool has_edge(const edge_type& edge) const {
-        return this->_matrix[to_idx(edge.source())][to_idx(edge.target())] == edge.id();
+        return specialized_impl::get_entry(*this, edge.source(), edge.target()) == edge.id();
     }
 
     [[nodiscard]] std::optional<edge_type> get_edge(id_type source_id, id_type target_id) const
     requires(traits::c_has_empty_properties<edge_type>)
     {
-        const auto edge_id = this->_matrix[to_idx(source_id)][to_idx(target_id)];
+        const auto edge_id = specialized_impl::get_entry(*this, source_id, target_id);
         if (edge_id == invalid_id)
             return std::nullopt;
         return std::make_optional<edge_type>(edge_id, source_id, target_id);
@@ -128,7 +128,7 @@ class adjacency_matrix final {
     ) const
     requires(traits::c_has_non_empty_properties<edge_type>)
     {
-        const auto edge_id = this->_matrix[to_idx(source_id)][to_idx(target_id)];
+        const auto edge_id = specialized_impl::get_entry(*this, source_id, target_id);
         if (edge_id == invalid_id)
             return std::nullopt;
         return std::make_optional<edge_type>(
@@ -139,7 +139,7 @@ class adjacency_matrix final {
     [[nodiscard]] std::vector<edge_type> get_edges(id_type source_id, id_type target_id) const
     requires(traits::c_has_empty_properties<edge_type>)
     {
-        const auto edge_id = this->_matrix[to_idx(source_id)][to_idx(target_id)];
+        const auto edge_id = specialized_impl::get_entry(*this, source_id, target_id);
         if (edge_id == invalid_id)
             return std::vector<edge_type>();
         return std::vector<edge_type>{
@@ -152,7 +152,7 @@ class adjacency_matrix final {
     ) const
     requires(traits::c_has_non_empty_properties<edge_type>)
     {
-        const auto edge_id = this->_matrix[to_idx(source_id)][to_idx(target_id)];
+        const auto edge_id = specialized_impl::get_entry(*this, source_id, target_id);
         if (edge_id == invalid_id)
             return std::vector<edge_type>();
         return std::vector<edge_type>{
@@ -197,11 +197,13 @@ class adjacency_matrix final {
     {
         return std::views::iota(initial_id_v<id_type>, this->_matrix.size())
              | std::views::filter([this, vertex_id](const auto source_id) {
-                   return this->_matrix[to_idx(source_id)][to_idx(vertex_id)] != invalid_id;
+                   return specialized_impl::get_entry(*this, source_id, vertex_id) != invalid_id;
                })
              | std::views::transform([this, vertex_id](const auto source_id) {
                    return edge_type{
-                       this->_matrix[to_idx(source_id)][to_idx(vertex_id)], source_id, vertex_id
+                       specialized_impl::get_entry(*this, source_id, vertex_id),
+                       source_id,
+                       vertex_id
                    };
                });
     }
@@ -213,10 +215,10 @@ class adjacency_matrix final {
     {
         return std::views::iota(initial_id_v<id_type>, this->_matrix.size())
              | std::views::filter([this, vertex_id](const auto source_id) {
-                   return this->_matrix[to_idx(source_id)][to_idx(vertex_id)] != invalid_id;
+                   return specialized_impl::get_entry(*this, source_id, vertex_id) != invalid_id;
                })
              | std::views::transform([this, vertex_id, &edge_properties_map](const auto source_id) {
-                   const auto edge_id = this->_matrix[to_idx(source_id)][to_idx(vertex_id)];
+                   const auto edge_id = specialized_impl::get_entry(*this, source_id, vertex_id);
                    return edge_type{
                        edge_id, source_id, vertex_id, *edge_properties_map[to_idx(edge_id)]
                    };

include/gl/impl/specialized/adjacency_list.hpp

@@ -154,7 +154,7 @@ struct directed_adjacency_list {
         }
 
         // remove the list of edges incident from the vertex entirely
-        self._list.erase(self._list.begin() + static_cast<std::ptrdiff_t>(vertex_id));
+        self._list.erase(self._list.begin() + to_diff(vertex_id));
         return removed_edges;
     }
 
@@ -255,7 +255,7 @@ struct undirected_adjacency_list {
         const auto removed_edges =
             self._list[vertex_idx] | std::views::transform(&item_type::edge_id)
             | std::ranges::to<std::vector>();
-        self._list.erase(self._list.begin() + static_cast<std::ptrdiff_t>(vertex_id));
+        self._list.erase(self._list.begin() + to_diff(vertex_id));
         return removed_edges;
     }
 

include/gl/impl/specialized/adjacency_matrix.hpp

@@ -154,17 +154,21 @@ struct directed_adjacency_matrix {
             | std::views::filter([](auto edge_id) { return edge_id != invalid_id; })
             | std::ranges::to<std::vector>();
 
-        self._matrix.erase(self._matrix.begin() + static_cast<std::ptrdiff_t>(vertex_id));
-
+        const auto vertex_pos = to_diff(vertex_id);
+        self._matrix.erase(self._matrix.begin() + vertex_pos);
         for (auto& row : self._matrix) {
             if (const auto edge_id = row[vertex_idx]; edge_id != invalid_id)
                 removed_edges.push_back(edge_id);
-            row.erase(row.begin() + static_cast<std::ptrdiff_t>(vertex_id));
+            row.erase(row.begin() + vertex_pos);
         }
 
         return removed_edges;
     }
 
+    static id_type get_entry(const impl_type& self, id_type source_id, id_type target_id) {
+        return self._matrix[to_idx(source_id)][to_idx(target_id)];
+    }
+
     static inline void add_edge(
         impl_type& self, id_type edge_id, id_type source_id, id_type target_id
     ) {
@@ -277,14 +281,18 @@ struct undirected_adjacency_matrix {
             | std::views::filter([](auto edge_id) { return edge_id != invalid_id; })
             | std::ranges::to<std::vector>();
 
-        const auto vertex_pos = static_cast<std::ptrdiff_t>(vertex_id);
+        const auto vertex_pos = to_diff(vertex_id);
         self._matrix.erase(self._matrix.begin() + vertex_pos);
         for (auto& row : self._matrix)
             row.erase(row.begin() + vertex_pos);
 
         return removed_edges;
     }
 
+    static id_type get_entry(const impl_type& self, id_type source_id, id_type target_id) {
+        return self._matrix[to_idx(source_id)][to_idx(target_id)];
+    }
+
     static void add_edge(impl_type& self, id_type edge_id, id_type source_id, id_type target_id) {
         detail::check_edge_override(self._matrix, source_id, target_id);
 

include/gl/impl/specialized/flat_adjacency_matrix.hpp

@@ -4,6 +4,7 @@
 
 #pragma once
 
+#include "gl/attributes/diagnostics.hpp"
 #include "gl/constants.hpp"
 #include "gl/decl/impl_tags.hpp"
 #include "gl/graph_traits.hpp"
@@ -19,6 +20,36 @@
 
 namespace gl::impl::specialized {
 
+namespace detail {
+
+template <traits::c_id_type IdType>
+[[nodiscard]] auto& strict_get(flat_matrix<IdType>& id_matrix, const auto& edge) {
+    // get the edge and validate the address
+    const auto [source_id, target_id] = edge.incident_vertices();
+    auto& edge_id = id_matrix[to_idx(source_id), to_idx(target_id)];
+    if (edge.id() != edge_id)
+        throw std::invalid_argument(std::format(
+            "Got invalid edge [id = {} | vertices = ({}, {})]", edge.id(), source_id, target_id
+        ));
+
+    return edge_id;
+}
+
+template <traits::c_id_type IdType>
+inline void check_edge_override(
+    const flat_matrix<IdType>& id_matrix, const IdType source_id, const IdType target_id
+) {
+    if (const auto edge_id = id_matrix[to_idx(source_id), to_idx(target_id)]; edge_id != invalid_id)
+        throw std::logic_error(std::format(
+            "Cannot override an existing edge: [id = {}, vertices = ({}, {})]",
+            edge_id,
+            source_id,
+            target_id
+        ));
+}
+
+} // namespace detail
+
 template <traits::c_instantiation_of<adjacency_matrix> AdjacencyMatrix>
 requires(traits::c_directed_edge<typename AdjacencyMatrix::edge_type>)
 struct directed_flat_adjacency_matrix {
@@ -66,9 +97,10 @@ struct directed_flat_adjacency_matrix {
         const auto row = self._matrix[vertex_idx];
         const auto col = self._matrix.col(vertex_idx);
 
-        for (auto v_idx = 0uz; v_idx < self._matrix.n_rows(); ++v_idx)
-            deg += static_cast<size_type>(row[v_idx] != invalid_id)
-                 + static_cast<size_type>(col[static_cast<std::ptrdiff_t>(v_idx)] != invalid_id);
+        const auto n_rows_bound = to_diff(self._matrix.n_rows());
+        for (auto v_pos = 0z; v_pos < n_rows_bound; ++v_pos)
+            deg += static_cast<size_type>(row[v_pos] != invalid_id)
+                 + static_cast<size_type>(col[v_pos] != invalid_id);
 
         return deg;
     }
@@ -121,7 +153,7 @@ struct directed_flat_adjacency_matrix {
             if (r_idx == vertex_idx)
                 continue;
 
-            const auto edge_id = col[static_cast<std::ptrdiff_t>(r_idx)];
+            const auto edge_id = col[to_diff(r_idx)];
             if (edge_id != invalid_id)
                 removed_edges.push_back(edge_id);
         }
@@ -133,6 +165,10 @@ struct directed_flat_adjacency_matrix {
         return removed_edges;
     }
 
+    static id_type get_entry(const impl_type& self, id_type source_id, id_type target_id) {
+        return self._matrix[to_idx(source_id), to_idx(target_id)];
+    }
+
     static inline void add_edge(
         impl_type& self, id_type edge_id, id_type source_id, id_type target_id
     ) {
@@ -151,7 +187,7 @@ struct directed_flat_adjacency_matrix {
 
         auto matrix_source_row = self._matrix[to_idx(source_id)];
         for (auto [edge_id, target_id] : std::views::zip(edge_ids, target_ids))
-            matrix_source_row[to_idx(target_id)] = edge_id;
+            matrix_source_row[to_diff(target_id)] = edge_id;
     }
 
     static inline void remove_edge(impl_type& self, const edge_type& edge) {
@@ -246,6 +282,10 @@ struct undirected_flat_adjacency_matrix {
         return removed_edges;
     }
 
+    static id_type get_entry(const impl_type& self, id_type source_id, id_type target_id) {
+        return self._matrix[to_idx(source_id), to_idx(target_id)];
+    }
+
     static void add_edge(impl_type& self, id_type edge_id, id_type source_id, id_type target_id) {
         detail::check_edge_override(self._matrix, source_id, target_id);
 
@@ -271,7 +311,7 @@ struct undirected_flat_adjacency_matrix {
 
         for (auto [edge_id, target_id] : std::views::zip(edge_ids, target_ids)) {
             const auto target_idx = to_idx(target_id);
-            matrix_source_row[target_idx] = edge_id;
+            matrix_source_row[to_diff(target_id)] = edge_id;
             if (target_idx != source_idx)
                 self._matrix[target_idx, source_idx] = edge_id;
         }

include/gl/types/core.hpp

@@ -7,6 +7,7 @@
 #include "gl/attributes/force_inline.hpp"
 
 #include <concepts>
+#include <cstddef>
 #include <cstdint>
 #include <optional>
 #include <utility>
@@ -27,6 +28,10 @@ concept c_id_type = std::unsigned_integral<T>;
     return static_cast<size_type>(id);
 }
 
+[[nodiscard]] gl_attr_force_inline constexpr std::ptrdiff_t to_diff(std::integral auto i) noexcept {
+    return static_cast<std::ptrdiff_t>(i);
+}
+
 template <typename T>
 using homogeneous_pair = std::pair<T, T>;