Gci paper (#123)

* Add GCI update strategy with all Q1-Q8 decisions resolved

Strategy document for updating D3130 Container Interface paper to match
graph-v3 implementation. All 8 open questions resolved:
- Q1: Hybrid exposition-only convention for descriptors
- Q2: Pass descriptors by value (full audit of 17 occurrences)
- Q3: Drop trait gate on edge<G,E>, no edge_list descriptors/views
- Q4: Keep adjacency matrix traits/concepts
- Q5: raw_vertex_id_t exposition-only, vertex_id_store_t normative
- Q6: Separate namespaces (std::graph::edge_list)
- Q7: vertex_property_map in GCI (D3130)
- Q8: source_id mandatory for descriptor-based edges

* Phase A: Rewrite D3130 source files to match graph-v3

- Delete concepts_edges_before.hpp and concepts_basic_adj_list.hpp
- Rewrite concepts_edges.hpp: single edge<G,E> concept (no trait gate, Q3)
- Rewrite concepts_target_edge_range.hpp: out_edge_range + in_edge_range
- Rewrite concepts_vertex_range.hpp: vertex<G,V>, vertex_range, index_vertex_range, mapped_vertex_range
- Rewrite concepts_adj_list.hpp: adjacency_list, bidirectional, index, mapped variants
- Rewrite descriptor.hpp: vertex_descriptor + edge_descriptor (exposition-only internals, Q1)
- Rewrite descriptor_view.hpp: vertex_descriptor_view + edge_descriptor_view
- Rewrite edgelist_concepts.hpp: 2-arg concepts in std::graph::edge_list namespace
- Rewrite edgelist_types.hpp: 2-arg type aliases, add raw_vertex_id_t, remove edge_reference_t
- Add descriptor_traits.hpp: is_vertex_descriptor, is_edge_descriptor, is_descriptor
- Update container_interface.tex: add lstinputlisting for descriptor.hpp and descriptor_traits.hpp
- Add gci_update_plan.md implementation plan

* Phase B: Update type alias and traits tables

- Traits table: update has_contains_edge to <G,V>, remove unordered/ordered edge
  traits, add bidirectional query traits (has_in_degree, has_find_in_edge,
  has_contains_in_edge), add compound traits (has_basic_queries, has_full_queries),
  note adjacency_matrix not yet in reference implementation
- Type alias table: already updated in Phase A amend (remove graph/vertex/edge
  _reference_t, add vertex_id_store_t, raw-vertex-id-type, out_edge_*/in_edge_*
  types, backward-compat aliases)

* Update phase overview with completion status

* Phase C: Update function tables and CPO names

- Graph table: rename has_edge(g)->has_edges(g), update default impl to use out_edges
- Vertex table: rename edges->out_edges, degree->out_degree; add in_edges, in_degree;
  note backward-compat aliases (edges, degree); update vertex_edge_range_t->out_edge_range_t
- Edge table: rename find_vertex_edge->find_out_edge, contains_edge->contains_out_edge;
  make source_id mandatory for descriptor-based edges (not optional); remove optional
  source_id separator; add find_in_edge, contains_in_edge rows; note backward-compat aliases
- Edgelist table: 1-arg->2-arg CPOs (target_id(e)->target_id(el,uv), etc.);
  update contains_edge lambda to use 2-arg forms; rename has_edge->has_edges
- Update prose references: edges(g,u)->out_edges(g,u), source_id(e)->source_id(el,uv), etc.
- Fix LaTeX errors from Phase B: \textit inside \tcode, vertex_t<G>{} braces

* Mark Phase C complete in plan

* Phase D: Rewrite concept sections

- Concepts intro: remove 'sourced' qualifier, add 'mapped' and 'bidirectional'
- Edge Concepts: single edge<G,E> concept; explain removal of targeted/sourced split;
  simplify return-type rationale; keep precedent note about sized_range
- Edge Range Concepts: explain out_edge_range + in_edge_range semantics
- Vertex Concepts: describe vertex<G,V>, index_vertex_range, mapped_vertex_range
- Adjacency List Concepts: list all 6 concepts and their axes; explain removal
  of basic_*/sourced_* variants due to descriptor design
- Edgelist Concepts: explain 2-arg form and three concept levels

* Mark Phase D complete in plan

* Phase E: Rewrite descriptor section with motivation and split architecture

- Add 'Why Descriptors?' motivation with comparison table (raw iterators vs descriptors)
- Add implicit vertex support explanation (index-based descriptors work without
  materialised vertex storage)
- Add automatic pattern recognition paragraph (random-access, associative, edge patterns)
- Replace old monolithic descriptor prose with split architecture description:
  vertex_descriptor<VertexIter> and edge_descriptor<EdgeIter,VertexIter,EdgeDirection>
- Fix inner_value() -> underlying_value(c) / inner_value(c) (container parameter required)
- Add pass-by-value convention paragraph (descriptors trivially copyable, const& only
  in requires clauses)
- Remove stale itemize list of descriptor properties (now covered in prose)
- Keep all three lstinputlisting calls: descriptor.hpp, descriptor_traits.hpp,
  descriptor_view.hpp

* Phase F: Update edgelist section — namespace, types table, edge_data patterns

- Remove \phil note from Namespace subsection
- Fix intro prose CPO args: source_id(el,e) -> source_id(el,uv) etc.
- Types table: remove edge_reference_t<EL>; add raw-vertex-id-type (exposition-only);
  update vertex_id_t definition to use source_id(el,uv) (consistent with edgelist_types.hpp)
- Pattern section: rename edge_info -> edge_data throughout (4 occurrences)
- Pattern section: add pair<integral,integral> pattern
- Pattern section: add edge_data reference variants:
    edge_data<VId,true,E&,void> and edge_data<VId,true,E&,EV>

* Phase G: Add data structs, value function concepts, vertex property map

- Add vertex_data/edge_data/neighbor_data struct families with specialization tables
- Add copyable_vertex_t/copyable_edge_t/copyable_neighbor_t helper alias table
- Add Value Function Concepts subsection: vertex_value_function, edge_value_function
- Add Vertex Property Map subsection: vertex_property_map<G,T> type alias,
  make_vertex_property_map (eager+lazy), vertex_property_map_contains,
  vertex_property_map_get
- Fix: use L{8cm} column spec in copyable_types table (arydshln requires at least one L column)
- Fix: remove texcl-interpreted comment from vertex_property_map lstlisting

* Phase H: Establish graph::adj_list and graph::edge_list as peer namespaces

- GCI intro: introduce both namespaces by name; explain that adj_list is re-exported
  to graph:: but edge_list is not (vertex_id_t conflict)
- Adjacency List Interface: add Namespace subsection explaining graph::adj_list,
  re-export to graph::, and when to use the qualified form
- Edgelist Interface: expand Namespace subsection to explain the peer relationship,
  contrast the two ADTs, and note the shared CPOs (source_id, target_id, edge_value)

* Phase H: Prose audit and revision history

- Traits table: fix has_degree comment degree->out_degree, has_find_vertex_edge
  comment find_vertex_edge->find_out_edge, has_contains_edge comment
  contains_edge->contains_out_edge (adj_list CPO names)
- Partition section: edges(g,uid,pid)/edges(g,u,pid) -> out_edges(g,uid,pid)/
  out_edges(g,u,pid)
- Revision history: add r4 entry summarising all descriptor, concept, CPO,
  type alias, data struct, namespace and edgelist changes from Phases A-H

* Phase J: Cross-paper fixups for algorithms and shared spec text

- tex/conventions.tex: vertex_reference_t<G> -> vertex_t<G> (descriptor row);
  edge_reference_t<G> -> edge_t<G> (edge descriptor row);
  vertex_info -> vertex_data (VProj description);
  edge_info -> edge_data (EProj description)
- tex/specification.tex: vertex_reference_t<G> -> vertex_t<G> in
  vertex_value(), has_degree, has_find_vertex_edge, adjacency_list,
  incidence(), neighbors() (6 occurrences)
- D3128_Algorithms/tex/algorithms.tex: edge_reference_t<G> -> edge_t<G>
  in basic_edge_weight_function and edge_weight_function concepts (2 occurrences)
- D3128_Algorithms and D3130_Container_Interface both build cleanly

* Update gci_update_plan and conventions.tex

Author: pratzl

D3128_Algorithms/tex/algorithms.tex

@@ -148,12 +148,12 @@ \subsection{Edge Weight Concepts}
       is_arithmetic_v<DistanceValue> && 
       strict_weak_order<Compare, DistanceValue, DistanceValue> &&
       assignable_from<add_lvalue_reference_t<DistanceValue>,
-            invoke_result_t<Combine, DistanceValue, invoke_result_t<WF, edge_reference_t<G>>>>;
+            invoke_result_t<Combine, DistanceValue, invoke_result_t<WF, edge_t<G>>>>;
 
 // For exposition only
 template <class G, class WF, class DistanceValue>
 concept edge_weight_function = // e.g. weight(uv)
-      is_arithmetic_v<invoke_result_t<WF, edge_reference_t<G>>> &&
+      is_arithmetic_v<invoke_result_t<WF, edge_t<G>>> &&
       basic_edge_weight_function<G,
                                   WF,
                                   DistanceValue,

D3130_Container_Interface/src/concepts_adj_list.hpp

@@ -1,21 +1,33 @@
 // For exposition only
 
-template <class G>                                 
-concept adjacency_list = vertex_range<G> &&        //
-                         targeted_edge_range<G> && //
-                         targeted_edge<G>;
+template <class G>
+concept adjacency_list = requires(G& g, vertex_t<G> u) {
+  { vertices(g) } -> vertex_range<G>;
+  { out_edges(g, u) } -> out_edge_range<G>;
+};
+
+template <class G>
+concept index_adjacency_list = adjacency_list<G> &&
+                               index_vertex_range<G>;
 
-template <class G>                                       
-concept index_adjacency_list = index_vertex_range<G> &&  //
-                               targeted_edge_range<G> && //
-                               targeted_edge<G>;
+template <class G>
+concept bidirectional_adjacency_list =
+    adjacency_list<G> &&
+    requires(G& g, vertex_t<G> u, in_edge_t<G> ie) {
+      { in_edges(g, u) } -> in_edge_range<G>;
+      { source_id(g, ie) } -> convertible_to<vertex_id_t<G>>;
+    };
+
+template <class G>
+concept index_bidirectional_adjacency_list =
+    bidirectional_adjacency_list<G> &&
+    index_vertex_range<G>;
 
 template <class G>
-concept sourced_adjacency_list = vertex_range<G> &&        //
-                                 targeted_edge_range<G> && //
-                                 sourced_targeted_edge<G>;
+concept mapped_adjacency_list = adjacency_list<G> &&
+                                mapped_vertex_range<G>;
 
 template <class G>
-concept sourced_index_adjacency_list = index_vertex_range<G> &&  //
-                                       targeted_edge_range<G> && //
-                                       sourced_targeted_edge<G>;
+concept mapped_bidirectional_adjacency_list =
+    bidirectional_adjacency_list<G> &&
+    mapped_vertex_range<G>;

D3130_Container_Interface/src/concepts_basic_adj_list.hpp

@@ -1,16 +1,9 @@
 // For exposition only
 
-template <class G>                                
-concept targeted_edge = requires(G&& g, edge_reference_t<G> uv) { 
-                            target(g, uv); 
-                            target_id(g, uv);
-                        };
-
-template <class G>                              
-concept sourced_edge = requires(G&& g, edge_reference_t<G> uv) { 
-                        source(g, uv); 
-                        source_id(g, uv);
-                    };
-
-template <class G>                                  
-concept sourced_targeted_edge = targeted_edge<G> && sourced_edge<G>;
+template <class G, class E>
+concept edge = requires(G& g, const E& e) {
+  source_id(g, e);
+  source(g, e);
+  target_id(g, e);
+  target(g, e);
+};

D3130_Container_Interface/src/concepts_edges.hpp

@@ -1,9 +1,9 @@
 // For exposition only
 
-template <class G>
-concept targeted_edge_range = 
-          basic_targeted_edge_range<G> &&
-          requires(G&& g, vertex_reference_t<G> u, vertex_id_t<G> uid) {
-            { edges(g, u) } -> forward_range;
-            { edges(g, uid) } -> forward_range; // implies call to find\_vertex(g,uid)
-          };
+template <class R, class G>
+concept out_edge_range = forward_range<R> &&
+                         edge<G, range_value_t<R>>;
+
+template <class R, class G>
+concept in_edge_range = forward_range<R> &&
+                        edge<G, range_value_t<R>>;

D3130_Container_Interface/src/concepts_edges_before.hpp

@@ -1,14 +1,28 @@
 // For exposition only
 
-template <class G>
-concept _common_vertex_range = ranges::sized_range<vertex_range_t<G>> &&
-                               requires(G&& g, vertex_iterator_t<G> ui) { vertex_id(g, ui); };
+template <class G, class V>
+concept vertex = requires(G& g, const V& u, const vertex_id_t<G>& uid) {
+  vertex_id(g, u);
+  find_vertex(g, uid);
+};
+
+template <class R, class G>
+concept vertex_range = forward_range<R> &&
+                       sized_range<R> &&
+                       vertex<G, remove_cvref_t<range_value_t<R>>>;
 
-template <class G>                                                
-concept vertex_range = _common_vertex_range<vertex_range_t<G>> &&
-                            forward_range<vertex_range_t<G>>;
+template <class G>
+concept index_vertex_range =
+    integral<vertex_id_t<G>> &&
+    integral<typename vertex_range_t<G>::storage_type> &&
+    requires(G& g) {
+      { vertices(g) } -> vertex_range<G>;
+    };
 
-template <class G>                                                             
-concept index_vertex_range = _common_vertex_range<vertex_range_t<G>> &&
-                                random_access_range<vertex_range_t<G>> &&
-                                integral<vertex_id_t<G>>;
+template <class G>
+concept mapped_vertex_range =
+    !index_vertex_range<G> &&
+    requires(G& g, const vertex_id_t<G>& uid) {
+      { vertices(g) } -> forward_range;
+      find_vertex(g, uid);
+    };

D3130_Container_Interface/src/concepts_target_edge_range.hpp

@@ -1,129 +1,81 @@
-template <forward_iterator InnerIter>
-class descriptor {
-public:
-  using inner_iterator   = InnerIter;
-  using inner_value_type = iter_value_t<inner_iterator>;
-  // preserve inner value constness based on inner\_iterator
-  using inner_reference = 
-            conditional_t<is_const_v<remove_reference_t<decltype(*declval<inner_iterator>())>>,
-                          add_lvalue_reference_t<std::add_const_t<inner_value_type>>,
-                          add_lvalue_reference_t<inner_value_type>>;
-  using inner_pointer = 
-            conditional_t<is_const_v<remove_reference_t<decltype(*declval<inner_iterator>())>>,
-                          add_pointer_t<std::add_const_t<inner_value_type>>,
-                          add_pointer_t<inner_value_type>>;
-
-  // Determine if this an index-based or iterator-based descriptor
-  using id_type    = ptrdiff_t; 
-  using value_type = conditional_t<random_access_iterator<inner_iterator>, id_type, inner_iterator>;
-
-  // Honor the const/non-const contract for the value type
-  using pointer       = std::add_pointer_t<value_type>;
-  using const_pointer = std::add_pointer_t<std::add_const_t<value_type>>;
-
-  using reference       = std::add_lvalue_reference_t<value_type>;
-  using const_reference = std::add_lvalue_reference_t<std::add_const_t<value_type>>;
-
-  using difference_type = std::iter_difference_t<inner_iterator>;
-
-  constexpr descriptor()                  = default;
-  constexpr descriptor(const descriptor&) = default;
-  constexpr descriptor(descriptor&&)      = default;
-  constexpr ~descriptor() noexcept        = default;
-
-  constexpr descriptor(InnerIter first, InnerIter it) : begin_(first);
-  constexpr descriptor(InnerIter first, ptrdiff_t id);
-
-  // for testing
-  template <forward_range R>
-  requires is_convertible_v<iterator_t<R>, InnerIter>
-  constexpr descriptor(R& r, inner_iterator it).
-
-  template <forward_range R>
-  requires is_convertible_v<iterator_t<R>, InnerIter>
-  constexpr descriptor(R& r, std::ptrdiff_t id = 0);
-
-  constexpr descriptor& operator=(const descriptor&) = default;
-  constexpr descriptor& operator=(descriptor&&) = default;
-
-  // Properies
+// For exposition only
+
+struct out_edge_tag {};
+struct in_edge_tag {};
+
+template <class VertexIter>
+class vertex_descriptor {
 public:
-  constexpr value_type& value() const noexcept;
+  using iterator_type = VertexIter;
+  using value_type    = iter_value_t<VertexIter>;
+
+  // index for random-access, iterator for bidirectional (for exposition only)
+  using storage_type =
+      conditional_t<random_access_iterator<VertexIter>, size_t, VertexIter>;
+
+  constexpr vertex_descriptor() = default;
+  constexpr explicit vertex_descriptor(storage_type val) noexcept;
 
-  constexpr inner_iterator get_inner_iterator() const;
+  // Properties
+  constexpr storage_type      value() const noexcept;
+  constexpr decltype(auto)    vertex_id() const noexcept;
 
-  [[nodiscard]] constexpr inner_reference inner_value() noexcept;
-  [[nodiscard]] constexpr inner_reference inner_value() const noexcept;
+  template <class Container>
+  constexpr decltype(auto) underlying_value(Container& c) const noexcept;
 
-  // Operators
+  template <class Container>
+  constexpr decltype(auto) inner_value(Container& c) const noexcept;
+
+  // Iterator-like interface
+  constexpr vertex_descriptor& operator++() noexcept;
+  constexpr vertex_descriptor  operator++(int) noexcept;
+
+  // Comparison
+  constexpr auto operator<=>(const vertex_descriptor&) const noexcept = default;
+  constexpr bool operator==(const vertex_descriptor&) const noexcept  = default;
+
+private:
+  storage_type storage_ = storage_type(); // for exposition only
+};
+
+
+template <class EdgeIter,
+          class VertexIter,
+          class EdgeDirection = out_edge_tag>
+class edge_descriptor {
 public:
-  //
-  // dereference
-  //
-  // Note: range concept requirement: decltype(*descriptor) == value\_type\&
-  [[nodiscard]] constexpr reference       operator*() noexcept;
-  [[nodiscard]] constexpr const_reference operator*() const noexcept;
-
-  [[nodiscard]] constexpr pointer       operator->() noexcept;
-  [[nodiscard]] constexpr const_pointer operator->() const noexcept;
-
-  //
-  // operator ++ += +
-  //
-  constexpr descriptor& operator++();
-  constexpr descriptor  operator++(int);
-
-  constexpr descriptor& operator+=(iter_difference_t<inner_iterator> n)
-  requires random_access_iterator<inner_iterator>;
-  constexpr descriptor operator+(iter_difference_t<inner_iterator> n) const
-  requires random_access_iterator<inner_iterator>;
-
-  //
-  // operator -- -= -
-  //
-  constexpr descriptor& operator--()
-  requires bidirectional_iterator<inner_iterator>;
-  constexpr descriptor operator--(int)
-  requires bidirectional_iterator<inner_iterator>;
-
-  constexpr descriptor& operator-=(iter_difference_t<inner_iterator> n)
-  requires random_access_iterator<inner_iterator>;
-  constexpr descriptor operator-(iter_difference_t<inner_iterator> n) const
-  requires random_access_iterator<inner_iterator>;
-
-  template <class InnerIter2>
-  constexpr iter_difference_t<inner_iterator> operator-(const descriptor<InnerIter2>& rhs) const
-  requires random_access_iterator<inner_iterator>;
-
-  //
-  // operator []
-  //
-  constexpr inner_reference operator[](iter_difference_t<inner_iterator> n) const
-  requires random_access_iterator<inner_iterator>;
-
-  //
-  // operators ==, <=>
-  //
-  constexpr bool operator==(const descriptor& rhs) const noexcept;
-
-  template <forward_iterator InnerIter2>
-  requires std::equality_comparable_with<InnerIter, InnerIter2>
-  constexpr bool operator==(const descriptor<InnerIter2>& rhs) const noexcept;
-
-  // for testing; useful in general?
-  template <forward_iterator InnerIter2>
-  requires std::equality_comparable_with<InnerIter, InnerIter2>
-  constexpr bool operator==(const InnerIter2& rhs) const noexcept;
-
-  constexpr auto operator<=>(const descriptor& rhs) const noexcept
-  requires std::integral<value_type> || std::random_access_iterator<inner_iterator>;
-
-  template <random_access_iterator InnerIter2>
-  requires std::three_way_comparable_with<InnerIter, InnerIter2> &&
-           (std::integral<value_type> || random_access_iterator<inner_iterator>)
-  constexpr auto operator<=>(const descriptor<InnerIter2>& rhs) const noexcept;
+  using edge_iterator_type   = EdgeIter;
+  using vertex_iterator_type = VertexIter;
+  using vertex_desc          = vertex_descriptor<VertexIter>;
+  using edge_direction       = EdgeDirection;
+
+  static constexpr bool is_in_edge  = is_same_v<EdgeDirection, in_edge_tag>;
+  static constexpr bool is_out_edge = is_same_v<EdgeDirection, out_edge_tag>;
+
+  // index for random-access, iterator for forward (for exposition only)
+  using edge_storage_type =
+      conditional_t<random_access_iterator<EdgeIter>, size_t, EdgeIter>;
+
+  constexpr edge_descriptor() = default;
+  constexpr edge_descriptor(edge_storage_type edge_val,
+                            vertex_desc source) noexcept;
+
+  // Properties
+  constexpr edge_storage_type value() const noexcept;
+  constexpr vertex_desc       source() const noexcept;
+  constexpr decltype(auto)    source_id() const noexcept;
+
+  template <class VertexData>
+  constexpr auto target_id(const VertexData& vd) const noexcept;
+
+  template <class VertexData>
+  constexpr decltype(auto) underlying_value(VertexData& vd) const noexcept;
+
+  // Comparison
+  constexpr auto operator<=>(const edge_descriptor&) const noexcept = default;
+  constexpr bool operator==(const edge_descriptor&) const noexcept  = default;
 
 private:
-  value_type     value_ = value_type();     // index or iterator (for exposition only)
-  inner_iterator begin_ = inner_iterator(); // begin of the inner range (for exposition only)
+  edge_storage_type edge_storage_ = edge_storage_type(); // for exposition only
+  vertex_desc       source_       = vertex_desc();       // for exposition only
 };