# javierfa98/ma-lstm-mlp architecture

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

- Interactive diagram: https://gitdiagram.com/javierfa98/ma-lstm-mlp
- Repository: https://github.com/javierfa98/ma-lstm-mlp

## Overview

##### Project Type and Purpose
- The project is focused on simulating nonlinear dynamical systems, especially for industrial applications such as robotics and control systems.
- Its key function is to predict the state of a dynamic system using historical data, control inputs, and an iterative, attention-based learning model.
- The system is built using Python with dependencies on TensorFlow/Keras, which run the neural network model, and utilities for data preprocessing, metrics, and plotting.

##### File Structure Analysis
- Main Script: “ma_lstm_mlp.py” orchestrates training and testing.
- Datasets: The “datasets” folder contains subdirectories (e.g., “robot”, “wiener_hammerstein”) with CSV series, pre-trained models (.h5 files), loss values, and scalers.
- Libraries (“libs/”): Contains modules such as “config.py” (for hyperparameters and configurations), “data.py” (for data preprocessing), “network.py” (for model training/testing), “metrics.py” (for performance evaluation), and “plot.py” (for visualizations).
- Supporting Files: “requirements.txt” for dependencies, “LICENSE”, and the “README.md” providing documentation and usage instructions.
- Image assets under “img/” provide visual guides specific to the MA-LSTM-MLP architecture and prediction plots.

a. Data Ingestion and Preprocessing:
- Component: “Datasets” (CSV files from robots and Wiener-Hammerstein systems) stored in the “datasets/<dataset>/series” directories.
- Subcomponent: Data preprocessing functions (libs/data.py) that read CSV files and transform them into suitable input formats (splitting control inputs and state variables).

b. Configuration and Hyperparameter Management:
- Component: “Config Module” (libs/config.py) where hyperparameters (number of inputs/outputs, sequence lengths, learning parameters) are set.

c. Model Training & Testing:
- Component: “MA-LSTM-MLP Model” (encapsulated in libs/network.py).
- Submodules:
- LSTM with Attention: Processes past state estimates and control inputs.
- MLP layers: Incorporated for further state prediction.
- The main script (ma_lstm_mlp.py) coordinates training (with optional teacher forcing or not) and testing.

d. Evaluation and Visualization:
- Component: “Metrics & Plotting” (libs/metrics.py and libs/plot.py)
- Loss evolution, RMSE, NRMSE, R² metrics along with plots comparing predicted vs. actual outputs.

e. Data Storage & Artifacts:
- Component: "Trained Models and Loss Logs"
- Location: saved under “datasets/<dataset>/networks” and “datasets/<dataset>/losses”
- Bidirectional feedback between training processes and saved model artifacts.

f. External Dependencies & Environmental Setup:
- An external widget representing key libraries/technologies:
- Python 3.6.8 runtime,
- TensorFlow, Keras, Pandas, NumPy, Matplotlib and scikit-learn.
- Optionally, show the use of a GPU (e.g., NVIDIA GeForce GTX Titan XP) for accelerated training.

##### Relationships and Interactions
- From raw data (CSV files) into the preprocessing functions.
- Configuration settings (from config.py) feed into the model.
- The model (MA-LSTM-MLP) receives preprocessed data, performs training/updating, and outputs network predictions.

##### Architectural Patterns & Design Principles
- Modular design: separation of concerns across data ingestion, configuration, modeling, evaluation, and visualization.
- Pipeline architecture for end-to-end data flow.
- The use of configuration files and modular sub-systems (data, model, metrics, plotting) ensures extensibility and reusability.
- Emphasis on separation of training and testing workflows is clearly captured in the main script and dataset directory structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    M["External Dependencies (Python, TensorFlow, etc)"]:::external
    N["Dependency Management (requirements.txt)"]:::external
    M --> N
    M --> D

    subgraph "Raw Data"
        A(("Robot CSV Data")):::database
        B(("Wiener CSV Data")):::database
    end

    C["Data Preprocessing (libs/data.py)"]:::module
    D["Configuration (libs/config.py)"]:::module
    E["Orchestration Script (ma_lstm_mlp.py)"]:::module
    F["MA-LSTM-MLP Model (libs/network.py)"]:::module
    G["Metrics (libs/metrics.py)"]:::module
    H["Plotting (libs/plot.py)"]:::module

    subgraph "Data Artifacts"
        I(("Trained Models (Robot)")):::database
        J(("Trained Models (Wiener-Hammerstein)")):::database
        K(("Loss Logs (Robot)")):::database
        L(("Loss Logs (Wiener-Hammerstein)")):::database
    end

    %% Data Flow
    A --> C
    B --> C
    C --> D
    D --> E
    E --> F
    D --> F
    F --> G
    G --> H

    %% Bidirectional feedback with stored artifacts
    F <--> I
    F <--> J
    F <--> K
    F <--> L

    %% Click Events
    click A "https://github.com/javierfa98/ma-lstm-mlp/tree/main/datasets/robot/series/"
    click B "https://github.com/javierfa98/ma-lstm-mlp/tree/main/datasets/wiener_hammerstein/series/"
    click C "https://github.com/javierfa98/ma-lstm-mlp/blob/main/libs/data.py"
    click D "https://github.com/javierfa98/ma-lstm-mlp/blob/main/libs/config.py"
    click E "https://github.com/javierfa98/ma-lstm-mlp/blob/main/ma_lstm_mlp.py"
    click F "https://github.com/javierfa98/ma-lstm-mlp/blob/main/libs/network.py"
    click G "https://github.com/javierfa98/ma-lstm-mlp/blob/main/libs/metrics.py"
    click H "https://github.com/javierfa98/ma-lstm-mlp/blob/main/libs/plot.py"
    click I "https://github.com/javierfa98/ma-lstm-mlp/tree/main/datasets/robot/networks/"
    click J "https://github.com/javierfa98/ma-lstm-mlp/tree/main/datasets/wiener_hammerstein/networks/"
    click K "https://github.com/javierfa98/ma-lstm-mlp/tree/main/datasets/robot/losses/"
    click L "https://github.com/javierfa98/ma-lstm-mlp/tree/main/datasets/wiener_hammerstein/losses/"
    click N "https://github.com/javierfa98/ma-lstm-mlp/blob/main/requirements.txt"

    %% Styles
    classDef external fill:#ffccff,stroke:#990099,stroke-width:2px;
    classDef module fill:#cce5ff,stroke:#0066cc,stroke-width:2px;
    classDef database fill:#ccffcc,stroke:#009900,stroke-width:2px;
```
