Options defined by 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"

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
@@ -9,27 +21,13 @@ using SparseArrays
 # Definitions
 
 include("libcolpack.jl")
-include("method.jl")
-include("order.jl")
-include("utils.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 row_partial_d2_coloring, column_partial_d2_coloring
-export implicit_star_bicoloring, explicit_star_bicoloring, explicit_modified_star_bicoloring, implicit_greedy_star_bicoloring
-
-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, ColPackPartialColoring, ColPackBiColoring, get_colors
 
 end #module

src/colpack_bicoloring.jl

@@ -3,55 +3,58 @@
 
 Struct holding the parameters of a bicoloring as well as its results (which can be queried with [`get_colors`](@ref)).
 
-# 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).
-
 # Constructors
 
-    ColPackBiColoring(
-        filename::AbstractString,
-        method::ColoringMethod,
-        order::ColoringOrder;
-        verbose::Bool=false    
+ColPackBiColoring(
+    filename::AbstractString,
+    method::String,
+    order::String;
+    verbose::Bool=false    
     )
-
+    
     ColPackBiColoring(
         M::SparseMatrixCSC,
-        method::ColoringMethod,
-        order::ColoringOrder;
+        method::String,
+        order::String;
         verbose::Bool=false    
     )
+        
+Perform the coloring of a matrix that is either given directly or read from a `.mtx` file.
 
-Perform the coloring of a matrix that is either given directly or read from a file.
-
-The users needs to specify a bicoloring `method` and an `order` on the vertices.
+The users needs to specify
 
-# See also
+- a bicoloring `method` among `$BICOLORING_METHODS`
+- an `order` on the vertices among `$BICOLORING_ORDERS`
 
-- [`ColoringMethod`](@ref)
-- [`ColoringOrder`](@ref)
+# 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::ColoringMethod
-    order::ColoringOrder
+    method::String
+    order::String
 end
 
 Base.unsafe_convert(::Type{Ptr{Cvoid}}, coloring::ColPackBiColoring) = coloring.refColPack[]
 
 function ColPackBiColoring(
-    filename::AbstractString,
-    method::ColoringMethod,
-    order::ColoringOrder;
-    verbose::Bool=false,
+    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.method, order.order, verbose)
+    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[])
@@ -63,10 +66,14 @@ end
 """
     get_colors(coloring::ColPackBiColoring)
 
-Retrieve the colors from a [`ColPackBiColoring`](@ref) as vectors of integers.
+Retrieve the colors from a [`ColPackBiColoring`](@ref) as two vectors of integers.
 """
 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