diff --git a/docs/src/api/inits.md b/docs/src/api/inits.md index 3397676c0..716707189 100644 --- a/docs/src/api/inits.md +++ b/docs/src/api/inits.md @@ -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 diff --git a/docs/src/api/inits/scale_free.md b/docs/src/api/inits/scale_free.md new file mode 100644 index 000000000..960f69a94 --- /dev/null +++ b/docs/src/api/inits/scale_free.md @@ -0,0 +1,5 @@ +# scale_free + +```@docs + scale_free +``` diff --git a/src/ReservoirComputing.jl b/src/ReservoirComputing.jl index 128121d89..5309896c2 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, 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! diff --git a/src/inits/inits_reservoir.jl b/src/inits/inits_reservoir.jl index 0760b59b9..189e021ce 100644 --- a/src/inits/inits_reservoir.jl +++ b/src/inits/inits_reservoir.jl @@ -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( @@ -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) @@ -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...) diff --git a/test/inits_tests.jl b/test/inits_tests.jl index 7e3995877..ed2498ff3 100644 --- a/test/inits_tests.jl +++ b/test/inits_tests.jl @@ -72,6 +72,125 @@ begin ] @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( + 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;