Skip to content
Open
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 @@ -62,6 +62,8 @@ where full details and examples are provided.
in the Poincaré ball and constructing weights based on hyperbolic distances between them.
- [`rand_sparse`](inits/rand_sparse.md): Generates a random sparse
reservoir with controlled sparsity and spectral radius.
- [`scale_free`](inits/scale_free.md): Creates a Barabási-Albert reservoir
using degree-based preferential attachment.
- [`dale_sparse`](inits/dale_sparse.md): Dale-compliant sparse reservoir
(E/I column signs).
- [`selfloop_cycle`](inits/selfloop_cycle.md): Builds a simple cycle
Expand Down
5 changes: 5 additions & 0 deletions docs/src/api/inits/scale_free.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# scale_free

```@docs
scale_free
```
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, small_world, dale_sparse, selfloop_backward_cycle, selfloop_cycle, selfloop_delayline_backward,
pseudo_svd, rand_hyper, rand_sparse, scale_free, 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
179 changes: 177 additions & 2 deletions src/inits/inits_reservoir.jl
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ function small_world(
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))"
"(got num_neighbors=$(num_neighbors), num_nodes=$(num_nodes))"
)
)
iseven(num_neighbors) || throw(
Expand Down Expand Up @@ -186,6 +186,181 @@ function small_world(
return return_init_as(Val(return_sparse), reservoir_matrix)
end

@doc raw"""
scale_free([rng], [T], dims...;
initial_nodes, attachments, radius=1.0, return_sparse=false)

Create a reservoir whose undirected connection topology follows the
Barabási-Albert preferential-attachment model. The network starts with a complete
graph of `initial_nodes` nodes. Each remaining node connects to `attachments`
different existing nodes, sampled with probability proportional to their degree.
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`: Real floating-point type of the elements in the reservoir matrix.
Default is `Float32`.
- `dims`: Dimensions of the reservoir matrix.

## Keyword arguments

- `initial_nodes`: Number of nodes in the initial complete graph. It must be at
least two and no larger than the total number of nodes.
- `attachments`: Number of existing nodes that each new node connects to. It
must be positive and no larger than `initial_nodes`.
- `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`.

## References

Barabási, A.-L. and Albert, R. (1999). Emergence of scaling in random networks.
*Science*, 286(5439), 509-512. [doi:10.1126/science.286.5439.509](https://doi.org/10.1126/science.286.5439.509)

## Examples

Create a scale-free reservoir:

```jldoctest scalefree
julia> reservoir_matrix = scale_free(MersenneTwister(123), 8, 8;
initial_nodes = 3, attachments = 2);

julia> size(reservoir_matrix) == (8, 8) &&
(reservoir_matrix .!= 0) == transpose(reservoir_matrix .!= 0)
true
```

Request a sparse reservoir matrix:

```jldoctest scalefree
julia> reservoir_matrix = scale_free(MersenneTwister(123), 8, 8;
initial_nodes = 3, attachments = 2, return_sparse = true);

julia> reservoir_matrix isa SparseMatrixCSC{Float32} && size(reservoir_matrix) == (8, 8)
true
```
"""
function scale_free(
rng::AbstractRNG, ::Type{T}, dims::Integer...;
initial_nodes::Integer,
attachments::Integer,
radius = one(T),
return_sparse::Bool = false
) where {T <: Number}
throw_sparse_error(return_sparse)
check_res_size(dims...)
num_nodes = first(dims)

T <: AbstractFloat || throw(
ArgumentError("scale_free requires a real floating-point element type, got $T")
)
radius isa Real || throw(ArgumentError("radius must be real, got $(typeof(radius))"))
isfinite(radius) || throw(
ArgumentError("radius must be finite, got $radius")
)
radius >= zero(radius) || throw(
ArgumentError("radius must be nonnegative, got $radius")
)
converted_radius = T(radius)
isfinite(converted_radius) || throw(
ArgumentError("radius must be finite after conversion to $T, got $radius")
)

2 <= initial_nodes <= num_nodes || throw(
ArgumentError(
"initial_nodes must be at least two and no larger than the number of nodes " *
"(got initial_nodes=$(initial_nodes), num_nodes=$(num_nodes))"
)
)
1 <= attachments <= initial_nodes || throw(
ArgumentError(
"attachments must be positive and no larger than initial_nodes " *
"(got attachments=$(attachments), initial_nodes=$(initial_nodes))"
)
)

adjacency_matrix = falses(num_nodes, num_nodes)
degrees = zeros(Int, num_nodes)
for first_node in 1:(initial_nodes - 1), second_node in (first_node + 1):initial_nodes
adjacency_matrix[first_node, second_node] = true
adjacency_matrix[second_node, first_node] = true
degrees[first_node] += 1
degrees[second_node] += 1
end

for new_node in (initial_nodes + 1):num_nodes
selected_nodes = falses(new_node - 1)
for _ in 1:attachments
available_degree = sum(
node -> selected_nodes[node] ? 0 : degrees[node], 1:(new_node - 1)
)
draw = rand(rng, 1:available_degree)
cumulative_degree = 0
selected_node = 0
for existing_node in 1:(new_node - 1)
selected_nodes[existing_node] && continue
cumulative_degree += degrees[existing_node]
if draw <= cumulative_degree
selected_node = existing_node
break
end
end

adjacency_matrix[new_node, selected_node] = true
adjacency_matrix[selected_node, new_node] = true
selected_nodes[selected_node] = true
degrees[new_node] += 1
degrees[selected_node] += 1
end
end

working_type = promote_type(T, Float64)
target_radius = working_type(converted_radius)
radius_tolerance = sqrt(eps(T))
max_weight_attempts = 100

reservoir_matrix = zeros(T, num_nodes, num_nodes)
accepted = false
for _ in 1:max_weight_attempts
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

if iszero(converted_radius)
fill!(reservoir_matrix, zero(T))
accepted = true
break
end

spectral_radius = maximum(abs, eigvals(working_type.(reservoir_matrix)))
(!isfinite(spectral_radius) || iszero(spectral_radius)) && continue
reservoir_matrix .*= T(target_radius / spectral_radius)
any(!isfinite, reservoir_matrix) && continue

realized_radius = maximum(abs, eigvals(working_type.(reservoir_matrix)))
if isapprox(
realized_radius, target_radius;
rtol = radius_tolerance,
atol = zero(working_type)
)
accepted = true
break
end
end

accepted || throw(
ArgumentError(
"could not generate weights with spectral radius $converted_radius after " *
"$max_weight_attempts attempts; use a wider floating-point element type"
)
)
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 @@ -2949,7 +3124,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, :small_world,
:dale_sparse, :scale_free, :small_world,
)
@eval begin
function ($initializer)(dims::Integer...; kwargs...)
Expand Down
119 changes: 119 additions & 0 deletions test/inits_tests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,125 @@
]

