From fed892bc915b8499ae1186978cbcc6c7968b4825 Mon Sep 17 00:00:00 2001 From: Phil Ratzloff Date: Sun, 31 May 2026 10:50:20 -0400 Subject: [PATCH] docs(agents): restructure and correct bgl_migration_strategy.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix factual contradictions: mutation support (dynamic_graph + undirected both have add/remove vertex/edge), transpose API (class not factory fn), scorecard mutation row (was 'undirected only / 40%') - Add 'How to use this document' reader-orientation intro - Restructure: move practical guide (§1-11) ahead of reference material; demote Algorithm Gap Analysis, Roadmap, and Scorecard to Appendices A/B/C - Topological sort reclassified as traversal (with BFS/DFS) in Appendix A and Appendix C; traversal score updated to 100% - Visitor row updated to reflect shipped composable adaptor toolkit (visitor_factory.hpp); score 75% -> 90% - Property system score corrected to 100% (by design): tag-dispatch machinery was a C++03 workaround, not a missing feature - Overall coverage re-evaluated: ~33% -> ~46%, with core/specialist split - Appendix B: add Boost incubation strategy subsection (Boost as BGL2 to gain field usage for std::graph proposal; alias-layer packaging guidance) - Fix proposal-voice in §8 (DOT writer): 'should leverage' -> 'leverages' - MutableGraph concept note clarified: mutation exists as member functions --- agents/bgl_migration_strategy.md | 420 ++++++++++++++++++------------- 1 file changed, 242 insertions(+), 178 deletions(-) diff --git a/agents/bgl_migration_strategy.md b/agents/bgl_migration_strategy.md index 5d3f109..678800b 100644 --- a/agents/bgl_migration_strategy.md +++ b/agents/bgl_migration_strategy.md @@ -1,11 +1,22 @@ -# BGL → graph-v3 Upgrade Strategy +# BGL → graph-v3 Migration Strategy -A comprehensive analysis of the Boost Graph Library (BGL) and graph-v3, identifying gaps, migration paths, and recommended extensions to enable a smooth upgrade transition. +A comprehensive analysis of the Boost Graph Library (BGL) and graph-v3, identifying migration paths, gaps, and recommended extensions to enable a smooth upgrade transition. > **Last reviewed:** 2026-05-30 against `include/graph/` source tree. --- +## How to use this document + +This guide serves two audiences: + +- **Migrating a BGL codebase?** Start with [§3 Graph Container Mapping](#3-graph-container-mapping), [§5 Property System Migration](#5-property-system-migration), [§10 API Pattern Migration Guide](#10-api-pattern-migration-guide), and [§11 Adapting an Existing BGL Graph](#11-adapting-an-existing-bgl-graph-for-graph-v3). These are task-oriented and show side-by-side before/after code. +- **Planning graph-v3 work or tracking parity?** See [Appendix A. Algorithm Gap Analysis](#appendix-a-algorithm-gap-analysis) and [Appendix B. Recommended Extensions & Roadmap](#appendix-b-recommended-extensions--roadmap), which are reference/planning material. + +[§1 Executive Summary](#1-executive-summary) gives the high-level picture for both. + +--- + ## Table of Contents 1. [Executive Summary](#1-executive-summary) @@ -13,14 +24,18 @@ A comprehensive analysis of the Boost Graph Library (BGL) and graph-v3, identify 3. [Graph Container Mapping](#3-graph-container-mapping) 4. [Concept & Type System Comparison](#4-concept--type-system-comparison) 5. [Property System Migration](#5-property-system-migration) -6. [Algorithm Gap Analysis](#6-algorithm-gap-analysis) -7. [Visitor Pattern Migration](#7-visitor-pattern-migration) -8. [Graph Adaptors & Views](#8-graph-adaptors--views) -9. [Graph I/O & Serialization](#9-graph-io--serialization) -10. [Graph Generators](#10-graph-generators) -11. [API Pattern Migration Guide](#11-api-pattern-migration-guide) -12. [Adapting an Existing BGL Graph for graph-v3](#12-adapting-an-existing-bgl-graph-for-graph-v3) -13. [Recommended Extensions & Roadmap](#13-recommended-extensions--roadmap) +6. [Visitor Pattern Migration](#6-visitor-pattern-migration) +7. [Graph Adaptors & Views](#7-graph-adaptors--views) +8. [Graph I/O & Serialization](#8-graph-io--serialization) +9. [Graph Generators](#9-graph-generators) +10. [API Pattern Migration Guide](#10-api-pattern-migration-guide) +11. [Adapting an Existing BGL Graph for graph-v3](#11-adapting-an-existing-bgl-graph-for-graph-v3) + +**Appendices** (reference & planning material) + +- [Appendix A. Algorithm Gap Analysis](#appendix-a-algorithm-gap-analysis) +- [Appendix B. Recommended Extensions & Roadmap](#appendix-b-recommended-extensions--roadmap) +- [Appendix C. Migration Readiness Scorecard](#appendix-c-migration-readiness-scorecard) --- @@ -46,7 +61,6 @@ graph-v3 is a ground-up C++20 redesign targeting ISO standardization (P3126–P3 - No `subgraph` hierarchy with descriptor mapping - No DIMACS or METIS I/O - Graph generators partially implemented (Erdős-Rényi G(n,p), Barabási-Albert, 2D grid, path available; Watts-Strogatz, R-MAT, complete graph still missing) -- Both `dynamic_graph` and `undirected_adjacency_list` now support full mutation (`add_vertex`, `add_edge`, `remove_edge`, `remove_vertex`); no major mutation gaps remain - No `adjacency_matrix` container - No `copy_graph` utility with cross-type and property mapping support - No `labeled_graph` adaptor (string labels → vertex mapping) @@ -88,7 +102,7 @@ graph-v3 is a ground-up C++20 redesign targeting ISO standardization (P3126–P3 | BGL Container | graph-v3 Equivalent | Notes | |---------------|---------------------|-------| -| `adjacency_list` | `dynamic_graph` | Closest built-in vector/vector analogue; `dynamic_graph` still lacks individual `add_edge` / `remove_edge` | +| `adjacency_list` | `dynamic_graph` | Closest built-in vector/vector analogue | | `adjacency_list` | `dynamic_graph` | Closest built-in vector/vector bidirectional analogue | | `adjacency_list` | `undirected_adjacency_list` | Closest built-in undirected container; dual-list design, not a storage/layout match for BGL `vecS` / `vecS` | | `compressed_sparse_row_graph` | `compressed_graph` | Both CSR; graph-v3 uses projection-based loading | @@ -141,7 +155,7 @@ These are behavioral analogues, not strict one-to-one translations. In particula | `EdgeListGraph` | `basic_sourced_edgelist` / `basic_sourced_index_edgelist` | Concepts for an edgelist (range of edges); `edgelist(g)` is a *view* that produces such a range from an adjacency list | | `VertexAndEdgeListGraph` | `adjacency_list` | Combined by default | | `AdjacencyMatrix` | ❌ Not available | No O(1) edge lookup concept | -| `MutableGraph` | ❌ No unified concept | No mutating CPOs are defined in the current design | +| `MutableGraph` | ❌ No unified concept | No mutating CPOs; mutation is provided as member functions on `dynamic_graph` and `undirected_adjacency_list` | | `PropertyGraph` | ❌ No formal concept | CPOs `vertex_value`/`edge_value` and their matching `vertex_value_t/edge_value_t` serve the role | | `ColorValue` | ❌ Internal only | Hidden inside algorithms | @@ -227,143 +241,7 @@ dijkstra_shortest_paths(g, {s}, container_value_fn(dist), ...); --- -## 6. Algorithm Gap Analysis - -### Algorithms Present in Both Libraries - -| Algorithm | BGL | graph-v3 | Interface Differences | -|-----------|-----|----------|-----------------------| -| **BFS** | `breadth_first_search(g, s, visitor(v).color_map(c))` | `breadth_first_search(g, sources, visitor)` | graph-v3: multi-source native, no color map, concept-checked visitor | -| **DFS** | `depth_first_search(g, visitor(v).color_map(c))` | `depth_first_search(g, sources, visitor)` | graph-v3: edge classification (tree/back/forward_or_cross), multi-source | -| **Dijkstra** | `dijkstra_shortest_paths(g, s, weight_map(w).distance_map(d).predecessor_map(p))` | `dijkstra_shortest_paths(g, sources, dist_fn, pred_fn, weight_fn, visitor)` | graph-v3: function-object properties, multi-source, custom compare/combine | -| **Bellman-Ford** | `bellman_ford_shortest_paths(g, N, weight_map(w).distance_map(d))` | `bellman_ford_shortest_paths(g, sources, dist_fn, pred_fn, weight_fn, visitor)` | Similar; graph-v3 detects negative cycles via visitor | -| **Kruskal MST** | `kruskal_minimum_spanning_tree(g, back_inserter(mst))` | `kruskal(edges, mst_output)` | graph-v3 works on edge lists directly; also `inplace_kruskal` | -| **Prim MST** | `prim_minimum_spanning_tree(g, pmap)` | `prim(g, source, mst_output, weight_fn)` | graph-v3 takes a source; thin wrapper over `dijkstra_shortest_paths` | -| **Connected Components** | `connected_components(g, comp_map)` | `connected_components(g, comp_fn)` | graph-v3 uses function objects | -| **Strong Components** | `strong_components(g, comp_map)` | `kosaraju(g, comp_fn)` + `tarjan_scc(g, comp_fn)` | graph-v3 has both Kosaraju and Tarjan; `tarjan_scc.hpp` is **not** in `algorithms.hpp` umbrella (include directly) | -| **Biconnected Components** | `biconnected_components(g, comp_map)` | `biconnected_components(g, output)` | Similar | -| **Topological Sort** | `topological_sort(g, back_inserter(order))` | `topological_sort(g, output_iter)` | Both use output iterators; graph-v3 returns bool (cycle detection) | -| **Articulation Points** | `articulation_points(g, back_inserter(art))` | `articulation_points(g, output_iter)` | Similar | - -### Algorithms in BGL but MISSING from graph-v3 - -#### Shortest Paths (3 missing) -| Algorithm | Priority | Difficulty | Notes | -|-----------|----------|------------|-------| -| **A\* Search** | 🔴 High | Medium | Heavily used; needs heuristic function concept | -| **Johnson All-Pairs** | 🟡 Medium | Medium | Builds on Dijkstra + Bellman-Ford (both exist) | -| **Floyd-Warshall** | 🟡 Medium | Low | O(V³) all-pairs; straightforward implementation | -| **DAG Shortest Paths** | 🟢 Low | Low | Linear-time on DAGs; topological sort + relaxation | - -#### Network Flow (7 missing) -| Algorithm | Priority | Difficulty | Notes | -|-----------|----------|------------|-------| -| **Edmonds-Karp Max Flow** | 🔴 High | Medium | Core max-flow; needs `edge_reverse` and `residual_capacity` properties | -| **Push-Relabel Max Flow** | 🟡 Medium | High | Higher performance than Edmonds-Karp | -| **Boykov-Kolmogorov Max Flow** | 🟡 Medium | High | Used in computer vision | -| **Stoer-Wagner Min Cut** | 🟡 Medium | Medium | Undirected min-cut | -| **Cycle Canceling (min-cost flow)** | 🟢 Low | High | Specialized | -| **Successive Shortest Path** | 🟢 Low | High | Min-cost flow variant | -| **Find Flow Cost** | 🟢 Low | Low | Utility for min-cost flow | - -#### Matching (2 missing) -| Algorithm | Priority | Difficulty | Notes | -|-----------|----------|------------|-------| -| **Max Cardinality Matching** | 🟡 Medium | Medium | Useful for bipartite problems | -| **Maximum Weighted Matching** | 🟢 Low | High | Complex implementation | - -#### Coloring (2 missing) -| Algorithm | Priority | Difficulty | Notes | -|-----------|----------|------------|-------| -| **Sequential Vertex Coloring** | 🟡 Medium | Low | Simple greedy coloring | -| **Edge Coloring** | 🟢 Low | Medium | Vizing's theorem | - -#### Planarity (7 missing) -| Algorithm | Priority | Difficulty | Notes | -|-----------|----------|------------|-------| -| **Boyer-Myrvold Planarity Test** | 🟡 Medium | High | Core planarity test | -| **Kuratowski Subgraph** | 🟢 Low | High | Planarity certificate | -| **Chrobak-Payne Drawing** | 🟢 Low | High | Planar graph drawing | -| **Planar Canonical Ordering** | 🟢 Low | High | For planar drawings | -| **Planar Face Traversal** | 🟢 Low | Medium | Dual graph operations | -| **Make Biconnected/Connected/Maximal Planar** | 🟢 Low | Medium | Graph augmentation | - -#### Isomorphism (3 missing) -| Algorithm | Priority | Difficulty | Notes | -|-----------|----------|------------|-------| -| **Graph Isomorphism** | 🟡 Medium | High | General isomorphism test | -| **VF2 Subgraph Isomorphism** | 🟡 Medium | High | Pattern matching in graphs | -| **McGregor Common Subgraphs** | 🟢 Low | High | Maximum common subgraph | - -#### Centrality & Metrics (7 missing) -| Algorithm | Priority | Difficulty | Notes | -|-----------|----------|------------|-------| -| **Betweenness Centrality** | 🔴 High | Medium | Widely used in network analysis | -| **PageRank** | 🔴 High | Low | Iterative; straightforward | -| **Degree Centrality** | 🟡 Medium | Low | Trivial with `degree()` CPO | -| **Closeness Centrality** | 🟡 Medium | Medium | Requires all-pairs shortest paths | -| **Clustering Coefficient** | 🟡 Medium | Low | Related to existing triangle count | -| **Eccentricity** | 🟢 Low | Medium | Max distance from vertex | -| **Geodesic Distance** | 🟢 Low | Medium | Average shortest path | - -#### Ordering & Bandwidth (6 missing) -| Algorithm | Priority | Difficulty | Notes | -|-----------|----------|------------|-------| -| **Cuthill-McKee Ordering** | 🟡 Medium | Medium | Bandwidth reduction; used in sparse matrix solvers | -| **King Ordering** | 🟢 Low | Medium | Profile reduction | -| **Sloan Ordering** | 🟢 Low | Medium | Wavefront reduction | -| **Minimum Degree Ordering** | 🟢 Low | High | Fill-reduction ordering | -| **Smallest Last Ordering** | 🟢 Low | Low | Coloring heuristic | -| **Bandwidth/Profile/Wavefront** | 🟢 Low | Low | Metrics only | - -#### Cycle Detection (3 missing) -| Algorithm | Priority | Difficulty | Notes | -|-----------|----------|------------|-------| -| **Tiernan All Cycles** | 🟢 Low | Medium | Enumerate all cycles | -| **Hawick Circuits** | 🟢 Low | Medium | All elementary circuits | -| **Howard Cycle Ratio** | 🟢 Low | High | Min/max cycle ratio | - -#### DAG & Closure (3 missing) -| Algorithm | Priority | Difficulty | Notes | -|-----------|----------|------------|-------| -| **Transitive Closure** | 🟡 Medium | Medium | Used in dependency analysis | -| **Transitive Reduction** | 🟡 Medium | Medium | Minimal equivalent DAG | -| **Dominator Tree** | 🟢 Low | High | Compiler/control flow analysis | - -#### Layout (5 missing) -| Algorithm | Priority | Difficulty | Notes | -|-----------|----------|------------|-------| -| **Fruchterman-Reingold** | 🟡 Medium | Medium | Force-directed layout | -| **Kamada-Kawai** | 🟡 Medium | Medium | Spring layout | -| **Gursoy-Atun** | 🟢 Low | Medium | Topology-based layout | -| **Circle Layout** | 🟢 Low | Low | Trivial | -| **Random Layout** | 🟢 Low | Low | Trivial | - -#### Other (8 missing) -| Algorithm | Priority | Difficulty | Notes | -|-----------|----------|------------|-------| -| **Core Numbers** | 🟡 Medium | Medium | k-core decomposition | -| **Maximum Adjacency Search** | 🟡 Medium | Medium | Used by Stoer-Wagner | -| **Bipartite Test** | 🟡 Medium | Low | BFS-based 2-coloring | -| **TSP Approximation** | 🟢 Low | Medium | Metric TSP heuristic | -| **Random Spanning Tree** | 🟢 Low | Medium | Wilson's algorithm | -| **Copy Graph** | 🟡 Medium | Low | Cross-type copy with property mapping | -| **Bron-Kerbosch All Cliques** | 🟢 Low | Medium | Maximal clique enumeration | -| **Create Condensation Graph** | 🟢 Low | Low | DAG from SCC | - -### Algorithms in graph-v3 but NOT in BGL - -| Algorithm | Header | Notes | -|-----------|--------|-------| -| **Jaccard Coefficient** | `jaccard.hpp` | Similarity metric for adjacent vertex neighborhoods | -| **Label Propagation** | `label_propagation.hpp` | Community detection algorithm | -| **Maximal Independent Set** | `mis.hpp` | Greedy MIS | -| **Triangle Count** | `tc.hpp` | `triangle_count()` and `directed_triangle_count()` | -| **Afforest** | `connected_components.hpp` | Parallel-friendly connected components (Sutton et al.) | - ---- - -## 7. Visitor Pattern Migration +## 6. Visitor Pattern Migration ### BGL Visitor → graph-v3 Visitor @@ -473,7 +351,7 @@ Key differences from BGL: --- -## 8. Graph Adaptors & Views +## 7. Graph Adaptors & Views ### BGL Adaptors → graph-v3 Equivalents @@ -525,7 +403,7 @@ graph-v3's lazy view system is a significant advancement over BGL: --- -## 9. Graph I/O & Serialization +## 8. Graph I/O & Serialization ### BGL I/O Support vs. graph-v3 @@ -544,7 +422,7 @@ graph-v3's lazy view system is a significant advancement over BGL: ### DOT API — `std::format`-Based (implemented) -The DOT writer should leverage `std::format` (C++20) for type-safe value serialization. This avoids inventing a new extension point — users who specialize `std::formatter` get DOT output for free. +The DOT writer leverages `std::format` (C++20) for type-safe value serialization. This avoids inventing a new extension point — users who specialize `std::formatter` get DOT output for free. **Design: auto-format with opt-in override.** @@ -593,7 +471,7 @@ void write_dot(ostream& os, const G& g) { **Comparison with BGL's approach:** -| Aspect | BGL | Proposed graph-v3 | +| Aspect | BGL | graph-v3 | |--------|-----|-------------------| | Value → string | `dynamic_properties` + per-property converters | `std::format` via `std::formatter` specialization | | Customization | Verbose `dp.property("name", get(&VP::name, g))` for each field | Single `vertex_attr_fn` / `edge_attr_fn` callable | @@ -642,7 +520,7 @@ auto read_graphml(istream& is) -> dynamic_graph; --- -## 10. Graph Generators +## 9. Graph Generators ### BGL Generators vs. graph-v3 @@ -707,7 +585,7 @@ To achieve full BGL parity, the following generators are still needed: --- -## 11. API Pattern Migration Guide +## 10. API Pattern Migration Guide ### Common BGL Patterns → graph-v3 Equivalents @@ -763,9 +641,9 @@ g.add_edge(0, 1, 10.0); g.add_edge(1, 2, 20.0); g.add_edge(2, 3, 30.0); ``` -* Note that add_edge is a member function of g. There are no mutating CPOs at this time. +* Note that add_edge is a member function of `dynamic_graph`. There are no mutating CPOs at this time. -Or with an _Initializer list_ +Or with an _initializer list_ ```cpp Graph g({{0,1,10.0}, {1,2,20.0}, {2,3,30.0}}); ``` @@ -871,7 +749,7 @@ depth_first_search(rg, visitor(vis)); **graph-v3:** ```cpp -auto tg = graph::views::transpose(g); // requires bidirectional graph +graph::views::transpose_view tg(g); // requires bidirectional graph depth_first_search(tg, {s}, vis); ``` @@ -889,7 +767,7 @@ auto first_10 = vertices_dfs(g, source) | std::views::take(10); --- -## 12. Adapting an Existing BGL Graph for graph-v3 +## 11. Adapting an Existing BGL Graph for graph-v3 This section describes how to make an existing `boost::adjacency_list` (or any BGL-modelling type) usable as input to graph-v3 algorithms and views, **without rewriting the storage**. The goal is incremental migration: keep the BGL container, expose graph-v3 CPOs on top of it. @@ -901,7 +779,7 @@ This section describes how to make an existing `boost::adjacency_list` (or any B > See the [BGL Adaptor User Guide](../../docs/user-guide/bgl-adaptor.md) and [examples/bgl_adaptor_example.cpp](../../examples/bgl_adaptor_example.cpp) for usage. > The manual approach described below remains useful for understanding the CPO dispatch mechanism or for adapting non-standard BGL types. -### 12.1 What graph-v3 Requires +### 11.1 What graph-v3 Requires graph-v3 dispatches everything through CPOs and a small set of concepts. The minimum surface to satisfy `graph::adjacency_list` is: @@ -933,7 +811,7 @@ There is **no `graph_traits` to specialise**. A CPO is satisfied in one of three For BGL types you will use **option 2**: add free functions in `namespace boost`. ADL will find them because `boost::adjacency_list` lives in that namespace. -### 12.2 Recommended Layout +### 11.2 Recommended Layout Put the adapter in its own header, included **before** any graph-v3 algorithm header that will be invoked on a BGL graph: @@ -949,7 +827,7 @@ Put the adapter in its own header, included **before** any graph-v3 algorithm he All adapter functions go inside `namespace boost { ... }` so ADL picks them up. -### 12.3 Minimal Adapter for `boost::adjacency_list` +### 11.3 Minimal Adapter for `boost::adjacency_list` > **Note:** graph-v3 already ships a complete, production-ready BGL adaptor — prefer it > over hand-rolling your own. Include `` (and @@ -1030,7 +908,7 @@ auto vertex_id(const adjacency_list& /*g*/, With just these five functions, a `boost::adjacency_list` satisfies `graph::index_adjacency_list` and can be passed to BFS, DFS, and topological sort. -### 12.4 Bidirectional Graphs +### 11.4 Bidirectional Graphs For algorithms that need in-edges (e.g. transposed traversals), add: @@ -1049,7 +927,7 @@ auto in_edges(adjacency_list& g, This only compiles when the underlying graph is `bidirectionalS`. -### 12.5 Property Access +### 11.5 Property Access BGL graphs expose properties three different ways. graph-v3 reads them through `vertex_value(g, u)` / `edge_value(g, uv)` CPOs, plus user-supplied callables for algorithm-specific maps (e.g. weight). @@ -1103,7 +981,7 @@ graph::dijkstra_shortest_paths(g, {source}, distances, predecessors, weight); Each property is an independent callable, so you only define the ones a given algorithm requires. -### 12.6 Other BGL Container Configurations +### 11.6 Other BGL Container Configurations | BGL `OutEdgeS` / `VertexS` | Vertex descriptor | Adapter notes | |----------------------------|-------------------|---------------| @@ -1115,7 +993,7 @@ Each property is an independent callable, so you only define the ones a given al For non-`vecS` `VertexS`, prefer copying the graph into a graph-v3 container at the migration boundary rather than maintaining an id-mapping adapter. -### 12.7 Verifying the Adapter +### 11.7 Verifying the Adapter After writing the adapter, confirm the concepts compile: @@ -1134,23 +1012,176 @@ static_assert(graph::index_adjacency_list); If the assertions pass, all graph-v3 algorithms constrained on `index_adjacency_list` will accept the BGL graph. -### 12.8 Migration Workflow +### 11.8 Migration Workflow 1. Drop in the adapter header — no source changes to existing BGL code. 2. Pick one new code path (e.g. a new analytics pass) and write it against graph-v3 CPOs, taking the existing BGL graph as input. 3. As tests cover more code paths, port BGL call sites one at a time using the API mappings in [Section 11](#11-api-pattern-migration-guide). 4. Once all algorithm call sites are ported, replace the BGL container with `graph::dynamic_graph` (or another graph-v3 container) and remove the adapter. -### 12.9 Limitations +### 11.9 Limitations - The adapter exposes the BGL graph as **read-only** to graph-v3. Mutation must continue to go through BGL APIs (`add_vertex`, `add_edge`). - `partition_id`, `num_partitions`, and other multi-partition CPOs are not provided; graph-v3 defaults to a single partition, which is correct for plain BGL graphs. - Algorithms that require `ranges::sized_range` on `edges(g, u)` (rare) need the BGL graph to use a sized out-edge container (`vecS`, `setS`). -- If `vertex_descriptor` is a pointer or opaque type, the integer-id assumption in `vertex_id` / `target_id` does not hold; see §12.6. +- If `vertex_descriptor` is a pointer or opaque type, the integer-id assumption in `vertex_id` / `target_id` does not hold; see §11.6. + +--- + +# Appendices + +## Appendix A. Algorithm Gap Analysis + +### Algorithms Present in Both Libraries + +#### Traversal +| Algorithm | BGL | graph-v3 | Interface Differences | +|-----------|-----|----------|-----------------------| +| **BFS** | `breadth_first_search(g, s, visitor(v).color_map(c))` | `breadth_first_search(g, sources, visitor)` | graph-v3: multi-source native, no color map, concept-checked visitor | +| **DFS** | `depth_first_search(g, visitor(v).color_map(c))` | `depth_first_search(g, sources, visitor)` | graph-v3: edge classification (tree/back/forward_or_cross), multi-source | +| **Topological Sort** | `topological_sort(g, back_inserter(order))` | `topological_sort(g, output_iter)` | Both use output iterators; graph-v3 returns bool (cycle detection); also `vertices_topological_sort(g)` lazy view | + +#### Shortest Paths +| Algorithm | BGL | graph-v3 | Interface Differences | +|-----------|-----|----------|-----------------------| +| **Dijkstra** | `dijkstra_shortest_paths(g, s, weight_map(w).distance_map(d).predecessor_map(p))` | `dijkstra_shortest_paths(g, sources, dist_fn, pred_fn, weight_fn, visitor)` | graph-v3: function-object properties, multi-source, custom compare/combine | +| **Bellman-Ford** | `bellman_ford_shortest_paths(g, N, weight_map(w).distance_map(d))` | `bellman_ford_shortest_paths(g, sources, dist_fn, pred_fn, weight_fn, visitor)` | Similar; graph-v3 detects negative cycles via visitor | + +#### Minimum Spanning Tree +| Algorithm | BGL | graph-v3 | Interface Differences | +|-----------|-----|----------|-----------------------| +| **Kruskal MST** | `kruskal_minimum_spanning_tree(g, back_inserter(mst))` | `kruskal(edges, mst_output)` | graph-v3 works on edge lists directly; also `inplace_kruskal` | +| **Prim MST** | `prim_minimum_spanning_tree(g, pmap)` | `prim(g, source, mst_output, weight_fn)` | graph-v3 takes a source; thin wrapper over `dijkstra_shortest_paths` | + +#### Connectivity +| Algorithm | BGL | graph-v3 | Interface Differences | +|-----------|-----|----------|-----------------------| +| **Connected Components** | `connected_components(g, comp_map)` | `connected_components(g, comp_fn)` | graph-v3 uses function objects | +| **Strong Components** | `strong_components(g, comp_map)` | `kosaraju(g, comp_fn)` + `tarjan_scc(g, comp_fn)` | graph-v3 has both Kosaraju and Tarjan; `tarjan_scc.hpp` is **not** in `algorithms.hpp` umbrella (include directly) | +| **Biconnected Components** | `biconnected_components(g, comp_map)` | `biconnected_components(g, output)` | Similar | +| **Articulation Points** | `articulation_points(g, back_inserter(art))` | `articulation_points(g, output_iter)` | Similar | + +### Algorithms in BGL but MISSING from graph-v3 + +#### Shortest Paths (3 missing) +| Algorithm | Priority | Difficulty | Notes | +|-----------|----------|------------|-------| +| **A\* Search** | 🔴 High | Medium | Heavily used; needs heuristic function concept | +| **Johnson All-Pairs** | 🟡 Medium | Medium | Builds on Dijkstra + Bellman-Ford (both exist) | +| **Floyd-Warshall** | 🟡 Medium | Low | O(V³) all-pairs; straightforward implementation | +| **DAG Shortest Paths** | 🟢 Low | Low | Linear-time on DAGs; topological sort + relaxation | + +#### Network Flow (7 missing) +| Algorithm | Priority | Difficulty | Notes | +|-----------|----------|------------|-------| +| **Edmonds-Karp Max Flow** | 🔴 High | Medium | Core max-flow; needs `edge_reverse` and `residual_capacity` properties | +| **Push-Relabel Max Flow** | 🟡 Medium | High | Higher performance than Edmonds-Karp | +| **Boykov-Kolmogorov Max Flow** | 🟡 Medium | High | Used in computer vision | +| **Stoer-Wagner Min Cut** | 🟡 Medium | Medium | Undirected min-cut | +| **Cycle Canceling (min-cost flow)** | 🟢 Low | High | Specialized | +| **Successive Shortest Path** | 🟢 Low | High | Min-cost flow variant | +| **Find Flow Cost** | 🟢 Low | Low | Utility for min-cost flow | + +#### Matching (2 missing) +| Algorithm | Priority | Difficulty | Notes | +|-----------|----------|------------|-------| +| **Max Cardinality Matching** | 🟡 Medium | Medium | Useful for bipartite problems | +| **Maximum Weighted Matching** | 🟢 Low | High | Complex implementation | + +#### Coloring (2 missing) +| Algorithm | Priority | Difficulty | Notes | +|-----------|----------|------------|-------| +| **Sequential Vertex Coloring** | 🟡 Medium | Low | Simple greedy coloring | +| **Edge Coloring** | 🟢 Low | Medium | Vizing's theorem | + +#### Planarity (7 missing) +| Algorithm | Priority | Difficulty | Notes | +|-----------|----------|------------|-------| +| **Boyer-Myrvold Planarity Test** | 🟡 Medium | High | Core planarity test | +| **Kuratowski Subgraph** | 🟢 Low | High | Planarity certificate | +| **Chrobak-Payne Drawing** | 🟢 Low | High | Planar graph drawing | +| **Planar Canonical Ordering** | 🟢 Low | High | For planar drawings | +| **Planar Face Traversal** | 🟢 Low | Medium | Dual graph operations | +| **Make Biconnected/Connected/Maximal Planar** | 🟢 Low | Medium | Graph augmentation | + +#### Isomorphism (3 missing) +| Algorithm | Priority | Difficulty | Notes | +|-----------|----------|------------|-------| +| **Graph Isomorphism** | 🟡 Medium | High | General isomorphism test | +| **VF2 Subgraph Isomorphism** | 🟡 Medium | High | Pattern matching in graphs | +| **McGregor Common Subgraphs** | 🟢 Low | High | Maximum common subgraph | + +#### Centrality & Metrics (7 missing) +| Algorithm | Priority | Difficulty | Notes | +|-----------|----------|------------|-------| +| **Betweenness Centrality** | 🔴 High | Medium | Widely used in network analysis | +| **PageRank** | 🔴 High | Low | Iterative; straightforward | +| **Degree Centrality** | 🟡 Medium | Low | Trivial with `degree()` CPO | +| **Closeness Centrality** | 🟡 Medium | Medium | Requires all-pairs shortest paths | +| **Clustering Coefficient** | 🟡 Medium | Low | Related to existing triangle count | +| **Eccentricity** | 🟢 Low | Medium | Max distance from vertex | +| **Geodesic Distance** | 🟢 Low | Medium | Average shortest path | + +#### Ordering & Bandwidth (6 missing) +| Algorithm | Priority | Difficulty | Notes | +|-----------|----------|------------|-------| +| **Cuthill-McKee Ordering** | 🟡 Medium | Medium | Bandwidth reduction; used in sparse matrix solvers | +| **King Ordering** | 🟢 Low | Medium | Profile reduction | +| **Sloan Ordering** | 🟢 Low | Medium | Wavefront reduction | +| **Minimum Degree Ordering** | 🟢 Low | High | Fill-reduction ordering | +| **Smallest Last Ordering** | 🟢 Low | Low | Coloring heuristic | +| **Bandwidth/Profile/Wavefront** | 🟢 Low | Low | Metrics only | + +#### Cycle Detection (3 missing) +| Algorithm | Priority | Difficulty | Notes | +|-----------|----------|------------|-------| +| **Tiernan All Cycles** | 🟢 Low | Medium | Enumerate all cycles | +| **Hawick Circuits** | 🟢 Low | Medium | All elementary circuits | +| **Howard Cycle Ratio** | 🟢 Low | High | Min/max cycle ratio | + +#### DAG & Closure (3 missing) +| Algorithm | Priority | Difficulty | Notes | +|-----------|----------|------------|-------| +| **Transitive Closure** | 🟡 Medium | Medium | Used in dependency analysis | +| **Transitive Reduction** | 🟡 Medium | Medium | Minimal equivalent DAG | +| **Dominator Tree** | 🟢 Low | High | Compiler/control flow analysis | + +#### Layout (5 missing) +| Algorithm | Priority | Difficulty | Notes | +|-----------|----------|------------|-------| +| **Fruchterman-Reingold** | 🟡 Medium | Medium | Force-directed layout | +| **Kamada-Kawai** | 🟡 Medium | Medium | Spring layout | +| **Gursoy-Atun** | 🟢 Low | Medium | Topology-based layout | +| **Circle Layout** | 🟢 Low | Low | Trivial | +| **Random Layout** | 🟢 Low | Low | Trivial | + +#### Other (8 missing) +| Algorithm | Priority | Difficulty | Notes | +|-----------|----------|------------|-------| +| **Core Numbers** | 🟡 Medium | Medium | k-core decomposition | +| **Maximum Adjacency Search** | 🟡 Medium | Medium | Used by Stoer-Wagner | +| **Bipartite Test** | 🟡 Medium | Low | BFS-based 2-coloring | +| **TSP Approximation** | 🟢 Low | Medium | Metric TSP heuristic | +| **Random Spanning Tree** | 🟢 Low | Medium | Wilson's algorithm | +| **Copy Graph** | 🟡 Medium | Low | Cross-type copy with property mapping | +| **Bron-Kerbosch All Cliques** | 🟢 Low | Medium | Maximal clique enumeration | +| **Create Condensation Graph** | 🟢 Low | Low | DAG from SCC | + +### Algorithms in graph-v3 but NOT in BGL + +| Algorithm | Header | Notes | +|-----------|--------|-------| +| **Jaccard Coefficient** | `jaccard.hpp` | Similarity metric for adjacent vertex neighborhoods | +| **Label Propagation** | `label_propagation.hpp` | Community detection algorithm | +| **Maximal Independent Set** | `mis.hpp` | Greedy MIS | +| **Triangle Count** | `tc.hpp` | `triangle_count()` and `directed_triangle_count()` | +| **Afforest** | `connected_components.hpp` | Parallel-friendly connected components (Sutton et al.) | --- -## 13. Recommended Extensions & Roadmap +## Appendix B. Recommended Extensions & Roadmap + +This roadmap is for graph-v3 maintainers: a phased plan for closing the parity gaps in [Appendix A](#appendix-a-algorithm-gap-analysis). It is not a migration task list for BGL users. ### Phase 1: Critical Migration Enablers (High Priority) @@ -1244,9 +1275,37 @@ namespace graph::compat { > **Recommendation:** A compatibility shim should be provided as a **separate, non-standardized** header — not part of the core library. It serves as a migration aid, not a long-term API. +### Standardization Strategy: Boost Incubation + +A recurring objection to standardizing graph-v3 is the absence of field usage — the design has not yet been validated by a real user base. This is an evidence gap, not a design flaw, and WG21/LEWG explicitly weigh "existing practice" when evaluating library proposals. + +**Strategy: ship graph-v3 to Boost as a modern successor to BGL ("BGL2") to gather users, then feed the resulting field experience back into the standards proposals (P3126–P3131, P3337).** + +Why this strengthens — rather than competes with — the `std::graph` goal: + +- **It directly answers the objection.** Boost adoption produces real users, bug reports, performance data versus BGL, and API-friction reports that paper review cannot surface. +- **Strong precedent.** `filesystem`, `optional`, `variant`, `any`, and networking (`asio`) all incubated in Boost before moving toward `std`. A Boost library *is* existing practice. +- **Right audience.** Boost users are standards-aware early adopters who will exercise the concept constraints, CPO ergonomics, error-message quality, and adaptor composition that most need validation. +- **Built-in migration population.** Positioning as "modern BGL" inherits BGL's mindshare and gives the library an immediate user base (the audience this document serves). + +**Packaging guidance (avoid a fork):** + +- Keep the **canonical source in `namespace graph`** (the working name that migrates cleanly to `std::graph`). +- Present the Boost-facing name (e.g. `boost::graph2` or `boost::graph::v2`) as an **alias / inline-namespace layer** over the canonical namespace, **not** a rename or fork. One source of truth, two presented names. This keeps the eventual `std::graph` migration a near-mechanical re-alias. +- Use Boost's pre-acceptance "no stability guarantee" window to keep refining the design while usage data accrues, so a Boost release does not prematurely calcify the API/ABI that the proposal depends on. + +**Scope discipline:** the standardization core is the container / concept / CPO / traversal foundation (the core categories average ~75% in [Appendix C](#appendix-c-migration-readiness-scorecard)). Ship that foundation to Boost to validate it; the specialist algorithm domains still at 0% in Appendix A (flow, matching, coloring, planarity, isomorphism, ordering, layout) can land incrementally and block neither the Boost review nor the proposal. + +**Sequencing:** + +1. Boost release as "modern BGL," canonical `namespace graph` with a Boost-facing alias layer. +2. Collect usage: bug reports, benchmarks versus BGL, ergonomics/API-friction reports, and real-world coexistence testing of the CPO-suppresses-ADL behavior (see §11). +3. Feed refinements back into P3126–P3131 / P3337 as field-experience evidence. +4. Re-alias the validated subset into `std::graph`. + --- -## Summary: Migration Readiness Scorecard +## Appendix C. Migration Readiness Scorecard The scores below are directional editorial estimates, not audited counts. @@ -1254,8 +1313,8 @@ The scores below are directional editorial estimates, not audited counts. |----------|-------------|-------------------|-------| | **Core graph types** | 8 containers | 3 containers + zero-config | 60% | | **Concepts & traits** | 18+ concepts | 9 concepts (broader) | 80% (by design) | -| **Property system** | Interior + exterior + bundled | Single value + external maps | 70% | -| **Traversal algorithms** | BFS, DFS, undirected DFS | BFS, DFS + lazy views | 90% | +| **Property system** | Interior + exterior + bundled (tag-dispatched) | Single `VV`/`EV` value (struct for multiple fields) + `container_value_fn` / `vertex_property_map` for external maps; tag dispatch eliminated by design | 100% (by design) | +| **Traversal algorithms** | BFS, DFS, undirected DFS, topological sort | BFS, DFS, topological sort + lazy views | 100% | | **Shortest paths** | 8 algorithms | 2 algorithms | 25% | | **MST** | 2 algorithms | 2 algorithms (+ in-place) | 100% | | **Connectivity** | 5 algorithms | 5 algorithms | 100% | @@ -1270,9 +1329,14 @@ The scores below are directional editorial estimates, not audited counts. | **Graph adaptors** | 5 adaptors | 3 (transpose, filtered, BGL adaptor) | 60% | | **Graph I/O** | 5 formats | 3 (DOT, GraphML, JSON) | 60% | | **Graph generators** | 6 generators | 4 (path, grid, Erdős–Rényi, Barabási–Albert) | 67% | -| **Visitors** | 5 types + composable adaptors | Concept-checked visitors | 75% | -| **Graph mutation** | Full `MutableGraph` concept | Partial (undirected only) | 40% | +| **Visitors** | 5 types + composable adaptors | Concept-checked visitors + composable adaptors (`make_visitor`, `on_*` event wrappers, `predecessor_recorder`, `distance_recorder`, `time_stamper`). The remaining unimplemented visitor events are related to colored tranversal not supported in graph-v3. | 90% | +| **Graph mutation** | Full `MutableGraph` concept (CPOs) | Member-function mutation on both `dynamic_graph` and `undirected_adjacency_list`; no mutating CPOs | 70% | + +**Overall estimated BGL API coverage: ~46%** + +The unweighted average across all 20 scorecard rows is now ~46%, but the picture splits sharply: -**Overall estimated BGL API coverage: ~33%** +- **Core/everyday categories** (graph types, architecture, properties, traversal, MST, connectivity, I/O, adaptors, generators, visitors, mutation — 12 rows): average ~75%. For a BGL user doing graph construction, traversal, shortest paths, MST, or connectivity work, graph-v3 covers the vast majority of the API surface. +- **Specialist algorithm domains** (network flow, matching, coloring, planarity, isomorphism, ordering, layout — 7 rows): all at 0%, and these pull the overall figure down significantly. -The coverage that exists is architecturally superior (C++20, ranges, concepts, CPOs, zero-config), and the library includes novel features (lazy traversal views, triangle counting, label propagation, Jaccard similarity) not found in BGL. The primary migration barrier is breadth of algorithm and utility coverage. +The coverage that exists is architecturally superior (C++20, ranges, concepts, CPOs, zero-config), and the library includes novel features (lazy traversal views, triangle counting, label propagation, Jaccard similarity) not found in BGL. The primary migration barrier is breadth of specialist algorithm coverage.