# ivanpanshin/supcon-framework architecture

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

- Interactive diagram: https://gitdiagram.com/ivanpanshin/supcon-framework
- Repository: https://github.com/ivanpanshin/supcon-framework

## Overview

##### Main Components

- Config Manager:
- The “configs” directory holds all the YAML configuration files that dictate hyperparameters, training stages, and other experimental setups.

- Data Pipeline:
- Look into “tools/datasets.py” which defines dataset classes and augmentation logic (using albumentations).
- This module is responsible for loading, augmenting, and preprocessing the image data.

- Model & Loss Modules:
- The “tools” directory contains submodules such as “backbones.py”, “models.py”, and “losses.py” which define the neural network architectures (like ResNet18), projection heads, and various losses (including LabelSmoothing and contrastive losses).
- As a “Model Construction” block and “Loss Functions” block.

- Training Engines:
- The primary training scripts are “train.py” and “swa.py” (Stochastic Weight Averaging) with “learning_rate_finder.py” serving for hyperparameter optimization.

- Optimization & Utilities:
- Tools for optimizers, schedulers, and additional helper functions are available under “tools/optimizers.py”, “tools/schedulers.py”, and “tools/utils.py”.
- This forms the “Optimization & Utility” layer that configures backpropagation, learning rate scheduling, EMA, and mixed precision (AMP) handling.

- Logging & Visualization:
- The README and included notebook “t-SNE.ipynb” indicate that tensorboard logging and t-SNE visualizations are key parts of tracking training progress and evaluating the model’s embeddings.

##### Relationships and Interactions

- Data Flow:
- The “Training Controller” orchestrates data loading (via the “Data Pipeline”), builds the neural network (invoking “Model & Loss Modules”), and applies optimization steps (using “Optimization & Utility”).
- Once training is underway, the process includes periodic validations and logging through “Logging & Visualization”.

- Dependencies:
- The configuration files drive different training modes (first stage, second stage, LR finder, or SWA training).
- The “Training Controller” calls upon different components based on the configuration, such as using EMA or Automatic Mixed Precision (AMP).

##### Architectural Patterns & Technologies

- Modular Design:
- The code is separated into well-defined modules (configs, tools, training scripts) to follow modular programming principles.

- Two-Stage Training:

- External Libraries and Frameworks:
- Key libraries include PyTorch for deep learning, albumentations for augmentations, timm for model architectures, pytorch-metric-learning for evaluation metrics, and tensorboard for logging.
- As external dependencies interacting with the core modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Configuration Module"]:::module
    B["Training Controller"]:::module
    C["Data Pipeline (Dataset Loader & Augmentation)"]:::module
    D["Model Construction (Neural Network Architectures)"]:::module
    E["Loss Functions"]:::module
    F["Optimization & Utilities"]:::module
    G["Logging & Visualization (TensorBoard,t-SNE,Checkpoints)"]:::module
    X["External Libraries (PyTorch,albumentations,timm,metric-learning,tensorboard)"]:::external

    A -->|"config_input"| B
    B -->|"loads_data"| C
    B -->|"builds_model"| D
    B -->|"computes_loss"| E
    B -->|"applies_optimization"| F
    B -->|"logs_training"| G
    G -->|"feedback_loop"| B

    X ---|"supports"| C
    X ---|"supports"| D
    X ---|"supports"| E
    X ---|"supports"| F
    X ---|"supports"| G

    click A "https://github.com/ivanpanshin/supcon-framework/tree/main/configs/"
    click C "https://github.com/ivanpanshin/supcon-framework/blob/main/tools/datasets.py"
    click D "https://github.com/ivanpanshin/supcon-framework/blob/main/tools/backbones.py"
    click D "https://github.com/ivanpanshin/supcon-framework/blob/main/tools/models.py"
    click E "https://github.com/ivanpanshin/supcon-framework/blob/main/tools/losses.py"
    click B "https://github.com/ivanpanshin/supcon-framework/blob/main/train.py"
    click B "https://github.com/ivanpanshin/supcon-framework/blob/main/swa.py"
    click B "https://github.com/ivanpanshin/supcon-framework/blob/main/learning_rate_finder.py"
    click F "https://github.com/ivanpanshin/supcon-framework/blob/main/tools/optimizers.py"
    click F "https://github.com/ivanpanshin/supcon-framework/blob/main/tools/schedulers.py"
    click F "https://github.com/ivanpanshin/supcon-framework/blob/main/tools/utils.py"
    click G "https://github.com/ivanpanshin/supcon-framework/blob/main/t-SNE.ipynb"
    click G "https://github.com/ivanpanshin/supcon-framework/blob/main/README.md"

    classDef module fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B7950B,stroke-width:2px,stroke-dasharray: 5 5;
```
