Upgrade ColPack bindings, options as strings, systematic tests

Project.toml

@@ -1,7 +1,7 @@
 name = "ColPack"
 uuid = "ffa27691-3a59-46ab-a8d4-551f45b8d401"
-authors = ["Michel Schanen <[email protected]>", "Guillaume Dalle"]
-version = "0.4.0"
+authors = ["Michel Schanen <[email protected]>", "Alexis Montoison", "Guillaume Dalle"]
+version = "0.5.0"
 
 [deps]
 ColPack_jll = "f218ff0c-cb54-5151-80c4-c0f62c730ce6"
@@ -10,8 +10,8 @@ Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 
 [compat]
-ColPack_jll = "0.3.0"
-LinearAlgebra = "1"
-Random = "1"
-SparseArrays = "1"
+ColPack_jll = "0.4.0"
+LinearAlgebra = "1.6"
+Random = "1.6"
+SparseArrays = "1.6"
 julia = "1.6"

README.md

@@ -4,7 +4,7 @@
 [![Stable Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://exanauts.github.io/ColPack.jl/stable/)
 [![Dev Documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://exanauts.github.io/ColPack.jl/dev/)
 
-This is the Julia interface to [ColPack](https://github.com/CSCsw/ColPack) for graph and matrix coloring.
+A Julia interface to the C++ library [ColPack](https://github.com/CSCsw/ColPack) for graph and sparse matrix coloring.
 
 ## Getting started
 
@@ -14,10 +14,12 @@ You can install this package by running the following command in a Julia Pkg REP
 pkg> add ColPack
 ```
 
-Take a look at the tutorial in the documentation to get a feel for what you can do.
-
 ## Mathematical background
 
 To understand the link between graph coloring and automatic differentiation, read the following survey:
 
 > [_What Color Is Your Jacobian? Graph Coloring for Computing Derivatives_](https://epubs.siam.org/doi/10.1137/S0036144504444711), Gebremedhin et al. (2005)
+
+The ColPack library itself is described in:
+
+> [_ColPack: Software for graph coloring and related problems in scientific computing_](https://dl.acm.org/doi/10.1145/2513109.2513110), Gebremedhin et al. (2012)

docs/make.jl

@@ -5,10 +5,10 @@ cp(joinpath(@__DIR__, "..", "README.md"), joinpath(@__DIR__, "src", "index.md");
 
 makedocs(;
     modules=[ColPack],
-    authors="Michel Schanen, Guillaume Dalle",
+    authors="Michel Schanen, Alexis Montoison, Guillaume Dalle",
     sitename="ColPack.jl",
     format=Documenter.HTML(),
-    pages=["Home" => "index.md", "Tutorial" => "tutorial.md", "API reference" => "api.md"],
+    pages=["Home" => "index.md", "API reference" => "api.md"],
 )
 
 deploydocs(; repo="github.com/exanauts/ColPack.jl", devbranch="master")

docs/src/api.md

@@ -1,30 +1,13 @@
-```@meta
-CollapsedDocStrings = true
-```
-
 # API reference
 
-## Entry points
-
-```@autodocs
-Modules = [ColPack]
-Pages = ["colpackcoloring.jl", "utils.jl"]
-Private = false
-```
-
-## Coloring method
-
-```@autodocs
-Modules = [ColPack]
-Pages = ["method.jl"]
-Private = false
+```@meta
+CollapsedDocStrings = true
 ```
 
-## Coloring order
+## Public
 
 ```@autodocs
 Modules = [ColPack]
-Pages = ["order.jl"]
 Private = false
 ```
 

src/ColPack.jl

@@ -1,3 +1,15 @@
+"""
+    ColPack
+
+A Julia interface to the C++ library [ColPack](https://github.com/CSCsw/ColPack) for graph and sparse matrix coloring.
+
+# Exports
+
+- [`ColPackColoring`](@ref)
+- [`ColPackPartialColoring`](@ref)
+- [`ColPackBiColoring`](@ref)
+- [`get_colors`](@ref)
+"""
 module ColPack
 
 # Imports
@@ -8,23 +20,14 @@ using SparseArrays
 
 # Definitions
 
-include("method.jl")
-include("order.jl")
-include("utils.jl")
-include("colpackcoloring.jl")
+include("libcolpack.jl")
+include("options.jl")
+include("colpack_coloring.jl")
+include("colpack_partial_coloring.jl")
+include("colpack_bicoloring.jl")
 
 # Exports
 
-export ColoringMethod
-export d1_coloring, d2_coloring, acyclic_coloring, star_coloring
-
-export ColoringOrder
-export natural_ordering, largest_first_ordering, dynamic_largest_first_ordering, distance_two_largest_first_ordering
-export smallest_last_ordering, distance_two_smallest_last_ordering, incidence_degree_ordering, distance_two_incidence_degree_ordering
-export random_ordering
-
-export matrix2adjmatrix
-
-export ColPackColoring, get_colors
+export ColPackColoring, ColPackPartialColoring, get_colors
 
 end #module

src/colpack_bicoloring.jl

@@ -0,0 +1,83 @@
+"""
+    ColPackBiColoring
+
+Struct holding the parameters of a bicoloring as well as its results (which can be queried with [`get_colors`](@ref)).
+
+!!! danger
+    This is still experimental and not protected by semantic versioning, use at your own risk.
+
+# Constructors
+
+    ColPackBiColoring(
+        filename::AbstractString,
+        method::String,
+        order::String;
+        verbose::Bool=false    
+    )
+
+    ColPackBiColoring(
+        M::SparseMatrixCSC,
+        method::String,
+        order::String;
+        verbose::Bool=false    
+    )
+
+Perform the coloring of a matrix that is either given directly or read from a `.mtx` file.
+
+The users needs to specify
+
+- a bicoloring `method` among `$BICOLORING_METHODS`
+- an `order` on the vertices among `$BICOLORING_ORDERS`
+
+# Fields
+
+The fields of this struct are not part of the public API, they are only useful to interface with the C++ library [ColPack](https://github.com/CSCsw/ColPack).
+"""
+mutable struct ColPackBiColoring
+    refColPack::Base.RefValue{Ptr{Cvoid}}
+    coloring1::Vector{Cint}
+    coloring2::Vector{Cint}
+    method::String
+    order::String
+end
+
+Base.unsafe_convert(::Type{Ptr{Cvoid}}, coloring::ColPackBiColoring) = coloring.refColPack[]
+
+function ColPackBiColoring(
+    filename::AbstractString, method::String, order::String; verbose::Bool=false
+)
+    if !(method in BICOLORING_METHODS)
+        throw(ArgumentError("""Method "$method" is not in $BICOLORING_METHODS"""))
+    end
+    if !(order in BICOLORING_ORDERS)
+        throw(ArgumentError("""Order "$order" is not in $BICOLORING_ORDERS"""))
+    end
+    refColPack = Ref{Ptr{Cvoid}}(C_NULL)
+    reflen1 = Ref{Cint}(0)
+    reflen2 = Ref{Cint}(0)
+    ret = build_bicoloring_from_file(
+        refColPack, reflen1, reflen2, filename, method, order, verbose
+    )
+    (ret == 0) && error("ColPack bicoloring failed.")
+    coloring1 = zeros(Cint, reflen1[])
+    coloring2 = zeros(Cint, reflen2[])
+    g = ColPackBiColoring(refColPack, coloring1, coloring2, method, order)
+    finalizer(free_bicoloring, g)
+    return g
+end
+
+"""
+    get_colors(coloring::ColPackBiColoring)
+
+Retrieve the colors from a [`ColPackBiColoring`](@ref) as two vectors of integers, one for the rows and one for the columns respectively.
+"""
+function get_colors(coloring::ColPackBiColoring)
+    get_bicoloring(coloring.refColPack[], coloring.coloring1, coloring.coloring2)
+    #=
+    Zero is a neutral color in bicoloring, it may make sense to keep it.
+    I am not yet sure how the coloring vectors are defined.
+    =#
+    coloring.coloring1 .+= Cint(1)
+    coloring.coloring2 .+= Cint(1)
+    return coloring.coloring1, coloring.coloring2
+end

src/colpack_coloring.jl

@@ -0,0 +1,125 @@
+"""
+    ColPackColoring
+
+Struct holding the parameters of a coloring as well as its results (which can be queried with [`get_colors`](@ref)).
+
+# Constructors
+
+    ColPackColoring(
+        filename::AbstractString,
+        method::String,
+        order::String;
+        verbose::Bool=false    
+    )
+
+    ColPackColoring(
+        M::SparseMatrixCSC,
+        method::String,
+        order::String;
+        verbose::Bool=false    
+    )
+
+Perform the coloring of a matrix that is either given directly or read from a `.mtx` file.
+
+The users needs to specify
+
+- a coloring `method` among `$COLORING_METHODS`
+- an `order` on the vertices among `$COLORING_ORDERS`
+
+# Example
+
+```jldoctest
+julia> using ColPack, SparseArrays
+
+julia> H = sparse([1 1 1; 1 1 0; 1 0 1])
+3×3 SparseMatrixCSC{Int64, Int64} with 7 stored entries:
+ 1  1  1
+ 1  1  ⋅
+ 1  ⋅  1
+
+julia> get_colors(ColPackColoring(H, "STAR", "NATURAL"))
+3-element Vector{Int32}:
+ 1
+ 2
+ 2
+```
+
+# Fields
+
+The fields of this struct are not part of the public API, they are only useful to interface with the C++ library [ColPack](https://github.com/CSCsw/ColPack).
+"""
+mutable struct ColPackColoring
+    refColPack::Base.RefValue{Ptr{Cvoid}}
+    coloring::Vector{Cint}
+    method::String
+    order::String
+end
+
+Base.unsafe_convert(::Type{Ptr{Cvoid}}, coloring::ColPackColoring) = coloring.refColPack[]
+
+function ColPackColoring(
+    filename::AbstractString, method::String, order::String; verbose::Bool=false
+)
+    if !(method in COLORING_METHODS)
+        throw(ArgumentError("""Method "$method" is not in $COLORING_METHODS"""))
+    end
+    if !(order in COLORING_ORDERS)
+        throw(ArgumentError("""Order "$order" is not in $COLORING_ORDERS"""))
+    end
+    refColPack = Ref{Ptr{Cvoid}}(C_NULL)
+    reflen = Ref{Cint}(0)
+    ret = build_coloring_from_file(refColPack, reflen, filename, method, order, verbose)
+    (ret == 0) && error("ColPack coloring failed.")
+    coloring = zeros(Cint, reflen[])
+    g = ColPackColoring(refColPack, coloring, method, order)
+    finalizer(free_coloring, g)
+    return g
+end
+
+function ColPackColoring(
+    M::SparseMatrixCSC, method::String, order::String; verbose::Bool=false
+)
+    if !(method in COLORING_METHODS)
+        throw(ArgumentError("""Method "$method" is not in $COLORING_METHODS"""))
+    end
+    if !(order in COLORING_ORDERS)
+        throw(ArgumentError("""Order "$order" is not in $COLORING_ORDERS"""))
+    end
+    if size(M, 1) != size(M, 2)
+        throw(DimensionMismatch("Matrix must be square (and symmetric)"))
+    end
+    # We expect M to be symmetric.
+    csr = Vector{Ref{Cuint}}()
+    csr_mem = Vector{Vector{Cuint}}()
+    for i in 1:(length(M.colptr) - 1)
+        vec = Vector{Cuint}()
+        # Number of column elements
+        push!(vec, Cuint(M.colptr[i + 1] - M.colptr[i]))
+        for j in M.colptr[i]:(M.colptr[i + 1] - 1)
+            push!(vec, Cuint(M.rowval[j] - 1))
+        end
+        push!(csr, Base.unsafe_convert(Ptr{Cuint}, vec))
+        push!(csr_mem, vec)
+    end
+    nrows = size(M, 2)
+    reflen = Ref{Cint}(0)
+    refColPack = Ref{Ptr{Cvoid}}(C_NULL)
+    ret = build_coloring_from_adolc(refColPack, reflen, csr, nrows, method, order, verbose)
+    (ret == 0) && error("ColPack coloring failed.")
+
+    coloring = zeros(Cint, reflen[])
+    g = ColPackColoring(refColPack, coloring, method, order)
+    finalizer(free_coloring, g)
+    return g
+end
+
+"""
+    get_colors(coloring::ColPackColoring)
+
+Retrieve the colors from a [`ColPackColoring`](@ref) as a vector of integers.
+"""
+function get_colors(coloring::ColPackColoring)
+    get_coloring(coloring.refColPack[], coloring.coloring)
+    coloring.coloring .+= Cint(1)
+    return coloring.coloring
+end