docs

Author: MartinuzziFrancesco

docs/src/api/inits.md

@@ -7,6 +7,7 @@
     weighted_init
     informed_init
     minimal_init
+    chebyshev_mapping
 ```
 
 ## Reservoirs
@@ -18,4 +19,5 @@
     cycle_jumps
     simple_cycle
     pseudo_svd
+    chaotic_init
 ```

src/esn/esn_inits.jl

@@ -317,7 +317,25 @@ Subsequent rows are generated by applying the mapping:
   - `chebyshev_parameter`: Control parameter for the Chebyshev mapping in
     subsequent rows. This parameter influences the distribution of the
     matrix elements. Default is one.
-  - `return_sparse`: If `true`, the function returns the matrix as a sparse matrix. Default is `true`.
+  - `return_sparse`: If `true`, the function returns the matrix as a sparse matrix. Default is `false`.
+
+# Examples
+
+```jldoctest
+julia> input_matrix = chebyshev_mapping(10, 3)
+10×3 Matrix{Float32}:
+ 0.866025  0.866025   1.22465f-16
+ 0.866025  0.866025  -4.37114f-8
+ 0.866025  0.866025  -4.37114f-8
+ 0.866025  0.866025  -4.37114f-8
+ 0.866025  0.866025  -4.37114f-8
+ 0.866025  0.866025  -4.37114f-8
+ 0.866025  0.866025  -4.37114f-8
+ 0.866025  0.866025  -4.37114f-8
+ 0.866025  0.866025  -4.37114f-8
+ 0.866025  0.866025  -4.37114f-8
+ 
+```
 
 [^xie2024]: Xie, Minzhi, Qianxue Wang, and Simin Yu.
     "Time Series Prediction of ESN Based on Chebyshev Mapping and Strongly
@@ -327,7 +345,7 @@ Subsequent rows are generated by applying the mapping:
 function chebyshev_mapping(rng::AbstractRNG, ::Type{T}, dims::Integer...;
         amplitude::AbstractFloat = one(T), sine_divisor::AbstractFloat = one(T),
         chebyshev_parameter::AbstractFloat = one(T),
-        return_sparse::Bool = true) where {T <: Number} 
+        return_sparse::Bool = false) where {T <: Number} 
     input_matrix = DeviceAgnostic.zeros(rng, T, dims...)
     n_rows, n_cols = dims[1], dims[2]
 
@@ -752,23 +770,80 @@ function digital_chaotic_adjacency(rng::AbstractRNG, bit_precision::Integer;
   return adjacency_matrix
 end
 
+"""
+    chaotic_init([rng], [T], dims...;
+        extra_edge_probability=T(0.1), spectral_radius=one(T),
+        return_sparse_matrix=true)
+
+Construct a chaotic reservoir matrix using a digital chaotic system [^xie2024].
+
+The matrix topology is derived from a strongly connected adjacency
+matrix based on a digital chaotic system operating at finite precision.
+If the requested matrix order does not exactly match a valid order the 
+closest valid order is used.
+
+# Arguments
+  - `rng`: Random number generator. Default is `Utils.default_rng()`
+    from WeightInitializers.
+  - `T`: Type of the elements in the reservoir matrix.
+    Default is `Float32`.
+  - `dims`: Dimensions of the reservoir matrix.
+
+# Keyword arguments
+  - `extra_edge_probability`: Probability of adding extra random edges in
+    the adjacency matrix to enhance connectivity. Default is 0.1.
+  - `desired_spectral_radius`: The target spectral radius for the
+    reservoir matrix. Default is one.
+  - `return_sparse_matrix`: If `true`, the function returns the
+    reservoir matrix as a sparse matrix. Default is `true`.
+
+# Examples
+
+```jldoctest
+julia> res_matrix = chaotic_init(8, 8)
+┌ Warning: 
+│ 
+│     Adjusting reservoir matrix order:
+│         from 8 (requested) to 4
+│     based on computed bit precision = 1. 
+│ 
+└ @ ReservoirComputing ~/.julia/dev/ReservoirComputing/src/esn/esn_inits.jl:805
+4×4 SparseArrays.SparseMatrixCSC{Float32, Int64} with 6 stored entries:
+   ⋅        -0.600945   ⋅          ⋅ 
+   ⋅          ⋅        0.132667   2.21354
+   ⋅        -2.60383    ⋅        -2.90391
+ -0.578156    ⋅         ⋅          ⋅ 
+
+```
+
+[^xie2024]: Xie, Minzhi, Qianxue Wang, and Simin Yu.
+    "Time Series Prediction of ESN Based on Chebyshev Mapping and Strongly
+    Connected Topology."
+    Neural Processing Letters 56.1 (2024): 30.
+"""
 function chaotic_init(rng::AbstractRNG, ::Type{T}, dims::Integer...;
         extra_edge_probability::AbstractFloat = T(0.1), spectral_radius::AbstractFloat = one(T),
         return_sparse_matrix::Bool = true) where {T <: Number}
 
     requested_order = first(dims)
     if length(dims) > 1 && dims[2] != requested_order
-        @warn "Using dims[1] = $requested_order for the chaotic reservoir matrix order."
+        @warn """\n
+            Using dims[1] = $requested_order for the chaotic reservoir matrix order.\n
+        """
     end
-    D_estimate = log2(requested_order) / 2
-    D_floor = max(floor(Int, D_estimate), 1)
-    D_ceil  = ceil(Int, D_estimate)
-    candidate_order_floor = 2^(2 * D_floor)
-    candidate_order_ceil  = 2^(2 * D_ceil)
-    chosen_bit_precision = abs(candidate_order_floor - requested_order) <= abs(candidate_order_ceil - requested_order) ? D_floor : D_ceil
+    d_estimate = log2(requested_order) / 2
+    d_floor = max(floor(Int, d_estimate), 1)
+    d_ceil  = ceil(Int, d_estimate)
+    candidate_order_floor = 2^(2 * d_floor)
+    candidate_order_ceil  = 2^(2 * d_ceil)
+    chosen_bit_precision = abs(candidate_order_floor - requested_order) <= abs(candidate_order_ceil - requested_order) ? d_floor : d_ceil
     actual_matrix_order = 2^(2 * chosen_bit_precision)
     if actual_matrix_order != requested_order
-        @warn "Chaotic reservoir matrix order adjusted from $requested_order to $actual_matrix_order based on computed bit precision = $chosen_bit_precision."
+        @warn """\n
+            Adjusting reservoir matrix order:
+                from $requested_order (requested) to $actual_matrix_order
+            based on computed bit precision = $chosen_bit_precision. \n
+        """
     end
 
     random_weight_matrix = T(2) * rand(rng, T, actual_matrix_order, actual_matrix_order) .- T(1)