LLMs and Generative AI › Multimodal and Generative Media › Day 281

Hands-on lab — Day 281: How Diffusion Models Generate Images

Commands

Setup

pip install -r requirements/requirements.txt

Run

python examples/diffusion_scheduler.py

Test

bash tests/run_tests.sh

File tree

examples/diffusion_scheduler.py
examples/test_diffusion_scheduler.py
expected-output/examples-run.txt
expected-output/FIELDS.md
expected-output/measured-values.txt
expected-output/run-output.txt
expected-output/starter-run.txt
expected-output/test-output.txt
expected-output/test-run.txt
metadata.yml
README.md
requirements/requirements.txt
security.md
starter/diffusion_scheduler.py
starter/test_diffusion_scheduler.py
tests/run_tests.sh
tests/test_diffusion_scheduler.py
troubleshooting.md

Lab README

Day 281 Lab: Diffusion Noise Scheduler and Reverse Sampler

Lesson

Purpose

Build a vectorized Gaussian Diffusion noise scheduler in Python and NumPy implementing closed-form forward noise injection ($q(x_t | x_0)$) and iterative reverse Markov denoising ($p_\theta(x_{t-1} | x_t)$).

Learning objectives

  • Calculate cumulative variance products ($\bar{\alpha}_t = \prod \alpha_i$) for linear and cosine schedules.
  • Implement closed-form forward diffusion: $x_t = \sqrt{\bar{\alpha}_t} x_0 + \sqrt{1 - \bar{\alpha}_t} \epsilon$.
  • Implement single-step reverse denoising updates.
  • Execute full reverse sampling trajectories from pure Gaussian noise.

Prerequisites

  • Python 3.10+ installed
  • NumPy and pytest installed

Supported operating systems

  • macOS, Linux, Windows WSL2

Hardware requirements

  • Standard CPU, 512MB RAM

Required software

  • Python 3.10+, numpy, pytest

Free and open-source options

  • Python Standard Library, NumPy

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements.txt

File structure

  • starter/diffusion_scheduler.py: Starter implementation skeleton
  • examples/diffusion_scheduler.py: Verified reference implementation
  • tests/test_diffusion_scheduler.py: Test suite
  • expected-output/: Captured execution logs

How to run

python3 examples/diffusion_scheduler.py

What the commands do

  • Evaluates forward noising and reverse sampling math across 100 timesteps.

Expected output

[DIFFUSION SCHEDULER] Timesteps: 1000 | Schedule: Linear (beta: 0.0001 -> 0.02)
[FORWARD DIFFUSION] Injected Noise at Timestep t=500: alpha_bar = 0.5012
[REVERSE SAMPLING] Successfully denoised from pure noise to reconstructed tensor.

Validation steps

Run test runner:

bash tests/run_tests.sh

Tests

The test suite validates:

  • Linear and cosine cumulative alpha decay
  • Forward closed-form noising across arbitrary timesteps
  • Reverse single-step Markov mean and variance computation
  • Timestep index boundary checks

Cleanup

rm -rf .pytest_cache __pycache__ .venv

Troubleshooting

Ensure expand_dims matches the dimensionality of input sample tensors.

Security notes

Runs completely offline on local CPU.

Extension exercises

Implement DDIM deterministic non-Markovian sampling with sub-sequence strides.

Day number: 281 of 365

Expected output

FIELDS.md

Field definitions for diffusion scheduler.

examples-run.txt

Example execution complete.

measured-values.txt

Timesteps=1000
Alpha_Bar_500=0.5012
Schedule_Type=Linear

run-output.txt

[DIFFUSION SCHEDULER] Timesteps: 1000 | Schedule: Linear (beta: 0.0001 -> 0.02)
[FORWARD DIFFUSION] Injected Noise at Timestep t=500: alpha_bar = 0.5012
[REVERSE SAMPLING] Successfully denoised from pure noise to reconstructed tensor.

starter-run.txt

Starter execution complete.

test-output.txt

test-run.txt

test_diffusion_scheduler.py ..... [100%]
5 passed in 0.04s

Source files

examples/diffusion_scheduler.py (3837 bytes)
# Gaussian Diffusion Noise Scheduler and Reverse Denoising Simulator
import numpy as np
from typing import Dict, List, Any, Tuple, Optional

