merge

SciML · Nov 16, 2022 · b4bce7a · b4bce7a
1 parent 6be916f
commit b4bce7a
Show file tree

Hide file tree

Showing 12 changed files with 169 additions and 45 deletions.
diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml
@@ -21,4 +21,8 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
-        run: julia --project=docs/ docs/make.jl
+        run: julia --project=docs/ --code-coverage=user docs/make.jl
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v1
+        with:
+          file: lcov.info
diff --git a/.github/workflows/Invalidations.yml b/.github/workflows/Invalidations.yml
@@ -0,0 +1,40 @@
+name: Invalidations
+
+on:
+  pull_request:
+
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: always.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  evaluate:
+    # Only run on PRs to the default branch.
+    # In the PR trigger above branches can be specified only explicitly whereas this check should work for master, main, or any other default branch
+    if: github.base_ref == github.event.repository.default_branch
+    runs-on: ubuntu-latest
+    steps:
+    - uses: julia-actions/setup-julia@v1
+      with:
+        version: '1'
+    - uses: actions/checkout@v3
+    - uses: julia-actions/julia-buildpkg@v1
+    - uses: julia-actions/julia-invalidations@v1
+      id: invs_pr
+
+    - uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.repository.default_branch }}
+    - uses: julia-actions/julia-buildpkg@v1
+    - uses: julia-actions/julia-invalidations@v1
+      id: invs_default
+
+    - name: Report invalidation counts
+      run: |
+        echo "Invalidations on default branch: ${{ steps.invs_default.outputs.total }} (${{ steps.invs_default.outputs.deps }} via deps)" >> $GITHUB_STEP_SUMMARY
+        echo "This branch: ${{ steps.invs_pr.outputs.total }} (${{ steps.invs_pr.outputs.deps }} via deps)" >> $GITHUB_STEP_SUMMARY
+    - name: Check if the PR does increase number of invalidations
+      if: steps.invs_pr.outputs.total > steps.invs_default.outputs.total
+      run: exit 1
diff --git a/CITATION.bib b/CITATION.bib
@@ -1,10 +1,10 @@
-@misc{https://doi.org/10.48550/arxiv.2204.05117,
-  doi = {10.48550/ARXIV.2204.05117},
-  url = {https://arxiv.org/abs/2204.05117},
-  author = {Martinuzzi, Francesco and Rackauckas, Chris and Abdelrehim, Anas and Mahecha, Miguel D. and Mora, Karin},
-  keywords = {Computational Engineering, Finance, and Science (cs.CE), Artificial Intelligence (cs.AI), FOS: Computer and information sciences, FOS: Computer and information sciences},
-  title = {ReservoirComputing.jl: An Efficient and Modular Library for Reservoir Computing Models},
-  publisher = {arXiv},
-  year = {2022},
-  copyright = {Creative Commons Attribution 4.0 International}
+@article{JMLR:v23:22-0611,
+  author  = {Francesco Martinuzzi and Chris Rackauckas and Anas Abdelrehim and Miguel D. Mahecha and Karin Mora},
+  title   = {ReservoirComputing.jl: An Efficient and Modular Library for Reservoir Computing Models},
+  journal = {Journal of Machine Learning Research},
+  year    = {2022},
+  volume  = {23},
+  number  = {288},
+  pages   = {1--8},
+  url     = {http://jmlr.org/papers/v23/22-0611.html}
 }
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "ReservoirComputing"
 uuid = "7c2d2b1e-3dd4-11ea-355a-8f6a8116e294"
 authors = ["Francesco Martinuzzi"]
-version = "0.9.0"
+version = "0.9.1"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"
@@ -22,7 +22,7 @@ CellularAutomata = "0.0.2"
 Distances = "0.10"
 Distributions = "0.24, 0.25"
 LIBSVM = "0.8"
-MLJLinearModels = "0.5, 0.6, 0.7"
+MLJLinearModels = "0.5, 0.6, 0.7, 0.8"
 NNlib = "0.8.4"
 Optim = "1"
 julia = "1.6"

diff --git a/README.md b/README.md
@@ -1,13 +1,19 @@
 # ReservoirComputing.jl
 
-![rc_full_logo_large_white_cropped](https://user-images.githubusercontent.com/10376688/144242116-8243f58a-5ac6-4e0e-88d5-3409f00e20b4.png)
+[![Join the chat at https://julialang.zulipchat.com #sciml-bridged](https://img.shields.io/static/v1?label=Zulip&message=chat&color=9558b2&labelColor=389826)](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged)
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](http://nonlinearsolve.sciml.ai/stable/)
+[![Global Docs](https://img.shields.io/badge/docs-SciML-blue.svg)](https://docs.sciml.ai/ReservoirComputing/stable/)
+ [![arXiv](https://img.shields.io/badge/arXiv-2204.05117-00b300.svg)](https://arxiv.org/abs/2204.05117)
+
+[![codecov](https://codecov.io/gh/SciML/ReservoirComputing.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/SciML/ReservoirComputing.jl)
+[![Build Status](https://github.com/SciML/ReservoirComputing.jl/workflows/CI/badge.svg)](https://github.com/SciML/ReservoirComputing.jl/actions?query=workflow%3ACI)
 
-| **Documentation** | **Build Status** | **Reference** |
-|:----------:|:----------:|:----------:|
-| [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](http://reservoir.sciml.ai/stable/) [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](http://reservoir.sciml.ai/dev/) | [![Build Status](https://github.com/SciML/ReservoirComputing.jl/workflows/CI/badge.svg)](https://github.com/SciML/ReservoirComputing.jl/actions?query=workflow%3ACI) [![codecov](https://codecov.io/gh/SciML/ReservoirComputing.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/SciML/ReservoirComputing.jl) | [![arXiv](https://img.shields.io/badge/arXiv-2204.05117-00b300.svg)](https://arxiv.org/abs/2204.05117)
+[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
+[![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle)
 
+![rc_full_logo_large_white_cropped](https://user-images.githubusercontent.com/10376688/144242116-8243f58a-5ac6-4e0e-88d5-3409f00e20b4.png)
 
-ReservoirComputing.jl provides an efficient, modular and easy to use implementation of Reservoir Computing models such as Echo State Networks (ESNs). For information on using this package please refer to the [stable documentation](http://reservoir.sciml.ai/stable/). Use the [in-development documentation](http://reservoir.sciml.ai/dev/) to take a look at at not yet released features.
+ReservoirComputing.jl provides an efficient, modular and easy to use implementation of Reservoir Computing models such as Echo State Networks (ESNs). For information on using this package please refer to the [stable documentation](https://docs.sciml.ai/ReservoirComputing/stable/). Use the [in-development documentation](https://docs.sciml.ai/ReservoirComputing/dev/) to take a look at at not yet released features.
 
 ## Quick Example
 
@@ -75,14 +81,14 @@ plot!(transpose(test)[:,1], transpose(test)[:,2], transpose(test)[:,3], label="a
 If you use this library in your work, please cite:
 
 ```bibtex
-@misc{https://doi.org/10.48550/arxiv.2204.05117,
-  doi = {10.48550/ARXIV.2204.05117},
-  url = {https://arxiv.org/abs/2204.05117},
-  author = {Martinuzzi, Francesco and Rackauckas, Chris and Abdelrehim, Anas and Mahecha, Miguel D. and Mora, Karin},
-  keywords = {Computational Engineering, Finance, and Science (cs.CE), Artificial Intelligence (cs.AI), FOS: Computer and information sciences, FOS: Computer and information sciences},
-  title = {ReservoirComputing.jl: An Efficient and Modular Library for Reservoir Computing Models},
-  publisher = {arXiv},
-  year = {2022},
-  copyright = {Creative Commons Attribution 4.0 International}
+@article{JMLR:v23:22-0611,
+  author  = {Francesco Martinuzzi and Chris Rackauckas and Anas Abdelrehim and Miguel D. Mahecha and Karin Mora},
+  title   = {ReservoirComputing.jl: An Efficient and Modular Library for Reservoir Computing Models},
+  journal = {Journal of Machine Learning Research},
+  year    = {2022},
+  volume  = {23},
+  number  = {288},
+  pages   = {1--8},
+  url     = {http://jmlr.org/papers/v23/22-0611.html}
 }
 ```
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,13 +1,16 @@
 using Documenter, ReservoirComputing
 
+cp("./docs/Manifest.toml", "./docs/src/assets/Manifest.toml", force = true)
+cp("./docs/Project.toml", "./docs/src/assets/Project.toml", force = true)
+
 include("pages.jl")
 
 makedocs(modules = [ReservoirComputing],
          clean = true, doctest = false,
          sitename = "ReservoirComputing.jl",
          format = Documenter.HTML(analytics = "UA-90474609-3",
                                   assets = ["assets/favicon.ico"],
-                                  canonical = "https://reservoircomputing.sciml.ai/stable/"),
+                                  canonical = "https://docs.sciml.ai/ReservoirComputing/stable/"),
          pages = pages)
 
 deploydocs(repo = "github.com/SciML/ReservoirComputing.jl.git";

diff --git a/docs/src/esn_tutorials/different_drivers.md b/docs/src/esn_tutorials/different_drivers.md
@@ -33,7 +33,7 @@ f4(x) = x/sqrt(1+x*x)
 
 It is now possible to build different drivers, using the parameters suggested by the paper. Also in this instance the numbering follows the test cases of the paper. In the end a simple for loop is implemented to compare the different drivers and activation functions.
 ```julia
-using Reservoir Computing, Random
+using ReservoirComputing, Random
 
 #fix seed for reproducibility
 Random.seed!(42)

diff --git a/docs/src/esn_tutorials/lorenz_basic.md b/docs/src/esn_tutorials/lorenz_basic.md
@@ -86,6 +86,10 @@ Once the ```OutputLayer``` has been obtained the prediction can be done followin
 output = esn(Generative(predict_len), output_layer)
 ```
 both the training method and the output layer are needed in this call. The number of steps for the prediction must be specified to the ```Generative``` method. The output results are given in a matrix. 
+
+!!! info "Saving the states during prediction"
+    While the states are saved in the `ESN` struct for the training, for the prediction they are not saved by default. To inspect the states it is necessary to pass the boolean keyword argument `save_states` to the prediction call, in this example using `esn(... ; save_states=true)`. This returns a tuple `(output, states)` where `size(states) = res_size, prediction_len`
+
 To inspect the results they can easily be plotted using an external library. In this case ```Plots``` is adopted:
 ```julia
 using Plots, Plots.PlotMeasures

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -88,14 +88,69 @@ Contributions are very welcomed! Some interesting variation of RC models are pos
 If you use this library in your work, please cite:
 
 ```bibtex
-@misc{https://doi.org/10.48550/arxiv.2204.05117,
-  doi = {10.48550/ARXIV.2204.05117},
-  url = {https://arxiv.org/abs/2204.05117},
-  author = {Martinuzzi, Francesco and Rackauckas, Chris and Abdelrehim, Anas and Mahecha, Miguel D. and Mora, Karin},
-  keywords = {Computational Engineering, Finance, and Science (cs.CE), Artificial Intelligence (cs.AI), FOS: Computer and information sciences, FOS: Computer and information sciences},
-  title = {ReservoirComputing.jl: An Efficient and Modular Library for Reservoir Computing Models},
-  publisher = {arXiv},
-  year = {2022},
-  copyright = {Creative Commons Attribution 4.0 International}
+@article{JMLR:v23:22-0611,
+  author  = {Francesco Martinuzzi and Chris Rackauckas and Anas Abdelrehim and Miguel D. Mahecha and Karin Mora},
+  title   = {ReservoirComputing.jl: An Efficient and Modular Library for Reservoir Computing Models},
+  journal = {Journal of Machine Learning Research},
+  year    = {2022},
+  volume  = {23},
+  number  = {288},
+  pages   = {1--8},
+  url     = {http://jmlr.org/papers/v23/22-0611.html}
 }
 ```
+
+## Reproducibility
+```@raw html
+<details><summary>The documentation of this SciML package was built using these direct dependencies,</summary>
+```
+```@example
+using Pkg # hide
+Pkg.status() # hide
+```
+```@raw html
+</details>
+```
+```@raw html
+<details><summary>and using this machine and Julia version.</summary>
+```
+```@example
+using InteractiveUtils # hide
+versioninfo() # hide
+```
+```@raw html
+</details>
+```
+```@raw html
+<details><summary>A more complete overview of all dependencies and their versions is also provided.</summary>
+```
+```@example
+using Pkg # hide
+Pkg.status(;mode = PKGMODE_MANIFEST) # hide
+```
+```@raw html
+</details>
+```
+```@raw html
+You can also download the 
+<a href="
+```
+```@eval
+using TOML
+version = TOML.parse(read("../../Project.toml",String))["version"]
+name = TOML.parse(read("../../Project.toml",String))["name"]
+link = "https://github.com/SciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Manifest.toml"
+```
+```@raw html
+">manifest</a> file and the
+<a href="
+```
+```@eval
+using TOML
+version = TOML.parse(read("../../Project.toml",String))["version"]
+name = TOML.parse(read("../../Project.toml",String))["name"]
+link = "https://github.com/SciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Project.toml"
+```
+```@raw html
+">project</a> file.
+```
diff --git a/src/esn/echostatenetwork.jl b/src/esn/echostatenetwork.jl
@@ -164,8 +164,8 @@ end
 
 function (esn::ESN)(prediction::AbstractPrediction,
                     output_layer::AbstractOutputLayer;
-                    initial_conditions = output_layer.last_value,
-                    last_state = esn.states[:, [end]])
+                    last_state = esn.states[:, [end]],
+                    kwargs...)
     variation = esn.variation
     pred_len = prediction.prediction_len
 
@@ -178,10 +178,10 @@ function (esn::ESN)(prediction::AbstractPrediction,
         model_pred_data = model(u0, tspan_new, predict_tsteps)[:, 2:end]
         return obtain_esn_prediction(esn, prediction, last_state, output_layer,
                                      model_pred_data;
-                                     initial_conditions = initial_conditions)
+                                     kwargs...)
     else
         return obtain_esn_prediction(esn, prediction, last_state, output_layer;
-                                     initial_conditions = initial_conditions)
+                                     kwargs...)
     end
 end
 

diff --git a/src/esn/esn_predict.jl b/src/esn/esn_predict.jl
@@ -3,13 +3,15 @@ function obtain_esn_prediction(esn,
                                x,
                                output_layer,
                                args...;
-                               initial_conditions = output_layer.last_value)
+                               initial_conditions = output_layer.last_value,
+                               save_states = false)
     out_size = output_layer.out_size
     training_method = output_layer.training_method
     prediction_len = prediction.prediction_len
 
     output = output_storing(training_method, out_size, prediction_len, typeof(esn.states))
     out = initial_conditions
+    states = similar(esn.states, size(esn.states, 1), prediction_len)
 
     out_pad = allocate_outpad(esn.variation, esn.states_type, out)
     tmp_array = allocate_tmp(esn.reservoir_driver, typeof(esn.states), esn.res_size)
@@ -20,23 +22,26 @@ function obtain_esn_prediction(esn,
                                           args...)
         out_tmp = get_prediction(output_layer.training_method, output_layer, x_new)
         out = store_results!(output_layer.training_method, out_tmp, output, i)
+        states[:, i] = x
     end
 
-    return output
+    save_states ? (output, states) : output
 end
 
 function obtain_esn_prediction(esn,
                                prediction::Predictive,
                                x,
                                output_layer,
                                args...;
-                               initial_conditions = output_layer.last_value)
+                               initial_conditions = output_layer.last_value,
+                               save_states = false)
     out_size = output_layer.out_size
     training_method = output_layer.training_method
     prediction_len = prediction.prediction_len
 
     output = output_storing(training_method, out_size, prediction_len, typeof(esn.states))
     out = initial_conditions
+    states = similar(esn.states, size(esn.states, 1), prediction_len)
 
     out_pad = allocate_outpad(esn.variation, esn.states_type, out)
     tmp_array = allocate_tmp(esn.reservoir_driver, typeof(esn.states), esn.res_size)
@@ -47,9 +52,10 @@ function obtain_esn_prediction(esn,
                                           out_pad, i, tmp_array, args...)
         out_tmp = get_prediction(training_method, output_layer, x_new)
         out = store_results!(training_method, out_tmp, output, i)
+        states[:, i] = x
     end
 
-    return output
+    save_states ? (output, states) : output
 end
 
 #prediction dispatch on esn 

diff --git a/test/esn/test_train.jl b/test/esn/test_train.jl
@@ -26,3 +26,9 @@ for t in training_methods
     output = esn(Predictive(input_data), output_layer)
     @test mean(abs.(target_data .- output)) ./ mean(abs.(target_data)) < 0.21
 end
+
+for t in training_methods
+    output_layer = train(esn, target_data, t)
+    output, states = esn(Predictive(input_data), output_layer, save_states = true)
+    @test size(states) == (res_size, size(input_data, 2))
+end