Skip to content

Commit b6b2ec5

Browse files
SpectraL519SpectraL519
committed
structural tags + hypergraph traits docs
1 parent 46be8f9 commit b6b2ec5

4 files changed

Lines changed: 231 additions & 0 deletions

File tree

‎include/hgl/decl/impl_tags.hpp‎

Lines changed: 34 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 hgl/decl/impl_tags.hpp
6+
/// @brief Forward declares implementation tags for different hypergraph representations.
7+
58
#pragma once
69

710
#include "hgl/impl/layout_tags.hpp"
@@ -35,26 +38,57 @@ struct flat_matrix_t;
3538

3639
namespace traits {
3740

41+
/// @ingroup HGL-Traits
42+
/// @brief Validates if a type is an instantiation of the @ref hgl::impl::list_t "impl::list_t" tag.
43+
/// @tparam T The type to evaluate against the concept.
3844
template <typename T>
3945
concept c_hypergraph_list_impl = c_instantiation_of<T, impl::list_t>;
4046

47+
/// @ingroup HGL-Traits
48+
/// @brief Validates if a type is an instantiation of the @ref hgl::impl::flat_list_t "impl::flat_list_t" tag.
49+
/// @tparam T The type to evaluate against the concept.
4150
template <typename T>
4251
concept c_hypergraph_flat_list_impl = c_instantiation_of<T, impl::flat_list_t>;
4352

53+
/// @ingroup HGL-Traits
54+
/// @brief Validates if a type is a valid incidence list implementation tag (either standard or flattened).
55+
/// @tparam T The type to evaluate against the concept.
4456
template <typename T>
4557
concept c_hypergraph_incidence_list_impl =
4658
c_hypergraph_list_impl<T> or c_hypergraph_flat_list_impl<T>;
4759

60+
/// @ingroup HGL-Traits
61+
/// @brief Validates if a type is an instantiation of the @ref hgl::impl::matrix_t "impl::matrix_t" tag.
62+
/// @tparam T The type to evaluate against the concept.
4863
template <typename T>
4964
concept c_hypergraph_matrix_impl = c_instantiation_of<T, impl::matrix_t>;
5065

66+
/// @ingroup HGL-Traits
67+
/// @brief Validates if a type is an instantiation of the @ref hgl::impl::flat_matrix_t "impl::flat_matrix_t" tag.
68+
/// @tparam T The type to evaluate against the concept.
5169
template <typename T>
5270
concept c_hypergraph_flat_matrix_impl = c_instantiation_of<T, impl::flat_matrix_t>;
5371

72+
/// @ingroup HGL-Traits
73+
/// @brief Validates if a type is a valid incidence matrix implementation tag (either standard or flattened).
74+
/// @tparam T The type to evaluate against the concept.
5475
template <typename T>
5576
concept c_hypergraph_incidence_matrix_impl =
5677
c_hypergraph_matrix_impl<T> or c_hypergraph_flat_matrix_impl<T>;
5778

79+
/// @ingroup HGL-Traits
80+
/// @brief Validates if a type is one of the defined hypergraph implementation tags.
81+
///
82+
/// This concept is used to constrain template parameters that are expected to be
83+
/// specific hypergraph implementation tags, ensuring type safety and clear intent in template usage.
84+
///
85+
/// The valid tags include:
86+
/// - @ref hgl::impl::list_t "impl::list_t": Represents a standard incidence list implementation.
87+
/// - @ref hgl::impl::flat_list_t "impl::flat_list_t": Represents a flattened incidence list implementation.
88+
/// - @ref hgl::impl::matrix_t "impl::matrix_t": Represents a standard incidence matrix implementation.
89+
/// - @ref hgl::impl::flat_matrix_t "impl::flat_matrix_t": Represents a flattened incidence matrix implementation.
90+
///
91+
/// @tparam T The type to evaluate against the concept.
5892
template <typename T>
5993
concept c_hypergraph_impl_tag =
6094
c_hypergraph_incidence_list_impl<T> or c_hypergraph_incidence_matrix_impl<T>;

‎include/hgl/hypergraph_traits.hpp‎

Lines changed: 111 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 hgl/hypergraph_traits.hpp
6+
/// @brief Defines the primary hypergraph traits structure and related type aliases for different configurations.
7+
58
#pragma once
69

710
#include "gl/types/core.hpp"
@@ -12,24 +15,57 @@
1215

1316
namespace hgl {
1417

18+
/// @ingroup HGL-Core
19+
/// @brief Primary hypergraph traits structure that encapsulates all necessary type information for hypergraph implementations.
20+
///
21+
/// This structure serves as the central point for defining the properties and types associated with a hypergraph,
22+
/// including directionality, element properties, as well as implementation and identifier types. It provides a clean,
23+
/// extensible way to customize hypergraph behavior.
24+
///
25+
/// ### Template Parameters
26+
/// | Parameter | Description | Default | Constraint |
27+
/// | :-------- | :---------- | :------ | :--------- |
28+
/// | DirectionalTag | Specifies whether the hypergraph is undirected or bf_directed. | @ref hgl::undirected_t "undirected_t" | [**c_hypergraph_directional_tag**](hgl_concepts.md#hgl-traits-c-hypergraph-directional-tag) |
29+
/// | VertexProperties | The type of properties attached to each vertex. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
30+
/// | HyperedgeProperties | The type of properties attached to each hyperedge. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
31+
/// | ImplTag | Specifies the internal container representation for incidence. | @ref hgl::impl::list_t "impl::list_t<>" | [**c_hypergraph_impl_tag**](hgl_concepts.md#hgl-traits-c-hypergraph-impl-tag) |
1532
template <
1633
traits::c_hypergraph_directional_tag DirectionalTag = undirected_t,
1734
traits::c_properties VertexProperties = empty_properties,
1835
traits::c_properties HyperedgeProperties = empty_properties,
1936
traits::c_hypergraph_impl_tag ImplTag = impl::list_t<>>
2037
struct hypergraph_traits {
38+
/// @brief The directional tag indicating the hypergraph's orientation.
2139
using directional_tag = DirectionalTag;
40+
/// @brief The implementation tag defining the internal storage mechanism.
2241
using implementation_tag = ImplTag;
42+
/// @brief The layout tag governing major/minor element ordering.
2343
using layout_tag = typename implementation_tag::layout_tag;
44+
/// @brief The integer type used for element identifiers.
2445
using id_type = typename implementation_tag::id_type;
2546

47+
/// @brief The fully resolved type representing a vertex descriptor.
2648
using vertex_type = vertex_descriptor<VertexProperties, id_type>;
49+
/// @brief The property payload type associated with vertices.
2750
using vertex_properties_type = typename vertex_type::properties_type;
2851

52+
/// @brief The fully resolved type representing a hyperedge descriptor.
2953
using hyperedge_type = hyperedge_descriptor<HyperedgeProperties, id_type>;
54+
/// @brief The property payload type associated with hyperedges.
3055
using hyperedge_properties_type = typename hyperedge_type::properties_type;
3156
};
3257

58+
/// @ingroup HGL-Core
59+
/// @brief Convenience alias for `hypergraph_traits` using a standard incidence list implementation.
60+
///
61+
/// ### Template Parameters
62+
/// | Parameter | Description | Default | Constraint |
63+
/// | :-------- | :---------- | :------ | :--------- |
64+
/// | LayoutTag | Memory orientation for the list structures. | @ref hgl::impl::bidirectional_t "bidirectional_t" | [**c_hypergraph_layout_tag**](hgl_concepts.md#hgl-traits-c-hypergraph-layout-tag) |
65+
/// | DirectionalTag | Specifies whether the hypergraph is undirected or bf_directed. | @ref hgl::undirected_t "undirected_t" | [**c_hypergraph_directional_tag**](hgl_concepts.md#hgl-traits-c-hypergraph-directional-tag) |
66+
/// | VertexProperties | The type of properties attached to each vertex. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
67+
/// | HyperedgeProperties | The type of properties attached to each hyperedge. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
68+
/// | IdType | The integer type used for element identifiers. | @ref gl::default_id_type "default_id_type" | [**c_id_type**](gl_concepts.md#gl-traits-c-id-type) |
3369
template <
3470
traits::c_hypergraph_layout_tag LayoutTag = impl::bidirectional_t,
3571
traits::c_hypergraph_directional_tag DirectionalTag = undirected_t,
@@ -42,6 +78,17 @@ using list_hypergraph_traits = hypergraph_traits<
4278
HyperedgeProperties,
4379
impl::list_t<LayoutTag, IdType>>;
4480

81+
/// @ingroup HGL-Core
82+
/// @brief Convenience alias for `hypergraph_traits` using a flattened incidence list implementation.
83+
///
84+
/// ### Template Parameters
85+
/// | Parameter | Description | Default | Constraint |
86+
/// | :-------- | :---------- | :------ | :--------- |
87+
/// | LayoutTag | Memory orientation for the flat list structures. | @ref hgl::impl::bidirectional_t "bidirectional_t" | [**c_hypergraph_layout_tag**](hgl_concepts.md#hgl-traits-c-hypergraph-layout-tag) |
88+
/// | DirectionalTag | Specifies whether the hypergraph is undirected or bf_directed. | @ref hgl::undirected_t "undirected_t" | [**c_hypergraph_directional_tag**](hgl_concepts.md#hgl-traits-c-hypergraph-directional-tag) |
89+
/// | VertexProperties | The type of properties attached to each vertex. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
90+
/// | HyperedgeProperties | The type of properties attached to each hyperedge. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
91+
/// | IdType | The integer type used for element identifiers. | @ref gl::default_id_type "default_id_type" | [**c_id_type**](gl_concepts.md#gl-traits-c-id-type) |
4592
template <
4693
traits::c_hypergraph_layout_tag LayoutTag = impl::bidirectional_t,
4794
traits::c_hypergraph_directional_tag DirectionalTag = undirected_t,
@@ -54,6 +101,17 @@ using flat_list_hypergraph_traits = hypergraph_traits<
54101
HyperedgeProperties,
55102
impl::flat_list_t<LayoutTag, IdType>>;
56103

104+
/// @ingroup HGL-Core
105+
/// @brief Convenience alias for `hypergraph_traits` using a standard incidence matrix implementation.
106+
///
107+
/// ### Template Parameters
108+
/// | Parameter | Description | Default | Constraint |
109+
/// | :-------- | :---------- | :------ | :--------- |
110+
/// | LayoutTag | Memory orientation (must be asymmetric). | @ref hgl::impl::hyperedge_major_t "hyperedge_major_t" | [**c_hypergraph_asymmetric_layout_tag**](hgl_concepts.md#hgl-traits-c-hypergraph-asymmetric-layout-tag) |
111+
/// | DirectionalTag | Specifies whether the hypergraph is undirected or bf_directed. | @ref hgl::undirected_t "undirected_t" | [**c_hypergraph_directional_tag**](hgl_concepts.md#hgl-traits-c-hypergraph-directional-tag) |
112+
/// | VertexProperties | The type of properties attached to each vertex. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
113+
/// | HyperedgeProperties | The type of properties attached to each hyperedge. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
114+
/// | IdType | The integer type used for element identifiers. | @ref gl::default_id_type "default_id_type" | [**c_id_type**](gl_concepts.md#gl-traits-c-id-type) |
57115
template <
58116
traits::c_hypergraph_asymmetric_layout_tag LayoutTag = impl::hyperedge_major_t,
59117
traits::c_hypergraph_directional_tag DirectionalTag = undirected_t,
@@ -66,6 +124,17 @@ using matrix_hypergraph_traits = hypergraph_traits<
66124
HyperedgeProperties,
67125
impl::matrix_t<LayoutTag, IdType>>;
68126

127+
/// @ingroup HGL-Core
128+
/// @brief Convenience alias for `hypergraph_traits` using a flattened incidence matrix implementation.
129+
///
130+
/// ### Template Parameters
131+
/// | Parameter | Description | Default | Constraint |
132+
/// | :-------- | :---------- | :------ | :--------- |
133+
/// | LayoutTag | Memory orientation (must be asymmetric). | @ref hgl::impl::hyperedge_major_t "hyperedge_major_t" | [**c_hypergraph_asymmetric_layout_tag**](hgl_concepts.md#hgl-traits-c-hypergraph-asymmetric-layout-tag) |
134+
/// | DirectionalTag | Specifies whether the hypergraph is undirected or bf_directed. | @ref hgl::undirected_t "undirected_t" | [**c_hypergraph_directional_tag**](hgl_concepts.md#hgl-traits-c-hypergraph-directional-tag) |
135+
/// | VertexProperties | The type of properties attached to each vertex. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
136+
/// | HyperedgeProperties | The type of properties attached to each hyperedge. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
137+
/// | IdType | The integer type used for element identifiers. | @ref gl::default_id_type "default_id_type" | [**c_id_type**](gl_concepts.md#gl-traits-c-id-type) |
69138
template <
70139
traits::c_hypergraph_asymmetric_layout_tag LayoutTag = impl::hyperedge_major_t,
71140
traits::c_hypergraph_directional_tag DirectionalTag = undirected_t,
@@ -78,13 +147,31 @@ using flat_matrix_hypergraph_traits = hypergraph_traits<
78147
HyperedgeProperties,
79148
impl::flat_matrix_t<LayoutTag, IdType>>;
80149

150+
/// @ingroup HGL-Core
151+
/// @brief Type alias for undirected hypergraph traits with configurable properties and implementation.
152+
///
153+
/// ### Template Parameters
154+
/// | Parameter | Description | Default | Constraint |
155+
/// | :-------- | :---------- | :------ | :--------- |
156+
/// | VertexProperties | The type of properties attached to each vertex. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
157+
/// | HyperedgeProperties | The type of properties attached to each hyperedge. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
158+
/// | ImplTag | Specifies the internal container representation for incidence. | @ref hgl::impl::list_t "impl::list_t<>" | [**c_hypergraph_impl_tag**](hgl_concepts.md#hgl-traits-c-hypergraph-impl-tag) |
81159
template <
82160
traits::c_properties VertexProperties = empty_properties,
83161
traits::c_properties HyperedgeProperties = empty_properties,
84162
traits::c_hypergraph_impl_tag ImplTag = impl::list_t<>>
85163
using undirected_hypergraph_traits =
86164
hypergraph_traits<undirected_t, VertexProperties, HyperedgeProperties, ImplTag>;
87165

166+
/// @ingroup HGL-Core
167+
/// @brief Type alias for bf-directed hypergraph traits with configurable properties and implementation.
168+
///
169+
/// ### Template Parameters
170+
/// | Parameter | Description | Default | Constraint |
171+
/// | :-------- | :---------- | :------ | :--------- |
172+
/// | VertexProperties | The type of properties attached to each vertex. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
173+
/// | HyperedgeProperties | The type of properties attached to each hyperedge. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) |
174+
/// | ImplTag | Specifies the internal container representation for incidence. | @ref hgl::impl::list_t "impl::list_t<>" | [**c_hypergraph_impl_tag**](hgl_concepts.md#hgl-traits-c-hypergraph-impl-tag) |
88175
template <
89176
traits::c_properties VertexProperties = empty_properties,
90177
traits::c_properties HyperedgeProperties = empty_properties,
@@ -94,39 +181,63 @@ using bf_directed_hypergraph_traits =
94181

95182
namespace traits {
96183

184+
/// @ingroup HGL-Traits
185+
/// @brief Validates if a type is an instantiation of @ref hgl::hypergraph_traits "hypergraph_traits" with a standard incidence list implementation.
186+
/// @tparam TraitsType The type to evaluate against the concept.
97187
template <typename TraitsType>
98188
concept c_list_hypergraph_traits =
99189
c_instantiation_of<TraitsType, hypergraph_traits>
100190
and c_hypergraph_list_impl<typename TraitsType::implementation_tag>;
101191

192+
/// @ingroup HGL-Traits
193+
/// @brief Validates if a type is an instantiation of @ref hgl::hypergraph_traits "hypergraph_traits" with a flattened incidence list implementation.
194+
/// @tparam TraitsType The type to evaluate against the concept.
102195
template <typename TraitsType>
103196
concept c_flat_list_hypergraph_traits =
104197
c_instantiation_of<TraitsType, hypergraph_traits>
105198
and c_hypergraph_flat_list_impl<typename TraitsType::implementation_tag>;
106199

200+
/// @ingroup HGL-Traits
201+
/// @brief Validates if a type is an instantiation of @ref hgl::hypergraph_traits "hypergraph_traits" with an incidence list implementation (either standard or flattened).
202+
/// @tparam TraitsType The type to evaluate against the concept.
107203
template <typename TraitsType>
108204
concept c_incidence_list_hypergraph_traits =
109205
c_list_hypergraph_traits<TraitsType> or c_flat_list_hypergraph_traits<TraitsType>;
110206

207+
/// @ingroup HGL-Traits
208+
/// @brief Validates if a type is an instantiation of @ref hgl::hypergraph_traits "hypergraph_traits" with a standard incidence matrix implementation.
209+
/// @tparam TraitsType The type to evaluate against the concept.
111210
template <typename TraitsType>
112211
concept c_matrix_hypergraph_traits =
113212
c_instantiation_of<TraitsType, hypergraph_traits>
114213
and c_hypergraph_matrix_impl<typename TraitsType::implementation_tag>;
115214

215+
/// @ingroup HGL-Traits
216+
/// @brief Validates if a type is an instantiation of @ref hgl::hypergraph_traits "hypergraph_traits" with a flattened incidence matrix implementation.
217+
/// @tparam TraitsType The type to evaluate against the concept.
116218
template <typename TraitsType>
117219
concept c_flat_matrix_hypergraph_traits =
118220
c_instantiation_of<TraitsType, hypergraph_traits>
119221
and c_hypergraph_flat_matrix_impl<typename TraitsType::implementation_tag>;
120222

223+
/// @ingroup HGL-Traits
224+
/// @brief Validates if a type is an instantiation of @ref hgl::hypergraph_traits "hypergraph_traits" with an incidence matrix implementation (either standard or flattened).
225+
/// @tparam TraitsType The type to evaluate against the concept.
121226
template <typename TraitsType>
122227
concept c_incidence_matrix_hypergraph_traits =
123228
c_matrix_hypergraph_traits<TraitsType> or c_flat_matrix_hypergraph_traits<TraitsType>;
124229

230+
/// @ingroup HGL-Traits
231+
/// @brief Validates if a type is an instantiation of @ref hgl::hypergraph_traits "hypergraph_traits" with an undirected configuration.
232+
/// @tparam TraitsType The type to evaluate against the concept.
125233
template <typename TraitsType>
126234
concept c_undirected_hypergraph_traits =
127235
c_instantiation_of<TraitsType, hypergraph_traits>
128236
and std::same_as<typename TraitsType::directional_tag, undirected_t>;
129237

238+
/// @ingroup HGL-Traits
239+
/// @brief Validates if a type is an instantiation of @ref hgl::hypergraph_traits "hypergraph_traits" with a bf_directed configuration.
240+
/// @tparam TraitsType The type to evaluate against the concept.
130241
template <typename TraitsType>
131242
concept c_bf_directed_hypergraph_traits =
132243
c_instantiation_of<TraitsType, hypergraph_traits>

0 commit comments

Comments
 (0)