Skip to content

Commit f90082d

Browse files
SpectraL519SpectraL519
committed
conversion docs
1 parent af9ec04 commit f90082d

2 files changed

Lines changed: 114 additions & 5 deletions

File tree

‎include/gl/conversion.hpp‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ struct swap_impl_tag<graph<graph_traits<Dir, VP, EP, OldImplTag, IdType>>, NewIm
5454
};
5555

5656
/// @ingroup GL GL-Traits
57-
/// @brief Alias template for easier usage of the `swap_impl_tag` trait to resolve the swapped type directly.
57+
/// @brief Alias template for easier usage of the @ref gl::traits::swap_impl_tag "swap_impl_tag" trait to resolve the swapped type directly.
5858
/// ### See Also:
5959
/// - @ref gl::to "to" : For the function that utilizes this trait to perform graph conversions between different implementations.
6060
template <typename GT, traits::c_graph_impl_tag NewImplTag>
@@ -162,13 +162,18 @@ struct to_impl<impl::matrix_t, impl::flat_matrix_t> {
162162
/// @ingroup GL GL-Core
163163
/// @headerfile gl/conversion.hpp
164164
/// @brief Converts a graph from one implementation model to another.
165+
///
166+
/// This function efficiently transforms a graph's underlying memory representation (e.g., from a standard adjacency list to a flattened adjacency list) while preserving its exact topology, properties, and identifiers.
167+
///
165168
/// ### Template Parameters
166169
/// | Parameter | Description | Constraints |
167170
/// | :------------ | :---------- | :---------- |
168171
/// | TargetImplTag | The implementation tag of the desired target representation (e.g., `gl::impl::flat_list_t`) | [**c_graph_impl_tag**](gl_concepts.md#gl-traits-c-graph-impl-tag) |
169172
/// | Graph | The type of the source graph, which will be automatically deduced from the function argument. | [**c_graph**](gl_concepts.md#gl-traits-c-graph) |
173+
///
170174
/// @param source The graph to convert. After the operation it will be left in a valid, empty state.
171-
/// @return A new graph containing the moved data, structured according to TargetImplTag.
175+
/// @return A new graph containing the moved data, structured according to `TargetImplTag`.
176+
///
172177
/// ### See Also
173178
/// - @ref gl::traits::swap_impl_tag "swap_impl_tag" : For the trait used to resolve the target graph type with the swapped implementation tag.
174179
template <traits::c_graph_impl_tag TargetImplTag, traits::c_graph Graph>

‎include/hgl/conversion.hpp‎

Lines changed: 107 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl).
33
// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
44

5+
/// @file hgl/conversion.hpp
6+
/// @brief Defines utilities for hypergraph representation model conversion and projection into standard graphs.
7+
58
#pragma once
69

