How cyber-physical-systems-in-mech-eng/pyreco works
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).