# bgu-cs-vil/cludi architecture

> Architecture diagram of the GitHub repository bgu-cs-vil/cludi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bgu-cs-vil/cludi
- Repository: https://github.com/bgu-cs-vil/cludi

## Overview

CLUDI is a research implementation for clustering image embeddings with self-supervised diffusion. The documented workflow obtains pretrained-model embeddings with the external TEMI pipeline, then runs `cludi.py` to train student/teacher models and produce cluster assignments evaluated with clustering metrics. Internally, `diff_utils.py` owns diffusion noising and sampling calls. The sampled excerpts establish the main training and sampling links; other utility connections are limited to references in the source index, so the graph does not infer deeper data flow for them.

Main entry points: [`cludi.py`](https://github.com/bgu-cs-vil/cludi/blob/main/cludi.py) (Training entry point), [`train_utils.py`](https://github.com/bgu-cs-vil/cludi/blob/main/train_utils.py) (Training utilities), [`denoising_diffusion_pytorch/denoising_diffusion_pytorch.py`](https://github.com/bgu-cs-vil/cludi/blob/main/denoising_diffusion_pytorch/denoising_diffusion_pytorch.py) (Gaussian diffusion), [`denoising_diffusion_pytorch/attend.py`](https://github.com/bgu-cs-vil/cludi/blob/main/denoising_diffusion_pytorch/attend.py) (Attention kernels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Clustering workflow"]
  node_embedding_input["Image embeddings"]
  node_cludi["Training entry point<br/>[cludi.py]"]
  node_cluster_results["Cluster evaluation<br/>[eval_utils.py]"]
end

subgraph group_runtime["Model and diffusion runtime"]
  node_student_teacher["Student teacher models<br/>[vit_new.py]"]
  node_diffusion["Gaussian diffusion"]
  node_diffusion_ops["Diffusion sampling ops<br/>[diff_utils.py]"]
  node_attention["Attention kernels<br/>[attend.py]"]
  node_unet2d["2D Karras U-Net<br/>[karras_unet.py]"]
  node_unet1d["1D Karras U-Net<br/>[karras_unet_1d.py]"]
  node_unet3d["3D Karras U-Net<br/>[karras_unet_3d.py]"]
  node_diffusion_variants["Diffusion variants"]
end

subgraph group_support["Training support"]
  node_augmentations["Image augmentations<br/>[dino_utils.py]"]
  node_training_utils["Training utilities<br/>[train_utils.py]"]
  node_losses["Clustering losses<br/>[loss_utils.py]"]
  node_logging["Logging utilities<br/>[log_utils.py]"]
end

node_embedding_input -->|"provides features"| node_cludi
node_cludi -->|"trains models"| node_student_teacher
node_cludi -->|"runs sampling"| node_diffusion_ops
node_diffusion_ops -->|"noises and samples"| node_diffusion
node_training_utils -->|"imports model"| node_student_teacher
node_training_utils -->|"imports diffusion"| node_diffusion
node_cludi -->|"imports evaluation"| node_cluster_results
node_cludi -->|"imports utilities"| node_training_utils
node_cludi -->|"imports losses"| node_losses
node_cludi -->|"imports transforms"| node_augmentations
node_cludi -->|"imports logging"| node_logging
node_unet2d -->|"uses attention"| node_attention
node_unet3d -->|"uses attention"| node_attention
node_unet1d -->|"uses attention"| node_attention
node_diffusion_variants -.->|"extends diffusion APIs"| node_diffusion

click node_cludi "https://github.com/bgu-cs-vil/cludi/blob/main/cludi.py"
click node_cluster_results "https://github.com/bgu-cs-vil/cludi/blob/main/eval_utils.py"
click node_student_teacher "https://github.com/bgu-cs-vil/cludi/blob/main/vit_new.py"
click node_diffusion "https://github.com/bgu-cs-vil/cludi/blob/main/denoising_diffusion_pytorch/denoising_diffusion_pytorch.py"
click node_diffusion_ops "https://github.com/bgu-cs-vil/cludi/blob/main/diff_utils.py"
click node_attention "https://github.com/bgu-cs-vil/cludi/blob/main/denoising_diffusion_pytorch/attend.py"
click node_unet2d "https://github.com/bgu-cs-vil/cludi/blob/main/denoising_diffusion_pytorch/karras_unet.py"
click node_unet1d "https://github.com/bgu-cs-vil/cludi/blob/main/denoising_diffusion_pytorch/karras_unet_1d.py"
click node_unet3d "https://github.com/bgu-cs-vil/cludi/blob/main/denoising_diffusion_pytorch/karras_unet_3d.py"
click node_diffusion_variants "https://github.com/bgu-cs-vil/cludi/tree/main/denoising_diffusion_pytorch"
click node_augmentations "https://github.com/bgu-cs-vil/cludi/blob/main/dino_utils.py"
click node_training_utils "https://github.com/bgu-cs-vil/cludi/blob/main/train_utils.py"
click node_losses "https://github.com/bgu-cs-vil/cludi/blob/main/loss_utils.py"
click node_logging "https://github.com/bgu-cs-vil/cludi/blob/main/log_utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_embedding_input,node_cludi,node_cluster_results toneBlue
class node_student_teacher,node_diffusion,node_diffusion_ops,node_attention,node_unet2d,node_unet1d,node_unet3d,node_diffusion_variants toneAmber
class node_augmentations,node_training_utils,node_losses,node_logging toneMint
```

## Components

### Clustering workflow

- **Image embeddings**
- [Training entry point](https://github.com/bgu-cs-vil/cludi/blob/main/cludi.py): `cludi.py`
- [Cluster evaluation](https://github.com/bgu-cs-vil/cludi/blob/main/eval_utils.py): `eval_utils.py`

### Model and diffusion runtime

- [Student teacher models](https://github.com/bgu-cs-vil/cludi/blob/main/vit_new.py): `vit_new.py`
- [Gaussian diffusion](https://github.com/bgu-cs-vil/cludi/blob/main/denoising_diffusion_pytorch/denoising_diffusion_pytorch.py): `denoising_diffusion_pytorch/denoising_diffusion_pytorch.py`
- [Diffusion sampling ops](https://github.com/bgu-cs-vil/cludi/blob/main/diff_utils.py): `diff_utils.py`
- [Attention kernels](https://github.com/bgu-cs-vil/cludi/blob/main/denoising_diffusion_pytorch/attend.py): `denoising_diffusion_pytorch/attend.py`
- [2D Karras U-Net](https://github.com/bgu-cs-vil/cludi/blob/main/denoising_diffusion_pytorch/karras_unet.py): `denoising_diffusion_pytorch/karras_unet.py`
- [1D Karras U-Net](https://github.com/bgu-cs-vil/cludi/blob/main/denoising_diffusion_pytorch/karras_unet_1d.py): `denoising_diffusion_pytorch/karras_unet_1d.py`
- [3D Karras U-Net](https://github.com/bgu-cs-vil/cludi/blob/main/denoising_diffusion_pytorch/karras_unet_3d.py): `denoising_diffusion_pytorch/karras_unet_3d.py`
- [Diffusion variants](https://github.com/bgu-cs-vil/cludi/tree/main/denoising_diffusion_pytorch): `denoising_diffusion_pytorch`

### Training support

- [Image augmentations](https://github.com/bgu-cs-vil/cludi/blob/main/dino_utils.py): `dino_utils.py`
- [Training utilities](https://github.com/bgu-cs-vil/cludi/blob/main/train_utils.py): `train_utils.py`
- [Clustering losses](https://github.com/bgu-cs-vil/cludi/blob/main/loss_utils.py): `loss_utils.py`
- [Logging utilities](https://github.com/bgu-cs-vil/cludi/blob/main/log_utils.py): `log_utils.py`

## Connections

- Image embeddings → Training entry point: provides features (evidence: `README.md`)
- Training entry point → Student teacher models: trains models (evidence: `cludi.py`)
- Training entry point → Diffusion sampling ops: runs sampling (evidence: `cludi.py`)
- Diffusion sampling ops → Gaussian diffusion: noises and samples (evidence: `diff_utils.py`)
- Training utilities → Student teacher models: imports model (evidence: `train_utils.py`)
- Training utilities → Gaussian diffusion: imports diffusion (evidence: `train_utils.py`)
- Training entry point → Cluster evaluation: imports evaluation (evidence: `cludi.py`)
- Training entry point → Training utilities: imports utilities (evidence: `cludi.py`)
- Training entry point → Clustering losses: imports losses (evidence: `cludi.py`)
- Training entry point → Image augmentations: imports transforms (evidence: `cludi.py`)
- Training entry point → Logging utilities: imports logging (evidence: `cludi.py`)
- 2D Karras U-Net → Attention kernels: uses attention (evidence: `denoising_diffusion_pytorch/karras_unet.py`)
- 3D Karras U-Net → Attention kernels: uses attention (evidence: `denoising_diffusion_pytorch/karras_unet_3d.py`)
- 1D Karras U-Net → Attention kernels: uses attention (evidence: `denoising_diffusion_pytorch/karras_unet_1d.py`)
- Diffusion variants → Gaussian diffusion: extends diffusion APIs (evidence: `denoising_diffusion_pytorch/__init__.py`)