710
#include "gl/attributes/force_inline.hpp"
@@ -20,10 +23,16 @@ namespace hgl {
2023

2124
namespace traits {
2225

26+
/// @ingroup HGL-Traits
27+
/// @brief Utility trait type used to swap the implementation tag of a hypergraph traits or hypergraph type.
28+
/// ### See Also:
29+
/// - @ref hgl::to "to" : For the function that utilizes this trait to perform hypergraph conversions between different implementations.
2330
template <typename HT, traits::c_hypergraph_impl_tag NewImplTag>
2431
requires c_hypergraph<HT> or c_instantiation_of<HT, hypergraph_traits>
2532
struct swap_impl_tag;
2633

34+
/// @ingroup HGL-Traits
35+
/// @brief Specialization of @ref hgl::traits::swap_impl_tag "swap_impl_tag" for the @ref hgl::hypergraph_traits "hypergraph_traits" type.
2736
template <
2837
traits::c_hypergraph_directional_tag Dir,
2938
traits::c_properties VP,
@@ -34,6 +43,8 @@ struct swap_impl_tag<hypergraph_traits<Dir, VP, EP, OldImplTag>, NewImplTag> {
3443
using type = hypergraph_traits<Dir, VP, EP, NewImplTag>;
3544
};
3645

46+
/// @ingroup HGL-Traits
47+
/// @brief Specialization of @ref hgl::traits::swap_impl_tag "swap_impl_tag" for the @ref hgl::hypergraph "hypergraph" type.
3748
template <
3849
traits::c_hypergraph_directional_tag Dir,
3950
traits::c_properties VP,
@@ -44,6 +55,10 @@ struct swap_impl_tag<hypergraph<hypergraph_traits<Dir, VP, EP, OldImplTag>>, New
4455
using type = hypergraph<hypergraph_traits<Dir, VP, EP, NewImplTag>>;
4556
};
4657

58+
/// @ingroup HGL-Traits
59+
/// @brief Alias template for easier usage of the @ref hl::traits::swap_impl_tag "swap_impl_tag" trait to resolve the swapped type directly.
60+
/// ### See Also:
61+
/// - @ref hgl::to "to" : For the function that utilizes this trait to perform hypergraph conversions between different implementations.
4762
template <typename HT, traits::c_hypergraph_impl_tag NewImplTag>
4863
requires c_hypergraph<HT> or c_instantiation_of<HT, hypergraph_traits>
4964
using swap_impl_tag_t = typename swap_impl_tag<HT, NewImplTag>::type;
@@ -201,11 +216,22 @@ struct to_impl<impl::list_t<LayoutTag>, impl::flat_list_t<LayoutTag>> {
201216

202217
} // namespace detail
203218

219+
/// @ingroup HGL-Core
204220
/// @brief Converts a hypergraph from one implementation model to another.
205-
/// @tparam TargetImplTag The desired implementation tag (e.g., gl::impl::flat_list_t)
206-
/// @tparam Hypergraph The automatically deduced type of the source hypergraph
221+
///
222+
/// This function efficiently transforms a hypergraph's underlying memory representation (e.g., from a standard incidence list to a flattened incidence list) while preserving its exact topology, properties, and identifiers.
223+
///
224+
/// ### Template Parameters
225+
/// | Parameter | Description | Constraint |
226+
/// | :-------- | :---------- | :--------- |
227+
/// | TargetImplTag | The implementation tag of the desired target representation (e.g., `hgl::impl::flat_list_t`). | [**c_hypergraph_impl_tag**](hgl_concepts.md#hgl-traits-c-hypergraph-impl-tag) |
228+
/// | Hypergraph | The type of the source hypergraph, which will be automatically deduced from the function argument. | [**c_hypergraph**](hgl_concepts.md#hgl-traits-c-hypergraph) |
229+
///
207230
/// @param source The hypergraph to convert. After the operation it will be left in a valid, empty state.
208-
/// @return A new hypergraph containing the moved data, structured according to TargetImplTag.
231+
/// @return A new hypergraph containing the moved data, structured according to `TargetImplTag`.
232+
///
233+
/// ### See Also
234+
/// - @ref hgl::traits::swap_impl_tag "swap_impl_tag" : For the trait used to resolve the target hypergraph type with the swapped implementation tag.
209235
template <traits::c_hypergraph_impl_tag TargetImplTag, traits::c_hypergraph Hypergraph>
210236
[[nodiscard]] auto to(Hypergraph&& source) {
211237
using source_traits = typename Hypergraph::traits_type;
@@ -229,6 +255,23 @@ template <traits::c_hypergraph_impl_tag TargetImplTag, traits::c_hypergraph Hype
229255

230256
// --- Hypergraph to Hypergraph Conversion ---
231257

258+
/// @ingroup HGL-Core
259+
/// @brief Computes the projection (clique expansion) of an *undirected* hypergraph.
260+
///
261+
/// Projects the hypergraph onto a standard undirected graph. Each hyperedge in the hypergraph is expanded
262+
/// into a clique (a fully connected subgraph) connecting all of its incident vertices in the resulting graph.
263+
/// Duplicate edges generated by multiple hyperedges overlapping on the same vertices are collapsed into a single edge.
264+
///
265+
/// > [!NOTE] Performance for Flat List Graphs
266+
/// >
267+
/// > If the requested target graph `G` satisfies [**c_flat_list_graph**](gl_concepts.md#gl-traits-c-flat-list-graph),
268+
/// > an optimized overload is automatically selected. It internally constructs a standard adjacency list graph
269+
/// > first, and then utilizes the @ref gl::to conversion to flatten it. This is significantly faster than
270+
/// > inserting edges one-by-one into a flat representation.
271+
///
272+
/// @tparam G The target standard graph type to construct. Must satisfy [**c_undirected_graph**](gl_concepts.md#gl-traits-c-undirected-graph).
273+
/// @param h The source undirected hypergraph.
274+
/// @return A standard undirected graph representing the projection.
232275
template <gl::traits::c_undirected_graph G>
233276
[[nodiscard]] G projection(const traits::c_undirected_hypergraph auto& h) {
234277
using edge_vertices = homogeneous_pair<typename G::id_type>;
@@ -261,6 +304,23 @@ requires std::same_as<typename G::traits_type::implementation_tag, gl::impl::fla
261304
return gl::to<gl::impl::flat_list_t>(projection<list_graph>(h));
262305
}
263306

307+
/// @ingroup HGL-Core
308+
/// @brief Computes the projection of a *BF-directed* hypergraph.
309+
///
310+
/// Projects the hypergraph onto a standard directed graph. For each hyperedge, directed edges are created
311+
/// from every vertex in the hyperedge's tail (source) to every vertex in its head (destination).
312+
/// Duplicate edges generated by multiple hyperedges overlapping on the same vertices are collapsed into a single edge.
313+
///
314+
/// > [!NOTE] Performance for Flat List Graphs
315+
/// >
316+
/// > If the requested target graph `G` satisfies [**c_flat_list_graph**](gl_concepts.md#gl-traits-c-flat-list-graph),
317+
/// > an optimized overload is automatically selected. It internally constructs a standard adjacency list graph
318+
/// > first, and then utilizes the @ref gl::to "to" conversion to flatten it. This is significantly faster than
319+
/// > inserting edges one-by-one into a flat representation.
320+
///
321+
/// @tparam G The target standard graph type to construct. Must satisfy [**c_directed_graph**](gl_concepts.md#gl-traits-c-directed-graph).
322+
/// @param h The source bf-directed hypergraph.
323+
/// @return A standard directed graph representing the projection.
264324
template <gl::traits::c_directed_graph G>
265325
[[nodiscard]] G projection(const traits::c_bf_directed_hypergraph auto& h) {
266326
using edge_vertices = homogeneous_pair<typename G::id_type>;
@@ -292,6 +352,28 @@ requires std::same_as<typename G::traits_type::implementation_tag, gl::impl::fla
292352
return gl::to<gl::impl::flat_list_t>(projection<list_graph>(h));
293353
}
294354

355+
/// @ingroup HGL-Core
356+
/// @brief Computes the bipartite incidence graph representation of an *undirected* hypergraph.
357+
///
358+
/// Converts the hypergraph into a standard bipartite graph where both the original vertices and the
359+
/// original hyperedges are represented as standard graph vertices. Undirected edges are created between
360+
/// a vertex node and a hyperedge node if they are incident.
361+
///
362+
/// > [!NOTE] ID Shifting
363+
/// >
364+
/// > To ensure uniqueness in the resulting graph, the IDs of the hyperedge nodes are shifted by `h.n_vertices()`.
365+
/// > For example, hyperedge ID `0` becomes vertex ID `h.n_vertices() + 0` in the resulting graph.
366+
///
367+
/// > [!NOTE] Performance for Flat List Graphs
368+
/// >
369+
/// > If the requested target graph `G` satisfies [**c_flat_list_graph**](gl_concepts.md#gl-traits-c-flat-list-graph),
370+
/// > an optimized overload is automatically selected. It internally constructs a standard adjacency list graph
371+
/// > first, and then utilizes the @ref gl::to conversion to flatten it. This is significantly faster than
372+
/// > inserting edges one-by-one into a flat representation.
373+
///
374+
/// @tparam G The target standard graph type to construct. Must satisfy [**c_undirected_graph**](gl_concepts.md#gl-traits-c-undirected-graph).
375+
/// @param h The source undirected hypergraph.
376+
/// @return A standard undirected bipartite graph representing the incidence structure.
295377
template <gl::traits::c_undirected_graph G>
296378
[[nodiscard]] G incidence_graph(const traits::c_undirected_hypergraph auto& h) {
297379
using g_id_type = typename G::id_type;
@@ -319,6 +401,28 @@ requires std::same_as<typename G::traits_type::implementation_tag, gl::impl::fla
319401
return gl::to<gl::impl::flat_list_t>(incidence_graph<list_graph>(h));
320402
}
321403

404+
/// @ingroup HGL-Core
405+
/// @brief Computes the bipartite incidence graph representation of a *BF-directed* hypergraph.
406+
///
407+
/// Converts the hypergraph into a standard bipartite directed graph. Directed edges are created
408+
/// from original *tail* vertex nodes to the hyperedge nodes, and from the hyperedge nodes to the
409+
/// original *head* vertex nodes.
410+
///
411+
/// > [!NOTE] ID Shifting
412+
/// >
413+
/// > To ensure uniqueness in the resulting graph, the IDs of the hyperedge nodes are shifted by `h.n_vertices()`.
414+
/// > For example, hyperedge ID `0` becomes vertex ID `h.n_vertices() + 0` in the resulting graph.
415+
///
416+
/// > [!NOTE] Performance for Flat List Graphs
417+
/// >
418+
/// > If the requested target graph `G` satisfies [**c_flat_list_graph**](gl_concepts.md#gl-traits-c-flat-list-graph),
419+
/// > an optimized overload is automatically selected. It internally constructs a standard adjacency list graph
420+
/// > first, and then utilizes the @ref gl::to conversion to flatten it. This is significantly faster than
421+
/// > inserting edges one-by-one into a flat representation.
422+
///
423+
/// @tparam G The target standard graph type to construct. Must satisfy [**c_directed_graph**](gl_concepts.md#gl-traits-c-directed-graph).
424+
/// @param h The source bf-directed hypergraph.
425+
/// @return A standard directed bipartite graph representing the incidence structure.
322426
template <gl::traits::c_directed_graph G>
323427
[[nodiscard]] G incidence_graph(const traits::c_bf_directed_hypergraph auto& h) {
324428
using g_id_type = typename G::id_type;

0 commit comments

Comments
 (0)