From e83f59c9660c2543e8a0e419fefca494694600aa Mon Sep 17 00:00:00 2001 From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com> Date: Fri, 4 Apr 2025 10:11:47 +0200 Subject: [PATCH 1/2] Remove warnings on ColPack orders --- src/order.jl | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/order.jl b/src/order.jl index 2bfceb95..7e55775f 100644 --- a/src/order.jl +++ b/src/order.jl @@ -109,9 +109,6 @@ end 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. - # Type parameters - `degtype::Symbol`: can be `:forward` (for the forward degree) or `:back` (for the back degree) @@ -119,7 +116,10 @@ Instance of [`AbstractOrder`](@ref) which sorts vertices using a dynamically com # 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. +- `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 from the end of a bucket, which incurs a significant 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. + +!!! 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. # Concrete variants @@ -392,7 +392,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. + 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. # See also @@ -406,7 +406,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. + 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. # See also @@ -420,7 +420,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. + 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. # See also From fd9d16fd8405eb06fc1f345630b081934e327792 Mon Sep 17 00:00:00 2001 From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com> Date: Fri, 4 Apr 2025 10:29:36 +0200 Subject: [PATCH 2/2] Rephrase --- src/order.jl | 35 ++++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/src/order.jl b/src/order.jl index 7e55775f..9cefc1b2 100644 --- a/src/order.jl +++ b/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. +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 exact 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 significant 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. - -!!! 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. - # 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 - 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. +$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 - 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. +$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 - 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. +$COLPACK_WARNING # See also