# andrewspano/disentangled-variational-autoencoder architecture

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

- Interactive diagram: https://gitdiagram.com/andrewspano/disentangled-variational-autoencoder
- Repository: https://github.com/andrewspano/disentangled-variational-autoencoder

## Overview

##### Project type and purpose
- This is a research-oriented ML project implementing Variational Autoencoders (VAE and β-VAE) in PyTorch/PyTorch Lightning.
- Its primary function is to train and evaluate generative models (VAEs) on image datasets (MNIST, FashionMNIST, CIFAR10) via a CLI or Colab notebook, using different configuration files.

##### File structure
Top-level directories and files:
- config/ – configuration files for dataset, architecture, hyperparameters
- src/ – core codebase
– main.py – CLI entrypoint
– models/ – VAE and β-VAE PyTorch Lightning modules
– utils/ – error definitions, CLI interface parser, helper utilities
- notebook/ – Colab notebook for interactive experimentation
- mathematical_analysis/ – LaTeX and PDF notes on VAE theory
- tests/ – generated sample outputs and result markdowns
- requirements.txt, README.md, .gitignore, LICENSE

##### README for insights
- Confirms two supported model variants: VAE and β-VAE
- Explains execution flow: `python3 main.py -c <config> -v <VAE|B-VAE>`
- Describes config file schema (dataset, conv layers, latent dim, hyperparameters)
- Points to examples in config/ and usage patterns in notebook/

##### Main components
a. Entrypoint & Configuration
– “CLI Interface” component (main.py + src/utils/interface.py)
– “Config Loader” (parses config/*.cfg)
b. Data Layer
– “Dataset Loader” (PyTorch datasets: MNIST, FashionMNIST, CIFAR10)
c. Model Layer
– “VAE Module” (src/models/vae.py)
– “β-VAE Module” (src/models/beta_vae.py)
– “Model Utilities” (src/models/model_utils.py)
d. Training Engine
– “PyTorch Lightning Trainer”
e. Utility Layer
– “Error Handling” (src/utils/errors.py)
– “General Utils” (src/utils/utils.py)
f. Outputs & Artifacts
– “Generated Samples” → tests/images/
– “Evaluation Reports” → tests/*.md
g. Notebook & Analysis
– “Colab Notebook” (notebook/notebook.ipynb)
– “Mathematical Analysis Docs” (mathematical_analysis/*.pdf/.tex/images)

##### Relationships and interactions
- The CLI Interface reads a .cfg file via Config Loader.
- Config Loader passes parameters to Dataset Loader & Model Factory.
- Dataset Loader pulls data from local disk or downloads via PyTorch.
- Model Factory (in main.py) instantiates either VAE or β-VAE module, injecting conv-layer specs, latent dim, β hyperparameter.
- Training Engine wraps the model and dataset, running epochs, backprop, checkpointing.
- Utility Layer supports logging, error checking, seed setting, metrics computation.
- Training Engine outputs sample images and markdown summaries to tests/.
- Notebook reuses all src/ components but drives experiments interactively (bypasses CLI).
- Mathematical Analysis docs are a separate artifact (no runtime interaction) but visually support architecture understanding.

##### Architectural patterns and design principles
- Separation of concerns: config vs. interface vs. models vs. utilities
- Pluggable model variants via a simple “variation” flag
- Reuse of PyTorch Lightning for training loop abstraction
- Modular directory layout to support testing and documentation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry point
    CLI["CLI Interface"]:::code

    %% Configuration
    Config["Config Loader"]:::artifact

    %% Data and Models
    Dataset["Dataset Loader"]:::code
    VAE["VAE Module"]:::code
    BVAE["β-VAE Module"]:::code
    Mutils["Model Utilities"]:::code

    %% Training engine
    Trainer["PyTorch Lightning Trainer"]:::external

    %% Utilities
    Errors["Error Handling"]:::code
    Utils["General Utilities"]:::code

    %% Outputs
    Samples["Generated Samples"]:::output
    Reports["Evaluation Reports"]:::output

    %% Notebook & Docs
    Notebook["Colab Notebook"]:::artifact
    Docs["Mathematical Analysis Docs"]:::artifact

    %% Flow
    CLI -->|"reads cfg"| Config
    Config -->|"params"| Dataset
    Config -->|"params"| VAE
    Config -->|"params"| BVAE
    Dataset -->|"data"| Trainer
    VAE -->|"model"| Trainer
    BVAE -->|"model"| Trainer
    Mutils -->|"helpers"| VAE
    Mutils -->|"helpers"| BVAE
    Errors -.-> CLI
    Errors -.-> Trainer
    Utils -.-> CLI
    Utils -.-> Trainer
    Trainer -->|"saves images"| Samples
    Trainer -->|"saves reports"| Reports
    Notebook -->|"interactive call"| Dataset
    Notebook -->|"interactive call"| VAE
    Notebook -->|"interactive call"| BVAE

    %% Docs separate
    Docs

    %% Click Events
    click CLI "https://github.com/andrewspano/disentangled-variational-autoencoder/blob/main/src/main.py"
    click CLI "https://github.com/andrewspano/disentangled-variational-autoencoder/blob/main/src/utils/interface.py"
    click Config "https://github.com/andrewspano/disentangled-variational-autoencoder/tree/main/config/"
    click VAE "https://github.com/andrewspano/disentangled-variational-autoencoder/blob/main/src/models/vae.py"
    click BVAE "https://github.com/andrewspano/disentangled-variational-autoencoder/blob/main/src/models/beta_vae.py"
    click Mutils "https://github.com/andrewspano/disentangled-variational-autoencoder/blob/main/src/models/model_utils.py"
    click Errors "https://github.com/andrewspano/disentangled-variational-autoencoder/blob/main/src/utils/errors.py"
    click Utils "https://github.com/andrewspano/disentangled-variational-autoencoder/blob/main/src/utils/utils.py"
    click Samples "https://github.com/andrewspano/disentangled-variational-autoencoder/tree/main/tests/images/"
    click Reports "https://github.com/andrewspano/disentangled-variational-autoencoder/blob/main/tests/mnist.md"
    click Reports "https://github.com/andrewspano/disentangled-variational-autoencoder/blob/main/tests/fashion_mnist.md"
    click Notebook "https://github.com/andrewspano/disentangled-variational-autoencoder/blob/main/notebook/notebook.ipynb"
    click Docs "https://github.com/andrewspano/disentangled-variational-autoencoder/blob/main/mathematical_analysis/vae_maths.pdf"
    click Docs "https://github.com/andrewspano/disentangled-variational-autoencoder/blob/main/mathematical_analysis/vae_maths.tex"
    click Docs "https://github.com/andrewspano/disentangled-variational-autoencoder/tree/main/mathematical_analysis/images/"

    %% Styles
    classDef code fill:#CAE8FF,stroke:#333,stroke-width:1px;
    classDef external fill:#CFFFB3,stroke:#333,stroke-width:1px;
    classDef artifact fill:#FFF4B3,stroke:#333,stroke-width:1px;
    classDef output fill:#FFE4B5,stroke:#333,stroke-width:1px;
```
