Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/src/api/inits.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions docs/src/api/inits/small_world.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# small_world

```@docs
small_world
```
2 changes: 1 addition & 1 deletion src/ReservoirComputing.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand Down
109 changes: 108 additions & 1 deletion src/inits/inits_reservoir.jl
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,113 @@
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`.

## 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...;
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))"

Check warning on line 144 in src/inits/inits_reservoir.jl

View workflow job for this annotation

GitHub Actions / runic-suggestions / Runic Suggestions

[Runic] reported by reviewdog 🐶 Raw Output: src/inits/inits_reservoir.jl:144:- "(got num_neighbors=$(num_neighbors), num_nodes=$(num_nodes))" src/inits/inits_reservoir.jl:144:+ "(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

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)

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)
Expand Down Expand Up @@ -2842,7 +2949,7 @@
: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...)
Expand Down
63 changes: 63 additions & 0 deletions test/inits_tests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,69 @@ 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)

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,
)
@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)
Expand Down
Loading