refactor: align RECA to new apis

Author: MartinuzziFrancesco

docs/src/reca_tutorials/reca.md

@@ -18,31 +18,37 @@ output = readdlm("./5bitoutput.txt", ',', Float64)
 To use a ReCA model, it is necessary to define the rule one intends to use. To do so, ReservoirComputing.jl leverages [CellularAutomata.jl](https://github.com/MartinuzziFrancesco/CellularAutomata.jl) that needs to be called as well to define the `RECA` struct:
 
 ```@example reca
-using ReservoirComputing, CellularAutomata
+using ReservoirComputing, CellularAutomata, Random
+Random.seed!(42)
+rng = MersenneTwister(17)
 
 ca = DCA(90)
 ```
 
 To define the ReCA model, it suffices to call:
 
 ```@example reca
-reca = RECA(input, ca;
-    generations=16,
-    input_encoding=RandomMapping(16, 40))
+reca = RECA(4, 4, DCA(90);
+           generations=16,
+           input_encoding=RandomMapping(16, 40))
+ps, st = setup(rng, reca)
 ```
-
 After this, the training can be performed with the chosen method.
 
 ```@example reca
-output_layer = train(reca, output, StandardRidge(0.00001))
+ps, st = train!(reca, input, output, ps, st, StandardRidge(0.00001))
 ```
 
-The prediction in this case will be a `Predictive()` with the input data equal to the training data. In addition, to test the 5 bit memory task, a conversion from Float to Bool is necessary (at the moment, we are aware of a bug that doesn't allow boolean input data to the RECA models):
+We are going to test the recall ability of the model, feeding the input data
+and investigating wether the predicted output equals the output data.
+In addition, to test the 5 bit memory task, a conversion from Float to Bool
+is necessary (at the moment, we are aware of a bug that doesn't allow boolean
+input data to the RECA models):
 
 ```@example reca
-prediction = reca(Predictive(input), output_layer)
+_, st0 = setup(rng, reca) #reset the first ca state
+pred_out, st = predict(reca, input, ps, st0)
 final_pred = convert(AbstractArray{Float32}, prediction .> 0.5)
 
 final_pred == output
 ```
-

ext/RCCellularAutomataExt.jl

@@ -1,65 +1,62 @@
 module RCCellularAutomataExt
-using ReservoirComputing: RECA, RandomMapping, RandomMaps
-import ReservoirComputing: train, next_state_prediction!, AbstractOutputLayer, NLADefault,
-                           StandardStates, obtain_prediction
+using ReservoirComputing: RECA, RandomMapping, RandomMaps, AbstractInputEncoding,
+    IntegerType, Readout, ReservoirChain, StatefulLayer
+import ReservoirComputing: RECACell, RECA
 using CellularAutomata
 using Random: randperm
 
-function RECA(train_data,
-        automata;
-        generations = 8,
-        input_encoding = RandomMapping(),
-        nla_type = NLADefault(),
-        states_type = StandardStates())
-    in_size = size(train_data, 1)
-    #res_size = obtain_res_size(input_encoding, generations)
-    state_encoding = create_encoding(input_encoding, train_data, generations)
-    states = reca_create_states(state_encoding, automata, train_data)
-
-    return RECA(train_data, automata, state_encoding, nla_type, states, states_type)
+function (reca::RECACell)((inp, (ca_prev,)), ps, st::NamedTuple)
+    rm = reca.enc
+    T = eltype(inp)
+    ca0 = T.(encoding(rm, inp, T.(ca_prev)))
+    ca = CellularAutomaton(reca.automaton, ca0, rm.generations + 1)
+    evo = ca.evolution
+    feat2T = evo[2:end, :]
+    feats = reshape(permutedims(feat2T), rm.states_size)
+    ca_last = evo[end, :]
+    return (T.(feats), (T.(ca_last),)), st
 end
 
-#training dispatch
-function train(reca::RECA, target_data, training_method = StandardRidge; kwargs...)
-    states_new = reca.states_type(reca.nla_type, reca.states, reca.train_data)
-    return train(training_method, Float32.(states_new), Float32.(target_data); kwargs...)
+function (reca::RECACell)(inp::AbstractVector, ps, st::NamedTuple)
+    ca = st.ca
+    return reca((inp, (ca,)), ps, st)
 end
 
-#predict dispatch
-function (reca::RECA)(prediction,
-        output_layer::AbstractOutputLayer,
-        initial_conditions = output_layer.last_value,
-        last_state = zeros(reca.input_encoding.ca_size))
-    return obtain_prediction(reca, prediction, last_state, output_layer;
-        initial_conditions = initial_conditions)
-end
+function RECA(in_dims::IntegerType,
+    out_dims::IntegerType,
+    automaton;
+    input_encoding::AbstractInputEncoding=RandomMapping(),
+    generations::Integer=8,
+    state_modifiers=(),
+    readout_activation=identity)
+
+    rm = create_encoding(input_encoding, in_dims, generations)
+    cell = RECACell(automaton, rm)
+
+    mods = state_modifiers isa Tuple || state_modifiers isa AbstractVector ?
+           Tuple(state_modifiers) : (state_modifiers,)
 
-function next_state_prediction!(reca::RECA, x, out, i, args...)
-    rm = reca.input_encoding
-    x = encoding(rm, out, x)
-    ca = CellularAutomaton(reca.automata, x, rm.generations + 1)
-    ca_states = ca.evolution[2:end, :]
-    x_new = reshape(transpose(ca_states), rm.states_size)
-    x = ca.evolution[end, :]
-    return x, x_new
+    ro = Readout(rm.states_size => out_dims, readout_activation)
+
+    return ReservoirChain((StatefulLayer(cell), mods..., ro)...)
 end
 
-function RandomMapping(; permutations = 8, expansion_size = 40)
+function RandomMapping(; permutations=8, expansion_size=40)
     RandomMapping(permutations, expansion_size)
 end
 
-function RandomMapping(permutations; expansion_size = 40)
+function RandomMapping(permutations; expansion_size=40)
     RandomMapping(permutations, expansion_size)
 end
 
-function create_encoding(rm::RandomMapping, input_data, generations)
-    maps = init_maps(size(input_data, 1), rm.permutations, rm.expansion_size)
+function create_encoding(rm::RandomMapping, in_dims::IntegerType, generations::IntegerType)
+    maps = init_maps(in_dims, rm.permutations, rm.expansion_size)
     states_size = generations * rm.expansion_size * rm.permutations
     ca_size = rm.expansion_size * rm.permutations
-    return RandomMaps(rm.permutations, rm.expansion_size, generations, maps, states_size,
-        ca_size)
+    return RandomMaps(rm.permutations, rm.expansion_size, generations, maps, states_size, ca_size)
 end
 
+
 function reca_create_states(rm::RandomMaps, automata, input_data)
     train_time = size(input_data, 2)
     states = zeros(rm.states_size, train_time)
@@ -82,21 +79,21 @@ function encoding(rm::RandomMaps, input_vector, tot_encoded_vector)
     new_tot_enc_vec = copy(tot_encoded_vector)
 
     for i in 1:(rm.permutations)
-        new_tot_enc_vec[((i - 1) * rm.expansion_size + 1):(i * rm.expansion_size)] = single_encoding(
+        new_tot_enc_vec[((i-1)*rm.expansion_size+1):(i*rm.expansion_size)] = single_encoding(
             input_vector,
-            new_tot_enc_vec[((i - 1) * rm.expansion_size + 1):(i * rm.expansion_size)],
+            new_tot_enc_vec[((i-1)*rm.expansion_size+1):(i*rm.expansion_size)],
             rm.maps[i,
-            :])
+                :])
     end
 
     return new_tot_enc_vec
 end
 
-#function obtain_res_size(rm::RandomMapping, generations)
-#    generations*rm.expansion_size*rm.permutations
-#end
-
 function single_encoding(input_vector, encoded_vector, map)
+    @assert length(map) == length(input_vector) """
+        RandomMaps mismatch: map length = $(length(map)) but input length = $(length(input_vector)).
+        (Build RandomMaps with in_dims = size(input, 1) used at training time.)
+        """
     new_enc_vec = copy(encoded_vector)
 
     for i in 1:size(input_vector, 1)

src/ReservoirComputing.jl

@@ -59,7 +59,7 @@ export add_jumps!, backward_connection!, delay_line!, reverse_simple_cycle!,
 export train
 export ESN, HybridESN, KnowledgeModel, DeepESN
 #reca
-export RECA
+export RECACell, RECA
 export RandomMapping, RandomMaps
 
 end #module

src/extensions/reca.jl

@@ -6,13 +6,50 @@ abstract type AbstractEncodingData end
     RandomMapping(permutations; expansion_size=40)
     RandomMapping(;permutations=8, expansion_size=40)
 
-Random mapping of the input data directly in the reservoir. The `expansion_size`
-determines the dimension of the single reservoir, and `permutations` determines the
-number of total reservoirs that will be connected, each with a different mapping.
-The detail of this implementation can be found in [1].
+Specify the **random input embedding** used by the Cellular Automata reservoir.
+Each time step, the input vector of length `in_dims` is randomly placed into a
+larger 1D lattice of length `expansion_size`, and this is repeated for
+`permutations` independent lattices (blocks). The concatenation of these blocks
+forms the CA initial condition of length: `ca_size = expansion_size * permutations`.
+The detail of this implementation can be found in [Nichele2017](@cite).
 
-[1] Nichele, Stefano, and Andreas Molund. “Deep reservoir computing using cellular
-automata.” arXiv preprint arXiv:1703.02806 (2017).
+## Arguments
+
+- `permutations`: number of independent random maps (blocks). Larger
+  values increase feature diversity and `ca_size` proportionally.
+- `expansion_size`: width of each block (the size of a single CA
+  lattice). Larger values increase the spatial resolution and both `ca_size`
+  and `states_size`.
+
+## Usage
+
+This is a **configuration object**; it does not perform the mapping by itself.
+Create the concrete tables with `create_encoding` and pass them to
+[`RECACell`](@ref):
+
+```julia
+using ReservoirComputing, CellularAutomata, Random
+
+in_dims = 4
+generations = 8
+mapping = RandomMapping(permutations=8, expansion_size=40)
+
+enc = ReservoirComputing.create_encoding(mapping, in_dims, generations)  # → RandomMaps
+cell = RECACell(DCA(90), enc)
+
+rc = ReservoirChain(
+    StatefulLayer(cell),
+    Readout(enc.states_size => in_dims; include_collect=true)
+)
+```
+
+Or let [`RECA`](@ref) do this for you:
+
+```julia
+rc = RECA(in_dims=4, out_dims=4, DCA(90);
+          input_encoding = RandomMapping(permutations=8, expansion_size=40),
+          generations = 8)
+```
 """
 struct RandomMapping{I,T} <: AbstractInputEncoding
     permutations::I
@@ -28,28 +65,112 @@ struct RandomMaps{T,E,G,M,S} <: AbstractEncodingData
     ca_size::S
 end
 
-abstract type AbstractReca end
+@doc raw"""
+    RECACell(automaton, enc::RandomMaps)
+
+Cellular Automata (CA)–based reservoir recurrent cell. At each time step,
+the input vector is randomly embedded into a CA configuration, the CA is
+evolved for a fixed number of generations, and the flattened CA evolution
+is emitted as the reservoir state. The last CA configuration is carried
+to the next step. For more details please refer to [Nichele2017](@cite),
+and [Yilmaz2014](@cite).
+
+## Arguments
+
+  - `automaton`: A cellular automaton rule/object from `CellularAutomata.jl`
+    (e.g., `DCA(90)`, `DCA(30)`, …).
+
+  - `enc`: Precomputed random-mapping/encoding metadata given as a
+    [`RandomMapping`](@ref).
+
+## Inputs
+
+  - Case A: a single input vector `x` with length
+    `in_dims`. The cell internally uses the stored CA state (`st.ca`) as the
+    previous configuration.
+
+  - Case B: a tuple `(x, (ca,))` where `x` is as above and
+    `ca` has length `enc.ca_size`.
+
+## Computation
+
+1. Random embedding of `x` into a CA initial condition `c₀` using `enc.maps`
+   across `enc.permutations` blocks of length `enc.expansion_size`.
+
+2. CA evolution for `G = enc.generations` steps with the given `automaton`,
+   producing an evolution matrix `E ∈ ℝ^{(G+1) × ca_size}` where `E[1,:] = c₀`
+   and `E[t+1,:] = F(E[t,:])`.
+
+3. Feature vector is the flattened stack of `E[2:end, :]` (dropping the
+   initial row), shaped as a column vector of length `enc.states_size`.
+
+4. Carry is the final CA configuration `E[end, :]`.
+
+## Returns
+
+  - Output: `(h, (caₙ,))` where
+      * `h` has length `enc.states_size` (the CA features),
+      * `caₙ` has length `enc.ca_size` (next carry).
+  - Updated (unchanged) cell state (parameters-free layer state).
+
+## Parameters & State
+
+  - Parameters: none
+  - State: `(ca = zeros(Float32, enc.ca_size))`
 
 """
-    RECA(train_data,
-        automata;
-        generations = 8,
+@concrete struct RECACell <: AbstractReservoirRecurrentCell
+    automaton
+    enc <: RandomMaps
+end
+
+Base.show(io::IO, reca::RECACell) = print(io,
+    "RECACell(in ⇒ ", reca.enc.ca_size, ", out=", reca.enc.states_size,
+    ", gens=", reca.enc.generations, ", perms=", reca.enc.permutations,
+    ", exp=", reca.enc.expansion_size, ")")
+
+initialparameters(::AbstractRNG, ::RECACell) = NamedTuple()
+
+function initialstates(::AbstractRNG, reca::RECACell)
+    return (ca=zeros(Float32, reca.enc.ca_size),)
+end
+
+@doc raw"""
+    RECA(in_dims, out_dims, automaton;
         input_encoding=RandomMapping(),
-        nla_type = NLADefault(),
-        states_type = StandardStates())
+        generations=8, state_modifiers=(),
+        readout_activation=identity)
+
+Construct a cellular–automata reservoir model.
+
+At each time step the input vector is randomly embedded into a Cellular
+Automaton (CA) lattice, the CA is evolved for `generations` steps, and the
+flattened evolution (excluding the initial row) is used as the reservoir state.
+A linear [`Readout`](@ref) maps these features to `out_dims`.
 
