Merge branch 'main' into gd/decomp_bigger

Author: gdalle

src/graph.jl

@@ -150,23 +150,23 @@ function bidirectional_pattern(S::SparsityPatternCSC{T}; symmetric_pattern::Bool
         counter = 1
         for col in (n + 1):p
             nnz_col = colptr[col]
-            colptr[col] = counter
+            colptr[col] = nnzS + counter
             counter += nnz_col
         end
 
         for j in 1:n
             for index in S.colptr[j]:(S.colptr[j + 1] - 1)
                 i = S.rowval[index]
                 pos = colptr[n + i]
-                rowval[nnzS + pos] = j
-                edge_to_index[nnzS + pos] = edge_to_index[index]
+                rowval[pos] = j
+                edge_to_index[pos] = edge_to_index[index]
                 colptr[n + i] += 1
             end
         end
 
         colptr[p + 1] = nnzS + counter
         for col in p:-1:(n + 2)
-            colptr[col] = nnzS + colptr[col - 1]
+            colptr[col] = colptr[col - 1]
         end
         colptr[n + 1] = nnzS + 1
     end

src/order.jl

@@ -104,29 +104,41 @@ function vertices(bg::BipartiteGraph{T}, ::Val{side}, ::LargestFirst) where {T,s
     return sort(vertices(bg, Val(side)); by=criterion, rev=true)
 end
 
+const COLPACK_WARNING = """
+!!! danger
+    The option `reproduce_colpack=true` induces a large slowdown to mirror the original implementation details of ColPack, it should not be used in performance-sensitive applications.
+    This setting is mostly for the purpose of reproducing past research results which rely on implementation details.
+"""
+
 """
     DynamicDegreeBasedOrder{degtype,direction}(; reproduce_colpack=false)
 
 Instance of [`AbstractOrder`](@ref) which sorts vertices using a dynamically computed degree.
 
-!!! danger
-    This order is still experimental and needs more tests, correctness is not yet guaranteed.
+This order works by assigning vertices to buckets based on their dynamic degree, and then updating buckets iteratively by transfering vertices between them.
 
 # Type parameters
 
 - `degtype::Symbol`: can be `:forward` (for the forward degree) or `:back` (for the back degree)
 - `direction::Symbol`: can be `:low2high` (if the order is defined from lowest to highest, i.e. `1` to `n`) or `:high2low` (if the order is defined from highest to lowest, i.e. `n` to `1`)
 
-# Settings
-
-- `reproduce_colpack::Bool`: whether to manage the buckets in the same way as the original ColPack implementation. When `reproduce_colpack=true`, we always append and remove vertices from the end of a bucket, which incurs a large performance penalty because every modification requires a circular permutation of the corresponding bucket. This setting is mostly for the purpose of reproducing past research results which rely on implementation details.
-
 # Concrete variants
 
 - [`IncidenceDegree`](@ref)
 - [`SmallestLast`](@ref)
 - [`DynamicLargestFirst`](@ref)
 
+# Settings
+
+- `reproduce_colpack::Bool`: whether to manage the buckets in the exact same way as the original ColPack implementation.
+  - When `reproduce_colpack=true`, we always append and remove vertices at the end of a bucket (unilateral).
+  - When `reproduce_colpack=false` (the default), we can append and remove vertices either at the start or at the end of a bucket (bilateral).
+
+Allowing modifications on both sides of a bucket enables storage optimization, with a single fixed-size vector for all buckets instead of one dynamically-sized vector per bucket.
+Our implementation is optimized for this bilateral setting, which means we pay a large performance penalty to artificially imitate the unilateral setting.
+
+$COLPACK_WARNING
+
 # References
 
 - [_ColPack: Software for graph coloring and related problems in scientific computing_](https://dl.acm.org/doi/10.1145/2513109.2513110), Gebremedhin et al. (2013), Section 5
@@ -391,8 +403,7 @@ end
 
 Instance of [`AbstractOrder`](@ref) which sorts vertices from lowest to highest using the dynamic back degree.
 
-!!! danger
-    This order is still experimental and needs more tests, correctness is not yet guaranteed.
+$COLPACK_WARNING
 
 # See also
 
@@ -405,8 +416,7 @@ const IncidenceDegree = DynamicDegreeBasedOrder{:back,:low2high}
 
 Instance of [`AbstractOrder`](@ref) which sorts vertices from highest to lowest using the dynamic back degree.
 
-!!! danger
-    This order is still experimental and needs more tests, correctness is not yet guaranteed.
+$COLPACK_WARNING
 
 # See also
 
@@ -419,8 +429,7 @@ const SmallestLast = DynamicDegreeBasedOrder{:back,:high2low}
 
 Instance of [`AbstractOrder`](@ref) which sorts vertices from lowest to highest using the dynamic forward degree.
 
-!!! danger
-    This order is still experimental and needs more tests, correctness is not yet guaranteed.
+$COLPACK_WARNING
 
 # See also