Skip to content

Commit

Permalink
Merge pull request #133 from stdgraph/bfs
Browse files Browse the repository at this point in the history 
Changes from feedback
  • Loading branch information
@pratzl
pratzl committed Sep 20, 2024
2 parents 3d572ef + 5d281b0 commit bef80c2
Show file tree
Hide file tree
Showing 12 changed files with 262 additions and 241 deletions.
129 changes: 73 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,25 @@
# Graph Library Proposal for the C++ Standard
[![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)

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

- bi-partite and n-partite graphs are under investigation.
- Hyper-graphs are outside the scope of this project.
- 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).
- 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).

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

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

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

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

## Description
In the following tables, P1709 identifies that the feature is in the P1709 proposal. A value of "TBD" indicates that it
is being considered, subject to the size of the proposal and other priorities.

### Graph Algorithms

| Algorithm | P1709 | Status |
| :-------------------------------| :---- | :-------------------------------------------------------------------------------|
| Dijkstra Shortest Paths | Yes | dijkstra_clrs: needs review |
| Bellman-Ford Shortest Paths | Yes | needs implementation |
| Connected Components | Yes | needs implementation |
| Strongly Connected Components | Yes | needs implementation |
| Bi-Connected Components | Yes | needs implementation |
| Articulation Points | Yes | needs implementation |
| Minimum Spanning Tree | Yes | needs implementation |
| Page Rank | TBD | needs implementation |
| Betweenness Centrality | TBD | needs implementation |
| Triangle Count | TBD | needs implementation |
| Subgraph Isomorphism | TBD | needs implementation |
| Kruskell Minimum Spanning Tree | TBD | needs implementation |
| Prim Minimum Spanning Tre | TBD | needs implementation |
| Louvain (Community Detection) | TBD | needs implementation |
| Label propagation (Comm. Detection) | TBD | needs implementation |


### Graph Views

| View | Done? | Description |
| :-------------------------------| :---- | :-------------------------------------------------------------------------------|
| vertexlist | Yes | Iterates over vertices |
| incidence | Yes | Iterates over outgoing edges of a vertex |
| neighbors | Yes | Iterates over outgoing neighbor vertices of a vertex |
| edgelist | Yes | Iterates over edges of a graph |
| depth_first_search | Yes | Iterates over vertices or edges of a seed vertex in depth-first order |
| breadth_first_search | Yes | Iterates over vertices or edges of a seed vertex in breadth-first order |
| topological_sort | No | Iterates over vertices or edges of a seed vertex in topological sort order |

### Graph Containers

| Container | P1709 | Description |
| :-------------------------------| :---- | :-------------------------------------------------------------------------------|
| compressed_graph | Yes | Compresed Sparse Row graph. High performance, static structure. |
| dynamic_graph | No | Easy to use different containers for vertices and edges. |

### Graph Algorithms ([P3128](https://wg21.link/P3128))
The following algorithms are planned for the Graph Library.

| Algorithm | Status |
| :---------------------------------- | :-------------------------------------------------------------------------------|
| Breadth First Search | revision scheduled |
| Depth First Search | revision scheduled |
| Topological Sort | implementation scheduled |
| Dijkstra Shortest Paths | Completed |
| Bellman-Ford Shortest Paths | Completed |
| Triangle Counting | needs implementation |
| Label propagation (Comm. Detection) | needs implementation |
| Articulation Points | needs implementation |
| Bi-Connected Components | needs implementation |
| Connected Components | needs implementation |
| Strongly Connected Components | needs implementation |
| Maximal Independent Set | needs implementation |
| Jaccard Coefficient | needs implementation |
| Kruskell Minimum Spanning Tree | needs implementation |
| Prim Minimum Spanning Tre | needs implementation |


### Graph Views ([P3129](https://wg21.link/P3129) )

| View | Description |
| :-------------------------------| :-------------------------------------------------------------------------------|
| vertexlist | Iterates over vertices |
| incidence | Iterates over outgoing edges of a vertex |
| neighbors | Iterates over outgoing neighbor vertices of a vertex |
| edgelist | Iterates over edges of a graph |
| depth_first_search | Iterates over vertices or edges of a seed vertex in depth-first order |
| breadth_first_search | Iterates over vertices or edges of a seed vertex in breadth-first order |
| topological_sort | Iterates over vertices or edges of a seed vertex in topological sort order |

### Graph Containers ([P3131](https://wg21.link/P3130))

| Container | Description |
| :-------------------------------| :-------------------------------------------------------------------------------|
| compressed_graph | Compresed Sparse Row graph. High performance, static structure. |
| dynamic_graph | Easy to use different containers for vertices and edges. |
| (std containers) | Use standard containers like `vector` and `list` to define a simple graph. |

## Papers
The following papers make up the current proposal for the Graph Library.

