# fmokadem/tdcnn architecture

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

- Interactive diagram: https://gitdiagram.com/fmokadem/tdcnn
- Repository: https://github.com/fmokadem/tdcnn

## Overview

##### Project Type & Purpose
- This is a research-oriented project focusing on model compression for CNNs.
- Its primary function is to run experiments to compare the trade-offs between compression (through HTD) and performance, with modules for finetuning and logging the results.
- The README clearly distinguishes between experimental notebooks (each corresponding to a given CNN) and shared common utility modules that handle core functionality (e.g., logging, dataset management, and model loading).

##### Main Components
a. Experiment Notebooks:
- Three main notebooks are provided (htd-alexnet-res.ipynb, htd-vgg-res.ipynb, htd-resnet-res.ipynb). These drive the experiments for each specific model.
- Loading the pre-trained models.
- Identifying convolutional layers.
- Generating and applying HTD configurations.
- Optionally triggering fine-tuning when the FINETUNE flag is enabled.

b. Common Utility Module:
- The "common" directory encapsulates helper functions such as logging (_logging.py), dataset handling (dataset.py), model loading (load_models.py), and miscellaneous utilities (utils.py).
- This as a “Helper/Utility Library” block that is accessed by notebooks and finetuning modules.

c. Finetuning Module:
- Located in the "finetuned" directory, this section contains the scripts and code to further adjust (finetune) the compressed models after applying HTD.

d. Analysis and Log Processing:
- Scripts like analyze_results.py and jsonify_logs.py are used for post-experiment analysis of the logs.
- As separate “Result Analysis” components that take input from the log files and produce performance comparisons and visualization outputs.

e. External Dependencies / Artifacts:
- Although not explicitly visible in the file tree, note the external pre-trained models and the generated image artifact (model_comparison_radar.png) that come out of the experiments.

##### Relevant Architectural Patterns and Technologies
- The separation of concerns is highlighted with clear boundaries: experiment orchestration (notebooks), core functionality (common), fine-tuning experiments (finetuned), and post-process analysis.
- A modular design where experimental components use shared utility functions, and results are processed in a decoupled manner.
- That this experimental framework is built in Python, using Jupyter Notebooks for interactive execution and possibly leveraging popular deep learning or scientific libraries (even if not explicitly spelled out).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Experiment Notebooks Subgraph
    subgraph "Experiment Notebooks"
        NB1["HTD Experiment Notebook (AlexNet)"]:::notebook
        NB2["HTD Experiment Notebook (VGG16)"]:::notebook
        NB3["HTD Experiment Notebook (ResNet18)"]:::notebook
    end

    %% External Dependencies
    E1["Pre-trained Models"]:::external

    %% Common Utility Module Subgraph
    subgraph "Common Utility Module"
        CU1["Logging"]:::utility
        CU2["Dataset Handler"]:::utility
        CU3["Model Loader"]:::utility
        CU4["Misc Utilities"]:::utility
    end

    %% Finetuning Module Subgraph
    subgraph "Finetuning Module"
        F1["Finetuning Engine"]:::finetuning
        F2["Finetuning Assets"]:::finetuning
    end

    %% Logs Storage (cylindrical shape)
    LS(("Logs Storage")):::utility

    %% Analysis and Log Processing Subgraph
    subgraph "Result Analysis"
        AN1["Analyze Results"]:::analysis
        AN2["JSONify Logs"]:::analysis
    end

    %% External Output Visualizations
    E2["Output Visualizations"]:::external

    %% Connections
    %% Notebooks use Pre-trained Models
    NB1 -->|"uses"| E1
    NB2 -->|"uses"| E1
    NB3 -->|"uses"| E1

    %% Notebooks access Common Utility Module (representative: Logging)
    NB1 -->|"calls"| CU1
    NB2 -->|"calls"| CU1
    NB3 -->|"calls"| CU1

    %% Notebooks trigger Finetuning Module (representative: Finetuning Engine)
    NB1 -->|"triggers"| F1
    NB2 -->|"triggers"| F1
    NB3 -->|"triggers"| F1

    %% Finetuning Engine produces logs
    F1 -->|"produces"| LS

    %% Logs fed into Analysis components
    LS -->|"analyzes"| AN1
    LS -->|"converts"| AN2

    %% Analysis outputs visualizations
    AN1 -->|"generates"| E2
    AN2 -->|"generates"| E2

    %% Styles
    classDef notebook fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef utility fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef finetuning fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef analysis fill:#FF6347,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events for Experiment Notebooks
    click NB1 "https://github.com/fmokadem/tdcnn/blob/main/htd-alexnet-res.ipynb"
    click NB2 "https://github.com/fmokadem/tdcnn/blob/main/htd-vgg-res.ipynb"
    click NB3 "https://github.com/fmokadem/tdcnn/blob/main/htd-resnet-res.ipynb"

    %% Click Events for Common Utility Module files
    click CU1 "https://github.com/fmokadem/tdcnn/blob/main/common/_logging.py"
    click CU2 "https://github.com/fmokadem/tdcnn/blob/main/common/dataset.py"
    click CU3 "https://github.com/fmokadem/tdcnn/blob/main/common/load_models.py"
    click CU4 "https://github.com/fmokadem/tdcnn/blob/main/common/utils.py"

    %% Click Events for Finetuning Module
    click F1 "https://github.com/fmokadem/tdcnn/blob/main/finetuned/finetune_models.py"
    click F2 "https://github.com/fmokadem/tdcnn/tree/main/finetuned/"

    %% Click Event for Logs Storage
    click LS "https://github.com/fmokadem/tdcnn/tree/main/finetuned/logs/"

    %% Click Events for Analysis Modules
    click AN1 "https://github.com/fmokadem/tdcnn/blob/main/analyze_results.py"
    click AN2 "https://github.com/fmokadem/tdcnn/blob/main/jsonify_logs.py"
```
