Settle the interface names and the return-type caveats

docs/src/changelog.md

@@ -11,12 +11,12 @@ and edges used internally.
   terminology. The overloads for implementing a new `AbstractNamedGraph` are
   `encoded_graph(g)` (replaces `position_graph`, with a generic
   `EncodedGraphView` fallback so a graph type does not need to store an
-  integer graph), `encode_vertex(g, v)` (replaces `vertex_positions`), and
-  `decode_vertex(g, c)` (replaces `ordered_vertices`). Codes are not stable
+  integer graph), `encoded_vertex(g, v)` (replaces `vertex_positions`), and
+  `decoded_vertex(g, c)` (replaces `ordered_vertices`). Codes are not stable
   across mutation
   ([#178](https://github.com/ITensor/NamedGraphs.jl/pull/178)).
 - The `OrdinalIndexing` submodule is removed, so `vertices(g)[4th]` becomes
-  `decode_vertex(g, 4)`
+  `decoded_vertex(g, 4)`
   ([#178](https://github.com/ITensor/NamedGraphs.jl/pull/178)).
 - `vertices(g::Named[Di]Graph)` outputs a
   `Dictionaries.Indices` instead of the internal `OrderedIndices` type, which
@@ -25,7 +25,7 @@ and edges used internally.
   Vertices iterate in insertion order, which is stable under removals and
   therefore no longer matches the integer codes after removals, so code that
   aligns `vertices(g)` with results computed on the integer graph should
-  translate through `decode_vertex`
+  translate through `decoded_vertex`
   ([#178](https://github.com/ITensor/NamedGraphs.jl/pull/178)).
 - `edges(g)` outputs a lazy iterator instead of a `Vector`, like
   `edges(::SimpleGraph)` in Graphs.jl. Membership (`in`) matches `has_edge`,

docs/src/dev_interface.md

@@ -11,21 +11,21 @@ Subtype [`AbstractNamedGraph`](@ref) and overload the minimal interface below,
 the graph on integer vertex codes and the translation between names and codes.
 Everything else in the Graphs.jl interface has generic fallbacks in terms of
 these. Graph types that do not store an integer graph get a generic
-`EncodedGraphView` fallback for `encoded_graph` and only need `encode_vertex`
-and `decode_vertex`.
+`EncodedGraphView` fallback for `encoded_graph` and only need `encoded_vertex`
+and `decoded_vertex`.
 
 Vertex codes are not stable across mutation: adding or removing vertices may
 reassign the codes of other vertices.
 
 These names are `public` rather than exported, so reach them with
-`using NamedGraphs: encode_vertex` or by qualifying.
+`using NamedGraphs: encoded_vertex` or by qualifying.
 
 ```@docs; canonical=false
 encoded_graph
-encode_vertex
-decode_vertex
-encode_edge
-decode_edge
+encoded_vertex
+decoded_vertex
+encoded_edge
+decoded_edge
 ```
 
 ## Graphs.jl interface extensions

ext/NamedGraphsGraphsFlowsExt/NamedGraphsGraphsFlowsExt.jl

@@ -2,7 +2,7 @@ module NamedGraphsGraphsFlowsExt
 using Graphs: AbstractGraph, IsDirected
 using GraphsFlows: GraphsFlows
 using NamedGraphs: NamedGraphs, AbstractNamedGraph, DefaultNamedCapacity, _symmetrize,
-    decode_vertex, directed_graph, encode_dist_matrix, encode_vertex, encoded_graph
+    decoded_vertex, directed_graph, encode_dist_matrix, encoded_graph, encoded_vertex
 using SimpleTraits: SimpleTraits, @traitfn
 
 @traitfn function NamedGraphs.encode_dist_matrix(
@@ -20,13 +20,13 @@ end
     )
     encoded_part1, encoded_part2, flow = GraphsFlows.mincut(
         encoded_graph(graph),
-        encode_vertex(graph, source),
-        encode_vertex(graph, target),
+        encoded_vertex(graph, source),
+        encoded_vertex(graph, target),
         encode_dist_matrix(graph, capacity_matrix),
         algorithm
     )
     (part1, part2) = map((encoded_part1, encoded_part2)) do encoded_part
-        return map(c -> decode_vertex(graph, c), encoded_part)
+        return map(c -> decoded_vertex(graph, c), encoded_part)
     end
     return (part1, part2, flow)
 end

ext/NamedGraphsITensorVisualizationBaseExt/NamedGraphsITensorVisualizationBaseExt.jl

@@ -2,7 +2,7 @@ module NamedGraphsITensorVisualizationBaseExt
 
 using Graphs: vertices
 using ITensorVisualizationBase: ITensorVisualizationBase
-using NamedGraphs: AbstractNamedGraph, decode_vertex, encoded_graph
+using NamedGraphs: AbstractNamedGraph, decoded_vertex, encoded_graph
 
 function ITensorVisualizationBase.visualize(
         graph::AbstractNamedGraph,
@@ -14,7 +14,7 @@ function ITensorVisualizationBase.visualize(
     if !isnothing(vertex_labels_prefix)
         # In code order, to align with the vertices of `encoded_graph(graph)`.
         vertex_labels = [
-            vertex_labels_prefix * string(decode_vertex(graph, c)) for
+            vertex_labels_prefix * string(decoded_vertex(graph, c)) for
                 c in vertices(encoded_graph(graph))
         ]
     end

ext/NamedGraphsSimpleGraphAlgorithmsExt/NamedGraphsSimpleGraphAlgorithmsExt.jl

@@ -1,6 +1,6 @@
 module NamedGraphsSimpleGraphAlgorithmsExt
 using Graphs: AbstractGraph, dst, edges, edgetype, src, vertices
-using NamedGraphs: AbstractNamedGraph, decode_vertex, encoded_graph
+using NamedGraphs: AbstractNamedGraph, decoded_vertex, encoded_graph
 using SimpleGraphAlgorithms: SimpleGraphAlgorithms
 using SimpleGraphs: UndirectedGraph, add!
 
@@ -23,7 +23,7 @@ function SimpleGraphAlgorithms.edge_color(g::AbstractNamedGraph, k::Int64)
     return [
         [
                 edgetype(g)(
-                    decode_vertex(g, first(first(e))), decode_vertex(g, last(first(e)))
+                    decoded_vertex(g, first(first(e))), decoded_vertex(g, last(first(e)))
                 ) for
                 e in ec_dict if last(e) == i
             ]

src/NamedGraphs.jl

@@ -40,7 +40,7 @@ if VERSION >= v"1.11.0-DEV.469"
     # overload, so it is public rather than exported.
     eval(
         Meta.parse(
-            "public decode_edge, decode_vertex, encode_edge, encode_vertex, encoded_graph, to_graph_index"
+            "public decoded_edge, decoded_vertex, encoded_edge, encoded_graph, encoded_vertex, to_graph_index"
         )
     )
 end

src/PartitionedGraphs/abstractpartitionedgraph.jl

@@ -126,10 +126,7 @@ end
 
 The [`QuotientEdge`](@ref)s of `graph` that connect the given quotient vertices
 to the quotient vertices outside of them, i.e. the boundary edges of
-`quotientvertices` in the quotient graph of `graph`. Returns an `AbstractVector`
-of [`QuotientEdge`](@ref)s; the concrete type is not part of the interface, and
-the result may be a view into `graph`, so do not modify it or use it after
-mutating `graph`.
+`quotientvertices` in the quotient graph of `graph`.
 
 Keyword arguments are forwarded to `boundary_edges`, in
 particular `dir`, which selects the edge direction to consider in a directed
@@ -283,11 +280,11 @@ Graphs.edges(pg::AbstractPartitionedGraph) = edges(unpartitioned_graph(pg))
 function NamedGraphs.encoded_graph(pg::AbstractPartitionedGraph)
     return NamedGraphs.encoded_graph(unpartitioned_graph(pg))
 end
-function NamedGraphs.encode_vertex(pg::AbstractPartitionedGraph, vertex)
-    return NamedGraphs.encode_vertex(unpartitioned_graph(pg), vertex)
+function NamedGraphs.encoded_vertex(pg::AbstractPartitionedGraph, vertex)
+    return NamedGraphs.encoded_vertex(unpartitioned_graph(pg), vertex)
 end
-function NamedGraphs.decode_vertex(pg::AbstractPartitionedGraph, code::Integer)
-    return NamedGraphs.decode_vertex(unpartitioned_graph(pg), code)
+function NamedGraphs.decoded_vertex(pg::AbstractPartitionedGraph, code::Integer)
+    return NamedGraphs.decoded_vertex(unpartitioned_graph(pg), code)
 end
 Graphs.edgetype(pg::AbstractPartitionedGraph) = edgetype(unpartitioned_graph(pg))
 

src/PartitionedGraphs/quotientedge.jl

@@ -99,10 +99,6 @@ end
 
 Return the set of edges in the graph `g` that correspond to a single quotient edge or
 a list of quotient edges.
-
-As with `vertices(g, ::QuotientVertex)`, the result can alias the
-partitioning stored in `g`: treat it as read-only, discard it when `g` changes,
-and rely only on it being an `AbstractVector` of edges.
 """
 function Graphs.edges(pg::AbstractGraph, quotientedge::QuotientEdge)
     pes = partitioned_edges(pg)

src/PartitionedGraphs/quotientvertex.jl

@@ -71,14 +71,12 @@ end
 
 """
     vertices(g::AbstractGraph, quotientvertex::QuotientVertex)
-    vertices(g::AbstractGraph, quotientvertices::Vector{QuotientVertex})
+    vertices(g::AbstractGraph, quotientvertices::QuotientVertices)
 
 Return the set of vertices in the graph `g` associated with the quotient vertex
 `quotientvertex` or set of quotient vertices `quotientvertices`.
 
-The result can alias the partitioning stored in `g`, so do not modify it and do
-not use it after mutating `g`. Rely only on it being an `AbstractVector` of
-vertices.
+The result can alias the partitioning stored in `g`, so do not modify it.
 """
 function Graphs.vertices(g::AbstractGraph, quotientvertex::QuotientVertex)
     qv = parent(quotientvertex)

src/PartitionedGraphs/quotientview.jl

@@ -1,5 +1,5 @@
 using ..NamedGraphs: NamedGraph, directed_graph_type, encoded_graph_type,
-    induced_subgraph_from_vertices, similar_type, undirected_graph_type
+    induced_subgraph_from_vertices, parent_graph_type, similar_type, undirected_graph_type
 using Graphs: AbstractGraph, edges, has_edge, rem_edge!, rem_vertex!, vertices
 
 """
@@ -54,8 +54,7 @@ struct QuotientView{V, G <: AbstractGraph} <: AbstractNamedGraph{V}
 end
 
 Base.parent(qg::QuotientView) = qg.graph
-parent_graph_type(g::AbstractGraph) = parent_graph_type(typeof(g))
-parent_graph_type(::Type{<:QuotientView{V, G}}) where {V, G} = G
+NamedGraphs.parent_graph_type(::Type{<:QuotientView{V, G}}) where {V, G} = G
 
 Base.copy(qv::QuotientView) = copy(quotient_graph(parent(qv)))
 
@@ -90,11 +89,11 @@ function Graphs.rem_edge!(qg::QuotientView, e)
 end
 
 NamedGraphs.encoded_graph(g::QuotientView) = NamedGraphs.encoded_graph(copy(g))
-function NamedGraphs.encode_vertex(g::QuotientView, vertex)
-    return NamedGraphs.encode_vertex(copy(g), vertex)
+function NamedGraphs.encoded_vertex(g::QuotientView, vertex)
+    return NamedGraphs.encoded_vertex(copy(g), vertex)
 end
-function NamedGraphs.decode_vertex(g::QuotientView, code::Integer)
-    return NamedGraphs.decode_vertex(copy(g), code)
+function NamedGraphs.decoded_vertex(g::QuotientView, code::Integer)
+    return NamedGraphs.decoded_vertex(copy(g), code)
 end
 
 function NamedGraphs.similar_type(type::Type{<:QuotientView})