esnfed 1.0.0__tar.gz

esnfed-1.0.0/.gitignore

@@ -0,0 +1,56 @@
+# LaTeX build artifacts
+*.aux
+*.bbl
+*.bcf
+*.blg
+*.fdb_latexmk
+*.fls
+*.log
+*.out
+*.run.xml
+*.synctex.gz
+*.toc
+*.lof
+*.lot
+*.nav
+*.snm
+*.vrb
+memoria/memoria.pdf
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+env/
+*.egg-info/
+dist/
+build/
+.ipynb_checkpoints/
+*.pyc
+.pytest_cache/
+
+# Data (may be large/licensed)
+datos/crudos/
+datos/procesados/
+!datos/crudos/.gitkeep
+!datos/procesados/.gitkeep
+
+# Generated outputs
+salidas/
+!salidas/.gitkeep
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Claude Code
+.claude/

esnfed-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dairon Andres Benites Aldaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

esnfed-1.0.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: esnfed
+Version: 1.0.0
+Summary: Echo State Networks for Federated Learning: reservoirs, topologies and federated strategies
+Project-URL: Homepage, https://github.com/daibeal/tfg-inf
+Project-URL: Repository, https://github.com/daibeal/tfg-inf
+Project-URL: Issues, https://github.com/daibeal/tfg-inf/issues
+Author-email: Dairon Andres Benites Aldaz <dairon.aldaz@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: echo state networks,ensemble learning,federated learning,machine learning,recurrent neural networks,reservoir computing,time series
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: networkx>=3.0
+Requires-Dist: numpy>=1.21
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Provides-Extra: experiments
+Requires-Dist: matplotlib>=3.5; extra == 'experiments'
+Requires-Dist: pandas>=1.3; extra == 'experiments'
+Requires-Dist: scikit-learn>=1.0; extra == 'experiments'
+Requires-Dist: scipy>=1.7; extra == 'experiments'
+Provides-Extra: flower
+Requires-Dist: flwr>=1.7; extra == 'flower'
+Provides-Extra: reservoirpy
+Requires-Dist: reservoirpy>=0.3; extra == 'reservoirpy'
+Description-Content-Type: text/markdown
+
+# esnfed — a federated reservoir computing toolkit
+
+`esnfed` is a small, dependency-light Python library for training **Echo State
+Networks** (reservoir computing) in a **federated** setting — where several
+parties jointly train a model without sharing their raw data. It accompanies the
+Final Degree Project *Ensemble of Recurrent Networks for Federated Learning*
+(ETSINF, Universitat Politècnica de València).
+
+The core library depends only on **NumPy** and **NetworkX**.
+
+> **Why this and not ReservoirPy?** [ReservoirPy](https://reservoirpy.readthedocs.io)
+> is the mature, full-featured library for *building and tuning* reservoir
+> computing models, and `esnfed` does **not** try to replace it. `esnfed`
+> focuses on the part ReservoirPy does not cover: **federating** reservoir
+> models across parties. You can design a reservoir in ReservoirPy and federate
+> it here in one line (see *Interoperability* below).
+
+## Features
+
+- **Echo State Network** with leaky-integrator neurons and a closed-form ridge
+  readout (`EchoStateNetwork`).
+- **Federated strategies**:
+  - `federated_ridge` — *exact* federated training for a shared reservoir
+    (clients exchange only ridge sufficient statistics; provably equal to pooled
+    training, in one communication round);
+  - `fedavg` — iterative FedAvg on the readout;
+  - `ensemble_predict` — prediction ensemble for *heterogeneous* reservoirs;
+  - `structural_alignment` — interpolate reservoirs toward a shared structure.
+- **Reservoir topologies**: Erdős–Rényi, small-world, scale-free, ring.
+- **Data**: synthetic benchmarks (NARMA-10, Mackey-Glass, Lorenz) **and** real
+  data — a bundled counterparty-risk series (the TED spread) plus generic
+  loaders (`from_array`, `load_csv`, `load_fred`).
+- **Interoperability**: adapters for [ReservoirPy](https://reservoirpy.readthedocs.io)
+  reservoirs and an example integration with the
+  [Flower](https://flower.ai) federated-learning framework.
+
+## Installation
+
+```bash
+pip install esnfed                  # core (numpy + networkx)
+pip install "esnfed[experiments]"   # + matplotlib/pandas/scipy/scikit-learn
+pip install "esnfed[reservoirpy]"   # + ReservoirPy interop
+pip install "esnfed[flower]"        # + Flower integration
+```
+
+## Quick start
+
+### Federated counterparty-risk forecasting (real data)
+
+Several institutions jointly forecast the **TED spread** (a classic gauge of
+interbank/counterparty credit risk) without sharing their data. Exact federated
+ridge equals pooled training in a single round:
+
+```python
+from esnfed import datasets, federated, topologies, metrics
+
+u, y = datasets.load_ted_spread()                 # bundled real series (FRED)
+u_tr, y_tr, u_te, y_te = datasets.split(u, y, 0.7)
+parts = datasets.partition_iid(u_tr, y_tr, n_clients=8)   # 8 "institutions"
+
+W = topologies.random_reservoir(200, density=0.1, rng=0)
+esn_kw = dict(spectral_radius=0.9, leaking_rate=0.5, washout=100, ridge=1e-6)
+clients, ref = federated.make_shared_clients(W, parts, input_seed=0, esn_kwargs=esn_kw)
+
+W_out = federated.federated_ridge(clients, ref)   # one round, exact, private
+Z_test = ref.harvest(u_te)[ref.washout:]
+print("federated NRMSE:", metrics.nrmse(y_te[ref.washout:], Z_test @ W_out))
+```
+
+Need another series? `datasets.load_fred("BAMLH0A0HYM2")` pulls a high-yield
+credit spread from FRED; `datasets.from_array(my_series)` or
+`datasets.load_csv("my.csv")` turn any series into a forecasting task.
+
+### Train a single ESN
+
+```python
+import numpy as np
+from esnfed import EchoStateNetwork, datasets, topologies, metrics
+
+u, y = datasets.narma10(3000, rng=0)
+u_tr, y_tr, u_te, y_te = datasets.split(u, y)
+W = topologies.random_reservoir(200, density=0.1, rng=0)
+esn = EchoStateNetwork(1, 1, W, spectral_radius=0.9, washout=100).fit(u_tr, y_tr)
+print("NRMSE:", metrics.nrmse(y_te[100:], esn.predict(u_te)[100:]))
+```
+
+## Interoperability
+
+### ReservoirPy — design there, federate here
+
+```python
+from reservoirpy.nodes import Reservoir
+from esnfed import interop, datasets, federated
+
+res = Reservoir(200, sr=0.9, lr=0.5, input_dim=1)   # design/tune in ReservoirPy
+esn = interop.to_esn(res, n_inputs=1)               # -> esnfed EchoStateNetwork
+W = interop.reservoir_matrix(res)                   # ... then federate it
+```
+
+### Flower — a real FL framework
+
+`examples/flower_federated_ridge.py` shows the exact federated-ridge scheme as a
+Flower `NumPyClient` + custom `Strategy`: each client's `fit` returns its ridge
+sufficient statistics and the server sums them and solves once. The Flower-routed
+result is identical to `federated_ridge` to numerical precision.
+
+## Modules
+
+| Module | Contents |
+|--------|----------|
+| `esnfed.esn` | `EchoStateNetwork`, ridge helpers |
+| `esnfed.topologies` | reservoir generators + `graph_metrics` |
+| `esnfed.datasets` | NARMA-10, Mackey-Glass, Lorenz; `from_array`, `load_csv`, `load_ted_spread`, `load_fred` |
+| `esnfed.metrics` | `nrmse`, `rmse`, `mse`, `r2_score` |
+| `esnfed.federated` | `Client`, `federated_ridge`, `fedavg`, `ensemble_predict`, `structural_alignment` |
+| `esnfed.interop` | ReservoirPy adapters (`to_esn`, `reservoir_matrix`) |
+
+## Reproducing the research experiments
+
+```bash
+pip install -e ".[experiments,reservoirpy,flower]"
+python -m pytest                    # 37 tests
+python experiments/run_all.py       # synthetic-benchmark figures and tables
+python experiments/exp6_finance.py  # federated counterparty-risk (TED spread)
+```
+
+## Data attribution
+
+The bundled TED spread is sourced from the Federal Reserve Bank of St. Louis
+(FRED, series `TEDRATE`) and is used for demonstration under FRED's terms.
+
+## Citation
+
+```bibtex
+@thesis{benites2026esnfed,
+  author = {Benites Aldaz, Dairon Andres},
+  title  = {Ensemble of Recurrent Networks for Federated Learning},
+  school = {Universitat Politecnica de Valencia (ETSINF)},
+  year   = {2026},
+  type   = {Bachelor's thesis},
+}
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

esnfed-1.0.0/README.md

@@ -0,0 +1,146 @@
+# esnfed — a federated reservoir computing toolkit
+
+`esnfed` is a small, dependency-light Python library for training **Echo State
+Networks** (reservoir computing) in a **federated** setting — where several
+parties jointly train a model without sharing their raw data. It accompanies the
+Final Degree Project *Ensemble of Recurrent Networks for Federated Learning*
+(ETSINF, Universitat Politècnica de València).
+
+The core library depends only on **NumPy** and **NetworkX**.
+
+> **Why this and not ReservoirPy?** [ReservoirPy](https://reservoirpy.readthedocs.io)
+> is the mature, full-featured library for *building and tuning* reservoir
+> computing models, and `esnfed` does **not** try to replace it. `esnfed`
+> focuses on the part ReservoirPy does not cover: **federating** reservoir
+> models across parties. You can design a reservoir in ReservoirPy and federate
+> it here in one line (see *Interoperability* below).
+
+## Features
+
+- **Echo State Network** with leaky-integrator neurons and a closed-form ridge
+  readout (`EchoStateNetwork`).
+- **Federated strategies**:
+  - `federated_ridge` — *exact* federated training for a shared reservoir
+    (clients exchange only ridge sufficient statistics; provably equal to pooled
+    training, in one communication round);
+  - `fedavg` — iterative FedAvg on the readout;
+  - `ensemble_predict` — prediction ensemble for *heterogeneous* reservoirs;
+  - `structural_alignment` — interpolate reservoirs toward a shared structure.
+- **Reservoir topologies**: Erdős–Rényi, small-world, scale-free, ring.
+- **Data**: synthetic benchmarks (NARMA-10, Mackey-Glass, Lorenz) **and** real
+  data — a bundled counterparty-risk series (the TED spread) plus generic
+  loaders (`from_array`, `load_csv`, `load_fred`).
+- **Interoperability**: adapters for [ReservoirPy](https://reservoirpy.readthedocs.io)
+  reservoirs and an example integration with the
+  [Flower](https://flower.ai) federated-learning framework.
+
+## Installation
+
+```bash
+pip install esnfed                  # core (numpy + networkx)
+pip install "esnfed[experiments]"   # + matplotlib/pandas/scipy/scikit-learn
+pip install "esnfed[reservoirpy]"   # + ReservoirPy interop
+pip install "esnfed[flower]"        # + Flower integration
+```
+
+## Quick start
+
+### Federated counterparty-risk forecasting (real data)
+
+Several institutions jointly forecast the **TED spread** (a classic gauge of
+interbank/counterparty credit risk) without sharing their data. Exact federated
+ridge equals pooled training in a single round:
+
+```python
+from esnfed import datasets, federated, topologies, metrics
+
+u, y = datasets.load_ted_spread()                 # bundled real series (FRED)
+u_tr, y_tr, u_te, y_te = datasets.split(u, y, 0.7)
+parts = datasets.partition_iid(u_tr, y_tr, n_clients=8)   # 8 "institutions"
+
+W = topologies.random_reservoir(200, density=0.1, rng=0)
+esn_kw = dict(spectral_radius=0.9, leaking_rate=0.5, washout=100, ridge=1e-6)
+clients, ref = federated.make_shared_clients(W, parts, input_seed=0, esn_kwargs=esn_kw)
+
+W_out = federated.federated_ridge(clients, ref)   # one round, exact, private
+Z_test = ref.harvest(u_te)[ref.washout:]
+print("federated NRMSE:", metrics.nrmse(y_te[ref.washout:], Z_test @ W_out))
+```
+
+Need another series? `datasets.load_fred("BAMLH0A0HYM2")` pulls a high-yield
+credit spread from FRED; `datasets.from_array(my_series)` or
+`datasets.load_csv("my.csv")` turn any series into a forecasting task.
+
+### Train a single ESN
+
+```python
+import numpy as np
+from esnfed import EchoStateNetwork, datasets, topologies, metrics
+
+u, y = datasets.narma10(3000, rng=0)
+u_tr, y_tr, u_te, y_te = datasets.split(u, y)
+W = topologies.random_reservoir(200, density=0.1, rng=0)
+esn = EchoStateNetwork(1, 1, W, spectral_radius=0.9, washout=100).fit(u_tr, y_tr)
+print("NRMSE:", metrics.nrmse(y_te[100:], esn.predict(u_te)[100:]))
+```
+
+## Interoperability
+
+### ReservoirPy — design there, federate here
+
+```python
+from reservoirpy.nodes import Reservoir
+from esnfed import interop, datasets, federated
+
+res = Reservoir(200, sr=0.9, lr=0.5, input_dim=1)   # design/tune in ReservoirPy
+esn = interop.to_esn(res, n_inputs=1)               # -> esnfed EchoStateNetwork
+W = interop.reservoir_matrix(res)                   # ... then federate it
+```
+
+### Flower — a real FL framework
+
+`examples/flower_federated_ridge.py` shows the exact federated-ridge scheme as a
+Flower `NumPyClient` + custom `Strategy`: each client's `fit` returns its ridge
+sufficient statistics and the server sums them and solves once. The Flower-routed
+result is identical to `federated_ridge` to numerical precision.
+
+## Modules
+
+| Module | Contents |
+|--------|----------|
+| `esnfed.esn` | `EchoStateNetwork`, ridge helpers |
+| `esnfed.topologies` | reservoir generators + `graph_metrics` |
+| `esnfed.datasets` | NARMA-10, Mackey-Glass, Lorenz; `from_array`, `load_csv`, `load_ted_spread`, `load_fred` |
+| `esnfed.metrics` | `nrmse`, `rmse`, `mse`, `r2_score` |
+| `esnfed.federated` | `Client`, `federated_ridge`, `fedavg`, `ensemble_predict`, `structural_alignment` |
+| `esnfed.interop` | ReservoirPy adapters (`to_esn`, `reservoir_matrix`) |
+
+## Reproducing the research experiments
+
+```bash
+pip install -e ".[experiments,reservoirpy,flower]"
+python -m pytest                    # 37 tests
+python experiments/run_all.py       # synthetic-benchmark figures and tables
+python experiments/exp6_finance.py  # federated counterparty-risk (TED spread)
+```
+
+## Data attribution
+
+The bundled TED spread is sourced from the Federal Reserve Bank of St. Louis
+(FRED, series `TEDRATE`) and is used for demonstration under FRED's terms.
+
+## Citation
+
+```bibtex
+@thesis{benites2026esnfed,
+  author = {Benites Aldaz, Dairon Andres},
+  title  = {Ensemble of Recurrent Networks for Federated Learning},
+  school = {Universitat Politecnica de Valencia (ETSINF)},
+  year   = {2026},
+  type   = {Bachelor's thesis},
+}
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

esnfed-1.0.0/esnfed/__init__.py

@@ -0,0 +1,31 @@
+"""esnfed - Echo State Networks for Federated Learning.
+
+A small, dependency-light research library accompanying the Final Degree Project
+*Ensemble of Recurrent Networks for Federated Learning* (ETSINF, UPV).
+
+Modules
+-------
+esn          Echo State Network (reservoir + ridge readout).
+topologies   Reservoir topology generators (random, small-world, scale-free, ring).
+datasets     Benchmark sequential tasks (NARMA-10, Mackey-Glass, Lorenz, sine).
+metrics      Error metrics (NRMSE, MSE, memory capacity).
+federated    Federated strategies (FedAvg, exact federated ridge, ensemble, alignment).
+"""
+
+from .esn import EchoStateNetwork
+from .metrics import nrmse, mse, rmse
+from . import topologies, datasets, federated, metrics, interop
+
+__all__ = [
+    "EchoStateNetwork",
+    "nrmse",
+    "mse",
+    "rmse",
+    "topologies",
+    "datasets",
+    "federated",
+    "metrics",
+    "interop",
+]
+
+__version__ = "1.0.0"