# rasbt/deeplearning-models architecture

> Architecture diagram of the GitHub repository rasbt/deeplearning-models, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rasbt/deeplearning-models
- Repository: https://github.com/rasbt/deeplearning-models

## Overview

#### Purpose and Entry Points
This is an educational deep-learning notebook collection, not a deployed application or unified package. Users execute topic-specific Jupyter notebooks directly. `README.md` is the catalog and primary navigation surface; runnable entry points are notebooks under `pytorch_ipynb/`, `pytorch-lightning_ipynb/`, and `tensorflow1_ipynb/`.

#### Framework Partition
The repository maintains parallel implementations across three runtime families:
- Native PyTorch experiments: `pytorch_ipynb/cnn/`, `pytorch_ipynb/rnn/`
- PyTorch Lightning versions of selected supervised-learning workflows: `pytorch-lightning_ipynb/cnn/`, `pytorch-lightning_ipynb/transformer/`
- Legacy TensorFlow 1.x equivalents: `tensorflow1_ipynb/cnn/`, `tensorflow1_ipynb/mechanics/`

These are largely independent instructional tracks rather than interchangeable modules.

#### PyTorch Shared Workflow Layer
Native PyTorch notebooks can reuse local helpers for common training lifecycle stages: data loading, training, evaluation, plotting, and utility behavior. The principal shared-code boundary is:
- `pytorch_ipynb/helper_data.py`
- `pytorch_ipynb/helper_train.py`
- `pytorch_ipynb/helper_evaluate.py`

Typical notebook control flow is dataset acquisition/preprocessing → `Dataset`/`DataLoader` batching → model definition → optimization loop → metrics/visualization. Individual notebooks remain responsible for their model and experiment configuration.

#### Model Families and Learning Tasks
The main educational content is organized by model/task families:
- Supervised tabular and image classification, MLPs, and CNN architecture variants: `pytorch_ipynb/basic-ml/`, `pytorch_ipynb/mlp/`, `pytorch_ipynb/cnn/`
- Sequence and NLP models, from RNNs through DistilBERT: `pytorch_ipynb/rnn/`, `pytorch_ipynb/transformer/`
- Generative representation/modeling work: `pytorch_ipynb/autoencoder/`, `pytorch_ipynb/gan/`
- Specialized methods: ordinal regression and graph neural networks: `pytorch_ipynb/ordinal/`, `pytorch_ipynb/gnn/`

Each notebook is a self-contained experiment, often using the same conceptual pipeline but different architectures, loss functions, or datasets.

#### Data, Model, and Runtime Boundaries
Data is primarily external or downloaded at execution time (e.g., MNIST, CIFAR-10, CelebA, IMDB, QuickDraw); only small example datasets are versioned under `pytorch_ipynb/data/` and `tensorflow1_ipynb/data/`. Dataset-specific ingestion examples live in `pytorch_ipynb/mechanics/`; TensorFlow 1.x storage/pipeline examples cover HDF5, NPZ, TFRecords, and queues in `tensorflow1_ipynb/mechanics/`.

Material external ecosystems include PyTorch, TorchVision, PyTorch Lightning, TensorFlow 1.x, Hugging Face/DistilBERT, scikit-learn, TorchMetrics, and selected libraries such as `pl_cross` and `embetter`. GPU-oriented examples demonstrate DataParallel, pipeline parallelism, pinned memory, AMP, and gradient checkpointing.

#### Lightning and Experiment Templates
Lightning notebooks encapsulate model/training lifecycle under Lightning abstractions, including augmentation, cross-validation, and transformer fine-tuning. Key examples are `pytorch-lightning_ipynb/data-augmentation/autoaugment/with-autoaugment.ipynb`, `pytorch-lightning_ipynb/kfold/kfold-light-cnn-mnist.ipynb`, and `pytorch-lightning_ipynb/transformer/distilbert-finetuning-ii.ipynb`.

Reusable starting points and batch/HPC-oriented execution artifacts are isolated under `templates/pytorch_lightning/`, notably `templates/pytorch_lightning/template_classification_basic.ipynb` and `templates/pytorch_lightning/tune_classification_basic.py`.

