# vmarsocci/pangaea-bench architecture

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

- Interactive diagram: https://gitdiagram.com/vmarsocci/pangaea-bench
- Repository: https://github.com/vmarsocci/pangaea-bench

## Overview

##### Main Components
- Data Sources & Datasets: Represented by the collection of dataset configurations in the “configs/dataset” directory and the corresponding dataset loader implementations in “pangaea/datasets/”. These parts manage the ingestion and preprocessing of various geospatial datasets.
- Preprocessing Pipeline: The “configs/preprocessing” files and the code in parts of the codebase (perhaps invoked via the pangaea/engine/data_preprocessor.py) specify normalization, resizing, cropping, and other augmentations.
- Model Components – Encoders and Decoders:
- Encoders are defined in “pangaea/encoders/” and configured via “configs/encoder”. They are responsible for extracting features from the input images using various architectures (e.g., RemoteCLIP, SSL4EO variants, ViTs).
- Decoders are located in “pangaea/decoders/” and configured via “configs/decoder”. They map extracted features to outputs for segmentation, change detection, or regression tasks.
- Training & Evaluation Engine:
- The “pangaea/engine” directory implements the training, evaluation, and finetuning logic (Trainer, Evaluator, etc.). It coordinates the flow from data ingestion to model training.
- Experiment Configuration & Orchestration:
- Hydra configuration management is central throughout the repository (all config files in “configs/”). This management supports dynamic overrides at runtime.
- Utility Modules:
- Common utilities for logging, loss calculations, scheduling, and sampling are housed in “pangaea/utils/”. They are essential for training stability and reporting.

##### Relationships & Interactions
- Data Flow: The process starts by reading dataset configurations, loading raw geospatial data through the dataset loaders, and applying preprocessing.
- Feature Extraction & Modeling: Preprocessed data is then fed into the encoder modules, whose outputs are passed to the decoder modules. Multiple strategies (e.g., for multi-temporal processing or change detection via concatenation or differencing) lead to different configuration choices.
- Training Loop: The engine (in “pangaea/engine”) manages the training loop, integrating the model components, optimizers (from “configs/optimizer” and “pangaea/utils/optimizers.py”), learning rate schedulers (from “configs/lr_scheduler”), and criterion modules (defined in “pangaea/utils/losses.py”).
- Evaluation: After or during training, the evaluator component assesses model performance, with checkpoints and configurations stored for later inference.
- Hydra: This crucial framework allows command-line overrides, dynamically merging various configuration files (dataset, encoder, decoder, task, etc.) and orchestrating experiment runs.

##### Architectural Patterns
- Modular/Plug-and-Play Design: The clearly separated directories for datasets, encoders, decoders, and utilities facilitate swapping or extending components without affecting others.
- Configuration-Driven Approach: All parameters, from model architecture to dataset details, are isolated in YAML configuration files, ensuring high customizability via Hydra.
- Layered System: Data processing (input layer) → Model processing (feature extraction, intermediate representations) → Training/Evaluation logic (control and orchestration) → External integrations (Hydra, logging, external models/datasets).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        D1("Dataset Configurations"):::dataset
        D2("Dataset Loader Implementations"):::dataset
    end

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        P1("Preprocessing Configurations"):::preprocess
        P2("Data Preprocessing Code"):::preprocess
    end

    %% Model Core
    subgraph "Model Core"
        E1("Encoder Configurations"):::encoder
        E2("Encoder Implementations"):::encoder
        D3("Decoder Configurations"):::decoder
        D4("Decoder Implementations"):::decoder
    end

    %% Training Engine
    subgraph "Training Engine"
        T("Training & Evaluation Engine"):::engine
    end

    %% Experiment Orchestration and Utilities
    H("Hydra & YAML Configurations"):::hydra
    U("Common Utilities & Helpers"):::utils

    %% Data Flow Connections
    D1 --> D2
    D2 --> P1
    P1 --> P2
    P2 --> E1
    E1 --> E2
    E2 --> D3
    D3 --> D4
    D4 --> T
    T --> H
    T --> U

    %% Configuration overrides from Hydra
    H -.-> D1
    H -.-> P1
    H -.-> E1
    H -.-> D3
    H -.-> T

    %% Click Events
    click D1 "https://github.com/vmarsocci/pangaea-bench/tree/main/configs/dataset"
    click D2 "https://github.com/vmarsocci/pangaea-bench/tree/main/pangaea/datasets"
    click P1 "https://github.com/vmarsocci/pangaea-bench/tree/main/configs/preprocessing"
    click P2 "https://github.com/vmarsocci/pangaea-bench/blob/main/pangaea/engine/data_preprocessor.py"
    click E1 "https://github.com/vmarsocci/pangaea-bench/tree/main/configs/encoder"
    click E2 "https://github.com/vmarsocci/pangaea-bench/tree/main/pangaea/encoders"
    click D3 "https://github.com/vmarsocci/pangaea-bench/tree/main/configs/decoder"
    click D4 "https://github.com/vmarsocci/pangaea-bench/tree/main/pangaea/decoders"
    click T "https://github.com/vmarsocci/pangaea-bench/tree/main/pangaea/engine"
    click H "https://github.com/vmarsocci/pangaea-bench/tree/main/configs"
    click U "https://github.com/vmarsocci/pangaea-bench/tree/main/pangaea/utils"

    %% Styles
    classDef dataset fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef preprocess fill:#FFE4B5,stroke:#000,stroke-width:1px;
    classDef encoder fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef decoder fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef engine fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef hydra fill:#FFA07A,stroke:#000,stroke-width:1px,stroke-dasharray:5,5;
    classDef utils fill:#E6E6FA,stroke:#000,stroke-width:1px;
```