@testset "Reservoir Initializers" begin
@testset "Scale-free initializer" begin
initial_nodes = 4
attachments = 2
num_nodes = 20
reservoir_matrix = scale_free(
MersenneTwister(42), Float64, num_nodes, num_nodes;
initial_nodes, attachments,
)
@test reservoir_matrix == scale_free(
MersenneTwister(42), Float64, num_nodes, num_nodes;
initial_nodes, attachments,
)
@test size(reservoir_matrix) == (num_nodes, num_nodes)
@test eltype(reservoir_matrix) == Float64
@test all(iszero, diag(reservoir_matrix))
@test (reservoir_matrix .!= 0) == transpose(reservoir_matrix .!= 0)
expected_edges = initial_nodes * (initial_nodes - 1) ÷ 2 +
(num_nodes - initial_nodes) * attachments
@test count(!iszero, reservoir_matrix) == 2 * expected_edges
@test all(>=(attachments), count(!iszero, reservoir_matrix; dims = 1))
@test check_radius(reservoir_matrix, 1.0)

dense = scale_free(
MersenneTwister(7), Float32, num_nodes, num_nodes;
initial_nodes, attachments, radius = 0.75f0,
)
sparse = scale_free(
MersenneTwister(7), Float32, num_nodes, num_nodes;
initial_nodes, attachments, radius = 0.75f0, return_sparse = true,
)
@test sparse isa SparseMatrixCSC{Float32}
@test Matrix(sparse) == dense
@test check_radius(dense, 0.75f0)

initial_graph = scale_free(
MersenneTwister(11), Float64, initial_nodes, initial_nodes;
initial_nodes, attachments = initial_nodes,
)
@test count(!iszero, initial_graph) == initial_nodes * (initial_nodes - 1)
@test check_radius(initial_graph, 1.0)

