How andrewspano/disentangled-variational-autoencoder works
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