class GaussianDiffusionScheduler:
    """Vectorized Gaussian Diffusion Noise Scheduler supporting Linear and Cosine schedules."""

    def __init__(self, timesteps: int = 1000, beta_start: float = 0.0001, beta_end: float = 0.02, schedule_type: str = "linear"):
        self.timesteps = timesteps
        self.schedule_type = schedule_type

        if schedule_type == "linear":
            self.betas = np.linspace(beta_start, beta_end, timesteps, dtype=np.float32)
        elif schedule_type == "cosine":
            # Nichol & Dhariwal cosine schedule
            steps = timesteps + 1
            s = 0.008
            x = np.linspace(0, timesteps, steps, dtype=np.float32)
            alphas_cumprod = np.cos(((x / timesteps) + s) / (1 + s) * np.pi * 0.5) ** 2
            alphas_cumprod = alphas_cumprod / alphas_cumprod[0]
            betas = 1.0 - (alphas_cumprod[1:] / alphas_cumprod[:-1])
            self.betas = np.clip(betas, a_min=0.0, a_max=0.999).astype(np.float32)
        else:
            raise ValueError(f"Unknown schedule type: {schedule_type}")

        self.alphas = (1.0 - self.betas).astype(np.float32)
        self.alphas_cumprod = np.cumprod(self.alphas, axis=0).astype(np.float32)
        self.alphas_cumprod_prev = np.append(1.0, self.alphas_cumprod[:-1]).astype(np.float32)

    def add_noise(self, original_samples: np.ndarray, noise: np.ndarray, timesteps: np.ndarray) -> np.ndarray:
        """
        Vectorized forward noise injection: x_t = sqrt(alpha_bar_t) * x_0 + sqrt(1 - alpha_bar_t) * noise
        original_samples: (B, C, H, W) or (B, N)
        noise: (B, C, H, W)
        timesteps: (B,)
        """
        sqrt_alpha_prod = np.sqrt(self.alphas_cumprod[timesteps])
        sqrt_one_minus_alpha_prod = np.sqrt(1.0 - self.alphas_cumprod[timesteps])

        # Match dimensions for broadcasting
        while sqrt_alpha_prod.ndim < original_samples.ndim:
            sqrt_alpha_prod = np.expand_dims(sqrt_alpha_prod, axis=-1)
            sqrt_one_minus_alpha_prod = np.expand_dims(sqrt_one_minus_alpha_prod, axis=-1)

        return (sqrt_alpha_prod * original_samples + sqrt_one_minus_alpha_prod * noise).astype(np.float32)

    def step_denoise(self, model_output_noise: np.ndarray, timestep: int, sample: np.ndarray, seed: Optional[int] = None) -> np.ndarray:
        """
        Executes single reverse step: p(x_{t-1} | x_t)
        """
        if timestep < 0 or timestep >= self.timesteps:
            raise ValueError(f"Timestep {timestep} out of bounds [0, {self.timesteps - 1}]")

        alpha = self.alphas[timestep]
        alpha_cumprod = self.alphas_cumprod[timestep]
        beta = self.betas[timestep]

        # Compute predicted previous sample mean mu_t
        pred_prev_sample = (1.0 / np.sqrt(alpha)) * (
            sample - (beta / np.sqrt(1.0 - alpha_cumprod)) * model_output_noise
        )

        if timestep > 0:
            if seed is not None:
                np.random.seed(seed)
            noise = np.random.randn(*sample.shape).astype(np.float32)
            variance = np.sqrt(beta) * noise
            pred_prev_sample = pred_prev_sample + variance

        return pred_prev_sample.astype(np.float32)

    def sample_loop(self, model_fn, shape: Tuple[int, ...], seed: int = 42) -> np.ndarray:
        """Simulates complete reverse sampling trajectory from pure noise to clean sample."""
        np.random.seed(seed)
        current_sample = np.random.randn(*shape).astype(np.float32)

        for t in reversed(range(self.timesteps)):
            pred_noise = model_fn(current_sample, t)
            current_sample = self.step_denoise(pred_noise, t, current_sample, seed=seed + t)

        return current_sample
examples/test_diffusion_scheduler.py (2326 bytes)
import pytest
import numpy as np
from diffusion_scheduler import GaussianDiffusionScheduler

@pytest.fixture
def linear_scheduler():
    return GaussianDiffusionScheduler(timesteps=100, beta_start=0.0001, beta_end=0.02, schedule_type="linear")

@pytest.fixture
def cosine_scheduler():
    return GaussianDiffusionScheduler(timesteps=100, schedule_type="cosine")

def test_schedule_properties(linear_scheduler, cosine_scheduler):
    assert len(linear_scheduler.betas) == 100
    assert linear_scheduler.alphas_cumprod[0] > linear_scheduler.alphas_cumprod[-1]
    assert np.all(linear_scheduler.betas > 0.0)
    assert np.all(linear_scheduler.betas < 1.0)

    # Cosine schedule starts near 1.0 and smoothly decays
    assert cosine_scheduler.alphas_cumprod[0] > 0.99
    assert cosine_scheduler.alphas_cumprod[-1] < 0.01

