From 628e5bb3537ac412a75308619c432afff6302452 Mon Sep 17 00:00:00 2001 From: aviralgarg05 Date: Fri, 13 Nov 2026 15:02:46 +0530 Subject: [PATCH 1/3] feat: add small-world reservoir initializer --- src/ReservoirComputing.jl | 2 +- src/inits/inits_reservoir.jl | 87 +++++++++++++++++++++++++++++++++++- test/inits_tests.jl | 56 +++++++++++++++++++++++ 3 files changed, 143 insertions(+), 2 deletions(-) diff --git a/src/ReservoirComputing.jl b/src/ReservoirComputing.jl index 50b64a663..128121d89 100644 --- a/src/ReservoirComputing.jl +++ b/src/ReservoirComputing.jl @@ -104,7 +104,7 @@ export chebyshev_mapping, informed_init, logistic_mapping, minimal_init, modified_lm, scaled_rand, weighted_init, weighted_minimal export band_init, block_diagonal, chaotic_init, cycle_jumps, delay_line, delayline_backward, diagonal_init, double_cycle, forward_connection, low_connectivity, lower_triangular, permutation_init, - pseudo_svd, rand_hyper, rand_sparse, dale_sparse, selfloop_backward_cycle, selfloop_cycle, selfloop_delayline_backward, + pseudo_svd, rand_hyper, rand_sparse, small_world, dale_sparse, selfloop_backward_cycle, selfloop_cycle, selfloop_delayline_backward, selfloop_forwardconnection, simple_cycle, toeplitz_init, true_doublecycle, wigner_init export add_jumps!, backward_connection!, delay_line!, permute_matrix!, reverse_simple_cycle!, scale_radius!, self_loop!, simple_cycle! diff --git a/src/inits/inits_reservoir.jl b/src/inits/inits_reservoir.jl index 177d08496..0a285eed6 100644 --- a/src/inits/inits_reservoir.jl +++ b/src/inits/inits_reservoir.jl @@ -79,6 +79,91 @@ function rand_sparse( return return_init_as(Val(return_sparse), reservoir_matrix) end +@doc raw""" + small_world([rng], [T], dims...; + num_neighbors, rewiring_probability, radius=1.0, return_sparse=false) + +Create a reservoir whose connection topology follows the Watts-Strogatz small-world +model. The initial ring lattice connects every node to `num_neighbors` neighbours; +each clockwise edge is then rewired with probability `rewiring_probability`. +Connection weights are sampled uniformly from ``[-1, 1]`` before the matrix is +scaled to the requested spectral radius. + +## Arguments + + - `rng`: Random number generator. Default is `Xoshiro(1234)`. + - `T`: Type of the elements in the reservoir matrix. Default is `Float32`. + - `dims`: Dimensions of the reservoir matrix. + +## Keyword arguments + + - `num_neighbors`: Even number of neighbours for each node in the initial ring + lattice. It must be at least two and smaller than the number of nodes. + - `rewiring_probability`: Probability in `[0, 1]` of rewiring each clockwise + lattice edge. + - `radius`: Desired spectral radius of the reservoir. Defaults to 1.0. + - `return_sparse`: Flag for returning a `sparse` matrix. `true` requires + `SparseArrays` to be loaded. Default is `false`. +""" +function small_world( + rng::AbstractRNG, ::Type{T}, dims::Integer...; + num_neighbors::Integer, + rewiring_probability::Real, + radius::Real = one(T), + return_sparse::Bool = false + ) where {T <: Number} + throw_sparse_error(return_sparse) + check_res_size(dims...) + num_nodes = first(dims) + + 2 <= num_neighbors < num_nodes || throw( + ArgumentError( + "num_neighbors must be at least two and smaller than the number of nodes " * + "(got num_neighbors=$(num_neighbors), num_nodes=$(num_nodes))" + ) + ) + iseven(num_neighbors) || throw( + ArgumentError("num_neighbors must be even, got $(num_neighbors)") + ) + zero(rewiring_probability) <= rewiring_probability <= one(rewiring_probability) || throw( + ArgumentError( + "rewiring_probability must be between zero and one, got $(rewiring_probability)" + ) + ) + + adjacency_matrix = falses(num_nodes, num_nodes) + half_neighbors = num_neighbors รท 2 + for current_node in 1:num_nodes, offset in 1:half_neighbors + neighbor_node = mod1(current_node + offset, num_nodes) + adjacency_matrix[current_node, neighbor_node] = true + adjacency_matrix[neighbor_node, current_node] = true + end + + for current_node in 1:num_nodes, offset in 1:half_neighbors + neighbor_node = mod1(current_node + offset, num_nodes) + if rand(rng) < rewiring_probability + potential_new_neighbors = findall( + candidate -> candidate != current_node && !adjacency_matrix[current_node, candidate], + 1:num_nodes, + ) + isempty(potential_new_neighbors) && continue + new_neighbor_node = rand(rng, potential_new_neighbors) + adjacency_matrix[current_node, neighbor_node] = false + adjacency_matrix[neighbor_node, current_node] = false + adjacency_matrix[current_node, new_neighbor_node] = true + adjacency_matrix[new_neighbor_node, current_node] = true + end + end + + reservoir_matrix = ( + T(2) .* DeviceAgnostic.rand(rng, T, num_nodes, num_nodes) .- T(1) + ) .* adjacency_matrix + reservoir_matrix = scale_radius!(reservoir_matrix, radius) + check_inf_nan(reservoir_matrix) + + return return_init_as(Val(return_sparse), reservoir_matrix) +end + """ rand_hyper([rng], [T], dims...; poincare_dim=2, disk_radius=0.99, top_k=0, sigma=1.0, radius=1.0, return_sparse=false) @@ -2842,7 +2927,7 @@ for initializer in ( :selfloop_cycle, :selfloop_backward_cycle, :selfloop_delayline_backward, :selfloop_forwardconnection, :forward_connection, :true_doublecycle, :block_diagonal, :permutation_init, :diagonal_init, :wigner_init, :rand_hyper, :band_init, :toeplitz_init, - :dale_sparse, + :dale_sparse, :small_world, ) @eval begin function ($initializer)(dims::Integer...; kwargs...) diff --git a/test/inits_tests.jl b/test/inits_tests.jl index 26dd1cf4e..07a756840 100644 --- a/test/inits_tests.jl +++ b/test/inits_tests.jl @@ -72,6 +72,62 @@ begin ] @testset "Reservoir Initializers" begin + @testset "Small-world initializer" begin + zero_rewiring = small_world( + MersenneTwister(42), Float64, 20, 20; + num_neighbors = 4, rewiring_probability = 0.0, + ) + @test zero_rewiring == small_world( + MersenneTwister(42), Float64, 20, 20; + num_neighbors = 4, rewiring_probability = 0.0, + ) + @test size(zero_rewiring) == (20, 20) + @test eltype(zero_rewiring) == Float64 + @test all(iszero, diag(zero_rewiring)) + @test count(!iszero, zero_rewiring) == 20 * 4 + @test (zero_rewiring .!= 0) == transpose(zero_rewiring .!= 0) + @test check_radius(zero_rewiring, 1.0) + + full_rewiring = small_world( + MersenneTwister(42), Float32, 20, 20; + num_neighbors = 4, rewiring_probability = 1.0, radius = 0.75f0, + ) + @test count(!iszero, full_rewiring) == 20 * 4 + @test (full_rewiring .!= 0) == transpose(full_rewiring .!= 0) + @test check_radius(full_rewiring, 0.75f0) + @test (full_rewiring .!= 0) != (zero_rewiring .!= 0) + + dense = small_world( + MersenneTwister(42), Float32, 20, 20; + num_neighbors = 4, rewiring_probability = 0.3, + ) + sparse = small_world( + MersenneTwister(42), Float32, 20, 20; + num_neighbors = 4, rewiring_probability = 0.3, return_sparse = true, + ) + @test sparse isa SparseMatrixCSC{Float32} + @test Matrix(sparse) == dense + + @test_throws DimensionMismatch small_world( + MersenneTwister(42), 20, 19; num_neighbors = 4, rewiring_probability = 0.1 + ) + @test_throws ArgumentError small_world( + MersenneTwister(42), 20, 20; num_neighbors = 0, rewiring_probability = 0.1 + ) + @test_throws ArgumentError small_world( + MersenneTwister(42), 20, 20; num_neighbors = 3, rewiring_probability = 0.1 + ) + @test_throws ArgumentError small_world( + MersenneTwister(42), 20, 20; num_neighbors = 20, rewiring_probability = 0.1 + ) + @test_throws ArgumentError small_world( + MersenneTwister(42), 20, 20; num_neighbors = 4, rewiring_probability = -0.1 + ) + @test_throws ArgumentError small_world( + MersenneTwister(42), 20, 20; num_neighbors = 4, rewiring_probability = 1.1 + ) + end + @testset "Sizes and types: $init $T" for init in reservoir_inits, T in ft #sizes @test size(init(res_size, res_size)) == (res_size, res_size) From 407c672f1d73f32dac01e578b8049051fa7560ff Mon Sep 17 00:00:00 2001 From: aviralgarg05 Date: Mon, 16 Nov 2026 13:46:20 +0530 Subject: [PATCH 2/3] docs: document small-world initializer --- docs/src/api/inits.md | 2 ++ docs/src/api/inits/small_world.md | 5 +++++ src/inits/inits_reservoir.jl | 22 ++++++++++++++++++++++ 3 files changed, 29 insertions(+) create mode 100644 docs/src/api/inits/small_world.md diff --git a/docs/src/api/inits.md b/docs/src/api/inits.md index 864eb4d82..3397676c0 100644 --- a/docs/src/api/inits.md +++ b/docs/src/api/inits.md @@ -72,6 +72,8 @@ where full details and examples are provided. cycle where odd nodes self-loop and even nodes have forward/backward links. - [`selfloop_forwardconnection`](inits/selfloop_forwardconnection.md): Adds self-loops onto a forward-connection reservoir (stride-2). +- [`small_world`](inits/small_world.md): Creates a Watts-Strogatz small-world + reservoir with configurable neighbourhood size and rewiring probability. - [`simple_cycle`](inits/simple_cycle.md): Builds a basic directed ring reservoir with uniform weights. - [`toeplitz_init`](inits/toeplitz_init.md): Creates Toeplitz sparse reservoir topology diff --git a/docs/src/api/inits/small_world.md b/docs/src/api/inits/small_world.md new file mode 100644 index 000000000..5b8b81050 --- /dev/null +++ b/docs/src/api/inits/small_world.md @@ -0,0 +1,5 @@ +# small_world + +```@docs + small_world +``` diff --git a/src/inits/inits_reservoir.jl b/src/inits/inits_reservoir.jl index 0a285eed6..3d24d17a5 100644 --- a/src/inits/inits_reservoir.jl +++ b/src/inits/inits_reservoir.jl @@ -104,6 +104,28 @@ scaled to the requested spectral radius. - `radius`: Desired spectral radius of the reservoir. Defaults to 1.0. - `return_sparse`: Flag for returning a `sparse` matrix. `true` requires `SparseArrays` to be loaded. Default is `false`. + +## Examples + +Create a ring lattice by disabling rewiring: + +```jldoctest smallworld +julia> reservoir_matrix = small_world(MersenneTwister(123), 5, 5; + num_neighbors = 2, rewiring_probability = 0.0); + +julia> all(==(2), count(!iszero, reservoir_matrix; dims = 1)) +true +``` + +Request a sparse reservoir matrix: + +```jldoctest smallworld +julia> reservoir_matrix = small_world(MersenneTwister(123), 5, 5; + num_neighbors = 2, rewiring_probability = 0.5, return_sparse = true); + +julia> reservoir_matrix isa SparseMatrixCSC{Float32} && size(reservoir_matrix) == (5, 5) +true +``` """ function small_world( rng::AbstractRNG, ::Type{T}, dims::Integer...; From 2c634eb37791fd4984ce9585176d34b75156ff58 Mon Sep 17 00:00:00 2001 From: aviralgarg05 Date: Mon, 16 Nov 2026 15:59:56 +0530 Subject: [PATCH 3/3] fix: preserve small-world Float16 topology Avoid zero edge weights so finite-precision sampling retains the selected graph support. Cover the regression with a deterministic Float16 ring test. --- src/inits/inits_reservoir.jl | 6 +++--- test/inits_tests.jl | 7 +++++++ 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/src/inits/inits_reservoir.jl b/src/inits/inits_reservoir.jl index 3d24d17a5..0760b59b9 100644 --- a/src/inits/inits_reservoir.jl +++ b/src/inits/inits_reservoir.jl @@ -177,9 +177,9 @@ function small_world( end end - reservoir_matrix = ( - T(2) .* DeviceAgnostic.rand(rng, T, num_nodes, num_nodes) .- T(1) - ) .* adjacency_matrix + weights = T(2) .* DeviceAgnostic.rand(rng, T, num_nodes, num_nodes) .- T(1) + weights = ifelse.(iszero.(weights), eps(T), weights) + reservoir_matrix = weights .* adjacency_matrix reservoir_matrix = scale_radius!(reservoir_matrix, radius) check_inf_nan(reservoir_matrix) diff --git a/test/inits_tests.jl b/test/inits_tests.jl index 07a756840..7e3995877 100644 --- a/test/inits_tests.jl +++ b/test/inits_tests.jl @@ -88,6 +88,13 @@ begin @test (zero_rewiring .!= 0) == transpose(zero_rewiring .!= 0) @test check_radius(zero_rewiring, 1.0) + float16_zero_rewiring = small_world( + Xoshiro(56), Float16, 20, 20; + num_neighbors = 4, rewiring_probability = 0.0, + ) + @test count(!iszero, float16_zero_rewiring) == 20 * 4 + @test (float16_zero_rewiring .!= 0) == transpose(float16_zero_rewiring .!= 0) + full_rewiring = small_world( MersenneTwister(42), Float32, 20, 20; num_neighbors = 4, rewiring_probability = 1.0, radius = 0.75f0,