# cyber-physical-systems-in-mech-eng/pyreco architecture

> Architecture diagram of the GitHub repository cyber-physical-systems-in-mech-eng/pyreco, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cyber-physical-systems-in-mech-eng/pyreco
- Repository: https://github.com/cyber-physical-systems-in-mech-eng/pyreco

## Overview

##### Project Type and Purpose
- pyReCo is an open-source Python library (no UI or networked services) focused on reservoir computing (RC) for time-series forecasting and research.
- It provides two user-facing APIs:
- Model API (scikit-learn–style `.fit()` / `.predict()`)
- CustomModel API (TensorFlow‐style `.add()` layers + `.compile()`)
- Core capabilities: random reservoir layers, readout training (Ridge regression), cross-validation, network analysis, and more.

##### High-Level Architectural Components
1. User Interfaces (APIs)
- Model API
- CustomModel API
2. Core Reservoir Engine
- Layers
- Initializers
- Optimizers
- Pruning
- Transient Removal
3. Data & Utilities
- Dataset loaders (`utils_data`, `datasets`)
- Metrics (`metrics`)
- Plotting & Visualization (`plotting`)
- Graph & Network analysis (`graph_analyzer`, `network_prop_extractor`, `node_analyzer`, `node_selector`)
4. Cross-Validation & Evaluation
- `cross_validation.py`
5. Extensibility & Configuration
- Custom models
- Configuration (setup.py, pyproject.toml, setup.cfg)
6. Supporting Artifacts (outside runtime)
- Examples
- Documentation
- Tests

##### Modules and Their Relationships
- The User (or script) → imports `pyreco.models.ReservoirComputer` or `pyreco.custom_models.RC`.
- Upon `.fit(X, y)`:
- Data flows through InputLayer → ReservoirLayer(s) → ReadoutLayer.
- Internally, `initializer` builds reservoir weight matrices; `optimizers` (e.g., ridge regression) learn readout.
- Optional network analysis steps: `graph_analyzer`, `node_selector`, `pruning`, `remove_transients`.
- Upon `.predict(X)`:
- New input is propagated through the same layer stack to produce output.
- The `cross_validation` module orchestrates repeated training/prediction cycles and aggregates metrics via the `metrics` module.
- Utility modules (`utils_data`, `utils_networks`) provide helper functions for data formatting and network creation.
- Plotting is separate: user calls `plotting` after obtaining results.

##### Architectural Patterns and Design Principles
- Layered architecture: clear separation between data I/O, model definition, model training, evaluation, and utilities.
- Plugin-style extensibility: users can add custom layers or override default behavior.
- Single-responsibility modules (one Python file per major service).
- Conformity to existing APIs (scikit-learn, TensorFlow Sequential) to reduce learning curve.

##### Technologies & Dependencies
- Core language: Python
- Numerical & ML backends: NumPy, SciPy
- Linear algebra & optimization: Scikit-learn (Ridge), TensorFlow (optional for CustomModel)
- Documentation: Sphinx + ReadTheDocs
- Testing: pytest, coverage, tox
- CI/CD: GitHub Actions (`.github/workflows`)

##### Essential Elements
- Footnotes or small callouts for special modules (e.g., `graph_analyzer` for structure-function research).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User
    User["User / External Script"]:::external

    %% API Layer
    subgraph "API Layer"
        ModelAPI["Model API"]:::core
        CustomModelAPI["CustomModel API"]:::core
    end

    %% Core Reservoir Engine
    subgraph "Core Reservoir Engine"
        Layers["Layers"]:::core
        Initializer["Initializer"]:::core
        Optimizers["Optimizers"]:::core
        Pruning["Pruning"]:::core
        TransientRemoval["Transient Removal"]:::core
    end

    %% Data & Utilities
    subgraph "Data & Utilities"
        Datasets["Dataset Loaders"]:::util
        UtilsData["Data Helpers"]:::util
        UtilsNetworks["Network Helpers"]:::util
        Metrics["Metrics"]:::util
        Plotting["Plotting & Visualization"]:::util
        GraphAnalyzer["Graph Analysis"]:::util
        NetworkProp["Network Property Extraction"]:::util
        NodeAnalyzer["Node Analysis"]:::util
        NodeSelector["Node Selection"]:::util
    end

    %% Cross-Validation & Evaluation
    CV["Cross-Validation & Evaluation"]:::util

    %% Supporting Artifacts
    subgraph "Supporting Artifacts"
        Examples["Examples"]:::ext
        Docs["Documentation"]:::ext
        Tests["Tests"]:::ext
    end

    %% Connections
    User -->|"calls .fit()/.predict()"| ModelAPI
    User -->|"calls .add()/.compile()"| CustomModelAPI

    ModelAPI -->|"X, y arrays"| Layers
    CustomModelAPI -->|"X, y arrays"| Layers

    Layers --> Initializer
    Layers --> Optimizers
    Layers --> Pruning
    Layers --> TransientRemoval

    ModelAPI -->|"uses data helpers"| UtilsData
    ModelAPI -->|"uses metrics"| Metrics
    CustomModelAPI -->|"uses data helpers"| UtilsData
    CustomModelAPI -->|"uses metrics"| Metrics

    CV -->|"triggers .fit()/.predict() cycles"| ModelAPI
    CV -->|"collects metrics"| Metrics
    ModelAPI <-->|"feedback"| CV

    User -->|"visualize results"| Plotting

    %% Supporting artifacts connections
    User -.-> Examples
    User -.-> Docs
    User -.-> Tests

    %% Click Events
    click ModelAPI "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/models.py"
    click CustomModelAPI "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/custom_models.py"
    click Layers "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/layers.py"
    click Initializer "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/initializer.py"
    click Optimizers "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/optimizers.py"
    click Pruning "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/pruning.py"
    click TransientRemoval "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/remove_transients.py"
    click Datasets "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/datasets.py"
    click UtilsData "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/utils_data.py"
    click UtilsNetworks "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/utils_networks.py"
    click Metrics "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/metrics.py"
    click Plotting "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/plotting.py"
    click GraphAnalyzer "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/graph_analyzer.py"
    click NetworkProp "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/network_prop_extractor.py"
    click NodeAnalyzer "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/node_analyzer.py"
    click NodeSelector "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/node_selector.py"
    click CV "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/blob/main/src/pyreco/cross_validation.py"
    click Examples "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/tree/main/examples/"
    click Docs "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/tree/main/docs/"
    click Tests "https://github.com/cyber-physical-systems-in-mech-eng/pyreco/tree/main/tests/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef util fill:#E6FFE6,stroke:#28a745,color:#155724;
    classDef ext fill:#F0F0F0,stroke:#6c757d,color:#343a40;
    classDef external fill:#FFF0D6,stroke:#d39e00,color:#856404;
```
