Bglws2

CHANGELOG.md

@@ -3,6 +3,14 @@
 ## [Unreleased]
 
 ### Added
+- **`filtered_graph` adaptor** (`adaptors/filtered_graph.hpp`) — non-owning wrapper that filters vertices and edges by predicate during traversal. Satisfies `adjacency_list` so all views and algorithms work transparently on the filtered subgraph. Uses self-contained `filtering_iterator` to avoid `std::views::filter` iterator dangling issues.
+- **BGL graph adaptor** (`adaptors/bgl/graph_adaptor.hpp`) — adapts Boost.Graph types for use with graph-v3 CPOs, views, and algorithms. Includes `bgl_edge_iterator.hpp` (C++20 iterator wrapper) and `property_bridge.hpp` (BGL property maps → graph-v3 value functions). Supports adjacency_list, CSR, and bidirectional BGL graphs.
+- `graph::adaptors::keep_all` — sentinel predicate (accepts everything, zero-overhead)
+- `graph::adaptors::filtering_iterator` — self-contained forward iterator with predicate stored in `std::optional` (custom assignment for lambda non-assignability)
+- `graph::adaptors::filtered_vertices(fg)` — lazy filtered vertex iteration convenience function
+- `graph::bgl::graph_adaptor` with CTAD, `graph_bgl_adl` namespace for ADL dispatch
+- `graph::bgl::make_bgl_edge_weight_fn`, `make_vertex_id_property_fn` — property bridge factories
+- 5 filtered_graph tests + 34 BGL adaptor test cases (107 assertions)
 - **Indexed d-ary heap for Dijkstra** (`detail/indexed_dary_heap.hpp`) — opt-in O(V)-bounded heap with true decrease-key, parameterized by arity. Selected via the new `use_indexed_dary_heap<Arity>` heap-selector tag on `dijkstra_shortest_paths` / `dijkstra_shortest_distances`. Supports both dense graphs (via `vector_position_map`) and mapped / hashable-vertex-id graphs (via `assoc_position_map`).
 - `use_default_heap` and `use_indexed_dary_heap<Arity>` heap-selector tags. **`use_default_heap` remains the default** — it wins on grid (E/V≈4) and path (E/V=1) workloads. Use `use_indexed_dary_heap<8>` for high-E/V random / scale-free graphs on `compressed_graph`, where Phase 4 benchmarks measured −25% (Erdős–Rényi) and −17% (Barabási–Albert) at 100K vertices vs. the default. See `agents/indexed_dary_heap_results.md` for full numbers.
 - `vector_position_map` / `assoc_position_map` adapters (`detail/heap_position_map.hpp`) used by the indexed heap.

README.md

