# yashvashist-iitbhu/enhanced-loss-function architecture

> Architecture diagram of the GitHub repository yashvashist-iitbhu/enhanced-loss-function, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yashvashist-iitbhu/enhanced-loss-function
- Repository: https://github.com/yashvashist-iitbhu/enhanced-loss-function

## Overview

##### Project type and purpose
- This is an ML research/pipeline project aimed at implementing an Enhanced AM-Softmax loss for face-recognition tasks. It’s not a web or full-stack app but an offline data-processing and model-training pipeline, driven by Jupyter notebooks, CSV datasets, and a final report.

##### File structure
Top‐level files:
- Final_model_94%.ipynb – Main training & evaluation notebook.
- LFW.ipynb – Data preprocessing and exploration on the LFW dataset.
- lfw_allnames.csv, lfw_readme.csv – Dataset metadata.
- matchpairsDev*.csv / mismatchpairsDev*.csv – Positive/negative face-pair labels for dev/train/test splits.
- report (2).pdf – Final write-up of methods and results.
- README.md – Project overview and loss-function math.

##### README for additional insights
- Purpose: Modify AM-Softmax with an additive margin and exponential scaling factor to improve intra-class compactness and inter-class separability.
- Key components: data ingestion, custom loss module, model training, and evaluation.

a. Main components:
1. Data Ingestion & Storage
2. Data Preprocessing & Pair Generation
3. Model Definition & Enhanced Loss Module
4. Training Engine
5. Evaluation & Metrics
6. Reporting & Visualization
b. Relationships & data flow:
- “Data Ingestion” → “Preprocessing”
- “Preprocessing” → “Model Definition” & “Training Engine”
- “Model Definition” (Loss Module) → “Training Engine”
- “Training Engine” → “Evaluation & Metrics”
- “Evaluation & Metrics” → “Reporting & Visualization”
c. Architectural patterns/design principles:
- Pipeline pattern: sequential stages transforming raw CSV → features → trained model → results.
- Modularity: separate components for loss function, data prep, training, evaluation.
d. Technologies/frameworks:
- Jupyter Notebooks for orchestration (LFW.ipynb, Final_model_94%.ipynb)
- Python libraries (e.g., NumPy, Pandas, TensorFlow or PyTorch – implied in notebooks)
- CSV files as data store
- PDF report for final deliverable

##### Detailed element checklist
- Component labels: “Data Ingestion (lfw_allnames.csv, …)”, “Preprocessing (LFW.ipynb)”, “Enhanced AM-Softmax Loss Module”, etc.
- Parameter inputs (m, s) feeding into loss block
- Output artifacts: trained model checkpoint, evaluation metrics, PDF report

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Storage
    subgraph "Data Ingestion & Storage"
        AllNames["lfw_allnames.csv"]:::data
        ReadmeCSV["lfw_readme.csv"]:::data
        MatchTrain["matchpairsDevTrain.csv"]:::data
        MismatchTrain["mismatchpairsDevTrain.csv"]:::data
        MatchTest["matchpairsDevTest.csv"]:::data
        MismatchTest["mismatchpairsDevTest.csv"]:::data
    end

    %% Preprocessing
    DataPre["Preprocessing\n(LFW.ipynb)"]:::process

    %% Overview & Loss Spec
    Overview["README.md"]:::process

    %% Model & Loss Module
    ModelDef["Model Definition & Enhanced AM-Softmax Loss\n(Final_model_94%.ipynb)"]:::model

    %% Training Engine
    Training["Training Engine\n(Final_model_94%.ipynb)"]:::model

    %% Evaluation & Metrics
    Evaluation["Evaluation & Metrics\n(Final_model_94%.ipynb)"]:::evaluation

    %% Reporting & Visualization
    Report["Reporting & Visualization\n(report (2).pdf)"]:::report

    %% Data Flow
    AllNames -->|"raw CSVs"| DataPre
    ReadmeCSV -->|"raw CSVs"| DataPre
    MatchTrain -->|"raw CSVs"| DataPre
    MismatchTrain -->|"raw CSVs"| DataPre
    MatchTest -->|"raw CSVs"| DataPre
    MismatchTest -->|"raw CSVs"| DataPre

    DataPre -->|"feature embeddings"| ModelDef
    DataPre -->|"input pairs"| Training

    Overview -->|"loss specification"| ModelDef

    ModelDef -->|"Enhanced AM-Softmax"| Training

    Training -->|"trained weights"| Evaluation

    Evaluation -->|"metrics & plots"| Report

    %% Click Events
    click AllNames "https://github.com/yashvashist-iitbhu/enhanced-loss-function/blob/main/lfw_allnames.csv"
    click ReadmeCSV "https://github.com/yashvashist-iitbhu/enhanced-loss-function/blob/main/lfw_readme.csv"
    click MatchTrain "https://github.com/yashvashist-iitbhu/enhanced-loss-function/blob/main/matchpairsDevTrain.csv"
    click MismatchTrain "https://github.com/yashvashist-iitbhu/enhanced-loss-function/blob/main/mismatchpairsDevTrain.csv"
    click MatchTest "https://github.com/yashvashist-iitbhu/enhanced-loss-function/blob/main/matchpairsDevTest.csv"
    click MismatchTest "https://github.com/yashvashist-iitbhu/enhanced-loss-function/blob/main/mismatchpairsDevTest.csv"
    click DataPre "https://github.com/yashvashist-iitbhu/enhanced-loss-function/blob/main/LFW.ipynb"
    click Overview "https://github.com/yashvashist-iitbhu/enhanced-loss-function/blob/main/README.md"
    click ModelDef "https://github.com/yashvashist-iitbhu/enhanced-loss-function/blob/main/Final_model_94%.ipynb"
    click Training "https://github.com/yashvashist-iitbhu/enhanced-loss-function/blob/main/Final_model_94%.ipynb"
    click Evaluation "https://github.com/yashvashist-iitbhu/enhanced-loss-function/blob/main/Final_model_94%.ipynb"
    click Report "https://github.com/yashvashist-iitbhu/enhanced-loss-function/blob/main/report (2).pdf"

    %% Styles
    classDef data fill:#cce5ff,stroke:#004085,color:#004085;
    classDef process fill:#d4edda,stroke:#155724,color:#155724;
    classDef model fill:#fff3cd,stroke:#856404,color:#856404;
    classDef evaluation fill:#e2d5f3,stroke:#4b0082,color:#4b0082;
    classDef report fill:#f5c6cb,stroke:#721c24,color:#721c24;
```
