# sthalles/simclr architecture

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

- Interactive diagram: https://gitdiagram.com/sthalles/simclr
- Repository: https://github.com/sthalles/simclr

## Overview

##### Project type and purpose
- This is a command-line, monolithic Python framework implementing the SimCLR self-supervised learning algorithm in PyTorch.
- It provides (a) data augmentation components, (b) a contrastive learning training pipeline, (c) model definitions (ResNet-based encoder + projection head), and (d) a downstream linear evaluation protocol.

##### File structure
- Top-level scripts:
- run.py – Entrypoint: parses CLI args, sets up config, launches training or evaluation
- simclr.py – Core training logic for SimCLR (encoder forward passes, loss computation, backprop)
- data_aug/ – Data pipeline modules generating augmented views:
- contrastive_learning_dataset.py – wrapper around torch.utils.data.Dataset that returns two augmented views per sample
- gaussian_blur.py, view_generator.py – individual augmentation transforms
- models/ – Model definitions:
- resnet_simclr.py – Builds a ResNet backbone + projection head
- feature_eval/ – Notebook for linear evaluation of learned representations
- exceptions/ – Custom error classes
- utils.py – Helper routines (e.g., logging, checkpoint I/O)
- env.yml, requirements.txt – Environment and dependencies

##### README for additional insights
- Confirms PyTorch & AMP for mixed-precision GPU training
- CLI flags for dataset location, dataset name, logging frequency, epochs, disabling CUDA
- Downstream linear evaluation on STL10/CIFAR10

a. Main components:
1. Data Source (raw image dataset on disk, e.g., STL10, CIFAR10)
2. Data Augmentation Pipeline (data_aug package)
3. Data Loader (PyTorch DataLoader)
4. SimCLR Training Engine (simclr.py + run.py orchestrator)
5. Model (ResNet encoder + projection head from models/)
6. Loss Computation (NT-Xent loss in simclr.py)
7. Optimizer & AMP (PyTorch optimizer, optional fp16 AMP)
8. Logging & Checkpointing (utils.py)
9. Feature Evaluation (feature_eval notebook)
10. CLI & Configuration (argparse in run.py, env.yml)

b. Relationships & interactions:
- Data Source → Data Augmentation Pipeline → DataLoader batches two views
- Batches → Training Engine → Model forward pass → Loss Computation → Backprop → Optimizer step
- Training Engine → Logging & Checkpointing → Filesystem
- After training, saved encoder weights → Feature Evaluation Notebook → Linear classifier training & evaluation

c. Architectural patterns & design principles:
- Modular separation: data augmentation is isolated from model and training logic
- Single-process, pipeline pattern: sequential data → model → loss → optimize
- Plug-in points: CLI flags for dataset, device, optimizer, precision
- Extensibility: one can add new augmentations, swap backbones, or evaluation protocols

d. Key technologies:
- Python 3.x, PyTorch (torch, torchvision)
- Conda for environment (env.yml)
- AMP for mixed precision (built-in)
- Jupyter Notebook for evaluation

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI & Configuration"
        CLI["run.py"]:::config
        Env["Environment (env.yml)"]:::config
        Req["requirements.txt"]:::config
        Readme["README.md"]:::config
        License["LICENSE.txt"]:::config
    end

    subgraph "Data Pipeline"
        DS["Raw Dataset (CIFAR10/STL10)"]:::storage
        DA["Data Augmentation Pipeline"]:::data
        CLD["ContrastiveLearningDataset"]:::data
        GB["Gaussian Blur Transform"]:::data
        VG["View Generator Transform"]:::data
        DL["PyTorch DataLoader"]:::data
    end

    subgraph "Training Engine"
        Engine["SimCLR Training Engine"]:::training
        Model["ResNet Encoder + Projection Head"]:::model
        Loss["NT-Xent Loss Computation"]:::training
        Opt["Optimizer & AMP"]:::training
        Utils["Logging & Checkpointing (utils.py)"]:::storage
        Exc["Custom Exceptions"]:::config
    end

    subgraph "Evaluation"
        Eval["Linear Evaluation Notebook"]:::evaluation
    end

    CLI -->|"CLI flags & config"| Engine
    Env --> Engine
    Req --> Engine
    Readme --> Engine

    DS -->|"images"| DA
    DA --> CLD
    GB --> DA
    VG --> DA
    CLD -->|"two views per sample"| DL
    DL -->|"image batch (2 views)"| Engine

    Engine --> Model
    Model -->|"representations"| Engine
    Engine --> Loss
    Loss -->|"loss value"| Engine
    Engine -->|"gradients"| Opt
    Opt --> Model
    Engine --> Utils
    Engine --> Exc

    Utils -->|"checkpoint files"| StorageFS["Filesystem"]:::storage
    StorageFS --> Eval
    ModelWeights["Saved Encoder Weights"]:::storage
    StorageFS --> ModelWeights
    ModelWeights --> Eval

    classDef data fill:#ADD8E6,stroke:#000;
    classDef training fill:#90EE90,stroke:#000;
    classDef model fill:#98FB98,stroke:#000;
    classDef storage fill:#FFA500,stroke:#000;
    classDef evaluation fill:#DDA0DD,stroke:#000;
    classDef config fill:#87CEFA,stroke:#000;

    click CLI "https://github.com/sthalles/simclr/blob/master/run.py"
    click Env "https://github.com/sthalles/simclr/blob/master/env.yml"
    click Req "https://github.com/sthalles/simclr/blob/master/requirements.txt"
    click Readme "https://github.com/sthalles/simclr/blob/master/README.md"
    click License "https://github.com/sthalles/simclr/blob/master/LICENSE.txt"
    click DA "https://github.com/sthalles/simclr/tree/master/data_aug/"
    click CLD "https://github.com/sthalles/simclr/blob/master/data_aug/contrastive_learning_dataset.py"
    click GB "https://github.com/sthalles/simclr/blob/master/data_aug/gaussian_blur.py"
    click VG "https://github.com/sthalles/simclr/blob/master/data_aug/view_generator.py"
    click Model "https://github.com/sthalles/simclr/blob/master/models/resnet_simclr.py"
    click Engine "https://github.com/sthalles/simclr/blob/master/simclr.py"
    click Utils "https://github.com/sthalles/simclr/blob/master/utils.py"
    click Exc "https://github.com/sthalles/simclr/blob/master/exceptions/exceptions.py"
    click Eval "https://github.com/sthalles/simclr/blob/master/feature_eval/mini_batch_logistic_regression_evaluator.ipynb"
```