@@ -13,7 +13,7 @@
 
 [![C++ Standard](https://img.shields.io/badge/C%2B%2B-20-blue.svg)](https://en.cppreference.com/w/cpp/20)
 [![License](https://img.shields.io/badge/license-BSL--1.0-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-4405%20passing-brightgreen.svg)](docs/status/metrics.md)
+[![Tests](https://img.shields.io/badge/tests-4874%20passing-brightgreen.svg)](docs/status/metrics.md)
 
 ---
 
@@ -24,10 +24,13 @@
 - **Works with your graphs** — Bring your own graph. `std::vector<std::vector<int>>` and `std::map<int, std::list<std::pair<int,double>>>` are also valid graphs out of the box.
 - **14 algorithms** — Dijkstra, Bellman-Ford, BFS, DFS, topological sort, connected components, Tarjan SCC, articulation points, biconnected components, MST, triangle counting, MIS, label propagation, Jaccard coefficient
 - **7 lazy views** — vertexlist, edgelist, incidence, neighbors, BFS, DFS, topological sort — all composable with range adaptors
+- **2 graph adaptors** — `filtered_graph` (vertex/edge predicate filtering), BGL interop adaptor
 - **Bidirectional edge access** — `in_edges`, `in_degree`, reverse BFS/DFS/topological sort via `in_edge_accessor`
 - **Customization Point Objects (CPOs)** — adapt existing data structures without modifying them
 - **3 containers, 27 trait combinations** — `dynamic_graph`, `compressed_graph`, `undirected_adjacency_list` with mix-and-match vertex/edge storage
-- **4405 tests passing** — comprehensive Catch2 test suite
+- **4 graph generators** — path, grid, Erdős–Rényi, Barabási–Albert for testing and benchmarking
+- **3 I/O formats** — DOT (GraphViz), GraphML (XML), JSON with zero-config `std::format`-based serialization
+- **4874 tests passing** — comprehensive Catch2 test suite
 
 ---
 
@@ -98,7 +101,10 @@ Both share a common descriptor system and customization-point interface.
 |----------|-----------------|---------|
 | **Algorithms** | Dijkstra, Bellman-Ford, BFS, DFS, topological sort, connected components, Tarjan SCC, articulation points, biconnected components, MST, triangle counting, MIS, label propagation, Jaccard | [Algorithm reference](docs/status/implementation_matrix.md#algorithms) |
 | **Views** | vertexlist, edgelist, incidence, neighbors, BFS, DFS, topological sort | [View reference](docs/status/implementation_matrix.md#views) |
+| **Adaptors** | `filtered_graph`, BGL `graph_adaptor` | [Adaptor reference](docs/user-guide/adaptors.md) |
 | **Containers** | `dynamic_graph` (27 trait combos), `compressed_graph` (CSR), `undirected_adjacency_list` | [Container reference](docs/status/implementation_matrix.md#containers) |
+| **Generators** | path, grid, Erdős–Rényi, Barabási–Albert | [Generator guide](docs/user-guide/generators.md) |
+| **I/O** | DOT (GraphViz), GraphML (XML), JSON | [I/O guide](docs/user-guide/io.md) |
 | **CPOs** | 19 customization point objects (vertices, edges, target_id, vertex_value, edge_value, …) | [CPO reference](docs/reference/cpo-reference.md) |
 | **Concepts** | 9 graph concepts (edge, vertex, adjacency_list, …) | [Concepts reference](docs/reference/concepts.md) |
 
@@ -195,4 +201,4 @@ Distributed under the [Boost Software License 1.0](LICENSE).
 ---
 
 <!-- Status counts pinned to docs/status/metrics.md -->
-**Status:** 4405 / 4405 tests passing · 13 algorithms · 7 views · 3 containers · 27 trait combinations · C++20 · BSL-1.0
+**Status:** 4874 / 4874 tests passing · 13 algorithms · 7 views · 2 adaptors · 3 containers · 4 generators · 3 I/O formats · 27 trait combinations · C++20 · BSL-1.0

agents/bgl_graph_adapt_goal.md

@@ -0,0 +1,78 @@
+# Enable the use of BGL graph data structures by graph-v3 views and algorithms
+
+I want algorithms and views in this library to work with graphs created in BGL.
+This will help BGL users explore this library before committing to it, and ease transition
+from BGL.
+
+## Definitions
+- `BGL`: Boost Graph Library
+- `CPO`: Customization Point Object
+
+## Requirements
+- Create ADL-based CPO customizations to adapt BGL graph types for use by views and algorithms
+  in this library.
+- Identify any additional features needed to enable the adaptation of BGL graphs. 
+  - Simple changes can be done immediately. 
+  - Tasks that take longer may require separate efforts to enable the adaptation.
+- Identify how readable and writable BGL property maps can be represented using this library's
+  `vertex_value_function` and `edge_value_function` concepts (function objects that access
+  properties on a vertex or edge).
+  - Function objects that expose writable properties should return a reference to the underlying
+    value.
+- Test the supported phase-1 BGL graph types and the graph-v3 views and algorithms intended to
+  work with them.
+- Create documentation to help BGL users use their graphs.
+
+## Scope & Priority
+Start with the most common BGL graph types and expand:
+1. `adjacency_list<vecS, vecS, directedS>` — most common BGL graph; `vecS` vertex lists
+   map naturally to `index_adjacency_list` because vertex descriptors are integral indices.
+2. Undirected and bidirectional variants (`undirectedS`, `bidirectionalS`).
+3. `compressed_sparse_row_graph` — valid phase-1 target because it matches `compressed_graph`
+  in the current library.
+4. Alternative vertex/edge selectors (`listS`, `setS`) — follow-on work after the phase-1
+  targets are working.
+5. `adjacency_matrix` — candidate for later expansion.
+
+## Phase-1 Adaptation Surface
+Phase 1 should establish the minimum graph interface needed for the initial BGL targets to work
+with graph-v3 views and algorithms. This includes support for:
+- Vertex and edge access used by graph-v3 concepts and algorithms, such as `vertices`,
+  `out_edges`, `vertex_id`, `source_id`, `target_id`, and `num_vertices`.
+- `in_edges` where bidirectional BGL graphs are part of the supported target set.
+- Property access for readable and writable vertex and edge properties.
+
+Detailed concept mapping, descriptor-model differences, and ID-mapping approaches for non-index
+descriptor types should be captured in `bgl_migration_strategy.md` rather than expanded here.
+
+## Phase-1 Views and Algorithms
+Phase 1 should prove that the adaptor works with a focused set of graph-v3 functionality:
+- Views: `vertexlist`, `incidence`, `neighbors`, and `edgelist`.
+- Algorithms: `dijkstra_shortest_paths` first, then the additional algorithms that naturally fit
+  the supported phase-1 graph types.
+
+## Acceptance Criteria
+- A BGL user can run graph-v3's `dijkstra_shortest_paths` on a
+  BGL `adjacency_list<vecS, vecS, directedS>` graph with minimal adaptor boilerplate.
+- A BGL user can run the phase-1 target views and algorithms on supported BGL graph types.
+- BGL property maps are accessible through graph-v3's function-object property interface,
+  including writable properties needed by algorithms such as shortest paths.
+- At least one end-to-end example and corresponding tests exist.
+- After all previous acceptance criteria are achieved, update `bgl_migration_strategy.md` with any
+  additional information that may be useful.
+
+## Other Information
+- A measure of success is a minimal set of work required by the BGL user to use their graphs.
+- `bgl2_comparison_query.md` and `bgl2_comparison_result.md` contain information for an experimental,
+  agent-assisted conversion of BGL to use C++20 and its idioms. They should be avoided because we want 
+  to focus on the active BGL library.
+- `bgl_migration_strategy.md` contains a comprehensive BGL → graph-v3 migration analysis;
+  Section 12 specifically covers adapting an existing BGL graph for graph-v3.
+- `uniform_prop_goal.md` defines the uniform property-function design that BGL property maps
+  must map into; progress on that effort may affect what is possible here.
+- `benchmark/algorithms/bgl_dijkstra_fixtures.hpp` already builds BGL and graph-v3 graphs
+  from identical edge sources and is a useful starting point.
+
+## References
+- BGL headers are at `/home/phil/dev_graph/boost/boost/graph/`
+- BGL source is at `/home/phil/dev_graph/boost/libs/graph/`