# google-research/simclr architecture

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

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

## Overview

##### Project type and purpose
- This is a machine-learning framework and CLI application for pretraining, fine-tuning, evaluating, and demoing SimCLR (contrastive learning) models in both TensorFlow 1.x and TensorFlow 2.x.
- It provides reusable modules (data pipelines, model definitions, loss functions, optimizers) and Colab notebooks to bootstrap research and demonstrations, as well as integration with Cloud TPUs and Google Cloud Storage for checkpointing.

##### Main components
a. Data Ingestion & Augmentation
- Modules: data.py, data_util.py
- Inputs: local datasets (CIFAR-10, TensorFlow Datasets ImageNet), `imagenet_subsets/` text files
b. Model Construction
- Modules: resnet.py, model.py, model_util.py
- Components: ResNet base network (configurable depth/width/SK), projection head (configurable layers), supervised head for linear eval
c. Loss & Objective
- Module: objective.py
- Contrastive loss (NT-Xent), temperature hyperparameter
d. Optimizer
- Module: lars_optimizer.py
- Choices: Momentum or LARS, learning-rate schedules (linear or sqrt scaling), weight decay
e. Training & Evaluation Orchestration
- Entry point: run.py
- Modes: pretrain, finetune (linear head and full network), train_then_eval
- CLI flags → hyperparameter injection → initialize data, model, loss, optimizer → distribution strategy (TPU / single GPU) → training loop → evaluation loop
f. Logging & Checkpointing
- TensorBoard summaries
- Google Cloud Storage buckets for pretrained/fine-tuned/distilled models (gs://simclr-checkpoints/…)
g. Interactive Notebooks
- Folder: colabs/ (TF1.x) and tf2/colabs/ (TF2.x) – demonstration and tutorial notebooks for distillation, finetuning, inference, intriguing properties demos

##### Relationships & data flows
- The run.py orchestrator invokes the Data pipeline → feeds batched data into the Model → computes Loss → applies Optimizer → emits checkpoints and logs.
- Distribution strategy layer (tf.distribute.TPUStrategy or single-GPU) wraps the training loop.
- Checkpoint module reads/writes to GCS buckets; TensorBoard writes summaries to local or GCS paths.
- Colab notebooks import and call the same modules (data.py, run.py) for interactive demos.

##### Architectural patterns & design principles
- Modular layering: clear separation between data, model, objective, optimizer, and runner.
- CLI-driven configuration: all hyperparameters and modes controlled by flags to run.py.
- Dual support for TF1.x and TF2.x via parallel folder structures (root vs. tf2/).
- Use of tf.data for high-throughput data input and tf.distribute for distributed compute.
- Reusability and extensibility: easy to swap optimizers, change model depth, add new datasets or heads.

##### Technologies, frameworks & external services
- Core: Python, TensorFlow 1.x & 2.x, tf.data, tf.distribute, Keras (in TF2 path)
- Compute: Cloud TPU (via TPUName env + TPU strategy) or single GPU
- Storage: Google Cloud Storage (checkpoints), TensorFlow Datasets (ImageNet)
- Experiment tracking: TensorBoard
- Interactive demos: Jupyter/Colab notebooks

##### Essential elements
- Clear, consistent labels for every module and data store
- Internal modules vs. external services
- TF1.x vs. TF2.x implementation tracks

## Diagram (Mermaid)

```mermaid
graph TB
    %% Data Layer
    subgraph "Data Ingestion & Augmentation" 
        direction TB
        subgraph "TF1.x" 
            direction TB
            D1["data.py"]:::data
            D2["data_util.py"]:::data
            S1["imagenet_subsets/10percent.txt"]:::data
            S2["imagenet_subsets/1percent.txt"]:::data
        end
        subgraph "TF2.x" 
            direction TB
            D3["tf2/data.py"]:::data
            D4["tf2/data_util.py"]:::data
        end
        TFDS["TensorFlow Datasets (ImageNet)"]:::external
        LocalDS["Local Datasets (CIFAR-10)"]:::external
    end

    %% Model Layer
    subgraph "Model Construction"
        direction TB
        subgraph "TF1.x"
            direction TB
            M1["resnet.py"]:::compute
            M2["model.py"]:::compute
            M3["model_util.py"]:::compute
        end
        subgraph "TF2.x"
            direction TB
            M4["tf2/resnet.py"]:::compute
            M5["tf2/model.py"]:::compute
        end
    end

    %% Loss & Optimizer Layer
    subgraph "Loss & Objective / Optimizer"
        direction TB
        subgraph "TF1.x"
            direction TB
            L1["objective.py"]:::compute
            O1["lars_optimizer.py"]:::compute
        end
        subgraph "TF2.x"
            direction TB
            L2["tf2/objective.py"]:::compute
            O2["tf2/lars_optimizer.py"]:::compute
        end
    end

    %% Orchestration & Distribution
    subgraph "Training & Evaluation Orchestration"
        direction TB
        subgraph "TF1.x"
            direction TB
            R1["run.py"]:::orchestrator
        end
        subgraph "TF2.x"
            direction TB
            R2["tf2/run.py"]:::orchestrator
        end
        Dist["Distribution Strategy (TPU/GPU)"]:::external
    end

    %% Storage & Logging
    subgraph "Storage & Logging"
        direction TB
        GCS["GCS Buckets (gs://simclr-checkpoints/)"]:::external
        TBLOG["TensorBoard Summaries"]:::external
    end

    %% Notebooks
    subgraph "Interactive Notebooks"
        direction TB
        subgraph "TF1.x colabs"
            direction TB
            N1["colabs/distillation_self_training.ipynb"]:::notebook
            N2["colabs/finetuning.ipynb"]:::notebook
            N3["colabs/load_and_inference.ipynb"]:::notebook
            N4["colabs/intriguing_properties/*.ipynb"]:::notebook
        end
        subgraph "TF2.x colabs"
            direction TB
            N5["tf2/colabs/distillation_self_training.ipynb"]:::notebook
            N6["tf2/colabs/finetuning.ipynb"]:::notebook
            N7["tf2/colabs/imagenet_results.ipynb"]:::notebook
            N8["tf2/colabs/load_and_inference.ipynb"]:::notebook
        end
    end

    %% Data Flow
    LocalDS -->|TFRecords| D1
    TFDS -->|tensors| D3
    D1 -->|batched tensors| M1
    D3 -->|batched tensors| M4
    M1 -->|features| L1
    M4 -->|features| L2
    L1 -->|loss| O1
    L2 -->|loss| O2
    O1 -->|updates| M1
    O2 -->|updates| M4
    R1 -->|orchestrates| D1
    R1 -->|orchestrates| M1
    R1 -->|orchestrates| L1
    R1 -->|orchestrates| O1
    R1 -->|wraps with| Dist
    R2 -->|orchestrates| D3
    R2 -->|orchestrates| M4
    R2 -->|orchestrates| L2
    R2 -->|orchestrates| O2
    R2 -->|wraps with| Dist
    O1 -->|checkpoints| GCS
    O2 -->|checkpoints| GCS
    O1 -->|logs| TBLOG
    O2 -->|logs| TBLOG
    N1 -->|imports| R1
    N5 -->|imports| R2

    %% Click events
    click D1 "https://github.com/google-research/simclr/blob/master/data.py"
    click D2 "https://github.com/google-research/simclr/blob/master/data_util.py"
    click S1 "https://github.com/google-research/simclr/blob/master/imagenet_subsets/10percent.txt"
    click S2 "https://github.com/google-research/simclr/blob/master/imagenet_subsets/1percent.txt"
    click D3 "https://github.com/google-research/simclr/blob/master/tf2/data.py"
    click D4 "https://github.com/google-research/simclr/blob/master/tf2/data_util.py"
    click M1 "https://github.com/google-research/simclr/blob/master/resnet.py"
    click M2 "https://github.com/google-research/simclr/blob/master/model.py"
    click M3 "https://github.com/google-research/simclr/blob/master/model_util.py"
    click M4 "https://github.com/google-research/simclr/blob/master/tf2/resnet.py"
    click M5 "https://github.com/google-research/simclr/blob/master/tf2/model.py"
    click L1 "https://github.com/google-research/simclr/blob/master/objective.py"
    click L2 "https://github.com/google-research/simclr/blob/master/tf2/objective.py"
    click O1 "https://github.com/google-research/simclr/blob/master/lars_optimizer.py"
    click O2 "https://github.com/google-research/simclr/blob/master/tf2/lars_optimizer.py"
    click R1 "https://github.com/google-research/simclr/blob/master/run.py"
    click R2 "https://github.com/google-research/simclr/blob/master/tf2/run.py"
    click N1 "https://github.com/google-research/simclr/blob/master/colabs/distillation_self_training.ipynb"
    click N2 "https://github.com/google-research/simclr/blob/master/colabs/finetuning.ipynb"
    click N3 "https://github.com/google-research/simclr/blob/master/colabs/load_and_inference.ipynb"
    click N4 "https://github.com/google-research/simclr/tree/master/colabs/intriguing_properties"
    click N5 "https://github.com/google-research/simclr/blob/master/tf2/colabs/distillation_self_training.ipynb"
    click N6 "https://github.com/google-research/simclr/blob/master/tf2/colabs/finetuning.ipynb"
    click N7 "https://github.com/google-research/simclr/blob/master/tf2/colabs/imagenet_results.ipynb"
    click N8 "https://github.com/google-research/simclr/blob/master/tf2/colabs/load_and_inference.ipynb"

    %% Styles
    classDef data fill:#ccffcc,stroke:#006600
    classDef compute fill:#cce5ff,stroke:#004080
    classDef orchestrator fill:#e5ccff,stroke:#800080
    classDef external fill:#f2f2f2,stroke:#999999,stroke-dasharray: 2 2
    classDef notebook fill:#fff2cc,stroke:#997300
```
