# lucapedrelli/deepesn architecture

> Architecture diagram of the GitHub repository lucapedrelli/deepesn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucapedrelli/deepesn
- Repository: https://github.com/lucapedrelli/deepesn

## Overview

DeepESN is a Python library for deep reservoir recurrent networks and sequence/time-series tasks. Users construct a model from recurrent layers and a readout, then drive it with a series; task evaluators split data, fit the readout, generate predictions, and report task-specific scores. The graph preserves the documented legacy API, intrinsic-plasticity capability, both task types, dataset utilities, and all readout methods. Some implementation details are unsampled, so edges are limited to documented or indexed relationships.

Main entry points: [`src/deepesn/readouts/base.py`](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/readouts/base.py) (Readout base and registry), [`src/deepesn/deepesn.py`](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/deepesn.py) (DeepESN model), [`src/deepesn/tasks/memory_capacity.py`](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/tasks/memory_capacity.py) (Memory capacity), [`src/deepesn/tasks/next_step.py`](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/tasks/next_step.py) (Next-step prediction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Model orchestration"]
  node_model["DeepESN model<br/>[deepesn.py]"]
  node_legacy_config["Legacy configurations<br/>[configurations.py]"]
end

subgraph group_layers["Reservoir layers"]
  node_layer_base["Layer base and RNG<br/>[base.py]"]
  node_esn["ESN layer<br/>[esn.py]"]
  node_liesn["Leaky ESN layer<br/>[liesn.py]"]
end

subgraph group_readouts["Readout training"]
  node_readout_base["Readout base and registry<br/>[base.py]"]
  node_svd["SVD readout<br/>[svd.py]"]
  node_ne["Normal equations<br/>[ne.py]"]
  node_ridge["Ridge readout<br/>[ridge.py]"]
  node_ine["Incremental equations<br/>[ine.py]"]
  node_rls["Recursive least squares<br/>[rls.py]"]
end

subgraph group_tasks["Tasks and data"]
  node_task_base["Task evaluation protocol<br/>[base.py]"]
  node_memory["Memory capacity<br/>[memory_capacity.py]"]
  node_next_step["Next-step prediction<br/>[next_step.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
  node_datasets["Legacy dataset loaders<br/>[datasets.py]"]
  node_legacy_task["Legacy task utilities<br/>[task.py]"]
end

node_user(("Library user"))
node_result["Predictions and scores"]

node_user -->|"constructs"| node_model
node_legacy_config -->|"configures legacy API"| node_model
node_model -->|"initializes layers"| node_layer_base
node_esn -->|"extends"| node_layer_base
node_liesn -->|"extends"| node_esn
node_model -->|"uses readout"| node_readout_base
node_svd -->|"implements"| node_readout_base
node_ne -->|"implements"| node_readout_base
node_ridge -->|"implements"| node_readout_base
node_ine -->|"implements"| node_readout_base
node_rls -->|"implements"| node_readout_base
node_user -->|"evaluates task"| node_memory
node_user -->|"evaluates task"| node_next_step
node_memory -->|"extends"| node_task_base
node_next_step -->|"extends"| node_task_base
node_task_base -->|"uses metrics"| node_metrics
node_memory -->|"computes states"| node_model
node_memory -->|"fits and predicts"| node_readout_base
node_next_step -->|"computes states"| node_model
node_next_step -->|"fits and predicts"| node_readout_base
node_memory -->|"returns capacity scores"| node_result
node_next_step -->|"returns predictions and scores"| node_result
node_legacy_task -->|"imports utilities"| node_datasets
node_user -.->|"loads legacy data"| node_datasets

click node_model "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/deepesn.py"
click node_legacy_config "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/configurations.py"
click node_layer_base "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/layers/base.py"
click node_esn "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/layers/esn.py"
click node_liesn "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/layers/liesn.py"
click node_readout_base "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/readouts/base.py"
click node_svd "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/readouts/svd.py"
click node_ne "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/readouts/ne.py"
click node_ridge "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/readouts/ridge.py"
click node_ine "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/readouts/ine.py"
click node_rls "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/readouts/rls.py"
click node_task_base "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/tasks/base.py"
click node_memory "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/tasks/memory_capacity.py"
click node_next_step "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/tasks/next_step.py"
click node_metrics "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/metrics.py"
click node_datasets "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/datasets.py"
click node_legacy_task "https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/task.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_model,node_legacy_config,node_user toneBlue
class node_layer_base,node_esn,node_liesn toneAmber
class node_readout_base,node_svd,node_ne,node_ridge,node_ine,node_rls toneMint
class node_task_base,node_memory,node_next_step,node_metrics,node_datasets,node_legacy_task toneRose
class node_result toneIndigo
```

## Components

### Model orchestration

- [DeepESN model](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/deepesn.py): `src/deepesn/deepesn.py`
- [Legacy configurations](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/configurations.py): `src/deepesn/configurations.py`

### Reservoir layers

- [Layer base and RNG](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/layers/base.py): `src/deepesn/layers/base.py`
- [ESN layer](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/layers/esn.py): `src/deepesn/layers/esn.py`
- [Leaky ESN layer](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/layers/liesn.py): `src/deepesn/layers/liesn.py`

### Readout training

- [Readout base and registry](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/readouts/base.py): `src/deepesn/readouts/base.py`
- [SVD readout](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/readouts/svd.py): `src/deepesn/readouts/svd.py`
- [Normal equations](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/readouts/ne.py): `src/deepesn/readouts/ne.py`
- [Ridge readout](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/readouts/ridge.py): `src/deepesn/readouts/ridge.py`
- [Incremental equations](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/readouts/ine.py): `src/deepesn/readouts/ine.py`
- [Recursive least squares](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/readouts/rls.py): `src/deepesn/readouts/rls.py`

### Tasks and data

- [Task evaluation protocol](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/tasks/base.py): `src/deepesn/tasks/base.py`
- [Memory capacity](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/tasks/memory_capacity.py): `src/deepesn/tasks/memory_capacity.py`
- [Next-step prediction](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/tasks/next_step.py): `src/deepesn/tasks/next_step.py`
- [Evaluation metrics](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/metrics.py): `src/deepesn/metrics.py`
- [Legacy dataset loaders](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/datasets.py): `src/deepesn/datasets.py`
- [Legacy task utilities](https://github.com/lucapedrelli/deepesn/blob/master/src/deepesn/task.py): `src/deepesn/task.py`

### Other components

- **Library user**
- **Predictions and scores**

## Connections

- Library user → DeepESN model: constructs (evidence: `README.md`)
- Legacy configurations → DeepESN model: configures legacy API (evidence: `README.md`)
- DeepESN model → Layer base and RNG: initializes layers (evidence: `src/deepesn/deepesn.py`)
- ESN layer → Layer base and RNG: extends (evidence: `src/deepesn/layers/esn.py`)
- Leaky ESN layer → ESN layer: extends (evidence: `src/deepesn/layers/liesn.py`)
- DeepESN model → Readout base and registry: uses readout (evidence: `src/deepesn/deepesn.py`)
- SVD readout → Readout base and registry: implements (evidence: `src/deepesn/readouts/svd.py`)
- Normal equations → Readout base and registry: implements (evidence: `src/deepesn/readouts/ne.py`)
- Ridge readout → Readout base and registry: implements (evidence: `src/deepesn/readouts/ridge.py`)
- Incremental equations → Readout base and registry: implements (evidence: `src/deepesn/readouts/ine.py`)
- Recursive least squares → Readout base and registry: implements (evidence: `src/deepesn/readouts/rls.py`)
- Library user → Memory capacity: evaluates task (evidence: `README.md`)
- Library user → Next-step prediction: evaluates task (evidence: `README.md`)
- Memory capacity → Task evaluation protocol: extends (evidence: `src/deepesn/tasks/memory_capacity.py`)
- Next-step prediction → Task evaluation protocol: extends (evidence: `src/deepesn/tasks/next_step.py`)
- Task evaluation protocol → Evaluation metrics: uses metrics (evidence: `src/deepesn/tasks/base.py`)
- Memory capacity → DeepESN model: computes states (evidence: `src/deepesn/tasks/memory_capacity.py`)
- Memory capacity → Readout base and registry: fits and predicts (evidence: `src/deepesn/tasks/memory_capacity.py`)
- Next-step prediction → DeepESN model: computes states (evidence: `src/deepesn/tasks/next_step.py`)
- Next-step prediction → Readout base and registry: fits and predicts (evidence: `src/deepesn/tasks/next_step.py`)
- Memory capacity → Predictions and scores: returns capacity scores (evidence: `src/deepesn/tasks/memory_capacity.py`)
- Next-step prediction → Predictions and scores: returns predictions and scores (evidence: `src/deepesn/tasks/next_step.py`)
- Legacy task utilities → Legacy dataset loaders: imports utilities (evidence: `src/deepesn/task.py`)
- Library user → Legacy dataset loaders: loads legacy data