docs: move reca tutorials over to ReservoirCellularAutomata

Author: MartinuzziFrancesco

docs/pages.jl

@@ -1,23 +1,22 @@
 pages = [
     "ReservoirComputing.jl" => "index.md",
     "General Settings" => Any[
-        "Changing Training Algorithms" => "general/different_training.md",
-        "Altering States" => "general/states_variation.md",
-        "Generative vs Predictive" => "general/predictive_generative.md"],
+        "Changing Training Algorithms"=>"general/different_training.md",
+        "Altering States"=>"general/states_variation.md",
+        "Generative vs Predictive"=>"general/predictive_generative.md"],
     "Echo State Network Tutorials" => Any[
-        "Lorenz System Forecasting" => "esn_tutorials/lorenz_basic.md",
+        "Lorenz System Forecasting"=>"esn_tutorials/lorenz_basic.md",
         #"Mackey-Glass Forecasting on GPU" => "esn_tutorials/mackeyglass_basic.md",
-        "Using Different Layers" => "esn_tutorials/change_layers.md",
-        "Using Different Reservoir Drivers" => "esn_tutorials/different_drivers.md",
+        "Using Different Layers"=>"esn_tutorials/change_layers.md",
+        "Using Different Reservoir Drivers"=>"esn_tutorials/different_drivers.md",
         #"Using Different Training Methods" => "esn_tutorials/different_training.md",
-        "Deep Echo State Networks" => "esn_tutorials/deep_esn.md",
-        "Hybrid Echo State Networks" => "esn_tutorials/hybrid.md"],
-    "Reservoir Computing with Cellular Automata" => "reca_tutorials/reca.md",
-    "API Documentation" => Any["Training Algorithms" => "api/training.md",
-        "States Modifications" => "api/states.md",
-        "Prediction Types" => "api/predict.md",
-        "Echo State Networks" => "api/esn.md",
-        "ESN Initializers" => "api/inits.md",
-        "ESN Drivers" => "api/esn_drivers.md",
-        "ESN Variations" => "api/esn_variations.md"]
+        "Deep Echo State Networks"=>"esn_tutorials/deep_esn.md",
+        "Hybrid Echo State Networks"=>"esn_tutorials/hybrid.md"],
+    "API Documentation" => Any["Training Algorithms"=>"api/training.md",
+        "States Modifications"=>"api/states.md",
+        "Prediction Types"=>"api/predict.md",
+        "Echo State Networks"=>"api/esn.md",
+        "ESN Initializers"=>"api/inits.md",
+        "ESN Drivers"=>"api/esn_drivers.md",
+        "ESN Variations"=>"api/esn_variations.md"]
 ]

docs/src/reca_tutorials/reca.md

@@ -1,4 +1,5 @@
 pages = [
     "ReservoirCellularAutomata.jl" => "index.md",
+    "Solving the 5 bit memory task" => "reca_tutorials/fbmt.md",
     "API Manual" => "api/reca.md"
 ]

lib/ReservoirCellularAutomata/docs/pages.jl

@@ -0,0 +1,61 @@
+# Reservoir Computing using Cellular Automata
+
+Reservoir Computing based on Cellular Automata ReCA
+[Yilmaz2014](@cite) [Margem2017](@cite) proposes the advantage of storing the reservoir
+states as binary data. Less parameter tuning represents another advantage of this model.
+The architecture implemented in ReservoirCellularAutomata.jl follows [Nichele2017](@cite)
+which builds on top of the original implementation, improving the results.
+It is strongly suggested to go through the paper to get a solid understanding of the model
+before delving into experimentation with the code.
+
+To showcase how to use these models, this page illustrates the performance of
+ReCA in the 5 bit memory task.
+
+## 5 bit memory task
+
+The data can be read as follows:
+
+```@example reca
+using DelimitedFiles
+
+input = readdlm("./5bitinput.txt", ',', Float64)
+output = readdlm("./5bitoutput.txt", ',', Float64)
+```
+
+To use a ReCA model, it is necessary to define the rule one intends to use. To do so,
+ReservoirCellularAutomata.jl leverages
+[CellularAutomata.jl](https://github.com/MartinuzziFrancesco/CellularAutomata.jl).
+All the functionalities of CellularAutomata.jl are reexported in ReservoirCellularAutomata.
+
+```@example reca
+using ReservoirCellularAutomata
+
+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))
+```
+
+After this, the training can be performed with the chosen method.
+
+```@example reca
+output_layer = train(reca, output, 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):
+
+```@example reca
+prediction = reca(Predictive(input), output_layer)
+final_pred = convert(AbstractArray{Float32}, prediction .> 0.5)
+
+final_pred == output
+```

docs/src/reca_tutorials/5bitinput.txt renamed to lib/ReservoirCellularAutomata/docs/src/reca_tutorials/5bitinput.txt

@@ -4,13 +4,14 @@ using CellularAutomata: CellularAutomaton
 using Random: randperm
 using Reexport: @reexport
 using ReservoirComputing
+@reexport using CellularAutomata
 @reexport import ReservoirComputing: NLADefault, NLAT1, NLAT2, NLAT3, PartialSquare,
-                                     ExtendedSquare,
-                                     StandardStates, ExtendedStates, PaddedStates,
-                                     PaddedExtendedStates, StandardRidge, Generative,
-                                     Predictive, OutputLayer
+    ExtendedSquare,
+    StandardStates, ExtendedStates, PaddedStates,
+    PaddedExtendedStates, StandardRidge, Generative,
+    Predictive, OutputLayer
 import ReservoirComputing: train, AbstractReservoirComputer, AbstractOutputLayer,
-                           obtain_prediction, next_state_prediction!
+    obtain_prediction, next_state_prediction!
 
 include("reca.jl")
 include("reca_input_encodings.jl")