# netneurolab/conn2res architecture

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

- Interactive diagram: https://gitdiagram.com/netneurolab/conn2res
- Repository: https://github.com/netneurolab/conn2res

## Overview

##### Project Type & Purpose
- This project is a scientific/neuroscience toolbox designed to implement reservoir computing using connectome-informed architectures. It supports various cognitive tasks by setting up reservoirs with custom connectivity, input/readout selection, and different node dynamics.
- The toolbox is applied to supervised tasks (leveraging tools like NeuroGym) and can also simulate physical connectome-informed memristive reservoirs—a key aspect of its uniqueness.

##### Analyzing the File Structure
- The top-level directories and files (e.g., conn2res, docs, examples) show you have a modular library with:
- Core functional modules: connectivity.py, performance.py, plotting.py, readout.py, reservoir.py, tasks.py.
- Utility functions in utils.py.
- A set of tests under conn2res/tests to validate the implementation.
- Example scripts and a comprehensive documentation structure (docs/).
- Configuration and build files (setup.py, pyproject.toml, setup.cfg) indicate a standard Python package structure meant to be installed, while versioneer.py hints at automated version management.

##### Key Insights from README
- The README explains the workflow: providing task types or datasets, specifying connectivity matrices (binary/weighted), selecting input and readout nodes, and defining reservoir dynamics.
- The classical architecture of reservoir computing is depicted (input, reservoir, readout), while also discussing adaptability to both artificial and biologically inspired networks.

a. Main Components:
- Data/Task Input Module:
- Handles input either as NeuroGym tasks or supervised datasets.
- Connectivity Module:
- Manages loading/defining the connectome (binary/weighted matrices) that sets the reservoir’s architecture.
- Reservoir Module:
- Implements the dynamical system (with local dynamics – continuous or discrete including spiking or artificial neurons).
- Readout Module:
- Extracts reservoir states and trains a supervised linear model (or equivalent) to produce outputs.
- Performance and Plotting Modules:
- Utility Components:
- Provide supporting functions and helpers across the workflow.
- Testing and Examples:
- That each component works as intended and offer guides on using the toolbox.

b. Components Relationships & Data Flow:
- Input data flow moving from the Task Input component to the Reservoir.
- The connectivity module configures the reservoir’s architecture.
- Output from the reservoir is sent to the Readout module.
- Performance evaluation feeds back into parameter selection adjustments.
- Plotting and documentation components use outputs from these core processes for visualization.
- Feedback loops if parameter-tuning or iterative experimentation is employed.

c. Architectural Patterns & Design Principles:
- Pipeline flow inherent in reservoir computing:
- Data ingestion → Connectivity setup → Reservoir processing → Readout training → Evaluation/Visualization.
- Modularity: each Python module (e.g., connectivity.py, reservoir.py) is self-contained, enabling easier extension and testing.
- Decoupling between components (for example, input handling is kept separate from the reservoir dynamics).

d. Relevant Technologies & Adjustments:
- That the toolbox uses Python 3.8+ with key dependencies now including PyTorch (replacing the original NumPy dependency) to support numerical computations within the reservoir simulations.
- Other libraries: scipy, pandas, scikit-learn, matplotlib, seaborn, bctpy, reservoirpy, gym, and NeuroGym.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Core Pipeline"
        DT["Data/Task Input Module"]:::task
        CN["Connectivity Module"]:::connect
        RS["Reservoir Module (PyTorch-based)"]:::reservoir
        RO["Readout Module"]:::readout
        PE["Performance Module"]:::performance
        PL["Plotting Module"]:::plot
    end

    subgraph "Support Components"
        UT["Utility Components"]:::utility
        TS["Testing Components"]:::testing
        EX["Examples and User Workflows"]:::examples
        DC["Documentation"]:::docs
    end

    DT -->|"provides_data"| CN
    CN -->|"configures"| RS
    DT -->|"feeds_data"| RS
    RS -->|"state_output"| RO
    RS -->|"performance_metrics"| PE
    RS -->|"visual_data"| PL
    RO -->|"trained_output"| PE
    PE -->|"feedback_tuning"| CN

    UT ---|"supports"| DT
    UT ---|"supports"| CN
    UT ---|"supports"| RS
    UT ---|"supports"| RO
    UT ---|"supports"| PE
    UT ---|"supports"| PL

    TS ---|"verifies"| DT
    TS ---|"verifies"| CN
    TS ---|"verifies"| RS
    TS ---|"verifies"| RO

    EX ---|"demonstrates_usage"| DT
    EX ---|"demonstrates_usage"| RS
    EX ---|"demonstrates_usage"| RO

    DC ---|"guides"| DT
    DC ---|"guides"| CN
    DC ---|"guides"| RS
    DC ---|"guides"| RO
    DC ---|"guides"| PE
    DC ---|"guides"| PL

    click DT "https://github.com/netneurolab/conn2res/blob/master/conn2res/tasks.py"
    click CN "https://github.com/netneurolab/conn2res/blob/master/conn2res/connectivity.py"
    click RS "https://github.com/netneurolab/conn2res/blob/master/conn2res/reservoir.py"
    click RO "https://github.com/netneurolab/conn2res/blob/master/conn2res/readout.py"
    click PE "https://github.com/netneurolab/conn2res/blob/master/conn2res/performance.py"
    click PL "https://github.com/netneurolab/conn2res/blob/master/conn2res/plotting.py"
    click UT "https://github.com/netneurolab/conn2res/blob/master/conn2res/utils.py"
    click TS "https://github.com/netneurolab/conn2res/tree/master/conn2res/tests"
    click EX "https://github.com/netneurolab/conn2res/tree/master/examples"
    click DC "https://github.com/netneurolab/conn2res/tree/master/docs"

    classDef task fill:#a2d5f2,stroke:#000,stroke-width:2px;
    classDef connect fill:#bada55,stroke:#000,stroke-width:2px;
    classDef reservoir fill:#ff9999,stroke:#000,stroke-width:2px;
    classDef readout fill:#f6c7a7,stroke:#000,stroke-width:2px;
    classDef performance fill:#d3a4ff,stroke:#000,stroke-width:2px;
    classDef plot fill:#ffb3ba,stroke:#000,stroke-width:2px;
    classDef utility fill:#cccccc,stroke:#000,stroke-width:2px;
    classDef testing fill:#ffff99,stroke:#000,stroke-width:2px;
    classDef examples fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef docs fill:#9fe2bf,stroke:#000,stroke-width:2px;
```
