Define StructuredColoringAlgorithm

Author: gdalle

Project.toml

@@ -1,7 +1,7 @@
 name = "SparseMatrixColorings"
 uuid = "0a514795-09f3-496d-8182-132a7b665d35"
 authors = ["Guillaume Dalle", "Alexis Montoison"]
-version = "0.4.21"
+version = "0.4.22"
 
 [deps]
 ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"

docs/make.jl

@@ -2,7 +2,11 @@ using Documenter
 using DocumenterInterLinks
 using SparseMatrixColorings
 
-links = InterLinks("ADTypes" => "https://sciml.github.io/ADTypes.jl/stable/")
+links = InterLinks(
+    "ADTypes" => "https://sciml.github.io/ADTypes.jl/stable/",
+    "BandedMatrices" => "https://julialinearalgebra.github.io/BandedMatrices.jl/stable/",
+    "LinearAlgebra" => "https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/",
+)
 
 cp(joinpath(@__DIR__, "..", "README.md"), joinpath(@__DIR__, "src", "index.md"); force=true)
 

docs/src/api.md

@@ -17,8 +17,14 @@ SparseMatrixColorings
 coloring
 fast_coloring
 ColoringProblem
+```
+
+## Coloring algorithms
+
+```@docs
 GreedyColoringAlgorithm
 ConstantColoringAlgorithm