-[1] Yilmaz, Ozgur. “_Reservoir computing using cellular automata._”
-arXiv preprint arXiv:1410.0162 (2014).
+!!! note
+    This constructor is only available when the `CellularAutomata.jl` package is
+    loaded.
 
-[2] Nichele, Stefano, and Andreas Molund. “_Deep reservoir computing using cellular
-automata._” arXiv preprint arXiv:1703.02806 (2017).
+## Arguments
+
+- `in_dims`: Number of input features (rows of training data).
+- `out_dims`: Number of output features (rows of target data).
+- `automaton`: A CA rule/object from `CellularAutomata.jl` (e.g. `DCA(90)`,
+  `DCA(30)`, …).
+
+## Keyword Arguments
+
+- `input_encoding`: Random embedding spec with
+  fields `permutations` and `expansion_size`.
+  Default is `RandomMapping()`.
+- `generations`: Number of CA generations to evolve per time step.
+  Default is 8.
+- `state_modifiers`: Optional tuple/vector of additional layers applied
+  after the CA cell and before the readout (e.g., `NLAT2()`, `Pad(1.0)`,
+  custom transforms, etc.). Functions are wrapped automatically.
+  Default is none.
+- `readout_activation`: Activation applied by the readout
+  Default is `identity`.
 """
-struct RECA{S,R,E,N,T,Q} <: AbstractReca
-    #res_size::I
-    train_data::S
-    automata::R
-    input_encoding::E
-    nla_type::N
-    states::T
-    states_type::Q
-end
+RECA(::Any...) = error("RECA requires CellularAutomata.jl; use it to enable this constructor.")