diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..b02b520 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,37 @@ +# Normalize text files and keep LF in this repository. +* text=auto eol=lf + +# Source and build files +*.c text eol=lf +*.cc text eol=lf +*.cpp text eol=lf +*.cxx text eol=lf +*.h text eol=lf +*.hh text eol=lf +*.hpp text eol=lf +*.hxx text eol=lf +*.ixx text eol=lf +*.cmake text eol=lf +CMakeLists.txt text eol=lf + +# Scripts +*.sh text eol=lf +*.ps1 text eol=lf + +# Docs and config +*.md text eol=lf +*.dot text eol=lf +*.svg text eol=lf +*.yml text eol=lf +*.yaml text eol=lf +*.json text eol=lf +*.toml text eol=lf +*.txt text eol=lf + +# Keep common binary assets untouched +*.png binary +*.jpg binary +*.jpeg binary +*.gif binary +*.webp binary +*.pdf binary diff --git a/.vscode/settings.json b/.vscode/settings.json index 129b157..d1d6d85 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,8 +1,8 @@ -{ - "cmake.configureOnOpen": false, - "cmake.preferredGenerators": [ - "Ninja" - ], - "cmake.generator": "Ninja", - "cmake.cmakePath": "cmake" -} +{ + "cmake.configureOnOpen": false, + "cmake.preferredGenerators": [ + "Ninja" + ], + "cmake.generator": "Ninja", + "cmake.cmakePath": "cmake" +} diff --git a/docs/assets/adjacency_list_concepts.dot b/docs/assets/adjacency_list_concepts.dot index 7b57fca..0f54976 100644 --- a/docs/assets/adjacency_list_concepts.dot +++ b/docs/assets/adjacency_list_concepts.dot @@ -11,43 +11,43 @@ digraph ConceptHierarchy { node [fillcolor="#cce5ff"] // light blue - basic_edge_c [label="basic_edge\nsource_id · target_id\n(shared with edge_list)"] - edge_c [label="edge\nbasic_edge\n+ source · target"] - vertex_c [label="vertex\nvertex_descriptor\nvertex_id · find_vertex"] - hashable_vertex_id [label="hashable_vertex_id\nhash(vertex_id_t)"] + basic_edge_c [label="basic_edge\nsource_id(g, e)\ntarget_id(g, e)\n(shared with edge_list)"] + edge_c [label="edge\nbasic_edge\nsource(g, e)\ntarget(g, e)"] + vertex_c [label="vertex\nis_vertex_descriptor_v\nvertex_id(g, u)\nfind_vertex(g, uid)"] + hashable_vertex_id [label="hashable_vertex_id\nhash>{}(uid) → size_t"] // ── Range concepts ──────────────────────────────────────────────────────── // Built from primitives; parameterised on a range type R node [fillcolor="#d4edda"] // light green - out_edge_range [label="out_edge_range\nforward_range of edge"] - in_edge_range [label="in_edge_range\nforward_range of edge"] - vertex_range [label="vertex_range\nforward_range + sized_range\nof vertex"] + out_edge_range [label="out_edge_range\nforward_range\nedge>"] + in_edge_range [label="in_edge_range\nforward_range\nedge>"] + vertex_range [label="vertex_range\nforward_range ∧ sized_range\nvertex>"] // ── Vertex range refinements ────────────────────────────────────────────── node [fillcolor="#fff3cd"] // light yellow - index_vertex_range [label="index_vertex_range\nintegral vid\nintegral storage_type"] - mapped_vertex_range [label="mapped_vertex_range\n!index_vertex_range\nhashable_vertex_id\nfind_vertex"] + index_vertex_range [label="index_vertex_range\nintegral>\nintegral::storage_type>"] + mapped_vertex_range [label="mapped_vertex_range\n¬index_vertex_range\nhashable_vertex_id\nfind_vertex(g, uid)"] // ── Core graph concepts ─────────────────────────────────────────────────── node [fillcolor="#f8d7da"] // light red/salmon - adjacency_list [label="adjacency_list\nvertex_range + out_edge_range"] - ordered_vertex_edges [label="ordered_vertex_edges\nadjacency_list\n+ edges sorted by target_id"] - bidirectional_adjacency_list [label="bidirectional_adjacency_list\nadjacency_list\n+ in_edge_range"] + adjacency_list [label="adjacency_list\nvertices(g) → vertex_range\nout_edges(g, u) → out_edge_range"] + ordered_vertex_edges [label="ordered_vertex_edges\nadjacency_list\nout_edges(g, u) sorted by target_id"] + bidirectional_adjacency_list [label="bidirectional_adjacency_list\nadjacency_list\nin_edges(g, u) → in_edge_range"] - // ── Compound / specialised concepts ────────────────────────────────────── + // ── Compound / specialised concepts ─────────────────────────────────────── node [fillcolor="#e2d9f3"] // light purple - index_adjacency_list [label="index_adjacency_list\nadjacency_list\n+ index_vertex_range"] - mapped_adjacency_list [label="mapped_adjacency_list\nadjacency_list\n+ mapped_vertex_range"] - index_bidirectional_adjacency_list [label="index_bidirectional\n_adjacency_list\nbidirectional\n+ index_vertex_range"] - mapped_bidirectional_adjacency_list [label="mapped_bidirectional\n_adjacency_list\nbidirectional\n+ mapped_vertex_range"] + index_adjacency_list [label="index_adjacency_list\nadjacency_list ∧ index_vertex_range"] + mapped_adjacency_list [label="mapped_adjacency_list\nadjacency_list ∧ mapped_vertex_range"] + index_bidirectional_adjacency_list [label="index_bidirectional\n_adjacency_list\nbidirectional_adjacency_list ∧ index_vertex_range"] + mapped_bidirectional_adjacency_list [label="mapped_bidirectional\n_adjacency_list\nbidirectional_adjacency_list ∧ mapped_vertex_range"] // ── Edges (arrows = "is required by" / "refines") ───────────────────────── @@ -77,7 +77,7 @@ digraph ConceptHierarchy { adjacency_list -> index_adjacency_list index_vertex_range -> index_adjacency_list - adjacency_list -> mapped_adjacency_list + adjacency_list -> mapped_adjacency_list mapped_vertex_range -> mapped_adjacency_list bidirectional_adjacency_list -> index_bidirectional_adjacency_list diff --git a/docs/assets/adjacency_list_concepts.svg b/docs/assets/adjacency_list_concepts.svg index ee5fc31..86eda70 100644 --- a/docs/assets/adjacency_list_concepts.svg +++ b/docs/assets/adjacency_list_concepts.svg @@ -4,258 +4,260 @@ - - + + ConceptHierarchy - + basic_edge_c - -basic_edge<G,E> -source_id · target_id -(shared with edge_list) + +basic_edge<G,E> +source_id(g, e) +target_id(g, e) +(shared with edge_list) edge_c - -edge<G,E> -basic_edge -+ source · target + +edge<G,E> +basic_edge<G,E> +source(g, e) +target(g, e) basic_edge_c->edge_c - - + + out_edge_range - -out_edge_range<R,G> -forward_range of edge<G,·> + +out_edge_range<R,G> +forward_range<R> +edge<G, range_value_t<R>> edge_c->out_edge_range - - + + in_edge_range - -in_edge_range<R,G> -forward_range of edge<G,·> + +in_edge_range<R,G> +forward_range<R> +edge<G, range_value_t<R>> edge_c->in_edge_range - - + + vertex_c - -vertex<G,V> -vertex_descriptor -vertex_id · find_vertex + +vertex<G,V> +is_vertex_descriptor_v<V> +vertex_id(g, u) +find_vertex(g, uid) vertex_range - -vertex_range<R,G> -forward_range + sized_range -of vertex<G,·> + +vertex_range<R,G> +forward_range<R> ∧ sized_range<R> +vertex<G, range_value_t<R>> vertex_c->vertex_range - - + + hashable_vertex_id - -hashable_vertex_id<G> -hash(vertex_id_t<G>) + +hashable_vertex_id<G> +hash<vertex_id_t<G>>{}(uid) → size_t mapped_vertex_range - -mapped_vertex_range<G> -!index_vertex_range -hashable_vertex_id -find_vertex + +mapped_vertex_range<G> +¬index_vertex_range<G> +hashable_vertex_id<G> +find_vertex(g, uid) hashable_vertex_id->mapped_vertex_range - - + + adjacency_list - -adjacency_list<G> -vertex_range + out_edge_range + +adjacency_list<G> +vertices(g) → vertex_range<G> +out_edges(g, u) → out_edge_range<G> out_edge_range->adjacency_list - - + + bidirectional_adjacency_list - -bidirectional_adjacency_list<G> -adjacency_list -+ in_edge_range + +bidirectional_adjacency_list<G> +adjacency_list<G> +in_edges(g, u) → in_edge_range<G> in_edge_range->bidirectional_adjacency_list - - + + index_vertex_range - -index_vertex_range<G> -integral vid -integral storage_type + +index_vertex_range<G> +integral<vertex_id_t<G>> +integral<vertex_range_t<G>::storage_type> vertex_range->index_vertex_range - - + + vertex_range->mapped_vertex_range - - -  !index_vertex_range + + +  !index_vertex_range vertex_range->adjacency_list - - + + index_adjacency_list - -index_adjacency_list<G> -adjacency_list -+ index_vertex_range + +index_adjacency_list<G> +adjacency_list<G> ∧ index_vertex_range<G> index_vertex_range->index_adjacency_list - - + + index_bidirectional_adjacency_list - -index_bidirectional -_adjacency_list<G> -bidirectional -+ index_vertex_range + +index_bidirectional +_adjacency_list<G> +bidirectional_adjacency_list<G> ∧ index_vertex_range<G> index_vertex_range->index_bidirectional_adjacency_list - - + + mapped_adjacency_list - -mapped_adjacency_list<G> -adjacency_list -+ mapped_vertex_range + +mapped_adjacency_list<G> +adjacency_list<G> ∧ mapped_vertex_range<G> mapped_vertex_range->mapped_adjacency_list - - + + mapped_bidirectional_adjacency_list - -mapped_bidirectional -_adjacency_list<G> -bidirectional -+ mapped_vertex_range + +mapped_bidirectional +_adjacency_list<G> +bidirectional_adjacency_list<G> ∧ mapped_vertex_range<G> mapped_vertex_range->mapped_bidirectional_adjacency_list - - + + ordered_vertex_edges - -ordered_vertex_edges<G> -adjacency_list -+ edges sorted by target_id + +ordered_vertex_edges<G> +adjacency_list<G> +out_edges(g, u) sorted by target_id adjacency_list->ordered_vertex_edges - - + + adjacency_list->bidirectional_adjacency_list - - + + adjacency_list->index_adjacency_list - - + + adjacency_list->mapped_adjacency_list - - + + bidirectional_adjacency_list->index_bidirectional_adjacency_list - - + + bidirectional_adjacency_list->mapped_bidirectional_adjacency_list - - + + diff --git a/docs/assets/edge_list_concepts.dot b/docs/assets/edge_list_concepts.dot index 826885e..04ca41b 100644 --- a/docs/assets/edge_list_concepts.dot +++ b/docs/assets/edge_list_concepts.dot @@ -10,16 +10,16 @@ digraph EdgeListConceptHierarchy { node [fillcolor="#cce5ff"] // light blue - basic_edge [label="basic_edge\nsource_id · target_id\n(shared with adj_list)"] - basic_sourced_edgelist [label="basic_sourced_edgelist\ninput_range\n!range-of-ranges\nbasic_edge>"] + basic_edge [label="basic_edge\nsource_id(el, e)\ntarget_id(el, e)\n(shared with adj_list)"] + basic_sourced_edgelist [label="basic_sourced_edgelist\ninput_range\n¬range-of-ranges\nbasic_edge>"] // ── Refinements ─────────────────────────────────────────────────────────── node [fillcolor="#d4edda"] // light green - basic_sourced_index_edgelist [label="basic_sourced_index_edgelist\nbasic_sourced_edgelist\n+ integral source_id\n+ integral target_id"] + basic_sourced_index_edgelist [label="basic_sourced_index_edgelist\nbasic_sourced_edgelist\n∧ integral>\n∧ integral>"] - has_edge_value [label="has_edge_value\nbasic_sourced_edgelist\n+ edge_value(el, uv)"] + has_edge_value [label="has_edge_value\nbasic_sourced_edgelist\n∧ edge_value(el, uv) → edge_value_t"] // ── Edges ───────────────────────────────────────────────────────────────── diff --git a/docs/assets/edge_list_concepts.svg b/docs/assets/edge_list_concepts.svg index 451bf47..130133c 100644 --- a/docs/assets/edge_list_concepts.svg +++ b/docs/assets/edge_list_concepts.svg @@ -4,62 +4,63 @@ - - + + EdgeListConceptHierarchy - + basic_edge - -basic_edge<EL,E> -source_id · target_id -(shared with adj_list) + +basic_edge<EL,E> +source_id(el, e) +target_id(el, e) +(shared with adj_list) basic_sourced_edgelist - -basic_sourced_edgelist<EL> -input_range -!range-of-ranges -basic_edge<EL, range_value_t<EL>> + +basic_sourced_edgelist<EL> +input_range<EL> +¬range-of-ranges +basic_edge<EL, range_value_t<EL>> basic_edge->basic_sourced_edgelist - - + + basic_sourced_index_edgelist basic_sourced_index_edgelist<EL> -basic_sourced_edgelist -+ integral source_id -+ integral target_id +basic_sourced_edgelist<EL> +∧ integral<source_id_t<EL>> +∧ integral<target_id_t<EL>> basic_sourced_edgelist->basic_sourced_index_edgelist - - + + has_edge_value - -has_edge_value<EL> -basic_sourced_edgelist -+ edge_value(el, uv) + +has_edge_value<EL> +basic_sourced_edgelist<EL> +∧ edge_value(el, uv) → edge_value_t<EL> basic_sourced_edgelist->has_edge_value - - + + diff --git a/examples/BGLWorkshop2026/bglws_outline.md b/examples/BGLWorkshop2026/bglws_outline.md index 87f2f0b..24752d1 100755 --- a/examples/BGLWorkshop2026/bglws_outline.md +++ b/examples/BGLWorkshop2026/bglws_outline.md @@ -1,116 +1,116 @@ -# BGL Workshop Outline - -I (Phil) am scheduled to do a presentation to BGL users with Andrew on May 6, 2026. -We have 90 minutes with the following agenda: -- Retrospective on BGL and lessons learned over 26 years (Andrew) -- The nwgraph library using standard C++ containers (Andrew) -- graph-v3 and standardization (Phil) -- Graphs and agentic coding (Phil) - - Creating graph-v3 using vibe coding - - Observations on using an AI agent to convert BGL to use C++20 -- Q&A (15 minutes) - -Definitions and People -- BGL: Boost Graph Library written circa 2000 by Andrew Lumsdaine, et al -- graph-v3: A modern graph library using C++20 by Phil Ratzloff with contributors Andrew Lumsdaine - Kevin Deweese, and Scott McMillan. It was started in 2021 with the goal of adding it to the - C++ standard library. - -The following sections describe the organization of the presentation, but it may change as -it is refined. - -## Introduction to graph-v3 -This section compares graph-v3 with BGL - -### Kevin Bacon - -General Syntax differences -- Graph data: actors, directors, and movies - - Show graph image -- Problem(s): six degrees of Kevin Bacon - - Bacon number -- bacon1 - - graph construction - - edge iteration, views - - Bacon number -- bacon2 - - non-integral & sparse vertex ids - - building & constructing the bipartite graph - -### French Roads - - Dijkstra shortest_paths & shortest_distances - - properties - - internal: city_name, route_distance - - container_value_fn(distances) - -### Performance comparison -- P3337 - -### Agentic Coding - - graph-v3 - - bgl modernization - - algorithm demo (optional): Adamic-Adar Index, Transitive Closure - -### Parallel Narrative - -- goals: - - easy to use, natural C++20 style when used - - expressive - - performant -- SG19 - - getting started - - learn, grow (be open to critique, set aside ego) - - play with the big boys -- Discoveries - - ranges - - CPOs - - Descriptors -- Current State - -## Design -- Guiding Principles: simplicity, expressiveness, flexibility, performance - - use features & idioms in the C++20 std: ranges, concepts, r-value references, free functions (e.g. begin(r), end(r)), structured bindings, fnc objs -- Architecture - - Layers: algorithms, views, GCI, graph containers - - Data model: range-of-ranges as key abstraction supported & enforced by concepts - - algorithms writes to - - graphs are adapted to - - primitive functions (CPOs) and default impl - - values (std) vs. properties - - descriptors -- Views -- Algorithms - - visitors -- Graph Containers - - std-based container patterns - - library graphs: compressed_graph, dynamic_graph, undirected_graph - - BYOG; patterns supported - - typical integration - 4-7 fnc overloads - -## Feature Comparison BGL graph-v3 -- Create & init graph -- vertex & edge iteration -- concepts, traits, types - - graph_traits required only on dynamic_graph -- properties - -- Other BGL - - BGL wrapper - - -## Miscellaneous Notes (agent must ignore) - - BGL graph-v3 -Graph Defintion graph_traits - -properties: property maps vs. fnc objs, internal vs. external properties -concepts -parallel algorithms -distributed algorithms -features not supported (yet) -function creation -Examples: Kevin Bacon, social network, road network -iteration -key C++ features: ranges, concepts, structured bindings, constexpr -BYOG; patterns supported - +# BGL Workshop Outline + +I (Phil) am scheduled to do a presentation to BGL users with Andrew on May 6, 2026. +We have 90 minutes with the following agenda: +- Retrospective on BGL and lessons learned over 26 years (Andrew) +- The nwgraph library using standard C++ containers (Andrew) +- graph-v3 and standardization (Phil) +- Graphs and agentic coding (Phil) + - Creating graph-v3 using vibe coding + - Observations on using an AI agent to convert BGL to use C++20 +- Q&A (15 minutes) + +Definitions and People +- BGL: Boost Graph Library written circa 2000 by Andrew Lumsdaine, et al +- graph-v3: A modern graph library using C++20 by Phil Ratzloff with contributors Andrew Lumsdaine + Kevin Deweese, and Scott McMillan. It was started in 2021 with the goal of adding it to the + C++ standard library. + +The following sections describe the organization of the presentation, but it may change as +it is refined. + +## Introduction to graph-v3 +This section compares graph-v3 with BGL + +### Kevin Bacon + +General Syntax differences +- Graph data: actors, directors, and movies + - Show graph image +- Problem(s): six degrees of Kevin Bacon + - Bacon number +- bacon1 + - graph construction + - edge iteration, views + - Bacon number +- bacon2 + - non-integral & sparse vertex ids + - building & constructing the bipartite graph + +### French Roads + - Dijkstra shortest_paths & shortest_distances + - properties + - internal: city_name, route_distance + - container_value_fn(distances) + +### Performance comparison +- P3337 + +### Agentic Coding + - graph-v3 + - bgl modernization + - algorithm demo (optional): Adamic-Adar Index, Transitive Closure + +### Parallel Narrative + +- goals: + - easy to use, natural C++20 style when used + - expressive + - performant +- SG19 + - getting started + - learn, grow (be open to critique, set aside ego) + - play with the big boys +- Discoveries + - ranges + - CPOs + - Descriptors +- Current State + +## Design +- Guiding Principles: simplicity, expressiveness, flexibility, performance + - use features & idioms in the C++20 std: ranges, concepts, r-value references, free functions (e.g. begin(r), end(r)), structured bindings, fnc objs +- Architecture + - Layers: algorithms, views, GCI, graph containers + - Data model: range-of-ranges as key abstraction supported & enforced by concepts + - algorithms writes to + - graphs are adapted to + - primitive functions (CPOs) and default impl + - values (std) vs. properties + - descriptors +- Views +- Algorithms + - visitors +- Graph Containers + - std-based container patterns + - library graphs: compressed_graph, dynamic_graph, undirected_graph + - BYOG; patterns supported + - typical integration - 4-7 fnc overloads + +## Feature Comparison BGL graph-v3 +- Create & init graph +- vertex & edge iteration +- concepts, traits, types + - graph_traits required only on dynamic_graph +- properties + +- Other BGL + - BGL wrapper + + +## Miscellaneous Notes (agent must ignore) + + BGL graph-v3 +Graph Defintion graph_traits + +properties: property maps vs. fnc objs, internal vs. external properties +concepts +parallel algorithms +distributed algorithms +features not supported (yet) +function creation +Examples: Kevin Bacon, social network, road network +iteration +key C++ features: ranges, concepts, structured bindings, constexpr +BYOG; patterns supported +