| Paper | Description |
| :---------------------------------------------------------| :-------------------------------------------------------------------------------------------------------|
| [P3126 Overview](https://wg21.link/P3126) | Describes the big picture of what we are proposing. |
| [P3127 Background](https://wg21.link/P3127) | Background and Terminology, provides the motivation and theoretical background underlying the proposal. |
| [P3128 Algoritms](https://wg21.link/P3128) | Covers the initial algorithms as well as the ones we'd like to see in the future. |
| [P3129 Views](https://wg21.link/P3129) | Helpful views for traversing a graph. |
| [P3130 Graph Container Interface](https://wg21.link/P3130)| The core interface for uniformly accessing graph data structure and adapting to external graphs. |
| [P3131 Graph Containers](https://wg21.link/P3130) | Includes the `compressed_graph` and how to use standard containers to define simple graphs. |
| [P3337 Graph Comparison](https://wg21.link/P3337) | *[future]* Syntax and performance comparison to the Boost Graph Library. |


## Acknowledgments
Expand Down
14 changes: 7 additions & 7 deletions include/graph/algorithm/bellman_ford_shortest_paths.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -224,10 +224,10 @@ requires is_arithmetic_v<range_value_t<Distances>> && //
sized_range<Predecessors> && //
basic_edge_weight_function<G, WF, range_value_t<Distances>, Compare, Combine>
[[nodiscard]] constexpr optional<vertex_id_t<G>> bellman_ford_shortest_paths(
G&& g,
const vertex_id_t<G> source,
Distances& distances,
Predecessors& predecessor,
G&& g,
vertex_id_t<G> source,
Distances& distances,
Predecessors& predecessor,
WF&& weight = [](edge_reference_t<G> uv) { return range_value_t<Distances>(1); }, // default weight(uv) -> 1
Visitor&& visitor = empty_visitor(),
Compare&& compare = less<range_value_t<Distances>>(),
Expand Down Expand Up @@ -300,9 +300,9 @@ requires is_arithmetic_v<range_value_t<Distances>> && //
sized_range<Distances> && //
basic_edge_weight_function<G, WF, range_value_t<Distances>, Compare, Combine>
[[nodiscard]] constexpr optional<vertex_id_t<G>> bellman_ford_shortest_distances(
G&& g,
const vertex_id_t<G> source,
Distances& distances,
G&& g,
vertex_id_t<G> source,
Distances& distances,
WF&& weight = [](edge_reference_t<G> uv) { return range_value_t<Distances>(1); }, // default weight(uv) -> 1
Visitor&& visitor = empty_visitor(),
Compare&& compare = less<range_value_t<Distances>>(),
Expand Down
19 changes: 10 additions & 9 deletions include/graph/algorithm/common_shortest_paths.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

#include <algorithm>
#include <numeric>
#include <graph/detail/graph_using.hpp>

#ifndef GRAPH_COMMON_SHORTEST_PATHS_HPP
# define GRAPH_COMMON_SHORTEST_PATHS_HPP
Expand Down Expand Up @@ -80,49 +81,49 @@ constexpr void init_shortest_paths(Distances& distances, Predecessors& predecess

// Vertex visitor concepts
template <class G, class Visitor>
concept has_on_initialize_vertex = //
concept has_on_initialize_vertex = // For exposition only
requires(Visitor& v, vertex_descriptor<vertex_id_t<G>, vertex_reference_t<G>, void> vdesc) {
{ v.on_initialize_vertex(vdesc) };
};
template <class G, class Visitor>
concept has_on_discover_vertex = //
concept has_on_discover_vertex = // For exposition only
requires(Visitor& v, vertex_descriptor<vertex_id_t<G>, vertex_reference_t<G>, void> vdesc) {
{ v.on_discover_vertex(vdesc) };
};
template <class G, class Visitor>
concept has_on_examine_vertex = //
concept has_on_examine_vertex = // For exposition only
requires(Visitor& v, vertex_descriptor<vertex_id_t<G>, vertex_reference_t<G>, void> vdesc) {
{ v.on_examine_vertex(vdesc) };
};
template <class G, class Visitor>
concept has_on_finish_vertex = //
concept has_on_finish_vertex = // For exposition only
requires(Visitor& v, vertex_descriptor<vertex_id_t<G>, vertex_reference_t<G>, void> vdesc) {
{ v.on_finish_vertex(vdesc) };
};

// Edge visitor concepts
template <class G, class Visitor>
concept has_on_examine_edge = //
concept has_on_examine_edge = // For exposition only
requires(Visitor& v, edge_descriptor<vertex_id_t<G>, true, edge_reference_t<G>, void> edesc) {
{ v.on_examine_edge(edesc) };
};
template <class G, class Visitor>
concept has_on_edge_relaxed = //
concept has_on_edge_relaxed = // For exposition only
requires(Visitor& v, edge_descriptor<vertex_id_t<G>, true, edge_reference_t<G>, void> edesc) {
{ v.on_edge_relaxed(edesc) };
};
template <class G, class Visitor>
concept has_on_edge_not_relaxed = //
concept has_on_edge_not_relaxed = // For exposition only
requires(Visitor& v, edge_descriptor<vertex_id_t<G>, true, edge_reference_t<G>, void> edesc) {
{ v.on_edge_not_relaxed(edesc) };
};
template <class G, class Visitor>
concept has_on_edge_minimized = //
concept has_on_edge_minimized = // For exposition only
requires(Visitor& v, edge_descriptor<vertex_id_t<G>, true, edge_reference_t<G>, void> edesc) {
{ v.on_edge_minimized(edesc) };
};
template <class G, class Visitor>
concept has_on_edge_not_minimized =
concept has_on_edge_not_minimized = // For exposition only
requires(Visitor& v, edge_descriptor<vertex_id_t<G>, true, edge_reference_t<G>, void> edesc) {
{ v.on_edge_not_minimized(edesc) };
};
Expand Down
Loading

0 comments on commit bef80c2

Please sign in to comment.