#### Visualization and Interpretation
Visualization is an adjunct execution stage: notebooks train/load a CNN then compute input-gradient or guided-backprop interpretations. The Cats-vs-Dogs VGG16 visualization subset contains reusable model/data code at `pytorch_ipynb/viz/cnns/cats-and-dogs/vgg16.py` and `pytorch_ipynb/viz/cnns/cats-and-dogs/datautils.py`, consumed by adjacent visualization notebooks.

Main entry points: [`README.md`](https://github.com/rasbt/deeplearning-models/blob/master/README.md) (README catalog), [`pytorch_ipynb/helper_train.py`](https://github.com/rasbt/deeplearning-models/blob/master/pytorch_ipynb/helper_train.py) (Training helpers), [`pytorch-lightning_ipynb/transformer/distilbert-finetuning-ii.ipynb`](https://github.com/rasbt/deeplearning-models/blob/master/pytorch-lightning_ipynb/transformer/distilbert-finetuning-ii.ipynb) (Lightning DistilBERT), [`pytorch_ipynb/viz/cnns/cats-and-dogs/vgg16.py`](https://github.com/rasbt/deeplearning-models/blob/master/pytorch_ipynb/viz/cnns/cats-and-dogs/vgg16.py) (CNN interpretation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pytorch["Native PyTorch"]
  node_pytorch_supervised["Supervised models<br/>notebook collection"]
  node_pytorch_sequences["Sequence &amp; NLP<br/>notebook collection"]
  node_pytorch_transformers["Transformer notebooks<br/>notebook collection"]
  node_pytorch_generative["Generative models<br/>notebook collection"]
  node_pytorch_specialized["Specialized methods<br/>notebook collection"]
  node_pytorch_data_mechanics["Dataset mechanics<br/>notebook collection"]
  node_pytorch_helpers["Training helpers<br/>shared code<br/>[helper_train.py]"]
  node_pytorch_local_data[("Versioned examples<br/>local data")]
  node_visualization["CNN interpretation<br/>notebook collection<br/>[vgg16.py]"]
end

subgraph group_lightning["PyTorch Lightning"]
  node_lightning_workflows["Lightning workflows<br/>notebook collection"]
  node_lightning_transformers["Lightning DistilBERT<br/>fine-tuning notebook"]
  node_lightning_templates["Lightning templates<br/>starter artifacts"]
end

subgraph group_tensorflow["TensorFlow 1.x"]
  node_tf1_models["TF1 CNN experiments<br/>notebook collection"]
  node_tf1_mechanics["TF1 data pipelines<br/>notebook collection"]
  node_tf1_local_data[("TF1 example data<br/>local data")]
end

node_readme["README catalog<br/>navigation<br/>[README.md]"]
node_external_data[("External datasets<br/>data source")]

node_readme -->|"catalogs"| node_pytorch_supervised
node_readme -->|"catalogs"| node_pytorch_sequences
node_readme -->|"catalogs"| node_lightning_workflows
node_readme -->|"catalogs"| node_tf1_models
node_external_data -->|"ingestion examples"| node_pytorch_data_mechanics
node_external_data -.->|"downloaded at runtime"| node_pytorch_supervised
node_external_data -.->|"downloaded at runtime"| node_pytorch_sequences
node_pytorch_local_data -.->|"small examples"| node_pytorch_supervised
node_pytorch_data_mechanics -.->|"feeds experiments"| node_pytorch_supervised
node_pytorch_helpers -.->|"optional training lifecycle"| node_pytorch_supervised
node_pytorch_helpers -.->|"optional training lifecycle"| node_pytorch_sequences
node_pytorch_helpers -.->|"optional training lifecycle"| node_pytorch_generative
node_pytorch_sequences -.->|"includes NLP progression"| node_pytorch_transformers
node_pytorch_supervised -->|"trained CNNs interpreted"| node_visualization
node_external_data -.->|"training data"| node_lightning_workflows
node_lightning_templates -.->|"starting patterns"| node_lightning_workflows
node_lightning_templates -.->|"training pattern"| node_lightning_transformers
node_external_data -.->|"fine-tuning data"| node_lightning_transformers
node_external_data -->|"storage and pipeline formats"| node_tf1_mechanics
node_tf1_mechanics -.->|"feeds experiments"| node_tf1_models
node_tf1_local_data -.->|"small examples"| node_tf1_mechanics

click node_readme "https://github.com/rasbt/deeplearning-models/blob/master/README.md"
click node_pytorch_helpers "https://github.com/rasbt/deeplearning-models/blob/master/pytorch_ipynb/helper_train.py"
click node_visualization "https://github.com/rasbt/deeplearning-models/blob/master/pytorch_ipynb/viz/cnns/cats-and-dogs/vgg16.py"
click node_lightning_transformers "https://github.com/rasbt/deeplearning-models/blob/master/pytorch-lightning_ipynb/transformer/distilbert-finetuning-ii.ipynb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pytorch_supervised,node_pytorch_sequences,node_pytorch_transformers,node_pytorch_generative,node_pytorch_specialized,node_pytorch_data_mechanics,node_pytorch_helpers,node_pytorch_local_data,node_visualization toneBlue
class node_lightning_workflows,node_lightning_transformers,node_lightning_templates toneAmber
class node_tf1_models,node_tf1_mechanics,node_tf1_local_data toneMint
class node_readme,node_external_data toneNeutral
```

## Components

### Native PyTorch

Self-contained instructional notebooks with optional shared helpers.

- **Supervised models**: notebook collection · Tabular, MLP, and CNN classification experiments.
- **Sequence & NLP**: notebook collection · RNN through DistilBERT experiments.
- **Transformer notebooks**: notebook collection
- **Generative models**: notebook collection · Autoencoder and GAN experiments.
- **Specialized methods**: notebook collection · Ordinal regression and graph neural network notebooks.
- **Dataset mechanics**: notebook collection · Dataset-specific ingestion examples.
- [Training helpers](https://github.com/rasbt/deeplearning-models/blob/master/pytorch_ipynb/helper_train.py): shared code · Shared data loading, training, and evaluation lifecycle helpers. · `pytorch_ipynb/helper_train.py`
- **Versioned examples**: local data · Small bundled example datasets.
- [CNN interpretation](https://github.com/rasbt/deeplearning-models/blob/master/pytorch_ipynb/viz/cnns/cats-and-dogs/vgg16.py): notebook collection · Input-gradient and guided-backprop visualization workflows. · `pytorch_ipynb/viz/cnns/cats-and-dogs/vgg16.py`

### PyTorch Lightning

Lightning-based training and fine-tuning examples.

- **Lightning workflows**: notebook collection · Augmentation, cross-validation, and supervised training examples.
- [Lightning DistilBERT](https://github.com/rasbt/deeplearning-models/blob/master/pytorch-lightning_ipynb/transformer/distilbert-finetuning-ii.ipynb): fine-tuning notebook · `pytorch-lightning_ipynb/transformer/distilbert-finetuning-ii.ipynb`
- **Lightning templates**: starter artifacts · Reusable notebook and batch/HPC-oriented training starters.

### TensorFlow 1.x

Legacy parallel instructional track.

- **TF1 CNN experiments**: notebook collection · Legacy TensorFlow 1.x model equivalents.
- **TF1 data pipelines**: notebook collection · HDF5, NPZ, TFRecords, and queue examples.
- **TF1 example data**: local data

### Other components

- [README catalog](https://github.com/rasbt/deeplearning-models/blob/master/README.md): navigation · Primary catalog for directly executed notebooks. · `README.md`
- **External datasets**: data source · Datasets are commonly downloaded during notebook execution.

## Connections

- README catalog → Supervised models: catalogs
- README catalog → Sequence & NLP: catalogs
- README catalog → Lightning workflows: catalogs
- README catalog → TF1 CNN experiments: catalogs
- External datasets → Dataset mechanics: ingestion examples
- External datasets → Supervised models: downloaded at runtime
- External datasets → Sequence & NLP: downloaded at runtime
- Versioned examples → Supervised models: small examples
- Dataset mechanics → Supervised models: feeds experiments
- Training helpers → Supervised models: optional training lifecycle
- Training helpers → Sequence & NLP: optional training lifecycle
- Training helpers → Generative models: optional training lifecycle
- Sequence & NLP → Transformer notebooks: includes NLP progression
- Supervised models → CNN interpretation: trained CNNs interpreted
- External datasets → Lightning workflows: training data
- Lightning templates → Lightning workflows: starting patterns
- Lightning templates → Lightning DistilBERT: training pattern
- External datasets → Lightning DistilBERT: fine-tuning data
- External datasets → TF1 data pipelines: storage and pipeline formats
- TF1 data pipelines → TF1 CNN experiments: feeds experiments
- TF1 example data → TF1 data pipelines: small examples