+StructuredColoringAlgorithm
 ```
 
 ## Result analysis

ext/SparseMatrixColoringsBandedMatricesExt.jl

@@ -5,7 +5,7 @@ using SparseMatrixColorings:
     BipartiteGraph,
     ColoringProblem,
     ColumnColoringResult,
-    GreedyColoringAlgorithm,
+    StructuredColoringAlgorithm,
     RowColoringResult,
     column_colors,
     cycle_range,
@@ -21,7 +21,7 @@ https://github.com/JuliaDiff/FiniteDiff.jl
 function SMC.coloring(
     A::BandedMatrix,
     ::ColoringProblem{:nonsymmetric,:column},
-    algo::GreedyColoringAlgorithm;
+    ::StructuredColoringAlgorithm;
     kwargs...,
 )
     width = length(bandrange(A))
@@ -33,7 +33,7 @@ end
 function SMC.coloring(
     A::BandedMatrix,
     ::ColoringProblem{:nonsymmetric,:row},
-    algo::GreedyColoringAlgorithm;
+    ::StructuredColoringAlgorithm;
     kwargs...,
 )
     width = length(bandrange(A))

ext/SparseMatrixColoringsBlockBandedMatricesExt.jl

@@ -13,7 +13,7 @@ using SparseMatrixColorings:
     BipartiteGraph,
     ColoringProblem,
     ColumnColoringResult,
-    GreedyColoringAlgorithm,
+    StructuredColoringAlgorithm,
     RowColoringResult,
     column_colors,
     cycle_range,
@@ -75,7 +75,7 @@ end
 function SMC.coloring(
     A::Union{BlockBandedMatrix,BandedBlockBandedMatrix},
     ::ColoringProblem{:nonsymmetric,:column},
-    algo::GreedyColoringAlgorithm;
+    ::StructuredColoringAlgorithm;
     kwargs...,
 )
     color = blockbanded_coloring(A, 2)
@@ -86,7 +86,7 @@ end
 function SMC.coloring(
     A::Union{BlockBandedMatrix,BandedBlockBandedMatrix},
     ::ColoringProblem{:nonsymmetric,:row},
-    algo::GreedyColoringAlgorithm;
+    ::StructuredColoringAlgorithm;
     kwargs...,
 )
     color = blockbanded_coloring(A, 1)

src/SparseMatrixColorings.jl

@@ -66,7 +66,7 @@ export NaturalOrder, RandomOrder, LargestFirst
 export DynamicDegreeBasedOrder, SmallestLast, IncidenceDegree, DynamicLargestFirst
 export PerfectEliminationOrder
 export ColoringProblem, GreedyColoringAlgorithm, AbstractColoringResult
-export ConstantColoringAlgorithm
+export ConstantColoringAlgorithm, StructuredColoringAlgorithm
 export coloring, fast_coloring
 export column_colors, row_colors, ncolors
 export column_groups, row_groups

src/structured.jl

@@ -1,3 +1,21 @@
+"""
+    StructuredColoringAlgorithm  <: ADTypes.AbstractColoringAlgorithm
+
+Coloring algorithm which leverages specific matrix structures to produce optimal or near-optimal solutions.
+
+The following matrix types are supported:
+
+- From the standard library `LinearAlgebra`: [`Diagonal`](@extref LinearAlgebra.Diagonal), [`Bidiagonal`](@extref LinearAlgebra.Bidiagonal), [`Tridiagonal`](@extref LinearAlgebra.Tridiagonal)
+- From [BandedMatrices.jl](https://github.com/JuliaLinearAlgebra/BandedMatrices.jl): [`BandedMatrix`](@extref BandedMatrices.BandedMatrix)
+
+!!! warning
+    Only `:nonsymmetric` structures with `:row` or `:column` partitions (aka unidirectional Jacobian colorings) are supported by this algorithm at the moment.
+
+!!! tip
+    To request support for a new type of structured matrix, open an issue on the SparseMatrixColorings.jl GitHub repository!
+"""
+struct StructuredColoringAlgorithm <: ADTypes.AbstractColoringAlgorithm end
+
 #=
 This code is partly taken from ArrayInterface.jl
 https://github.com/JuliaArrays/ArrayInterface.jl
@@ -21,7 +39,7 @@ end
 function coloring(
     A::Diagonal,
     ::ColoringProblem{:nonsymmetric,:column},
-    algo::GreedyColoringAlgorithm;
+    ::StructuredColoringAlgorithm;
     kwargs...,
 )
     color = fill(1, size(A, 2))
@@ -32,7 +50,7 @@ end
 function coloring(
     A::Diagonal,
     ::ColoringProblem{:nonsymmetric,:row},
-    algo::GreedyColoringAlgorithm;
+    ::StructuredColoringAlgorithm;
     kwargs...,
 )
     color = fill(1, size(A, 1))
@@ -61,7 +79,7 @@ end
 function coloring(
     A::Bidiagonal,
     ::ColoringProblem{:nonsymmetric,:column},
-    algo::GreedyColoringAlgorithm;
+    ::StructuredColoringAlgorithm;
     kwargs...,
 )
     color = cycle_range(2, size(A, 2))
@@ -72,7 +90,7 @@ end
 function coloring(
     A::Bidiagonal,
     ::ColoringProblem{:nonsymmetric,:row},
-    algo::GreedyColoringAlgorithm;
+    ::StructuredColoringAlgorithm;
     kwargs...,
 )
     color = cycle_range(2, size(A, 1))
@@ -113,7 +131,7 @@ end
 function coloring(
     A::Tridiagonal,
     ::ColoringProblem{:nonsymmetric,:column},
-    algo::GreedyColoringAlgorithm;
+    ::StructuredColoringAlgorithm;
     kwargs...,
 )
     color = cycle_range(3, size(A, 2))
@@ -124,7 +142,7 @@ end
 function coloring(
     A::Tridiagonal,
     ::ColoringProblem{:nonsymmetric,:row},
-    algo::GreedyColoringAlgorithm;
+    ::StructuredColoringAlgorithm;
     kwargs...,
 )
     color = cycle_range(3, size(A, 1))

test/structured.jl

@@ -6,53 +6,65 @@ using SparseMatrixColorings
 using Test
 
 @testset "Diagonal" begin
-    for n in (1, 2, 10, 100)
-        A = Diagonal(rand(n))
-        test_structured_coloring_decompression(A)
+    @testset for algo in [GreedyColoringAlgorithm(), StructuredColoringAlgorithm()]
+        for n in (1, 2, 10, 100)
+            A = Diagonal(rand(n))
+            test_structured_coloring_decompression(A, algo)
+        end
     end
 end;
 
 @testset "Bidiagonal" begin
-    for n in (2, 10, 100)
-        A1 = Bidiagonal(rand(n), rand(n - 1), :U)
-        A2 = Bidiagonal(rand(n), rand(n - 1), :L)
-        test_structured_coloring_decompression(A1)
-        test_structured_coloring_decompression(A2)
+    @testset for algo in [GreedyColoringAlgorithm(), StructuredColoringAlgorithm()]
+        for n in (2, 10, 100)
+            A1 = Bidiagonal(rand(n), rand(n - 1), :U)
+            A2 = Bidiagonal(rand(n), rand(n - 1), :L)
+            test_structured_coloring_decompression(A1, algo)
+            test_structured_coloring_decompression(A2, algo)
+        end
     end
 end;
 
 @testset "Tridiagonal" begin
-    for n in (2, 10, 100)
-        A = Tridiagonal(rand(n - 1), rand(n), rand(n - 1))
-        test_structured_coloring_decompression(A)
+    @testset for algo in [GreedyColoringAlgorithm(), StructuredColoringAlgorithm()]
+        for n in (2, 10, 100)
+            A = Tridiagonal(rand(n - 1), rand(n), rand(n - 1))
+            test_structured_coloring_decompression(A, algo)
+        end
     end
 end;
 
 @testset "BandedMatrices" begin
-    @testset for (m, n) in [(10, 20), (20, 10)], l in 0:5, u in 0:5
-        A = brand(m, n, l, u)
-        test_structured_coloring_decompression(A)
+    @testset for algo in [GreedyColoringAlgorithm(), StructuredColoringAlgorithm()]
+        @testset for (m, n) in [(10, 20), (20, 10)], l in 0:5, u in 0:5
+            A = brand(m, n, l, u)
+            test_structured_coloring_decompression(A, algo)
+        end
     end
 end;
 
 @testset "BlockBandedMatrices" begin
-    for (mb, nb) in [(10, 20), (20, 10)], lb in 0:3, ub in 0:3, _ in 1:10
-        rows = rand(1:5, mb)
-        cols = rand(1:5, nb)
-        A = BlockBandedMatrix{Float64}(rand(sum(rows), sum(cols)), rows, cols, (lb, ub))
-        test_structured_coloring_decompression(A)
+    @testset for algo in [GreedyColoringAlgorithm(), StructuredColoringAlgorithm()]
+        for (mb, nb) in [(10, 20), (20, 10)], lb in 0:3, ub in 0:3, _ in 1:10
+            rows = rand(1:5, mb)
+            cols = rand(1:5, nb)
+            A = BlockBandedMatrix{Float64}(rand(sum(rows), sum(cols)), rows, cols, (lb, ub))
+            test_structured_coloring_decompression(A, algo)
+        end
     end
 end;
 
 @testset "BandedBlockBandedMatrices" begin
-    for (mb, nb) in [(10, 20), (20, 10)], lb in 0:3, ub in 0:3, _ in 1:10
-        rows = rand(5:10, mb)
-        cols = rand(5:10, nb)
-        λ = rand(0:5)
-        μ = rand(0:5)
-        A = BandedBlockBandedMatrix{Float64}(
-            rand(sum(rows), sum(cols)), rows, cols, (lb, ub), (λ, μ)
-        )
-        test_structured_coloring_decompression(A)
+    @testset for algo in [GreedyColoringAlgorithm(), StructuredColoringAlgorithm()]
+        for (mb, nb) in [(10, 20), (20, 10)], lb in 0:3, ub in 0:3, _ in 1:10
+            rows = rand(5:10, mb)
+            cols = rand(5:10, nb)
+            λ = rand(0:5)
+            μ = rand(0:5)
+            A = BandedBlockBandedMatrix{Float64}(
+                rand(sum(rows), sum(cols)), rows, cols, (lb, ub), (λ, μ)
+            )
+            test_structured_coloring_decompression(A, algo)
+        end
     end
 end;

test/utils.jl

@@ -218,10 +218,11 @@ function test_bicoloring_decompression(
     end
 end
 
-function test_structured_coloring_decompression(A::AbstractMatrix)
+function test_structured_coloring_decompression(
+    A::AbstractMatrix, algo=StructuredColoringAlgorithm()
+)
     column_problem = ColoringProblem(; structure=:nonsymmetric, partition=:column)
     row_problem = ColoringProblem(; structure=:nonsymmetric, partition=:row)
-    algo = GreedyColoringAlgorithm()
 
     # Column
     result = coloring(A, column_problem, algo)
@@ -231,7 +232,9 @@ function test_structured_coloring_decompression(A::AbstractMatrix)
     @test D == A
     @test nameof(typeof(D)) == nameof(typeof(A))
     @test structurally_orthogonal_columns(A, color)
-    @test color == ArrayInterface.matrix_colors(A)
+    if algo isa StructuredColoringAlgorithm
+        @test color == ArrayInterface.matrix_colors(A)
+    end
 
     # Row
     result = coloring(A, row_problem, algo)