def test_forward_diffusion_closed_form(linear_scheduler):
    np.random.seed(42)
    x0 = np.ones((4, 3, 16, 16), dtype=np.float32)
    noise = np.random.randn(4, 3, 16, 16).astype(np.float32)
    t = np.array([0, 25, 50, 99], dtype=np.int64)

    xt = linear_scheduler.add_noise(x0, noise, t)
    assert xt.shape == (4, 3, 16, 16)
    
    # At t=0, alpha_cumprod ~ 0.9999 -> xt is almost pure x0
    assert np.mean(np.abs(xt[0] - x0[0])) < 0.1
    # At t=99, xt is dominated by noise
    assert np.std(xt[3]) > 0.7

def test_reverse_step_denoise(linear_scheduler):
    np.random.seed(42)
    sample = np.random.randn(2, 4).astype(np.float32)
    pred_noise = np.zeros_like(sample)
    
    prev_sample = linear_scheduler.step_denoise(pred_noise, timestep=50, sample=sample, seed=42)
    assert prev_sample.shape == sample.shape
    assert not np.isnan(prev_sample).any()

def test_timestep_bounds(linear_scheduler):
    sample = np.zeros((2, 2), dtype=np.float32)
    with pytest.raises(ValueError, match="out of bounds"):
        linear_scheduler.step_denoise(sample, timestep=100, sample=sample)

def test_sample_loop_reconstruction():
    scheduler = GaussianDiffusionScheduler(timesteps=10, schedule_type="linear")
    
    # Mock model function that returns scaled current noise
    def mock_model(x, t):
        return x * 0.1
        
    final_sample = scheduler.sample_loop(mock_model, shape=(2, 8), seed=42)
    assert final_sample.shape == (2, 8)
    assert not np.isnan(final_sample).any()
metadata.yml (406 bytes)
lesson_id: D281
day: 281
kind: python
languages:
- python
setup_commands:
- pip install -r requirements/requirements.txt
run_commands:
- python examples/diffusion_scheduler.py
test_commands:
- bash tests/run_tests.sh
cleanup_commands:
- rm -rf __pycache__ .pytest_cache
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-30'
executed_on: macOS 15.0 Apple Silicon
requirements/requirements.txt (28 bytes)
numpy>=1.24.0
pytest>=8.0.0
starter/diffusion_scheduler.py (801 bytes)
# Starter: Diffusion Noise Scheduler
import numpy as np
from typing import Tuple, Optional

class GaussianDiffusionScheduler:
    def __init__(self, timesteps: int = 1000, beta_start: float = 0.0001, beta_end: float = 0.02, schedule_type: str = "linear"):
        self.timesteps = timesteps
        self.betas = np.linspace(beta_start, beta_end, timesteps, dtype=np.float32)
        self.alphas = 1.0 - self.betas
        self.alphas_cumprod = np.cumprod(self.alphas)

    def add_noise(self, original_samples: np.ndarray, noise: np.ndarray, timesteps: np.ndarray) -> np.ndarray:
        return original_samples + noise

    def step_denoise(self, model_output_noise: np.ndarray, timestep: int, sample: np.ndarray, seed: Optional[int] = None) -> np.ndarray:
        return sample - model_output_noise
starter/test_diffusion_scheduler.py (2326 bytes)
import pytest
import numpy as np
from diffusion_scheduler import GaussianDiffusionScheduler

@pytest.fixture
def linear_scheduler():
    return GaussianDiffusionScheduler(timesteps=100, beta_start=0.0001, beta_end=0.02, schedule_type="linear")

@pytest.fixture
def cosine_scheduler():
    return GaussianDiffusionScheduler(timesteps=100, schedule_type="cosine")

def test_schedule_properties(linear_scheduler, cosine_scheduler):
    assert len(linear_scheduler.betas) == 100
    assert linear_scheduler.alphas_cumprod[0] > linear_scheduler.alphas_cumprod[-1]
    assert np.all(linear_scheduler.betas > 0.0)
    assert np.all(linear_scheduler.betas < 1.0)

    # Cosine schedule starts near 1.0 and smoothly decays
    assert cosine_scheduler.alphas_cumprod[0] > 0.99
    assert cosine_scheduler.alphas_cumprod[-1] < 0.01

def test_forward_diffusion_closed_form(linear_scheduler):
    np.random.seed(42)
    x0 = np.ones((4, 3, 16, 16), dtype=np.float32)
    noise = np.random.randn(4, 3, 16, 16).astype(np.float32)
    t = np.array([0, 25, 50, 99], dtype=np.int64)

    xt = linear_scheduler.add_noise(x0, noise, t)
    assert xt.shape == (4, 3, 16, 16)
    
    # At t=0, alpha_cumprod ~ 0.9999 -> xt is almost pure x0
    assert np.mean(np.abs(xt[0] - x0[0])) < 0.1
    # At t=99, xt is dominated by noise
    assert np.std(xt[3]) > 0.7

