Add a function substitutable_bidirectional

Author: amontoison

docs/src/dev.md

@@ -51,6 +51,7 @@ SparseMatrixColorings.symmetrically_orthogonal_columns
 SparseMatrixColorings.structurally_orthogonal_columns
 SparseMatrixColorings.structurally_biorthogonal
 SparseMatrixColorings.substitutable_columns
+SparseMatrixColorings.substitutable_bidirectional
 SparseMatrixColorings.valid_dynamic_order
 ```
 

src/check.jl

@@ -130,6 +130,8 @@ A bipartition of the rows and columns of a matrix `A` is _structurally biorthogo
 1. the group containing the column `A[:, j]` has no other column with a nonzero in row `i`
 2. the group containing the row `A[i, :]` has no other row with a nonzero in column `j`
 
+It is equivalent to an __star bicoloring__.
+
 !!! warning
     This function is not coded with efficiency in mind, it is designed for small-scale tests.
 """
@@ -142,8 +144,8 @@ function structurally_biorthogonal(
     if !proper_length_bicoloring(A, row_color, column_color; verbose)
         return false
     end
-    column_group = group_by_color(column_color)
     row_group = group_by_color(row_color)
+    column_group = group_by_color(column_color)
     for i in axes(A, 1), j in axes(A, 2)
         iszero(A[i, j]) && continue
         ci, cj = row_color[i], column_color[j]
@@ -313,6 +315,48 @@ function substitutable_columns(
     return true
 end
 
+"""
+    substitutable_bidirectional(
+        A::AbstractMatrix, order_nonzeros::AbstractMatrix, row_color::AbstractVector{<:Integer}, column_color::AbstractVector{<:Integer};
+        verbose=false
+    )
+
+Return `true` if bicoloring of the matrix `A` with the vectors `row_color` and `column_color` results in a bipartition that is substitutable, and `false` otherwise.
+For all nonzeros `A[i, j]`, `order_nonzeros[i, j]` provides its order of recovery.
+
+A bipartition of the rows and columns of a matrix `A` is _substitutable_ if, for every nonzero element `A[i, j]`, either of the following statements holds:
+
+1. the group containing the column `A[:, j]` has all nonzeros in row `i` ordered before `A[i, j]`
+2. the group containing the row `A[i, :]` has all nonzeros in column `j` ordered before `A[i, j]`
+
+It is equivalent to an __acyclic bicoloring__.
+
+!!! warning
+    This function is not coded with efficiency in mind, it is designed for small-scale tests.
+"""
+function substitutable_bidirectional(
+    A::AbstractMatrix,
+    order_nonzeros::AbstractMatrix,
+    row_color::AbstractVector{<:Integer},
+    column_color::AbstractVector{<:Integer};
+    verbose::Bool=false,
+)
+    if !proper_length_bicoloring(A, row_color, column_color; verbose)
+        return false
+    end
+    row_group = group_by_color(row_color)
+    column_group = group_by_color(column_color)
+    for i in axes(A, 1), j in axes(A, 2)
+        iszero(A[i, j]) && continue
+        ci, cj = row_color[i], column_color[j]
+        check = _substitutable_check(
+            A, order_nonzeros; i, j, ci, cj, row_group, column_group, verbose
+        )
+        !check && return false
+    end
+    return true
+end
+
 function _substitutable_check(
     A::AbstractMatrix,
     order_nonzeros::AbstractMatrix;

test/check.jl

@@ -282,3 +282,28 @@ For coefficient (i=3, j=5) with colors (ci=3, cj=0):
 """,
     ) substitutable_columns(A3, B3, [1, 2, 3, 3, 0]; verbose=true)
 end
+
+@testset "Substitutable bidirectional" begin
+    A = [
+        1 0 0
+        0 1 0
+        0 0 1
+    ]
+    B = [
+        1 0 0
+        0 2 0
+        0 0 3
+    ]
+
+    # success
+
+    substitutable_bidirectional(A, B, [1, 0, 0], [0, 1, 1])
+
+    # failure
+
+    log = (:warn, "2 colors provided for 3 columns.")
+    @test_logs log !substitutable_bidirectional(A, B, [1, 0, 0], [0, 1]; verbose=true)
+
+    log = (:warn, "4 colors provided for 3 rows.")
+    @test_logs log !substitutable_bidirectional(A, B, [1, 0, 0, 1], [0, 1, 1]; verbose=true)
+end

test/utils.jl

@@ -8,23 +8,25 @@ using SparseMatrixColorings:
     AdjacencyGraph,
     LinearSystemColoringResult,
     TreeSetColoringResult,
+    BicoloringResult,
     directly_recoverable_columns,
     matrix_versions,
     respectful_similar,
     structurally_orthogonal_columns,
     symmetrically_orthogonal_columns,
     structurally_biorthogonal,
-    substitutable_columns
+    substitutable_columns,
+    substitutable_bidirectional
 using Test
 
 const _ALL_ORDERS = (
     NaturalOrder(), LargestFirst(), SmallestLast(), IncidenceDegree(), DynamicLargestFirst()
 )
 
 function order_from_trees(result::TreeSetColoringResult)
-    (; ag, color, reverse_bfs_orders, diagonal_indices, tree_edge_indices, nt) = result
+    (; A, ag, reverse_bfs_orders, diagonal_indices, tree_edge_indices, nt) = result
     (; S) = ag
-    n = length(color)
+    m, n = size(A)
     nnzS = nnz(S)
     nzval = zeros(Int, nnzS)
     order_nonzeros = SparseMatrixCSC(n, n, S.colptr, S.rowval, nzval)
@@ -46,6 +48,36 @@ function order_from_trees(result::TreeSetColoringResult)
     return order_nonzeros
 end
 
+function order_from_trees(result::BicoloringResult)
+    (; A, abg, row_color, column_color, symmetric_result, large_colptr, large_rowval) =
+        result
+    @assert symmetric_result isa TreeSetColoringResult
+    (; ag, reverse_bfs_orders, tree_edge_indices, nt) = symmetric_result
+    (; S) = ag
+    m, n = size(A)
+    nnzA = nnz(S) ÷ 2
+    nzval = zeros(Int, nnzA)
+    colptr = large_colptr[1:(n + 1)]
+    rowval = large_rowval[1:nnzA]
+    rowval .-= n
+    order_nonzeros = SparseMatrixCSC(m, n, colptr, rowval, nzval)
+    counter = 0
+    for k in 1:nt
+        first = tree_edge_indices[k]
+        last = tree_edge_indices[k + 1] - 1
+        for pos in first:last
+            (i, j) = reverse_bfs_orders[pos]
+            counter += 1
+            if i > j
+                order_nonzeros[i - n, j] = counter
+            else
+                order_nonzeros[j - n, i] = counter
+            end
+        end
+    end
+    return order_nonzeros
+end
+
 function test_coloring_decompression(
     A0::AbstractMatrix,
     problem::ColoringProblem{structure,partition},
@@ -123,10 +155,12 @@ function test_coloring_decompression(
             end
         end
 
-        if decompression == :substitution
-            if structure == :symmetric
-                order_nonzeros = order_from_trees(result)
-                @test substitutable_columns(A0, order_nonzeros, color)
+        @testset "Substitutable" begin
+            if decompression == :substitution
+                if structure == :symmetric
+                    order_nonzeros = order_from_trees(result)
+                    @test substitutable_columns(A0, order_nonzeros, color)
+                end
             end
         end
 
@@ -268,6 +302,15 @@ function test_bicoloring_decompression(
                 @test structurally_biorthogonal(A0, row_color, column_color)
             end
         end
+
+        if decompression == :substitution
+            @testset "Substitutable" begin
+                order_nonzeros = order_from_trees(result)
+                @test substitutable_bidirectional(
+                    A0, order_nonzeros, row_color, column_color
+                )
+            end
+        end
     end
 
     @testset "More orders is better" begin