# ithronne/rr-former architecture

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

- Interactive diagram: https://gitdiagram.com/ithronne/rr-former
- Repository: https://github.com/ithronne/rr-former

## Overview

##### Project type and purpose
- This is an open-source ML tool for rainfall–runoff modeling, centered on a Transformer architecture (“RR-Former”).
- Key workflows: pretraining a global model, testing it (globally or per–basin), then fine-tuning and testing.

##### File structure
- Top-level scripts:
– pretrain.py / pretrain_test_global.py / pretrain_test_single.py
– fine_tune.py / fine_tune_test.py
- Core modules:
– configs/ (all experiment, dataset, model, run–time settings)
– data/ (raw list files, dataset loader)
– models/ (Transformer and LSTM implementations)
– utils/ (training loops, evaluation, metrics, loss, learning‐rate strategies)

##### README insights
- Workflow stages:
– Pretrain on CAMELS data → evaluate globally or per basin
– Fine‐tune from pretrained weights → evaluate
- Configuration is entirely code‐based under configs/.
- Data must be downloaded separately and pointed to via configs.

##### Main components and interactions
a. Data Ingestion & Preprocessing
– data/*.txt files (raw basin lists) + data/dataset.py
– Controlled by configs/data_shape_config.py & configs/dataset_config.py
b. Configuration Manager
– project_config.py sets global paths
– model_config/ (LSTM vs. Transformer hyperparameters)
– run_config/ (pretrain vs. fine_tune settings)
c. Model Definitions
– models/transformer/transformer.py (RR-Former)
– models/lstm/* (alternative architectures)
d. Training Pipeline
– pretrain.py / fine_tune.py invoke utils/train_epoch.py and utils/train_full.py
– Read data → build model with selected config → loop epochs → save checkpoints
e. Evaluation Pipeline
– pretrain_test_*.py / fine_tune_test.py use utils/eval_model.py, utils/metrics.py, utils/test_full.py
f. Auxiliary Utilities
– utils/lr_strategies.py, utils/nseloss.py for specialized losses and schedulers
– utils/tools.py for I/O and logging

##### Architectural patterns and principles
- Separation of concerns:
– Configs decoupled from code, enabling reproducibility
– Modular model implementations vs. generic training/eval loops
- Pipeline pattern: distinct stages (ingest → preprocess → train → evaluate)
- Extensibility: plug in new model architectures by dropping them into models/

– “Model Zoo” cluster containing Transformer and LSTM modules
– “Training Pipeline” process block
– “Evaluation Pipeline” process block
– Configs → Data Ingestion
– Configs → Model Zoo
– Data Ingestion → Training Pipeline
– Model Zoo → Training Pipeline
– Training Pipeline → Checkpoints & Logs
– Checkpoints & Logs + Data Ingestion → Evaluation Pipeline
– Evaluation Pipeline → Logs / Metrics outputs
c. Highlighted patterns:
– Pipeline stages in sequence (left to right or top to bottom)
– Components grouped by directory (configs, data, models, utils)
d. Technologies & frameworks:
– Python modules (no external services)
– Core dependencies implied: PyTorch/TensorFlow (specify if known)
– Data files on local FS; model artifacts on disk

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Configuration Manager
  subgraph "Configuration Manager"
    pc["project_config.py"]:::config
    dsc["data_shape_config.py"]:::config
    dcc["dataset_config.py"]:::config
    tconf["Transformer_config.py"]:::config
    l1conf["LSTMS2S_config.py"]:::config
    l2conf["LSTMMSVS2S_config.py"]:::config
    rtpre["pretrain_config.py"]:::config
    rftune["fine_tune_config.py"]:::config
  end

  %% Data Ingestion & Preprocessing
  subgraph "Data Ingestion & Preprocessing"
    txt1["448basins_list.txt"]:::data
    txt2["671basins_list.txt"]:::data
    txt3["673basins_list.txt"]:::data
    ds["dataset.py"]:::data
  end

  %% Model Zoo
  subgraph "Model Zoo"
    trf["transformer.py"]:::model
    lms["lstm_s2s.py"]:::model
    lmm["lstm_msv_s2s.py"]:::model
  end

  %% Training Pipeline
  subgraph "Training Pipeline"
    pt["pretrain.py"]:::process
    ft["fine_tune.py"]:::process
    te["train_epoch.py"]:::process
    tf["train_full.py"]:::process
  end

  %% Evaluation Pipeline
  subgraph "Evaluation Pipeline"
    ptg["pretrain_test_global.py"]:::process
    pts["pretrain_test_single.py"]:::process
    ftt["fine_tune_test.py"]:::process
    em["eval_model.py"]:::process
    tfull["test_full.py"]:::process
    met["metrics.py"]:::process
  end

  %% Auxiliary Utilities
  subgraph "Auxiliary Utilities"
    lr["lr_strategies.py"]:::process
    nl["nseloss.py"]:::process
    tl["tools.py"]:::process
  end

  %% Storage
  ck["Checkpoints & Logs"]:::storage

  %% Connections
  pc -->|uses| txt1
  pc -->|uses| txt2
  pc -->|uses| txt3
  pc -->|configures| ds
  pc -->|configures| trf
  pc -->|configures| lms
  pc -->|configures| lmm

  ds -->|feeds| pt
  trf -->|feeds| pt
  lms -->|feeds| pt
  lmm -->|feeds| pt

  pt -->|invokes| te
  pt -->|invokes| tf
  ft -->|invokes| te
  ft -->|invokes| tf

  tf -->|saves| ck
  te -->|uses| tl
  tf -->|uses| lr
  tf -->|uses| nl

  ck -->|provides| ptg
  ds -->|feeds| ptg
  ck -->|provides| pts
  ds -->|feeds| pts
  ck -->|provides| ftt
  ds -->|feeds| ftt

  ptg -->|calls| em
  pts -->|calls| em
  ftt -->|calls| em
  em -->|uses| met
  tfull -->|aggregates| met

  %% Click Events - Configuration Manager
  click pc "https://github.com/ithronne/rr-former/blob/main/configs/project_config.py"
  click dsc "https://github.com/ithronne/rr-former/blob/main/configs/data_shape_config.py"
  click dcc "https://github.com/ithronne/rr-former/blob/main/configs/dataset_config.py"
  click tconf "https://github.com/ithronne/rr-former/blob/main/configs/model_config/Transformer_config.py"
  click l1conf "https://github.com/ithronne/rr-former/blob/main/configs/model_config/LSTMS2S_config.py"
  click l2conf "https://github.com/ithronne/rr-former/blob/main/configs/model_config/LSTMMSVS2S_config.py"
  click rtpre "https://github.com/ithronne/rr-former/blob/main/configs/run_config/pretrain_config.py"
  click rftune "https://github.com/ithronne/rr-former/blob/main/configs/run_config/fine_tune_config.py"

  %% Click Events - Data Ingestion & Preprocessing
  click txt1 "https://github.com/ithronne/rr-former/blob/main/data/448basins_list.txt"
  click txt2 "https://github.com/ithronne/rr-former/blob/main/data/671basins_list.txt"
  click txt3 "https://github.com/ithronne/rr-former/blob/main/data/673basins_list.txt"
  click ds "https://github.com/ithronne/rr-former/blob/main/data/dataset.py"

  %% Click Events - Model Zoo
  click trf "https://github.com/ithronne/rr-former/blob/main/models/transformer/transformer.py"
  click lms "https://github.com/ithronne/rr-former/blob/main/models/lstm/lstm_s2s.py"
  click lmm "https://github.com/ithronne/rr-former/blob/main/models/lstm/lstm_msv_s2s.py"

  %% Click Events - Training Pipeline
  click pt "https://github.com/ithronne/rr-former/blob/main/pretrain.py"
  click ft "https://github.com/ithronne/rr-former/blob/main/fine_tune.py"
  click te "https://github.com/ithronne/rr-former/blob/main/utils/train_epoch.py"
  click tf "https://github.com/ithronne/rr-former/blob/main/utils/train_full.py"

  %% Click Events - Evaluation Pipeline
  click ptg "https://github.com/ithronne/rr-former/blob/main/pretrain_test_global.py"
  click pts "https://github.com/ithronne/rr-former/blob/main/pretrain_test_single.py"
  click ftt "https://github.com/ithronne/rr-former/blob/main/fine_tune_test.py"
  click em "https://github.com/ithronne/rr-former/blob/main/utils/eval_model.py"
  click tfull "https://github.com/ithronne/rr-former/blob/main/utils/test_full.py"
  click met "https://github.com/ithronne/rr-former/blob/main/utils/metrics.py"

  %% Click Events - Auxiliary Utilities
  click lr "https://github.com/ithronne/rr-former/blob/main/utils/lr_strategies.py"
  click nl "https://github.com/ithronne/rr-former/blob/main/utils/nseloss.py"
  click tl "https://github.com/ithronne/rr-former/blob/main/utils/tools.py"

  %% Styles
  classDef config fill:#bbdefb,stroke:#444,stroke-width:1px
  classDef data fill:#c8e6c9,stroke:#444,stroke-width:1px
  classDef model fill:#ffe0b2,stroke:#444,stroke-width:1px
  classDef process fill:#e1bee7,stroke:#444,stroke-width:1px
  classDef storage fill:#eeeeee,stroke:#444,stroke-width:1px
```
