# sgvaze/generalized-category-discovery architecture

> Architecture diagram of the GitHub repository sgvaze/generalized-category-discovery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sgvaze/generalized-category-discovery
- Repository: https://github.com/sgvaze/generalized-category-discovery

## Overview

##### Project Type and Purpose
- This is a research‐code repository for “Generalized Category Discovery” (GCD), an ML pipeline that:
- Trains a representation (contrastive learning) on partially labeled data
- Extracts features using the trained model
- Applies (semi‐supervised) k‐means to assign categories to unlabelled examples
- Evaluates performance under two metrics (ACC v1 & v2)

##### Main Architectural Components
A. Data & Configuration
- Datasets (data/*): CIFAR, ImageNet, CUB, Stanford Cars, Herbarium19, SSB splits
- Augmentations module (data/augmentations)
- config.py: paths & experiment settings
- environment.yml & requirements.txt: dependency management
B. Training Module
- Contrastive training code (methods/contrastive_training/contrastive_training.py)
- Model definitions (models/resnet_twohead.py, models/vision_transformer.py)
- Schedulers & utils (project_utils/schedulers.py, general_utils.py)
- Slurm output parser (project_utils/slurm_out_parser.py)
C. Feature Extraction
- extract_features.sh (bash_scripts) orchestrates
- methods/clustering/extract_features.py reads a checkpoint, dumps feature vectors
D. Clustering Module
- methods/clustering/k_means.py & faster_mix_k_means_pytorch.py
- feature_vector_dataset.py for DataLoader abstraction
- Estimate optimal K (methods/estimate_k/estimate_k.py)
E. Evaluation & Logging
- cluster_and_log_utils.py implements ACC v1 & v2 (Hungarian assignment)
- Logs written to SAVE_DIR via bash scripts

##### Interactions & Data Flow
1. Data Ingestion: raw images → augmentations → DataLoaders
2. Contrastive Training: DataLoader + model → optimized weights → checkpoint saved
3. Feature Extraction: checkpoint + DataLoader → feature files (.npy/.pkl)
4. Clustering: features + optional labels → cluster assignments → metrics
5. Evaluation: assignments + ground truth → ACC old/new/all → log outputs

##### Architectural Patterns & Design Principles
- Pipeline/Layered Pattern: clear separation between data, model, training, feature‐extraction, clustering, evaluation
- Modular & Pluggable:
- New augmentations under data/augmentations/
- Swap in a different model under models/
- Extend clustering by dropping in a new method under methods/clustering/
- Script‐driven Orchestration: bash_scripts provide reproducible end‐to‐end runs

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Data & Config Layer
  subgraph "Data & Config"
    direction TB
    DS["Datasets"]:::cylinder
    AUG["Augmentations\n(data/augmentations/)"]:::code
    CO["cut_out.py"]:::code
    RA["randaugment.py"]:::code
    LO["Dataset Loaders"]:::code
    CIF["cifar.py"]:::code
    IMN["imagenet.py"]:::code
    CUB["cub.py"]:::code
    SC["stanford_cars.py"]:::code
    HB["herbarium_19.py"]:::code
    SSB["ssb_splits/"]:::code
    DU["data_utils.py"]:::code
    GD["get_datasets.py"]:::code
    CFG["config.py"]:::doc
    ENV["environment.yml"]:::doc
    REQ["requirements.txt"]:::doc

    AUG --> CO
    AUG --> RA
    LO --> CIF
    LO --> IMN
    LO --> CUB
    LO --> SC
    LO --> HB
    LO --> SSB
    DU --- GD
  end

  %% Training Layer
  subgraph "Training"
    direction TB
    CT["Contrastive Training\n(methods/contrastive_training/)"]:::code
    R2H["resnet_twohead.py"]:::code
    VT["vision_transformer.py"]:::code
    SCH["schedulers.py"]:::code
    GU["general_utils.py"]:::code
    SP["slurm_out_parser.py"]:::code
    TS["contrastive_train.sh"]:::script
  end

  CK["Checkpoint"]:::cylinder

  %% Feature Extraction Layer
  subgraph "Feature Extraction"
    direction TB
    FE_SH["extract_features.sh"]:::script
    FE["extract_features.py"]:::code
  end

  FT["Features"]:::cylinder

  %% Clustering Layer
  subgraph "Clustering"
    direction TB
    KM["k_means.py"]:::code
    FMKM["faster_mix_k_means_pytorch.py"]:::code
    FVD["feature_vector_dataset.py"]:::code
    KMSH["k_means.sh"]:::script
  end

  CA["Cluster Assignments"]:::cylinder

  %% Estimate K Layer
  subgraph "Estimate Optimal K"
    direction TB
    EK["estimate_k.py"]:::code
    EKSH["estimate_k.sh"]:::script
  end

  %% Evaluation & Logging Layer
  subgraph "Evaluation & Logging"
    direction TB
    CLU["cluster_and_log_utils.py"]:::code
    CU["cluster_utils.py"]:::code
    LG["Logs"]:::cylinder
  end

  %% Data Flow
  DS -->|provides raw images| AUG
  AUG -->|augmented data| LO
  LO -->|DataLoader| CT
  CFG --> CT
  TS --> CT
  CT --> CK
  CK --> FE
  FE_SH --> FE
  CFG --> FE
  FE --> KM
  FE --> FMKM
  FVD --> KM
  KM --> CA
  FMKM --> CA
  CA --> CLU
  CU --> LG
  EK --> KM
  EKSH --> EK

  %% Click Events Data & Config
  click DS "https://github.com/sgvaze/generalized-category-discovery/tree/main/data/"
  click AUG "https://github.com/sgvaze/generalized-category-discovery/tree/main/data/augmentations/"
  click CO "https://github.com/sgvaze/generalized-category-discovery/blob/main/data/augmentations/cut_out.py"
  click RA "https://github.com/sgvaze/generalized-category-discovery/blob/main/data/augmentations/randaugment.py"
  click CIF "https://github.com/sgvaze/generalized-category-discovery/blob/main/data/cifar.py"
  click IMN "https://github.com/sgvaze/generalized-category-discovery/blob/main/data/imagenet.py"
  click CUB "https://github.com/sgvaze/generalized-category-discovery/blob/main/data/cub.py"
  click SC "https://github.com/sgvaze/generalized-category-discovery/blob/main/data/stanford_cars.py"
  click HB "https://github.com/sgvaze/generalized-category-discovery/blob/main/data/herbarium_19.py"
  click SSB "https://github.com/sgvaze/generalized-category-discovery/tree/main/data/ssb_splits/"
  click DU "https://github.com/sgvaze/generalized-category-discovery/blob/main/data/data_utils.py"
  click GD "https://github.com/sgvaze/generalized-category-discovery/blob/main/data/get_datasets.py"
  click CFG "https://github.com/sgvaze/generalized-category-discovery/blob/main/config.py"
  click ENV "https://github.com/sgvaze/generalized-category-discovery/blob/main/environment.yml"
  click REQ "https://github.com/sgvaze/generalized-category-discovery/blob/main/requirements.txt"

  %% Click Events Training
  click CT "https://github.com/sgvaze/generalized-category-discovery/blob/main/methods/contrastive_training/contrastive_training.py"
  click R2H "https://github.com/sgvaze/generalized-category-discovery/blob/main/models/resnet_twohead.py"
  click VT "https://github.com/sgvaze/generalized-category-discovery/blob/main/models/vision_transformer.py"
  click SCH "https://github.com/sgvaze/generalized-category-discovery/blob/main/project_utils/schedulers.py"
  click GU "https://github.com/sgvaze/generalized-category-discovery/blob/main/project_utils/general_utils.py"
  click SP "https://github.com/sgvaze/generalized-category-discovery/blob/main/project_utils/slurm_out_parser.py"
  click TS "https://github.com/sgvaze/generalized-category-discovery/blob/main/bash_scripts/contrastive_train.sh"

  %% Click Events Feature Extraction
  click FE_SH "https://github.com/sgvaze/generalized-category-discovery/blob/main/bash_scripts/extract_features.sh"
  click FE "https://github.com/sgvaze/generalized-category-discovery/blob/main/methods/clustering/extract_features.py"

  %% Click Events Clustering
  click KM "https://github.com/sgvaze/generalized-category-discovery/blob/main/methods/clustering/k_means.py"
  click FMKM "https://github.com/sgvaze/generalized-category-discovery/blob/main/methods/clustering/faster_mix_k_means_pytorch.py"
  click FVD "https://github.com/sgvaze/generalized-category-discovery/blob/main/methods/clustering/feature_vector_dataset.py"
  click KMSH "https://github.com/sgvaze/generalized-category-discovery/blob/main/bash_scripts/k_means.sh"

  %% Click Events Estimate K
  click EK "https://github.com/sgvaze/generalized-category-discovery/blob/main/methods/estimate_k/estimate_k.py"
  click EKSH "https://github.com/sgvaze/generalized-category-discovery/blob/main/bash_scripts/estimate_k.sh"

  %% Click Events Evaluation & Logging
  click CLU "https://github.com/sgvaze/generalized-category-discovery/blob/main/project_utils/cluster_and_log_utils.py"
  click CU "https://github.com/sgvaze/generalized-category-discovery/blob/main/project_utils/cluster_utils.py"

  %% Styles
  classDef code fill:#D6EAF8,stroke:#AED6F1
  classDef doc fill:#F9E79F,stroke:#F7DC6F
  classDef script fill:#F5B7B1,stroke:#EC7063
  classDef cylinder fill:#ABEBC6,stroke:#82E0AA
```
