GraphOptInterface maintenance

.github/workflows/CI.yml

@@ -24,7 +24,7 @@ jobs:
       matrix:
         version:
           - '1.6'
-          - '1.8'
+          - '1.12'
           - 'nightly'
         os:
           - ubuntu-latest

Project.toml

@@ -12,7 +12,7 @@ SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
-DataStructures = "0.18"
+DataStructures = "0.18,0.19"
 Lazy="0.15"
 Graphs = "1.8"
 MathOptInterface = "1.6"

src/GraphOptInterface.jl

@@ -15,6 +15,12 @@ Abstract supertype for block-structure-exploiting optimizers.
 """
 abstract type AbstractGraphOptimizer <: MOI.AbstractOptimizer end
 
+"""
+    supports_graph_interface(optimizer::MOI.AbstractOptimizer)
+
+Check if the given optimizer supports the graph interface. Returns `false` for standard 
+MOI optimizers and `true` for `AbstractGraphOptimizer` subtypes.
+"""
 function supports_graph_interface(::MOI.AbstractOptimizer)
     return false
 end

src/GraphViews/bipartite.jl

@@ -8,10 +8,21 @@ mutable struct BipartiteGraph <: Graphs.AbstractGraph{Int64}
     vertexset1::Vector{Int64}
     vertexset2::Vector{Int64}
 end
+"""
+    BipartiteGraph()
+
+Construct an empty `BipartiteGraph` with no vertices or edges.
+"""
 function BipartiteGraph()
     return BipartiteGraph(Graphs.Graph(), Vector{Int64}(), Vector{Int64}())
 end
 
+"""
+    Graphs.add_vertex!(bgraph::BipartiteGraph; bipartite=1)
+
+Add a vertex to the bipartite graph. The `bipartite` keyword argument specifies
+which vertex set to add the vertex to (1 or 2). Returns the success status.
+"""
 function Graphs.add_vertex!(bgraph::BipartiteGraph; bipartite=1)
     added = Graphs.add_vertex!(bgraph.graph)
     vertex = Graphs.nv(bgraph.graph)
@@ -24,34 +35,91 @@ function Graphs.add_vertex!(bgraph::BipartiteGraph; bipartite=1)
     return added
 end
 
+"""
+    Graphs.add_edge!(bgraph::BipartiteGraph, from::Int64, to::Int64)
+
+Add an edge between vertices `from` and `to`. Enforces bipartite structure by
+requiring that the vertices be in different vertex sets.
+"""
 function Graphs.add_edge!(bgraph::BipartiteGraph, from::Int64, to::Int64)
     length(intersect((from, to), bgraph.vertexset1)) == 1 ||
         error("$from and $to must be in separate vertex sets")
     return Graphs.add_edge!(bgraph.graph, from, to)
 end
 
+"""
+    Graphs.edges(bgraph::BipartiteGraph)
+
+Return an iterator over all edges in the bipartite graph.
+"""
 Graphs.edges(bgraph::BipartiteGraph) = Graphs.edges(bgraph.graph)
 
+"""
+    Graphs.edgetype(bgraph::BipartiteGraph)
+
+Return the edge type for a bipartite graph (`SimpleEdge{Int64}`).
+"""
 Graphs.edgetype(bgraph::BipartiteGraph) = Graphs.SimpleGraphs.SimpleEdge{Int64}
 
+"""
+    Graphs.has_edge(bgraph::BipartiteGraph, from::Int64, to::Int64)
+
+Check if the bipartite graph has an edge from `from` to `to`.
+"""
 function Graphs.has_edge(bgraph::BipartiteGraph, from::Int64, to::Int64)
     return Graphs.has_edge(bgraph.graph, from, to)
 end
 
+"""
+    Graphs.has_vertex(bgraph::BipartiteGraph, v::Integer)
+
+Check if the bipartite graph contains vertex `v`.
+"""
 function Graphs.has_vertex(bgraph::BipartiteGraph, v::Integer)
     return Graphs.has_vertex(bgraph.graph, v)
 end
 
+"""
+    Graphs.is_directed(bgraph::BipartiteGraph)
+
+Bipartite graphs are undirected. Always returns `false`.
+"""
 Graphs.is_directed(bgraph::BipartiteGraph) = false
 
+"""
+    Graphs.is_directed(::Type{BipartiteGraph})
+
+Bipartite graphs are undirected. Always returns `false`.
+"""
 Graphs.is_directed(::Type{BipartiteGraph}) = false
 
+"""
+    Graphs.ne(bgraph::BipartiteGraph)
+
+Return the number of edges in the bipartite graph.
+"""
 Graphs.ne(bgraph::BipartiteGraph) = Graphs.ne(bgraph.graph)
 
+"""
+    Graphs.nv(bgraph::BipartiteGraph)
+
+Return the number of vertices in the bipartite graph.
+"""
 Graphs.nv(bgraph::BipartiteGraph) = Graphs.nv(bgraph.graph)
 
+"""
+    Graphs.vertices(bgraph::BipartiteGraph)
+
+Return a vector of all vertices in the bipartite graph.
+"""
 Graphs.vertices(bgraph::BipartiteGraph) = Graphs.vertices(bgraph.graph)
 
+"""
+    Graphs.adjacency_matrix(bgraph::BipartiteGraph)
+
+Return the adjacency matrix of the bipartite graph. Rows correspond to vertices
+in the first set, columns correspond to vertices in the second set.
+"""
 function Graphs.adjacency_matrix(bgraph::BipartiteGraph)
     n_v1 = length(bgraph.vertexset1)
     n_v2 = length(bgraph.vertexset2)
@@ -62,6 +130,18 @@ function Graphs.adjacency_matrix(bgraph::BipartiteGraph)
     return A
 end
 
+"""
+    identify_separators(bgraph::BipartiteGraph, partitions::Vector; cut_selector=Graphs.degree)
+
+Identify separator elements (cut vertices or cut edges) that separate the given `partitions`.
+The `cut_selector` parameter determines how to assign boundary elements to cuts. It can be:
+- A function (e.g., `Graphs.degree`) that compares element degrees
+- `:vertex` to always assign vertices as separators
+- `:edge` to always assign edges as separators
+
+Returns a tuple `(partition_elements, cross_elements)` where `partition_elements` are the 
+elements local to each partition and `cross_elements` are the separator elements.
+"""
 function identify_separators(
     bgraph::BipartiteGraph, partitions::Vector; cut_selector=Graphs.degree
 )
@@ -123,6 +203,21 @@ function identify_separators(
     return partition_elements, cross_elements
 end
 
+"""
+    induced_elements(bgraph::BipartiteGraph, partitions::Vector; cut_selector=Graphs.degree)
+
+Get the induced elements for each partition (i.e., elements local to each partition,
+excluding separators). This is a convenience function that returns only the first element
+of `identify_separators`.
+
+# Arguments
+- `bgraph::BipartiteGraph`: The bipartite graph
+- `partitions::Vector`: Vector of partitions
+- `cut_selector=Graphs.degree`: Selector for determining cut assignment (function, `:vertex`, or `:edge`)
+
+# Returns
+A vector of vectors, where each inner vector contains the induced elements for that partition.
+"""
 function induced_elements(
     bgraph::BipartiteGraph, partitions::Vector; cut_selector=Graphs.degree
 )