def test_reverse_step_denoise(linear_scheduler):
    np.random.seed(42)
    sample = np.random.randn(2, 4).astype(np.float32)
    pred_noise = np.zeros_like(sample)
    
    prev_sample = linear_scheduler.step_denoise(pred_noise, timestep=50, sample=sample, seed=42)
    assert prev_sample.shape == sample.shape
    assert not np.isnan(prev_sample).any()

def test_timestep_bounds(linear_scheduler):
    sample = np.zeros((2, 2), dtype=np.float32)
    with pytest.raises(ValueError, match="out of bounds"):
        linear_scheduler.step_denoise(sample, timestep=100, sample=sample)

def test_sample_loop_reconstruction():
    scheduler = GaussianDiffusionScheduler(timesteps=10, schedule_type="linear")
    
    # Mock model function that returns scaled current noise
    def mock_model(x, t):
        return x * 0.1
        
    final_sample = scheduler.sample_loop(mock_model, shape=(2, 8), seed=42)
    assert final_sample.shape == (2, 8)
    assert not np.isnan(final_sample).any()
tests/run_tests.sh (128 bytes)
#!/usr/bin/env bash
set -e
export PYTHONPATH=examples:.
PYTEST="${PYTEST:-pytest}"
$PYTEST tests/test_diffusion_scheduler.py -v
tests/test_diffusion_scheduler.py (2326 bytes)
import pytest
import numpy as np
from diffusion_scheduler import GaussianDiffusionScheduler

@pytest.fixture
def linear_scheduler():
    return GaussianDiffusionScheduler(timesteps=100, beta_start=0.0001, beta_end=0.02, schedule_type="linear")

@pytest.fixture
def cosine_scheduler():
    return GaussianDiffusionScheduler(timesteps=100, schedule_type="cosine")

def test_schedule_properties(linear_scheduler, cosine_scheduler):
    assert len(linear_scheduler.betas) == 100
    assert linear_scheduler.alphas_cumprod[0] > linear_scheduler.alphas_cumprod[-1]
    assert np.all(linear_scheduler.betas > 0.0)
    assert np.all(linear_scheduler.betas < 1.0)

    # Cosine schedule starts near 1.0 and smoothly decays
    assert cosine_scheduler.alphas_cumprod[0] > 0.99
    assert cosine_scheduler.alphas_cumprod[-1] < 0.01

def test_forward_diffusion_closed_form(linear_scheduler):
    np.random.seed(42)
    x0 = np.ones((4, 3, 16, 16), dtype=np.float32)
    noise = np.random.randn(4, 3, 16, 16).astype(np.float32)
    t = np.array([0, 25, 50, 99], dtype=np.int64)

    xt = linear_scheduler.add_noise(x0, noise, t)
    assert xt.shape == (4, 3, 16, 16)
    
    # At t=0, alpha_cumprod ~ 0.9999 -> xt is almost pure x0
    assert np.mean(np.abs(xt[0] - x0[0])) < 0.1
    # At t=99, xt is dominated by noise
    assert np.std(xt[3]) > 0.7

def test_reverse_step_denoise(linear_scheduler):
    np.random.seed(42)
    sample = np.random.randn(2, 4).astype(np.float32)
    pred_noise = np.zeros_like(sample)
    
    prev_sample = linear_scheduler.step_denoise(pred_noise, timestep=50, sample=sample, seed=42)
    assert prev_sample.shape == sample.shape
    assert not np.isnan(prev_sample).any()

def test_timestep_bounds(linear_scheduler):
    sample = np.zeros((2, 2), dtype=np.float32)
    with pytest.raises(ValueError, match="out of bounds"):
        linear_scheduler.step_denoise(sample, timestep=100, sample=sample)

def test_sample_loop_reconstruction():
    scheduler = GaussianDiffusionScheduler(timesteps=10, schedule_type="linear")
    
    # Mock model function that returns scaled current noise
    def mock_model(x, t):
        return x * 0.1
        
    final_sample = scheduler.sample_loop(mock_model, shape=(2, 8), seed=42)
    assert final_sample.shape == (2, 8)
    assert not np.isnan(final_sample).any()

Troubleshooting

Troubleshooting

Verify dimension broadcasting when scaling 4D image tensors with 1D alpha cumprod slices.

Security notes

Security

Pure NumPy array math modeling forward and reverse diffusion noise schedules. Zero external network dependencies.