How davidadsp/generative_deep_learning_2nd_edition works
Purpose and Entry Points
This is the companion codebase for *Generative Deep Learning, 2nd Edition*: an interactive, notebook-first collection of model implementations and exercises. Users primarily start Docker Compose, open Jupyter, and execute chapter/example notebooks under notebooks/. Runtime setup is defined by docker-compose.yml, GPU alternative docker-compose.gpu.yml, and image definitions in docker/Dockerfile and docker/Dockerfile.gpu.
Execution Environment
Docker provides the reproducible Python/Jupyter environment, with CPU and GPU deployment variants. Environment variables from a local .env (templated by sample.env) supply Jupyter/TensorBoard ports and Kaggle credentials. Cloud GPU usage is documented in docs/googlecloud.md; local container operation in docs/docker.md. Dependencies are centralized in requirements.txt.
Notebook Curriculum as Application Surface
Each notebook is a self-contained training/inference workflow rather than part of a shared application service. The content progresses from neural-network foundations through generative-model families:
• MLP/CNN foundations: notebooks/02_deeplearning/01_mlp/mlp.ipynb, notebooks/02_deeplearning/02_cnn/cnn.ipynb
• VAEs: notebooks/03_vae/01_autoencoder/autoencoder.ipynb, notebooks/03_vae/02_vae_fashion/vae_fashion.ipynb
• GANs: notebooks/04_gan/01_dcgan/dcgan.ipynb, notebooks/04_gan/02_wgan_gp/wgan_gp.ipynb
• Autoregressive models: notebooks/05_autoregressive/01_lstm/lstm.ipynb, notebooks/05_autoregressive/02_pixelcnn/pixelcnn.ipynb
• Later methods and applications: notebooks/06_normflow/01_realnvp/realnvp.ipynb, notebooks/08_diffusion/01_ddm/ddm.ipynb, notebooks/09_transformer/gpt/gpt.ipynb.
Training Artifact Boundary
Examples conventionally separate generated state from source: each model directory has checkpoint/, logs/, models/, and output/ directories, generally gitignored. Notebook execution reads prepared/downloaded data, trains models, writes recoverable checkpoints and saved models, emits TensorBoard logs, and produces samples/visualizations. Representative layout: notebooks/04_gan/01_dcgan/checkpoint, notebooks/04_gan/01_dcgan/logs, notebooks/04_gan/01_dcgan/output.
Shared and Domain-Specific Python Support
Most implementation logic lives inline in notebooks; reusable support is intentionally limited. Cross-notebook utilities reside in notebooks/utils.py. Complex domain-specific preprocessing/model support is colocated with music notebooks: notebooks/11_music/01_transformer/transformer_utils.py and notebooks/11_music/02_musegan/musegan_utils.py. VAE face-specific support is in notebooks/03_vae/03_vae_faces/vae_utils.py.
Data Acquisition and External Services
Persistent datasets are expected beneath data/, excluded from version control. scripts/download.sh is the data-ingestion entry point and dispatches source-specific downloaders, including Kaggle-backed acquisition in scripts/downloaders/download_kaggle_data.sh and music-data downloaders such as scripts/downloaders/download_bach_chorale_data.sh. Kaggle is the material external service and requires KAGGLE_USERNAME/KAGGLE_KEY; downloaded data forms the boundary between external sources and local notebook workflows.
Observability
TensorBoard is the experiment-monitoring surface. scripts/tensorboard.sh targets a selected chapter/example log directory and exposes it through the configured host port. This couples directly to per-example logs/ outputs, for example notebooks/08_diffusion/01_ddm/logs and notebooks/11_music/01_transformer/logs.
Main entry points: docker-compose.yml Docker Compose · download.sh Data Download Entry Point · Dockerfile Jupyter Images · output Per-Example Outputs
Components 17
Execution Environment
- Docker Compose · CPU and GPU Compose variants launch the notebook environment.
docker-compose.yml - Jupyter Images · CPU and GPU image definitions provide the reproducible Python runtime.
docker/Dockerfile - Python Dependencies
requirements.txt - Jupyter Notebook Runtime · Primary user-facing execution environment.
Notebook Curriculum
- Shared Notebook Utilities
notebooks/utils.py - MLP and CNN
notebooks/02_deeplearning/01_mlp/mlp.ipynb - VAE Workflows · Autoencoder, Fashion VAE, and face VAE examples.
notebooks/03_vae/02_vae_fashion/vae_fashion.ipynb - GAN Workflows · DCGAN and WGAN-GP training examples.
notebooks/04_gan/01_dcgan/dcgan.ipynb - Autoregressive Workflows · LSTM and PixelCNN examples.
notebooks/05_autoregressive/01_lstm/lstm.ipynb - Flows, Diffusion, Transformers · Later generative-model workflows.
notebooks/08_diffusion/01_ddm/ddm.ipynb - Music Model Support · Colocated preprocessing and model utilities for music notebooks.
notebooks/11_music/01_transformer/transformer_utils.py
Data Acquisition
- Data Download Entry Point · Dispatches source-specific dataset downloaders.
scripts/download.sh - Kaggle · Credentials are supplied through the local environment.
scripts/downloaders/download_kaggle_data.sh - Local Datasets · Downloaded and prepared notebook input data.
Training Artifacts
- Per-Example Outputs · Checkpoints, saved models, logs, and samples are kept beside each example.
notebooks/04_gan/01_dcgan/output - TensorBoard Launcher · Selects an example log directory and exposes TensorBoard.
scripts/tensorboard.sh - TensorBoard
Connections 16
- Docker Compose → Jupyter Images: builds/runs
- Jupyter Images → Python Dependencies: installs
- Docker Compose → Jupyter Notebook Runtime: starts
- Jupyter Notebook Runtime → MLP and CNN: executes
- Jupyter Notebook Runtime → VAE Workflows: executes
- Jupyter Notebook Runtime → GAN Workflows: executes
- Jupyter Notebook Runtime → Autoregressive Workflows: executes
- Jupyter Notebook Runtime → Flows, Diffusion, Transformers: executes
- Jupyter Notebook Runtime → Shared Notebook Utilities: imports
- Jupyter Notebook Runtime → Music Model Support: uses for music examples
- Data Download Entry Point → Kaggle: acquires datasets from
- Data Download Entry Point → Local Datasets: writes
- Local Datasets → Jupyter Notebook Runtime: feeds workflows
- Jupyter Notebook Runtime → Per-Example Outputs: writes checkpoints, models, logs, samples
- Per-Example Outputs → TensorBoard Launcher: log directory
- TensorBoard Launcher → TensorBoard: launches