# maple-research-lab/caco architecture

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

- Interactive diagram: https://gitdiagram.com/maple-research-lab/caco
- Repository: https://github.com/maple-research-lab/caco

## Overview

##### Project Type and Purpose
- CaCo is a Python‑based self‑supervised contrastive‑learning framework built on PyTorch.
- Its goal is to train an encoder (e.g., ResNet‑50) by learning both positives and negatives cooperatively and adversarially via a memory module.

##### File‑Structure Analysis
- data_processing/: image loaders & augmentation (MultiCrop_Transform.py, imagenet loader)
- model/: network definitions (ResNet, CaCo memory bank) and optimizer wrappers
- ops/: environment config, argument parsing, LARS optimizer, k‑NN monitoring, OS utilities
- training/: distributed training orchestration (main_worker), memory initialization, training loops
- main.py / linear.py: high‐level entry points for pre‑training and linear evaluation

##### Key Insights from README
- Uses torch.distributed for multi‑GPU, multi‑node training
- Supports single‑crop and multi‑crop regimes
- Exposes knobs (learning rates, batch size, memory updates, cluster size) via CLI args

a. Data Storage
- ImageNet dataset on shared filesystem (NFS/HDFS/S3)
b. Data Processing Pipeline
- Loader → augmentation transforms (random crops, MultiCrop) → batch collator
c. Model & Memory Module
- Encoder backbone (ResNet)
- CaCo memory bank: learnable positive/negative samples
d. Loss & Optimizer
- Contrastive loss calculation (InfoNCE style)
- Optimizers: SGD + optional LARS (ops/LARS.py)
e. Training Orchestrator
- main.py invokes torch.distributed.launch → training/main_worker.py
- training/train_caco.py: forward, loss, backward, memory updates
f. Utilities & Monitoring
- knn_monitor for periodic evaluation
- tensorboardX logging, checkpointing
g. Compute Infrastructure
- GPU workers (8×V100 per node), multi‑node cluster
- torch.distributed backend (NCCL/TCP)

##### Relationships & Data Flow
- Data flows from Storage → data_processing.Loader → augment → Model
- Model outputs query/key embeddings → loss module consults Memory Bank → loss computed
- Gradient flow → Optimizer updates Model parameters and Memory Bank parameters
- Orchestrator coordinates DistributedDataParallel across GPUs/nodes
- knn_monitor reads current embeddings for online evaluation
- Logging & Checkpoint modules write to disk/remote storage

##### Architectural Patterns & Design Principles
- Modular separation: data, model, training, ops
- Pipeline pattern: sequential transforms → model → loss → optimizer → update
- Distributed Data Parallelism for scalability
- Config‐driven via ops/argparser.py and Config_Environment.py

##### Essential Elements Checklist
- Notes on parameters tuned via CLI (batch_size, lr, cluster_size, multi_crop flag)
- Where logs and checkpoints are written (disk path or remote storage)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Storage["Image Store\n(NFS/HDFS/S3)"]:::infra
        Loader["Data Loader"]:::data
        Augment["Augmentation\n(random crop / MultiCrop)"]:::data
        BatchCollator["Batch Collator"]:::data
    end

    %% Model & Memory
    subgraph "Model & Memory" 
        direction TB
        Encoder["ResNet Encoder"]:::model
        MemoryBank["CaCo Memory Bank"]:::model
        Loss["Contrastive Loss\n(InfoNCE)"]:::model
    end

    %% Optimizer
    subgraph "Optimizer"
        direction TB
        Optimizer["SGD + optional LARS"]:::model
    end

    %% Training Orchestration
    subgraph "Training Orchestrator"
        direction TB
        ArgParser["CLI Arg Parser"]:::orchestrator
        ConfigEnv["Config Environment"]:::orchestrator
        Main["main.py"]:::orchestrator
        MainWorker["main_worker.py"]:::orchestrator
        TrainLoop["train_caco.py"]:::orchestrator
        InitMem["init_memory.py"]:::orchestrator
    end

    %% Utilities & Monitoring
    subgraph "Utilities & Monitoring"
        direction TB
        KNN["k-NN Monitor"]:::infra
        Logging["tensorboardX / Checkpoint"]:::infra
        OSOps["OS & IO Ops"]:::infra
    end

    %% Infrastructure
    subgraph "Compute Infrastructure"
        direction TB
        GPUs["GPU Cluster\n(8×V100)"]:::infra
        DDP["torch.distributed\n(NCCL/TCP)"]:::infra
    end

    %% Data Flow
    Storage -->|"images"| Loader
    Loader -->|"raw batch"| Augment
    Augment -->|"augmented batch"| BatchCollator
    BatchCollator -->|"batch images"| Encoder

    Encoder -->|"query/key embeddings"| Loss
    MemoryBank -->|"positives/negatives"| Loss
    Loss -->|"gradients"| Optimizer
    Optimizer -->|"updated weights"| Encoder
    Optimizer -->|"memory update"| MemoryBank

    %% Orchestration
    ArgParser --> Main
    ConfigEnv --> Main
    Main --> MainWorker
    MainWorker --> InitMem
    InitMem --> TrainLoop
    MainWorker --> TrainLoop
    TrainLoop --> Encoder
    TrainLoop --> Loss
    TrainLoop --> Optimizer

    %% Distributed
    MainWorker --> GPUs
    GPUs --> DDP
    DDP -->|sync gradients| TrainLoop

    %% Monitoring & Logging
    Encoder -->|"embeddings stream"| KNN
    KNN -->|"evaluation metrics"| Logging
    TrainLoop -->|"checkpoint write"| Logging
    OSOps --> Logging

    %% Click Events
    click Loader "https://github.com/maple-research-lab/caco/blob/main/data_processing/loader.py"
    click Augment "https://github.com/maple-research-lab/caco/blob/main/data_processing/MultiCrop_Transform.py"
    click Augment "https://github.com/maple-research-lab/caco/blob/main/data_processing/imagenet.py"
    click Encoder "https://github.com/maple-research-lab/caco/blob/main/model/ResNet.py"
    click MemoryBank "https://github.com/maple-research-lab/caco/blob/main/model/CaCo.py"
    click Optimizer "https://github.com/maple-research-lab/caco/blob/main/model/optimizer.py"
    click Optimizer "https://github.com/maple-research-lab/caco/blob/main/ops/LARS.py"
    click ArgParser "https://github.com/maple-research-lab/caco/blob/main/ops/argparser.py"
    click ConfigEnv "https://github.com/maple-research-lab/caco/blob/main/ops/Config_Environment.py"
    click Main "https://github.com/maple-research-lab/caco/blob/main/main.py"
    click MainWorker "https://github.com/maple-research-lab/caco/blob/main/training/main_worker.py"
    click TrainLoop "https://github.com/maple-research-lab/caco/blob/main/training/train_caco.py"
    click InitMem "https://github.com/maple-research-lab/caco/blob/main/training/init_memory.py"
    click OSOps "https://github.com/maple-research-lab/caco/blob/main/ops/os_operation.py"
    click KNN "https://github.com/maple-research-lab/caco/blob/main/ops/knn_monitor.py"
    click Logging "https://github.com/maple-research-lab/caco/blob/main/training/train_utils.py"
    click Logging "https://github.com/maple-research-lab/caco/blob/main/ops/os_operation.py"
    click LinearEval "https://github.com/maple-research-lab/caco/blob/main/linear.py"

    %% Styles
    classDef data fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef model fill:#90EE90,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#FFA500,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
```
