Skip to content

Commit a79c3e4

Browse files
kdeweesekdeweese
authored
Merge branch 'master' into algorithms/cc
2 parents 78a8e65 + 8b768da commit a79c3e4

File tree

85 files changed

+4717
-2259
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

85 files changed

+4717
-2259
lines changed

‎README.md

Lines changed: 73 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,25 @@
11
# Graph Library Proposal for the C++ Standard
22
[![codecov](https://codecov.io/github/stdgraph/graph-v2/branch/master/graph/badge.svg?token=49LGWDN0U1)](https://codecov.io/github/stdgraph/graph-v2) [![MacOS](https://github.com/stdgraph/graph-v2/actions/workflows/macos.yml/badge.svg)](https://github.com/stdgraph/graph-v2/actions/workflows/macos.yml) [![Ubuntu](https://github.com/stdgraph/graph-v2/actions/workflows/ubuntu.yml/badge.svg)](https://github.com/stdgraph/graph-v2/actions/workflows/ubuntu.yml) [![Windows](https://github.com/stdgraph/graph-v2/actions/workflows/windows.yml/badge.svg)](https://github.com/stdgraph/graph-v2/actions/workflows/windows.yml) [![Documentation](https://github.com/stdgraph/graph-v2/actions/workflows/pages.yml/badge.svg)](https://github.com/stdgraph/graph-v2/actions/workflows/pages.yml)
33

4-
> This library is in the alpha stage that may include significant changes to the interface. It is not recommended for general use.
4+
> This library is in the **alpha stage** that may include significant changes to the interface. It is not
5+
> recommended for general use.
6+
7+
> A **breaking change** in the near future will introduce a new concept of identifier for vertices and edges,
8+
> similar to the descriptor concept in the Boost Graph Library. It will replace the existing id and references
9+
> in the API and will allow for more flexibility in the design as well as reducing the number of concepts and
10+
> functions. Most functions and views will be affected. *Phil - September 2024*.
511
612
## Overview
713
This library designed to provide a useful set of algorithms, views and container(s) for graphs. It also defines
814
a core Graph Container Interface that provide the basis of interacting with an abstract adjacency list graph, and
915
to provide easy integration with external adjacency list graphs.
1016

11-
- bi-partite and n-partite graphs are under investigation.
1217
- Hyper-graphs are outside the scope of this project.
13-
- Comments and questions are welcome and can be directed to GitHub [discussions](https://github.com/stdgraph/graph-v2/discussions) or [issues](https://github.com/stdgraph/graph-v2/issues).
18+
- Comments and questions are welcome and can be directed to GitHub [discussions](https://github.com/stdgraph/graph-v2/discussions)
19+
or [issues](https://github.com/stdgraph/graph-v2/issues).
1420

1521
### Purpose
16-
This prototype library is an implementation of the proposed Graph Library for ISO Standard C++ as described in P1709.
22+
This prototype library is an implementation of the proposed Graph Library for ISO Standard C++.
1723
It has gone through major revisions since it was first introduced in 2019. While we are comfortable of the core design, there is
1824
still plenty of activity being done and refinements made in its design and implementation. Experimenting with this library is
1925
encouraged, keeping in mind that breaking changes are expected.
@@ -25,21 +31,19 @@ The goals of the library include:
2531
3. Define useful concepts and traits that can be used by algorithms to describe their requirements.
2632
4. Support views for graph traversal commonly used by algorithms.
2733
5. Support optional, user-defined value_types for an edge, vertex and graph.
28-
5. Easy integration of existing graph containers.
29-
6. Have an open design to allow for extensions in the future:
30-
1. Support for partite (partitioned) graphs. This requires extending (changing?) the Graph Container Interface.
31-
This is under investigation.
32-
2. Support the incoming edges on a vertex (e.g. bidirectional graphs).
33-
3. Investigate features that might make the Interface useful outside P1709, such as sparse vertex_ids.
34-
This can help validate the existing design and guide decisions for the future.
34+
6. Allow the use of standard containers to define simple graphs.
35+
7. Easy integration of existing graph data structures.
36+
8. Have an open design to allow for extensions in the future:
37+
1. Support the incoming edges on a vertex (e.g. bidirectional graphs).
38+
2. Support sparse vertex_ids stored in bi-directional ranges (e.g. `map` and `unordered_map`).
3539

3640
## Getting Started
37-
This is being actively developed with the latest releases of MSVC (VS2022) on Windows and gcc (11) on Linux/MacOS.
41+
This is being actively developed with the latest releases of MSVC (VS2022) on Windows and gcc (13) on Linux/MacOS.
3842
Other releases or compilers may or may not work.
3943

4044
### Prerequesites
41-
- C++20 compliant compiler that fully supports concepts and ranges.
42-
- CMake 20 or later (for CMake Presets)
45+
- C\+\+20 compliant compiler that fully supports concepts and ranges. (C\+\+23 is required for building the benchmarks.)
46+
- CMake 26 or later (for CMake Presets)
4347

4448
### Quick Start Guide (Linux, WSL, MacOS)
4549
```bash
@@ -55,48 +59,61 @@ You'll need to assure CMake Presets are enabled in your IDE or other development
5559
See https://docs.microsoft.com/en-us/cpp/build/cmake-presets-vs?view=msvc-170 for configuring Microsoft tools.
5660

5761
## Description
58-
In the following tables, P1709 identifies that the feature is in the P1709 proposal. A value of "TBD" indicates that it
59-
is being considered, subject to the size of the proposal and other priorities.
60-
61-
### Graph Algorithms
62-
63-
| Algorithm | P1709 | Status |
64-
| :-------------------------------| :---- | :-------------------------------------------------------------------------------|
65-
| Dijkstra Shortest Paths | Yes | dijkstra_clrs: needs review |
66-
| Bellman-Ford Shortest Paths | Yes | needs implementation |
67-
| Connected Components | Yes | needs implementation |
68-
| Strongly Connected Components | Yes | needs implementation |
69-
| Bi-Connected Components | Yes | needs implementation |
70-
| Articulation Points | Yes | needs implementation |
71-
| Minimum Spanning Tree | Yes | needs implementation |
72-
| Page Rank | TBD | needs implementation |
73-
| Betweenness Centrality | TBD | needs implementation |
74-
| Triangle Count | TBD | needs implementation |
75-
| Subgraph Isomorphism | TBD | needs implementation |
76-
| Kruskell Minimum Spanning Tree | TBD | needs implementation |
77-
| Prim Minimum Spanning Tre | TBD | needs implementation |
78-
| Louvain (Community Detection) | TBD | needs implementation |
79-
| Label propagation (Comm. Detection) | TBD | needs implementation |
80-
81-
82-
### Graph Views
83-
84-
| View | Done? | Description |
85-
| :-------------------------------| :---- | :-------------------------------------------------------------------------------|
86-
| vertexlist | Yes | Iterates over vertices |
87-
| incidence | Yes | Iterates over outgoing edges of a vertex |
88-
| neighbors | Yes | Iterates over outgoing neighbor vertices of a vertex |
89-
| edgelist | Yes | Iterates over edges of a graph |
90-
| depth_first_search | Yes | Iterates over vertices or edges of a seed vertex in depth-first order |
91-
| breadth_first_search | Yes | Iterates over vertices or edges of a seed vertex in breadth-first order |
92-
| topological_sort | No | Iterates over vertices or edges of a seed vertex in topological sort order |
93-
94-
### Graph Containers
95-
96-
| Container | P1709 | Description |
97-
| :-------------------------------| :---- | :-------------------------------------------------------------------------------|
98-
| compressed_graph | Yes | Compresed Sparse Row graph. High performance, static structure. |
99-
| dynamic_graph | No | Easy to use different containers for vertices and edges. |
62+
63+
### Graph Algorithms ([P3128](https://wg21.link/P3128))
64+
The following algorithms are planned for the Graph Library.
65+
66+
| Algorithm | Status |
67+
| :---------------------------------- | :-------------------------------------------------------------------------------|
68+
| Breadth First Search | revision scheduled |
69+
| Depth First Search | revision scheduled |
70+
| Topological Sort | implementation scheduled |
71+
| Dijkstra Shortest Paths | Completed |
72+
| Bellman-Ford Shortest Paths | Completed |
73+
| Triangle Counting | needs implementation |
74+
| Label propagation (Comm. Detection) | needs implementation |
75+
| Articulation Points | needs implementation |
76+
| Bi-Connected Components | needs implementation |
77+
| Connected Components | needs implementation |
78+
| Strongly Connected Components | needs implementation |
79+
| Maximal Independent Set | needs implementation |
80+
| Jaccard Coefficient | needs implementation |
81+
| Kruskell Minimum Spanning Tree | needs implementation |
82+
| Prim Minimum Spanning Tre | needs implementation |
83+
84+
85+
### Graph Views ([P3129](https://wg21.link/P3129) )
86+
87+
| View | Description |
88+
| :-------------------------------| :-------------------------------------------------------------------------------|
89+
| vertexlist | Iterates over vertices |
90+
| incidence | Iterates over outgoing edges of a vertex |
91+
| neighbors | Iterates over outgoing neighbor vertices of a vertex |
92+
| edgelist | Iterates over edges of a graph |
93+
| depth_first_search | Iterates over vertices or edges of a seed vertex in depth-first order |
94+
| breadth_first_search | Iterates over vertices or edges of a seed vertex in breadth-first order |
95+
| topological_sort | Iterates over vertices or edges of a seed vertex in topological sort order |
96+
97+
### Graph Containers ([P3131](https://wg21.link/P3130))
98+
99+
| Container | Description |
100+
| :-------------------------------| :-------------------------------------------------------------------------------|
101+
| compressed_graph | Compresed Sparse Row graph. High performance, static structure. |
102+
| dynamic_graph | Easy to use different containers for vertices and edges. |
103+
| (std containers) | Use standard containers like `vector` and `list` to define a simple graph. |
104+
105+
## Papers
106+
The following papers make up the current proposal for the Graph Library.
107+
108+
| Paper | Description |
109+
| :---------------------------------------------------------| :-------------------------------------------------------------------------------------------------------|
110+
| [P3126 Overview](https://wg21.link/P3126) | Describes the big picture of what we are proposing. |
111+
| [P3127 Background](https://wg21.link/P3127) | Background and Terminology, provides the motivation and theoretical background underlying the proposal. |
112+
| [P3128 Algoritms](https://wg21.link/P3128) | Covers the initial algorithms as well as the ones we'd like to see in the future. |
113+
| [P3129 Views](https://wg21.link/P3129) | Helpful views for traversing a graph. |
114+
| [P3130 Graph Container Interface](https://wg21.link/P3130)| The core interface for uniformly accessing graph data structure and adapting to external graphs. |
115+
| [P3131 Graph Containers](https://wg21.link/P3130) | Includes the `compressed_graph` and how to use standard containers to define simple graphs. |
116+
| [P3337 Graph Comparison](https://wg21.link/P3337) | *[future]* Syntax and performance comparison to the Boost Graph Library. |
100117

101118

102119
## Acknowledgments

‎ToDo.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,8 @@
3434
- [x] cancel() CPO? bfs, dfs: no, member only
3535
- [x] replace is_undirected_edge_v<G> & undirected_incidence_graph<G> with is_unordered_edge_v<G>
3636
- [ ] Views
37-
- [x] view classes should be in std::graph
38-
- [x] view functions should be in std::graph::view
37+
- [x] view classes should be in graph
38+
- [x] view functions should be in graph::view
3939
- [ ] add range overloads to appropriate views (DFS, BFS, topo_sort, etc.)
4040
- [ ] vertexlist
4141
- [ ] Use VVF&& instead of const VVF&

‎benchmark/mm_bench_dijkstra.cpp

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,8 @@ using std::endl;
4646
using fmt::print;
4747
using fmt::println;
4848

49-
using namespace std::graph;
50-
using namespace std::graph::experimental;
49+
using namespace graph;
50+
using namespace graph::experimental;
5151

5252
struct bench_results {
5353
size_t vertices_discovered = 0;
@@ -63,7 +63,7 @@ std::string current_timestamp() {
6363
template <typename Distance>
6464
size_t vertices_visited(const std::vector<Distance>& distances) {
6565
size_t visited = std::accumulate(distances.begin(), distances.end(), 0ULL, [](size_t count, Distance dist) {
66-
return (dist != shortest_path_invalid_distance<Distance>()) ? count + 1 : count;
66+
return (dist != shortest_path_infinite_distance<Distance>()) ? count + 1 : count;
6767
});
6868
//fmt::println("{:L} vertices were actually visited", visited);
6969
return visited;

‎benchmark/mm_load.hpp

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,8 @@ using std::convertible_to;
2929
using std::ranges::forward_range;
3030
using std::ranges::random_access_range;
3131
using std::ranges::range_value_t;
32-
using std::graph::adjacency_list;
33-
using std::graph::container::compressed_graph;
32+
using graph::adjacency_list;
33+
using graph::container::compressed_graph;
3434
namespace fmm = fast_matrix_market;
3535

3636
template <typename T>
@@ -287,14 +287,14 @@ struct graph_stats {
287287
size_t max_degree = 0;
288288
size_t self_loops_removed = 0;
289289

290-
template <std::graph::adjacency_list G>
290+
template <graph::adjacency_list G>
291291
graph_stats(const G& g, size_t self_loops = 0)
292-
: vertex_count(std::graph::num_vertices(g))
293-
, edge_count(static_cast<size_t>(std::graph::num_edges(g)))
292+
: vertex_count(graph::num_vertices(g))
293+
, edge_count(static_cast<size_t>(graph::num_edges(g)))
294294
, self_loops_removed(self_loops) {
295-
for (auto&& u : std::graph::vertices(g)) {
296-
min_degree = std::min(min_degree, size(std::graph::edges(g, u)));
297-
max_degree = std::max(max_degree, size(std::graph::edges(g, u)));
295+
for (auto&& u : graph::vertices(g)) {
296+
min_degree = std::min(min_degree, size(graph::edges(g, u)));
297+
max_degree = std::max(max_degree, size(graph::edges(g, u)));
298298
}
299299
}
300300
};
@@ -353,7 +353,7 @@ template <typename EV, typename VV, typename GV, integral VId, integral EIndex =
353353
auto zip_view = std::views::zip(triplet.rows, triplet.cols, triplet.vals);
354354
using zip_value = std::ranges::range_value_t<decltype(zip_view)>;
355355

356-
using edge_desc = std::graph::copyable_edge_t<VId, EV>;
356+
using edge_desc = graph::copyable_edge_t<VId, EV>;
357357
auto edge_proj = [](const zip_value& val) -> edge_desc {
358358
return edge_desc{std::get<0>(val), std::get<1>(val), std::get<2>(val)};
359359
};

‎benchmark/mm_load_example.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
using std::tuple;
77
using std::vector;
88

9-
using namespace std::graph::container;
9+
using namespace graph::container;
1010

1111
// Dataset: gap_twitter, symmetry_type::general, 1,468,364,884 rows
1212
// Deb/Rel parallel_ok num_threads Read Rows/Sec LoadSimple Edges/Sec LoadCompressed Edges/Sec

‎benchmark/nwgraph_dijkstra.hpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
template <adjacency_list Graph, class Weight, class Sources>
66
static auto nwgraph_dijkstra(
77
Graph&& graph, const Sources& sources, Weight weight = [](auto& e) -> auto& { return std::get<1>(e); }) {
8-
using namespace std::graph;
8+
using namespace graph;
99
using vertex_id_type = vertex_id_t<Graph>;
1010

1111
using distance_t = int64_t;

‎doc/Identifiers.docx

17.1 KB
Binary file not shown.

‎docs/sphinx/conf.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@
9292
#html_theme = 'sphinx13'
9393
html_theme = 'sphinx_rtd_theme'
9494
# html_theme = 'sphinx_book_theme'
95-
html_title = "std::graph Documentation"
95+
html_title = "graph Documentation"
9696

9797
# Add any paths that contain custom static files (such as style sheets) here,
9898
# relative to this directory. They are copied after the builtin static files,
@@ -114,7 +114,7 @@
114114

115115
# -- Options for the C++ Domain ----------------------------------------------
116116

117-
cpp_index_common_prefix = ['std::', 'std::graph::']
117+
cpp_index_common_prefix = ['std::', 'graph::']
118118

119119

120120
# -- Options for Breathe -----------------------------------------------------

0 commit comments

Comments
 (0)