preferential = scale_free(
Xoshiro(1), Float64, 4, 4;
initial_nodes = 2, attachments = 1,
)
@test !iszero(preferential[1, 3])
@test !iszero(preferential[1, 4])
@test iszero(preferential[2, 4])

float32_regression = scale_free(
Xoshiro(1971721), Float32, 3, 3;
initial_nodes = 2, attachments = 1,
)
float16_regression = scale_free(
Xoshiro(19672), Float16, 3, 3;
initial_nodes = 2, attachments = 1,
)
@test check_radius(Float64.(float32_regression), 1.0; tolerance = 1.0e-3)
@test check_radius(Float64.(float16_regression), 1.0; tolerance = 0.04)

tree_radius(matrix) = sqrt(abs(sum(

Check warning on line 135 in test/inits_tests.jl

View workflow job for this annotation

GitHub Actions / runic-suggestions / Runic Suggestions

[Runic] reported by reviewdog 🐶 Raw Output: test/inits_tests.jl:135:- tree_radius(matrix) = sqrt(abs(sum( test/inits_tests.jl:136:- BigFloat(matrix[i, j]) * BigFloat(matrix[j, i]) test/inits_tests.jl:137:- for i in axes(matrix, 1) for j in (i + 1):size(matrix, 2) test/inits_tests.jl:138:- ))) test/inits_tests.jl:135:+ tree_radius(matrix) = sqrt( test/inits_tests.jl:136:+ abs( test/inits_tests.jl:137:+ sum( test/inits_tests.jl:138:+ BigFloat(matrix[i, j]) * BigFloat(matrix[j, i]) test/inits_tests.jl:139:+ for i in axes(matrix, 1) for j in (i + 1):size(matrix, 2) test/inits_tests.jl:140:+ ) test/inits_tests.jl:141:+ ) test/inits_tests.jl:142:+ )
BigFloat(matrix[i, j]) * BigFloat(matrix[j, i])
for i in axes(matrix, 1) for j in (i + 1):size(matrix, 2)
)))
float32_small_radius = scale_free(
Xoshiro(1971721), Float32, 3, 3;
initial_nodes = 2, attachments = 1, radius = 0.001,
)
float16_small_radius = scale_free(
Xoshiro(19672), Float16, 3, 3;
initial_nodes = 2, attachments = 1, radius = 0.01,
)
@test isapprox(
tree_radius(float32_small_radius), BigFloat(Float32(0.001));
rtol = sqrt(eps(Float32)), atol = 0,
)
@test isapprox(
tree_radius(float16_small_radius), BigFloat(Float16(0.01));
rtol = sqrt(eps(Float16)), atol = 0,
)

invalid_radius_rng = Xoshiro(1)
@test_throws ArgumentError scale_free(
invalid_radius_rng, Float64, 4, 4;
initial_nodes = 2, attachments = 1, radius = -0.75,
)
@test rand(invalid_radius_rng) == rand(Xoshiro(1))
for (T, radius) in ((Float16, -1.0e-8), (Float32, -1.0e-100))
tiny_negative_radius_rng = Xoshiro(1)
@test_throws ArgumentError scale_free(
tiny_negative_radius_rng, T, 4, 4;
initial_nodes = 2, attachments = 1, radius,
)
@test rand(tiny_negative_radius_rng) == rand(Xoshiro(1))
end
@test_throws ArgumentError scale_free(
Xoshiro(1), Int, 4, 4; initial_nodes = 2, attachments = 1,
)
@test_throws ArgumentError scale_free(
Xoshiro(1), ComplexF32, 4, 4; initial_nodes = 2, attachments = 1,
)

@test_throws DimensionMismatch scale_free(
MersenneTwister(42), 20, 19; initial_nodes = 4, attachments = 2
)
@test_throws ArgumentError scale_free(
MersenneTwister(42), 20, 20; initial_nodes = 1, attachments = 1
)
@test_throws ArgumentError scale_free(
MersenneTwister(42), 20, 20; initial_nodes = 21, attachments = 1
)
@test_throws ArgumentError scale_free(
MersenneTwister(42), 20, 20; initial_nodes = 4, attachments = 0
)
@test_throws ArgumentError scale_free(
MersenneTwister(42), 20, 20; initial_nodes = 4, attachments = 5
)
end

@testset "Small-world initializer" begin
zero_rewiring = small_world(
MersenneTwister(42), Float64, 20, 20;
Expand Down
Loading