Generalize the API to enable bicoloring

Author: gdalle

src/decompression.jl

@@ -1,11 +1,17 @@
 """
     compress(A, result::AbstractColoringResult)
 
-Compress `A` into a new matrix `B`, given a coloring `result` of the sparsity pattern of `A`.
+Compress `A` given a coloring `result` of the sparsity pattern of `A`.
+
+- If `result` comes from a `:column` (resp. `:row`) partition, the output is a single matrix `B` compressed by column (resp. by row).
+- If `result` comes from a `:bidirectional` partition, the output is a tuple of matrices `(Br, Bc)`, where `Br` is compressed by row and `Bc` by column.
 
 Compression means summing either the columns or the rows of `A` which share the same color.
 It is undone by calling [`decompress`](@ref).
 
+!!! warning
+    At the moment, `:bidirectional` partitions are not implemented.
+
 # Example
 
 ```jldoctest
@@ -36,6 +42,7 @@ julia> B = compress(A, result)
 
 # See also
 
+- [`ColoringProblem`](@ref)
 - [`AbstractColoringResult`](@ref)
 """
 function compress end
@@ -104,6 +111,7 @@ true
 
 # See also
 
+- [`ColoringProblem`](@ref)
 - [`AbstractColoringResult`](@ref)
 """
 function decompress(B::AbstractMatrix{R}, result::AbstractColoringResult) where {R<:Real}
@@ -165,6 +173,7 @@ true
 
 # See also
 
+- [`ColoringProblem`](@ref)
 - [`AbstractColoringResult`](@ref)
 """
 function decompress!(

src/interface.jl

@@ -3,7 +3,7 @@
 
 Selector type for the coloring problem to solve, enabling multiple dispatch.
 
-It is used inside the main function [`coloring`](@ref).
+It is passed as an argument to the main function [`coloring`](@ref).
 
 # Constructor
 
@@ -23,11 +23,15 @@ It is used inside the main function [`coloring`](@ref).
 
 Matrix coloring is often used in automatic differentiation, and here is the translation guide:
 
-| matrix   | mode                 | `structure`     | `partition` |
-| -------- | -------------------- | --------------- | ----------- |
-| Jacobian | forward              | `:nonsymmetric` | `:column`   |
-| Jacobian | reverse              | `:nonsymmetric` | `:row`      |
-| Hessian  | forward-over-reverse | `:symmetric`    | `:column`   |
+| matrix   | mode                 | `structure`     | `partition`      |
+| -------- | -------------------- | --------------- | -----------------|
+| Jacobian | forward              | `:nonsymmetric` | `:column`        |
+| Jacobian | reverse              | `:nonsymmetric` | `:row`           |
+| Jacobian | forward + reverse    | `:nonsymmetric` | `:bidirectional` |
+| Hessian  | any                  | `:symmetric`    | `:column`        |
+
+!!! warning
+    At the moment, `:bidirectional` partitions are not implemented.
 """
 struct ColoringProblem{structure,partition,decompression} end
 
@@ -47,7 +51,7 @@ end
 
 Greedy coloring algorithm for sparse matrices which colors columns or rows one after the other, following a configurable order.
 
-It is used inside the main function [`coloring`](@ref).
+It is passed as an argument to the main function [`coloring`](@ref).
 
 # Constructor
 

src/result.jl

@@ -1,12 +1,20 @@
 ## Abstract type
 
 """
-    AbstractColoringResult
+    AbstractColoringResult{structure,partition,decompression}
 
 Abstract type for the result of a coloring algorithm.
 
 It is the supertype of the object returned by the main function [`coloring`](@ref).
 
+# Type parameters
+
+Same as those of the [`ColoringProblem`](@ref) that was solved to obtain the result:
+
+- `structure::Symbol`: either `:nonsymmetric` or `:symmetric`
+- `partition::Symbol`: either `:column`, `:row` or `:bidirectional`
+- `decompression::Symbol`: either `:direct` or `:substitution`
+
 # Applicable methods
 
 - [`column_colors`](@ref) and [`column_groups`](@ref) (for a `:column` or `:bidirectional` partition)