Skip to content

Commit 088291e

Browse files
SpectraL519SpectraL519
committed
topo docs
1 parent a84bb89 commit 088291e

5 files changed

Lines changed: 169 additions & 3 deletions

File tree

‎include/gl/topology/binary_tree.hpp‎

Lines changed: 45 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 gl/topology/binary_tree.hpp
6+
/// @brief Generators for regular and bidirectional binary tree topologies.
7+
58
#pragma once
69

710
#include "gl/constants.hpp"
@@ -15,7 +18,7 @@ namespace gl::topology {
1518

1619
namespace detail {
1720

18-
[[nodiscard]] gl_attr_force_inline auto get_binary_target_ids(traits::c_id_type auto source_id) {
21+
[[nodiscard]] gl_attr_force_inline auto get_bintree_target_ids(traits::c_id_type auto source_id) {
1922
using id_type = std::decay_t<decltype(source_id)>;
2023
return std::make_pair(
2124
static_cast<id_type>(2) * source_id + static_cast<id_type>(1),
@@ -27,6 +30,26 @@ constexpr size_type min_non_trivial_bin_tree_depth = 2uz;
2730

2831
} // namespace detail
2932

33+
/// @ingroup GL GL-Topology
34+
/// @brief Generates a regular (regular) binary tree of a specified depth.
35+
///
36+
/// A regular binary tree is a tree where all internal vertices have exactly two children
37+
/// and all leaf vertices are at the same depth. For a given depth \f$d\f$, the graph
38+
/// will contain exactly \f$2^d - 1\f$ vertices.
39+
///
40+
/// If the requested `GraphType` is directed, edges are created pointing from the parent
41+
/// vertex to its children.
42+
///
43+
/// > [!NOTE] Performance for Flat List Graphs
44+
/// >
45+
/// > If the requested `GraphType` satisfies [**c_flat_list_graph**](gl_concepts.md#gl-traits-c-flat-list-graph),
46+
/// > an optimized overload is automatically selected. It internally constructs a standard adjacency list graph
47+
/// > first, and then utilizes the @ref gl::to "to" conversion to flatten it. This is significantly faster than
48+
/// > inserting edges one-by-one into a flat representation.
49+
///
50+
/// @tparam GraphType The target graph type to generate.
51+
/// @param depth The depth (number of levels) of the binary tree. A depth of `1` yields a single root vertex.
52+
/// @return A newly constructed graph representing the regular binary tree.
3053
template <traits::c_graph GraphType>
3154
[[nodiscard]] GraphType regular_binary_tree(size_type depth) {
3255
using id_type = typename GraphType::id_type;
@@ -44,7 +67,7 @@ template <traits::c_graph GraphType>
4467
const auto n_source_vertices = n_vertices - util::upow(base, i_end);
4568

4669
for (id_type source_id = initial_id; source_id < n_source_vertices; ++source_id) {
47-
const auto target_ids = detail::get_binary_target_ids(source_id);
70+
const auto target_ids = detail::get_bintree_target_ids(source_id);
4871
graph.add_edges_from(
4972
source_id, std::initializer_list<id_type>{target_ids.first, target_ids.second}
5073
);
@@ -59,6 +82,25 @@ template <traits::c_flat_list_graph GraphType>
5982
return to<impl::flat_list_t>(regular_binary_tree<base_graph_type>(depth));
6083
}
6184

85+
/// @ingroup GL GL-Topology
86+
/// @brief Generates a regular binary tree with bidirectional edges.
87+
///
88+
/// For directed graphs, this function ensures that for every parent-to-child edge,
89+
/// a reciprocal child-to-parent edge is also created.
90+
///
91+
/// For undirected graphs, this function simply falls back to @ref gl::topology::regular_binary_tree "regular_binary_tree",
92+
/// as undirected edges are inherently bidirectional.
93+
///
94+
/// > [!NOTE] Performance for Flat List Graphs
95+
/// >
96+
/// > If the requested `GraphType` satisfies [**c_flat_list_graph**](gl_concepts.md#gl-traits-c-flat-list-graph),
97+
/// > an optimized overload is automatically selected. It internally constructs a standard adjacency list graph
98+
/// > first, and then utilizes the @ref gl::to "to" conversion to flatten it. This is significantly faster than
99+
/// > inserting edges one-by-one into a flat representation.
100+
///
101+
/// @tparam GraphType The target graph type to generate.
102+
/// @param depth The depth of the binary tree.
103+
/// @return A newly constructed graph representing the bidirectional binary tree.
62104
template <traits::c_graph GraphType>
63105
[[nodiscard]] GraphType bidirectional_regular_binary_tree(size_type depth) {
64106
if constexpr (traits::c_directed_graph<GraphType>) {
@@ -77,7 +119,7 @@ template <traits::c_graph GraphType>
77119
const auto n_source_vertices = n_vertices - util::upow(base, i_end);
78120

79121
for (id_type source_id = initial_id; source_id < n_source_vertices; ++source_id) {
80-
const auto target_ids = detail::get_binary_target_ids(source_id);
122+
const auto target_ids = detail::get_bintree_target_ids(source_id);
81123
graph.add_edges_from(
82124
source_id, std::initializer_list<id_type>{target_ids.first, target_ids.second}
83125
);

‎include/gl/topology/bipartite.hpp‎

Lines changed: 23 additions & 0 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 gl/topology/bipartite.hpp
6+
/// @brief Generators for complete bipartite (biclique) graph topologies.
7+
58
#pragma once
69

710
#include "gl/constants.hpp"
@@ -11,6 +14,26 @@
1114

1215
namespace gl::topology {
1316

17+
/// @ingroup GL GL-Topology
18+
/// @brief Generates a complete bipartite graph (biclique).
19+
///
20+
/// A complete bipartite graph is a graph whose vertices are partitioned into two disjoint
21+
/// sets, \f$A\f$ and \f$B\f$, such that every vertex in \f$A\f$ connects to every vertex in \f$B\f$.
22+
///
23+
/// If the requested `GraphType` is directed, this function generates reciprocal edges
24+
/// (from \f$A\f$ to \f$B\f$ and from \f$B\f$ to \f$A\f$) to mimic full undirected connectivity.
25+
///
26+
/// > [!NOTE] Performance for Flat List Graphs
27+
/// >
28+
/// > If the requested `GraphType` satisfies [**c_flat_list_graph**](gl_concepts.md#gl-traits-c-flat-list-graph),
29+
/// > an optimized overload is automatically selected. It internally constructs a standard adjacency list graph
30+
/// > first, and then utilizes the @ref gl::to "to" conversion to flatten it. This is significantly faster than
31+
/// > inserting edges one-by-one into a flat representation.
32+
///
33+
/// @tparam GraphType The target graph type to generate.
34+
/// @param n_vertices_a The number of vertices in partition \f$A\f$.
35+
/// @param n_vertices_b The number of vertices in partition \f$B\f$.
36+
/// @return A newly constructed graph representing the biclique.
1437
template <traits::c_graph GraphType>
1538
[[nodiscard]] GraphType biclique(size_type n_vertices_a, size_type n_vertices_b) {
1639
using id_type = typename GraphType::id_type;

‎include/gl/topology/clique.hpp‎

Lines changed: 21 additions & 0 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 gl/topology/clique.hpp
6+
/// @brief Generators for complete (clique) graph topologies.
7+
58
#pragma once
69

710
#include "gl/constants.hpp"
@@ -10,6 +13,24 @@
1013

1114
namespace gl::topology {
1215

16+
/// @ingroup GL GL-Topology
17+
/// @brief Generates a complete graph (clique).
18+
///
19+
/// A complete graph is a simple graph in which every pair of distinct vertices is connected by an edge.
20+
///
21+
/// If the requested `GraphType` is directed, this function generates fully bidirectional
22+
/// edges between every pair of vertices.
23+
///
24+
/// > [!NOTE] Performance for Flat List Graphs
25+
/// >
26+
/// > If the requested `GraphType` satisfies [**c_flat_list_graph**](gl_concepts.md#gl-traits-c-flat-list-graph),
27+
/// > an optimized overload is automatically selected. It internally constructs a standard adjacency list graph
28+
/// > first, and then utilizes the @ref gl::to "to" conversion to flatten it. This is significantly faster than
29+
/// > inserting edges one-by-one into a flat representation.
30+
///
31+
/// @tparam GraphType The target graph type to generate.
32+
/// @param n_vertices The total number of vertices in the clique.
33+
/// @return A newly constructed graph representing the clique.
1334
template <traits::c_graph GraphType>
1435
[[nodiscard]] GraphType clique(size_type n_vertices) {
1536
using id_type = typename GraphType::id_type;

‎include/gl/topology/cycle.hpp‎

Lines changed: 40 additions & 0 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 gl/topology/cycle.hpp
6+
/// @brief Generators for cycle (ring) graph topologies.
7+
58
#pragma once
69

710
#include "gl/constants.hpp"
@@ -10,6 +13,24 @@
1013

1114
namespace gl::topology {
1215

16+
/// @ingroup GL GL-Topology
17+
/// @brief Generates a regular cycle graph (ring topology).
18+
///
19+
/// A cycle graph consists of a single closed chain of vertices. Vertex \f$v_i\f$ is connected
20+
/// to vertex \f$v_{i+1}\f$, with the final vertex connecting back to vertex \f$v_0\f$.
21+
///
22+
/// For directed graphs, this creates a unidirectional loop.
23+
///
24+
/// > [!NOTE] Performance for Flat List Graphs
25+
/// >
26+
/// > If the requested `GraphType` satisfies [**c_flat_list_graph**](gl_concepts.md#gl-traits-c-flat-list-graph),
27+
/// > an optimized overload is automatically selected. It internally constructs a standard adjacency list graph
28+
/// > first, and then utilizes the @ref gl::to "to" conversion to flatten it. This is significantly faster than
29+
/// > inserting edges one-by-one into a flat representation.
30+
///
31+
/// @tparam GraphType The target graph type to generate.
32+
/// @param n_vertices The total number of vertices in the cycle.
33+
/// @return A newly constructed graph representing the cycle.
1334
template <traits::c_graph GraphType>
1435
[[nodiscard]] GraphType cycle(size_type n_vertices) {
1536
using id_type = typename GraphType::id_type;
@@ -28,6 +49,25 @@ template <traits::c_flat_list_graph GraphType>
2849
return to<impl::flat_list_t>(cycle<base_graph_type>(n_vertices));
2950
}
3051

52+
/// @ingroup GL GL-Topology
53+
/// @brief Generates a cycle graph with bidirectional edges.
54+
///
55+
/// For directed graphs, this function creates a reciprocal edge for every forward edge
56+
/// in the closed chain, forming a bidirectional ring.
57+
///
58+
/// For undirected graphs, this function simply falls back to @ref gl::topology::cycle "cycle",
59+
/// as undirected edges are inherently bidirectional.
60+
///
61+
/// > [!NOTE] Performance for Flat List Graphs
62+
/// >
63+
/// > If the requested `GraphType` satisfies [**c_flat_list_graph**](gl_concepts.md#gl-traits-c-flat-list-graph),
64+
/// > an optimized overload is automatically selected. It internally constructs a standard adjacency list graph
65+
/// > first, and then utilizes the @ref gl::to "to" conversion to flatten it. This is significantly faster than
66+
/// > inserting edges one-by-one into a flat representation.
67+
///
68+
/// @tparam GraphType The target graph type to generate.
69+
/// @param n_vertices The total number of vertices in the cycle.
70+
/// @return A newly constructed graph representing the bidirectional cycle.
3171
template <traits::c_graph GraphType>
3272
[[nodiscard]] GraphType bidirectional_cycle(size_type n_vertices) {
3373
if constexpr (traits::c_directed_graph<GraphType>) {

‎include/gl/topology/path.hpp‎

Lines changed: 40 additions & 0 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 gl/topology/path.hpp
6+
/// @brief Generators for path (linear) graph topologies.
7+
58
#pragma once
69

710
#include "gl/constants.hpp"
@@ -10,6 +13,24 @@
1013

1114
namespace gl::topology {
1215

16+
/// @ingroup GL GL-Topology
17+
/// @brief Generates a regular path graph (linear topology).
18+
///
19+
/// A path graph consists of a simple linear sequence of vertices. Vertex \f$v_i\f$ is connected
20+
/// to vertex \f$v_{i+1}\f$, terminating at the final vertex.
21+
///
22+
/// For directed graphs, this creates a one-way chain from the first to the last vertex.
23+
///
24+
/// > [!NOTE] Performance for Flat List Graphs
25+
/// >
26+
/// > If the requested `GraphType` satisfies [**c_flat_list_graph**](gl_concepts.md#gl-traits-c-flat-list-graph),
27+
/// > an optimized overload is automatically selected. It internally constructs a standard adjacency list graph
28+
/// > first, and then utilizes the @ref gl::to "to" conversion to flatten it. This is significantly faster than
29+
/// > inserting edges one-by-one into a flat representation.
30+
///
31+
/// @tparam GraphType The target graph type to generate.
32+
/// @param n_vertices The total number of vertices in the path.
33+
/// @return A newly constructed graph representing the linear path.
1334
template <traits::c_graph GraphType>
1435
[[nodiscard]] GraphType path(size_type n_vertices) {
1536
using id_type = typename GraphType::id_type;
@@ -28,6 +49,25 @@ template <traits::c_flat_list_graph GraphType>
2849
return to<impl::flat_list_t>(path<base_graph_type>(n_vertices));
2950
}
3051

52+
/// @ingroup GL GL-Topology
53+
/// @brief Generates a path graph with bidirectional edges.
54+
///
55+
/// For directed graphs, this function creates reciprocal edges along the linear sequence,
56+
/// allowing traversal in both directions.
57+
///
58+
/// For undirected graphs, this function simply falls back to @ref gl::topology::path "path",
59+
/// as undirected edges are inherently bidirectional.
60+
///
61+
/// > [!NOTE] Performance for Flat List Graphs
62+
/// >
63+
/// > If the requested `GraphType` satisfies [**c_flat_list_graph**](gl_concepts.md#gl-traits-c-flat-list-graph),
64+
/// > an optimized overload is automatically selected. It internally constructs a standard adjacency list graph
65+
/// > first, and then utilizes the @ref gl::to "to" conversion to flatten it. This is significantly faster than
66+
/// > inserting edges one-by-one into a flat representation.
67+
///
68+
/// @tparam GraphType The target graph type to generate.
69+
/// @param n_vertices The total number of vertices in the path.
70+
/// @return A newly constructed graph representing the bidirectional path.
3171
template <traits::c_graph GraphType>
3272
[[nodiscard]] GraphType bidirectional_path(size_type n_vertices) {
3373
if constexpr (traits::c_directed_graph<GraphType>) {

0 commit comments

Comments
 (0)