feat: seeding for random order (#163)

* feat: seeding for random order

* Generic seed type

* Random as test dep

Author: gdalle

Project.toml

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

src/SparseMatrixColorings.jl

@@ -28,7 +28,7 @@ using LinearAlgebra:
     ldiv!,
     parent,
     transpose
-using Random: AbstractRNG, default_rng, randperm
+using Random: Random, AbstractRNG, default_rng, randperm
 using SparseArrays:
     SparseArrays,
     SparseMatrixCSC,

src/order.jl

@@ -33,22 +33,42 @@ function vertices(bg::BipartiteGraph, ::Val{side}, ::NaturalOrder) where {side}
 end
 
 """
-    RandomOrder(rng=default_rng())
+    RandomOrder(rng=default_rng(), seed=nothing)
 
-Instance of [`AbstractOrder`](@ref) which sorts vertices using a random permutation.
+Instance of [`AbstractOrder`](@ref) which sorts vertices using a random permutation, generated from `rng` with a given `seed`.
+
+- If `seed = nothing`, the `rng` will never be re-seeded. Therefore, two consecutive calls to `vertices(g, order)` will give different results.
+- Otherwise, the `rng` will be re-seeded before each sample. Therefore, two consecutive calls to `vertices(g, order)` will give the same result.
+
+!!! warning
+    Do not use a seed with the `default_rng()`, otherwise you will affect the global state of your program.
+    If you need reproducibility, create a new `rng` specifically for your `RandomOrder`.
+    The package [StableRNGs.jl](https://github.com/JuliaRandom/StableRNGs.jl) offers random number generators whose behavior is stable across Julia versions.
 """
-struct RandomOrder{R<:AbstractRNG} <: AbstractOrder
+struct RandomOrder{R<:AbstractRNG,S} <: AbstractOrder
     rng::R
+    seed::S
 end
 
+RandomOrder(rng::AbstractRNG) = RandomOrder(rng, nothing)
 RandomOrder() = RandomOrder(default_rng())
 
 function vertices(g::AdjacencyGraph, order::RandomOrder)
-    return randperm(order.rng, nb_vertices(g))
+    (; rng, seed) = order
+    if isnothing(seed)
+        return randperm(rng, nb_vertices(g))
+    else
+        return randperm(Random.seed!(rng, seed), nb_vertices(g))
+    end
 end
 
 function vertices(bg::BipartiteGraph, ::Val{side}, order::RandomOrder) where {side}
-    return randperm(order.rng, nb_vertices(bg, Val(side)))
+    (; rng, seed) = order
+    if isnothing(seed)
+        return randperm(rng, nb_vertices(bg, Val(side)))
+    else
+        return randperm(Random.seed!(rng, seed), nb_vertices(bg, Val(side)))
+    end
 end
 
 """

test/Project.toml

@@ -14,6 +14,7 @@ JET = "c3a54625-cd67-489e-a8e7-0a5a0ff4e31b"
 JuliaFormatter = "98e50ef6-434e-11e9-1051-2b60c6c9e899"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MatrixDepot = "b51810bb-c9f3-55da-ae3c-350fc1fbce05"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 SparseMatrixColorings = "0a514795-09f3-496d-8182-132a7b665d35"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"

test/order.jl

@@ -11,6 +11,7 @@ using SparseMatrixColorings:
     nb_vertices,
     valid_dynamic_order,
     vertices
+using Random
 using StableRNGs
 using Test
 
@@ -31,10 +32,10 @@ rng = StableRNG(63)
 end;
 
 @testset "RandomOrder" begin
-    A = sprand(rng, Bool, 5, 5, 0.5)
+    A = sprand(rng, Bool, 10, 10, 0.5)
     ag = AdjacencyGraph(A)
-    @test sort(vertices(ag, RandomOrder(rng))) == 1:5
-    @test sort(vertices(ag, RandomOrder())) == 1:5
+    @test sort(vertices(ag, RandomOrder(rng))) == 1:10
+    @test sort(vertices(ag, RandomOrder())) == 1:10
 
     A = sprand(rng, Bool, 5, 4, 0.5)
     bg = BipartiteGraph(A)
@@ -45,6 +46,18 @@ end;
     bg = BipartiteGraph(A)
     @test sort(vertices(bg, Val(2), RandomOrder(rng))) == 1:4
     @test sort(vertices(bg, Val(2), RandomOrder())) == 1:4
+
+    order = RandomOrder()
+    @test order.rng === Random.default_rng()
+    @test isnothing(order.seed)
+
+    order = RandomOrder(StableRNG(0))
+    @test isnothing(order.seed)
+    @test vertices(ag, order) != vertices(ag, order)
+
+    order = RandomOrder(StableRNG(0), 6)
+    @test order.seed == 6
+    @test vertices(ag, order) == vertices(ag, order)
 end;
 
 @testset "LargestFirst" begin