# aleflabo/hycoclip architecture

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

- Interactive diagram: https://gitdiagram.com/aleflabo/hycoclip
- Repository: https://github.com/aleflabo/hycoclip

## Overview

##### Main Components
- Data & Assets:
- Assets and Synsets: The “assets” folder (for imagenet_synset and figures) and the raw datasets (e.g., ImageNet, COCO, Flickr30k) serve as resources for training and evaluation.
- WebDataset Preparation: Utilities such as “utils/prepare_GRIT_webdataset.py” handle dataset preprocessing.
- Configuration Management:
- Config files (in “configs”) contain separate configurations for different training regimes and evaluations (zero-shot classification, retrieval, hierarchical metrics).
- Core Library (hycoclip Package):
- Model Definition: “hycoclip/models.py” defines the architecture.
- Encoders: “hycoclip/encoders” includes image and text encoders.
- Evaluation: “hycoclip/evaluation” includes components for classification, retrieval, hierarchical metrics, and catalog lookup.
- Hyperbolic Components: “hycoclip/lorentz.py” and parts of the evaluation code indicate the use of hyperbolic geometry.
- Supporting Utilities: Files for checkpointing, distributed training, and timer utilities in “hycoclip/utils.”
- Training & Evaluation Scripts:
- “scripts/train.py”: Orchestrates the training process.
- “scripts/evaluate.py”: Handles evaluation tasks.
- Specialized scripts: Others (e.g., “scripts/interpolating_points.py”, “scripts/spatial_norm_dist.py”, “scripts/save_embeddings.py”) that cover interpolation, embedding saving, and spatial norm distribution analysis.
- Setup & Dependencies:
- Files like “requirements.txt” and “setup.py” define dependencies including PyTorch, timm, and others.

##### Relationships and Interactions
- Data flows from external datasets and assets into preprocessing utilities and mapped via “hycoclip/data” modules.
- Config files (in “configs”) drive both the training and evaluation pipelines by providing hyperparameters and architectural settings.
- The core “hycoclip” library components (encoders, models, and hyperbolic modules) interact to produce embeddings from image-text pairs.
- Scripts invoke these modules for specific tasks (training, evaluation, interpolation, etc.) and pass checkpoints and config parameters.
- External dependencies (e.g., Torch, torchvision) serve as the backbone for tensor operations and model management, integrated via setup instructions.

##### Architectural Patterns & Design Principles
- Modular design: Separation between configuration, model implementation, data processing, and training/evaluation scripts.
- Reusability and extensibility: A clearly modular “hycoclip” package allows various tasks (classification, retrieval) to share components like encoders and utility functions.
- Pipeline architecture: Data preparation, model training/inference, and evaluation follow distinct, sequential steps.
- Distributed and checkpoint management functionalities signal a design that supports large-scale training.

##### Technologies, Frameworks, and Libraries
- PyTorch and TorchVision (explicit installation reference).
- Timm: For pre-trained vision models.
- WebDataset: For handling large-scale and raw dataset processing.
- Hyperbolic representations are central (with custom modules like “lorentz.py”).

##### Elements
- Use clearly labeled blocks for each primary component (Data Sources, Preprocessing, Model Module, Encoders, Evaluation Modules, Training Pipeline).
- Components:
- Detail on hyperbolic embedding (special emphasis on “lorentz.py” and compositional structure) as this is central to the research contribution.

##### Final Recommendations
- Clearly separate each module (data processing, model components, training, evaluation) and illustrate the flow of data through them.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Assets
    subgraph "Data & Assets"
        A1["Assets & Raw Data"]:::data
        A2["Preprocessing Utility"]:::utility
    end

    %% Configuration Management
    subgraph "Configuration Management"
        C1["Configuration Files"]:::config
    end

    %% Core Library
    subgraph "Core Library"
        M1["Model Definition"]:::core
        E1["Encoders"]:::core
        EV1["Evaluation Modules"]:::core
        H1["Hyperbolic Component"]:::core
        U1["Supporting Utilities"]:::core
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        T1["Training Script"]:::script
    end

    %% Evaluation Pipeline
    subgraph "Evaluation Pipeline"
        E2["Evaluation Script"]:::script
        subgraph "Specialized Scripts"
            S1["Interpolation Script"]:::script
            S2["Spatial Norm Dist Script"]:::script
            S3["Save Embeddings Script"]:::script
        end
    end

    %% Setup & Dependencies
    subgraph "Setup & Dependencies"
        DEP1["Requirements & Dependencies"]:::setup
        DEP2["Setup Script"]:::setup
    end

    %% Connections
    A1 --> A2
    A2 --> C1

    C1 --> M1
    C1 --> E1
    C1 --> EV1
    C1 --> H1
    C1 --> U1

    M1 --> T1
    E1 --> T1
    H1 --> T1
    U1 --> T1

    M1 --> E2
    EV1 --> E2
    U1 --> E2

    M1 --> S1
    M1 --> S2
    M1 --> S3
    S1 --> E2
    S2 --> E2
    S3 --> E2

    DEP1 --> T1
    DEP2 --> T1
    DEP1 --> E2
    DEP2 --> E2

    %% Click Events
    click A1 "https://github.com/aleflabo/hycoclip/tree/main/assets"
    click A2 "https://github.com/aleflabo/hycoclip/blob/main/utils/prepare_GRIT_webdataset.py"
    click C1 "https://github.com/aleflabo/hycoclip/tree/main/configs"
    click M1 "https://github.com/aleflabo/hycoclip/blob/main/hycoclip/models.py"
    click E1 "https://github.com/aleflabo/hycoclip/tree/main/hycoclip/encoders"
    click EV1 "https://github.com/aleflabo/hycoclip/tree/main/hycoclip/evaluation"
    click H1 "https://github.com/aleflabo/hycoclip/blob/main/hycoclip/lorentz.py"
    click U1 "https://github.com/aleflabo/hycoclip/tree/main/hycoclip/utils"
    click T1 "https://github.com/aleflabo/hycoclip/blob/main/scripts/train.py"
    click E2 "https://github.com/aleflabo/hycoclip/blob/main/scripts/evaluate.py"
    click S1 "https://github.com/aleflabo/hycoclip/blob/main/scripts/interpolating_points.py"
    click S2 "https://github.com/aleflabo/hycoclip/blob/main/scripts/spatial_norm_dist.py"
    click S3 "https://github.com/aleflabo/hycoclip/blob/main/scripts/save_embeddings.py"
    click DEP1 "https://github.com/aleflabo/hycoclip/blob/main/requirements.txt"
    click DEP2 "https://github.com/aleflabo/hycoclip/blob/main/setup.py"

    %% Styles
    classDef data fill:#F4F1BB,stroke:#333,stroke-width:2px,color:#000;
    classDef config fill:#B8D8BA,stroke:#333,stroke-width:2px,color:#000;
    classDef core fill:#AED9E0,stroke:#333,stroke-width:2px,color:#000;
    classDef script fill:#F6AE2D,stroke:#333,stroke-width:2px,color:#000;
    classDef setup fill:#E4C1F9,stroke:#333,stroke-width:2px,color:#000;
    classDef utility fill:#FF9AA2,stroke:#333,stroke-width:2px,color:#000;
```
